screen_lock

Screen Lock

What This Does

Password-locks the graphical session and leaves everything running — agents keep working behind the password wall. Nothing sleeps, nothing is killed, no root is needed (no sudoers grant, no polkit rule).

Two paths, tried in order:

1. loginctl lock-session <id> against the explicitly resolved graphical session. Callers usually run as a systemd --user service with no XDG_SESSION_ID, so a bare lock-session has no ambient session to resolve and may refuse — naming the session is what makes the verb work from there.
2. gdbus → org.gnome.ScreenSaver.Lock as the fallback.

If both fail it says so. A screen that never locked is never reported as locked.

Doctrine — lock is the exception

A destructive action never fires from a locked screen. Lock itself must work from anywhere — that is its whole point.

So this verb is never gated: it does not ask whether the screen is already locked, does not require a desktop environment, and does not refuse when no graphical session can be resolved (it still tries the bare call). Callers that gate other verbs on screen state must leave this one ungated.

Available Actions

Action	Description
lock	Lock the screen now; agents keep running

Usage

drone @skills run screen_lock lock

In-process (what the Telegram control bot and the host API verb lane use):

from aipass.skills.lib.screen_lock import handler as screen_lock

result = screen_lock.lock_screen()
# {"locked": True, "method": "loginctl", "session": "3", "error": None}

When to Use

Use this skill when:

• You are leaving the machine and want the screen locked with work continuing
• A remote surface (phone, host API, chat bot) needs to secure the desk

Do NOT use this skill when:

• You want the machine to sleep — that is /suspend, a different verb with a wake, grace-window and reachability story. Lock never suspends.
• You want to end sessions — nothing is stopped or killed here.