session-orchestrator 5.3.0 → 5.5.0

package/scripts/lib/process-group.mjs

@@ -25,22 +25,35 @@
 import { spawn } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import {
-  appendFileSync,
   existsSync,
+  lstatSync,
   mkdirSync,
-  readFileSync,
+  renameSync,
+  unlinkSync,
   writeFileSync,
 } from 'node:fs';
 import path from 'node:path';
 
-import { DEFAULT_KILL_GRACE_MS } from './wave-executor/dispatch-common.mjs';
+import { NOT_A_REGULAR_FILE, appendNoFollow } from './orphan-reaper/no-follow-append.mjs';
+import { readTailWindow } from './tail-window.mjs';
 
 /**
- * Re-exported, never re-defined: the SIGTERM→SIGKILL grace is a repo
- * convention with its own named ceiling in `dispatch-common.mjs`. A second
- * literal here would drift from it silently.
+ * Grace period between SIGTERM and SIGKILL, in ms — the repo's one definition,
+ * used by the gate's group ladder here and by `wave-executor/foreign-dispatch.mjs`
+ * and `remote-dispatch.mjs` through `runChild` (`dispatch-common.mjs`).
+ *
+ * `child.kill('SIGTERM')` is a REQUEST: a child that installs a handler and
+ * ignores it never emits `close`, and `runChild`'s only resolve paths are
+ * `close` and `error` — so without escalation a wedged `cursor-agent` hangs
+ * `dispatchForeign` forever and takes the whole wave with it. SIGKILL is not
+ * catchable, so the escalation always terminates.
+ *
+ * Named ceiling (BV-004): 10 s is enough for a cooperative child to flush its
+ * stream-json tail and exit. Revisit if a well-behaved `cursor-agent` is ever
+ * measured needing longer than that to shut down — raise the constant, never
+ * drop the escalation.
  */
