@cohortapp/agent-sdk 2.18.15 → 2.18.16

package/scripts/daemon/agent-daemon.mjs

@@ -160,8 +160,10 @@ import { processOne } from "../../lib/execution/pipeline.mjs";
 // of spawning `claude --print`; not live → today's dispatch, unchanged. The
 // gate is pure (lib/session/frontdoor.mjs); the assurance sweep reopens a
 // session claim that was neither replied nor done within 20 min.
-import { shouldReviveFrontDoor, reviveCommand, sessionJobLabelOnDisk } from "../../lib/session/revive.mjs";
-import { makeFrontDoorGate, sessionLiveFromHeartbeat, readFrontDoorState } from "../../lib/session/frontdoor.mjs";
+import { shouldReviveFrontDoor, reviveCommand, sessionJobLabelOnDisk, confirmRevived, isTerminalReviveFailure, detectUnrequestedRestart } from "../../lib/session/revive.mjs";
+import { budgetSpentNote } from "../../lib/telemetry/collect.mjs";
+import { checkLock as checkProcessLock } from "../../lib/singleton.js";
+import { makeFrontDoorGate, sessionLiveFromHeartbeat, readFrontDoorState, DEFAULT_STALE_MS } from "../../lib/session/frontdoor.mjs";
 import { CADENCE_REGISTRY } from "./cadence-handlers.mjs";
 import { sweepSessionInboxForDaemon } from "../../lib/session/inbox-claims.mjs";
 import { defaultEffects, scheduleToQueue } from "../../lib/execution/effects.mjs";
@@ -294,33 +296,264 @@ const _frontDoorGate = makeFrontDoorGate({ agentRoot: AGENT_REPO_DIR });
 // we want rather than a stale count carried across it.
 /** How often the daemon asks whether the front door has gone quiet. */
 const REVIVE_CHECK_INTERVAL_MS = 60 * 1000;
