@cohortapp/agent-sdk 2.11.15 → 2.12.0

package/lib/collective/presence.mjs

@@ -20,9 +20,10 @@
 "use strict";
 
 import {
-  writeFileSync, readFileSync, unlinkSync, readdirSync, mkdirSync, existsSync,
+  readFileSync, unlinkSync, readdirSync, mkdirSync, existsSync,
 } from "node:fs";
 import { join, basename } from "node:path";
+import { writeJsonAtomic } from "../fs-atomic.mjs";
 
 const PRESENCE_REL = "state/collective/presence";
 const DEFAULT_STALE_SEC = 300;
@@ -84,7 +85,7 @@ export function register(agentRoot, info = {}) {
       status: info.status || "active",
       kind: info.kind || "interactive",
     };
-    writeFileSync(path, JSON.stringify(rec, null, 2));
+    writeJsonAtomic(path, rec);
     return true;
   } catch {
     return false;
@@ -104,7 +105,7 @@ export function heartbeat(agentRoot, sessionId, updates = {}) {
     rec.lastBeat = nowIso(updates.nowMs);
     if (updates.intent !== undefined) rec.intent = String(updates.intent).slice(0, 200);
     if (updates.status !== undefined) rec.status = updates.status;
-    writeFileSync(path, JSON.stringify(rec, null, 2));
+    writeJsonAtomic(path, rec);
     return true;
   } catch {
     return false;

package/lib/comms/send-gate.mjs

@@ -92,6 +92,31 @@ export const BANNED_OPENERS = Object.freeze([
   "Great question!",
 ]);
 
+/* ───────────────────────────── persona discipline ────────────────────────── */
+// Front-door session design (2026-09-08 §3.6): the agent is ONE persona to
+// every human; parallel sessions, sub-sessions, subagents and workflows are
+// internal workings and may never be named in outbound text, nor may "Claude
+// Code" or "a language model". Kept in sync with scripts/hooks/pre-send-audit.sh
+// PERSONA_PATTERNS so the PreToolUse hook and this in-process gate reject the
+// same set. "subagent"/"sub-agent" is blocked only when followed by
+// said|reported|session — the bare noun in an internal-process sentence is
+// tolerated; attributing speech to a machine part is not.
+export const PERSONA_PATTERNS = Object.freeze([
+  /claude\s+code/i,
+  /claude\s+sessions?/i,
+  /sub-sessions?/i,
+  /sub-?agents?\s+(?:said|reported|sessions?)/i,
+  /workflow\s+agents?/i,
+  /as\s+an\s+ai\b/i,
+  /language\s+model/i,
+]);
+
+/** Where the persona screen reads the agent's identity + peer registry from. */
+const PERSONA_FILES = Object.freeze({
+  agent: "config/agent.json",
+  peers: "state/session/peers.json",
+});
+
 /* ────────────────────────── recipient classification ─────────────────────── */
 
 /**
@@ -262,6 +287,84 @@ export function screenBannedPhrases(text) {
   return null;
 }
 
+function escapeRe(str) {
+  return String(str).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * (a2) Persona-leak screen. Pure; no IO. Returns a block reason (naming the
+ * offending phrase so the caller can rewrite in its own voice) or null.
+ *
+ * Session names are BOUNDED, not guessed: `<first>-main` is always internal,
+ * and any other name is internal only when it is in `sessionNames` (the
+ * registry `maestro session spawn` keeps in state/session/peers.json). A
+ * colleague called Marc-Antoine, the URL slug james-kirkland or the mailbox
+ * ethan-miller@ therefore pass, while `alex-main` / a registered `alex-deck`
+ * do not. Matching is word-bounded on [A-Za-z0-9_-] and case-insensitive.
+ *
+ * @param {string} text
+ * @param {{first?:string, sessionNames?:string[]}} [o]
+ * @returns {string|null}
+ */
+export function screenPersona(text, o = {}) {
+  const t = typeof text === "string" ? text : "";
+  if (!t) return null;
+  for (const re of PERSONA_PATTERNS) {
+    const m = re.exec(t);
+    if (m) {
+      return `persona leak "${m[0]}" — rewrite in your own voice (my team / a colleague); never name the machinery`;
+    }
+  }
+  const first = String(o.first || "").trim().toLowerCase().replace(/[^a-z0-9-]+/g, "");
+  const names = new Set();
+  if (first) names.add(`${first}-main`);
+  for (const n of Array.isArray(o.sessionNames) ? o.sessionNames : []) {
+    const v = String(n || "").trim().toLowerCase();
+    if (v) names.add(v);
+  }
+  for (const name of names) {
+    const re = new RegExp(`(^|[^A-Za-z0-9_-])(${escapeRe(name)})(?![A-Za-z0-9_-])`, "i");
+    const m = re.exec(t);
+    if (m) {
+      return `persona leak "${m[2]}" is an internal session name — say "my team" or "a colleague" instead`;
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve the persona inputs from disk (fail-open: anything unreadable is
+ * simply absent, and the name check is then skipped while the phrase check
+ * still runs). Explicit values win over the files.
+ */
+function personaContext(fs, agentRoot, { agentFirst, sessionNames }) {
+  let first = typeof agentFirst === "string" ? agentFirst : "";
+  if (!first) {
+    const a = readPolicy(fs, agentRoot, PERSONA_FILES.agent);
+    if (a.ok) {
+      try {
+        const doc = JSON.parse(a.text) || {};
+        first = String(doc.firstName || String(doc.fullName || "").split(/\s+/)[0] || "");
+      } catch { first = ""; }
+    }
+  }
+  let names = Array.isArray(sessionNames) ? sessionNames : null;
+  if (!names) {
+    names = [];
+    const p = readPolicy(fs, agentRoot, PERSONA_FILES.peers);
+    if (p.ok) {
+      try {
+        const doc = JSON.parse(p.text);
+        const list = Array.isArray(doc) ? doc : doc && Array.isArray(doc.peers) ? doc.peers : [];
+        for (const peer of list) {
+          if (peer && typeof peer === "object" && typeof peer.name === "string" && peer.name) names.push(peer.name);
+        }
+      } catch { /* a corrupt registry is an empty one */ }
+    }
+  }
+  return { first, sessionNames: names };
+}
+
 /**
  * (b) AI-disclosure screen. Resolves the active posture for the recipient's
  * jurisdiction from ai-disclosure.yaml and enforces two things:
@@ -431,6 +534,8 @@ export function screenAllowlist(recipient, allowlist) {
  * @param {boolean} [args.firstContact=true] is this the first message in the convo
  * @param {string[]} [args.internalDomains] email domains treated as internal
  * @param {string[]} [args.allowlist] recipient allowlist (opt-in)
+ * @param {string} [args.agentFirst] agent first name for the session-name check (default: agentRoot/config/agent.json)
+ * @param {string[]} [args.sessionNames] internal session names (default: agentRoot/state/session/peers.json)
  * @param {object} [args.fs] injected { readFileSync, existsSync } for tests
  * @returns {Promise<{allow:boolean, reason:string, redactedText?:string}>}
  */
@@ -443,6 +548,8 @@ export async function screenOutbound({
   firstContact = true,
   internalDomains = [],
   allowlist = undefined,
+  agentFirst = undefined,
+  sessionNames = undefined,
   fs: injectedFs = undefined,
 } = {}) {
   const fs = makeFs(injectedFs);
@@ -482,6 +589,14 @@ export async function screenOutbound({
     const bannedReason = screenBannedPhrases(text);
     if (bannedReason) return blocked(bannedReason);
 
+    // (a2) Persona discipline — pure over the identity + peer registry read
+    //      here (fail-open: no identity → the name check is skipped, the
+    //      phrase check still runs). This is what makes `maestro inbox reply`,
+    //      the daemon's delivery and the org MCP tools persona-safe without a
+    //      shell hook in the loop.
+    const personaReason = screenPersona(text, personaContext(fs, agentRoot, { agentFirst, sessionNames }));
+    if (personaReason) return blocked(personaReason);
+
     // (b) AI-disclosure. The truthfulness invariant is enforced from the
     //     embedded denial list even without the file; posture resolution needs
     //     the file. Missing file → invariant still runs; posture defaults apply.

package/lib/comms/send-gate.test.mjs

@@ -24,6 +24,7 @@ import { tmpdir } from "node:os";
 import {
   screenOutbound,
   screenBannedPhrases,
+  screenPersona,
   screenDisclosure,
   screenBarriers,
   screenAllowlist,
@@ -655,3 +656,115 @@ describe("screenOutbound — real-disk read path", () => {
     }
   });
 });
+
+/* ─── persona discipline (front-door session §3.6) ─────────────────────────
+ * The agent is one persona to every human. The machinery — Claude Code, a
+ * session, a sub-session, a subagent that "said", a workflow agent, the model,
+ * an internal session name — never appears in outbound text. This screen runs
+ * inside screenOutbound so EVERY lane gets it: the daemon's delivery
+ * (`maestro inbox reply`), lib/org/messaging.sendMessage, the org MCP tools
+ * (messaging_send, email_send, email_draft_send, org_rpc) and the adapters —
+ * not only the PreToolUse shell hook.
+ */
+
+describe("screenPersona (unit)", () => {
+  for (const [label, text] of [
+    ["Claude Code", "I'll have Claude Code pick that up this afternoon."],
+    ["Claude session", "A separate claude session is running the numbers."],
+    ["sub-session", "I kicked off a sub-session for the deck."],
+    ["subagent said", "The subagent said the deploy finished."],
+    ["sub-agent reported", "My sub-agent reported two blockers."],
+    ["subagent session", "The subagent session is still going."],
+    ["workflow agent", "The workflow agent will file the summary."],
+    ["language model", "Every language model has limits, mine included."],
+  ]) {
+    it(`blocks "${label}" and names the phrase`, () => {
+      const reason = screenPersona(text);
+      assert.ok(reason, `expected a block for "${label}"`);
+      assert.match(reason, /persona leak/i);
+      assert.match(reason.toLowerCase(), new RegExp(label.toLowerCase().replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/\s+/g, "\\s+")));
+    });
+  }
+
+  it("session names are BOUNDED: <first>-main always, other <first>-<x> only when registered as a peer", () => {
+    assert.ok(screenPersona("Check with alex-main for the latest.", { first: "alex" }));
+    assert.ok(screenPersona("Ask ALEX-MAIN.", { first: "alex" }), "case-insensitive");
+    assert.equal(screenPersona("alex-research has the draft ready.", { first: "alex" }), null, "unregistered peer name: not a session name");
+    assert.ok(screenPersona("alex-research has the draft ready.", { first: "alex", sessionNames: ["alex-research"] }));
+    assert.ok(screenPersona("alex-research has the draft ready.", { sessionNames: ["alex-research"] }), "names work without a first name");
+  });
+
+  it("does not block a colleague's hyphenated name, a URL slug or an email local part that starts with the first name", () => {
+    for (const [first, text] of [
+      ["marc", "Marc-Antoine confirmed the numbers."],
+      ["james", "See https://os.cohortapp.com/spaces/james-kirkland for the thread."],
+      ["ethan", "Loop in ethan-miller@example.com on the invoice."],
+      ["alex", "Alexandra-Maine sent the invoice."],
+      ["alex", "alex-mainland is the venue."],
+    ]) {
+      assert.equal(screenPersona(text, { first }), null, `"${text}" must pass for first=${first}`);
+    }
+  });
+
+  it("colleague phrasing, the bare noun 'subagents', and the calendar sense of 'session' all pass", () => {
+    for (const text of [
+      "One of my analysts is on it; I'll have the numbers by 3.",
+      "My team has the deck in review — sending the draft after lunch.",
+      "We use subagents internally for the heavy lifting.",
+      "The session on Thursday (the board session) starts at 9.",
+      "",
+    ]) {
+      assert.equal(screenPersona(text, { first: "alex" }), null, `"${text}" must pass`);
+    }
+    assert.equal(screenPersona(null), null);
+  });
+});
+
+describe("screenOutbound — persona", () => {
+  const PERSONA_FILES = {
+    ...GOOD_FILES,
+    "config/agent.json": JSON.stringify({ firstName: "Alex", fullName: "Alex Rivera" }),
+    "state/session/peers.json": JSON.stringify([{ name: "alex-deck", muxName: "maestro-alex-deck", purpose: "deck" }]),
+  };
+
+  it("blocks a persona leak for an internal Cohort recipient (the `maestro inbox reply` lane)", async () => {
+    const res = await screenOutbound({
+      channel: "cohort",
+      recipient: "clx0123456789abcdefghij",
+      text: "My sub-session is on it, check with alex-main.",
+      agentRoot: ROOT,
+      firstContact: false,
+      fs: memFs(PERSONA_FILES),
+    });
+    assert.equal(res.allow, false);
+    assert.match(res.reason, /persona leak/i);
+    assert.match(res.reason, /sub-session/i);
+  });
+
+  it("reads the first name from config/agent.json and the peer names from state/session/peers.json under agentRoot", async () => {
+    const fs = memFs(PERSONA_FILES);
+    const main = await screenOutbound({ channel: "cohort", recipient: "clx0123456789abcdefghij", text: "alex-main will chase it.", agentRoot: ROOT, firstContact: false, fs });
+    assert.equal(main.allow, false);
+    assert.match(main.reason, /alex-main/);
+    const peer = await screenOutbound({ channel: "cohort", recipient: "clx0123456789abcdefghij", text: "alex-deck has the slides.", agentRoot: ROOT, firstContact: false, fs });
+    assert.equal(peer.allow, false, "a registered peer name is a session name");
+    const other = await screenOutbound({ channel: "cohort", recipient: "clx0123456789abcdefghij", text: "alex-research is not a peer here.", agentRoot: ROOT, firstContact: false, fs });
+    assert.equal(other.allow, true, "an unregistered <first>-x is ordinary text");
+  });
+
+  it("explicit agentFirst / sessionNames override the disk read; no identity on disk → phrase gate still applies, name gate skipped", async () => {
+    const fs = memFs(GOOD_FILES);
+    const named = await screenOutbound({ channel: "cohort", recipient: "clx0123456789abcdefghij", text: "robin-main will chase it.", agentRoot: ROOT, firstContact: false, fs, agentFirst: "Robin" });
+    assert.equal(named.allow, false);
+    const none = await screenOutbound({ channel: "cohort", recipient: "clx0123456789abcdefghij", text: "robin-main will chase it.", agentRoot: ROOT, firstContact: false, fs });
+    assert.equal(none.allow, true, "no first name resolvable → the name check is skipped (fail-open on that one check)");
+    const phrase = await screenOutbound({ channel: "cohort", recipient: "clx0123456789abcdefghij", text: "Claude Code is on it.", agentRoot: ROOT, firstContact: false, fs });
+    assert.equal(phrase.allow, false, "the phrase gate needs no identity");
+  });
+
+  it("applies to external email too", async () => {
+    const res = await screenOutbound({ channel: "email", recipient: "graham@kpm.com", text: "Our workflow agent will send the summary. I am an AI assistant, for the record.", agentRoot: ROOT, fs: memFs(PERSONA_FILES) });
+    assert.equal(res.allow, false);
+    assert.match(res.reason, /persona leak/i);
+  });
+});

package/lib/feature-init.mjs

@@ -39,10 +39,10 @@ import {
   existsSync,
   mkdirSync,
   readFileSync,
-  writeFileSync,
 } from "node:fs";
 import { join, resolve, dirname } from "node:path";
 import { spawnSync } from "node:child_process";
+import { writeJsonAtomic } from "./fs-atomic.mjs";
 
 export const FEATURE_REGISTRY_RELATIVE = "framework-features.json";
 export const AGENT_STATE_RELATIVE = ".maestro/features.json";
@@ -116,7 +116,7 @@ export function loadAgentState(agentRoot) {
 export function saveAgentState(agentRoot, state) {
   const statePath = getStatePath(agentRoot);
   mkdirSync(dirname(statePath), { recursive: true });
-  writeFileSync(statePath, JSON.stringify(state, null, 2) + "\n");
+  writeJsonAtomic(statePath, state);
 }
 
 // ---------------------------------------------------------------------------

package/lib/mcp/server.test.mjs

@@ -166,19 +166,24 @@ test("tools/list: full active surface (email tools present — family is vendore
   // other desk block, these eight are GENERATED from the vendored protocol
   // declaration (lib/org/resource-tools.mjs), so this transport gets them, and
   // every future resource method, without a second hand-written table.
-  assert.equal(tools.length, 141, "email + artifact + desk families vendored → 141 tools");
+  // 141 → 144: the front-door session (2026-09). board_mine / board_track /
+  // session_status — "my tasks across every board" was unreadable from any
+  // plane (board.ready is unassigned-only), the inbound→board seam had no
+  // accepted/done ends, and nothing could tell a session whether the main
+  // session was alive.
+  assert.equal(tools.length, 144, "email + artifact + desk + front-door families vendored → 144 tools");
   const names = tools.map((t) => t.name);
-  for (const expected of ["org_whoami", "org_describe", "org_rpc", "org_read", "messaging_send", "task_assign", "board_ready", "email_send", "email_inbox", "artifact_create", "artifact_act", "artifact_catalog", "email_mailboxes", "email_draft_send", "files_list", "calendar_find_a_time", "crm_list_deals", "books_reports", "meetings_recap_file", "resource_list", "resource_attach_file"]) {
+  for (const expected of ["org_whoami", "org_describe", "org_rpc", "org_read", "messaging_send", "task_assign", "board_ready", "board_mine", "board_track", "session_status", "email_send", "email_inbox", "artifact_create", "artifact_act", "artifact_catalog", "email_mailboxes", "email_draft_send", "files_list", "calendar_find_a_time", "crm_list_deals", "books_reports", "meetings_recap_file", "resource_list", "resource_attach_file"]) {
     assert.ok(names.includes(expected), `${expected} listed`);
   }
   assert.ok(tools.every((t) => t.inputSchema && t.inputSchema.type === "object"));
   h.server.stop();
 });
 
-test("tools/list honours the email gate (emailAvailable:false → 136 tools)", async () => {
+test("tools/list honours the email gate (emailAvailable:false → 139 tools)", async () => {
   const h = harness({ emailAvailable: false });
   const r = await h.request("tools/list", {});
-  assert.equal(r.result.tools.length, 136, "the 5 own-mailbox email tools drop out");
+  assert.equal(r.result.tools.length, 139, "the 5 own-mailbox email tools drop out");
   const names = new Set(r.result.tools.map((t) => t.name));
   // The five own-mailbox tools (email:true) are gated out …
   for (const gated of ["email_send", "email_inbox", "email_message", "email_thread", "email_mark_read"]) {

package/lib/model-router/spawn.test.mjs

@@ -423,3 +423,24 @@ test("DeepSeek session retarget env is built when DeepSeek is the cheap candidat
   // Foreign keys scrubbed.
   assert.equal(seenEnv.MOONSHOT_API_KEY, undefined);
 });
+
+test("buildChildEnv KEEPS CLAUDE_CODE_OAUTH_TOKEN — the subscription token is not a foreign credential (§3.1)", () => {
+  // The scrub regex ends in `_AUTH_TOKEN$`; `_OAUTH_TOKEN` must not match it,
+  // otherwise every daemon spawn on the oauth-token path would silently fall
+  // back to an expired keychain login. Pinned here so a "tidy" of the regex
+  // cannot re-open F1.
+  const base = {
+    PATH: "/usr/bin",
+    CLAUDE_CODE_OAUTH_TOKEN: "sk-ant-oat01-example",
+    MAESTRO_PREFER_SUBSCRIPTION_AUTH: "1",
+    SOME_AUTH_TOKEN: "tok",
+  };
+  const stock = buildChildEnv(base, {});
+  assert.equal(stock.CLAUDE_CODE_OAUTH_TOKEN, "sk-ant-oat01-example");
+  assert.equal(stock.MAESTRO_PREFER_SUBSCRIPTION_AUTH, "1");
+  assert.equal(stock.SOME_AUTH_TOKEN, undefined, "a real *_AUTH_TOKEN is still scrubbed");
+  // A retarget (third-party session) keeps it too: the token is harmless to a
+  // foreign base URL and the ANTHROPIC_API_KEY="" discipline is what fences it.
+  const retarget = buildChildEnv(base, { ANTHROPIC_BASE_URL: "https://api.moonshot.ai/anthropic", ANTHROPIC_API_KEY: "" });
+  assert.equal(retarget.CLAUDE_CODE_OAUTH_TOKEN, "sk-ant-oat01-example");
+});

package/lib/org/board-mine-cache.mjs

@@ -0,0 +1,99 @@
+/**
+ * lib/org/board-mine-cache.mjs — the pure half of the daemon's board-mine
+ * cache (design 2026-09-08 §3.5; left over from WP-M2/M4).
+ *
+ * The daemon asks hq `board.mine` (`lib/org/client.mjs#listMine`, fail-open
+ * `[]`) every five minutes and writes the answer to
+ * `state/org/board-mine.json` as `{ts, items:[...]}`. Three readers already
+ * exist: the SessionStart primer (`lib/session/status-summary.mjs`), the
+ * `session_status` MCP tool and `maestro board mine` (`lib/cli/board.mjs`,
+ * which falls back to this cache when the live read is empty). This module
+ * decides WHEN to refresh and WHAT to write; the daemon does the I/O.
+ *
+ * @module lib/org/board-mine-cache
+ */
+
+"use strict";
+
+/** Five minutes, per the design. */
+export const REFRESH_INTERVAL_MS = 5 * 60_000;
+
+/** Where the daemon writes the cache, relative to the agent root. */
+export const BOARD_MINE_REL = "state/org/board-mine.json";
+
+/**
+ * Should the cache be refreshed now? Pure. `lastTs` is the `ts` of the last
+ * write (ISO string or epoch ms; null/invalid = never), `now` is epoch ms.
+ * A clock that went backwards (lastTs in the future) also refreshes, so a
+ * bad timestamp can never freeze the cache.
+ * @param {string|number|null|undefined} lastTs
+ * @param {number} now
+ * @param {number} [intervalMs]
+ * @returns {boolean}
+ */
+export function shouldRefresh(lastTs, now, intervalMs = REFRESH_INTERVAL_MS) {
+  const last = toMs(lastTs);
+  if (last === null) return true;
+  if (last > now) return true;
+  return now - last >= intervalMs;
+}
+
+/**
+ * The document to write. Pure. Non-array or non-object items are dropped so a
+ * malformed server answer cannot poison the readers.
+ * @param {unknown} items   what listMine() returned
+ * @param {number} now      epoch ms
+ * @returns {{ts:string, items:object[]}}
+ */
+export function render(items, now) {
+  const list = Array.isArray(items) ? items.filter((it) => it && typeof it === "object" && !Array.isArray(it)) : [];
+  return { ts: new Date(now).toISOString(), items: list };
+}
+
+/**
+ * What to write after a refresh attempt. Pure. A successful read renders the
+ * fresh items; a FAILED read keeps the previous document's items (last known
+ * good) and marks the document `stale: true` with `itemsAt` = when those
+ * items were actually fetched — so one unreachable hq tick does not turn the
+ * SessionStart primer, session_status and `maestro board mine` into "zero
+ * items" for five minutes. With nothing previous, a failed read renders
+ * empty-and-stale.
+ * @param {{ok:boolean, items?:unknown, error?:string}|unknown[]|null|undefined} result  listMineResult() (an array is treated as ok)
+ * @param {unknown} prev   the current cache document (or null)
+ * @param {number} now     epoch ms
+ * @returns {{ts:string, items:object[], stale?:true, itemsAt?:string|null, error?:string}}
+ */
+export function renderRefresh(result, prev, now) {
+  const r = Array.isArray(result) ? { ok: true, items: result } : (result && typeof result === "object" ? result : { ok: false, items: [] });
+  if (r.ok) return render(r.items, now);
+  const prevDoc = prev && typeof prev === "object" && !Array.isArray(prev) ? prev : null;
+  const kept = render(prevDoc ? prevDoc.items : [], now);
+  const itemsAt = prevDoc ? (prevDoc.stale && prevDoc.itemsAt !== undefined ? prevDoc.itemsAt : cacheTs(prevDoc)) : null;
+  const doc = { ...kept, stale: true, itemsAt: itemsAt || null };
+  if (r.error) doc.error = String(r.error).slice(0, 200);
+  return doc;
+}
+
+/**
+ * The `ts` of an existing cache document, or null. Tolerates the pre-M6
+ * `{fetchedAt}` spelling and a bare array (no timestamp → refresh).
+ * @param {unknown} doc
+ * @returns {string|null}
+ */
+export function cacheTs(doc) {
+  if (!doc || typeof doc !== "object" || Array.isArray(doc)) return null;
+  if (typeof doc.ts === "string") return doc.ts;
+  if (typeof doc.fetchedAt === "string") return doc.fetchedAt;
+  return null;
+}
+
+function toMs(v) {
+  if (typeof v === "number" && Number.isFinite(v)) return v;
+  if (typeof v === "string" && v.trim()) {
+    const n = Date.parse(v);
+    if (Number.isFinite(n)) return n;
+  }
+  return null;
+}
+
+export default { shouldRefresh, render, renderRefresh, cacheTs, REFRESH_INTERVAL_MS, BOARD_MINE_REL };

package/lib/org/board-mine-cache.test.mjs

@@ -0,0 +1,53 @@
+/**
+ * board-mine-cache.test.mjs — the pure half of the daemon's 5-minute
+ * state/org/board-mine.json cache.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { shouldRefresh, render, renderRefresh, cacheTs, REFRESH_INTERVAL_MS, BOARD_MINE_REL } from "./board-mine-cache.mjs";
+
+const NOW = Date.parse("2026-09-08T12:00:00Z");
+
+test("shouldRefresh: never written → yes; younger than 5 min → no; 5 min or older → yes; a future ts → yes", () => {
+  assert.equal(shouldRefresh(null, NOW), true);
+  assert.equal(shouldRefresh(undefined, NOW), true);
+  assert.equal(shouldRefresh("garbage", NOW), true);
+  assert.equal(shouldRefresh("2026-09-08T11:56:00Z", NOW), false);
+  assert.equal(shouldRefresh(NOW - REFRESH_INTERVAL_MS + 1, NOW), false);
+  assert.equal(shouldRefresh("2026-09-08T11:55:00Z", NOW), true);
+  assert.equal(shouldRefresh(NOW - REFRESH_INTERVAL_MS, NOW), true);
+  assert.equal(shouldRefresh("2026-09-08T12:30:00Z", NOW), true, "a clock that went backwards must not freeze the cache");
+  assert.equal(shouldRefresh("2026-09-08T11:59:30Z", NOW, 10_000), true, "interval is a parameter");
+  assert.equal(REFRESH_INTERVAL_MS, 300_000);
+  assert.equal(BOARD_MINE_REL, "state/org/board-mine.json");
+});
+
+test("render: {ts, items} with only object items kept; a non-array answer renders as empty", () => {
+  const doc = render([{ itemId: "i1", title: "Do X" }, null, "junk", [1], { itemId: "i2" }], NOW);
+  assert.deepEqual(doc, { ts: "2026-09-08T12:00:00.000Z", items: [{ itemId: "i1", title: "Do X" }, { itemId: "i2" }] });
+  assert.deepEqual(render(undefined, NOW), { ts: "2026-09-08T12:00:00.000Z", items: [] });
+  assert.deepEqual(render({ items: [{ itemId: "x" }] }, NOW).items, [], "an object is not the items array (listMine already unwraps)");
+});
+
+test("cacheTs reads ts, tolerates the earlier fetchedAt spelling, and is null for a bare array or junk", () => {
+  assert.equal(cacheTs({ ts: "2026-09-08T11:59:00Z", items: [] }), "2026-09-08T11:59:00Z");
+  assert.equal(cacheTs({ fetchedAt: "2026-09-08T11:59:00Z", items: [] }), "2026-09-08T11:59:00Z");
+  assert.equal(cacheTs([{ itemId: "x" }]), null);
+  assert.equal(cacheTs(null), null);
+  assert.equal(cacheTs({ items: [] }), null);
+});
+
+test("renderRefresh: a successful read renders fresh items; a FAILED read keeps the previous items, marks stale and remembers when they were fetched", () => {
+  const prev = { ts: "2026-09-08T11:55:00.000Z", items: [{ itemId: "i1" }] };
+  assert.deepEqual(renderRefresh({ ok: true, items: [{ itemId: "i2" }] }, prev, NOW), { ts: "2026-09-08T12:00:00.000Z", items: [{ itemId: "i2" }] });
+  assert.deepEqual(renderRefresh([{ itemId: "i3" }], prev, NOW), { ts: "2026-09-08T12:00:00.000Z", items: [{ itemId: "i3" }] }, "a bare array (the old listMine shape) is a success");
+  assert.deepEqual(renderRefresh({ ok: true, items: [] }, prev, NOW), { ts: "2026-09-08T12:00:00.000Z", items: [] }, "an empty board is a real answer, not a failure");
+  const failed = renderRefresh({ ok: false, items: [], error: "http 503" }, prev, NOW);
+  assert.deepEqual(failed, { ts: "2026-09-08T12:00:00.000Z", items: [{ itemId: "i1" }], stale: true, itemsAt: "2026-09-08T11:55:00.000Z", error: "http 503" });
+  const failedAgain = renderRefresh({ ok: false, items: [] }, failed, NOW + 300_000);
+  assert.equal(failedAgain.itemsAt, "2026-09-08T11:55:00.000Z", "a second failure keeps the ORIGINAL fetch time, not the last stale write");
+  assert.deepEqual(failedAgain.items, [{ itemId: "i1" }]);
+  assert.deepEqual(renderRefresh({ ok: false, items: [] }, null, NOW), { ts: "2026-09-08T12:00:00.000Z", items: [], stale: true, itemsAt: null }, "nothing previous → empty and stale");
+  assert.deepEqual(renderRefresh(null, prev, NOW).items, [{ itemId: "i1" }], "a null result is a failure");
+});

package/lib/org/board.mjs

@@ -128,6 +128,17 @@ export function ready(opts = {}) {
   return resolveClient(opts).listReady(rpcOpts(opts));
 }
 
+/**
+ * Read THIS agent's items across every board (GET /v1/board.mine — assignee
+ * or reviewer = caller). Returns the items array, or [] on any failure
+ * (fail-open; an hq without the read yet answers 404 → []).
+ * @param {object} [opts] - { client?, base, token, fetchImpl? }
+ * @returns {Promise<object[]>}
+ */
+export function mine(opts = {}) {
+  return resolveClient(opts).listMine(rpcOpts(opts));
+}
+
 // ---------------------------------------------------------------------------
 // Read-only YAML projection writer
 // ---------------------------------------------------------------------------

package/lib/org/board.test.mjs

@@ -14,7 +14,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 import {
-  createItem, claimItem, completeItem, decompose, assign, link, ready,
+  createItem, claimItem, completeItem, decompose, assign, link, ready, mine,
   buildProjection, writeProjection, writeReadyProjection,
 } from "./board.mjs";
 import { okFrame, errFrame, BOARD_STATUS } from "./protocol.mjs";
@@ -38,6 +38,7 @@ function fakeClient(map = {}) {
     boardAssign: make("boardAssign"),
     boardLink: make("boardLink"),
     listReady: make("listReady"),
+    listMine: make("listMine"),
   };
 }
 
@@ -175,3 +176,12 @@ test("writeReadyProjection: down server (empty ready) writes an empty projection
     assert.equal(doc.count, 0);
   } finally { rmSync(root, { recursive: true, force: true }); }
 });
+
+test("mine: routes to client.listMine, forwarding conn opts (fail-open [] handled by the client)", async () => {
+  const client = fakeClient({ listMine: () => [{ itemId: "m1" }] });
+  assert.deepEqual(await mine({ client, ...CONN }), [{ itemId: "m1" }]);
+  // listMine takes ONE argument (the conn opts), like listReady.
+  const c = client.calls.find((x) => x.name === "listMine");
+  assert.equal(c.params.base, CONN.base);
+  assert.equal(c.params.token, CONN.token);
+});

package/lib/org/client.mjs

@@ -694,6 +694,42 @@ export async function listReady(o = {}) {
   return [];
 }
 
+/**
+ * List every board item assigned to (or under review by) THIS agent across all
+ * boards and workstreams (GET /v1/board.mine — hq 2026-09, front-door session
+ * §3.5). Returns the items array, or [] on any failure (fail-open): an older hq
+ * without the read answers 404 and this returns [], same as listReady.
+ * Item shape: {itemId, title, boardId, boardName, channelId, workstreamId, col,
+ * stage, priority, dueAt, updatedAt, url}.
+ * @param {object} o - { base, token, orgId?, fetchImpl? }
+ * @returns {Promise<object[]>}
+ */
+export async function listMine(o = {}) {
+  return (await listMineResult(o)).items;
+}
+
+/**
+ * `listMine` with the failure kept visible: `{ok:false, items:[]}` when hq
+ * could not be read, `{ok:true, items}` otherwise (an empty board is
+ * `ok:true`). The daemon's board-mine cache needs the difference so one
+ * unreachable tick does not overwrite the last known good answer with [].
+ * Never throws.
+ * @param {object} o - { base, token, orgId, fetchImpl? }
+ * @returns {Promise<{ok:boolean, items:object[], error?:string}>}
+ */
+export async function listMineResult(o = {}) {
+  try {
+    const r = await read("board.mine", o);
+    if (!r.ok) return { ok: false, items: [], error: (r.error && r.error.message) || `http ${r.status || 0}` };
+    if (!r.payload) return { ok: true, items: [] };
+    if (Array.isArray(r.payload)) return { ok: true, items: r.payload };
+    if (Array.isArray(r.payload.items)) return { ok: true, items: r.payload.items };
+    return { ok: true, items: [] };
+  } catch (err) {
+    return { ok: false, items: [], error: String((err && err.message) || err) }; // read() never throws; belt-and-braces for a throwing fetchImpl
+  }
+}
+
 /**
  * Fetch the event slice (GET /v1/events?cursor=N&limit=500). Returns the events
  * array (or [] on failure). The caller pipes these to verify.verifyEvents.