@cohortapp/agent-sdk 2.11.15 → 2.13.0

package/lib/cli/inbox.mjs

@@ -0,0 +1,304 @@
+/**
+ * lib/cli/inbox.mjs — `maestro inbox list|show|claim|reply|done|defer`
+ * (design §3.3): the main session's CLI over the inbox the daemon fills.
+ *
+ * One state machine, two actors. The daemon and the session share the file
+ * markers `scripts/poller/utils.mjs` defines (`.yaml` → `.yaml.dispatched` →
+ * `.yaml.processed`, `.yaml.deferred`) plus the session markers in
+ * `lib/session/inbox-claims.mjs`, so a claim made here is visible to the
+ * daemon's sweep and a `.processed` written here is terminal for both.
+ *
+ *   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
+ *   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
+ *
+ * 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`,
+ * `fetchHistory`, `now`, `stdout`) so the command is testable offline.
+ *
+ * @module lib/cli/inbox
+ */
+
+import { join } from "node:path";
+import { readdirSync, readFileSync, existsSync, renameSync } from "node:fs";
+
+import { parseInboxItemYaml } from "../../scripts/poller/inbox-scan-poller.mjs";
+import { maskTextString } from "../security/redact.mjs";
+import {
+  findInboxFile,
+  markSessionClaim,
+  markSessionDeferral,
+  markSessionReplied,
+  parseSessionMarkers,
+  stripMarkersInPlace,
+} from "../session/inbox-claims.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 reply <id> (--text "…" | --file <path>)
+  maestro inbox done <id>
+  maestro inbox defer <id> --until <iso|+30m|+2h|+1d> [--reason "…"]
+`;
+
+/** `--key value` / `--flag` / positionals. */
+function parseArgs(argv) {
+  const flags = {};
+  const pos = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith("--")) { flags[key] = next; i++; }
+      else flags[key] = true;
+    } else pos.push(a);
+  }
+  return { flags, pos };
+}
+
+/**
+ * `+30m` / `+2h` / `+1d` relative to `now`, or an ISO timestamp. Pure.
+ * @param {string} text
+ * @param {number} now epoch ms
+ * @returns {number|null} epoch ms, or null when unparsable
+ */
+export function parseUntil(text, now) {
+  const s = String(text || "").trim();
+  const rel = s.match(/^\+(\d+)([mhd])$/i);
+  if (rel) {
+    const n = Number(rel[1]);
+    const unit = { m: 60_000, h: 3_600_000, d: 86_400_000 }[rel[2].toLowerCase()];
+    return Number.isFinite(n) && n > 0 ? now + n * unit : null;
+  }
+  const abs = Date.parse(s);
+  return Number.isFinite(abs) ? abs : null;
+}
+
+function resolveAgentRoot(deps) {
+  return deps.agentRoot || process.env.AGENT_ROOT || process.env.AGENT_DIR || process.cwd();
+}
+
+function serviceDirs(agentRoot, only) {
+  if (only) return [String(only)];
+  try {
+    return readdirSync(join(agentRoot, "state", "inbox"), { withFileTypes: true })
+      .filter((e) => e.isDirectory() && e.name !== "attachments")
+      .map((e) => e.name)
+      .sort();
+  } catch { return []; /* no inbox yet */ }
+}
+
+/**
+ * The daemon's channel-kind enrichment, in miniature, so a reply built here
+ * routes exactly as the responder's would (`is_dm` decides the DM/thread
+ * transport in deliver.mjs). Mirrors scripts/daemon/agent-daemon#enrichItem.
+ */
+function enrich(item, service) {
+  const kind = String(item.channel_kind || "").toUpperCase();
+  const channelStr = String(item.channel || "").toLowerCase();
+  const channelId = String(item.channel_id || "");
+  item.is_dm = kind
+    ? kind === "DM"
+    : typeof item.is_dm === "boolean"
+      ? item.is_dm
+      : channelStr.startsWith("dm/") || channelId.startsWith("D");
+  if (!item.service) item.service = service;
+  return item;
+}
+
+function readItem(found) {
+  const raw = readFileSync(found.path, "utf-8");
+  const item = enrich(parseInboxItemYaml(raw), found.service);
+  return { raw, item, markers: parseSessionMarkers(raw) };
+}
+
+function preview(text) {
+  const one = String(text || "").replace(/\s+/g, " ").trim();
+  const cut = one.length > PREVIEW_CHARS ? `${one.slice(0, PREVIEW_CHARS - 1)}…` : one;
+  try { return maskTextString(cut); } catch { return cut; /* masking is defence in depth, never a blocker */ }
+}
+
+// ── subcommands ──────────────────────────────────────────────────────────────
+
+function list(agentRoot, flags) {
+  const out = [];
+  for (const service of serviceDirs(agentRoot, flags.service)) {
+    const dir = join(agentRoot, "state", "inbox", service);
+    if (!existsSync(dir)) continue;
+    let names;
+    try { names = readdirSync(dir); } catch { continue; }
+    for (const file of names) {
+      const isNew = file.endsWith(".yaml");
+      const isClaimed = file.endsWith(".yaml.dispatched");
+      if (!isNew && !isClaimed) continue;
+      try {
+        const raw = readFileSync(join(dir, file), "utf-8");
+        const markers = parseSessionMarkers(raw);
+        // A daemon-owned `.dispatched` (no session marker) is not the session's.
+        if (isClaimed && !markers.claimedBy) continue;
+        if (flags.new && isClaimed) continue;
+        const item = parseInboxItemYaml(raw);
+        if (!item.id) continue;
+        out.push({
+          id: item.id,
+          service,
+          state: isClaimed ? "claimed" : "new",
+          kind: item.kind || "message",
+          channel: item.channel || null,
+          channel_id: item.channel_id || null,
+          channel_kind: item.channel_kind || null,
+          sender: item.sender || null,
+          timestamp: item.timestamp || null,
+          subject: item.subject || null,
+          thread_id: item.thread_id || null,
+          preview: preview(item.content),
+          path: join(dir, file),
+          ...(markers.claimedAt ? { claimedAt: markers.claimedAt } : {}),
+        });
+      } catch { /* unreadable item — skipped, the daemon's own scan will report it */ }
+    }
+  }
+  out.sort((a, b) => String(a.timestamp || "").localeCompare(String(b.timestamp || "")) || a.id.localeCompare(b.id));
+  return { code: 0, body: out };
+}
+
+async function show(agentRoot, id, flags, deps) {
+  const found = findInboxFile(agentRoot, id, { service: flags.service });
+  if (!found) return { code: 1, body: { ok: false, error: "not-found", id } };
+  const { raw, item, markers } = readItem(found);
+  const body = { ok: true, id: item.id, service: found.service, state: found.state, path: found.path, item, markers, raw };
+  if (!String(item.content || "").trim() && item.channel_id) {
+    // The body was not hydrated at intake — pull recent history so the
+    // session can see the ask. Fail-open: no org, no network → [].
+    body.history = await hydrateHistory(agentRoot, item, deps);
+  }
+  return { code: 0, body };
+}
+
+async function hydrateHistory(agentRoot, item, deps) {
+  try {
+    const impl = deps.fetchHistory || (await defaultFetchHistory(agentRoot));
+    const rows = await impl({ channel: item.channel_id, limit: 20 });
+    return Array.isArray(rows) ? rows : [];
+  } catch { return []; /* history is a convenience, never a blocker */ }
+}
+
+async function defaultFetchHistory(agentRoot) {
+  const [{ fetchHistory }, { loadOrgConfig }] = await Promise.all([
+    import("../org/messaging.mjs"),
+    import("../org/client.mjs"),
+  ]);
+  const cfg = loadOrgConfig(agentRoot);
+  return (params) => fetchHistory(params, { cfg });
+}
+
+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 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 } };
+}
+
+async function reply(agentRoot, id, flags, deps) {
+  let text = typeof flags.text === "string" ? flags.text : null;
+  if (text == null && typeof flags.file === "string") {
+    try { text = readFileSync(flags.file, "utf-8"); }
+    catch (err) { return { code: 1, body: { ok: false, error: `cannot read --file: ${err.message}`, id } }; }
+  }
+  text = String(text || "").trim();
+  if (!text) return { code: 1, body: { ok: false, error: "reply text required (--text or --file)", id } };
+  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 } };
+  const { item } = readItem(found);
+  const deliverImpl = deps.deliver || (await import("../../scripts/daemon/deliver.mjs")).deliver;
+  let result;
+  try { result = await deliverImpl(item, text, { kind: "reply", agentRoot }); }
+  catch (err) { result = { sent: false, via: null, error: err && err.message ? err.message : String(err) }; }
+  const body = { ok: !!(result && result.sent), id, service: found.service, ...(result || {}) };
+  // Record the reply ON the item (replied_at) so the daemon's assurance sweep
+  // never reopens — and re-answers — an item the human already heard back on.
+  // Only an in-flight claim carries markers; a reply to a new item is sent
+  // but leaves the item claimable (the session did not claim it).
+  if (body.ok && found.state === "claimed") {
+    const stamped = markSessionReplied(agentRoot, found.service, { id }, { now: deps.now });
+    body.replied_recorded = stamped.ok;
+  }
+  return { code: body.ok ? 0 : 1, body };
+}
+
+function done(agentRoot, id, flags) {
+  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 } };
+  // 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.
+  let renamed = 0;
+  try {
+    stripMarkersInPlace(found.path);
+    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 } };
+}
+
+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 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 } };
+}
+
+/**
+ * Run `maestro inbox …`. Prints one JSON document (or usage) and returns the
+ * exit code; the caller decides whether to `process.exit`.
+ *
+ * @param {string[]} argv  args after `inbox`
+ * @param {object} [deps]
+ * @param {string} [deps.agentRoot]
+ * @param {Function} [deps.deliver]        (item, text, o) → delivery result
+ * @param {Function} [deps.fetchHistory]   (params) → rows
+ * @param {number} [deps.now]
+ * @param {Function} [deps.stdout]         (string) → void
+ * @returns {Promise<number>} exit code
+ */
+export async function runInbox(argv = [], deps = {}) {
+  const write = deps.stdout || ((s) => process.stdout.write(s));
+  const { flags, pos } = parseArgs(argv);
+  const [sub, id] = pos;
+  const agentRoot = resolveAgentRoot(deps);
+  const emit = (r) => { write(JSON.stringify(r.body, null, 2) + "\n"); return r.code; };
+  if (!sub || sub === "help" || flags.help) { write(USAGE); return sub === "help" || flags.help ? 0 : 1; }
+  if (!["list", "show", "claim", "reply", "done", "defer"].includes(sub)) { write(`Unknown inbox command: ${sub}\n${USAGE}`); return 1; }
+  if (sub !== "list" && !id) return emit({ code: 1, body: { ok: false, error: `${sub} requires an <id>` } });
+  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 "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));
+    default: return 1;
+  }
+}
+
+export default { runInbox, parseUntil, USAGE };

package/lib/cli/inbox.test.mjs

@@ -0,0 +1,230 @@
+/**
+ * inbox.test.mjs — `maestro inbox list|show|claim|reply|done|defer` (design
+ * §3.3): the session's CLI over the SAME inbox state machine the daemon uses
+ * (scripts/poller/utils.mjs markers + lib/session/inbox-claims markers).
+ *
+ * Everything with an effect outside the inbox directory is injected: the
+ * delivery seam (`deliver`), message-history hydration, the clock and stdout.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { runInbox, parseUntil } from "./inbox.mjs";
+
+const T0 = Date.parse("2026-09-08T10:00:00.000Z");
+const ITEM = (id, content = "can you send me the deck?") => `id: "${id}"
+service: "cohort"
+channel: "dm/olivia"
+channel_id: "ch_1"
+channel_kind: "DM"
+sender: "Olivia Chen"
+timestamp: "2026-09-08T09:59:00.000Z"
+subject: ""
+content: |
+  ${content}
+raw_ref: "${id}"
+`;
+
+function root() {
+  const dir = mkdtempSync(join(tmpdir(), "maestro-cli-inbox-"));
+  mkdirSync(join(dir, "state", "inbox", "cohort"), { recursive: true });
+  mkdirSync(join(dir, "state", "inbox", "slack"), { recursive: true });
+  return dir;
+}
+function rm(dir) { try { rmSync(dir, { recursive: true, force: true }); } catch { /* */ } }
+function plant(dir, service, name, body) { writeFileSync(join(dir, "state", "inbox", service, name), body); }
+function ls(dir, service = "cohort") { return readdirSync(join(dir, "state", "inbox", service)).sort(); }
+
+/** Run the CLI with captured stdout; returns { code, out (parsed JSON or raw) }. */
+async function run(dir, argv, deps = {}) {
+  let out = "";
+  const code = await runInbox(argv, { agentRoot: dir, now: T0, stdout: (s) => { out += s; }, ...deps });
+  let parsed = out;
+  try { parsed = JSON.parse(out); } catch { /* raw text (help) */ }
+  return { code, out: parsed, raw: out };
+}
+
+test("list: pending items as JSON across services; --service narrows; --new hides session claims; previews are bounded", async () => {
+  const dir = root();
+  try {
+    plant(dir, "cohort", "2026-09-08T09-59-00-000Z-c-1.yaml", ITEM("c-1", "x".repeat(600)));
+    plant(dir, "cohort", "2026-09-08T09-58-00-000Z-c-0.yaml.processed", ITEM("c-0"));
+    plant(dir, "cohort", "2026-09-08T09-57-00-000Z-c-old.yaml.dispatched", ITEM("c-old"));   // daemon-owned: hidden
+    plant(dir, "cohort", "2026-09-08T09-56-00-000Z-c-mine.yaml.dispatched", ITEM("c-mine") + 'claimed_by: "session"\nclaimed_at: "2026-09-08T09:56:30.000Z"\n');
+    plant(dir, "slack", "2026-09-08T09-55-00-000Z-s-1.yaml", ITEM("s-1").replace('service: "cohort"', 'service: "slack"'));
+
+    const all = await run(dir, ["list"]);
+    assert.equal(all.code, 0);
+    // Chronological (timestamp, then id) — every planted item shares one stamp here.
+    assert.deepEqual(all.out.map((i) => [i.id, i.service, i.state]), [["c-1", "cohort", "new"], ["c-mine", "cohort", "claimed"], ["s-1", "slack", "new"]]);
+    const c1 = all.out.find((i) => i.id === "c-1");
+    assert.equal(c1.sender, "Olivia Chen");
+    assert.equal(c1.channel_id, "ch_1");
+    assert.ok(c1.preview.length <= 240, "preview is bounded");
+    assert.ok(c1.path.endsWith("c-1.yaml"));
+    assert.equal(all.out.find((i) => i.id === "c-mine").claimedAt, "2026-09-08T09:56:30.000Z");
+
+    const cohort = await run(dir, ["list", "--service", "cohort"]);
+    assert.deepEqual(cohort.out.map((i) => i.id), ["c-1", "c-mine"]);
+    const fresh = await run(dir, ["list", "--new"]);
+    assert.deepEqual(fresh.out.map((i) => i.id), ["c-1", "s-1"]);
+    const none = await run(dir, ["list", "--service", "telegram"]);
+    assert.deepEqual(none.out, []);
+  } finally { rm(dir); }
+});
+
+test("show: the full parsed item + state + markers; hydrates history when the body is empty (fail-open)", async () => {
+  const dir = root();
+  try {
+    plant(dir, "cohort", "2026-09-08T09-59-00-000Z-c-1.yaml", ITEM("c-1"));
+    const r = await run(dir, ["show", "c-1"]);
+    assert.equal(r.code, 0);
+    assert.equal(r.out.item.id, "c-1");
+    assert.equal(r.out.item.content, "can you send me the deck?");
+    assert.equal(r.out.item.is_dm, true, "channel_kind DM → enriched as a DM, the way the daemon's responder sees it");
+    assert.equal(r.out.state, "new");
+    assert.equal(r.out.service, "cohort");
+    assert.equal(r.out.history, undefined, "no hydration needed when the body is present");
+
+    // Empty body → hydrate via messaging.history through the injected seam.
+    plant(dir, "cohort", "2026-09-08T09-59-30-000Z-c-2.yaml", ITEM("c-2", "").replace("content: |\n  \n", 'content: ""\n'));
+    const calls = [];
+    const r2 = await run(dir, ["show", "c-2"], { fetchHistory: async (params) => { calls.push(params); return [{ id: "m1", body: "the actual ask" }]; } });
+    assert.equal(r2.code, 0);
+    assert.equal(calls.length, 1);
+    assert.equal(calls[0].channel, "ch_1");
+    assert.deepEqual(r2.out.history, [{ id: "m1", body: "the actual ask" }]);
+    // A throwing history seam never breaks show.
+    const r3 = await run(dir, ["show", "c-2"], { fetchHistory: async () => { throw new Error("offline"); } });
+    assert.equal(r3.code, 0);
+    assert.deepEqual(r3.out.history, []);
+    const missing = await run(dir, ["show", "ghost"]);
+    assert.equal(missing.code, 1);
+    assert.equal(missing.out.ok, false);
+  } finally { rm(dir); }
+});
+
+test("claim → reply → done: the daemon-shared state machine, with reply routed through deliver()", async () => {
+  const dir = root();
+  try {
+    plant(dir, "cohort", "2026-09-08T09-59-00-000Z-c-1.yaml", ITEM("c-1"));
+    const c = await run(dir, ["claim", "c-1"]);
+    assert.equal(c.code, 0);
+    assert.equal(c.out.ok, true);
+    assert.deepEqual(ls(dir), ["2026-09-08T09-59-00-000Z-c-1.yaml.dispatched"]);
+    assert.match(readFileSync(c.out.path, "utf-8"), /claimed_by: "session"/);
+    const twice = await run(dir, ["claim", "c-1"]);
+    assert.equal(twice.code, 1);
+    assert.equal(twice.out.error, "not-claimable");
+
+    const sends = [];
+    const deliver = async (item, text, o) => { sends.push({ item, text, o }); return { sent: true, via: "org-messaging", channel: item.channel_id }; };
+    const r = await run(dir, ["reply", "c-1", "--text", "On its way."], { deliver });
+    assert.equal(r.code, 0);
+    assert.equal(r.out.sent, true);
+    assert.equal(sends.length, 1);
+    assert.equal(sends[0].text, "On its way.");
+    assert.equal(sends[0].item.id, "c-1");
+    assert.equal(sends[0].item.service, "cohort");
+    assert.equal(sends[0].item.channel_id, "ch_1");
+    assert.equal(sends[0].item.is_dm, true, "the item is enriched the way the daemon's responder sees it");
+    assert.equal(sends[0].o.kind, "reply");
+    // A successful reply is recorded ON the item so the assurance sweep never re-answers it.
+    assert.match(readFileSync(c.out.path, "utf-8"), /replied_at: "2026-09-08T10:00:00\.000Z"/);
+    assert.match(readFileSync(c.out.path, "utf-8"), /claimed_by: "session"/, "the claim survives the reply stamp");
+
+    // --file reads the reply body from disk.
+    writeFileSync(join(dir, "reply.md"), "Attached below.\n");
+    const rf = await run(dir, ["reply", "c-1", "--file", join(dir, "reply.md")], { deliver });
+    assert.equal(rf.code, 0);
+    assert.equal(sends[1].text, "Attached below.");
+    // A failed delivery is reported and exits 1 — the item is NOT marked done.
+    const bad = await run(dir, ["reply", "c-1", "--text", "x"], { deliver: async () => ({ sent: false, via: null, error: "send-gate blocked" }) });
+    assert.equal(bad.code, 1);
+    assert.equal(bad.out.error, "send-gate blocked");
+    assert.deepEqual(ls(dir), ["2026-09-08T09-59-00-000Z-c-1.yaml.dispatched"]);
+    // Empty text is refused before touching the seam.
+    const empty = await run(dir, ["reply", "c-1", "--text", "   "], { deliver });
+    assert.equal(empty.code, 1);
+    assert.equal(sends.length, 2);
+
+    const d = await run(dir, ["done", "c-1"]);
+    assert.equal(d.code, 0);
+    assert.equal(d.out.ok, true);
+    assert.deepEqual(ls(dir), ["2026-09-08T09-59-00-000Z-c-1.yaml.processed"]);
+    const again = await run(dir, ["done", "c-1"]);
+    assert.equal(again.code, 1, "already terminal");
+  } finally { rm(dir); }
+});
+
+test("defer: --until accepts +30m / +2h / ISO; parks the item with reason; the sweep reopens it when due", async () => {
+  const dir = root();
+  try {
+    assert.equal(parseUntil("+30m", T0), T0 + 30 * 60_000);
+    assert.equal(parseUntil("+2h", T0), T0 + 2 * 3_600_000);
+    assert.equal(parseUntil("+1d", T0), T0 + 86_400_000);
+    assert.equal(parseUntil("2026-09-08T12:00:00Z", T0), Date.parse("2026-09-08T12:00:00Z"));
+    assert.equal(parseUntil("soon", T0), null);
+    assert.equal(parseUntil("+5x", T0), null);
+
+    plant(dir, "cohort", "2026-09-08T09-59-00-000Z-c-1.yaml", ITEM("c-1"));
+    const r = await run(dir, ["defer", "c-1", "--until", "+30m", "--reason", "waiting on finance"]);
+    assert.equal(r.code, 0);
+    assert.equal(r.out.ok, true);
+    assert.equal(r.out.until, new Date(T0 + 30 * 60_000).toISOString());
+    assert.deepEqual(ls(dir), ["2026-09-08T09-59-00-000Z-c-1.yaml.deferred"]);
+    assert.match(readFileSync(r.out.path, "utf-8"), /deferred_reason: "waiting on finance"/);
+    const bad = await run(dir, ["defer", "c-1", "--until", "whenever"]);
+    assert.equal(bad.code, 1);
+    const noUntil = await run(dir, ["defer", "c-1"]);
+    assert.equal(noUntil.code, 1);
+    // A parked item can still be finished: .deferred → .processed, markers stripped.
+    const d = await run(dir, ["done", "c-1"]);
+    assert.equal(d.code, 0);
+    assert.deepEqual(ls(dir), ["2026-09-08T09-59-00-000Z-c-1.yaml.processed"]);
+    assert.doesNotMatch(readFileSync(join(dir, "state/inbox/cohort", ls(dir)[0]), "utf-8"), /deferred_until/);
+  } finally { rm(dir); }
+});
+
+test("usage: unknown/missing subcommand prints help and exits 1; ids are required", async () => {
+  const dir = root();
+  try {
+    const h = await run(dir, []);
+    assert.equal(h.code, 1);
+    assert.match(h.raw, /maestro inbox (list|show)/);
+    assert.equal((await run(dir, ["bogus"])).code, 1);
+    const noId = await run(dir, ["show"]);
+    assert.equal(noId.code, 1);
+    assert.equal(noId.out.ok, false);
+  } finally { rm(dir); }
+});
+
+test("claim/done touch ONLY the named item: look-alike ids (m1 vs m10) are never renamed alongside it", async () => {
+  const dir = root();
+  try {
+    for (const id of ["cohort-m1", "cohort-m10", "cohort-m11"]) plant(dir, "cohort", `2026-09-08T09-59-00-000Z-${id}.yaml`, ITEM(id));
+    const c = await run(dir, ["claim", "cohort-m1"]);
+    assert.equal(c.code, 0);
+    assert.deepEqual(ls(dir), [
+      "2026-09-08T09-59-00-000Z-cohort-m1.yaml.dispatched",
+      "2026-09-08T09-59-00-000Z-cohort-m10.yaml",
+      "2026-09-08T09-59-00-000Z-cohort-m11.yaml",
+    ]);
+    const d = await run(dir, ["done", "cohort-m1"]);
+    assert.equal(d.code, 0);
+    assert.equal(d.out.renamed, 1);
+    assert.deepEqual(ls(dir), [
+      "2026-09-08T09-59-00-000Z-cohort-m1.yaml.processed",
+      "2026-09-08T09-59-00-000Z-cohort-m10.yaml",
+      "2026-09-08T09-59-00-000Z-cohort-m11.yaml",
+    ]);
+    // A truncated id that could mean several items is refused, not guessed.
+    const amb = await run(dir, ["claim", "m1"]);
+    assert.equal(amb.code, 1);
+    assert.equal(amb.out.error, "not-found");
+  } finally { rm(dir); }
+});

package/lib/cli/session-ack.mjs

@@ -0,0 +1,63 @@
+/**
+ * lib/cli/session-ack.mjs — `maestro session ack <tickId> [--result <path>]`
+ * (design §3.4): the main session reports a handed-off cadence tick as done.
+ *
+ * Moves `state/session/handoffs/<tickId>.json` to `handoffs/done/` with
+ * `status:"acked"`, so the consumer's timeout sweep no longer re-enqueues it.
+ * Idempotent. Exposed as `ackHandoff` for WP-M3's `lib/cli/session.mjs`
+ * (`case "ack"`) and reachable directly as `maestro session-ack` until that
+ * lands.
+ *
+ * @module lib/cli/session-ack
+ */
+
+import { ackHandoff as ackHandoffRecord, listHandoffs } from "../session/handoffs.mjs";
+
+export const USAGE = `Usage:
+  maestro session ack <tickId> [--result <path>] [--note "…"]
+`;
+
+/**
+ * Ack one handoff. Returns the ledger result; never throws.
+ * @param {{agentRoot?:string, tickId:string, resultPath?:string, note?:string, now?:number}} o
+ * @returns {{ok:true, path:string, already?:boolean}|{ok:false, error:string}}
+ */
+export function ackHandoff(o = {}) {
+  const agentRoot = o.agentRoot || process.env.AGENT_ROOT || process.env.AGENT_DIR || process.cwd();
+  if (!o.tickId) return { ok: false, error: "tickId required" };
+  return ackHandoffRecord(agentRoot, o.tickId, { resultPath: o.resultPath, note: o.note, now: o.now });
+}
+
+/**
+ * Run `maestro session ack …` (argv after `ack`). Prints one JSON document
+ * and returns the exit code. `--list` prints the open handoffs instead.
+ * @param {string[]} argv
+ * @param {{agentRoot?:string, now?:number, stdout?:Function}} [deps]
+ * @returns {Promise<number>}
+ */
+export async function runSessionAck(argv = [], deps = {}) {
+  const write = deps.stdout || ((s) => process.stdout.write(s));
+  const agentRoot = deps.agentRoot || process.env.AGENT_ROOT || process.env.AGENT_DIR || process.cwd();
+  let tickId = null;
+  let resultPath;
+  let note;
+  let list = false;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--result") { resultPath = argv[++i]; continue; }
+    if (a === "--note") { note = argv[++i]; continue; }
+    if (a === "--list") { list = true; continue; }
+    if (a === "--help" || a === "-h") { write(USAGE); return 0; }
+    if (!a.startsWith("--") && !tickId) tickId = a;
+  }
+  if (list) {
+    write(JSON.stringify(listHandoffs(agentRoot).map(({ path: _p, ...h }) => { void _p; return h; }), null, 2) + "\n");
+    return 0;
+  }
+  if (!tickId) { write(USAGE); return 1; }
+  const r = ackHandoff({ agentRoot, tickId, resultPath, note, now: deps.now });
+  write(JSON.stringify({ tickId, ...r }, null, 2) + "\n");
+  return r.ok ? 0 : 1;
+}
+
+export default { ackHandoff, runSessionAck, USAGE };

package/lib/cli/session-ack.test.mjs

@@ -0,0 +1,63 @@
+/**
+ * session-ack.test.mjs — `maestro session ack <tickId>` moves a handoff to
+ * done/ (design §3.4). The function form is what WP-M3's session CLI calls.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { writeHandoff, handoffPaths, listHandoffs } from "../session/handoffs.mjs";
+import { ackHandoff, runSessionAck } from "./session-ack.mjs";
+
+const T0 = Date.parse("2026-09-08T10:00:00.000Z");
+function root() { return mkdtempSync(join(tmpdir(), "maestro-session-ack-")); }
+function rm(dir) { try { rmSync(dir, { recursive: true, force: true }); } catch { /* */ } }
+async function run(dir, argv) {
+  let out = "";
+  const code = await runSessionAck(argv, { agentRoot: dir, now: T0 + 60_000, stdout: (s) => { out += s; } });
+  let parsed = out;
+  try { parsed = JSON.parse(out); } catch { /* usage text */ }
+  return { code, out: parsed, raw: out };
+}
+
+test("ackHandoff: acks an open handoff (function form for the session CLI); idempotent; unknown → not-found", () => {
+  const dir = root();
+  try {
+    writeHandoff(dir, { tickId: "evt-1", cadence: "goal-steward", mode: "escalate", promptPath: "/p" }, { now: T0 });
+    const r = ackHandoff({ agentRoot: dir, tickId: "evt-1", resultPath: "/tmp/r.md", now: T0 + 1000 });
+    assert.equal(r.ok, true);
+    assert.deepEqual(listHandoffs(dir), []);
+    const done = JSON.parse(readFileSync(join(handoffPaths(dir).done, "evt-1.json"), "utf-8"));
+    assert.equal(done.status, "acked");
+    assert.equal(done.resultPath, "/tmp/r.md");
+    assert.equal(ackHandoff({ agentRoot: dir, tickId: "evt-1" }).already, true);
+    assert.equal(ackHandoff({ agentRoot: dir, tickId: "evt-x" }).error, "not-found");
+    assert.equal(ackHandoff({ agentRoot: dir }).ok, false);
+  } finally { rm(dir); }
+});
+
+test("runSessionAck: CLI form prints JSON and exits 0/1; --list shows open handoffs; usage without an id", async () => {
+  const dir = root();
+  try {
+    writeHandoff(dir, { tickId: "evt-2", cadence: "daily-morning-brief", mode: "escalate", promptPath: "/p" }, { now: T0 });
+    const l = await run(dir, ["--list"]);
+    assert.equal(l.code, 0);
+    assert.deepEqual(l.out.map((h) => h.tickId), ["evt-2"]);
+    assert.equal(l.out[0].path, undefined, "no absolute ledger path in the listing");
+    const ok = await run(dir, ["evt-2", "--result", "/tmp/out.md", "--note", "done"]);
+    assert.equal(ok.code, 0);
+    assert.equal(ok.out.ok, true);
+    assert.equal(ok.out.tickId, "evt-2");
+    assert.equal(existsSync(join(handoffPaths(dir).done, "evt-2.json")), true);
+    assert.equal(JSON.parse(readFileSync(join(handoffPaths(dir).done, "evt-2.json"), "utf-8")).note, "done");
+    const missing = await run(dir, ["evt-nope"]);
+    assert.equal(missing.code, 1);
+    assert.equal(missing.out.error, "not-found");
+    const usage = await run(dir, []);
+    assert.equal(usage.code, 1);
+    assert.match(usage.raw, /maestro session ack/);
+  } finally { rm(dir); }
+});