-export { DEFAULT_KILL_GRACE_MS };
+export const DEFAULT_KILL_GRACE_MS = 10_000;
 
 /** Append-only ledger of every gate process THIS repo's orchestrator started.
  * Gitignored via `.gitignore:125` (`.orchestrator/runtime/`), verified with
@@ -478,6 +491,26 @@ function ledgerPathFor(repoRoot) {
   return path.join(repoRoot, ...GATE_PROCESS_LEDGER_RELPATH.split('/'));
 }
 
+/**
+ * Read the whole ledger without following a link and without blocking on a
+ * FIFO: `readTailWindow`'s `noFollow` open with a window larger than any file,
+ * so a regular ledger reads exactly as `readFileSync` read it. A plain
+ * `readFileSync` FOLLOWED a symlinked ledger (a foreign file parsed as kill
+ * candidates) and blocked for good in `open` on a planted FIFO — inside the
+ * gate's own registration path (#1489). THROWS like `readFileSync`: ENOENT,
+ * ELOOP for a symlink, `ERR_NOT_REGULAR_FILE` for a FIFO or directory.
+ *
+ * Named ceiling (BV-004): the file is read whole, as before — fine for a ledger
+ * pruned to 24 h (one line per gate command); revisit if it ever stops being
+ * pruned.
+ *
+ * @param {string} target
+ * @returns {string}
+ */
+function readLedgerNoFollow(target) {
+  return readTailWindow(target, Number.MAX_SAFE_INTEGER, { noFollow: true }).text;
+}
+
 /**
  * Append one {@link GateProcessRecord} to the gate-process ledger.
  *
@@ -487,6 +520,12 @@ function ledgerPathFor(repoRoot) {
  * vanishing (a ledger that silently stops being written is indistinguishable
  * from a host with no gate processes).
  *
+ * The write is {@link appendNoFollow}, never `appendFileSync(path)`: that
+ * followed a symlinked ledger, so every gate registration landed in the link's
+ * target, and its open of a planted FIFO blocked until a reader appeared — the
+ * gate hung in its own registration path (#1489). A link, FIFO, directory or
+ * hard-linked ledger is now refused with the same one WARN line.
+ *
  * @param {string} repoRoot
  * @param {GateProcessRecord} record
  * @param {object} [opts]
@@ -501,7 +540,7 @@ export function recordGateProcess(repoRoot, record, { appendFn } = {}) {
     if (!appendFn) mkdirSync(path.dirname(target), { recursive: true });
     const line = `${JSON.stringify(record)}\n`;
     if (appendFn) appendFn(target, line);
-    else appendFileSync(target, line, 'utf8');
+    else appendNoFollow(target, line);
   } catch (err) {
     process.stderr.write(
       `process-group: could not record gate process in ${GATE_PROCESS_LEDGER_RELPATH}: ${err?.message ?? String(err)}\n`,
@@ -520,14 +559,24 @@ export function recordGateProcess(repoRoot, record, { appendFn } = {}) {
  * counted separately — they are not candidates for anything, and their PIDs are
  * the most likely to have been recycled.
  *
+ * A symlinked, FIFO or otherwise non-regular ledger yields NO records, like an
+ * unreadable one ({@link readLedgerNoFollow}): never a link target's lines as
+ * candidates, never a blocked open — no records name no process group to
+ * signal. But it is not reported as empty (#1498): `state` tells the three
+ * outcomes apart — `read`, `absent` (no ledger yet, the ordinary case) and
+ * `unreadable` (refused or failed) — because the scan's `ledger-unreadable`
+ * skip was unreachable while a refused ledger looked exactly like a clean one.
+ *
  * @param {string} repoRoot
  * @param {object} [opts]
  * @param {(filePath: string) => string} [opts.readFn]  Reader seam; must throw or
  *   return '' for a missing file.
  * @param {number} [opts.nowMs]
  * @param {number} [opts.maxAgeMs]
- * @returns {{records: GateProcessRecord[], malformedLines: number, expired: number}}
- *   `records` are the fresh, parseable entries in source order.
+ * @returns {{records: GateProcessRecord[], malformedLines: number, expired: number,
+ *   state: 'read'|'absent'|'unreadable'}}
+ *   `records` are the fresh, parseable entries in source order; empty unless
+ *   `state` is `read`.
  */
 export function readGateProcessLedger(repoRoot, {
   readFn,
@@ -535,12 +584,19 @@ export function readGateProcessLedger(repoRoot, {
   maxAgeMs = DEFAULT_LEDGER_MAX_AGE_MS,
 } = {}) {
   const target = ledgerPathFor(repoRoot);
-  let raw = '';
+  let raw;
   try {
-    if (readFn) raw = readFn(target) ?? '';
-    else if (existsSync(target)) raw = readFileSync(target, 'utf8');
-  } catch {
-    return { records: [], malformedLines: 0, expired: 0 };
+    // No `existsSync` pre-check: it FOLLOWS a link, so a dangling symlink read
+    // as "no ledger yet" while `appendNoFollow` refused it on every
+    // registration (#1498 review). The no-follow open itself tells the cases
+    // apart — ENOENT only when nothing is at the path.
+    raw = readFn ? (readFn(target) ?? '') : readLedgerNoFollow(target);
+  } catch (err) {
+    // ENOENT: no ledger yet, or one that vanished (or a `readFn` reporting a
+    // missing file). Anything else — ELOOP (a symlink, dangling or not),
+    // ERR_NOT_REGULAR_FILE, EACCES — was refused.
+    const state = err?.code === 'ENOENT' ? 'absent' : 'unreadable';
+    return { records: [], malformedLines: 0, expired: 0, state };
   }
 
   /** @type {GateProcessRecord[]} */
@@ -568,11 +624,48 @@ export function readGateProcessLedger(repoRoot, {
     records.push(parsed);
   }
 
-  return { records, malformedLines, expired };
+  return { records, malformedLines, expired, state: 'read' };
+}
+
+/**
+ * Replace a regular file's contents atomically: write `<target>.tmp-<pid>` in
+ * the same directory, then rename it over the target. Throws instead of
+ * writing when the target is a symlink or not a regular file — the caller turns
+ * that into its one WARN line.
+ *
+ * Why not `writeFileSync(target)`: that truncates first, so a kill between the
+ * truncate and the write leaves the file empty, and it FOLLOWS a symlink — a
+ * ledger linked to `events.jsonl` emptied the link's target (CWE-59, reproduced
+ * 2026-10-01). `rename` replaces the directory entry itself, never a link's
+ * target, and the `wx` flag refuses a pre-planted file or link at the tmp name.
+ * The ONE copy (#1498): `orphan-reaper/reaper-audit.mjs` imports it for the
+ * audit prune — both ledgers its scan housekeeping rewrites. It lives here, not
+ * there, because this module imports nothing from `orphan-reaper/` beyond the
+ * fs-only `no-follow-append.mjs`, so the graph stays acyclic, and every
+ * importer of the audit module already loads this one.
+ *
+ * @param {string} target
+ * @param {string} body
+ * @param {{lstatSync: Function, writeFileSync: Function, renameSync: Function, unlinkSync: Function}} [io]
+ *   fs seam for tests; defaults to `node:fs`.
+ */
+export function replaceRegularFile(target, body, io = { lstatSync, writeFileSync, renameSync, unlinkSync }) {
+  if (!io.lstatSync(target).isFile()) throw new Error(NOT_A_REGULAR_FILE);
+  const tmp = `${target}.tmp-${process.pid}`;
+  try {
+    io.writeFileSync(tmp, body, { encoding: 'utf8', flag: 'wx' });
+    io.renameSync(tmp, target);
+  } catch (err) {
+    // EEXIST: the tmp name belongs to someone else — never remove it.
+    if (err?.code !== 'EEXIST') {
+      try { io.unlinkSync(tmp); } catch { /* nothing was created */ }
+    }
+    throw err;
+  }
 }
 
 /**
- * Drop expired and unusable lines from the ledger, rewriting it in place.
+ * Drop expired and unusable lines from the ledger, rewriting it atomically.
  * "Unusable" is {@link isValidLedgerRecord}'s verdict — the same one
  * {@link readGateProcessLedger} applies, so nothing the reader skips survives
  * the pruner.
@@ -583,6 +676,10 @@ export function readGateProcessLedger(repoRoot, {
  *
  * In-process fs only — never a shell `rm`/`mv` (PSA-003, and
  * `.orchestrator/metrics/**` deletions are a blocked-command rule for a reason).
+ * The read is {@link readLedgerNoFollow} and the rewrite goes through
+ * {@link replaceRegularFile}: a symlinked, FIFO or otherwise non-regular ledger
+ * is refused with one WARN and left untouched — refused at the READ, so a link
+ * target is never read and a FIFO never blocks the gate's registration path.
  *
  * Named ceiling (BV-004): read-filter-write is not atomic against a concurrent
  * append, so a line appended between the read and the write is lost. Acceptable
@@ -595,22 +692,37 @@ export function readGateProcessLedger(repoRoot, {
  * @param {object} [opts]
  * @param {number} [opts.nowMs]
  * @param {number} [opts.maxAgeMs]
- * @param {{existsSync: Function, readFileSync: Function, writeFileSync: Function}} [opts.fs]  fs seam.
+ * @param {{existsSync: Function, readFileSync: Function, writeFileSync: Function,
+ *   lstatSync: Function, renameSync: Function, unlinkSync: Function}} [opts.fs]  fs seam;
+ *   replaces `node:fs` wholesale, so a partial seam fails closed (WARN, 0).
  * @returns {number} Number of lines removed (expired + malformed). 0 when the
- *   ledger is absent, empty, or unreadable.
+ *   ledger is absent, empty, unreadable, or not a regular file.
  */
 export function pruneGateProcessLedger(repoRoot, {
   nowMs = Date.now(),
   maxAgeMs = DEFAULT_LEDGER_MAX_AGE_MS,
   fs: fsSeam,
 } = {}) {
-  const io = fsSeam ?? { existsSync, readFileSync, writeFileSync };
+  const io = fsSeam ?? {
+    existsSync,
+    readFileSync: readLedgerNoFollow,
+    writeFileSync,
+    lstatSync,
+    renameSync,
+    unlinkSync,
+  };
   const target = ledgerPathFor(repoRoot);
   let raw;
   try {
     if (!io.existsSync(target)) return 0;
     raw = io.readFileSync(target, 'utf8');
-  } catch {
+  } catch (err) {
+    // A refused ledger (ELOOP: a symlink; ERR_NOT_REGULAR_FILE: a FIFO, a
+    // directory) gets the same one WARN the rewrite gives it; an unreadable or
+    // vanished one stays silent, as before.
+    if (err?.code === 'ELOOP' || err?.code === 'ERR_NOT_REGULAR_FILE') {
+      process.stderr.write(`process-group: could not prune ${GATE_PROCESS_LEDGER_RELPATH}: ${NOT_A_REGULAR_FILE}\n`);
+    }
     return 0;
   }
 
@@ -634,7 +746,7 @@ export function pruneGateProcessLedger(repoRoot, {
 
   if (removed === 0) return 0;
   try {
-    io.writeFileSync(target, kept.length > 0 ? `${kept.join('\n')}\n` : '', 'utf8');
+    replaceRegularFile(target, kept.length > 0 ? `${kept.join('\n')}\n` : '', io);
   } catch (err) {
     process.stderr.write(
       `process-group: could not prune ${GATE_PROCESS_LEDGER_RELPATH}: ${err?.message ?? String(err)}\n`,

package/scripts/lib/project-hygiene.mjs

@@ -462,7 +462,9 @@ export function checkStaleArtifacts(repoRoot, ageDays = DEFAULT_ARTIFACT_AGE_DAY
  * H4 — CI configuration hygiene.
  *
  * Measured 5/6. Checks locally declared executable commands without evaluating
- * pipeline conditions or external includes. The dependency-audit gap is the load-bearing one: three
+ * pipeline conditions or external includes; when no local audit step is found
+ * but `.gitlab-ci.yml` declares `include:`, the finding is downgraded to an
+ * unverifiable, non-fixable one. The dependency-audit gap is the load-bearing one: three
  * of the tested repos carried known-vulnerable dependencies that no pipeline
  * would ever surface.
  *
@@ -506,6 +508,24 @@ export function checkCiConfig(repoRoot) {
   }
 
   if (ciConfigs.some(({ text }) => text) && !ciConfigs.some(hasAuditStep)) {
+    // Jobs supplied via include: (component/local/project/remote/template) are
+    // never resolved, so an audit may exist there — report it as unverifiable.
+    let includes = 0;
+    try {
+      const gitlabText = hasGitlab ? ciConfigs[0].text : '';
+      const include = yaml.loadAll(gitlabText, undefined, { schema: GITLAB_SCHEMA }).filter(isConfigMap).at(-1)?.include;
+      includes = Array.isArray(include) ? include.length : include ? 1 : 0;
+    } catch {
+      /* unparseable config — keep the plain missing-audit finding */
+    }
+    if (includes > 0) {
+      findings.push({
+        check: 'ci-audit-job',
+        fixable: false,
+        message: `CI dependency-audit step could not be verified: ${includes} include(s) not evaluated (.gitlab-ci.yml include:)`,
+      });
+      return findings;
+    }
     findings.push({
       check: 'ci-audit-job',
       fixable: true,

package/scripts/lib/quality-gate.mjs

@@ -63,7 +63,7 @@
 
 import { spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { emitEvent, sessionAttribution } from './events.mjs';
@@ -120,7 +120,8 @@ const GATE_TIMEOUT_MS = DEFAULT_GATE_TIMEOUT_MS;
  * @returns {string}
  */
 function resolveRepoRoot(explicit) {
-  if (typeof explicit === 'string' && explicit.trim()) return explicit;
+  // Absolute on purpose: emitEvent refuses a relative root (#1468).
+  if (typeof explicit === 'string' && explicit.trim()) return resolve(explicit);
   return process.cwd();
 }
 
@@ -773,13 +774,44 @@ function coerceMaxRetries(n) {
 // Public API
 // ---------------------------------------------------------------------------
 
+/**
+ * The kill-ladder fields of a `quality_gate.passed/.failed` record (#1439).
+ *
+ * ONE builder for BOTH emitters — this library's {@link emitGateEvent} and the
+ * `scripts/run-quality-gate.mjs` CLI — so the two can never publish different
+ * shapes under the same keys. From THIS builder all three keys are always
+ * present: `timed_out` `false`, `survivors` `0` and `kill_signals` `[]` are
+ * measurements ("not killed"), unlike `counts`, whose absence means "not
+ * measured". The CLI then passes the result through `joinGateKillFields()`
+ * (`scripts/lib/gates/gate-helpers.mjs`, #1457), which OR-joins the inner
+ * per-command ladders and MAY omit the three keys when that inner side was
+ * not measured and the outer ladder did not fire.
+ *
+ * - `timed_out` — the run hit its wall-clock ceiling and was killed (exit 124).
+ * - `survivors` — how many pids were still alive after the SIGKILL step; the
+ *   pids themselves stay in the gate output / diagnostics bundle.
+ * - `kill_signals` — the signals actually sent, in order (`SIGTERM`, `SIGKILL`).
+ *   Copied, because `spawnInGroup` records them at send time into a live array.
+ *
+ * @param {{timedOut?: boolean, killSignals?: string[], survivors?: number[]}|null|undefined} run
+ * @returns {{timed_out: boolean, survivors: number, kill_signals: string[]}}
+ */
+export function gateKillFields(run) {
+  return {
+    timed_out: run?.timedOut === true,
+    survivors: Array.isArray(run?.survivors) ? run.survivors.length : 0,
+    kill_signals: Array.isArray(run?.killSignals) ? [...run.killSignals] : [],
+  };
+}
+
 /**
  * Emit exactly one `orchestrator.quality_gate.{passed,failed}` event per
  * `runQualityGateWithRetry` CALL (#928b).
  *
  * NO DOUBLE-COUNTING. The two gate paths never nest:
  *   - `scripts/run-quality-gate.mjs` spawns `scripts/lib/gates/gate-*.mjs`
- *     directly and does not import this module;
+ *     directly; it imports only the pure `gateKillFields` helper from this
+ *     module, never `runQualityGateWithRetry`, so it never reaches this emitter;
  *   - this module spawns the resolved gate COMMANDS (and `parse-config.mjs`)
  *     directly and does not invoke that wrapper.
  * A single run therefore passes through exactly one emitter.
@@ -846,8 +878,13 @@ function coerceMaxRetries(n) {
  * @param {number} attempts
  * @param {string|null} gate
  * @param {{passed: number, failed: number, total: number}|null} [counts]
+ * @param {{timedOut?: boolean, killSignals?: string[], survivors?: number[]}|null} [killRun]
+ *   the run that decided the verdict — the last attempt's failing gate; `null`
+ *   on the passing path, where every gate exited 0 and so none was killed
+ *   (`spawnInGroup` only starts its kill ladder on timeout or overflow, and
+ *   both force a non-zero exit code).
  */
-async function emitGateEvent(repoRoot, ok, attempts, gate, counts) {
+async function emitGateEvent(repoRoot, ok, attempts, gate, counts, killRun = null) {
   try {
     await emitEvent(
       `orchestrator.quality_gate.${ok ? 'passed' : 'failed'}`,
@@ -857,6 +894,7 @@ async function emitGateEvent(repoRoot, ok, attempts, gate, counts) {
         attempts,
         ...(gate ? { gate } : {}),
         ...(counts ? { counts } : {}),
+        ...gateKillFields(killRun),
         ...sessionAttribution(repoRoot),
       },
       { repoRoot },
@@ -985,6 +1023,8 @@ export async function runQualityGateWithRetry(opts) {
         exitCode: result.exitCode,
         output: result.output,
         timedOut: result.timedOut,
+        killSignals: result.killSignals,
+        survivors: result.survivors,
         command: cmd,
         attempt,
       };
@@ -1063,7 +1103,7 @@ export async function runQualityGateWithRetry(opts) {
     `❌ quality-gate exhausted retries (${attempt}), writing diagnostics to ${bundlePath ?? '<unwritable>'}\n`,
   );
 
-  await emitGateEvent(repoRoot, false, attempt, lastFailure?.gate ?? null, testCounts);
+  await emitGateEvent(repoRoot, false, attempt, lastFailure?.gate ?? null, testCounts, lastFailure);
 
   const out = {
     ok: false,

package/scripts/lib/resource-probe.mjs

@@ -49,7 +49,7 @@ import { ramSnapshot, cpuSnapshot, processCounts, swapUsedMb, memoryPressurePctF
 
 export { evaluate, PROCESSES_PER_SESSION, PRESSURE_HARD_PCT, PRESSURE_SOFT_PCT, PRESSURE_HEALTHY_PCT, DEFAULT_RESOURCE_THRESHOLDS } from './resource-probe/evaluate.mjs';
 export { peerSessionsCount } from './resource-probe/probe-platform.mjs';
-export { parseEtimeToMinutes, countZombieProcesses, countProcessMatches, parseSwapUsageOutput, parseMemoryPressureOutput, parseVmStatAvailableGb } from './resource-probe/parsers.mjs';
+export { parseEtimeToMinutes, parseEtimeToSeconds, countZombieProcesses, countProcessMatches, parseSwapUsageOutput, parseMemoryPressureOutput, parseVmStatAvailableGb } from './resource-probe/parsers.mjs';
 
 // ---------------------------------------------------------------------------
 // Public API — probe()

package/scripts/lib/rule-loader.mjs

@@ -20,16 +20,17 @@
  * `globs:`. Precedence when BOTH keys are present on the same rule: `globs:`
  * wins (silently — no merge, no warning) and `paths:` is ignored entirely.
  *
- * A rule file MAY carry a leading single-line provenance header before its
- * frontmatter block — the vendoring pipeline (`scripts/rules-sync.mjs`)
- * requires a first-line `<!-- source: session-orchestrator plugin
- * (canonical: ...) -->` comment on every vendored rule. The frontmatter
- * parser tolerates any leading run of blank lines and/or single-line HTML
- * comments before the opening `---`, so a vendored rule keeps its `globs:`
- * scoping and scalar meta instead of silently falling back to always-on.
- * Only single-line comments are tolerated (no multi-line comment blocks);
- * files with no header, or starting directly with `---`, parse exactly as
- * before.
+ * Frontmatter counts ONLY when its opening `---` is the very first line of the
+ * file (#1449) — the same rule Claude Code applies when it reads `paths:`.
+ * Until #1449 this parser skipped leading blank lines and single-line HTML
+ * comments (the vendoring pipeline's `<!-- source: … -->` provenance header),
+ * so a rule Claude Code loads ALWAYS-ON was classified path-scoped here and
+ * `instruction-budget-guard.mjs` under-counted the always-on surface. A
+ * provenance comment now belongs directly AFTER the closing `---` (body text,
+ * inert). A frontmatter-shaped block that is NOT on line 1 — any text,
+ * comment or blank line before it — yields no globs and no meta at all, and
+ * the entry carries `defect: 'frontmatter-not-at-top'` so callers can report
+ * the file instead of silently loading it always-on.
  *
  * Beyond the `globs:` key (issue #336), the frontmatter parser also captures
  * these scalar activation keys (issue #694), surfaced on each RuleEntry:
@@ -150,34 +151,15 @@ function matchGlob(filePath, globPattern) {
 // Minimal YAML frontmatter parser (matches state-md.mjs style)
 // ---------------------------------------------------------------------------
 
+// Anchored at offset 0: frontmatter exists only when `---` is line 1 (#1449).
 const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
 
-// A single header line is either blank or a complete single-line HTML
-// comment (`<!-- ... -->` on one line). Multi-line comment blocks are
-// deliberately NOT supported — the vendoring convention is a single first
-// line, and tolerating a few stacked comment lines (each matching this RE)
-// is sufficient.
-const HEADER_LINE_RE = /^[ \t]*(?:<!--.*-->)?[ \t]*$/;
-
 /**
- * Skips a leading run of blank lines and/or single-line HTML comments
- * (`<!-- ... -->`) at the very start of a rule file's contents, so the
- * frontmatter opener (`---`) can be found even when the vendoring pipeline's
- * mandatory provenance header precedes it. Stops at the first line that is
- * neither blank nor a complete single-line comment.
- *
- * @param {string} contents - raw file contents
- * @returns {string} contents starting at the first non-header line (empty
- *   string when the entire content is header lines)
+ * Defect code for a frontmatter block that does not start on line 1 (#1449).
+ * Claude Code ignores such a block, so the rule loads always-on there; the
+ * loader mirrors that and tags the entry with this code.
  */
-function stripLeadingProvenanceHeader(contents) {
-  const lines = contents.split(/\r?\n/);
-  let idx = 0;
-  while (idx < lines.length && HEADER_LINE_RE.test(lines[idx])) {
-    idx++;
-  }
-  return lines.slice(idx).join('\n');
-}
+export const FRONTMATTER_NOT_AT_TOP = 'frontmatter-not-at-top';
 
 // Scalar activation keys captured (issue #694 + #692). The `globs` key keeps
 // its dedicated sequence/flow handling and is NOT routed through this table.
@@ -193,12 +175,36 @@ const SCALAR_META_KEYS = new Set([
   'tier',
 ]);
 
+/**
+ * Undo the ONE quoting style the renderer emits for a scalar (#1041 follow-up).
+ *
+ * `scripts/lib/reconcile/renderer.mjs` serialises `description:` through
+ * js-yaml, which picks SINGLE-quote style whenever the plain form would be
+ * ambiguous (a `: ` inside) and escapes an interior `'` as `''`. A bare
+ * leading/trailing-quote strip then returns `it''s` for `it's` — measured
+ * 2026-08-23 on 40 of 146 live learning insights carrying both characters.
+ * Single-quoted: strip + un-double. Double-quoted: strip + unescape `\"` and
+ * `\\`. Unquoted: returned verbatim (the pre-#1041 behaviour, unchanged).
+ */
+function unquoteYamlScalar(valuePart) {
+  const v = valuePart.trim();
+  if (v.length >= 2 && v.startsWith("'") && v.endsWith("'")) {
+    return v.slice(1, -1).replace(/''/g, "'");
+  }
+  if (v.length >= 2 && v.startsWith('"') && v.endsWith('"')) {
+    return v.slice(1, -1).replace(/\\(["\\])/g, '$1');
+  }
+  return v.replace(/^["']|["']$/g, '');
+}
+
 /**
  * Parses the YAML frontmatter block for the `globs:` field (issue #336),
  * its `paths:` alias (issue #795), and the scalar activation keys (issue #694).
  *
  * Returns:
  *   - `{ globs: string[] | null, meta: object }` on success
+ *   - `{ globs: null, meta: {}, defect: 'frontmatter-not-at-top' }` when a
+ *     frontmatter block exists but does not start on line 1 (#1449)
  *   - throws `Error` on malformed frontmatter so the caller can fall back
  *
  * `globs` is `null` when no frontmatter, and neither `globs:` nor `paths:` is
@@ -213,41 +219,63 @@ const SCALAR_META_KEYS = new Set([
  *   - all other recognised keys → quote-stripped strings
  * Unknown keys are ignored without error.
  *
- * A leading run of blank lines and/or single-line HTML comments (e.g. the
- * vendoring pipeline's provenance header) is tolerated before the opening
- * `---` — see `stripLeadingProvenanceHeader`. Files with no such header parse
- * identically to before this tolerance was added.
+ * Only a block whose opening `---` is line 1 is frontmatter (#1449), exactly
+ * as Claude Code reads it. Anything before the opener — a provenance comment,
+ * a blank line, any text — makes the block body text: no globs, no meta, and
+ * the `defect` field names the misplacement (see {@link FRONTMATTER_NOT_AT_TOP}).
  *
  * @param {string} contents - raw file contents
- * @returns {{ globs: string[] | null, meta: Record<string, unknown> }}
+ * @returns {{ globs: string[] | null, meta: Record<string, unknown>, defect?: 'frontmatter-not-at-top' }}
  */
+export function parseGlobsFrontmatter(contents) {
+  const match = FRONTMATTER_RE.exec(contents);
+  if (match) return parseFrontmatterBlock(match[1]);
+  if (hasDisplacedFrontmatter(contents)) {
+    return { globs: null, meta: {}, defect: FRONTMATTER_NOT_AT_TOP };
+  }
+  return { globs: null, meta: {} };
+}
+
 /**
- * Undo the ONE quoting style the renderer emits for a scalar (#1041 follow-up).
+ * Does `contents` carry a frontmatter block that is NOT on line 1 (#1449)?
  *
- * `scripts/lib/reconcile/renderer.mjs` serialises `description:` through
- * js-yaml, which picks SINGLE-quote style whenever the plain form would be
- * ambiguous (a `: ` inside) and escapes an interior `'` as `''`. A bare
- * leading/trailing-quote strip then returns `it''s` for `it's` — measured
- * 2026-08-23 on 40 of 146 live learning insights carrying both characters.
- * Single-quoted: strip + un-double. Double-quoted: strip + unescape `\"` and
- * `\\`. Unquoted: returned verbatim (the pre-#1041 behaviour, unchanged).
+ * Only the FIRST bare `---` line is considered, and its block must parse
+ * cleanly AND carry at least one key this loader honours (`globs`, `paths`,
+ * or a scalar activation key). That second condition keeps a horizontal rule
+ * pair around ordinary prose from being reported: prose between two `---`
+ * lines almost always holds a colon-less line (a heading, a sentence), which
+ * throws, and a recognised key at column 0 is what makes the misplacement
+ * change behaviour at all. The known blind spot is a displaced block that is
+ * itself malformed — it is treated as body text, which is what Claude Code
+ * does with it too.
+ *
+ * @param {string} contents - raw file contents
+ * @returns {boolean}
  */
-function unquoteYamlScalar(valuePart) {
-  const v = valuePart.trim();
-  if (v.length >= 2 && v.startsWith("'") && v.endsWith("'")) {
-    return v.slice(1, -1).replace(/''/g, "'");
-  }
-  if (v.length >= 2 && v.startsWith('"') && v.endsWith('"')) {
-    return v.slice(1, -1).replace(/\\(["\\])/g, '$1');
+function hasDisplacedFrontmatter(contents) {
+  const lines = contents.split(/\r?\n/);
+  const opener = lines.indexOf('---');
+  // -1: no opener at all. 0: the opener IS line 1, so FRONTMATTER_RE already
+  // had its chance (an unclosed block) — not a displacement.
+  if (opener <= 0) return false;
+  const block = FRONTMATTER_RE.exec(lines.slice(opener).join('\n'));
+  if (!block) return false;
+  try {
+    const { globs, meta } = parseFrontmatterBlock(block[1]);
+    return globs !== null || Object.keys(meta).length > 0;
+  } catch {
+    return false;
   }
-  return v.replace(/^["']|["']$/g, '');
 }
 
-export function parseGlobsFrontmatter(contents) {
-  const match = FRONTMATTER_RE.exec(stripLeadingProvenanceHeader(contents));
-  if (!match) return { globs: null, meta: {} };
-
-  const fmText = match[1];
+/**
+ * Parses the text BETWEEN the two `---` fences (the frontmatter body).
+ * Throws on a malformed top-level line — see {@link parseGlobsFrontmatter}.
+ *
+ * @param {string} fmText - frontmatter body without its fences
+ * @returns {{ globs: string[] | null, meta: Record<string, unknown> }}
+ */
+function parseFrontmatterBlock(fmText) {
   const lines = fmText.split(/\r?\n/);
 
   let globsValue = null;
@@ -466,6 +494,9 @@ function applyGates(meta, filePath, mode, hostClass, now, context = null) {
  *   from the `alwaysApply` frontmatter key)
  * @property {string[]} matchedGlobs - globs that matched; empty when alwaysOn
  * @property {true} [_parseError] - present only on frontmatter parse-error entries
+ * @property {'frontmatter-not-at-top'} [defect] - present only when a frontmatter
+ *   block exists but does not start on line 1 (#1449); such an entry is always
+ *   `alwaysOn: true` and carries no meta fields, mirroring Claude Code
  * @property {string} [description] - frontmatter `description` (issue #694), when present
  * @property {string} [mode] - frontmatter `mode` (issue #694), when present
  * @property {string} [hostClass] - frontmatter `host-class` (issue #694), when present
@@ -484,6 +515,10 @@ function applyGates(meta, filePath, mode, hostClass, now, context = null) {
  * Rules without `globs:` (or its `paths:` alias — issue #795) frontmatter are
  * always included (alwaysOn: true). Rules with `globs:`/`paths:` are included
  * only when at least one scopePath matches at least one glob pattern.
+ * A rule whose frontmatter does not start on line 1 is always-on with no meta
+ * (so no gate excludes it) and carries `defect: 'frontmatter-not-at-top'`
+ * (#1449) — no stderr line, because callers such as the instruction-budget
+ * guard load the directory several times per run and report the defect themselves.
  *
  * After a successful frontmatter parse, deterministic gates (issue #694) are
  * applied to BOTH always-on and glob-matched rules — a rule must pass ALL
@@ -557,10 +592,11 @@ export function loadApplicableRules({
 
     let globs;
     let meta;
+    let defect;
     let parseError = false;
 
     try {
-      ({ globs, meta } = parseGlobsFrontmatter(content));
+      ({ globs, meta, defect } = parseGlobsFrontmatter(content));
     } catch (err) {
       process.stderr.write(
         `[rule-loader] Frontmatter parse error in ${filePath}: ${err.message} — treating as always-on\n`,
@@ -581,7 +617,8 @@ export function loadApplicableRules({
     const metaFields = metaToEntryFields(meta);
 
     if (globs === null) {
-      // No globs frontmatter (or parse error) → always-on
+      // No globs frontmatter (or parse error, or frontmatter not on line 1 —
+      // #1449) → always-on
       results.push({
         path: filePath,
         content,
@@ -589,6 +626,7 @@ export function loadApplicableRules({
         matchedGlobs: [],
         ...metaFields,
         ...(parseError ? { _parseError: true } : {}),
+        ...(defect ? { defect } : {}),
       });
       continue;
     }