@cohortapp/agent-sdk 2.5.1 → 2.6.1

package/scripts/cost/track-claude-usage.test.mjs

@@ -0,0 +1,148 @@
+/**
+ * scripts/cost/track-claude-usage.test.mjs — the record contract every spawn
+ * path depends on.
+ *
+ * The defect these lock down: `Number(flags["input-tokens"] || 0)` turned an
+ * ABSENT token flag into a literal 0, so "we could not measure this session"
+ * and "this session was free" wrote identical rows. Every reader summed both as
+ * $0, and the budget governor could never trip.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync, readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const TRACKER = fileURLToPath(new URL("./track-claude-usage.mjs", import.meta.url));
+
+function withRoot(fn) {
+  const root = mkdtempSync(join(tmpdir(), "track-usage-"));
+  try { return fn(root); } finally { rmSync(root, { recursive: true, force: true }); }
+}
+
+function record(root, args) {
+  const r = spawnSync(process.execPath, [TRACKER, "record", ...args], {
+    encoding: "utf-8",
+    env: { ...process.env, AGENT_ROOT: root, AGENT_DIR: root },
+  });
+  assert.equal(r.status, 0, `tracker exited ${r.status}: ${r.stderr}`);
+  return r;
+}
+
+function rows(root) {
+  const date = new Date().toISOString().slice(0, 10);
+  const file = join(root, "state/cost-tracking", `${date}.jsonl`);
+  if (!existsSync(file)) return [];
+  return readFileSync(file, "utf-8").split("\n").filter(Boolean).map((l) => JSON.parse(l));
+}
+
+test("record: real usage is priced cache-aware and keeps the authoritative cost", () => {
+  withRoot((root) => {
+    // The live token profile: almost all prompt tokens are cache reads. The old
+    // per-1K, cache-blind table priced this session at $0.075 against a real
+    // $0.533 — a 7x under-read on a single row.
+    record(root, [
+      "--cadence", "inbox", "--source", "dispatcher", "--model", "sonnet",
+      "--input-tokens", "16", "--output-tokens", "5000",
+      "--cache-read-tokens", "553181", "--cache-creation-tokens", "78000",
+      "--total-cost-usd", "0.533412", "--exit", "0",
+    ]);
+    const [row] = rows(root);
+    assert.equal(row.measurement, "measured");
+    assert.equal(row.input_tokens, 16);
+    assert.equal(row.output_tokens, 5000);
+    assert.equal(row.cache_read_input_tokens, 553181);
+    assert.equal(row.cache_creation_input_tokens, 78000);
+    assert.equal(row.total_cost_usd, 0.533412);
+    // The estimate must now land in the same ballpark as the CLI's own figure.
+    // (Pre-fix it was 0.075048 — the cache tiers were simply not priced.)
+    const drift = Math.abs(row.estimated_usd - row.total_cost_usd) / row.total_cost_usd;
+    assert.ok(drift < 0.05, `cache-aware estimate should track the authoritative cost, drift=${drift}`);
+  });
+});
+
+test("record: an unmeasured session writes NULL tokens, never a zero", () => {
+  withRoot((root) => {
+    const r = record(root, [
+      "--cadence", "inbox", "--source", "dispatcher",
+      "--tokens-unknown", "no-usage-field",
+    ]);
+    const [row] = rows(root);
+    assert.equal(row.measurement, "unknown");
+    assert.equal(row.input_tokens, null, "NOT 0 — a zero here is what blinded the governor");
+    assert.equal(row.output_tokens, null);
+    assert.equal(row.estimated_usd, null, "no cost claim at all");
+    assert.equal(row.total_cost_usd, null);
+    assert.equal(row.unmeasured_reason, "no-usage-field");
+    // And it must be loud: this is the only place that observes the gap at
+    // write time, and every bug in this system has been a quiet catch.
+    assert.match(r.stderr, /UNMEASURED session recorded/);
+    assert.match(r.stderr, /unknown, not zero/);
+  });
+});
+
+test("record: a caller that passes NO token flags degrades to unknown, not $0", () => {
+  // An un-migrated caller must fail loudly rather than silently claim a free
+  // session — this is the exact shape of the original bug.
+  withRoot((root) => {
+    record(root, ["--cadence", "inbox", "--source", "dispatcher", "--model", "sonnet"]);
+    const [row] = rows(root);
+    assert.equal(row.measurement, "unknown");
+    assert.equal(row.input_tokens, null);
+    assert.equal(row.unmeasured_reason, "caller-passed-no-token-counts");
+  });
+});
+
+test("record: a genuine zero-token session stays MEASURED and free", () => {
+  withRoot((root) => {
+    record(root, [
+      "--cadence", "inbox", "--source", "dispatcher", "--model", "sonnet",
+      "--input-tokens", "0", "--output-tokens", "0", "--total-cost-usd", "0",
+    ]);
+    const [row] = rows(root);
+    assert.equal(row.measurement, "measured", "we looked; the answer was zero");
+    assert.equal(row.input_tokens, 0);
+    assert.equal(row.estimated_usd, 0);
+  });
+});
+
+test("record: --non-llm marks attribution rows that never invoked a model", () => {
+  withRoot((root) => {
+    record(root, ["--cadence", "messaging", "--source", "messaging", "--non-llm"]);
+    const [row] = rows(root);
+    assert.equal(row.measurement, "n/a");
+    assert.equal(row.model, null);
+    assert.equal(row.estimated_usd, 0, "$0 is a fact here, not a measurement gap");
+  });
+});
+
+test("summarise: reports unmeasured sessions instead of averaging them away", () => {
+  withRoot((root) => {
+    record(root, [
+      "--source", "dispatcher", "--model", "sonnet",
+      "--input-tokens", "16", "--output-tokens", "5000",
+      "--cache-read-tokens", "553181", "--total-cost-usd", "0.5",
+    ]);
+    record(root, ["--source", "dispatcher", "--tokens-unknown", "empty-stdout"]);
+    record(root, ["--source", "messaging", "--non-llm"]);
+
+    const r = spawnSync(process.execPath, [TRACKER, "summarise", "--days", "1"], {
+      encoding: "utf-8",
+      env: { ...process.env, AGENT_ROOT: root, AGENT_DIR: root },
+    });
+    assert.equal(r.status, 0, r.stderr);
+    const out = JSON.parse(r.stdout);
+    assert.equal(out.measurement.measured_sessions, 1);
+    assert.equal(out.measurement.unmeasured_sessions, 1);
+    assert.equal(out.measurement.non_llm_rows, 1, "a send is not a session");
+    assert.equal(out.measurement.authoritative_usd, 0.5);
+    assert.equal(out.totals.sessions, 2, "measured + unmeasured; the send is excluded");
+    assert.ok(
+      out.measurement.degradations.some((d) => /NO token counts/.test(d)),
+      "the gap is named, not swallowed"
+    );
+  });
+});

package/scripts/daemon/agent-daemon.mjs

@@ -54,6 +54,22 @@ import { classifyItem, isDirectedAtAgent } from "./classifier.mjs";
 import { dispatch, getStatus, availableSlots, canDispatchBacklog, resetActiveSessions } from "./dispatcher.mjs";
 import { buildPrompt } from "./prompt-builder.mjs";
 import { sendQuickResponse, sendHoldingMessage, isQuickReply } from "./responder.mjs";
+// ANSWER ASSURANCE (scripts/daemon/assurance.mjs). The guarantee that an ask is
+// always answered by SOMETHING: an instant model-free acknowledgement when a
+// session is about to make the human wait, an interim update when the work
+// outruns its welcome, a message on every terminal failure, and a durable
+// on-disk obligation that a sweep discharges when this process cannot. It is
+// imported here because this file is where every one of those moments happens —
+// the dispatch decision, the session close, and the tick loop.
+import {
+  shouldAcknowledge,
+  openAndAcknowledge,
+  noteSession,
+  settleSession,
+  sweepObligations,
+  openObligations,
+  escalate,
+} from "./assurance.mjs";
 import { recordPoll, recordClassification, recordSession, writeHealthDashboard } from "./health.mjs";
 import { acquireLock, releaseLock, updateLock, scanStaleLocks, acquireThreadLock, claimRequest, hasActiveClaim, sweepStaleItemClaims, sanitiseItemId } from "./session-lock.mjs";
 import { markDeferred } from "./inbox-deferral.mjs";
@@ -69,7 +85,8 @@ const RUNG_MECHANISM = Object.fromEntries(RUNGS.map((r) => [r.id, r.mechanism]))
 // local SQLite/interaction logs remain the fail-open cache.
 import { isEnabled as orgEnabled, loadOrgConfig } from "../../lib/org/client.mjs";
 import { remember as orgRemember } from "../../lib/org/knowledge.mjs";
-import { sweepSessionOutcomes } from "./session-outcomes.mjs";
+import { sweepSessionOutcomes, resultTextFromStdout } from "./session-outcomes.mjs";
+import { recordWorkStep as orgRecordWorkStep } from "../../lib/org/work-ledger.mjs";
 // Observability spine (WS — diagnostics). mintTraceId + withTrace give each
 // inbound item ONE trace_id that deep callees inherit via AsyncLocalStorage;
 // emitEvent appends the canonical interaction hops (item_received → … → sent /
@@ -518,6 +535,27 @@ export async function answerItem(item, service, itemId, trace_id, deps = {}, rou
       const result = await _sendQuickResponse(item, classResult, routed);
       if (result.sent) {
         markProcessed(item, service);
+        // WORK VISIBILITY on the FAST path too, with `deferred: false`. This is
+        // what stops the two planes drifting: an ask answered inside the turn
+        // gets a row ONLY if its text asks for something to be DONE, and that
+        // judgement is made by the server's gate — the same gate, the same
+        // answer, whether the agent is driven from here or from hq. Most
+        // quick replies leave no board row, which is correct: the answer IS the
+        // artifact, and a board full of answered questions is a board nobody
+        // reads.
+        // `accepted`, not `done`. The quick path posted a reply and nothing else,
+        // and the server gate only tracks a `deferred:false` ask when its text
+        // ASKED FOR WORK — exactly the case where a reply is not the work. A row
+        // created and closed in the same instant claims the ask was delivered by
+        // a message; leaving it open is the truthful reading, and the stable
+        // askKey means whatever really finishes it closes THIS row.
+        void trackWorkStep({
+          item,
+          stage: "accepted",
+          deferred: false,
+          note: "Answered directly in the conversation.",
+          source: { service, path: "quick_reply" },
+        });
         return { ok: true, path: "quick_reply", reason: classResult.model };
       }
       // If quick reply failed to send or was blocked by validation, fall through to dispatch a full session
@@ -525,20 +563,80 @@ export async function answerItem(item, service, itemId, trace_id, deps = {}, rou
       console.warn(`[daemon] Quick reply not sent (${reason}), falling through to session dispatch`);
     }
 
-    // COMPLEX WORK PATH: Send immediate holding message, then dispatch full session
+    // COMPLEX WORK PATH — reaching this line IS the decision that the answer is
+    // not arriving in this turn. Everything above either answered the human
+    // (quick reply) or declined to; from here a session spawns and the human
+    // waits minutes. So this is exactly where an acknowledgement is owed, and
+    // the only place it can be decided from fact rather than guess.
+    //
+    // THE OLD GATE ASKED THE CLASSIFIER: `action === respond|draft|research`.
+    // That silently excluded `queue` — which is what classifier.mjs's HEURISTIC
+    // FALLBACK emits when the LLM classifier itself fails. So precisely when the
+    // system was degraded, a directed DM got a 15-45 minute session and no
+    // acknowledgement whatsoever. `shouldAcknowledge` asks about control flow
+    // instead: a session is spawning and a human is on the other end of a
+    // resolvable channel, therefore say something now.
+    //
+    // The OBLIGATION is opened before the send and outlives this process. If the
+    // acknowledgement fails to go out, the debt is still on disk and the
+    // assurance sweep retries it — the old code caught that failure, logged it,
+    // and left the human staring at a typing indicator.
     let holdingText = null;
+    let obligationKeyForItem = null;
+    const ackVerdict = shouldAcknowledge({ willSpawnSession: true, item, source: "inbox" });
     try {
-      if (classResult.action === "respond" || classResult.action === "draft" || classResult.action === "research") {
-        const holdResult = await _sendHoldingMessage(item, classResult);
-        holdingText = holdResult.sent ? holdResult.holdingText : null;
-        if (holdResult.sent) {
-          updateLock(itemId, { holdingSent: true });
-        }
+      // The DEBT is opened whether or not we can speak. Those are two different
+      // questions and conflating them is what made a whole class of ask
+      // disappear: an item with no resolvable reply channel (calendar, voice, an
+      // inbound with no room) got no obligation, so when its session died the
+      // failure path had nothing to consult, marked the item processed on the
+      // FIRST failure, said nothing, and escalated nothing. The ask was gone.
+      // Now the record always exists — `ack:false` merely means the compensating
+      // action is an operator escalation instead of a message.
+      const opened = await openAndAcknowledge({
+        item,
+        classResult,
+        service,
+        traceId: trace_id,
+        ack: ackVerdict.ack,
+        deps: { ackSender: _sendHoldingMessage },
+      });
+      obligationKeyForItem = opened.key;
+      holdingText = opened.ackText;
+      if (opened.acked) {
+        updateLock(itemId, { holdingSent: true });
+      } else if (ackVerdict.ack) {
+        // NOT fatal, NOT silent, NOT forgotten. Loud here; retried by the sweep.
+        console.warn(`[daemon] acknowledgement not delivered for ${itemId} (${opened.error}) — obligation ${opened.key} left open for the assurance sweep`);
+        counters.bump("assurance.ack_deferred", { service });
+      } else {
+        console.log(`[daemon] no acknowledgement for ${itemId} (${ackVerdict.reason}) — debt ${opened.key} still tracked`);
       }
     } catch (err) {
-      console.error(`[daemon] Holding message failed (non-fatal): ${err.message}`);
+      // openAndAcknowledge does not throw; if it somehow does, the debt may not
+      // exist, so this is the one case worth shouting about.
+      console.error(`[daemon] acknowledgement path threw for ${itemId}: ${err.message}`);
+      emitEvent({ type: EVENT_TYPES.ERROR, trace_id, attrs: { item_id: itemId, service, stage: "acknowledge", error: err.message } });
     }
 
+    // WORK VISIBILITY, step 1 of 3: the ask goes on the board BEFORE the work
+    // starts, not after it finishes. Reaching this line is the same fact that
+    // earned the acknowledgement above — the answer is not arriving this turn —
+    // so the board row and the "let me look into it" have ONE trigger between
+    // them. A human who is about to wait fifteen minutes gets something to look
+    // at for those fifteen minutes, with himself tagged on it.
+    //
+    // `deferred: true` is the whole signal the server's gate needs; everything
+    // else about whether this deserves a row is decided there, by the same code
+    // that decides it for hq's responder.
+    void trackWorkStep({
+      item,
+      stage: "accepted",
+      deferred: true,
+      note: classResult && classResult.summary ? `Picked this up. ${classResult.summary}` : "Picked this up — starting work now.",
+      source: { service, trace_id, classified: String(classResult && classResult.action) },
+    });
+
     // Build prompt with holding message context and dispatch
     const prompt = await buildPrompt(item, classResult, {
       type: "inbox",
@@ -553,8 +651,38 @@ export async function answerItem(item, service, itemId, trace_id, deps = {}, rou
     // re-delivered on the next poll; a crash mid-flight leaves the admission for
     // recoverInFlight() to re-deliver on restart.
     recordInFlight(item, service);
+    if (obligationKeyForItem) noteSession(obligationKeyForItem, null);
     _dispatch(prompt, item, classResult, "inbox", {
+      // Carried into the session child's env so its CLI send lanes stamp their
+      // delivery receipts with the debt they discharge. This is what lets the
+      // close handler below distinguish "the session answered him" from "the
+      // session exited 0 in silence" — and, just as importantly, from "a
+      // DIFFERENT session answered a different ask in the same room".
+      obligationKey: obligationKeyForItem,
       onClose: ({ ok, code, sessionId, stdout }) => {
+        // EVERY terminal state now ends in a decision about what the human
+        // hears. `settleSession` owns that decision and is the only thing here
+        // that can speak; the branches below only handle bookkeeping.
+        //
+        // It cannot be awaited (onClose is sync by contract), so it is a
+        // fire-and-forget promise with its own catch — but unlike the fail-open
+        // catches around it, a throw HERE means the human may be owed a message,
+        // so it is logged at error level and the obligation stays open for the
+        // sweep to pick up.
+        const settle = obligationKeyForItem
+          ? Promise.resolve(settleSession({
+              key: obligationKeyForItem,
+              ok,
+              code,
+              sessionId,
+              stdout,
+              error: ok ? null : `session_close exit ${code}`,
+            })).catch((err) => {
+              console.error(`[daemon] settleSession threw for ${itemId}: ${err.message} — obligation left open for sweep`);
+              return { spoke: false, verdict: "settle_threw", willRetry: false };
+            })
+          : Promise.resolve({ spoke: false, verdict: "no-obligation", willRetry: false });
+
         if (ok) {
           markProcessed(item, service);
           clearInFlight(item);
@@ -570,20 +698,87 @@ export async function answerItem(item, service, itemId, trace_id, deps = {}, rou
           // DAEMON_SESSION_OUTCOMES=1; idempotent + fail-open; fire-and-forget.
           Promise.resolve(sweepOutcomesForSession({ sessionId, stdout, item, classResult }))
             .catch(() => { /* fail-open */ });
