@cohortapp/agent-sdk 2.11.15 → 2.13.0

package/scripts/daemon/cadence-consumer.mjs

@@ -16,6 +16,13 @@
  *                     prompt under schedules/triggers/<name>.md.
  *      Unknown cadences with a prompt on disk default to escalate; without
  *      a prompt they go straight to dlq with a clear error.
+ *      FRONT DOOR (design §3.4): when the seat's main session is live, an
+ *      escalate/guarded tick is HANDED to it (state/session/handoffs/<id>.json
+ *      + the rendered prompt) and processed as "handed-to-session" instead of
+ *      spawning; a handoff un-acked past its deadline is re-enqueued with
+ *      metadata.handoffTimedOut=true and then spawned on the legacy lane.
+ *      A deferred tick (circuit, governance, concurrency, per-cadence
+ *      in-flight guard) is re-keyed to the TAIL and the drain keeps scanning.
  *   4. Respects .emergency-stop: while present, the loop logs a heartbeat
  *      but never spawns a sub-session and never processes events. Existing
  *      claims remain on disk so they can be resumed once the stop is lifted.
@@ -49,7 +56,12 @@
  *   logger         optional fn({ ts, level, …rest }) → void for tests.
  *   now            injectable clock fn() → ms (tests); used when re-stamping
  *                  in-flight claim mtimes so the stale-claim sweep can't sweep
- *                  a live escalate (audit L6).
+ *                  a live escalate (audit L6), and for handoff deadlines.
+ *   frontDoorState injected fn() → { frontDoor, sessionLive } (tests);
+ *                  defaults to lib/session/frontdoor#readFrontDoorState over
+ *                  config/session.yaml + state/session/heartbeat.json.
+ *   handoffDeadlineMs  how long a handed-off tick may sit un-acked before it
+ *                  is re-enqueued on the legacy lane (default 30 min).
  */
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync, appendFileSync, openSync, closeSync, statSync, unlinkSync, utimesSync } from "node:fs";
@@ -63,6 +75,7 @@ import {
   completeTick,
   failTick,
   requeueTick,
+  enqueueTick,
   recoverStaleClaims,
   sweepRetention,
   writeHealth,
@@ -70,12 +83,24 @@ import {
   logBusEvent,
   busDepth,
 } from "../../lib/cadence-bus.mjs";
+// FRONT DOOR (design §3.4). When the seat's main session is live, an
+// escalate/guarded tick is HANDED to it (a handoff file + the rendered prompt
+// on disk) instead of spawning a `claude --print` sub-session; the session acks
+// with `maestro session ack <tickId>`. A handoff past its deadline is expired
+// and the tick re-enqueued with metadata.handoffTimedOut=true, which is never
+// handed off again — so a wedged session cannot starve a cadence. Not live →
+// the legacy spawn, unchanged. The decision is pure; the state reader is the
+// one edge and it fails open to "not live".
+import { readFrontDoorState, shouldHandOffTick } from "../../lib/session/frontdoor.mjs";
+import { writeHandoff, listHandoffs, expireHandoffs, pruneHandoffs, handoffPaths } from "../../lib/session/handoffs.mjs";
+import { writeFileAtomic } from "../../lib/fs-atomic.mjs";
 import { resolveClaudeBin as sharedResolveClaude, augmentedPath, daemonClaudeArgs } from "../../lib/claude-bin.mjs";
 import { getCadenceDef } from "./cadence-handlers.mjs";
 import { obligationAllowedUnderPosture } from "../../lib/plan/compile.mjs";
 import { isHumanLaneCadence } from "../../lib/cadences.mjs";
 import { sessionPermissionArgs } from "../../lib/session-permissions.mjs";
 import { renderTemplate, buildContext } from "../../lib/render.mjs";
+import { withParallelism } from "../../lib/prompts/parallelism.mjs";
 // Model router (opt-in). A `schema_version: 2` config routes each cadence
 // sub-session's model through resolveChain (SPEC §6.2): the RouteDecision
 // supplies the --model flag, the session-retarget env (third-party backends),
@@ -291,6 +316,43 @@ export function routeCadenceSpawn(agentRoot, cadence) {
   }
 }
 
