session-orchestrator 3.23.0 → 4.0.0

package/scripts/lib/events.mjs

@@ -7,12 +7,52 @@
  * Part of v3.0.0 migration (Epic #124, issue #133).
  * Issue #228: removed hardcoded personal-domain default URL. Clank Event Bus URL
  * must now be supplied explicitly via CLANK_EVENT_URL when CLANK_EVENT_SECRET is set.
+ *
+ * ## Correlation envelope (#1177 FA3)
+ *
+ * Measured 2026-09-02 @ c3ab480 over 33,608 ledger records: only 22.1% carry
+ * `session_id` and 4.8% carry `wave`, because filling them was every call
+ * site's own job and 32 of 34 call sites pass no options at all. `emitEvent()`
+ * now fills those keys itself — under three hard rules:
+ *
+ *   1. **Additive, never overriding.** The correlation keys are spread BEFORE
+ *      `payload`, so any caller-supplied `session_id` / `semantic_session_id` /
+ *      `wave` wins byte-for-byte. A payload that supplies EITHER session key
+ *      suppresses the session fill entirely (both keys), so a caller that
+ *      deliberately pins attribution elsewhere — `vault-mirror/telemetry.mjs`
+ *      pins to `SO_PROJECT_DIR` and passes both keys — is untouched.
+ *   2. **Omit, never fabricate.** When attribution cannot be PROVEN, both keys
+ *      are left ABSENT — never `null`, never `''`. An absent key is the only
+ *      honest encoding of "not attributable" (see `sessionAttribution()`).
+ *   3. **Never a peer's id (#1123).** A shared working copy means
+ *      `session.lock` can name a PEER session that won the acquire race. The
+ *      lock alone therefore does not prove ownership; the fill happens only
+ *      when a PROCESS-LOCAL id (`CLAUDE_CODE_SESSION_ID`, or a hook payload's
+ *      `session_id`) equals the lock's raw `session_id`. STATE.md is NOT a
+ *      witness here (#1177 FX1): it is a shared working-copy file written by
+ *      the lock holder, so under a peer-owned lock both agreed about the peer
+ *      and the union stamped the peer's ids. See {@link attributionForRecord}.
+ *
+ * The attribution root is the SAME root the ledger line is pinned to
+ * (`opts.repoRoot ?? SO_PROJECT_DIR`), never `process.cwd()`. Measured cost of
+ * the whole envelope (lock + wave manifest, 100 calls, this repo):
+ * 0.0961 ms/call.
  */
 
-import { promises as fs } from 'node:fs';
+import { promises as fs, existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
-import { SO_PROJECT_DIR, SO_SHARED_DIR } from './platform.mjs';
+import { getProjectDir, SO_SHARED_DIR } from './platform.mjs';
 import { readLock } from './session-lock.mjs';
+import { resolveStateMdPath } from './state-md/frontmatter-mutators.mjs';
+import {
+  classifyManifestSession,
+  readProcessLocalSessionIds,
+} from './session-identity/own-session.mjs';
+import {
+  EventValidationError,
+  stampEventSchemaVersion,
+  validateEventRecord,
+} from './events-schema.mjs';
 
 // ---------------------------------------------------------------------------
 // Public API
@@ -30,7 +70,7 @@ import { readLock } from './session-lock.mjs';
  * @param {string} [repoRoot=SO_PROJECT_DIR] — project root the events log lives under.
  * @returns {string}
  */
-export function eventsFilePath(repoRoot = SO_PROJECT_DIR) {
+export function eventsFilePath(repoRoot = getProjectDir()) {
   return path.join(repoRoot, SO_SHARED_DIR, 'metrics', 'events.jsonl');
 }
 
@@ -69,16 +109,189 @@ export function sessionAttribution(repoRoot) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Correlation envelope (#1177 FA3)
+// ---------------------------------------------------------------------------
+
+/** State-dir candidates, in the same order `state-md` resolves them. */
+const STATE_DIR_CANDIDATES = ['.claude', '.codex', '.cursor', '.pi'];
+
+/**
+ * Session-correlation keys for a record pinned to `root` — `{}` when ownership
+ * is not provable.
+ *
+ * Decision, in one line: **only a PROCESS-LOCAL id may confirm the lock, and
+ * when one exists it decides alone.**
+ *
+ *   - No lock (CI, a bare script) → `{}`. Nothing to attribute to.
+ *   - No process-local id (`CLAUDE_CODE_SESSION_ID` absent) → `{}`. Ownership is
+ *     UNPROVEN, and an unproven attribution is exactly the peer-id write #1123
+ *     forbids; an absent key costs a correlation, a wrong key costs a false one.
+ *   - A process-local id that equals the lock's raw `session_id` → fill BOTH
+ *     keys, verbatim from the lock.
+ *   - A process-local id that DISAGREES → `{}` (the lock names a peer that won
+ *     the acquire race).
+ *
+ * **Why STATE.md is not a witness (#1177 FX1).** It used to be one, unioned
+ * with the env id — and the union was the bug: `.claude/STATE.md` is a SHARED
+ * working-copy artefact written by the session that OWNS the working copy,
+ * i.e. normally the lock holder. When a peer holds the lock, the peer also
+ * wrote STATE.md, so both "independent" witnesses name the PEER and a
+ * disagreeing process-local id could not veto them. Measured: lock=peer,
+ * STATE.md=peer, `CLAUDE_CODE_SESSION_ID`=me → the peer's ids were stamped on
+ * this session's records. A shared file cannot prove which PROCESS is emitting;
+ * see `readProcessLocalSessionIds()` for the tiering rationale (HR-102: a
+ * better signal replaces a worse one, it does not merely get outvoted by it).
+ *
+ * CEILING (BV-004): the comparison is against the lock's RAW `session_id`, so a
+ * harness that ROTATES its session id mid-session (see
+ * `tests/hooks/on-session-end.test.mjs` `new-rotated-uuid`) has an env id that
+ * no longer equals the lock's raw id, and BOTH keys are then omitted — honest
+ * absence, never misattribution. REVISIT when the rotation rate is measured in
+ * `events.jsonl` (count `orchestrator.session.started` against lock rewrites):
+ * if rotation is common, the lock must be refreshed on rotation rather than
+ * this comparison widened.
+ *
+ * **THE manifest-binding writer contract (#1207).** This function is not only
+ * `emitEvent()`'s correlation fill — it is the canonical primitive for every
+ * caller that needs to name a `.orchestrator/`-adjacent artefact as "mine"
+ * without risking a peer's id. `skills/wave-executor/wave-loop.md` § Scope
+ * Manifest step 1 calls it directly to derive `wave-scope.json`'s `session_id` /
+ * `semantic_session_id` binding — a hand-written prose comparison against
+ * STATE.md previously stood in for exactly this check, and (per the STATE.md
+ * caveat above) that comparison could not veto a peer-owned lock. Any new
+ * writer facing the same "is this working-copy-shared artefact mine to
+ * stamp?" question should call this function rather than re-deriving the
+ * raw-id-vs-process-local comparison inline (see `scripts/memory-propose.mjs`
+ * `resolveRunningWaveId()` for a case that reads the SAME lock but needs the
+ * semantic id plus diagnostic detail this function's `{}`-on-any-mismatch
+ * contract intentionally does not expose, and keeps its own comparison for
+ * that reason).
+ *
+ * @param {string} [root=SO_PROJECT_DIR] — the repo the record is pinned to.
+ * @returns {{session_id?: string, semantic_session_id?: string}}
+ */
+export function attributionForRecord(root = getProjectDir()) {
+  const attribution = sessionAttribution(root);
+  const lockRawId =
+    typeof attribution.session_id === 'string' ? attribution.session_id.trim() : '';
+  if (!lockRawId) return {};
+  const processLocal = readProcessLocalSessionIds();
+  if (processLocal.length === 0) return {};
+  return processLocal.includes(lockRawId) ? { ...attribution } : {};
+}
+
+/**
+ * Absolute path of the active `wave-scope.json`, or `null` when none exists.
+ *
+ * The active platform's state dir is tried first (via `resolveStateMdPath()`,
+ * the repo's existing resolver), then the remaining candidates — so a Codex or
+ * Cursor run finds its own manifest rather than a stale `.claude/` one.
+ *
+ * @param {string} root
+ * @returns {string|null}
+ */
+function waveScopePath(root) {
+  const dirs = [];
+  try {
+    dirs.push(path.dirname(resolveStateMdPath(root)));
+  } catch {
+    /* fall through to the fixed candidate list */
+  }
+  for (const dir of STATE_DIR_CANDIDATES) {
+    const abs = path.join(root, dir);
+    if (!dirs.includes(abs)) dirs.push(abs);
+  }
+  for (const dir of dirs) {
+    const candidate = path.join(dir, 'wave-scope.json');
+    try {
+      if (existsSync(candidate)) return candidate;
+    } catch {
+      /* unreadable candidate — try the next one */
+    }
+  }
+  return null;
+}
+
+/**
+ * `{ wave }` from the live wave-scope manifest — `{}` when the manifest is
+ * missing, waveless, or belongs to another session.
+ *
+ * The manifest is a SHARED working-copy artefact (`.claude/wave-scope.json`),
+ * so a peer session's manifest is readable here and would stamp this session's
+ * events with a foreign wave number. Ownership is classified with
+ * `classifyManifestSession()` against the PROCESS-LOCAL id set plus whatever
+ * `attributionForRecord()` actually filled — the same tiering as the session
+ * keys, for the same reason (a shared file cannot prove which process emits):
+ *
+ *   - manifest classified `own` → fill (as a NUMBER, see below).
+ *   - anything else → omit. That includes an UNBOUND manifest (no `session_id` /
+ *     `semantic_session_id`): since #1123 BOTH writers stamp the binding, so a
+ *     manifest without one is a peer's or a stale artefact, never a legacy own
+ *     one. It also includes `unknown` because we cannot resolve our own
+ *     identity — stricter than `classifyManifestSession()`'s own `unknown`
+ *     doctrine on purpose: a wave number is data on the record, not a feature
+ *     gate, so "cannot tell" must not become "stamp it anyway".
+ *
+ * @param {string} root
+ * @param {{session_id?: string, semantic_session_id?: string}} attribution
+ * @returns {{wave?: number}}
+ */
+function waveForRecord(root, attribution) {
+  let scope;
+  try {
+    const file = waveScopePath(root);
+    if (!file) return {};
+    scope = JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return {};
+  }
+  // The ledger's `wave` is numeric in 1876 of 1876 live records; a manifest
+  // carrying `"wave": "3"` used to write the STRING through verbatim and split
+  // every downstream group-by. Coerce, and omit anything that is not an integer
+  // (`"abc"`, `2.5`) rather than writing a NaN or a fraction.
+  const waveNum = Number(scope?.wave);
+  if (scope?.wave === null || scope?.wave === '' || !Number.isInteger(waveNum)) return {};
+
+  const ownIds = new Set([
+    ...readProcessLocalSessionIds(),
+    ...[attribution.session_id, attribution.semantic_session_id].filter(Boolean),
+  ]);
+  const { verdict } = classifyManifestSession(scope, ownIds);
+  return verdict === 'own' ? { wave: waveNum } : {};
+}
+
 /**
  * Append a JSONL event record and optionally POST to the Clank Event Bus webhook.
  *
- * Writes `{ts, event, ...payload}` as a single JSON line to
- * `.orchestrator/metrics/events.jsonl` (creates parent directory if needed).
+ * Writes `{timestamp, event, schema_version, ...payload}` as a single JSON line
+ * to `.orchestrator/metrics/events.jsonl` (creates parent directory if needed).
  * If both `CLANK_EVENT_SECRET` and `CLANK_EVENT_URL` are set, fires an async
  * fire-and-forget POST to `CLANK_EVENT_URL` with a 3-second timeout. Network
  * errors are swallowed. Write errors propagate to the caller. No personal-domain
  * default URL exists — both vars must be set explicitly (#228).
  *
+ * Validation + versioning (#1177). Every record is stamped via
+ * `stampEventSchemaVersion()` (the schema module's own stamper — it fills the
+ * field only when absent, so a caller keeps authority over it) and run through
+ * `validateEventRecord()` BEFORE any side effect. An invalid record throws
+ * `EventValidationError` and produces NO ledger line and NO webhook POST —
+ * a malformed event is dropped at the producer rather than written and
+ * discovered by a downstream reader. The stamp is applied AFTER the payload
+ * spread, and still yields to it: the helper fills the field only when it is
+ * absent or null, so a caller supplying its own `schema_version` wins.
+ *
+ * Correlation envelope (#1177 FA3). When the payload carries neither session
+ * key, `session_id`/`semantic_session_id` are filled from
+ * {@link attributionForRecord}; when it carries no `wave`, `wave` is filled
+ * from the OWN wave-scope manifest. Both are additive and omitted whenever
+ * ownership is unproven — see the module header for the three rules.
+ *
+ * The webhook body deliberately stays `{ event_type, source, payload }` with the
+ * RAW payload — the wire format is a published contract with an external
+ * consumer; `schema_version` describes the JSONL record, not the webhook
+ * envelope, and is not added to it.
+ *
  * @param {string} type — event type (e.g. "orchestrator.session.started")
  * @param {object} [payload={}] — additional fields shallow-merged into the record
  * @param {object} [opts={}] — emission options.
@@ -95,8 +308,44 @@ export function sessionAttribution(repoRoot) {
  * @returns {Promise<void>}
  */
 export async function emitEvent(type, payload = {}, opts = {}) {
-  // Build the JSONL record: ts + event come first, payload spreads last.
-  const record = { timestamp: new Date().toISOString(), event: type, ...payload };
+  // Correlation envelope (#1177 FA3) — computed against the SAME root the line
+  // is pinned to. Both fills are gated on the payload NOT already carrying the
+  // key, and both spread BEFORE `payload`, so a caller always wins twice over.
+  // A payload that supplies EITHER session key suppresses BOTH: mixing a
+  // caller's `session_id` with a lock-derived `semantic_session_id` would
+  // silently produce a record whose two id fields name different sessions.
+  const attributionRoot = opts.repoRoot ?? getProjectDir();
+  const correlation = {};
+  if (payload.session_id === undefined && payload.semantic_session_id === undefined) {
+    Object.assign(correlation, attributionForRecord(attributionRoot));
+  }
+  if (payload.wave === undefined) {
+    Object.assign(correlation, waveForRecord(attributionRoot, correlation));
+  }
+
+  // Build the JSONL record: timestamp + event first, payload spreads last, and
+  // `stampEventSchemaVersion()` — the schema module's own stamper, which only
+  // fills an ABSENT/null field — adds the version. Routing through the helper
+  // instead of inlining `schema_version: CURRENT_SCHEMA_VERSION` keeps the
+  // stamp rule in ONE place: a caller-supplied version still wins, because the
+  // helper never overwrites a value the spread already put there.
+  const record = stampEventSchemaVersion({
+    timestamp: new Date().toISOString(),
+    event: type,
+    ...correlation,
+    ...payload,
+  });
+
+  // Validate BEFORE any side effect — no line, no directory, no webhook (#1177).
+  const verdict = validateEventRecord(record);
+  if (!verdict.valid) {
+    throw new EventValidationError(
+      `invalid event record for "${String(type)}": ${verdict.errors.join('; ')}`,
+      verdict.errors,
+      typeof type === 'string' ? type : undefined,
+    );
+  }
+
   const line = JSON.stringify(record) + '\n';
 
   // Ensure the destination directory exists before appending. Resolution order:

package/scripts/lib/evolve/autonomy-verdict.mjs

@@ -223,10 +223,15 @@ function readinessConfidence(autopilotSummary, judgmentSummary, score) {
 /**
  * Summarize autopilot run history plus type-8 mode effectiveness rollups.
  *
- * Abandoned-session filtering (#834): `sessions` is passed straight through
- * to `groupByMode()`, which filters phantom `status: 'abandoned'` stubs
- * before bucketing — this function inherits that guarantee transitively and
- * does not duplicate the filter. See `autopilot-effectiveness.mjs` `groupByMode()`.
+ * Abandoned-session filtering (#834) AND duplicate-identity collapse (#1167):
+ * `sessions` is passed straight through to `groupByMode()`, which canonicalizes
+ * the array (one record per physical session) and then filters phantom
+ * `status: 'abandoned'` stubs before bucketing — this function inherits BOTH
+ * guarantees transitively and duplicates neither. The abandoned filter alone
+ * was not enough: a `supersedes` pair and an exact same-id duplicate are two
+ * records of one session that both survive it. See
+ * `autopilot-effectiveness.mjs` `groupByMode()` (which canonicalizes via
+ * `canonicalizeSessions(sessions, { keepUnidentified: true })` before filtering).
  *
  * @param {Array} autopilotRuns
  * @param {Array} sessions

package/scripts/lib/evolve/autopilot-effectiveness.mjs

@@ -27,6 +27,7 @@
 import { randomUUID } from 'node:crypto';
 
 import { filterRealSessions } from '../session-schema.mjs';
+import { canonicalizeSessions } from '../sessions-canonical.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -181,7 +182,23 @@ export function groupByMode(autopilotRuns, sessions) {
   const out = new Map();
   if (!Array.isArray(sessions) || sessions.length === 0) return out;
 
-  const realSessions = filterRealSessions(sessions);
+  // Canonicalize BEFORE filtering (#1167). `filterRealSessions` drops phantom
+  // `abandoned` stubs, but two records of ONE physical session that are both
+  // real survive it — a `supersedes` pair (the backfilled stub plus the
+  // authoritative `completed` record that refutes it) and an exact same-id
+  // duplicate line both do. Each of those inflates `n_manual` / `n_autopilot`
+  // and skews every mean computed from the bucket, so the identity collapse
+  // has to happen first; the two compose in exactly this order (see
+  // `sessions-canonical.mjs` § "What this module does not do").
+  //
+  // `keepUnidentified: true` because effectiveness analysis must not LOSE the
+  // id-less rows `canonicalizeSessions` drops by default: legacy ledger rows
+  // and every in-repo fixture of the pre-id era carry `session_type` and
+  // metrics but no id, and dropping them would silently shrink `n_manual`
+  // instead of de-duplicating it.
+  const realSessions = filterRealSessions(
+    canonicalizeSessions(sessions, { keepUnidentified: true }),
+  );
   if (realSessions.length === 0) return out;
 
   // Optional: known autopilot_run_id set for stricter pairing. Empty set means

package/scripts/lib/frontmatter-guard.mjs

@@ -1,7 +1,8 @@
 /**
  * Frontmatter-Guard library (issue #328).
  *
- * Reads the canonical vault-frontmatter Zod schema source and exposes helpers
+ * Reads the canonical vault-frontmatter Zod schema source — when a
+ * projects-baseline checkout is reachable on this host — and exposes helpers
  * for generating a contextual schema snippet that can be injected into agent
  * prompts before vault-write tasks.
  *
@@ -10,15 +11,103 @@
  */
 
 import { digestSha256Short } from './crypto-digest-utils.mjs';
+import { resolveHostPath } from './config/host-paths.mjs';
 import { readFileSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
-/** Absolute path to the canonical vault-frontmatter schema source. */
-const SCHEMA_SOURCE_PATH = join(
-  homedir(),
-  'Projects/projects-baseline/packages/zod-schemas/src/vault-frontmatter.ts',
-);
+/** Path of the schema source RELATIVE to a projects-baseline checkout root. */
+const SCHEMA_REL_PATH = 'packages/zod-schemas/src/vault-frontmatter.ts';
+
+/** This file lives at `<repoRoot>/scripts/lib/` — two levels up is the repo root. */
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+/**
+ * Candidate projects-baseline checkout roots.
+ *
+ * The baseline is OPTIONAL and PRIVATE (see `docs/baseline.md`), so this list
+ * must never assume a particular operator layout — it carries no host-specific
+ * directory names.
+ *
+ * When the host-local override (`SO_BASELINE_PATH` / `owner.yaml`
+ * `paths.baseline-path`) is set it is used ALONE: probing past a wrong explicit
+ * value would silently read a DIFFERENT baseline than the one named. Degrading
+ * to `null` (and the documented fallback enum set) is the honest outcome there.
+ * Only when nothing is configured do the two CONVENTIONS apply — the sibling
+ * checkout `scripts/sync-vault-schema.mjs` already uses, then the legacy
+ * `~/Projects` default this module shipped with.
+ *
+ * @returns {string[]}
+ */
+function baselineCandidates() {
+  const configured = resolveHostPath('baseline-path', null);
+  if (typeof configured === 'string' && configured.trim() !== '') return [configured.trim()];
+  return [
+    resolve(REPO_ROOT, '..', 'projects-baseline'),
+    join(homedir(), 'Projects', 'projects-baseline'),
+  ];
+}
+
+/** @type {{ resolved: boolean, value: string|null }} */
+const _pathCache = { resolved: false, value: null };
+
+/**
+ * Resolve the canonical vault-frontmatter schema source, or `null` when no
+ * baseline checkout is reachable on this host.
+ *
+ * Ceiling: at most two `statSync` calls per invocation, and the result is
+ * memoised for the process lifetime. Revisit if the candidate list ever grows
+ * past a handful of entries — then it needs a real search, not a probe loop.
+ *
+ * @param {{ refresh?: boolean }} [opts] — `refresh: true` re-probes (tests only)
+ * @returns {string|null}
+ */
+export function resolveSchemaSourcePath({ refresh = false } = {}) {
+  if (!refresh && _pathCache.resolved) return _pathCache.value;
+  let found = null;
+  for (const base of baselineCandidates()) {
+    const candidate = join(base, SCHEMA_REL_PATH);
+    try {
+      if (statSync(candidate).isFile()) {
+        found = candidate;
+        break;
+      }
+    } catch {
+      /* candidate absent — try the next one */
+    }
+  }
+  _pathCache.resolved = true;
+  _pathCache.value = found;
+  return found;
+}
+
+/**
+ * Fallback enum/field set used when no baseline checkout is reachable.
+ *
+ * Values mirror `skills/vault-sync/validator.mjs` (`vaultNoteTypeSchema` /
+ * `vaultNoteStatusSchema`), which is this repo's own in-tree copy of the
+ * canonical schema and is what `vault-sync` actually validates against. Using
+ * it means a baseline-less host injects a snippet the local validator accepts,
+ * rather than throwing.
+ */
+const FALLBACK_SCHEMA = Object.freeze({
+  typeEnum: Object.freeze([
+    'note', 'daily', 'project', 'person', 'reference',
+    'idea', 'learning', 'session', 'peer-card', 'board',
+  ]),
+  statusEnum: Object.freeze([
+    'draft', 'active', 'verified', 'archived', 'production',
+    'mvp', 'idea', 'maintenance', 'planned', 'paused', 'dead',
+  ]),
+  requiredFields: Object.freeze(['id', 'type', 'created', 'updated']),
+  idRegex: '^[a-z0-9]+(?:-[a-z0-9]+)*$',
+  tagsRegex: '^[a-z0-9]+(?:-[a-z0-9]+)*(?:/[a-z0-9]+(?:-[a-z0-9]+)*)*$',
+  schemaText: null,
+});
+
+/** One WARN per process, not one per call — the condition is constant. */
+let _warnedFallback = false;
 
 /**
  * In-memory mtime cache so repeated calls within a single process invocation
@@ -93,9 +182,12 @@ function _parseSchema(text) {
  * @returns {{ typeEnum: string[], statusEnum: string[], requiredFields: string[], idRegex: string, tagsRegex: string, schemaText: string } | null}
  */
 export function readVaultSchema() {
+  const sourcePath = resolveSchemaSourcePath();
+  if (sourcePath === null) return null;
+
   let mtime;
   try {
-    mtime = statSync(SCHEMA_SOURCE_PATH).mtimeMs;
+    mtime = statSync(sourcePath).mtimeMs;
   } catch {
     // File missing or inaccessible
     return null;
@@ -107,7 +199,7 @@ export function readVaultSchema() {
 
   let text;
   try {
-    text = readFileSync(SCHEMA_SOURCE_PATH, 'utf8');
+    text = readFileSync(sourcePath, 'utf8');
   } catch {
     return null;
   }
@@ -122,10 +214,17 @@ export function readVaultSchema() {
  * Compute an 8-character SHA-256 hex prefix of the given schema source text.
  * Stable across calls for the same input — useful as a cache-busting token.
  *
- * @param {string} schemaText
- * @returns {string}
+ * Returns `null` when there is NO schema text (absent baseline checkout,
+ * `readVaultSchema()` → `null`). Hashing "nothing" previously produced
+ * `e3b0c442` — the SHA-256 of the empty string — which is a real-looking token
+ * that compares equal across every baseline-less host, so a cache keyed on it
+ * would report "schema unchanged" while having measured nothing at all.
+ *
+ * @param {string|null|undefined} schemaText
+ * @returns {string|null} 8-char hex prefix, or `null` when there is no schema
  */
 export function computeSchemaHash(schemaText) {
+  if (typeof schemaText !== 'string' || schemaText.length === 0) return null;
   return digestSha256Short(schemaText);
 }
 
@@ -133,11 +232,30 @@ export function computeSchemaHash(schemaText) {
  * Generate a deterministic Markdown snippet documenting the vault frontmatter
  * schema, suitable for injection into agent prompts before vault-write tasks.
  *
- * @param {{ typeEnum: string[], statusEnum: string[], requiredFields: string[], idRegex: string, tagsRegex: string }} schema
+ * Degrades instead of throwing when no schema is available: a host without a
+ * projects-baseline checkout gets `readVaultSchema() === null`, and destructuring
+ * that killed the caller with `Cannot destructure property 'typeEnum' of
+ * 'schema' as it is undefined`. The guard below falls back to FALLBACK_SCHEMA
+ * and warns ONCE on stderr — an injected snippet that is one schema-version
+ * behind is worth incomparably more than a crashed pre-dispatch hook.
+ *
+ * @param {{ typeEnum: string[], statusEnum: string[], requiredFields: string[], idRegex: string, tagsRegex: string }|null} [schema]
  * @returns {string}
  */
 export function generateFrontmatterSnippet(schema) {
-  const { typeEnum, statusEnum, requiredFields, idRegex, tagsRegex: _tagsRegex } = schema;
+  let source = schema;
+  if (source === null || typeof source !== 'object') {
+    if (!_warnedFallback) {
+      _warnedFallback = true;
+      process.stderr.write(
+        'frontmatter-guard: no projects-baseline schema reachable — using the in-module ' +
+          'fallback enum set (see docs/baseline.md). Set SO_BASELINE_PATH or ' +
+          'owner.yaml paths.baseline-path to read the canonical schema.\n',
+      );
+    }
+    source = FALLBACK_SCHEMA;
+  }
+  const { typeEnum, statusEnum, requiredFields, idRegex, tagsRegex: _tagsRegex } = source;
 
   const typeList = typeEnum.map((v) => `\`${v}\``).join(' | ');
   const statusList = statusEnum.map((v) => `\`${v}\``).join(' | ');

package/scripts/lib/gates/gate-full.mjs

@@ -9,6 +9,7 @@ import {
   runCheck,
   extractCount,
   extractTestCounts,
+  extractFailedTestFiles,
   collectDebugArtifacts,
 } from './gate-helpers.mjs';
 
@@ -64,11 +65,26 @@ const testCounts =
 // from a measured one — with `suite_died: false` derived from it, stating a
 // verdict nobody had checked. Absent, not zero: the same contract this
 // envelope's `counts` field already keeps (`admitSuiteCounts`).
+//
+// `failed_files` (this change) is the fifth member of that same set and joins
+// it for the same reason: it is DERIVED from the runner's file-level report, so
+// it is published exactly when the file-level measurement exists. A count with
+// no name is what made the 2026-09-06 pre-push block unusable —
+// `files_failed: 1` out of 662, and reconstructing WHICH file cost a manual
+// re-materialisation of the tracked tree. An EMPTY array here is meaningful and
+// is NOT the absent case: it says the file-level summary was parsed and no path
+// could be read out of it (a non-vitest reporter, a truncated capture), which
+// is a parser gap worth seeing — the unmeasured case is the absent key.
+const failedTestFiles = testResult.status === 'fail'
+  ? extractFailedTestFiles(testResult.fullOutput ?? testResult.output ?? '')
+  : [];
+
 const fileFields = testCounts.files
   ? {
       files_total: testCounts.files.total,
       files_passed: testCounts.files.passed,
       files_failed: testCounts.files.failed,
+      failed_files: failedTestFiles,
       // Self-diagnosing: true exactly when `status: 'fail'` sits beside a
       // test-case `failed: 0` that a file-level failure explains. Greppable —
       // a consumer no longer has to recompute the contradiction by hand.
@@ -154,6 +170,16 @@ const failed = [tcResult, testResult, lintResult].some(
 // of silence" the hook promises still holds; and the operator gets the failure
 // at the moment of the block instead of a second run to find it.
 if (failed) {
+  // Names FIRST, raw output after. Under the pre-push hook the raw block is
+  // hundreds of lines; the operator reads the top of it, and the one fact he
+  // needs to act (`npx vitest run <file>`) must not sit at the bottom.
+  if (failedTestFiles.length > 0) {
+    process.stderr.write(
+      `\n──── failing test files (${failedTestFiles.length}) ────\n` +
+        failedTestFiles.map((f) => `  ${f}\n`).join('') +
+        `  reproduce: npx vitest run ${failedTestFiles.join(' ')}\n`,
+    );
+  }
   for (const [name, result] of [
     ['typecheck', tcResult],
     ['test', testResult],