@cohortapp/agent-sdk 2.11.14 → 2.12.0

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.

package/lib/org/client.test.mjs

@@ -35,6 +35,9 @@ import {
   claimItem,
   completeItem,
   listReady,
+  listMine,
+  listMineResult,
+  trackWork,
   fetchEvents,
   fetchSnapshot,
   publishEntry,
@@ -1158,3 +1161,46 @@ test("loadOrgConfig: a PRESENT but unparseable org.yaml WARNS (never silently un
   assert.match(warnings.join("\n"), /could not be loaded/, "the operator must be told");
   assert.match(warnings.join("\n"), /NOT enrolled/, "and told what it means");
 });
+
+// ── WP-M4: board.mine + board.track passthrough (front-door session §3.5) ──
+
+test("listMineResult: keeps the failure visible — {ok:false} on an error frame or a throwing transport, {ok:true, items:[]} for an empty board", async () => {
+  assert.deepEqual(await listMineResult({ base: BASE, token: TOKEN, fetchImpl: fakeFetch(() => ({ body: [{ itemId: "i1" }] })) }), { ok: true, items: [{ itemId: "i1" }] });
+  assert.deepEqual(await listMineResult({ base: BASE, token: TOKEN, fetchImpl: fakeFetch(() => ({ body: { items: [] } })) }), { ok: true, items: [] }, "an empty board is a real answer");
+  const failed = await listMineResult({ base: BASE, token: TOKEN, fetchImpl: fakeFetch(() => ({ ok: false, status: 503, body: { error: { code: "UNAVAILABLE", message: "hq down" } } })) });
+  assert.equal(failed.ok, false);
+  assert.deepEqual(failed.items, []);
+  assert.match(failed.error, /hq down/);
+  const threw = await listMineResult({ base: BASE, token: TOKEN, fetchImpl: () => { throw new Error("ECONNREFUSED"); } });
+  assert.equal(threw.ok, false);
+  assert.deepEqual(threw.items, []);
+  assert.deepEqual(await listMine({ base: BASE, token: TOKEN, fetchImpl: () => { throw new Error("ECONNREFUSED"); } }), [], "listMine stays the fail-open [] its other callers expect");
+});
+
+test("listMine: GET /v1/board.mine; parses array and {items:[]}; [] on error / transport failure (fail-open)", async () => {
+  const f = fakeFetch(() => ({ body: [{ itemId: "i1", title: "Deck" }] }));
+  assert.deepEqual(await listMine({ base: BASE, token: TOKEN, fetchImpl: f }), [{ itemId: "i1", title: "Deck" }]);
+  assert.match(f.calls[0].url, /\/v1\/board\.mine$/);
+  assert.equal(f.calls[0].init.method, "GET");
+  assert.deepEqual(await listMine({ base: BASE, token: TOKEN, fetchImpl: fakeFetch(() => ({ body: { items: [{ itemId: "i2" }] } })) }), [{ itemId: "i2" }]);
+  assert.deepEqual(await listMine({ base: BASE, token: TOKEN, fetchImpl: fakeFetch(() => ({ ok: false, status: 404, body: { error: { code: "NOT_FOUND" } } })) }), [], "an hq without board.mine yet → []");
+  assert.deepEqual(await listMine({ base: BASE, token: TOKEN, fetchImpl: async () => { throw new Error("boom"); } }), []);
+  assert.deepEqual(await listMine({ base: "", token: TOKEN }), [], "no base → []");
+});
+
+test("trackWork: title/why/stage (incl. accepted|done) pass through to board.track verbatim", async () => {
+  const f = fakeFetch(() => ({ body: { ok: true, result: { tracked: true, taskId: "t1" } } }));
+  const r = await trackWork(
+    { service: "cohort", channelId: "c1", messageId: "m1", stage: "accepted", title: "Build the deck", why: "asked in DM" },
+    { base: BASE, token: TOKEN, fetchImpl: f, idempotencyKey: "k1" },
+  );
+  assert.equal(r.ok, true);
+  const body = JSON.parse(f.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.channelId, "c1");
+  const f2 = fakeFetch(() => ({ body: { ok: true, result: { tracked: true } } }));
+  await trackWork({ service: "cohort", channelId: "c1", messageId: "m1", stage: "done" }, { base: BASE, token: TOKEN, fetchImpl: f2 });
+  assert.equal(JSON.parse(f2.calls[0].init.body).stage, "done");
+});