-const _revive = { attempts: 0, lastAt: null };
-async function reviveFrontDoorIfShut(state, deps = {}) {
+// `notLive` is the count of CONSECUTIVE not-live reads — the actor-side
+// hysteresis (Ravi). Takeover is harmless and flips at one read; a kickstart
+// drops a working session, so the FIRST one waits for two consecutive not-live
+// reads. A live read resets it. Per-process and deliberately not persisted: a
+// daemon restart is itself a change of circumstances.
+// `halted` latches when an assert comes back TERMINAL (phantom pid / crash
+// loop): the seat needs a person, and a blind second kickstart would bury the
+// first failure's log under the loop. One attempt on that road, then hand up.
+//
+// `confirmedIdentity` carries the last poll's {pid, startTime} ACROSS the 60s
+// poll cadence, and `kickstartThisInterval` records whether THIS daemon
+// kickstarted the job since that identity was recorded. A within-window
+// continuity check cannot see a crash loop whose period exceeds the settle
+// window — the same identity appears twice inside it. Comparing the confirmed
+// identity against the next poll's observation, with the kickstart flag,
+// catches an UNREQUESTED restart at ANY period, with no window to tune.
+const _revive = { attempts: 0, lastAt: null, notLive: 0, halted: false, confirmedIdentity: null, kickstartThisInterval: false };
+/** TEST-ONLY: clear the per-process revive state between cases. */
+export function _resetRevive() {
+  _revive.attempts = 0; _revive.lastAt = null; _revive.notLive = 0; _revive.halted = false;
+  _revive.confirmedIdentity = null; _revive.kickstartThisInterval = false;
+}
+
+/** Gap between the two settle-window reads that prove the new session did not
+ *  come up and immediately crash. Short — the door was already dark for the
+ *  full grace before we kickstarted, so this only has to outlast a boot wobble. */
+const CONFIRM_SETTLE_MS = 5000;
+
+/**
+ * One observation of the session job: its launchctl pid, whether that pid is a
+ * GENUINELY LIVE process (not a phantom launchctl lists but `ps` says is dead —
+ * a silent crash loop), the process start-time that fingerprints the instance,
+ * and the COMM (the binary running under the pid). A relaunch changes the
+ * start-time even if the pid is reused, so comparing start-times across the
+ * settle window is how a crash loop is told apart from one continuous process;
+ * the comm is the third, complementary check — a live pid running the WRONG
+ * binary is not the process we kickstarted.
+ *
+ * ABSOLUTE `/bin/ps`, never bare `ps`: `ps` is aliased to `pnpm start` on this
+ * fleet, so a bare `ps` is poison. `kill -0` (a builtin/alias-immune existence
+ * signal) decides liveness; `/bin/ps` reads the immutable start-time and comm.
+ */
+async function readSessionSample(label) {
+  let pid = null, alive = false, startTime = null, comm = null;
+  try {
+    const { stdout } = await execFileAsync("launchctl", ["list", label]);
+    const m = /"PID"\s*=\s*(\d+)/.exec(String(stdout || ""));
+    if (m) pid = Number(m[1]);
+  } catch { /* no pid — the kickstart produced no running process */ }
+  if (Number.isInteger(pid) && pid > 0) {
+    try { process.kill(pid, 0); alive = true; } catch { alive = false; } // signal 0 = existence check
+    try {
+      // One /bin/ps call for both the start-time and the comm — absolute path so
+      // the `ps`→`pnpm start` alias cannot poison it.
+      const { stdout } = await execFileAsync("/bin/ps", ["-o", "lstart=,comm=", "-p", String(pid)]);
+      const line = String(stdout || "").trim();
+      // `lstart` is a fixed-width 24-char date ("Wed Sep 25 12:00:00 2026")
+      // followed by the comm; split on the last field boundary the date ends at.
+      const m = /^(.{24})\s+(.*)$/.exec(line);
+      if (m) { startTime = m[1].trim() || null; comm = m[2].trim() || null; }
+      else { startTime = line || null; } // unexpected shape — keep what we have, comm unknown
+    } catch { startTime = null; comm = null; } // ps gone or pid vanished — degrade; pid continuity still carries
+  }
+  return { pid, alive, startTime, comm };
+}
+
+/** The binary the session job should be running — matched by suffix against the
+ *  observed comm. Bare "node" so any install prefix (/opt/homebrew/bin/node,
+ *  /usr/local/bin/node) matches; a live pid running anything else (a `ps`-alias
+ *  stray `pnpm`, a wrong process) fails the comm-check and names `wrong-comm`. */
+const EXPECTED_SESSION_COMM = "node";
+
+/**
+ * After a kickstart, ASSERT the door came back before recording success — a
+ * restart helper's exit code is not a revive (Jacob's drain-then-restart-daemon.sh
+ * exited 0 and left the process stopped with NO pid). A ONE-SHOT read is not
+ * enough: it passes a phantom pid and a come-up-then-crash loop whose local beat
+ * file always looks fresh. So take TWO reads across a settle window (proving the
+ * process is one continuous instance, not a crash loop) and pair them with the
+ * session's OWN beat freshness — for a session that beat IS the after-signal a
+ * wedge kills, because the heartbeat rides tool use, so a session that stops
+ * working stops beating (unlike a daemon, which a crash loop keeps re-stamping).
+ */
+async function defaultConfirmAfter({ label, now, staleMs, sleep }) {
+  const _sleep = sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const s1 = await readSessionSample(label);
+  await _sleep(CONFIRM_SETTLE_MS);
+  const s2 = await readSessionSample(label);
+  // serverBeatFresh for the SESSION: is the heartbeat it should now be writing
+  // fresh? undefined (couldn't read) does not block — continuity carries it.
+  let serverBeatFresh;
+  try {
+    const st = readFrontDoorState(AGENT_REPO_DIR, { now, staleMs });
+    if (st && st.liveness && Number.isFinite(st.liveness.ageMs)) {
+      serverBeatFresh = st.liveness.ageMs < (staleMs || DEFAULT_STALE_MS);
+    }
+  } catch { /* still stale — a fresh session has not beaten yet; leave undefined */ }
+  return { samples: [s1, s2], serverBeatFresh };
+}
+
+// A failed revive has to reach the FLEET, not just this log: a kickstart that
+// returned with no live pid is a failure to escalate — the seat needs a person.
+// collect.mjs reads this into `machine.reviveNote`, so the presence beat carries
+// it. Best-effort (the console line already fired); cleared on a confirmed revive.
+const REVIVE_NOTE_PATH = join(AGENT_REPO_DIR, "state", "telemetry", "revive-note.json");
+function writeReviveNote({ reason, target, detail, at }) {
+  try {
+    mkdirSync(join(AGENT_REPO_DIR, "state", "telemetry"), { recursive: true });
+    const tmp = `${REVIVE_NOTE_PATH}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify({ reason, target: target || null, detail: detail || "", at }));
+    renameSync(tmp, REVIVE_NOTE_PATH);
+  } catch { /* the beat surface is best-effort; the log line already fired */ }
+}
+function clearReviveNote() { try { unlinkSync(REVIVE_NOTE_PATH); } catch { /* nothing to clear */ } }
+
+export async function reviveFrontDoorIfShut(state, deps = {}) {
   const now = deps.now ? deps.now() : Date.now();
+  // TEST-ONLY seam: seed the per-process ladder state so a case can start on a
+  // given rung (e.g. budget already spent) without threading a dozen polls.
+  if (deps.seedRevive && typeof deps.seedRevive === "object") Object.assign(_revive, deps.seedRevive);
+  // A latched terminal failure (a prior kickstart came up and crash-looped, or
+  // produced a phantom pid) means the seat is a person's problem now — do not
+  // fire another blind kickstart on top of a loop that would bury the evidence.
+  if (_revive.halted) return { revive: false, reason: "halted-escalated" };
   const live = sessionLiveFromHeartbeat(state && state.heartbeat, { now });
+  const label = deps.label || sessionJobLabelOnDisk(readdirSync, homedir());
+
+  // ── CROSS-POLL CRASH-LOOP CATCH (unbounded, no threshold) ─────────────────
+  //
+  // The within-window continuity check inside confirmRevived cannot see a crash
+  // loop whose period EXCEEDS the settle window: it shows the same identity
+  // twice inside a few seconds and false-confirms. Between two 60s polls,
+  // though, the loop has restarted — so if we hold a previously CONFIRMED
+  // identity and this poll observes a DIFFERENT one with no kickstart issued in
+  // the interval, that is an unrequested restart at ANY period. HALT and note it
+  // rather than blindly re-confirm/re-kickstart a loop forever.
+  //
+  // Armed ONLY while the door is still in trouble (not reading live). A door
+  // that is healthily answering again has recovered — a later identity change is
+  // ordinary churn (an SDK upgrade, a `session restart`, a supervisor resume
+  // rotation), none of which this daemon should police as a crash loop. So a
+  // healthy live read DISARMS the check; the loop this hunts is precisely one
+  // whose relaunched instance never beats a full grace, so it stays not-live.
+  if (label && _revive.confirmedIdentity && state && state.sessionLive !== true) {
+    const readSample = deps.readSessionSample || readSessionSample;
+    let curr = null;
+    try { curr = await readSample(label); } catch { curr = null; }
+    const drift = detectUnrequestedRestart({
+      prev: _revive.confirmedIdentity,
+      curr,
+      kickstartIssuedSince: _revive.kickstartThisInterval,
+    });
+    if (drift.restarted) {
+      _revive.halted = true;
+      const detail = `crash-loop-cross-poll: pid ${_revive.confirmedIdentity.pid}(${_revive.confirmedIdentity.startTime}) → pid ${curr && curr.pid}(${curr && curr.startTime}) with no kickstart since`;
+      console.error(`[daemon] ${label} identity changed across the poll cadence with no kickstart issued (${detail}) — a crash loop whose period outran the settle window; halting and escalating (this seat needs a person)`);
+      writeReviveNote({ reason: "session-revive-failed", target: label, detail, at: new Date(now).toISOString() });
+      return { revive: false, reason: "crash-loop-cross-poll", confirmed: { ok: false, reason: "crash-loop-cross-poll" } };
+    }
+  } else if (state && state.sessionLive === true && _revive.confirmedIdentity) {
+    // Recovered and answering — disarm; a healthy session's later identity
+    // changes are churn, not the loop.
+    _revive.confirmedIdentity = null;
+    _revive.kickstartThisInterval = false;
+  }
+
+  // Track the consecutive not-live streak BEFORE the decision; a live read
+  // resets it so a session that beats between two quiet reads never accrues.
+  const notLiveNow = !(state && state.sessionLive === true);
+  _revive.notLive = notLiveNow ? _revive.notLive + 1 : 0;
+  const reviveAfterMs = Number(process.env.MAESTRO_SESSION_STALE_S || 0) * 1000 || undefined;
   const verdict = shouldReviveFrontDoor({
     frontDoor: state && state.frontDoor,
     sessionLive: state && state.sessionLive,
     silentMs: live.ageMs,
+    notLiveReads: _revive.notLive,
     attempts: _revive.attempts,
     lastAttemptAt: _revive.lastAt,
     now,
-    reviveAfterMs: Number(process.env.MAESTRO_SESSION_STALE_S || 0) * 1000 || undefined,
+    reviveAfterMs,
   });
-  if (!verdict.revive) return verdict;
-  const label = sessionJobLabelOnDisk(readdirSync, homedir());
+  if (!verdict.revive) {
+    // A ladder that spent its whole budget and STOPPED is a failure that does
+    // not name itself — the seat goes quiet and a quiet system looks healthy.
+    // Turn that silence into a beat note through the same reviveNote channel.
+    if (verdict.reason === "budget-spent") {
+      const note = budgetSpentNote({ verdict: verdict.reason, target: label || null, attempts: _revive.attempts, at: new Date(now).toISOString() });
+      if (note) writeReviveNote(note);
+    }
+    return verdict;
+  }
   if (!label) return { revive: false, reason: "no-session-job" };
+
+  // Supervisor coordination via the resume loop's OWN lock, not a soft note
+  // (Jacob). The supervisor holds the `session` singleton for its whole life
+  // and writes the heartbeat as a healthy resume makes progress. We only reach
+  // here after the door has been dark past the FULL grace AND confirmed over
+  // two reads 60s apart — so a resume gap is already excluded by time, and a
+  // live holder here is a supervisor PARKED in its launch probe (the 3.5-day /
+  // 15-day case this module exists for), for which the hard kickstart is
+  // exactly right. Consulting the lock tells a parked supervisor (override,
+  // logged) apart from a dead one (a clean restart), and never blocks the
+  // parked case — the failure that a hard "skip if held" would reintroduce.
+  const supervisor = (deps.checkSessionLock || (() => checkProcessLock("session")))();
+  if (supervisor && supervisor.running) {
+    console.error(`[daemon] ${label} front door dark past grace while a supervisor (pid ${supervisor.pid}) still holds the session lock — parked in its launch probe; hard-kickstarting over it`);
+  }
+
   _revive.attempts += 1;
   _revive.lastAt = now;
+  // This daemon is now the one that asked for the restart, so a new identity on
+  // the NEXT poll is expected, not the crash loop the cross-poll check hunts.
+  _revive.kickstartThisInterval = true;
   const cmd = reviveCommand(label, typeof process.getuid === "function" ? process.getuid() : 0);
   console.error(`[daemon] front door shut — ${verdict.reason}; restarting ${label}`);
   try {
     await (deps.execFile || execFileAsync)(cmd.file, cmd.args);
-    console.error(`[daemon] ${label} restarted; a fresh session clears whatever the old one was sitting on`);
   } catch (err) {
     console.error(`[daemon] could not restart ${label}: ${err && err.message ? err.message : err} — this seat needs a person`);
+    return { ...verdict, confirmed: { ok: false, reason: "kickstart-threw" } };
+  }
+  // The kickstart returned. Now prove it actually came back — across a settle
+  // window, not a one-shot read that a phantom pid or a come-up-then-crash
+  // would pass.
+  const staleMs = reviveAfterMs;
+  const after = deps.confirmAfter
+    ? await deps.confirmAfter({ label, now, staleMs })
+    : await defaultConfirmAfter({ label, now, staleMs });
+  const confirmed = confirmRevived({ ...after, staleMs, expectedComm: EXPECTED_SESSION_COMM });
+  if (confirmed.ok) {
+    console.error(`[daemon] ${label} restarted and answering (${confirmed.reason}); a fresh session clears whatever the old one was sitting on`);
+    clearReviveNote();
+    // Record the identity this revive confirmed so the NEXT poll can tell one
+    // continuous instance from a crash loop whose period outran the settle
+    // window. Reset the kickstart flag: the interval it justified is over.
+    const alive = Array.isArray(after && after.samples) ? after.samples.find((s) => s && Number.isInteger(s.pid) && s.pid > 0 && s.alive === true) : null;
+    _revive.confirmedIdentity = alive ? { pid: alive.pid, startTime: alive.startTime } : null;
+    _revive.kickstartThisInterval = false;
+  } else if (isTerminalReviveFailure(confirmed)) {
+    // Phantom pid or a restart boundary inside the settle window: the kickstart
+    // produced no living, continuous process. STOP — one attempt, then hand up
+    // with what we saw, rather than kickstart again into a loop that buries it.
+    _revive.halted = true;
+    const evidence = describeSamples(after && after.samples);
+    console.error(`[daemon] ${label} kickstart did NOT revive it (${confirmed.reason}): ${evidence} — a helper's exit code is not a revive; this seat needs a person (failure to escalate)`);
+    writeReviveNote({ reason: "session-revive-failed", target: label, detail: `${confirmed.reason}: ${evidence}`, at: new Date(now).toISOString() });
+  } else {
+    console.error(`[daemon] ${label} restarted; awaiting its first beat (${confirmed.reason}) — the next check confirms or re-attempts within budget`);
   }
-  return verdict;
+  return { ...verdict, confirmed };
+}
+
+/** One-line evidence of what the settle-window reads actually saw, for the log
+ *  and the beat note — so a failed escalation carries the fingerprint, not just
+ *  a verdict. */
+function describeSamples(samples) {
+  if (!Array.isArray(samples) || !samples.length) return "no reads";
+  return samples.map((s) => `pid=${s && s.pid != null ? s.pid : "none"}${s && s.alive ? "(alive)" : "(dead)"}`).join(" then ");
 }
 
 /**

package/scripts/daemon/assurance.mjs

@@ -78,7 +78,8 @@ import * as counters from "../../lib/diagnostics/counters.mjs";
 // the only composer of interim copy left in the system, and carries the two
 // copy rules (GENERIC_OPENER, FORWARD_PROMISE) every interim must satisfy.
 import { replyTier } from "../../lib/assurance/tier.mjs";
-import { isRollCallItem } from "../../lib/org/inbound/broadcast.mjs";
+import { isRollCallItem, BROADCAST_REASON } from "../../lib/org/inbound/broadcast.mjs";
+import { isMembershipReason } from "../../lib/org/inbound/directedness.mjs";
 import {
   claimRoomInterim,
   claimRoomNotice,
@@ -397,6 +398,16 @@ export function itemSnapshot(item) {
     // reads belongs in this snapshot.
     scope_id: item.scope_id || null,
     thread_id: item.thread_id || null,
+    // WHY THIS ADDRESS PROVENANCE IS A DEBT FIELD, not decoration. The sweep and
+    // the silent-success path SPEAK from `rec.item`, long after the live item is
+    // gone, and one decision they make is whether a rescued result belongs in
+    // this room at all: a membership/broadcast-proved surface (a doc comment
+    // shared to a channel, a room this seat merely belongs to) is ambient, and
+    // dumping a finished session's result text into it is narration nobody is
+    // waiting on 1:1 — the exact leak doc-comment surfaces close silently to
+    // avoid. Without `direct_reason` in the snapshot the DM/ambient distinction
+    // is unrecoverable at sweep time; with it, the guard fails open to a DM.
+    direct_reason: item.direct_reason || null,
     sender: item.sender || null,
     sender_email: item.sender_email || null,
     subject: item.subject || null,
@@ -1280,6 +1291,32 @@ export function composeSilentSuccess(rec, o = {}) {
   return `${head} I don't have a clean result to show you, though. Want me to run it again?`;
 }
 
+/**
+ * Is this obligation's surface AMBIENT rather than a 1:1 the requester waits on?
+ *
+ * The signal is `direct_reason` — WHY the inbound join decided this event was
+ * this seat's — carried into the snapshot by `itemSnapshot`. A membership or
+ * broadcast reason (`channel`/`participant`/`shared`, or `collective`) is
+ * access-shaped: the seat was addressed because it can SEE the thing, not
+ * because anything named it, so any number of seats in the room hold the same
+ * event. An identity-shaped reason (a DM, `owner`, `named`, an assignee) is one
+ * person waiting on one reply.
+ *
+ * FAILS OPEN TO "NOT AMBIENT" (i.e. narrate). An item whose provenance was
+ * never stamped — the historical default, and every pre-existing silent-success
+ * test — is treated as a waiting DM, because the cost of narrating into a real
+ * DM is nothing and the cost of silencing one is the very defect this module
+ * exists to fix.
+ *
+ * @param {object} rec the obligation record; its `item.direct_reason` is read
+ * @returns {boolean}
+ */
+function isAmbientSurface(rec) {
+  const reason = String((rec && rec.item && rec.item.direct_reason) || "");
+  if (!reason) return false; // unknown provenance → treat as a DM, narrate
+  return isMembershipReason(reason) || reason === BROADCAST_REASON;
+}
+
 /** A session interrupted by the daemon itself dying/restarting. */
 export function composeInterrupted() {
   return `Heads up — my session on this was interrupted before it finished (my end restarted). I've picked it back up; I'll come back with the answer.`;
@@ -1843,6 +1880,24 @@ export async function settleSession(a = {}) {
   }
 
   if (a.ok && !heard) {
+    // A CLEAN SILENT EXIT OUTSIDE A DM CLOSES QUIETLY, LIKE A DOC COMMENT.
+    // The rescue message exists to hand a waiting requester the result their
+    // session produced but never sent. On an ambient/membership-proved surface
+    // there is no such requester — the seat was addressed because it can see
+    // the room, not because anyone named it — so the same message is result
+    // text NARRATED into a shared room, the leak doc-comment surfaces already
+    // close silently to avoid. The debt is still discharged (silent is not
+    // un-closed); only the narration is withheld. `direct_reason` reaches here
+    // through `itemSnapshot`, and the guard fails open to narrating.
+    if (isAmbientSurface(rec)) {
+      closeObligation(a.key, {
+        outcome: "answered",
+        now,
+        note: "session exited 0 without speaking; ambient surface closed without narration",
+      });
+      counters.bump("assurance.silent_success_ambient", { service: rec.service });
+      return { spoke: false, text: null, verdict: "silent-success", willRetry: false };
+    }
     const finalText = safeResultText(a.stdout);
     const text = composeSilentSuccess(rec, { finalText });
     const res = await send(item, text, { kind: "reply", idempotencySuffix: `rescue-${rec.attempts || 0}` });

package/scripts/fleet/rollout.mjs

@@ -545,6 +545,15 @@ export function seatVersion(entry) {
  * cannot see, and it would be wrong on whichever side of the hq deploy it was
  * not written for.
  *
+ * Each row also carries `wedged` (bool) and `wedgeReason` (string|null),
+ * derived from the same `machine` block {@link seatStuck} reads: a seat is
+ * wedged when the beat itself reports `machine.wedge.reason` (published by
+ * collect.mjs's sessionWedge — beating, but not reading its inbox/handoffs),
+ * OR when `machine.frontDoor === "session"` and `machine.sessionLive === false`
+ * (the front door is shut outright). The version stays on the row either way —
+ * wedged is a verdict {@link classifySeat} applies, not a fact this function
+ * withholds.
+ *
  * @param {object[]} members
  * @param {{seatWindowMs?:number, now?:number}} [o]
  * @returns {{seats:object[], nonSeats:object[], readCarriesVersionField:boolean}}
@@ -563,6 +572,10 @@ export function toSeats(members, o = {}) {
     }
     const p = m.presence && typeof m.presence === "object" ? m.presence : null;
     const beatMs = p && Number.isFinite(p.lastBeatMs) ? p.lastBeatMs : null;
+    // Same accessor seatStuck uses: the beat's machine block, wherever it hangs.
+    const mach = (m.status && typeof m.status === "object" && m.status.machine) || m.machine || {};
+    const wedge = mach.wedge && typeof mach.wedge === "object" ? mach.wedge : null;
+    const doorDown = mach.frontDoor === "session" && mach.sessionLive === false;
     const row = {
       id: String(m.id || ""),
       slug: String(m.slug || ""),
@@ -572,6 +585,8 @@ export function toSeats(members, o = {}) {
       lastBeatMs: beatMs,
       ...seatVersions(m),
       stuck: seatStuck(m, o.now),
+      wedged: !!((wedge && wedge.reason) || doorDown),
+      wedgeReason: (wedge && typeof wedge.reason === "string" && wedge.reason) || (doorDown ? "front-door-not-live" : null),
     };
     if (beatMs !== null && beatMs <= windowMs) seats.push(row);
     else nonSeats.push(row);
@@ -582,14 +597,18 @@ export function toSeats(members, o = {}) {
 
 /**
  * Verdict for one seat against the target version. Pure.
+ *   wedged       — beating, but its front door is not answering (a shut
+ *                  session or an overdue handoff); outranks current/stale —
+ *                  the version stays on the row for display, unread here
  *   current      — reported version equals the target
  *   stale        — reported a different (older or newer) version
  *   unverifiable — beating, but the read carries no version at all
  * @param {object} seat
  * @param {string} target
- * @returns {"current"|"stale"|"unverifiable"}
+ * @returns {"wedged"|"current"|"stale"|"unverifiable"}
  */
 export function classifySeat(seat, target) {
+  if (seat && seat.wedged) return "wedged";
   const v = seat && seat.version;
   if (!v) return "unverifiable";
   return compareVersions(v, target) === 0 ? "current" : "stale";
@@ -604,7 +623,7 @@ export function classifySeat(seat, target) {
  */
 export function summarise(fleet, target) {
   const rows = (fleet.seats || []).map((s) => ({ ...s, verdict: classifySeat(s, target) }));
-  const counts = { current: 0, stale: 0, unverifiable: 0 };
+  const counts = { current: 0, stale: 0, unverifiable: 0, wedged: 0 };
   for (const r of rows) counts[r.verdict] += 1;
   // Behind AND proved it cannot arrive — a strictly stronger statement than
   // `stale`, which clears itself on the next hourly run.
@@ -623,6 +642,7 @@ export function summarise(fleet, target) {
   // AND no seat is known to be unable to move.
   const stuck = rows.filter((r) => r.stuck && r.stuck.verdict === "stuck");
   const stale = rows.filter((r) => r.verdict === "stale");
+  const wedged = rows.filter((r) => r.verdict === "wedged");
   const staleSlugs = new Set(stale.map((r) => r.slug));
   return {
     target,
@@ -636,8 +656,10 @@ export function summarise(fleet, target) {
     stuckBehind: stuck.filter((r) => staleSlugs.has(r.slug)),
     /** Stuck against some other version while current on this one. Still a finding. */
     stuckElsewhere: stuck.filter((r) => !staleSlugs.has(r.slug)),
+    /** Beating, but its front door is not answering — a 4th verdict beside stale. */
+    wedged,
     readCarriesVersionField: fleet.readCarriesVersionField === true,
-    done: rows.length > 0 && counts.current === rows.length && stuck.length === 0,
+    done: rows.length > 0 && counts.current === rows.length && stuck.length === 0 && wedged.length === 0,
   };
 }
 
@@ -793,10 +815,18 @@ export function stuckClause(row, target) {
  * exit code: `behind` and `unverifiable` are different problems with different
  * fixes, and only the first is answered by waiting.
  *
+ * `wedged` is a fourth problem with a fourth fix: the seat is beating (so it is
+ * not `unverifiable`, and waiting for its next beat proves nothing) but its
+ * front door is not answering — a shut session or an overdue handoff. It is
+ * checked after `stuck` (stuck is the longer-standing, already-acted-on
+ * signal) and before `empty-fleet`/`unverifiable`/`behind`: reporting a wedged
+ * seat as merely "behind" would invite waiting it out, and waiting does
+ * nothing for a seat that is not reading.
+ *
  * Pure.
  *
  * @param {ReturnType<typeof summarise>|null|undefined} summary
- * @returns {{code:number, reason:"verified"|"stuck"|"behind"|"unverifiable"|"empty-fleet"|"no-fleet-read", note:string|null}}
+ * @returns {{code:number, reason:"verified"|"stuck"|"wedged"|"behind"|"unverifiable"|"empty-fleet"|"no-fleet-read", note:string|null}}
  */
 export function propagationOutcome(summary) {
   if (!summary || !Array.isArray(summary.rows)) {
@@ -829,6 +859,20 @@ export function propagationOutcome(summary) {
         renderVerdict(summary),
     };
   }
+  // WEDGED comes after stuck (stuck is longer-standing and still the one a
+  // person must act on first) but before empty-fleet/unverifiable/behind: a
+  // seat that is beating but not reading is not a seat anyone can wait out
+  // either, and it must not be reported as merely "behind" — waiting changes
+  // nothing when the front door itself is what is not answering.
+  if (summary.wedged && summary.wedged.length) {
+    return {
+      code: 3,
+      reason: "wedged",
+      note:
+        `${summary.wedged.length} seat(s) are beating but their front door is not answering (wedged) — the ` +
+        `daemon revive or a person must clear them; a version cannot be verified on a seat that is not reading.`,
+    };
+  }
   if (!summary.rows.length) {
     return {
       code: 3,

package/scripts/hooks/pre-write-yaml-validate.mjs

@@ -17,7 +17,14 @@
  * old_string replaced by new_string) and REFUSES — exit 2, a permissionDecision:"deny" JSON on
  * stdout and the reason on stderr — when:
  *   - an Edit's old_string is absent from the file, or matches more than once without
- *     replace_all (the edit would land somewhere the writer did not look at);
+ *     replace_all (the edit would land somewhere the writer did not look at); when that repeated
+ *     match is an `id:` line, the refusal names the real cause — the file already carries a
+ *     duplicate id and is unwritable via id-anchored edits until the collision is resolved;
+ *   - the would-be top-level `items:` list (or a top-level sequence) would carry two rows sharing
+ *     the same `id` value that was not already colliding on disk. A duplicate id slips past js-yaml
+ *     (the rows are distinct list entries, not duplicate map keys) but makes every id-anchored edit
+ *     ambiguous — the "collision then silently unwritable all day" failure — so it is refused loudly
+ *     as a WHOLE FILE BLOCK at the write boundary;
  *   - the result does not parse as YAML (js-yaml, which also rejects duplicate keys);
  *   - a provenance-keyed value NEW in this write ends on a dangling connector. The delta is
  *     judged, not the whole file, so a pre-existing truncated row never blocks an unrelated
@@ -108,6 +115,39 @@ export function guardedRowCount(doc) {
   return null;
 }
 
+/** The top-level list the id-uniqueness guard protects: `items:` or a top-level sequence, else null. */
+function guardedList(doc) {
+  if (Array.isArray(doc)) return doc;
+  if (doc && typeof doc === "object" && Array.isArray(doc.items)) return doc.items;
+  return null;
+}
+
+/**
+ * First `id` value that appears on two or more rows of the guarded top-level list, else null.
+ * A duplicate id makes every id-anchored edit ambiguous, so js-yaml lets it through (the rows are
+ * distinct list entries, not duplicate map keys) but the file becomes unwritable via id-anchored edits.
+ */
+export function duplicateItemId(doc) {
+  const list = guardedList(doc);
+  if (!list) return null;
+  const seen = new Set();
+  for (const row of list) {
+    if (!row || typeof row !== "object") continue;
+    const id = row.id;
+    if (typeof id !== "string" && typeof id !== "number") continue;
+    const key = String(id);
+    if (seen.has(key)) return key;
+    seen.add(key);
+  }
+  return null;
+}
+
+/** If `oldStr` is anchored on an `id:` line, return the id value; else null. */
+function repeatedIdAnchor(oldStr) {
+  const m = /(?:^|\n)\s*(?:-\s+)?id:\s*(.+?)\s*(?:\n|$)/.exec(oldStr);
+  return m ? m[1].replace(/^["']|["']$/g, "") : null;
+}
+
 /** Count non-overlapping occurrences of `needle` in `hay`. */
 function countOccurrences(hay, needle) {
   if (!needle) return 0;
@@ -138,7 +178,15 @@ export function wouldBeContent(toolName, ti, current) {
     if (typeof oldStr !== "string" || oldStr === "") return { refuse: "Edit with an empty old_string" };
     const n = countOccurrences(current, oldStr);
     if (n === 0) return { refuse: "old_string is not present in the file on disk — the edit would not land where you looked" };
-    if (n > 1 && !ti.replace_all) return { refuse: `old_string matches ${n} places — anchor it to one row or pass replace_all` };
+    if (n > 1 && !ti.replace_all) {
+      // A repeated `id:` line means the file already carries a duplicate id — the collision, not the
+      // anchor, is why every id-anchored edit matches twice. Name that instead of the generic advice.
+      const dupId = repeatedIdAnchor(oldStr);
+      if (dupId !== null) {
+        return { refuse: `WHOLE FILE BLOCKED — the file already contains a duplicate id '${dupId}', so this id-anchored edit matches ${n} places and cannot land. The file is unwritable via id-anchored edits until the duplicate id is resolved (give one of the colliding rows a unique id).` };
+      }
+      return { refuse: `old_string matches ${n} places — anchor it to one row or pass replace_all` };
+    }
     return { content: ti.replace_all ? current.split(oldStr).join(newStr) : current.replace(oldStr, () => newStr) };
   }
   if (toolName === "MultiEdit" && Array.isArray(ti.edits)) {
@@ -200,6 +248,19 @@ export function evaluate(payload, o = {}) {
     try { prev = yaml.load(current); prevParsed = true; } catch { prevParsed = false; }
   }
 
+  // Duplicate-id guard (id-uniqueness reserved at the write boundary). A second row sharing an id
+  // slips past js-yaml — the rows are distinct list entries, not duplicate map keys — but it makes
+  // every id-anchored edit ambiguous and the file effectively unwritable. Judged on the DELTA: a
+  // brand-new collision this write introduces always blocks; a pre-existing one the write leaves in
+  // place is surfaced by the id-anchored-Edit match-count path, not penalised twice here.
+  const nextDup = duplicateItemId(next);
+  if (nextDup !== null && (!prevParsed || duplicateItemId(prev) !== nextDup)) {
+    return {
+      decision: "deny",
+      reason: `${toolName} ${fp}: WHOLE FILE BLOCKED — two rows share id '${nextDup}'. A duplicate id makes every id-anchored edit ambiguous and the file unwritable. Give the new row a unique id before writing.`,
+    };
+  }
+
   // Provenance truncation — judged on the DELTA so pre-existing rows never block a new write.
   const before = new Set(prevParsed ? provenanceHits(prev).map((h) => `${h.id}\u0000${h.key}\u0000${h.value}`) : []);
   const fresh = provenanceHits(next).filter((h) => !before.has(`${h.id}\u0000${h.key}\u0000${h.value}`));