session-orchestrator 3.21.0 → 3.23.0

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

@@ -41,17 +41,28 @@ function isTestFile(filePath) {
 /**
  * Execute a shell command and return a structured result.
  *
+ * `output` is a bounded TAIL for humans. `fullOutput` is the complete captured
+ * text and is what every COUNT parse must read.
+ *
+ * Why both: the tail was 5 lines and was also the parser's input. Vitest prints
+ * its `Test Files` / `Tests` summary and THEN the per-failure detail, so on any
+ * real failure the summary sits hundreds of lines above the tail — measured
+ * 2026-08-22: line 174 of 936. `extractTestCounts` then found nothing and the
+ * gate reported `test: fail, total 0, passed 0, failed 0`, which reads as
+ * "the runner never produced results" and hides WHICH test failed. An hour was
+ * spent chasing that phantom before the real cause (one red test) was found.
+ *
  * @param {string} cmd - Shell command to run, or `"skip"` / empty to skip.
- * @returns {{ status: 'pass'|'fail'|'skip', output: string, exitCode: number, stubbed?: { kind: 'echo'|'noop' } }}
+ * @returns {{ status: 'pass'|'fail'|'skip', output: string, fullOutput: string, exitCode: number, stubbed?: { kind: 'echo'|'noop' } }}
  */
 export function runCheck(cmd) {
   if (!cmd || cmd === 'skip') {
-    return { status: 'skip', output: '', exitCode: 0 };
+    return { status: 'skip', output: '', fullOutput: '', exitCode: 0 };
   }
 
   const stub = detectStubCommand(cmd);
   if (stub.isStub) {
-    return { status: 'pass', output: `(stubbed: ${stub.kind})`, exitCode: 0, stubbed: { kind: stub.kind } };
+    return { status: 'pass', output: `(stubbed: ${stub.kind})`, fullOutput: `(stubbed: ${stub.kind})`, exitCode: 0, stubbed: { kind: stub.kind } };
   }
 
   try {
@@ -61,18 +72,18 @@ export function runCheck(cmd) {
       maxBuffer: RUN_CHECK_MAX_BUFFER_BYTES,
     });
     const output = raw.split('\n').slice(-5).join('\n').trim();
-    return { status: 'pass', output, exitCode: 0 };
+    return { status: 'pass', output, fullOutput: raw, exitCode: 0 };
   } catch (err) {
     const exitCode = typeof err.status === 'number' ? err.status : 1;
 
     // Exit code 127 means command not found — treat as skip.
     if (exitCode === 127) {
-      return { status: 'skip', output: 'command not found', exitCode };
+      return { status: 'skip', output: 'command not found', fullOutput: '', exitCode };
     }
 
     const combined = [err.stdout ?? '', err.stderr ?? ''].join('\n');
     const output = combined.split('\n').slice(-5).join('\n').trim();
-    return { status: 'fail', output, exitCode };
+    return { status: 'fail', output, fullOutput: combined, exitCode };
   }
 }
 