+/**
+ * A cadence trigger prompt, as the sub-session actually receives it.
+ *
+ * TWO transforms, and BOTH lanes must apply them or the two lanes disagree
+ * about what the same tick asked for:
+ *
+ *   1. `{{agent.*}}` / `{{company.*}}` identity tokens are rendered from
+ *      config/agent.json + config/company.json (lib/render.mjs), so a trigger
+ *      shipped generically in the package resolves to THIS seat. No-op on
+ *      token-free text.
+ *   2. The fleet parallelism directive LEADS the body (WP-M7 mechanic 5). An
+ *      escalate/guarded tick is exactly the sub-session the directive exists
+ *      for — a trigger that asks for six independent audits has, without it,
+ *      no standing permission to fan out, and runs them one at a time. The
+ *      inbox/backlog lane gets this from `prompt-builder.mjs#buildPrompt`;
+ *      cadence prompts never pass through that builder, which is how this lane
+ *      was missed. `withParallelism` is idempotent, so a trigger file that
+ *      already carries the text keeps exactly one copy.
+ *
+ * Pure apart from the two config reads; a missing/invalid config/agent.json
+ * leaves the body's tokens verbatim rather than failing the tick.
+ *
+ * @param {string} agentRoot
+ * @param {string} body the raw trigger prompt as read from disk
+ * @returns {string}
+ */
+export function renderCadencePromptBody(agentRoot, body) {
+  let out = typeof body === "string" ? body : "";
+  try {
+    const agentCfg = JSON.parse(readFileSync(join(agentRoot, "config/agent.json"), "utf-8"));
+    let companyCfg = {};
+    try { companyCfg = JSON.parse(readFileSync(join(agentRoot, "config/company.json"), "utf-8")); } catch { /* optional */ }
+    out = renderTemplate(out, buildContext(agentCfg, null, companyCfg));
+  } catch { /* no/invalid config/agent.json — leave body verbatim */ }
+  return withParallelism(out);
+}
+
 /**
  * Spawn a sub-session running the cadence's trigger prompt and resolve
  * with { exit_code, durationMs, stderr_tail }. Reads the prompt at call
@@ -315,17 +377,9 @@ function realSpawnSession({ agentRoot, cadence, promptPath, timeoutMs, log }) {
       return;
     }
 
-    // Render {{agent.*}} / {{company.*}} identity tokens at spawn time so framework
-    // triggers stay generic in the package and resolve to THIS agent + company
-    // (see lib/render.mjs). Synchronous, from config/agent.json + config/company.json.
-    // No-op on token-free text, so this is behaviour-preserving for any not-yet-
-    // tokenised trigger.
-    try {
-      const agentCfg = JSON.parse(readFileSync(join(agentRoot, "config/agent.json"), "utf-8"));
-      let companyCfg = {};
-      try { companyCfg = JSON.parse(readFileSync(join(agentRoot, "config/company.json"), "utf-8")); } catch { /* optional */ }
-      body = renderTemplate(body, buildContext(agentCfg, null, companyCfg));
-    } catch { /* no/invalid config/agent.json — leave body verbatim */ }
+    // Identity tokens + the parallelism directive, at spawn time — one seam,
+    // shared with the front-door handoff lane. See renderCadencePromptBody.
+    body = renderCadencePromptBody(agentRoot, body);
 
     const bin = resolveClaudeBin();
     // Permission scoping (audit H1). sessionPermissionArgs() defaults to the
