@cohortapp/agent-sdk 2.18.13 → 2.18.15

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.13",
+  "version": "2.18.15",
   "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/scaffold/config/alerts.yaml

@@ -15,6 +15,13 @@ alerts:
     # Cost guardrails (USD).
     costPerSessionP99USD: 2.50  # p99 session cost over the daily ledger
     dailySpendWarnUSD: 20       # soft warn before the hard budget cap
+    # A cadence failed for a cause that retrying cannot fix — its prompt file is
+    # missing or unreadable. Fires at ONE: a permanent failure means a scheduled
+    # obligation has stopped and will not restart until a person puts the file
+    # back. (Nested form, matching the built-in defaults.)
+    cadencePermanentFailure:
+      warnCount: 1
+      critCount: 3
     # Liveness (seconds).
     absentAgentSec: 900         # a peer with no heartbeat in 15min
     daemonHealthStaleSec: 180   # daemon health.json older than 3min

package/scripts/ci/check-cadence-prompts-exist.mjs

@@ -0,0 +1,96 @@
+/**
+ * check-cadence-prompts-exist.mjs — every built-in cadence's prompt file is on disk.
+ *
+ * WHY THIS GUARD EXISTS. On 2026-09-24 Eli Rosenberg's seat scheduled the
+ * cadence `commitment-sweep` with `prompt: schedules/triggers/commitment-sweep.md`,
+ * and that file was not there. The consumer never checked: the handoff renderer
+ * threw ENOENT, the catch fell through to the spawn — which opens the same path
+ * — and the tick went back on the bus. Measured at 16 requeues per 30 seconds,
+ * indefinitely, until an emergency stop halted the whole seat to contain it.
+ *
+ * Two fixes, and this is the cheap half. The runtime half is
+ * `lib/cadence-failure-class.mjs` + the consumer's `failPermanently`: a failure
+ * whose cause cannot change by waiting stops, records itself and alerts,
+ * instead of retrying at poll speed. But a cadence the FRAMEWORK ships should
+ * never reach that path at all — its prompt is a file in this repo, so its
+ * absence is a build-time fact, and a build-time fact belongs in a check rather
+ * than in a seat's log at 3 a.m.
+ *
+ * Scope, stated honestly: this guard covers the hardcoded CADENCE_REGISTRY in
+ * `scripts/daemon/cadence-handlers.mjs` — the cadences every seat gets. It
+ * CANNOT cover a seat's `config/.cadence-registry.json` (written by the plan
+ * compiler on the seat, naming prompts the seat is meant to author), which is
+ * exactly where Eli's came from. That case is the runtime half's job.
+ *
+ * Usage (standalone): `node scripts/ci/check-cadence-prompts-exist.mjs`
+ *   exit 0 → every registry prompt resolves; exit 1 → one is missing.
+ *
+ * @module scripts/ci/check-cadence-prompts-exist
+ */
+
+"use strict";
+
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Repo root: two levels up from scripts/ci/. @type {string} */
+const REPO_ROOT = path.resolve(fileURLToPath(new URL(".", import.meta.url)), "..", "..");
+
+/**
+ * Check every hardcoded cadence definition that names a prompt.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.cwd=REPO_ROOT]
+ * @param {object} [opts.registry]  pre-supplied registry (skips the import)
+ * @returns {Promise<{ok:boolean, checked:number, missing:Array<{cadence:string, prompt:string, resolved:string}>}>}
+ */
+export async function checkCadencePromptsExist(opts = {}) {
+  const cwd = opts.cwd || REPO_ROOT;
+  let registry = opts.registry;
+  if (!registry) {
+    const mod = await import(path.join(cwd, "scripts/daemon/cadence-handlers.mjs"));
+    registry = mod.CADENCE_REGISTRY || {};
+  }
+  const missing = [];
+  let checked = 0;
+  for (const [cadence, def] of Object.entries(registry)) {
+    const prompt = def && typeof def.prompt === "string" ? def.prompt : null;
+    if (!prompt) continue; // inline/guarded-only cadences have no prompt to ship
+    checked++;
+    const resolved = path.resolve(cwd, prompt);
+    if (!existsSync(resolved)) missing.push({ cadence, prompt, resolved });
+  }
+  return { ok: missing.length === 0, checked, missing };
+}
+
+/**
+ * Run the check and print a human report.
+ * @param {string} [cwd=REPO_ROOT]
+ * @returns {Promise<number>} 0 = ok, 1 = a prompt is missing
+ */
+export async function run(cwd = REPO_ROOT) {
+  const { ok, checked, missing } = await checkCadencePromptsExist({ cwd });
+  if (ok) {
+    console.log(`check-cadence-prompts-exist: OK (${checked} built-in cadence prompt(s) on disk)`);
+    return 0;
+  }
+  console.error("check-cadence-prompts-exist: FAIL — a shipped cadence names a prompt that is not in the repo:");
+  for (const m of missing) {
+    console.error(`  ${m.cadence} → "${m.prompt}"  (not found: ${m.resolved})`);
+  }
+  console.error(
+    `check-cadence-prompts-exist: ${missing.length} missing of ${checked} checked. ` +
+    "On a seat this is not a log line — it is a cadence that stops, loudly, every time it is due."
+  );
+  return 1;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  run()
+    .then((code) => process.exit(code))
+    .catch((err) => {
+      console.error("check-cadence-prompts-exist: ERROR", err && err.message ? err.message : err);
+      process.exit(2);
+    });
+}

package/scripts/ci/check.mjs

@@ -22,6 +22,7 @@
  *   - check-subagent-frontmatter: every agents/*.md passes the registry validator
  *   - check-durable-write-seam  : durable JSON writes under lib/ go through fs-atomic
  *   - check-skill-packs         : vendored design skill packs match their pinned manifests
+ *   - check-cadence-prompts-exist : every built-in cadence's prompt file is on disk
  *
  * Usage: `node scripts/ci/check.mjs`
  *   exit 0 → all checks passed; exit 1 → one or more failed.
@@ -42,6 +43,7 @@ import { run as runDocsAccuracy } from "./check-docs-accuracy.mjs";
 import { run as runSubagentFrontmatter } from "./check-subagent-frontmatter.mjs";
 import { run as runDurableWriteSeam } from "./check-durable-write-seam.mjs";
 import { run as runSkillPacks } from "./check-skill-packs.mjs";
+import { run as runCadencePrompts } from "./check-cadence-prompts-exist.mjs";
 
 /**
  * The ordered list of guards this aggregator runs.
@@ -60,6 +62,7 @@ export const CHECKS = [
   { name: "check-subagent-frontmatter", run: runSubagentFrontmatter },
   { name: "check-durable-write-seam", run: runDurableWriteSeam },
   { name: "check-skill-packs", run: runSkillPacks },
+  { name: "check-cadence-prompts-exist", run: runCadencePrompts },
 ];
 
 /**