@cohortapp/agent-sdk 2.18.13 → 2.18.15

package/lib/telemetry/collect.mjs

@@ -84,8 +84,14 @@
  *       // Also on `machine` (open record), so hq's fleet view can show it next
  *       // to sdkVersion without a schema change. `ok` is the attempt's verdict:
  *       // true = healthy on `to`; false = install failed or rolled back to `from`.
+ *       // `failStreak` is the one field here that describes a PATTERN: N
+ *       // consecutive failed attempts to reach @latest, since `stuckSince`,
+ *       // against `streakTarget`. Absent below 1. A seat that has simply not
+ *       // been asked (nothing newer published, or held after its last failure)
+ *       // never accrues one — see autoupdate.sh's write_last.
  *       upgrade?: { at: ISO8601, from: string, to: string, ok: boolean,
- *                   reason?: string, healthy?: boolean },  // reason: WHY a failure failed
+ *                   reason?: string, healthy?: boolean,     // reason: WHY a failure failed
+ *                   failStreak?: number, stuckSince?: ISO8601, streakTarget?: string },
  *       // THE BEATING DAEMON — which process is emitting this beat, what code
  *       // it is actually running, and the last health-gate verdict on it.
  *       // Also on `machine` (open record). `sdkVersion` ABOVE is what is
@@ -99,6 +105,28 @@
  *       daemon?: { pid?: number, bootAt?: ISO8601, uptimeS?: number,
  *                  sdkVersion?: string, dashboardAt?: ISO8601,
  *                  healthy?: boolean, healthReason?: string },
+ *       // WHICH UPSTREAM FIXES CANNOT REACH THIS SEAT. A `.maestroignore`
+ *       // pin on a FRAMEWORK path is a fork, and upstream moves under it:
+ *       // five of sixteen seats were degraded by exactly this on 2026-09-25,
+ *       // two of them crash-looping at import time on a pinned deliver.mjs.
+ *       // `stranded` counts framework pins where upstream holds lines this
+ *       // seat refuses (`onlyUpstream > 0` in .maestro/ignored-drift.json) —
+ *       // that, and not "a file differs", is the property that means no
+ *       // release can ever reach this colleague. ABSENT ENTIRELY on a seat
+ *       // that pins nothing; `{unknown:true}` when the seat has pins and
+ *       // could not read its own report, which must never read as clean.
+ *       // INVENTORY: carries the `at`/`sdkVersion` of the upgrade that took
+ *       // it, not the snapshot's.
+ *       // `patterns` counts lines in `.maestroignore`; `matched` counts the
+ *       // entries the drift report covers. Two numbers, two names, on both
+ *       // branches — one glob can match forty files, or none.
+ *       pinnedDrift?: { patterns: number|null, matched: number, framework: number,
+ *                       seatOwned: number, drifting: number, stranded: number,
+ *                       strandedCode: number, localOnly: number,
+ *                       at: ISO8601|null, sdkVersion: string|null,
+ *                       worst: [{ path: string, behind: number, code: boolean }] }
+ *                    | { unknown: true, patterns: number|null, matched: null,
+ *                        reason: string },
  *     },
  *     claudeAuth: "ok"|"relogin_required"|"unknown",
  *     alerts: [{ id, severity, kind, detail }],
@@ -142,6 +170,8 @@ import { liveClaudeStats } from "../resource-governor.mjs";
 import { agentFirstName } from "../session/identity.mjs";
 import { snapshot as countersSnapshot } from "../diagnostics/counters.mjs";
 import { replyDebtFromCounters } from "../daemon/reply-debt.mjs";
