@cohortapp/agent-sdk 2.8.1 → 2.9.1

package/lib/org/param-contract.mjs

@@ -346,6 +346,30 @@ export const PARAM_CONTRACT = {
   "calling.invite": { alias: { invitees: "memberIds", participantIds: "memberIds" }, required: ["callId", "memberIds"] },
 
   // ── board ────────────────────────────────────────────────────────────────
+  // `board.create` had NO entry, so `normalizeParams` passed its params through
+  // byte-for-byte and the board mirror's `{id, col, obligationKey}` reached a
+  // `.strict()` schema that accepts none of the three — every mirrored row was
+  // refused before a row was ever written, and the only trace was one fail-open
+  // warn line. (That mirror has since been retired in favour of the shared work
+  // ledger — `board.create`'s remaining caller is the self-directed goal path,
+  // lib/goals/collaborate.mjs. The contract stands either way: it is hq's
+  // schema, not one caller's habits.) The allow-list below IS hq's createSchema
+  // (src/server/methods/board/create.ts); hq's own board-lifecycle test pins the
+  // same six-plus-one names from the other side.
+  "board.create": {
+    alias: { id: "itemId", col: "status" },
+    dropAlias: true,
+    strict: ["title", "detail", "status", "priority", "workstreamId", "itemId", "channelId"],
+    // `status` is refined against the protocol BOARD_STATUS, which is the same
+    // ten words as `boardColEnum` — BOARD_COLS above is that list.
+    enums: { status: BOARD_COLS, priority: TASK_PRIORITIES },
+    required: ["title"],
+    note:
+      "createSchema is .strict(): `col`/`obligationKey`/a bare `id` 400 the whole create. " +
+      "`priority` is the P-scale (P0..P4) — the classifier's critical|high|normal|ignore is " +
+      "NOT accepted and must be mapped before the call (boardPriority, scripts/daemon/board-mirror.mjs). " +
+      "There is no `assigneeId`: board.claim is what puts an owner on a created row.",
+  },
   "board.complete": {
     strict: ["itemId", "proof"],
     transform: completeProof,

package/lib/org/work-ledger.mjs

@@ -138,6 +138,7 @@ function clip(s, n) {
  *   (true for the session path — the same signal that fires the holding
  *   message; false for the quick-reply path). The server's gate reads it.
  * @param {string} [a.title] row title (defaults server-side from the ask)
+ * @param {string} [a.priority] P0..P4, applied when the row is created
  * @param {string} [a.detail] row detail, written once at open
  * @param {string} [a.note] a progress comment for this step
  * @param {string[]} [a.notify] extra member ids to @-tag on this step
@@ -184,6 +185,10 @@ export async function recordWorkStep(a = {}) {
     const requester = requesterMemberId(a.item);
     if (requester) params.requesterId = requester;
     if (a.title) params.title = clip(a.title, MAX_TITLE);
+    // The classifier's urgency, already mapped onto hq's P-scale by the caller
+    // (`board-mirror.mjs#boardPriority` — hq 400s the whole call on anything
+    // that is not P0..P4). Only ever read when the row is CREATED.
+    if (a.priority) params.priority = String(a.priority);
     if (a.detail) params.detail = clip(a.detail, MAX_BODY);
     if (a.note) params.note = clip(a.note, MAX_NOTE);
     if (Array.isArray(a.notify) && a.notify.length) params.notify = a.notify.slice(0, 8);

package/lib/org/work-ledger.test.mjs

@@ -133,6 +133,42 @@ test("an accepted step sends the ask's identity and the deferred fact", async ()
   assert.equal(res.taskId, "t_1");
 });
 
+test("a `working` step is what puts the row where the live-work surface looks", async () => {
+  // `accepted` lands the row in `triage`, and NO live-work surface reads
+  // `triage` — hq's "On now" banner reads `running` and nothing else. Sending
+  // only the first step is why every daemon row existed and was still
+  // invisible, and why a second, ungated board writer came to exist beside it.
+  const { calls, impl } = capture();
+  await recordWorkStep({
+    item: inboxItem(),
+    stage: "working",
+    deferred: true,
+    cfg: CFG,
+    trackImpl: impl,
+  });
+  assert.equal(calls[0].params.stage, "working");
+  assert.equal(calls[0].opts.idempotencyKey, "board.track:ch_dm_1:msg_abc123:working");
+});
+
+test("the classifier's urgency rides along, already on hq's P-scale", async () => {
+  // hq validates `priority` against z.enum(["P0".."P4"]) and 400s the whole
+  // call on anything else, so the mapping happens before the wire
+  // (scripts/daemon/board-mirror.mjs#boardPriority) and this only forwards it.
+  const { calls, impl } = capture();
+  await recordWorkStep({
+    item: inboxItem(),
+    stage: "accepted",
+    priority: "P0",
+    cfg: CFG,
+    trackImpl: impl,
+  });
+  assert.equal(calls[0].params.priority, "P0");
+
+  const plain = capture();
+  await recordWorkStep({ item: inboxItem(), stage: "accepted", cfg: CFG, trackImpl: plain.impl });
+  assert.ok(!("priority" in plain.calls[0].params), "no priority ⇒ hq's own default answers");
+});
+
 test("directedness comes from the ingest layer's real verdict, never a guess", async () => {
   const { calls, impl } = capture();
   await recordWorkStep({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cohortapp/agent-sdk",
-  "version": "2.8.1",
+  "version": "2.9.1",
   "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/ci/conformance-org-api.mjs

@@ -495,6 +495,24 @@ export function buildProbes() {
       guard: "write",
       why: "creates a real Task",
     },
+    {
+      // NOT `ghost`. A ghost id is only a guard when the handler REQUIRES the
+      // entity to exist, and this one is a create — an unknown `itemId` is the
+      // CREATE branch, which is a real Task row. The only thing standing between
+      // a default read-only run and a junk row in the live org is that
+      // `assertChannelVisible` happens to run before `task.create`; reorder those
+      // two lines in hq and CI starts writing. Its sibling board.createTask makes
+      // the identical row and has always been `write` — so does this.
+      method: "board.create",
+      params: {
+        itemId: `probe-${Date.now()}`,
+        title: "[conformance probe] delete me",
+        priority: "P4",
+      },
+      writes: true,
+      guard: "write",
+      why: "creates a real Task — the same row board.createTask makes",
+    },
     {
       method: "decision.propose",
       params: { title: "[conformance probe] delete me", why: { reason: "wire conformance" }, tag: "probe" },

package/scripts/ci/conformance-org-api.test.mjs

@@ -221,7 +221,15 @@ test("SAFETY: a create-or-upsert method is never guarded `ghost` — an unknown
   // `writes:false` and a read-only run created a junk fact in the live org.
   //
   // These methods are upserts on hq's side and must stay `--write`-gated.
-  const UPSERTS = ["knowledge.replace", "contacts.upsert", "meetings.record"];
+  //
+  // `board.create` is here because it shipped as `ghost` and was one line away
+  // from the same incident: its `itemId` is a caller-chosen id, so an unknown
+  // one is the CREATE branch and makes a real Task. The only thing standing
+  // between a default read-only run and a junk row in the live org was that
+  // `assertChannelVisible` happened to run before `task.create` in hq — a
+  // guarantee no probe declaration should ever rest on. Its sibling
+  // `board.createTask` makes the identical row and has always been `write`.
+  const UPSERTS = ["knowledge.replace", "contacts.upsert", "meetings.record", "board.create"];
   const byMethod = new Map(buildProbes().map((p) => [p.method, p]));
   for (const method of UPSERTS) {
     const p = byMethod.get(method);

package/scripts/daemon/agent-daemon.mjs

@@ -87,6 +87,7 @@ import { isEnabled as orgEnabled, loadOrgConfig } from "../../lib/org/client.mjs
 import { remember as orgRemember } from "../../lib/org/knowledge.mjs";
 import { sweepSessionOutcomes, resultTextFromStdout } from "./session-outcomes.mjs";
 import { recordWorkStep as orgRecordWorkStep } from "../../lib/org/work-ledger.mjs";
+import { boardPriority } from "./board-mirror.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 /
@@ -582,6 +583,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 +609,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) {
@@ -629,18 +636,37 @@ export async function answerItem(item, service, itemId, trace_id, deps = {}, rou
     // `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.
+    //
+    // TWO steps, CHAINED. `accepted` is what tags the requester ("picked this up
+    // and put it on the board as X") and it lands the row in `triage`; `working`
+    // is what moves it to `running`, and `running` is the ONLY column the "On
+    // now" banner reads (hq components/dm/now-work.ts). Sending only the first
+    // left every daemon row parked where no live-work surface looks — the row
+    // existed and was still invisible, which is how a second, ungated writer
+    // (the old board mirror) came to exist. Chained rather than fired in
+    // parallel because `triage` is not terminal: an `accepted` that commits
+    // AFTER a `working` drags the row back out of `running` for good.
     void trackWorkStep({
       item,
       stage: "accepted",
       deferred: true,
+      priority: boardPriority(classResult && classResult.priority),
       note: classResult && classResult.summary ? `Picked this up. ${classResult.summary}` : "Picked this up — starting work now.",
       source: { service, trace_id, classified: String(classResult && classResult.action) },
-    });
+    }).then(() =>
+      trackWorkStep({
+        item,
+        stage: "working",
+        deferred: true,
+        source: { service, trace_id },
+      }),
+    );
 
     // Build prompt with holding message context and dispatch
     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,35 @@ 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 = { closeBoardItem: async () => ({ mirrored: false }) };
+  }
+  return _boardMirror;
+}
+
+/** Test seam: replace the board mirror wholesale. */
+export function _setBoardMirror(impl) { _boardMirror = impl; }
+
+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 +522,14 @@ export async function openAndAcknowledge(a = {}) {
   if (rec.deliverable === undefined) rec.deliverable = canDeliverTo(item);
   writeRecord(rec);
 
+  // NOTE: opening the board row is NOT done here. It belongs to the caller
+  // (agent-daemon.mjs, `accepted` → `working` through the shared work ledger),
+  // which holds the FULL inbox item — its directedness verdict, its author kind
+  // — rather than the thin snapshot above. This file used to open a second row
+  // of its own through `board.create`, which produced two cards per ask on the
+  // same board and gave every non-Cohort obligation an org-wide row named after
+  // a private message.
+
   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 +638,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/assurance.test.mjs

@@ -209,6 +209,46 @@ describe("openAndAcknowledge", () => {
     await openAndAcknowledge({ item: ITEM, classResult: CLASS_COMPLEX, deps: { ackSender: t.ackSender } });
     assert.equal(t.sent.length, 1, "do not spam");
   });
+
+  test("opens NO board row of its own — there is exactly one writer per ask", async () => {
+    // It used to mirror the obligation onto the board here, through
+    // `board.create`, while agent-daemon tracked the SAME item forty lines
+    // later through the shared ledger. One DM, two cards on one board, and the
+    // one the "On now" banner rendered was the copy with no requester, no
+    // comments and no provenance. The open belongs to the caller, which holds
+    // the full inbox item; this function only owes the acknowledgement.
+    const mirror = { calls: [], closeBoardItem: async (a) => { mirror.calls.push(a); return { mirrored: true }; } };
+    assurance._setBoardMirror(mirror);
+    try {
+      const t = fakeTransport();
+      await openAndAcknowledge({ item: ITEM, classResult: CLASS_COMPLEX, deps: { ackSender: t.ackSender } });
+      await new Promise((r) => setTimeout(r, 5));
+      assert.equal(mirror.calls.length, 0);
+      assert.equal(typeof mirror.openBoardItem, "undefined", "there is no open hook to call");
+    } finally {
+      assurance._setBoardMirror(null);
+    }
+  });
+
+  test("closing the debt retires the board row, carrying the obligation's own verdict", async () => {
+    // `closeObligation` is the funnel EVERY terminal path goes through, and only
+    // two of them reach the daemon's onClose. A row nothing retires sits in
+    // `running`, which is the one column the "On now" banner reads.
+    const mirror = { calls: [], closeBoardItem: async (a) => { mirror.calls.push(a); return { mirrored: true }; } };
+    assurance._setBoardMirror(mirror);
+    try {
+      const t = fakeTransport();
+      const r = await openAndAcknowledge({ item: ITEM, classResult: CLASS_COMPLEX, deps: { ackSender: t.ackSender } });
+      assurance.closeObligation(r.key, { outcome: "failed", note: "stale-no-outcome" });
+      await new Promise((res) => setTimeout(res, 5));
+      assert.equal(mirror.calls.length, 1);
+      assert.equal(mirror.calls[0].outcome, "failed");
+      assert.equal(mirror.calls[0].rec.key, r.key);
+      assert.ok(mirror.calls[0].rec.item, "the close needs the item to identify the ask");
+    } finally {
+      assurance._setBoardMirror(null);
+    }
+  });
 });
 
 // ---------------------------------------------------------------------------

package/scripts/daemon/board-mirror.mjs

@@ -0,0 +1,141 @@
+/**
+ * ── RETIRING THE BOARD ROW WHEN THE OBLIGATION SETTLES ───────────────────────
+ *
+ * Every piece of work this agent takes on becomes a row on its board, and moves
+ * as the work moves. The OPEN half of that lives in `scripts/daemon/agent-
+ * daemon.mjs` (accepted → working, through `trackWorkStep`); this is the CLOSE.
+ *
+ * WHY IT IS A SEPARATE HOOK. `closeObligation` is the funnel every terminal path
+ * in assurance.mjs goes through — answered, silent success, failed, undelivered,
+ * swept-stale — and only two of those reach the daemon's own onClose handler. A
+ * row that nothing retires sits in `running`, and `running` is the ONE column
+ * the product's "On now" banner reads, so a sweep-closed obligation would leave
+ * a colleague permanently "on" something it stopped doing hours ago. That stale
+ * banner is the exact complaint this whole workstream exists for.
+ *
+ * WHY IT NO LONGER CALLS `board.create`. It used to open and close its own row
+ * through `lib/org/board.mjs` — a SECOND implementation of a lifecycle hq and
+ * this repo already share exactly one of (`lib/org/work-ledger.mjs` → hq's
+ * `board.track` → `server/work/ledger.ts`). Two writers on the same ask is not a
+ * theoretical drift risk, it was the observed behaviour: `openAndAcknowledge`
+ * mirrored the obligation and the daemon tracked the same item forty lines
+ * later, so one DM produced TWO cards on the same board — one carrying the
+ * requester, the comments and the provenance, one carrying none of them, and
+ * the second was the one "On now" rendered. Worse, `board.create` gives a
+ * channel-less row ORG-WIDE visibility, and the mirror sent no channel for
+ * Slack/email/voice/telegram obligations — so a private ask's topic was
+ * published to everybody. The ledger's gate refuses those outright
+ * (`not-a-cohort-channel`), which is the rule this file now inherits instead of
+ * re-deciding.
+ *
+ * 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 { recordWorkStep } from "../../lib/org/work-ledger.mjs";
+import { loadOrgConfig } from "../../lib/org/client.mjs";
+
+/**
+ * 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);
+}
+
+/**
+ * The obligation priority vocabulary, mapped onto the board's P-scale.
+ *
+ * The classifier speaks `critical|high|normal|ignore` (classifier.mjs); hq
+ * validates `priority` against `z.enum(["P0"…"P4"])` and 400s the whole call on
+ * anything else. An unrecognised value yields undefined rather than a guess:
+ * hq's own default (P2) is a better answer than one we invented.
+ */
+const BOARD_PRIORITY = { critical: "P0", high: "P1", normal: "P2", ignore: "P3" };
+
+/** Obligation priority → board priority, or undefined when there is no mapping. */
+export function boardPriority(priority) {
+  const raw = String(priority || "").trim();
+  if (/^P[0-4]$/i.test(raw)) return raw.toUpperCase();
+  return BOARD_PRIORITY[raw.toLowerCase()];
+}
+
+/**
+ * How an obligation's own verdict reads on the board.
+ *
+ * `answered` is the only outcome that means the human got what he was owed.
+ * Everything else — a failed session, an undeliverable channel, a sweep that
+ * gave up — lands the row BLOCKED with the requester tagged, because the work is
+ * still owed to somebody and a row that quietly says `done` is worse than no row
+ * at all.
+ */
+export function closeStageFor(outcome) {
+  return String(outcome || "answered") === "answered" ? "done" : "failed";
+}
+
+/** The comment that goes on the row when it is retired. */
+function closeNote(rec) {
+  const state = String((rec && rec.state) || "answered");
+  const detail = rec && rec.closeNote ? ` (${String(rec.closeNote).slice(0, 200)})` : "";
+  if (state === "answered") return `Answered in the conversation${detail}.`;
+  if (state === "undeliverable") {
+    return `There was no way to deliver the answer${detail}. Back on the board, blocked.`;
+  }
+  return `This did not finish${detail}. Back on the board, blocked, rather than quietly dropped.`;
+}
+
+/**
+ * Retire the board row when the obligation settles.
+ *
+ * The obligation's SNAPSHOT (`assurance.mjs#itemSnapshot`) is deliberately thin
+ * — it carries the service, the channel and the ask, but not the ingest layer's
+ * directedness verdict — so `directed` is sent false. That is not a downgrade:
+ * hq's gate decides whether to START tracking, never whether to abandon it, so a
+ * row the open already created is closed normally, and an ask that never earned
+ * a row is refused here too. Fail-CLOSED on identity, fail-OPEN on transport.
+ *
+ * @param {object} a - { rec, outcome?, agentRoot?, deps? }
+ * @returns {Promise<{mirrored:boolean, reason?:string, taskId?:string|null, col?:string|null}>}
+ */
+export async function closeBoardItem(a = {}) {
+  const rec = a.rec || {};
+  const item = rec.item;
+  if (!item) return { mirrored: false, reason: "no-item" };
+
+  try {
+    const load = (a.deps && a.deps.loadOrgConfig) || loadOrgConfig;
+    const cfg = load(a.agentRoot) || {};
+    const track = (a.deps && a.deps.recordWorkStep) || recordWorkStep;
+    const res = await track({
+      item,
+      stage: closeStageFor(a.outcome || rec.state),
+      deferred: true,
+      title: boardTitle(rec),
+      note: closeNote(rec),
+      source: { service: String(item.service || ""), obligation: String(rec.key || "") },
+      cfg,
+    });
+    if (!res || !res.tracked) {
+      // A refusal is INFORMATION, not noise: "not-a-cohort-channel" is the rule
+      // working (a Slack ask has no board here), "no-substance" is the gate.
+      console.log(`[board-mirror] close not tracked: ${(res && res.reason) || "unknown"}`);
+      return { mirrored: false, reason: (res && res.reason) || "unknown" };
+    }
+    return { mirrored: true, taskId: res.taskId || null, col: res.col || null };
+  } catch (err) {
+    console.warn(`[board-mirror] could not close ${rec.key}: ${err && err.message}`);
+    return { mirrored: false, reason: "error" };
+  }
+}
+
+export default { boardTitle, boardPriority, closeStageFor, closeBoardItem };

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

@@ -0,0 +1,165 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { boardPriority, boardTitle, closeStageFor, closeBoardItem } from "./board-mirror.mjs";
+
+// ---------------------------------------------------------------------------
+// This file used to open AND close a board row of its own through
+// `board.create` + `board.claim` + `board.complete`. That was a second
+// implementation of a lifecycle hq and this repo already share exactly one of
+// (`lib/org/work-ledger.mjs` → `board.track` → hq `server/work/ledger.ts`), and
+// the daemon called BOTH on the same item — two cards per ask on one board, one
+// of them carrying no requester, no comments and no provenance. Worse,
+// `board.create` gives a channel-less row ORG-WIDE visibility and the mirror
+// sent no channel for Slack/email/voice, so a private ask's topic was published
+// to the whole workspace.
+//
+// What survives is the CLOSE hook, because `closeObligation` is the funnel every
+// terminal path goes through and only two of them reach the daemon's onClose.
+// These tests pin that it goes through the SHARED ledger, that it never
+// overstates, and that it still fails open.
+// ---------------------------------------------------------------------------
+
+const CFG = { org: { cohort: { enabled: true, base: "https://hq.example", token: "t" } } };
+const okCfg = { loadOrgConfig: () => CFG };
+
+/** A recording ledger seam. Answers the way `work-ledger.mjs` does. */
+function ledger(over = {}) {
+  const seen = { calls: [] };
+  return {
+    seen,
+    deps: {
+      ...okCfg,
+      recordWorkStep: async (a) => {
+        seen.calls.push(a);
+        if (over.impl) return over.impl(a);
+        return { tracked: true, reason: "ok", taskId: "task_1", col: a.stage === "done" ? "done" : "blocked" };
+      },
+    },
+  };
+}
+
+const REC = {
+  key: "cohort:dm:C1:9",
+  state: "answered",
+  summary: "compiling the regulatory filing calendar",
+  item: {
+    id: "cohort-msg_1",
+    raw_ref: "cohort:messaging:msg_1:1",
+    service: "cohort",
+    channel_id: "chan_1",
+    content: "can you compile the regulatory filing calendar",
+  },
+};
+
+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("the classifier's priority words are mapped onto hq's P-scale, which is all it accepts", () => {
+  // hq validates priority against z.enum(["P0".."P4"]); "critical" 400s the
+  // whole call, so the obligation vocabulary has to be translated here.
+  assert.equal(boardPriority("critical"), "P0");
+  assert.equal(boardPriority("high"), "P1");
+  assert.equal(boardPriority("normal"), "P2");
+  assert.equal(boardPriority("ignore"), "P3");
+  assert.equal(boardPriority("P1"), "P1");
+  // No mapping → omit, and let hq's own default (P2) answer.
+  assert.equal(boardPriority("whatever"), undefined);
+  assert.equal(boardPriority(undefined), undefined);
+});
+
+test("only `answered` closes the row as done — every other verdict blocks it", () => {
+  assert.equal(closeStageFor("answered"), "done");
+  assert.equal(closeStageFor(undefined), "done");
+  for (const bad of ["failed", "undeliverable", "stale", "anything-else"]) {
+    assert.equal(closeStageFor(bad), "failed", `${bad} must not read as delivered`);
+  }
+});
+
+test("the close goes through the SHARED ledger, not a second board writer", async () => {
+  const { seen, deps } = ledger();
+  const r = await closeBoardItem({ rec: REC, agentRoot: "/x", deps });
+
+  assert.equal(r.mirrored, true);
+  assert.equal(r.taskId, "task_1");
+  assert.equal(seen.calls.length, 1);
+  const call = seen.calls[0];
+  // The ledger identifies the ask from the ITEM (service + channel + message),
+  // and derives the dedupe key server-side — which is what makes this land on
+  // the SAME row the daemon's `accepted`/`working` steps opened, rather than a
+  // second card beside it.
+  assert.equal(call.item, REC.item);
+  assert.equal(call.stage, "done");
+  assert.equal(call.deferred, true);
+  assert.equal(call.cfg, CFG);
+  assert.match(call.note, /Answered in the conversation/);
+});
+
+test("a failed obligation lands the row blocked, and says why", async () => {
+  const { seen, deps } = ledger();
+  await closeBoardItem({ rec: { ...REC, state: "failed", closeNote: "exit 1" }, deps });
+  assert.equal(seen.calls[0].stage, "failed");
+  assert.match(seen.calls[0].note, /exit 1/);
+  assert.match(seen.calls[0].note, /blocked/);
+});
+
+test("an undeliverable obligation says so, and still does not read as delivered", async () => {
+  const { seen, deps } = ledger();
+  await closeBoardItem({ rec: { ...REC, state: "undeliverable" }, deps });
+  assert.equal(seen.calls[0].stage, "failed");
+  assert.match(seen.calls[0].note, /no way to deliver/);
+});
+
+test("an explicit outcome overrides the record's own state", async () => {
+  const { seen, deps } = ledger();
+  await closeBoardItem({ rec: REC, outcome: "failed", deps });
+  assert.equal(seen.calls[0].stage, "failed");
+});
+
+test("a non-Cohort obligation writes NO row — a private ask is not published org-wide", async () => {
+  // THE LEAK THIS REPLACED: `board.create` with no channelId produces a row
+  // every member of the org can read, titled after the ask. The daemon polls
+  // Slack, two Gmail accounts, telegram, whatsapp and voice. The shared gate
+  // refuses all of them (`not-a-cohort-channel`) — this test pins that the
+  // refusal reaches us as a benign no-op rather than being worked around.
+  const { seen, deps } = ledger({ impl: async () => ({ tracked: false, reason: "not-a-cohort-channel" }) });
+  const r = await closeBoardItem({
+    rec: { ...REC, item: { ...REC.item, service: "slack", channel_id: "D0123" } },
+    deps,
+  });
+  assert.equal(r.mirrored, false);
+  assert.equal(r.reason, "not-a-cohort-channel");
+  assert.equal(seen.calls.length, 1, "the decision is the ledger's, not a rule re-implemented here");
+});
+
+test("an obligation with no item snapshot is a no-op, not a throw", async () => {
+  const r = await closeBoardItem({
+    rec: { key: "k1" },
+    deps: { ...okCfg, recordWorkStep: async () => { throw new Error("must not be called"); } },
+  });
+  assert.equal(r.mirrored, false);
+  assert.equal(r.reason, "no-item");
+});
+
+test("the close is fail-open: a refusal, a throw and a missing credential all resolve", async () => {
+  for (const [label, impl] of [
+    ["refused", async () => ({ tracked: false, reason: "FORBIDDEN_SCOPE: no" })],
+    ["threw", async () => { throw new Error("socket hang up"); }],
+    ["disabled", async () => ({ tracked: false, reason: "org-disabled" })],
+  ]) {
+    const r = await closeBoardItem({
+      rec: REC,
+      deps: { ...okCfg, recordWorkStep: impl },
+    });
+    assert.equal(r.mirrored, false, label);
+    assert.ok(r.reason, `${label} must report why`);
+  }
+});

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/);
+});