@cohortapp/agent-sdk 2.12.0 → 2.14.0

package/lib/prompts/parallelism.test.mjs

@@ -0,0 +1,177 @@
+/**
+ * parallelism.test.mjs — the fleet-wide parallelism directive (WP-M7 mechanic 5).
+ *
+ * Three things are pinned here, and each has a distinct failure it prevents:
+ *
+ *   1. THE BYTES. The directive is quoted verbatim in the design spec and is the
+ *      one place a fleet-wide behaviour change is auditable. A silent reword —
+ *      dropping the file-scope sentence, say — would turn "maximum safe
+ *      parallelism" into two agents editing one file. So the expected text is
+ *      written out longhand below, NOT derived from the constant.
+ *   2. IDEMPOTENCE. Two seams apply it (`session spawn` and the daemon's
+ *      prompt-builder) and they compose. A doubled directive reads as emphasis
+ *      to a model, which is exactly how the safety sentence loses to the
+ *      permission sentence.
+ *   3. BOTH WIRINGS. A constant nothing calls is worth nothing; the two seams
+ *      are driven for real here.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { PARALLELISM_DIRECTIVE, withParallelism, countParallelism } from "./parallelism.mjs";
+
+/**
+ * The directive, longhand. Deliberately NOT built from the import: a test that
+ * compares a constant to itself proves nothing about the wording.
+ */
+const EXPECTED = [
+  "You are allowed to run multiple sub-agents concurrently.",
+  "",
+  "When the plan contains independent tasks, dispatch them together in a single parallel batch rather than waiting for each task to finish before starting the next.",
+  "",
+  "Only run tasks sequentially when one task genuinely depends on the output of another.",
+  "",
+  "Before dispatching any batch, check the planned file scope for each task and ensure that no two agents are assigned to edit the same file. If tasks would overlap on a file, sequence those tasks or redefine their scope to eliminate the conflict.",
+  "",
+  "Default to maximum safe parallelism.",
+].join("\n");
+
+test("PARALLELISM_DIRECTIVE is the spec's text, byte for byte", () => {
+  assert.equal(PARALLELISM_DIRECTIVE, EXPECTED);
+  // The two sentences that carry the whole point, named individually so a
+  // partial reword fails with a readable diff rather than one giant blob.
+  assert.match(PARALLELISM_DIRECTIVE, /single parallel batch/);
+  assert.match(PARALLELISM_DIRECTIVE, /no two agents are assigned to edit the same file/);
+  assert.ok(!PARALLELISM_DIRECTIVE.endsWith("\n"), "no trailing newline — the joiner adds the separator");
+});
+
+test("withParallelism prepends once and is idempotent", () => {
+  const prompt = "Reply to the message below.";
+  const once = withParallelism(prompt);
+  assert.ok(once.startsWith(PARALLELISM_DIRECTIVE), "the directive leads");
+  assert.ok(once.endsWith(prompt), "the caller's prompt survives intact");
+  assert.equal(countParallelism(once), 1);
+
+  const twice = withParallelism(once);
+  assert.equal(twice, once, "a second application changes nothing");
+  assert.equal(countParallelism(twice), 1);
+
+  const thrice = withParallelism(withParallelism(withParallelism(prompt)));
+  assert.equal(countParallelism(thrice), 1);
+});
+
+test("withParallelism tolerates an empty or non-string prompt", () => {
+  assert.equal(withParallelism(""), PARALLELISM_DIRECTIVE);
+  assert.equal(withParallelism("   \n "), PARALLELISM_DIRECTIVE);
+  assert.equal(withParallelism(undefined), PARALLELISM_DIRECTIVE);
+  assert.equal(withParallelism(null), PARALLELISM_DIRECTIVE);
+  assert.equal(withParallelism(42), PARALLELISM_DIRECTIVE);
+});
+
+test("a prompt that already carries the directive mid-body is not re-led", () => {
+  const embedded = `Context first.\n\n${PARALLELISM_DIRECTIVE}\n\nThen the task.`;
+  assert.equal(withParallelism(embedded), embedded);
+  assert.equal(countParallelism(withParallelism(embedded)), 1);
+});
+
+test("countParallelism counts non-overlapping occurrences", () => {
+  assert.equal(countParallelism(""), 0);
+  assert.equal(countParallelism(null), 0);
+  assert.equal(countParallelism("nothing here"), 0);
+  assert.equal(countParallelism(`${PARALLELISM_DIRECTIVE}\n\n${PARALLELISM_DIRECTIVE}`), 2);
+});
+
+// ── the two wired seams ─────────────────────────────────────────────────────
+
+test("maestro session spawn leads every peer prompt with the directive, exactly once", async () => {
+  const { buildSpawnArgs } = await import("../cli/session.mjs");
+  const prompt = "Sweep the backlog and file what you find.";
+  const args = buildSpawnArgs({ first: "nova", slug: "sweep", prompt, env: {}, allowedTools: [] });
+
+  assert.equal(args[0], "--name");
+  assert.equal(args[1], "nova-sweep");
+  const sent = args[args.length - 1];
+  assert.ok(sent.startsWith(PARALLELISM_DIRECTIVE), "the peer's prompt is led by the directive");
+  assert.ok(sent.endsWith(prompt));
+  assert.equal(countParallelism(sent), 1);
+
+  // The composing case: a prompt that already carries it is not doubled.
+  const pre = withParallelism(prompt);
+  const again = buildSpawnArgs({ first: "nova", slug: "sweep", prompt: pre, env: {}, allowedTools: [] });
+  assert.equal(countParallelism(again[again.length - 1]), 1);
+  assert.equal(again[again.length - 1], pre);
+});
+
+test("the daemon's prompt-builder leads every sub-session prompt with the directive, exactly once", async (t) => {
+  const { mkdtempSync, mkdirSync, writeFileSync } = await import("node:fs");
+  const { join } = await import("node:path");
+  const { tmpdir } = await import("node:os");
+
+  const root = mkdtempSync(join(tmpdir(), "maestro-parallelism-prompt-"));
+  mkdirSync(join(root, "config"), { recursive: true });
+  writeFileSync(join(root, "config", "agent.json"), JSON.stringify({ firstName: "Nova" }));
+  const prevAgentDir = process.env.AGENT_DIR;
+  process.env.AGENT_DIR = root;
+  t.after(() => {
+    if (prevAgentDir === undefined) delete process.env.AGENT_DIR;
+    else process.env.AGENT_DIR = prevAgentDir;
+  });
+
+  const url = new URL("../../scripts/daemon/prompt-builder.mjs", import.meta.url);
+  const pb = await import(`${url.href}?parallelism=${Math.random()}`);
+  const prompt = await pb.buildPrompt(
+    { sender: "Ana", content: "Three unrelated things need doing.", channel: "slack" },
+    { action: "respond", priority: "normal", summary: "three things" },
+    { type: "inbox" },
+  );
+
+  assert.ok(prompt.startsWith(PARALLELISM_DIRECTIVE), "the directive leads the built prompt");
+  assert.equal(countParallelism(prompt), 1);
+  assert.match(prompt, /Three unrelated things need doing\./, "the item's own content is still there");
+});
+
+test("the persona's precedence sentence names itself, so leading the prompt with the directive cannot mis-scope it", async (t) => {
+  // The sentence used to read "The section above … anything below". That was
+  // true only while the persona was the first thing in the prompt; once the
+  // directive leads, "above" has two candidate referents and the directive
+  // itself falls outside the rule (it is above, not below). Nothing else pins
+  // this ordering, so it is pinned here, beside the change that broke it.
+  const { mkdtempSync, mkdirSync, writeFileSync } = await import("node:fs");
+  const { join } = await import("node:path");
+  const { tmpdir } = await import("node:os");
+
+  const root = mkdtempSync(join(tmpdir(), "maestro-parallelism-persona-"));
+  mkdirSync(join(root, "config"), { recursive: true });
+  writeFileSync(join(root, "config", "agent.json"), JSON.stringify({ firstName: "Nova", lastName: "Reyes", title: "Chief of Staff" }));
+  writeFileSync(join(root, "config", "company.json"), JSON.stringify({ name: "Northwind" }));
+  const prevAgentDir = process.env.AGENT_DIR;
+  process.env.AGENT_DIR = root;
+  t.after(() => {
+    if (prevAgentDir === undefined) delete process.env.AGENT_DIR;
+    else process.env.AGENT_DIR = prevAgentDir;
+  });
+
+  const url = new URL("../../scripts/daemon/prompt-builder.mjs", import.meta.url);
+  const pb = await import(`${url.href}?persona=${Math.random()}`);
+  const prompt = await pb.buildPrompt(
+    { sender: "Ana", content: "Three unrelated things need doing.", channel: "slack" },
+    { action: "respond", priority: "normal", summary: "three things" },
+    { type: "inbox" },
+  );
+
+  assert.ok(prompt.startsWith(PARALLELISM_DIRECTIVE), "the directive leads");
+  assert.ok(
+    !/The section above is your identity/.test(prompt),
+    "a positional referent is wrong the moment anything is prepended",
+  );
+  assert.match(
+    prompt,
+    /This section is your identity, resolved from your organisation's record of you\. Where anything else in this prompt conflicts with it, this section wins\./,
+    "the precedence rule names itself and covers the whole prompt",
+  );
+  assert.ok(
+    prompt.indexOf(PARALLELISM_DIRECTIVE) < prompt.indexOf("This section is your identity"),
+    "the directive leads and the persona follows — the ordering the sentence had to stop assuming",
+  );
+});

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,