@cohortapp/agent-sdk 2.8.0 → 2.9.0

package/lib/telemetry/collect.mjs

@@ -241,6 +241,47 @@ function humanActivity(intent, taskClass) {
  *   uptimeDays?:number, spend24h?:number, device?:string, ram?:string, cores?:number
  * }>}
  */
+/**
+ * Percentage of memory genuinely unavailable.
+ *
+ * On macOS this is `100 - (memory_pressure's System-wide memory free
+ * percentage)`. That is the same source `scripts/watchdog/memory-watchdog.sh`
+ * thresholds on, so the number in the Fleet view and the number the watchdog
+ * acts on can no longer disagree — they used to disagree by ~66 points, which
+ * is how a healthy machine came to show a standing CRITICAL.
+ *
+ * Anywhere else (or if memory_pressure yields nothing) falls back to
+ * `1 - free/total`, which on Linux does mean what it says.
+ *
+ * @param {object} o    collector options; `o.execFile` is the test seam
+ * @param {object} osImpl
+ * @returns {Promise<number>}
+ */
+async function collectMemUsedPct(o, osImpl) {
+  const fallback = () => {
+    try {
+      const total = Number(osImpl.totalmem());
+      const free = Number(osImpl.freemem());
+      if (Number.isFinite(total) && total > 0 && Number.isFinite(free)) {
+        return pct((1 - free / total) * 100);
+      }
+    } catch { /* fall through */ }
+    return 0;
+  };
+
+  const platform = o.platform || process.platform;
+  if (platform !== "darwin" && !o.execFile) return fallback();
+
+  const execFileImpl = o.execFile || execFile;
+  const out = await execFileSafe(execFileImpl, "/usr/bin/memory_pressure", [], 4000);
+  const m = /System-wide memory free percentage:\s*([\d.]+)%/.exec(out || "");
+  if (!m) return fallback();
+
+  const freePct = Number(m[1]);
+  if (!Number.isFinite(freePct) || freePct < 0 || freePct > 100) return fallback();
+  return pct(100 - freePct);
+}
+
 export async function collectMachine(o = {}) {
   const osImpl = o.os || os;
   const machine = { loadavg: [0, 0, 0], memUsedPct: 0 };
@@ -253,14 +294,21 @@ export async function collectMachine(o = {}) {
     }
   } catch { /* keep [0,0,0] */ }
 
-  // memUsedPct = 1 - free/total
-  try {
-    const total = Number(osImpl.totalmem());
-    const free = Number(osImpl.freemem());
-    if (Number.isFinite(total) && total > 0 && Number.isFinite(free)) {
-      machine.memUsedPct = pct((1 - free / total) * 100);
-    }
-  } catch { /* keep 0 */ }
+  // memUsedPct — how much memory is genuinely UNAVAILABLE, not how much is
+  // merely occupied.
+  //
+  // This used to be `1 - os.freemem()/os.totalmem()`, which is not a pressure
+  // measure on macOS. os.freemem() counts only entirely-free pages, and macOS
+  // deliberately keeps almost all RAM occupied with file cache, purgeable and
+  // compressed pages that are reclaimable on demand. Measured on a healthy
+  // idle Mac mini M4 Pro at the same instant: os.freemem() → 99.2% "used",
+  // `memory_pressure` → 68% free. The old number sat permanently near 100 and
+  // fired CRITICAL alerts on machines with nothing wrong with them, while the
+  // memory watchdog — which reads memory_pressure — correctly stayed quiet.
+  //
+  // Prefer macOS's own answer; fall back to the free/total ratio only where
+  // memory_pressure does not exist (Linux, where the figure means what it says).
+  machine.memUsedPct = await collectMemUsedPct(o, osImpl);
 
   // cpuPct — coarse instantaneous estimate from loadavg/cpus when powermetrics
   // is unavailable. powermetrics (if it yields) overrides below.

package/lib/telemetry/collect.test.mjs

