Persistent Monitors

Persistent monitors let an agent watch a command after its own process exits. The Stib daemon stores the monitor on the card, runs it at the requested interval, and resumes an idle agent when stdout produces events.

Server permissions

Monitor commands run outside the agent sandbox with the operating-system permissions of the Stib server. Only monitor trusted commands. --allow-unsandboxed is a mandatory, persistent acknowledgement of this security boundary.

Commands

stib monitor add --cmd 'git fetch --quiet && ./check-ci' --interval 45s --description 'CI status' --allow-unsandboxed
stib monitor list
stib monitor remove 42

add accepts intervals from 10s to 24h. Its optional description defaults to a readable excerpt of the command. The CLI authenticates with the current card's nonce and self scope, so an agent can only manage its own card's monitors.

Execution and events

The daemon starts a monitor immediately at boot or after creation. A monitor never overlaps with itself: the next interval begins after the previous run finishes. At most four monitor commands run across the server, and each run times out after the smaller of its interval and 60 seconds.

Every stdout line is one event. Stderr is drained and saved as diagnostics. Events from all monitors on one card are ordered, collected for 10 seconds, then delivered in follow-ups of at most 100 events or 32 KiB. Longer output continues in later batches. Lines and total run output are bounded; explicit truncation markers are emitted.

Monitor events wait while the agent is working, waiting for the user, or awaiting plan approval. Delivery resumes through the normal agent follow-up mechanism once the card is idle.

Working directory and lifecycle

The CLI captures its current directory. The server accepts only the repository, the managed worktree, or an attached worktree belonging to the card. If that directory disappears, later runs fall back to the project's current repository path without recreating a worktree.

Monitors are deleted permanently when their card leaves an active column, is archived, moved to trash, or deleted, and when the card's column becomes passive. Removing a monitor or shutting down Stib terminates and reaps its running command and descendants.

Limits are eight monitors per card, a 16 KiB maximum line, and 1 MiB collected output per run. Stable creation errors include MONITOR_UNSANDBOXED_ACK_REQUIRED, MONITOR_INTERVAL_INVALID, MONITOR_CWD_OUTSIDE_CARD, and MONITOR_LIMIT_REACHED.