tickmarkr 2.1.3 → 2.1.5

package/dist/run/supervision.js

@@ -1,4 +1,5 @@
-import { mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { randomUUID } from "node:crypto";
 import { dirname, join } from "node:path";
 import { stateDirName, tickmarkrDir } from "../graph/graph.js";
 // SUP-01: supervision liveness as FILE STATE, not as a report — lock.ts's proven shape, one file per
@@ -32,8 +33,9 @@ export const SUPERVISION_FUTURE_GRACE_MS = 1_000;
 // SUP-05: CONTEXT is per SEAT, so its tiers are per seat too. One shared `context` tier would be read
 // by both supervising seats and beaten by whichever of them still had a watcher, so a live overseer
 // watcher would render the dead orchestrator one as armed — the mask this whole instrument exists to
-// remove. The enumeration is CLOSED at one tier per supervising seat: orchestrator and overseer.
-// `watch` beats nowhere on this tree and stays ABSENT, which is what ABSENT means.
+// remove. The enumeration is CLOSED at one supervision tier and one context tier per supervising
+// seat: orchestrator and overseer. `watch` is the sole process-owned tier and is armed seatlessly by
+// the live unbounded board.
 export const SUPERVISION_TIERS = [
     "orchestrator", "orchestrator-context", "overseer", "overseer-context", "watch",
 ];
@@ -42,18 +44,59 @@ export const SUPERVISION_TIERS = [
 // to a seat. Measured 2026-08-26: a consult seat of another tier ran the documented beat loop and the
 // board read that tier armed with no seat of that tier having armed anything. ARMED-and-seatless reads
 // as coverage, which is worse than ABSENT, so on these tiers a record that names no seat is not a beat.
-export const SUPERVISION_SEAT_TIERS = ["orchestrator-context", "overseer-context"];
+export const SUPERVISION_SEAT_TIERS = [
+    "orchestrator", "orchestrator-context", "overseer", "overseer-context",
+];
 /** Does this tier's record have to name the seat it speaks for? */
 export const isSeatTier = (tier) => SUPERVISION_SEAT_TIERS.includes(tier);
 // PURE path math: stateDirName, never tickmarkrDir — the latter mkdirs the state dir and writes its
 // .gitignore, so routing a READER through it would make status create the very tree it reports on.
-export const supervisionBeatPath = (repoRoot, tier) => join(repoRoot, stateDirName(repoRoot), "supervision", `${tier}.beat`);
+const supervisionDir = (repoRoot) => join(repoRoot, stateDirName(repoRoot), "supervision");
+export const supervisionBeatPath = (repoRoot, tier) => join(supervisionDir(repoRoot), `${tier}.beat`);
 /** Where a watcher records that it STOOD DOWN. Its own file: the beat keeps meaning only "alive". */
-export const supervisionStandDownPath = (repoRoot, tier) => join(repoRoot, stateDirName(repoRoot), "supervision", `${tier}.standdown`);
+export const supervisionStandDownPath = (repoRoot, tier) => join(supervisionDir(repoRoot), `${tier}.standdown`);
+// SUP-06: PRESENCE — one file per ARMED WATCHER, because a tier may legitimately have more than one.
+// Two boards watch one repo the moment an operator opens a second pane, and the tier is armed while
+// EITHER of them lives. The stand-down marker speaks for the whole tier, so the first board out
+// writing it renders the second board's own tier DISARMED until that board's next beat — a live seat
+// reported down, which is the under-claiming half of exactly the lie this instrument exists to remove.
+// So the marker is written only by the LAST watcher out, and these files are how it knows it is last.
+// Freshness decides presence, never a process table (SUP-02): a watcher that is killed cannot remove
+// its own file, and an unremoved file ages past the same ceiling a beat does and stops counting.
+const presencePrefix = (tier) => `${tier}.live.`;
+const supervisionPresencePath = (repoRoot, tier, id) => join(supervisionDir(repoRoot), `${presencePrefix(tier)}${id}`);
+/** Every presence file on this tier, by name. Missing directory ⇒ nobody is present. */
+const presenceNames = (repoRoot, tier) => {
+    try {
+        return readdirSync(supervisionDir(repoRoot)).filter((n) => n.startsWith(presencePrefix(tier)));
+    }
+    catch {
+        return [];
+    }
+};
+/**
+ * Stale peers observed in ONE directory snapshot, or undefined when that same snapshot saw a live
+ * one. A later arm has a new id and is deliberately absent from the returned cleanup set.
+ */
+function stalePeersIfLast(repoRoot, tier, id, now = Date.now()) {
+    const own = `${presencePrefix(tier)}${id}`;
+    const stale = [];
+    for (const name of presenceNames(repoRoot, tier)) {
+        if (name === own)
+            continue;
+        try {
+            if (now - statSync(join(supervisionDir(repoRoot), name)).mtimeMs <= SUPERVISION_STALE_MS)
+                return undefined;
+            stale.push(name);
+        }
+        catch { /* a vanished peer needs no cleanup and is not evidence of a live watcher */ }
+    }
+    return stale;
+}
 // WRITER — a watcher's own call, on its own tier, every SUPERVISION_BEAT_MS. Never a reader's: the
 // purity fence (status --watch leaves the state dir byte-identical) is the test that catches a reader
 // that beats on the watcher's behalf, which would report every dead tier as healthy.
-export function beatSupervision(repoRoot, tier, seat) {
+function writeSupervisionBeat(repoRoot, tier, seat, armId) {
     // A seat tier may not be armed anonymously, and the refusal belongs HERE rather than only in the
     // verb: any caller that could write a seatless record could arm a tier nobody occupies.
     if (isSeatTier(tier) && !seat?.trim()) {
@@ -62,7 +105,13 @@ export function beatSupervision(repoRoot, tier, seat) {
     tickmarkrDir(repoRoot); // the write path DOES create — beats land inside the gitignored state dir
     const p = supervisionBeatPath(repoRoot, tier);
     mkdirSync(dirname(p), { recursive: true });
-    writeFileSync(p, JSON.stringify({ tier, ...(seat ? { seat } : {}), pid: process.pid, beatAt: new Date().toISOString() }) + "\n");
+    writeFileSync(p, JSON.stringify({
+        tier, ...(seat ? { seat } : {}), ...(armId ? { armId } : {}),
+        pid: process.pid, beatAt: new Date().toISOString(),
+    }) + "\n");
+}
+export function beatSupervision(repoRoot, tier, seat) {
+    writeSupervisionBeat(repoRoot, tier, seat);
 }
 // THE WATCHER-FACING ENTRY POINT — the loop SUPERVISION_BEAT_MS actually drives. A supervising seat
 // calls this once at the top of its watch and holds the handle for the duration; a seat that dies,
@@ -71,9 +120,11 @@ export function beatSupervision(repoRoot, tier, seat) {
 // an unref'd interval that never holds the watcher's event loop open, and a beat failure that is
 // swallowed rather than crashing the watcher — an unwritten beat ages out and reads STALE, which is
 // the truth. The FIRST beat is swallowed on the same rule: a cosmetic instrument that could not write
-// must not take the run down with it. NOT called from `status`: status is a reader (its purity fence
-// is a test); the in-repo callsite is runDaemon, which arms the orchestrator tier for the life of
-// the run. A tier nobody arms reads ABSENT — exactly what ABSENT means, not a false "healthy".
+// must not take the watcher down with it. The sole production in-repo callsite is `status --watch`
+// when UNBOUNDED, which arms `watch` seatlessly for the life of the board — a bounded render is a
+// reader and arms nothing, which is the purity fence D-02 tests. Supervising seats write their named
+// tiers through the shipped beat verb instead. A tier nobody arms reads ABSENT — exactly what ABSENT
+// means, not a false "healthy".
 //
 // Arming CLEARS any prior stand-down record: a tier that stood down and armed again is armed, and a
 // marker left behind by the last run would otherwise report the live one as stood down forever.
@@ -86,40 +137,64 @@ export function armSupervision(repoRoot, tier, beatMs = SUPERVISION_BEAT_MS, sea
         rmSync(supervisionStandDownPath(repoRoot, tier), { force: true, recursive: true });
     }
     catch { /* uncleared: the reader validates the marker and a newer beat outranks it — never masked */ }
-    try {
-        beatSupervision(repoRoot, tier, seat);
-    }
-    catch { /* repo gone / disk full / no seat — the tier reads ABSENT rather than crashing its watcher */ }
-    const timer = setInterval(() => {
+    // This watcher's own identity fences BOTH its presence and its stand-down against every later arm.
+    // pid alone collides between two boards in one host (and after pid reuse); a UUID never aliases the
+    // stale presence of a killed process that a later last-one-out cleanup may already have observed.
+    const id = `${process.pid}.${randomUUID()}`;
+    const presence = supervisionPresencePath(repoRoot, tier, id);
+    // Presence is refreshed with the beat, so it ages by the same clock and needs no separate loop.
+    const mark = () => {
         try {
-            beatSupervision(repoRoot, tier, seat);
+            writeSupervisionBeat(repoRoot, tier, seat, id); // creates the directory presence is written into
+            writeFileSync(presence, JSON.stringify({ tier, pid: process.pid, id }) + "\n");
         }
-        catch { /* repo gone / disk full — let the beat expire */ }
-    }, beatMs);
+        catch { /* repo gone / disk full / no seat — the tier ages out rather than crashing its watcher */ }
+    };
+    mark();
+    const timer = setInterval(mark, beatMs);
     timer.unref();
     let stoodDown = false;
     return {
-        // Stand down: stop beating AND say so. Idempotent because the daemon disarms from more than one
-        // exit path (its signal reaper exits the process before the finally can run), and the recorded
-        // instant belongs to the first stand-down.
+        // Stand down: stop beating AND say so. Idempotence lets a watcher safely share cleanup across
+        // multiple exit paths; the recorded instant belongs to the first stand-down.
         disarm: () => {
             if (stoodDown)
                 return;
             stoodDown = true;
             clearInterval(timer);
+            try {
+                rmSync(presence, { force: true, recursive: true });
+            }
+            catch { /* ages out on its own */ }
+            // The marker speaks for the TIER, so only the last watcher out may write one: a peer still
+            // present means the tier is not down, and saying it is would render that live board's own tier
+            // DISARMED. The snapshot also fixes the cleanup set: a board arming after this decision receives
+            // a new id, so this older board can neither sweep its presence nor claim its beat stood down.
+            const stalePeers = stalePeersIfLast(repoRoot, tier, id);
+            if (stalePeers === undefined)
+                return;
             // Published ATOMICALLY — written aside, renamed over — so no reader can ever meet a half-written
             // marker. A torn marker is rejected anyway (see readStandDown), but a stand-down that reads as
             // garbage is a stand-down that reports as a death, and the rename costs one line.
             const p = supervisionStandDownPath(repoRoot, tier);
-            const tmp = `${p}.${process.pid}.tmp`;
+            const tmp = `${p}.${id}.tmp`;
             try {
                 mkdirSync(dirname(p), { recursive: true });
                 writeFileSync(tmp, JSON.stringify({
-                    tier, ...(seat ? { seat } : {}), pid: process.pid, disarmedAt: new Date().toISOString(),
+                    tier, ...(seat ? { seat } : {}), armId: id,
+                    pid: process.pid, disarmedAt: new Date().toISOString(),
                 }) + "\n");
                 renameSync(tmp, p);
             }
             catch { /* unrecordable stand-down ages out as STALE — pessimistic, which is the safe way to fail */ }
+            // Sweep only stale names in the pre-publication snapshot. Re-reading here used to catch and
+            // delete a newer board that armed between the peer check and this older board's rename.
+            for (const name of stalePeers) {
+                try {
+                    rmSync(join(supervisionDir(repoRoot), name), { force: true, recursive: true });
+                }
+                catch { /* next sweep */ }
+            }
         },
     };
 }
@@ -153,20 +228,26 @@ function readBeat(repoRoot, tier) {
     // is not evidence that nobody armed the tier). On a SEAT tier it is the opposite: a record naming no
     // seat leaves the tier armed and unattributable, which reads as coverage no seat is providing, so
     // it is UNREADABLE — something is there and no beat any reader can attribute comes out of it.
-    const seat = beatSeat(p);
+    const { seat, armId } = beatMetadata(p);
     if (isSeatTier(tier) && seat === undefined)
         return "UNREADABLE";
-    return { mtimeMs: st.mtimeMs, ...(seat !== undefined ? { seat } : {}) };
+    return {
+        mtimeMs: st.mtimeMs,
+        ...(seat !== undefined ? { seat } : {}),
+        ...(armId !== undefined ? { armId } : {}),
+    };
 }
-/** The seat a record declares, or undefined for any record that declares none this reader can use. */
-function beatSeat(path) {
+/** Optional metadata declared by a beat; its mtime remains the only source of age. */
+function beatMetadata(path) {
     try {
         const rec = JSON.parse(readFileSync(path, "utf8"));
-        return typeof rec?.seat === "string" && rec.seat.trim() ? rec.seat : undefined;
+        const seat = typeof rec?.seat === "string" && rec.seat.trim() ? rec.seat : undefined;
+        const armId = typeof rec?.armId === "string" && rec.armId.trim() ? rec.armId : undefined;
+        return { ...(seat !== undefined ? { seat } : {}), ...(armId !== undefined ? { armId } : {}) };
     }
     catch {
-        return undefined;
-    } // unparseable bytes name no seat — the caller decides what that means
+        return {};
+    } // unparseable bytes name no seat or arm — the caller decides what that means
 }
 function beatLiveness(tier, beat, now) {
     if (typeof beat !== "object")
@@ -203,6 +284,7 @@ function readStandDown(repoRoot, tier) {
     if (!st.isFile())
         return "UNREADABLE";
     let seat;
+    let armId;
     try {
         const rec = JSON.parse(readFileSync(p, "utf8"));
         if (rec?.tier !== tier)
@@ -210,6 +292,7 @@ function readStandDown(repoRoot, tier) {
         if (typeof rec.disarmedAt !== "string" || Number.isNaN(Date.parse(rec.disarmedAt)))
             return "UNREADABLE";
         seat = typeof rec.seat === "string" && rec.seat.trim() ? rec.seat : undefined;
+        armId = typeof rec.armId === "string" && rec.armId.trim() ? rec.armId : undefined;
         // A seat tier's hand-off names WHICH seat left, on the same rule as its beat: an anonymous
         // stand-down on a per-seat tier says a watcher left without saying whose, so it is no record.
         if (isSeatTier(tier) && seat === undefined)
@@ -218,18 +301,26 @@ function readStandDown(repoRoot, tier) {
     catch {
         return "UNREADABLE";
     } // unparseable or unreadable bytes — not a stand-down anyone can read
-    return { mtimeMs: st.mtimeMs, ...(seat !== undefined ? { seat } : {}) };
+    return {
+        mtimeMs: st.mtimeMs,
+        ...(seat !== undefined ? { seat } : {}),
+        ...(armId !== undefined ? { armId } : {}),
+    };
 }
 // THE TIER'S STATE — what every surface and every operator reads. A valid stand-down outranks the beat:
 // the watcher that wrote it is gone ON PURPOSE, and its last beat ages out exactly like a dead one's
-// would. It outranks the beat it FOLLOWED and no other — a beat stamped after the marker was written by
-// a watcher that armed again, so a marker some failed cleanup left behind can never mask a live tier.
+// would. It outranks the beat it FOLLOWED and no other — a later timestamp OR a FRESH different
+// armed-watcher identity is another arm, so a marker whose rename lost that race cannot mask a live
+// watcher. Once that foreign beat is stale, a newer clean hand-off must win: otherwise overlapping
+// boards closed in last-beater-first order would leave the tier reporting a death forever.
 export function supervisionStatus(repoRoot, tier, now = Date.now()) {
     const beat = readBeat(repoRoot, tier);
     const standDown = readStandDown(repoRoot, tier);
     if (standDown === "UNREADABLE")
         return { tier, state: "UNREADABLE" };
-    if (standDown !== "NONE" && !(typeof beat === "object" && beat.mtimeMs > standDown.mtimeMs)) {
+    const beatOutranksStandDown = standDown !== "NONE" && typeof beat === "object" && (beat.mtimeMs > standDown.mtimeMs || (now - beat.mtimeMs <= SUPERVISION_STALE_MS &&
+        beat.armId !== undefined && standDown.armId !== undefined && beat.armId !== standDown.armId));
+    if (standDown !== "NONE" && !beatOutranksStandDown) {
         // the seat that stood down is named by the marker, falling back to whatever its last beat named
         const seat = standDown.seat ?? (typeof beat === "object" ? beat.seat : undefined);
         return { tier, state: "DISARMED", ...(seat !== undefined ? { seat } : {}) };

package/fixtures/gsd-sample/07-live-check/07-03-SUMMARY.md

@@ -1 +1,5 @@
+---
+status: complete
+---
+
 # done earlier

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tickmarkr",
-  "version": "2.1.3",
+  "version": "2.1.5",
   "description": "Spec in, verified work out.",
   "type": "module",
   "license": "MIT",

package/skills/tickmarkr-overseer/SKILL.md

@@ -249,6 +249,111 @@ detect: **the ruling would have made the worker commit the violation the task wa
 
 ### Context is a supervised resource, for BOTH tiers
 
+**THE TIERS CLEAR EACH OTHER AT 50%. Neither tier clears itself on its own notice.** Operator directive,
+2026-08-28, and it exists because **a seat cannot reliably observe its own exhaustion** — the seat that
+most needs clearing is the one least able to notice, and this project has now measured that three ways:
+an overseer ran nine hours at 86% unable to read its own number; a context watcher went **alive and blind**
+when the run's own status text pushed the percentage off the statusline; and an orchestrator went
+**366k → 970k of 1M between two checks** while its ACT wake sat unread in a detached log.
+
+The protocol, in both directions:
+
+1. **Overseer sees orch at ≥50%** → nudge it: write `HANDOFF-ORCH-<ver>.md`, then `/clear`, then re-read
+   its brief **and** its handoff, then **re-arm every watcher it listed** (a cleared session has none).
+2. **The returning orch, now fresh, checks the OVERSEER.** If the overseer is at ≥50%, it directs the
+   overseer to write its handoff and clear, and **points it at `HANDOFF-OVERSEER-<ver>.md` by path**.
+3. Whichever seat is fresh performs the check. **Never both at once** — the run keeps one supervising tier
+   at all times, and the seat holding the endgame goes second.
+4. **The duty to clear the other tier must SURVIVE a clear**, so it belongs in BOTH handoff files as a
+   standing re-arm item — not only in the message that ordered it. Earned 2026-08-28: the orchestrator
+   performed the check on the overseer BEFORE its own clear, precisely because clearing first would have
+   wiped the instruction to do it, and its handoff did not record the duty.
+5. **A seat cannot `/clear` ITSELF — so the OTHER TIER SENDS IT.** `/clear` is a CLI command typed into a
+   session and no tool invokes it in your own pane, but it is just text in someone else's: the partner
+   tier types it into your pane. **This is the whole reason the protocol is mutual**, and it means the
+   loop closes without the operator. The exchange, both directions, in this exact order:
+
+   ```bash
+   # 1. the seat crossing 50% writes its handoff FIRST, ending with its terminal marker
+   # 2. it asks the partner, naming its own pane and handoff path:
+   herdr pane run <partner> "I am at <N>%. Clear me: send /clear to <my-pane>, then point me at <my-handoff>."
+   # 3. the PARTNER sends the clear, then VERIFIES before pointing:
+   herdr pane run <my-pane> "/clear"
+   #    read the pane back — a cleared claude session shows an empty prompt and a reset context gauge
+   # 4. and only THEN, as a SEPARATE send, the re-orientation:
+   herdr pane run <my-pane> "You were cleared at <N>%. Read <handoff> and <brief>, re-arm EVERY watcher
+   they name — a cleared session has none — then confirm you are back."
+   ```
+
+   ⚠ **Steps 3 and 4 are two sends, never one.** A pointer batched with the clear lands *during* it and is
+   lost with the context it was meant to survive. Verify the clear landed by reading the prompt line
+   before sending the pointer — the same read-back every other send in this skill requires.
+   ⚠ **The partner must not clear itself in the same window.** One supervising tier stays live at all
+   times; the seat holding the endgame goes second.
+   ⚠ **Step 4 must state an EXPECTED-RETURN DEADLINE**, e.g. *"confirm you are back within 10 minutes."*
+   A clear order without one is an unbounded wait: see rule 6.
+
+6. **THE RETURN LEG — the returning seat's FIRST act after re-arming is a verified notice to its partner.**
+   Not its second, not once the next milestone lands. **Measured 2026-08-28 (OBS-743):** an overseer cleared
+   at 00:05Z, was back at 00:07Z, *read the orchestrator's pane at 00:10Z to take its percentage* — and said
+   nothing. The orchestrator's last line had been *"T7 is mine until you're back."* It then held the task
+   alone for **53 minutes** across a reviewer flake, a retry, a merge and the whole tip verify, with no
+   signal that its supervising tier existed. The notice went out only because the operator noticed the gap.
+
+   **A one-way read is not a handshake.** The adopt step tells you to READ the partner's pane, which feels
+   like contact and transmits nothing — that is exactly how this gets skipped by a seat following the
+   protocol correctly.
+
+   The notice is ONE line (a newline submits early), sent with `herdr pane run` and **read back**, and it
+   carries four things:
+   ```bash
+   herdr pane run <partner> "RETURN NOTICE <seat>: back on <my-pane> since <HH:MM>Z. WATCHERS I NOW HOLD:
+   <list>. SWEPT: <what was dead>. MISSION STATE AS I READ IT: <one clause>. Reply with every watcher YOU
+   still hold so we deconflict — do not arm anything I just named."
+   ```
+   - **where and since when**, so the partner can stop holding your duties;
+   - **the watcher inventory you now hold** — coverage is the thing both tiers silently assume about each
+     other, and a returning seat that re-arms without saying so produces double-coverage that reads as
+     redundancy and is actually two tiers each trusting the other;
+   - **anything you swept**, because a dead watcher the partner armed is *its* belief about coverage, not
+     yours, and it will keep believing it;
+   - **an explicit deconfliction request.** Ask for the partner's inventory back; do not infer it.
+
+   ⚠ **RE-ADOPT EVERY DETACHED WATCHER ON RETURN, and prove it from disk.** A detached watcher (`ppid 1`)
+   is the one kind that SURVIVES your clear, which is exactly why it rots unattended: `stat` its heartbeat
+   and treat **stale as dead**. Measured the same morning (OBS-742): a detached resolution watcher's
+   heartbeat was **157 minutes stale** and the task it existed to report had resolved **2h04m after its
+   last beat** — present, silent, and indistinguishable from healthy to anyone who did not look. Sweep it,
+   archive the heartbeat rather than deleting it so the gap stays measurable, and name it in the notice.
+
+   ⚠ **A CLEAR AND A DEATH ARE THE SAME SILENCE.** A seat that clears and never returns — wrong pane,
+   crashed host, operator closed the tab — is indistinguishable from one mid-`/clear`. That is why step 4
+   states a deadline: **partner silent past it → escalate to the operator.** Without the deadline the
+   protocol's most dangerous state has no timeout, and the surviving tier waits forever on a peer that no
+   longer exists.
+
+⚠ **`∑ NNNk tok` ON A CLAUDE STATUSLINE IS CUMULATIVE SESSION SPEND, NOT CONTEXT FILL.** The percentage
+is the fill; the token total is what has been spent across every turn and keeps climbing after a compaction
+or a clear. **Measured 2026-08-28, expensively:** this seat built a fallback watcher on `∑ Nk tok`, read
+`970k` as 97% of a 1M window, and sent an urgent clear-order to an orchestrator that was actually at
+**33%** — which then began a handoff and offered to discard a session two-thirds fresh, mid-endgame.
+**Read the `%`. Never derive fill from the token total, and never build an instrument on a signal whose
+SEMANTICS you have not verified against a second source.**
+
+**Why 50% and not 85%:** a handoff written at 50% is written by a seat whose judgment is intact. One
+written at 85% is written by a seat already degraded, about the decisions it is least able to summarise.
+The threshold buys judgment, not headroom.
+
+**Why the OTHER tier issues it:** a self-issued clear competes with whatever the seat is doing and loses.
+An instruction from the other tier arrives as work, and the tier issuing it is not the tier that has to
+overcome its own momentum to obey.
+
+⚠ **A detached watcher gives COVERAGE and takes away NOTIFICATION.** A wake written to a log file that no
+seat reads is not a wake. If the watcher must outlive a turn, it also needs a path that reaches a seat —
+a beat the other tier reads, a notification, or an artifact the other tier watches. **Measured 2026-08-28:
+`ACT: orch-215 at 970k/1000k — handoff + /clear NOW` fired correctly and sat unread in a scratchpad log
+while the orchestrator kept working.**
+
 Arm a context watcher on the orchestrator at spawn time and treat a threshold wake as a first-class event:
 finish the step, write a handoff, `/clear` **plus a fresh brief — never `/compact`**, because a compaction
 is a lossy summary nobody trusts while a clean session re-oriented from disk-verifiable state is reliable.
@@ -257,8 +362,9 @@ good, not after. If your own context cannot be read by the watcher, say so to th
 number — an unmeasured budget is not a small budget.
 
 ```bash
-.claude/skills/tickmarkr-overseer/scripts/watch-context.sh orchestrator <orchestrator-agent-or-pane> 60 75 <handoff-file>
-.claude/skills/tickmarkr-overseer/scripts/watch-context.sh overseer <overseer-agent-or-pane> 60 75 <handoff-file>
+# WARN 50 / ACT 50 — the mutual-clear threshold above, not a headroom alarm.
+.claude/skills/tickmarkr-overseer/scripts/watch-context.sh orchestrator <orchestrator-agent-or-pane> 50 50 <handoff-file>
+.claude/skills/tickmarkr-overseer/scripts/watch-context.sh overseer <overseer-agent-or-pane> 50 50 <handoff-file>
 ```
 
 The first argument chooses the closed per-seat tier (`orchestrator-context` or `overseer-context`),

package/skills/tickmarkr-overseer/scripts/watch-context.sh

@@ -26,12 +26,18 @@
 #      last beat aged into a permanent stale — gradual growth never reached the auto-clear path at all.
 #   4. EVERY TERMINAL EXIT STANDS THE TIER DOWN, so a watcher that finished reads DISARMED, not dead.
 #      Only a killed watcher reads STALE, which is exactly what STALE means.
+#   5. A BLIND READ ALARMS (OBS-739). Ageing the tier is visible only to someone already reading the beat
+#      table; the seat that armed this watcher must be TOLD its instrument went blind. Silence and health
+#      must never look alike.
 #
-# usage: watch-context.sh <orchestrator|overseer> <agent|pane> <warn-pct> <act-pct> [handoff-file] [poll-s] [cap-s]
+# usage: watch-context.sh <role-slug> <agent|pane> <warn-pct> <act-pct> [handoff-file] [poll-s] [cap-s]
+#   <role-slug> is ANY seat role — orchestrator, overseer, surgeon, consult — and names the tier
+#   `<role>-context`. It is deliberately NOT a closed set: see OBS-730 at the guard below.
 #   TKR_AUTO_CLEAR=1   at act-pct WITH a fresh handoff, send /clear and re-brief instead of waking.
 #   TKR_REBRIEF=<path> the file the re-briefed seat is told to read (defaults to the handoff).
 #   TKR_HANDOFF_MAX_AGE_S  how fresh "fresh" is (default 900).
 #   TKR_CLEAR_SETTLE_S     seconds to let a cleared seat settle before the re-brief (default 6).
+#   TKR_BLIND_ALARM_S      seconds unreadable before CONTEXT_BLIND alarms (default 120).
 
 set -u
 ROLE="${1:?supervising seat role required: orchestrator|overseer}"
@@ -45,10 +51,16 @@ MAXAGE="${TKR_HANDOFF_MAX_AGE_S:-900}"
 REBRIEF="${TKR_REBRIEF:-$HANDOFF}"
 SETTLE="${TKR_CLEAR_SETTLE_S:-6}"
 
+# OBS-730: this rejected every role that was not orchestrator|overseer with exit 64 — while the skill
+# mandates a context watcher on EVERY spawned seat. The rule and its own instrument disagreed, so the
+# rule was unsatisfiable for surgeons, consults and every auxiliary seat, and the gap read as coverage.
+# Any role slug names a tier; validate the SHAPE (a tier name reaches a shell) and never the membership.
 case "$ROLE" in
-  orchestrator|overseer) TIER="${ROLE}-context" ;;
-  *) echo "watch-context.sh: unknown seat role '$ROLE' — expected orchestrator or overseer" >&2; exit 64 ;;
+  *[!a-zA-Z0-9_-]*|'')
+    echo "watch-context.sh: role '$ROLE' must be a non-empty slug of [a-zA-Z0-9_-]" >&2; exit 64 ;;
 esac
+TIER="${ROLE}-context"
+
 
 # The supervision beat interval (SUPERVISION_BEAT_MS = 10s). The loop ticks at the beat cadence or the
 # caller's poll, whichever is SHORTER: a beat may only follow a successful read (rule 2), so the read
@@ -57,9 +69,33 @@ BEAT_EVERY=5
 TICK=$(( POLL < BEAT_EVERY ? POLL : BEAT_EVERY ))
 [ "$TICK" -ge 1 ] 2>/dev/null || TICK=1   # a zero or junk poll would spin, not watch
 SEAT="$TARGET"
+# ⚠ THE OTHER HALF OF OBS-730 LIVES IN THE PRODUCT, NOT HERE. `tickmarkr beat` enforces its own CLOSED
+# tier set (`src/run/supervision.ts:45`), so widening only this script would let an auxiliary seat's
+# watcher run while every beat failed SILENTLY — armed-looking, tier nonexistent. That is strictly worse
+# than the exit 64 it replaced, and it is the precise failure this whole file exists to prevent.
+# So PROBE ONCE and be loud about the answer. Watching still has real value without a tier — the warn,
+# act and blind lines all still fire — but it must never be mistaken for registered supervision.
 
-beat()      { tickmarkr beat "$TIER" --seat "$SEAT" >/dev/null 2>&1; }
-stand_down() { tickmarkr beat "$TIER" --stand-down --seat "$SEAT" >/dev/null 2>&1; }
+# ⚠ THE OTHER HALF OF OBS-730 LIVES IN THE PRODUCT, NOT HERE. `tickmarkr beat` enforces its own CLOSED
+# tier set (`src/run/supervision.ts:45`), so widening only this script would let an auxiliary seat's
+# watcher run while every beat failed SILENTLY — armed-looking, tier nonexistent, which is strictly
+# WORSE than the exit 64 it replaced and is the precise failure this file exists to prevent.
+# The refusal is reported by the FIRST REAL BEAT rather than by a startup probe: a probe that beats
+# would emit one before any successful read and break rule 2 outright, and a probe that parses the
+# usage banner binds this script to another command's help text. Beating is what we do anyway, so it
+# perturbs nothing — and because a beat only ever follows a successful read, rule 2 still holds.
+beat_refused=0
+beat() {
+  tickmarkr beat "$TIER" --seat "$SEAT" >/dev/null 2>&1 && return 0
+  if [ "$beat_refused" -eq 0 ]; then
+    beat_refused=1
+    echo "TIER_UNREGISTERED ${TIER} — the product refused this tier (its set: src/run/supervision.ts:45)"
+    echo "  watching CONTINUES and every warn/act/blind line below is real"
+    echo "  but \`tickmarkr status\` will NOT show this seat as covered — never read that absence as safe"
+  fi
+  return 0
+}
+stand_down() { tickmarkr beat "$TIER" --stand-down --seat "$SEAT" >/dev/null 2>&1; return 0; }
 # EVERY terminal exit — act, unsafe-act, cap — leaves through here, so none of them can forget to
 # record the hand-off. A killed watcher never runs it, which is the one case that must read STALE.
 trap stand_down EXIT
@@ -81,7 +117,7 @@ handoff_fresh() {
   [ -f "$HANDOFF" ] || return 1
   local age now mt
   now=$(date +%s)
-  mt=$(stat -f %m "$HANDOFF" 2>/dev/null || stat -c %Y "$HANDOFF" 2>/dev/null) || return 1
+  mt=$(stat -c %Y "$HANDOFF" 2>/dev/null || stat -f %m "$HANDOFF" 2>/dev/null) || return 1
   age=$((now - mt))
   [ "$age" -le "$MAXAGE" ]
 }
@@ -108,13 +144,35 @@ act_on() {
 
 warned=0
 elapsed=0
+blind=0            # seconds in the current unreadable spell (OBS-739)
+blind_alarmed=0
+BLIND_ALARM_S="${TKR_BLIND_ALARM_S:-120}"
 while [ "$elapsed" -lt "$CAP" ]; do
   P=$(context_pct)
   if [ -z "$P" ]; then
     # Rule 2: no reading, no beat. The tier ages to STALE and a supervisor comes looking, which is the
     # truth about a watcher that cannot see the seat it was armed on.
+    #
+    # Rule 5 (OBS-739): ALARM ON THE BLIND READ. Ageing a tier is not enough — it is only visible to
+    # someone already reading the beat table, and the measured failure was a watcher ALIVE AND BLIND for
+    # hours because the run's own status text pushed the percentage off the statusline. An instrument
+    # that cannot report its own absence is worse than none: the seat believes it has coverage and stops
+    # looking. So say so on stdout, where the supervising seat is actually woken. Once per blind spell,
+    # not every tick — a repeating alarm trains the reader to ignore it.
+    blind=$((blind + TICK))
+    if [ "$blind" -ge "$BLIND_ALARM_S" ] && [ "$blind_alarmed" -eq 0 ]; then
+      blind_alarmed=1
+      echo "CONTEXT_BLIND $TARGET — no percentage readable for ${blind}s; tier ${TIER} is ALIVE AND BLIND"
+      echo "  this watcher is NOT providing coverage: read the seat by hand and re-arm on a clear statusline"
+      echo "  do NOT substitute the token total — '∑ Nk tok' is cumulative SPEND, not context fill"
+    fi
     sleep "$TICK"; elapsed=$((elapsed + TICK)); continue
   fi
+  # a successful read closes the blind spell and re-arms the alarm for the next one
+  if [ "$blind_alarmed" -eq 1 ]; then
+    echo "CONTEXT_BLIND_CLEARED $TARGET — percentage readable again at ${P}% after ${blind}s blind"
+  fi
+  blind=0; blind_alarmed=0
   beat
 
   if [ "$P" -ge "$ACT" ] 2>/dev/null; then