@@ -173,7 +173,11 @@ test("detectClaudeAuth: scans recent log files under agentRoot", () => {
 });
 
 test("collectMachine: derives memUsedPct + loadavg without powermetrics/df", async () => {
-  const m = await collectMachine({ os: fakeOs({ totalmem: 10e9, freemem: 2e9, loadavg: [4, 2, 1], cpus: 4 }), powermetrics: false, disk: false });
+  // memUsedPct now prefers macOS's memory_pressure, so "no external tools" has
+  // to include that one too — otherwise this test reads the REAL machine and
+  // asserts against the fake os, which is how it started failing.
+  const noTools = (cmd, args, opts, cb) => { cb(new Error("ENOENT")); return { on() {} }; };
+  const m = await collectMachine({ os: fakeOs({ totalmem: 10e9, freemem: 2e9, loadavg: [4, 2, 1], cpus: 4 }), execFile: noTools, powermetrics: false, disk: false });
   assert.equal(m.memUsedPct, 80);
   assert.deepEqual(m.loadavg, [4, 2, 1]);
   assert.equal(m.cpuPct, 100); // load 4 / 4 cpus = 100%
@@ -662,3 +666,75 @@ test("collectStatus ships the FULL machine vocabulary the Fleet row reads", asyn
     rmSync(root, { recursive: true, force: true });
   }
 });
