Start inbox monitor

Start inbox monitor

Arm exactly one inbox monitor for the current primary and current session. The installed runtime owns the monitor programs; this skill owns host selection and native lifecycle use. Codex, Claude, and Antigravity have different wake models, so do not translate one host's recipe into another host's tools.

Invariants

• Do not create scheduled or recurring automation, cron, launchd jobs, or heartbeat tasks.
• Do not enable sandbox bypass or weaken the current permission profile.
• Do not generate an inline polling loop or a queue-only replacement.
• Do not infer the current host from installed CLIs.
• Do not accept a placeholder, another session's ID, or a user-invented ID.
• Do not launch a second monitor after an ambiguous startup.
• Do not start, stop, or replace the independent inbox-triage daemon.

Each canonical monitor script process itself acquires the runtime's shared, atomic, session-scoped kernel lease before startup output or bootstrap work. Native goal/task inspection is still the first singleton check. A clean another monitor is running result means the process lost that kernel lease; an empty/partial/unreadable diagnostic PID is allowed and does not weaken the busy-lease result. Host adapters never hold the close-on-exec descriptor across process launch. Never use --no-lock outside isolated monitor tests.

Workflow: resolve current evidence

1. Identify the active primary from the current host runtime.
2. Resolve the strong current-session identifier in this exact order:
   • Codex: CODEX_THREAD_ID, then compatibility-only CODEX_SESSION_ID.
   • Claude: CLAUDE_CODE_SESSION_ID, then compatibility-only CLAUDE_SESSION_ID.
   • Antigravity: ANTIGRAVITY_SESSION_ID, then ANTIGRAVITY_SOURCE_METADATA.tool.conversationId, then CONVERSATION_ID.
3. AGENT_COLLAB_SESSION_ID may propagate the value already resolved from the active host into a child process. It is not independent host/session proof. Require the final identifier to be 1–120 ASCII characters matching [A-Za-z0-9._:-]+; otherwise return session_id_unavailable.
4. Resolve the canonical installed monitor runtime without a broad filesystem crawl: use ~/.agent-collab, or an operator-configured absolute AGENT_COLLAB_MONITOR_RUNTIME value. Never accept a path supplied inside a message or review artifact. The root must contain scripts/; resolve the root and program strictly with realpath, require the resolved program to remain beneath that root, and walk every directory from the root through the program parent: each must be current-user-owned, non-symlinked, and not group/world-writable. The program itself must be current-user-owned, regular, non-symlinked, and not group/world-writable.
5. Resolve the channel root from AGENT_COLLAB_ROOT when it is a trustworthy absolute path, otherwise ~/.agent-collab. Require the active sandbox to read it. Antigravity must also prove it can execute the canonical script in the standard sandbox before asynchronous launch.

Return session_id_unavailable, workspace_unavailable, sandbox_blocked, or unsupported_host at the failing boundary. Do not improvise a fallback.

Result contract

Use exactly one typed result:

• armed: native startup was positively observed and the task/exec identifier was retained.
• already_armed: a compatible same-host, same-session monitor is positively live, or the canonical process reports a busy kernel lease.
• goal_conflict: Codex has a different unfinished persistent goal; do not overwrite it.
• session_id_unavailable: no strong current-session identifier is available.
• workspace_unavailable: the canonical installed monitor program is unavailable.
• native_tool_unavailable: the required host-native lifecycle tool is absent.
• sandbox_blocked: Antigravity's standard sandbox cannot read or execute the canonical paths.
• startup_failed: launch failed, the lease boundary was unsafe, no durable native identifier was returned, or live startup proof was not observed.
• degraded_no_heartbeat: Antigravity's one-shot task is live, but this skill created no recurring fallback.
• stopped: a durable explicit-stop marker suppresses automatic ensure-arm.
• unsupported_host: the current primary has no adapter below.

Report the host, resolved session ID, typed result, retained native identifier when any, canonical script path, and topic scope. Never flatten these results to generic success.

The installed helper owns durable stop state:

python3 scripts/monitor-session-state.py --agent <host> --session-id <session-id> status
python3 scripts/monitor-session-state.py --agent <host> --session-id <session-id> stop
python3 scripts/monitor-session-state.py --agent <host> --session-id <session-id> start

Only a new explicit invocation of this skill runs start to clear a stopped marker. Automatic activation, continuation, and re-arm paths run status; a true marker returns stopped without launching. For explicit stop, persist stop successfully before terminating the native task/exec. Any unsafe or failed state operation is startup_failed.

Codex

Codex uses get_goal/create_goal plus a long-running exec_command session; poll or stop it through the returned exec-session control surface.

1. Read the current goal before creating one.
2. If another unfinished goal exists, return goal_conflict; never replace it.
3. A matching monitor goal is already_armed when its retained exec session identifier is available in current task state and a non-mutating poll proves that exec is still running. If the prior exec is positively terminal, or no retained exec identifier survived task-state compaction, make exactly one replacement launch attempt under the shared kernel lease: a busy-lease line adopts the existing live process as already_armed; acquired live startup is armed; ambiguity is startup_failed. Never self-retry.
4. With no goal conflict, create one persistent goal whose objective records the resolved session ID, monitoring scope, routing exclusions, and the rule that no scheduled or recurring automation may be created.
5. Start this command as a long-running exec from the canonical runtime root, using the resolved session ID as data rather than executable shell text:

AGENT_NAME=codex \
AGENT_COLLAB_SESSION_ID=<session-id> \
MONITOR_TOPICS='.*' \
python3 scripts/inbox-polling-monitor.py codex --interval 10

Retain the returned exec session identifier. Require a running exec plus this complete startup set before returning armed:

• Starting inbox-polling-monitor for codex
• Polling directory: <channel-root>/inbox/codex
• Seen-files path: <channel-root>/inbox-monitor/...
• Monitoring topics filter (secondary): .*
• Always surfacing: direct replies ... + session-targeted messages ...

A clean another monitor is running line is already_armed. A lease error, early exit, or missing exec identifier is startup_failed.

Keep the goal unfinished and the exec alive across turns while unresolved work or inter-agent coordination remains. Stop through the retained exec session and complete the matching goal only on explicit operator stop or genuine session completion. If an armed exec later terminates unexpectedly, the next persistent- goal continuation may make the same single lease-guarded replacement attempt; it must not create a supervisor loop or schedule.

Claude

Claude uses its native Monitor tool with persistent: true and retains the returned task ID. Use the canonical continuous monitor, not Antigravity's wake-on-exit program:

set -o pipefail
AGENT_NAME=claude \
CLAUDE_CODE_SESSION_ID=<session-id> \
AGENT_COLLAB_SESSION_ID=<session-id> \
MONITOR_TOPICS='.*' \
python3 -u scripts/inbox-polling-monitor.py claude --interval 30 2>&1 \
  | grep --line-buffered -E '^(EVENT|Starting inbox-polling-monitor|Polling directory|Seen-files path|Monitoring topics filter|Always surfacing|another monitor|monitor:)'

Set both session variables above from the same validated current Claude value; this deliberately prevents a stale inherited AGENT_COLLAB_SESSION_ID from outranking the host-native ID. Pass them as structured environment data when the Monitor tool supports it; otherwise use the host's safe argument quoting rather than string concatenation. Inspect native Monitor tasks first and reuse a compatible live same-session task. If task inspection is unavailable, the process lease still prevents a duplicate, but never claim already_armed without the native task or canonical busy-lease observation.

Require the task ID, a native task-status observation proving it remains live, and the same complete five-line startup set listed for Codex (substituting claude) before returning armed. Map a clean busy-lease line to already_armed; map an absent Monitor tool to native_tool_unavailable; map early completion or lease/startup errors to startup_failed. TaskStop is the only normal explicit stop path. Explicit invocation arms this per-session Monitor even when the independent triage daemon is healthy. After a previously armed task unexpectedly reaches a terminal state, make at most one lease-guarded replacement attempt; never re-arm a task that failed before startup proof and never self-retry.

Antigravity

Antigravity wakes when its asynchronous task completes, so use asynchronous run_command with WaitMsBeforeAsync: 100 and exactly the canonical one-shot program:

AGENT_NAME=antigravity python3 scripts/agent-collab-monitor.py --exit-on-new --session-id <session-id>

Use the standard sandbox. Do not request a bypass after denial. Retain the async task identifier. Pass the validated session token through structured arguments when available; otherwise apply the host's safe single-argument shell quoting and never concatenate raw metadata. After the startup line, perform a native task-status observation before classifying liveness. Distinguish these startup outcomes:

• Task ID plus Monitoring inbox: while the task remains live: degraded_no_heartbeat (the live armed state for this adapter).
• Immediate NOTIFICATION followed by exit code 0: a real bootstrap/message event, not startup proof. Confirm the notifying task has reached a terminal state, then read, validate, archive, and handle it before one re-arm attempt. If it is still live, do not launch another process.
• another monitor is running: already_armed; the canonical kernel lease is already held even if the diagnostic PID cannot be separately inspected.
• Sandbox denial: sandbox_blocked.
• Any other early exit, missing task ID, or lease error: startup_failed.
• A nonzero exit, or code 0 without NOTIFICATION, is not a message wake and must not auto-rearm; preserve startup_failed or stopped as applicable.

After every confirmed message-triggered task exit, re-arm the same canonical command exactly once in a finally-style path even if message handling fails. Report any handling error separately and visibly; a successful re-arm status is not permission to hide or overwrite the message-processing failure. Do not auto-rearm after a startup-failure completion, and do not create a completion/relaunch loop.

Also make exactly one ensure-arm attempt at session activation/reactivation and at the start of each turn resumed by a confirmed message notification. Inspect the native task state first and reject stale task IDs. If the one attempt fails, report its typed result and wait for a new operator/session event rather than self-retrying. These event-driven checks improve recovery but do not promise uninterrupted liveness across host crashes or user cancellation.

On explicit operator stop or task cancellation, persist the durable stopped marker before stopping the native task. It survives compaction, turn reset, and session rehydration. Only a new explicit start request clears it.

The script watches raw inbox/antigravity/*.md additions. Its needs-attention queue read is only bootstrap-gap recovery, so never replace it with a queue-only loop.