+          // WORK VISIBILITY, step 2 of 3: the row moves to done and carries what
+          // the turn actually produced as a comment, so the board says what
+          // happened rather than merely that something did. The requester is
+          // tagged, so "it's finished" reaches him without him having to look.
+          void trackWorkStep({
+            item,
+            stage: "done",
+            deferred: true,
+            note: sessionCompletionNote(stdout),
+            source: { service, sessionId: String(sessionId || ""), exit_code: String(code) },
+          });
           // Finalize (interaction end): emit `sent` carrying the SAME trace_id
           // minted at item_received, so the full hop chain (item_received → … →
-          // sent) groups by one stable id. The session itself posts the actual
-          // user-facing reply via the Slack/Gmail APIs; this row marks the clean
-          // close of the work the user's message kicked off.
-          emitEvent({ type: EVENT_TYPES.SENT, trace_id, attrs: { item_id: itemId, service, exit_code: code } });
+          // sent) groups by one stable id.
+          //
+          // `exit_code: 0` is NOT evidence that the human was answered. The old
+          // comment here asserted "the session itself posts the actual reply",
+          // and nothing ever checked — so a session that exited 0 having sent
+          // nothing (observed: 241s, $2.36, final text "Nothing was sent.") was
+          // marked processed forever and emitted as `sent`. The `spoke` attr now
+          // carries what settleSession actually established.
+          settle.then((s) => {
+            emitEvent({
+              type: EVENT_TYPES.SENT,
+              trace_id,
+              attrs: { item_id: itemId, service, exit_code: code, verdict: s.verdict, daemon_spoke: !!s.spoke },
+            });
+            if (s.verdict === "silent-success") {
+              counters.bump("assurance.silent_success_rescued", { service });
+            }
+          });
         } else {
-          // Leave the inbox file un-`.processed` (re-deliverable). Drop the
-          // admission + release the per-item lock so the next poll re-delivers
-          // immediately rather than waiting out the stale-lock TTL.
           clearInFlight(item);
           const key = inflightKey(item);
           if (key) releaseLock(key);
           emitEvent({ type: EVENT_TYPES.ERROR, trace_id, attrs: { item_id: itemId, service, exit_code: code, stage: "session_close" } });
+          // WORK VISIBILITY, step 3 of 3 — THE ONE THAT MATTERS. A session that
+          // dies used to leave exactly one observable: the typing dot stopping.
+          // The row now moves to BLOCKED (never quietly to done — the work is
+          // still owed to somebody), carries the exit code, and TAGS the
+          // requester. This is the difference between a process that failed and
+          // a process that failed invisibly.
+          void trackWorkStep({
+            item,
+            stage: "failed",
+            deferred: true,
+            note: `The session handling this ended without completing (exit ${code}). It is back on the board, blocked, rather than quietly dropped.`,
+            source: { service, sessionId: String(sessionId || ""), exit_code: String(code) },
+          });
+          // SELF-HEAL, BOUNDED. A transient failure with retries left leaves the
+          // inbox file un-`.processed` so the next poll re-delivers it — that was
+          // already true, but it was UNBOUNDED and SILENT: the same item could
+          // cycle through 45-minute sessions forever with the human hearing
+          // nothing. Now the requester is told a retry is running, and when the
+          // retries are spent the item is marked processed so the loop STOPS,
+          // the human is told it failed, and a durable needs-attention record is
+          // written. A dropped ask must leave a trace; it must not leave a loop.
+          settle.then((s) => {
+            if (!s.willRetry) {
+              // `no-obligation` reaches here only if the item had no stable key
+              // at all, so nothing durable is tracking it. Marking it processed
+              // would delete the ask on its FIRST failure with no message and no
+              // trace — the exact silent drop this whole unit exists to end. Write
+              // the escalation ourselves before the item goes.
+              if (s.verdict === "no-obligation") {
+                escalate(
+                  { key: itemId, sender: item.sender, service, channel: item.channel_id || item.channel || null,
+                    summary: classResult && classResult.summary, openedAt: Date.now(),
+                    attempts: 1, sessionId: String(sessionId || ""), traceId: trace_id,
+                    item: { content: item.content } },
+                  { failure: { label: `exit_${code}` }, told: false },
+                );
+              }
+              markProcessed(item, service);
+              counters.bump("assurance.gave_up", { service, verdict: s.verdict });
+              console.error(`[daemon] ${itemId} failed terminally (${s.verdict}); requester told: ${!!s.spoke}`);
+            } else {
+              counters.bump("assurance.retrying", { service, verdict: s.verdict });
+              console.warn(`[daemon] ${itemId} failed (${s.verdict}); retrying — requester told: ${!!s.spoke}`);
+            }
+          });
         }
       },
     });
