pan-wizard 3.34.0 → 3.36.0

package/scripts/mutation-probe.cjs

@@ -51,86 +51,13 @@ const TARGETS = [
   { file: 'pan-wizard-core/bin/pan-tools.cjs', tests: ['tests/dispatcher.test.cjs', 'tests/dispatcher-arms.test.cjs'] },
 ];
 
-/**
- * The mutation operators. Each is a plain textual swap with a token that must appear
- * OUTSIDE a string or comment to be worth mutating (see mutableLine). They are deliberately
- * few and blunt: the point is to find unconstrained logic, not to enumerate every possible
- * defect.
- */
-const OPERATORS = [
-  { id: 'gte→gt', find: ' >= ', replace: ' > ' },
-  { id: 'gt→gte', find: ' > ', replace: ' >= ' },
-  { id: 'lte→lt', find: ' <= ', replace: ' < ' },
-  { id: 'lt→lte', find: ' < ', replace: ' <= ' },
-  { id: 'eq→neq', find: ' === ', replace: ' !== ' },
-  { id: 'neq→eq', find: ' !== ', replace: ' === ' },
-  { id: 'and→or', find: ' && ', replace: ' || ' },
-  { id: 'or→and', find: ' || ', replace: ' && ' },
-  { id: 'true→false', find: 'return true', replace: 'return false' },
-  { id: 'false→true', find: 'return false', replace: 'return true' },
-  { id: 'plus→minus', find: ' + 1', replace: ' - 1' },
-];
-
-/**
- * Is this line worth mutating? Skips comments, and skips a line whose only occurrence of
- * the token is inside a string literal — mutating a message changes nothing a test should
- * be pinning, and a survivor there would be noise.
- *
- * Crude but conservative: a line containing a quote is only mutated when the token also
- * occurs before the first quote.
- */
-function mutableLine(line, token) {
-  const trimmed = line.trim();
-  if (!trimmed || trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*')) return false;
-  const at = line.indexOf(token);
-  if (at === -1) return false;
-  const firstQuote = Math.min(
-    ...["'", '"', '`'].map((q) => { const i = line.indexOf(q); return i === -1 ? Infinity : i; }),
-  );
-  return at < firstQuote;
-}
-
-/**
- * Every mutation available in a source file: one per (line, operator) pair, first
- * occurrence on the line.
- *
- * @returns {Array<{line: number, op: string, before: string, after: string}>}
- */
-function mutationsFor(src) {
-  const lines = src.split(/\r?\n/);
-  const out = [];
-  lines.forEach((line, i) => {
-    for (const op of OPERATORS) {
-      if (!mutableLine(line, op.find)) continue;
-      out.push({ line: i + 1, op: op.id, before: line, after: line.replace(op.find, op.replace) });
-    }
-  });
-  return out;
-}
-
-/** Apply one mutation to a source string, by line number. Throws if the line moved. */
-function applyMutation(src, mutation) {
-  const eol = src.includes('\r\n') ? '\r\n' : '\n';
-  const lines = src.split(/\r?\n/);
-  const idx = mutation.line - 1;
-  if (lines[idx] !== mutation.before) {
-    throw new Error(`line ${mutation.line} is not what the mutation was built from`);
-  }
-  lines[idx] = mutation.after;
-  return lines.join(eol);
-}
-
-/** Deterministic shuffle, so a run is reproducible from its seed. */
-function sample(items, n, seed) {
-  let s = seed >>> 0;
-  const rand = () => { s = (s * 1664525 + 1013904223) >>> 0; return s / 0x100000000; };
-  const copy = items.slice();
-  for (let i = copy.length - 1; i > 0; i--) {
-    const j = Math.floor(rand() * (i + 1));
-    [copy[i], copy[j]] = [copy[j], copy[i]];
-  }
-  return copy.slice(0, n);
-}
+// The operators, the line filter, mutation and the seeded sample live in the shipped
+// mutation report (pan-wizard-core/bin/lib/mutate.cjs, program V5), which a user's phase
+// diff is measured with; this probe applies the JavaScript table to PAN itself.
+const M = require('../pan-wizard-core/bin/lib/mutate.cjs');
+const OPERATORS = M.OPERATORS.js;
+const { mutableLine, applyMutation, sample } = M;
+const mutationsFor = (src) => M.mutationsFor(src, { family: 'js' });
 
 function parseArgs(argv) {
   const a = { max: 20, seed: 1, json: false, targets: [], timeoutMs: 600000, help: false };

package/scripts/prompt-lint.cjs

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * Prompt-contract lint (program L2): the contract a shipped prompt has with the
+ * engine and the host, checked in code. Applied to commands/pan, agents and
+ * pan-wizard-core/workflows by tests/prompt-lint.test.cjs, with
+ * tests/fixtures/prompt-lint-allowlist.json (every entry names its reason, usually
+ * the plan item that fixes it).
+ *
+ *   unknown-verb        a `pan-tools <verb> [<sub>]` call naming a verb or a subcommand
+ *                       the engine does not have (tests/fixtures/surface.json)
+ *   tool-not-granted    an agent told to use a tool its frontmatter `tools:` does not grant
+ *   pasted-source       an @-include of engine source (`*.cjs` / `*.js`) into a prompt
+ *   oversized-question  an AskUserQuestion block offering more than four options (the
+ *                       host's limit: two to four)
+ *   untyped-spawn       a Task( spawn without `model=`, or a general-purpose spawn told
+ *                       to read a role file instead of naming the agent type
+ *   dev-skill           a shipped prompt sending the user to a dev-only skill of this
+ *                       repository (.claude/commands/*.md), which no install carries
+ *
+ *   node scripts/prompt-lint.cjs            # report the current tree, exit 1 on a finding
+ */
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+const TOOLS = ['Write', 'Edit', 'WebSearch', 'WebFetch', 'Task'];
+
+function surface(root = ROOT) {
+  const s = JSON.parse(fs.readFileSync(path.join(root, 'tests', 'fixtures', 'surface.json'), 'utf8'));
+  const subs = new Map();
+  for (const entry of s.subcommands) {
+    const [verb, sub] = entry.split(' ');
+    if (!subs.has(verb)) subs.set(verb, new Set());
+    subs.get(verb).add(sub);
+  }
+  return { verbs: new Set(s.verbs), subs };
+}
+
+function devSkills(root = ROOT) {
+  try {
+    return fs.readdirSync(path.join(root, '.claude', 'commands')).filter((f) => f.endsWith('.md')).map((f) => f.replace(/\.md$/, ''));
+  } catch { return []; }
+}
+
+const lineOf = (text, index) => text.slice(0, index).split('\n').length;
+
+function frontmatterTools(text) {
+  const fm = text.match(/^---\n([\s\S]*?)\n---/);
+  if (!fm) return null;
+  const m = fm[1].match(/^tools:[ \t]*(.+)$/m);
+  return m ? new Set(m[1].split(',').map((t) => t.trim().replace(/\*$/, '')).filter(Boolean)) : null;
+}
+
+/**
+ * Lint one file's text.
+ * @param {string} rel - repository-relative path (decides which rules apply)
+ * @param {string} raw - file content
+ * @param {{verbs: Set, subs: Map, dev: string[]}} ctx
+ * @returns {Array<{rule, file, line, text}>}
+ */
+function lintText(rel, raw, ctx) {
+  const text = raw.replace(/\r\n/g, '\n');
+  const out = [];
+  const hit = (rule, index, snippet) => out.push({ rule, file: rel, line: lineOf(text, index), text: String(snippet).trim().slice(0, 140) });
+
+  // unknown-verb
+  // An invocation, not prose: the script path (`pan-tools.cjs <verb>`) or a backticked `pan-tools <verb>`.
+  const callRe = /(?:pan-tools\.cjs"?|`pan-tools)[ \t]+([a-z][a-z0-9-]*)(?:[ \t]+([a-z][a-z0-9-]*))?/g;
+  let m;
+  while ((m = callRe.exec(text))) {
+    const [, verb, sub] = m;
+    if (!ctx.verbs.has(verb)) { hit('unknown-verb', m.index, m[0]); continue; }
+    const known = ctx.subs.get(verb);
+    if (known && sub && !known.has(sub) && !ctx.verbs.has(sub)) hit('unknown-verb', m.index, m[0]);
+  }
+
+  // pasted-source
+  const incRe = /^@\S+\.(?:cjs|mjs|js)\s*$/gm;
+  while ((m = incRe.exec(text))) hit('pasted-source', m.index, m[0]);
+
+  // tool-not-granted (agents only)
+  if (rel.startsWith('agents/')) {
+    const granted = frontmatterTools(text);
+    if (granted) {
+      for (const tool of TOOLS) {
+        if (granted.has(tool)) continue;
+        const re = new RegExp(`\\b(?:use|using|with|via|call|run)\\s+(?:the\\s+)?\`?${tool}\`?(?:\\s+tool)?\\b|\\bthe\\s+\`?${tool}\`?\\s+tool\\b`, 'g');
+        let mm;
+        while ((mm = re.exec(text))) {
+          // "Never use Edit or Write tools" is the rule being kept, not broken.
+          const before = text.slice(Math.max(0, mm.index - 24), mm.index).toLowerCase();
+          if (/\b(never|not|don't|do not|no)\s*$/.test(before)) continue;
+          hit('tool-not-granted', mm.index, `${tool} (granted: ${[...granted].join(', ')}): ${mm[0]}`);
+          break;
+        }
+      }
+    }
+  }
+
+  // oversized-question
+  const askRe = /AskUserQuestion/g;
+  while ((m = askRe.exec(text))) {
+    const window = text.slice(m.index, m.index + 6000);
+    const optRe = /options\s*:\s*\[/g;
+    let o;
+    while ((o = optRe.exec(window))) {
+      let depth = 0;
+      let end = -1;
+      for (let i = o.index + o[0].length - 1; i < window.length; i++) {
+        if (window[i] === '[') depth++;
+        else if (window[i] === ']') { depth--; if (depth === 0) { end = i; break; } }
+      }
+      if (end < 0) break;
+      const labels = (window.slice(o.index, end).match(/\blabel\s*:/g) || []).length;
+      if (labels > 4) hit('oversized-question', m.index + o.index, `${labels} options in one question`);
+      optRe.lastIndex = end;
+    }
+    askRe.lastIndex = m.index + 1;
+  }
+
+  // untyped-spawn (workflows and commands)
+  if (!rel.startsWith('agents/')) {
+    const lines = text.split('\n');
+    lines.forEach((l, i) => {
+      if (!/^\s*Task\(/.test(l)) return;
+      let j = i;
+      while (j < lines.length - 1 && !/^\s*\)\s*$/.test(lines[j]) && !/description="[^"]*"\s*\)\s*$/.test(lines[j])) j++;
+      const block = lines.slice(i, j + 1).join('\n');
+      const at = lines.slice(0, i).join('\n').length + 1;
+      if (!/\bmodel\s*=/.test(block)) hit('untyped-spawn', at, 'a Task( spawn without model=');
+      else if (/subagent_type="general-purpose"/.test(block) && /agents\/pan-[a-z-]+\.md for your role/.test(block)) hit('untyped-spawn', at, 'general-purpose spawn told to read a role file');
+    });
+  }
+
+  // dev-skill
+  if (ctx.dev.length) {
+    // Every regex metacharacter escaped, backslash included (inline: CodeQL does not follow a helper).
+    const names = ctx.dev.map((d) => d.replace(/[.*+?^${}()|[\]\\-]/g, '\\$&'));
+    const devRe = new RegExp(`(^|[\\s\`'"(])/(${names.join('|')})(?=[\\s\`'".,;:)]|$)`, 'gm');
+    while ((m = devRe.exec(text))) hit('dev-skill', m.index + m[1].length, m[0]);
+  }
+  return out;
+}
+
+/** The shipped prompt files, repository-relative. */
+function shippedPrompts(root = ROOT) {
+  const list = [];
+  for (const dir of ['commands/pan', 'agents', 'pan-wizard-core/workflows']) {
+    for (const f of fs.readdirSync(path.join(root, dir)).filter((x) => x.endsWith('.md')).sort()) list.push(`${dir}/${f}`);
+  }
+  return list;
+}
+
+function lintTree(root = ROOT) {
+  const ctx = { ...surface(root), dev: devSkills(root) };
+  return shippedPrompts(root).flatMap((rel) => lintText(rel, fs.readFileSync(path.join(root, rel), 'utf8'), ctx));
+}
+
+if (require.main === module) {
+  const findings = lintTree();
+  for (const f of findings) process.stdout.write(`${f.rule} ${f.file}:${f.line} — ${f.text}\n`);
+  process.stdout.write(`${findings.length} finding(s)\n`);
+  process.exitCode = findings.length ? 1 : 0;
+}
+
+module.exports = { lintText, lintTree, shippedPrompts, surface, devSkills, frontmatterTools };

package/scripts/test-surface.cjs

@@ -19,7 +19,9 @@
  * Modes:
  *   node scripts/test-surface.cjs            summary
  *   node scripts/test-surface.cjs --write    write tests/fixtures/surface.json (the committed registry)
- *   node scripts/test-surface.cjs --check    exit 1 when the committed registry differs from the code
+ *   node scripts/test-surface.cjs --check    exit 1 when the committed registry differs from the code, or
+ *                                            a command, agent, verb or config key has no user (liveness, L1)
+ *   node scripts/test-surface.cjs --liveness who uses each command, agent, verb, subcommand and config key
  *   node scripts/test-surface.cjs --map      which test files reference each surface row; lists the misses
  *   node scripts/test-surface.cjs --scaffold <dir>   one todo stub per unreferenced row (for a suite rebuilt from scratch)
  *
@@ -65,6 +67,7 @@ const EXTRA_HOOK_ROWS = Object.freeze([
 ]);
 const EVENT_HOOKS = Object.freeze({
   sessionStart: ['pan-check-update.js'],
+  preToolUse: ['pan-guard.js'],
   postToolUse: ['pan-context-monitor.js'],
   subagentStop: ['pan-cost-logger.js', 'pan-trace-logger.js'],
   stop: ['pan-stop-guard.js'],
@@ -296,6 +299,153 @@ function scaffold(missingRows, outDir) {
 
 function readJson(p) { return JSON.parse(fs.readFileSync(p, 'utf8')); }
 
+// ─── Liveness (program L1) ──────────────────────────────────────────────────
+//
+// The map above asks "does a test name it?". Liveness asks "does anything USE it?":
+//   - every shipped command and agent is named by a harness scenario, so some behavioural
+//     run exercises it as a user would;
+//   - every pan-tools verb and subcommand has a caller in what PAN ships: a prompt
+//     (commands, agents, workflows, references, templates), a native workflow's prompt
+//     (bin/install-lib.cjs), or an MCP tool or resource (the bridge registry);
+//   - every config default has a reader: code under the core, hooks, installer or MCP
+//     bridge that reads the key, or a shipped prompt that runs `config-get <key>`.
+// An orphan either gains a user or sits in tests/fixtures/liveness-allowlist.json with a
+// reason; `--check` fails on an orphan without one, and on an entry no longer needed.
+
+const LIVENESS_ALLOWLIST_REL = path.join('tests', 'fixtures', 'liveness-allowlist.json');
+const PROMPT_DIRS = Object.freeze(['commands/pan', 'agents', 'pan-wizard-core/workflows', 'pan-wizard-core/references', 'pan-wizard-core/templates']);
+const NATIVE_WORKFLOW_SOURCES = Object.freeze(['bin/install-lib.cjs']);
+const READER_DIRS = Object.freeze(['pan-wizard-core/bin', 'pan-wizard-core/mcp', 'pan-wizard-core/opencode', 'hooks', 'bin']);
+const SCENARIO_DIR = 'harness/scenarios';
+
+/** Every file under rel (recursively) whose name matches re, as posix paths; skips dist/ and node_modules/. */
+function walkFiles(root, rel, re) {
+  const out = [];
+  const walk = (r) => {
+    let ents;
+    try { ents = fs.readdirSync(path.join(root, r), { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      const p = path.posix.join(r, e.name);
+      if (e.isDirectory()) { if (e.name !== 'dist' && e.name !== 'node_modules') walk(p); } else if (re.test(e.name)) out.push(p);
+    }
+  };
+  walk(rel);
+  return out.sort();
+}
+
+/**
+ * The verbs and `verb sub` pairs a text invokes: the script path (`pan-tools.cjs <verb>`),
+ * a backticked `pan-tools <verb>`, or `pan-tools <verb>` as a shell command (opening a
+ * line, or after `|`, `;`, `&` or `(`), then the verb and an optional subcommand. Prose
+ * that mentions pan-tools is not a call.
+ */
+function pantoolsCalls(text) {
+  const out = new Set();
+  const re = /(?:pan-tools\.cjs["']?|`pan-tools|(?:^|[|;&(])[ \t]*pan-tools)[ \t]+([a-z][a-z0-9-]*)(?:[ \t]+([a-z][a-z0-9-]*))?/gm;
+  let m;
+  while ((m = re.exec(text))) { out.add(m[1]); if (m[2]) out.add(`${m[1]} ${m[2]}`); }
+  return out;
+}
+
+/** The text a liveness check reads, from the tree. Tests pass a hand-built object instead. */
+function loadLivenessInputs(root = ROOT) {
+  const read = (rel) => fs.readFileSync(path.join(root, rel), 'utf8');
+  const prompts = PROMPT_DIRS.flatMap((d) => walkFiles(root, d, /\.(md|js)$/)).map((file) => ({ file, src: read(file) }));
+  const native = NATIVE_WORKFLOW_SOURCES.filter((f) => fs.existsSync(path.join(root, f))).map((file) => ({ file, src: read(file) }));
+  const registry = require(path.join(root, SOURCES.mcpRegistry));
+  const mcp = [...(registry.TOOLS || []), ...(registry.RESOURCES || [])].map((t) => ({ name: t.name || t.uri, verb: t.verb, sub: (t.args && t.args[0]) || null }));
+  const scenarios = walkFiles(root, SCENARIO_DIR, /\.json$/).map((file) => ({ file, src: read(file) }));
+  const configSrc = path.posix.normalize(SOURCES.config);
+  const readers = READER_DIRS.flatMap((d) => walkFiles(root, d, /\.(c?js|mjs)$/)).map((file) => ({ file, src: read(file), isConfig: file === configSrc }));
+  return { prompts, native, mcp, scenarios, readers };
+}
+
+/** The body of buildConfigDefaults in config.cjs: where defaults are written, which is not a read. */
+function stripDefaultsBuilder(src) {
+  const start = src.indexOf('function buildConfigDefaults');
+  if (start === -1) return src;
+  const open = src.indexOf('{', start);
+  let depth = 0;
+  for (let i = open; i < src.length; i++) {
+    if (src[i] === '{') depth++;
+    else if (src[i] === '}' && --depth === 0) return src.slice(0, start) + src.slice(i + 1);
+  }
+  return src;
+}
+
+/**
+ * Who uses each piece of the surface. Pure over `surface` (extractSurface) and `inputs`
+ * (loadLivenessInputs). Returns one row per command, agent, verb, subcommand and config
+ * key: `{id, kind, users: string[]}`; a row with no users is an orphan.
+ */
+function liveness(surface, inputs) {
+  const rows = [];
+  const scen = inputs.scenarios;
+  const named = (re) => scen.filter((s) => re.test(s.src)).map((s) => s.file);
+  for (const f of surface.content['commands/pan'] || []) {
+    const name = f.replace(/\.md$/, '');
+    // /pan:<name> (Claude, Gemini), /pan-<name> or pan-<name> as a skill (Codex, Copilot, OpenCode), or the file itself.
+    rows.push({ id: `command:${name}`, kind: 'command', users: named(new RegExp(`(?:/pan[:-]|commands/pan/|\\bpan-)${esc(name)}(?![a-z0-9-])`)) });
+  }
+  for (const f of surface.content.agents || []) {
+    const name = f.replace(/\.md$/, '');
+    rows.push({ id: `agent:${name}`, kind: 'agent', users: named(new RegExp(`(?<![a-z0-9-])${esc(name)}(?![a-z0-9-])`)) });
+  }
+  const callers = new Map();
+  const add = (key, who) => { if (!callers.has(key)) callers.set(key, new Set()); callers.get(key).add(who); };
+  for (const t of [...inputs.prompts, ...inputs.native]) for (const c of pantoolsCalls(t.src)) add(c, t.file);
+  // A registry entry with no verb (one served by the bridge itself) calls nothing.
+  for (const t of inputs.mcp.filter((x) => x.verb)) { add(t.verb, `mcp:${t.name}`); if (t.sub) add(`${t.verb} ${t.sub}`, `mcp:${t.name}`); }
+  for (const v of surface.verbs) {
+    const direct = callers.get(v) || new Set();
+    // A verb is alive when it is called, bare or through any of its subcommands.
+    const viaSub = [...callers.entries()].filter(([k]) => k.startsWith(`${v} `)).flatMap(([, s]) => [...s]);
+    rows.push({ id: `caller:verb:${v}`, kind: 'verb', users: [...new Set([...direct, ...viaSub])].sort() });
+  }
+  for (const s of surface.subcommands) rows.push({ id: `caller:sub:${s}`, kind: 'sub', users: [...(callers.get(s) || [])].sort() });
+  const readerText = inputs.readers.map((r) => ({ file: r.file, src: r.isConfig ? stripDefaultsBuilder(r.src) : r.src }));
+  const promptText = [...inputs.prompts, ...inputs.native];
+  for (const key of surface.config_keys) {
+    const last = esc(key.split('.').pop());
+    const codeRe = new RegExp(`['"\`]${esc(key)}['"\`]|\\.${last}\\b|\\[['"]${last}['"]\\]|['"]${last}['"]`);
+    // A prompt reads a key with `config-get <key>`, or names the full dotted key in backticks
+    // for the agent to check in the config or the init payload (`workflow.x: true`).
+    const promptRe = new RegExp(`config-get[ \\t]+["']?${esc(key)}\\b|\`${esc(key)}[\`:= ]`);
+    const users = [...readerText.filter((r) => codeRe.test(r.src)).map((r) => r.file), ...promptText.filter((p) => promptRe.test(p.src)).map((p) => p.file)];
+    rows.push({ id: `reader:config:${key}`, kind: 'config', users: [...new Set(users)].sort() });
+  }
+  return rows;
+}
+
+/**
+ * Orphans not allowlisted, and allowlist entries that are wrong (no reason, no such row, or
+ * a row that has users now). `--check` fails when either list is non-empty.
+ */
+function livenessProblems(rows, allowlist) {
+  const allow = new Map(allowlist.map((a) => [a.id, a]));
+  const problems = [];
+  for (const a of allowlist) {
+    if (!a.reason || !String(a.reason).trim()) problems.push(`liveness allowlist entry ${a.id} has no reason`);
+    const row = rows.find((r) => r.id === a.id);
+    if (!row) problems.push(`liveness allowlist entry ${a.id} names nothing that exists — remove it`);
+    else if (row.users.length) problems.push(`liveness allowlist entry ${a.id} has a user now (${row.users[0]}) — remove the entry`);
+  }
+  const hint = { command: 'name it in a harness scenario', agent: 'name it in a harness scenario', verb: 'call it from a shipped prompt', sub: 'call it from a shipped prompt', config: 'read it in code, or drop the default' };
+  for (const r of rows) if (!r.users.length && !allow.has(r.id)) problems.push(`orphan ${r.id} — ${hint[r.kind]}, or allowlist it in ${LIVENESS_ALLOWLIST_REL} with a reason`);
+  return problems;
+}
+
+/** What `--check` decides: registry drift plus liveness problems. Pure. */
+function checkReport(committed, surface, inputs, allowlist) {
+  const drift = diffSurface(committed, surface);
+  const live = livenessProblems(liveness(surface, inputs), allowlist);
+  return { drift, live, ok: !drift.added.length && !drift.removed.length && !live.length };
+}
+
+function readLivenessAllowlist(root = ROOT) {
+  try { return readJson(path.join(root, LIVENESS_ALLOWLIST_REL)); } catch { return []; }
+}
+
 // ─── CLI ────────────────────────────────────────────────────────────────────
 
 function main(argv) {
@@ -309,13 +459,25 @@ function main(argv) {
   if (argv.includes('--check')) {
     let committed;
     try { committed = readJson(registryPath); } catch { console.error(`no committed registry at ${REGISTRY_REL} — run --write`); return 1; }
-    const d = diffSurface(committed, surface);
-    if (!d.added.length && !d.removed.length) { console.log('surface registry matches the code'); return 0; }
-    console.error(`surface registry is stale — run \`node scripts/test-surface.cjs --write\` and commit it`);
-    for (const x of d.added) console.error(`  + ${x}`);
-    for (const x of d.removed) console.error(`  - ${x}`);
+    const { drift: d, live, ok } = checkReport(committed, surface, loadLivenessInputs(ROOT), readLivenessAllowlist(ROOT));
+    if (ok) { console.log('surface registry matches the code; every command, agent, verb and config key is alive'); return 0; }
+    if (d.added.length || d.removed.length) {
+      console.error(`surface registry is stale — run \`node scripts/test-surface.cjs --write\` and commit it`);
+      for (const x of d.added) console.error(`  + ${x}`);
+      for (const x of d.removed) console.error(`  - ${x}`);
+    }
+    if (live.length) {
+      console.error('liveness: orphans without a user or an allowlist reason');
+      for (const x of live) console.error(`  ${x}`);
+    }
     return 1;
   }
+  if (argv.includes('--liveness')) {
+    const rows = liveness(surface, loadLivenessInputs(ROOT));
+    for (const r of rows) console.log(`${r.users.length ? 'ok    ' : 'ORPHAN'} ${r.id.padEnd(48)} ${r.users.slice(0, 2).join(', ')}${r.users.length > 2 ? ` +${r.users.length - 2}` : ''}`);
+    console.log(`liveness rows: ${rows.length} · orphans: ${rows.filter((r) => !r.users.length).length}`);
+    return 0;
+  }
   const rows = mapSurface(surfaceRows(surface), loadTestSources(ROOT));
   const missing = rows.filter((r) => !r.hits.length);
   if (argv.includes('--scaffold')) {
@@ -338,4 +500,5 @@ module.exports = {
   ROOT, REGISTRY_REL, ALLOWLIST_REL, SOURCES, EXTRA_HOOK_ROWS,
   parseTopLevelCommands, parseGroupSubcommands, parseCaseArms, parseInstallerFlags, flattenKeys, hookMatrix,
   extractSurface, surfaceRows, referencePattern, mapSurface, listTestFiles, loadTestSources, diffSurface, scaffold,
+  LIVENESS_ALLOWLIST_REL, pantoolsCalls, loadLivenessInputs, stripDefaultsBuilder, liveness, livenessProblems, checkReport, readLivenessAllowlist,
 };