agentleFS
EtanHeyEtanHey/golems/skills/golem-powers/collab-monitor/SKILL.md

collab-monitor

Skill0 starsChanged 19 days agoApache-2.0View on GitHub

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.

The file

Show its rules and text

We split this skill into the rules it gives an agent

17 rules. About 0 are common, 10 are distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈10

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use the native Monitor tool when the harness exposes it.

    line 12
  2. Very specific:

    If something genuinely must sit and watch, dispatch one bounded codex.subagent.mechanical child per /agent-routing § Routing rules (SSOT).

    line 42
  3. Very specific:

    Every worker brief says Report to <collab path>, not to the lead thread, then end your task.

    line 54
  4. Distinctive:

    Don't dispatch from a waiter-woken T3 turn: a next step follows on the completion wake.

    line 66
  5. Distinctive:

    Don't relay worker updates into chat.

    line 73
  6. Very specific:

    Call Monitor({command, description, timeout_ms: 1800000}): a command, a short description naming the lane, and a 30-minute timeout.

    line 77
  7. Very specific:

    Keep every timer wake inside the prompt-cache window (Claude ~60 min, Codex ~30 min): a Monitor timeout_ms, ScheduleWakeup delay or re-arm …

    line 83
  8. Distinctive:

    Use the foreground routing filter as the native tool's command.

    line 92
  9. Distinctive:

    Never point a test watch at a real lane's state root.

    line 109
  10. Distinctive:

    If the report is missing or malformed, the watch stays open until its deadline.

    line 158
  11. Distinctive:

    After a version match, run the required real-client smoke.

    line 184
  12. Very specific:

    When a watch ends unexpectedly, repair it and re-arm before dispatch resumes.

    line 198
  13. Very specific:

    When its task finishes, stop it.

    line 199
  14. Distinctive:

    Only for a Codex seat running inside a cmux fleet with no T3 parent and no native Monitor.

    line 205
  15. Distinctive:

    After handoff or lane closure:

    line 234
  16. Very specific:

    Stop by listen name, never by a process-name pattern.

    line 253
  17. Distinctive:

    Use live queries on every tick.

    line 278

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Collab Monitor

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, then end your task. Workers append their status, DONE and BLOCKED lines to the collab, then end the task.
  • In T3, the task's end is the real wake. Workers send no separate thread message; they end normally (with the report pointer), and the completion notification wakes the lead, whose turn from it can dispatch the next step.
  • 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.
  • In T3, that name waiter is for awareness only. A waiter wake can arrive as a background-task turn, and T3 can refuse delegate_task from it (parent_not_active, reproduced twice on 2026-11-02; once it did dispatch). Don't dispatch from a waiter-woken T3 turn: a next step follows on the completion wake. Task-completion and PR-watch wakes can dispatch. In T3 the completion notification stays the liveness guard and the dispatch wake; the collab waiter carries the messages.
  • On a Claude cmux seat, the native Monitor is the completion watch too (§ Native Monitor first): act on an addressed BLOCKED/DONE line from its wake, including dispatching the next step.
  • Don't relay worker updates into chat; chat is for Etan and orc's routing. No polling turns.

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.

Legacy cmux-only adapter

Only for a Codex seat running inside a cmux fleet with no T3 parent and no native Monitor. Any T3 seat, or any Codex seat that can rely on completion notifications, stops at Codex and T3 seats. Record its listen name and PID, verify readiness, and attach its consumer to the orchestrator's monitored command session:

CM="$HOME/.claude/skills/collab-monitor/scripts/collab-monitor.sh"
# Or set CM to the absolute script path from your harness's skill catalog.
test -f "$CM" || { printf 'Missing collab-monitor script: %s\n' "$CM" >&2; exit 1; }
bash "$CM" start --alias @<seat-id> @<listen-name> /absolute/path/collab.md
bash "$CM" status @<listen-name>
bash "$CM" follow @<listen-name>

run, follow, and the start producer exit cleanly when their owning agent dies. Ownership is the nearest claude/codex ancestor, or the initial parent when no agent ancestor exists; --owner-pid <pid> overrides it on all three commands. start captures ownership before detaching and persists independently of the invoking shell while that owner lives. Foreground run/follow also exit on reparenting to PID 1; the packaged detached producer is exempt from that parent check. Owner checks continue during sleep/tail waits (at most one second apart), and normal cleanup reaps sleep/tail children and releases owned state. follow replays the current session log then streams new alerts, and exits when that named watch stops. It is the attached consumer, not proof of a native Monitor tool on Codex. For a caller-owned foreground process, use run; for a scheduled single poll, use run --once. Both use the same bounded routing filter.

After handoff or lane closure:

bash "$CM" stop @<listen-name>

status is read-only: it never acquires locks or prunes state. start prunes inactive runtime records across its state root: PID/instance/owner/ready records, stale run locks and abandoned event extracts. Pruning retains logs, dedup hashes and size watermarks. A live producer or foreground run keeps all its files, including when its token is inconsistent; active or ownerless start locks younger than 30 seconds are preserved; older ownerless locks are recoverable after interrupted publication. Pruning has signal cleanup. Reused PIDs belonging to unrelated processes are pruned without signaling them. start records the owner PID and status prints owner_pid (unknown for older instances). Instance identity works across checkout paths. run and follow exit and reap their children if the script or any packaged helper disappears, including during long waits.

Stop by listen name, never by a process-name pattern. The implementation checks PID and per-start identity before signaling. On STATE_CONFLICT, inspect the preserved records; do not delete state or signal an unverified process.

Defaults: state ~/.local/state/collab-monitor/<listen-name>/, positive POLL_SECONDS, readiness budget 30 seconds. START_TIMEOUT_SECONDS can extend readiness to at most 86400 seconds; malformed intervals and names . / .. are rejected. --include-self is for explicit audits only and labels those records SELF-POST rather than inbound mail. Never share test state with a lane.

Limits and supervision

The filter detects byte-size shrink, retries transient missing/unreadable files, and reports incomplete polls. It does not detect same-size rewrites, messages outside the routing grammar, process death without a supervisor, or completion visible only in a worker registry. A crash between alert emission and persistence can duplicate the final alert: delivery is at-least-once.

You MUST NOT poll read_screen in a loop for a worker outcome. For headless Codex workers use codex-workflows' watch: observe process completion, then read its finished output once. A monitor observes an artifact, not whether a reviewer was actually routed. Keep handoff ownership explicit in the lane's closure record.

Recurring payloads

Use live queries on every tick; never copy a stale PR state into the payload. Frame the tick with a timestamp, cycle and last verified action. Counters reset only on a verified side effect. Finish with dispatch, verify-and-decrement or escalate-park. Codex and T3 seats write no recurring collab-reading ticks (Codex and T3 seats). Scheduler-specific fallback guidance is in references/cron-payloads.md; it is not a prerequisite for native Monitor.

Evaluation

python3 skills/golem-powers/collab-monitor/evals/monitor-howto.py
python3 skills/golem-powers/collab-monitor/evals/episode-dedup.py
bash skills/golem-powers/collab-monitor/evals/run-evals.sh candidate
bash skills/golem-powers/collab-monitor/evals/live-two-file-smoke.sh
python3 skills/golem-powers/collab-monitor/evals/owner-exit.py
python3 skills/golem-powers/collab-monitor/evals/state-hygiene.py

The how-to checks exercise synthetic report/version command transitions and teaching contracts. The routing suite exercises the packaged filter and detached fallback. Neither proves native Monitor execution on a harness where it is unavailable. Agent-behavior scenarios are recorded separately in evals.json.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.