@cohortapp/agent-sdk 2.11.15 → 2.13.0

package/lib/session/liveness.mjs

@@ -0,0 +1,174 @@
+/**
+ * lib/session/liveness.mjs — is the main session alive? Is the daemon?
+ *
+ * The daemon must never ASSUME a main session is there: liveness is MEASURED.
+ * The feed (scripts/session/feed.mjs) writes `state/session/heartbeat.json`
+ * every {@link HEARTBEAT_INTERVAL_MS}; anything that needs to know whether the
+ * front door is open calls {@link isSessionLive} and gets a boolean derived
+ * from that file's age against an injected clock. A beat older than
+ * {@link STALE_MS} (six missed beats) means the session is gone and the daemon
+ * falls back to legacy `--print` dispatch, so nothing is dropped either way.
+ *
+ * Heartbeat shape (frozen contract, read by the daemon and the doctor):
+ *
+ *   { pid, ppid, sessionId, name, ts, feedVersion }
+ *
+ * The daemon's own liveness (for the feed's `daemon-stale` directive) is the
+ * mtime of `state/dashboards/daemon-health.yaml`, rescued by a live
+ * `state/daemon.pid` — both read by the caller and handed to the pure
+ * {@link isDaemonStale}.
+ *
+ * All decisions are pure over injected inputs; the two I/O helpers
+ * ({@link writeHeartbeat}, {@link sessionLiveness}) take injectable fs and never
+ * throw.
+ *
+ * @module lib/session/liveness
+ */
+
+"use strict";
+
+import { readFileSync as fsReadFileSync } from "node:fs";
+import { writeJsonAtomic as fsWriteJsonAtomic } from "../fs-atomic.mjs";
+import { sessionPaths } from "./config.mjs";
+
+/** Bumped when the feed's line vocabulary changes. Carried on every beat. */
+export const FEED_VERSION = "1";
+/** How often the feed beats. */
+export const HEARTBEAT_INTERVAL_MS = 15_000;
+/** A beat older than this means the session is not live (six missed beats). */
+export const STALE_MS = 90_000;
+/** A daemon health file older than this (with no live pid) is a stale daemon. */
+export const DAEMON_STALE_MS = 5 * 60_000;
+
+function nowMs(now) { return typeof now === "function" ? Number(now()) : (now == null ? Date.now() : Number(now)); }
+
+/**
+ * Pure: the heartbeat record.
+ * @param {{pid:number, ppid:number, sessionId:string|null, name:string, now?:number|Function, feedVersion?:string}} a
+ */
+export function buildHeartbeat(a) {
+  return {
+    pid: a.pid,
+    ppid: a.ppid,
+    sessionId: a.sessionId ?? null,
+    name: a.name,
+    ts: new Date(nowMs(a.now)).toISOString(),
+    feedVersion: a.feedVersion || FEED_VERSION,
+  };
+}
+
+/**
+ * Pure: parse a heartbeat file body. Null unless it carries a parseable `ts`.
+ * @param {string|null|undefined} text
+ */
+export function parseHeartbeat(text) {
+  if (typeof text !== "string" || !text.trim()) return null;
+  let raw;
+  try { raw = JSON.parse(text); } catch { return null; }
+  if (!raw || typeof raw !== "object" || typeof raw.ts !== "string" || !Number.isFinite(Date.parse(raw.ts))) return null;
+  return {
+    pid: Number.isInteger(raw.pid) ? raw.pid : null,
+    ppid: Number.isInteger(raw.ppid) ? raw.ppid : null,
+    sessionId: typeof raw.sessionId === "string" ? raw.sessionId : null,
+    name: typeof raw.name === "string" ? raw.name : "",
+    ts: raw.ts,
+    feedVersion: typeof raw.feedVersion === "string" ? raw.feedVersion : "",
+  };
+}
+
+/**
+ * Pure: is this heartbeat live at `now`?
+ *
+ * Liveness is a WINDOW around `now`, not a one-sided age: a beat older than
+ * `staleMs` is stale, and a beat further in the FUTURE than `staleMs` is
+ * clock skew — the clock was stepped back after the beat was written (NTP,
+ * a manual correction), so the beat says nothing about whether the feed is
+ * running now. Both read as not-live, because the daemon's fallback for
+ * not-live is legacy dispatch (fail-open): a wrong "live" withholds every
+ * inbound item for the size of the step, a wrong "not live" costs one
+ * double-handled item at most. Small skew (under `staleMs`) is tolerated so
+ * a resume/suspend jitter does not evict a real session. An optional
+ * `pidAlive(pid)` probe lets a caller refuse a fresh beat whose writer is
+ * known to be dead.
+ *
+ * @param {ReturnType<typeof parseHeartbeat>} hb
+ * @param {{now?:number|Function, staleMs?:number, pidAlive?:(pid:number)=>boolean}} [opts]
+ * @returns {{live:boolean, reason:"fresh"|"stale"|"skew"|"missing"|"pid-dead", ageMs:number|null}}
+ */
+export function heartbeatLiveness(hb, opts = {}) {
+  if (!hb) return { live: false, reason: "missing", ageMs: null };
+  const staleMs = opts.staleMs ?? STALE_MS;
+  const ageMs = nowMs(opts.now) - Date.parse(hb.ts);
+  if (ageMs >= staleMs) return { live: false, reason: "stale", ageMs };
+  if (ageMs <= -staleMs) return { live: false, reason: "skew", ageMs };
+  if (typeof opts.pidAlive === "function" && Number.isInteger(hb.pid) && hb.pid > 0) {
+    let alive = true;
+    try { alive = !!opts.pidAlive(hb.pid); } catch { alive = true; /* probe failure must not evict a fresh beat */ }
+    if (!alive) return { live: false, reason: "pid-dead", ageMs };
+  }
+  return { live: true, reason: "fresh", ageMs };
+}
+
+/**
+ * Write the heartbeat atomically (tmp + rename). Result frame, never throws.
+ * @param {string} agentRoot @param {object} hb @param {{writeJsonAtomic?:Function}} [deps]
+ * @returns {{ok:true}|{ok:false, error:string}}
+ */
+export function writeHeartbeat(agentRoot, hb, deps = {}) {
+  const writeJsonAtomic = deps.writeJsonAtomic || fsWriteJsonAtomic;
+  try {
+    writeJsonAtomic(sessionPaths(agentRoot).heartbeatFile, hb);
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err && err.message ? err.message : String(err) };
+  }
+}
+
+/**
+ * Read the heartbeat file and judge it. Fail-open: any read error is
+ * "missing" (not live), because a daemon that cannot see a beat must dispatch.
+ *
+ * @param {string} agentRoot
+ * @param {{now?:number|Function, staleMs?:number, pidAlive?:Function, readFileSync?:Function}} [opts]
+ * @returns {{live:boolean, reason:string, ageMs:number|null, heartbeat:object|null}}
+ */
+export function sessionLiveness(agentRoot, opts = {}) {
+  const readFileSync = opts.readFileSync || fsReadFileSync;
+  let hb = null;
+  try {
+    hb = parseHeartbeat(readFileSync(sessionPaths(agentRoot).heartbeatFile, "utf8"));
+  } catch {
+    // No heartbeat file: no session has ever run here, or it is gone. Not live.
+    hb = null;
+  }
+  return { ...heartbeatLiveness(hb, opts), heartbeat: hb };
+}
+
+/**
+ * The boolean the daemon asks for: is the main session live right now?
+ * @param {string} agentRoot
+ * @param {{now?:number|Function, staleMs?:number, pidAlive?:Function, readFileSync?:Function}} [opts]
+ */
+export function isSessionLive(agentRoot, opts = {}) {
+  return sessionLiveness(agentRoot, opts).live;
+}
+
+/**
+ * Pure: is the daemon stale? Fresh health-file mtime → no. A live daemon pid
+ * → no (a daemon can be up while its dashboard writer is behind). Otherwise,
+ * an absent or old health file is stale.
+ *
+ * @param {{healthMtimeMs:number|null, pidAlive:boolean|null, now?:number|Function, staleMs?:number}} a
+ */
+export function isDaemonStale(a) {
+  if (a.pidAlive === true) return false;
+  const staleMs = a.staleMs ?? DAEMON_STALE_MS;
+  if (!Number.isFinite(a.healthMtimeMs)) return true;
+  return nowMs(a.now) - a.healthMtimeMs >= staleMs;
+}
+
+export default {
+  FEED_VERSION, HEARTBEAT_INTERVAL_MS, STALE_MS, DAEMON_STALE_MS,
+  buildHeartbeat, parseHeartbeat, heartbeatLiveness, writeHeartbeat,
+  sessionLiveness, isSessionLive, isDaemonStale,
+};

