@cohortapp/agent-sdk 2.17.0 → 2.18.4

package/lib/cli/doctor-checks.mjs

@@ -25,15 +25,20 @@
 
 "use strict";
 
-import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { existsSync, readFileSync, readdirSync, accessSync, constants as fsConstants } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 import { spawnSync } from "node:child_process";
 import { loadOrgConfig, call } from "../org/client.mjs";
 import { probeClaude as defaultProbeClaude } from "../setup/claude-probe.mjs";
+import { readSeatEngine } from "../runtime/adapter.mjs";
 import { sessionLiveness, SESSION_STALE_MS } from "../telemetry/collect.mjs";
+import { CONSOLE_KEY_REMEDY, SEAT_AUTH_VARS, REQUIRE_CONSOLE_KEY_VAR, seatAuthVerdict } from "./seat-auth.mjs";
 
 export const SDK_PACKAGE = "@cohortapp/agent-sdk";
+/** The SDK checkout this module ships in — the source of the shipped hook copies. */
+const SHIPPED_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
 
 /** Where the tailscale CLI lives, in the order we try it (mirrors telemetry). */
 const TAILSCALE_BINS = Object.freeze([
@@ -84,26 +89,94 @@ export function authMode(env = {}) {
   const token = !!env.CLAUDE_CODE_OAUTH_TOKEN;
   const prefer = /^(1|true|yes)$/i.test(String(env.MAESTRO_PREFER_SUBSCRIPTION_AUTH || ""));
   const key = !!env.ANTHROPIC_API_KEY;
-  if (token && prefer) return { mode: "oauth-token", level: "ok", msg: "Claude auth: subscription OAuth token (CLAUDE_CODE_OAUTH_TOKEN + MAESTRO_PREFER_SUBSCRIPTION_AUTH=1)" };
+  // The fleet posture is a per-agent Console API key in a capped workspace
+  // (docs/guides/billing-console-keys.md; Cohort Compute gate G4). Subscription
+  // OAuth still RUNS, so it is a warning, not a failure — but no remedy here
+  // recommends minting one.
+  if (token && prefer) {
+    return {
+      mode: "oauth-token", level: "warn",
+      msg: `Claude auth: subscription OAuth token (CLAUDE_CODE_OAUTH_TOKEN + MAESTRO_PREFER_SUBSCRIPTION_AUTH=1) — not the fleet posture; ${CONSOLE_KEY_REMEDY}`,
+    };
+  }
   if (token) {
     return {
       mode: "oauth-token", level: "warn",
-      msg: "Claude auth: CLAUDE_CODE_OAUTH_TOKEN is set but MAESTRO_PREFER_SUBSCRIPTION_AUTH=1 is not — add it so spawns strip ANTHROPIC_API_KEY and ride the token",
+      msg: `Claude auth: CLAUDE_CODE_OAUTH_TOKEN is set but MAESTRO_PREFER_SUBSCRIPTION_AUTH=1 is not, so spawns may still send ANTHROPIC_API_KEY — ${CONSOLE_KEY_REMEDY}`,
     };
   }
   if (prefer) {
     return {
       mode: "subscription", level: "warn",
-      msg: "Claude auth: keychain login (MAESTRO_PREFER_SUBSCRIPTION_AUTH=1, no token) — it expires headlessly; run `claude setup-token` and put the result in .env as CLAUDE_CODE_OAUTH_TOKEN",
+      msg: `Claude auth: keychain login (MAESTRO_PREFER_SUBSCRIPTION_AUTH=1, no key) — it expires headlessly; ${CONSOLE_KEY_REMEDY}`,
     };
   }
-  if (key) return { mode: "api-key", level: "ok", msg: "Claude auth: ANTHROPIC_API_KEY (pay-per-token)" };
+  if (key) return { mode: "api-key", level: "ok", msg: "Claude auth: ANTHROPIC_API_KEY (Console API key, pay-per-token)" };
   return {
     mode: "none", level: "fail",
-    msg: "Claude auth: nothing configured — run `claude setup-token` on any logged-in machine and put the result in .env as CLAUDE_CODE_OAUTH_TOKEN (plus MAESTRO_PREFER_SUBSCRIPTION_AUTH=1), or set ANTHROPIC_API_KEY",
+    msg: `Claude auth: nothing configured — ${CONSOLE_KEY_REMEDY}`,
   };
 }
 
+/**
+ * The one remedy every auth row gives (CF-13). It lives in `lib/cli/seat-auth.mjs`
+ * — the G4 module — and is re-exported here so the doctor rows and the
+ * `maestro seat-auth` surface cannot drift into saying different things.
+ */
+export { CONSOLE_KEY_REMEDY };
+
+// ── Pre-send hook (CF-14) ────────────────────────────────────────────────────
+
+/** Where scripts/hooks/pre-send-audit.sh looks for node when `command -v node` fails. */
+export const HOOK_NODE_CANDIDATES = Object.freeze(["/opt/homebrew/bin/node", "/usr/local/bin/node", "~/.local/bin/node", "/usr/bin/node"]);
+
+/**
+ * Can the pre-send hook wrapper find node? It runs the gate with `node`, and it
+ * fails CLOSED without it — every outbound send would be blocked. Pure over
+ * its inputs.
+ * @param {{onPath:string, isExecutable:(p:string)=>boolean, home?:string}} o
+ */
+export function hookNodeResolvable({ onPath = "", isExecutable = () => false, home = "" } = {}) {
+  const found = String(onPath || "").trim();
+  if (found) return { level: "ok", msg: `Pre-send hook: node resolves on PATH (${found})` };
+  for (const c of HOOK_NODE_CANDIDATES) {
+    const p = c.startsWith("~/") ? `${home}/${c.slice(2)}` : c;
+    if (home || !c.startsWith("~/")) {
+      if (isExecutable(p)) return { level: "ok", msg: `Pre-send hook: node found at ${p} (the wrapper's fallback path)` };
+    }
+  }
+  return {
+    level: "fail",
+    msg: "Pre-send hook: node is not resolvable — scripts/hooks/pre-send-audit.sh runs lib/comms/send-gate.mjs with node and fails closed without it, so EVERY outbound send is blocked; install node (brew install node) or put it on the hook runner's PATH",
+  };
+}
+
+/**
+ * Do the seat's copies of the pre-send hook and the send gate match the
+ * versions this SDK ships? `maestro upgrade` keeps a locally modified copy (and
+ * drops the upstream one in .maestro/incoming/), so a seat can run a stale gate
+ * indefinitely without anything saying so. Pure over its inputs.
+ * @param {Array<{label:string, seatPath:string, seat:string|null, shipped:string|null}>} files
+ * @param {string} [version]
+ */
+export function hookCopyDrift(files = [], version = "") {
+  const rows = [];
+  for (const f of files) {
+    if (f.shipped == null) continue; // nothing to compare against
+    if (f.seat == null) {
+      rows.push({ level: "warn", msg: `Pre-send hook: ${f.label} is missing at ${f.seatPath} — run \`maestro upgrade\`` });
+    } else if (f.seat !== f.shipped) {
+      rows.push({
+        level: "warn",
+        msg: `Pre-send hook: ${f.label} at ${f.seatPath} differs from the shipped version${version ? ` (${SDK_PACKAGE} ${version})` : ""} — \`maestro upgrade\` keeps locally modified copies; compare with .maestro/incoming/ and reconcile`,
+      });
+    } else {
+      rows.push({ level: "ok", msg: `Pre-send hook: ${f.label} matches the shipped version` });
+    }
+  }
+  return rows;
+}
+
 /**
  * Does this look like an org ID (`org_default_<slug>`) rather than a bare slug?
  * Shared with the setup wizard's org section so both judge the pin the same way.
@@ -324,6 +397,7 @@ function agentFirstName(cwd) {
  * @param {Function} [o.fetchImpl]
  * @param {() => string[]} [o.listPlists]        names in ~/Library/LaunchAgents
  * @param {(agentRoot:string)=>object} [o.probeClaude]
+ * @param {(agentRoot:string)=>string} [o.seatEngine]  the seat's runtime.engine (default: config/agent.json)
  * @returns {Promise<Array<{level:"ok"|"warn"|"fail", msg:string}>>}
  */
 export async function runDoctorChecks(o = {}) {
@@ -343,9 +417,28 @@ export async function runDoctorChecks(o = {}) {
 
   // ── Claude auth (F1) ──────────────────────────────────────────────────────
   const dotEnv = parseDotEnv(safeRead(join(cwd, ".env")));
+  let seatEngine = "claude";
+  try { seatEngine = (o.seatEngine || readSeatEngine)(cwd); } catch { seatEngine = "claude"; /* unreadable config: the default engine */ }
+  if (seatEngine === "cohort") {
+    // An engine-cohort seat never talks to Claude: the only auth that matters is its
+    // cohort-llm seat credential, proven by the engine's `auth status` (claude-probe.mjs).
+    try {
+      const probe = (o.probeClaude || defaultProbeClaude)(cwd, { env });
+      if (probe.ok && probe.verified === true) rows.push({ level: "ok", msg: `${probe.name}: ${probe.detail || "verified"}` });
+      else if (probe.ok) rows.push({ level: "warn", msg: `${probe.name}: ${probe.detail || "could not verify"}` });
+      else rows.push({ level: "fail", msg: `${probe.name}: ${probe.remedy || "failed"}` });
+    } catch (err) {
+      rows.push({ level: "warn", msg: `Cohort engine auth probe threw: ${err && err.message ? err.message : err}` });
+    }
+    // W4-E1 (row 36): the legacy shell lanes run claude outside the runtime adapter and refuse on this seat.
+    rows.push({
+      level: "warn",
+      msg: "Legacy shell lanes are retired on this engine-cohort seat: scripts/spawn-session.sh, scripts/continuous-monitor.sh and scripts/local-triggers/run-trigger.sh refuse to run (exit 3). Use `maestro session spawn`, the daemon, or `node scripts/cadence/enqueue-cadence-tick.mjs <trigger> --source=manual`.",
+    });
+  }
   const merged = { ...pick(env, ["CLAUDE_CODE_OAUTH_TOKEN", "MAESTRO_PREFER_SUBSCRIPTION_AUTH", "ANTHROPIC_API_KEY"]), ...dotEnv };
-  const auth = authMode(merged);
-  rows.push({ level: auth.level, msg: auth.msg });
+  const auth = seatEngine === "cohort" ? { mode: "none" } : authMode(merged);
+  if (seatEngine !== "cohort") rows.push({ level: auth.level, msg: auth.msg });
   if (auth.mode !== "none") {
     try {
       // The probe judges the mode from the SAME env this row did (.env first,
@@ -364,6 +457,26 @@ export async function runDoctorChecks(o = {}) {
     }
   }
 
+  // ── Billing rail: is this seat on the fleet posture? (G4) ─────────────────
+  //
+  // `authMode` above answers "which credential will the CLI use"; this answers
+  // "is that the rail the org is allowed to be on", which is a different
+  // question with a different owner. It runs on EVERY seat, engine-cohort
+  // included — a subscription token sitting in an engine-cohort seat's .env is
+  // still the non-compliant shape, even though no lane there would use it.
+  // Names only, never a value. Warn today; `MAESTRO_REQUIRE_CONSOLE_KEY=1`
+  // turns it into a failure once the fleet has migrated.
+  {
+    const railEnv = { ...pick(env, [...SEAT_AUTH_VARS, REQUIRE_CONSOLE_KEY_VAR]), ...dotEnv };
+    const railSources = {};
+    for (const n of SEAT_AUTH_VARS) {
+      if (dotEnv[n]) railSources[n] = ".env";
+      else if (env[n]) railSources[n] = "env";
+    }
+    const rail = seatAuthVerdict(railEnv, { seatEngine, sources: railSources });
+    rows.push({ level: rail.level, msg: `${rail.msg} (paste-able inventory row: \`maestro seat-auth --row\`)` });
+  }
+
   // ── Effective Cohort sources (F3) ─────────────────────────────────────────
   const orgYaml = existsSync(join(cwd, "config", "org.yaml")) ? loadOrgConfig(cwd) : null;
   const sources = effectiveSource({ orgYaml, dotEnv, env: pick(env, ["COHORT_BASE", "COHORT_API_URL", "COHORT_ORG_ID", "COHORT_API_TOKEN", "COHORT_TOKEN", "COHORT_API_KEY", "COHORT_AGENT_ID"]) });
@@ -422,6 +535,20 @@ export async function runDoctorChecks(o = {}) {
   const ts = tailscaleSsh(status, prefs);
   rows.push({ level: ts.level, msg: ts.msg });
 
+  // ── Pre-send hook: node + drift (CF-14) ─────────────────────────────────────
+  {
+    const onPath = tryExec("which", ["node"], { timeout: 2000 }).trim();
+    const isExecutable = o.isExecutable || ((p) => { try { accessSync(p, fsConstants.X_OK); return true; } catch { return false; } });
+    const nodeRow = hookNodeResolvable({ onPath, isExecutable, home: o.home !== undefined ? o.home : homedir() });
+    rows.push(nodeRow);
+    const sdkRoot = resolve(o.sdkRoot || SHIPPED_ROOT);
+    if (sdkRoot !== cwd) {
+      const pair = (rel, label) => ({ label, seatPath: join(cwd, rel), seat: readOrNull(join(cwd, rel)), shipped: readOrNull(join(sdkRoot, rel)) });
+      const version = (() => { try { return JSON.parse(readFileSync(join(sdkRoot, "package.json"), "utf-8")).version || ""; } catch { return ""; } })();
+      for (const r of hookCopyDrift([pair("scripts/hooks/pre-send-audit.sh", "pre-send-audit.sh"), pair("lib/comms/send-gate.mjs", "send-gate.mjs")], version)) rows.push(r);
+    }
+  }
+
   // ── Main session job (§3.1) ───────────────────────────────────────────────
   const listPlists = o.listPlists || (() => { try { return readdirSync(join(homedir(), "Library", "LaunchAgents")); } catch { return []; } });
   const loaded = parseLaunchctlList(tryExec("launchctl", ["list"], { timeout: 4000 }));
@@ -432,10 +559,14 @@ export async function runDoctorChecks(o = {}) {
   return rows;
 }
 
+function readOrNull(p) {
+  try { return existsSync(p) ? readFileSync(p, "utf-8") : null; } catch { return null; }
+}
+
 function pick(obj, keys) {
   const out = {};
   for (const k of keys) if (obj && obj[k]) out[k] = String(obj[k]);
   return out;
 }
 
-export default { parseDotEnv, mask, authMode, looksLikeOrgId, orgIdShape, effectiveSource, sdkGlobalInstall, tailscaleSsh, sessionInstalled, runDoctorChecks };
+export default { parseDotEnv, mask, authMode, looksLikeOrgId, orgIdShape, effectiveSource, sdkGlobalInstall, tailscaleSsh, sessionInstalled, hookNodeResolvable, hookCopyDrift, runDoctorChecks };

package/lib/cli/global-setup-extras.mjs

@@ -307,7 +307,11 @@ export async function applyFrontDoorSetup(o = {}) {
         let done = false;
         if (claudeBin) {
           try {
-            const r = exec(claudeBin, ["mcp", "add-json", "cohort", JSON.stringify(entry), "--scope", "user"]);
+            // argv from the runtime adapter (lane "mcp-register"); a failure to
+            // load it is a spawn failure like any other → JSON merge below.
+            const { buildSpawn } = await import("../runtime/adapter.mjs");
+            const spec = buildSpawn({ lane: "mcp-register", bin: claudeBin, registration: { name: "cohort", config: JSON.stringify(entry), scope: "user" } });
+            const r = spec.ok ? exec(spec.bin, spec.argv) : null;
             if (r && r.status === 0) {
               // Trust but verify: the CLI owns the file format; confirm the entry landed.
               const after = readJsonFile(claudeJsonPath);

package/lib/cli/inbox.mjs

@@ -10,12 +10,22 @@
  *
  *   list  [--service <svc>] [--new]        pending items (JSON)
  *   show  <id>                             the full item (+ history when the body is empty)
- *   claim <id>                             .yaml → .yaml.dispatched, claimed_by: session
+ *   claim <id> [--title …] [--why …]       .yaml → .yaml.dispatched, claimed_by: session
+ *                                          (title/why land on the board row, which
+ *                                          opens HERE and nowhere later)
  *   reply <id> (--text "…" | --file <p>)   routes through scripts/daemon/deliver.mjs#deliver
  *                                          (surface routing, send-gate, audit, receipts)
  *   done  <id>                             .processed (terminal)
  *   defer <id> --until <iso|+30m> [--reason "…"]   parked; the daemon sweep reopens it when due
  *
+ * THE ASK LEDGER RIDES ON THESE COMMANDS. `claim`, `reply`, `done` and `defer`
+ * each write their own board step through `lib/session/ask-ledger.mjs`, because
+ * the lane that ACCEPTS an ask owns its ledger. Before that the only writer was
+ * the daemon's `answerItem`, which the front-door gate (`de35690`) switched off
+ * the moment this CLI's session came up — thirteen days with no automatic row
+ * and no channel tag, on a board that was visibly busy the whole time. The
+ * outcome rides inside the command's own JSON as `board`.
+ *
  * Output is one JSON document on stdout. Exit 0 on success, 1 on any refusal
  * (`{ok:false, error}` — expected failures are values, never throws). Every
  * effect outside the inbox directory is an injected seam (`deliver`,
@@ -37,13 +47,14 @@ import {
   parseSessionMarkers,
   stripMarkersInPlace,
 } from "../session/inbox-claims.mjs";
+import { runAskLedger, formatLedgerOutcome } from "../session/ask-ledger.mjs";
 
 const PREVIEW_CHARS = 240;
 
 export const USAGE = `Usage:
   maestro inbox list [--service <svc>] [--new]
   maestro inbox show <id>
-  maestro inbox claim <id>
+  maestro inbox claim <id> [--title "…"] [--why "…"]
   maestro inbox reply <id> (--text "…" | --file <path>)
   maestro inbox done <id>
   maestro inbox defer <id> --until <iso|+30m|+2h|+1d> [--reason "…"]
@@ -201,12 +212,70 @@ async function defaultFetchHistory(agentRoot) {
   return (params) => fetchHistory(params, { cfg });
 }
 
-function claim(agentRoot, id, flags, deps) {
+/**
+ * THE ASK LEDGER, WRITTEN WHERE THE WORK IS ACCEPTED.
+ *
+ * Every automatic board row used to be written from one place — the daemon's
+ * `answerItem` — and `de35690` put a front-door gate in front of the only path
+ * that reaches it. The daemon stepped back, the session lane took the ask, and
+ * the ledger went dark for thirteen days while boards kept moving through tools
+ * so nothing looked broken. See `lib/session/ask-ledger.mjs` for the full
+ * account. This is the session lane's half: the commands that ACCEPT, ANSWER,
+ * CLOSE and PARK an ask each write their own step, so no later step-back can
+ * take the ledger with it.
+ *
+ * Fail-open and after the fact: the command's own effect has already landed
+ * before this runs, and `runAskLedger` cannot throw. The outcome rides in the
+ * command's JSON as `board`, so stdout stays exactly one document.
+ *
+ * @returns {Promise<string|null>} the summary line, or null when nothing was owed
+ */
+async function askLedger(agentRoot, action, item, extra, deps) {
+  try {
+    // NO OFF-SWITCH LIVES HERE. An earlier draft carried a `deps.askLedger ===
+    // false` seam "for tests". Nothing used it, and it is the exact shape of
+    // the bug this module exists to fix: one flag that silences the whole
+    // ledger with nothing going red. The only seams are the ones a test must
+    // fake to run offline (`runAskLedger`, `trackImpl`, `fetchImpl`, `cfg`) —
+    // each of which still proves a frame was BUILT. `inbox-ledger-dispatch.
+    // test.mjs` pins that the shipped `bin/maestro inbox` path, with no deps at
+    // all, puts a real board.track on the wire.
+    const run = (deps && deps.runAskLedger) || runAskLedger;
+    const cfg = deps && deps.cfg !== undefined ? deps.cfg : await loadOrgCfg(agentRoot);
+    const outcome = await run({ action, item, cfg, ...extra, trackImpl: deps && deps.trackImpl, fetchImpl: deps && deps.fetchImpl });
+    return formatLedgerOutcome(action, outcome);
+  } catch {
+    // The ledger is bookkeeping; the command already did its job.
+    return null;
+  }
+}
+
+/** org.yaml, loaded lazily so `inbox list` never pays for it. */
+async function loadOrgCfg(agentRoot) {
+  try {
+    const { loadOrgConfig } = await import("../org/client.mjs");
+    return loadOrgConfig(agentRoot);
+  } catch { return {}; /* no org config → recordWorkStep answers `org-disabled` */ }
+}
+
+async function claim(agentRoot, id, flags, deps) {
   const found = findInboxFile(agentRoot, id, { service: flags.service });
   if (!found) return { code: 1, body: { ok: false, error: "not-found", id } };
   if (found.state !== "new") return { code: 1, body: { ok: false, error: "not-claimable", id, state: found.state } };
+  const { item } = readItem(found);
   const r = markSessionClaim(agentRoot, found.service, { id }, { now: deps.now });
-  return r.ok ? { code: 0, body: { ok: true, id, service: found.service, path: r.path } } : { code: 1, body: { ok: false, error: r.error, id } };
+  if (!r.ok) return { code: 1, body: { ok: false, error: r.error, id } };
+  // ACCEPTANCE. The claim is this lane taking the ask; the row opens here —
+  // and OPENING is the only moment hq reads `title` and `why` (ledger.ts writes
+  // both inside `if (!taskId)`, and `why.reason` is a PROTECTED key a later
+  // patch may not overwrite). So a better title than the ask's own first
+  // sentence has to travel on the claim; `maestro board track --title` after
+  // the fact is accepted and silently ignored.
+  const board = await askLedger(agentRoot, "claim", item, {
+    title: typeof flags.title === "string" ? flags.title : undefined,
+    why: typeof flags.why === "string" ? flags.why : undefined,
+  }, deps);
+  return { code: 0, body: { ok: true, id, service: found.service, path: r.path, ...(board ? { board } : {}) } };
 }
 
 async function reply(agentRoot, id, flags, deps) {
@@ -234,13 +303,22 @@ async function reply(agentRoot, id, flags, deps) {
     const stamped = markSessionReplied(agentRoot, found.service, { id }, { now: deps.now });
     body.replied_recorded = stamped.ok;
   }
+  // DELIVERY. In this lane the reply IS the work landing, so it closes the row
+  // and tags the originating channel. Only on a reply that actually went out.
+  if (body.ok) {
+    const board = await askLedger(agentRoot, "reply", item, { text }, deps);
+    if (board) body.board = board;
+  }
   return { code: body.ok ? 0 : 1, body };
 }
 
-function done(agentRoot, id, flags) {
+async function done(agentRoot, id, flags, deps = {}) {
   const found = findInboxFile(agentRoot, id, { service: flags.service });
   if (!found) return { code: 1, body: { ok: false, error: "not-found", id } };
   if (found.state === "processed" || found.state === "bundled") return { code: 1, body: { ok: false, error: "already-processed", id } };
+  // Read BEFORE the rename strips the markers: `replied_at` is what tells the
+  // ledger the row was already closed by the reply.
+  const { item, markers } = readItem(found);
   // ONE file — the located item — to `<base>.yaml.processed`, the terminal
   // name the scanner skips. (utils#markInboxProcessed matches by substring and
   // would retire look-alike ids beside it.) Markers are stripped in place.
@@ -250,22 +328,25 @@ function done(agentRoot, id, flags) {
     renameSync(found.path, found.path.replace(/\.(dispatched|deferred)$/, "") + ".processed");
     renamed = 1;
   } catch { renamed = 0; /* vanished under us — reported below as not-finishable */ }
-  return renamed
-    ? { code: 0, body: { ok: true, id, service: found.service, renamed } }
-    : { code: 1, body: { ok: false, error: "not-finishable", id, state: found.state } };
+  if (!renamed) return { code: 1, body: { ok: false, error: "not-finishable", id, state: found.state } };
+  const board = await askLedger(agentRoot, "done", item, { markers }, deps);
+  return { code: 0, body: { ok: true, id, service: found.service, renamed, ...(board ? { board } : {}) } };
 }
 
-function defer(agentRoot, id, flags, deps) {
+async function defer(agentRoot, id, flags, deps) {
   if (flags.until === undefined || flags.until === true) return { code: 1, body: { ok: false, error: "--until required (iso | +30m | +2h | +1d)", id } };
   const now = typeof deps.now === "number" ? deps.now : Date.now();
   const until = parseUntil(flags.until, now);
   if (until == null) return { code: 1, body: { ok: false, error: `invalid --until: ${flags.until}`, id } };
   const found = findInboxFile(agentRoot, id, { service: flags.service });
   if (!found) return { code: 1, body: { ok: false, error: "not-found", id } };
+  const { item } = readItem(found);
   const r = markSessionDeferral(agentRoot, found.service, { id }, { until, reason: typeof flags.reason === "string" ? flags.reason : "", now });
-  return r.ok
-    ? { code: 0, body: { ok: true, id, service: found.service, path: r.path, until: r.until } }
-    : { code: 1, body: { ok: false, error: r.error, id } };
+  if (!r.ok) return { code: 1, body: { ok: false, error: r.error, id } };
+  // PARKED, not dropped. A blocked row with the reason on it is the truthful
+  // reading of an ask nobody is working right now.
+  const board = await askLedger(agentRoot, "defer", item, { until: r.until, reason: flags.reason }, deps);
+  return { code: 0, body: { ok: true, id, service: found.service, path: r.path, until: r.until, ...(board ? { board } : {}) } };
 }
 
 /**
@@ -277,6 +358,10 @@ function defer(agentRoot, id, flags, deps) {
  * @param {string} [deps.agentRoot]
  * @param {Function} [deps.deliver]        (item, text, o) → delivery result
  * @param {Function} [deps.fetchHistory]   (params) → rows
+ * @param {Function} [deps.runAskLedger]   injected ask-ledger runner
+ * @param {object} [deps.cfg]              injected org config (skips the org.yaml read)
+ * @param {Function} [deps.trackImpl]      injected `board.track`
+ * @param {Function} [deps.fetchImpl]      injected fetch
  * @param {number} [deps.now]
  * @param {Function} [deps.stdout]         (string) → void
  * @returns {Promise<number>} exit code
@@ -293,10 +378,10 @@ export async function runInbox(argv = [], deps = {}) {
   switch (sub) {
     case "list": return emit(list(agentRoot, flags));
     case "show": return emit(await show(agentRoot, id, flags, deps));
-    case "claim": return emit(claim(agentRoot, id, flags, deps));
+    case "claim": return emit(await claim(agentRoot, id, flags, deps));
     case "reply": return emit(await reply(agentRoot, id, flags, deps));
-    case "done": return emit(done(agentRoot, id, flags));
-    case "defer": return emit(defer(agentRoot, id, flags, deps));
+    case "done": return emit(await done(agentRoot, id, flags, deps));
+    case "defer": return emit(await defer(agentRoot, id, flags, deps));
     default: return 1;
   }
 }