@cohortapp/agent-sdk 2.11.15 → 2.13.0

package/lib/session/feed-core.test.mjs

@@ -0,0 +1,198 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  PREVIEW_MAX,
+  emptySeen,
+  parseSeen,
+  isLiveInboxFile,
+  isHandoffFile,
+  inboundEvent,
+  handoffEvent,
+  computeFeedEvents,
+} from "./feed-core.mjs";
+import { inboxItemToYaml } from "../../scripts/poller/utils.mjs";
+
+const T0 = Date.parse("2026-09-08T10:00:00Z");
+
+function cohortItem(over = {}) {
+  return inboxItemToYaml({
+    id: "msg-1",
+    service: "cohort",
+    channel: "dm/casey",
+    channel_id: "ch_abc",
+    sender: "Casey Ng",
+    sender_privilege: "ceo",
+    timestamp: "2026-09-08T09:59:00.000Z",
+    subject: "Cohort message",
+    content: "Can you pull the Q3 numbers? my key is sk-ant-api03-" + "a".repeat(40),
+    thread_id: "th_1",
+    kind: "mention",
+    direct_reason: "mention",
+    channel_kind: "DM",
+    raw_ref: "cohort:ch_abc:msg-1",
+    ...over,
+  });
+}
+
+test("emptySeen / parseSeen: versioned, fail-open", () => {
+  assert.deepEqual(emptySeen(), { version: 1, seq: 0, inbox: {}, handoffs: {}, signals: {} });
+  assert.deepEqual(parseSeen("{"), emptySeen());
+  assert.deepEqual(parseSeen(JSON.stringify({ version: 99 })), emptySeen());
+  const s = { version: 1, seq: 7, inbox: { "cohort/a.yaml": T0 }, handoffs: {}, signals: { restart: 1 } };
+  assert.deepEqual(parseSeen(JSON.stringify(s)), s);
+});
+
+test("isLiveInboxFile / isHandoffFile", () => {
+  assert.equal(isLiveInboxFile("2026-09-08T09-59-00-000Z-msg-1.yaml"), true);
+  assert.equal(isLiveInboxFile("x.yaml.dispatched"), false);
+  assert.equal(isLiveInboxFile("x.yaml.processed"), false);
+  assert.equal(isLiveInboxFile("x.yaml.deferred"), false);
+  assert.equal(isLiveInboxFile(".hidden.yaml"), false);
+  assert.equal(isHandoffFile("tick-1.json"), true);
+  assert.equal(isHandoffFile("tick-1.json.tmp.1.2.ab"), false);
+  assert.equal(isHandoffFile("done"), false);
+});
+
+test("inboundEvent: the documented line, surface from kind, topic from the surface table, preview redacted + capped", () => {
+  const ev = inboundEvent({ service: "cohort", path: "/agent/state/inbox/cohort/a.yaml", body: cohortItem(), seq: 3 });
+  assert.equal(ev.type, "inbound");
+  assert.equal(ev.id, "msg-1");
+  assert.equal(ev.service, "cohort");
+  assert.equal(ev.surface, "mention");
+  assert.equal(ev.topic, "message");
+  assert.equal(ev.reason, "mention");
+  assert.equal(ev.from, "Casey Ng");
+  assert.equal(ev.channelId, "ch_abc");
+  assert.equal(ev.channelName, "dm/casey");
+  assert.equal(ev.threadId, "th_1");
+  assert.equal(ev.path, "/agent/state/inbox/cohort/a.yaml");
+  assert.equal(ev.seq, 3);
+  assert.match(ev.preview, /Q3 numbers/);
+  assert.doesNotMatch(ev.preview, /sk-ant-api03/);
+  assert.ok(ev.preview.length <= PREVIEW_MAX);
+  assert.deepEqual(Object.keys(ev), ["type", "id", "service", "surface", "topic", "reason", "from", "channelId", "channelName", "threadId", "preview", "path", "seq"]);
+});
+
+test("inboundEvent: a plain message maps to surface=message/topic=message; a task kind maps to topic=task; long previews are capped", () => {
+  const plain = inboundEvent({ service: "cohort", path: "/p", body: cohortItem({ kind: undefined, direct_reason: undefined, content: "x ".repeat(400) }), seq: 1 });
+  assert.equal(plain.surface, "message");
+  assert.equal(plain.topic, "message");
+  assert.equal(plain.reason, "");
+  assert.equal(plain.preview.length, PREVIEW_MAX);
+  const task = inboundEvent({ service: "cohort", path: "/p", body: cohortItem({ kind: "task_assigned", direct_reason: "assignee" }), seq: 2 });
+  assert.equal(task.topic, "task");
+  assert.equal(task.reason, "assignee");
+});
+
+test("inboundEvent: an unparseable body yields null (the file is skipped, not a crash)", () => {
+  assert.equal(inboundEvent({ service: "cohort", path: "/p", body: "", seq: 1 }), null);
+  assert.equal(inboundEvent({ service: "cohort", path: "/p", body: null, seq: 1 }), null);
+});
+
+test("handoffEvent: from the consumer's handoff JSON; id falls back to the file name", () => {
+  const body = JSON.stringify({ tickId: "t-9", cadence: "morning-brief", mode: "escalate", promptPath: "/agent/state/session/handoffs/t-9.prompt.md", enqueuedAt: "2026-09-08T10:00:00Z", deadlineAt: "x" });
+  const ev = handoffEvent({ path: "/agent/state/session/handoffs/t-9.json", file: "t-9.json", body, seq: 5 });
+  assert.deepEqual(ev, { type: "handoff", id: "t-9", cadence: "morning-brief", promptPath: "/agent/state/session/handoffs/t-9.prompt.md", enqueuedAt: "2026-09-08T10:00:00Z", path: "/agent/state/session/handoffs/t-9.json", seq: 5 });
+  const bare = handoffEvent({ path: "/h/tick-2.json", file: "tick-2.json", body: "{}", seq: 6 });
+  assert.equal(bare.id, "tick-2");
+  assert.equal(bare.cadence, "");
+  assert.equal(handoffEvent({ path: "/h/x.json", file: "x.json", body: "{", seq: 7 }), null);
+});
+
+function snapshot(over = {}) {
+  return {
+    inbox: { cohort: [] },
+    handoffs: [],
+    signals: { restartRequestedMtimeMs: null, upgradeNotice: null, daemonHealthMtimeMs: T0, daemonPidAlive: null },
+    ...over,
+  };
+}
+
+test("computeFeedEvents: new inbox items and handoffs are emitted once, in a stable order, with increasing seq", () => {
+  const snap = snapshot({
+    inbox: {
+      cohort: [
+        { file: "b.yaml", path: "/i/b.yaml", body: cohortItem({ id: "b" }) },
+        { file: "a.yaml", path: "/i/a.yaml", body: cohortItem({ id: "a" }) },
+        { file: "c.yaml.dispatched", path: "/i/c.yaml.dispatched", body: cohortItem({ id: "c" }) },
+      ],
+    },
+    handoffs: [{ file: "t.json", path: "/h/t.json", body: JSON.stringify({ tickId: "t", cadence: "c" }) }],
+  });
+  const r1 = computeFeedEvents(snap, emptySeen(), { now: T0 });
+  assert.deepEqual(r1.events.map((e) => [e.type, e.id, e.seq]), [["inbound", "a", 1], ["inbound", "b", 2], ["handoff", "t", 3]]);
+  assert.equal(r1.seen.seq, 3);
+  assert.deepEqual(Object.keys(r1.seen.inbox).sort(), ["cohort/a.yaml", "cohort/b.yaml"]);
+  assert.deepEqual(Object.keys(r1.seen.handoffs), ["t.json"]);
+  // Same snapshot again → nothing new.
+  const r2 = computeFeedEvents(snap, r1.seen, { now: T0 + 1_000 });
+  assert.deepEqual(r2.events, []);
+  assert.equal(r2.seen.seq, 3);
+});
+
+test("computeFeedEvents: a file that disappears leaves the seen-set; if it re-appears it is re-emitted (assurance re-open)", () => {
+  const withA = snapshot({ inbox: { cohort: [{ file: "a.yaml", path: "/i/a.yaml", body: cohortItem({ id: "a" }) }] } });
+  const r1 = computeFeedEvents(withA, emptySeen(), { now: T0 });
+  assert.equal(r1.events.length, 1);
+  const r2 = computeFeedEvents(snapshot(), r1.seen, { now: T0 + 1 });
+  assert.deepEqual(r2.seen.inbox, {});
+  const r3 = computeFeedEvents(withA, r2.seen, { now: T0 + 2 });
+  assert.equal(r3.events.length, 1);
+  assert.equal(r3.events[0].seq, 2);
+});
+
+test("computeFeedEvents: services not in the snapshot are simply absent; unparseable bodies are skipped and not marked seen", () => {
+  const snap = snapshot({ inbox: { cohort: [{ file: "bad.yaml", path: "/i/bad.yaml", body: "" }], slack: [{ file: "s.yaml", path: "/i/s.yaml", body: cohortItem({ id: "s", service: "slack" }) }] } });
+  const r = computeFeedEvents(snap, emptySeen(), { now: T0 });
+  assert.deepEqual(r.events.map((e) => e.id), ["s"]);
+  assert.equal(r.events[0].service, "slack");
+  assert.deepEqual(Object.keys(r.seen.inbox), ["slack/s.yaml"]);
+});
+
+test("computeFeedEvents: restart-requested → one directive per appearance (keyed by mtime); cleared when the file goes", () => {
+  const s1 = snapshot({ signals: { restartRequestedMtimeMs: T0, upgradeNotice: null, daemonHealthMtimeMs: T0, daemonPidAlive: null } });
+  const r1 = computeFeedEvents(s1, emptySeen(), { now: T0 });
+  assert.deepEqual(r1.events, [{ type: "directive", action: "restart", detail: { requestedAt: "2026-09-08T10:00:00.000Z" }, seq: 1 }]);
+  const r2 = computeFeedEvents(s1, r1.seen, { now: T0 + 1 });
+  assert.deepEqual(r2.events, []);
+  const r3 = computeFeedEvents(snapshot(), r2.seen, { now: T0 + 2 });
+  assert.deepEqual(r3.events, []);
+  assert.equal(r3.seen.signals.restart, undefined);
+  const s4 = snapshot({ signals: { restartRequestedMtimeMs: T0 + 5, upgradeNotice: null, daemonHealthMtimeMs: T0, daemonPidAlive: null } });
+  assert.equal(computeFeedEvents(s4, r3.seen, { now: T0 + 5 }).events.length, 1);
+});
+
+test("computeFeedEvents: upgrade-notice → directive carrying the parsed notice, once per mtime", () => {
+  const s = snapshot({ signals: { restartRequestedMtimeMs: null, upgradeNotice: { mtimeMs: T0, body: JSON.stringify({ from: "2.11.17", to: "2.12.0" }) }, daemonHealthMtimeMs: T0, daemonPidAlive: null } });
+  const r1 = computeFeedEvents(s, emptySeen(), { now: T0 });
+  assert.deepEqual(r1.events, [{ type: "directive", action: "upgrade-available", detail: { notice: { from: "2.11.17", to: "2.12.0" } }, seq: 1 }]);
+  assert.deepEqual(computeFeedEvents(s, r1.seen, { now: T0 + 1 }).events, []);
+  // Junk notice body → detail carries the raw text, still one directive.
+  const junk = snapshot({ signals: { restartRequestedMtimeMs: null, upgradeNotice: { mtimeMs: T0 + 9, body: "not json" }, daemonHealthMtimeMs: T0, daemonPidAlive: null } });
+  const rj = computeFeedEvents(junk, r1.seen, { now: T0 + 9 });
+  assert.equal(rj.events.length, 1);
+  assert.deepEqual(rj.events[0].detail, { notice: null, raw: "not json" });
+});
+
+test("computeFeedEvents: daemon-stale fires once on the transition to stale and re-arms when the daemon is fresh again", () => {
+  const stale = snapshot({ signals: { restartRequestedMtimeMs: null, upgradeNotice: null, daemonHealthMtimeMs: T0 - 10 * 60_000, daemonPidAlive: false } });
+  const r1 = computeFeedEvents(stale, emptySeen(), { now: T0 });
+  assert.equal(r1.events.length, 1);
+  assert.equal(r1.events[0].action, "daemon-stale");
+  assert.deepEqual(r1.events[0].detail, { healthAgeMs: 10 * 60_000, pidAlive: false });
+  assert.deepEqual(computeFeedEvents(stale, r1.seen, { now: T0 + 1 }).events, []);
+  const fresh = snapshot();
+  const r3 = computeFeedEvents(fresh, r1.seen, { now: T0 + 2 });
+  assert.deepEqual(r3.events, []);
+  assert.equal(r3.seen.signals.daemonStale, false);
+  assert.equal(computeFeedEvents(stale, r3.seen, { now: T0 + 3 }).events.length, 1);
+});
+
+test("computeFeedEvents: never mutates its inputs", () => {
+  const seen = emptySeen();
+  const frozen = JSON.stringify(seen);
+  const snap = snapshot({ inbox: { cohort: [{ file: "a.yaml", path: "/i/a.yaml", body: cohortItem({ id: "a" }) }] } });
+  computeFeedEvents(snap, seen, { now: T0 });
+  assert.equal(JSON.stringify(seen), frozen);
+});