package/lib/session/liveness.test.mjs

@@ -0,0 +1,100 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { join } from "node:path";
+
+import {
+  FEED_VERSION,
+  HEARTBEAT_INTERVAL_MS,
+  STALE_MS,
+  DAEMON_STALE_MS,
+  buildHeartbeat,
+  parseHeartbeat,
+  heartbeatLiveness,
+  writeHeartbeat,
+  sessionLiveness,
+  isSessionLive,
+  isDaemonStale,
+} from "./liveness.mjs";
+
+const T0 = Date.parse("2026-09-08T10:00:00Z");
+const UUID = "11111111-2222-4333-8444-555555555555";
+
+test("constants: 15 s beat, 90 s stale, 5 min daemon stale", () => {
+  assert.equal(HEARTBEAT_INTERVAL_MS, 15_000);
+  assert.equal(STALE_MS, 90_000);
+  assert.equal(DAEMON_STALE_MS, 5 * 60_000);
+  assert.equal(typeof FEED_VERSION, "string");
+});
+
+test("buildHeartbeat: exactly the documented fields, ts from the injected clock", () => {
+  const hb = buildHeartbeat({ pid: 10, ppid: 9, sessionId: UUID, name: "olivia-main", now: T0 });
+  assert.deepEqual(hb, { pid: 10, ppid: 9, sessionId: UUID, name: "olivia-main", ts: "2026-09-08T10:00:00.000Z", feedVersion: FEED_VERSION });
+});
+
+test("parseHeartbeat: round-trip; junk → null", () => {
+  const hb = buildHeartbeat({ pid: 10, ppid: 9, sessionId: UUID, name: "n", now: T0 });
+  assert.deepEqual(parseHeartbeat(JSON.stringify(hb)), hb);
+  assert.equal(parseHeartbeat("{"), null);
+  assert.equal(parseHeartbeat(JSON.stringify({ pid: 1 })), null); // no ts
+  assert.equal(parseHeartbeat(JSON.stringify({ ts: "yesterday" })), null);
+  assert.equal(parseHeartbeat(undefined), null);
+});
+
+test("heartbeatLiveness: fresh → live; older than staleMs → stale; slightly future-dated beats are live", () => {
+  const hb = buildHeartbeat({ pid: 1, ppid: 0, sessionId: UUID, name: "n", now: T0 });
+  assert.deepEqual(heartbeatLiveness(hb, { now: T0 + 30_000 }), { live: true, reason: "fresh", ageMs: 30_000 });
+  assert.deepEqual(heartbeatLiveness(hb, { now: T0 + 90_000 }), { live: false, reason: "stale", ageMs: 90_000 });
+  assert.equal(heartbeatLiveness(hb, { now: T0 + 89_999 }).live, true);
+  assert.equal(heartbeatLiveness(hb, { now: T0 + 10_000, staleMs: 5_000 }).live, false);
+  assert.equal(heartbeatLiveness(hb, { now: T0 - 5_000 }).live, true);
+  assert.deepEqual(heartbeatLiveness(null, { now: T0 }), { live: false, reason: "missing", ageMs: null });
+});
+
+test("heartbeatLiveness: a beat further in the FUTURE than staleMs is clock skew, not liveness (fail-open to dispatch)", () => {
+  // The feed beat at T0, the session died, and NTP stepped the clock back
+  // 20 min: without a bound the dead session would read as live for 20 min
+  // and the daemon would withhold dispatch the whole time.
+  const hb = buildHeartbeat({ pid: 1, ppid: 0, sessionId: UUID, name: "n", now: T0 });
+  assert.deepEqual(heartbeatLiveness(hb, { now: T0 - 20 * 60_000 }), { live: false, reason: "skew", ageMs: -20 * 60_000 });
+  assert.deepEqual(heartbeatLiveness(hb, { now: T0 - 90_000 }), { live: false, reason: "skew", ageMs: -90_000 });
+  assert.equal(heartbeatLiveness(hb, { now: T0 - 89_999 }).live, true);
+  assert.equal(heartbeatLiveness(hb, { now: T0 - 6_000, staleMs: 5_000 }).reason, "skew");
+});
+
+test("heartbeatLiveness: a beat whose pid is known-dead is not live even when fresh", () => {
+  const hb = buildHeartbeat({ pid: 4242, ppid: 0, sessionId: UUID, name: "n", now: T0 });
+  const r = heartbeatLiveness(hb, { now: T0 + 1_000, pidAlive: () => false });
+  assert.deepEqual(r, { live: false, reason: "pid-dead", ageMs: 1_000 });
+  // pid liveness is optional: without a probe, freshness decides.
+  assert.equal(heartbeatLiveness(hb, { now: T0 + 1_000 }).live, true);
+});
+
+test("writeHeartbeat: atomic write to state/session/heartbeat.json; failure is a value", () => {
+  const disk = {};
+  const hb = buildHeartbeat({ pid: 1, ppid: 0, sessionId: UUID, name: "n", now: T0 });
+  assert.deepEqual(writeHeartbeat("/agent", hb, { writeJsonAtomic: (p, o) => { disk[p] = o; } }), { ok: true });
+  assert.deepEqual(disk[join("/agent", "state", "session", "heartbeat.json")], hb);
+  const bad = writeHeartbeat("/agent", hb, { writeJsonAtomic: () => { throw new Error("ENOSPC"); } });
+  assert.equal(bad.ok, false);
+  assert.match(bad.error, /ENOSPC/);
+});
+
+test("sessionLiveness / isSessionLive read the heartbeat file through injected fs", () => {
+  const hb = buildHeartbeat({ pid: process.pid, ppid: 0, sessionId: UUID, name: "n", now: T0 });
+  const deps = { readFileSync: (p) => { assert.equal(p, join("/agent", "state", "session", "heartbeat.json")); return JSON.stringify(hb); } };
+  const r = sessionLiveness("/agent", { now: T0 + 1_000, ...deps });
+  assert.equal(r.live, true);
+  assert.equal(r.heartbeat.sessionId, UUID);
+  assert.equal(isSessionLive("/agent", { now: T0 + 1_000, ...deps }), true);
+  assert.equal(isSessionLive("/agent", { now: T0 + 100_000, ...deps }), false);
+  assert.equal(isSessionLive("/agent", { now: T0, readFileSync: () => { throw new Error("ENOENT"); } }), false);
+  assert.deepEqual(sessionLiveness("/agent", { now: T0, readFileSync: () => { throw new Error("ENOENT"); } }), { live: false, reason: "missing", ageMs: null, heartbeat: null });
+});
+
+test("isDaemonStale: fresh health file → not stale; old health + dead pid → stale; a live pid rescues an old file", () => {
+  assert.equal(isDaemonStale({ healthMtimeMs: T0 - 60_000, pidAlive: false, now: T0 }), false);
+  assert.equal(isDaemonStale({ healthMtimeMs: T0 - 6 * 60_000, pidAlive: false, now: T0 }), true);
+  assert.equal(isDaemonStale({ healthMtimeMs: T0 - 6 * 60_000, pidAlive: true, now: T0 }), false);
+  assert.equal(isDaemonStale({ healthMtimeMs: null, pidAlive: null, now: T0 }), true);
+  assert.equal(isDaemonStale({ healthMtimeMs: null, pidAlive: true, now: T0 }), false);
+});

