/cos-watch

name: cos-watch
description: "Supervise active PLs, including wake cadence, liveness, recovery, large-run launches, and cross-journey order. Loaded ONLY by the cos core via its routing table; NEVER auto-load from context or invoke directly."
requires:
  programs: []
  harness:
    - {slot: 4.shell, need: required}
    - {slot: 4.file-read-write, need: required}
    - {slot: 4.background-processes, need: required}

COS — live supervision

Apply the COS core's finite development budget and affected-test scope. Estimate setup, execution, and reporting from available prior runtimes; do not add estimation machinery or preflight. Full suites and new security checks need the owner's specific approval, never COS approval. Missing auxiliary records do not stop functional work.

Before running these commands, set `COS_SKILL_DIR` and `PL_SKILL_DIR` to the absolute directories of the installed `cos` and `pl` skills, in the same Bash call.

Prerequisites are listed in the `cos` core (§Prerequisites and terms): Linux, tmux, flock, jq, python3, pstree and pgrep, and the `pl` skill.

Loaded whenever anything is in flight: a journey running, a night shift open, a wake tick firing, a PL gone quiet, a big run launching.

**Exclusive authority of this overlay:** reopening a dead PL (within the cap of three), and editing a stale board document mid-flight. Everything else still leaves as a card.

The wake cycle

COS schedules its own wakeups. During a night shift the owner types nothing.

**The intervals live in ONE table — the core's Iron rule 0 — and are not restated here.** On a declared night shift the number is 10 minutes and is never reasoned upward. A second copy of that table is how a supervisor ends up picking 20–60 minutes on the one shift where the law says 10 minutes.

Every tick, in order:

1. `sno reach inbox --as <your address>`, then `"${COS_SKILL_DIR}/scripts/cos-roster.sh"` — the roll call. 2. Re-read `LEARNING.md`'s index. It is at most 64 lines and effectively free, and re-reading is what stops a long session from running on a cached picture. 3. Check each owned PL against the six reasons to act (core, §Decision discipline). 4. **Flush the buffer if anything carded in.** An executor or PL that sent a card is stopped and waiting — that reply carries every buffered item for free (core skill, §Card timing). Buffered items that nobody has given you a free ride for stay buffered. 5. Append **one line** to the watch log: time (UTC by default), each PL's state, what moved, and how many items are still buffered — a buffer nobody reports is a buffer that gets forgotten. 6. **Stay silent unless a trigger fires.** A tick that finds nothing produces no message to the owner and no card.

How to actually schedule it

**One mechanism, and nothing blocks.** A COS that ends its turn without a heartbeat armed has become the unwatched inbox its own core law describes — the failure it exists to prevent, committed by the supervisor. End the turn; a heartbeat rings your own seat to start the next one. The same on every runtime, with no waiting command and no polling loop:

# Register first, or a PL's card cannot ring this window between ticks.
# register prints `cos-claim: registered address=<addr> owner=<token>`; keep the address.
COS_ADDR=$(bash "${COS_SKILL_DIR}/scripts/cos-claim.sh" register [<seat-letter>] \
  | sed -n 's/^cos-claim: registered address=\([^ ]*\).*/\1/p')
[[ -n "$COS_ADDR" ]] || exit 64
sno heartbeat --interval <interval> --label cos-<name> -- sno reach ring "$COS_ADDR"

`<interval>` comes from the core's table (`10m` on a night shift). `sno heartbeat --list` shows whether it is still armed (yours is marked); it stops by itself after 24 hours, so re-arm then, and `sno heartbeat --stop cos-<name>` before re-arming with a new interval. The next wake is armed before the turn ends, every time — including the tick that found nothing.

**THE RING IS A HINT. YOUR INBOX IS THE QUEUE.** Begin every tick with `sno reach inbox --as <your-address>` and never treat "a ring arrived" as the same event as "a card arrived". Cards whose wake failed sit in the inbox for hours, questions included. Every send that fails to wake returns exit 5 or 6 to its sender, and reading the inbox on your own schedule is the independent check that the queue itself is being drained.

**The tell:** send exit 5 or 6 means the card exists but the wake did not land. Check the recipient's inbox immediately and restore its registration. Do not resend the card and do not create a second wake path with a direct terminal command.

Liveness — the turn lock leads; the heartbeat is never decisive

Run `"${COS_SKILL_DIR}/scripts/cos-roster.sh"`. Never assemble this by hand — that is the exact action it was built to abolish.

| Source | Proves | Does NOT prove | |---|---|---| | **Turn lock + heartbeat-ring, read as ONE pair** — the idle-inhibitor reading `Codex is running an active turn` (it exists only for Codex on Linux with systemd; on any other setup judge liveness from the seat and `sno reach seats` instead), together with whether that lane's heartbeat-ring is armed (`sno heartbeat --list`) | the pair, and only the pair: **lock = a turn is executing**; **no lock + heartbeat-ring armed = healthy between ticks** (reachable, NOT working); **no lock and no heartbeat-ring = not reachable on schedule**, a compliance failure | **the lock alone anything**: a turn stuck on one command holds it too. Also: Claude-runtime agents take no lock at all | | Role from arguments — `codex exec …` vs plain `codex …` | executor versus interactive window | **which** window. A PL's window and one the owner opened are indistinguishable — say so rather than guessing | | Heartbeat file age | recent activity when fresh | **nothing when stale.** A PL deep in an owner conversation leaves no other disk trace | | Inbox and artifact movement | work is landing | quiet may mean thinking, waiting, or dead. Repo-wide, so it