@cohortapp/agent-sdk 2.18.13 → 2.18.15

package/scripts/daemon/cadence-consumer.mjs

@@ -96,6 +96,13 @@ import { writeHandoff, listHandoffs, expireHandoffs, pruneHandoffs, handoffPaths
 import { writeFileAtomic } from "../../lib/fs-atomic.mjs";
 import { resolveClaudeBin as sharedResolveClaude } from "../../lib/claude-bin.mjs";
 import { getCadenceDef } from "./cadence-handlers.mjs";
+// PERMANENT vs TRANSIENT (lane/permanent-errors). A retry loop that never
+// inspects its error class is how two seats burned down: a cadence whose prompt
+// file does not exist retried at poll speed forever (measured 16 requeues per
+// 30 s on Eli Rosenberg's seat, 2026-09-24). The taxonomy is pure and lives on
+// its own so the policy can be argued with without a daemon.
+import { classifyCadenceFailure, isPermanent, PERMANENT_MAX_ATTEMPTS } from "../../lib/cadence-failure-class.mjs";
+import { bump as bumpCounter } from "../../lib/diagnostics/counters.mjs";
 import { obligationAllowedUnderPosture } from "../../lib/plan/compile.mjs";
 import { isHumanLaneCadence } from "../../lib/cadences.mjs";
 import { sessionPermissionArgs } from "../../lib/session-permissions.mjs";
@@ -636,6 +643,12 @@ export function startConsumer(opts = {}) {
   const budgetEscalateMs = opts.budgetEscalateMs ?? DEFAULT_BUDGET_ESCALATE_MS;
   const maxSpawnMs = opts.maxSpawnMs ?? DEFAULT_SPAWN_TIMEOUT_MS;
   const spawnSession = opts.spawnSession || realSpawnSession;
+  // Cadence registry lookup. Injectable because the config-driven half
+  // (`config/.cadence-registry.json`) is read once and memoised at module
+  // scope, which a hermetic test cannot re-point — and the permanent-error
+  // path is reached precisely through a CONFIGURED cadence whose prompt is
+  // absent, so it has to be reachable in a test.
+  const cadenceDef = typeof opts.getCadenceDef === "function" ? opts.getCadenceDef : getCadenceDef;
   const userLogger = opts.logger;
   // Test / tuning hooks for the reliability layer.
   const backoffSchedule = opts.backoffSchedule || BACKOFF_SCHEDULE_MS;
@@ -725,13 +738,64 @@ export function startConsumer(opts = {}) {
    * `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.
+   *
+   * WHY IT TAGS ITS OWN FAILURES. This function does two unrelated things: it
+   * READS the cadence's prompt (whose failure says the spawn cannot work
+   * either — the spawn opens the same path) and it WRITES a rendered copy into
+   * the handoff dir (whose failure says nothing about the spawn at all). The
+   * caller has to tell them apart, and the first attempt at that inferred it
+   * from the message — `msg.includes(promptPath)`.
+   *
+   * That inference is WRONG, measured 2026-09-25: `readFileSync` on a
+   * DIRECTORY throws exactly `EISDIR: illegal operation on a directory, read`,
+   * with no path in the text. A directory at the configured prompt path
+   * therefore passed the `existsSync` pre-check, threw here, was read as "not
+   * about the prompt", classified transient, and fell through to a spawn — the
+   * commonest unreadable case, and precisely the one the PROMPT_UNREADABLE code
+   * exists for. Node puts the path in the message for ENOENT and EACCES and
+   * not for EISDIR; no caller should have to know which.
+   *
+   * So the phase is not inferred, it is STAMPED, at the only two places that
+   * know it: `err.cadencePhase` is `"prompt"` on the read and `"handoff"` on
+   * everything after it. `err.cadenceErrno` carries `err.code` alongside, since
+   * the errno is the contract and the message is not.
    */
   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;
+    let source;
+    try {
+      source = readFileSync(fullPrompt, "utf-8");
+    } catch (err) {
+      throw stampPhase(err, "prompt");
+    }
+    // Everything past the read is about OUR output, not the cadence's input:
+    // a render bug or an unwritable handoff dir leaves the spawn perfectly able
+    // to run, so neither may be read as a permanent prompt fault.
+    try {
+      const body = renderCadencePromptBody(agentRoot, source);
+      const out = join(handoffPaths(agentRoot).prompts, `${tickId}.md`);
+      writeFileAtomic(out, body);
+      return out;
+    } catch (err) {
+      throw stampPhase(err, "handoff");
+    }
+  }
+
+  /**
+   * Stamp an error with the phase it came from, so a catch does not have to
+   * guess. Non-destructive: an already-stamped error keeps its innermost phase
+   * (the read is nested inside nothing, but this keeps re-throws honest), and a
+   * non-object throw is wrapped rather than dropped.
+   */
+  function stampPhase(err, phase) {
+    if (!err || typeof err !== "object") {
+      const wrapped = new Error(String(err ?? "unknown error"));
+      wrapped.cadencePhase = phase;
+      return wrapped;
+    }
+    if (!err.cadencePhase) err.cadencePhase = phase;
+    if (!err.cadenceErrno && typeof err.code === "string") err.cadenceErrno = err.code;
+    return err;
   }
 
   /**
@@ -759,7 +823,7 @@ export function startConsumer(opts = {}) {
       // predicate both places — the daemon and the plan cannot disagree about
       // what is suspended.
       if (posture && cadence) {
-        const def = getCadenceDef(cadence) || {};
+        const def = cadenceDef(cadence) || {};
         const verdict = obligationAllowedUnderPosture(
           {
             kind: "SCHEDULE",
@@ -824,6 +888,13 @@ export function startConsumer(opts = {}) {
     handed_off: 0,
     handoff_timeouts: 0,
     deferred: 0,
+    // A failure the classifier called PERMANENT — the cause cannot change by
+    // waiting, so the tick was dead-lettered instead of retried. Rides the
+    // heartbeat (writeHealth) so `maestro cadence status` and the beat carry it
+    // without a new channel; `last_permanent_failure` names the cadence and the
+    // code so the reader does not have to go back to the log to find out which.
+    permanent_failures: 0,
+    last_permanent_failure: null,
     last_event_id: null,
     last_decision: null,
   };
@@ -887,6 +958,99 @@ export function startConsumer(opts = {}) {
     return { ok: false, decision: "deferred", reason };
   }
 
+  /**
+   * A failure the classifier calls PERMANENT: stop retrying, record it
+   * durably, and make it visible to a person.
+   *
+   * THE FAULT THIS CLOSES (Eli Rosenberg's seat, 2026-09-24). A cadence whose
+   * configured prompt file was not on disk requeued forever — measured at 16
+   * per 30 seconds — because nothing in the retry path ever asked whether the
+   * cause could change by waiting. It cannot: a file that does not exist will
+   * not exist 30 seconds later.
+   *
+   * Three things happen, and all three matter:
+   *
+   *  1. STOP. `failTick` with `min(this consumer's budget,
+   *     PERMANENT_MAX_ATTEMPTS)` — the permanent cap lowers a budget, never
+   *     raises one. Two attempts, then dlq/: not because the cause can never be
+   *     repaired (someone can drop the prompt onto the seat), but because it
+   *     cannot be repaired BY WAITING.
+   *
+   *     STATED HONESTLY (corrected 2026-09-25). `failTick`'s first outcome for
+   *     attempt 1 is a REQUEUE, so what this buys is "one extra attempt, then
+   *     stop" — not "the cadence's own schedule is the retry window", which is
+   *     what an earlier draft of this comment claimed. The schedule only
+   *     becomes the window once the last attempt reaches dlq/. Spacing the one
+   *     extra attempt is a separate act, and it is done here:
+   *     `holdCadenceForBackoff` moves the per-cadence gate forward so the retry
+   *     cannot land in the same drain that produced the first failure. The
+   *     measured before/after is 16 requeues per 30 s, unbounded → 2 attempts
+   *     one backoff interval apart, then a durable stop.
+   *
+   *     The budget is the smaller half of this; the bigger half is (2) and (3),
+   *     and that a permanent fault no longer falls through to a second code
+   *     path that opens the same missing file.
+   *  2. RECORD. The dlq/ file is the durable record and now carries
+   *     `permanent:<code>` in `last_error`, so the reason survives a restart
+   *     and a log rotation. A durable counter (`cadence.permanent_failure`)
+   *     goes to logs/diagnostics/counters/<day>.jsonl alongside it.
+   *  3. BE VISIBLE. The counter is what the seat's EXISTING alert lane reads
+   *     (lib/diagnostics/alerts.mjs `cadence_permanently_failing`, delivered by
+   *     the alerts cadence through config/alerts.yaml's webhook, or logged
+   *     when there is none) — no new channel. And `stats.permanent_failures`
+   *     rides the heartbeat, so the seat's health file and everything
+   *     downstream of it say so without anyone tailing a log.
+   *
+   * Never throws: the counter bump is best-effort by contract and failTick is
+   * already guarded.
+   *
+   * @param {object} event     the claimed tick
+   * @param {object} verdict   a CadenceFailureVerdict (class "permanent")
+   * @param {string} detail    the raw error text, for the dlq record + log
+   * @param {string} stage     log stage naming WHERE it was caught
+   */
+  function failPermanently(event, verdict, detail, stage) {
+    // The permanent cap LOWERS a budget, never raises one: if this consumer is
+    // already stricter than the cap, its own number wins.
+    const budget = Math.min(maxAttempts, verdict.maxAttempts ?? PERMANENT_MAX_ATTEMPTS);
+    const reason = `permanent:${verdict.code} — ${verdict.reason}${detail ? `: ${detail}` : ""}`;
+    log({
+      level: "error",
+      stage,
+      permanent: true,
+      code: verdict.code,
+      id: event.id,
+      cadence: event.cadence,
+      error: detail || verdict.reason,
+      max_attempts: budget,
+      note: "cause cannot change by waiting — one more attempt after the cadence backoff, then dead-lettered",
+    });
+    try {
+      bumpCounter("cadence.permanent_failure", { cadence: event.cadence, code: verdict.code }, { agentRoot });
+    } catch { /* a counter must never crash the path it observes */ }
+    stats.permanent_failures += 1;
+    stats.last_permanent_failure = {
+      cadence: event.cadence,
+      code: verdict.code,
+      at: new Date().toISOString(),
+    };
+    stats.last_decision = "permanent-failure";
+    // Space the one remaining attempt. Without this the requeue below is
+    // re-claimed by the very next drain pass — "bounded" but still at poll
+    // speed, which is the behaviour this lane exists to remove.
+    const heldUntil = holdCadenceForBackoff(event.cadence);
+    const outcome = failTick(agentRoot, event.id, reason, { maxAttempts: budget });
+    if (outcome?.destination === "dlq") stats.dlq += 1;
+    else {
+      stats.retries += 1;
+      log({ level: "warn", stage: "permanent_retry_held", id: event.id, cadence: event.cadence, code: verdict.code, retry_at: new Date(heldUntil).toISOString() });
+    }
+    // The heartbeat is the visible surface; write it now rather than waiting up
+    // to `heartbeatMs` for a reader to learn a cadence just died.
+    heartbeat();
+    return { ok: false, decision: outcome?.destination === "dlq" ? "dlq-permanent" : "failed-permanent", code: verdict.code };
+  }
+
   // Ledger hygiene runs from the sweep at most this often.
   const HANDOFF_PRUNE_EVERY_MS = 60 * 60_000;
   let lastHandoffPruneAt = 0;
@@ -989,20 +1153,47 @@ export function startConsumer(opts = {}) {
     s.failures += 1;
     // Exponential back-off honouring the (test-overridable) schedule.
     const idx = Math.min(s.failures, backoffSchedule.length - 1);
-    s.nextAllowedAt = Date.now() + backoffSchedule[idx];
+    s.nextAllowedAt = nowMs() + backoffSchedule[idx];
     if (s.failures >= circuitThreshold) {
-      s.openUntil = Date.now() + circuitDurationMs;
+      s.openUntil = nowMs() + circuitDurationMs;
       log({ level: "error", stage: "circuit_opened", cadence, failures: s.failures, open_until: new Date(s.openUntil).toISOString() });
       writeCircuitFile();
     }
   }
 
+  /**
+   * Hold a cadence off the spawn path for one backoff interval WITHOUT
+   * advancing it toward an open circuit.
+   *
+   * WHY IT IS SEPARATE FROM `recordSubsessionFailure`. A permanent failure is
+   * not a flaky sub-session: counting it toward `circuitThreshold` would trip a
+   * breaker whose whole job is to ride out a bad patch, for a cause that has no
+   * patch to ride out. What it DOES need is spacing — `PERMANENT_MAX_ATTEMPTS`
+   * is a count, not a delay, and `failPermanently`'s first outcome is a requeue,
+   * so without this the "one extra attempt" lands in the very same drain that
+   * produced the first. `escalate` consults `isCadenceAllowed` before it reaches
+   * the prompt at all, so moving `nextAllowedAt` forward is all it takes for the
+   * extra attempt to cost a real interval rather than a millisecond.
+   *
+   * Idempotent-ish and monotonic: never moves the hold EARLIER, so a circuit or
+   * a longer transient backoff already in force keeps its own deadline.
+   */
+  function holdCadenceForBackoff(cadence) {
+    const s = getCadenceState(cadence);
+    // The first rung is deliberately 0 ("retry immediately once"); a permanent
+    // fault has already proved it needs a gap, so take the first NON-zero rung.
+    const step = backoffSchedule.find((ms) => ms > 0) ?? 0;
+    const until = nowMs() + step;
+    if (until > s.nextAllowedAt) s.nextAllowedAt = until;
+    return s.nextAllowedAt;
+  }
+
   function writeCircuitFile() {
     // Persist the open-circuit snapshot so doctor + the operator can see
     // which cadences are currently held back without scraping logs.
     const open = {};
     for (const [cad, s] of cadenceState.entries()) {
-      if (s.openUntil > Date.now()) {
+      if (s.openUntil > nowMs()) {
         open[cad] = { failures: s.failures, open_until: new Date(s.openUntil).toISOString() };
       }
     }
@@ -1020,7 +1211,7 @@ export function startConsumer(opts = {}) {
 
   function isCadenceAllowed(cadence) {
     const s = getCadenceState(cadence);
-    const now = Date.now();
+    const now = nowMs();
     if (s.openUntil > now) return { allowed: false, reason: "circuit-open", retry_at: s.openUntil };
     if (s.nextAllowedAt > now) return { allowed: false, reason: "backoff", retry_at: s.nextAllowedAt };
     // Circuit closes automatically when openUntil passes.
@@ -1107,7 +1298,7 @@ export function startConsumer(opts = {}) {
       }
     }
 
-    const def = getCadenceDef(event.cadence);
+    const def = cadenceDef(event.cadence);
     let promptPath = def?.prompt;
     if (!promptPath) {
       // Unknown cadence — try the conventional location.
@@ -1121,6 +1312,15 @@ export function startConsumer(opts = {}) {
         stats.dlq += 1;
         return { ok: false, decision: "dlq-no-prompt" };
       }
+    } else if (!existsSync(join(agentRoot, promptPath))) {
+      // THE ELI FAULT, caught before it can loop. The `!promptPath` branch above
+      // has checked the conventional path since it was written; a prompt named
+      // by CONFIG was never checked at all — it was handed straight to the
+      // handoff renderer and then, when that threw, to the spawn, which opens
+      // the same path. Both fail, neither is terminal, and the tick comes back
+      // on the bus 30 seconds later. Check it once, here, and classify.
+      const verdict = classifyCadenceFailure({ phase: "prompt", error: `prompt not found: ${promptPath}` });
+      return failPermanently(event, verdict, `configured prompt missing: ${promptPath}`, "escalate_prompt_missing");
     }
 
     // Per-cadence in-flight guard (F9): never the same cadence twice at once —
@@ -1139,31 +1339,69 @@ export function startConsumer(opts = {}) {
       const fd = frontDoorState();
       const verdict = shouldHandOffTick({ ...fd, mode: def?.mode, metadata: event.metadata });
       if (verdict.handOff) {
+        // The PROMPT read is its own step, with its own catch. It used to sit
+        // inside the handoff try/catch, so a prompt that could not be read was
+        // indistinguishable from a handoff file that could not be written — and
+        // the shared catch fell through to the spawn, which opens the same
+        // prompt path. That is the busy loop: `handoff_failed_spawning_instead`
+        // 16 times per 30 seconds on Eli Rosenberg's seat, 2026-09-24.
+        // Split apart, each failure gets the answer it deserves: a permanent
+        // prompt fault stops here; an unwritable handoff still falls through,
+        // because the spawn genuinely might work.
+        let rendered = null;
         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" };
+          rendered = renderHandoffPrompt(event.id, promptPath);
         } 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 });
+          // renderHandoffPrompt stamps which half failed (see its doc): the
+          // READ of the cadence prompt, or everything after it. Only the read
+          // says anything about whether a spawn would work — the spawn opens
+          // the same path — so only `cadencePhase === "prompt"` may reach a
+          // permanent verdict. An unwritable handoff dir falls through to the
+          // spawn like any other handoff fault.
+          //
+          // This used to be inferred from `msg.includes(promptPath)`, which is
+          // false for EISDIR (Node omits the path), so the commonest unreadable
+          // case — a DIRECTORY at the prompt path — fell through and spawned.
+          // Never classify a path fault by whether the message quotes the path.
+          const msg = (err && err.message) || "";
+          const promptVerdict = classifyCadenceFailure({
+            phase: err?.cadencePhase === "prompt" ? "prompt" : "spawn",
+            error: msg,
+            errno: err?.cadenceErrno,
+          });
+          if (isPermanent(promptVerdict)) {
+            return failPermanently(event, promptVerdict, msg, "handoff_prompt_failed_permanently");
+          }
+          log({ level: "warn", stage: "handoff_render_failed_spawning_instead", id: event.id, cadence: event.cadence, phase: err?.cadencePhase || null, error: msg });
+        }
+        if (rendered) {
+          try {
+            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 FILE we could not write is not a reason to lose the tick,
+            // and it says nothing about whether the spawn would work — fall
+            // through to the legacy spawn, loudly, exactly as before. The prompt
+            // half of this, which DOES say so, is handled above.
+            log({ level: "warn", stage: "handoff_failed_spawning_instead", id: event.id, cadence: event.cadence, error: err && err.message });
+          }
         }
       }
     }
@@ -1292,6 +1530,15 @@ export function startConsumer(opts = {}) {
     stats.spawn_failures += 1;
     recordSubsessionFailure(event.cadence);
     const reason = result.error || (stderrTail ? `exit ${result.exit_code}: ${stderrTail}` : `exit ${result.exit_code}`);
+    // Can this possibly succeed if we try again? `realSpawnSession` answers
+    // -2 (prompt not on disk) / -3 (prompt unreadable) for causes that do not
+    // move; those get the classifier's bounded budget and a durable,
+    // visible record. Everything else — a timeout, a non-zero exit, a crash —
+    // is transient and unchanged.
+    const spawnVerdict = classifyCadenceFailure({ phase: "spawn", exitCode: result.exit_code, error: reason });
+    if (isPermanent(spawnVerdict)) {
+      return failPermanently(event, spawnVerdict, reason, "subsession_failed_permanently");
+    }
     const outcome = failTick(agentRoot, event.id, reason, { maxAttempts });
     if (outcome?.destination === "dlq") stats.dlq += 1;
     else stats.retries += 1;
@@ -1304,7 +1551,7 @@ export function startConsumer(opts = {}) {
     stats.received += 1;
     stats.last_event_id = event.id;
 
-    const def = getCadenceDef(event.cadence);
+    const def = cadenceDef(event.cadence);
     if (def?.mode === "inline" && typeof def.handler === "function") {
       try {
         const out = await def.handler({ event, agentRoot, log });

package/scripts/daemon/deliver.mjs

@@ -35,6 +35,7 @@ import { recordOutbound } from "../../lib/comms/receipts.mjs";
 // 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 { ROOM_SURFACES, SURFACE_NAMES } from "../../lib/org/inbound/surfaces.mjs";
+import { isRetiredFirstReply } from "../../lib/assurance/first-reply.mjs";
 
 const AGENT_REPO_DIR = process.env.AGENT_DIR || join(new URL(".", import.meta.url).pathname, "../..");
 
@@ -741,11 +742,117 @@ export function scaffoldMarkerLeak(text) {
  *          escalate rather than lose the message to an exception. `permanent`
  *          means retrying cannot help (no route, or a NOT_FOUND/BAD_REQUEST).
  */
+/**
+ * Can this inbound be answered with a REACTION rather than a sentence?
+ *
+ * Only a Cohort message in a real room can: a reaction is attached to a message
+ * id in a channel, and that is the one surface where both exist. A board
+ * comment, a doc comment, an email and a Slack item all answer `false` here
+ * even where the underlying product has reactions, because this daemon has no
+ * route to them — and a shape decision that promises a reaction the transport
+ * cannot make would turn "acknowledge cheaply" into "say nothing at all".
+ *
+ * @param {object} item
+ * @returns {boolean}
+ */
+export function canReactTo(item) {
+  if (!item || item.service !== "cohort") return false;
+  const route = cohortReplyRoute(item);
+  if (route.transport !== "channel") return false;
+  return Boolean(str(item.message_id));
+}
+
+/**
+ * Put a reaction on the message that arrived.
+ *
+ * The cheapest honest acknowledgement there is: it tells the sender their
+ * message reached a person, and it adds no row to the channel. That second
+ * property is the whole argument for it — the measured flood
+ * (`lib/assurance/tier.mjs`) was 3,069 acknowledgement ROWS, and a reaction is
+ * an acknowledgement that is not a row.
+ *
+ * Fail-open and quiet: a reaction that cannot be made is not an error worth
+ * escalating, it is a reason to write the line instead, and the caller treats
+ * `{sent:false}` exactly that way.
+ *
+ * @param {object} item
+ * @param {string} emoji
+ * @param {object} [o] {cfg, agentRoot, reactImpl, fetchImpl} test seams
+ * @returns {Promise<{sent:boolean, via:string|null, error?:string}>}
+ */
+export async function deliverReaction(item, emoji, o = {}) {
+  if (!canReactTo(item)) return { sent: false, via: null, error: "no reaction surface" };
+  const e = str(emoji);
+  if (!e) return { sent: false, via: null, error: "no emoji" };
+  try {
+    const route = cohortReplyRoute(item);
+    const agentRoot = o.agentRoot || process.env.AGENT_ROOT || process.env.AGENT_DIR || process.cwd();
+    const cfg = o.cfg || (await import("../../lib/org/client.mjs")).loadOrgConfig(agentRoot);
+    const reactImpl = o.reactImpl || (await import("../../lib/org/messaging.mjs")).reactMessage;
+    const frame = await reactImpl(
+      { channel: route.channelId, messageId: str(item.message_id), emoji: e },
+      { cfg, agentRoot, idempotencyKey: `react-${str(item.message_id)}-${e}`, ...(o.fetchImpl ? { fetchImpl: o.fetchImpl } : {}) },
+    );
+    if (frame && frame.ok) {
+      recordOutbound({ service: "cohort", channel: route.channelId, kind: "reaction", via: "cohort", chars: 0, agentRoot });
+      return { sent: true, via: "cohort" };
+    }
+    return { sent: false, via: null, error: str(frame && frame.error && frame.error.message) || "react failed" };
+  } catch (err) {
+    return { sent: false, via: null, error: (err && err.message) || String(err) };
+  }
+}
+
 export async function deliver(item, text, o = {}) {
   const kind = o.kind || "reply";
   if (!item || !text || !String(text).trim()) {
     return { sent: false, via: null, error: "nothing to deliver" };
   }
+  // ── THE REGISTER, AT THE CHOKEPOINT ──────────────────────────────────────
+  // Every outbound this daemon makes crosses this function — the answer, the
+  // acknowledgement and the assurance sweep alike — which is why the scaffold
+  // check below lives here rather than at three call sites. The retired
+  // placeholder replies get the same treatment, and for a reason the composer
+  // guards cannot cover:
+  //
+  // On 2026-09-25 two seats (Ravi Patel, Daniel Connors) were still emitting
+  // "On it." / "Looking now." / "On it — digging in now." — 251 of them in six
+  // days, the last at 11:28Z that morning — with `clientMsgId` ending `-ack`,
+  // i.e. through this very path, while `AgentStatus.machine.daemon` reported
+  // sdkVersion 2.18.13 and `versionsAgree: true`. The published package at that
+  // version contains none of those strings and `sanitiseAckText` returns null
+  // for all three. The explanation is that the daemon runs
+  // `$AGENT_ROOT/scripts/daemon/maestro-daemon.mjs` — the seat's PRESERVED
+  // LOCAL COPY — and `versionsAgree` compares two npm version numbers, which
+  // says nothing whatever about that tree.
+  //
+  // WHAT THIS GUARD DOES AND DOES NOT REACH — stated exactly, because the first
+  // version of this comment overclaimed it and a reader would have taken the
+  // stale-seat vector for closed.
+  //
+  //   IT DOES     protect every outbound of an UPDATED daemon, at the last point
+  //               before bytes leave the machine, whatever composed the text:
+  //               the answer, the acknowledgement, the assurance sweep, and any
+  //               composer added later that nobody remembers to guard. That is
+  //               the case for putting it here rather than at three call sites.
+  //   IT DOES NOT reach the two seats that were actually emitting these
+  //               sentences. This file is `scripts/daemon/deliver.mjs`, and it
+  //               lives in the very tree those seats have preserved a stale copy
+  //               of — a stale tree ships a stale deliver.mjs alongside its
+  //               stale composer. THE REMEDY FOR THOSE SEATS IS THE ROLLOUT
+  //               (publish, then `scripts/local-triggers/autoupdate.sh` on each
+  //               box, verified by a server-recorded presence.beat rather than
+  //               by `versionsAgree`). Nothing in this file can shorten that.
+  //
+  // The other plane is covered separately: `lib/comms/send-gate.screenOutbound`
+  // and `screenHookPayload` apply the same register to `messaging_send`,
+  // `email_send`, `email_draft_send` and `org_call_share_step`, which is how a
+  // SPAWNED SESSION typing "On it." itself gets refused — that path never
+  // crosses this function.
+  if (isRetiredFirstReply(text)) {
+    try { console.error(`[deliver] refused: retired placeholder reply in outbound body ${JSON.stringify(String(text).slice(0, 120))} — this is a stale composer, not a message (permanent, not retrying)`); } catch { /* */ }
+    return { sent: false, via: null, permanent: true, channel: item && item.channel_id, code: "FORBIDDEN_SCOPE", error: "FORBIDDEN_SCOPE: retired placeholder reply — the first line must be generated from the actual thread, or nothing" };
+  }
   const leak = scaffoldMarkerLeak(text);
   if (leak) {
     const surface = (item && item.channel_id) ? "room" : "unknown";
@@ -827,6 +934,8 @@ export async function deliverWithRetry(item, text, o = {}) {
 export default {
   deliver,
   deliverWithRetry,
+  canReactTo,
+  deliverReaction,
   resolveSlackChannel,
   replyTargetOf,
   canDeliverTo,

package/scripts/daemon/dispatcher.mjs

@@ -6,7 +6,7 @@ import { spawn } from "child_process";
 import { appendFileSync, mkdirSync, writeFileSync, readFileSync, renameSync, existsSync, readdirSync, unlinkSync } from "fs";
 import { randomUUID } from "crypto";
 import { join, dirname } from "path";
-import { releaseLock, releaseThreadLock, releaseRequestClaim, claimItem, releaseItemClaim } from "./session-lock.mjs";
+import { releaseLock, releaseThreadLock, threadLockKey, releaseRequestClaim, claimItem, releaseItemClaim } from "./session-lock.mjs";
 import { promoteDeferred } from "./inbox-deferral.mjs";
 import { recordSession } from "./health.mjs";
 import { startTyping, stopTyping } from "./typing-registry.mjs";
@@ -2020,7 +2020,16 @@ function spawnSession(entry) {
     {
       const channel = item.channel_id || (item.raw_ref ? (item.raw_ref.match(/slack:([^:]+):/) || [])[1] : null) || item.channel;
       if (channel) {
-        releaseThreadLock(channel, item.thread_id);
+        // THE SAME KEY THE DAEMON TOOK. `item.thread_id` alone is not that
+        // key: an untreaded post locks `channel-main` and a Cohort DM locks
+        // `dm-channel`, and neither is derivable from an empty thread id
+        // without the item's own DM verdict. One derivation, both sides.
+        releaseThreadLock(channel, threadLockKey({
+          channel,
+          threadId: item.thread_id,
+          isDm: item.is_dm === true,
+          channelMainLock: String(process.env.MAESTRO_CHANNEL_MAIN_LOCK ?? "1") !== "0",
+        }));
         // Now that the lock is gone, promote any messages that were
         // deferred behind it. Latest-wins: a burst of N messages
         // collapses into ONE re-dispatch carrying the most recent
@@ -2157,7 +2166,16 @@ function spawnSession(entry) {
     {
       const channel = item.channel_id || (item.raw_ref ? (item.raw_ref.match(/slack:([^:]+):/) || [])[1] : null) || item.channel;
       if (channel) {
-        releaseThreadLock(channel, item.thread_id);
+        // THE SAME KEY THE DAEMON TOOK. `item.thread_id` alone is not that
+        // key: an untreaded post locks `channel-main` and a Cohort DM locks
+        // `dm-channel`, and neither is derivable from an empty thread id
+        // without the item's own DM verdict. One derivation, both sides.
+        releaseThreadLock(channel, threadLockKey({
+          channel,
+          threadId: item.thread_id,
+          isDm: item.is_dm === true,
+          channelMainLock: String(process.env.MAESTRO_CHANNEL_MAIN_LOCK ?? "1") !== "0",
+        }));
         const promo = promoteDeferred(channel, AGENT_REPO_DIR);
         if (promo.promoted > 0) {
           logSession({