@cohortapp/agent-sdk 2.5.1 → 2.6.1

package/scripts/daemon/assurance.mjs

@@ -0,0 +1,944 @@
+/**
+ * assurance.mjs — the guarantee that an ask is always answered by something.
+ *
+ * THE COMPLAINT THIS EXISTS TO FIX
+ *
+ * "The typing indicator activates, so I know she received it… if the work takes
+ *  long or errors out, she either never replies, or replies 15-20-30 minutes
+ *  later… right now it dies silently and I never hear from her again unless I
+ *  chase her."
+ *
+ * Measured, that was: acknowledgements delivered 34% of the time (the other 66%
+ * died on a 60s `claude --print` timeout and told the human nothing); sessions
+ * with a median duration of 14.7 minutes and a p90 of 39; and three separate
+ * ways for a session to end without a single word reaching the requester —
+ * non-zero exit (telemetry only), SIGTERM at the 45-minute cap (telemetry only),
+ * and, worst of all, exit 0 having said nothing (marked processed forever and
+ * emitted as `sent`).
+ *
+ * THE MODEL
+ *
+ * An inbound ask that will take real work opens an OBLIGATION: a durable
+ * on-disk debt saying "a human is waiting to hear from me about this." The
+ * obligation is discharged only by evidence that something reached them — a
+ * delivery RECEIPT (lib/comms/receipts), not an exit code. Until it is
+ * discharged it is swept, and every sweep that finds an overdue debt SPEAKS.
+ *
+ *   open      → ack immediately (template, no model, cannot time out)
+ *   overdue   → interim progress update, capped, never spam
+ *   failed    → say what happened and what happens next; retry once if the
+ *               cause was transient; when out of retries, say so and escalate
+ *   finished  → verify a receipt exists; if the session said nothing, say it
+ *   orphaned  → a daemon that restarts finds the debt and speaks to it
+ *
+ * WHY THE LEDGER IS ON DISK AND THE SWEEP IS NOT A TIMER
+ *
+ * Every in-process mechanism here dies with the process, and the process dying
+ * is one of the failure modes. An obligation file outlives the daemon; the
+ * sweep re-derives what is owed from disk on every tick, including the first
+ * tick after a restart. `daemonPid` on the record is what makes an interrupted
+ * obligation self-evident.
+ *
+ * FAIL-OPEN, NEVER SILENT. Nothing in this module throws into the hot path. But
+ * the fail-open direction is chosen deliberately in each case: when we cannot
+ * tell whether the human was spoken to, we assume they were not. The worst case
+ * is one redundant message; the bug being fixed is silence.
+ *
+ * @module scripts/daemon/assurance
+ */
+
+"use strict";
+
+import { mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "fs";
+import { join } from "path";
+import { deliver, deliverWithRetry, replyTargetOf, canDeliverTo } from "./deliver.mjs";
+import { spokeFor } from "../../lib/comms/receipts.mjs";
+import { resultTextFromStdout } from "./session-outcomes.mjs";
+
+const AGENT_REPO_DIR = process.env.AGENT_DIR || join(new URL(".", import.meta.url).pathname, "../..");
+
+// ---------------------------------------------------------------------------
+// Tuning — every threshold is env-overridable so an operator can tighten or
+// loosen the promise without a code change.
+// ---------------------------------------------------------------------------
+
+const num = (v, d) => { const n = parseInt(v, 10); return Number.isFinite(n) ? n : d; };
+
+/** How long after opening we expect the ack to already be out. The sweep
+ *  compensates anything still un-acked past this — the fix for "the holding
+ *  message failed and nothing ever retried it". */
+export const ACK_GRACE_MS = num(process.env.ASSURANCE_ACK_GRACE_MS, 45_000);
+
+/** Work that outruns this gets an interim update rather than silence. Set just
+ *  under the measured p50 session (14.7 min) so the common case is covered,
+ *  and well above the quick path so a fast answer never triggers one. */
+export const PROGRESS_AFTER_MS = num(process.env.ASSURANCE_PROGRESS_AFTER_MS, 5 * 60_000);
+
+/** Gap between interim updates. */
+export const PROGRESS_EVERY_MS = num(process.env.ASSURANCE_PROGRESS_EVERY_MS, 10 * 60_000);
+
+/** Hard cap on interim updates per obligation. "Do not spam" is a requirement,
+ *  not a nicety: two updates over 45 minutes is attentive, six is noise. */
+export const PROGRESS_MAX = num(process.env.ASSURANCE_PROGRESS_MAX, 2);
+
+/** An obligation still open this long after admission has outlived every
+ *  session timeout in the dispatcher (45 min for opus/inbox). Past this the
+ *  work is gone, whatever the logs say, and the human is told. */
+export const STALE_AFTER_MS = num(process.env.ASSURANCE_STALE_AFTER_MS, 50 * 60_000);
+
+/** Automatic retries of the WORK (not of a send) before we stop and escalate.
+ *  Deliberately small: each attempt costs 15-45 minutes of a human's patience,
+ *  so an unbounded silent retry loop is itself a defect. */
+export const RETRY_MAX = num(process.env.ASSURANCE_RETRY_MAX, 1);
+
+/** Retained after discharge so an audit can see what was promised and when. */
+const CLOSED_RETENTION_MS = num(process.env.ASSURANCE_RETENTION_MS, 3 * 24 * 60 * 60 * 1000);
+
+/**
+ * How many times the sweep will re-attempt an acknowledgement that would not
+ * send, before it concludes the channel is unreachable rather than flaky.
+ *
+ * This bound is not a nicety. Without it the sweep's ack branch `continue`d on
+ * every tick, so an item on a service transport cannot reach — telegram,
+ * whatsapp, voice, calendar all route through the daemon and none of them
+ * through `deliver` — was retried once a minute forever: 1,440 impossible sends
+ * a day, an obligation that could never reach any other branch, and a human who
+ * was never told a thing. Five attempts spans four minutes of genuine flakiness;
+ * past that the honest answer is "I cannot reach this person" and the debt
+ * belongs in needs-attention where an operator will see it.
+ */
+export const ACK_MAX_ATTEMPTS = num(process.env.ASSURANCE_ACK_MAX_ATTEMPTS, 5);
+
+/**
+ * Minimum age before the sweep will call an obligation "interrupted" on the
+ * strength of a pid mismatch.
+ *
+ * A mismatch alone proves nothing. Two daemons sharing one AGENT_DIR — a manual
+ * run alongside the launchd one, which is exactly what an operator does while
+ * debugging — each see the other's fresh, healthy, actively-running obligations
+ * as foreign, and with no guard would tell those requesters "my session was
+ * interrupted" one second after it started, while it runs to completion behind
+ * the apology. Liveness is checked first (a pid we can signal is a daemon that
+ * is still working); this window is the backstop for a pid that has been
+ * recycled onto an unrelated process.
+ */
+export const INTERRUPT_GRACE_MS = num(process.env.ASSURANCE_INTERRUPT_GRACE_MS, 3 * 60_000);
+
+// ---------------------------------------------------------------------------
+// Ledger
+// ---------------------------------------------------------------------------
+
+function obligationDir() {
+  const dir = join(AGENT_REPO_DIR, "state", "obligations");
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/** Filesystem-safe form of an arbitrary item key. */
+export function sanitiseKey(key) {
+  return String(key || "unknown").replace(/[^a-zA-Z0-9._-]/g, "_").slice(0, 180);
+}
+
+/**
+ * The obligation key. Same precedence as the daemon's per-item lock and
+ * in-flight admission (raw_ref, then id) so all three name the same thing and a
+ * cross-reference is possible during an incident.
+ */
+export function obligationKey(item) {
+  if (!item) return null;
+  return item.raw_ref || item.id || item.message_id || null;
+}
+
+function pathFor(key) {
+  return join(obligationDir(), `${sanitiseKey(key)}.json`);
+}
+
+function writeRecord(rec) {
+  try {
+    const p = pathFor(rec.key);
+    const tmp = `${p}.tmp`;
+    writeFileSync(tmp, JSON.stringify(rec, null, 2));
+    renameSync(tmp, p); // atomic — a torn record is an unreadable debt
+    return true;
+  } catch (err) {
+    console.warn(`[assurance] could not persist obligation ${rec && rec.key}: ${err.message}`);
+    return false;
+  }
+}
+
+/** Read one obligation. Returns null when absent or corrupt. */
+export function readObligation(key) {
+  try { return JSON.parse(readFileSync(pathFor(key), "utf-8")); }
+  catch { return null; }
+}
+
+/** Every obligation on disk, open and closed. */
+export function listObligations() {
+  const out = [];
+  let files = [];
+  try { files = readdirSync(obligationDir()).filter((f) => f.endsWith(".json")); }
+  catch { return out; }
+  for (const f of files) {
+    try { out.push(JSON.parse(readFileSync(join(obligationDir(), f), "utf-8"))); }
+    catch { /* a corrupt record must not hide the rest */ }
+  }
+  return out;
+}
+
+/** Only what is still owed. */
+export function openObligations() {
+  return listObligations().filter((r) => r && r.state === "open");
+}
+
+/**
+ * The minimal snapshot of an item needed to SPEAK to its human later — from a
+ * sweep tick, possibly in a different process, long after the original item
+ * object is gone. Content is truncated: this file is a debt record, not a
+ * message archive.
+ */
+function itemSnapshot(item) {
+  return {
+    id: item.id || null,
+    raw_ref: item.raw_ref || null,
+    message_id: item.message_id || null,
+    service: item.service || null,
+    channel: item.channel || null,
+    channel_id: item.channel_id || null,
+    thread_id: item.thread_id || null,
+    sender: item.sender || null,
+    sender_email: item.sender_email || null,
+    subject: item.subject || null,
+    content: typeof item.content === "string" ? item.content.slice(0, 400) : null,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The judgement: does this ask need an acknowledgement at all?
+// ---------------------------------------------------------------------------
+
+/**
+ * "A simple ask should still get a direct answer without a pointless 'I'll look
+ * into it' first — getting that distinction right is the whole feature."
+ *
+ * The distinction is NOT a classifier enum. It is a fact about control flow:
+ * an ack is owed exactly when the answer will NOT arrive in this turn — i.e.
+ * when a session is being spawned. If the quick path answered, the human
+ * already has their answer and an ack would be noise; if a session is spawning,
+ * the human is about to wait minutes and an ack is the whole point.
+ *
+ * The previous gate asked the classifier instead (`respond || draft ||
+ * research`), which silently excluded `queue` — the action the HEURISTIC
+ * FALLBACK emits when the LLM classifier itself fails. So exactly when the
+ * system was degraded, a directed DM got a 15-minute session and no ack at all.
+ *
+ * @param {object} o
+ * @param {boolean} o.willSpawnSession  is a session being dispatched for this item
+ * @param {object}  [o.item]            the inbox item
+ * @param {string}  [o.source]          "inbox" | "backlog"
+ * @returns {{ack:boolean, reason:string}}
+ */
+export function shouldAcknowledge(o = {}) {
+  if (!o.willSpawnSession) return { ack: false, reason: "answered-in-turn" };
+  if (o.source && o.source !== "inbox") return { ack: false, reason: "no-waiting-human" };
+  const item = o.item || {};
+  if (!item.service) return { ack: false, reason: "no-service" };
+  if (!replyTargetOf(item)) return { ack: false, reason: "no-reply-target" };
+  // A service this agent has no transport for. Saying "I'm on it" into a
+  // channel we cannot write to is not an acknowledgement, it is an exception
+  // with a nicer name — and the sweep would then retry that impossible send
+  // once a minute forever. The DEBT is still opened (see openAndAcknowledge):
+  // an ask we cannot answer in public is exactly the one an operator must be
+  // told about, and that is what needs-attention is for.
+  if (!canDeliverTo(item)) return { ack: false, reason: "no-transport" };
+  // Nobody is waiting on work the agent gave itself.
+  if (item.self_originated === true) return { ack: false, reason: "self-originated" };
+  return { ack: true, reason: "session-dispatched" };
+}
+
+// ---------------------------------------------------------------------------
+// Composition — deterministic strings. No model, therefore no timeout.
+// ---------------------------------------------------------------------------
+
+/** Deterministic variant pick, so repeated acks in a thread are not identical
+ *  boilerplate but are still perfectly reproducible in a test. */
+function variant(seed, n) {
+  let h = 0;
+  const s = String(seed || "");
+  for (let i = 0; i < s.length; i++) h = (h * 31 + s.charCodeAt(i)) >>> 0;
+  return h % n;
+}
+
+/** Trim the classifier's summary into a clause that reads naturally mid-sentence. */
+function topicClause(classResult, item) {
+  const raw = (classResult && classResult.summary) || (item && item.subject) || "";
+  const t = String(raw).trim().replace(/\s+/g, " ").replace(/[.!?]+$/, "");
+  if (!t || t.length > 120) return null;
+  return t.charAt(0).toLowerCase() + t.slice(1);
+}
+
+/** Rough, honest expectation. Derived from the measured distribution of real
+ *  sessions, not invented: sonnet work clusters near a minute, opus work near
+ *  fifteen. Phrased as a range because it IS a range. */
+export function expectedWindow(classResult) {
+  const model = classResult && classResult.model;
+  const priority = classResult && classResult.priority;
+  if (model === "opus" || priority === "critical") return "usually within 10-20 minutes";
+  return "usually within a few minutes";
+}
+
+/**
+ * The acknowledgement. Two or three sentences, warm, specific where it can be,
+ * and — critically — it commits to coming back "either way". That clause is a
+ * promise the rest of this module now actually keeps: failure notices, interim
+ * updates and the stale sweep all exist so it is never a lie.
+ */
+export function composeAck(item, classResult = {}) {
+  const topic = topicClause(classResult, item);
+  const v = variant(obligationKey(item) || (item && item.sender), 3);
+  const openers = [
+    "No problem — let me look into this and sort it out.",
+    "Got it — I'm on this now.",
+    "Understood — let me dig into this.",
+  ];
+  const parts = [openers[v]];
+  if (topic) parts.push(`Picking up: ${topic}.`);
+  parts.push(`It needs a bit of work, so I'll come back to you here with an answer — ${expectedWindow(classResult)}, and I'll message you either way.`);
+  return parts.join(" ");
+}
+
+/**
+ * The topic, set off in parentheses.
+ *
+ * It is NOT interpolated as the object of a preposition, because the classifier's
+ * summary is as often a verb phrase ("fix the issues and push them") as a noun
+ * phrase ("July spend reconciliation") — and "Still working on fix the issues"
+ * is the kind of sentence that tells a reader they are talking to a machine.
+ * Parentheses read correctly for both.
+ */
+function topicAside(rec) {
+  return rec && rec.summary ? ` (${rec.summary})` : "";
+}
+
+/** An interim update. Says how long it has been and that the work is live. */
+export function composeProgress(rec, o = {}) {
+  const now = Number.isFinite(o.now) ? o.now : Date.now();
+  const mins = Math.max(1, Math.round((now - (rec.openedAt || now)) / 60_000));
+  const topic = topicAside(rec);
+  if ((rec.progressSent || 0) === 0) {
+    return `Still working on this${topic} — ${mins} minutes in, and it's taking longer than I expected. Nothing's stuck; I'll come back as soon as I have something worth sending.`;
+  }
+  return `Quick check-in: still on this${topic}, ${mins} minutes in. I haven't forgotten it — I'll follow up the moment it's done, or tell you if I can't finish it.`;
+}
+
+/**
+ * The failure notice. Says WHAT HAPPENED and WHAT HAPPENS NEXT, in that order,
+ * because those are the two things the human is missing when a session dies.
+ * Never blames the human, never hides behind "an error occurred", and never
+ * ends without a next step.
+ */
+export function composeFailure(rec, o = {}) {
+  const f = o.failure || {};
+  const topic = topicAside(rec);
+  const cause = f.human || "the working session ended unexpectedly";
+  if (o.willRetry) {
+    return `I hit a problem with this${topic} — ${cause}. I'm retrying it now (attempt ${(rec.attempts || 1) + 1} of ${RETRY_MAX + 1}); if it fails again I'll come straight back to you rather than leave you waiting.`;
+  }
+  return `I couldn't get this done${topic} — ${cause}. I've stopped retrying so I'm not silently burning time on it, and I've flagged it so it isn't lost. Do you want me to try a narrower version of this, hand it to someone else, or leave it with you?`;
+}
+
+/**
+ * The one the old code could not even conceive of: the session exited ZERO and
+ * said nothing. Observed live — a 241-second, $2.36 session whose own result
+ * text ended "Nothing was sent.", marked processed forever and emitted as
+ * `sent`. This message is what the human gets instead of that silence.
+ */
+export function composeSilentSuccess(rec, o = {}) {
+  const topic = topicAside(rec);
+  const tail = (o.finalText || "").trim();
+  const head = `I finished working on this${topic} but didn't get a reply out to you — that's my fault, not yours.`;
+  if (tail) {
+    const excerpt = tail.length > 900 ? `${tail.slice(0, 900).trimEnd()}…` : tail;
+    return `${head} Here's where I got to:\n\n${excerpt}\n\nIf that doesn't answer it, say so and I'll take another run at it.`;
+  }
+  return `${head} I don't have a clean result to show you, so I'd rather say that than pretend otherwise. Want me to run it again?`;
+}
+
+/** A session interrupted by the daemon itself dying/restarting. */
+export function composeInterrupted(rec) {
+  const topic = topicAside(rec);
+  return `Heads up — my working session on this${topic} was interrupted before it finished (my end restarted). I've put it back in the queue and I'm picking it up again now; I'll come back to you with the answer.`;
+}
+
+// ---------------------------------------------------------------------------
+// Failure classification — what happened, and is it worth trying again?
+// ---------------------------------------------------------------------------
+
+/**
+ * Map a terminal session state onto a plain-English cause and a retry verdict.
+ *
+ * The distinction matters because the two wrong answers are both bad: retrying
+ * a permanent fault burns another 45 minutes of the human's patience for the
+ * same outcome, and refusing to retry a transient one throws away work that
+ * would have succeeded.
+ *
+ * @param {object} o
+ * @param {number|null} [o.code]   process exit code
+ * @param {string} [o.error]       error text (spawn error, stderr tail)
+ * @param {string} [o.stage]
+ * @returns {{transient:boolean, label:string, human:string}}
+ */
+export function classifyFailure(o = {}) {
+  const err = String(o.error || "");
+  const code = o.code;
+
+  if (/rate.?limit|429|overloaded|529/i.test(err)) {
+    return { transient: true, label: "rate_limited", human: "the model API was rate-limiting me" };
+  }
+  if (/ENOENT|EACCES|command not found|spawn error/i.test(err)) {
+    // The binary or its permissions are wrong. Another attempt changes nothing.
+    return { transient: false, label: "spawn_failed", human: "I couldn't start my working session at all (a setup problem on my machine)" };
+  }
+  if (/budget|spend cap|daily budget|essential-only/i.test(err)) {
+    return { transient: false, label: "budget_refused", human: "I've hit my spend cap for today, so I can't run the work that would answer this" };
+  }
+  if (/out of memory|ENOMEM|low free memory/i.test(err)) {
+    return { transient: true, label: "resource_starved", human: "my machine ran out of memory partway through" };
+  }
+  if (code === 143 || /SIGTERM|timed out/i.test(err)) {
+    return { transient: true, label: "timeout", human: "the work ran past its time limit and got cut off" };
+  }
+  if (code === 137 || /SIGKILL/i.test(err)) {
+    return { transient: true, label: "killed", human: "the working session was killed before it finished" };
+  }
+  if (code === 0) {
+    return { transient: false, label: "silent_success", human: "the work finished but produced nothing I could send you" };
+  }
+  return { transient: true, label: `exit_${code == null ? "unknown" : code}`, human: "the working session ended with an error" };
+}
+
+// ---------------------------------------------------------------------------
+// Lifecycle
+// ---------------------------------------------------------------------------
+
+/**
+ * Open a debt and acknowledge it — in that order.
+ *
+ * The record is written BEFORE the send, so a crash between the two leaves an
+ * un-acked obligation the sweep will notice and compensate. Written after, a
+ * crash would leave a human waiting on a debt that nothing knows exists.
+ *
+ * @param {object} a
+ * @param {object} a.item
+ * @param {object} [a.classResult]
+ * @param {string} [a.service]
+ * @param {string} [a.traceId]
+ * @param {number} [a.now]
+ * @param {object} [a.deps] {ackSender} — `(item, classResult) => {sent, holdingText,
+ *        error}`, i.e. exactly responder.sendHoldingMessage's contract, so the
+ *        daemon's existing injected-fake seam keeps working unchanged. Defaults
+ *        to composing the text here and handing it to transport.
+ * @param {boolean} [a.ack=true] open the debt but say nothing. Used when there
+ *        is no transport to the requester: the debt is REAL — a session is
+ *        about to run and may die — but the compensating action is an operator
+ *        escalation, not a message into a channel that does not exist. Opening
+ *        it anyway is what turned "one failed session silently deletes the ask"
+ *        into a bounded retry with a durable trace.
+ * @returns {Promise<{key:string|null, opened:boolean, acked:boolean, ackText:string|null, error?:string}>}
+ */
+export async function openAndAcknowledge(a = {}) {
+  const item = a.item || {};
+  const key = obligationKey(item);
+  if (!key) return { key: null, opened: false, acked: false, ackText: null, error: "item has no stable key" };
+  const now = Number.isFinite(a.now) ? a.now : Date.now();
+  const classResult = a.classResult || {};
+  const wantAck = a.ack !== false;
+
+  const existing = readObligation(key);
+  if (existing && existing.state === "open" && existing.acknowledged) {
+    // Already acknowledged (a re-delivery of the same item). Acknowledge ONCE.
+    return { key, opened: false, acked: true, ackText: null, reason: "already-acknowledged" };
+  }
+
+  const rec = existing && existing.state === "open" ? existing : {
+    key,
+    itemId: item.id || null,
+    raw_ref: item.raw_ref || null,
+    service: a.service || item.service || null,
+    channel: replyTargetOf(item),
+    sender: item.sender || null,
+    summary: topicClause(classResult, item),
+    priority: classResult.priority || null,
+    model: classResult.model || null,
+    openedAt: now,
+    // The clock the STALE check runs against. It is distinct from openedAt
+    // because a retry restarts the work: measuring "has this outrun every
+    // session timeout" from the original arrival declares a running retry dead
+    // and tells the human the opposite of what it was told five minutes ago.
+    lastAttemptAt: now,
+    acknowledged: false,
+    ackAt: null,
+    ackAttempts: 0,
+    deliverable: canDeliverTo(item),
+    progressSent: 0,
+    lastProgressAt: null,
+    attempts: 0,
+    lastError: null,
+    sessionId: null,
+    traceId: a.traceId || item.trace_id || null,
+    daemonPid: process.pid,
+    state: "open",
+    item: itemSnapshot(item),
+  };
+  rec.daemonPid = process.pid;
+  if (rec.deliverable === undefined) rec.deliverable = canDeliverTo(item);
+  writeRecord(rec);
+
+  if (!wantAck || !rec.deliverable) {
+    // The debt is on the books and the sweep will not try to speak into a
+    // channel that does not exist (see sweepObligations branch (b)). What it
+    // WILL do is escalate if the work then fails — which is the whole point of
+    // opening a record we cannot acknowledge.
+    return { key, opened: true, acked: false, ackText: null, reason: rec.deliverable ? "ack-suppressed" : "no-transport" };
+  }
+
+  const ackSender = (a.deps && a.deps.ackSender)
+    || (async (i, cr) => {
+      const t = composeAck(i, cr);
+      const r = await deliverWithRetry(i, t, { kind: "ack", ...(a.deps && a.deps.sleep ? { sleep: a.deps.sleep } : {}) });
+      return { sent: r.sent, holdingText: t, error: r.error };
+    });
+  const res = await ackSender(item, classResult);
+  const text = (res && res.holdingText) || composeAck(item, classResult);
+
+  if (res && res.sent) {
+    rec.acknowledged = true;
+    rec.ackAt = Number.isFinite(a.now) ? a.now : Date.now();
+    writeRecord(rec);
+    return { key, opened: true, acked: true, ackText: text };
+  }
+  // NOT fatal, and NOT forgotten: the debt stays open and un-acked, and the
+  // sweep retries it within ACK_GRACE_MS. This is precisely the case the old
+  // code logged and dropped.
+  rec.lastError = (res && res.error) || "ack send failed";
+  rec.ackAttempts = (rec.ackAttempts || 0) + 1;
+  writeRecord(rec);
+  console.warn(`[assurance] ack not delivered for ${key} (${rec.lastError}) — obligation left open for sweep`);
+  return { key, opened: true, acked: false, ackText: text, error: rec.lastError };
+}
+
+/**
+ * Attach the dispatched session id, so an incident can join debt ↔ session log.
+ *
+ * Also restarts the staleness clock: this is a fresh attempt at the work, and
+ * the question the STALE branch asks — "has this outrun every session timeout
+ * there is?" — is about the RUNNING session, not about how long ago the human
+ * first asked.
+ */
+export function noteSession(key, sessionId, o = {}) {
+  const rec = readObligation(key);
+  if (!rec) return false;
+  rec.sessionId = sessionId || null;
+  rec.attempts = (rec.attempts || 0) + 1;
+  rec.lastAttemptAt = Number.isFinite(o.now) ? o.now : Date.now();
+  rec.daemonPid = process.pid;
+  return writeRecord(rec);
+}
+
+/**
+ * Is the process that opened this obligation still running?
+ *
+ * `kill(pid, 0)` signals nothing and throws ESRCH only when no such process
+ * exists, so it is the cheapest honest liveness test available. EPERM means the
+ * pid exists but belongs to another user — still alive, still not ours to
+ * declare dead. Anything unexpected is treated as ALIVE, because the cost of a
+ * false "dead" is telling a human their work was interrupted while it runs.
+ */
+export function isPidAlive(pid) {
+  if (!Number.isFinite(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; }
+  catch (err) { return err && err.code === "EPERM"; }
+}
+
+/**
+ * How many OPEN debts share a room with this one.
+ *
+ * The receipt ledger's fallback rung — "an unattributed message reached this
+ * room, so assume it was the answer" — is only safe when the room holds exactly
+ * one unanswered ask. With two, the message answered one of them and guessing
+ * which is how an unanswered ask gets closed as answered.
+ */
+function siblingsInRoom(rec, open) {
+  const ch = String(rec.channel || "").trim().toLowerCase();
+  if (!ch) return 1;
+  return open.filter((r) => String(r.channel || "").trim().toLowerCase() === ch).length;
+}
+
+/**
+ * Ask "was this debt's human actually spoken to?", through whichever seam the
+ * caller injected.
+ *
+ * The real implementation is `spokeFor`, which returns `{heard, basis}` — the
+ * basis matters, because "a receipt carrying this obligation's key" and "an
+ * unattributed message in a quiet room" are different strengths of evidence and
+ * an incident needs to know which one closed a debt. A test that only wants to
+ * pin the answer may inject a plain boolean; normalising here keeps that seam
+ * honest without every caller having to fabricate a basis.
+ */
+function askHeard(impl, query) {
+  const r = impl(query);
+  if (typeof r === "boolean") return { heard: r, basis: "injected" };
+  return r && typeof r === "object" ? r : { heard: false, basis: "unknown" };
+}
+
+/**
+ * Discharge the debt: the human has their answer.
+ * @param {string} key
+ * @param {object} [o] {outcome, now}
+ */
+export function closeObligation(key, o = {}) {
+  const rec = readObligation(key);
+  if (!rec) return false;
+  rec.state = o.outcome || "answered";
+  rec.closedAt = Number.isFinite(o.now) ? o.now : Date.now();
+  if (o.note) rec.closeNote = o.note;
+  return writeRecord(rec);
+}
+
+/**
+ * A session ended. Decide what the human hears, and say it.
+ *
+ * This is the single place that turns every terminal session state into a
+ * message. The four cases it covers are the four ways the old code went silent:
+ *
+ *   ok:true  + a receipt exists  → the session spoke. Close the debt quietly;
+ *                                  do NOT add a message (that would be spam).
+ *   ok:true  + no receipt        → silent success. Say so, with the result text.
+ *   ok:false + transient + tries → say what broke and that a retry is running.
+ *   ok:false + terminal          → say it failed, stop, escalate durably.
+ *
+ * @param {object} a
+ * @param {string} a.key
+ * @param {boolean} a.ok
+ * @param {number|null} [a.code]
+ * @param {string} [a.stdout]  the session's raw stdout (for the result text)
+ * @param {string} [a.error]
+ * @param {number} [a.now]
+ * @param {object} [a.deps] {deliverImpl, spokeSinceImpl}
+ * @returns {Promise<{spoke:boolean, text:string|null, verdict:string, willRetry:boolean}>}
+ */
+export async function settleSession(a = {}) {
+  const rec = readObligation(a.key);
+  if (!rec) return { spoke: false, text: null, verdict: "no-obligation", willRetry: false };
+  const now = Number.isFinite(a.now) ? a.now : Date.now();
+  if (a.sessionId && rec.sessionId !== a.sessionId) { rec.sessionId = a.sessionId; writeRecord(rec); }
+  const item = rec.item || {};
+  const send = (a.deps && a.deps.deliverImpl) || deliver;
+
+  // Did THIS session's work reach THIS person? Not "did anything land in that
+  // room" — a room is shared, and a channel-only check let one session's answer
+  // discharge every other debt open in the same DM, closing unanswered asks as
+  // answered with nobody told. `spokeFor` resolves the receipt against the
+  // obligation's own key and session id; only an unambiguous room falls back.
+  // Our own courtesy messages are excluded throughout: an ack is not an answer.
+  const heardBy = (a.deps && (a.deps.spokeForImpl || a.deps.spokeSinceImpl)) || spokeFor;
+  const verdictHeard = askHeard(heardBy, {
+    obligation: rec,
+    now,
+    siblingOpenCount: siblingsInRoom(rec, openObligations()),
+    excludeKinds: ["ack", "progress", "failure"],
+    agentRoot: AGENT_REPO_DIR,
+    // Legacy shape, for a seam injected as the older channel-scoped predicate.
+    channel: rec.channel,
+    sinceMs: rec.openedAt || now - 3_600_000,
+  });
+  const heard = !!(verdictHeard && verdictHeard.heard);
+
+  if (a.ok && heard) {
+    closeObligation(a.key, { outcome: "answered", now, note: `receipt:${verdictHeard.basis}` });
+    return { spoke: false, text: null, verdict: "answered-by-session", willRetry: false, basis: verdictHeard.basis };
+  }
+
+  if (a.ok && !heard) {
+    const finalText = safeResultText(a.stdout);
+    const text = composeSilentSuccess(rec, { finalText });
+    const res = await send(item, text, { kind: "reply", idempotencySuffix: `rescue-${rec.attempts || 0}` });
+    closeObligation(a.key, {
+      outcome: res && res.sent ? "answered" : "undeliverable",
+      now,
+      note: res && res.sent ? "session exited 0 without speaking; daemon delivered its result text" : `silent-success fallback undeliverable: ${res && res.error}`,
+    });
+    return { spoke: !!(res && res.sent), text, verdict: "silent-success", willRetry: false };
+  }
+
+  // ── failure ────────────────────────────────────────────────────────────
+  const failure = classifyFailure({ code: a.code, error: a.error });
+  const attempts = rec.attempts || 1;
+  const willRetry = failure.transient && attempts <= RETRY_MAX;
+
+  rec.lastError = failure.label;
+  rec.lastFailureAt = now;
+  writeRecord(rec);
+
+  const text = composeFailure(rec, { failure, willRetry });
+  const res = await send(item, text, { kind: "failure", idempotencySuffix: `failure-${attempts}` });
+
+  if (willRetry) {
+    // The debt stays OPEN and the inbox item stays un-`.processed`, so the next
+    // poll re-delivers it. The difference from before is that the human now
+    // knows a retry is happening instead of watching a typing dot stop.
+    //
+    // Restart the staleness clock HERE, not only at the next noteSession. The
+    // retry is announced at this instant ("I'm retrying it now"), and until the
+    // next poll picks the item up there is a window in which the sweep would
+    // otherwise measure age from the original arrival, cross STALE_AFTER_MS and
+    // tell the same human "I've stopped retrying" — a flat contradiction of a
+    // message they received minutes earlier, while the retry runs.
+    rec.lastAttemptAt = now;
+    writeRecord(rec);
+    return { spoke: !!(res && res.sent), text, verdict: `retrying:${failure.label}`, willRetry: true };
+  }
+
+  escalate(rec, { failure, now, told: !!(res && res.sent) });
+  closeObligation(a.key, { outcome: "failed", now, note: failure.label });
+  return { spoke: !!(res && res.sent), text, verdict: `failed:${failure.label}`, willRetry: false };
+}
+
+function safeResultText(stdout) {
+  try { return resultTextFromStdout(stdout || "") || ""; }
+  catch { return ""; }
+}
+
+/**
+ * Durable "this was not delivered and needs a person" record.
+ *
+ * Honest scope note: this does NOT raise an hq `Escalation` row. The escalation
+ * effect in lib/execution/effects.mjs writes a row and speaks to nobody
+ * (journalled `spoke:false` on all 9 observed escalations), which is the same
+ * silence in a different table. What a waiting human actually needs is to be
+ * TOLD — that already happened above — plus a trace an operator can sweep. This
+ * file is that trace.
+ */
+export function escalate(rec, o = {}) {
+  try {
+    const dir = join(obligationDir(), "needs-attention");
+    mkdirSync(dir, { recursive: true });
+    const p = join(dir, `${sanitiseKey(rec.key)}.json`);
+    writeFileSync(p, JSON.stringify({
+      key: rec.key,
+      sender: rec.sender,
+      service: rec.service,
+      channel: rec.channel,
+      summary: rec.summary,
+      openedAt: rec.openedAt ? new Date(rec.openedAt).toISOString() : null,
+      failedAt: new Date(Number.isFinite(o.now) ? o.now : Date.now()).toISOString(),
+      cause: o.failure ? o.failure.label : (rec.lastError || "unknown"),
+      requesterWasTold: !!o.told,
+      attempts: rec.attempts || 0,
+      sessionId: rec.sessionId || null,
+      traceId: rec.traceId || null,
+      itemPreview: rec.item ? rec.item.content : null,
+    }, null, 2));
+    console.error(`[assurance] ESCALATED ${rec.key} — ${o.failure ? o.failure.label : rec.lastError}; requester told: ${!!o.told}`);
+    return true;
+  } catch (err) {
+    console.error(`[assurance] could not write escalation for ${rec && rec.key}: ${err.message}`);
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// The sweep — the safety net under every path above
+// ---------------------------------------------------------------------------
+
+/**
+ * Walk the open debts and speak to whichever are overdue.
+ *
+ * This is what makes the guarantee hold across process death, unhandled
+ * rejections, a dispatcher that never calls back, and an ack whose send failed.
+ * It is intentionally the only mechanism with no in-memory state: everything it
+ * needs is on disk, so the first tick after a restart is as effective as the
+ * hundredth tick of a healthy process.
+ *
+ * @param {object} [a]
+ * @param {number} [a.now]
+ * @param {object} [a.deps] {deliverImpl, spokeSinceImpl}
+ * @returns {Promise<{swept:number, acked:number, progressed:number, staled:number, closed:number}>}
+ */
+export async function sweepObligations(a = {}) {
+  const now = Number.isFinite(a.now) ? a.now : Date.now();
+  const send = (a.deps && a.deps.deliverImpl) || deliver;
+  const heardBy = (a.deps && (a.deps.spokeForImpl || a.deps.spokeSinceImpl)) || spokeFor;
+  const alive = (a.deps && a.deps.isPidAliveImpl) || isPidAlive;
+  const stats = { swept: 0, acked: 0, progressed: 0, staled: 0, closed: 0, interrupted: 0, unreachable: 0 };
+
+  const open = openObligations();
+  for (const rec of open) {
+    stats.swept++;
+    // Two clocks, deliberately. `age` is how long the HUMAN has been waiting and
+    // is what progress messages talk about. `workAge` is how long the current
+    // attempt has been running and is what the stale check judges — a retry
+    // resets it, because declaring a running retry dead is worse than waiting.
+    const age = now - (rec.openedAt || now);
+    const workAge = now - (rec.lastAttemptAt || rec.openedAt || now);
+    const item = rec.item || {};
+
+    // (a) The session already answered — discharge without saying anything.
+    // Attributed, not room-wide: see spokeFor. An unattributed message in a room
+    // holding two open debts closes neither.
+    const v = askHeard(heardBy, {
+      obligation: rec,
+      now,
+      siblingOpenCount: siblingsInRoom(rec, open),
+      excludeKinds: ["ack", "progress", "failure"],
+      agentRoot: AGENT_REPO_DIR,
+      channel: rec.channel,
+      sinceMs: rec.openedAt || now,
+    });
+    if (v && v.heard) {
+      closeObligation(rec.key, { outcome: "answered", now, note: `receipt:${v.basis}` });
+      stats.closed++;
+      continue;
+    }
+
+    // (b) No transport to this person at all. Every branch below this one ends
+    // in a send, so without this the obligation is unserviceable AND immortal:
+    // the ack branch's `continue` meant the stale branch was never reached, and
+    // an impossible send was retried every 60 seconds for as long as the daemon
+    // lived. Escalate ONCE, close the debt, and let an operator see it.
+    if (rec.deliverable === false || (rec.ackAttempts || 0) >= ACK_MAX_ATTEMPTS) {
+      const failure = {
+        transient: false,
+        label: rec.deliverable === false ? "no_transport" : "ack_undeliverable",
+        human: "I have no way to reply to you on this channel",
+      };
+      escalate(rec, { failure, now, told: false });
+      closeObligation(rec.key, { outcome: "undeliverable", now, note: failure.label });
+      stats.unreachable++;
+      continue;
+    }
+
+    // (c) Past every session timeout there is. The work is gone whatever the
+    // logs claim; stop pretending and tell them.
+    //
+    // This is checked BEFORE the ack retry, not after. Ordered the other way,
+    // an obligation whose ack keeps failing never advances past the ack branch's
+    // `continue`, so the promise that the sweep is a backstop is void for
+    // exactly the obligations that most need one.
+    if (workAge >= STALE_AFTER_MS) {
+      const failure = { transient: false, label: "no_outcome", human: "the work never came back with a result and has now outrun its time limit" };
+      const text = composeFailure(rec, { failure, willRetry: false });
+      const res = await send(item, text, { kind: "failure", idempotencySuffix: "failure-stale" });
+      escalate(rec, { failure, now, told: !!(res && res.sent) });
+      closeObligation(rec.key, { outcome: "failed", now, note: "stale-no-outcome" });
+      stats.staled++;
+      continue;
+    }
+
+    // (d) An acknowledgement that never made it out. Compensate it — this is
+    // the 66%-of-the-time case that used to be logged and dropped. Bounded by
+    // ACK_MAX_ATTEMPTS above, so a channel that will never accept a message
+    // becomes an escalation rather than a permanent retry loop.
+    if (!rec.acknowledged && age >= ACK_GRACE_MS) {
+      const text = composeAck(item, { summary: rec.summary, model: rec.model, priority: rec.priority });
+      const res = await send(item, text, { kind: "ack", idempotencySuffix: "ack" });
+      if (res && res.sent) {
+        rec.acknowledged = true;
+        rec.ackAt = now;
+        writeRecord(rec);
+        stats.acked++;
+      } else {
+        // A permanent refusal (no transport, policy block) is worth five ticks
+        // of nobody's time; count it out at once.
+        rec.ackAttempts = (rec.ackAttempts || 0) + (res && res.permanent ? ACK_MAX_ATTEMPTS : 1);
+        rec.lastError = (res && res.error) || "ack send failed";
+        writeRecord(rec);
+      }
+      continue; // one message per obligation per tick, always
+    }
+
+    // (e) Interrupted: the debt was opened by a daemon that is no longer this
+    // process, and nothing has closed it. The work died with that process.
+    //
+    // A pid MISMATCH alone does not establish that. Two daemons on one AGENT_DIR
+    // — a manual run next to the launchd one, which is what an operator does
+    // while debugging — each see the other's healthy, actively-running debts as
+    // foreign. Unguarded, both tell those requesters "my session was
+    // interrupted" seconds after the ask arrived, while the work runs fine
+    // behind the apology. So: the owning process must be provably GONE, and the
+    // debt must have sat still long enough that a live handover would have shown
+    // up by now.
+    if (
+      rec.daemonPid && rec.daemonPid !== process.pid && !rec.interruptedNotifiedAt
+      && workAge >= INTERRUPT_GRACE_MS && !alive(rec.daemonPid)
+    ) {
+      const text = composeInterrupted(rec);
+      const res = await send(item, text, { kind: "progress", idempotencySuffix: `interrupted-${rec.attempts || 0}` });
+      rec.interruptedNotifiedAt = now;
+      rec.daemonPid = process.pid;
+      writeRecord(rec);
+      if (res && res.sent) stats.interrupted++;
+      continue;
+    }
+
+    // (f) Long work gets progress, not silence — capped.
+    const sinceUpdate = now - (rec.lastProgressAt || rec.ackAt || rec.openedAt || now);
+    const due = (rec.progressSent || 0) === 0
+      ? age >= PROGRESS_AFTER_MS
+      : sinceUpdate >= PROGRESS_EVERY_MS;
+    if (due && (rec.progressSent || 0) < PROGRESS_MAX) {
+      const text = composeProgress(rec, { now });
+      const res = await send(item, text, { kind: "progress", idempotencySuffix: `progress-${(rec.progressSent || 0) + 1}` });
+      if (res && res.sent) {
+        rec.progressSent = (rec.progressSent || 0) + 1;
+        rec.lastProgressAt = now;
+        writeRecord(rec);
+        stats.progressed++;
+      }
+    }
+  }
+
+  pruneObligations({ now });
+  return stats;
+}
+
+/** Delete discharged debts past retention. Open debts are NEVER pruned — an
+ *  obligation may only leave the ledger by being discharged. */
+export function pruneObligations(o = {}) {
+  const now = Number.isFinite(o.now) ? o.now : Date.now();
+  let removed = 0;
+  for (const rec of listObligations()) {
+    if (!rec || rec.state === "open") continue;
+    if (now - (rec.closedAt || 0) < CLOSED_RETENTION_MS) continue;
+    try { unlinkSync(pathFor(rec.key)); removed++; } catch { /* best-effort */ }
+  }
+  return removed;
+}
+
+/** Test seam: wipe the ledger. */
+export function _resetObligations() {
+  for (const rec of listObligations()) {
+    try { unlinkSync(pathFor(rec.key)); } catch { /* */ }
+  }
+  try {
+    const dir = join(obligationDir(), "needs-attention");
+    for (const f of readdirSync(dir)) { try { unlinkSync(join(dir, f)); } catch { /* */ } }
+  } catch { /* */ }
+}
+
+export default {
+  shouldAcknowledge,
+  composeAck,
+  composeProgress,
+  composeFailure,
+  composeSilentSuccess,
+  composeInterrupted,
+  classifyFailure,
+  openAndAcknowledge,
+  noteSession,
+  settleSession,
+  sweepObligations,
+  closeObligation,
+  openObligations,
+  obligationKey,
+  isPidAlive,
+};