@cohortapp/agent-sdk 2.11.15 → 2.13.0

package/lib/org/mesh.mjs

@@ -22,6 +22,13 @@
  *                           (lib/org/policy.fetchAndApply against the PINNED root).
  *        - "resync"       → re-fetch the directory (client.fetchDirectory) into the
  *                           local peers cache (state/org/peers/<id>.json).
+ *        - "restart"      → (audit F10) the daemon flushes and exits NON-ZERO so
+ *                           launchd's KeepAlive {SuccessfulExit:false} relaunches
+ *                           it. Never writes .emergency-stop — a restart is not a
+ *                           halt. Injected as requestRestart.
+ *        - "session.restart" → touch state/session/restart-requested; the main
+ *                           session's feed sees it and the session restarts itself
+ *                           at an idle moment (design §3.10). The daemon stays up.
  *   3. stop() — clears the interval so the daemon can shut the mesh down cleanly.
  *
  * FAIL-OPEN by design (mirrors lib/org/client): if the org is disabled
@@ -42,6 +49,7 @@
 
 import { join, resolve } from "node:path";
 import { mkdirSync, writeFileSync } from "node:fs";
+import { writeJsonAtomic } from "../fs-atomic.mjs";
 
 import * as defaultClient from "./client.mjs";
 import * as policy from "./policy.mjs";
@@ -70,8 +78,13 @@ const KNOWN_DIRECTIVES = new Set([
   "policy_stale",
   "resync",
   "toolset_changed",
+  "restart",
+  "session.restart",
 ]);
 
+/** Where the session runtime looks for a restart request (relative to the agent root). */
+export const SESSION_RESTART_FLAG_RELATIVE = "state/session/restart-requested";
+
 function logInfo(msg) { try { console.log(`[org-mesh] ${msg}`); } catch { /* never throw from logging */ } }
 function logWarn(msg) { try { console.warn(`[org-mesh] ${msg}`); } catch { /* never throw from logging */ } }
 
@@ -84,6 +97,38 @@ function defaultRequestStop() {
   try { process.kill(process.pid, "SIGTERM"); } catch { /* fail-open */ }
 }
 
+/**
+ * Default restart signal (the "restart" directive, audit F10). The daemon
+ * plist's KeepAlive is {SuccessfulExit:false}: launchd relaunches ONLY after a
+ * non-zero exit, and a clean exit 0 leaves the seat down. So: set exitCode 1
+ * first, then go through the daemon's own SIGTERM handlers (they flush
+ * active-session state + the health dashboard and exit honouring exitCode).
+ * If we cannot signal ourselves, exit 1 directly — a restart must not turn
+ * into a hang.
+ */
+function defaultRequestRestart() {
+  process.exitCode = 1;
+  try { process.kill(process.pid, "SIGTERM"); }
+  catch { try { process.exit(1); } catch { /* fail-open */ } }
+}
+
+/**
+ * Ask the main session to restart itself ("session.restart"): write the
+ * restart-requested flag the session's feed watches. Idempotent overwrite
+ * (the newest request time wins) and fail-open. Never throws.
+ */
+function requestSessionRestart(agentRoot, now) {
+  const at = new Date((typeof now === "function" ? now() : Date.now())).toISOString();
+  try {
+    const path = join(agentRoot, SESSION_RESTART_FLAG_RELATIVE);
+    mkdirSync(join(agentRoot, "state", "session"), { recursive: true });
+    writeFileSync(path, `${at}\n`);
+    logInfo(`session.restart directive — flagged ${SESSION_RESTART_FLAG_RELATIVE} (${at})`);
+  } catch (err) {
+    logWarn(`session.restart directive — failed to write the restart flag (${err && err.message})`);
+  }
+}
+
 /**
  * Trip the local kill switch in response to a "halt" directive.
  *   1. Write `.emergency-stop` (the same flag emergency-stop.sh drops) so a
@@ -187,7 +232,7 @@ async function resyncDirectory(o) {
     const id = String(p.id).toLowerCase().replace(/[^a-z0-9._-]/gi, "_");
     if (!id) continue;
     try {
-      writeFileSync(join(peersDir, `${id}.json`), JSON.stringify({ ...p, source: "synced" }, null, 2));
+      writeJsonAtomic(join(peersDir, `${id}.json`), { ...p, source: "synced" });
       written += 1;
     } catch { /* skip this peer, keep going */ }
   }
