session-orchestrator 3.19.0 → 3.21.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/state-md/mission-status.mjs

@@ -24,8 +24,9 @@ import { updateFrontmatterFields, writeStateMd } from './frontmatter-mutators.mj
  * STATE.md files). Returns `[]` when the key is present but the value is an empty
  * array. Returns the array of entries when present and non-empty.
  *
- * Does NOT validate individual entry shapes — callers that need schema validation
- * should use `validateMissionStatusEntry` from mission-status-schema.mjs.
+ * Does NOT validate individual entry shapes, and no helper in this repo does:
+ * entry shape and the `status` enum are coordinator convention, deliberately not a
+ * mechanical gate (see `syncFrontmatterMissionStatus` below for why).
  *
  * @param {object} frontmatter
  * @returns {object[]|null}
@@ -55,9 +56,9 @@ export function parseMissionStatus(frontmatter) {
  * - Works on string input (pure — no file I/O). Returns the updated STATE.md contents.
  * - No-ops if `contents` has no parseable frontmatter (returns input unchanged).
  *
- * Individual entry objects must conform to the shape validated by
- * `validateMissionStatusEntry` in mission-status-schema.mjs, but this function does
- * NOT enforce that constraint — callers are responsible for pre-validation.
+ * Individual entry objects are expected to carry `{ id, task, wave, status }`, but
+ * this function does NOT enforce that shape and no validator in this repo does —
+ * callers own the invariant.
  *
  * @param {string} contents
  * @param {object[]|null|undefined} missionStatusArray
@@ -85,16 +86,24 @@ export function writeMissionStatus(contents, missionStatusArray) {
  * UPDATE-ONLY by design: when the key is absent, is not an array, or holds no entry
  * with a matching `id`, the frontmatter is returned unchanged. It is deliberately
  * neither created nor an error, because `setMissionStatus(contents, taskId, status)`
- * knows only `id` and `status` — it lacks the `task` and `wave` fields that
- * `validateMissionStatusEntry` (mission-status-schema.mjs) requires, so a synthesised
- * entry would be schema-invalid yet look authoritative to frontmatter consumers such
- * as `vault-status/narrative-mirror.mjs`. Throwing is likewise excluded by the
- * never-throw contract of `setMissionStatus`.
+ * knows only `id` and `status` — it lacks the `task` and `wave` fields a full entry
+ * carries, so a synthesised entry would be shape-invalid yet look authoritative to
+ * frontmatter consumers such as `vault-status/narrative-mirror.mjs`. Throwing is
+ * likewise excluded by the never-throw contract of `setMissionStatus`.
  *
  * `status` is mirrored verbatim without an enum check on purpose: gating it would
  * reintroduce the exact divergence (body says X, frontmatter says Y) this sync exists
- * to remove. An out-of-enum value now lands on BOTH surfaces, where the repo's own
- * validator can see it.
+ * to remove. An out-of-enum value therefore lands visibly on BOTH surfaces rather than
+ * being silently rejected on one.
+ *
+ * There is deliberately NO transition validator behind this. A `mission-status-schema.mjs`
+ * once existed (#340) offering `isValidMissionStatusTransition`; it was never wired and
+ * was removed, because the only guard form it enabled — read the current status, reject a
+ * disallowed transition — would reject legitimate live writes. Measured against a copy of
+ * this repo's own STATE.md carrying 24 items: 12 had no body entry yet (current status
+ * reads `null`, so every transition out of them is "invalid"), and the routine
+ * `in-dev` → `completed` write is not in the strict forward chain either — 18 of 24
+ * writes would have been refused. The enum is a vocabulary, not a state machine.
  *
  * @param {object} frontmatter
  * @param {string} taskId

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/tmux-layout/vcs-detector.mjs

@@ -6,20 +6,116 @@
  * so all commands are wrapped in a `while true; sleep` loop per D5 findings.
  *
  * Issue #561 — ADR-0007 tmux-visualization substrate.
+ *
+ * ## The probed pane commands — SSOT for the lockstep test
+ *
+ * The two lines below are the argv this module emits, with the resolved repo
+ * spec written as `<spec>` and the `2>&1` redirect dropped. They are not a
+ * description of the commands: `tests/lib/tmux-layout/vcs-detector.test.mjs`
+ * reconstructs the same normalisation from `detectVcsCommand()` and asserts
+ * equality, so a flag added to the emitted command without a matching probe
+ * here turns that test RED. See § Why a probe line, not prose.
+ *
+ *   PROBE 2026-08-14 glab 1.91.0: glab ci status -R <spec> --output json
+ *   PROBE 2026-08-14 gh 2.86.0: gh pr checks --watch
+ *
+ * ## Why `glab ci status` carries no pipeline selector (#1022)
+ *
+ * The glab pane emitted `--pipeline-id LATEST` until 2026-08-14. That flag does
+ * not exist on any `glab ci` subcommand, and `glab ci status --help` (1.91.0)
+ * lists only `-b --branch`, `-c --compact`, `-l --live`, `-F --output`,
+ * `-R --repo`. Probed from a non-git cwd against this repo's own remote:
+ *
+ *   with the flag → `ERROR Unknown flag: --pipeline-id.`, exit 1
+ *   without it    → exit 0, `{"jobs":[…],"pipeline":{…}}`
+ *
+ * So the flag was the sole cause and it has NO replacement: the argument-less
+ * form already means "the pipeline of the current branch" (glab's own help
+ * example). `--branch=<name>` is the only selector glab offers and is
+ * deliberately NOT used — it would freeze a render-time branch snapshot into a
+ * pane that must follow the operator's checkout, the same reason the gh pane
+ * takes no positional.
+ *
+ * The `jq` filter was dead by the same measurement and is fixed with it: the
+ * payload is an OBJECT keyed `jobs`/`pipeline`, so the old `.[]` raised
+ * `Cannot index array with string "name"` (jq exit 5) on every real response.
+ * `.jobs[]` returns one `<status> <name>` line per job. Because the whole
+ * pipeline is `… 2>&1 | jq … 2>/dev/null || echo …`, both failures were
+ * swallowed into the fallback text — the pane printed "glab not available or no
+ * pipeline" against a healthy pipeline, indistinguishable from a missing binary.
+ *
+ * ## Why only the glab pane carries `-R` (#971)
+ *
+ * The pane commands run in whatever cwd the operator pastes the one-liner into,
+ * so an omitted `-R`/`--repo` silently targets the ambient cwd remote. Both
+ * halves were probed against the installed binaries on 2026-08-14
+ * (glab 1.91.0 / gh 2.86.0) and they do NOT behave the same:
+ *
+ *  - `glab ci status -R <spec> --output json` from a NON-git cwd → exit 0 with
+ *    real pipeline JSON. The flag is applicable and makes the pane
+ *    cwd-independent, so it is passed whenever `resolveRepoSpec()` resolves one.
+ *  - `gh pr checks -R <spec>` with NO positional argument →
+ *    `argument required when using the --repo flag` (exit non-zero, no output).
+ *    gh selects "the PR of the current branch" ONLY in the argument-less form;
+ *    `-R` is legal there only alongside a `<number> | <url> | <branch>`
+ *    positional, which this pane deliberately does not have (the watched branch
+ *    must follow the operator's checkout, and a render-time branch snapshot
+ *    would go stale on the next `git switch`). Adding `-R` there would break the
+ *    pane at runtime — the exact defect shape recorded in
+ *    `scripts/lib/ci-status-banner.mjs` (`-R` on `gh repo view`, which rejects
+ *    it). The gh pane therefore stays cwd-scoped BY MEASUREMENT, not by
+ *    oversight.
+ *
+ * ## Why a probe line, not prose
+ *
+ * The #971 sweep added `-R` here and left `--pipeline-id` untouched, then wrote
+ * a header documenting a probe of `glab ci status -R <spec> --output json` —
+ * a command the pane never emitted. The measurement was real and cited for
+ * something it had not measured, so a dead flag rode through a green test.
+ * NAMED CEILING: the lockstep only proves that command and probe were changed
+ * together; it cannot prove the probe was re-executed. It buys the one step
+ * that was skipped — no flag change without touching the measurement record.
+ * Revisit if a pane ever needs a runtime-varying flag, which this shape cannot
+ * express.
+ */
+
+import { resolveRepoSpec } from '../vcs-repo-spec.mjs';
+
+/**
+ * Shell-safe spec shape. A git remote URL (`git@host:group/project.git`,
+ * `https://host/group/project.git`) and an `OWNER/REPO` spec are both fully
+ * inside this character class, so a matching value can be spliced into the pane
+ * command line without quoting. A value OUTSIDE it is DROPPED (the flag is
+ * omitted) rather than quoted — this mirrors `resolveRepoSpec`'s own contract
+ * that an unresolvable spec means "omit the flag entirely", never "emit a
+ * broken one", and keeps a hostile remote URL out of the pane's shell.
  */
+const SHELL_SAFE_SPEC_RE = /^[A-Za-z0-9._:/@+-]+$/;
 
 /**
  * Resolve the CI-watch pane command based on Session Config vcs: key.
  *
- * @param {{ config?: object, projectRoot: string }} args
+ * @param {{
+ *   config?: object,
+ *   projectRoot: string,
+ *   gitRun?: (args: string[]) => { ok: boolean, stdout: string, stderr: string }
+ * }} args
+ *   - gitRun: optional `resolveRepoSpec` seam, so callers/tests can pin the
+ *     resolved repo spec instead of spawning `git` against the real checkout.
  * @returns {{ bin: 'glab'|'gh'|null, command: string, fallback: string, blocking: boolean, platform: 'gitlab'|'github'|null }}
  *   - command: the shell command for Pane 3 (wrapped in poll-loop since glab/gh are poll-based, not live-tail)
  *   - fallback: shell command shown when bin is not available in PATH
  */
-export function detectVcsCommand({ config, projectRoot: _projectRoot }) {
+export function detectVcsCommand({ config, projectRoot, gitRun }) {
   const vcs = config?.vcs;   // 'gitlab' | 'github' | undefined
 
   if (vcs === 'gitlab') {
+    const spec = resolveRepoSpec({
+      repoRoot: projectRoot,
+      vcs: 'gitlab',
+      ...(typeof gitRun === 'function' ? { gitRun } : {}),
+    });
+    const repoFlag = spec && SHELL_SAFE_SPEC_RE.test(spec) ? ` -R ${spec}` : '';
     return {
       bin: 'glab',
       platform: 'gitlab',
@@ -29,8 +125,12 @@ export function detectVcsCommand({ config, projectRoot: _projectRoot }) {
         '  clear;',
         '  date;',
         "  echo '--- glab ci status (refresh: 15s) ---';",
-        '  glab ci status --pipeline-id LATEST --output json 2>&1',
-        "    | jq -r '.[] | \"\\(.status) \\(.name)\"' 2>/dev/null",
+        // No pipeline selector: `--pipeline-id` is not a glab flag (1.91.0
+        // rejects it outright) and the argument-less form already means "the
+        // current branch's pipeline". `.jobs[]`, not `.[]` — the payload is an
+        // object. Both measured 2026-08-14; see the module header.
+        `  glab ci status${repoFlag} --output json 2>&1`,
+        "    | jq -r '.jobs[] | \"\\(.status) \\(.name)\"' 2>/dev/null",
         "    || echo 'glab not available or no pipeline';",
         '  sleep 15;',
         'done',
@@ -55,6 +155,10 @@ export function detectVcsCommand({ config, projectRoot: _projectRoot }) {
         '  clear;',
         '  date;',
         "  echo '--- gh pr checks --watch (will exit on PR completion) ---';",
+        // No `-R` here BY MEASUREMENT, not by oversight: `gh pr checks -R <spec>`
+        // without a positional PR/branch argument is rejected outright
+        // ("argument required when using the `--repo` flag", gh 2.86.0), and this
+        // pane must follow the operator's current branch. See the module header.
         '  gh pr checks --watch 2>&1',
         "    || echo 'no PR in current branch';",
         '  sleep 15;',

package/scripts/lib/validate/check-agents.mjs

@@ -7,7 +7,9 @@
 import { readFileSync, readdirSync, existsSync } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import yaml from 'js-yaml';
 import { ALLOWED_MODEL_ALIASES, MODEL_ID_RE } from '../agent-frontmatter.mjs';
+import { extractInitialFrontmatter } from './frontmatter-block.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -57,10 +59,45 @@ function fail(msg) {
 /**
  * Extract YAML frontmatter content (between first --- and second ---).
  * Returns null if no valid frontmatter block found.
+ *
+ * Delegates to the shared extractor. This file carried a THIRD verbatim copy of
+ * that regex until now (check-skills.mjs and check-commands.mjs held the other
+ * two, which is why the extraction was lifted into frontmatter-block.mjs). Only
+ * the block-finding is shared — the field RULES stay per-gate and disagree on
+ * purpose; see the header of frontmatter-block.mjs.
+ *
+ * Checks 7-10 only need "text, or nothing"; Check 6 reads the shared
+ * diagnostic directly for a precise message.
  */
 function extractFrontmatter(content) {
-  const m = content.match(/^---\n([\s\S]*?)\n---/);
-  return m ? m[1] : null;
+  const extracted = extractInitialFrontmatter(content);
+  return extracted.ok ? extracted.yamlText : null;
+}
+
+/**
+ * Parse a frontmatter block with a real YAML parser (CORE_SCHEMA, matching
+ * check-commands.mjs and check-skills.mjs).
+ *
+ * @param {string} yamlText - the block's inner text, no fences
+ * @returns {{ ok: true, data: unknown } | { ok: false, message: string }}
+ *   On failure, `message` is a caller-printable reason with a frontmatter-local
+ *   line/column when js-yaml supplies one.
+ */
+function parseFrontmatterYaml(yamlText) {
+  let data;
+  try {
+    data = yaml.load(yamlText, { schema: yaml.CORE_SCHEMA });
+  } catch (error) {
+    const reason = error?.reason ?? error?.message ?? String(error);
+    const location = error?.mark
+      ? ` at frontmatter line ${error.mark.line + 1}, column ${error.mark.column + 1}`
+      : '';
+    return { ok: false, message: `invalid YAML frontmatter: ${reason}${location}` };
+  }
+  if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+    return { ok: false, message: 'YAML frontmatter must be a non-null mapping/object' };
+  }
+  return { ok: true, data };
 }
 
 /**
@@ -146,17 +183,48 @@ const mdFiles = readdirSync(agentsDir).filter(isAgentDefFile);
 if (mdFiles.length === 0) {
   fail('agents directory is empty (no .md files)');
 } else {
+  let parseable = 0;
+
   for (const agentFile of mdFiles) {
     const agentName = agentFile;
     const filePath = join(agentsDir, agentFile);
     const content = readFileSync(filePath, 'utf8');
 
-    const frontmatter = extractFrontmatter(content);
+    const extracted = extractInitialFrontmatter(content);
 
-    if (!frontmatter) {
-      fail(`${agentName}: missing YAML frontmatter`);
+    if (!extracted.ok) {
+      fail(`${agentName}: ${extracted.diagnostic}`);
       continue;
     }
+    const frontmatter = extracted.yamlText;
+
+    // ------------------------------------------------------------------
+    // The block is valid YAML.
+    //
+    // Every rule below reads the block with LINE REGEXES (getField/hasField),
+    // which model Claude Code's own lenient loader. That leniency is exactly
+    // how 14 of 16 agent definitions sat unparseable in the tree unnoticed: an
+    // unquoted single-line `description:` containing a `: ` (e.g.
+    // `<example>Context: /plan ...`) is not YAML, and a regex looking only for
+    // `^description:` sees nothing wrong. A ` #` inside such a value is worse
+    // still — it opens a YAML comment, so the block PARSES while silently
+    // truncating the description at that point.
+    //
+    // A parse failure is reported alone (no fall-through to the field rules):
+    // the block is broken at the root, and six regex verdicts stacked on top
+    // of it are cascade noise that buries the one defect worth fixing. Same
+    // posture as check-skills.mjs R8.
+    //
+    // ORTHOGONAL to the `description` block-scalar ban further down: this rule
+    // demands the block BE YAML; that one forbids one particular valid YAML
+    // form the agent loader cannot read. Neither implies the other.
+    // ------------------------------------------------------------------
+    const parsedFm = parseFrontmatterYaml(frontmatter);
+    if (!parsedFm.ok) {
+      fail(`${agentName}: ${parsedFm.message}`);
+      continue;
+    }
+    parseable++;
 
     // ------------------------------------------------------------------
     // Required fields check
@@ -236,6 +304,10 @@ if (mdFiles.length === 0) {
       }
     }
   }
+
+  if (parseable === mdFiles.length) {
+    pass(`all ${mdFiles.length} agent frontmatter blocks parse as YAML mappings`);
+  }
 }
 
 // ============================================================================