session-orchestrator 3.24.0 → 4.0.0

package/scripts/lib/dispatcher/rank.mjs

@@ -29,12 +29,12 @@
  * @typedef {{ repoRoot: string, repoName: string, free: boolean, status: 'frei'|'in-progress'|'force-closed', heartbeat: string|null, sessionId: string|null }} Candidate
  */
 
-import { readFileSync } from 'node:fs';
 import path from 'node:path';
 
 import { scanBacklog } from '../backlog-scan.mjs';
 import { checkCiStatus as realCheckCiStatus } from '../ci-status-banner.mjs';
 import { probe as realProbe, evaluate as realEvaluate, DEFAULT_RESOURCE_THRESHOLDS as CANONICAL_RESOURCE_THRESHOLDS } from '../resource-probe.mjs';
+import { readCanonicalSessions } from '../sessions-canonical.mjs';
 import { isRealSession } from '../session-schema/filters.mjs';
 
 /** Staleness cap (days). Beyond this, additional age does not raise the score. */
@@ -154,17 +154,29 @@ async function defaultFetchPriority(repoRoot, nowMs) {
 
 /**
  * Default STALENESS source: read `<repoRoot>/.orchestrator/metrics/sessions.jsonl`,
- * find the last REAL (non-phantom) record scanning backward from the tail, and
- * compute days since `completed_at` (fallback `started_at`). No file / no
- * parsable REAL record / no timestamp ⇒ `STALENESS_CAP_DAYS` (treat as
- * maximally stale = most worthwhile).
+ * find the MOST RECENT REAL (non-phantom) record's timestamp, and compute days
+ * since `completed_at` (fallback `started_at`). No file / no parsable REAL
+ * record / no timestamp ⇒ `STALENESS_CAP_DAYS` (treat as maximally stale =
+ * most worthwhile).
  *
- * Scans backward PAST any trailing `status: 'abandoned'` phantom stubs (#834)
- * — session-close-backfill writes these for sessions that ended without a real
- * close (0 waves, seconds of runtime). Stopping at the raw last LINE would let
- * a single recent phantom make a genuinely neglected repo look freshly
- * touched, defeating the dispatcher's whole purpose (this is the N=1 extreme
- * case of the phantom-tail problem — one stub is enough to zero out staleness).
+ * Skips `status: 'abandoned'` phantom stubs (#834) — session-close-backfill
+ * writes these for sessions that ended without a real close (0 waves, seconds
+ * of runtime). Counting one would let a single recent phantom make a
+ * genuinely neglected repo look freshly touched, defeating the dispatcher's
+ * whole purpose (this is the N=1 extreme case of the phantom-tail problem —
+ * one stub is enough to zero out staleness).
+ *
+ * #1209: takes the MAX timestamp over every canonical REAL record instead of
+ * scanning backward through raw file lines from the tail. A raw backward scan
+ * trusts FILE POSITION as a proxy for recency, which silently breaks the
+ * moment a backfill/repair writer appends an OLDER record after genuinely
+ * newer ones already exist — `session-record-repair.mjs` and
+ * `migrate-sessions-jsonl.mjs` both do this by design (see
+ * `sessions-canonical.mjs`'s module header, "by-design raw" list). A
+ * duplicated `session_id` re-appended late at the tail would make the old
+ * backward scan report the STALE re-append's date instead of the genuinely
+ * newer session's date; `readCanonicalSessions` collapses the duplicate to
+ * one record first, so the max-reduce below sees only the true timestamps.
  *
  * @param {string} repoRoot
  * @param {number} nowMs
@@ -173,33 +185,21 @@ async function defaultFetchPriority(repoRoot, nowMs) {
 async function defaultStaleDaysFor(repoRoot, nowMs) {
   try {
     const file = path.join(repoRoot, '.orchestrator', 'metrics', 'sessions.jsonl');
-    const raw = readFileSync(file, 'utf8');
-    const lines = raw.split('\n').map((l) => l.trim()).filter(Boolean);
-    if (lines.length === 0) return STALENESS_CAP_DAYS;
-
-    // Scan backward for the last REAL (non-abandoned) session record, skipping
-    // both corrupt lines and phantom stubs.
-    let last = null;
-    for (let i = lines.length - 1; i >= 0; i -= 1) {
-      let parsed;
-      try {
-        parsed = JSON.parse(lines[i]);
-      } catch {
-        continue; // Skip a corrupt line and try the previous one.
-      }
-      if (isRealSession(parsed)) {
-        last = parsed;
-        break;
-      }
+    const records = readCanonicalSessions({ filePath: file });
+    if (records.length === 0) return STALENESS_CAP_DAYS;
+
+    let latestMs = null;
+    for (const rec of records) {
+      if (!isRealSession(rec)) continue;
+      const iso = rec.completed_at || rec.started_at || null;
+      if (!iso || typeof iso !== 'string') continue;
+      const t = Date.parse(iso);
+      if (Number.isNaN(t)) continue;
+      if (latestMs === null || t > latestMs) latestMs = t;
     }
-    if (!last || typeof last !== 'object') return STALENESS_CAP_DAYS;
-
-    const iso = last.completed_at || last.started_at || null;
-    if (!iso || typeof iso !== 'string') return STALENESS_CAP_DAYS;
-    const t = Date.parse(iso);
-    if (Number.isNaN(t)) return STALENESS_CAP_DAYS;
+    if (latestMs === null) return STALENESS_CAP_DAYS;
 
-    const days = (nowMs - t) / MS_PER_DAY;
+    const days = (nowMs - latestMs) / MS_PER_DAY;
     return days > 0 ? days : 0;
   } catch {
     // No sessions file (or unreadable) ⇒ never worked on ⇒ maximally stale.
@@ -209,21 +209,75 @@ async function defaultStaleDaysFor(repoRoot, nowMs) {
 
 /**
  * Default READINESS (CI) source: thin wrapper over `checkCiStatus`.
- * Returns the 'green'|'red'|'unknown' status string, or null (no-op).
- * null / 'unknown' are treated as non-blocking by `scoreCandidate`.
+ *
+ * Passes the probe's result through VERBATIM rather than flattening it to a
+ * status string (#1031 follow-up). `checkCiStatus` has THREE return states —
+ * `null` (benign absence), `{status, …}` (a real reading), and
+ * `{severity:'warn', degraded:<reason>}` (the state could NOT be read) — and
+ * the old `typeof result.status === 'string' ? result.status : null` collapsed
+ * the third onto the first. That was not a scoring bug (both are non-blocking)
+ * but it discarded the one thing the operator needs to know: the ranking was
+ * computed WITHOUT a CI reading, and why. {@link normalizeCiSignal} in
+ * `rankCandidates` performs the shape reduction and keeps the reason.
+ *
+ * A THROW is the fourth state, and it is NOT the first: `checkCiStatus` is
+ * documented never to throw, so an exception here means the probe itself broke
+ * (a bad import, an unexpected runtime error). Returning `null` for it would
+ * assert measured ABSENCE — the one thing we know is false. It is mapped to the
+ * degraded shape instead, so {@link normalizeCiSignal} surfaces it as
+ * `ciStatus: 'unknown'` + `ciDegraded: 'probe-threw'` rather than silently.
  *
  * @param {{ repoRoot: string }} args
- * @returns {Promise<'green'|'red'|'unknown'|null>}
+ * @returns {Promise<'green'|'red'|'unknown'|null|object>} raw probe result.
  */
 async function defaultCheckCiStatus({ repoRoot }) {
   try {
-    const result = await realCheckCiStatus({ repoRoot });
-    return result && typeof result.status === 'string' ? result.status : null;
-  } catch {
-    return null;
+    return (await realCheckCiStatus({ repoRoot })) ?? null;
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    return {
+      severity: 'warn',
+      ok: false,
+      message: `⚠ ci-status: CI probe threw — state UNKNOWN, not "green". ${detail}`,
+      degraded: 'probe-threw',
+    };
   }
 }
 
+/**
+ * Reduce whatever a `checkCiStatus` dep returned to the pair the ranking needs:
+ * a scoring status and — when the state was UNREADABLE — the reason.
+ *
+ * Accepts every shape the dep contract permits, old and new:
+ *   - a bare status string (`'green'`/`'red'`/`'unknown'`) — the shape every
+ *     injected test dep uses; passed through unchanged.
+ *   - `null`/`undefined` — genuine absence, no signal, no reason.
+ *   - `{status: <string>}` — a real reading from `checkCiStatus`.
+ *   - `{degraded: <reason>}` with no usable `status` — the probe FAILED. Mapped
+ *     to `'unknown'`, which `scoreCandidate` already treats as non-blocking
+ *     (`ciFactor` dampens on `'red'` only), so ranking is byte-identical to the
+ *     previous `null` — but the reason survives into `readiness.ciDegraded`
+ *     and into a `warnings` entry.
+ *   - anything else — `null`, as before.
+ *
+ * `ciDegraded` is `null` (and the caller OMITS the key) whenever the state was
+ * readable, so existing strict `toEqual` pins on `signals.readiness` hold.
+ *
+ * @param {unknown} raw
+ * @returns {{ ciStatus: 'green'|'red'|'unknown'|null, ciDegraded: string|null }}
+ */
+export function normalizeCiSignal(raw) {
+  if (typeof raw === 'string' && raw) return { ciStatus: raw, ciDegraded: null };
+  if (!raw || typeof raw !== 'object') return { ciStatus: null, ciDegraded: null };
+  if (typeof raw.status === 'string' && raw.status) {
+    return { ciStatus: raw.status, ciDegraded: null };
+  }
+  if (typeof raw.degraded === 'string' && raw.degraded) {
+    return { ciStatus: 'unknown', ciDegraded: raw.degraded };
+  }
+  return { ciStatus: null, ciDegraded: null };
+}
+
 /**
  * Default READINESS (resource) source: probe the host ONCE and evaluate against
  * the canonical default thresholds. This is a HOST-level signal (identical for
@@ -290,7 +344,7 @@ export function defaultDeps() {
  *   ranked: Array<{ candidate: Candidate, score: number, signals: {
  *     priority: { criticalCount: number, highCount: number } | null,
  *     staleDays: number,
- *     readiness: { ciStatus: 'green'|'red'|'unknown'|null, resourceVerdict: 'green'|'warn'|'degraded'|'critical' },
+ *     readiness: { ciStatus: 'green'|'red'|'unknown'|null, resourceVerdict: 'green'|'warn'|'degraded'|'critical', ciDegraded?: string },
  *   } }>,
  *   warnings: string[],
  * }>}
@@ -342,18 +396,40 @@ export async function rankCandidates(freeCandidates, opts = {}) {
       staleDays = STALENESS_CAP_DAYS;
     }
 
-    // READINESS — CI status.
+    // READINESS — CI status. A degraded probe result ("state unknown") is
+    // NON-BLOCKING but not INVISIBLE: it scores like `null`, and reports why.
+    // Declared WITHOUT an initialiser on purpose: both paths below assign, and
+    // a `= null` seed would quietly re-create a fall-through "absent" default.
     let ciStatus;
+    let ciDegraded;
     try {
-      ciStatus = await deps.checkCiStatus({ repoRoot });
+      ({ ciStatus, ciDegraded } = normalizeCiSignal(await deps.checkCiStatus({ repoRoot })));
     } catch {
-      ciStatus = null;
+      // A THROWING dep is not measured ABSENCE. Leaving `ciDegraded` at null
+      // here re-created the exact collapse `normalizeCiSignal` exists to
+      // prevent: the ranking silently proceeded as if no CI signal existed,
+      // when in truth the probe broke. Scoring is unchanged (`'unknown'` is
+      // non-blocking) — only the reason becomes visible.
+      ciStatus = 'unknown';
+      ciDegraded = 'probe-threw';
+    }
+    if (ciDegraded) {
+      warnings.push(
+        `CI state unknown for ${repoName} (${ciDegraded}) — ranked without CI dampening`,
+      );
     }
 
     const signals = {
       priority,
       staleDays,
-      readiness: { ciStatus, resourceVerdict },
+      readiness: {
+        ciStatus,
+        resourceVerdict,
+        // Key OMITTED when the CI state was readable — a strict `toEqual` on
+        // `signals.readiness` must not have to know about a field that only
+        // exists on the failure path.
+        ...(ciDegraded ? { ciDegraded } : {}),
+      },
     };
     const score = scoreCandidate(signals);
 

package/scripts/lib/ecosystem-health.mjs

@@ -164,13 +164,27 @@ async function watchLoop(intervalS) {
 }
 
 /**
+ * Poll delay.
+ *
+ * The timer is deliberately NOT `unref()`d: it is the only handle this process
+ * holds (the two signal handlers do not keep the loop alive), so an unref'd
+ * timer drains the event loop and node exits 0 the instant the first tick is
+ * scheduled — a watcher that supervises nothing while looking like a clean
+ * shutdown, because it exits 0 with an empty stderr. Measured 2026-09-06 on the
+ * unref'd variant: `node scripts/lib/ecosystem-health.mjs --watch --interval=1`
+ * returned exit 0 after 48 ms instead of running until SIGTERM. Third copy of
+ * the #980 defect A1 measured in `scripts/lib/wave-transcript-tail.mjs` and
+ * `scripts/lib/convergence-monitor.mjs`; this one was missed when those two
+ * were fixed. Pinned by a DURATION assertion (an exit-code assertion cannot
+ * tell a healthy monitor from a dead one) in
+ * `tests/lib/ecosystem-health-watch.test.mjs`.
+ *
  * @param {number} ms
  * @returns {Promise<void>}
  */
 function sleep(ms) {
   return new Promise((resolve) => {
-    const t = setTimeout(resolve, ms);
-    t.unref?.();
+    setTimeout(resolve, ms);
   });
 }
 

package/scripts/lib/eval/engine.mjs

@@ -36,6 +36,7 @@ import path from 'node:path';
 
 import { resolvePluginRoot } from '../common.mjs';
 import { readJsonlFile } from '../io.mjs';
+import { readCanonicalSessions } from '../sessions-canonical.mjs';
 import { buildRunId, CURRENT_STANDARD_VERSION, VALID_MODEL_SOURCES } from './schema.mjs';
 import { resolveSession, computeWindow, findPeerOverlap } from './session-resolve.mjs';
 
@@ -538,7 +539,14 @@ export function evaluateSession(opts = {}) {
 
   const sessionsPath = path.join(metricsDir, 'sessions.jsonl');
   const eventsPath = path.join(metricsDir, 'events.jsonl');
-  const records = readJsonlFile(sessionsPath, { skipInvalid: true });
+  // #1209: sessions.jsonl is APPEND-ONLY (the same physical session can carry
+  // more than one line — crash-recovery re-appends, #1068 stub/supersede
+  // pairs), so a raw readJsonlFile() left resolveSession()/findPeerOverlap()
+  // to hand-roll their own dedup over duplicated / phantom-doubled records.
+  // readCanonicalSessions() collapses those first (newest-wins per
+  // session_id, #1068 double-stub collapse, supersede removal) — see
+  // session-resolve.mjs for how that simplifies both callers below.
+  const records = readCanonicalSessions({ filePath: sessionsPath });
   const events = readJsonlFile(eventsPath, { skipInvalid: true });
 
   const { record: session, resolvedVia } = resolveSession(records, sessionId);

package/scripts/lib/eval/session-resolve.mjs

@@ -48,11 +48,17 @@ export function resolveSession(records, sessionId) {
 
   // Explicit selection: the LAST record carrying this session_id (records may be
   // rewritten/backfilled across a session's life; the latest is authoritative).
+  //
+  // #1209: engine.mjs's production caller now passes CANONICAL records
+  // (readCanonicalSessions already resolved newest-wins per session_id before
+  // this array reaches here — see sessions-canonical.mjs), so at most one
+  // record can carry a given id in practice. `resolveSession` stays a
+  // general, pure function — `findLast` keeps the exact "last match wins"
+  // semantics for a caller that hands in raw, un-deduped records directly
+  // (e.g. the unit tests below), while degenerating to a single candidate on
+  // the canonical path.
   if (sessionId) {
-    let match = null;
-    for (const r of records) {
-      if (isPlainObject(r) && r.session_id === sessionId) match = r;
-    }
+    const match = records.findLast((r) => isPlainObject(r) && r.session_id === sessionId) ?? null;
     if (!match) {
       throw new SessionResolutionError(`session not found: ${sessionId}`);
     }
@@ -114,6 +120,19 @@ export function computeWindow(record) {
  * rewrites of the SAME session) are excluded, as are records without a valid
  * window.
  *
+ * #1209: the #1068 double-stub class — two ABANDONED records for ONE physical
+ * session (a real semantic `session_id` + a synthetic backfill twin, sharing
+ * an exact `started_at`/`completed_at` tuple, see `sessions-canonical.mjs`
+ * rule 2) — used to be counted as TWO distinct peers here, because the raw
+ * `records` array carried both lines under different ids and this function has
+ * no way to know they are the same physical session. With engine.mjs's
+ * production caller now passing `readCanonicalSessions()` output,
+ * `collapseAbandonedTuples()` has already dropped the synthetic twin before
+ * this array reaches here — a double-stub pair can therefore no longer
+ * produce a false EXTRA peer (`count` inflated by one) on the canonical path.
+ * `findPeerOverlap` itself stays general/pure for callers (including the unit
+ * tests below) that pass raw, un-deduped records directly.
+ *
  * @param {object[]} records — all sessions.jsonl records.
  * @param {object} resolved — the resolved session record.
  * @returns {{ count: number, peers: string[] }} unique overlapping session_ids.

package/scripts/lib/events.mjs

@@ -41,7 +41,7 @@
 
 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 {
@@ -70,7 +70,7 @@ import {
  * @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');
 }
 
@@ -152,10 +152,26 @@ const STATE_DIR_CANDIDATES = ['.claude', '.codex', '.cursor', '.pi'];
  * 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 = SO_PROJECT_DIR) {
+export function attributionForRecord(root = getProjectDir()) {
   const attribution = sessionAttribution(root);
   const lockRawId =
     typeof attribution.session_id === 'string' ? attribution.session_id.trim() : '';
@@ -209,8 +225,8 @@ function waveScopePath(root) {
  * 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` /
- *     `semantic_session`): since #1123 BOTH writers stamp the binding, so a
+ *   - 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`
@@ -298,7 +314,7 @@ export async function emitEvent(type, payload = {}, opts = {}) {
   // 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 ?? SO_PROJECT_DIR;
+  const attributionRoot = opts.repoRoot ?? getProjectDir();
   const correlation = {};
   if (payload.session_id === undefined && payload.semantic_session_id === undefined) {
     Object.assign(correlation, attributionForRecord(attributionRoot));

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],