session-orchestrator 5.7.0 → 5.8.0

package/scripts/lib/io.mjs

@@ -16,7 +16,7 @@
  * #457; writeJsonAtomicSync extracted for #558 M1.
  */
 
-import { writeFile, rename, mkdir } from 'node:fs/promises';
+import { writeFile, rename, mkdir, copyFile, unlink } from 'node:fs/promises';
 import {
   mkdirSync,
   writeFileSync,
@@ -888,7 +888,10 @@ export async function writeJsonAtomic(filePath, value, opts = {}) {
  * @param {object} [opts]
  * @param {number} [opts.indent=2]      JSON.stringify indent.
  * @param {string} [opts.tmpPrefix='.tmp']  Tmp-file prefix (callers pick their domain prefix).
- * @returns {{ ok: true } | { ok: false, reason: 'fs-error', error: string }}
+ * @returns {{ ok: true } | { ok: false, reason: 'fs-error', error: string, code: string|null }}
+ *   `code` is the failing call's `err.code` (`'ENOSPC'`, `'EACCES'`, …), or `null`
+ *   when the error carried none (a serialization TypeError, the partial-adapter
+ *   refusal). Additive (#1032): `error` keeps its exact text.
  */
 export function writeJsonAtomicSync(filePath, data, opts = {}) {
   const { indent = 2, tmpPrefix = '.tmp' } = opts;
@@ -897,7 +900,7 @@ export function writeJsonAtomicSync(filePath, data, opts = {}) {
   try {
     body = JSON.stringify(data, null, indent) + '\n';
   } catch (err) {
-    return { ok: false, reason: 'fs-error', error: err?.message ?? String(err) };
+    return _fsErrorEnvelope(err);
   }
 
   const res = atomicWriteWithBackup(filePath, body, { tmpPrefix });
@@ -941,9 +944,10 @@ export function writeJsonAtomicSync(filePath, data, opts = {}) {
  * envelope is returned. Without that, every failed write leaves a
  * `<tmpPrefix>.<hex>` behind — the board writer's failure mode is a retry loop,
  * so the litter accumulates in the operator's vault directory. The cleanup is
- * attempted only when the write actually created the tmp file, and its own
- * failure is swallowed: a leaked tmp is worse than a silent unlink miss, and
- * neither may mask the original error.
+ * attempted once the tmp path has been chosen — including a write that created
+ * the file and then failed mid-way — and its own failure is swallowed: a leaked
+ * tmp is worse than a silent unlink miss, and neither may mask the original
+ * error.
  *
  * ── BV-004 ceiling + revisit trigger ────────────────────────────────────────
  * THREE PRODUCTION CALL-SITES (re-measured 2026-10-03 @ 0e0c4b08 with
@@ -964,8 +968,8 @@ export function writeJsonAtomicSync(filePath, data, opts = {}) {
  * `backup: false` and no `fs`, so the backup half and the injection seam still
  * rest on tests plus one board-writer flag. REVISIT TRIGGER — when a sweep
  * migrates the remaining hand-rolled sites, re-check before widening:
- * (a) whether an `async` twin is needed rather than bolting a promise mode onto
- * this one (three known sites are `fs/promises`), and (b) whether rotation
+ * (a) answered (#1032): the async twin is {@link atomicWriteText}, not a
+ * promise mode on this function; and (b) whether rotation
  * belongs here after all (it does only if ≥2 migrated callers want the SAME
  * keep-N). If NO caller ever passes `backup: true` in production, that half is
  * still the part to shrink back.
@@ -982,7 +986,9 @@ export function writeJsonAtomicSync(filePath, data, opts = {}) {
  *   Injectable fs (tests). Omitted methods fall back to `node:fs` — EXCEPT on
  *   the backup path, which fails closed (see below).
  * @returns {{ ok: true, path: string, bytes: number, backupPath: string|null }
- *   | { ok: false, reason: 'fs-error', error: string }}
+ *   | { ok: false, reason: 'fs-error', error: string, code: string|null }}
+ *   `code` is the failing call's `err.code`, or `null` when there was none
+ *   (additive, #1032 — a caller that must re-throw with the same code can now).
  */
 export function atomicWriteWithBackup(filePath, body, opts = {}) {
   const {
@@ -1016,20 +1022,15 @@ export function atomicWriteWithBackup(filePath, body, opts = {}) {
   // methods are guarded, not just `copyFileSync` — a missing `existsSync` probes
   // the real target and silently decides the backup branch from it, which is the
   // same escape one step earlier.
-  if (backup && injectedFs) {
-    for (const method of ['existsSync', 'copyFileSync']) {
-      if (typeof injectedFs[method] !== 'function') {
-        return {
-          ok: false,
-          reason: 'fs-error',
-          error: `partial fs adapter: ${method} required for backup`,
-        };
-      }
-    }
-  }
+  const refusal = _partialAdapterRefusal(backup, injectedFs, ['existsSync', 'copyFileSync']);
+  if (refusal) return refusal;
 
+  // Assigned BEFORE the write, and cleanup keys on it rather than on the write
+  // having returned: `writeFileSync` can create the tmp file and THEN throw
+  // (ENOSPC / EIO mid-write), and a flag set only after it returned leaked
+  // exactly that file (#1032). Unlinking a tmp that was never created throws
+  // ENOENT, which the cleanup swallows.
   let tmpFile = null;
-  let tmpCreated = false;
 
   try {
     const dir = dirname(filePath);
@@ -1037,34 +1038,170 @@ export function atomicWriteWithBackup(filePath, body, opts = {}) {
 
     let backupPath = null;
     if (backup && fsExists(filePath)) {
-      const stamp = (now instanceof Date ? now : new Date()).toISOString().replace(/[:.]/g, '-');
-      backupPath = `${filePath}.bak-${stamp}`;
+      backupPath = _backupPathFor(filePath, now);
       fsCopyFile(filePath, backupPath);
     }
 
-    tmpFile = path.join(dir, `${tmpPrefix}.${randomBytes(6).toString('hex')}`);
+    tmpFile = _tmpPathFor(dir, tmpPrefix);
     fsWriteFile(tmpFile, body, encoding);
-    tmpCreated = true;
     fsRename(tmpFile, filePath);
 
-    return {
-      ok: true,
-      path: filePath,
-      bytes: Buffer.isBuffer(body) ? body.length : Buffer.byteLength(String(body), encoding),
-      backupPath,
-    };
+    return { ok: true, path: filePath, bytes: _byteLength(body, encoding), backupPath };
   } catch (err) {
-    // Only when the write got far enough to create it. The name carries 12 hex
-    // chars of entropy, so this cannot collide with a caller's real file.
-    if (tmpCreated) {
+    // The name carries 12 hex chars of entropy, so this cannot collide with a
+    // caller's real file.
+    if (tmpFile !== null) {
       try {
         fsUnlink(tmpFile);
       } catch {
         // Best-effort: never let cleanup replace the error the caller needs.
       }
     }
-    return { ok: false, reason: 'fs-error', error: err?.message ?? String(err) };
+    return _fsErrorEnvelope(err);
+  }
+}
+
+/**
+ * Async twin of {@link atomicWriteWithBackup} (#1032): same tmp naming
+ * (`<dir>/<tmpPrefix>.<12 hex>`), same backup stamp, SAME envelope — and like
+ * the sync helper it RESOLVES on failure and never rejects. A `promise` mode on
+ * the sync function was rejected on purpose: one contract with two failure
+ * directions (`ok:false` vs. reject) is the bug class this envelope exists to
+ * end. Callers whose contract is to throw re-raise via {@link envelopeToError},
+ * which keeps the message and `err.code`.
+ *
+ * Shared with the sync helper: tmp/backup naming, byte count, the error
+ * envelope and the partial-adapter refusal. The five-step flow itself is
+ * spelled twice — sync calls and awaited calls cannot share one body without a
+ * generator driver, which would put an indirection on the hook-hot sync path
+ * for ~15 lines of saved control flow.
+ *
+ * Backup differs in one detail: it copies and treats `ENOENT` as "first write,
+ * nothing to snapshot" instead of probing `existsSync` first — the same result
+ * without a check-then-act window.
+ *
+ * @param {string} filePath  Target path; parent dirs created with mkdir -p semantics.
+ * @param {string|Buffer} body  Bytes to write, verbatim. Never inspected.
+ * @param {object} [opts]
+ * @param {BufferEncoding} [opts.encoding='utf8']  Encoding for a string `body`.
+ * @param {boolean} [opts.backup=false]  Snapshot the existing file to `.bak-<ISO>` first.
+ * @param {string} [opts.tmpPrefix='.tmp']  Tmp-file prefix (callers pick their domain prefix).
+ * @param {Date} [opts.now]  Clock seam for the backup stamp (tests).
+ * @param {{ mkdir?: Function, writeFile?: Function, rename?: Function,
+ *   copyFile?: Function, unlink?: Function }} [opts.fs]
+ *   Injectable `fs/promises`-shaped object (tests). Omitted methods fall back to
+ *   `node:fs/promises` — except `copyFile` under `backup: true`, which fails closed.
+ * @returns {Promise<{ ok: true, path: string, bytes: number, backupPath: string|null }
+ *   | { ok: false, reason: 'fs-error', error: string, code: string|null }>}
+ */
+export async function atomicWriteText(filePath, body, opts = {}) {
+  const {
+    encoding = 'utf8',
+    backup = false,
+    tmpPrefix = '.tmp',
+    now = new Date(),
+    fs: injectedFs,
+  } = opts;
+
+  const fsMkdir = injectedFs?.mkdir ?? mkdir;
+  const fsWriteFile = injectedFs?.writeFile ?? writeFile;
+  const fsRename = injectedFs?.rename ?? rename;
+  const fsCopyFile = injectedFs?.copyFile ?? copyFile;
+  const fsUnlink = injectedFs?.unlink ?? unlink;
+
+  const refusal = _partialAdapterRefusal(backup, injectedFs, ['copyFile']);
+  if (refusal) return refusal;
+
+  let tmpFile = null;
+
+  try {
+    const dir = dirname(filePath);
+    await fsMkdir(dir, { recursive: true });
+
+    let backupPath = null;
+    if (backup) {
+      const candidate = _backupPathFor(filePath, now);
+      try {
+        await fsCopyFile(filePath, candidate);
+        backupPath = candidate;
+      } catch (err) {
+        if (err?.code !== 'ENOENT') throw err;
+      }
+    }
+
+    tmpFile = _tmpPathFor(dir, tmpPrefix);
+    await fsWriteFile(tmpFile, body, encoding);
+    await fsRename(tmpFile, filePath);
+
+    return { ok: true, path: filePath, bytes: _byteLength(body, encoding), backupPath };
+  } catch (err) {
+    if (tmpFile !== null) {
+      try {
+        await fsUnlink(tmpFile);
+      } catch {
+        // Best-effort: never let cleanup replace the error the caller needs.
+      }
+    }
+    return _fsErrorEnvelope(err);
+  }
+}
+
+/**
+ * Re-raise a failed {@link atomicWriteText} / {@link atomicWriteWithBackup}
+ * envelope as an Error carrying the original message and `code`, for call-sites
+ * whose own contract is to throw (#1032).
+ *
+ * @param {{ error: string, code?: string|null }} envelope
+ * @returns {Error & { code?: string }}
+ */
+export function envelopeToError(envelope) {
+  const err = new Error(envelope.error);
+  if (envelope.code) err.code = envelope.code;
+  return err;
+}
+
+/** @returns {{ ok: false, reason: 'fs-error', error: string, code: string|null }} */
+function _fsErrorEnvelope(err) {
+  return {
+    ok: false,
+    reason: 'fs-error',
+    error: err?.message ?? String(err),
+    code: typeof err?.code === 'string' ? err.code : null,
+  };
+}
+
+/**
+ * Backup-path fail-closed for a partial injected adapter (see the rationale in
+ * {@link atomicWriteWithBackup}). Returns the refusal envelope, or null.
+ */
+function _partialAdapterRefusal(backup, injectedFs, methods) {
+  if (!backup || !injectedFs) return null;
+  for (const method of methods) {
+    if (typeof injectedFs[method] !== 'function') {
+      return {
+        ok: false,
+        reason: 'fs-error',
+        error: `partial fs adapter: ${method} required for backup`,
+        code: null,
+      };
+    }
   }
+  return null;
+}
+
+/** `<filePath>.bak-<ISO>` with `:`/`.` → `-`, so a lexical sort is chronological. */
+function _backupPathFor(filePath, now) {
+  const stamp = (now instanceof Date ? now : new Date()).toISOString().replace(/[:.]/g, '-');
+  return `${filePath}.bak-${stamp}`;
+}
+
+/** Sibling tmp path (same filesystem → atomic rename): `<dir>/<tmpPrefix>.<12 hex>`. */
+function _tmpPathFor(dir, tmpPrefix) {
+  return path.join(dir, `${tmpPrefix}.${randomBytes(6).toString('hex')}`);
+}
+
+function _byteLength(body, encoding) {
+  return Buffer.isBuffer(body) ? body.length : Buffer.byteLength(String(body), encoding);
 }
 
 /**

package/scripts/lib/learnings/candidates.mjs

@@ -48,11 +48,11 @@
  * re-derived (not re-cited) if a threshold is ever revisited.
  *
  * **Stage 0 — corpus prep (once per run).**
- *   1. Read through the existing funnel (`io.mjs::readLearnings` →
- *      `schema.mjs::normalizeLearning`) so producer dialects (`files` →
- *      `file_paths`) and type aliases (`gotcha` → `anti-pattern`) are already
- *      canonical. The in-memory entry point re-applies {@link normalizeDialects}
- *      so both entry points score the same shape.
+ *   1. Canonicalise producer dialects (`files` → `file_paths`) and type
+ *      aliases (`gotcha` → `anti-pattern`): the caller reads through the
+ *      existing funnel (`io.mjs::readLearnings` → `schema.mjs::normalizeLearning`),
+ *      and the entry point re-applies {@link normalizeDialects} so raw
+ *      in-memory records score the same shape.
  *   2. Drop expired records — they may neither seed a pool nor join one.
  *   3. Derive `learning_key` = `` `${type}/${kebab(title || subject)}` `` using
  *      the SHARED {@link kebab}. A divergent kebab does not produce an ugly
@@ -184,7 +184,6 @@
  */
 
 import { tokenize } from './affinity.mjs';
-import { readLearnings } from './io.mjs';
 import { learningKeyOf } from './kebab.mjs';
 import { normalizeDialects } from './schema.mjs';
 
@@ -218,7 +217,7 @@ export const PATH_BOOST_EXACT = 0.05;
 export const PATH_BOOST_DIR = 0.025;
 
 /** How many leading directory segments define the directory-prefix boost. */
-export const DIR_PREFIX_SEGMENTS = 2;
+const DIR_PREFIX_SEGMENTS = 2;
 
 /**
  * Documented ceiling for consumers (accepted failure mode 2): a pool graph walk
@@ -229,7 +228,7 @@ export const DIR_PREFIX_SEGMENTS = 2;
 export const MAX_POOL_HOPS = 2;
 
 /** Token length floor — tokens shorter than this are dropped before stoplisting. */
-export const MIN_TOKEN_LENGTH = 3;
+const MIN_TOKEN_LENGTH = 3;
 
 /** Cap on the reported `sharedTokens` — a diagnostic for the judge, not a payload. */
 const SHARED_TOKEN_CAP = 8;
@@ -705,23 +704,3 @@ export function buildCandidatePools(records, opts = {}) {
     return emptyPools();
   }
 }
-
-/**
- * File entry-point: read through the existing funnel (`readLearnings` →
- * `normalizeLearning`, so dialects and type aliases are canonical), then pool.
- *
- * There is no second reader here on purpose — a private read path would be a
- * second place for the dialect normalization to drift out of.
- *
- * @param {string} filePath — absolute path to learnings.jsonl
- * @param {object} [opts] — everything {@link buildCandidatePools} accepts
- * @returns {Promise<CandidatePools>} {@link emptyPools} on a missing/unreadable file
- */
-export async function buildCandidatePoolsFromFile(filePath, opts = {}) {
-  try {
-    const { entries } = await readLearnings(filePath);
-    return buildCandidatePools(entries, opts);
-  } catch {
-    return emptyPools();
-  }
-}

package/scripts/lib/learnings/io.mjs

@@ -262,6 +262,11 @@ export async function readLearningsSnapshot(filePath) {
  * malformed too (#1500): `normalizeLearning` turned it into a record of
  * defaults alone, and every rewrite wrote that invented record back.
  *
+ * A UTF-8 BOM (U+FEFF) in front of the FIRST line — an editor's save — is
+ * stripped before parsing, so that line is an entry, not malformed (#1506.5b).
+ * A BOM inside the file (line 2+) stays malformed: that is a concatenation
+ * artefact the drop-malformed preview reports as `bom`.
+ *
  * @param {string} raw
  * @returns {{entries: object[], malformed: string[], malformedLineNumbers: number[]}}
  *   `malformedLineNumbers[i]` is the 1-based line of `malformed[i]` in `raw`
@@ -273,7 +278,7 @@ export function parseLearningsText(raw) {
   raw.split('\n').forEach((line, i) => {
     if (line.trim().length === 0) return;
     try {
-      const parsed = JSON.parse(line);
+      const parsed = JSON.parse(i === 0 && line.charCodeAt(0) === 0xfeff ? line.slice(1) : line);
       if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
         throw new TypeError('not a JSON object');
       }
@@ -414,7 +419,7 @@ const BACKUP_KEEP = 3;
  * @param {string} fileName — sibling filename to classify
  * @returns {string|null} the suffix after the delimiter, or `null`
  */
-export function backupSuffixOf(baseName, fileName) {
+function backupSuffixOf(baseName, fileName) {
   const stem = `${baseName}.bak`;
   if (!fileName.startsWith(stem)) return null;
   const delim = fileName[stem.length];

package/scripts/lib/learnings/judgment.mjs

@@ -145,10 +145,7 @@ export const JUDGMENT_DECISIONS = Object.freeze([
 ]);
 
 /** Decisions that assert a relation to at least one other record. */
-export const RELATION_DECISIONS = Object.freeze(['refine', 'supersede', 'merge', 'contradict']);
-
-/** Decisions that assert no relation (`skip`) or no judgment (`abstain`). */
-export const NO_RELATION_DECISIONS = Object.freeze(['skip', 'abstain']);
+const RELATION_DECISIONS = Object.freeze(['refine', 'supersede', 'merge', 'contradict']);
 
 /**
  * The eight failure modes. Closed set — the free-text `detail` field carries
@@ -174,7 +171,7 @@ export const FAILURE_MODES = Object.freeze([
  * on purpose: registering the AUQ in the SAME map as the archive writer is what
  * makes "an AUQ is a write" structural rather than a comment someone can miss.
  */
-export const EFFECT_BY_DECISION = Object.freeze({
+const EFFECT_BY_DECISION = Object.freeze({
   skip: null,
   abstain: null,
   refine: 'refine',
@@ -191,7 +188,7 @@ export const EFFECT_BY_DECISION = Object.freeze({
  * the corpus develops genuine clusters (max pairwise similarity > ~0.4) or if
  * live judgments start naming a truncated-away record in their rationale.
  */
-export const DEFAULT_MAX_NEIGHBOURS = 12;
+const DEFAULT_MAX_NEIGHBOURS = 12;
 
 /**
  * Judge wall-clock budget. Ceiling: 60s — a judgment pass runs at session-end
@@ -206,7 +203,7 @@ export const DEFAULT_JUDGE_TIMEOUT_MS = 60_000;
  * the judge to lean on `scope` or `host_class` would be steering it by a field
  * that is constant across the corpus.
  */
-export const SURFACE_HINT = [
+const SURFACE_HINT = [
   'Judge the SURFACE, not the subject line.',
   '',
   'Measured 2026-08-13 over the 100 live records: `scope` is "local" in 100/100 and',
@@ -233,7 +230,7 @@ export const SURFACE_HINT = [
  * restatement drifts silently, and the failure mode of drift here is that every
  * batch voids and the feature is dead while looking wired.
  */
-export const JUDGMENT_OUTPUT_CONTRACT = [
+const JUDGMENT_OUTPUT_CONTRACT = [
   'Answer with JSON only, exactly this shape:',
   '',
   '{"candidate_id": "<the candidate id you were given>",',

package/scripts/lib/learnings/select.mjs

@@ -182,7 +182,7 @@ export const DEFAULT_MAX_GLOBAL = 4;
  * overlaps only, so a directory-prefix match scores 0.75 without appearing
  * there. Using it as a proxy would silently drop the strongest partial matches.
  */
-export const SCOPE_MATCH_MIN_PATH_SCORE = 0.25;
+const SCOPE_MATCH_MIN_PATH_SCORE = 0.25;
 
 /**
  * Blend of relevance (affinity to this agent's scope) against quality
@@ -190,7 +190,7 @@ export const SCOPE_MATCH_MIN_PATH_SCORE = 0.25;
  * IS the acceptance criterion. Weight-normalized like `affinity()`, so the
  * result stays in [0,1] for any non-negative pair.
  */
-export const SELECT_WEIGHTS = Object.freeze({ relevanceWeight: 0.7, qualityWeight: 0.3 });
+const SELECT_WEIGHTS = Object.freeze({ relevanceWeight: 0.7, qualityWeight: 0.3 });
 
 /**
  * How many active entries the file entry-point pulls before ranking.
@@ -496,7 +496,7 @@ export function renderIndexLine(entry, opts = {}) {
  * @param {{now?: Date|number, decay?: object, affinityOpts?: object}} [opts]
  * @returns {{score: number, relevance: number, quality: number, pathScore: number}}
  */
-export function scoreLearning(entry, scope, opts = {}) {
+function scoreLearning(entry, scope, opts = {}) {
   const zero = { score: 0, relevance: 0, quality: 0, pathScore: 0 };
   if (!_isRecord(entry)) return zero;
 

package/scripts/lib/maintenance-due-banner.mjs

@@ -73,7 +73,7 @@
 import { existsSync, statSync } from 'node:fs';
 import path from 'node:path';
 
-import { SCAN_CHUNK_BYTES, scanEventsBackwards } from './events.mjs';
+import { SCAN_CHUNK_BYTES, eventsFilePath, scanEventsBackwards } from './events.mjs';
 import { computeReconcileNudge } from './reconcile-nudge-banner.mjs';
 import { sweepExpiredLearnings } from './learnings/expiry-sweep.mjs';
 import { shouldDispatchAutoDialectic } from './auto-dialectic.mjs';
@@ -204,7 +204,7 @@ export const EVOLVE_SCAN_BUDGET_MS = 1000;
  *   `events-rotation.max-backups`), so a miss has not proven "never" either.
  */
 function readLastEvolveRun(repoRoot) {
-  const file = path.join(repoRoot, '.orchestrator', 'metrics', 'events.jsonl');
+  const file = eventsFilePath(repoRoot); // #1514: the repo's one ledger
   let lastAt = null;
   const scan = scanEventsBackwards({
     filePath: file,

package/scripts/lib/memory-proposals/sink.mjs

@@ -42,11 +42,11 @@
  */
 
 import { appendFile, mkdir, readdir, rm } from 'node:fs/promises';
-import { writeFileSync, renameSync, readFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync } from 'node:fs';
 import path from 'node:path';
-import crypto from 'node:crypto';
 import { appendLearning } from '../learnings/io.mjs';
 import { validatePathInsideProject } from '../path-utils.mjs';
+import { atomicWriteWithBackup } from '../io.mjs';
 
 // ---------------------------------------------------------------------------
 // Path constants (relative to repoRoot)
@@ -320,10 +320,9 @@ export async function clearProposalsJsonl({ repoRoot }) {
     // target — a concurrent hook reading proposals.jsonl mid-clear observes
     // either the pre-clear content or the fully-cleared file, never a
     // partial truncate.
-    const tmpSuffix = crypto.randomBytes(6).toString('hex');
-    const tmpFile = path.join(metricsDirPath, `.proposals.jsonl.tmp.${tmpSuffix}`);
-    writeFileSync(tmpFile, '', 'utf8');
-    renameSync(tmpFile, proposalsPath);
+    // Same tmp-name shape as before: `.proposals.jsonl.tmp.<12 hex>`.
+    const res = atomicWriteWithBackup(proposalsPath, '', { tmpPrefix: '.proposals.jsonl.tmp' });
+    if (!res.ok) return { cleared: false, summariesCleared: 0 };
   } catch {
     return { cleared: false, summariesCleared: 0 };
   }

package/scripts/lib/memory-proposals/store.mjs

@@ -16,10 +16,10 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import crypto from 'node:crypto';
 import { serializeProposal } from './schema.mjs';
 import { validatePathInsideProject } from '../path-utils.mjs';
 import { tryAcquireFileLock, releaseFileLock } from '../file-lock.mjs';
+import { writeJsonAtomicSync } from '../io.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -285,10 +285,8 @@ function incrementSummary(summaryPath, field) {
     ensureDir(summaryPath);
     const current = readSummary(summaryPath);
     current[field] = (current[field] ?? 0) + 1;
-    const tmpSuffix = crypto.randomBytes(4).toString('hex');
-    const tmpFile = `${summaryPath}.tmp.${tmpSuffix}`;
-    fs.writeFileSync(tmpFile, JSON.stringify(current, null, 2) + '\n', 'utf8');
-    fs.renameSync(tmpFile, summaryPath);
+    // Same bytes (indent 2 + trailing newline); a failure is swallowed as before.
+    writeJsonAtomicSync(summaryPath, current, { tmpPrefix: `.${path.basename(summaryPath)}.tmp` });
   } catch {
     /* best-effort: summary writes are non-critical */
   }

package/scripts/lib/mirror-issues-banner.mjs

@@ -61,7 +61,9 @@ const MESSAGE_ISSUE_CAP = 5;
  *
  * `query-failed` is the residual bucket for a `gh` that ran and exited
  * non-zero for a reason that is neither missing-CLI, timeout, nor auth
- * (network down, repo renamed, rate limit). It is a deliberate fifth member
+ * (network down, repo renamed, rate limit — including GitHub's HTTP 403
+ * rate-limit answer, which `classifyFailure` checks before its 403 → auth
+ * rule). It is a deliberate fifth member
  * beyond the four originally specified: folding those into `parse-error`
  * would mislabel a network failure as malformed output, reintroducing the
  * dishonest-state class this module was built to remove.
@@ -122,6 +124,14 @@ function classifyFailure(err) {
 
   const stderr = err && typeof err === 'object' ? String(/** @type {any} */ (err).stderr ?? '') : '';
   const haystack = `${message}\n${stderr}`.toLowerCase();
+  // Rate limit BEFORE the auth check (#1034 item 2): GitHub answers a primary
+  // or secondary rate limit with HTTP 403, so the `http 403` test below would
+  // otherwise tell the operator to re-authenticate when waiting is the fix. A
+  // 403 without rate-limit wording (expired token, missing scope) stays
+  // `auth-error`, and so does an UNAUTHENTICATED rate limit, whose fix is to
+  // log in. `abuse detection` is GitHub's older wording for the secondary limit.
+  const rateLimited = haystack.includes('rate limit') || haystack.includes('abuse detection');
+  if (rateLimited && !haystack.includes('authenticated requests get a higher')) return 'query-failed';
   if (
     haystack.includes('gh auth login') ||
     haystack.includes('not logged in') ||

package/scripts/lib/native-command.mjs

@@ -0,0 +1,48 @@
+/** Shell-free command launching for native Windows and Unix hosts. */
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+/**
+ * Windows cannot spawn npm's .cmd shim without cmd.exe. Run its JavaScript
+ * entrypoint with this Node instead, preserving each argument literally.
+ * Supports Node's bundled npm (including nvm-windows) and npm on PATH.
+ * Other commands and Unix retain their normal executable lookup.
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {object} [context] Host overrides for platform regression tests.
+ * @returns {{cmd: string, args: string[]}}
+ */
+export function resolveNativeCommand(cmd, args, {
+  platform = process.platform, execPath = process.execPath, env = process.env, exists = existsSync,
+} = {}) {
+  if (platform !== 'win32' || !/^npm(?:\.cmd)?$/i.test(cmd)) return { cmd, args };
+  const winPath = path.win32;
+  const pathKey = Object.keys(env).find((key) => key.toLowerCase() === 'path');
+  const dirs = [winPath.dirname(execPath), ...(env[pathKey] || '').split(';')];
+  for (const dir of dirs) {
+    // Ignore empty/relative PATH entries: never select npm from the working repo.
+    const absolute = dir.replace(/^"(.*)"$/, '$1');
+    if (!winPath.isAbsolute(absolute)) continue;
+    const cli = winPath.join(absolute, 'node_modules', 'npm', 'bin', 'npm-cli.js');
+    if (exists(cli)) return { cmd: execPath, args: [cli, ...args] };
+  }
+  throw Object.assign(new Error('Cannot locate npm-cli.js beside Node or on PATH; install npm with Node.js.'), { code: 'ENOENT' });
+}
+
+/** Like spawnSync, with shell-free Windows npm support and spawn-style errors. */
+export function spawnNativeSync(cmd, args, options = {}) {
+  try {
+    const command = resolveNativeCommand(cmd, args, { env: options.env ?? process.env });
+    return spawnSync(command.cmd, command.args, { ...options, shell: false });
+  } catch (error) {
+    return { error, status: null, stdout: '', stderr: '' };
+  }
+}
+
+/** Test for a command using the host's executable locator, without a shell. */
+export function commandOnPath(bin) {
+  return spawnSync(process.platform === 'win32' ? 'where.exe' : 'which', [bin], {
+    encoding: 'utf8', timeout: 10_000, shell: false,
+  }).status === 0;
+}

package/scripts/lib/orphan-reaper/scan.mjs

@@ -8,6 +8,7 @@
  */
 
 import {
+  GATE_PROCESS_LEDGER_RELPATH,
   killProcessGroup,
   pruneGateProcessLedger,
   readGateProcessLedger,
@@ -25,9 +26,16 @@ import {
 } from './reaper-audit.mjs';
 import { decideReapCandidates, verifyGroupMemberIdentity } from './reaper-decide.mjs';
 
-/** Name const for the one event this module emits. @see docs/events-schema.md */
+/** Name const for the scan-summary event. @see docs/events-schema.md */
 export const REAPER_SCAN_EVENT = 'orchestrator.reaper.scan_completed';
 
+/**
+ * Name const for the degraded-scan event (#1505 point 5a, owner decision
+ * 2026-10-03). An unreadable process register disables the scan; this record
+ * is what makes that countable (HR-105). @see docs/events-schema.md
+ */
+export const LEDGER_UNREADABLE_EVENT = 'orchestrator.ledger.unreadable';
+
 /** Default own-session-id reader. Lazily imported so the static import closure
  *  of this module stays small — it is destined for a hot-path hook (#1432).
  *  @param {string} repoRoot @returns {Promise<string|null>} */
@@ -237,16 +245,34 @@ export async function runOrphanScan({
 
   const { rows, malformed } = parsePsSnapshotDetailed(text);
 
+  // HR-105 (#1505 point 5a): an unreadable register switches the scan off, and
+  // the detached hook child ignores the exit 2 that says so — without a record
+  // the instrument is off with no trace. Once per degraded scan; the scan runs
+  // throttled, so this cannot become a per-fire signal (HR-101). Repo-relative
+  // path only, never a host path. A failing emit never fails the scan.
+  const unreadable = async (reason) => {
+    try {
+      await d.emitEvent(LEDGER_UNREADABLE_EVENT, {
+        path: GATE_PROCESS_LEDGER_RELPATH,
+        reason,
+        consumer: 'orphan-reaper',
+      }, { repoRoot });
+    } catch {
+      /* telemetry that can fail a scan would fail the hook the scan runs in */
+    }
+    return empty('ledger-unreadable', malformed);
+  };
+
   let ledger;
   try {
     ledger = d.readLedger(repoRoot, { nowMs: startedAt });
   } catch {
-    return empty('ledger-unreadable', malformed);
+    return unreadable('reader-threw');
   }
   // The default reader never throws: a refused or unreadable ledger comes back
   // as no records with `state: 'unreadable'` (#1498). Read as "no register
   // hits" it ran a clean-looking scan that measured nothing.
-  if (ledger?.state === 'unreadable') return empty('ledger-unreadable', malformed);
+  if (ledger?.state === 'unreadable') return unreadable('refused');
 
   let ownSessionId = null;
   try {