@cohortapp/agent-sdk 2.18.12 → 2.18.14

package/lib/telemetry/collect.mjs

@@ -99,6 +99,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 +164,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 +1253,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",
 };
 
 /**
@@ -1509,6 +1540,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 +2085,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 +2152,9 @@ export const _internals = {
   upgradeSummary,
   parseDaemonHealthYaml,
   daemonSummary,
+  pinnedDriftSummary,
+  readIgnoredDriftReport,
+  readPinCount,
   detectClaudeAuth,
   resetAuthProbeCache,
   scanForRelogin,

package/lib/upgrade/pinned-drift.mjs

@@ -0,0 +1,467 @@
+/**
+ * lib/upgrade/pinned-drift.mjs — a `.maestroignore` pin that has STRANDED an
+ * upstream fix, said loudly enough that somebody acts on it.
+ *
+ * ── THE FAULT THIS EXISTS TO END ────────────────────────────────────────────
+ * `.maestroignore` tells `maestro upgrade` never to touch a path. That is the
+ * entry's whole purpose and it is usually right: a seat's own `config/`,
+ * `CLAUDE.md`, `knowledge/` and `memory/` are the agent, not the framework,
+ * and nothing should ever overwrite them. (The upgrade does not ship those
+ * paths at all, so pinning them is belt-and-braces, not a fork.)
+ *
+ * A pin on a FRAMEWORK path is a different animal. It is a FORK: the seat's
+ * copy stops moving while the libraries it imports keep going, and the seat
+ * eventually dies at import time —
+ *
+ *   SyntaxError: The requested module './deliver.mjs' does not provide an
+ *   export named 'cohortSurfaceIsDeclared'
+ *
+ * MEASURED 2026-09-25, repairing five of sixteen seats by hand. Candace Wong
+ * and Layla Al-Masri were crash-looping on a pinned `deliver.mjs`. Jacob Stein
+ * and Isla Roselli pinned `scripts/daemon/agent-daemon.mjs`, which is why the
+ * front-door revive fix (2.18.11/12) and the persona fix never reached them —
+ * Jacob went on emitting an AI self-introduction for DAYS after it was fixed
+ * upstream, because the fix could not physically arrive.
+ *
+ * ── THE PART THAT STINGS ────────────────────────────────────────────────────
+ * Every one of those seats already KNEW. `lib/upgrade/ignored-drift.mjs` has
+ * computed the per-file answer for weeks and `maestro upgrade` writes it to
+ * `.maestro/ignored-drift.json` on every run. Nothing read it: no warning that
+ * distinguished a dangerous pin from a harmless one, no field on the presence
+ * beat, no alert. The knowledge sat on the disk of the machine it was about.
+ *
+ * This module is the reading half. It is PURE over the report
+ * `ignored-drift.mjs` already produces, and it answers ONE question the raw
+ * report does not: **is upstream carrying lines this seat cannot receive?**
+ *
+ * ── WHY `onlyUpstream`, NOT "drifts" ────────────────────────────────────────
+ * `drifts` is the wrong alarm and it would cry wolf on every healthy fork.
+ * Measured on this seat the same day: seven pinned files, all seven `drifts`,
+ * and TWO of them (`scripts/healthcheck.sh`, `scripts/system-verify.sh`) had
+ * `onlyUpstream: 0` — the local file is a strict superset of upstream, upstream
+ * holds nothing the seat lacks, and the pin is stranding precisely nothing.
+ * That is what a pin is FOR and paging about it teaches the reader to ignore
+ * the page.
+ *
+ * `onlyUpstream > 0` is the honest predicate: upstream has lines this file does
+ * not, the pin refuses them, and no release will ever change that. A file in
+ * that state is called STRANDED here, and it is the only thing worth waking
+ * somebody for.
+ *
+ * It is a LOWER BOUND, not a patch: the line counts are a multiset difference
+ * (see `ignored-drift.mjs`), so a moved block counts as zero. A stranded file
+ * is therefore certainly stranded; a non-stranded one is merely not visibly so.
+ * The claim this module makes is only ever the first of those.
+ *
+ * @module lib/upgrade/pinned-drift
+ */
+
+"use strict";
+
+/**
+ * Paths the SEAT owns. `maestro upgrade` ships none of them, so a pin here
+ * protects nothing and strands nothing — it is inert, and it should STAY.
+ *
+ * Listed so the warning can say so out loud. The measured failure mode of a
+ * loud drift warning is an operator who empties `.maestroignore` to silence it
+ * and loses their own agent in the process; naming these as safe is what stops
+ * that being the obvious next move.
+ */
+export const SEAT_OWNED_PREFIXES = Object.freeze([
+  "config/",
+  "knowledge/",
+  "memory/",
+  "state/",
+  "logs/",
+  "notes/",
+  "journal/",
+  ".maestro/",
+]);
+
+/** Seat-owned single files, matched exactly. */
+export const SEAT_OWNED_FILES = Object.freeze([
+  "CLAUDE.md",
+  "AGENTS.md",
+  ".env",
+  ".maestroignore",
+]);
+
+/**
+ * Trees `maestro upgrade` actually ships, from this package's own `files`
+ * list. A pin under one of these is a FORK of framework code or framework
+ * prompts, and upstream will move under it.
+ *
+ * Kept as data rather than read from `package.json` at runtime because this
+ * module is pure and is also evaluated against a report produced by a
+ * DIFFERENT (older) SDK than the one reading it — the seat's report names
+ * paths, not a manifest, and the classification must not change depending on
+ * which package happens to be installed where the check runs.
+ *
+ * PREFIXES ARE NOT THE WHOLE MANIFEST — see {@link SHIPPED_ROOT_FILES}. The
+ * hand-copied list is pinned against the real `files` array by this module's
+ * test, because the failure mode of a hand-copied manifest is silence: a
+ * shipped path this list forgets is classified `other`, strands nothing by
+ * construction, and prints no warning at all.
+ */
+export const FRAMEWORK_PREFIXES = Object.freeze([
+  "bin/",
+  "lib/",
+  "scripts/",
+  "schedules/",
+  "workflows/",
+  "agents/",
+  "policies/",
+  "teams/",
+  "archetypes/",
+  "scaffold/",
+  "mcp/",
+  "ingest/",
+  "desktop-control/",
+  "plugins/",
+  "public/",
+  "docs/",
+  ".claude/",
+]);
+
+/**
+ * Files `maestro upgrade` ships at the ROOT of the agent directory, matched
+ * exactly. Three of them, and every one is a live framework surface.
+ *
+ * THIS SET IS WHY THE PREFIX LIST ALONE IS A BUG. `package.json#files` carries
+ * `framework-features.json` (21KB of feature declarations an upgrade would
+ * otherwise replace wholesale), `README.md` and `.env.example` beside the
+ * trees. A prefix-only classifier calls all three `other`, which means
+ * `isStranded` is false for them, which means a seat that pins ONLY
+ * `framework-features.json` while upstream moves under it prints nothing —
+ * byte-identical to the output of a seat that pins nothing at all. Before this
+ * module existed that seat got a blanket drift warning; the first cut of this
+ * module took the warning away and gave it no replacement.
+ *
+ * `.env.example` is NOT `.env`: the seat owns the latter (see
+ * {@link SEAT_OWNED_FILES}) and upgrade ships the former. They are matched
+ * exactly, so the two never collide.
+ */
+export const SHIPPED_ROOT_FILES = Object.freeze([
+  "framework-features.json",
+  "README.md",
+  ".env.example",
+]);
+
+/** Where the report lives, quoted in the overflow line. */
+const IGNORED_DRIFT_HINT = ".maestro/ignored-drift.json";
+
+/** Extensions whose rot is an IMPORT-TIME DEATH rather than a stale sentence. */
+const CODE_EXTENSIONS = Object.freeze([".mjs", ".js", ".cjs", ".ts", ".sh", ".py"]);
+
+/**
+ * Who owns this pinned path.
+ *
+ *   "seat"      the agent's own content — upgrade never ships it, pin is inert
+ *   "framework" a tree upgrade ships — the pin is a fork and upstream moves
+ *   "other"     neither; upgrade ships nothing there, so nothing can strand
+ *
+ * Seat-owned wins over framework on a tie, and there is one real tie:
+ * `.claude/` is shipped AND edited by hand. It is classified framework because
+ * that is where the danger is; a seat that wants its own command file there
+ * keeps the pin and accepts the fork, which the warning says.
+ *
+ * @param {string} path repo-relative path as the report records it
+ * @returns {"seat"|"framework"|"other"}
+ */
+export function pinClass(path) {
+  const p = String(path || "").replace(/^\.\//, "");
+  if (p === "") return "other";
+  if (SEAT_OWNED_FILES.includes(p)) return "seat";
+  for (const pre of SEAT_OWNED_PREFIXES) if (p.startsWith(pre)) return "seat";
+  if (SHIPPED_ROOT_FILES.includes(p)) return "framework";
+  for (const pre of FRAMEWORK_PREFIXES) if (p.startsWith(pre)) return "framework";
+  return "other";
+}
+
+/**
+ * Ownership of a REPORTED pin, with the report's own evidence outranking the
+ * hand-copied manifest above.
+ *
+ * ── WHY EVIDENCE BEATS THE LIST ─────────────────────────────────────────────
+ * {@link pinClass} knows the shipped set by NAME, and a list of names is the
+ * thing that goes stale — quietly, in the direction of saying nothing, which
+ * is exactly how `framework-features.json` fell out of the warning. The REPORT
+ * does not guess: `ignored-drift.mjs` only records `drifts`, `identical` or
+ * `upstream-only` for a path where it actually READ an upstream copy out of
+ * the installed package. Any of those three states is proof that upgrade ships
+ * that path, whatever this module's prefixes happen to say.
+ *
+ * So a path the list does not name, whose report says upstream holds a copy,
+ * is framework. `local-only` is the one state that proves the opposite
+ * (upstream ships nothing there) and stays `other`; a seat-owned path stays
+ * seat-owned, since upgrade shipping something under `config/` would be a bug
+ * upstream rather than a fork here.
+ *
+ * @param {{path?:string, state?:string}} file one entry of the report
+ * @returns {"seat"|"framework"|"other"}
+ */
+export function pinClassOf(file) {
+  const cls = pinClass(file && file.path);
+  if (cls !== "other") return cls;
+  const state = file && file.state;
+  if (state === "drifts" || state === "identical" || state === "upstream-only") {
+    return "framework";
+  }
+  return "other";
+}
+
+/** Would rot here kill the seat at import time, rather than merely age? */
+export function isCodePin(path) {
+  const p = String(path || "").toLowerCase();
+  return CODE_EXTENSIONS.some((ext) => p.endsWith(ext));
+}
+
+/**
+ * Is upstream carrying lines this pinned file cannot receive?
+ *
+ * TRUE only for a FRAMEWORK pin ({@link pinClassOf}, so a shipped path this
+ * module's prefix list forgot still counts) in state `drifts` with
+ * `onlyUpstream > 0`. A
+ * `local-only` file strands nothing (upstream ships nothing there), an
+ * `identical` one is an idle entry, and an `upstream-only` one was never taken
+ * in the first place — none of those can hide a fix.
+ *
+ * @param {{path?:string, state?:string, onlyUpstream?:number}} file
+ */
+export function isStranded(file) {
+  if (!file || typeof file !== "object") return false;
+  if (file.state !== "drifts") return false;
+  if (!(Number(file.onlyUpstream) > 0)) return false;
+  return pinClassOf(file) === "framework";
+}
+
+/** How many `worst` entries the summary ever carries. A beat is not a log. */
+export const WORST_LIMIT = 3;
+/** Longest path the summary carries; a path is a path, not prose. */
+export const PATH_MAX = 120;
+
+/**
+ * Fold a `.maestro/ignored-drift.json` report into the bounded shape the
+ * presence beat and the upgrade warning both read.
+ *
+ * ── THE THREE ANSWERS, AND WHY "UNKNOWN" IS ONE OF THEM ─────────────────────
+ * A reader must be able to tell "this seat has no pins" from "this seat could
+ * not tell me". They are opposite instructions — the first is nothing to do,
+ * the second is go and look — and collapsing them is the failure the whole
+ * drift report already suffered from once. So:
+ *
+ *   null              the seat pins NOTHING. No field, no alert (and the
+ *                     caller is expected to drop the key entirely).
+ *   {unknown:true}    the seat HAS pins and the report could not be read.
+ *                     Never reads as clean.
+ *   a summary         counts, and the worst few paths.
+ *
+ * `pinCount` is what the caller counted in `.maestroignore` itself — the only
+ * evidence that pins exist when the report is missing. Pass `null` when even
+ * that could not be read, and the answer is `unknown` as well: an unreadable
+ * `.maestroignore` on a seat is not proof of an empty one.
+ *
+ * ── TWO COUNTS, TWO NAMES ───────────────────────────────────────────────────
+ * `patterns` and `matched` are different numbers and this shape used to call
+ * both of them `pins`, which made the field mean one thing on the unknown
+ * branch (pattern lines in `.maestroignore`) and another on the readable one
+ * (files the report covers). Measured: a seat with a 5-pattern `.maestroignore`
+ * matching 2 real files reported `pins: 2` when its report was readable and
+ * `pins: 5` when it was not, under one label, to a human. A glob is not a file
+ * and three patterns that match nothing are worth SEEING — so:
+ *
+ *   patterns  non-comment lines in `.maestroignore`; `null` if unreadable.
+ *   matched   entries the drift report carries; `null` under `unknown`.
+ *
+ * Both are present on both branches, so no reader has to know which branch it
+ * is on to know which number it is holding.
+ *
+ * @param {object|null} report  parsed `.maestro/ignored-drift.json`, or null
+ * @param {{pinCount?:number|null, limit?:number}} [opt]
+ * @returns {{unknown:true, patterns:number|null, matched:null, reason:string}
+ *          | {patterns:number|null, matched:number, framework:number,
+ *             seatOwned:number, drifting:number, stranded:number,
+ *             strandedCode:number, localOnly:number,
+ *             worst:Array<{path:string, behind:number, code:boolean}>,
+ *             at:string|null, sdkVersion:string|null}
+ *          | null}
+ */
+export function summarisePinnedDrift(report, opt = {}) {
+  const pinCount = opt.pinCount === undefined ? null : opt.pinCount;
+  const limit = Number.isInteger(opt.limit) && opt.limit > 0 ? opt.limit : WORST_LIMIT;
+
+  const files =
+    report && typeof report === "object" && Array.isArray(report.files)
+      ? report.files.filter((f) => f && typeof f === "object" && typeof f.path === "string")
+      : null;
+
+  if (files === null) {
+    // No readable report. Whether that is "nothing to report" or "could not
+    // tell" is decided by `.maestroignore`, which the caller counted.
+    if (pinCount === 0) return null;
+    return {
+      unknown: true,
+      patterns: typeof pinCount === "number" ? pinCount : null,
+      matched: null,
+      reason:
+        pinCount === null
+          ? "neither .maestroignore nor .maestro/ignored-drift.json could be read"
+          : ".maestro/ignored-drift.json is missing or unreadable — run `maestro upgrade` to write it",
+    };
+  }
+
+  if (files.length === 0 && (pinCount === null || pinCount === 0)) return null;
+
+  let framework = 0;
+  let seatOwned = 0;
+  let drifting = 0;
+  let stranded = 0;
+  let strandedCode = 0;
+  let localOnly = 0;
+  const worstAll = [];
+  for (const f of files) {
+    const cls = pinClassOf(f);
+    if (cls === "framework") framework += 1;
+    else if (cls === "seat") seatOwned += 1;
+    if (f.state === "local-only") localOnly += 1;
+    if (f.state === "drifts" && cls === "framework") drifting += 1;
+    if (isStranded(f)) {
+      stranded += 1;
+      const code = isCodePin(f.path);
+      if (code) strandedCode += 1;
+      worstAll.push({
+        path: String(f.path).slice(0, PATH_MAX),
+        behind: Math.floor(Number(f.onlyUpstream)),
+        code,
+      });
+    }
+  }
+
+  // Worst = most upstream lines refused. Code before prose on a tie, because a
+  // stranded `.mjs` is an import-time death and a stranded `.md` is a stale
+  // sentence; path last so the list is stable across runs.
+  worstAll.sort(
+    (a, b) =>
+      b.behind - a.behind ||
+      Number(b.code) - Number(a.code) ||
+      a.path.localeCompare(b.path)
+  );
+
+  return {
+    patterns: typeof pinCount === "number" ? pinCount : null,
+    matched: files.length,
+    framework,
+    seatOwned,
+    drifting,
+    stranded,
+    strandedCode,
+    localOnly,
+    worst: worstAll.slice(0, limit),
+    at: typeof report.at === "string" ? report.at : null,
+    sdkVersion: typeof report.sdkVersion === "string" ? report.sdkVersion : null,
+  };
+}
+
+/** Did this summary find a fix that cannot land? */
+export function isStrandedSummary(summary) {
+  return Boolean(summary) && summary.unknown !== true && summary.stranded > 0;
+}
+
+/**
+ * The loud, specific warning `maestro upgrade` prints last.
+ *
+ * Three obligations, each of which a shorter message failed at least once:
+ *
+ *  1. NAME THE FILE AND THE DISTANCE. "14 ignored (.maestroignore protected)"
+ *     is what the summary said for months while two seats crash-looped. A
+ *     count is not an instruction.
+ *  2. GIVE THE EXACT REMEDY, runnable. The diff command against the installed
+ *     package is the whole fix, and nobody composes it from memory.
+ *  3. SAY WHAT MUST NOT BE UNPINNED. The obvious response to a scary drift
+ *     warning is to empty `.maestroignore`, which deletes the seat's own
+ *     forks along with the rotten ones. `config/`, `CLAUDE.md`, `knowledge/`
+ *     and `memory/` are never shipped by upgrade and must stay pinned.
+ *
+ * Returns LINES, not a printed block, so the caller owns colour and the test
+ * can read the words.
+ *
+ * @param {object|null} summary  {@link summarisePinnedDrift}'s output
+ * @param {{pkg?:string}} [opt]  installed package root for the diff hint
+ * @returns {string[]}
+ */
+export function formatPinnedDriftWarning(summary, opt = {}) {
+  if (!summary) return [];
+  const pkg = opt.pkg || "node_modules/@cohortapp/agent-sdk";
+  const out = [];
+
+  if (summary.unknown === true) {
+    out.push(
+      `.maestroignore pins ${summary.patterns === null ? "files" : `${summary.patterns} pattern${summary.patterns === 1 ? "" : "s"}`} and their drift could not be read — ${summary.reason}.`
+    );
+    out.push(
+      "  Until it can be read, treat every pinned framework file as possibly stranding an upstream fix."
+    );
+    return out;
+  }
+
+  if (summary.stranded === 0) {
+    // Not silence: the operator asked for the report by having pins at all,
+    // and "your pins are currently stranding nothing" is the sentence that
+    // makes the loud version believable when it does arrive.
+    if (summary.framework > 0) {
+      out.push(
+        `${summary.framework} pinned framework file${summary.framework === 1 ? "" : "s"}, none stranding an upstream line. Nothing to port.`
+      );
+    }
+    return out;
+  }
+
+  const n = summary.stranded;
+  out.push(
+    `${n} PINNED FRAMEWORK FILE${n === 1 ? "" : "S"} ${n === 1 ? "IS" : "ARE"} STRANDING UPSTREAM FIXES — .maestroignore refuses them, so no release can ever reach ${n === 1 ? "it" : "them"}:`
+  );
+  for (const f of summary.worst) {
+    out.push(
+      `    ~ ${f.path} — ${f.behind} upstream line${f.behind === 1 ? "" : "s"} refused${f.code ? " (code: this is how a seat dies at import time)" : ""}`
+    );
+  }
+  if (n > summary.worst.length) {
+    out.push(`    … and ${n - summary.worst.length} more in ${IGNORED_DRIFT_HINT}`);
+  }
+  out.push("  Remedy, per file:");
+  out.push(`    diff -u ${pkg}/<path> <path>   # what this seat is refusing`);
+  out.push("    …port the upstream change in, then keep the pin; or delete the");
+  out.push("    entry from .maestroignore and let the next upgrade take the file.");
+  out.push(
+    "  Do NOT empty .maestroignore to clear this. config/, CLAUDE.md, knowledge/"
+  );
+  out.push(
+    "  and memory/ are never shipped by upgrade — pinning them costs nothing and"
+  );
+  out.push("  should stay. Only a pin on a FRAMEWORK path can rot.");
+  if (summary.localOnly > 0) {
+    out.push(
+      `  (${summary.localOnly} pinned path${summary.localOnly === 1 ? " is" : "s are"} local-only — upstream ships nothing there, so ${summary.localOnly === 1 ? "it strands" : "they strand"} nothing. Different thing; leave ${summary.localOnly === 1 ? "it" : "them"} alone.)`
+    );
+  }
+  return out;
+}
+
+/**
+ * Count real pattern lines in a `.maestroignore`. Comments and blanks are not
+ * pins; a file of nothing but comments pins nothing, which must read as `0`
+ * (no field) and not as `unknown`.
+ *
+ * @param {string|null} text  file contents, or null when it could not be read
+ * @returns {number|null}
+ */
+export function countPins(text) {
+  if (typeof text !== "string") return null;
+  let n = 0;
+  for (const raw of text.split("\n")) {
+    const line = raw.trim();
+    if (line === "" || line.startsWith("#")) continue;
+    n += 1;
+  }
+  return n;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cohortapp/agent-sdk",
-  "version": "2.18.12",
+  "version": "2.18.14",
   "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": {

package/plugins/maestro-skills/skills/persona-discipline.md

@@ -37,11 +37,33 @@ actor is needed, it is a person-shaped one: team, colleague, analyst.
 
 ## Being straight about what you are
 
+**Never open a message by announcing what you are.** No standing identity
+line in any shape: nothing that pairs your name with your own nature, nothing
+that pairs it with the person you work for, no throat-clearing preamble whose
+only job is to flag what you are before you say anything. Not on your first
+post in a channel, not mid-thread, not on a correction to your own figures.
+Cohort marks every AI member on every surface it has: the member row, the
+directory, the mailbox list, the message header. A colleague reading you has
+already seen it. The sentence tells them nothing new and reads as you
+disclaiming your own work before you have said anything.
+
+The renderings of that line live in `policies/ai-disclosure.yaml` as
+`channels.<c>.identity_line`, scoped to an external first contact. They are
+deliberately not reproduced here, or anywhere else in this tree: a banned
+string quoted as an example is how the next author reads it in good faith and
+writes it back into the product. This file is loaded into a live session's
+context, so it is one of the places that would happen from.
+
 If someone sincerely asks whether they are dealing with an AI, say yes,
 plainly, once, and carry on. That is an honest answer to a direct question,
 not a disclaimer to attach to your work, and it does not license naming the
-machinery. `policies/ai-disclosure.yaml` says where proactive disclosure is
-required.
+machinery. The two rules are one rule: **honest when asked, silent when not.**
+
+Proactive disclosure is owed in exactly one place — an EXTERNAL first contact
+— and it is not yours to decide. `policies/ai-disclosure.yaml` scopes it
+(`posture.internal_recipients_exempt`, `channels.<c>.identity_scope`) and the
+send-gate applies it. Inside your own workspace the duty does not arise, so
+volunteering the line there is not caution; it is noise.
 
 ## When the send gate blocks you