session-orchestrator 3.19.0 → 3.20.0

package/scripts/lib/session-token-rollup.mjs

@@ -3,7 +3,9 @@
  *
  * Reads `.orchestrator/metrics/subagents.jsonl` (or a caller-supplied path),
  * filters to a given `parent_session_id`, and sums `token_input` /
- * `token_output` across all matched records, skipping null/undefined values.
+ * `token_output` across the records whose token fields are TRUSTWORTHY — see
+ * § Token provenance below, which is the whole reason this module is not a
+ * two-line sum.
  *
  * Design notes:
  * - Pure function — no top-level side effects, no writes.
@@ -12,7 +14,44 @@
  *   "session was genuinely free / cost $0".
  * - Malformed JSONL lines are silently skipped (resilience over strictness).
  * - `subagents_with_tokens` counts distinct agent_ids that have at least one
- *   record with a non-null token_input or token_output value (coverage metric).
+ *   TOKEN-BEARING record (coverage metric).
+ *
+ * ## Token provenance — why a bare Σ over token_input is wrong (#949)
+ *
+ * Two record classes in this ledger carry a `token_input` that must NEVER be
+ * summed, and both look identical to a naive reader:
+ *
+ * 1. **Pre-#949 records** (written before 2026-07-31). The producer read the
+ *    PARENT session transcript instead of the subagent's own, so every stop
+ *    record carries the parent's running totals. Summing them counts the parent
+ *    once per subagent. `hooks/subagent-telemetry.mjs` § TOKEN-DATA PROVENANCE
+ *    states the consumer obligation outright: "Consumers MUST discard token_* on
+ *    every stop record written before this fix landed."
+ * 2. **Phantom stops** (#939). The harness fires `SubagentStop` for an ephemeral
+ *    agent class that never fires `SubagentStart` and for which no subagent ever
+ *    existed. These carry null tokens today — harmless to sum, but they inflate
+ *    any coverage ratio computed against `matched_records`.
+ *
+ * `subagent_transcript_found === true` settles both at once and is the flag the
+ * producer writes for exactly this purpose. It is a sufficient cutoff on its own:
+ * the field did not exist before the #949 fix, so `=== true` excludes every
+ * pre-fix record without needing a date comparison.
+ *
+ * Measured over this repo's ledger on 2026-08-11 (3,981 records / 116 sessions):
+ * 73 sessions summed to 96,148,781 tokens that no agent ever spent — every one of
+ * them a pre-#949 parent total. Under this filter those sessions correctly report
+ * null ("no token data") instead.
+ *
+ *   jq -r 'select(.event=="stop" and .subagent_transcript_found==true and .token_input==null)' \
+ *     .orchestrator/metrics/subagents.jsonl | wc -l     # → 0
+ *
+ * i.e. the flag never excludes a record that genuinely had tokens.
+ *
+ * FORWARD-ONLY. Session totals already written into `sessions.jsonl` by the
+ * unfiltered recipe are NOT recomputed — that ledger is append-only and the
+ * transcripts that produced the oldest records have aged out, so a rewrite would
+ * be reconstruction, not correction. Consumers comparing token totals across the
+ * 2026-08-11 boundary must treat it as a series break.
  *
  * @module session-token-rollup
  */
@@ -30,12 +69,28 @@ const DEFAULT_SUBAGENTS_PATH = '.orchestrator/metrics/subagents.jsonl';
 // Public API
 // ---------------------------------------------------------------------------
 
+/**
+ * Is this record's token data trustworthy enough to sum? (#949)
+ *
+ * The producer sets `subagent_transcript_found: true` only when it located and
+ * read the subagent's OWN transcript. Every other shape — a phantom stop, a
+ * start record, or any record written before the flag existed — is excluded.
+ * See the module header § Token provenance for why this single flag is a
+ * sufficient cutoff and what it costs to omit it.
+ *
+ * @param {object} record — a parsed subagents.jsonl record
+ * @returns {boolean}
+ */
+function isTokenBearing(record) {
+  return record?.subagent_transcript_found === true;
+}
+
 /**
  * @typedef {Object} TokenRollupResult
- * @property {number|null} total_token_input  - Sum of token_input across matched records; null when no record had a non-null value.
- * @property {number|null} total_token_output - Sum of token_output across matched records; null when no record had a non-null value.
- * @property {number}      subagents_with_tokens - Count of distinct agent_ids that had at least one non-null token value.
- * @property {number}      matched_records    - Total count of JSONL records matched by parentSessionId (includes null-token records).
+ * @property {number|null} total_token_input  - Sum of token_input across TOKEN-BEARING matched records; null when none had a non-null value.
+ * @property {number|null} total_token_output - Sum of token_output across TOKEN-BEARING matched records; null when none had a non-null value.
+ * @property {number}      subagents_with_tokens - Count of distinct agent_ids with at least one token-bearing record. This is the numerator of the honest coverage ratio.
+ * @property {number}      matched_records    - Total count of JSONL records matched by parentSessionId. Counts start records, phantom stops and pre-#949 records alike, so it is NOT the denominator for a token-coverage ratio — dividing by it is what made healthy sessions read as 12% covered.
  */
 
 /**
@@ -107,6 +162,13 @@ export function rollupSessionTokens({
   const agentsWithTokens = new Set();
 
   for (const record of matched) {
+    // Provenance gate (#949) — a record whose tokens describe the PARENT
+    // transcript, or no transcript at all, contributes nothing. Skipping it
+    // entirely (rather than treating its values as 0) preserves the null
+    // sentinel: a session of only untrustworthy records reports "no data",
+    // which is true, instead of a fabricated 0.
+    if (!isTokenBearing(record)) continue;
+
     const inp = record.token_input;
     const out = record.token_output;
 

package/scripts/lib/soul-resolve.mjs

@@ -5,6 +5,18 @@
  * config loaded via `owner-yaml.mjs` (D1). Pure at the `resolveSoul` level;
  * `loadAndResolveSoul` performs disk I/O.
  *
+ * ── NO RUNTIME CALLER — read this before assuming a soul.md is resolved ──────
+ *
+ * Nothing in `scripts/`, `hooks/`, or any skill body calls either export. Skill
+ * bodies instruct the coordinator to read soul.md DIRECTLY, so whatever is in
+ * the file on disk is what the coordinator sees — an unsubstituted `{{slot}}`
+ * reaches the model verbatim and instructs nothing. `skills/session-start/soul.md`
+ * is therefore authored pre-resolved: it carries no slots, and the operator's
+ * `efficiency.output-level` selects one of its literal `### output-level: <value>`
+ * blocks (see that file's § Output Levels; the skill body performs the lookup).
+ * Slots that remain in other soul.md files are inert for the same reason.
+ * Do not add a slot to a soul.md expecting substitution — wire a caller first.
+ *
  * ── Slot syntax ──────────────────────────────────────────────────────────────
  *
  *   {{owner.language}}          → 'de' | 'en'

package/scripts/lib/tmux-layout/telemetry.mjs

@@ -18,25 +18,52 @@
 import { appendFileSync, mkdirSync, existsSync } from 'node:fs';
 import path from 'node:path';
 
-const EVENTS_PATH = '.orchestrator/metrics/events.jsonl';
+import { findProjectRoot } from '../common.mjs';
 
 /**
- * Emit a single tmux-layout event to events.jsonl.
+ * Path FRAGMENT joined against a resolved repo root at write time — NOT a
+ * relative path constant. A relative constant resolves against process.cwd(),
+ * which is how ~8k test-emitted tmux events landed in the real ledger: the
+ * suite spawns scripts/tmux-layout.mjs with cwd = repo root, so every
+ * telemetry write went straight into production telemetry.
+ * Same shape as scripts/lib/session-close-backfill.mjs § EVENTS_REL.
+ */
+const EVENTS_REL = ['.orchestrator', 'metrics', 'events.jsonl'];
+
+/**
+ * True when this process is a vitest run, or a child spawned by one
+ * (vitest sets VITEST=true and the child inherits process.env).
+ * @returns {boolean}
+ */
+function isTestRunner() {
+  return Boolean(process.env.VITEST) || process.env.VITEST_WORKER_ID !== undefined;
+}
+
+/**
+ * Emit a single tmux-layout event to <repoRoot>/.orchestrator/metrics/events.jsonl.
  * Best-effort — never throws (telemetry must not block the layout itself).
  *
+ * Under a test runner an emit WITHOUT an explicit `repoRoot` is dropped: a test
+ * process has no business appending to a real ledger, and telemetry is
+ * best-effort by contract, so dropping is the correct degradation. Tests that
+ * assert on the write pass `repoRoot` and get the full write path.
+ *
  * @param {string} eventType - 'tmux-layout.invoked' | 'tmux-layout.degraded' | 'tmux-layout.completed'
  * @param {object} [payload] - additional fields (layout, duration_ms, reason, etc.)
+ * @param {{ repoRoot?: string }} [opts] - repoRoot the ledger is resolved against (default: findProjectRoot())
  */
-export function emit(eventType, payload = {}) {
+export function emit(eventType, payload = {}, { repoRoot } = {}) {
   try {
-    const dir = path.dirname(EVENTS_PATH);
+    if (!repoRoot && isTestRunner()) return;
+    const eventsPath = path.join(repoRoot || findProjectRoot(), ...EVENTS_REL);
+    const dir = path.dirname(eventsPath);
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
     const record = {
       event: eventType,
       timestamp: new Date().toISOString(),
       ...payload,
     };
-    appendFileSync(EVENTS_PATH, JSON.stringify(record) + '\n');
+    appendFileSync(eventsPath, JSON.stringify(record) + '\n');
   } catch {
     // Best-effort — swallow all errors. Telemetry must not block layout.
   }
@@ -45,18 +72,24 @@ export function emit(eventType, payload = {}) {
 /**
  * Wrap a layout function with telemetry. Emits invoked → completed/degraded.
  *
+ * The repoRoot is taken ONLY from this explicit option — never derived from the
+ * wrapped call's own `projectRoot` argument. Deriving it would hand the spawned
+ * CLI an explicit root inside the test suite and re-open the exact
+ * production-ledger contamination path the emit() guard closes.
+ *
  * @param {string} layoutName - 'default' | 'debug'
  * @param {Function} fn - async function returning { ok, oneliner, panes, degraded, attachCommand, error? }
+ * @param {{ repoRoot?: string }} [opts] - repoRoot the ledger is resolved against (default: findProjectRoot())
  * @returns {Function} wrapped function with same signature
  * @throws {TypeError} synchronously when fn is not a function
  */
-export function withTelemetry(layoutName, fn) {
+export function withTelemetry(layoutName, fn, { repoRoot } = {}) {
   if (typeof fn !== 'function') {
     throw new TypeError(`withTelemetry: fn must be a function (got ${typeof fn})`);
   }
   return async function telemetryWrapped(...args) {
     const startedAt = Date.now();
-    emit('tmux-layout.invoked', { layout: layoutName });
+    emit('tmux-layout.invoked', { layout: layoutName }, { repoRoot });
     try {
       const result = await fn(...args);
       const durationMs = Date.now() - startedAt;
@@ -66,13 +99,13 @@ export function withTelemetry(layoutName, fn) {
           duration_ms: durationMs,
           panes: result.panes ?? null,
           degraded: result.degraded === true,
-        });
+        }, { repoRoot });
       } else {
         emit('tmux-layout.degraded', {
           layout: layoutName,
           duration_ms: durationMs,
           reason: result?.error ?? 'unknown',
-        });
+        }, { repoRoot });
       }
       return result;
     } catch (err) {
@@ -81,7 +114,7 @@ export function withTelemetry(layoutName, fn) {
         layout: layoutName,
         duration_ms: durationMs,
         reason: `exception: ${err?.message ?? String(err)}`,
-      });
+      }, { repoRoot });
       throw err;
     }
   };