package/lib/session/status-summary.mjs

@@ -0,0 +1,172 @@
+/**
+ * lib/session/status-summary.mjs — the pure session-status core.
+ *
+ * ONE derivation of "is the main session live, who are its peers, what is
+ * waiting for it" shared by three consumers: the cohort-mcp `session_status`
+ * tool, the SessionStart `prime` hook (which injects a one-line status into
+ * every new session on the machine), and `maestro board`. The feed
+ * (scripts/session/feed.mjs) writes `state/session/heartbeat.json` every 15 s;
+ * `maestro session spawn` keeps `state/session/peers.json`; the cadence
+ * consumer drops `state/session/handoffs/<tickId>.json`; the daemon caches
+ * `board.mine` to `state/org/board-mine.json` (`{ts, items}`) every 5 min via
+ * lib/org/board-mine-cache.mjs. This module only
+ * READS those — the writers own their formats and this tolerates every
+ * partial/absent/corrupt shape by reporting "absent", never by throwing.
+ *
+ * `summarizeSessionStatus` is pure over injected snapshots + `now`;
+ * `readSessionStatus` is the thin disk reader around it.
+ *
+ * @module lib/session/status-summary
+ */
+
+"use strict";
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { buildIdentityClaudeMd, IDENTITY_BEGIN, IDENTITY_END } from "../collective/global-config.mjs";
+
+/** A heartbeat older than this is a dead or wedged session (feed beats every 15 s). */
+export const DEFAULT_STALE_MS = 90_000;
+
+function toMs(v) {
+  if (typeof v === "number" && Number.isFinite(v)) return v;
+  if (typeof v === "string") {
+    const n = Date.parse(v);
+    if (Number.isFinite(n)) return n;
+    const asNum = Number(v);
+    if (Number.isFinite(asNum) && v.trim() !== "") return asNum;
+  }
+  return null;
+}
+
+function itemsOf(boardMine) {
+  if (Array.isArray(boardMine)) return boardMine;
+  if (boardMine && typeof boardMine === "object" && Array.isArray(boardMine.items)) return boardMine.items;
+  return [];
+}
+
+function peersOf(peers) {
+  if (Array.isArray(peers)) return peers.filter((p) => p && typeof p === "object");
+  if (peers && typeof peers === "object" && Array.isArray(peers.peers)) return peers.peers.filter((p) => p && typeof p === "object");
+  return [];
+}
+
+/**
+ * Derive the session status from snapshots. Pure.
+ *
+ * @param {object} o
+ * @param {object|null} [o.heartbeat] - state/session/heartbeat.json
+ * @param {object[]|object|null} [o.peers] - state/session/peers.json (array, or {peers:[]})
+ * @param {string[]|null} [o.handoffs] - names of open handoff files
+ * @param {object|object[]|null} [o.boardMine] - state/org/board-mine.json ({ts, items}; older {items, fetchedAt}) or a bare array
+ * @param {number} [o.now]
+ * @param {number} [o.staleMs]
+ */
+export function summarizeSessionStatus(o = {}) {
+  const now = Number.isFinite(o.now) ? o.now : Date.now();
+  const staleMs = Number.isFinite(o.staleMs) && o.staleMs > 0 ? o.staleMs : DEFAULT_STALE_MS;
+  const hb = o.heartbeat && typeof o.heartbeat === "object" ? o.heartbeat : null;
+  const ts = hb ? toMs(hb.ts) : null;
+  let state = "absent";
+  let ageMs = null;
+  if (ts !== null) {
+    ageMs = Math.max(0, now - ts);
+    state = ageMs <= staleMs ? "live" : "stale";
+  }
+  const peers = peersOf(o.peers);
+  const handoffs = Array.isArray(o.handoffs) ? o.handoffs.filter((h) => typeof h === "string") : [];
+  const items = itemsOf(o.boardMine);
+  // The daemon writes {ts, items} (lib/org/board-mine-cache.mjs); fetchedAt is the earlier spelling.
+  const bm = o.boardMine && typeof o.boardMine === "object" && !Array.isArray(o.boardMine) ? o.boardMine : null;
+  const fetchedAt = bm && typeof bm.fetchedAt === "string" ? bm.fetchedAt : bm && typeof bm.ts === "string" ? bm.ts : null;
+  return {
+    live: state === "live",
+    state,
+    name: hb && typeof hb.name === "string" ? hb.name : null,
+    sessionId: hb && typeof hb.sessionId === "string" ? hb.sessionId : null,
+    pid: hb && Number.isFinite(hb.pid) ? hb.pid : null,
+    heartbeatAt: ts === null ? null : new Date(ts).toISOString(),
+    ageMs,
+    staleMs,
+    peers: peers.map((p) => ({
+      name: typeof p.name === "string" ? p.name : null,
+      purpose: typeof p.purpose === "string" ? p.purpose : null,
+      startedAt: typeof p.startedAt === "string" ? p.startedAt : null,
+    })),
+    peerCount: peers.length,
+    handoffsOpen: handoffs.length,
+    handoffs,
+    boardMineCount: items.length,
+    boardMineFetchedAt: fetchedAt,
+  };
+}
+
+function plural(n, word) { return `${n} ${word}${n === 1 ? "" : "s"}`; }
+
+/** One line for a primer: "main session alex-main live (beat 5s ago) · 1 peer · 1 open handoff · 2 board items". */
+export function statusLine(s) {
+  const st = s && typeof s === "object" ? s : summarizeSessionStatus({});
+  const who = st.name ? `main session ${st.name}` : "main session";
+  let head;
+  if (st.state === "live") head = `${who} live (beat ${Math.round((st.ageMs || 0) / 1000)}s ago)`;
+  else if (st.state === "stale") head = `${who} stale (last beat ${Math.round((st.ageMs || 0) / 1000)}s ago)`;
+  else head = `${who} not running (no heartbeat)`;
+  return [
+    head,
+    plural(st.peerCount || 0, "peer"),
+    plural(st.handoffsOpen || 0, "open handoff"),
+    plural(st.boardMineCount || 0, "board item") + (st.boardMineFetchedAt ? " (cached)" : ""),
+  ].join(" · ");
+}
+
+function readJson(p) {
+  try {
+    if (!existsSync(p)) return null;
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch {
+    return null; // absent/corrupt state is "not running", never a crash in a hook
+  }
+}
+
+/**
+ * Read the four state files under an agent root and summarise. Fail-open:
+ * an unreadable file is the same as an absent one.
+ * @param {string} agentRoot
+ * @param {{now?:number, staleMs?:number}} [o]
+ */
+export function readSessionStatus(agentRoot, o = {}) {
+  const root = String(agentRoot || "");
+  const sess = join(root, "state", "session");
+  let handoffs = [];
+  try {
+    const dir = join(sess, "handoffs");
+    if (existsSync(dir)) handoffs = readdirSync(dir).filter((f) => f.endsWith(".json"));
+  } catch {
+    handoffs = []; // a vanished directory mid-read is an empty queue
+  }
+  return summarizeSessionStatus({
+    heartbeat: readJson(join(sess, "heartbeat.json")),
+    peers: readJson(join(sess, "peers.json")),
+    handoffs,
+    boardMine: readJson(join(root, "state", "org", "board-mine.json")),
+    now: o.now,
+    staleMs: o.staleMs,
+  });
+}
+
+/**
+ * The SessionStart primer text: the identity block (delimited, so a reader can
+ * tell it from the memory digest) + the one-line status. Empty when the
+ * agent has no identity yet (a bare/unconfigured repo says nothing).
+ * @param {{agentJson:object, agentRoot:string, status:object}} o
+ * @returns {string}
+ */
+export function buildPrimerContext(o = {}) {
+  const a = o.agentJson && typeof o.agentJson === "object" ? o.agentJson : null;
+  if (!a || !(a.fullName || a.firstName)) return "";
+  const block = buildIdentityClaudeMd(a, { agentRoot: o.agentRoot });
+  const status = o.status && typeof o.status === "object" ? o.status : summarizeSessionStatus({});
+  return [IDENTITY_BEGIN, block, IDENTITY_END, "", `Session status: ${statusLine(status)}.`].join("\n");
+}
+
+export default { summarizeSessionStatus, readSessionStatus, statusLine, buildPrimerContext, DEFAULT_STALE_MS };

package/lib/session/status-summary.test.mjs

@@ -0,0 +1,118 @@
+/**
+ * status-summary.test.mjs — the pure session-status core the cohort-mcp
+ * `session_status` tool, the SessionStart primer and `maestro board` share.
+ * Run: node --test lib/session/status-summary.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  summarizeSessionStatus, readSessionStatus, statusLine, buildPrimerContext, DEFAULT_STALE_MS,
+} from "./status-summary.mjs";
+
+const NOW = Date.parse("2026-09-08T12:00:00Z");
+
+test("summarizeSessionStatus: live when the heartbeat is fresh, stale past staleMs, absent when missing", () => {
+  const fresh = summarizeSessionStatus({
+    heartbeat: { pid: 1, sessionId: "abc", name: "alex-main", ts: new Date(NOW - 10_000).toISOString() },
+    now: NOW,
+  });
+  assert.equal(fresh.live, true);
+  assert.equal(fresh.state, "live");
+  assert.equal(fresh.name, "alex-main");
+  assert.equal(fresh.ageMs, 10_000);
+  const stale = summarizeSessionStatus({ heartbeat: { ts: NOW - DEFAULT_STALE_MS - 1 }, now: NOW });
+  assert.equal(stale.live, false);
+  assert.equal(stale.state, "stale");
+  const none = summarizeSessionStatus({ heartbeat: null, now: NOW });
+  assert.equal(none.live, false);
+  assert.equal(none.state, "absent");
+  const garbage = summarizeSessionStatus({ heartbeat: { ts: "not a date" }, now: NOW });
+  assert.equal(garbage.state, "absent", "unparseable ts is absent, never a throw");
+});
+
+test("summarizeSessionStatus: counts peers, open handoffs and board-mine items; tolerates garbage", () => {
+  const s = summarizeSessionStatus({
+    heartbeat: { ts: NOW },
+    peers: [{ name: "alex-research" }, { name: "alex-deck" }],
+    handoffs: ["t1.json", "t2.json", "t3.json"],
+    boardMine: { items: [{ itemId: "a" }, { itemId: "b" }], fetchedAt: new Date(NOW - 60_000).toISOString() },
+    now: NOW,
+  });
+  assert.equal(s.peers.length, 2);
+  assert.equal(s.peerCount, 2);
+  assert.equal(s.handoffsOpen, 3);
+  assert.equal(s.boardMineCount, 2);
+  assert.equal(s.boardMineFetchedAt, new Date(NOW - 60_000).toISOString());
+  const g = summarizeSessionStatus({ peers: "x", handoffs: null, boardMine: [1, 2, 3], now: NOW });
+  assert.equal(g.peerCount, 0);
+  assert.equal(g.handoffsOpen, 0);
+  assert.equal(g.boardMineCount, 3, "a bare array is accepted as the item list");
+  const g2 = summarizeSessionStatus({ boardMine: { nope: true }, now: NOW });
+  assert.equal(g2.boardMineCount, 0);
+  assert.equal(g2.boardMineFetchedAt, null);
+});
+
+test("statusLine: one line a primer can inject", () => {
+  const s = summarizeSessionStatus({
+    heartbeat: { ts: NOW - 5_000, name: "alex-main" },
+    peers: [{ name: "alex-deck" }],
+    handoffs: ["a"],
+    boardMine: { items: [{}, {}] },
+    now: NOW,
+  });
+  const line = statusLine(s);
+  assert.equal(line.split("\n").length, 1);
+  assert.match(line, /alex-main/);
+  assert.match(line, /live/);
+  assert.match(line, /1 peer/);
+  assert.match(line, /1 open handoff/);
+  assert.match(line, /2 board item/);
+  const absent = statusLine(summarizeSessionStatus({ now: NOW }));
+  assert.match(absent, /not running|absent/i);
+});
+
+test("readSessionStatus: reads state/session/{heartbeat,peers}.json, handoffs/*.json and state/org/board-mine.json; fail-open", () => {
+  const root = mkdtempSync(join(tmpdir(), "status-summary-"));
+  try {
+    assert.equal(readSessionStatus(root, { now: NOW }).state, "absent", "empty root → absent, no throw");
+    mkdirSync(join(root, "state", "session", "handoffs", "done"), { recursive: true });
+    mkdirSync(join(root, "state", "org"), { recursive: true });
+    writeFileSync(join(root, "state", "session", "heartbeat.json"), JSON.stringify({ pid: 9, name: "alex-main", ts: NOW - 1000 }));
+    writeFileSync(join(root, "state", "session", "peers.json"), JSON.stringify([{ name: "alex-deck", muxName: "m" }]));
+    writeFileSync(join(root, "state", "session", "handoffs", "t1.json"), "{}");
+    writeFileSync(join(root, "state", "session", "handoffs", "t2.json"), "{}");
+    writeFileSync(join(root, "state", "session", "handoffs", "notes.txt"), "x");
+    writeFileSync(join(root, "state", "session", "handoffs", "done", "t0.json"), "{}");
+    writeFileSync(join(root, "state", "org", "board-mine.json"), JSON.stringify({ items: [{ itemId: "i1" }], fetchedAt: "2026-09-08T11:59:00.000Z" }));
+    const s = readSessionStatus(root, { now: NOW });
+    assert.equal(s.live, true);
+    assert.equal(s.name, "alex-main");
+    assert.equal(s.peerCount, 1);
+    assert.equal(s.handoffsOpen, 2, "only *.json in handoffs/, not done/ or other files");
+    assert.equal(s.boardMineCount, 1);
+    // peers.json may also be an object with a `peers` array.
+    writeFileSync(join(root, "state", "session", "peers.json"), JSON.stringify({ peers: [{ name: "a" }, { name: "b" }] }));
+    assert.equal(readSessionStatus(root, { now: NOW }).peerCount, 2);
+    // Corrupt files are absent, not fatal.
+    writeFileSync(join(root, "state", "session", "heartbeat.json"), "{not json");
+    assert.equal(readSessionStatus(root, { now: NOW }).state, "absent");
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("buildPrimerContext: identity block + status line + counts; empty when there is no agent identity", () => {
+  const status = summarizeSessionStatus({ heartbeat: { ts: NOW, name: "alex-main" }, handoffs: ["a", "b"], boardMine: { items: [{}] }, now: NOW });
+  const ctx = buildPrimerContext({ agentJson: { fullName: "Alex Rivera", firstName: "Alex" }, agentRoot: "/r/alex-ai", status });
+  assert.match(ctx, /maestro:identity/);
+  assert.match(ctx, /Alex Rivera/);
+  assert.match(ctx, /alex-main/);
+  assert.match(ctx, /2 open handoffs/);
+  assert.match(ctx, /1 board item/);
+  assert.equal(buildPrimerContext({ agentJson: {}, agentRoot: "/r", status }), "", "no identity → nothing to say");
+  assert.equal(buildPrimerContext({ agentJson: null, agentRoot: "/r", status }), "");
+});

package/lib/session-permissions.mjs

@@ -20,7 +20,9 @@
  * (`--strict-mcp-config` / `--bare`) exactly as before, so `--strict-mcp-config`
  * is preserved in BOTH modes.
  *
- * Caller sites (today): scripts/daemon/cadence-consumer.mjs#realSpawnSession.
+ * Caller sites (today): scripts/daemon/cadence-consumer.mjs#realSpawnSession,
+ * classifier/responder/assurance (`source`), and the front-door supervisor
+ * (`source: "main-session"`, see {@link MAIN_SESSION_SOURCE}).
  */
 
 import { getCadenceDef } from "../scripts/daemon/cadence-handlers.mjs";
@@ -64,6 +66,29 @@ function resolveAllowlist(cadence) {
   return [...CONSERVATIVE_DEFAULT_ALLOWLIST];
 }
 
+/**
+ * The `source` the front-door supervisor passes. The main session is an
+ * INTERACTIVE `claude` inside a multiplexer with nobody attached: any tool
+ * outside its allowlist raises a y/n prompt that no one can answer, and the
+ * session wedges while its feed keeps beating (so the daemon believes the
+ * front door is open and withholds dispatch). The conservative `--print`
+ * allowlist therefore never applies to it — in scoped mode it gets either
+ * the operator's explicit main-session allowlist (`config/session.yaml`
+ * `allowedTools`) or, absent one, bypass.
+ */
+export const MAIN_SESSION_SOURCE = "main-session";
+
+/**
+ * Pure: a caller-supplied allowlist, cleaned. Non-array / empty → null.
+ * @param {unknown} list
+ * @returns {string[]|null}
+ */
+function explicitAllowlist(list) {
+  if (!Array.isArray(list)) return null;
+  const cleaned = list.filter((t) => typeof t === "string" && t.trim()).map((t) => t.trim());
+  return cleaned.length > 0 ? cleaned : null;
+}
+
 /**
  * Build the `claude` CLI permission args for a spawned sub-session.
  *
@@ -83,12 +108,19 @@ function resolveAllowlist(cadence) {
  * via `.env` and have a long-lived daemon pick it up on the next spawn without
  * a code change.
  *
+ *   - "1" with `source: "main-session"` — the interactive front door. Uses
+ *     `allowedTools` when the caller supplies a non-empty list, else bypass;
+ *     the conservative `--print` default is never applied (it would hang an
+ *     unattended interactive session on its first permission prompt).
+ *
  * @param {Object} [opts]
  * @param {string} [opts.cadence] cadence name; used to look up a per-cadence allowlist in scoped mode.
  * @param {string} [opts.mode]    cadence mode ("inline"|"guarded"|"escalate"); accepted for forward-compat (future per-mode tightening), currently unused.
- * @returns {string[]} permission CLI args to splice into the `claude --print` argv.
+ * @param {string} [opts.source]  who is spawning ("classifier", "responder", "ack", "main-session", …); only {@link MAIN_SESSION_SOURCE} changes the result.
+ * @param {string[]} [opts.allowedTools] main-session only: an explicit allowlist from config/session.yaml.
+ * @returns {string[]} permission CLI args to splice into the `claude` argv.
  */
-export function sessionPermissionArgs({ cadence, mode } = {}) {
+export function sessionPermissionArgs({ cadence, mode, source, allowedTools } = {}) {
   // `mode` is reserved for future per-mode tightening; reference it so linters
   // don't flag it as unused while keeping the signature stable for callers.
   void mode;
@@ -96,6 +128,10 @@ export function sessionPermissionArgs({ cadence, mode } = {}) {
     // Default / back-compat: UNCHANGED behaviour.
     return ["--dangerously-skip-permissions"];
   }
+  if (source === MAIN_SESSION_SOURCE) {
+    const explicit = explicitAllowlist(allowedTools);
+    return explicit ? ["--allowedTools", explicit.join(",")] : ["--dangerously-skip-permissions"];
+  }
   const allow = resolveAllowlist(cadence);
   return ["--allowedTools", allow.join(",")];
 }

package/lib/session-permissions.test.mjs

@@ -98,3 +98,23 @@ test("conservative default allowlist is read-only / search-only (no write, shell
   // And it must be non-empty so scoped mode never emits an empty allowlist.
   assert.ok(CONSERVATIVE_DEFAULT_ALLOWLIST.length > 0);
 });
+
+test("main session: scoped mode never hands the interactive front door the --print allowlist (it would hang on the first prompt)", () => {
+  withScopedEnv("1", () => {
+    // No main-session allowlist configured → bypass, because nobody is
+    // attached to answer a y/n prompt inside the multiplexer.
+    assert.deepEqual(sessionPermissionArgs({ source: "main-session" }), ["--dangerously-skip-permissions"]);
+    assert.deepEqual(sessionPermissionArgs({ source: "main-session", allowedTools: [] }), ["--dangerously-skip-permissions"]);
+    assert.deepEqual(sessionPermissionArgs({ source: "main-session", allowedTools: "Read" }), ["--dangerously-skip-permissions"]);
+    // An operator-defined main-session allowlist IS honoured.
+    assert.deepEqual(
+      sessionPermissionArgs({ source: "main-session", allowedTools: ["Read", " Monitor ", "", 3, "mcp__cohort__*"] }),
+      ["--allowedTools", "Read,Monitor,mcp__cohort__*"],
+    );
+    // Other sources are untouched by the new option.
+    assert.deepEqual(sessionPermissionArgs({ source: "responder", allowedTools: ["Bash"] }), ["--allowedTools", CONSERVATIVE_DEFAULT_ALLOWLIST.join(",")]);
+  });
+  withScopedEnv(undefined, () => {
+    assert.deepEqual(sessionPermissionArgs({ source: "main-session", allowedTools: ["Read"] }), ["--dangerously-skip-permissions"]);
+  });
+});