package/lib/org/inbound/directedness.mjs

@@ -406,7 +406,9 @@ function yes(surface, reason, extra = {}) {
  * @param {Candidate} cand
  * @param {string} me the agent's member id
  * @param {import("./facts.mjs").Facts} facts
- * @param {{enabled?: Record<string,boolean>}} [opts]
+ * @param {{enabled?: Record<string,boolean>, meAliases?: string[]}} [opts]
+ *   `meAliases` — additional identity strings for this seat (slug, member id,
+ *   agent email). Used ONLY to widen own-echo suppression; never to widen reach.
  * @returns {{directed:boolean, surface:string|null, reason:string, why:string}}
  */
 export function resolveDirected(cand, me, facts = {}, opts = {}) {
@@ -414,10 +416,24 @@ export function resolveDirected(cand, me, facts = {}, opts = {}) {
   const enabled = opts.enabled || null;
   const on = (s) => (enabled ? !!enabled[s] : true);
   const meId = me ? String(me) : "";
+  // Every identity string that means "this seat". `me` SHOULD be the org member
+  // id (a cuid), because that is what hq stamps on `actor` and `directTo`. But a
+  // real machine can just as easily hand us the SLUG ("A028") — COHORT_AGENT_ID
+  // holds a slug, and the daemon's responder-election path needs it that way.
+  // When the slug arrives here, `actor === meId` compares across two namespaces,
+  // never matches, and the own-echo drop below silently stops existing. Echo
+  // suppression must not depend on which alias the caller happened to pass, so
+  // match ANY known alias. Observed in production 2026-08-26: A028 re-ingested
+  // its own morning brief and its own holding note and began answering itself.
+  const meAliases = new Set(
+    [meId, ...(Array.isArray(opts.meAliases) ? opts.meAliases : [])]
+      .map((v) => (v == null ? "" : String(v).trim()))
+      .filter(Boolean),
+  );
 
   // My OWN echo is never inbound. This is the single most important drop: without
   // it an agent re-ingests its own replies and holds a conversation with itself.
-  if (meId && cand.actor && cand.actor === meId) return no("own_echo");
+  if (cand.actor && meAliases.has(String(cand.actor))) return no("own_echo");
 
   // A payload that named me outright needs no join at all.
   if (meId && cand.directTo.map(String).includes(meId)) {

package/lib/org/inbound/directedness.test.mjs

@@ -145,6 +145,64 @@ test("NEGATIVE: my own echo is never inbound", () => {
   assert.equal(resolveDirected(c, ME, f).reason, "own_echo");
 });
 
+// --- own-echo across id namespaces (regression, production 2026-08-26) -------
+//
+// `me` SHOULD be the org member cuid — that is what hq stamps on `actor`. But
+// COHORT_AGENT_ID holds a SLUG and the daemon's responder-election path needs it
+// that way, so a slug reaches this resolver on a real machine. Strict equality
+// on one id then compares across two namespaces: it does not throw, it answers
+// "no" to every identity question, and the own-echo drop silently stops
+// existing. That is how a seat re-ingested its own morning brief and its own
+// holding note and began answering itself.
+//
+// These tests exist because nothing turns red when this lapses. The failure has
+// no runtime signal at all — only an assertion.
+
+const ME_SLUG = "A028";
+
+test("REGRESSION: a SLUG in the me position still suppresses my own echo", () => {
+  const f = withChannel(facts(), "C-dm", "DM");
+  const c = classifyEvent(
+    ev({ family: "messaging", kind: "send", actor: ME, entity_id: "m1", payload: { actor: ME, channelId: "C-dm", channelKind: "DM" } }),
+  );
+  // hq stamped the cuid; the caller handed us the slug. Pre-fix this returned
+  // `dm` — the agent's own message delivered back to it as fresh inbound.
+  const v = resolveDirected(c, ME_SLUG, f, { meAliases: [ME_SLUG, ME] });
+  assert.equal(v.directed, false);
+  assert.equal(v.reason, "own_echo");
+});
+
+test("REGRESSION: a SLUG-shaped actor is suppressed when me is the cuid", () => {
+  const f = withChannel(facts(), "C-dm", "DM");
+  const c = classifyEvent(
+    ev({ family: "messaging", kind: "send", actor: ME_SLUG, entity_id: "m1", payload: { actor: ME_SLUG, channelId: "C-dm", channelKind: "DM" } }),
+  );
+  // Symmetric: suppression must not depend on WHICH namespace either side used.
+  assert.equal(resolveDirected(c, ME, f, { meAliases: [ME, ME_SLUG] }).reason, "own_echo");
+});
+
+test("meAliases widen own-echo ONLY — never reach", () => {
+  const f = facts(); // C-theirs is in nobody's roster but its members'
+  const c = classifyEvent(
+    ev({ family: "messaging", kind: "send", entity_id: "m1", payload: { actor: THEM, channelId: "C-theirs", channelKind: "DM" } }),
+  );
+  const v = resolveDirected(c, ME_SLUG, f, { meAliases: [ME_SLUG, ME] });
+  assert.equal(v.directed, false, "an alias list must never open someone else's room");
+  assert.equal(v.reason, "channel_not_visible");
+});
+
+test("a blank/garbage alias never swallows real inbound", () => {
+  const f = withChannel(facts(), "C-dm", "DM");
+  withMessage(f, "C-dm", { id: "m1", authorId: THEM, body: "ping" });
+  const c = classifyEvent(
+    ev({ family: "messaging", kind: "send", entity_id: "m1", payload: { actor: THEM, channelId: "C-dm", channelKind: "DM", mentionCount: 0, threaded: false } }),
+  );
+  // Empty strings and nullish entries are dropped, so `has(actor)` cannot match
+  // on emptiness and turn every message into my own echo.
+  const v = resolveDirected(c, ME, f, { meAliases: [null, "", "   ", undefined] });
+  assert.deepEqual({ d: v.directed, r: v.reason }, { d: true, r: "dm" });
+});
+
 // ---------------------------------------------------------------------------
 // messaging — DM / mention / thread / ambient
 // ---------------------------------------------------------------------------

package/lib/org/inbound/index.mjs

@@ -87,6 +87,8 @@ const DEFAULT_EVENT_LIMIT = 200;
  * @param {number} [o.limit]
  * @param {Function} [o.fetchImpl]
  * @param {string[]} [o.myNames]               display names for prose-mention matching
+ * @param {string[]} [o.meAliases]             other identity strings for this seat
+ *   (slug, member id) — widens OWN-ECHO suppression only, never reach
  * @param {string[]|Record<string,boolean>} [o.surfaces] surface enable override
  * @param {object} [o.limits]                  overrides for {@link DEFAULT_LIMITS}
  * @param {Function} [o.log]                   (level, message, meta?) — daemon logger
@@ -125,6 +127,11 @@ export async function pullWideInbound(o = {}) {
     return empty;
   }
 
+  // Extra identity strings for own-echo suppression only (slug AND member id).
+  // The caller cannot always know which namespace `agentId` is in; passing both
+  // means a slug-valued COHORT_AGENT_ID can never silently disable the drop.
+  const meAliases = Array.isArray(o.meAliases) ? o.meAliases.filter(Boolean) : [];
+
   const { enabled, unknown } = resolveEnabledSurfaces(
     o.surfaces !== undefined ? o.surfaces : parseSurfaceEnv(process.env.COHORT_INBOUND_SURFACES),
   );
@@ -185,7 +192,7 @@ export async function pullWideInbound(o = {}) {
   // ── 3. Verdicts.
   const directed = [];
   for (const cand of candidates) {
-    const verdict = resolveDirected(cand, me, facts, { enabled });
+    const verdict = resolveDirected(cand, me, facts, { enabled, meAliases });
     if (!verdict.directed) {
       stats.dropped[verdict.reason] = (stats.dropped[verdict.reason] || 0) + 1;
       continue;

package/lib/org/inbound/index.test.mjs

@@ -208,6 +208,28 @@ test("NEGATIVE: nothing from someone else's private room, my own echo, or ambien
   assert.ok(stats.dropped.channel_not_visible >= 1);
 });
 
+test("REGRESSION: a slug-valued agentId still drops my own echo, via meAliases", async () => {
+  // The production shape on 2026-08-26: COHORT_AGENT_ID is a SLUG, hq stamps
+  // `actor` with the member cuid. `agentId` alone then matches nothing and the
+  // own-echo drop silently stops existing — no throw, no log, just the seat
+  // answering itself. The daemon hands BOTH namespaces down as `meAliases`, so
+  // the drop survives regardless of which one `agentId` resolved to.
+  const io = fakeIo(routes());
+  const { events, stats } = await pullWideInbound({
+    cfg: CFG,
+    agentId: "A028",
+    meAliases: ["A028", ME],
+    io,
+  });
+
+  assert.ok(stats.dropped.own_echo >= 1, "own_echo must still fire when me is the slug");
+  assert.equal(
+    events.some((e) => e.message_id === "m-mine"),
+    false,
+    "my own message must never come back, whichever id namespace the caller passed",
+  );
+});
+
 test("email is OFF by default and is not even hydrated", async () => {
   const io = fakeIo(routes());
   const { events } = await pullWideInbound({ cfg: CFG, agentId: ME, io });

package/lib/org/mesh-directives.test.mjs

@@ -0,0 +1,110 @@
+/**
+ * mesh-directives.test.mjs — the two front-door directives (design §3.4 /
+ * audit F10): hq's `remediateFleetSeat` queues `restart` and nothing honoured
+ * it. Now:
+ *
+ *   restart          → the daemon flushes and exits NON-ZERO so launchd's
+ *                      KeepAlive {SuccessfulExit:false} relaunches it (a clean
+ *                      exit 0 would leave it down). Injected as requestRestart.
+ *   session.restart  → touch state/session/restart-requested; the session's
+ *                      feed sees it and the session restarts itself at an idle
+ *                      moment. The daemon is untouched.
+ *
+ * Driven through the same fake client + explicit beatOnce as mesh.test.mjs.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { connectOrgMesh, _internals } from "./mesh.mjs";
+
+const BASE = "https://org.cohortapp.com";
+function tmpRepo() {
+  const root = mkdtempSync(join(tmpdir(), "org-mesh-directives-"));
+  mkdirSync(join(root, "config"), { recursive: true });
+  writeFileSync(join(root, "config", "agent.json"), JSON.stringify({ firstName: "Alex", fullName: "Alex Chen", repoSlug: "alex-ai" }));
+  return root;
+}
+function cfgEnabled() { return { org: { cohort: { enabled: true, base: BASE, token: "tok" } } }; }
+function fakeClient(beatFrames) {
+  const c = {
+    isEnabled: (cfg) => !!(cfg && cfg.org && cfg.org.cohort && cfg.org.cohort.enabled),
+    configFromAgent: () => ({ base: BASE, token: "tok", orgId: "", enabled: true, trustedSignersPem: [] }),
+    _beatFrames: beatFrames.slice(),
+    register() { return Promise.resolve({ ok: true, result: { status: 200 } }); },
+    presenceBeat() { return Promise.resolve(c._beatFrames.length ? c._beatFrames.shift() : { ok: true, result: { directives: [] } }); },
+    fetchDirectory() { return Promise.resolve({ ok: true, result: { agents: [] } }); },
+    call() { return Promise.resolve({ ok: true, result: {} }); },
+  };
+  return c;
+}
+
+test("KNOWN_DIRECTIVES includes restart and session.restart", () => {
+  assert.ok(_internals.KNOWN_DIRECTIVES.has("restart"));
+  assert.ok(_internals.KNOWN_DIRECTIVES.has("session.restart"));
+});
+
+test('"restart" directive stops the beat loop and asks the daemon to restart (exit non-zero); never writes .emergency-stop', async () => {
+  const root = tmpRepo();
+  const client = fakeClient([{ ok: true, result: { directives: ["restart"] } }]);
+  let stops = 0;
+  let restarts = 0;
+  const handle = await connectOrgMesh({
+    agentRoot: root, cfg: cfgEnabled(), client,
+    setInterval: () => ({ unref() {} }),
+    requestStop: () => { stops += 1; },
+    requestRestart: () => { restarts += 1; },
+  });
+  const directives = await _internals.beatOnce(handle._ctx);
+  assert.deepEqual(directives, ["restart"]);
+  assert.equal(restarts, 1, "requestRestart() was invoked");
+  assert.equal(stops, 0, "a restart is not a halt");
+  assert.equal(existsSync(join(root, ".emergency-stop")), false, "a restart must never trip the kill switch");
+  assert.equal(handle._ctx.stopped, true, "the beat loop stopped: the process is going down to come back");
+});
+
+test('"session.restart" directive touches state/session/restart-requested and leaves the daemon running', async () => {
+  const root = tmpRepo();
+  const client = fakeClient([{ ok: true, result: { directives: ["session.restart"] } }]);
+  let stops = 0;
+  let restarts = 0;
+  const T0 = Date.parse("2026-09-08T10:00:00.000Z");
+  const handle = await connectOrgMesh({
+    agentRoot: root, cfg: cfgEnabled(), client,
+    setInterval: () => ({ unref() {} }),
+    now: () => T0,
+    requestStop: () => { stops += 1; },
+    requestRestart: () => { restarts += 1; },
+  });
+  const directives = await _internals.beatOnce(handle._ctx);
+  assert.deepEqual(directives, ["session.restart"]);
+  const flag = join(root, "state", "session", "restart-requested");
+  assert.ok(existsSync(flag), "restart-requested flag written");
+  assert.match(readFileSync(flag, "utf8"), /2026-09-08T10:00:00/, "flag carries the request time");
+  assert.equal(stops, 0);
+  assert.equal(restarts, 0, "the daemon itself is not restarted");
+  assert.equal(handle._ctx.stopped, false, "the beat loop keeps running");
+  // Idempotent: a second directive overwrites the flag, never throws.
+  await _internals.handleDirective("session.restart", handle._ctx);
+  assert.ok(existsSync(flag));
+});
+
+test("the default restart signal sets a non-zero exit code before the graceful stop, so launchd relaunches", () => {
+  // defaultRequestRestart is the production path; we only check its contract
+  // on process.exitCode without sending ourselves a signal.
+  const prevExitCode = process.exitCode;
+  const prevKill = process.kill;
+  let killed = null;
+  process.kill = (pid, sig) => { killed = { pid, sig }; return true; };
+  try {
+    _internals.defaultRequestRestart();
+    assert.equal(process.exitCode, 1, "exit code 1 → KeepAlive {SuccessfulExit:false} brings the daemon back");
+    assert.deepEqual(killed, { pid: process.pid, sig: "SIGTERM" }, "graceful stop via the daemon's own SIGTERM handlers (flush)");
+  } finally {
+    process.kill = prevKill;
+    process.exitCode = prevExitCode;
+  }
+});

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; }
 }