@cohortapp/agent-sdk 2.9.0 → 2.10.0

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 /
@@ -635,13 +636,31 @@ 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, {

package/scripts/daemon/assurance.mjs

@@ -64,7 +64,7 @@ async function 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 }) };
+    _boardMirror = { closeBoardItem: async () => ({ mirrored: false }) };
   }
   return _boardMirror;
 }
@@ -72,17 +72,6 @@ async function 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 () => {
@@ -236,14 +225,25 @@ export function openObligations() {
  * object is gone. Content is truncated: this file is a debt record, not a
  * message archive.
  */
-function itemSnapshot(item) {
+export function itemSnapshot(item) {
   return {
     id: item.id || null,
     raw_ref: item.raw_ref || null,
     message_id: item.message_id || null,
     service: item.service || null,
+    // `kind` IS AN ADDRESS TOO — `deliver.cohortSurfaceOf` falls back to it when
+    // `raw_ref` carries no surface name, and without it every such item
+    // re-routed from the sweep as a plain `dm` with no channel: undeliverable.
+    kind: item.kind || null,
     channel: item.channel || null,
     channel_id: item.channel_id || null,
+    // `scope_id` IS AN ADDRESS, not decoration. `deliver.cohortReplyRoute` reads
+    // it FIRST for every roomless Cohort surface (board, doc, decision). The
+    // sweep re-delivers from `rec.item`, so leaving it out meant the sweep
+    // routed a DIFFERENT item than the live path did — masked only by every
+    // hydrator happening to set `thread_id` too. Anything the routing table
+    // reads belongs in this snapshot.
+    scope_id: item.scope_id || null,
     thread_id: item.thread_id || null,
     sender: item.sender || null,
     sender_email: item.sender_email || null,
@@ -533,12 +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);
+  // 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

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

@@ -1,37 +1,41 @@
 /**
- * ── THE BOARD MIRROR ─────────────────────────────────────────────────────────
+ * ── 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.
+ * as the work moves. The OPEN half of that lives in `scripts/daemon/agent-
+ * daemon.mjs` (accepted → working, through `trackWorkStep`); this is the CLOSE.
  *
- * `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.
+ * 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.
  *
- * 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.
+ * 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.
+ * 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 { recordWorkStep } from "../../lib/org/work-ledger.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.
  *
@@ -49,94 +53,89 @@ export function boardTitle(rec) {
   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 };
+/**
+ * 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()];
 }
 
 /**
- * Open a `running` board row for an obligation the agent has just accepted.
+ * How an obligation's own verdict reads on the board.
  *
- * 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}>}
+ * `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 async function openBoardItem(a = {}) {
-  const rec = a.rec || {};
-  const itemId = boardItemId(rec.key);
-  if (!itemId) return { mirrored: false, itemId: null, reason: "no-key" };
+export function closeStageFor(outcome) {
+  return String(outcome || "answered") === "answered" ? "done" : "failed";
+}
 
-  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" };
+/** 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.`;
 }
 
 /**
- * Close the board row when the obligation settles.
+ * 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.
  *
- * `outcome` mirrors the obligation's own verdict, so a row that ended in a
- * failure notice does not read as delivered work.
+ * @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 itemId = boardItemId(rec.key);
-  if (!itemId) return { mirrored: false, itemId: null, reason: "no-key" };
+  const item = rec.item;
+  if (!item) return { mirrored: false, reason: "no-item" };
 
-  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 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" };
     }
-    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 };
+    return { mirrored: true, taskId: res.taskId || null, col: res.col || null };
   } catch (err) {
-    console.warn(`[board-mirror] could not close ${itemId}: ${err.message}`);
-    return { mirrored: false, itemId, reason: "error" };
+    console.warn(`[board-mirror] could not close ${rec.key}: ${err && err.message}`);
+    return { mirrored: false, reason: "error" };
   }
 }
 
-function describe(res) {
-  const e = res && res.error;
-  if (!e) return "unknown error";
-  return `${e.code || "ERROR"} — ${e.message || "no message"}`;
-}
+export default { boardTitle, boardPriority, closeStageFor, closeBoardItem };