@cohortapp/agent-sdk 2.11.14 → 2.12.0

package/lib/session/first-run.test.mjs

@@ -0,0 +1,121 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { join } from "node:path";
+
+import {
+  CLAUDE_CONFIG_FILE,
+  HEARTBEAT_GRACE_MS,
+  seedClaudeConfig,
+  ensureClaudeConfig,
+  heartbeatSilence,
+  attentionRecord,
+} from "./first-run.mjs";
+
+const ROOT = "/Users/o/olivia-ai";
+const T0 = Date.parse("2026-09-08T10:00:00Z");
+
+test("seedClaudeConfig: an absent/empty ~/.claude.json gets both acknowledgements", () => {
+  for (const text of [undefined, null, "", "   "]) {
+    const r = seedClaudeConfig(text, { agentRoot: ROOT, bypass: true });
+    assert.equal(r.ok, true);
+    assert.equal(r.changed, true);
+    assert.deepEqual(r.applied, ["bypassPermissionsModeAccepted", `projects[${ROOT}].hasTrustDialogAccepted`]);
+    assert.deepEqual(r.config, { bypassPermissionsModeAccepted: true, projects: { [ROOT]: { hasTrustDialogAccepted: true } } });
+  }
+});
+
+test("seedClaudeConfig: existing keys, other projects and project fields are preserved; only the missing flags are added", () => {
+  const existing = {
+    numStartups: 40,
+    theme: "dark",
+    projects: {
+      "/Users/o/other": { hasTrustDialogAccepted: false, allowedTools: ["Bash"] },
+      [ROOT]: { allowedTools: ["Read"], hasCompletedProjectOnboarding: true },
+    },
+  };
+  const r = seedClaudeConfig(JSON.stringify(existing), { agentRoot: ROOT, bypass: true });
+  assert.equal(r.changed, true);
+  assert.deepEqual(r.config, {
+    numStartups: 40,
+    theme: "dark",
+    bypassPermissionsModeAccepted: true,
+    projects: {
+      "/Users/o/other": { hasTrustDialogAccepted: false, allowedTools: ["Bash"] },
+      [ROOT]: { allowedTools: ["Read"], hasCompletedProjectOnboarding: true, hasTrustDialogAccepted: true },
+    },
+  });
+});
+
+test("seedClaudeConfig: already seeded → unchanged (idempotent); bypass:false leaves the bypass flag alone", () => {
+  const seeded = { bypassPermissionsModeAccepted: true, projects: { [ROOT]: { hasTrustDialogAccepted: true } } };
+  const r = seedClaudeConfig(JSON.stringify(seeded), { agentRoot: ROOT, bypass: true });
+  assert.equal(r.changed, false);
+  assert.deepEqual(r.applied, []);
+  const r2 = seedClaudeConfig("{}", { agentRoot: ROOT, bypass: false });
+  assert.deepEqual(r2.applied, [`projects[${ROOT}].hasTrustDialogAccepted`]);
+  assert.equal("bypassPermissionsModeAccepted" in r2.config, false);
+});
+
+test("seedClaudeConfig: a malformed or non-object file is NOT clobbered", () => {
+  for (const text of ["{", "[1,2]", "42", "null"]) {
+    const r = seedClaudeConfig(text, { agentRoot: ROOT, bypass: true });
+    assert.equal(r.ok, false, text);
+    assert.equal(r.changed, false);
+    assert.match(r.error, /malformed|not an object/);
+  }
+});
+
+test("ensureClaudeConfig: writes ~/.claude.json only when something changed; never throws", () => {
+  const home = "/Users/o";
+  const file = join(home, CLAUDE_CONFIG_FILE);
+  const writes = [];
+  const deps = (files) => ({
+    readFileSync: (p) => { if (!(p in files)) { const e = new Error("ENOENT"); e.code = "ENOENT"; throw e; } return files[p]; },
+    writeFileAtomic: (p, data) => { writes.push([p, String(data)]); },
+  });
+  // Absent → written.
+  let r = ensureClaudeConfig({ homeDir: home, agentRoot: ROOT, bypass: true, ...deps({}) });
+  assert.equal(r.ok, true);
+  assert.equal(r.changed, true);
+  assert.equal(r.path, file);
+  assert.equal(writes.length, 1);
+  assert.deepEqual(JSON.parse(writes[0][1]), { bypassPermissionsModeAccepted: true, projects: { [ROOT]: { hasTrustDialogAccepted: true } } });
+  // Already seeded → no write.
+  r = ensureClaudeConfig({ homeDir: home, agentRoot: ROOT, bypass: true, ...deps({ [file]: writes[0][1] }) });
+  assert.equal(r.changed, false);
+  assert.equal(writes.length, 1);
+  // Malformed → reported, untouched.
+  r = ensureClaudeConfig({ homeDir: home, agentRoot: ROOT, bypass: true, ...deps({ [file]: "{oops" }) });
+  assert.equal(r.ok, false);
+  assert.equal(writes.length, 1);
+  // A throwing writer is a result, not a throw.
+  r = ensureClaudeConfig({ homeDir: home, agentRoot: ROOT, bypass: true, readFileSync: deps({}).readFileSync, writeFileAtomic: () => { throw new Error("EROFS"); } });
+  assert.equal(r.ok, false);
+  assert.match(r.error, /EROFS/);
+  // No home → nothing to do.
+  r = ensureClaudeConfig({ homeDir: "", agentRoot: ROOT, bypass: true, ...deps({}) });
+  assert.equal(r.ok, false);
+  assert.equal(writes.length, 1);
+});
+
+test("heartbeatSilence: within grace → not silent; a beat since launch → beating; no/old beat past grace → silent", () => {
+  const started = T0;
+  assert.deepEqual(heartbeatSilence({ startedAt: started, heartbeat: null, now: T0 + 10_000 }), { silent: false, reason: "within-grace", runMs: 10_000 });
+  assert.equal(HEARTBEAT_GRACE_MS, 120_000);
+  assert.deepEqual(heartbeatSilence({ startedAt: started, heartbeat: null, now: T0 + 120_000 }), { silent: true, reason: "no-heartbeat", runMs: 120_000 });
+  const old = { ts: new Date(T0 - 60_000).toISOString() }; // from the PREVIOUS lifetime
+  assert.deepEqual(heartbeatSilence({ startedAt: started, heartbeat: old, now: T0 + 120_000 }), { silent: true, reason: "stale-heartbeat", runMs: 120_000 });
+  const fresh = { ts: new Date(T0 + 15_000).toISOString() };
+  assert.deepEqual(heartbeatSilence({ startedAt: started, heartbeat: fresh, now: T0 + 120_000 }), { silent: false, reason: "beating", runMs: 120_000 });
+  assert.equal(heartbeatSilence({ startedAt: started, heartbeat: null, now: T0 + 30_000, graceMs: 20_000 }).silent, true);
+});
+
+test("attentionRecord: what the doctor reads — reason, since, the attach command for the mux in use", () => {
+  const r = attentionRecord({ reason: "no-heartbeat", mux: { kind: "screen" }, muxName: "maestro-olivia", since: T0, runMs: 120_000 });
+  assert.equal(r.reason, "no-heartbeat");
+  assert.equal(r.since, "2026-09-08T10:00:00.000Z");
+  assert.equal(r.runMs, 120_000);
+  assert.equal(r.attach, "screen -r maestro-olivia");
+  assert.match(r.hint, /dialog|prompt/i);
+  assert.equal(attentionRecord({ reason: "no-heartbeat", mux: { kind: "tmux" }, muxName: "maestro-olivia", since: T0, runMs: 1 }).attach, "tmux attach -t =maestro-olivia");
+});

