@cohortapp/agent-sdk 2.18.7 → 2.18.10

package/scripts/daemon/agent-daemon.mjs

@@ -63,6 +63,9 @@ import { classifyItem, isDirectedAtAgent } from "./classifier.mjs";
 // gets a deterministic classification (no LLM triage), no holding ack, and a
 // per-seat jitter so thirteen answers do not land in the same second.
 import { isRollCallItem, rollCallJitterMs } from "../../lib/org/inbound/broadcast.mjs";
+import { isRoomSurface } from "../../lib/org/inbound/surfaces.mjs";
+import { isMembershipReason } from "../../lib/org/inbound/directedness.mjs";
+import { cohortSurfaceOf, cohortSurfaceLabel, cohortSurfaceIsDeclared } from "./deliver.mjs";
 import { itemCollectiveIntent } from "../../lib/org/inbound/collective.mjs";
 import { dispatch, getStatus, availableSlots, canDispatchBacklog, resetActiveSessions, yieldBacklogForReactive, linkActiveSessionBoard } from "./dispatcher.mjs";
 import { boardItemRefFor } from "../../lib/session/current-work.mjs";
@@ -132,6 +135,9 @@ import { boardPriority } from "./board-mirror.mjs";
 import { mintTraceId, withTrace } from "../../lib/diagnostics/trace.mjs";
 import { emitEvent, EVENT_TYPES } from "../../lib/diagnostics/events.mjs";
 import * as counters from "../../lib/diagnostics/counters.mjs";
+// Replies this seat owed and did not send, counted where a human can see them
+// (the presence beat) rather than only in a file on this disk.
+import { REPLY_DEBT_COUNTERS, isScopeFault } from "../../lib/daemon/reply-debt.mjs";
 import { getHookBus } from "../../lib/hooks/bus.mjs";
 // EXECUTION LADDER (lib/execution/**). The reactive front of the chain:
 // intake (what surface is this, and is it mine) → match (which compiled
