@cohortapp/agent-sdk 2.13.0 → 2.14.0

package/docs/guides/front-door-session.md

@@ -47,6 +47,43 @@ direction. The beat reports which lane is active: `machine.frontDoor`
 open record — rather than `session`, which hq validates strictly and which
 stays `null` while no work session runs.
 
+**And WHY it is not live.** `sessionLive: false` on its own is a symptom with
+several cures, and no seat in the fleet accepts SSH, so the beat has to carry
+the cause too. When (and only when) the front door is down, the beat adds
+`machine.sessionNote` — `{reason, since?, detail?}`:
+
+| `reason` | what happened | what to do |
+| --- | --- | --- |
+| `job-absent` | no `ai.maestro.<first>-session` plist in `~/Library/LaunchAgents`. A statement of configuration, not necessarily a fault — a seat whose front door is deliberately the daemon lane reports this on every beat | nothing, if that is the intent; else `maestro session install` |
+| `awaiting-input` | `state/session/attention.json` exists and no later heartbeat has superseded it: the session is up but has never beaten, so it is sitting on a first-run trust/permission dialog | attach with the command in `detail` and answer it |
+| `heartbeat-stale` | a heartbeat exists but has aged out — supervisor died, or the mux session ended; `since` is the last beat | `maestro session restart` |
+| `heartbeat-unreadable` | `heartbeat.json` is there and will not parse. The job may well have beaten — this is NOT "never beaten" | delete the file and let the feed rewrite it |
+| `never-beaten` | no heartbeat file at all and no watchdog record yet (the supervisor's watchdog fires 120 s in) | wait a minute, then `maestro session status` |
+
+`detail` is capped at 200 characters and scrubbed of home paths, session ids
+and token-shaped words before it leaves the machine
+(`lib/telemetry/collect.mjs#sanitizeNoteDetail`); the attach command survives,
+because that is the actionable part. `since` is never passed through from the
+file either — it is parsed and re-emitted as canonical ISO 8601, so nothing can
+ride it that the `detail` scrubber would have caught.
+
+Two rules the reasons obey, because a note that misleads is worse than no note:
+
+- **An unknown is reported as neither an absence nor a presence.** `job-absent`
+  comes only from a directory that was read and genuinely did not hold the
+  label; an unreadable `~/Library/LaunchAgents` (or a non-Mac seat) yields
+  `never-beaten` with a `detail` that says the job's presence could not be
+  checked, rather than claiming an installation nobody verified.
+- **Every reason is PRESENT-TENSE and expires with the snapshot**, like
+  `frontDoor` and `sessionLive` and unlike `machine.upgrade`. `job-absent` and
+  `never-beaten` carry no `since`, so a consumer dates them from the snapshot's
+  own `ts` — printing "attach and answer the dialog" off a week-old snapshot is
+  the mistake this note exists to prevent, not to cause.
+
+The decision itself is the pure `sessionNote(...)` over injected inputs — the
+reads that feed it are fail-open, so a throw anywhere in them drops the field
+rather than the beat.
+
 **Exactly one.** The supervisor takes an O_EXCL lock (`lib/singleton.js`,
 name `session`); a second supervisor exits 0 so launchd does not thrash. An
 orphaned mux session with no lock holder is adopted, not duplicated.

package/lib/telemetry/collect.mjs

@@ -47,6 +47,38 @@
  *       // silently drops the seat out of the mesh.
  *       frontDoor: "session"|"daemon",  // the main session job, or the daemon's --print lane
  *       sessionLive: boolean,           // state/session/heartbeat.json fresher than 90 s
+ *       // WHY the front door is not live (WP-M8). Present ONLY when
+ *       // `sessionLive` is false — a live seat says nothing. The beat is the
+ *       // only channel to a seat that takes no SSH, so it has to carry the
+ *       // cause, not just the symptom. Small and bounded by construction:
+ *       // three fields, `detail` capped at SESSION_NOTE_DETAIL_MAX and
+ *       // scrubbed of home paths and token-shaped words (see sanitizeNoteDetail),
+ *       // `since` re-formatted from a parsed instant rather than passed through.
+ *       // MOMENTARY, like frontDoor/sessionLive: every reason is PRESENT-TENSE
+ *       // and expires with the snapshot, so a consumer must gate it on
+ *       // snapshot freshness — it is NOT read the way `upgrade` (a fact about
+ *       // the past) is read. Two of the reasons have no moment to date and so
+ *       // carry no `since`; age then comes from the snapshot's own `ts`.
+ *       //   "job-absent"     no <first>-session plist in ~/Library/LaunchAgents.
+ *       //                    A statement of CONFIGURATION, not necessarily a
+ *       //                    fault: a seat whose front door is deliberately the
+ *       //                    daemon --print lane reports this on every beat.
+ *       //                    Emitted only from a hard "not there", never from
+ *       //                    a directory we could not read. No `since`.
+ *       //   "awaiting-input" state/session/attention.json exists AND has not
+ *       //                    been superseded by a later heartbeat: the session
+ *       //                    is up but has never beaten, so it is sitting on a
+ *       //                    first-run trust/permission dialog nobody answered.
+ *       //                    `since` and `detail` carry the supervisor's own
+ *       //                    attentionRecord moment + hint (truncated).
+ *       //   "heartbeat-stale" a heartbeat exists but has aged out — the supervisor
+ *       //                    died or the mux session ended. `since` is the last beat.
+ *       //   "heartbeat-unreadable" the file is there and will not parse: the job
+ *       //                    may well have beaten, so this is NOT "never beaten".
+ *       //   "never-beaten"   no heartbeat file at all and no watchdog record yet.
+ *       //                    `detail` claims the job is installed only when its
+ *       //                    presence was actually established. No `since`.
+ *       sessionNote?: { reason: string, since?: ISO8601, detail?: string },
  *       // LAST UPGRADE — the outcome autoupdate.sh recorded in
  *       // state/autoupdate/last.json (WP-M6); absent until a first attempt.
  *       // Also on `machine` (open record), so hq's fleet view can show it next
@@ -92,6 +124,7 @@ import { probeClaude as defaultProbeClaude } from "../setup/claude-probe.mjs";
 import { list as listPresence } from "../collective/presence.mjs";
 import { billableUsd } from "../cost/ledger-row.mjs";
 import { liveClaudeStats } from "../resource-governor.mjs";
+import { agentFirstName } from "../session/identity.mjs";
 
 /** Default temperature probe ceiling — used only as a guard in alerts; here we just report. */
 const VALID_STATES = new Set(["active", "idle", "busy", "error", "offline"]);
@@ -1031,6 +1064,216 @@ export function sessionLiveness(hb, nowMs, opts = {}) {
   return { frontDoor: "session", sessionLive: live };
 }
 
+/** Hard cap on `machine.sessionNote.detail` — the beat is a heartbeat, not a log. */
+export const SESSION_NOTE_DETAIL_MAX = 200;
+
+/**
+ * Absolute paths that could name a person, a home or a private temp dir.
+ *
+ * A path segment may CONTAIN a space — `/Users/Olivia Chen/…` is an ordinary
+ * macOS home — so the match does not simply stop at the first whitespace, which
+ * left `<path> Chen/olivia-ai/state` (a surname and the seat's layout) standing
+ * in the note. A space is swallowed only when what follows it is still a path
+ * (more non-space characters and then a `/`), so ordinary prose after a path
+ * survives: `blocked in /Users/maya and then retry` redacts only the path.
+ */
+const NOTE_PATH_RE = /(?:~|\/(?:Users|home|private|var\/folders))\/(?:[^\s"'`]|[ \t](?=[^\s"'`]*\/))*/g;
+/** Token-shaped words: an api-key prefix, or any long opaque run (uuids included). */
+const NOTE_TOKEN_RE = /\b(?:sk-[A-Za-z0-9_-]{8,}|[A-Za-z0-9][A-Za-z0-9_-]{31,})\b/g;
+
+/**
+ * Pure: make a free-text note safe and small enough to ride every beat.
+ *
+ * The text this scrubs is OUR OWN (the supervisor's attention hint), so it is
+ * not a sanitiser standing between us and an attacker — it is the guarantee the
+ * contract makes to hq and to every operator reading a fleet view: a note never
+ * carries a home directory, a session id, a token or a file path, and never
+ * grows past {@link SESSION_NOTE_DETAIL_MAX}. The hint names an attach command
+ * (`tmux attach -t =maestro-alex`), which is exactly the actionable part and
+ * survives; the paths and ids around it do not.
+ *
+ * @param {unknown} text
+ * @param {number} [max]
+ * @returns {string} "" when there is nothing safe left to say
+ */
+export function sanitizeNoteDetail(text, max = SESSION_NOTE_DETAIL_MAX) {
+  if (typeof text !== "string" || !text) return "";
+  const cap = Number.isFinite(max) && max > 0 ? Math.floor(max) : SESSION_NOTE_DETAIL_MAX;
+  let out = text.replace(/[\u0000-\u001F\u007F]+/g, " ");
+  out = out.replace(NOTE_PATH_RE, "<path>");
+  out = out.replace(NOTE_TOKEN_RE, "<redacted>");
+  out = out.replace(/\s+/g, " ").trim();
+  if (out.length > cap) out = `${out.slice(0, cap - 1).trimEnd()}…`;
+  return out;
+}
+
+/** ms-or-ISO `ts` off a heartbeat record -> epoch ms, else null. */
+function heartbeatTs(hb) {
+  if (!hb || typeof hb !== "object") return null;
+  const ts = typeof hb.ts === "number" ? hb.ts : Date.parse(hb.ts);
+  return Number.isFinite(ts) ? ts : null;
+}
+
+/**
+ * Pure: an ISO-8601 string -> epoch ms, else null.
+ *
+ * `since` rides the beat as the note's only structured field, and it used to
+ * ride VERBATIM behind a bare `Date.parse` finiteness check — which V8's legacy
+ * date parser passes for a string carrying trailing prose, so a home path or a
+ * token-shaped run could travel on the one field {@link sanitizeNoteDetail}
+ * does not cover. Parsing to ms here and re-formatting through `toISOString()`
+ * makes `since` bounded and canonical by CONSTRUCTION rather than by trusting
+ * the file it came from.
+ */
+function instantMs(v) {
+  if (typeof v !== "string" || !v) return null;
+  const ms = Date.parse(v);
+  return Number.isFinite(ms) ? ms : null;
+}
+
+/**
+ * The supervisor watchdog's vocabulary (`lib/session/first-run#heartbeatSilence`)
+ * in plain words.
+ *
+ * Its `"no-heartbeat"` means "the session is UP and has never beaten"; the
+ * beat's own reasons of nearly the same spelling mean something else, and the
+ * two met inside one payload (`{reason:"awaiting-input", detail:"no-heartbeat: …"}`),
+ * which reads as a contradiction to anything that shows reason and detail side
+ * by side. An unrecognised value still passes through verbatim — a word we do
+ * not know is better than a word we invent.
+ */
+const ATTENTION_WHY = {
+  "no-heartbeat": "up, never beaten",
+  "stale-heartbeat": "no beat since this launch",
+};
+
+/**
+ * Pure: WHY the front door is not live — the beat's `machine.sessionNote`.
+ *
+ * THE GAP (WP-M8): after 2.12.0, seats A010 and A016 beat
+ * `frontDoor:"daemon", sessionLive:false` for days and nothing on the beat
+ * could tell a job that was never installed from a session sitting on an
+ * unanswered first-run dialog from a supervisor that had died — three states an
+ * operator fixes three different ways. No seat in the fleet accepts SSH, so the
+ * beat is the only channel; the seat already knew the answer
+ * (`state/session/attention.json`), it just never left the machine.
+ *
+ * ORDER, and why each step outranks the next:
+ *
+ *  1. `job-absent` first: a seat with no job cannot have a meaningful heartbeat
+ *     or attention record, and a stale `attention.json` left behind by a
+ *     previous install must not mask "the job is gone". It is a statement of
+ *     CONFIGURATION, not necessarily a fault — a seat whose front door is
+ *     deliberately the daemon --print lane reports it on every beat, and the
+ *     detail says so rather than accusing the seat.
+ *  2. `awaiting-input` next — but ONLY while the record still describes the
+ *     present. `scripts/session/supervisor.mjs` clears `attention.json` at the
+ *     START of the next launch and never when the human answers the dialog, so
+ *     a record can outlive its truth by days: the session gets answered, beats
+ *     for a week, then dies. A heartbeat LATER than the record is proof the
+ *     dialog was answered, and the record is then superseded — otherwise the
+ *     beat hands the operator a week-old attach command for a mux session that
+ *     no longer exists while the real fault stays invisible.
+ *  3. `heartbeat-stale` / `heartbeat-unreadable` / `never-beaten` last, from
+ *     what the heartbeat file itself can prove.
+ *
+ * Every emitted `detail` must be TRUE of the state it describes: an unknown is
+ * never reported as an absence (`job-absent` comes only from a hard `false`)
+ * and, symmetrically, never as a presence (`never-beaten` says the job is
+ * installed only when it was actually checked).
+ *
+ * Everything is INJECTED — no clock, no fs, no launchctl. Every malformed
+ * input resolves to a coarser answer or to `null`; nothing here throws.
+ *
+ * @param {object} a
+ * @param {object|null} [a.heartbeat]     parsed state/session/heartbeat.json (null when absent/corrupt)
+ * @param {boolean} [a.heartbeatUnreadable] the file was THERE but would not parse (a different fault from "never beaten")
+ * @param {object|null} [a.attention]     parsed state/session/attention.json (lib/session/first-run#attentionRecord)
+ * @param {boolean|null} [a.jobInstalled] is the `<first>-session` launchd job present? null = COULD NOT TELL (reported as neither an absence nor a presence)
+ * @param {string} [a.label]              the launchd label, for the job-absent detail
+ * @param {number} a.now                  epoch ms
+ * @param {number} [a.staleMs]            heartbeat staleness bound (default {@link SESSION_STALE_MS})
+ * @returns {{reason:string, since?:string, detail?:string}|null} null when the front door is live (or `now` is unusable)
+ */
+export function sessionNote(a = {}) {
+  const o = a && typeof a === "object" ? a : {};
+  const now = Number(o.now);
+  if (!Number.isFinite(now)) return null;
+  const staleMs = Number.isFinite(o.staleMs) ? o.staleMs : SESSION_STALE_MS;
+  const hb = o.heartbeat && typeof o.heartbeat === "object" && !Array.isArray(o.heartbeat) ? o.heartbeat : null;
+
+  // A live front door has nothing to explain — the note is an EXCEPTION field.
+  if (sessionLiveness(hb, now, { staleMs }).sessionLive) return null;
+
+  // 1. The job is not on this seat at all. `false` only; `null` is "unknown",
+  //    and an unknown must never be reported as an absence.
+  if (o.jobInstalled === false) {
+    const label = typeof o.label === "string" && o.label.trim() ? o.label.trim() : "";
+    return {
+      reason: "job-absent",
+      detail: sanitizeNoteDetail(
+        `no ${label || "main-session"} launchd job on this seat — the daemon --print lane is the front door (by configuration, or the session job was never installed)`,
+      ),
+    };
+  }
+
+  const hbMs = heartbeatTs(hb);
+
+  // 2. The supervisor's watchdog has already named it: alive, never beaten —
+  //    a first-run trust/permission dialog with nobody attached to answer.
+  //    Unless a LATER heartbeat proves the dialog was answered and the record
+  //    is simply one the supervisor never got to clear (see ORDER above). A
+  //    record with no usable `since` cannot be ordered against the heartbeat,
+  //    and a heartbeat with a real timestamp is the harder evidence, so that
+  //    too counts as superseded.
+  const att = o.attention && typeof o.attention === "object" && !Array.isArray(o.attention) ? o.attention : null;
+  const attMs = att ? instantMs(att.since) : null;
+  const superseded = att !== null && hbMs !== null && (attMs === null || hbMs > attMs);
+  if (att && !superseded) {
+    const note = { reason: "awaiting-input" };
+    if (attMs !== null) note.since = new Date(attMs).toISOString();
+    const raw = typeof att.reason === "string" ? att.reason.trim() : "";
+    const why = raw ? (ATTENTION_WHY[raw] || raw) : "";
+    const hint = typeof att.hint === "string" ? att.hint : "";
+    const detail = sanitizeNoteDetail(why && hint ? `${why}: ${hint}` : why || hint);
+    if (detail) note.detail = detail;
+    return note;
+  }
+
+  // 3. It beat once and stopped: the supervisor died, or the mux session ended.
+  if (hbMs !== null) {
+    const ageMs = now - hbMs;
+    return {
+      reason: "heartbeat-stale",
+      since: new Date(hbMs).toISOString(),
+      detail: ageMs < 0 ? "last beat is in the future (clock skew)" : `no beat for ${Math.round(ageMs / 1000)} s`,
+    };
+  }
+
+  // 4. A heartbeat file is THERE but says nothing usable. Not the same fault as
+  //    "never beaten" — the job may well have beaten and the file be corrupt —
+  //    so it gets its own reason and its own fix.
+  if (hb || o.heartbeatUnreadable === true) {
+    return {
+      reason: "heartbeat-unreadable",
+      detail: hb
+        ? "the heartbeat file is present but carries no readable timestamp"
+        : "the heartbeat file is present but could not be parsed",
+    };
+  }
+
+  // 5. Nothing on disk at all: a job that has never beaten and whose watchdog
+  //    has not fired yet. What we say about the job depends on whether its
+  //    presence was actually established — `true`, and only `true`, licenses
+  //    "the session job is installed".
+  return {
+    reason: "never-beaten",
+    detail: o.jobInstalled === true
+      ? "the session job is installed but has never written a heartbeat"
+      : "no heartbeat from the session job, and its presence on this seat could not be checked",
+  };
+}
+
 /**
  * Pure: the beat's `machine.upgrade` from state/autoupdate/last.json
  * (`{from,to,at,ok,healthy,reason}` as autoupdate.sh writes it). Only the four
@@ -1053,10 +1296,87 @@ function readAutoupdateLast(agentRoot) {
   return safeReadJson(join(resolve(agentRoot), "state", "autoupdate", "last.json"));
 }
 
-/** Read state/session/heartbeat.json; null when absent or malformed. */
-function readSessionHeartbeat(agentRoot) {
+/**
+ * Read state/session/heartbeat.json, distinguishing ABSENT from PRESENT-BUT-
+ * UNPARSEABLE.
+ *
+ * `safeReadJson` maps both to `null`, which is right for liveness (neither is a
+ * live beat) and wrong for the note: a corrupt file told the operator the job
+ * "has never written a heartbeat" when in fact it had, and the fix for the two
+ * is not the same. The two facts are separated here and rejoined in
+ * {@link sessionNote}.
+ *
+ * @returns {{heartbeat:object|null, unreadable:boolean}}
+ */
+function readSessionHeartbeatState(agentRoot) {
+  if (!agentRoot) return { heartbeat: null, unreadable: false };
+  let text;
+  try {
+    text = readFileSync(join(resolve(agentRoot), "state", "session", "heartbeat.json"), "utf8");
+  } catch {
+    return { heartbeat: null, unreadable: false }; // no file: the job has never beaten
+  }
+  try {
+    const v = JSON.parse(text);
+    if (v && typeof v === "object" && !Array.isArray(v)) return { heartbeat: v, unreadable: false };
+    return { heartbeat: null, unreadable: true }; // a JSON scalar is not a heartbeat
+  } catch {
+    return { heartbeat: null, unreadable: true };
+  }
+}
+
+/** Read state/session/attention.json (the supervisor's watchdog record); null when absent or malformed. */
+function readSessionAttention(agentRoot) {
   if (!agentRoot) return null;
-  return safeReadJson(join(resolve(agentRoot), "state", "session", "heartbeat.json"));
+  return safeReadJson(join(resolve(agentRoot), "state", "session", "attention.json"));
+}
+
+/**
+ * The launchd label of this seat's main-session job, as
+ * `scripts/local-triggers/generate-plists.sh` and `maestro session` spell it.
+ * "" when the first name cannot be derived.
+ */
+function sessionJobLabel(agentRoot, first) {
+  // NOT lower-cased: `agentFirstName` deliberately leaves its directory-name
+  // fallback as-is (`~/Maya-ai` -> `Maya`) because the generator does, so
+  // lower-casing an INJECTED first here built a label the plist file does not
+  // carry — and a label that does not match is how a healthy seat gets accused
+  // of `job-absent`, the one verdict that must come from a hard fact.
+  const f = typeof first === "string" && first.trim() ? first.trim() : (agentRoot ? agentFirstName(resolve(agentRoot)) : "");
+  return f ? `ai.maestro.${f}-session` : "";
+}
+
+/**
+ * Is the main-session launchd job on this seat? A filename scan of
+ * ~/Library/LaunchAgents — a readdir, NOT a `launchctl list` fork, because this
+ * runs on every presence beat.
+ *
+ * Returns `null` for "could not tell" (no label, no home, an unreadable
+ * directory, a non-darwin box) and only ever `false` when the directory was
+ * read and the label was genuinely not in it: `sessionNote` reports an absence
+ * only from a `false`, never from an unknown.
+ *
+ * @returns {boolean|null}
+ */
+function sessionJobInstalled(o, label) {
+  if (typeof o.sessionJobInstalled === "boolean") return o.sessionJobInstalled;
+  if (!label) return null;
+  let names = o.launchAgents;
+  if (!Array.isArray(names)) {
+    try {
+      const osImpl = o.os || os;
+      const home = typeof osImpl.homedir === "function" ? String(osImpl.homedir() || "") : "";
+      if (!home) return null;
+      names = readdirSync(join(home, "Library", "LaunchAgents"));
+    } catch {
+      return null; // no directory, no permission, not a Mac — unknown, not absent
+    }
+  }
+  // Case-insensitively: HFS+/APFS are case-preserving but case-INsensitive by
+  // default, so `ai.maestro.Maya-session.plist` and the lower-cased label are
+  // the same file to launchd. A case difference must not read as an absence.
+  const want = label.toLowerCase();
+  return names.some((n) => String(n).replace(/\.plist$/, "").toLowerCase() === want);
 }
 
 // ---------------------------------------------------------------------------
@@ -1357,12 +1677,39 @@ export async function collectStatus(o = {}) {
   // and `machine` open, so this is the only place a new seat-level fact can
   // land without a lock-step hq deploy. `session` stays `null` when idle.
   let door = { frontDoor: "daemon", sessionLive: false };
+  let heartbeat = null;
+  let heartbeatUnreadable = false;
   try {
-    const hb = opt.heartbeat !== undefined ? opt.heartbeat : readSessionHeartbeat(opt.agentRoot);
-    door = sessionLiveness(hb, nowMs, { staleMs: opt.sessionStaleMs });
+    if (opt.heartbeat !== undefined) heartbeat = opt.heartbeat;
+    else {
+      const hbState = readSessionHeartbeatState(opt.agentRoot);
+      heartbeat = hbState.heartbeat;
+      heartbeatUnreadable = hbState.unreadable;
+    }
+    door = sessionLiveness(heartbeat, nowMs, { staleMs: opt.sessionStaleMs });
   } catch { /* defaults: daemon front door, not live */ }
   machine = { ...machine, ...door };
 
+  // 4b-ii. WHY it is not live (WP-M8) — `machine.sessionNote`, present ONLY
+  // when `sessionLive` is false. The decision is the pure `sessionNote`; this
+  // is just the reads that feed it, and it is fail-open in the same way every
+  // other probe here is: a throw anywhere drops the field, never the beat.
+  if (door.sessionLive !== true) {
+    try {
+      const label = typeof opt.sessionLabel === "string" ? opt.sessionLabel : sessionJobLabel(opt.agentRoot, opt.agentFirst);
+      const note = sessionNote({
+        heartbeat,
+        heartbeatUnreadable: opt.heartbeatUnreadable !== undefined ? opt.heartbeatUnreadable === true : heartbeatUnreadable,
+        attention: opt.attention !== undefined ? opt.attention : readSessionAttention(opt.agentRoot),
+        jobInstalled: sessionJobInstalled(opt, label),
+        label,
+        now: nowMs,
+        staleMs: opt.sessionStaleMs,
+      });
+      if (note) machine.sessionNote = note;
+    } catch { /* no sessionNote — the beat still carries frontDoor/sessionLive */ }
+  }
+
   // 4c. last upgrade outcome (WP-M6) — `machine.upgrade`, absent until the
   // first autoupdate attempt; a corrupt file drops the field, never the beat.
   try {
@@ -1409,6 +1756,11 @@ export const _internals = {
   collectTailnetIp,
   readSdkVersion,
   sessionLiveness,
+  sessionNote,
+  sanitizeNoteDetail,
+  sessionJobLabel,
+  sessionJobInstalled,
+  readSessionAttention,
   upgradeSummary,
   detectClaudeAuth,
   resetAuthProbeCache,

package/lib/telemetry/collect.test.mjs

@@ -933,3 +933,288 @@ test("collectStatus: machine.upgrade rides the beat when state/autoupdate/last.j
     assert.equal(injected.machine.upgrade.ok, false);
   } finally { rmSync(root, { recursive: true, force: true }); }
 });
+
+// ---------------------------------------------------------------------------
+// machine.sessionNote (WP-M8) — WHY the front door is not live
+// ---------------------------------------------------------------------------
+
+const M8_NOW = Date.parse("2026-09-11T12:00:00Z");
+/** The record scripts/session/supervisor.mjs writes via first-run#attentionRecord. */
+const attention = (over = {}) => ({
+  reason: "no-heartbeat",
+  since: "2026-09-11T11:57:00.000Z",
+  runMs: 180_000,
+  attach: "tmux attach -t =maestro-maya",
+  hint: "The session has been up 180 s without a heartbeat — it is probably waiting on a first-run dialog or a permission prompt. Attach with `tmux attach -t =maestro-maya` and answer it.",
+  ...over,
+});
+
+test("sessionNote: a live front door says nothing at all", () => {
+  const { sessionNote } = _internals;
+  assert.equal(sessionNote({ heartbeat: { ts: M8_NOW - 1_000 }, now: M8_NOW }), null);
+  assert.equal(sessionNote({ heartbeat: { ts: M8_NOW - 89_000 }, jobInstalled: false, attention: attention(), now: M8_NOW }), null,
+    "liveness wins over every other input — the note exists only to explain a door that is NOT open");
+  // A shorter staleness bound makes the same beat stale, and then it does speak.
+  assert.equal(sessionNote({ heartbeat: { ts: M8_NOW - 30_000 }, jobInstalled: true, now: M8_NOW, staleMs: 10_000 }).reason, "heartbeat-stale");
+});
+
+test("sessionNote: job-absent — no plist for this seat, and only ever from a hard false", () => {
+  const { sessionNote } = _internals;
+  const n = sessionNote({ jobInstalled: false, label: "ai.maestro.maya-session", now: M8_NOW });
+  assert.equal(n.reason, "job-absent");
+  assert.match(n.detail, /ai\.maestro\.maya-session/);
+  assert.equal(n.since, undefined, "there is no moment to date — the job was never there");
+  // It outranks a stale attention record left behind by a previous install.
+  assert.equal(sessionNote({ jobInstalled: false, attention: attention(), heartbeat: { ts: M8_NOW - 600_000 }, now: M8_NOW }).reason, "job-absent");
+  // UNKNOWN is not absent: a home we could not read must never accuse the seat.
+  assert.equal(sessionNote({ jobInstalled: null, now: M8_NOW }).reason, "never-beaten");
+  assert.equal(sessionNote({ now: M8_NOW }).reason, "never-beaten");
+  // No label still yields a usable line.
+  assert.match(sessionNote({ jobInstalled: false, now: M8_NOW }).detail, /main-session launchd job/);
+  // …and it does not call a deliberate daemon-front-door seat broken: this seat
+  // reports job-absent on EVERY beat forever, so the line states a configuration.
+  assert.match(n.detail, /the daemon --print lane is the front door/);
+  assert.match(n.detail, /by configuration, or the session job was never installed/);
+});
+
+test("sessionNote: awaiting-input passes the supervisor's own reason, since and hint through", () => {
+  const { sessionNote } = _internals;
+  const n = sessionNote({ jobInstalled: true, attention: attention(), now: M8_NOW });
+  assert.equal(n.reason, "awaiting-input", "the beat's vocabulary — the record's own reason rides in detail");
+  assert.equal(n.since, "2026-09-11T11:57:00.000Z", "attentionRecord.since, normalised to canonical ISO");
+  assert.match(n.detail, /^up, never beaten: /, "the record's own reason survives, rendered out of the watchdog's vocabulary");
+  assert.match(n.detail, /tmux attach -t =maestro-maya/, "the attach command is the actionable part");
+  assert.ok(n.detail.length <= 200);
+  // screen seats say screen.
+  assert.match(sessionNote({ attention: attention({ attach: "screen -r maestro-isla", hint: "… Attach with `screen -r maestro-isla` and answer it." }), now: M8_NOW }).detail, /screen -r maestro-isla/);
+  // It outranks a stale heartbeat: "waiting on a human" is the actionable fact.
+  assert.equal(sessionNote({ jobInstalled: true, attention: attention(), heartbeat: { ts: M8_NOW - 600_000 }, now: M8_NOW }).reason, "awaiting-input");
+});
+
+test("sessionNote: a heartbeat LATER than the attention record supersedes it", () => {
+  const { sessionNote } = _internals;
+  // supervisor.mjs clears attention.json only at the START of the next launch —
+  // never when the human answers the dialog — so the record outlives its truth.
+  // Answered at 11:57, beat until 3 days later, then the session died.
+  const beat = M8_NOW + 3 * 86_400_000;
+  const n = sessionNote({ jobInstalled: true, attention: attention(), heartbeat: { ts: beat }, now: beat + 86_400_000 });
+  assert.equal(n.reason, "heartbeat-stale", "a days-old attach command for a mux session that ended is worse than no note");
+  assert.equal(n.since, new Date(beat).toISOString());
+  // A record with no orderable `since` loses to a heartbeat that has one.
+  assert.equal(sessionNote({ jobInstalled: true, attention: attention({ since: "not a date" }), heartbeat: { ts: M8_NOW - 600_000 }, now: M8_NOW }).reason, "heartbeat-stale");
+  // But the record still wins while it is the LATER fact — the ordinary case:
+  // the session came up, never beat, and the watchdog flagged it.
+  assert.equal(sessionNote({ jobInstalled: true, attention: attention(), heartbeat: { ts: M8_NOW - 600_000 }, now: M8_NOW }).reason, "awaiting-input");
+  // …and with no heartbeat at all there is nothing to supersede it.
+  assert.equal(sessionNote({ jobInstalled: true, attention: attention(), heartbeat: { pid: 7 }, now: M8_NOW }).reason, "awaiting-input");
+});
+
+test("sessionNote: `since` is re-formatted from a parsed instant, never passed through", () => {
+  const { sessionNote } = _internals;
+  // V8's legacy date parser accepts trailing prose, so a bare Date.parse check
+  // let a home path and a token-shaped run ride the one field the detail
+  // sanitiser does not cover. `since` is canonical ISO or it is absent.
+  const evil = "Thu, 01 Jan 2026 00:00:00 GMT (token sk-ant-supersecretvalue1234567890 /Users/maya/x)";
+  assert.ok(Number.isFinite(Date.parse(evil)), "the hostile string really does parse — that is the hazard");
+  const n = sessionNote({ jobInstalled: true, attention: attention({ since: evil }), now: M8_NOW });
+  assert.equal(n.since, "2026-01-01T00:00:00.000Z");
+  assert.ok(!/Users|sk-ant/.test(n.since));
+  // Non-ISO spellings are normalised rather than echoed.
+  assert.equal(sessionNote({ jobInstalled: true, attention: attention({ since: "2026-09-11T11:57:00+00:00" }), now: M8_NOW }).since, "2026-09-11T11:57:00.000Z");
+});
+
+test("sessionNote: the attention record's own vocabulary is rendered, not collided with", () => {
+  const { sessionNote } = _internals;
+  // first-run#heartbeatSilence's "no-heartbeat" means "up, never beaten" — the
+  // opposite of what a beat reason of nearly that spelling would mean. Rendering
+  // it keeps `{reason, detail}` from reading as a contradiction side by side.
+  assert.match(sessionNote({ jobInstalled: true, attention: attention(), now: M8_NOW }).detail, /^up, never beaten: /);
+  assert.match(sessionNote({ jobInstalled: true, attention: attention({ reason: "stale-heartbeat" }), now: M8_NOW }).detail, /^no beat since this launch: /);
+  // A word we do not know passes through verbatim rather than being invented.
+  assert.match(sessionNote({ jobInstalled: true, attention: attention({ reason: "wedged-mcp" }), now: M8_NOW }).detail, /^wedged-mcp: /);
+  // And no beat reason collides with a watchdog reason any more.
+  const beatReasons = new Set(["job-absent", "awaiting-input", "heartbeat-stale", "heartbeat-unreadable", "never-beaten"]);
+  for (const r of ["no-heartbeat", "stale-heartbeat", "within-grace", "beating"]) assert.ok(!beatReasons.has(r), `${r} is the watchdog's word, not the beat's`);
+});
+
+test("sessionNote: heartbeat-stale carries the last beat and its age", () => {
+  const { sessionNote } = _internals;
+  const n = sessionNote({ jobInstalled: true, heartbeat: { ts: M8_NOW - 600_000, pid: 4242 }, now: M8_NOW });
+  assert.deepEqual(n, { reason: "heartbeat-stale", since: "2026-09-11T11:50:00.000Z", detail: "no beat for 600 s" });
+  // ISO timestamps are the shape the feed actually writes.
+  assert.equal(sessionNote({ jobInstalled: true, heartbeat: { ts: "2026-09-11T11:50:00Z" }, now: M8_NOW }).since, "2026-09-11T11:50:00.000Z");
+  // A beat from the future is clock skew, not a negative age.
+  assert.equal(sessionNote({ jobInstalled: true, heartbeat: { ts: M8_NOW + 600_000 }, now: M8_NOW }).detail, "last beat is in the future (clock skew)");
+});
+
+test("sessionNote: every malformed input degrades to a coarser note or to null, and nothing throws", () => {
+  const { sessionNote } = _internals;
+  // No `now` at all → no note (a note with no clock behind it would be a guess).
+  assert.equal(sessionNote({ heartbeat: { ts: 1 } }), null);
+  assert.equal(sessionNote({ now: NaN, jobInstalled: false }), null);
+  assert.equal(sessionNote(), null);
+  assert.equal(sessionNote(null), null);
+  assert.equal(sessionNote("nonsense"), null);
+  // Absent files (the reader's null) → the installed-but-silent note.
+  assert.deepEqual(sessionNote({ heartbeat: null, attention: null, jobInstalled: true, now: M8_NOW }),
+    { reason: "never-beaten", detail: "the session job is installed but has never written a heartbeat" });
+  // …and when job presence was never established, the note says THAT rather
+  // than affirming an installation nobody checked.
+  assert.deepEqual(sessionNote({ jobInstalled: null, now: M8_NOW }),
+    { reason: "never-beaten", detail: "no heartbeat from the session job, and its presence on this seat could not be checked" });
+  assert.equal(sessionNote({ now: M8_NOW }).detail, "no heartbeat from the session job, and its presence on this seat could not be checked");
+  // A parsed-but-wrong SHAPE must not throw.
+  assert.equal(sessionNote({ heartbeat: "{}", attention: "{}", now: M8_NOW }).reason, "never-beaten");
+  assert.equal(sessionNote({ heartbeat: [], attention: [], jobInstalled: true, now: M8_NOW }).reason, "never-beaten", "arrays are not records");
+  // A heartbeat file that is THERE but says nothing usable is its own fault —
+  // the job may well have beaten, so it is never called "never beaten".
+  assert.deepEqual(sessionNote({ heartbeat: { pid: 7 }, jobInstalled: true, now: M8_NOW }),
+    { reason: "heartbeat-unreadable", detail: "the heartbeat file is present but carries no readable timestamp" });
+  assert.equal(sessionNote({ heartbeat: { ts: "not a date" }, jobInstalled: true, now: M8_NOW }).reason, "heartbeat-unreadable");
+  assert.deepEqual(sessionNote({ heartbeatUnreadable: true, jobInstalled: true, now: M8_NOW }),
+    { reason: "heartbeat-unreadable", detail: "the heartbeat file is present but could not be parsed" });
+  // An attention record missing every field is still the right REASON — it is
+  // the file's existence that says "the supervisor flagged this seat".
+  assert.deepEqual(sessionNote({ attention: {}, jobInstalled: true, now: M8_NOW }), { reason: "awaiting-input" });
+  assert.deepEqual(sessionNote({ attention: { since: 12345, reason: 7, hint: null }, jobInstalled: true, now: M8_NOW }), { reason: "awaiting-input" });
+  assert.equal(sessionNote({ attention: { since: "not a date", reason: "no-heartbeat" }, jobInstalled: true, now: M8_NOW }).since, undefined);
+});
+
+test("sanitizeNoteDetail: no home paths, no ids, no control characters, never past the cap", () => {
+  const { sanitizeNoteDetail } = _internals;
+  assert.equal(sanitizeNoteDetail("attach with `tmux attach -t =maestro-maya`"), "attach with `tmux attach -t =maestro-maya`");
+  // Home directories name a person and leak the seat's layout.
+  assert.equal(sanitizeNoteDetail("blocked in /Users/maya/maya-ai/state"), "blocked in <path>");
+  // A home directory with a space in it is ordinary on macOS, and its tail
+  // carries the person's surname — the match may not stop at the whitespace.
+  assert.equal(sanitizeNoteDetail("blocked in /Users/olivia chen/maya-ai/state/session"), "blocked in <path>");
+  assert.equal(sanitizeNoteDetail("blocked in /Users/Olivia Chen/Library/Application Support/x"), "blocked in <path>");
+  // …but ordinary prose after a path is not swallowed with it.
+  assert.equal(sanitizeNoteDetail("blocked in /Users/maya and then retry"), "blocked in <path> and then retry");
+  assert.equal(sanitizeNoteDetail("attach to /Users/maya/x and answer it"), "attach to <path> and answer it");
+  assert.equal(sanitizeNoteDetail("blocked in ~/maya-ai and /home/maya/x and /private/var/folders/t/x"), "blocked in <path> and <path> and <path>");
+  // Session ids and token-shaped runs.
+  assert.equal(sanitizeNoteDetail("resume 3f2a1c94-7b0e-4a11-9c3d-0b7e2f8a6d51 failed"), "resume <redacted> failed");
+  assert.equal(sanitizeNoteDetail("token sk-ant-0123456789abcdef rejected"), "token <redacted> rejected");
+  // Newlines and control characters collapse; the note is one line.
+  assert.equal(sanitizeNoteDetail("a\nb\tc\r\nd"), "a b c d");
+  // The cap holds, with an ellipsis so a reader knows it was cut.
+  const long = sanitizeNoteDetail("lorem ipsum ".repeat(50));
+  assert.equal(long.length, 200);
+  assert.ok(long.endsWith("…"));
+  assert.ok(sanitizeNoteDetail("ab ".repeat(20), 10).length <= 10, "the cap is a ceiling, never exceeded (a word boundary can land under it)");
+  // Nothing to say → "", and the caller then omits the field entirely.
+  assert.equal(sanitizeNoteDetail(""), "");
+  assert.equal(sanitizeNoteDetail(null), "");
+  assert.equal(sanitizeNoteDetail(undefined), "");
+  assert.equal(sanitizeNoteDetail(42), "");
+  assert.equal(sanitizeNoteDetail("   \n  "), "");
+  // A hint long enough to overflow is truncated, not dropped.
+  const hint = sanitizeNoteDetail(`no-heartbeat: The session has been up 1800 s without a heartbeat — it is probably waiting on a first-run dialog or a permission prompt. Attach with \`tmux attach -t =maestro-maya\` and answer it. ${"tail ".repeat(20)}`);
+  assert.ok(hint.length <= 200 && hint.endsWith("…"), "an over-long hint is truncated, not dropped");
+});
+
+test("sessionJobInstalled: a readdir of ~/Library/LaunchAgents, and 'unknown' whenever it cannot be read", () => {
+  const { sessionJobInstalled, sessionJobLabel } = _internals;
+  const label = "ai.maestro.maya-session";
+  assert.equal(sessionJobInstalled({ launchAgents: ["ai.maestro.maya.plist", "ai.maestro.maya-session.plist"] }, label), true);
+  assert.equal(sessionJobInstalled({ launchAgents: ["ai.maestro.maya-session"] }, label), true, "bare labels count too");
+  assert.equal(sessionJobInstalled({ launchAgents: ["ai.maestro.maya.plist"] }, label), false);
+  assert.equal(sessionJobInstalled({ launchAgents: [] }, label), false);
+  // Unknowns: no label, an unreadable home, a home that is not there.
+  assert.equal(sessionJobInstalled({ launchAgents: ["ai.maestro.maya-session.plist"] }, ""), null);
+  assert.equal(sessionJobInstalled({ os: { homedir: () => "" } }, label), null);
+  assert.equal(sessionJobInstalled({ os: { homedir: () => { throw new Error("nope"); } } }, label), null);
+  assert.equal(sessionJobInstalled({ os: { homedir: () => join(tmpdir(), "no-such-home-xyz") } }, label), null);
+  // An explicit override wins (the daemon may already know).
+  assert.equal(sessionJobInstalled({ sessionJobInstalled: true, launchAgents: [] }, label), true);
+  // A case difference is not an absence: agentFirstName leaves its directory
+  // fallback as-is (`~/Maya-ai` -> `Maya`), and the volume is case-insensitive.
+  assert.equal(sessionJobInstalled({ launchAgents: ["ai.maestro.Maya-session.plist"] }, "ai.maestro.maya-session"), true);
+  assert.equal(sessionJobInstalled({ launchAgents: ["ai.maestro.maya-session.plist"] }, "ai.maestro.Maya-session"), true);
+  // The label matches what generate-plists.sh and `maestro session` spell —
+  // including its casing, which the generator does not lower-case either.
+  assert.equal(sessionJobLabel("/x/maya-ai", "maya"), "ai.maestro.maya-session");
+  assert.equal(sessionJobLabel("/x/Maya-ai", "Maya"), "ai.maestro.Maya-session");
+  assert.equal(sessionJobLabel("", ""), "");
+});
+
+test("collectStatus: machine.sessionNote appears ONLY when the front door is down, and rides machine (never session)", async () => {
+  const root = mkdtempSync(join(tmpdir(), "session-note-"));
+  try {
+    const now = Date.parse("2026-09-11T12:00:00Z");
+    const osImpl = fakeOs({});
+    osImpl.hostname = () => "seat.local";
+    const base = {
+      agentRoot: root, now, os: osImpl, execFile: fakeExecFile({}), subAgentsRunning: 0,
+      powermetrics: false, disk: false, spend: false, agentFirst: "maya", launchAgents: [],
+    };
+    const sess = join(root, "state", "session");
+    mkdirSync(sess, { recursive: true });
+
+    // 1. No job on the seat — the case A010/A016 could not tell apart.
+    const absent = await collectStatus(base);
+    assert.equal(absent.machine.sessionLive, false);
+    assert.equal(absent.machine.sessionNote.reason, "job-absent");
+    assert.match(absent.machine.sessionNote.detail, /ai\.maestro\.maya-session/);
+    assert.equal(absent.session, null, "the note NEVER touches session — hq validates that object strictly");
+    assert.ok(!("sessionNote" in (absent.session || {})));
+
+    // 2. Job installed, session up, waiting on a first-run dialog.
+    const installed = { ...base, launchAgents: ["ai.maestro.maya-session.plist"] };
+    writeFileSync(join(sess, "attention.json"), JSON.stringify(attention()));
+    const waiting = await collectStatus(installed);
+    assert.equal(waiting.machine.sessionNote.reason, "awaiting-input");
+    assert.equal(waiting.machine.sessionNote.since, "2026-09-11T11:57:00.000Z");
+    assert.match(waiting.machine.sessionNote.detail, /tmux attach -t =maestro-maya/);
+
+    // 3. The supervisor cleared attention.json and the beat then went stale.
+    rmSync(join(sess, "attention.json"));
+    writeFileSync(join(sess, "heartbeat.json"), JSON.stringify({ pid: 4242, ts: "2026-09-11T11:50:00Z" }));
+    const stale = await collectStatus(installed);
+    assert.equal(stale.machine.frontDoor, "session");
+    assert.deepEqual(stale.machine.sessionNote, { reason: "heartbeat-stale", since: "2026-09-11T11:50:00.000Z", detail: "no beat for 600 s" });
+
+    // 4. A live front door carries NO note — the key is absent, not null.
+    writeFileSync(join(sess, "heartbeat.json"), JSON.stringify({ pid: 4242, ts: "2026-09-11T11:59:50Z" }));
+    const live = await collectStatus(installed);
+    assert.equal(live.machine.sessionLive, true);
+    assert.ok(!("sessionNote" in live.machine), "a healthy seat must not pay for a field it has nothing to say in");
+
+    // 5. Corrupt state files never break the beat — and a heartbeat file that
+    //    is THERE and will not parse is reported as such, not as "never beaten".
+    writeFileSync(join(sess, "heartbeat.json"), "{not json");
+    writeFileSync(join(sess, "attention.json"), "{not json");
+    const corrupt = await collectStatus(installed);
+    assert.equal(corrupt.machine.sessionLive, false);
+    assert.deepEqual(corrupt.machine.sessionNote,
+      { reason: "heartbeat-unreadable", detail: "the heartbeat file is present but could not be parsed" });
+    assert.equal(typeof corrupt.ts, "string", "the snapshot is intact");
+
+    // 5b. No heartbeat file at all, job installed → never-beaten.
+    rmSync(join(sess, "heartbeat.json"));
+    rmSync(join(sess, "attention.json"));
+    const silent = await collectStatus(installed);
+    assert.deepEqual(silent.machine.sessionNote,
+      { reason: "never-beaten", detail: "the session job is installed but has never written a heartbeat" });
+
+    // 6. The whole note is a best-effort extra: a throwing os.homedir drops the
+    //    launchd read, never the beat — and an unknown job presence is reported
+    //    as neither an absence nor a presence.
+    const hostile = await collectStatus({ ...base, launchAgents: undefined, os: { ...osImpl, homedir: () => { throw new Error("no home"); } } });
+    assert.equal(hostile.machine.sessionNote.reason, "never-beaten", "unknown job presence is not an absence");
+    assert.equal(hostile.machine.sessionNote.detail, "no heartbeat from the session job, and its presence on this seat could not be checked",
+      "…and it is not reported as a presence either");
+    assert.equal(hostile.machine.sessionLive, false);
+
+    // 7. The emitted shape is exactly {reason, since?, detail?} — nothing else,
+    //    and nothing unbounded.
+    for (const s of [absent, waiting, stale, corrupt, silent, hostile]) {
+      const note = s.machine.sessionNote;
+      assert.equal(typeof note.reason, "string");
+      for (const k of Object.keys(note)) assert.ok(["reason", "since", "detail"].includes(k), `sessionNote.${k} is not in the contract`);
+      if (note.since !== undefined) assert.ok(Number.isFinite(Date.parse(note.since)), "since is ISO 8601");
+      if (note.detail !== undefined) assert.ok(note.detail.length <= 200 && !/\/Users\//.test(note.detail));
+    }
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cohortapp/agent-sdk",
-  "version": "2.13.0",
+  "version": "2.14.0",
   "description": "Cohort Agent SDK — autonomous AI colleague runtime. Deploy senior AI colleagues on dedicated Mac minis, wired to the Cohort operating surface.",
   "type": "module",
   "bin": {