package/lib/session/first-run.mjs

@@ -0,0 +1,126 @@
+/**
+ * lib/session/first-run.mjs — the dialogs an unattended session cannot answer.
+ *
+ * The supervisor launches an INTERACTIVE `claude` inside a multiplexer with
+ * nobody attached. On a fresh seat that first launch shows two one-time
+ * dialogs and waits for a keypress that never comes:
+ *
+ *   - the bypass-permissions acknowledgement (`--dangerously-skip-permissions`),
+ *     recorded in `~/.claude.json` as `bypassPermissionsModeAccepted: true`;
+ *   - the per-directory trust dialog, recorded as
+ *     `projects[<cwd>].hasTrustDialogAccepted: true`.
+ *
+ * Neither is a secret and both are exactly what the operator answered when
+ * they set the seat up by hand, so the supervisor SEEDS them before launch:
+ * {@link seedClaudeConfig} is the pure merge (adds only the missing flags,
+ * preserves every other key, refuses to touch a malformed file), and
+ * {@link ensureClaudeConfig} is its I/O shell (writes only when something
+ * changed, so the one-time race with a `--print` session rewriting the same
+ * file is confined to the first boot of a seat).
+ *
+ * Belt and braces: a session that is alive but has never beaten after
+ * {@link HEARTBEAT_GRACE_MS} is exactly the shape of a blocked dialog (or a
+ * missing skill, or a wedged permission prompt). {@link heartbeatSilence}
+ * decides that from the heartbeat and an injected clock; the supervisor logs
+ * it and writes `state/session/attention.json` ({@link attentionRecord}) so
+ * `doctor` can report it and an operator knows which command attaches.
+ *
+ * Pure except the one I/O shell; no ambient clock, fs or home.
+ *
+ * @module lib/session/first-run
+ */
+
+"use strict";
+
+import { join } from "node:path";
+
+/** Claude Code's user-level config file, relative to the home directory. */
+export const CLAUDE_CONFIG_FILE = ".claude.json";
+/** A session alive this long without a beat is flagged for attention. */
+export const HEARTBEAT_GRACE_MS = 120_000;
+
+/**
+ * Pure: merge the two acknowledgements into a `~/.claude.json` body.
+ *
+ * @param {string|null|undefined} text current file body (absent → empty)
+ * @param {{agentRoot:string, bypass?:boolean}} a `bypass` — seed the bypass-permissions flag (only needed when launching with --dangerously-skip-permissions)
+ * @returns {{ok:true, changed:boolean, applied:string[], config:object}|{ok:false, changed:false, applied:[], error:string}}
+ */
+export function seedClaudeConfig(text, a) {
+  let raw = {};
+  if (typeof text === "string" && text.trim()) {
+    try { raw = JSON.parse(text); } catch { return { ok: false, changed: false, applied: [], error: "malformed JSON" }; }
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return { ok: false, changed: false, applied: [], error: "not an object" };
+  }
+  const applied = [];
+  const next = { ...raw };
+  if (a.bypass !== false && next.bypassPermissionsModeAccepted !== true) {
+    next.bypassPermissionsModeAccepted = true;
+    applied.push("bypassPermissionsModeAccepted");
+  }
+  const projects = next.projects && typeof next.projects === "object" && !Array.isArray(next.projects) ? next.projects : {};
+  const proj = projects[a.agentRoot] && typeof projects[a.agentRoot] === "object" && !Array.isArray(projects[a.agentRoot]) ? projects[a.agentRoot] : {};
+  if (proj.hasTrustDialogAccepted !== true) {
+    next.projects = { ...projects, [a.agentRoot]: { ...proj, hasTrustDialogAccepted: true } };
+    applied.push(`projects[${a.agentRoot}].hasTrustDialogAccepted`);
+  }
+  return { ok: true, changed: applied.length > 0, applied, config: next };
+}
+
+/**
+ * Read `~/.claude.json`, seed it, write it back only if something changed.
+ * Result frame; never throws (a seat must still launch when this fails —
+ * the dialog then blocks and {@link heartbeatSilence} reports it).
+ *
+ * @param {{homeDir:string, agentRoot:string, bypass?:boolean, readFileSync:Function, writeFileAtomic:Function}} a
+ * @returns {{ok:boolean, changed:boolean, applied:string[], path:string|null, error?:string}}
+ */
+export function ensureClaudeConfig(a) {
+  if (!a.homeDir) return { ok: false, changed: false, applied: [], path: null, error: "no home directory" };
+  const path = join(a.homeDir, CLAUDE_CONFIG_FILE);
+  let text = null;
+  try { text = a.readFileSync(path, "utf8"); } catch (err) {
+    if (!err || err.code !== "ENOENT") return { ok: false, changed: false, applied: [], path, error: err && err.message ? err.message : String(err) };
+    text = null; // first launch on this account
+  }
+  const seeded = seedClaudeConfig(text, { agentRoot: a.agentRoot, bypass: a.bypass });
+  if (!seeded.ok) return { ok: false, changed: false, applied: [], path, error: seeded.error };
+  if (!seeded.changed) return { ok: true, changed: false, applied: [], path };
+  try {
+    a.writeFileAtomic(path, JSON.stringify(seeded.config, null, 2) + "\n");
+  } catch (err) {
+    return { ok: false, changed: false, applied: [], path, error: err && err.message ? err.message : String(err) };
+  }
+  return { ok: true, changed: true, applied: seeded.applied, path };
+}
+
+/**
+ * Pure: has the session run past the grace period without beating?
+ * @param {{startedAt:number, heartbeat:{ts:string}|null, now:number, graceMs?:number}} a
+ * @returns {{silent:boolean, reason:"within-grace"|"beating"|"no-heartbeat"|"stale-heartbeat", runMs:number}}
+ */
+export function heartbeatSilence(a) {
+  const graceMs = a.graceMs ?? HEARTBEAT_GRACE_MS;
+  const runMs = Number(a.now) - Number(a.startedAt);
+  if (runMs < graceMs) return { silent: false, reason: "within-grace", runMs };
+  const ts = a.heartbeat && typeof a.heartbeat.ts === "string" ? Date.parse(a.heartbeat.ts) : NaN;
+  if (Number.isFinite(ts) && ts >= Number(a.startedAt)) return { silent: false, reason: "beating", runMs };
+  return { silent: true, reason: Number.isFinite(ts) ? "stale-heartbeat" : "no-heartbeat", runMs };
+}
+
+/**
+ * Pure: the `state/session/attention.json` body.
+ * @param {{reason:string, mux:{kind:string}, muxName:string, since:number, runMs:number}} a
+ */
+export function attentionRecord(a) {
+  const attach = a.mux && a.mux.kind === "tmux" ? `tmux attach -t =${a.muxName}` : `screen -r ${a.muxName}`;
+  return {
+    reason: a.reason,
+    since: new Date(Number(a.since)).toISOString(),
+    runMs: a.runMs,
+    attach,
+    hint: `The session has been up ${Math.round(a.runMs / 1000)} s without a heartbeat — it is probably waiting on a first-run dialog or a permission prompt. Attach with \`${attach}\` and answer it.`,
+  };
+}
+
+export default { CLAUDE_CONFIG_FILE, HEARTBEAT_GRACE_MS, seedClaudeConfig, ensureClaudeConfig, heartbeatSilence, attentionRecord };

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");
+});