+import { summarisePinnedDrift, countPins } from "../upgrade/pinned-drift.mjs";
+import { IGNORED_DRIFT_REL } from "../upgrade/ignored-drift.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"]);
@@ -1229,6 +1259,13 @@ const ATTENTION_WHY = {
   "no-heartbeat": "up, never beaten",
   "stale-heartbeat": "no beat since this launch",
   "beat-stopped": "beat, then stopped",
+  // The session is not wedged — it never STARTS. Written by the supervisor
+  // once N consecutive launches have failed identically
+  // (scripts/session/supervisor.mjs, lib/session/launch-failure.mjs). It is a
+  // different fault from the three above, with a different fix, and it is the
+  // one that looked like health for days on a seat relaunching a dead resume
+  // id every ten minutes.
+  "launch-failing": "cannot launch",
 };
 
 /**
@@ -1364,7 +1401,9 @@ export function sessionNote(a = {}) {
  * fields the fleet view reads; anything malformed → null, and the field drops
  * out rather than lying.
  * @param {object|null} last
- * @returns {{at:string, from:string, to:string, ok:boolean}|null}
+ * @returns {{at:string, from:string, to:string, ok:boolean, reason?:string,
+ *            healthy?:boolean, failStreak?:number, stuckSince?:string,
+ *            streakTarget?:string}|null}
  */
 export function upgradeSummary(last) {
   if (!last || typeof last !== "object") return null;
@@ -1382,6 +1421,19 @@ export function upgradeSummary(last) {
   // Bounded on the way out: a reason is a short token plus at most a trimmed
   // error line, and the beat is not a log shipper.
   const reason = typeof last.reason === "string" ? last.reason.trim().slice(0, 300) : "";
+  // `failStreak` — how many CONSECUTIVE upgrade attempts have failed, with the
+  // instant the run of failures began and the version it is failing against.
+  // Written by autoupdate.sh's write_last; see the long block above it for what
+  // does and does not count as an attempt. This is the ONLY field here that is
+  // about a pattern rather than an event, and it is the reason three seats sat
+  // on 2.17.0 for days without anything saying so: every individual record was
+  // a truthful `ok:false` that told a reader nothing about the fortieth one.
+  //
+  // Absent when zero, so a healthy seat's beat carries nothing extra and a
+  // reader can treat presence as the finding.
+  const failStreak = Number.isInteger(last.failStreak) && last.failStreak > 0 ? last.failStreak : 0;
+  const stuckSince = typeof last.stuckSince === "string" && !Number.isNaN(Date.parse(last.stuckSince)) ? last.stuckSince : "";
+  const streakTarget = typeof last.streakTarget === "string" ? last.streakTarget.trim().slice(0, 40) : "";
   return {
     at,
     from: typeof last.from === "string" ? last.from : "",
@@ -1389,6 +1441,9 @@ export function upgradeSummary(last) {
     ok: last.ok === true,
     ...(reason ? { reason } : {}),
     ...(typeof last.healthy === "boolean" ? { healthy: last.healthy } : {}),
+    ...(failStreak ? { failStreak } : {}),
+    ...(failStreak && stuckSince ? { stuckSince } : {}),
+    ...(failStreak && streakTarget ? { streakTarget } : {}),
   };
 }
 
@@ -1509,6 +1564,86 @@ export function daemonSummary(dash, last) {
   return Object.keys(out).length > 0 ? out : null;
 }
 
+// ---------------------------------------------------------------------------
+// Pinned framework files — WHICH UPSTREAM FIXES CANNOT REACH THIS SEAT
+// (`machine.pinnedDrift`)
+// ---------------------------------------------------------------------------
+
+/**
+ * Pure: the beat's `machine.pinnedDrift`.
+ *
+ * WHY THIS FIELD EXISTS. A `.maestroignore` entry on a framework path is a
+ * fork, and upstream keeps moving under it. MEASURED 2026-09-25, repairing
+ * five of sixteen seats by hand: two were crash-looping at import time on a
+ * pinned `lib/org/inbound/deliver.mjs`; two more pinned
+ * `scripts/daemon/agent-daemon.mjs` and therefore could not receive the
+ * front-door revive fix (2.18.11/12) OR the persona fix — one of them went on
+ * emitting an AI self-introduction for days after it was fixed upstream,
+ * because the fix could not physically arrive.
+ *
+ * Every one of those seats already knew. `maestro upgrade` has written the
+ * per-file answer to `.maestro/ignored-drift.json` for weeks and NOTHING read
+ * it — no warning, no beat field, no alert. This is the half that makes the
+ * knowledge leave the machine it is about.
+ *
+ * THE PROPERTY WORTH CARRYING is not "a file differs". It is "upstream holds
+ * lines this pin refuses", which is `onlyUpstream > 0` on a framework path —
+ * see `lib/upgrade/pinned-drift.mjs` for why (on this seat the same day, two
+ * of seven drifting pins refused nothing at all, which is what a pin is FOR).
+ *
+ * SMALL AND BOUNDED, like every other field on `machine`: a handful of counts
+ * and at most three paths, each capped (the size floor is pinned by
+ * `pinned-drift-beat.test.mjs`). It rides `machine` for the reason
+ * `frontDoor` and `daemon` do — hq validates `machine` as an OPEN record
+ * (`presence/beat.ts#statusSchema`) while `session` is `.strict()`, so a new
+ * seat-level fact lands without a lock-step hq deploy.
+ *
+ * THREE ANSWERS, AND THE THIRD IS THE POINT:
+ *   · a seat that pins nothing returns `null` — the caller drops the key, and
+ *     hq grows no field and no alert for a seat with nothing wrong;
+ *   · a seat that pins something and cannot read its own report returns
+ *     `{unknown:true}` — never a clean bill. "Could not tell" and "nothing to
+ *     tell" are opposite instructions, and collapsing them is the exact
+ *     failure this whole field exists to end.
+ *
+ * INVENTORY, not a momentary reading: the report is written by the last
+ * upgrade and stays true until the next one, so it carries its own `at` and
+ * the `sdkVersion` it was taken against rather than borrowing the snapshot's.
+ *
+ * @param {object|null} report  parsed `.maestro/ignored-drift.json`, or null
+ * @param {number|null} pinCount  pattern lines in `.maestroignore`, or null
+ *                                when even that could not be read
+ */
+export function pinnedDriftSummary(report, pinCount) {
+  return summarisePinnedDrift(report, { pinCount });
+}
+
+/** `.maestro/ignored-drift.json`, or null — fail-open. */
+function readIgnoredDriftReport(agentRoot) {
+  if (!agentRoot) return null;
+  return safeReadJson(join(resolve(agentRoot), IGNORED_DRIFT_REL));
+}
+
+/**
+ * How many real patterns `.maestroignore` holds — `0` when the file is absent
+ * (a seat with no pins), `null` when it exists and could not be read.
+ *
+ * The distinction is load-bearing: `0` is what lets the field be dropped
+ * entirely, and `null` is what forces `unknown` instead of a clean answer.
+ * A missing file is a definite zero; an unreadable one is not.
+ */
+function readPinCount(agentRoot) {
+  if (!agentRoot) return null;
+  const file = join(resolve(agentRoot), ".maestroignore");
+  let text;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch (e) {
+    return e && e.code === "ENOENT" ? 0 : null;
+  }
+  return countPins(text);
+}
+
 /** state/autoupdate/last.json, or null. */
 function readAutoupdateLast(agentRoot) {
   if (!agentRoot) return null;
@@ -1974,6 +2109,21 @@ export async function collectStatus(o = {}) {
     if (d) machine.daemon = d;
   } catch { /* no daemon field */ }
 
+  // 4e. WHICH UPSTREAM FIXES CANNOT REACH THIS SEAT — `machine.pinnedDrift`,
+  // absent on a seat that pins nothing. See `pinnedDriftSummary` for the five
+  // seats this was measured on. Fail-open like every probe here: a throw drops
+  // the field, never the beat — but note that a *readable* seat with pins and
+  // an unreadable report deliberately lands `{unknown:true}` rather than
+  // nothing, because "I could not tell" must never render as "clean".
+  try {
+    const pinReport = opt.ignoredDrift !== undefined
+      ? opt.ignoredDrift
+      : readIgnoredDriftReport(opt.agentRoot);
+    const pins = opt.pinCount !== undefined ? opt.pinCount : readPinCount(opt.agentRoot);
+    const pd = pinnedDriftSummary(pinReport, pins);
+    if (pd) machine.pinnedDrift = pd;
+  } catch { /* no pinnedDrift field */ }
+
   const status = {
     state,
     activity: act.activity || "idle",
@@ -2026,6 +2176,9 @@ export const _internals = {
   upgradeSummary,
   parseDaemonHealthYaml,
   daemonSummary,
+  pinnedDriftSummary,
+  readIgnoredDriftReport,
+  readPinCount,
   detectClaudeAuth,
   resetAuthProbeCache,
   scanForRelogin,