@cohortapp/agent-sdk 2.11.15 → 2.13.0

package/lib/cli/board.mjs

@@ -0,0 +1,285 @@
+/**
+ * lib/cli/board.mjs — `maestro board mine|track|claim|complete`.
+ *
+ * The session-side CLI over the board client (design spec 2026-09-08 §3.5):
+ *
+ *   maestro board mine [--json]                     my items across every board
+ *   maestro board track <inbox-id> --stage <s> [--title …] [--why …] [--note …]
+ *                                                   file/advance an inbound ask on its board
+ *   maestro board claim <itemId>                    claim a ready item (server resolves races)
+ *   maestro board complete <itemId> [--note …]      close a claimed item
+ *
+ * `track` reads the inbox item under state/inbox/cohort/ by id (live,
+ * .dispatched or .processed) and lets the SERVER derive the board from the
+ * message identity — the same seam the daemon's work-ledger uses, so the
+ * session and the daemon land on the same row. `mine` reads live and falls
+ * back to the daemon's 5-minute cache (state/org/board-mine.json) when the
+ * live read is empty or the org is off.
+ *
+ * `runBoard(argv, deps)` is the testable core (every I/O injectable);
+ * `boardCmd(argv)` is the bin entry that resolves the agent root and config.
+ * Expected failures are printed and become exit 1; nothing throws.
+ *
+ * @module lib/cli/board
+ */
+
+"use strict";
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { loadOrgConfig, configFromAgent, isEnabled, listMine, trackWork, claimItem, completeItem } from "../org/client.mjs";
+import { WORK_STAGES, cohortChannelId, cohortMessageId } from "../org/work-ledger.mjs";
+
+/** The ladder `track` accepts on the command line (the ledger's, minus nothing). */
+export const TRACK_STAGES = WORK_STAGES;
+
+export function usage() {
+  return [
+    "Usage:",
+    "  maestro board mine [--json]                     Items assigned to you (or awaiting your review) across every board",
+    "  maestro board track <inbox-id> --stage <stage> [--title T] [--why W] [--note N]",
+    `                                                  File or advance an inbound ask on its board. stage: ${TRACK_STAGES.join("|")}`,
+    "  maestro board claim <itemId>                    Claim a ready board item",
+    "  maestro board complete <itemId> [--note N]      Close a claimed item (note becomes proof.note)",
+    "",
+    "The inbox id is the `id` of the item under state/inbox/cohort/ (e.g. cohort-<messageId>),",
+    "as printed by `maestro inbox list`. The board itself is derived server-side from the message.",
+  ].join("\n");
+}
+
+/** Parse argv → {sub, id, json, stage, title, why, note, help, error}. Pure. */
+export function parseBoardArgs(argv) {
+  const args = Array.isArray(argv) ? argv.map(String) : [];
+  const out = { sub: null, id: null, json: false, stage: null, title: null, why: null, note: null, help: false, error: null };
+  if (args.length === 0 || args.includes("--help") || args.includes("-h")) { out.help = true; return out; }
+  out.sub = args[0];
+  const rest = args.slice(1);
+  const positional = [];
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    const eq = a.indexOf("=");
+    const key = a.startsWith("--") && eq > 0 ? a.slice(0, eq) : a;
+    const inline = a.startsWith("--") && eq > 0 ? a.slice(eq + 1) : undefined;
+    const take = () => (inline !== undefined ? inline : rest[++i]);
+    if (key === "--json") out.json = true;
+    else if (key === "--stage") out.stage = take() ?? null;
+    else if (key === "--title") out.title = take() ?? null;
+    else if (key === "--why") out.why = take() ?? null;
+    else if (key === "--note") out.note = take() ?? null;
+    else if (a.startsWith("-")) { out.error = `unknown flag ${a}`; return out; }
+    else positional.push(a);
+  }
+  out.id = positional[0] || null;
+  switch (out.sub) {
+    case "mine":
+      break;
+    case "track":
+      if (!out.id) out.error = "track needs an <inbox-id>";
+      else if (!out.stage) out.error = "track needs --stage";
+      else if (!TRACK_STAGES.includes(out.stage)) out.error = `--stage must be one of ${TRACK_STAGES.join("|")}`;
+      break;
+    case "claim":
+    case "complete":
+      if (!out.id) out.error = `${out.sub} needs an <itemId>`;
+      break;
+    default:
+      out.error = `unknown board command: ${out.sub}`;
+  }
+  return out;
+}
+
+/**
+ * Pick the inbox file that carries `id` from a directory listing. Prefers the
+ * live `.yaml`, then `.dispatched` (in flight), then `.processed` (done — a
+ * `track --stage done` after the reply is the common case). The id must match
+ * as a whole token (`-<id>.yaml`), so `cohort-m1` never picks `cohort-m10`.
+ * @param {string[]} files
+ * @param {string} id
+ * @returns {string|null}
+ */
+export function findInboxItemFile(files, id) {
+  const needle = String(id || "");
+  if (!needle) return null;
+  const list = Array.isArray(files) ? files : [];
+  const hit = (suffix) => list.find((f) => f.endsWith(`-${needle}.yaml${suffix}`) || f === `${needle}.yaml${suffix}`) || null;
+  return hit("") || hit(".dispatched") || hit(".deferred") || hit(".processed") || hit(".processed-bundled");
+}
+
+/**
+ * The board.track params for an inbox item. Identity (channel + message id)
+ * comes from the item exactly as the daemon's ledger derives it, so the
+ * session and the daemon compute the same server-side row key. Pure.
+ * @returns {{ok:true, params:object, idempotencyKey:string}|{ok:false, error:string}}
+ */
+export function buildTrackParams(item, o = {}) {
+  const stage = String(o.stage || "");
+  if (!TRACK_STAGES.includes(stage)) return { ok: false, error: `stage must be one of ${TRACK_STAGES.join("|")}` };
+  const channelId = cohortChannelId(item);
+  if (!channelId) return { ok: false, error: "not a Cohort conversation — only Cohort asks have a board to land on" };
+  const messageId = cohortMessageId(item);
+  if (!messageId) return { ok: false, error: "inbox item carries no message id" };
+  const params = { service: "cohort", channelId, messageId, stage };
+  const body = item && (item.content || item.text || item.subject);
+  if (body) params.body = String(body).slice(0, 20000);
+  if (item && item.priority_signals && item.priority_signals.mentions_agent) params.directed = true;
+  if (o.title) params.title = String(o.title).slice(0, 200);
+  if (o.why) params.why = String(o.why).slice(0, 1000);
+  if (o.note) params.note = String(o.note).slice(0, 4000);
+  return { ok: true, params, idempotencyKey: `board.track:${channelId}:${messageId}:${stage}` };
+}
+
+/** One line per item for a terminal. */
+export function formatMine(items, o = {}) {
+  const list = Array.isArray(items) ? items : [];
+  if (list.length === 0) return o.cached ? "Nothing assigned to you (cached)." : "Nothing assigned to you across any board.";
+  const lines = list.map((it) => {
+    const pri = it.priority ? String(it.priority).padEnd(2) : "  ";
+    const col = it.col || it.stage || "?";
+    const board = it.boardName || it.boardId || "";
+    const due = it.dueAt ? `  due ${String(it.dueAt).slice(0, 10)}` : "";
+    return `${pri}  ${it.itemId || it.id || "?"}  [${col}]  ${it.title || "(untitled)"}${board ? `  — ${board}` : ""}${due}`;
+  });
+  if (o.cached) lines.push(`(cached ${o.fetchedAt || "earlier"} by the daemon; the live read was empty)`);
+  return lines.join("\n");
+}
+
+function readBoardMineCache(agentRoot) {
+  try {
+    const p = join(String(agentRoot || ""), "state", "org", "board-mine.json");
+    if (!existsSync(p)) return null;
+    const doc = JSON.parse(readFileSync(p, "utf8"));
+    const items = Array.isArray(doc) ? doc : doc && Array.isArray(doc.items) ? doc.items : null;
+    if (!items) return null;
+    // The daemon writes {ts, items} (lib/org/board-mine-cache.mjs); fetchedAt is the earlier spelling.
+    const fetchedAt = doc && typeof doc.fetchedAt === "string" ? doc.fetchedAt : doc && typeof doc.ts === "string" ? doc.ts : null;
+    return { items, fetchedAt };
+  } catch {
+    return null; // a corrupt cache is the same as no cache
+  }
+}
+
+/**
+ * Load + parse an inbox item by id. Uses the poller's own YAML reader.
+ *
+ * The daemon retires items by RENAME (.yaml → .yaml.dispatched → .processed),
+ * and `board track --stage done` right after a reply is exactly when that
+ * happens — so a listing can name a file the read no longer finds. An ENOENT
+ * on the read re-lists (a few times) instead of surfacing as an error; an item
+ * that is gone for good is the ordinary "not found".
+ */
+async function loadInboxItem(agentRoot, id, deps) {
+  const dir = join(String(agentRoot || ""), "state", "inbox", "cohort");
+  const list = deps.readdirImpl || ((d) => (existsSync(d) ? readdirSync(d) : []));
+  const read = deps.readFileImpl || ((p) => readFileSync(p, "utf8"));
+  const parse = deps.parseInboxItem || (await import("../../scripts/poller/inbox-scan-poller.mjs")).parseInboxItemYaml;
+  for (let attempt = 0; attempt < 3; attempt++) {
+    let files = [];
+    try {
+      files = list(dir) || [];
+    } catch {
+      files = []; // unreadable inbox dir → "not found" below
+    }
+    const file = findInboxItemFile(files, id);
+    if (!file) return null;
+    let text;
+    try {
+      text = read(join(dir, file));
+    } catch (err) {
+      if (err && err.code === "ENOENT") continue; // renamed under us: re-list
+      throw err;
+    }
+    const item = parse(text);
+    if (item && !item.id) item.id = id;
+    return item;
+  }
+  return null;
+}
+
+function fmtErr(frame) {
+  const e = frame && frame.error ? frame.error : null;
+  return e ? `${e.code || "error"}: ${e.message || ""}`.trim() : "no response";
+}
+
+/**
+ * The testable core. deps: { agentRoot, cfg, write, listMineImpl, trackImpl,
+ * claimImpl, completeImpl, fetchImpl, parseInboxItem, readdirImpl, readFileImpl }.
+ * @returns {Promise<{code:number}>}
+ */
+export async function runBoard(argv, deps = {}) {
+  const write = typeof deps.write === "function" ? deps.write : (s) => process.stdout.write(`${s}\n`);
+  const p = parseBoardArgs(argv);
+  if (p.help) { write(usage()); return { code: 0 }; }
+  if (p.error) { write(`error: ${p.error}\n\n${usage()}`); return { code: 1 }; }
+  const agentRoot = deps.agentRoot || process.cwd();
+  const cfg = deps.cfg || loadOrgConfig(agentRoot);
+  const enabled = isEnabled(cfg);
+  const conn = enabled ? configFromAgent(cfg) : { base: "", token: "", orgId: "" };
+  const callOpts = { base: conn.base, token: conn.token, orgId: conn.orgId, fetchImpl: deps.fetchImpl };
+
+  try {
+    if (p.sub === "mine") {
+      let items = [];
+      if (enabled) items = await (deps.listMineImpl || listMine)(callOpts);
+      let cached = false;
+      let fetchedAt = null;
+      if (!Array.isArray(items) || items.length === 0) {
+        const cache = readBoardMineCache(agentRoot);
+        if (cache && cache.items.length > 0) { items = cache.items; cached = true; fetchedAt = cache.fetchedAt; }
+        else items = [];
+      }
+      write(p.json ? JSON.stringify(items, null, 2) : formatMine(items, { cached, fetchedAt }));
+      return { code: 0 };
+    }
+
+    if (!enabled) { write("error: the org (Cohort) is not enabled for this agent — run `maestro setup --only org`."); return { code: 1 }; }
+
+    if (p.sub === "track") {
+      const item = await loadInboxItem(agentRoot, p.id, deps);
+      if (!item) { write(`error: no inbox item ${p.id} under state/inbox/cohort/ (see \`maestro inbox list\`)`); return { code: 1 }; }
+      const built = buildTrackParams(item, { stage: p.stage, title: p.title, why: p.why, note: p.note });
+      if (!built.ok) { write(`error: ${built.error}`); return { code: 1 }; }
+      const frame = await (deps.trackImpl || trackWork)(built.params, { ...callOpts, idempotencyKey: built.idempotencyKey });
+      if (!frame || !frame.ok) { write(`error: board.track failed — ${fmtErr(frame)}`); return { code: 1 }; }
+      const r = frame.result || {};
+      write(p.json ? JSON.stringify(r, null, 2) : `tracked ${p.stage}: task ${r.taskId || "?"}${r.col ? ` [${r.col}]` : ""}${r.created ? " (opened)" : ""}${r.moved ? " (moved)" : ""}`);
+      return { code: 0 };
+    }
+
+    if (p.sub === "claim") {
+      const frame = await (deps.claimImpl || claimItem)({ itemId: p.id }, { ...callOpts, idempotencyKey: `board.claim:${p.id}` });
+      if (!frame || !frame.ok) { write(`error: board.claim failed — ${fmtErr(frame)}`); return { code: 1 }; }
+      write(p.json ? JSON.stringify(frame.result || {}, null, 2) : `claimed ${p.id}`);
+      return { code: 0 };
+    }
+
+    if (p.sub === "complete") {
+      const params = { itemId: p.id };
+      if (p.note) params.proof = { note: String(p.note) };
+      const frame = await (deps.completeImpl || completeItem)(params, { ...callOpts, idempotencyKey: `board.complete:${p.id}` });
+      if (!frame || !frame.ok) { write(`error: board.complete failed — ${fmtErr(frame)}`); return { code: 1 }; }
+      write(p.json ? JSON.stringify(frame.result || {}, null, 2) : `completed ${p.id}`);
+      return { code: 0 };
+    }
+  } catch (err) {
+    write(`error: ${err && err.message ? err.message : String(err)}`);
+    return { code: 1 };
+  }
+  write(usage());
+  return { code: 1 };
+}
+
+/** bin entry: resolve the agent root (env → walk → machine pointer) and run. */
+export async function boardCmd(argv) {
+  let agentRoot = null;
+  try {
+    const { resolveAgentRoot } = await import("../collective/config.mjs");
+    agentRoot = resolveAgentRoot(process.cwd());
+  } catch {
+    agentRoot = null; // fall through to cwd
+  }
+  const r = await runBoard(argv, { agentRoot: agentRoot || process.cwd() });
+  process.exitCode = r.code;
+  return r;
+}
+
+export default { runBoard, boardCmd, parseBoardArgs, findInboxItemFile, buildTrackParams, formatMine, usage, TRACK_STAGES };