@@ -1094,6 +1289,76 @@ export function _resetDaemonOrgCfgCache() {
   _cachedDaemonOrgCfg = undefined;
 }
 
+/** Longest completion note we will put on a board comment. */
+const COMPLETION_NOTE_CHARS = 1200;
+
+/**
+ * What the finished session actually produced, as a board comment.
+ *
+ * Reuses `session-outcomes.mjs#resultTextFromStdout` — the same tolerant
+ * extractor the outcome sweep uses — rather than re-parsing the `claude --print`
+ * envelope a second way. A turn that produced nothing readable still gets an
+ * honest line: "finished" with no evidence is worse than nothing, because it is
+ * the exact claim `exit 0` already made falsely.
+ *
+ * @param {string} stdout the session's raw stdout
+ * @returns {string}
+ */
+export function sessionCompletionNote(stdout) {
+  let text = "";
+  try {
+    text = String(resultTextFromStdout(stdout) || "").trim();
+  } catch {
+    text = "";
+  }
+  if (!text) return "The session finished but produced no readable result text.";
+  const clipped = text.length > COMPLETION_NOTE_CHARS ? `${text.slice(0, COMPLETION_NOTE_CHARS)}…` : text;
+  return `Done. What the work produced:\n\n${clipped}`;
+}
+
+/**
+ * WORK VISIBILITY. Record one step of the work this item kicked off against the
+ * org board (`board.track` → hq's `server/work/ledger.ts`).
+ *
+ * DRIVEN, not left to the model. The three call sites below are the three
+ * moments a human's experience changes — the ask is taken on, the work lands,
+ * the work dies — and none of them may depend on a session remembering to write
+ * something down. `DAEMON_SESSION_OUTCOMES` is the cautionary tale: a whole
+ * outcome-discipline module, correct and tested, that has never run in
+ * production because the flag is absent from the launchd plist. This has no
+ * flag. The gate is on the SERVER, where it is one implementation shared with
+ * hq's responder, and where it can be changed without redeploying a laptop.
+ *
+ * Fail-open and fire-and-forget: never awaited on the dispatch path, never able
+ * to throw into it. But never silent either — the reason is always logged, which
+ * is the rule this entire workstream exists to enforce.
+ *
+ * @param {object} a - { item, stage, deferred?, note?, title?, source? } plus
+ *   test seams ({ cfg?, trackImpl?, fetchImpl? })
+ * @returns {Promise<object>} the step result (or a benign refusal)
+ */
+export async function trackWorkStep(a = {}) {
+  try {
+    const cfg = a.cfg !== undefined ? a.cfg : daemonOrgCfg();
+    const res = await orgRecordWorkStep({ ...a, cfg });
+    if (res && res.tracked) {
+      console.log(
+        `[board] ${a.stage} → task ${res.taskId} (${res.col})` +
+          `${res.created ? " created" : ""}${res.moved ? " moved" : ""}` +
+          `${res.commented ? " commented" : ""}${res.tagged ? ` tagged=${res.tagged}` : ""}`,
+      );
+    } else {
+      // A refusal is INFORMATION, not noise: "no-substance" is the gate working,
+      // "org-disabled" is configuration, and an error frame is a real fault.
+      console.log(`[board] ${a.stage} not tracked: ${(res && res.reason) || "unknown"}`);
+    }
+    return res;
+  } catch (err) {
+    console.warn(`[board] track failed (${a.stage}): ${err && err.message}`);
+    return { tracked: false, reason: "error" };
+  }
+}
+
 // A distillation longer than this is truncated before it lands in the store —
 // the shared memory holds a salient one-liner, never a transcript.
 const SESSION_DISTILL_MAX_CHARS = 400;