package/lib/session/frontdoor.mjs

@@ -0,0 +1,266 @@
+/**
+ * lib/session/frontdoor.mjs — WHO answers an inbound event: the main session
+ * or the daemon's legacy `claude --print` lane (design §3.1, §3.3, §3.4).
+ *
+ * THE ONE RULE. When the seat's main session is the configured front door AND
+ * it is provably live (a fresh `state/session/heartbeat.json`), the daemon
+ * stops spawning for the surfaces the session owns: Cohort inbox items are
+ * left in place for the session to claim, and escalate/guarded cadence ticks
+ * are written as handoffs for the session to ack. When the session is NOT
+ * live — no heartbeat, a stale one, or the front door is `daemon` — the daemon
+ * dispatches exactly as it always has. Liveness is MEASURED, never assumed,
+ * and the fallback is the legacy lane, so nothing is ever dropped.
+ *
+ * PURE CORE. `sessionLiveFromHeartbeat`, `resolveFrontDoor`,
+ * `frontDoorServices`, `shouldDaemonDispatch` and `shouldHandOffTick` take
+ * every input as a parameter — the parsed heartbeat object, the clock, the
+ * mode, the tick's mode/metadata. `readFrontDoorState` is the ONE edge reader
+ * (config/session.yaml + state/session/heartbeat.json) and it takes its fs /
+ * env / clock injected so a call site can be tested without a disk.
+ *
+ * NOTE: `lib/session/{config,liveness}.mjs` (WP-M1) own the canonical session
+ * config + heartbeat readers once they land; the readers here are deliberately
+ * minimal and shaped to be swapped for those without touching the callers.
+ *
+ * @module lib/session/frontdoor
+ */
+
+import { join } from "node:path";
+import * as nodeFs from "node:fs";
+import { createRequire } from "node:module";
+
+// js-yaml is a declared dependency; loaded synchronously so the reader stays
+// sync. Fail-open: without it the flat line parser below still reads the
+// one-level form (`frontDoor: daemon`), and every nested form is a no-op.
+let defaultYamlParse = null;
+try {
+  const y = createRequire(import.meta.url)("js-yaml");
+  if (y && typeof y.load === "function") defaultYamlParse = (text) => y.load(text);
+} catch { defaultYamlParse = null; }
+
+/** A heartbeat older than this is stale — the session is treated as not live. */
+export const DEFAULT_STALE_MS = 90_000;
+/** Inbox services the session fronts by default. */
+export const DEFAULT_FRONT_DOOR_SERVICES = Object.freeze(["cohort"]);
+/** Cadence modes whose tick spawns a sub-session — the ones a live session takes over. */
+export const HANDOFF_MODES = Object.freeze(["escalate", "guarded"]);
+/** Where the session runtime writes its heartbeat (relative to the agent root). */
+export const HEARTBEAT_RELATIVE = "state/session/heartbeat.json";
+/** Session runtime config (relative to the agent root). */
+export const SESSION_CONFIG_RELATIVE = "config/session.yaml";
+
+const MODES = new Set(["session", "daemon"]);
+
+/**
+ * Is the main session live, given its parsed heartbeat? Pure.
+ *
+ * @param {object|null} heartbeat parsed `state/session/heartbeat.json` ({ts,...}) or null
+ * @param {object} [o]
+ * @param {number} [o.now] epoch ms
+ * @param {number} [o.staleMs] freshness window (default DEFAULT_STALE_MS)
+ * @returns {{live:boolean, reason:string, ageMs:number|null}}
+ */
+export function sessionLiveFromHeartbeat(heartbeat, o = {}) {
+  const now = typeof o.now === "number" ? o.now : Date.now();
+  const staleMs = Number.isFinite(o.staleMs) && o.staleMs > 0 ? o.staleMs : DEFAULT_STALE_MS;
+  if (!heartbeat || typeof heartbeat !== "object") return { live: false, reason: "no-heartbeat", ageMs: null };
+  const raw = heartbeat.ts;
+  const ts = typeof raw === "number" ? raw : (typeof raw === "string" ? Date.parse(raw) : NaN);
+  if (!Number.isFinite(ts)) return { live: false, reason: "bad-ts", ageMs: null };
+  const ageMs = now - ts;
+  // A slightly future stamp is writer/reader clock skew, not a dead session;
+  // a stamp further ahead than the window is a broken clock — not trusted.
+  if (ageMs < -staleMs) return { live: false, reason: "future-ts", ageMs };
+  if (ageMs > staleMs) return { live: false, reason: "stale", ageMs };
+  return { live: true, reason: "fresh", ageMs };
+}
+
+/**
+ * Which process is the front door. `MAESTRO_FRONT_DOOR` in the env wins, then
+ * `frontDoor` / `front_door` in config/session.yaml (a string, or an object
+ * with `.mode`), else `session`. An unknown value never selects a mode.
+ *
+ * @param {{env?:object, config?:object|null}} [o]
+ * @returns {"session"|"daemon"}
+ */
+export function resolveFrontDoor(o = {}) {
+  const env = o.env && typeof o.env === "object" ? o.env : {};
+  const fromEnv = String(env.MAESTRO_FRONT_DOOR || "").trim().toLowerCase();
+  if (MODES.has(fromEnv)) return fromEnv;
+  const cfg = o.config && typeof o.config === "object" ? o.config : {};
+  const raw = cfg.frontDoor !== undefined ? cfg.frontDoor : cfg.front_door;
+  const val = raw && typeof raw === "object" ? raw.mode : raw;
+  const fromCfg = String(val || "").trim().toLowerCase();
+  if (MODES.has(fromCfg)) return fromCfg;
+  return "session";
+}
+
+/**
+ * The inbox services the session fronts. `frontDoor.services` or a top-level
+ * `services` list in config/session.yaml; default `["cohort"]`.
+ *
+ * @param {object|null} config
+ * @returns {string[]}
+ */
+export function frontDoorServices(config) {
+  const cfg = config && typeof config === "object" ? config : {};
+  const fd = cfg.frontDoor && typeof cfg.frontDoor === "object" ? cfg.frontDoor : null;
+  const list = fd && Array.isArray(fd.services) ? fd.services : (Array.isArray(cfg.services) ? cfg.services : null);
+  if (!list) return [...DEFAULT_FRONT_DOOR_SERVICES];
+  const out = list.map((s) => String(s || "").trim().toLowerCase()).filter(Boolean);
+  return out.length ? out : [...DEFAULT_FRONT_DOOR_SERVICES];
+}
+
+/**
+ * Should the DAEMON dispatch an inbox item from `service`? Pure.
+ * `dispatch:false` means "leave the item in place — the live session owns it".
+ * Any malformed input resolves to dispatch (fail-open: never drop an item).
+ *
+ * @param {{frontDoor?:string, sessionLive?:boolean, service?:string, services?:string[]}} a
+ * @returns {{dispatch:boolean, reason:string}}
+ */
+export function shouldDaemonDispatch(a) {
+  const x = a && typeof a === "object" ? a : {};
+  if (x.frontDoor !== "session") return { dispatch: true, reason: "front-door-daemon" };
+  if (x.sessionLive !== true) return { dispatch: true, reason: "session-not-live" };
+  const services = Array.isArray(x.services) && x.services.length ? x.services : DEFAULT_FRONT_DOOR_SERVICES;
+  const svc = String(x.service || "").trim().toLowerCase();
+  if (!svc || !services.includes(svc)) return { dispatch: true, reason: "service-not-front-door" };
+  return { dispatch: false, reason: "session-live" };
+}
+
+/**
+ * Should the cadence consumer HAND a tick to the live session instead of
+ * spawning a sub-session? Pure. Only escalate/guarded ticks (the ones that
+ * spawn) qualify; a tick whose previous handoff timed out is never handed off
+ * again (`metadata.handoffTimedOut`), so a wedged session cannot starve a
+ * cadence. An absent mode means "unknown cadence" — the consumer treats those
+ * as escalate, so they qualify too.
+ *
+ * @param {{frontDoor?:string, sessionLive?:boolean, mode?:string, metadata?:object}} a
+ * @returns {{handOff:boolean, reason:string}}
+ */
+export function shouldHandOffTick(a) {
+  const x = a && typeof a === "object" ? a : {};
+  if (x.frontDoor !== "session") return { handOff: false, reason: "front-door-daemon" };
+  if (x.sessionLive !== true) return { handOff: false, reason: "session-not-live" };
+  const mode = x.mode == null ? "escalate" : String(x.mode);
+  if (!HANDOFF_MODES.includes(mode)) return { handOff: false, reason: "mode-not-handoff" };
+  if (x.metadata && typeof x.metadata === "object" && x.metadata.handoffTimedOut === true) {
+    return { handOff: false, reason: "handoff-timed-out" };
+  }
+  return { handOff: true, reason: "hand-off" };
+}
+
+/**
+ * YAML reader for config/session.yaml: the injected parser, else js-yaml
+ * (the documented nested `frontDoor: {mode, services}` shape needs a real
+ * parser), else a flat `key: value` / `key: [a, b]` line parser as the last
+ * resort. Never throws — returns null on any failure.
+ */
+function parseSessionYaml(text, yamlParse) {
+  const parse = typeof yamlParse === "function" ? yamlParse : defaultYamlParse;
+  if (parse) {
+    try { const v = parse(text); return v && typeof v === "object" ? v : null; } catch { return null; }
+  }
+  const out = {};
+  try {
+    for (const line of String(text).split(/\r?\n/)) {
+      const m = line.match(/^([A-Za-z_][A-Za-z0-9_]*):\s*(.*?)\s*$/);
+      if (!m) continue;
+      const [, k, v] = m;
+      if (/^\[.*\]$/.test(v)) out[k] = v.slice(1, -1).split(",").map((s) => s.trim().replace(/^["']|["']$/g, "")).filter(Boolean);
+      else if (v !== "") out[k] = v.replace(/^["']|["']$/g, "");
+    }
+  } catch { return null; }
+  return out;
+}
+
+/**
+ * THE EDGE READER. Reads config/session.yaml and state/session/heartbeat.json
+ * under `agentRoot` and folds them into the decision inputs. Every failure is
+ * fail-open: an unreadable config keeps the env/default mode, an unreadable or
+ * corrupt heartbeat means "not live" — i.e. the legacy daemon lane runs.
+ *
+ * @param {string} agentRoot
+ * @param {object} [deps]
+ * @param {object} [deps.fs] `{existsSync, readFileSync}` (default node:fs)
+ * @param {object} [deps.env] (default process.env)
+ * @param {number} [deps.now] epoch ms
+ * @param {number} [deps.staleMs]
+ * @param {Function} [deps.yamlParse] optional YAML parser (js-yaml `load`)
+ * @returns {{frontDoor:"session"|"daemon", sessionLive:boolean, services:string[], liveness:object, heartbeat:object|null}}
+ */
+export function readFrontDoorState(agentRoot, deps = {}) {
+  const fs = deps.fs || nodeFs;
+  const env = deps.env || process.env;
+  const now = typeof deps.now === "number" ? deps.now : Date.now();
+  let config = null;
+  try {
+    const p = join(agentRoot, SESSION_CONFIG_RELATIVE);
+    if (fs.existsSync(p)) config = parseSessionYaml(fs.readFileSync(p, "utf-8"), deps.yamlParse);
+  } catch { config = null; /* unreadable config → env/default mode (fail-open) */ }
+  let heartbeat = null;
+  try {
+    const p = join(agentRoot, HEARTBEAT_RELATIVE);
+    if (fs.existsSync(p)) {
+      const parsed = JSON.parse(fs.readFileSync(p, "utf-8"));
+      heartbeat = parsed && typeof parsed === "object" ? parsed : null;
+    }
+  } catch { heartbeat = null; /* corrupt heartbeat → not live → legacy lane (fail-open) */ }
+  const liveness = sessionLiveFromHeartbeat(heartbeat, { now, staleMs: deps.staleMs });
+  return {
+    frontDoor: resolveFrontDoor({ env, config }),
+    sessionLive: liveness.live,
+    services: frontDoorServices(config),
+    liveness,
+    heartbeat,
+  };
+}
+
+/**
+ * A small stateful gate for a poll loop: `check(service)` re-reads the front
+ * door state and returns the dispatch verdict plus `changed` — true only when
+ * the verdict for that service differs from the last one, so a 2-second poll
+ * can log transitions without logging every tick. A throwing reader fails
+ * open to dispatch.
+ *
+ * @param {{agentRoot:string, readState?:Function, now?:Function}} o
+ * @returns {{check:(service:string)=>{dispatch:boolean, reason:string, changed:boolean, state:object|null}}}
+ */
+export function makeFrontDoorGate(o = {}) {
+  const readState = typeof o.readState === "function" ? o.readState : readFrontDoorState;
+  const nowFn = typeof o.now === "function" ? o.now : Date.now;
+  // Last verdict key per service — the only state, and only for log hygiene.
+  const last = new Map();
+  return {
+    check(service) {
+      let state = null;
+      let verdict;
+      try {
+        state = readState(o.agentRoot, { now: nowFn() });
+        verdict = shouldDaemonDispatch({ ...state, service });
+      } catch {
+        // A broken reader must never stall intake: dispatch on the legacy lane.
+        verdict = { dispatch: true, reason: "reader-error" };
+      }
+      const key = `${verdict.dispatch}:${verdict.reason}`;
+      const changed = last.get(service) !== key;
+      last.set(service, key);
+      return { ...verdict, changed, state };
+    },
+  };
+}
+
+export default {
+  DEFAULT_STALE_MS,
+  DEFAULT_FRONT_DOOR_SERVICES,
+  HANDOFF_MODES,
+  sessionLiveFromHeartbeat,
+  resolveFrontDoor,
+  frontDoorServices,
+  shouldDaemonDispatch,
+  shouldHandOffTick,
+  readFrontDoorState,
+  makeFrontDoorGate,
+};

package/lib/session/frontdoor.test.mjs

@@ -0,0 +1,205 @@
+/**
+ * frontdoor.test.mjs — the pure front-door decision core (design §3.1, §3.4).
+ *
+ * Every function here is a pure decision over injected inputs: the parsed
+ * heartbeat, a clock, the front-door mode and the tick shape. No disk, no
+ * env reads inside the core — `readFrontDoorState` is the one edge reader and
+ * it takes its fs/env/clock as parameters so the tests are hermetic.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  DEFAULT_STALE_MS,
+  DEFAULT_FRONT_DOOR_SERVICES,
+  sessionLiveFromHeartbeat,
+  resolveFrontDoor,
+  frontDoorServices,
+  shouldDaemonDispatch,
+  shouldHandOffTick,
+  readFrontDoorState,
+  makeFrontDoorGate,
+} from "./frontdoor.mjs";
+
+const T0 = Date.parse("2026-09-08T10:00:00.000Z");
+
+// ── sessionLiveFromHeartbeat ─────────────────────────────────────────────────
+
+test("liveness: a fresh heartbeat is live; a stale one is not; none is not", () => {
+  assert.deepEqual(
+    sessionLiveFromHeartbeat({ pid: 1, ts: new Date(T0 - 10_000).toISOString() }, { now: T0 }),
+    { live: true, reason: "fresh", ageMs: 10_000 },
+  );
+  const stale = sessionLiveFromHeartbeat({ ts: new Date(T0 - DEFAULT_STALE_MS - 1).toISOString() }, { now: T0 });
+  assert.equal(stale.live, false);
+  assert.equal(stale.reason, "stale");
+  assert.equal(sessionLiveFromHeartbeat(null, { now: T0 }).live, false);
+  assert.equal(sessionLiveFromHeartbeat(null, { now: T0 }).reason, "no-heartbeat");
+  assert.equal(sessionLiveFromHeartbeat({ ts: "garbage" }, { now: T0 }).reason, "bad-ts");
+});
+
+test("liveness: accepts epoch-ms ts, honours a custom staleMs, tolerates slight clock skew", () => {
+  assert.equal(sessionLiveFromHeartbeat({ ts: T0 - 5_000 }, { now: T0 }).live, true);
+  assert.equal(sessionLiveFromHeartbeat({ ts: T0 - 5_000 }, { now: T0, staleMs: 4_000 }).live, false);
+  // A heartbeat a second "in the future" (writer/reader clock skew) is fresh.
+  assert.equal(sessionLiveFromHeartbeat({ ts: T0 + 1_000 }, { now: T0 }).live, true);
+});
+
+// ── resolveFrontDoor / frontDoorServices ─────────────────────────────────────
+
+test("resolveFrontDoor: env wins over config; config string or object; default session", () => {
+  assert.equal(resolveFrontDoor(), "session");
+  assert.equal(resolveFrontDoor({ config: { frontDoor: "daemon" } }), "daemon");
+  assert.equal(resolveFrontDoor({ config: { front_door: "daemon" } }), "daemon");
+  assert.equal(resolveFrontDoor({ config: { frontDoor: { mode: "daemon" } } }), "daemon");
+  assert.equal(resolveFrontDoor({ env: { MAESTRO_FRONT_DOOR: "daemon" }, config: { frontDoor: "session" } }), "daemon");
+  // An unknown value never selects an unknown mode.
+  assert.equal(resolveFrontDoor({ env: { MAESTRO_FRONT_DOOR: "banana" } }), "session");
+  assert.equal(resolveFrontDoor({ config: { frontDoor: "banana" } }), "session");
+});
+
+test("frontDoorServices: default cohort; config may widen; junk is ignored", () => {
+  assert.deepEqual(frontDoorServices(null), [...DEFAULT_FRONT_DOOR_SERVICES]);
+  assert.deepEqual(frontDoorServices({ frontDoor: { services: ["cohort", "slack"] } }), ["cohort", "slack"]);
+  assert.deepEqual(frontDoorServices({ services: ["orgmail"] }), ["orgmail"]);
+  assert.deepEqual(frontDoorServices({ services: "nope" }), [...DEFAULT_FRONT_DOOR_SERVICES]);
+});
+
+// ── shouldDaemonDispatch ─────────────────────────────────────────────────────
+
+test("shouldDaemonDispatch: the daemon steps back only when the session is the live front door for that service", () => {
+  assert.deepEqual(
+    shouldDaemonDispatch({ frontDoor: "session", sessionLive: true, service: "cohort" }),
+    { dispatch: false, reason: "session-live" },
+  );
+  assert.deepEqual(
+    shouldDaemonDispatch({ frontDoor: "session", sessionLive: false, service: "cohort" }),
+    { dispatch: true, reason: "session-not-live" },
+  );
+  assert.deepEqual(
+    shouldDaemonDispatch({ frontDoor: "daemon", sessionLive: true, service: "cohort" }),
+    { dispatch: true, reason: "front-door-daemon" },
+  );
+  assert.deepEqual(
+    shouldDaemonDispatch({ frontDoor: "session", sessionLive: true, service: "slack" }),
+    { dispatch: true, reason: "service-not-front-door" },
+  );
+  assert.deepEqual(
+    shouldDaemonDispatch({ frontDoor: "session", sessionLive: true, service: "slack", services: ["cohort", "slack"] }),
+    { dispatch: false, reason: "session-live" },
+  );
+  // Garbage in → legacy dispatch (fail-open: nothing is ever dropped).
+  assert.equal(shouldDaemonDispatch({}).dispatch, true);
+  assert.equal(shouldDaemonDispatch(null).dispatch, true);
+});
+
+// ── shouldHandOffTick ────────────────────────────────────────────────────────
+
+test("shouldHandOffTick: escalate/guarded ticks hand off to a live session; inline never; timed-out never", () => {
+  const live = { frontDoor: "session", sessionLive: true };
+  assert.deepEqual(shouldHandOffTick({ ...live, mode: "escalate" }), { handOff: true, reason: "hand-off" });
+  assert.deepEqual(shouldHandOffTick({ ...live, mode: "guarded" }), { handOff: true, reason: "hand-off" });
+  assert.deepEqual(shouldHandOffTick({ ...live, mode: "inline" }), { handOff: false, reason: "mode-not-handoff" });
+  // An unknown cadence (no registry entry) defaults to escalate in the consumer.
+  assert.deepEqual(shouldHandOffTick({ ...live, mode: undefined }), { handOff: true, reason: "hand-off" });
+  assert.deepEqual(
+    shouldHandOffTick({ ...live, mode: "escalate", metadata: { handoffTimedOut: true } }),
+    { handOff: false, reason: "handoff-timed-out" },
+  );
+  assert.deepEqual(
+    shouldHandOffTick({ frontDoor: "session", sessionLive: false, mode: "escalate" }),
+    { handOff: false, reason: "session-not-live" },
+  );
+  assert.deepEqual(
+    shouldHandOffTick({ frontDoor: "daemon", sessionLive: true, mode: "escalate" }),
+    { handOff: false, reason: "front-door-daemon" },
+  );
+  assert.equal(shouldHandOffTick(null).handOff, false);
+});
+
+// ── readFrontDoorState (edge reader, injected fs/env/clock) ──────────────────
+
+function fakeFs(files) {
+  return {
+    existsSync: (p) => Object.prototype.hasOwnProperty.call(files, p),
+    readFileSync: (p) => {
+      if (!Object.prototype.hasOwnProperty.call(files, p)) { const e = new Error("ENOENT"); e.code = "ENOENT"; throw e; }
+      return files[p];
+    },
+  };
+}
+
+test("readFrontDoorState: reads config/session.yaml + state/session/heartbeat.json through injected fs", () => {
+  const root = "/agent";
+  const fs = fakeFs({
+    "/agent/config/session.yaml": "frontDoor: session\nservices: [cohort, slack]\n",
+    "/agent/state/session/heartbeat.json": JSON.stringify({ pid: 4, ts: new Date(T0 - 1000).toISOString() }),
+  });
+  const st = readFrontDoorState(root, { fs, env: {}, now: T0 });
+  assert.equal(st.frontDoor, "session");
+  assert.equal(st.sessionLive, true);
+  assert.deepEqual(st.services, ["cohort", "slack"]);
+  assert.equal(st.liveness.reason, "fresh");
+});
+
+test("readFrontDoorState: no config + no heartbeat → session mode, not live (legacy dispatch); env override honoured", () => {
+  const st = readFrontDoorState("/agent", { fs: fakeFs({}), env: {}, now: T0 });
+  assert.equal(st.frontDoor, "session");
+  assert.equal(st.sessionLive, false);
+  assert.deepEqual(st.services, ["cohort"]);
+  const st2 = readFrontDoorState("/agent", { fs: fakeFs({}), env: { MAESTRO_FRONT_DOOR: "daemon" }, now: T0 });
+  assert.equal(st2.frontDoor, "daemon");
+});
+
+test("readFrontDoorState: a corrupt heartbeat or config never throws — fails open to not-live", () => {
+  const fs = fakeFs({
+    "/agent/config/session.yaml": ": : not yaml [[[",
+    "/agent/state/session/heartbeat.json": "{not json",
+  });
+  const st = readFrontDoorState("/agent", { fs, env: {}, now: T0 });
+  assert.equal(st.sessionLive, false);
+  assert.equal(st.frontDoor, "session");
+});
+
+// ── makeFrontDoorGate ────────────────────────────────────────────────────────
+
+test("makeFrontDoorGate: check() reports the decision and flags transitions only once", () => {
+  let live = true;
+  const gate = makeFrontDoorGate({
+    agentRoot: "/agent",
+    readState: () => ({ frontDoor: "session", sessionLive: live, services: ["cohort"] }),
+  });
+  const a = gate.check("cohort");
+  assert.equal(a.dispatch, false);
+  assert.equal(a.changed, true, "first observation is a transition");
+  const b = gate.check("cohort");
+  assert.equal(b.changed, false, "same verdict again is not a transition");
+  live = false;
+  const c = gate.check("cohort");
+  assert.equal(c.dispatch, true);
+  assert.equal(c.changed, true, "liveness flipped → transition");
+  // A reader that throws fails open to dispatch.
+  const broken = makeFrontDoorGate({ agentRoot: "/agent", readState: () => { throw new Error("boom"); } });
+  assert.equal(broken.check("cohort").dispatch, true);
+});
+
+test("readFrontDoorState: the documented NESTED config (frontDoor.mode / frontDoor.services) and the flow form are read without an injected parser", () => {
+  const nested = readFrontDoorState("/agent", {
+    fs: fakeFs({ "/agent/config/session.yaml": "frontDoor:\n  mode: daemon\n  services: [cohort, slack]\n" }),
+    env: {}, now: T0,
+  });
+  assert.equal(nested.frontDoor, "daemon", "an operator opting a seat out via the nested form must be honoured");
+  assert.deepEqual(nested.services, ["cohort", "slack"]);
+  const flow = readFrontDoorState("/agent", {
+    fs: fakeFs({ "/agent/config/session.yaml": "frontDoor: {mode: daemon}\n" }),
+    env: {}, now: T0,
+  });
+  assert.equal(flow.frontDoor, "daemon");
+  const block = readFrontDoorState("/agent", {
+    fs: fakeFs({ "/agent/config/session.yaml": "# session runtime\nfrontDoor:\n  mode: session\n  services:\n    - cohort\n    - orgmail\n" }),
+    env: {}, now: T0,
+  });
+  assert.equal(block.frontDoor, "session");
+  assert.deepEqual(block.services, ["cohort", "orgmail"]);
+});