@@ -279,6 +324,16 @@ async function handleDirective(directive, ctx) {
       // Force an immediate refresh + disk write, ahead of the 30s poll.
       await refreshIntegrationTools(ctx);
       return;
+    case "restart":
+      // Stop beating first: this process is going down to come back, and a
+      // beat in flight during teardown would just be noise.
+      logWarn("restart directive received — stopping the beat loop and restarting the daemon (exit 1 → launchd relaunch)");
+      ctx.stop();
+      try { ctx.requestRestart(); } catch { /* fail-open */ }
+      return;
+    case "session.restart":
+      requestSessionRestart(ctx.agentRoot, ctx.now);
+      return;
     default:
       return; // forward-compatible: ignore unknown directives
   }
@@ -389,6 +444,7 @@ async function beatOnce(ctx) {
  * @param {Function} [o.clearInterval]         injected interval clearer
  * @param {object}  [o.client]                 injected org client (defaults to lib/org/client)
  * @param {Function}[o.requestStop]            injected stop signal (defaults to SIGTERM self)
+ * @param {Function}[o.requestRestart]         injected restart signal (defaults to exitCode 1 + SIGTERM self)
  * @param {number}  [o.beatMs]                 beat interval (defaults to DEFAULT_BEAT_MS)
  * @param {Function}[o.collectStatus]         injected status collector (defaults to lib/telemetry/collect)
  * @returns {Promise<{stop:Function, isEnabled:boolean}>}
@@ -409,6 +465,7 @@ export async function connectOrgMesh(o = {}) {
   const clearIntervalFn = typeof o.clearInterval === "function" ? o.clearInterval : clearInterval;
   const beatMs = Number.isFinite(o.beatMs) && o.beatMs > 0 ? o.beatMs : DEFAULT_BEAT_MS;
   const requestStop = typeof o.requestStop === "function" ? o.requestStop : defaultRequestStop;
+  const requestRestart = typeof o.requestRestart === "function" ? o.requestRestart : defaultRequestRestart;
 
   let conn = {};
   try { conn = client.configFromAgent(cfg) || {}; } catch { conn = {}; }
@@ -420,6 +477,7 @@ export async function connectOrgMesh(o = {}) {
     fetchImpl: o.fetchImpl,
     now,
     requestStop,
+    requestRestart,
     base: conn.base,
     token: conn.token,
     orgId: conn.orgId,
@@ -491,6 +549,8 @@ export const _internals = {
   handleDirective,
   tripKillSwitch,
   flagRepairNeeded,
+  defaultRequestRestart,
+  requestSessionRestart,
   resyncDirectory,
   refreshPolicy,
   refreshIntegrationTools,

package/lib/org/protocol.checksum

@@ -1 +1 @@
-b2cbf124c99800a0ad1b19d7aea6a88c3c72f07b53838eb44ef6f82d888fda43
+8bce96163171fc5b9f23ea03889cd9220113af09e14f87d704c635f33f9aa76e

package/lib/org/protocol.mjs

@@ -1045,6 +1045,49 @@ export const METHODS = Object.freeze({
   "architecture.status": { family: "architecture", scope: "org.read", sideEffecting: false },
   "architecture.accept": { family: "architecture", scope: "org.write", sideEffecting: true, idempotent: true },
   "architecture.approve": { family: "architecture", scope: "org.write", sideEffecting: true, idempotent: true },
+  // --- architecture, the LIVE half (2026-08): the COMMITTED company's board at
+  //     hq's /org/architecture, as opposed to the three above, which review a
+  //     Genesis DRAFT. Same family because it is the same surface outliving the
+  //     run — the reason the family was split from `genesis` in the first place.
+  //
+  //     THREE METHODS, AND THE SHAPE OF THE THREE IS THE AUTHORITY MODEL.
+  //     hq's own rule (src/server/architecture/proposals.ts) is that a change is
+  //     gated on a reviewed record when the CHANGE has a cascade, not when the
+  //     ACTOR is a machine: axis acts and capability removal need a proposal
+  //     somebody with the floor approved; the mechanical 90% goes direct. What
+  //     an agent gets on this wire is therefore the ASKING (`propose`) and
+  //     enough of the board to ask accurately (`board`), plus the queue that
+  //     tells it what became of the ask (`proposals`). Approval is NOT here: it
+  //     is a session act in hq, and the module that owns it says why — "an agent
+  //     cannot reach an approval at all, not because a check says no, but
+  //     because there is no door. A door that does not exist has to be BUILT,
+  //     and building it is a review a person will see."
+  //
+  //     `architecture.board` EXISTS BECAUSE THE IDS ON SCREEN ADDRESS NOTHING.
+  //     hq mints a board's entity ids BY POSITION (`P1`/`S3`/`C12`, `D1`/`T1`)
+  //     because its id schema bounds an id at 2-4 chars while a cuid is 25, and
+  //     every write resolves through a derived-id -> row-id map the browser
+  //     holds. An agent has no browser. Without this read the only ids it could
+  //     put in a proposal are guessed ones, so the read is not a convenience —
+  //     it is the addressing layer `propose` is unusable without.
+  //
+  //     SCOPES REUSE `org.read` / `org.write` — the same argument the resource
+  //     family makes below, and here it is also the reason the family is
+  //     reachable AT ALL on the day it lands: both are in DEFAULT_AGENT_SCOPES,
+  //     `org.read` is in hq's VIEWER tier, so a paired key can read the board
+  //     today and an EDITOR key can propose. NOTE the asymmetry that follows,
+  //     deliberately: `org.write` is NOT in hq's HUMAN_DEFAULT_SCOPES, so
+  //     `architecture.propose` is an AGENT-plane verb and the human proposes
+  //     from the web app's own server action. That is the same split the
+  //     resource family notes, and it is the right way round here — the human
+  //     already has the surface; the agent is the one that had no door.
+  //
+  //     `propose` is NOT idempotent, and the omission is the declaration: a
+  //     second call with the same params is a second, honestly distinct ask, and
+  //     caching one under a replay key would silently swallow it.
+  "architecture.board": { family: "architecture", scope: "org.read", sideEffecting: false },
+  "architecture.propose": { family: "architecture", scope: "org.write", sideEffecting: true },
+  "architecture.proposals": { family: "architecture", scope: "org.read", sideEffecting: false },
   // --- resource (2026-08): THE VENTURE-DELIVERABLE CATALOGUE. `OrgResource` is
   //     the org-scoped index of a venture's own artifacts — one row per
   //     deliverable, keyed `(orgId, slug)`, provisioned by the portal
@@ -1163,6 +1206,11 @@ export const READS = Object.freeze({
   "hierarchy": "org.read",
   "board.ready": "board.read",
   "board.context": "board.read",
+  // the seat's OWN work across every board (2026-09, front-door session §3.5):
+  // every item where the caller is assignee or reviewer. `board.ready` is the
+  // unassigned frontier and cannot answer "what is mine?"; the daemon caches
+  // this for the main session's primer and the session works it proactively.
+  "board.mine": "board.read",
   "ops": "org.read",
   // phase 3 reads
   "approval.wait": "approval.request", // bounded long-poll for an approval outcome
@@ -1213,6 +1261,10 @@ export const DIRECTIVES = Object.freeze([
   "pause_schedules", // stop INITIATING (Loop B + Loop C); keep answering when addressed
   "plan_stale",      // the seat's mandate moved — refetch `mandate.get` and recompile
   "revoke_scope",    // a scope was withdrawn; drop it locally and re-probe capabilities
+  // --- front-door session (2026-09) ---
+  "restart",         // a human pressed "Restart" on the fleet surface: exit the main
+                     //   session cleanly so the supervisor relaunches it on current code.
+                     //   The beat delivers it once; alerts close only on a later clean beat.
 ]);
 
 // ---------------------------------------------------------------------------

package/lib/org/protocol.test.mjs

@@ -205,7 +205,18 @@ test("protocol: frozen family + method counts (additive evolution guard)", () =>
   // to `files.*`: a card carries a fileId POINTER and the drive keeps its own
   // seat-scoped read surface → 483. Then +1: messaging.electResponder (the
   // fleet's server-side respond-election) → 484.
-  assert.equal(Object.keys(METHODS).length, 484, "method count");
+  // The 2026-08 architecture live-board pass adds 3, closing the half of the
+  // `architecture` family that was never on the wire: the three methods above
+  // review a Genesis DRAFT, while hq's /org/architecture is a CRUD surface over
+  // the COMMITTED company and no agent could see it, let alone ask it to change.
+  // architecture.board (the read that hands back LIVE ROW IDS beside the
+  // positional `P1`/`S3` labels the board renders — an agent has no browser to
+  // hold the derived-id -> row-id map, so without it every id it could propose
+  // on would be a guess), architecture.propose (the agent's end of hq's
+  // "agents propose, a human with the floor approves" rule) and
+  // architecture.proposals (the queue that says what became of the ask). NOT
+  // approve/reject: those are session acts in hq by design → 487.
+  assert.equal(Object.keys(METHODS).length, 487, "method count");
 });
 
 test("protocol SP3: messaging + calling families/methods/scopes", async () => {

package/lib/org/registry.mjs

@@ -16,7 +16,8 @@
 
 "use strict";
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from "node:fs";
+import { existsSync, readFileSync, mkdirSync, readdirSync } from "node:fs";
+import { writeJsonAtomic } from "../fs-atomic.mjs";
 import { join } from "node:path";
 
 const ORG_REL = "state/org";
@@ -151,7 +152,7 @@ function orgDir(agentRoot) { return join(agentRoot, ORG_REL); }
 export function writeSelfEntry(agentRoot, entry) {
   try {
     mkdirSync(orgDir(agentRoot), { recursive: true });
-    writeFileSync(join(orgDir(agentRoot), "self.json"), JSON.stringify(entry, null, 2));
+    writeJsonAtomic(join(orgDir(agentRoot), "self.json"), entry);
     return true;
   } catch { return false; }
 }

package/lib/org/tool-surface.mjs

@@ -96,7 +96,15 @@ import {
   read,
   approvalWait,
   fetchSelfProfile,
+  listMine,
 } from "./client.mjs";
+// The work ladder hq's board.track walks (accepted → working → blocked/review
+// → done/failed) — one vocabulary, owned by the ledger client.
+import { WORK_STAGES } from "./work-ledger.mjs";
+// Front-door session status (2026-09): the main session's heartbeat, its peer
+// sessions, open cadence handoffs and the cached board-mine count, read from
+// local state so the tool answers with no token and no network.
+import { readSessionStatus, statusLine } from "../session/status-summary.mjs";
 // The hq vocabularies the model must pick from (an out-of-vocabulary enum value
 // is a BAD_REQUEST). Sourced from the wire contract so the tool table and the
 // normaliser can never disagree about what hq accepts.
@@ -809,6 +817,86 @@ export const ORG_TOOLS = Object.freeze([
     access: "write",
     binding: { kind: "rpc", method: "board.track" },
   },
+  // ── front-door session (2026-09): my work across boards, the inbound→board
+  //    seam, and the main session's liveness ─────────────────────────────────
+  {
+    name: "board_mine",
+    title: "My work across all boards",
+    description:
+      "Every board item assigned to you or awaiting your review, across every board and " +
+      "workstream (GET /v1/board.mine) — the list `board_ready` cannot show, because that feed " +
+      "is unassigned work only. Each item: {itemId, title, boardId, boardName, channelId, " +
+      "workstreamId, col, stage, priority, dueAt, updatedAt, url}. Use it when idle to pick the " +
+      "highest-priority item you can move, then `board_claim` it; use it to answer \"what is on " +
+      "your plate?\". An org server that does not serve this read yet returns an empty list, " +
+      "not an error.",
+    input_schema: S({}),
+    access: "read",
+    binding: { kind: "local" },
+  },
+  {
+    name: "board_track",
+    title: "File or advance an ask on its board",
+    description:
+      "Record where an ask stands on the board that owns it (board.track) — the server derives " +
+      "the board from the message identity (a DM's conversation board or the space's board), " +
+      "dedupes on (channelId, messageId) and ladders the column, so a repeated call is free. " +
+      "This is the sanctioned way to put an inbound ask onto a board: when a request needs more " +
+      "than one reply's worth of work, acknowledge it in-channel in the SAME turn and call this " +
+      "with stage 'accepted' (title = what you took on, why = the one-line reason it is more " +
+      "than a reply). Advance with 'working', 'blocked' (say what you need; `notify` whoever " +
+      "can unstick it), 'review' (finished, wants a human's eyes) and close with 'done' or " +
+      "'failed'. `work_track` is the mid-work subset of this verb.",
+    input_schema: S(
+      {
+        channelId: str("The channel the ask arrived on."),
+        messageId: str("The id of the message that asked. Identifies the board row."),
+        stage: {
+          type: "string",
+          enum: WORK_STAGES,
+          description:
+            "accepted = taken on (opens the row); working = started; blocked = stuck and needs " +
+            "someone; review = finished, needs a human's eyes; done / failed = closed.",
+        },
+        title: str("Row title when the row is opened (optional; the server defaults it from the ask)."),
+        why: str("One line on why this became board work rather than a reply (optional)."),
+        note: str("What changed, in a sentence or two, for the person waiting (optional)."),
+        priority: {
+          type: "string",
+          enum: TASK_PRIORITIES,
+          description: "Priority P0 (highest) .. P4, read only when the row is created (optional).",
+        },
+        notify: {
+          type: "array",
+          items: { type: "string" },
+          description: "Member ids to @-tag on this step — only people who must act or know.",
+        },
+        attachments: {
+          type: "array",
+          description: "Files this step produced: [{name, mimeType?, sizeBytes?, dataUrl}].",
+          items: { type: "object" },
+        },
+      },
+      ["channelId", "messageId", "stage"],
+    ),
+    access: "write",
+    binding: { kind: "rpc", method: "board.track" },
+  },
+  {
+    name: "session_status",
+    title: "Main session status",
+    description:
+      "Whether this agent's main (front-door) session is live on this machine, its name, the " +
+      "peer sessions it has spawned, how many cadence handoffs are waiting for it, and how many " +
+      "board items the daemon last cached for it — read from local state, offline, no token " +
+      "needed. `live:false` with state 'stale' means the session exists but stopped beating; " +
+      "'absent' means it is not running (the daemon is then answering inbound itself). Use it " +
+      "before addressing the main session with SendMessage, or to answer \"is the front door " +
+      "up?\". Never quote session names to a human — they are internal.",
+    input_schema: S({}),
+    access: "read",
+    binding: { kind: "local" },
+  },
   // ── decisions / approvals ────────────────────────────────────────────────
   {
     name: "decision_list",
@@ -2977,6 +3065,9 @@ export function orgToolDef(name) {
  * the first-class tools.
  * @type {Set<string>}
  */
+/** board_track input fields forwarded to hq (the schema's optional keys). */
+export const BOARD_TRACK_PASSTHROUGH = Object.freeze(["title", "why", "note", "priority", "notify", "attachments"]);
+
 export const OUTBOUND_METHODS = Object.freeze(
   new Set(
     ORG_TOOLS.filter((t) => t.outbound && t.binding && t.binding.kind === "rpc").map(
@@ -3263,6 +3354,10 @@ async function executeOrgToolInner(name, input = {}, o = {}) {
 
     // Offline-capable local tools first.
     if (name === "org_describe") return describeProtocol(input);
+    if (name === "session_status") {
+      const status = readSessionStatus(cfg.agentRoot, { now: Date.now() });
+      return okFrame({ ...status, agentRoot: cfg.agentRoot, summary: statusLine(status) });
+    }
 
     // Every network tool needs a token; per §1.4 the server stays up and each
     // call returns a clear error frame instead.
@@ -3421,6 +3516,31 @@ async function executeOrgToolInner(name, input = {}, o = {}) {
         return readToFrame(await read(withQuery("events", q), callOpts));
       }
 
+      case "board_mine": {
+        // listMine is fail-open by contract: an hq that does not serve the read
+        // yet (404), a transport error or a malformed body all come back as [].
+        const items = await listMine(callOpts);
+        return okFrame({ items, count: items.length });
+      }
+
+      case "board_track": {
+        const i = input || {};
+        const channelId = i.channelId ? String(i.channelId) : "";
+        const messageId = i.messageId ? String(i.messageId) : "";
+        const stage = i.stage ? String(i.stage) : "";
+        if (!channelId || !messageId) return errFrame("BAD_REQUEST", "board_track: channelId and messageId are required");
+        if (!WORK_STAGES.includes(stage)) {
+          return errFrame("BAD_REQUEST", `board_track: stage must be one of ${WORK_STAGES.join("|")} (got ${stage || "(none)"})`);
+        }
+        // `service` is pinned (this seam is Cohort-only) and only the schema's
+        // passthrough fields travel: model input never reaches hq verbatim.
+        const params = { service: "cohort", channelId, messageId, stage };
+        for (const k of BOARD_TRACK_PASSTHROUGH) if (i[k] !== undefined) params[k] = i[k];
+        // Same ask + same stage = the same call (mirrors lib/org/work-ledger):
+        // a retry after a timeout must not double-post the tag.
+        return call("board.track", params, { ...callOpts, idempotencyKey: `board.track:${channelId}:${messageId}:${stage}` });
+      }
+
       case "decision_list": {
         const q = input && input.status ? { status: input.status } : null;
         return readToFrame(await read(withQuery("decision.list", q), callOpts));

package/lib/org/tool-surface.test.mjs

@@ -9,6 +9,9 @@
 "use strict";
 
 import { test, before, after } from "node:test";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import assert from "node:assert/strict";
 
 import {
@@ -117,7 +120,14 @@ test("table: curated 54 + 5 email + 5 artifact + 77 desk tools, snake_case names
   // declaration (lib/org/resource-tools.mjs) rather than transcribed from hq's
   // desk, so it cannot acquire the 239-vs-69 drift the hand-copied desks
   // already carry; resource-tools.test.mjs is the parity that holds it there.
-  assert.equal(ORG_TOOLS.length, 141, "54 curated + 5 email + 5 artifact + 77 desk");
+  // The FRONT-DOOR delta (+3 curated → 57, table 141 → 144; design spec
+  // 2026-09-08 §3.5/§3.7): board_mine (the agent's own items across every
+  // board — board.ready is unassigned-only, so "my tasks" was unreadable from
+  // any plane), board_track (the sanctioned inbound→board seam with the
+  // accepted/done ends of the ladder and title/why passthrough) and
+  // session_status (the main session's liveness + peers from local state,
+  // offline-capable).
+  assert.equal(ORG_TOOLS.length, 144, "57 curated + 5 email + 5 artifact + 77 desk");
   assert.equal(ORG_TOOLS.filter((t) => t.desk).length, 77, "exactly seventy-seven desk tools");
   assert.equal(ORG_TOOLS.filter((t) => t.email).length, 5, "exactly five email tools");
   assert.equal(ORG_TOOLS.filter((t) => t.artifact).length, 5, "exactly five artifact tools");
@@ -168,19 +178,19 @@ test("OUTBOUND_METHODS is DERIVED from outbound:true tools (messaging/email/mail
 test("email gating: family present in the vendored protocol → tools active; override excludes", () => {
   // The email family landed in the vendored protocol (sync-protocol phase 1).
   assert.equal(emailFamilyAvailable(), true, "vendored protocol carries email.send");
-  assert.equal(getOrgTools().length, 141);
+  assert.equal(getOrgTools().length, 144);
   const without = getOrgTools({ emailAvailable: false });
-  assert.equal(without.length, 136);
+  assert.equal(without.length, 139);
   assert.ok(!without.some((t) => t.email), "email tools excluded when family absent");
 });
 
 test("artifact gating: family present → tools active; override excludes (email precedent)", () => {
   assert.equal(artifactFamilyAvailable(), true, "vendored protocol carries artifact.act");
   const without = getOrgTools({ artifactAvailable: false });
-  assert.equal(without.length, 136);
+  assert.equal(without.length, 139);
   assert.ok(!without.some((t) => t.artifact), "artifact tools excluded when family absent");
   const neither = getOrgTools({ emailAvailable: false, artifactAvailable: false, desksAvailable: false });
-  assert.equal(neither.length, 54, "all additive families off → the 54 always-on tools");
+  assert.equal(neither.length, 57, "all additive families off → the 57 always-on tools");
 });
 
 test("isOrgTool / orgToolDef cover the full table; unknown names rejected", () => {
@@ -1153,3 +1163,106 @@ test("transport failure on a new tool fails open into an INTERNAL frame, never a
   assert.equal(frame.ok, false);
   assert.equal(frame.error.code, "INTERNAL");
 });
+
+// ── WP-M4: front-door tools (board_mine / board_track / session_status) ────
+
+test("board_mine: read access, GET /v1/board.mine, items normalised, [] when hq lacks the read (fail-open)", async () => {
+  const def = orgToolDef("board_mine");
+  assert.ok(def, "board_mine curated");
+  assert.equal(def.access, "read");
+  assert.equal(def.binding.kind, "local", "local so an hq without board.mine yet degrades to [] instead of a bare 404");
+  const fetchImpl = fakeFetch({ items: [{ itemId: "i1", title: "Deck", col: "doing" }] });
+  const frame = await executeOrgTool("board_mine", {}, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl });
+  assert.equal(frame.ok, true);
+  assert.deepEqual(frame.result.items, [{ itemId: "i1", title: "Deck", col: "doing" }]);
+  assert.equal(frame.result.count, 1);
+  assert.match(fetchImpl.calls[0].url, /\/v1\/board\.mine$/);
+  assert.equal(fetchImpl.calls[0].init.method, "GET");
+  const gone = fakeFetch({ error: { code: "NOT_FOUND", message: "no such read" } }, { status: 404, ok: false });
+  const f2 = await executeOrgTool("board_mine", {}, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl: gone });
+  assert.equal(f2.ok, true, "fail-open: an older hq is an empty list, not an error the model must interpret");
+  assert.deepEqual(f2.result.items, []);
+  // No token → UNAUTHORIZED like every other network tool.
+  const noTok = await executeOrgTool("board_mine", {}, { orgConfig: { org: { cohort: { enabled: true, base: "https://org.example" } } }, agentRoot: "/tmp/none", fetchImpl });
+  assert.equal(noTok.ok, false);
+  assert.equal(noTok.error.code, "UNAUTHORIZED");
+});
+
+test("board_track: write access on board.track; title/why/stage pass through; whole ladder incl. accepted|done; bad stage rejected offline", async () => {
+  const def = orgToolDef("board_track");
+  assert.ok(def, "board_track curated");
+  assert.equal(def.access, "write");
+  assert.equal(def.binding.method, "board.track");
+  assert.deepEqual(def.input_schema.properties.stage.enum, ["accepted", "working", "blocked", "review", "done", "failed"]);
+  assert.ok(def.input_schema.properties.title, "title passthrough");
+  assert.ok(def.input_schema.properties.why, "why passthrough");
+  const fetchImpl = fakeFetch({ ok: true, result: { tracked: true, taskId: "t1", col: "todo", created: true } });
+  const frame = await executeOrgTool(
+    "board_track",
+    { channelId: "c1", messageId: "m1", stage: "accepted", title: "Build the deck", why: "asked in DM", note: "on it" },
+    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl },
+  );
+  assert.equal(frame.ok, true);
+  assert.equal(frame.result.taskId, "t1");
+  assert.match(fetchImpl.calls[0].url, /\/v1\/board\.track$/);
+  const body = JSON.parse(fetchImpl.calls[0].init.body);
+  assert.equal(body.stage, "accepted");
+  assert.equal(body.title, "Build the deck");
+  assert.equal(body.why, "asked in DM");
+  assert.equal(body.service, "cohort", "service defaults to cohort");
+  assert.equal(body.channelId, "c1");
+  assert.equal(body.messageId, "m1");
+  assert.equal(fetchImpl.calls[0].init.headers["x-idempotency-key"], "board.track:c1:m1:accepted", "stable per (ask, stage)");
+  const bad = fakeFetch();
+  const rej = await executeOrgTool("board_track", { channelId: "c1", messageId: "m1", stage: "later" }, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl: bad });
+  assert.equal(rej.ok, false);
+  assert.equal(rej.error.code, "BAD_REQUEST");
+  assert.equal(bad.calls.length, 0, "validated before any network");
+});
+
+test("session_status: offline local read of state/session + state/org/board-mine; works with no token", async () => {
+  const def = orgToolDef("session_status");
+  assert.ok(def, "session_status curated");
+  assert.equal(def.access, "read");
+  assert.equal(def.binding.kind, "local");
+  const root = mkdtempSync(join(tmpdir(), "ts-session-"));
+  try {
+    mkdirSync(join(root, "state", "session", "handoffs"), { recursive: true });
+    mkdirSync(join(root, "state", "org"), { recursive: true });
+    writeFileSync(join(root, "state", "session", "heartbeat.json"), JSON.stringify({ pid: 1, name: "alex-main", sessionId: "s1", ts: Date.now() }));
+    writeFileSync(join(root, "state", "session", "peers.json"), JSON.stringify([{ name: "alex-deck", purpose: "board deck" }]));
+    writeFileSync(join(root, "state", "session", "handoffs", "t1.json"), "{}");
+    writeFileSync(join(root, "state", "org", "board-mine.json"), JSON.stringify({ items: [{ itemId: "i1" }, { itemId: "i2" }], fetchedAt: new Date().toISOString() }));
+    const fetchImpl = fakeFetch();
+    const frame = await executeOrgTool("session_status", {}, { orgConfig: { org: { cohort: { enabled: true, base: "https://org.example" } } }, agentRoot: root, fetchImpl });
+    assert.equal(frame.ok, true, "no token is fine — this never touches the network");
+    assert.equal(fetchImpl.calls.length, 0);
+    assert.equal(frame.result.live, true);
+    assert.equal(frame.result.name, "alex-main");
+    assert.equal(frame.result.peers[0].name, "alex-deck");
+    assert.equal(frame.result.handoffsOpen, 1);
+    assert.equal(frame.result.boardMineCount, 2);
+    assert.equal(typeof frame.result.summary, "string");
+    // An empty root is "absent", not an error.
+    const empty = await executeOrgTool("session_status", {}, { orgConfig: CFG, agentRoot: join(root, "nope"), fetchImpl });
+    assert.equal(empty.ok, true);
+    assert.equal(empty.result.state, "absent");
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("board_track: the model cannot override service or smuggle extra keys — only the schema's passthrough fields reach hq", async () => {
+  const fetchImpl = fakeFetch({ ok: true, result: { tracked: true, taskId: "t2", col: "doing" } });
+  const frame = await executeOrgTool(
+    "board_track",
+    { channelId: "c1", messageId: "m1", stage: "working", service: "slack", junk: "x", note: "halfway", priority: "P1", notify: ["u1"] },
+    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl },
+  );
+  assert.equal(frame.ok, true);
+  const body = JSON.parse(fetchImpl.calls[0].init.body);
+  assert.equal(body.service, "cohort", "service is pinned, not model-supplied");
+  assert.equal(body.junk, undefined, "unknown keys are dropped");
+  assert.equal(body.note, "halfway");
+  assert.equal(body.priority, "P1");
+  assert.deepEqual(body.notify, ["u1"]);
+  assert.deepEqual(Object.keys(body).sort(), ["channelId", "messageId", "note", "notify", "priority", "service", "stage"]);
+});

package/lib/prompts/parallelism.mjs

@@ -0,0 +1,79 @@
+/**
+ * lib/prompts/parallelism.mjs — the fleet-wide parallelism directive (WP-M7).
+ *
+ * THE GAP this closes (owner directive 2026-09-09): a session handed a plan with
+ * six independent tasks ran them one at a time, because nothing in its prompt
+ * ever said it was allowed not to. The directive below is the standing
+ * permission — plus the ONE safety rule that makes parallel dispatch safe on a
+ * shared checkout (no two agents editing the same file).
+ *
+ * It is a CONSTANT, not a template: the same bytes reach `maestro session spawn`
+ * (peer sessions) and `scripts/daemon/prompt-builder.mjs` (escalate/guarded
+ * sub-sessions), so the wording can be audited in one place and a test can pin
+ * it byte-for-byte.
+ *
+ * {@link withParallelism} is IDEMPOTENT. Two prompt seams compose (a daemon
+ * prompt handed to `session spawn`), and a directive repeated twice reads as
+ * emphasis to a model, which is exactly how "maximum safe parallelism" turns
+ * into "ignore the file-scope rule" — so a prompt that already carries the text
+ * is returned unchanged.
+ *
+ * Pure: no clock, no env, no I/O. Node builtins only. ESM.
+ *
+ * @module lib/prompts/parallelism
+ */
+
+"use strict";
+
+/**
+ * The directive, verbatim (design spec 2026-09-08 §WP-M7 mechanic 5). Do not
+ * reword without changing the spec — `parallelism.test.mjs` pins these bytes.
+ * @type {string}
+ */
+export const PARALLELISM_DIRECTIVE = `You are allowed to run multiple sub-agents concurrently.
+
+When the plan contains independent tasks, dispatch them together in a single parallel batch rather than waiting for each task to finish before starting the next.
+
+Only run tasks sequentially when one task genuinely depends on the output of another.
+
+Before dispatching any batch, check the planned file scope for each task and ensure that no two agents are assigned to edit the same file. If tasks would overlap on a file, sequence those tasks or redefine their scope to eliminate the conflict.
+
+Default to maximum safe parallelism.`;
+
+/**
+ * Prepend {@link PARALLELISM_DIRECTIVE} to a prompt, exactly once.
+ *
+ * A prompt that already contains the directive anywhere in its body is returned
+ * unchanged (idempotent — see the module docstring). A non-string or empty
+ * prompt yields the directive alone, so a caller that lost its prompt still
+ * sends something coherent rather than `undefined`.
+ *
+ * @param {string} prompt the prompt to lead
+ * @returns {string}
+ */
+export function withParallelism(prompt) {
+  const body = typeof prompt === "string" ? prompt : "";
+  if (body.includes(PARALLELISM_DIRECTIVE)) return body;
+  if (!body.trim()) return PARALLELISM_DIRECTIVE;
+  return `${PARALLELISM_DIRECTIVE}\n\n${body}`;
+}
+
+/**
+ * How many times the directive appears in a string. The seam a test (or a
+ * caller composing two prompts) uses to assert "exactly once".
+ * @param {string} text
+ * @returns {number}
+ */
+export function countParallelism(text) {
+  const body = typeof text === "string" ? text : "";
+  if (!body) return 0;
+  let n = 0;
+  let i = body.indexOf(PARALLELISM_DIRECTIVE);
+  while (i !== -1) {
+    n += 1;
+    i = body.indexOf(PARALLELISM_DIRECTIVE, i + PARALLELISM_DIRECTIVE.length);
+  }
+  return n;
+}
+
+export default { PARALLELISM_DIRECTIVE, withParallelism, countParallelism };