@@ -1528,6 +1793,23 @@ async function main() {
   // if the work had completed). Runs BEFORE the first poll so recovery wins the
   // race against re-acquisition.
   recoverInFlight();
+  // ANSWER ASSURANCE on startup. `recoverInFlight` above re-delivers the WORK;
+  // this speaks to the PEOPLE. Any obligation still open was opened by a daemon
+  // process that no longer exists — meaning a human asked for something, was
+  // told "I'll come back to you", and then this process died mid-session. They
+  // are owed a word before anything else happens, and the sweep's interrupted
+  // branch is what gives it to them. Awaited (unlike the tick-loop call) so the
+  // first poll cannot spawn new work ahead of settling old debts.
+  const owed = openObligations().length;
+  if (owed > 0) {
+    console.log(`[daemon] ${owed} unanswered obligation(s) survived the last run — settling before first poll`);
+    try {
+      const s = await sweepObligations();
+      console.log(`[daemon] startup assurance sweep — acked:${s.acked} interrupted:${s.interrupted} stale:${s.staled} closed:${s.closed}`);
+    } catch (err) {
+      console.error("[daemon] startup assurance sweep failed:", err.message);
+    }
+  }
   // WS4: on startup, reconcile in-flight session resume markers — re-dispatch
   // `claude --print --resume` for any work that was mid-flight when the box
   // rebooted/lost power (3-strike cap → status:blocked). Shutdown paths below
@@ -1558,7 +1840,14 @@ async function main() {
     }
   }, BACKLOG_INTERVAL);
 