package/scripts/lib/validate/check-banner-parity.mjs

@@ -0,0 +1,376 @@
+#!/usr/bin/env node
+/**
+ * Invariant canary for the #621 HISTORICAL guard banner.
+ *
+ * The banner is a single canonical literal exported as `HISTORICAL_GUARD_BANNER`
+ * from `scripts/lib/historical-guard.mjs` (the SSOT), and it is ALSO quoted as
+ * prose in the skill bodies that instruct the coordinator to render it. A reword
+ * on the prose side silently diverges from the code constant and weakens the
+ * stale-replay guard, because nothing recompiles when markdown changes.
+ *
+ * This check pins cross-file parity: every prose site that still carries the
+ * banner marker must reproduce the SSOT literal byte-for-byte (or an explicitly
+ * elided prefix of it — see `classifyBannerSite`).
+ *
+ * Why per-SITE and not per-FILE: a file-wide `includes(BANNER)` assertion stays
+ * green while five of six sites in the same file rot, because one intact copy
+ * satisfies it. Each occurrence is therefore judged independently.
+ *
+ * Deliberate non-goal — this check never pins a SITE COUNT. Sites may legitimately
+ * be added or removed; only DIVERGENCE is an error. Whole-site DELETION is covered
+ * by the placement tests in `tests/skills/session-start/` (SKILL.md only —
+ * presentation-format.md has no placement coverage; for that file this check is
+ * the only divergence gate).
+ *
+ * Known residuals, named so nobody over-reads the coverage claim:
+ *  - Detection is marker-gated on TWO SSOT-derived phrases (`DETECTION_MARKERS`).
+ *    A reword that destroys BOTH phrases removes the site from the census — that
+ *    degenerate case is indistinguishable from whole-site deletion (see above).
+ *  - Judging is per-LINE: two banner copies on ONE physical line are satisfied
+ *    by the intact copy (unlikely in prose; accepted).
+ *  - Only `SCAN_DIRS` markdown is censused; a future banner copy in e.g.
+ *    `agents/` or `docs/` would be invisible until the dir is added here.
+ *  - Authoring constraint (fail-closed, not fail-open): the elided form must be
+ *    the whole normalized line (canonical prefix + elision marker), and a
+ *    soft-wrapped multi-line banner is reported as divergent.
+ *
+ * Reading is done with `readFileSync`, never a `grep` spawn: a single NUL byte
+ * makes a text file invisible to grep-based audits (see
+ * `.claude/rules/anti-pattern-a-nul-byte-in-a-tracked-production-file-...md`),
+ * which would silently drop a rotted site from the census.
+ *
+ * Import-safety: importing this module only exposes the inspector and runner;
+ * the CLI path is guarded at the bottom of the file.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { HISTORICAL_GUARD_BANNER } from '../historical-guard.mjs';
+
+/** Directories whose markdown quotes the banner as coordinator-facing prose. */
+const SCAN_DIRS = Object.freeze(['skills', 'commands']);
+
+/** Only markdown carries prose copies of the banner. */
+const MARKDOWN_EXT = '.md';
+
+/**
+ * `git` is invoked with a filtered environment so an ambient `GIT_DIR` cannot
+ * redirect enumeration at a foreign repository — that would silently census the
+ * wrong file set and pass vacuously.
+ */
+const GIT_ENV_ALLOWLIST = Object.freeze(['PATH', 'HOME', 'LANG', 'LC_ALL', 'TMPDIR', 'TZ']);
+
+/**
+ * Load-bearing first sentence of the canonical banner, derived from the SSOT.
+ * An elided quote may never truncate below this — dropping "NOT LIVE
+ * INSTRUCTIONS" removes the entire guard force of the banner.
+ */
+export const BANNER_FIRST_SENTENCE = HISTORICAL_GUARD_BANNER.slice(
+  0,
+  HISTORICAL_GUARD_BANNER.indexOf('.') + 1,
+);
+
+/**
+ * Substring that marks a line as "this line is quoting the banner", derived from
+ * the SSOT rather than hardcoded — a second hardcoded copy of banner text inside
+ * the drift checker would be the very drift class this check exists to catch.
+ */
+export const DETECTION_MARKER = BANNER_FIRST_SENTENCE.replace(/^[^A-Z]+/, '').split(' — ')[0];
+
+/**
+ * Detection is a DISJUNCTION of two SSOT-derived phrases: a reword that destroys
+ * one marker must not hide the site from the census — only destroying both does,
+ * and that degenerate case equals whole-site deletion (owned by the placement
+ * tests for SKILL.md). Both tokens derive from the SSOT at import time.
+ */
+export const DETECTION_MARKERS = Object.freeze([
+  DETECTION_MARKER,
+  BANNER_FIRST_SENTENCE.split(' — ')[1].replace(/\.$/, ''),
+]);
+
+/** @param {string} text @returns {boolean} whether any detection marker is present */
+function hasDetectionMarker(text) {
+  return DETECTION_MARKERS.some((marker) => text.includes(marker));
+}
+
+/** Explicit elision markers a prose site may use to shorten the quote. */
+const ELISION_MARKERS = Object.freeze(['…', '...']);
+
+/** Offending-text budget in the reported finding (keeps stdout bounded). */
+const QUOTE_BUDGET = 160;
+
+/**
+ * @typedef {{
+ *   kind: string,
+ *   file: string,
+ *   line: number,
+ *   message: string,
+ * }} Finding
+ */
+
+/**
+ * @typedef {{
+ *   file: string,
+ *   line: number,
+ *   form: 'full' | 'elided',
+ * }} BannerSite
+ */
+
+/**
+ * Recursively collect markdown files in deterministic path order.
+ *
+ * Symlinked entries are never followed: a symlink is an operator-controlled path
+ * escape, and following one would scan a file outside the plugin root.
+ *
+ * @param {string} directory absolute directory path
+ * @returns {string[]} absolute markdown file paths, sorted
+ */
+function walkMarkdown(directory) {
+  if (!existsSync(directory)) return [];
+  /** @type {string[]} */
+  const files = [];
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    if (entry.isSymbolicLink()) continue;
+    const fullPath = path.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...walkMarkdown(fullPath));
+    } else if (entry.isFile() && path.extname(entry.name) === MARKDOWN_EXT) {
+      files.push(fullPath);
+    }
+  }
+  return files.sort();
+}
+
+/**
+ * Resolve a path through symlinks, falling back to the input when it does not
+ * exist (so a missing root is reported by the caller, not thrown here).
+ *
+ * @param {string} target
+ * @returns {string}
+ */
+function safeRealpath(target) {
+  try {
+    return realpathSync(target);
+  } catch {
+    return target;
+  }
+}
+
+/**
+ * Enumerate tracked markdown under the scan directories.
+ *
+ * `git ls-files` is the primary source (tracked-only, so scratch drafts do not
+ * fail the build); it is trusted ONLY when `pluginRoot` is itself the repository
+ * toplevel. When the root sits inside some other repository — or git is
+ * unavailable — enumeration falls back to a recursive filesystem walk rather
+ * than censusing a foreign file set.
+ *
+ * @param {string} pluginRoot absolute plugin root
+ * @returns {string[]} absolute markdown file paths, sorted
+ */
+export function collectMarkdownFiles(pluginRoot) {
+  const env = {};
+  for (const key of GIT_ENV_ALLOWLIST) {
+    if (process.env[key] !== undefined) env[key] = process.env[key];
+  }
+
+  try {
+    const toplevel = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+      cwd: pluginRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      env,
+    }).trim();
+    if (toplevel && safeRealpath(toplevel) === safeRealpath(pluginRoot)) {
+      const output = execFileSync('git', ['ls-files', '-z', '--', ...SCAN_DIRS], {
+        cwd: pluginRoot,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        env,
+      });
+      return output
+        .split('\0')
+        .filter(Boolean)
+        .filter((relative) => path.extname(relative) === MARKDOWN_EXT)
+        .map((relative) => path.join(pluginRoot, relative))
+        .filter((absolute) => {
+          try {
+            return lstatSync(absolute).isFile();
+          } catch {
+            return false;
+          }
+        })
+        .sort();
+    }
+  } catch {
+    // fall through to the filesystem walk
+  }
+
+  return SCAN_DIRS.flatMap((dir) => walkMarkdown(path.join(pluginRoot, dir))).sort();
+}
+
+/**
+ * Strip the markdown decoration a prose site may wrap the banner in, so the
+ * comparison judges banner TEXT rather than markdown formatting.
+ *
+ * Handles leading indentation, one or more `>` blockquote prefixes, and a
+ * surrounding backtick run. Inner backticks are deliberately preserved — the
+ * full-form comparison is a substring match and does not need them removed.
+ *
+ * @param {string} line raw markdown line
+ * @returns {string} normalized line text
+ */
+export function normalizeQuotedLine(line) {
+  let text = line.trim();
+  while (text.startsWith('>')) text = text.slice(1).trim();
+  return text.replace(/^`+/, '').replace(/`+$/, '').trim();
+}
+
+/**
+ * Judge one normalized banner-quoting line against the SSOT literal.
+ *
+ * Two forms are accepted:
+ *  - `full`   — the line contains the canonical banner byte-for-byte;
+ *  - `elided` — the line is a canonical PREFIX followed by an explicit elision
+ *               marker, and that prefix still covers the load-bearing first
+ *               sentence. Render-template examples legitimately shorten the
+ *               quote; a reword inside the visible part is still caught, because
+ *               every visible character must match the SSOT.
+ *
+ * @param {string} normalized line text from `normalizeQuotedLine`
+ * @returns {{ok: boolean, form: 'full' | 'elided' | 'divergent'}}
+ */
+export function classifyBannerSite(normalized) {
+  if (normalized.includes(HISTORICAL_GUARD_BANNER)) return { ok: true, form: 'full' };
+
+  const ellipsis = ELISION_MARKERS.find((marker) => normalized.endsWith(marker));
+  if (ellipsis) {
+    const prefix = normalized.slice(0, -ellipsis.length).trim();
+    const ok =
+      HISTORICAL_GUARD_BANNER.startsWith(prefix) && prefix.length >= BANNER_FIRST_SENTENCE.length;
+    return { ok, form: 'elided' };
+  }
+
+  return { ok: false, form: 'divergent' };
+}
+
+/**
+ * Inspect cross-file parity of the HISTORICAL guard banner.
+ *
+ * @param {string} pluginRoot absolute plugin root
+ * @returns {{ok: boolean, summary: {filesScanned: number, files: number, sites: number}, sites: BannerSite[], findings: Finding[], toolError: boolean}}
+ */
+export function inspectBannerParity(pluginRoot) {
+  const result = {
+    ok: false,
+    summary: { filesScanned: 0, files: 0, sites: 0 },
+    /** @type {BannerSite[]} */
+    sites: [],
+    /** @type {Finding[]} */
+    findings: [],
+    toolError: false,
+  };
+
+  let markdownFiles;
+  try {
+    markdownFiles = collectMarkdownFiles(pluginRoot);
+  } catch (error) {
+    result.toolError = true;
+    result.findings.push({
+      kind: 'tool-error',
+      file: SCAN_DIRS.join(', '),
+      line: 1,
+      message: `cannot enumerate markdown: ${error instanceof Error ? error.message : String(error)}`,
+    });
+    return result;
+  }
+  result.summary.filesScanned = markdownFiles.length;
+
+  for (const filePath of markdownFiles) {
+    const relative = path.relative(pluginRoot, filePath);
+    let body;
+    try {
+      body = readFileSync(filePath, 'utf8');
+    } catch (error) {
+      result.toolError = true;
+      result.findings.push({
+        kind: 'tool-error',
+        file: relative,
+        line: 1,
+        message: `cannot read file: ${error instanceof Error ? error.message : String(error)}`,
+      });
+      continue;
+    }
+    if (!hasDetectionMarker(body)) continue;
+
+    let sitesInFile = 0;
+    const lines = body.split('\n');
+    for (let index = 0; index < lines.length; index += 1) {
+      const raw = lines[index];
+      if (!hasDetectionMarker(raw)) continue;
+      sitesInFile += 1;
+      result.summary.sites += 1;
+
+      const normalized = normalizeQuotedLine(raw);
+      const verdict = classifyBannerSite(normalized);
+      if (verdict.ok) {
+        result.sites.push({ file: relative, line: index + 1, form: verdict.form });
+        continue;
+      }
+
+      const quoted =
+        normalized.length > QUOTE_BUDGET ? `${normalized.slice(0, QUOTE_BUDGET)}…` : normalized;
+      result.findings.push({
+        kind: 'banner-divergence',
+        file: relative,
+        line: index + 1,
+        message:
+          `quoted banner diverges from HISTORICAL_GUARD_BANNER (SSOT: scripts/lib/historical-guard.mjs); ` +
+          `found: ${JSON.stringify(quoted)}`,
+      });
+    }
+    if (sitesInFile > 0) result.summary.files += 1;
+  }
+
+  result.ok = !result.toolError && result.findings.length === 0;
+  return result;
+}
+
+/**
+ * Run the human-readable validator CLI.
+ *
+ * @param {string} pluginRoot absolute plugin root
+ * @returns {number} 0 = pass, 1 = banner divergence, 2 = filesystem/tool failure
+ */
+export function runCheckBannerParity(pluginRoot) {
+  console.log('--- Check: HISTORICAL guard banner parity (#621 invariant canary) ---');
+  const inspection = inspectBannerParity(pluginRoot);
+  if (inspection.ok) {
+    console.log(
+      `  PASS: ${inspection.summary.sites} banner site(s) across ${inspection.summary.files} file(s) match the SSOT literal ` +
+        `(${inspection.summary.filesScanned} markdown file(s) scanned)`,
+    );
+    console.log('');
+    console.log('Results: 1 passed, 0 failed');
+    return 0;
+  }
+
+  for (const item of inspection.findings) {
+    console.log(`  FAIL: ${item.file}:${item.line} — ${item.message}`);
+  }
+  console.log('');
+  console.log(`Results: 0 passed, ${inspection.findings.length} failed`);
+  return inspection.toolError ? 2 : 1;
+}
+
+const isMain = import.meta.url === pathToFileURL(process.argv[1] || '').href;
+if (isMain) {
+  const pluginRoot = process.argv[2];
+  if (!pluginRoot) {
+    console.error('Usage: check-banner-parity.mjs <plugin-root>');
+    process.exit(2);
+  }
+  process.exit(runCheckBannerParity(path.resolve(pluginRoot)));
+}