Persistent Monitors

Persistent monitors and card watches let an agent keep waiting after its own process exits. The Stib daemon stores them on the card and resumes an idle agent when something happens: a monitor runs a command at the requested interval and reports its stdout; a card watch waits for another card's agent to stop, or to settle.

Card watches

stib monitor watch-card 905 --description 'Verifone type 14'
stib monitor list
stib monitor unwatch 3

A card watch needs no command and no credential: the server reads the target card's state itself. The target must be another card of the same project whose agent is running; otherwise creation is refused with CARD_WATCH_TARGET_NOT_RUNNING and the target's current state, so the agent can report it right away instead of promising a notification. The target accepts the same references as other card commands (905, "#905", id:905, STIB-12).

The watch fires once, then disappears. It fires when the target's turn finishes (idle, success or error), when its agent waits for user input or a plan approval, and when the target is archived, trashed, deleted or moved to a passive column. Waits that belong to Stib rather than to the agent — a full context window waiting for a fresh session, a deferred start, a quota resume — keep it armed, and so does an automatic hand-off that restarts the agent within a few seconds. A watch that fired while Stib was stopped is delivered after the restart.

Until the card settles

A card whose turn ended is not always done: its agent may still run background tasks or sub-agents, or have scheduled a wakeup, and Claude Code resumes on its own when they end. To be told about the real end, arm the watch with --until settled:

stib monitor watch-card 905 --until settled --description 'Review of #905'

A settled watch fires once the target is stopped with no background task, sub-agent, scheduled wakeup or expected resume left. It also fires at once when the target waits for user input or a plan approval, and when it is archived, trashed or deleted. A target moved to a passive column fires it once its background work is over. It accepts a target that already stopped but still has background work; a plain watch refuses that target, and its refusal suggests --until settled. A card holds one watch per target: to switch modes, remove the watch with unwatch and arm a new one.

A background task that never ends, such as a dev server, holds a settled watch until the background-task ceiling (6 hours by default, configurable) abandons the task; the card then settles and the watch fires. With that ceiling lifted, nothing bounds the wait and unwatch is the way out. Codex and ACP agents report no background tasks: for them, settled means stopped.

In both modes, the event line of a target that stopped with background work says what is still coming, for example card #stib:905 "Title" stopped: success — 2 background tasks still running, the card will resume.

Agents read the same state on cards: stib cards get and each item of stib cards list carry settled and background (tasks, subagents, wakeupAt, resumeExpected), and stib cards tasks 905 lists the background tasks still running on a card of the same project.

Other stable errors are CARD_WATCH_SELF, CARD_WATCH_TARGET_NOT_FOUND, CARD_WATCH_ALREADY_ARMED, CARD_WATCH_LIMIT_REACHED and, for a watcher that left its active column, CARD_WATCH_CARD_INACTIVE. A project agent's conversation can watch cards even though its card lives in a passive column. A server without card watches makes watch-card refuse with an update message, and list show monitors only.

Command monitors

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.

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 and watches.

A monitor command runs in the server's environment, without Stib credentials: the stib CLI cannot authenticate inside it. To wait for another card, use a card watch.

add waits for the monitor's first run and reports it: first run: success, or the failure with its error and exit code 4, or a warning when the run has not finished within its timeout plus a scheduling margin. The monitor stays armed either way. The failure is also queued as an event: removing the monitor in the same turn drops it before it reaches the agent, while a monitor left armed delivers it once the card is idle.

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 and watches 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.

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.

Notifications

A follow-up triggered by a monitor or a watch belongs to the person who started the agent run that armed it. The agent's reply to the events therefore produces the same desktop and mobile notifications as a reply to that person's own message. A person who has since lost access to the project is not notified, and monitors armed by automation notify nobody.

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 and watches 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. A project agent's conversation keeps them in its passive column; resetting or deleting the conversation removes them. Removing a monitor or shutting down Stib terminates and reaps its running command and descendants.

Limits are eight monitors and 32 card watches 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.