-  // Health dashboard + stale claim sweep
+  // Health dashboard + stale claim sweep + the ANSWER-ASSURANCE sweep.
+  //
+  // The assurance sweep is the safety net under every other path: it is the one
+  // mechanism with no in-memory state, so it works identically on the first tick
+  // after a restart and the ten-thousandth tick of a healthy process. It is what
+  // makes the promise hold when an acknowledgement's send failed, when a
+  // dispatcher never called back, when a promise rejected unhandled, and when
+  // the daemon itself died mid-session.
   setInterval(() => {
     try {
       writeHealthDashboard();
@@ -1570,6 +1859,15 @@ async function main() {
     } catch (err) {
       console.error("[daemon] Health write error:", err.message);
     }
+    // Separate try: a health-write failure must not skip the sweep, because the
+    // sweep is the thing that speaks to humans.
+    Promise.resolve(sweepObligations())
+      .then((s) => {
+        if (s.acked || s.progressed || s.staled || s.interrupted) {
+          console.log(`[daemon] assurance sweep — acked:${s.acked} progress:${s.progressed} stale:${s.staled} interrupted:${s.interrupted} closed:${s.closed} (open:${s.swept})`);
+        }
+      })
+      .catch((err) => console.error("[daemon] assurance sweep error:", err.message));
   }, HEALTH_INTERVAL);
 
   // Graceful shutdown — clean up active.json so next startup doesn't see stale sessions