@cohortapp/agent-sdk 2.11.15 → 2.12.0

package/lib/session/feed-core.mjs

@@ -0,0 +1,229 @@
+/**
+ * lib/session/feed-core.mjs — scan → events, pure.
+ *
+ * The feed runner (scripts/session/feed.mjs) takes a SNAPSHOT of the files the
+ * main session cares about and hands it here with the SEEN-SET from the last
+ * tick; this module answers "which lines does the session need to read now"
+ * and returns the seen-set to persist. No I/O, no clock reads, no randomness —
+ * every decision is a function of (snapshot, seen, now).
+ *
+ * Snapshot shape (built by the runner):
+ *
+ *   {
+ *     inbox:    { [service]: [{ file, path, body }] },   // directory listing + bodies
+ *     handoffs: [{ file, path, body }],                  // state/session/handoffs/*.json
+ *     signals:  {
+ *       restartRequestedMtimeMs: number|null,            // state/session/restart-requested
+ *       upgradeNotice: { mtimeMs, body }|null,           // state/session/upgrade-notice.json
+ *       daemonHealthMtimeMs: number|null,                // state/dashboards/daemon-health.yaml
+ *       daemonPidAlive: boolean|null,                    // state/daemon.pid liveness
+ *     },
+ *   }
+ *
+ * Lines emitted (one JSON object each — the session's whole vocabulary):
+ *
+ *   {"type":"inbound","id","service","surface","topic","reason","from","channelId","channelName","threadId","preview","path","seq"}
+ *   {"type":"handoff","id","cadence","promptPath","enqueuedAt","path","seq"}
+ *   {"type":"directive","action":"restart"|"upgrade-available"|"daemon-stale","detail","seq"}
+ *
+ * The seen-set is keyed by file, and a key whose file has GONE is dropped —
+ * so an item the daemon's assurance sweep re-opens (`.dispatched` → `.yaml`)
+ * is re-emitted, exactly as the design requires. `seq` is monotonic across
+ * runner restarts because it lives in the seen-set.
+ *
+ * @module lib/session/feed-core
+ */
+
+"use strict";
+
+import { parseInboxItemYaml } from "../../scripts/poller/inbox-scan-poller.mjs";
+import { SURFACES } from "../org/inbound/surfaces.mjs";
+import { maskTextString } from "../security/redact.mjs";
+import { isDaemonStale } from "./liveness.mjs";
+
+/** Seen-set schema version. */
+export const SEEN_VERSION = 1;
+/** Inbound preview cap (characters). */
+export const PREVIEW_MAX = 240;
+
+function nowMs(now) { return typeof now === "function" ? Number(now()) : (now == null ? Date.now() : Number(now)); }
+
+/** A fresh seen-set. */
+export function emptySeen() {
+  return { version: SEEN_VERSION, seq: 0, inbox: {}, handoffs: {}, signals: {} };
+}
+
+/** Parse a persisted seen-set; anything unexpected → empty (replay is bounded by what is still on disk). */
+export function parseSeen(text) {
+  if (typeof text !== "string") return emptySeen();
+  try {
+    const raw = JSON.parse(text);
+    if (!raw || typeof raw !== "object" || raw.version !== SEEN_VERSION) return emptySeen();
+    return {
+      version: SEEN_VERSION,
+      seq: Number.isInteger(raw.seq) && raw.seq >= 0 ? raw.seq : 0,
+      inbox: raw.inbox && typeof raw.inbox === "object" ? { ...raw.inbox } : {},
+      handoffs: raw.handoffs && typeof raw.handoffs === "object" ? { ...raw.handoffs } : {},
+      signals: raw.signals && typeof raw.signals === "object" ? { ...raw.signals } : {},
+    };
+  } catch {
+    // A torn or foreign file is not worth a crash: start over, bounded by disk.
+    return emptySeen();
+  }
+}
+
+/** A live inbox item: `*.yaml`, not a `.dispatched/.processed/.deferred` sibling, not hidden. */
+export function isLiveInboxFile(name) {
+  return typeof name === "string" && !name.startsWith(".") && name.endsWith(".yaml");
+}
+
+/** A handoff: `*.json` directly in the handoffs dir (temp siblings excluded). */
+export function isHandoffFile(name) {
+  return typeof name === "string" && !name.startsWith(".") && name.endsWith(".json");
+}
+
+/** kind → topic, from the surface table; unknown kinds are plain messages. */
+const TOPIC_BY_KIND = (() => {
+  const m = new Map();
+  for (const s of Object.values(SURFACES)) if (s && s.kind && !m.has(s.kind)) m.set(s.kind, s.topic);
+  return m;
+})();
+
+function preview(text) {
+  const masked = maskTextString(String(text || "")).replace(/\s+/g, " ").trim();
+  return masked.length > PREVIEW_MAX ? masked.slice(0, PREVIEW_MAX) : masked;
+}
+
+/**
+ * Pure: one inbox file → an `inbound` line, or null when the body is not an item.
+ * @param {{service:string, path:string, body:string, seq:number}} a
+ */
+export function inboundEvent(a) {
+  if (typeof a.body !== "string" || !a.body.trim()) return null;
+  let item;
+  try { item = parseInboxItemYaml(a.body); } catch { return null; }
+  if (!item || !item.id) return null;
+  const surface = item.kind || "message";
+  return {
+    type: "inbound",
+    id: item.id,
+    service: a.service,
+    surface,
+    topic: TOPIC_BY_KIND.get(surface) || "message",
+    reason: item.direct_reason || "",
+    from: item.sender || "",
+    channelId: item.channel_id || "",
+    channelName: item.channel || "",
+    threadId: item.thread_id || "",
+    preview: preview(item.content),
+    path: a.path,
+    seq: a.seq,
+  };
+}
+
+/**
+ * Pure: one handoff file → a `handoff` line, or null when the body is not JSON.
+ * @param {{path:string, file:string, body:string, seq:number}} a
+ */
+export function handoffEvent(a) {
+  let raw;
+  try { raw = JSON.parse(a.body); } catch { return null; }
+  if (!raw || typeof raw !== "object") return null;
+  const id = typeof raw.tickId === "string" && raw.tickId ? raw.tickId : String(a.file).replace(/\.json$/, "");
+  return {
+    type: "handoff",
+    id,
+    cadence: typeof raw.cadence === "string" ? raw.cadence : "",
+    promptPath: typeof raw.promptPath === "string" ? raw.promptPath : "",
+    enqueuedAt: typeof raw.enqueuedAt === "string" ? raw.enqueuedAt : "",
+    path: a.path,
+    seq: a.seq,
+  };
+}
+
+/**
+ * Pure: the tick. Returns the lines to emit and the seen-set to persist.
+ * @param {object} snapshot  see module docblock
+ * @param {ReturnType<typeof emptySeen>} seenIn
+ * @param {{now?:number|Function}} [opts]
+ * @returns {{events:object[], seen:ReturnType<typeof emptySeen>}}
+ */
+export function computeFeedEvents(snapshot, seenIn, opts = {}) {
+  const now = nowMs(opts.now);
+  const prev = seenIn || emptySeen();
+  const seen = { version: SEEN_VERSION, seq: prev.seq || 0, inbox: {}, handoffs: {}, signals: { ...(prev.signals || {}) } };
+  const events = [];
+  const next = () => ++seen.seq;
+
+  // Inbox: every configured service, files in name order (timestamp-prefixed
+  // names sort chronologically), only live `*.yaml`.
+  const inbox = snapshot && snapshot.inbox && typeof snapshot.inbox === "object" ? snapshot.inbox : {};
+  for (const service of Object.keys(inbox).sort()) {
+    const entries = (inbox[service] || []).filter((e) => e && isLiveInboxFile(e.file)).sort((x, y) => (x.file < y.file ? -1 : x.file > y.file ? 1 : 0));
+    for (const e of entries) {
+      const key = `${service}/${e.file}`;
+      if (prev.inbox && prev.inbox[key] != null) { seen.inbox[key] = prev.inbox[key]; continue; }
+      const ev = inboundEvent({ service, path: e.path, body: e.body, seq: seen.seq + 1 });
+      if (!ev) continue; // unreadable now; retried next tick, never marked seen
+      next();
+      events.push(ev);
+      seen.inbox[key] = now;
+    }
+  }
+
+  // Handoffs: `*.json` in name order.
+  const handoffs = (snapshot && Array.isArray(snapshot.handoffs) ? snapshot.handoffs : [])
+    .filter((e) => e && isHandoffFile(e.file))
+    .sort((x, y) => (x.file < y.file ? -1 : x.file > y.file ? 1 : 0));
+  for (const e of handoffs) {
+    if (prev.handoffs && prev.handoffs[e.file] != null) { seen.handoffs[e.file] = prev.handoffs[e.file]; continue; }
+    const ev = handoffEvent({ path: e.path, file: e.file, body: e.body, seq: seen.seq + 1 });
+    if (!ev) continue;
+    next();
+    events.push(ev);
+    seen.handoffs[e.file] = now;
+  }
+
+  // Signals.
+  const sig = snapshot && snapshot.signals && typeof snapshot.signals === "object" ? snapshot.signals : {};
+
+  // restart-requested: once per appearance (keyed by the marker's mtime).
+  if (Number.isFinite(sig.restartRequestedMtimeMs)) {
+    if (seen.signals.restart !== sig.restartRequestedMtimeMs) {
+      seen.signals.restart = sig.restartRequestedMtimeMs;
+      events.push({ type: "directive", action: "restart", detail: { requestedAt: new Date(sig.restartRequestedMtimeMs).toISOString() }, seq: next() });
+    }
+  } else {
+    delete seen.signals.restart;
+  }
+
+  // upgrade-notice: once per notice (keyed by mtime), detail = parsed body.
+  const un = sig.upgradeNotice;
+  if (un && Number.isFinite(un.mtimeMs)) {
+    if (seen.signals.upgrade !== un.mtimeMs) {
+      seen.signals.upgrade = un.mtimeMs;
+      let notice = null;
+      try { notice = JSON.parse(un.body); } catch { notice = null; /* a hand-written marker still announces the upgrade */ }
+      const detail = notice && typeof notice === "object" ? { notice } : { notice: null, raw: String(un.body || "").slice(0, PREVIEW_MAX) };
+      events.push({ type: "directive", action: "upgrade-available", detail, seq: next() });
+    }
+  } else {
+    delete seen.signals.upgrade;
+  }
+
+  // daemon-stale: on the transition only; re-armed once the daemon is fresh.
+  const stale = isDaemonStale({ healthMtimeMs: sig.daemonHealthMtimeMs ?? null, pidAlive: sig.daemonPidAlive ?? null, now });
+  if (stale && seen.signals.daemonStale !== true) {
+    events.push({
+      type: "directive",
+      action: "daemon-stale",
+      detail: { healthAgeMs: Number.isFinite(sig.daemonHealthMtimeMs) ? now - sig.daemonHealthMtimeMs : null, pidAlive: sig.daemonPidAlive ?? null },
+      seq: next(),
+    });
+  }
+  seen.signals.daemonStale = stale;
+
+  return { events, seen };
+}
+
+export default { SEEN_VERSION, PREVIEW_MAX, emptySeen, parseSeen, isLiveInboxFile, isHandoffFile, inboundEvent, handoffEvent, computeFeedEvents };

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