@cohortapp/agent-sdk 2.18.15 → 2.18.17

package/lib/session/revive.mjs

@@ -22,9 +22,10 @@
  *
  * The daemon is the honest home for this. It is a separate process, it is
  * already alive on every seat that beats, it already reads the front-door
- * state every poll to decide who owns the inbox, and it runs every thirty
- * seconds. A seat whose door shuts is then measured in a minute rather than a
- * day, by something the shut door cannot take down with it.
+ * state every poll to decide who owns the inbox, and it re-checks the door on
+ * its own sixty-second cadence (REVIVE_CHECK_INTERVAL_MS). A seat whose door
+ * shuts is then measured in a minute or two rather than a day, by something
+ * the shut door cannot take down with it.
  *
  * Pure: the decision only. The daemon owns the kickstart.
  */
@@ -38,19 +39,33 @@ export const DEFAULT_REVIVE_BACKOFF_MS = 15 * 60 * 1000;
 /** How many restarts before the daemon stops and leaves it to a person. */
 export const DEFAULT_REVIVE_MAX = 3;
 
+/**
+ * Consecutive not-live reads required before the FIRST kickstart.
+ *
+ * A kickstart drops whatever the session was doing. One bad read is not
+ * enough evidence to pay that cost — a heartbeat file can be caught
+ * mid-write, or a poll can land in the one second between a session ending
+ * a tool call and starting the next. Two reads in a row, SIXTY seconds
+ * apart at the daemon's revive-check cadence (REVIVE_CHECK_INTERVAL_MS), is
+ * the line Ravi drew after the fleet had already seen what a single-read
+ * trigger costs.
+ */
+export const DEFAULT_REVIVE_CONFIRM_READS = 2;
+
 /**
  * Should the daemon restart the front door right now?
  *
  * The caller supplies the front-door state it already reads for dispatch, the
  * age of the session heartbeat, and what this daemon has already tried. Every
  * bound is explicit because the failure mode of getting this wrong is a seat
- * that restarts its own session every thirty seconds forever — which is worse
+ * that restarts its own session every sixty seconds forever — which is worse
  * than the shut door, and is the reason the ladder ends in "stop and say so"
  * rather than in another attempt.
  *
  * @param {{frontDoor?:string, sessionLive?:boolean, silentMs?:number|null,
  *          attempts?:number, lastAttemptAt?:number|null, now:number,
- *          reviveAfterMs?:number, backoffMs?:number, maxAttempts?:number}} a
+ *          reviveAfterMs?:number, backoffMs?:number, maxAttempts?:number,
+ *          notLiveReads?:number, confirmReads?:number}} a
  * @returns {{revive:boolean, reason:string}}
  */
 export function shouldReviveFrontDoor(a) {
@@ -59,6 +74,7 @@ export function shouldReviveFrontDoor(a) {
   const after = Number.isFinite(x.reviveAfterMs) && x.reviveAfterMs > 0 ? x.reviveAfterMs : DEFAULT_REVIVE_AFTER_MS;
   const backoff = Number.isFinite(x.backoffMs) && x.backoffMs > 0 ? x.backoffMs : DEFAULT_REVIVE_BACKOFF_MS;
   const max = Number.isFinite(x.maxAttempts) && x.maxAttempts >= 0 ? x.maxAttempts : DEFAULT_REVIVE_MAX;
+  const confirm = Number.isFinite(x.confirmReads) && x.confirmReads > 0 ? x.confirmReads : DEFAULT_REVIVE_CONFIRM_READS;
 
   // A seat whose lane is the daemon has no front door to revive: the daemon
   // itself is answering, and restarting a session job it does not depend on
@@ -82,6 +98,16 @@ export function shouldReviveFrontDoor(a) {
   if (!Number.isFinite(silentMs)) return { revive: false, reason: "silence-unknown" };
   if (silentMs < after) return { revive: false, reason: "within-grace" };
 
+  // Two-read hysteresis, gating only the FIRST kickstart: a kickstart drops
+  // whatever the session was mid-way through, so the daemon must not act on
+  // a single not-live read before it has confirmed the verdict on the next
+  // poll. `notLiveReads` undefined means a caller that predates this streak
+  // (every existing test above) — treat it as already confirmed so those
+  // callers see no change in behaviour; the daemon is the one caller that
+  // threads the real streak through.
+  const reads = x.notLiveReads === undefined ? confirm : Number(x.notLiveReads);
+  if (!(reads >= confirm)) return { revive: false, reason: "confirming" };
+
   const attempts = Number(x.attempts) || 0;
   if (attempts >= max) return { revive: false, reason: "budget-spent" };
 
@@ -93,6 +119,277 @@ export function shouldReviveFrontDoor(a) {
   return { revive: true, reason: `front door silent ${Math.round(silentMs / 1000)}s (attempt ${attempts + 1}/${max})` };
 }
 
+/**
+ * Should this seat's daemon job be restarted? Local check only — the
+ * reciprocal of `shouldReviveFrontDoor`'s job, but it CANNOT be run by the
+ * daemon on itself: a process that is alive to ask the question is a process
+ * launchctl reports a live pid for, so a live daemon can never observe its own
+ * down state. The actor is therefore the hourly `autoupdate.sh` backstop (it
+ * already parses `launchctl list` for `daemon_last_exit`), which is exactly
+ * the seat-local watchdog that catches a daemon that has stopped while the
+ * front door kept beating (Jacob's 2026-09-25 case: heartbeat.json ticking, no
+ * overdue handoff, daemon dead). `autoupdate.sh#revive_daemon` is the caller.
+ *
+ * `launchctl` is read by the caller from `launchctl list`, the same source
+ * `sibling_job_audit` and `autoupdate.sh` already parse: "pid" when the
+ * column holds a number, "dash" when it holds `-` (loaded, no pid), "absent"
+ * when the label is not in the list at all.
+ *
+ * PHANTOM PID: a silent crash loop can leave `launchctl list` holding a pid
+ * whose process has genuinely exited — the label still carries a number, but a
+ * `kill -0` on that pid fails because no such process is running, a kickstart
+ * yields another dead pid, and nothing lands on stderr. A LISTED pid is not a
+ * RUNNING daemon. So the caller decides liveness by `kill -0` on the pid and
+ * passes `pidAlive`; a phantom pid (`launchctl:"pid"` but `pidAlive:false`) is
+ * treated exactly like "dash" — loaded with no live process — and the beat age
+ * decides, instead of the listed pid rubber-stamping the daemon as alive.
+ *
+ * @param {{launchctl?:string, beatAgeMs?:number, staleMs?:number, pidAlive?:boolean}} a
+ * @returns {{revive:boolean, reason:string}}
+ */
+export function shouldReviveDaemon(a) {
+  const x = a && typeof a === "object" ? a : {};
+  const stale = Number.isFinite(x.staleMs) && x.staleMs > 0 ? x.staleMs : DEFAULT_REVIVE_AFTER_MS;
+
+  // A pid that launchctl lists but the OS does not actually run is a phantom —
+  // the same down state as a dash, dressed up as alive. Only an EXPLICIT
+  // `pidAlive === false` demotes it; a caller that does not probe liveness
+  // (`pidAlive` undefined) keeps the old behaviour, so nothing that never
+  // measured it changes.
+  const phantom = x.launchctl === "pid" && x.pidAlive === false;
+  const state = phantom ? "dash" : x.launchctl;
+
+  if (state === "pid") return { revive: false, reason: "daemon-alive" };
+
+  // No job at all is not a wedge to clear — it is a seat that was never
+  // provisioned with one, or had it removed, and a kickstart has nothing to
+  // aim at.
+  if (state === "absent") return { revive: false, reason: "daemon-job-absent" };
+
+  if (state === "dash") {
+    const beatAgeMs = Number(x.beatAgeMs);
+    // A loaded job with no live pid and a beat that has gone stale is the down
+    // state this exists to catch. A fresh beat under the same launchctl
+    // reading means the prior instance is still exiting, not that this one
+    // needs help.
+    if (!(beatAgeMs > stale)) return { revive: false, reason: "daemon-settling" };
+    return { revive: true, reason: phantom ? "daemon-phantom-pid" : "daemon-down" };
+  }
+
+  // Anything else — missing, empty, an error string from a failed parse — is
+  // a reading this cannot name a state from, and an unnamed state is never
+  // grounds to act.
+  return { revive: false, reason: "daemon-state-unknown" };
+}
+
+/** How many consecutive observations across the settle window prove continuity. */
+export const DEFAULT_CONFIRM_SAMPLES = 2;
+
+/**
+ * Did a revive attempt actually work? Checked from OUTSIDE the restart helper,
+ * on purpose: a helper that exits 0 has told you it ran, not that it succeeded,
+ * and trusting that exit code is the gap that let a shut front door sit
+ * unrestarted for days while the job meant to fix it kept reporting clean.
+ *
+ * ── WHY A ONE-SHOT PID CHECK IS NOT ENOUGH (Jacob, incident-validated) ──────
+ *
+ * A single "is there a pid, is the beat fresh" read passes two things that are
+ * NOT a revive: a PHANTOM pid (launchctl lists it, the process is dead),
+ * and a COME-UP-THEN-CRASH loop that beats once, dies, and is relaunched — its
+ * local beat file always looks fresh because the crash-looping restart keeps
+ * re-stamping it. The bar is "alive-AND-still-beating-server-side", proven two
+ * ways, either of which alone is sufficient:
+ *
+ *   1. UPTIME CONTINUITY — the one thing a crash loop cannot fake. One pid,
+ *      alive on every read (`pidAlive`), the SAME process identity (start-time,
+ *      `ps -o lstart`) across the whole settle window: no restart boundary. A
+ *      crash loop moves its start-time on every restart, so identity drift is
+ *      the tell. This alone still admits an alive-but-WEDGED process, so it is
+ *      paired with a fresh presence beat read back FROM THE SERVER — not the
+ *      local beat file, which the wedged/crash-looping process keeps stamping.
+ *      `serverBeatFresh:false` (server reachable, beat stale = alive-but-not-
+ *      publishing) blocks; `undefined` (could not reach the server) does NOT —
+ *      recovery is never held hostage to org reachability, continuity carries.
+ *
+ *   2. A COMPLETED UNIT OF WORK — the STRONGER signal when it exists, and
+ *      SUFFICIENT on its own (Jacob's positive control: A001 recovered dark →
+ *      12 authored posts). A crash loop cannot author a real unit of work.
+ *
+ * Work is sufficient, not necessary: a seat that recovered into an EMPTY queue
+ * does real nothing and MUST still pass on continuity alone — an assert that
+ * demanded work would fire a revive on every idle seat overnight and get
+ * itself disabled at 3am. Continuity-OR-work separates busy-recovered,
+ * crash-loop, phantom, AND quiet-recovered.
+ *
+ * ── THREE COMPLEMENTARY WITHIN-WINDOW CONDITIONS ────────────────────────────
+ *
+ * Continuity is three independent checks, each catching a failure the other two
+ * cannot: pid-recycling breaks start-time, a crash loop breaks pid, and a WRONG
+ * process (right pid, wrong binary) breaks comm. The third exists because `ps`
+ * is aliased to `pnpm start` on this fleet — a stray match on the wrong process
+ * would otherwise read as a revive. When the caller supplies `expectedComm` and
+ * a `comm` per sample (from `/bin/ps -p <pid> -o comm=`), a mismatch fails and
+ * NAMES `wrong-comm`; a null comm is unknown, not wrong, and continuity carries
+ * it. A caller that passes no `expectedComm` sees the pre-comm-check behaviour.
+ *
+ * @param {{
+ *   samples?:Array<{pid?:number, alive?:boolean, startTime?:string|null, comm?:string|null}>,
+ *   serverBeatFresh?:boolean, workObserved?:boolean, minSamples?:number,
+ *   expectedComm?:string
+ * }} a  `samples` are the per-read observations across the settle window;
+ *   `serverBeatFresh` is a fresh presence beat read back from the SERVER;
+ *   `workObserved` is a completed unit of work since the kickstart;
+ *   `expectedComm` is the binary name the revived pid must be running.
+ * @returns {{ok:boolean, reason:string}}
+ */
+export function confirmRevived(a) {
+  const x = a && typeof a === "object" ? a : {};
+
+  // Work is sufficient on its own and is the strongest evidence there is — a
+  // crash loop cannot produce a completed unit of work.
+  if (x.workObserved === true) return { ok: true, reason: "revived-work" };
+
+  const min = Number.isFinite(x.minSamples) && x.minSamples > 0 ? x.minSamples : DEFAULT_CONFIRM_SAMPLES;
+  const samples = Array.isArray(x.samples) ? x.samples : null;
+
+  // Fewer reads than the settle window needs cannot establish continuity: the
+  // process may be about to crash on its next breath. Not a failure to
+  // escalate — just not yet confirmed, so the caller re-checks within budget.
+  if (!samples || samples.length < min) return { ok: false, reason: "settling" };
+
+  // A live pid must appear SOMEWHERE in the window. If none ever did — every
+  // read dead — the helper claimed a process that is not there: a phantom pid
+  // (launchctl lists it, `kill -0` says dead) or an exit-0-with-no-pid. That is
+  // the failure-to-escalate that hands the seat to a person.
+  const isAlive = (s) => s && Number.isInteger(s.pid) && s.pid > 0 && s.alive === true;
+  const aliveSamples = samples.filter(isAlive);
+  if (aliveSamples.length === 0) return { ok: false, reason: "no-pid" };
+
+  // A dead read FOLLOWED BY a live one is a daemon mid-boot, not a failed
+  // revive. The first settle sample is taken the instant the kickstart returns,
+  // before a normal slow boot has drawn its first breath — so a dead first read
+  // then an alive one is boot-in-progress. Latching that as terminal aborts a
+  // revive that was working. A window that is not yet all-alive is still
+  // SETTLING: re-check within budget rather than escalate. Only two genuinely
+  // ALIVE reads can prove — or refute — continuity.
+  if (aliveSamples.length < samples.length) return { ok: false, reason: "settling" };
+
+  // Every read is alive. Same pid AND same start-time across the window = one
+  // instance that never restarted. A restart boundary between two ALIVE reads —
+  // a different pid, or the same pid with a different start-time (PID reuse by
+  // the relaunched process) — is the fingerprint of a crash loop, never a
+  // revive. `startTime` may be null on both when `ps` was unavailable;
+  // identical-null still agrees, and the pid continuity carries the degraded
+  // case.
+  const first = aliveSamples[0];
+  const continuous = aliveSamples.every((s) => s.pid === first.pid && s.startTime === first.startTime);
+  if (!continuous) return { ok: false, reason: "restart-boundary" };
+
+  // THIRD within-window condition: the binary under the pid must be the one we
+  // kickstarted. Right pid, right start-time, WRONG process is still not a
+  // revive — and `ps` aliased to `pnpm start` on this fleet makes a stray match
+  // real. Opt-in: only when the caller supplies `expectedComm`. A null comm is
+  // unknown (ps unavailable / pid vanished), not wrong — continuity carries it,
+  // as a null start-time does; only an OBSERVED, mismatching comm fails. Matched
+  // by suffix because `ps -o comm=` prints the absolute path and the expected
+  // value is a bare binary name.
+  if (x.expectedComm) {
+    const want = String(x.expectedComm);
+    const observed = aliveSamples.filter((s) => s.comm != null);
+    const commOk = observed.every((s) => {
+      const got = String(s.comm);
+      return got === want || got.endsWith(`/${want}`) || want.endsWith(`/${got}`);
+    });
+    if (!commOk) return { ok: false, reason: "wrong-comm" };
+  }
+
+  // Alive and continuous, but is it actually WORKING? The local beat file lies
+  // in a wedge, so the confirming signal is the presence beat the server
+  // recorded. An explicit stale reading (reachable, not publishing) blocks; an
+  // unknown reading (unreachable) does not — continuity carries it.
+  if (x.serverBeatFresh === false) return { ok: false, reason: "beat-not-advancing" };
+
+  return { ok: true, reason: "revived" };
+}
+
+/**
+ * A confirm outcome that must STOP the revive and hand the seat to a person,
+ * rather than fire another blind kickstart. A second attempt after a crash-loop
+ * assert buries the FIRST failure's log under the loop, so these outcomes are
+ * terminal: `no-pid` (phantom / exit-0-with-no-pid), `restart-boundary`
+ * (came-up-then-crashed within the settle window), `wrong-comm` (a live pid
+ * running the wrong binary — not the process we kickstarted), and
+ * `crash-loop-cross-poll` (an unrequested restart caught a poll later — the
+ * crash loop whose period outran the settle window). `settling` and
+ * `beat-not-advancing` are "not yet" — the caller may re-check within budget.
+ *
+ * @param {{ok?:boolean, reason?:string}} confirmed
+ * @returns {boolean}
+ */
+export function isTerminalReviveFailure(confirmed) {
+  const r = confirmed && confirmed.reason;
+  return r === "no-pid" || r === "restart-boundary" || r === "wrong-comm" || r === "crash-loop-cross-poll";
+}
+
+/**
+ * Did the session job restart WITHOUT this daemon asking it to, BETWEEN two
+ * daemon polls? The unbounded companion to `confirmRevived`'s within-window
+ * continuity check.
+ *
+ * ── WHY WITHIN-WINDOW CONTINUITY IS NOT ENOUGH ──────────────────────────────
+ *
+ * `confirmRevived` proves continuity across a SETTLE WINDOW (a few seconds). A
+ * crash loop whose period EXCEEDS that window shows the SAME identity twice
+ * inside it — two alive reads, same pid, same start-time — and false-confirms
+ * "revived". A 25s crash-loop period against a 5s settle window is invisible to
+ * a within-window check, and WIDENING the window only relocates the threshold:
+ * a 65s period beats a 60s window just as cleanly.
+ *
+ * The fix has no threshold to tune. The daemon persists the last-confirmed
+ * {pid, startTime} between its 60s poll iterations. On the NEXT poll, if the job
+ * holds a DIFFERENT identity (a different pid, OR the same pid with a moved
+ * start-time from PID reuse by the relaunched process) AND this daemon issued NO
+ * kickstart in the interval, that is an UNREQUESTED restart — the crash loop, at
+ * ANY period. A changed identity WITH a kickstart in between is exactly what a
+ * legitimate revive looks like and is never flagged.
+ *
+ * Pure: the verdict only. The daemon owns the persistence, the kickstart flag,
+ * and the halt.
+ *
+ * @param {{prev?:{pid?:number, startTime?:string|null}|null,
+ *          curr?:{pid?:number, startTime?:string|null}|null,
+ *          kickstartIssuedSince?:boolean}} a
+ *   `prev` is the last poll's confirmed identity (null on the first poll);
+ *   `curr` is this poll's observed identity; `kickstartIssuedSince` is whether
+ *   THIS daemon kickstarted the job between the two polls.
+ * @returns {{restarted:boolean, reason:string}}
+ */
+export function detectUnrequestedRestart(a) {
+  const x = a && typeof a === "object" ? a : {};
+  const prev = x.prev && typeof x.prev === "object" ? x.prev : null;
+  const curr = x.curr && typeof x.curr === "object" ? x.curr : null;
+
+  // Nothing to compare against yet — the first poll after boot establishes the
+  // baseline, it cannot judge drift from one.
+  if (!prev || !(Number.isInteger(prev.pid) && prev.pid > 0)) return { restarted: false, reason: "no-prior" };
+
+  // No live identity this poll is a DOWN door, not an identity change — that is
+  // the revive ladder's job. This function speaks only to drift between two
+  // observed identities.
+  if (!curr || !(Number.isInteger(curr.pid) && curr.pid > 0)) return { restarted: false, reason: "no-current" };
+
+  const sameIdentity = curr.pid === prev.pid && curr.startTime === prev.startTime;
+  if (sameIdentity) return { restarted: false, reason: "continuous" };
+
+  // Identity changed. If this daemon asked for it, that is a legitimate revive,
+  // not the loop.
+  if (x.kickstartIssuedSince === true) return { restarted: false, reason: "kickstart-issued" };
+
+  // Changed identity, no kickstart in between: an unrequested restart — the
+  // crash loop, at whatever period it runs.
+  return { restarted: true, reason: "unrequested-restart" };
+}
+
 /**
  * The command that restarts the front-door job. Pure — the caller runs it.
  *

package/lib/telemetry/collect.mjs

@@ -172,6 +172,7 @@ import { snapshot as countersSnapshot } from "../diagnostics/counters.mjs";
 import { replyDebtFromCounters } from "../daemon/reply-debt.mjs";
 import { summarisePinnedDrift, countPins } from "../upgrade/pinned-drift.mjs";
 import { IGNORED_DRIFT_REL } from "../upgrade/ignored-drift.mjs";
+import { listHandoffs, DEFAULT_HANDOFF_DEADLINE_MS } from "../session/handoffs.mjs";
 
 /** Default temperature probe ceiling — used only as a guard in alerts; here we just report. */
 const VALID_STATES = new Set(["active", "idle", "busy", "error", "offline"]);
@@ -1135,6 +1136,44 @@ async function collectIdentity(o, osImpl) {
 /** A main-session heartbeat older than this is not live. */
 export const SESSION_STALE_MS = 90_000;
 
+/**
+ * A FAILED REVIVE, written by the on-host actors (the daemon's front-door
+ * revive and `autoupdate.sh#revive_daemon`) when a kickstart returned but no
+ * live pid could be confirmed — a failure to escalate, which has to reach the
+ * fleet, not just the seat's log. Relative to the agent root; fresh window
+ * bounds how long it rides the beat after the last failed attempt.
+ */
+export const REVIVE_NOTE_REL = "state/telemetry/revive-note.json";
+export const REVIVE_NOTE_FRESH_MS = 90 * 60 * 1000;
+
+/**
+ * Pure: a revive-note that NAMES budget exhaustion, or null.
+ *
+ * A separate legibility defect from a failed revive: when the revive ladder
+ * spends its whole restart budget and STOPS (`shouldReviveFrontDoor` →
+ * `budget-spent`), nothing is written — the seat goes quiet and a quiet system
+ * looks healthy. A ladder that gave up is a failure that does not name itself.
+ * This turns that silence into a beat note carried through the SAME channel as
+ * `machine.reviveNote`, so the beat says "stopped because budget spent" rather
+ * than nothing. Only the budget-spent verdict qualifies — any other verdict
+ * (still confirming, backing off, answering) is not the ladder giving up.
+ *
+ * @param {{verdict?:string, target?:string, attempts?:number, at?:string}} a
+ * @returns {{reason:string, target?:string, detail:string, at:string}|null}
+ */
+export function budgetSpentNote(a = {}) {
+  const x = a && typeof a === "object" ? a : {};
+  if (x.verdict !== "budget-spent") return null;
+  const attempts = Number.isFinite(x.attempts) ? x.attempts : 0;
+  const at = typeof x.at === "string" && x.at ? x.at : new Date().toISOString();
+  return {
+    reason: "revive-budget-spent",
+    ...(typeof x.target === "string" && x.target ? { target: x.target } : {}),
+    detail: `revive budget spent after ${attempts} attempts`,
+    at,
+  };
+}
+
 /**
  * Pure: derive `{frontDoor, sessionLive}` from the heartbeat the main session's
  * feed writes every 15 s (`state/session/heartbeat.json` `{pid, ppid, sessionId,
@@ -1395,6 +1434,136 @@ export function sessionNote(a = {}) {
   };
 }
 
+/**
+ * Front-door-routed inbox lanes. `sweep`, `held` and `deferred` are the
+ * consumer's OWN maintenance lanes — items it parked on purpose, not items
+ * waiting on a person — and a `cohort-held-*` id is the sibling hold-queue
+ * shape (see meeting-capture's `kind==HOLD`). Neither is evidence the front
+ * door is failing to read; counting them would wedge a seat that is doing
+ * exactly what it was told to do.
+ */
+const WEDGE_EXCLUDED_LANES = new Set(["sweep", "held", "deferred"]);
+const WEDGE_HELD_ID_RE = /^cohort-held-/;
+
+/** An inbox item this file's `sessionWedge` treats as front-door-routed. */
+function isFrontDoorInboxItem(item) {
+  if (!item || typeof item !== "object") return false;
+  const id = typeof item.id === "string" ? item.id : "";
+  if (WEDGE_HELD_ID_RE.test(id)) return false;
+  const lane = typeof item.lane === "string" ? item.lane : "";
+  if (WEDGE_EXCLUDED_LANES.has(lane)) return false;
+  return true;
+}
+
+/**
+ * Pure: the wedge verdict — "beating but not reading". A seat can have a
+ * perfectly live heartbeat while the process behind it has stopped actually
+ * answering inbound (wedged on a dialog with no watchdog for THIS failure
+ * mode, a deadlocked event loop, anything short of the process dying). Two
+ * independent signals, checked in order, because they catch different
+ * failures and the first is the harder evidence:
+ *
+ *  1. PRIMARY — an un-acked handoff (`lib/session/handoffs.mjs`) past its
+ *     deadline. The consumer handed a cadence tick to the front door and
+ *     nobody acked it in time; this is true regardless of which front door is
+ *     nominally live, because a handoff is only ever written TO whichever
+ *     door claimed the tick. Deadline math mirrors `expireHandoffs` exactly
+ *     (`deadlineAt`, else `enqueuedAt + deadlineMs`) so the two never
+ *     disagree about which handoff is overdue.
+ *  2. SECONDARY — inbox-unconsumed. DEFERRED and HELD OFF in this build
+ *     (`SECONDARY_WEDGE_ENABLED === false`), because it cannot yet fire
+ *     correctly end-to-end (Hannah, PR #70 review #2). Three things must land
+ *     together first, NONE of them in this PR:
+ *       (i)   a consume-stamp on EVERY front-door path — today only
+ *             `ackHandoff` stamps `lastConsumedAt`, so it advances only on
+ *             handoff acks (~every 30 min), never on the inbound
+ *             claim/reply/done path in session-runtime;
+ *       (ii)  a real front-door inbox reader feeding `frontDoorInbox` into
+ *             `collectStatus` — nothing feeds it, so `inbox` is always `[]`;
+ *       (iii) lane/held keying matched to the real item shape — on this fleet
+ *             inbox items carry `channel`/`kind`/`claimed_by`, not `lane`, and
+ *             no id begins `cohort-held-`, so `isFrontDoorInboxItem`'s
+ *             exclusion is keyed on fields the items do not carry.
+ *     Shipped live at the 90s bound it would read most seats wedged, and
+ *     `rollout`'s `done` (which requires zero wedged) would never clear. The
+ *     branch, `isFrontDoorInboxItem` and `WEDGE_EXCLUDED_LANES` are kept
+ *     intact behind the flag so the follow-up wires them rather than rebuilds
+ *     them; the PRIMARY handoff-overdue tell is the real signal and is fully
+ *     live.
+ *
+ * Defensive by construction: every read is behind a type check, nothing here
+ * touches a clock or the filesystem, and no input shape can make it throw.
+ *
+ * @param {object} [a]
+ * @param {object[]} [a.handoffs]      `listHandoffs()` records (or equivalent)
+ * @param {object[]} [a.inbox]         raw inbox items, each `{id?, lane?}`
+ * @param {number|null} [a.lastConsumedAt] epoch ms, or null/undefined = never
+ * @param {"session"|"daemon"} [a.frontDoor]
+ * @param {boolean} [a.sessionLive]
+ * @param {number} [a.now]             epoch ms
+ * @param {number} [a.deadlineMs]      handoff deadline (default {@link DEFAULT_HANDOFF_DEADLINE_MS})
+ * @param {number} [a.staleMs]         inbox staleness bound (default {@link SESSION_STALE_MS})
+ * @returns {{wedged:false}|{wedged:true, reason:"handoff-overdue"|"inbox-unconsumed", since?:string}}
+ */
+// SECONDARY (inbox-unconsumed) is deferred — see the header above. A named
+// const, not a deleted branch: the follow-up flips this once the consume-stamp,
+// the frontDoorInbox feed and the real lane/held keying are all wired.
+export const SECONDARY_WEDGE_ENABLED = false;
+
+export function sessionWedge(a = {}) {
+  const o = a && typeof a === "object" ? a : {};
+  const now = Number(o.now);
+  if (!Number.isFinite(now)) return { wedged: false };
+  const deadlineMs = Number.isFinite(o.deadlineMs) && o.deadlineMs > 0 ? o.deadlineMs : DEFAULT_HANDOFF_DEADLINE_MS;
+  const staleMs = Number.isFinite(o.staleMs) ? o.staleMs : SESSION_STALE_MS;
+
+  // 1. PRIMARY — mirrors expireHandoffs' deadline math exactly.
+  const handoffs = Array.isArray(o.handoffs) ? o.handoffs : [];
+  for (const rec of handoffs) {
+    if (!rec || typeof rec !== "object" || rec.status !== "open") continue;
+    let deadline = Date.parse(rec.deadlineAt || "");
+    if (!Number.isFinite(deadline)) {
+      const enq = Date.parse(rec.enqueuedAt || "");
+      deadline = Number.isFinite(enq) ? enq + deadlineMs : now; // undated → already due
+    }
+    if (now >= deadline) {
+      return { wedged: true, reason: "handoff-overdue", since: new Date(deadline).toISOString() };
+    }
+  }
+
+  // 2. SECONDARY — DEFERRED (see header): held off until the consume-stamp,
+  // the frontDoorInbox feed and the real lane/held keying are wired end-to-end.
+  // Kept behind the flag so it is not shipped reading seats wedged spuriously.
+  if (SECONDARY_WEDGE_ENABLED && o.frontDoor === "session" && o.sessionLive === true) {
+    const inbox = Array.isArray(o.inbox) ? o.inbox : [];
+    const routed = inbox.filter(isFrontDoorInboxItem);
+    if (routed.length > 0) {
+      const lastConsumedAt = Number.isFinite(o.lastConsumedAt) ? o.lastConsumedAt : null;
+      const staleConsume = lastConsumedAt === null || now - lastConsumedAt > staleMs;
+      if (staleConsume) {
+        const since = lastConsumedAt !== null ? lastConsumedAt : oldestInboxAt(routed);
+        return {
+          wedged: true,
+          reason: "inbox-unconsumed",
+          ...(Number.isFinite(since) ? { since: new Date(since).toISOString() } : {}),
+        };
+      }
+    }
+  }
+
+  return { wedged: false };
+}
+
+/** Oldest `enqueuedAt`/`ts` among inbox items, epoch ms, else NaN. */
+function oldestInboxAt(items) {
+  let oldest = NaN;
+  for (const it of items) {
+    const ms = Date.parse((it && (it.enqueuedAt || it.ts)) || "");
+    if (Number.isFinite(ms) && (Number.isNaN(oldest) || ms < oldest)) oldest = ms;
+  }
+  return oldest;
+}
+
 /**
  * Pure: the beat's `machine.upgrade` from state/autoupdate/last.json
  * (`{from,to,at,ok,healthy,reason}` as autoupdate.sh writes it). Only the four
@@ -2069,6 +2238,60 @@ export async function collectStatus(o = {}) {
     } catch { /* no sessionNote — the beat still carries frontDoor/sessionLive */ }
   }
 
+  // 4b-iii. BEATING BUT NOT READING (DARK-SEAT) — `machine.wedge`, present
+  // ONLY when wedged, exactly like `sessionNote` above. The decision is the
+  // pure `sessionWedge`; this is the reads that feed it — the open handoff
+  // ledger — and it is fail-open in the same way every other probe here is: a
+  // throw anywhere (a corrupt handoff file) drops the field, never the beat.
+  // `opt.handoffs` overrides disk, mirroring `opt.attention` above, so a
+  // caller that already has the ledger in memory (the daemon, a test) is never
+  // made to round-trip it through the filesystem.
+  //
+  // The `frontDoorInbox`/`lastConsumedAt` reads that fed the SECONDARY
+  // (inbox-unconsumed) signal are gone from here: that signal is DEFERRED
+  // (`SECONDARY_WEDGE_ENABLED === false` in sessionWedge), so feeding it would
+  // be inert work. They return when the follow-up wires the secondary.
+  try {
+    const handoffs = opt.handoffs !== undefined ? opt.handoffs : listHandoffs(opt.agentRoot);
+    const wedge = sessionWedge({
+      handoffs,
+      frontDoor: machine.frontDoor,
+      sessionLive: machine.sessionLive,
+      now: nowMs,
+      deadlineMs: opt.handoffDeadlineMs,
+    });
+    if (wedge && wedge.wedged) machine.wedge = { reason: wedge.reason, ...(wedge.since ? { since: wedge.since } : {}) };
+  } catch { /* no wedge field — the beat still carries frontDoor/sessionLive/sessionNote */ }
+
+  // 4b-iv. A FAILED REVIVE — `machine.reviveNote`, present only when a revive
+  // kickstarted a job and then could NOT confirm a live pid (Jacob's
+  // drain-then-restart-daemon.sh exited 0 with a dead daemon). The two on-host
+  // actors — the daemon's front-door revive (agent-daemon.mjs) and the hourly
+  // daemon backstop (autoupdate.sh#revive_daemon) — write it to
+  // state/telemetry/revive-note.json; a no-pid-after-kickstart is a FAILURE TO
+  // ESCALATE and has to reach the fleet, not just this seat's log — the seat
+  // needs a person. Surfaced only while fresh (REVIVE_NOTE_FRESH_MS) so a
+  // recovered seat ages out; the writers refresh it every attempt and clear it
+  // on a confirmed revive. `machine` is an OPEN record (like wedge/upgrade), so
+  // this lands without an hq schema change. Fail-open. `opt.reviveNote`
+  // overrides disk for tests.
+  try {
+    const rn = opt.reviveNote !== undefined
+      ? opt.reviveNote
+      : (opt.agentRoot ? safeReadJson(join(resolve(opt.agentRoot), REVIVE_NOTE_REL)) : null);
+    if (rn && typeof rn === "object" && typeof rn.reason === "string") {
+      const at = Date.parse(rn.at || "");
+      const freshMs = Number.isFinite(opt.reviveNoteFreshMs) ? opt.reviveNoteFreshMs : REVIVE_NOTE_FRESH_MS;
+      if (Number.isFinite(at) && nowMs - at <= freshMs) {
+        machine.reviveNote = {
+          reason: rn.reason,
+          at: new Date(at).toISOString(),
+          ...(typeof rn.target === "string" && rn.target ? { target: rn.target } : {}),
+        };
+      }
+    }
+  } catch { /* no reviveNote — the beat still carries everything else */ }
+
   // 4c. last upgrade outcome (WP-M6) — `machine.upgrade`, absent until the
   // first autoupdate attempt; a corrupt file drops the field, never the beat.
   try {
@@ -2169,6 +2392,7 @@ export const _internals = {
   readSdkVersion,
   sessionLiveness,
   sessionNote,
+  sessionWedge,
   sanitizeNoteDetail,
   sessionJobLabel,
   sessionJobInstalled,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cohortapp/agent-sdk",
-  "version": "2.18.15",
+  "version": "2.18.17",
   "description": "Cohort Agent SDK — autonomous AI colleague runtime. Deploy senior AI colleagues on dedicated Mac minis, wired to the Cohort operating surface.",
   "type": "module",
   "bin": {