package/lib/cli/board.test.mjs

@@ -0,0 +1,227 @@
+/**
+ * board.test.mjs — `maestro board mine|track|claim|complete`.
+ * Run: node --test lib/cli/board.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+
+import { parseBoardArgs, findInboxItemFile, buildTrackParams, runBoard, formatMine, usage } from "./board.mjs";
+
+const CFG = { org: { cohort: { enabled: true, base: "https://org.example", orgId: "acme", token: "nlk_secret" } } };
+
+test("parseBoardArgs: subcommands, flags, errors", () => {
+  assert.deepEqual(parseBoardArgs(["mine"]).sub, "mine");
+  assert.equal(parseBoardArgs(["mine", "--json"]).json, true);
+  const t = parseBoardArgs(["track", "cohort-m1", "--stage", "accepted", "--title", "Build the deck", "--why", "asked in DM"]);
+  assert.equal(t.sub, "track");
+  assert.equal(t.id, "cohort-m1");
+  assert.equal(t.stage, "accepted");
+  assert.equal(t.title, "Build the deck");
+  assert.equal(t.why, "asked in DM");
+  assert.equal(parseBoardArgs(["track", "cohort-m1", "--stage=done"]).stage, "done");
+  assert.equal(parseBoardArgs(["claim", "item_1"]).id, "item_1");
+  const c = parseBoardArgs(["complete", "item_1", "--note", "shipped"]);
+  assert.equal(c.sub, "complete");
+  assert.equal(c.note, "shipped");
+  assert.equal(parseBoardArgs([]).help, true);
+  assert.equal(parseBoardArgs(["--help"]).help, true);
+  assert.match(parseBoardArgs(["track"]).error, /inbox-id/);
+  assert.match(parseBoardArgs(["track", "x"]).error, /--stage/);
+  assert.match(parseBoardArgs(["track", "x", "--stage", "later"]).error, /accepted\|working\|blocked\|review\|done/);
+  assert.match(parseBoardArgs(["claim"]).error, /itemId/);
+  assert.match(parseBoardArgs(["frobnicate"]).error, /unknown/i);
+});
+
+test("findInboxItemFile: prefers live .yaml, then .dispatched, then .processed; null when absent", () => {
+  const files = ["2026-09-08T10-00-00-cohort-m1.yaml.processed", "2026-09-08T10-00-00-cohort-m1.yaml.dispatched", "2026-09-08T10-00-00-cohort-m2.yaml"];
+  assert.equal(findInboxItemFile(files, "cohort-m1"), "2026-09-08T10-00-00-cohort-m1.yaml.dispatched");
+  assert.equal(findInboxItemFile(files, "cohort-m2"), "2026-09-08T10-00-00-cohort-m2.yaml");
+  assert.equal(findInboxItemFile(["2026-09-08T10-00-00-cohort-m1.yaml.processed"], "cohort-m1"), "2026-09-08T10-00-00-cohort-m1.yaml.processed");
+  assert.equal(findInboxItemFile(files, "cohort-m9"), null);
+  assert.equal(findInboxItemFile(files, ""), null);
+  // Does not match a longer id by substring (m1 vs m10).
+  assert.equal(findInboxItemFile(["x-cohort-m10.yaml"], "cohort-m1"), null);
+});
+
+test("buildTrackParams: identity from the inbox item, stage/title/why passthrough, non-cohort rejected", () => {
+  const item = { id: "cohort-m1", service: "cohort", cohort_channel_id: "C1", raw_ref: "cohort:messaging:m1:7", content: "please build the deck" };
+  const r = buildTrackParams(item, { stage: "accepted", title: "Build the deck", why: "asked in DM" });
+  assert.equal(r.ok, true);
+  assert.equal(r.params.service, "cohort");
+  assert.equal(r.params.channelId, "C1");
+  assert.equal(r.params.messageId, "m1");
+  assert.equal(r.params.stage, "accepted");
+  assert.equal(r.params.title, "Build the deck");
+  assert.equal(r.params.why, "asked in DM");
+  assert.equal(r.params.body, "please build the deck");
+  assert.equal(r.idempotencyKey, "board.track:C1:m1:accepted");
+  const slack = buildTrackParams({ id: "slack-1", service: "slack", channel_id: "C9" }, { stage: "accepted" });
+  assert.equal(slack.ok, false);
+  assert.match(slack.error, /cohort/i);
+  const noStage = buildTrackParams(item, { stage: "later" });
+  assert.equal(noStage.ok, false);
+});
+
+test("formatMine: one line per item, priority/board/col visible; empty → a plain sentence", () => {
+  const out = formatMine([
+    { itemId: "i1", title: "Build the deck", boardName: "Sales", col: "doing", priority: "P1", dueAt: "2026-09-10T00:00:00Z" },
+    { itemId: "i2", title: "Reply to Marc", boardName: "DM: Marc", col: "todo", priority: "P2" },
+  ]);
+  const lines = out.split("\n");
+  assert.equal(lines.length, 2);
+  assert.match(lines[0], /P1/);
+  assert.match(lines[0], /Build the deck/);
+  assert.match(lines[0], /Sales/);
+  assert.match(lines[0], /doing/);
+  assert.match(lines[0], /i1/);
+  assert.match(formatMine([]), /nothing assigned|no items/i);
+  assert.match(usage(), /maestro board mine/);
+});
+
+test("runBoard mine: live read via listMineImpl; --json prints the array; falls back to the cache when the read is empty and the cache exists", async () => {
+  const root = mkdtempSync(join(tmpdir(), "board-cli-"));
+  try {
+    const out = [];
+    const deps = { agentRoot: root, cfg: CFG, listMineImpl: async () => [{ itemId: "i1", title: "Deck", col: "doing", priority: "P1" }], write: (s) => out.push(s) };
+    const r = await runBoard(["mine"], deps);
+    assert.equal(r.code, 0);
+    assert.match(out.join("\n"), /Deck/);
+    out.length = 0;
+    const rj = await runBoard(["mine", "--json"], deps);
+    assert.equal(rj.code, 0);
+    assert.deepEqual(JSON.parse(out.join("")), [{ itemId: "i1", title: "Deck", col: "doing", priority: "P1" }]);
+    // Empty live read + a daemon cache → the cache (marked as such).
+    mkdirSync(join(root, "state", "org"), { recursive: true });
+    writeFileSync(join(root, "state", "org", "board-mine.json"), JSON.stringify({ items: [{ itemId: "c1", title: "Cached item" }], fetchedAt: "2026-09-08T11:00:00Z" }));
+    out.length = 0;
+    const rc = await runBoard(["mine"], { ...deps, listMineImpl: async () => [] });
+    assert.equal(rc.code, 0);
+    assert.match(out.join("\n"), /Cached item/);
+    assert.match(out.join("\n"), /cached/i);
+    // Org disabled → [] and exit 0 (fail-open), never a crash.
+    out.length = 0;
+    const off = await runBoard(["mine", "--json"], { ...deps, cfg: { org: { cohort: { enabled: false } } }, listMineImpl: async () => { throw new Error("must not be called"); } });
+    assert.equal(off.code, 0);
+    assert.deepEqual(JSON.parse(out.join("")), [{ itemId: "c1", title: "Cached item" }], "cache still served when the org is off");
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("runBoard track: reads the inbox item by id from state/inbox/cohort, calls board.track with stage/title/why", async () => {
+  const root = mkdtempSync(join(tmpdir(), "board-cli-"));
+  try {
+    const dir = join(root, "state", "inbox", "cohort");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "2026-09-08T10-00-00-cohort-m1.yaml.dispatched"), [
+      "id: cohort-m1",
+      "service: cohort",
+      "channel_id: C1",
+      "raw_ref: cohort:messaging:m1:7",
+      "sender: Marc",
+      "content: |",
+      "  please build the deck",
+      "",
+    ].join("\n"));
+    const calls = [];
+    const out = [];
+    const deps = {
+      agentRoot: root, cfg: CFG, write: (s) => out.push(s),
+      trackImpl: async (params, o) => { calls.push({ params, o }); return { ok: true, result: { tracked: true, taskId: "t1", col: "todo", created: true } }; },
+    };
+    const r = await runBoard(["track", "cohort-m1", "--stage", "accepted", "--title", "Build the deck", "--why", "asked in DM"], deps);
+    assert.equal(r.code, 0, out.join("\n"));
+    assert.equal(calls.length, 1);
+    assert.equal(calls[0].params.channelId, "C1");
+    assert.equal(calls[0].params.messageId, "m1");
+    assert.equal(calls[0].params.stage, "accepted");
+    assert.equal(calls[0].params.title, "Build the deck");
+    assert.equal(calls[0].params.why, "asked in DM");
+    assert.equal(calls[0].o.idempotencyKey, "board.track:C1:m1:accepted");
+    assert.equal(calls[0].o.base, "https://org.example");
+    assert.match(out.join("\n"), /t1/);
+    // Unknown id → exit 1 with a clear message, no call.
+    out.length = 0;
+    const miss = await runBoard(["track", "cohort-nope", "--stage", "done"], deps);
+    assert.equal(miss.code, 1);
+    assert.match(out.join("\n"), /cohort-nope/);
+    assert.equal(calls.length, 1);
+    // Server error frame → exit 1, message shown.
+    const err = await runBoard(["track", "cohort-m1", "--stage", "done"], { ...deps, trackImpl: async () => ({ ok: false, error: { code: "FORBIDDEN_SCOPE", message: "nope" } }) });
+    assert.equal(err.code, 1);
+    assert.match(out.join("\n"), /FORBIDDEN_SCOPE/);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("runBoard claim/complete: route to the client with a stable idempotency key; --note wraps into proof.note", async () => {
+  const calls = [];
+  const out = [];
+  const deps = {
+    agentRoot: "/tmp/none", cfg: CFG, write: (s) => out.push(s),
+    claimImpl: async (params, o) => { calls.push({ name: "claim", params, o }); return { ok: true, result: { itemId: params.itemId, leaseToken: "L" } }; },
+    completeImpl: async (params, o) => { calls.push({ name: "complete", params, o }); return { ok: true, result: { itemId: params.itemId, status: "done" } }; },
+  };
+  assert.equal((await runBoard(["claim", "item_1"], deps)).code, 0);
+  assert.equal(calls[0].params.itemId, "item_1");
+  assert.equal(calls[0].o.idempotencyKey, "board.claim:item_1");
+  assert.equal((await runBoard(["complete", "item_1", "--note", "shipped v2"], deps)).code, 0);
+  assert.deepEqual(calls[1].params, { itemId: "item_1", proof: { note: "shipped v2" } });
+  assert.equal((await runBoard(["complete", "item_2"], deps)).code, 0);
+  assert.deepEqual(calls[2].params, { itemId: "item_2" });
+  // A CONFLICT (someone else won the race) is exit 1 and says so.
+  const lost = await runBoard(["claim", "item_1"], { ...deps, claimImpl: async () => ({ ok: false, error: { code: "CONFLICT", message: "already claimed" } }) });
+  assert.equal(lost.code, 1);
+  assert.match(out.join("\n"), /CONFLICT/);
+  // Org disabled → exit 1 with a reason, never a throw.
+  const off = await runBoard(["claim", "item_1"], { ...deps, cfg: { org: { cohort: { enabled: false } } } });
+  assert.equal(off.code, 1);
+  assert.match(out.join("\n"), /org|cohort/i);
+  // --help → exit 0 + usage.
+  out.length = 0;
+  assert.equal((await runBoard(["--help"], deps)).code, 0);
+  assert.match(out.join("\n"), /maestro board/);
+});
+
+test("bin: `maestro board --help` dispatches to lib/cli/board and exits 0", () => {
+  const cli = new URL("../../bin/maestro.mjs", import.meta.url).pathname;
+  const r = spawnSync(process.execPath, [cli, "board", "--help"], { encoding: "utf8" });
+  assert.equal(r.status, 0, r.stderr);
+  assert.match(r.stdout, /maestro board mine/);
+});
+
+test("runBoard track: an inbox item renamed by the daemon between the directory listing and the read (.yaml → .dispatched) is re-listed, not reported as ENOENT", async () => {
+  const yaml = ["id: cohort-m9", "service: cohort", "channel_id: C9", "raw_ref: cohort:messaging:m9:1", "content: hi", ""].join("\n");
+  let listings = 0;
+  let reads = 0;
+  const calls = [];
+  const out = [];
+  const deps = {
+    agentRoot: "/virtual", cfg: CFG, write: (s) => out.push(s),
+    readdirImpl: () => { listings += 1; return listings === 1 ? ["2026-09-08T10-00-00-cohort-m9.yaml"] : ["2026-09-08T10-00-00-cohort-m9.yaml.dispatched"]; },
+    readFileImpl: (p) => {
+      reads += 1;
+      if (String(p).endsWith(".yaml")) { const e = new Error("ENOENT: no such file"); e.code = "ENOENT"; throw e; }
+      return yaml;
+    },
+    trackImpl: async (params, o) => { calls.push({ params, o }); return { ok: true, result: { tracked: true, taskId: "t9", col: "done" } }; },
+  };
+  const r = await runBoard(["track", "cohort-m9", "--stage", "done"], deps);
+  assert.equal(r.code, 0, out.join("\n"));
+  assert.equal(listings, 2, "re-listed once after the rename");
+  assert.equal(reads, 2);
+  assert.equal(calls[0].params.messageId, "m9");
+  // Gone for good (retired between listings) → the documented "not found" exit, never a raw ENOENT.
+  out.length = 0;
+  const gone = await runBoard(["track", "cohort-m9", "--stage", "done"], {
+    ...deps,
+    readdirImpl: () => ["2026-09-08T10-00-00-cohort-m9.yaml"],
+    readFileImpl: () => { const e = new Error("ENOENT"); e.code = "ENOENT"; throw e; },
+  });
+  assert.equal(gone.code, 1);
+  assert.match(out.join("\n"), /no inbox item cohort-m9/);
+  assert.ok(!/ENOENT/.test(out.join("\n")));
+});