@@ -143,7 +154,35 @@ export function extractCount(output, pattern) {
 const TEST_SUMMARY_LINE = /^\s*Tests\b/;
 
 /**
- * Parse test-runner output for pass/fail/total TEST-CASE counts.
+ * Matches vitest's FILE-level summary line (`Test Files  8 failed | 595 passed (603)`).
+ *
+ * Distinct from {@link TEST_SUMMARY_LINE} (the TEST-CASE line, `Tests  ...`): a
+ * suite that dies at import time is counted HERE, and the `Tests` line then
+ * carries no `N failed` segment at all (#1149) — vitest omits it whenever zero
+ * individual test cases ran. Last matching line wins (the final summary after
+ * any rerun), mirroring `TEST_SUMMARY_LINE`'s own convention.
+ */
+const TEST_FILES_SUMMARY_LINE = /^\s*Test Files\b/;
+
+/**
+ * Parse a `<N> passed` / `<N> failed` pair out of one summary line/scope.
+ * `total` is their sum (skipped excluded) — the same rule the top-level
+ * test-case triple in {@link extractTestCounts} publishes.
+ *
+ * @param {string} scope
+ * @returns {{ passed: number, failed: number, total: number }}
+ */
+function parseCountTriple(scope) {
+  const passMatch = scope.match(/(\d+)\s+passed/);
+  const failMatch = scope.match(/(\d+)\s+failed/);
+  const passed = passMatch ? parseInt(passMatch[1], 10) : 0;
+  const failed = failMatch ? parseInt(failMatch[1], 10) : 0;
+  return { passed, failed, total: passed + failed };
+}
+
+/**
+ * Parse test-runner output for pass/fail/total TEST-CASE counts, plus the
+ * vitest FILE-level triple when a `Test Files` summary line is present.
  *
  * ## Which line is parsed
  *
@@ -157,10 +196,38 @@ const TEST_SUMMARY_LINE = /^\s*Tests\b/;
  * A naive whole-output scan hits the FILE count (550) and publishes it as the
  * test count — the number then rides `gate-full.mjs`'s `test.passed` into the
  * `orchestrator.quality_gate.*` event stream looking authoritative. So: when a
- * `Tests`-anchored summary line exists, ONLY that line is parsed (the LAST one,
- * which is the final summary after any rerun). Terse or non-vitest output with
- * no such line falls back to scanning the whole string, which preserves the
- * bare `"42 passed"` / `"10 passed, 5 failed"` forms.
+ * `Tests`-anchored summary line exists, ONLY that line is parsed for the
+ * test-case triple (the LAST one, which is the final summary after any
+ * rerun). Terse or non-vitest output with no such line falls back to scanning
+ * the whole string, which preserves the bare `"42 passed"` / `"10 passed, 5
+ * failed"` forms.
+ *
+ * The `Test Files` line is parsed the same way, into a SEPARATE nested `files`
+ * triple — never folded into `failed`/`total`. `total === passed + failed` is
+ * load-bearing for the test-case triple (`admitSuiteCounts`, and historically
+ * `failed = total - passed` in `run-quality-gate.mjs`); mixing file counts in
+ * would either break that invariant or invent phantom test-case failures. A
+ * suite that dies at import is invisible on the `Tests` line (vitest omits
+ * `N failed` there when zero test cases ran) and visible only on `Test
+ * Files` — #1149, measured as
+ * `{"test":{"status":"fail","total":14671,"passed":14671,"failed":0}}`, with
+ * no field anywhere naming the 8 files that actually died.
+ * `gate-full.mjs` derives a `suite_died` boolean from `files.failed` for
+ * exactly this shape.
+ *
+ * ## `files` is NULL when no `Test Files` line was seen — never a zero triple
+ *
+ * Only vitest prints that line. A non-vitest runner, a terse reporter, or a
+ * fail-fast crash produces output with no file-level summary at all, and the
+ * function used to publish `files_total/passed/failed: 0` there — an UNMEASURED
+ * zero, byte-identical in the envelope to a measured one, from which
+ * `gate-full.mjs` then derived `suite_died: false` as if it had checked. That is
+ * the same "absent is not zero" defect `admitSuiteCounts` exists to prevent one
+ * field over, so it uses the same channel: `null` means "no file-level
+ * measurement", and the caller OMITS the keys rather than zero-filling them.
+ * The test-case triple keeps its zeros — those are the caller's fallback, not a
+ * parse result, and `total: 0` is already the "no counts" signal
+ * `admitSuiteCounts` rejects.
  *
  * ## What `total` means — passed + failed, NOT vitest's parenthesised number
  *
@@ -178,22 +245,27 @@ const TEST_SUMMARY_LINE = /^\s*Tests\b/;
  * see. Add it together with a consumer, never ahead of one.
  *
  * @param {string} output - Captured test-runner stdout/stderr (or a tail of it).
- * @returns {{ passed: number, failed: number, total: number }} `total === passed + failed`.
+ * @returns {{ passed: number, failed: number, total: number, files: {passed: number, failed: number, total: number}|null }}
+ *   Test-case `total === passed + failed`. `files` is `null` when the output
+ *   carried no `Test Files` summary line; when present,
+ *   `files.total === files.passed + files.failed`.
  */
 export function extractTestCounts(output) {
-  if (!output) return { passed: 0, failed: 0, total: 0 };
+  const EMPTY = { passed: 0, failed: 0, total: 0, files: null };
+  if (!output) return EMPTY;
 
-  const summaryLines = output.split('\n').filter((line) => TEST_SUMMARY_LINE.test(line));
+  const lines = output.split('\n');
+  const summaryLines = lines.filter((line) => TEST_SUMMARY_LINE.test(line));
   const scope = summaryLines.length > 0 ? summaryLines[summaryLines.length - 1] : output;
+  const { passed, failed, total } = parseCountTriple(scope);
 
-  const passMatch = scope.match(/(\d+)\s+passed/);
-  const failMatch = scope.match(/(\d+)\s+failed/);
-
-  const passed = passMatch ? parseInt(passMatch[1], 10) : 0;
-  const failed = failMatch ? parseInt(failMatch[1], 10) : 0;
-  const total = passed + failed;
+  const fileSummaryLines = lines.filter((line) => TEST_FILES_SUMMARY_LINE.test(line));
+  const fileScope = fileSummaryLines.length > 0 ? fileSummaryLines[fileSummaryLines.length - 1] : '';
+  // No `Test Files` line → NOT MEASURED. See the docstring section above: a zero
+  // triple here would be indistinguishable from a real all-passed-zero-files run.
+  const files = fileScope ? parseCountTriple(fileScope) : null;
 
-  return { passed, failed, total };
+  return { passed, failed, total, files };
 }
 
 /**

package/scripts/lib/git-config-drift.mjs

@@ -47,11 +47,35 @@
  *  - a `.git/config` written AFTER this probe ran. It is a session-start
  *    snapshot, not a watcher.
  *
- * **Revisit trigger:** if an operator reports a standing false positive on a
- * deliberate local override, add an explicit allow-list (a `[sessionOrchestrator]`
+ * **Revisit trigger (identity / remote / gpgsign only):** if an operator
+ * reports a standing false positive on a deliberate local override of one of
+ * those three, add an explicit allow-list (a `[sessionOrchestrator]`
  * local-config key naming the accepted keys) — do NOT widen or delete a rule,
  * which would re-open the exact hole the probe was built to close.
  *
+ * `hooks-path` is no longer in that bucket (#1158, 2026-08-28): a
+ * `core.hooksPath` outside `.husky/_` is accepted when the repo DECLARES it —
+ * `git ls-files -- <hooksPath>` returns at least one TRACKED file DIRECTLY
+ * under the hooksPath whose BASENAME is a real git hook name (see
+ * `GIT_HOOK_NAMES`, sourced from `git help hooks`), the same "declared beats
+ * guessed" shape `isFixtureHost` already applies to the remote finding. A
+ * tracked `.githooks/pre-commit` with `core.hooksPath=.githooks` is a
+ * deliberate setup, not drift, and stops flagging without any config key. An
+ * untracked or out-of-repo hooksPath still flags exactly as before — that is
+ * still the incident class this probe exists for (a fixture that rewrote
+ * hooksPath to somewhere nothing is tracked).
+ *
+ * **Narrowed 2026-08-28 (review, #1158/#1159 N1):** the first cut of this
+ * acceptance rule asked only "does `git ls-files` return anything at all
+ * under the hooksPath" — which accepted `core.hooksPath=scripts` the moment
+ * ANY file under `scripts/` was tracked, including an UNTRACKED executable
+ * literally named `pre-commit` planted alongside ordinary tracked source
+ * (measured exploit: `git ls-files -- scripts` returns 456 tracked files in
+ * this repo, none of them a hook, and the old check accepted it on count
+ * alone). `hooksPathIsTracked` now requires a tracked file DIRECTLY under the
+ * hooksPath whose basename git itself would invoke as a hook — a tracked
+ * directory of unrelated source no longer counts as a declaration.
+ *
  * ## Fail-open is forbidden here
  *
  * A failed query is NOT a clean repo. That fold — `null` meaning both "asked
@@ -77,6 +101,7 @@
  */
 
 import { spawnSync } from 'node:child_process';
+import { isAbsolute, relative } from 'node:path';
 
 /** Default timeout in ms for each `git config` invocation. */
 export const DEFAULT_TIMEOUT_MS = 5000;
@@ -112,7 +137,9 @@ export const DEGRADED_REASONS = Object.freeze([
  *    global identity. The costliest entry of the incident.
  *  - `local-gpgsign`    — a local `commit.gpgsign` differing from the global.
  *  - `fixture-remote`   — a remote URL on a reserved/fixture host.
- *  - `hooks-path`       — a local `core.hooksPath` not pointing at `.husky/_`.
+ *  - `hooks-path`       — a local `core.hooksPath` not pointing at `.husky/_`
+ *    and not DECLARED by the repo — no tracked file directly under it is a
+ *    real git hook name; see `hooksPathIsTracked` / `GIT_HOOK_NAMES`.
  *
  * @type {readonly ['ambient-git-env','local-identity','local-gpgsign','fixture-remote','hooks-path']}
  */
@@ -181,6 +208,45 @@ const FIXTURE_HOSTS = Object.freeze([
 /** The only `core.hooksPath` this repo expects, matched as a path tail. */
 const EXPECTED_HOOKS_PATH_TAIL = '.husky/_';
 
+/**
+ * Every hook name git itself recognizes under a `core.hooksPath` directory.
+ * Source: `git help hooks`. A tracked file below a declared hooksPath whose
+ * BASENAME is not one of these is not a hook git will ever invoke — accepting
+ * it as a "declaration" would accept an arbitrary tracked file, which is the
+ * #1158 review finding this list closes (see the module header's Narrowed
+ * note).
+ */
+const GIT_HOOK_NAMES = Object.freeze([
+  'applypatch-msg',
+  'pre-applypatch',
+  'post-applypatch',
+  'pre-commit',
+  'pre-merge-commit',
+  'prepare-commit-msg',
+  'commit-msg',
+  'post-commit',
+  'pre-rebase',
+  'post-checkout',
+  'post-merge',
+  'pre-push',
+  'pre-receive',
+  'update',
+  'proc-receive',
+  'post-receive',
+  'post-update',
+  'reference-transaction',
+  'push-to-checkout',
+  'pre-auto-gc',
+  'post-rewrite',
+  'sendemail-validate',
+  'fsmonitor-watchman',
+  'p4-changelist',
+  'p4-prepare-changelist',
+  'p4-post-changelist',
+  'p4-pre-submit',
+  'post-index-change',
+]);
+
 /**
  * Build the filtered child environment. See {@link GIT_ENV_ALLOWLIST}.
  *
@@ -310,6 +376,67 @@ function hooksPathIsExpected(value) {
   return normalized === EXPECTED_HOOKS_PATH_TAIL || normalized.endsWith(`/${EXPECTED_HOOKS_PATH_TAIL}`);
 }
 
+/**
+ * @param {string} pathspec repo-relative hooksPath (posix separators, no
+ *   trailing slash) already resolved to sit inside `repoRoot`
+ * @param {string} trackedLine one line of `git ls-files` output (repo-relative;
+ *   git prints `/`-separated paths even on Windows, but this normalizes `\`
+ *   too in case a future caller feeds it something else)
+ * @returns {boolean} true when `trackedLine` sits DIRECTLY under `pathspec`
+ *   (not in a nested subdirectory) and its basename is a recognized git hook
+ *   name — see {@link GIT_HOOK_NAMES}. A tracked file two levels deep, or a
+ *   tracked file with an unrelated name, is deliberately NOT a declaration.
+ */
+function isDeclaredHookFile(pathspec, trackedLine) {
+  const line = String(trackedLine ?? '').replace(/\\/g, '/');
+  const slash = line.lastIndexOf('/');
+  const dir = slash === -1 ? '' : line.slice(0, slash);
+  const base = slash === -1 ? line : line.slice(slash + 1);
+  return dir === pathspec && GIT_HOOK_NAMES.includes(base);
+}
+
+/**
+ * @param {string} value a `core.hooksPath` value that already failed
+ *   {@link hooksPathIsExpected}
+ * @param {{repoRoot: string, env: Record<string,string|undefined>, timeoutMs: number, spawn: Function}} ctx
+ *   the same context {@link runGitConfig} uses — same filtered env, same `-C`
+ *   seam, so this query cannot be redirected any more than the config read can
+ * @returns {boolean} true when the path is DECLARED as a hook by the repo:
+ *   `git ls-files -- <path>` returns at least one TRACKED file DIRECTLY under
+ *   it whose basename is a real git hook name (#1158 review — a tracked
+ *   directory of ordinary source files is not itself a declaration; see
+ *   {@link GIT_HOOK_NAMES} / {@link isDeclaredHookFile}). An absolute value is
+ *   resolved relative to `repoRoot` first; a value outside the repo root can
+ *   never be tracked and returns `false` without spawning git. Any spawn
+ *   failure (missing git, timeout, non-zero exit) also returns `false` — this
+ *   helper only ever WIDENS acceptance, so a query it cannot answer must fall
+ *   back to "not declared", never the reverse.
+ */
+function hooksPathIsTracked(value, ctx) {
+  const raw = String(value ?? '').trim();
+  if (raw === '') return false;
+
+  let pathspec = raw.replace(/\\/g, '/').replace(/\/+$/, '');
+  if (isAbsolute(raw)) {
+    const rel = relative(ctx.repoRoot, raw);
+    if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) return false; // outside repo root
+    pathspec = rel.replace(/\\/g, '/').replace(/\/+$/, '');
+  }
+
+  const res = ctx.spawn('git', ['-C', ctx.repoRoot, 'ls-files', '--', pathspec], {
+    encoding: 'utf8',
+    timeout: ctx.timeoutMs,
+    env: filteredGitEnv(ctx.env),
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  if (res?.error || res?.signal) return false;
+  if (typeof res?.status !== 'number' || res.status !== 0) return false;
+
+  const lines = String(res?.stdout ?? '').split('\n').filter((l) => l.length > 0);
+  return lines.some((line) => isDeclaredHookFile(pathspec, line));
+}
+
 /**
  * Build the degraded result. Distinct from `null` on purpose — see the header.
  *
@@ -439,12 +566,14 @@ export function checkGitConfigDrift(opts = {}, deps = {}) {
         continue;
       }
 
-      if (lower === 'core.hookspath' && !hooksPathIsExpected(value)) {
+      if (lower === 'core.hookspath' && !hooksPathIsExpected(value) && !hooksPathIsTracked(value, ctx)) {
         findings.push({
           kind: 'hooks-path',
           key,
           value,
-          detail: `core.hooksPath=${value} zeigt nicht auf ${EXPECTED_HOOKS_PATH_TAIL} — Husky-Hooks laufen nicht.`,
+          detail:
+            `core.hooksPath=${value} zeigt nicht auf ${EXPECTED_HOOKS_PATH_TAIL} und ist im Repo ` +
+            `nicht als getrackter Pfad deklariert — Hooks laufen möglicherweise nicht.`,
         });
       }
     }

package/scripts/lib/host-identity.mjs

@@ -30,11 +30,26 @@
  */
 
 import { readFile, writeFile, mkdir, chmod } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  chmodSync,
+  mkdirSync,
+  unlinkSync,
+} from 'node:fs';
 import { digestSha256WithSalt } from './crypto-digest-utils.mjs';
 import path from 'node:path';
 import os from 'node:os';
-import { SO_OS, SO_PLATFORM } from './platform.mjs';
+// NOTE (#1072 gate fix): platform.mjs is deliberately NOT imported statically.
+// Its module level computes SO_PLATFORM/SO_PLUGIN_ROOT via detectPlatform()/
+// resolvePluginRoot(), which walk the filesystem (existsSync + readFileSync of
+// package.json up the tree). session-lock.mjs now imports this module, which
+// put those import-time reads into every graph that imports session-lock —
+// including fs-mocked test graphs (tests/lib/vault-mirror/process.test.mjs went
+// red: the walk consumed the mocks' sequenced return values). The only two
+// consumers (SO_OS/SO_PLATFORM in collectFingerprint) are async — load lazily.
 
 const FINGERPRINT_TTL_MS = 24 * 60 * 60 * 1000; // 24h
 const PLACEHOLDER_SALT = 'env-aware-v1-default-salt-replaced-by-owner-yaml';
@@ -97,6 +112,235 @@ export function hashHostname(hostname, salt) {
   return digestSha256WithSalt(hostname, { salt: String(salt) });
 }
 
+// ---------------------------------------------------------------------------
+// Stable host identity (GitLab #1072)
+// ---------------------------------------------------------------------------
+//
+// `os.hostname()` is NOT stable on a single machine. Measured on the reference
+// host 2026-08-24: two readings ten minutes apart returned `Mac.home` and
+// `Ferdinands-MacBook-Pro.local`, and `.orchestrator/metrics/events.jsonl`
+// carries both spellings (106× / 27×). Every `lock.host === os.hostname()`
+// comparison in the lock family therefore fails against the machine's OWN lock
+// after a flip: stale detection reports `cross-host` (and cross-host locks are
+// never reaped or overridden by design, PSA-003), the reaper refuses with
+// `cross-host-requires-operator`, and release owner-match returns `not-owner`.
+//
+// Two independent layers, because one is not enough:
+//   1. `stableHostname()` normalises the SUFFIX difference (`Mac.home` vs
+//      `Mac.local` → `mac`). It cannot bridge `mac` vs `ferdinands-macbook-pro`
+//      — those differ before the suffix.
+//   2. The self-alias ledger records every spelling THIS machine has presented
+//      itself under, so `hostnamesMatch()` can bridge the remaining gap. Only
+//      names the local machine wrote about itself ever enter it, which is what
+//      keeps a genuinely foreign host from ever matching.
+
+/**
+ * Suffixes stripped by {@link stableHostname}. mDNS (`.local`), the common
+ * router-assigned search domains (`.home`, `.lan`), and the POSIX default
+ * (`.localdomain`). Deliberately NOT a generic "strip the last label" rule:
+ * `a.b.example.com` is a real FQDN whose labels carry meaning.
+ */
+const LOCAL_HOST_SUFFIXES = ['.local', '.home', '.lan', '.localdomain'];
+
+/**
+ * Normalise a hostname into a comparable form: trimmed, lowercased, with ONE
+ * trailing local-network suffix removed.
+ *
+ * Never throws. A non-string, empty, or whitespace-only input yields `''`
+ * (which {@link hostnamesMatch} treats as "no identity" — it never matches).
+ *
+ * NOTE on the default: `stableHostname()` and `stableHostname(undefined)` both
+ * normalise `os.hostname()`, because that is JavaScript default-parameter
+ * semantics. Pass `''` or `null` to get the empty result.
+ *
+ * @param {string} [raw=os.hostname()]
+ * @returns {string} normalised hostname, or '' when there is nothing to normalise.
+ */
+export function stableHostname(raw = os.hostname()) {
+  if (typeof raw !== 'string') return '';
+  let name = raw.trim().toLowerCase();
+  if (name === '') return '';
+  for (const suffix of LOCAL_HOST_SUFFIXES) {
+    // `name.length > suffix.length` keeps a bare `.local` from normalising to ''.
+    if (name.endsWith(suffix) && name.length > suffix.length) {
+      name = name.slice(0, -suffix.length);
+      break; // ONE suffix only — `foo.lan.local` keeps its inner label.
+    }
+  }
+  return name;
+}
+
+/**
+ * Host-alias ledger path. `SO_HOST_ALIASES_FILE` overrides it — MANDATORY for
+ * tests, which must never write into the operator's real `~/.config`.
+ *
+ * The `.trim() || fallback` shape is deliberate: a whitespace-only env var is
+ * truthy and would otherwise short-circuit the `||` (see `.claude/rules/
+ * development.md` § Error Handling, env-var fallback whitespace trap).
+ *
+ * @returns {string}
+ */
+function _hostAliasesFile() {
+  const override = (process.env.SO_HOST_ALIASES_FILE || '').trim();
+  if (override) return override;
+  return path.join(_privateDir(), 'host-aliases.json');
+}
+
+/**
+ * Named ceiling (BV-004): a machine realistically presents 2–4 spellings of
+ * itself (`os.hostname()`, the mDNS variant, a DHCP-assigned name). 16 bounds
+ * the pathological DHCP-churn case while leaving ample headroom. Revisit if a
+ * real host is ever observed writing more than a handful of distinct names —
+ * beyond that the ledger stops being an identity record and becomes a history.
+ */
+const HOST_ALIASES_MAX = 16;
+
+/**
+ * Synchronous atomic JSON write with an explicit mode. The async twin
+ * `_writeJsonAtomic` below cannot serve the alias ledger: every caller of
+ * {@link recordHostAlias} sits on a SYNCHRONOUS lock path. `io.mjs`'s
+ * `writeJsonAtomicSync` is not reused because it offers no mode argument, and
+ * 0o600 is the whole point of a file that lives beside `host-private.json`.
+ *
+ * @param {string} filePath
+ * @param {*} data
+ * @param {number} mode
+ */
+function _writeJsonAtomicSync(filePath, data, mode) {
+  mkdirSync(path.dirname(filePath), { recursive: true });
+  const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    // `flag: 'wx'` + `mode` on the CREATE, never a chmod after the rename.
+    // Two distinct holes closed: `wx` fails with EEXIST rather than following a
+    // pre-planted symlink at the (predictable) tmp path, so an attacker cannot
+    // redirect the write; and the mode is applied at creation, so the file is
+    // never briefly world-readable between `writeFileSync` and `chmodSync` —
+    // the window in which the ledger beside `host-private.json` was readable.
+    writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n', { encoding: 'utf8', mode, flag: 'wx' });
+    renameSync(tmp, filePath);
+  } catch (err) {
+    try { unlinkSync(tmp); } catch { /* best effort */ }
+    throw err;
+  }
+  // Belt-and-braces for the pre-existing-target case: `rename` keeps the
+  // SOURCE inode, so the mode above already governs — this only repairs a
+  // umask-widened mode on platforms that ignore the create mode.
+  try { chmodSync(filePath, mode); } catch { /* best effort */ }
+}
+
+/**
+ * Read the self-alias ledger. Returns normalised names.
+ *
+ * Fail-CLOSED by construction: any failure (absent file, unreadable, malformed
+ * JSON, wrong shape) yields `[]`, which reduces {@link hostnamesMatch} to plain
+ * normalised equality. A broken ledger can therefore only ever REFUSE a match
+ * that would otherwise have been made — it can never manufacture one.
+ *
+ * @returns {string[]} normalised alias names; `[]` on any failure.
+ */
+export function readHostAliases() {
+  try {
+    const parsed = JSON.parse(readFileSync(_hostAliasesFile(), 'utf8'));
+    if (!Array.isArray(parsed)) return [];
+    const seen = new Set();
+    for (const entry of parsed) {
+      const norm = typeof entry === 'string' ? stableHostname(entry) : '';
+      if (norm) seen.add(norm);
+    }
+    return [...seen];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Record the name this machine currently presents itself under, so a later
+ * reading under a DIFFERENT spelling can still be recognised as the same host.
+ *
+ * Best-effort and idempotent: never throws, never duplicates, and writes
+ * nothing when the name is already present or normalises away to ''. Callers
+ * invoke it once per session-lock acquisition — the one moment we know for a
+ * fact that the current `os.hostname()` belongs to THIS machine.
+ *
+ * @param {string} [name=stableHostname()] — raw or normalised hostname.
+ * @returns {string[]} the ledger contents after the call (`[]` on failure).
+ */
+export function recordHostAlias(name = stableHostname()) {
+  try {
+    const norm = stableHostname(typeof name === 'string' ? name : '');
+    if (!norm) return readHostAliases();
+    const current = readHostAliases();
+    if (current.includes(norm)) return current;
+    // Keep the MOST RECENT names when the cap bites — an old spelling this
+    // machine has not used in 16 renames is the safest one to forget.
+    const next = [...current, norm].slice(-HOST_ALIASES_MAX);
+    _writeJsonAtomicSync(_hostAliasesFile(), next, 0o600);
+    return next;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Decide whether two hostnames name the SAME machine.
+ *
+ * Match when the normalised forms are equal, or when BOTH appear in the
+ * self-alias set (see {@link recordHostAlias}). Requiring both sides to be in
+ * the set is what preserves the cross-host invariants: a foreign host's name
+ * was never written by this machine, so it cannot be in the ledger, so it can
+ * never match — `cross-host` stays `cross-host` (PSA-003).
+ *
+ * The ledger is read ONLY when normalised equality already failed, so the
+ * common same-host path costs no filesystem access even inside a poll loop.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @param {{ aliases?: string[] }} [opts] — inject the alias set (tests, and
+ *   callers that already hold it); omitted → read the ledger.
+ * @returns {boolean}
+ */
+export function hostnamesMatch(a, b, { aliases } = {}) {
+  const normA = stableHostname(typeof a === 'string' ? a : '');
+  const normB = stableHostname(typeof b === 'string' ? b : '');
+  if (!normA || !normB) return false;
+  if (normA === normB) return true;
+
+  const set = Array.isArray(aliases)
+    ? aliases.map((x) => (typeof x === 'string' ? stableHostname(x) : '')).filter(Boolean)
+    : readHostAliases();
+  return set.includes(normA) && set.includes(normB);
+}
+
+/**
+ * Pick the host identity to compare a lock body against: the normalised
+ * `host_id` when it carries one, else the raw pre-#1072 `host`.
+ *
+ * `||`, not `??`, and that is the whole point. `??` falls back on `null` and
+ * `undefined` only, so a lock whose `host_id` is the EMPTY STRING — what a
+ * writer produces when `os.hostname()` momentarily returns '' or whitespace —
+ * short-circuits to `''`, and `hostnamesMatch('', host)` is false by contract
+ * ("no identity never matches"). The machine then reads its OWN lock as
+ * cross-host: stale detection is disabled, the reaper refuses with
+ * `cross-host-requires-operator`, and release returns `not-owner` — the exact
+ * #1072 failure the `host_id` field was added to prevent, re-entered through
+ * the fallback operator. Falling back on '' costs nothing: an empty `host` too
+ * yields '' here, and `hostnamesMatch` still refuses it.
+ *
+ * The `.trim()` extends the same fix one step: a whitespace-only `host_id` is
+ * TRUTHY, so a bare `||` would short-circuit on it exactly as `??` does on `''`
+ * (`.claude/rules/development.md` § Error Handling, env-var fallback whitespace
+ * trap — the same shape, one domain over).
+ *
+ * @param {{ host_id?: unknown, host?: unknown }|null|undefined} lock
+ * @returns {string} raw (un-normalised, but trimmed) candidate name; '' when
+ *   neither field carries a usable value. Never throws.
+ */
+export function lockHostCandidate(lock) {
+  const id = typeof lock?.host_id === 'string' ? lock.host_id.trim() : '';
+  if (id) return id;
+  return typeof lock?.host === 'string' ? lock.host.trim() : '';
+}
+
 // ---------------------------------------------------------------------------
 // Paths
 // ---------------------------------------------------------------------------
@@ -149,6 +393,7 @@ export async function resolveSalt() {
  * @param {string} [opts.salt] — override salt (tests)
  */
 export async function collectFingerprint(opts = {}) {
+  const { SO_OS, SO_PLATFORM } = await import('./platform.mjs');
   const osName = SO_OS;
   const arch = process.arch;
   const cpus = os.cpus() || [];

package/scripts/lib/instruction-budget-guard.mjs

@@ -107,8 +107,38 @@ export const DEFAULT_CEILING = 480;
  * the live repo sits at 471/480 directives (98.1% of ceiling) but 108589/114000
  * bytes (95.3%). That asymmetry is inherited from the pre-existing directive
  * ratchet, not introduced here.
+ *
+ * RE-BASELINED 2026-08-22: 114000 -> 121000. The ratchet fired for exactly the
+ * reason stated above — "a genuinely NEW always-on surface is added". Since the
+ * 2026-07-30 calibration this repo's corpus grew 108589 -> 115730 B, and the
+ * largest single cause is a rule file the operator adopted:
+ * .claude/rules/host-resources.md (7457 B, #1089, live 2026-08-21). Headroom
+ * unchanged at +5%: 115730 x 1.05 = 121516, rounded DOWN to 121000. Same
+ * relative slack, measured against the corpus that actually exists.
+ *
+ * Consumer impact was CHECKED, not assumed. This module ships inside the npm
+ * package, so the first instinct was to keep the shared default fixed and set a
+ * repo-local `instruction-budget.byte-ceiling` override instead. Two
+ * measurements killed that plan: (a) the package ships THREE always-on rules
+ * totalling 9261 B — both ceilings sit ~12x above any consumer's inherited
+ * corpus, so the delta is numerically inert downstream; and (b) the number was
+ * never a shipped-corpus figure in the first place — the calibration above says
+ * "measured against this repo's own always-on corpus". A repo-local override
+ * also could not have worked: tests/rules/receiving-review.test.mjs calls
+ * computeInstructionBudget({repoRoot}), which does not read Session Config, so
+ * it pins this constant by construction.
+ *
+ * Not a licence to raise the number whenever it is hit — a ratchet that yields
+ * on contact measures nothing, and the NEXT breach belongs to a diet. 4499 B of
+ * the always-on security.md still describes surfaces this repo does not have
+ * (SSRF via an http-client package, an OWASP table, RLS, bcrypt/JWT), vendored
+ * from the baseline and never adapted — the same class as the Semgrep claim
+ * fixed today. That cut is real and nameable and is tracked in #1126; it was
+ * deliberately NOT taken in the same pass that raised the ceiling, because
+ * deleting security prose to hit a number is the failure build-value.md BV-002
+ * names.
  */
-export const DEFAULT_BYTE_CEILING = 114000;
+export const DEFAULT_BYTE_CEILING = 121000;
 
 /**
  * Read the `instruction-budget:` nested block from the `## Session Config`