+
+// ---------------------------------------------------------------------------
+// memUsedPct — pressure, not occupancy
+//
+// This was `1 - os.freemem()/os.totalmem()`, which is not a pressure measure on
+// macOS: os.freemem() counts only entirely-free pages, and macOS keeps nearly
+// all RAM occupied with file cache, purgeable and compressed pages that are
+// reclaimable on demand. Measured on a healthy idle Mac mini M4 Pro at one
+// instant: os.freemem() → 99.2% "used", memory_pressure → 68% free. The seat
+// showed a standing CRITICAL while the watchdog, reading memory_pressure,
+// correctly did nothing.
+// ---------------------------------------------------------------------------
+
+test("memUsedPct comes from memory_pressure, not from free/total", async () => {
+  const seen = [];
+  const execFile = (cmd, args, opts, cb) => {
+    seen.push(cmd);
+    if (cmd === "/usr/bin/memory_pressure") {
+      cb(null, "System-wide memory free percentage: 68%\n");
+    } else {
+      cb(new Error("not stubbed"));
+    }
+    return { on() {} };
+  };
+  // An os whose free/total ratio would say 99% used — the old, wrong answer.
+  const osImpl = {
+    loadavg: () => [1, 1, 1],
+    totalmem: () => 24 * 1024 ** 3,
+    freemem: () => 0.2 * 1024 ** 3,
+    cpus: () => [],
+    uptime: () => 3600,
+  };
+
+  const m = await collectMachine({ execFile, os: osImpl, platform: "darwin" });
+
+  assert.equal(m.memUsedPct, 32, "100 - 68 free, i.e. what the watchdog thresholds on");
+  assert.notEqual(m.memUsedPct, 99, "the free/total ratio must not be the answer on darwin");
+  assert.ok(seen.includes("/usr/bin/memory_pressure"), "memory_pressure is consulted");
+});
+
+test("memUsedPct falls back to free/total when memory_pressure yields nothing", async () => {
+  // Linux, or a macOS where the binary is missing/erroring. There the ratio
+  // does mean what it says, so a fallback is right — silence is not.
+  const execFile = (cmd, args, opts, cb) => { cb(new Error("ENOENT")); return { on() {} }; };
+  const osImpl = {
+    loadavg: () => [0, 0, 0],
+    totalmem: () => 1000,
+    freemem: () => 250,
+    cpus: () => [],
+    uptime: () => 1,
+  };
+
+  const m = await collectMachine({ execFile, os: osImpl, platform: "darwin" });
+  assert.equal(m.memUsedPct, 75, "1 - 250/1000");
+});
+
+test("memUsedPct ignores an out-of-range memory_pressure reading", async () => {
+  const execFile = (cmd, args, opts, cb) => {
+    cb(null, "System-wide memory free percentage: 8000%\n");
+    return { on() {} };
+  };
+  const osImpl = {
+    loadavg: () => [0, 0, 0],
+    totalmem: () => 1000,
+    freemem: () => 400,
+    cpus: () => [],
+    uptime: () => 1,
+  };
+
+  const m = await collectMachine({ execFile, os: osImpl, platform: "darwin" });
+  assert.equal(m.memUsedPct, 60, "a nonsense percentage falls back rather than propagating");
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cohortapp/agent-sdk",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "description": "Cohort Agent SDK \u2014 autonomous AI colleague runtime. Deploy senior AI colleagues on dedicated Mac minis, wired to the Cohort operating surface.",
   "type": "module",
   "bin": {

package/scripts/daemon/agent-daemon.mjs

@@ -582,6 +582,11 @@ export async function answerItem(item, service, itemId, trace_id, deps = {}, rou
     // assurance sweep retries it — the old code caught that failure, logged it,
     // and left the human staring at a typing indicator.
     let holdingText = null;
+    // Whether the acknowledgement actually LANDED, which is a different fact
+    // from whether one was composed. openAndAcknowledge returns ackText on both
+    // paths; passing only the text to buildPrompt made every failed ack read to
+    // the session as a delivered one.
+    let holdingDelivered = false;
     let obligationKeyForItem = null;
     const ackVerdict = shouldAcknowledge({ willSpawnSession: true, item, source: "inbox" });
     try {
@@ -603,6 +608,7 @@ export async function answerItem(item, service, itemId, trace_id, deps = {}, rou
       });
       obligationKeyForItem = opened.key;
       holdingText = opened.ackText;
+      holdingDelivered = Boolean(opened.acked);
       if (opened.acked) {
         updateLock(itemId, { holdingSent: true });
       } else if (ackVerdict.ack) {
@@ -641,6 +647,7 @@ export async function answerItem(item, service, itemId, trace_id, deps = {}, rou
     const prompt = await buildPrompt(item, classResult, {
       type: "inbox",
       holdingMessage: holdingText,
+      holdingSent: holdingDelivered,
     });
     // F1/H2: record a DURABLE in-flight admission and DEFER markProcessed() to
     // the dispatch onClose SUCCESS path. The previous code marked the item

package/scripts/daemon/assurance.mjs

@@ -55,6 +55,46 @@ import { deliver, deliverWithRetry, replyTargetOf, canDeliverTo } from "./delive
 import { spokeFor } from "../../lib/comms/receipts.mjs";
 import { resultTextFromStdout } from "./session-outcomes.mjs";
 
+// ── Board mirror seams ───────────────────────────────────────────────────────
+// Imported lazily so a board module problem can never stop the daemon booting,
+// and so tests can swap the implementation without a live org credential.
+let _boardMirror = null;
+async function boardMirror() {
+  if (_boardMirror) return _boardMirror;
+  try { _boardMirror = await import("./board-mirror.mjs"); }
+  catch (err) {
+    console.warn(`[assurance] board mirror unavailable: ${err.message}`);
+    _boardMirror = { openBoardItem: async () => ({ mirrored: false }), closeBoardItem: async () => ({ mirrored: false }) };
+  }
+  return _boardMirror;
+}
+
+/** Test seam: replace the board mirror wholesale. */
+export function _setBoardMirror(impl) { _boardMirror = impl; }
+
+function mirrorOpen(rec, a = {}) {
+  const inject = a.deps && a.deps.boardMirror;
+  const run = async () => {
+    const m = inject || (await boardMirror());
+    return m.openBoardItem({ rec, agentRoot: AGENT_REPO_DIR, deps: a.deps });
+  };
+  return run().catch((err) => {
+    console.warn(`[assurance] board mirror open failed: ${err.message}`);
+  });
+}
+
+function mirrorClose(rec, o = {}) {
+  const inject = o.deps && o.deps.boardMirror;
+  const run = async () => {
+    const m = inject || (await boardMirror());
+    return m.closeBoardItem({ rec, outcome: rec.state, agentRoot: AGENT_REPO_DIR, deps: o.deps });
+  };
+  return run().catch((err) => {
+    console.warn(`[assurance] board mirror close failed: ${err.message}`);
+  });
+}
+
+
 const AGENT_REPO_DIR = process.env.AGENT_DIR || join(new URL(".", import.meta.url).pathname, "../..");
 
 // ---------------------------------------------------------------------------
@@ -493,6 +533,13 @@ export async function openAndAcknowledge(a = {}) {
   if (rec.deliverable === undefined) rec.deliverable = canDeliverTo(item);
   writeRecord(rec);
 
+  // Mirror the accepted work onto the board, so "what is this colleague on?"
+  // has an answer a human can read. Deliberately NOT awaited: the board is
+  // bookkeeping and the acknowledgement is the product, so a slow or
+  // unreachable board must not add a millisecond to the reply. board-mirror
+  // never rejects, so the floating promise is safe.
+  mirrorOpen(rec, a);
+
   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
@@ -601,7 +648,13 @@ export function closeObligation(key, o = {}) {
   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);
+  const wrote = writeRecord(rec);
+  // Every close path in this module funnels through here — answered, silent
+  // success, failed, undeliverable, stale — so this is the one place the
+  // board row can be retired without the seven call sites drifting apart.
+  // Fire-and-forget for the same reason as the open hook.
+  mirrorClose(rec, o);
+  return wrote;
 }
 
 /**

package/scripts/daemon/board-mirror.mjs

@@ -0,0 +1,142 @@
+/**
+ * ── THE BOARD MIRROR ─────────────────────────────────────────────────────────
+ *
+ * Every piece of work this agent takes on becomes a row on its board, and moves
+ * as the work moves.
+ *
+ * `lib/org/board.mjs` has been complete for a long time and had exactly ONE
+ * caller — `lib/goals/collaborate.mjs`, the self-directed goal path. Nothing on
+ * the responder path touched it. So an agent could spend forty minutes on an
+ * ask that arrived by DM and leave no trace on the board at all: the human
+ * asking "what are you on?" saw whatever seed rows the workspace shipped with.
+ * On one live seat those were three tasks from 22 June, and the product's "On
+ * now" banner had been faithfully rendering one of them ever since.
+ *
+ * The hook point is the OBLIGATION, not the session. An obligation is already
+ * the daemon's record of "a human is owed something and I have started" — it
+ * opens when work is accepted and closes when the answer lands, it survives a
+ * crash, and it is keyed stably. Mirroring it needs no new lifecycle and cannot
+ * drift from the one that already governs replies.
+ *
+ * EVERYTHING HERE FAILS OPEN. A board that is unreachable, unauthorised or slow
+ * must never delay or break a reply — the work and the answer matter, the row
+ * is bookkeeping. Every function resolves; none throws; failures warn once.
+ */
+
+import { createItem, completeItem } from "../../lib/org/board.mjs";
+import { loadOrgConfig } from "../../lib/org/client.mjs";
+
+/** Board item ids are derived from the obligation key, so re-entry is idempotent. */
+export function boardItemId(obligationKey) {
+  if (!obligationKey) return null;
+  return `ob-${String(obligationKey).replace(/[^a-zA-Z0-9_-]/g, "-").slice(0, 96)}`;
+}
+
+/**
+ * A board title from the obligation's own summary.
+ *
+ * The summary is the topic clause the acknowledgement already speaks aloud
+ * ("compiling the regulatory filing calendar"), so the row and the reply say
+ * the same thing — which is the point of a board a human reads next to a
+ * conversation. Sentence case, no trailing stop, bounded length.
+ */
+export function boardTitle(rec) {
+  const raw =
+    (rec && (rec.summary || (rec.item && rec.item.subject) || (rec.item && rec.item.content))) || "";
+  const one = String(raw).replace(/\s+/g, " ").trim().replace(/[.\s]+$/, "");
+  if (!one) return "Responding to an inbound request";
+  const capped = one.length > 120 ? `${one.slice(0, 117)}…` : one;
+  return capped.charAt(0).toUpperCase() + capped.slice(1);
+}
+
+function connOpts(agentRoot, deps) {
+  const load = (deps && deps.loadOrgConfig) || loadOrgConfig;
+  const cfg = load(agentRoot) || {};
+  return { base: cfg.base, token: cfg.token, cfg, agentRoot };
+}
+
+/**
+ * Open a `running` board row for an obligation the agent has just accepted.
+ *
+ * Idempotent: the id is derived from the obligation key, so a re-delivery or a
+ * daemon restart re-creates the same row rather than a duplicate.
+ *
+ * @returns {Promise<{mirrored:boolean, itemId:string|null, reason?:string}>}
+ */
+export async function openBoardItem(a = {}) {
+  const rec = a.rec || {};
+  const itemId = boardItemId(rec.key);
+  if (!itemId) return { mirrored: false, itemId: null, reason: "no-key" };
+
+  const create = (a.deps && a.deps.createItem) || createItem;
+  try {
+    const opts = connOpts(a.agentRoot, a.deps);
+    if (!opts.base || !opts.token) {
+      return { mirrored: false, itemId, reason: "no-org-credential" };
+    }
+    const res = await create(
+      {
+        id: itemId,
+        title: boardTitle(rec),
+        // `running` is what the product's "On now" reads. A row parked in
+        // `todo` would be invisible there, which defeats the whole exercise.
+        status: "running",
+        col: "running",
+        priority: rec.priority || undefined,
+        detail: rec.sender ? `Requested by ${rec.sender}.` : undefined,
+        obligationKey: rec.key,
+      },
+      { ...opts, idempotencyKey: itemId }
+    );
+    if (res && res.ok === false) {
+      console.warn(`[board-mirror] board.create refused ${itemId}: ${describe(res)}`);
+      return { mirrored: false, itemId, reason: "refused" };
+    }
+    return { mirrored: true, itemId };
+  } catch (err) {
+    console.warn(`[board-mirror] could not open ${itemId}: ${err.message}`);
+    return { mirrored: false, itemId, reason: "error" };
+  }
+}
+
+/**
+ * Close the board row when the obligation settles.
+ *
+ * `outcome` mirrors the obligation's own verdict, so a row that ended in a
+ * failure notice does not read as delivered work.
+ */
+export async function closeBoardItem(a = {}) {
+  const rec = a.rec || {};
+  const itemId = boardItemId(rec.key);
+  if (!itemId) return { mirrored: false, itemId: null, reason: "no-key" };
+
+  const complete = (a.deps && a.deps.completeItem) || completeItem;
+  try {
+    const opts = connOpts(a.agentRoot, a.deps);
+    if (!opts.base || !opts.token) {
+      return { mirrored: false, itemId, reason: "no-org-credential" };
+    }
+    const res = await complete(
+      {
+        itemId,
+        proof: a.outcome ? `outcome:${a.outcome}` : undefined,
+        obligationKey: rec.key,
+      },
+      { ...opts, idempotencyKey: `${itemId}-done` }
+    );
+    if (res && res.ok === false) {
+      console.warn(`[board-mirror] board.complete refused ${itemId}: ${describe(res)}`);
+      return { mirrored: false, itemId, reason: "refused" };
+    }
+    return { mirrored: true, itemId };
+  } catch (err) {
+    console.warn(`[board-mirror] could not close ${itemId}: ${err.message}`);
+    return { mirrored: false, itemId, reason: "error" };
+  }
+}
+
+function describe(res) {
+  const e = res && res.error;
+  if (!e) return "unknown error";
+  return `${e.code || "ERROR"} — ${e.message || "no message"}`;
+}

package/scripts/daemon/board-mirror.test.mjs

@@ -0,0 +1,107 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  boardItemId,
+  boardTitle,
+  openBoardItem,
+  closeBoardItem,
+} from "./board-mirror.mjs";
+
+// ---------------------------------------------------------------------------
+// The board mirror exists because lib/org/board.mjs had exactly ONE caller —
+// the self-directed goal path — and nothing on the responder path touched it.
+// An agent could spend forty minutes on a DM ask and leave the board showing
+// whatever seed rows the workspace shipped with.
+//
+// Its cardinal rule is that it FAILS OPEN: the work and the answer matter, the
+// row is bookkeeping. Most of these tests are about it staying out of the way.
+// ---------------------------------------------------------------------------
+
+const CFG = { base: "https://hq.example", token: "t" };
+const okCfg = { loadOrgConfig: () => CFG };
+
+test("board item ids are derived from the obligation key, so re-entry is idempotent", () => {
+  const a = boardItemId("cohort:dm:abc123:7");
+  const b = boardItemId("cohort:dm:abc123:7");
+  assert.equal(a, b, "the same obligation must map to the same row");
+  assert.match(a, /^ob-/);
+  assert.ok(!/[^a-zA-Z0-9_-]/.test(a.slice(3)), "id is transport-safe");
+  assert.equal(boardItemId(null), null);
+});
+
+test("the title is the topic the acknowledgement already speaks aloud", () => {
+  assert.equal(
+    boardTitle({ summary: "compiling the regulatory filing calendar." }),
+    "Compiling the regulatory filing calendar"
+  );
+  // Falls back through the item, then to something honest.
+  assert.equal(boardTitle({ item: { subject: "Q3 numbers" } }), "Q3 numbers");
+  assert.equal(boardTitle({}), "Responding to an inbound request");
+  assert.ok(boardTitle({ summary: "x".repeat(400) }).length <= 120);
+});
+
+test("opens the row in `running`, which is what the product's On now reads", async () => {
+  let sent = null;
+  const r = await openBoardItem({
+    rec: { key: "k1", summary: "drafting a reply to Karen", sender: "Karen" },
+    agentRoot: "/x",
+    deps: { ...okCfg, createItem: async (item) => { sent = item; return { ok: true }; } },
+  });
+  assert.equal(r.mirrored, true);
+  assert.equal(sent.status, "running");
+  assert.equal(sent.col, "running", "a row parked in todo is invisible to the banner");
+  assert.equal(sent.title, "Drafting a reply to Karen");
+  assert.equal(sent.obligationKey, "k1");
+  assert.match(sent.detail, /Karen/);
+});
+
+test("a missing org credential is a no-op, not a throw", async () => {
+  const r = await openBoardItem({
+    rec: { key: "k1" },
+    deps: { loadOrgConfig: () => ({}), createItem: async () => { throw new Error("must not be called"); } },
+  });
+  assert.equal(r.mirrored, false);
+  assert.equal(r.reason, "no-org-credential");
+});
+
+test("a refusing board does not throw — the reply must still go out", async () => {
+  const r = await openBoardItem({
+    rec: { key: "k1", summary: "x" },
+    deps: { ...okCfg, createItem: async () => ({ ok: false, error: { code: "FORBIDDEN", message: "no" } }) },
+  });
+  assert.equal(r.mirrored, false);
+  assert.equal(r.reason, "refused");
+});
+
+test("a throwing transport does not throw — same reason", async () => {
+  const r = await openBoardItem({
+    rec: { key: "k1", summary: "x" },
+    deps: { ...okCfg, createItem: async () => { throw new Error("socket hang up"); } },
+  });
+  assert.equal(r.mirrored, false);
+  assert.equal(r.reason, "error");
+});
+
+test("closing carries the obligation's own verdict, so a failure does not read as delivered", async () => {
+  let sent = null;
+  const r = await closeBoardItem({
+    rec: { key: "k1" },
+    outcome: "failed",
+    deps: { ...okCfg, completeItem: async (p) => { sent = p; return { ok: true }; } },
+  });
+  assert.equal(r.mirrored, true);
+  assert.equal(sent.proof, "outcome:failed");
+  assert.equal(sent.itemId, boardItemId("k1"));
+});
+
+test("close is as fail-open as open", async () => {
+  for (const deps of [
+    { ...okCfg, completeItem: async () => ({ ok: false, error: { code: "GONE" } }) },
+    { ...okCfg, completeItem: async () => { throw new Error("boom"); } },
+    { loadOrgConfig: () => ({}), completeItem: async () => { throw new Error("nope"); } },
+  ]) {
+    const r = await closeBoardItem({ rec: { key: "k1" }, outcome: "answered", deps });
+    assert.equal(r.mirrored, false);
+  }
+});

package/scripts/daemon/prompt-builder.mjs

@@ -616,7 +616,11 @@ function buildBacklogContext(queueItem) {
  * @returns {string} Prompt string ready for claude --print
  */
 export async function buildPrompt(item, classResult, options = {}) {
-  const { type = "inbox", queueItem, holdingMessage } = options;
+  const { type = "inbox", queueItem, holdingMessage, holdingSent } = options;
+  // Only `false` — an explicit "the send failed" from the caller — flips the
+  // framing. Callers that pass no flag keep the historical assertion, so this
+  // cannot silently downgrade a genuinely delivered acknowledgement.
+  const holdingDelivered = holdingSent !== false;
   const preamble = loadPreamble();
   const action = classResult.action || "respond";
   const actionBlock = ACTION_INSTRUCTIONS[action] || ACTION_INSTRUCTIONS.respond;
@@ -652,7 +656,7 @@ export async function buildPrompt(item, classResult, options = {}) {
   // 1a. Holding message warning — TOP OF PROMPT so Claude sees it before action instructions.
   // This is the most critical instruction in the prompt: prevents double-replies.
   // We repeat it at section 7a as well, immediately before the action block.
-  if (holdingMessage) {
+  if (holdingMessage && holdingDelivered) {
     parts.push("===== STOP — READ THIS FIRST =====");
     parts.push(`A HOLDING MESSAGE has ALREADY been sent to the sender by the daemon. The exact text was:`);
     parts.push(`  "${holdingMessage}"`);
@@ -664,6 +668,25 @@ export async function buildPrompt(item, classResult, options = {}) {
     parts.push("- If after investigation you still cannot deliver a substantive response and need more time, send a SECOND-LEVEL UPDATE (specific blocker, ETA, what you need from the user) — never a generic 'still looking into it'.");
     parts.push("===== END WARNING =====");
     parts.push("");
+  } else if (holdingMessage) {
+    // The acknowledgement was COMPOSED but never landed (openAndAcknowledge
+    // returns ackText on the failure path too, so the session can see what the
+    // sender would have read). Asserting "already sent" here is the bug this
+    // branch exists to prevent: a session told a human had been acknowledged
+    // opens mid-conversation at a human who has heard nothing at all, and — if
+    // the item is one this session decides needs no reply — the ask lands
+    // nowhere with no trace the sender can see.
+    parts.push("===== STOP — READ THIS FIRST =====");
+    parts.push(`An acknowledgement was composed for this item but DELIVERY FAILED. The sender has received NOTHING — they do not know this item was seen. The text that did not go out was:`);
+    parts.push(`  "${holdingMessage}"`);
+    parts.push("");
+    parts.push("Plan around that, do not paper over it.");
+    parts.push("- Do NOT write as though contact has already been made — no 'as I mentioned', no 'following up on my earlier note'.");
+    parts.push("- The reply channel is unresolved or unreachable. Before composing anything, establish whether you actually have a working channel to this sender.");
+    parts.push("- If you DO have one, send a single self-contained message: the acknowledgement and the substantive answer together.");
+    parts.push("- If you do NOT, do not let the item evaporate. Record the undeliverable ask and escalate it to the operator — silence plus a closed inbox item is how a request disappears.");
+    parts.push("===== END WARNING =====");
+    parts.push("");
   }
 
   // 2. Session context
@@ -724,9 +747,12 @@ export async function buildPrompt(item, classResult, options = {}) {
   // 5. Action instructions
   // If a holding message was already sent, prepend a second reminder so the
   // action block is unambiguous about not re-acknowledging.
-  if (holdingMessage) {
+  if (holdingMessage && holdingDelivered) {
     parts.push("REMINDER: A holding message was already sent (see top of prompt). The action below describes WHAT to do — but you must NOT begin your reply with another acknowledgment. Open with substance.");
     parts.push("");
+  } else if (holdingMessage) {
+    parts.push("REMINDER: The acknowledgement for this item FAILED to send (see top of prompt) — the sender has heard nothing. The action below describes WHAT to do; carry it out knowing this is still first contact, and escalate rather than close the item silently if you cannot reach them.");
+    parts.push("");
   }
   parts.push(actionBlock);
   parts.push("");

package/scripts/daemon/prompt-builder.test.mjs

@@ -211,3 +211,44 @@ test("buildPrompt caps the number of injected org facts (bounded)", async () =>
     assert.ok(bullets > 0 && bullets <= 6, `expected <=6 injected facts, got ${bullets}`);
   });
 });
+
+test("buildPrompt states the acknowledgement was sent when it actually was", async () => {
+  const prompt = await buildPrompt(ITEM, CLASS, {
+    type: "inbox",
+    holdingMessage: "Understood — let me dig into this.",
+    holdingSent: true,
+  });
+  assert.match(prompt, /A HOLDING MESSAGE has ALREADY been sent/);
+  assert.ok(prompt.includes("Understood — let me dig into this."));
+  assert.ok(!/DELIVERY FAILED/.test(prompt), "no failure framing on a delivered ack");
+});
+
+test("buildPrompt does NOT claim delivery when the acknowledgement failed to send", async () => {
+  const prompt = await buildPrompt(ITEM, CLASS, {
+    type: "inbox",
+    holdingMessage: "Understood — let me dig into this.",
+    holdingSent: false,
+  });
+  // The lie: telling the session a human already heard from us when they did not.
+  assert.ok(
+    !/has ALREADY been sent/.test(prompt),
+    "must not assert delivery of an acknowledgement that never left the process"
+  );
+  assert.ok(
+    !/they already received the holding note/.test(prompt),
+    "must not assert receipt in the second-reminder block either"
+  );
+  // And it must say so positively, so the session plans around it.
+  assert.match(prompt, /DELIVERY FAILED/);
+  assert.match(prompt, /received NOTHING/);
+  // The composed text is still shown — it is what the sender would have seen.
+  assert.ok(prompt.includes("Understood — let me dig into this."));
+});
+
+test("buildPrompt treats an unspecified holdingSent as delivered (back-compat)", async () => {
+  const prompt = await buildPrompt(ITEM, CLASS, {
+    type: "inbox",
+    holdingMessage: "Understood — let me dig into this.",
+  });
+  assert.match(prompt, /A HOLDING MESSAGE has ALREADY been sent/);
+});