@@ -499,18 +505,41 @@ function claudeAvailable() {
  * `electedMe:false`. A degraded election must never fall back to respond-to-all —
  * that is the storm this whole change exists to end.
  *
+ * ── WHAT A REASON MEANS, AND WHY `decided` IS ON THE VERDICT ────────────────
+ * Every path below that is not an election result ends in silence too, because
+ * the fail-safe is inverted — but silence-because-hq-picked-someone-else and
+ * silence-because-the-election-could-not-run are different events, and for
+ * months the caller printed both as "not elected to respond". An operator
+ * reading that log saw a decision where there had been an outage, or a missing
+ * id, or an item that was never a message. So the verdict now carries `decided`:
+ * TRUE only when hq actually ran the election and named responders. The caller
+ * logs the two cases in different words.
+ *
  * @param {object} item the (cohort) inbox item
  * @param {object} [deps] { electResponder, orgCfg } injectable seams for tests
- * @returns {Promise<{electedMe:boolean, reason:string, election?:string, mode?:string}>}
+ * @returns {Promise<{electedMe:boolean, decided:boolean, reason:string, election?:string, mode?:string}>}
  */
 async function electResponderVerdict(item, deps = {}) {
   const impl = deps.electResponder || electResponder;
   try {
     const cfg = deps.orgCfg !== undefined ? deps.orgCfg : daemonOrgCfg();
-    if (!orgEnabled(cfg)) return { electedMe: false, reason: "org-disabled" };
+    if (!orgEnabled(cfg)) {
+      return { electedMe: false, decided: false, reason: "org integration disabled — no roster to elect against" };
+    }
     const channelId = cohortChannelId(item);
     const messageId = cohortMessageId(item);
-    if (!channelId || !messageId) return { electedMe: false, reason: "no-message-id" };
+    // A ROOM ITEM MISSING ITS IDS IS A DEFECT, AND THE LOG MUST SAY SO. These
+    // two used to share the single reason "no-message-id", which was wrong on
+    // both counts: it named the message when the CHANNEL was the missing half,
+    // and it was the reason 23 doc comments printed in a day — items that have
+    // no channel id because they are not room traffic and never should have
+    // reached this call at all. That class is now excluded by the caller's
+    // surface gate, so anything landing here genuinely is a room item whose
+    // projection lost an id.
+    if (!channelId || !messageId) {
+      const missing = !channelId && !messageId ? "channel id and message id" : (!channelId ? "channel id" : "message id");
+      return { electedMe: false, decided: false, reason: `room item carries no ${missing} — the election cannot be asked` };
+    }
     const conn = configFromAgent(cfg);
     const res = await impl(
       { messageId, channelId },
@@ -518,9 +547,9 @@ async function electResponderVerdict(item, deps = {}) {
     );
     if (!res || res.error) {
       const reason = res && res.error
-        ? `${res.error.code || "error"}: ${res.error.message || ""}`
-        : "no-response";
-      return { electedMe: false, reason: reason.slice(0, 200) };
+        ? `hq refused the election (${res.error.code || "error"}: ${res.error.message || ""})`
+        : "hq returned no election frame";
+      return { electedMe: false, decided: false, reason: reason.slice(0, 200) };
     }
     const out = res.result !== undefined ? res.result : res;
     const responders = Array.isArray(out && out.responders) ? out.responders : [];
@@ -535,14 +564,40 @@ async function electResponderVerdict(item, deps = {}) {
     const electedMe =
       !!mySlug &&
       responders.some((r) => String((r && r.slug) || "").trim().toLowerCase() === mySlug);
+    // NO SLUG ON RECORD is not an election result: hq may well have elected
+    // somebody, this seat simply cannot tell whether it was itself. Reporting it
+    // as "hq elected another seat" would be an assertion nothing checked.
+    if (!mySlug) {
+      return {
+        electedMe: false,
+        decided: false,
+        reason: "this seat has no org member slug on record — cannot tell whether it was elected",
+        election: out && out.election,
+        mode: out && out.mode,
+      };
+    }
+    const others = responders
+      .map((r) => String((r && r.slug) || "").trim())
+      .filter(Boolean)
+      .slice(0, 5)
+      .join(", ");
     return {
       electedMe,
-      reason: electedMe ? "elected" : "not-elected",
+      decided: true,
+      reason: electedMe
+        ? "hq elected this seat"
+        : others
+          ? `hq elected ${others}`
+          : "hq elected nobody",
       election: out && out.election,
       mode: out && out.mode,
     };
   } catch (err) {
-    return { electedMe: false, reason: `error: ${err && err.message ? err.message : String(err)}`.slice(0, 200) };
+    return {
+      electedMe: false,
+      decided: false,
+      reason: `the election call threw (${err && err.message ? err.message : String(err)})`.slice(0, 200),
+    };
   }
 }
 
@@ -802,25 +857,136 @@ export async function answerItem(item, service, itemId, trace_id, deps = {}, rou
     // twelve seats silent on a message that named all thirteen. The inbound
     // join proved the address (human author, my room, collective marker), so
     // this is not ambient traffic and there is nothing to hold an election over.
+    //
+    // AND IT NEEDS A ROOM. `messaging.electResponder` takes
+    // `{messageId, channelId}`, loads that Message row and that channel's AI
+    // roster, and picks one of the seats IN THE ROOM. A document comment, a
+    // board comment, an approval or a decision names no channel and has no room
+    // roster — there is nobody to elect between. Asking the messaging election
+    // about one produced `no-message-id`, and because this gate's failure mode
+    // is inverted to fail-SILENT, "this is not a message" came out as "stay
+    // quiet": 23 doc comments dropped on this seat in a single day, each one
+    // logged as a decision not to answer a message.
+    //
+    // TWO SEPARATE QUESTIONS, AND THEY MUST NOT BE COLLAPSED INTO ONE. "Is this
+    // surface room traffic?" decides whether an election is the RIGHT mechanism;
+    // "was the address ambient?" decides whether one is NEEDED; "does the item
+    // name a channel?" decides whether one can be ASKED. A personal address on a
+    // non-room surface (I own the doc, I am the assignee, the approval is on my
+    // desk) skips the election because there is nothing to arbitrate. An AMBIENT
+    // address on a non-room surface still wants one — and gets one whenever the
+    // item names a room. `isRoomSurface` answers TRUE for an unknown name, so a
+    // new ambient channel surface keeps the storm gate by default.
     const rollCall = isRollCallItem(item);
-    if (service === "cohort" && !isDm && !rollCall && !isDirectedAtAgent(item)) {
+    const surface = service === "cohort" ? cohortSurfaceOf(item) : "";
+    // The name a PERSON reads. `cohortSurfaceOf` answers for ROUTING, and its
+    // fallback for a legacy `cohort:<channelId>:<messageId>` raw_ref (or a bare
+    // `kind:"message"`, which is what `lib/org/messaging.mjs` stamps) is "dm" —
+    // correct as a route, a lie as a label, and it printed
+    // `Election on dm in channel/roadmap` for an ambient PUBLIC-channel message
+    // in this very lane's test output. `cohortSurfaceLabel` never guesses.
+    const surfaceLabel = service === "cohort" ? cohortSurfaceLabel(item) : "";
+    const surfaceDeclared = service === "cohort" ? cohortSurfaceIsDeclared(item) : false;
+    // THE ADDRESS THE SERVER PROVED OUTRANKS THE LOCAL PROSE HEURISTIC. The
+    // comment above says an @mention or a named address "skips the election
+    // entirely (`isDirectedAtAgent` already decided)" — but `isDirectedAtAgent`
+    // is a SLACK-shaped rule: it matches the seat's configured first name and
+    // Slack member id against the message prose, and knows nothing about a
+    // Cohort mention row. A Cohort @mention whose prose spells the seat
+    // differently (a display name, a surname, a slug) therefore read as
+    // UNDIRECTED and went to an election — one surface's gate judging another
+    // surface's item, which is the same shape as the doc-comment bug above.
+    // `priority_signals.mentions_agent` is the ingest layer's real verdict,
+    // stamped by `lib/org/inbound/project.mjs` only for a genuine dm / mention /
+    // named / direct address, so it is the one to trust here.
+    const provenAddress = service === "cohort" && item.priority_signals && item.priority_signals.mentions_agent === true;
+    const undirectedCohort =
+      service === "cohort" && !isDm && !rollCall && !provenAddress && !isDirectedAtAgent(item);
+    // AMBIENT vs PERSONAL, and whether an election can be ASKED at all. Three
+    // facts, kept separate because they answer different questions:
+    //
+    //   `nonRoom`  — the surface's reply is not a message posted into a room.
+    //   `ambient`  — the address was proved by MEMBERSHIP or VISIBILITY
+    //                (`channel`, `participant`, `shared`), so every seat that
+    //                shares the room or the share holds an equal claim. That is
+    //                what an election is for.
+    //   `roomToArbitrate` — the item names a real Cohort channel, so
+    //                `messaging.electResponder` has a roster to elect from.
+    //
+    // ONLY THE COMBINATION `nonRoom && ambient && !roomToArbitrate` IS A DEAD
+    // END. An ambient non-room item that DOES name a room still goes to the
+    // election, exactly as it did before this change — a comment on a
+    // chat-attached file (`resolveChatFile` → `yes("file_comment","channel")`)
+    // carries its channel id, so hq can arbitrate the room's roster and one
+    // seat can answer. Excluding it unconditionally would have made that class
+    // permanently unanswerable by anybody, which is a behaviour change this
+    // lane never claimed and does not want: if hq cannot resolve the comment id
+    // as a Message the election errors, the inverted fail-safe fires, and the
+    // silence is the same one — so asking costs nothing and can only turn a
+    // never into an answer.
+    const nonRoom = undirectedCohort && !isRoomSurface(surface);
+    const ambient = undirectedCohort && isMembershipReason(item.direct_reason);
+    const roomToArbitrate = Boolean(cohortChannelId(item));
+    if (nonRoom && ambient && !roomToArbitrate) {
+      // AMBIENT, AND NO MECHANISM CAN REACH IT. A doc comment is addressed to
+      // this seat only because the file is SHARED with it — a visibility fact a
+      // whole channel can hold at once — but the reply is an RPC against a file
+      // id, there is no Message row and no channel id, and
+      // `messaging.electResponder` has nothing to be asked about. So the seat
+      // stays silent, and the log says THAT: a missing mechanism, not a
+      // decision. Arbitration for ambient non-room surfaces is a real gap; it
+      // needs a server-side election keyed on the entity, not a local guess.
+      console.log(`[daemon] No arbitration exists for an ambient ${surfaceLabel} item (addressed by ${item.direct_reason || "membership"}, it names no room, and the responder election is messaging-only) — staying silent (gap, not a decision; from ${item.sender})`);
+      logEvent("classifications", {
+        item_id: itemId,
+        sender: item.sender,
+        service,
+        surface,
+        surface_declared: surfaceDeclared,
+        skipped: true,
+        reason: `no_arbitration_for_ambient_surface: ${surface}`,
+        direct_reason: item.direct_reason || null,
+        summary: classResult.summary,
+      });
+      markProcessed(item, service);
+      return { ok: true, path: "filtered", reason: "no_arbitration_for_ambient_surface" };
+    } else if (nonRoom && !ambient) {
+      console.log(`[daemon] No election on a ${surfaceLabel} item — it is not room traffic and the inbound join already proved it is addressed here (${item.direct_reason || "addressed"}); handling it on its own surface (from ${item.sender})`);
+    } else if (undirectedCohort) {
       const verdict = await _electResponderVerdict(item);
       if (!verdict.electedMe) {
-        console.log(`[daemon] Election: not elected to respond (${verdict.reason}) — staying silent for ${item.sender} in ${item.channel}`);
+        // TWO DIFFERENT EVENTS, TWO DIFFERENT SENTENCES. `decided` is true only
+        // when hq ran the election and named responders; everything else is the
+        // fail-safe firing on an outage or a malformed item, and calling that a
+        // decision is how an outage reads as normal operation in the log.
+        console.log(
+          verdict.decided
+            ? `[daemon] Election on ${surfaceLabel} in ${item.channel}: ${verdict.reason} — this seat stays silent (from ${item.sender})`
+            : `[daemon] Election on ${surfaceLabel} in ${item.channel} could not be decided: ${verdict.reason} — staying silent (fail-safe, not a decision; from ${item.sender})`,
+        );
         logEvent("classifications", {
           item_id: itemId,
           sender: item.sender,
           service,
+          surface,
+          surface_declared: surfaceDeclared,
           skipped: true,
-          reason: `not_elected: ${verdict.reason}`,
+          reason: verdict.decided
+            ? `election_elected_another: ${verdict.reason}`
+            : `election_undecided: ${verdict.reason}`,
+          election_decided: verdict.decided === true,
           election: verdict.election || null,
           mode: verdict.mode || null,
           summary: classResult.summary,
         });
         markProcessed(item, service);
-        return { ok: true, path: "filtered", reason: "not_elected" };
+        return {
+          ok: true,
+          path: "filtered",
+          reason: verdict.decided ? "election_elected_another" : "election_undecided",
+        };
       }
-      console.log(`[daemon] Election: elected to respond (${verdict.election || "elected"}, mode=${verdict.mode || "?"}) for ${item.sender} in ${item.channel}`);
+      console.log(`[daemon] Election on ${surfaceLabel} in ${item.channel}: ${verdict.reason} (${verdict.election || "elected"}, mode=${verdict.mode || "?"}) — answering ${item.sender}`);
     }
 
     // DIRECTED-MESSAGE GATE: In channels and group chats, only respond to
@@ -1046,6 +1212,32 @@ export async function answerItem(item, service, itemId, trace_id, deps = {}, rou
       // the forbidden one); the escalation is the trace that a human must act.
       if (result.permanent) {
         const cause = result.code || result.error || "permanent send failure";
+        // A SCOPE REFUSAL IS A CONFIGURATION FAULT AND SOMEBODY ELSE'S TO FIX.
+        // Everything below this line is correct and stays — the ask is not
+        // lost, the obligation is durable, an operator can sweep
+        // state/obligations/needs-attention. But all of it is on THIS DISK. The
+        // measured case (2026-09-22, doc comment on a file this seat may not
+        // comment on) produced three log lines and one JSON file, and nothing
+        // off the box ever said the seat was missing a scope. A person would
+        // have to already suspect this seat to go and look, which is the same
+        // silence in a nicer folder.
+        //
+        // So a scope fault is also COUNTED, and the count rides the presence
+        // beat (lib/telemetry/collect → machine.replyDebt → the
+        // `seat_missing_scope` alert). Counting rather than sending: the only
+        // channel we had was the forbidden one, and the seat cannot know which
+        // other room would reach the right human. What it CAN do is stop being
+        // the only thing that knows.
+        //
+        // Falling through to a session is still refused, for the reason below:
+        // a denied session runs autonomously and improvises unrelated work into
+        // a channel this seat was just told it may not write to.
+        if (isScopeFault(result.code)) {
+          counters.bump(REPLY_DEBT_COUNTERS.scopeRefused, {
+            service, sender: item.sender || "unknown",
+            channel: item.channel_id || item.channel || "none",
+          });
+        }
         console.error(`[daemon] Quick reply PERMANENTLY failed for ${item.sender} (${cause}) — NOT spawning a session; opening obligation + escalating`);
         let obligationKey = itemId;
         try {
@@ -1061,6 +1253,7 @@ export async function answerItem(item, service, itemId, trace_id, deps = {}, rou
             channel: item.channel_id || item.channel || null,
             summary: classResult && classResult.summary, openedAt: Date.now(),
             attempts: 1, sessionId: null, traceId: trace_id, lastError: cause,
+            configFault: isScopeFault(result.code) ? "missing-scope" : null,
             item: { content: item.content } },
           { failure: { label: cause }, told: false },
         );

package/scripts/daemon/assurance.mjs

@@ -1556,6 +1556,11 @@ export function escalate(rec, o = {}) {
       failedAt: new Date(Number.isFinite(o.now) ? o.now : Date.now()).toISOString(),
       cause: o.failure ? o.failure.label : (rec.lastError || "unknown"),
       requesterWasTold: !!o.told,
+      // WHO has to act. A transport failure is this seat's own problem and the
+      // sweep retries it; a scope fault is a configuration the seat cannot
+      // grant itself, so the row says so in a word an operator can grep rather
+      // than leaving them to infer it from `cause`.
+      configFault: rec.configFault || null,
       attempts: rec.attempts || 0,
       sessionId: rec.sessionId || null,
       traceId: rec.traceId || null,

package/scripts/daemon/deliver.mjs

@@ -34,7 +34,7 @@ import { recordOutbound } from "../../lib/comms/receipts.mjs";
 // Pure data (a frozen table, no imports of its own) — the surface vocabulary the
 // inbound projection stamps into `raw_ref`. Imported rather than re-listed so a
 // new surface cannot be added upstream without this file's switch noticing.
-import { SURFACE_NAMES } from "../../lib/org/inbound/surfaces.mjs";
+import { ROOM_SURFACES, SURFACE_NAMES } from "../../lib/org/inbound/surfaces.mjs";
 
 const AGENT_REPO_DIR = process.env.AGENT_DIR || join(new URL(".", import.meta.url).pathname, "../..");
 
@@ -117,11 +117,17 @@ export function resolveSlackChannel(item) {
  * correct case for it.
  */
 
-/** Surfaces that genuinely live in a Cohort room — these reply with a message. */
-// `broadcast` is a room message like a mention: the roll-call answer posts
-// into the space it was asked in. Without this entry the reply has no
-// transport, `canDeliverTo` says no, and the surface is dark at the last step.
-const CHANNEL_SURFACES = Object.freeze(["dm", "mention", "broadcast", "thread_reply", "call"]);
+/**
+ * Surfaces that genuinely live in a Cohort room — these reply with a message.
+ *
+ * DERIVED, not re-typed. This was a hand-kept copy of five names, and a
+ * hand-kept copy is a list that can be forgotten: `broadcast` had to be added
+ * here by hand when the roll-call surface landed, and until it was, the reply
+ * had no transport, `canDeliverTo` said no, and the surface was dark at the last
+ * step. `surfaces.mjs` now carries `room` as a per-surface fact and this reads
+ * it, so a new room surface is routable the moment it is declared.
+ */
+const CHANNEL_SURFACES = ROOM_SURFACES;
 
 /**
  * Error frame codes a retry cannot change.
@@ -174,17 +180,77 @@ function entityFromRawRef(item) {
  */
 export function cohortSurfaceOf(item) {
   if (!item) return "";
-  // Guarded against the LEGACY raw_ref shape, which is `cohort:<channelId>:
-  // <messageId>` — still on disk today. An all-lowercase channel id would
-  // otherwise parse as a surface name and route a working DM to nowhere.
-  const m = /^cohort:([a-z_]+):/.exec(str(item.raw_ref));
-  if (m && SURFACE_NAMES.includes(m[1])) return m[1];
+  const declared = declaredSurface(item);
+  if (declared) return declared;
   const kind = str(item.kind);
   if (kind === "file_comment") return str(item.channel_id) ? "file_comment" : "doc_comment";
   if (!kind || kind === "message") return "dm";
   return kind;
 }
 
+/**
+ * The surface name `project.mjs` DECLARED in `raw_ref`, or "" when it declared
+ * none.
+ *
+ * Guarded against the LEGACY raw_ref shape, which is `cohort:<channelId>:
+ * <messageId>` — still on disk today, and still what `lib/org/messaging.mjs`
+ * stamps. An all-lowercase channel id would otherwise parse as a surface name
+ * and route a working DM to nowhere.
+ */
+function declaredSurface(item) {
+  const m = /^cohort:([a-z_]+):/.exec(str(item && item.raw_ref));
+  return m && SURFACE_NAMES.includes(m[1]) ? m[1] : "";
+}
+
+/**
+ * Did `raw_ref` actually DECLARE this item's surface, or was it inferred?
+ *
+ * Worth recording next to a logged surface: an inferred one is a guess made
+ * from `kind` / `channel_kind`, and an operator reading the row later should be
+ * able to tell the two apart without re-deriving it.
+ *
+ * @param {object} item
+ * @returns {boolean}
+ */
+export function cohortSurfaceIsDeclared(item) {
+  return declaredSurface(item) !== "";
+}
+
+/**
+ * How to NAME this item's surface in a line a person reads.
+ *
+ * ── WHY THIS IS NOT `cohortSurfaceOf` ──
+ * Because that function's job is ROUTING, and for routing its fallbacks are
+ * right: an item with the legacy `cohort:<channelId>:<messageId>` raw_ref, or
+ * bare `kind:"message"`, replies with a message posted into `channel_id`, which
+ * is precisely what the `dm` branch does. But "dm" is then a ROUTE, not a
+ * claim about where the message was written — and a log line that prints it
+ * tells an operator "dm" about a message in a PUBLIC channel. The lane that
+ * added these lines to make the log truthful hit exactly that in its own test
+ * output: `Election on dm in channel/roadmap`.
+ *
+ * So the label is derived separately and never guesses: a declared surface is
+ * used verbatim; otherwise `channel_kind` (which hq stamps on the narrow reader)
+ * names the room; otherwise the item's own `is_dm`; otherwise it says plainly
+ * that the surface was never declared, rather than inventing one.
+ *
+ * @param {object} item
+ * @returns {string}
+ */
+export function cohortSurfaceLabel(item) {
+  if (!item) return "unknown surface";
+  const declared = declaredSurface(item);
+  if (declared) return declared;
+  const kind = str(item.kind);
+  if (kind === "file_comment") return str(item.channel_id) ? "file_comment" : "doc_comment";
+  if (kind && kind !== "message") return kind;
+  const channelKind = str(item.channel_kind).toUpperCase();
+  if (channelKind === "DM") return "dm";
+  if (channelKind) return `${channelKind.toLowerCase()} channel message`;
+  if (item.is_dm === true) return "dm";
+  return "message (surface not declared in raw_ref)";
+}
+
 /**
  * Where a reply to this Cohort item goes — a pure function of the item, so it
  * can be asked BEFORE anything is promised (see `canDeliverTo`).
@@ -766,5 +832,7 @@ export default {
   canDeliverTo,
   cohortReplyRoute,
   cohortSurfaceOf,
+  cohortSurfaceLabel,
+  cohortSurfaceIsDeclared,
   DELIVERABLE_SERVICES,
 };

package/scripts/daemon/dispatcher.mjs

@@ -527,11 +527,19 @@ const ACTIVE_PATH = join(AGENT_REPO_DIR, "state", "sessions", "active.json");
 // A marker is written to state/sessions/resume-pending/<sessionId>.json right
 // after spawn and DELETED on a clean close. Its presence after a crash/reboot
 // means "this session was mid-flight" — resetActiveSessions() reconciles them
-// (re-dispatching `claude --print --session-id <claudeSessionId> <prompt>`,
-// the SAME continuation mechanism responder.mjs uses — NOT `--resume`) within a
-// freshness window, instead of blindly wiping the slate. 3 strikes → the queue
-// item is marked status:blocked. This is the "never brick / never drop work"
-// recovery path for the dispatcher.
+// (re-dispatching `claude --print --resume <claudeSessionId> <prompt>`, the
+// same continuation mechanism responder.mjs uses) within a freshness window,
+// instead of blindly wiping the slate. 3 strikes → the queue item is marked
+// status:blocked. This is the "never brick / never drop work" recovery path
+// for the dispatcher.
+//
+// ~~"re-dispatching `claude --print --session-id <claudeSessionId> <prompt>`
+// … NOT `--resume`"~~ — struck 2026-09-25 with the flag itself. A marker's
+// claudeSessionId by construction HAS a transcript, and `--session-id` is
+// REFUSED for such an id (`Error: Session ID <uuid> is already in use.`,
+// exit 1, no model call), so every reconcile exited 1 rather than recovering
+// anything. `--resume` is the continuation. See lib/runtime/adapter.mjs
+// #sessionArgs for the measurement.
 const RESUME_PENDING_DIR = join(AGENT_REPO_DIR, "state", "sessions", "resume-pending");
 // Sessions whose marker is older than this are too stale to resume meaningfully
 // (the work context has moved on); reconcile blocks them rather than re-running.
@@ -634,10 +642,14 @@ function markItemBlocked(marker, reason) {
  * WS4 — instead of *also* blindly discarding any work that was mid-flight when
  * the box rebooted/lost power, when `opts.reconcile` is set we walk
  * state/sessions/resume-pending/ and, for each marker still inside the
- * freshness window, re-spawn `claude --print --session-id <claudeSessionId>
- * <prompt>` (the responder's continuation pattern — NOT `--resume`) so the work
- * continues where it left off. After RESUME_MAX_ATTEMPTS (3) the item is marked
- * status:blocked with a reason rather than retried forever.
+ * freshness window, re-spawn `claude --print --resume <claudeSessionId>
+ * <prompt>` (the responder's continuation pattern) so the work continues where
+ * it left off. After RESUME_MAX_ATTEMPTS (3) the item is marked status:blocked
+ * with a reason rather than retried forever.
+ *
+ * ~~"`--session-id <claudeSessionId> <prompt>` … NOT `--resume`"~~ — struck
+ * 2026-09-25: the CLI refuses `--session-id` for an id that already has a
+ * transcript, which every marker's id does.
  *
  * Graceful shutdown passes no opts (just clears active.json); only startup
  * reconciles, so we never re-spawn work we're deliberately stopping.
@@ -736,8 +748,11 @@ export function reconcileResumePending(opts = {}) {
     }
 
     // No original prompt persisted → there's nothing to re-spawn with (the
-    // resume re-issues `--session-id <id> <prompt>`, NOT `--resume`). A marker
-    // without a prompt is either a legacy marker (pre-H1) or one whose write
+    // resume re-issues `--resume <id> <prompt>`: the flag continues the
+    // transcript, the prompt is what the continuation is FOR, and a bare
+    // `--resume` with no prompt is the do-nothing exit 0 that H1 guards
+    // against). A marker without a prompt is either a legacy marker (pre-H1)
+    // or one whose write
     // dropped the field; we can't truly resume it, so retire it rather than
     // spawn a no-op that the close handler would mistake for "done". (H1)
     if (typeof marker.prompt !== "string" || !marker.prompt) {
@@ -894,6 +909,11 @@ export function buildResumeSpawn(o = {}) {
     model: flag,
     prompt: marker.prompt,
     sessionId: marker.claudeSessionId,
+    // Crash recovery by definition continues a transcript the dead session
+    // already wrote, so this is `--resume`. It was `--session-id`, which the
+    // CLI refuses for an id it has seen — so recovery has been exiting 1 in a
+    // tenth of a second rather than recovering anything.
+    resumeSession: true,
     permissions: Array.isArray(o.permissionArgs) ? o.permissionArgs : [],
     mcp: {},
     knobs: t,
@@ -922,19 +942,30 @@ export function buildResumeSpawn(o = {}) {
 }
 
 /**
- * Real resume spawner. Mirrors responder.mjs's blessed session-continuation
- * pattern (see runClaudeCLI ~L116-122 + generateResponse ~L461-465): a
- * continuation re-spawns `claude --print --session-id <sessionId> <prompt>`
- * with the SAME model/flags the original used — it does NOT use `--resume`.
+ * Real resume spawner. Mirrors responder.mjs's session-continuation pattern: a
+ * continuation re-spawns `claude --print --resume <sessionId> <prompt>` with
+ * the SAME model/flags the original used. The flag rehydrates the transcript;
+ * the prompt is what the rehydrated session is asked to carry on with, which
+ * is why a resume here is never the bare `--resume` with no prompt.
+ *
+ * ~~"a continuation re-spawns `claude --print --session-id <sessionId>
+ * <prompt>` … it does NOT use `--resume`", and the "Why NOT `--resume` (the
+ * previous bug)" paragraph under it~~ — STRUCK 2026-09-25, in the same change
+ * that made `resumeSession: true` the flag this function emits. Both halves
+ * were false and the file still said them:
  *
- * Why NOT `--resume` (the previous bug): `--resume <id>` with no prompt and
- * stdin ignored either (a) exits 0 having done nothing — the close handler
- * then clears the marker and the interrupted work is silently lost — or (b)
- * errors, force-`blocked`ing every in-flight item after a reboot. Pre-minting
- * a stable session id and RE-SPAWNING against it with the original prompt is
- * the actual resume mechanism in `--print` mode (per the b1 flag-verification
- * report cited in responder.mjs). The CLI rehydrates the session-id's history
- * and the fresh prompt continues the work.
+ *   · `--session-id <id>` STARTS a session under a chosen id. The CLI refuses
+ *     it for an id that already has a transcript — `Error: Session ID <uuid>
+ *     is already in use.`, exit 1, ~0.1s, no model call — and a resume marker's
+ *     id always has one. So crash recovery had never recovered anything.
+ *   · The bare-`--resume` failure the struck paragraph described (exit 0 having
+ *     done nothing) is a resume with NO PROMPT. This lane always passes the
+ *     marker's prompt, so it was never the shape being warned about.
+ *
+ * Left standing, that paragraph is how the next author reinstates the flag:
+ * it reads as a rationale rather than as the belief that cost four replies on
+ * this seat, 09-22..24. lib/runtime/adapter.mjs#sessionArgs carries the
+ * reproduction.
  *
  * Audit F11: the argv and env are built through the SAME resolveSpawnTarget /
  * runtime-adapter path as spawnSession (buildResumeSpawn), so a retargeted
@@ -1652,9 +1683,13 @@ function spawnSession(entry) {
   // session in a live thread started COLD — the agent re-read the room, re-did
   // the orientation work, and answered a follow-up as if it were an opening
   // (design §3 R10). The router the responder already consults keys the
-  // conversation; a follow-up inside the TTL resumes the same session id, which
-  // in this daemon IS continuation (`--session-id <id> <prompt>`, never
-  // `--resume` — see the resume-pending notes above).
+  // conversation; a follow-up inside the TTL resumes the same session id.
+  //
+  // ~~"which in this daemon IS continuation (`--session-id <id> <prompt>`,
+  // never `--resume`)"~~ — struck: it is not, and never was. `--session-id`
+  // STARTS a session under a chosen id and the CLI refuses it for an id that
+  // already has a transcript. Continuation is `--resume`, which is what
+  // `resumeSession` below now selects.
   //
   // Inbox only. Backlog work is not a conversation, and keying it would put
   // unrelated items in one session.
@@ -1725,6 +1760,13 @@ function spawnSession(entry) {
     model: engineShape ? engineShape.model : effectiveModelFlag,
     prompt,
     sessionId: claudeSessionId,
+    // `--resume <id>` when this id names a transcript that already exists (the
+    // router's RESUME decision), `--session-id <id>` when we just minted it.
+    // Passing a used id to `--session-id` is refused outright by the CLI
+    // ("Session ID … is already in use", exit 1 before any model call), which
+    // is what made every routed continuation die — see sessionArgs() in
+    // lib/runtime/adapter.mjs.
+    resumeSession: resumedSessionId != null,
     permissions: sessionPermissionArgs({ source: "dispatcher", priority: classResult?.priority }),
     mcp: {},
     knobs: engineShape ? engineShape.knobs : target,

package/scripts/daemon/lib/session-router.mjs

@@ -85,6 +85,27 @@ export function _resetInFlightForTests() {
   inFlightKeys.clear();
 }
 
+/**
+ * Does this CLI failure mean "the id you asked to START is already taken"?
+ *
+ * The CLI's exact text is `Error: Session ID <uuid> is already in use.` on
+ * stderr with exit 1, emitted in ~0.1s before any model call. It is a PURE
+ * addressing fault: the same prompt with a fresh id succeeds. So it is the one
+ * spawn failure a reply path may retry blind, and the caller that catches it
+ * owes exactly one retry with a new id rather than a dropped reply.
+ *
+ * Matched loosely on purpose — the caller sees this wrapped as
+ * `claude CLI exited 1: Error: Session ID … is already in use.` — but anchored
+ * on both halves so an unrelated "in use" message cannot trigger a retry.
+ *
+ * @param {unknown} err an Error, or the message/stderr text
+ * @returns {boolean}
+ */
+export function isSessionIdCollision(err) {
+  const text = err instanceof Error ? err.message : typeof err === "string" ? err : "";
+  return /session id\b/i.test(text) && /\bis already in use/i.test(text);
+}
+
 /**
  * Services whose routing key is `<source>:<channel>[:<thread>]`.
  *