@@ -549,6 +603,37 @@ export function startConsumer(opts = {}) {
   const governor = opts.governor || resourceGovernor;
   const rateGuard = opts.rateGuard || rateGuardModule;
   const budgetGuard = opts.budgetGuard || budgetGuardModule;
+  const handoffDeadlineMs = opts.handoffDeadlineMs;
+  const frontDoorStateImpl = typeof opts.frontDoorState === "function"
+    ? opts.frontDoorState
+    : () => readFrontDoorState(agentRoot, { now: nowMs() });
+
+  /**
+   * The front-door state for THIS decision. A throwing reader means "not
+   * live" — the legacy lane runs, nothing is dropped.
+   */
+  function frontDoorState() {
+    try {
+      const st = frontDoorStateImpl();
+      return st && typeof st === "object" ? st : { frontDoor: "daemon", sessionLive: false };
+    } catch {
+      return { frontDoor: "daemon", sessionLive: false, reason: "reader-error" };
+    }
+  }
+
+  /**
+   * Render a cadence prompt the way realSpawnSession does — the SAME
+   * `renderCadencePromptBody`, so the handed-off prompt is byte-identical to
+   * what a sub-session would have been given, parallelism directive included —
+   * and land it under state/session/handoffs/prompts/<tickId>.md.
+   */
+  function renderHandoffPrompt(tickId, promptPath) {
+    const fullPrompt = join(agentRoot, promptPath);
+    const body = renderCadencePromptBody(agentRoot, readFileSync(fullPrompt, "utf-8"));
+    const out = join(handoffPaths(agentRoot).prompts, `${tickId}.md`);
+    writeFileAtomic(out, body);
+    return out;
+  }
 
   /**
    * Admission gate for an escalation. Folds the shared 429 breaker + the
@@ -635,6 +720,11 @@ export function startConsumer(opts = {}) {
     dlq: 0,
     retries: 0,
     spawn_failures: 0,
+    // Front door (design §3.4): ticks handed to the live main session, handoffs
+    // that timed out and were re-enqueued, and deferrals re-keyed to the tail.
+    handed_off: 0,
+    handoff_timeouts: 0,
+    deferred: 0,
     last_event_id: null,
     last_decision: null,
   };
@@ -660,10 +750,94 @@ export function startConsumer(opts = {}) {
   // change recoverStaleClaims' signature (it lives in lib/cadence-bus.mjs,
   // owned by another change-set).
   const inFlightClaimIds = new Set();
+  // Per-cadence in-flight guard (audit F9: the same cadence spawned twice
+  // back-to-back). A cadence whose sub-session is still running, or whose
+  // handoff is still open with the session, must not start again — the second
+  // tick is deferred to the tail instead. Names, not ids: two ticks of one
+  // cadence are the duplicate this guards against.
+  const inFlightCadences = new Set();
 
   // Injectable clock so tests can drive the stale window deterministically.
   const nowMs = typeof opts.now === "function" ? opts.now : Date.now;
 
+  /** Is a cadence in flight — running here, or open as a handoff with the session? */
+  function cadenceInFlight(cadence) {
+    if (inFlightCadences.has(cadence)) return "sub-session";
+    try {
+      if (listHandoffs(agentRoot).some((h) => h.cadence === cadence)) return "handoff";
+    } catch { /* unreadable handoff dir → not a reason to block */ }
+    return null;
+  }
+
+  /**
+   * Re-queue a tick that cannot run YET (an upstream gate, never a per-event
+   * failure) to the TAIL under a new id (audit F8). Attempts untouched.
+   * `count:false` (the circuit/backoff skip) re-keys without touching the
+   * retry/deferral counters or last_decision — a held-back cadence was never
+   * attempted, and the skip is already logged and counted as skipped_*; a
+   * 30 s poll inside a 60 min circuit window must not read as 120 retries.
+   */
+  function deferTick(event, reason, extra = {}, { count = true } = {}) {
+    const r = requeueTick(agentRoot, event, { defer: true });
+    if (count) {
+      stats.retries += 1;
+      stats.deferred += 1;
+      stats.last_decision = "deferred";
+      log({ level: "info", stage: "escalate_deferred", reason, id: event.id, requeued_as: r && r.id, cadence: event.cadence, ...extra });
+    }
+    return { ok: false, decision: "deferred", reason };
+  }
+
+  // Ledger hygiene runs from the sweep at most this often.
+  const HANDOFF_PRUNE_EVERY_MS = 60 * 60_000;
+  let lastHandoffPruneAt = 0;
+
+  /**
+   * Expire handoffs past their deadline and re-enqueue each tick on the legacy
+   * lane with metadata.handoffTimedOut=true (never handed off again). The
+   * re-enqueue runs BEFORE the handoff is retired (expireHandoffs#onExpire):
+   * if the bus is unwritable the handoff stays open and the next sweep
+   * retries, so the cadence run is never lost. Cheap: one readdir of a small
+   * directory. Never throws.
+   */
+  function sweepHandoffTimeouts() {
+    const now = nowMs();
+    let out;
+    try {
+      out = expireHandoffs(agentRoot, {
+        now,
+        deadlineMs: handoffDeadlineMs,
+        onExpire: (h) => {
+          const meta = h.metadata && typeof h.metadata === "object" ? h.metadata : {};
+          const r = enqueueTick({
+            cadence: h.cadence,
+            source: "handoff-timeout",
+            agentRoot,
+            metadata: { ...meta, handoffTimedOut: true, handoffTickId: h.tickId, reason: `handoff to session timed out (${h.deadlineAt || "no deadline"})` },
+          });
+          // enqueueTick swallows an unwritable inbox (fallbackOnly, audit row
+          // only) — that is NOT back on the bus: keep the handoff open.
+          if (!r || !r.path) throw new Error(`tick not enqueued (${r && r.fallbackOnly ? "inbox unwritable" : "no path"})`);
+          stats.handoff_timeouts += 1;
+          log({ level: "warn", stage: "handoff_timed_out", id: h.tickId, cadence: h.cadence, requeued_as: r.id, deadline_at: h.deadlineAt || null });
+          return true;
+        },
+      });
+    } catch { return 0; }
+    for (const f of out.failed) {
+      log({ level: "error", stage: "handoff_requeue_failed", id: f.tickId, error: f.error, note: "handoff kept open; retried next sweep" });
+    }
+    if (now - lastHandoffPruneAt >= HANDOFF_PRUNE_EVERY_MS) {
+      lastHandoffPruneAt = now;
+      try {
+        const pr = pruneHandoffs(agentRoot, { now });
+        const n = pr.removed.done.length + pr.removed.prompts.length;
+        if (n > 0) log({ level: "info", stage: "handoffs_pruned", done: pr.removed.done.length, prompts: pr.removed.prompts.length });
+      } catch { /* hygiene is never a reason to skip the tick */ }
+    }
+    return out.expired.length;
+  }
+
   /**
    * Re-stamp the mtime of every in-flight claim file to the current time so
    * the next mtime-based stale sweep treats it as fresh. Best-effort: a missing
@@ -793,56 +967,22 @@ export function startConsumer(opts = {}) {
       });
       if (gate.reason === "circuit-open") stats.skipped_circuit_open += 1;
       else stats.skipped_backoff += 1;
-      // Put the event back in inbox unchanged. Attempt accounting is
-      // single-sourced in failTick (audit M5), so we no longer decrement here
-      // — a held-back-by-circuit re-queue is not a failed attempt and must
-      // not drift the count. Use the atomic requeueTick (audit M6) instead of
-      // a bare writeFileSync so a crash can't leave a half-written inbox file.
-      requeueTick(agentRoot, event);
+      // Put the event back — to the TAIL (F8). Attempt accounting is
+      // single-sourced in failTick (audit M5), so we never touch it here: a
+      // held-back-by-circuit re-queue is not a failed attempt, nor a retry.
+      deferTick(event, gate.reason, { retry_at: new Date(gate.retry_at).toISOString() }, { count: false });
       return { ok: false, decision: gate.reason };
     }
 
     // WS4 governance gate — beside the concurrency cap. If the host is under
     // memory/load pressure, the 429 breaker is open, or the daily budget is
-    // exhausted (essential-only), DEFER this cadence tick: requeue it unchanged
-    // and DO NOT call failTick (a governor/rate deferral is an upstream gate,
-    // not a per-event failure — burning retry budget here would eventually DLQ
-    // a perfectly good cadence just because the box was busy).
+    // exhausted (essential-only), DEFER this cadence tick: requeue it to the
+    // tail and DO NOT call failTick (a governor/rate deferral is an upstream
+    // gate, not a per-event failure — burning retry budget here would
+    // eventually DLQ a perfectly good cadence just because the box was busy).
     {
       const gov = governanceGate(event.cadence);
-      if (!gov.admit) {
-        log({
-          level: "info",
-          stage: "escalate_deferred",
-          reason: gov.reason,
-          id: event.id,
-          cadence: event.cadence,
-        });
-        requeueTick(agentRoot, event);
-        stats.retries += 1;
-        stats.last_decision = "deferred";
-        return { ok: false, decision: "deferred" };
-      }
-    }
-
-    if (activeSubSessions >= MAX_CONCURRENT_SUB_SESSIONS) {
-      // Re-queue and try again next tick. Single-owner cadence consumer
-      // means this can only happen when a prior tick is still running —
-      // queue depth is the right back-pressure signal.
-      log({
-        level: "info",
-        stage: "escalate_deferred",
-        id: event.id,
-        cadence: event.cadence,
-        active_subsessions: activeSubSessions,
-      });
-      // Re-queue unchanged — concurrent-spawn isn't a per-event failure, so
-      // it must not touch the attempt count (single-sourced in failTick,
-      // audit M5). Atomic requeueTick (audit M6) replaces the bare
-      // writeFileSync that could leave a half-written inbox file.
-      requeueTick(agentRoot, event);
-      stats.retries += 1;
-      return { ok: false, decision: "deferred" };
+      if (!gov.admit) return deferTick(event, gov.reason);
     }
 
     const def = getCadenceDef(event.cadence);
@@ -861,7 +1001,61 @@ export function startConsumer(opts = {}) {
       }
     }
 
+    // Per-cadence in-flight guard (F9): never the same cadence twice at once —
+    // neither as two sub-sessions nor as a sub-session beside an open handoff.
+    {
+      const why = cadenceInFlight(event.cadence);
+      if (why) return deferTick(event, `cadence-in-flight:${why}`);
+    }
+
+    // FRONT DOOR (§3.4): a live main session takes this tick instead of a
+    // sub-session. Handoff = rendered prompt on disk + the ledger file; the
+    // tick is processed here with decision "handed-to-session". A tick whose
+    // previous handoff timed out (metadata.handoffTimedOut) falls through to
+    // the legacy spawn — shouldHandOffTick is pure and owns that rule.
+    {
+      const fd = frontDoorState();
+      const verdict = shouldHandOffTick({ ...fd, mode: def?.mode, metadata: event.metadata });
+      if (verdict.handOff) {
+        try {
+          const rendered = renderHandoffPrompt(event.id, promptPath);
+          const h = writeHandoff(agentRoot, {
+            tickId: event.id,
+            cadence: event.cadence,
+            mode: def?.mode || "escalate",
+            promptPath: rendered,
+            metadata: { ...(event.metadata || {}), sourcePrompt: promptPath },
+          }, { now: nowMs(), deadlineMs: handoffDeadlineMs });
+          if (!h.ok) throw new Error(h.error || "handoff write failed");
+          completeTick(agentRoot, event.id, {
+            decision: "handed-to-session",
+            cadence: event.cadence,
+            prompt: promptPath,
+            handoff: h.path,
+            deadline_at: h.handoff && h.handoff.deadlineAt,
+          });
+          stats.handed_off += 1;
+          stats.last_decision = "handed-to-session";
+          log({ level: "info", stage: "handed_to_session", id: event.id, cadence: event.cadence, prompt: rendered, deadline_at: h.handoff && h.handoff.deadlineAt });
+          return { ok: true, decision: "handed-to-session" };
+        } catch (err) {
+          // A handoff we could not write is not a reason to lose the tick —
+          // fall through to the legacy spawn, loudly.
+          log({ level: "warn", stage: "handoff_failed_spawning_instead", id: event.id, cadence: event.cadence, error: err && err.message });
+        }
+      }
+    }
+
+    if (activeSubSessions >= MAX_CONCURRENT_SUB_SESSIONS) {
+      // Re-queue (to the tail) and try again next tick. Single-owner cadence
+      // consumer means this can only happen when a prior tick is still
+      // running — queue depth is the right back-pressure signal. Not a
+      // per-event failure: the attempt count (failTick, audit M5) is untouched.
+      return deferTick(event, "concurrency", { active_subsessions: activeSubSessions });
+    }
+
     activeSubSessions += 1;
+    inFlightCadences.add(event.cadence);
     // Audit L6: mark this claim in-flight so the periodic stale-claim sweep
     // (which can run concurrently with a long-running sub-session) does not
     // treat its claimed/<id>.json as crashed and re-queue it under us.
@@ -878,6 +1072,7 @@ export function startConsumer(opts = {}) {
       });
     } finally {
       activeSubSessions -= 1;
+      inFlightCadences.delete(event.cadence);
       inFlightClaimIds.delete(event.id);
     }
 
@@ -910,14 +1105,11 @@ export function startConsumer(opts = {}) {
         const rec = rateGuard.recordUsageLimit(RATE_PROVIDER, cadenceUl.resetAt, { agentRoot });
         log({ level: "warn", stage: "subsession_usage_limited", id: event.id, cadence: event.cadence, open_until: rec.openUntil, reset_at: rec.resetAt });
       } catch { /* */ }
