Other

/collab-monitor

Native Monitor for addressed collab mail on Claude/cmux seats, report DONE markers and installed-version watches. Codex/T3 seats: no polling turns; completion notifications wake you; a T3 lead keeps one lead name waiter. NOT for file-integrity auditing.

$ golems-cli skills install collab-monitor
35 evals
fixtures

Updated yesterday

Use the native Monitor tool when the harness exposes it. Arm before dispatch, keep the returned watch identifier in the lane record, and stop it when its lane closes. Codex and T3 seats never poll collabs with turns; a T3 lead keeps one name waiter (next section), which also watches its lane collab (§ Lanes with a collab). A detached producer alone does not wake an agent.

Codex and T3 seats

The m1-launch-queue collab is now an admission ledger, not a request queue: agent-routing/references/cross-machine.md § 5.

"Codex seats must not poll collabs; T3 delegate completions already wake you." "No polling turns. No collab-monitor wakes in Codex" (Etan 2026-10-18, via orc collab)

Why: the weekly Codex quota drained in under 24 h, with the Codex "Collab Monitor" skill at 196 uses on Oct 18, and "Collab-monitor polling wakes cost another 201M across 729 turns." (Etan 2026-10-18, via orc collab)

  • A Codex seat never arms collab-monitor, never runs start/follow/run, and never polls a collab file with model turns, in a loop or on a schedule (a lead's one shell name waiter below is the only exception).
  • A T3 seat (any vendor) relies on its parent-owned wake signals: delegate_task completion notifications for child work and watch_pull_request for PRs. Do not add a second watcher on top of them, apart from the lead name waiter below.
  • A T3 lead keeps exactly one name waiter armed at all times on the leads+orc collab, orchestrator/docs.local/collab/orc-inbox.md (lead rules §1, 2026-10-30), and on each lane collab it leads (§ Lanes with a collab): a background shell loop that exits on the first new @<handle> or @all-leads line in the inbox, or the first new line addressed to its listen name in a lane collab. Register it with t3_background_wait and re-arm it on every wake. It costs no model turns until a line matches, so it is not a polling turn. Keep your own handle out of your own posts, or it wakes you. Workers and children never arm it.
  • If something genuinely must sit and watch, dispatch one bounded codex.subagent.mechanical child per /agent-routing § Routing rules (SSOT); resolve its model with node scripts/model-roles.mjs codex.subagent.mechanical --use watcher. It reports once and exits; it never owns the parent's PR watch.
  • Native Monitor below is for Claude seats in a cmux fleet.

Lanes with a collab

"when there is a collab the message shouldn't travel through the chat, but have the monitor on the […] collab damn it" (Etan 2026-11-02, via orc)

  • Every worker brief says Report to <collab path>, not to the lead thread. Workers append their status, DONE and BLOCKED lines to the collab.
  • The lead keeps ONE live monitor on the collab, for lines addressed to it. A Claude seat in a cmux fleet uses native Monitor (§ Collab tail with a lead filter), re-armed at expiry. A T3 lead (any vendor) extends the one name waiter above to the lane collab, so it adds no second waiter and no polling turns.
  • The completion notification stays the liveness guard. The collab monitor carries the messages.
  • Don't relay worker updates into chat. Chat is for Etan and orc's routing.

Native Monitor first

Call Monitor({command, description, timeout_ms: 1800000}): a command, a short description naming the lane, and a 30-minute timeout. This Claude Code harness caps the tool at 1800000 ms; other harness versions may differ, so check their schema. Give it events that each require action; use one completion watch for a batch of tests or CI jobs.

Keep every timer wake inside the prompt-cache window (Claude ~60 min, Codex ~30 min): a Monitor timeout_ms, ScheduleWakeup delay or re-arm interval is ≤50 min (3000000 ms) on a Claude seat and ≤25 min on a Codex seat. Never arm 3600 s: wakes past the window busted the cache 20 times in a week, costing Claude 7.4M tokens (35 Monitor arms at 3600 s, cache audit 2026-10-19). Prefer an event wake (a completion notification or watch_pull_request) over a timer.

Collab tail with a lead filter

Use the foreground routing filter as the native tool's command. Monitor owns the process and wakeups; the filter owns watermarks, hash dedup and author matching. This avoids spawning a detached producer before every native watch.

Monitor({
  command: 'bash "$HOME/.claude/skills/collab-monitor/scripts/collab-monitor.sh" run --alias @<seat-id> @<lead-listen-name> /absolute/path/collab.md',
  description: '<lane> addressed collab mail',
  timeout_ms: 1800000,
})

Replace the listen name, seat alias and file with the actual lane values. Use a private, explicit state root via MONITOR_STATE_DIR when isolating a test watch. Resolve the script from the skill location supplied by your harness; the example uses this MacBook's installed ~/.claude/skills/collab-monitor symlink. Verify the resolved script exists before arming; use its absolute path on other hosts. Never point a test watch at a real lane's state root.

The bounded lead filter accepts word-bounded @<name> mentions, headers addressed ### author → name (also ->), and that lead's own <name>-w<N> / <name>-r<N> DONE/BLOCKED lines. It excludes self-authored blocks, signature-only tags, near-miss names and unrelated headings. Fenced and indented code cannot route mail; an unclosed fence reports an incomplete poll and is retried. Add --alias for each actual delivery name, not a broad prefix.

The first poll seeds existing history silently. Re-arming with the same state root preserves dedup. New mail should produce NEW-FOR-@<name>; readiness alone is not proof that the consumer received a message. Append collab posts with cat >> or an append-only writer.

Repeated identical headings in one append-only file are separate occurrences. The first retains its content hash; later ones carry episode=2, episode=3, etc. Read that routed occurrence outside code in the alert's file for its report body and pointer. Extending a body does not create another heading episode. Restart preserves dedup; existing heading-only state silently seeds pre-watermark repeated headings on its next successful growth poll. Identical copies at the same occurrence in different watched files still share a dedup key. Use a unique final completion heading per report episode so older installed monitors also catch it. This repair does not attach a parent consumer or replay a missed report.

Report-file DONE markers

Set the report path and the exact marker in this command, then pass it as Monitor's command with timeout_ms: 1800000. Check the exact final line, not a DONE word in the report body. This watch completes once; read the report and verify its requested artifact after it fires.

REPORT='/absolute/private/report.md'
DONE_MARKER='DONE_LANE'
deadline=$(( $(date +%s) + 1800 ))
while true; do
  if [ -r "$REPORT" ] && [ "$(tail -n 1 "$REPORT")" = "$DONE_MARKER" ]; then
    printf 'REPORT_DONE %s\n' "$REPORT"
    exit 0
  fi
  if [ "$(date +%s)" -ge "$deadline" ]; then
    printf 'REARM_REQUIRED report watch\n'
    exit 0
  fi
  sleep 1 # Cheap local file-stat poll cadence; not an urgency signal.
done

A marker is a handoff signal, not proof of merge, publication or installation. If the report is missing or malformed, the watch stays open until its deadline.

Installed-version watches

Query the installed command, not the checkout, a merge receipt or a release tag. Set the exact expected --version output and pass this body to native Monitor. The command re-reads the installed binary on every tick, including replacements at the same path.

TOOL='/absolute/path/installed-command'
EXPECTED_VERSION='expected exact version output'
deadline=$(( $(date +%s) + 1800 ))
while true; do
  if current="$("$TOOL" --version 2>/dev/null)" && [ "$current" = "$EXPECTED_VERSION" ]; then
    printf 'VERSION_MATCH %s\n' "$current"
    exit 0
  fi
  if [ "$(date +%s)" -ge "$deadline" ]; then
    printf 'REARM_REQUIRED installed-version watch\n'
    exit 0
  fi
  sleep 1 # Cheap local file-stat poll cadence; not an urgency signal.
done

After a version match, run the required real-client smoke. A version string alone does not prove the installed service serves requests successfully.

Re-arm at 30 minutes

The 30-minute re-arm is the tool's hard expiry, not an optional reminder. On expiry and after every compaction, re-check which lanes remain open and re-arm their watches using current paths, identifiers and expected versions. Report/version examples emit REARM_REQUIRED after their 30-minute budget. For a collab stream, cancel the prior native watch by its returned identifier before replacing it; keep the same routing state to avoid history replay. In this Claude Code harness, use TaskStop with the returned task id to cancel early; check the current schema on other harness versions. Do not leave duplicate streams attached.

When a watch ends unexpectedly, repair it and re-arm before dispatch resumes. When its task finishes, stop it. Workers do not monitor their lead's reviewer. Review routing: /agent-routing § Routing rules (SSOT). Follow an engine-issued mailbox contract when one exists.