-      // Same requeue-unchanged handling as a 429: a window-usage limit is a
-      // shared, provider-side gate — not evidence THIS cadence is broken — so
-      // requeue without failTick or a circuit trip; the shared breaker (held
-      // until reset) gates re-escalation.
-      requeueTick(agentRoot, event);
-      stats.retries += 1;
-      stats.last_decision = "deferred";
-      return { ok: false, decision: "deferred" };
+      // Same handling as a 429: a window-usage limit is a shared, provider-side
+      // gate — not evidence THIS cadence is broken — so requeue (to the tail)
+      // without failTick or a circuit trip; the shared breaker (held until
+      // reset) gates re-escalation.
+      return deferTick(event, "usage-limited");
     }
     if (rateGuard.classifyStderr(cadenceOut)) {
       try {
@@ -929,12 +1121,9 @@ export function startConsumer(opts = {}) {
       // NOT evidence that THIS cadence is broken, so we must NOT call
       // recordSubsessionFailure here: doing so would advance the per-cadence
       // circuit toward open and leave a perfectly-healthy cadence circuit-open
-      // even after the shared breaker clears. Requeue unchanged (no failTick,
+      // even after the shared breaker clears. Requeue to the tail (no failTick,
       // no circuit trip); the shared breaker gates re-escalation.
-      requeueTick(agentRoot, event);
-      stats.retries += 1;
-      stats.last_decision = "deferred";
-      return { ok: false, decision: "deferred" };
+      return deferTick(event, "rate-limited");
     }
 
     // Failure path: log + cap retries low. The exact stderr tail comes
@@ -1040,40 +1229,49 @@ export function startConsumer(opts = {}) {
     // Routed through the guarded wrapper so an in-flight claim is never swept
     // (audit L6).
     recoverStaleClaimsGuarded();
+    // Front door: a handed-off tick the session never acked comes back to the
+    // legacy lane here, ahead of the drain, so it is claimable in this tick.
+    sweepHandoffTimeouts();
 
     let processed = 0;
-    let escalatedThisTick = 0;
-    // Drain inline events as much as the consumer can in one tick; cap
-    // sub-session escalations at 1 per tick so a fast-failing cadence
-    // can't burn a whole minute's worth of retries inside a single poll.
-    // The next poll (DEFAULT_POLL_MS later) will pick up where we left off.
+    let spawnedThisTick = 0;
+    // Head-of-line (F8): a deferred tick is re-keyed to the tail, so the loop
+    // KEEPS SCANNING past it to the next cadence instead of breaking. This set
+    // (keyed by the tick's original id, which a re-key preserves) is how the
+    // loop notices it has come back round to a tick it already deferred in
+    // this very tick — it puts that one back untouched and stops, so a queue
+    // holding only un-runnable ticks costs one visit per tick, not sixteen.
+    const seenThisTick = new Set();
     while (!stopping) {
       const claim = claimNextTick(agentRoot);
       if (!claim) break;
       const event = claim.event;
+      const key = (event.metadata && event.metadata.originalId) || event.id;
+      if (seenThisTick.has(key)) {
+        requeueTick(agentRoot, event);
+        break;
+      }
+      seenThisTick.add(key);
       activeTick = event.id;
-      let didEscalate = false;
+      let didSpawn = false;
       try {
-        const def = getCadenceDef(event.cadence);
-        const willEscalate = !def || (def.mode !== "inline" && (def.mode !== "guarded" || true));
-        // Roughly: if it's not a registry-inline cadence, we MAY escalate.
-        // We don't yet know if the guard will say inline; processEvent
-        // will tell us via stats. Use the escalated stats delta as the
-        // signal that an actual sub-session ran this iteration.
-        const before = stats.escalated + stats.spawn_failures + stats.skipped_circuit_open + stats.skipped_backoff;
+        // Did a sub-session actually run (or fail to spawn) this iteration? A
+        // deferral — circuit/backoff skip, governance, concurrency, in-flight
+        // guard — is NOT a spawn and must not end the scan (that was the
+        // head-of-line block). A handoff is not a spawn either: it is cheap.
+        const before = stats.escalated + stats.spawn_failures;
         await processEvent(event);
-        const after = stats.escalated + stats.spawn_failures + stats.skipped_circuit_open + stats.skipped_backoff;
-        if (after > before) didEscalate = true;
-        // Silence unused var warning.
-        void willEscalate;
+        const after = stats.escalated + stats.spawn_failures;
+        if (after > before) didSpawn = true;
       } finally {
         activeTick = null;
       }
       processed += 1;
-      if (didEscalate) escalatedThisTick += 1;
-      // Hard cap: at most ONE sub-session spawn per tick. Inline ticks
-      // keep draining freely (they're cheap).
-      if (escalatedThisTick >= 1) break;
+      if (didSpawn) spawnedThisTick += 1;
+      // Hard cap: at most ONE sub-session spawn per tick so a fast-failing
+      // cadence can't burn a whole minute's worth of retries inside a single
+      // poll. Inline ticks and handoffs keep draining freely (they're cheap).
+      if (spawnedThisTick >= 1) break;
       if (processed >= 16) break; // soft batch cap
     }
     return { processed };
@@ -1216,6 +1414,8 @@ export function startConsumer(opts = {}) {
     _recoverStaleClaimsGuarded: recoverStaleClaimsGuarded,
     _markInFlight: (id) => inFlightClaimIds.add(id),
     _clearInFlight: (id) => inFlightClaimIds.delete(id),
+    // Front door: the open handoffs this consumer has written for the session.
+    _handoffs: () => listHandoffs(agentRoot),
   };
 }
 

package/scripts/daemon/cadence-handlers.mjs

@@ -679,6 +679,33 @@ const MESSAGING_CURSOR_REL = join("state", "messaging", "inbound-cursor.json");
  * (re)install starts at "now" and replays nothing. A real, persisted cursor
  * (always > 0 in practice — see writeMessagingCursor) is returned as-is.
  */
+/**
+ * The seat's own member cuid, as resolved by `agent-daemon.resolveSelfMemberId`
+ * and persisted to `config/agent.json`. This is the `actor` hq stamps on every
+ * event the seat emits, so it is the ONLY id the wide reader's own-echo and
+ * mention joins can match against.
+ *
+ * Returns "" when unresolved. Also returns "" when the field holds the SLUG
+ * (COHORT_AGENT_ID) rather than a cuid — a bad writer putting the slug in the
+ * cuid field would otherwise make this fix mask the very bug it fixes, since a
+ * slug read from disk is exactly as broken as a slug read from env.
+ *
+ * @param {string} agentRoot
+ * @returns {string} member cuid, or "" if unresolved
+ */
+function persistedMemberId(agentRoot) {
+  try {
+    const c = JSON.parse(readFileSync(join(agentRoot, "config", "agent.json"), "utf-8"));
+    const mid = c && typeof c.memberId === "string" ? c.memberId.trim() : "";
+    if (!mid) return "";
+    const slug = String(process.env.COHORT_AGENT_ID || "").trim();
+    if (slug && mid === slug) return "";
+    return mid;
+  } catch {
+    return "";
+  }
+}
+
 function readMessagingCursor(agentRoot) {
   try {
     const p = join(agentRoot, MESSAGING_CURSOR_REL);
@@ -813,11 +840,36 @@ async function guardMessagingInbound({ event, agentRoot, log }, opts = {}) {
     // skipped, and the agent re-ingests its own replies as fresh inbound (a
     // conversation with itself). config/org.yaml does not carry an agentId, so
     // env is the reliable source on a real machine.
+    //
+    // MUST BE THE MEMBER CUID, NOT THE SLUG. hq names the actor on every
+    // /v1/events row by member cuid ("cmqh0te…"); COHORT_AGENT_ID is a SLUG
+    // ("A028"). Every directedness join in the wide reader — own_echo, mention,
+    // assignee, decision proposer, doc owner — compares `me` against a
+    // cuid-shaped payload field, so handing it the slug does not throw: it
+    // silently answers "no" to every identity question. own_echo then never
+    // fires and the seat re-ingests its own outbound, which produces a holding
+    // note, which is itself re-ingested — a self-sustaining loop that burns a
+    // sub-session per cycle and posts into real rooms.
+    //
+    // agent-daemon.resolveSelfMemberId already resolves the cuid via whoami and
+    // persists it to config/agent.json; prefer that, and fall back to the slug
+    // (degraded, but better than no id) only until it has been resolved once.
     const agentId =
       opts.agentId ||
+      persistedMemberId(agentRoot) ||
       process.env.COHORT_AGENT_ID ||
       (cfg && cfg.org && cfg.org.cohort && cfg.org.cohort.agentId) ||
       undefined;
+    // Belt and braces on top of the id above: hand the reader BOTH namespaces so
+    // own-echo suppression cannot silently lapse if `agentId` resolves to the
+    // slug after all (persistedMemberId returns "" when no memberId is on record,
+    // or when it equals the slug). resolveDirected uses these ONLY to widen the
+    // own-echo drop — never to widen what the agent is entitled to read.
+    const meAliases = [
+      cfg && cfg.memberId,
+      process.env.COHORT_AGENT_ID,
+      cfg && cfg.org && cfg.org.cohort && cfg.org.cohort.agentId,
+    ].filter((v) => typeof v === "string" && v.trim());
     // Display names for prose-mention matching ("Isla, can you…" with no @).
     // The wide reader only ever uses these to match text it was ALREADY entitled
     // to read, so this cannot widen the aperture.
@@ -835,6 +887,7 @@ async function guardMessagingInbound({ event, agentRoot, log }, opts = {}) {
     const res = await pull({
       cfg,
       agentId,
+      meAliases,
       cursor,
       fetchImpl: opts.fetchImpl,
       myNames,

package/scripts/daemon/classifier.mjs

@@ -196,7 +196,7 @@ const CLAUDE_CLI_TIMEOUT_MS = 30_000;
  * it was a hardcoded example-company literal sitting between two interpolated
  * fields. This
  * is not cosmetic: the classifier's `summary` is carried verbatim into
- * assurance.composeAck (text a human reads) and board-mirror's board row title,
+ * board-mirror's board row title and the needs-attention escalation record,
  * so a fabricated employer in its frame of reference leaks into the org record.
  *
  * @param {{name?:string, role?:string, company?:string, principal?:object}} id