session-orchestrator 5.7.0 → 5.8.0

package/scripts/lib/peer-cards/writer.mjs

@@ -22,9 +22,9 @@
  * Part of #503 (Wave 2; sibling to schema.mjs / reader.mjs / merger.mjs).
  */
 
-import { writeFile, rename, mkdir, unlink } from 'node:fs/promises';
+import { mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
-import { randomUUID } from 'node:crypto';
+import { atomicWriteText, envelopeToError } from '../io.mjs';
 
 import { validatePeerCardFrontmatter } from './schema.mjs';
 
@@ -118,21 +118,9 @@ export async function writePeerCard(repoRoot, target, card) {
 
   const bodyStr = typeof card.body === 'string' ? card.body : '';
   const content = `${serializeFrontmatter(fm)}\n\n${bodyStr.trimStart()}`;
-  const tmpPath = `${finalPath}.${randomUUID().slice(0, 8)}.tmp`;
-
-  try {
-    await writeFile(tmpPath, content, 'utf8');
-    await rename(tmpPath, finalPath);
-    return { ok: true, path: finalPath };
-  } catch (err) {
-    // Best-effort cleanup of orphaned tmp file. Swallow secondary failures —
-    // the primary error is what the caller needs to see.
-    try {
-      await unlink(tmpPath);
-    } catch {
-      /* tmp file may not exist if writeFile failed before creating it */
-    }
-    throw err;
-  }
+  // The helper unlinks its own tmp on failure; re-raise with the same code.
+  const res = await atomicWriteText(finalPath, content, { tmpPrefix: `.${filename}.tmp` });
+  if (!res.ok) throw envelopeToError(res);
+  return { ok: true, path: finalPath };
 }
 

package/scripts/lib/platform.mjs

@@ -13,7 +13,7 @@
  * NOTHING in this module touches the filesystem at import time.
  */
 
-import { existsSync, realpathSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { resolvePluginRoot as _resolvePluginRootRobust } from './plugin-root.mjs';
@@ -354,9 +354,14 @@ function _isStrictlyInside(child, parent) {
 
 /**
  * The SESSION ROOT (#1492) — the working copy whose control files belong to the
- * session a hook fires in: `wave-scope.json`, the `.orchestrator/` ledgers, the
- * event records. One resolver for every hook that reads them (enforce-scope,
- * enforce-commands, post-bash-write-verify, pre-task-scope-disjoint).
+ * session a hook fires in: `wave-scope.json`, the `filescopes/` manifests, the
+ * `.orchestrator/` dispatch ledger. One resolver for every hook that reads them
+ * (enforce-scope, enforce-commands, post-bash-write-verify,
+ * pre-task-scope-disjoint). The event records are written via
+ * `eventsFilePath(<session root>)` (`scripts/lib/events.mjs`), which maps a
+ * linked worktree to its main checkout — ONE ledger per repo (owner decision on
+ * #1514 point 1), so a worktree session's events stay readable after the
+ * worktree is gone.
  *
  * NOT the launch dir whenever the session works elsewhere: `$CLAUDE_PROJECT_DIR`
  * stays on the dir the session was LAUNCHED in after it enters a worktree
@@ -453,6 +458,109 @@ export function resolveSessionRoot(cwd, toplevel = '') {
   return launch !== '' && _isStrictlyInside(launch, root) ? launch : root;
 }
 
+// ---------------------------------------------------------------------------
+// resolveEventsLedgerRoot (#1514 point 1)
+// ---------------------------------------------------------------------------
+
+/** Repo root holding a `.git` entry → its main checkout ('' = none). Per process. */
+const _mainCheckoutMemo = new Map();
+
+/**
+ * The MAIN checkout of the linked git worktree rooted at `root` (whose `.git`
+ * is a FILE), or `''` when `root` is no linked worktree of a non-bare repo or
+ * its git metadata cannot be read.
+ *
+ * SPAWN-FREE, so it is safe on the hook hot path (every default `emitEvent()`):
+ * git's own on-disk layout answers it. A linked worktree's `.git` file reads
+ * `gitdir: <X>` (X = `<common>/worktrees/<name>`), and `<X>/commondir` names the
+ * common dir relative to X. Only a common dir named `.git` counts — its parent
+ * is the main checkout. A submodule (`gitdir:` into `.git/modules/<name>`, no
+ * `commondir` file) and a bare repo's worktree (common dir `repo.git`) fall
+ * through to `''`. Never throws.
+ *
+ * @param {string} root  a directory holding a `.git` entry
+ * @returns {string}
+ */
+function _mainCheckoutOfLinkedWorktree(root) {
+  if (_mainCheckoutMemo.has(root)) return _mainCheckoutMemo.get(root);
+  let main = '';
+  try {
+    const dotGit = path.join(root, '.git');
+    if (statSync(dotGit).isFile()) {
+      const match = /^gitdir:\s*(.+?)\s*$/m.exec(readFileSync(dotGit, 'utf8'));
+      if (match) {
+        const gitDir = path.resolve(root, match[1]);
+        const commonDir = path.resolve(gitDir, readFileSync(path.join(gitDir, 'commondir'), 'utf8').trim());
+        if (path.basename(commonDir) === '.git' && commonDir !== gitDir) main = path.dirname(commonDir);
+      }
+    }
+  } catch {
+    main = ''; // unreadable metadata, no `commondir` (a submodule) — the caller falls back
+  }
+  _mainCheckoutMemo.set(root, main);
+  return main;
+}
+
+/**
+ * `dir` mapped from a linked worktree to the SAME relative spot in its main
+ * checkout (a launch in a worktree's subdirectory keeps its subdirectory), or
+ * `''` when `dir` sits in no linked worktree.
+ *
+ * @param {string} dir  absolute
+ * @returns {string}
+ */
+function _inMainCheckout(dir) {
+  const ancestor = dotGitAncestor(dir);
+  if (!ancestor) return '';
+  const main = _mainCheckoutOfLinkedWorktree(ancestor);
+  return main ? path.join(main, path.relative(ancestor, dir)) : '';
+}
+
+/**
+ * The root of the ONE events ledger (`<root>/.orchestrator/metrics/events.jsonl`)
+ * — owner decision on #1514 point 1: "Event-Ledger immer im Haupt-Checkout".
+ *
+ * Precedence:
+ *   1. the launch dir from env ({@link launchDirFromEnv}, `path.resolve`d) —
+ *      mapped to the main checkout when it IS a linked worktree. A session
+ *      LAUNCHED in a worktree (headless, offload, Codex) hands its hooks
+ *      `$CLAUDE_PROJECT_DIR` = the worktree; without the mapping its hooks wrote
+ *      the worktree's ledger while its scripts (rung 2) wrote the main one;
+ *   2. when `cwd` sits in a LINKED git worktree, that repo's main checkout.
+ *      Measured 2026-10-03: a Bash-tool command does NOT get
+ *      `$CLAUDE_PROJECT_DIR`, and after `EnterWorktree` its cwd is the
+ *      worktree — without this rung a coordinator-run script (`scope-echo
+ *      --verify`, `materialize-wave-scope`) wrote and read the worktree's
+ *      ledger while the hooks wrote the launch dir's;
+ *   3. {@link getProjectDir} — the pre-#1514 answer, unchanged for a plain
+ *      repo, a bare repo's worktree, a submodule and a non-git directory.
+ *
+ * Spawn-free (see {@link _mainCheckoutOfLinkedWorktree}). Deliberately NOT
+ * folded into `resolveProjectDir()`: every other consumer of the project dir
+ * (config, STATE.md, manifests) keeps its answer.
+ *
+ * `repoRoot` given: the same mapping applied to that root — for a caller that
+ * holds a repo root and wants THE ledger of that repo.
+ *
+ * @param {string} [repoRoot]  an explicit root to map (skips the env/cwd rungs)
+ * @param {string} [cwd=process.cwd()]
+ * @returns {string}  Absolute path
+ */
+export function resolveEventsLedgerRoot(repoRoot, cwd = process.cwd()) {
+  if (typeof repoRoot === 'string' && repoRoot.trim() !== '') {
+    const root = path.resolve(repoRoot);
+    return _inMainCheckout(root) || root;
+  }
+  const launchRaw = launchDirFromEnv();
+  if (launchRaw !== '') {
+    const launch = path.resolve(launchRaw);
+    return _inMainCheckout(launch) || launch;
+  }
+  const ancestor = dotGitAncestor(path.resolve(cwd));
+  const main = ancestor ? _mainCheckoutOfLinkedWorktree(ancestor) : '';
+  return main || getProjectDir();
+}
+
 // ---------------------------------------------------------------------------
 // resolveStateDir
 // ---------------------------------------------------------------------------
@@ -595,6 +703,7 @@ export function _resetPlatformCache() {
   _cache.projectDir = undefined;
   _cache.stateDir = undefined;
   _cache.configFile = undefined;
+  _mainCheckoutMemo.clear();
 }
 
 // The deprecated `export let SO_PLATFORM / SO_PLUGIN_ROOT / SO_PROJECT_DIR /

package/scripts/lib/plugin-package-stage.mjs

@@ -0,0 +1,169 @@
+/**
+ * plugin-package-stage.mjs — the host-local packed copy of this package that
+ * every harness marketplace reads instead of the working checkout.
+ *
+ * WHY: a marketplace registered on the clone copies ALL of it into the
+ * harness's plugin cache. Measured 2026-10-03: Claude Code cached 7557 files
+ * instead of 1164, `.env.local` (NPM_TOKEN) and `.orchestrator/` included
+ * (#1515); the Codex cache on the same host held 15742 files, `.env.local`,
+ * `.orchestrator/` and `tests/` included (#1518). `npm pack` carries only the
+ * package.json `files` allowlist, so the staged copy cannot leak the rest.
+ *
+ * Shared by scripts/self-update.mjs (Claude Code) and scripts/codex-install.mjs
+ * (Codex): one stage dir, one staging routine.
+ */
+
+import {
+  copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, renameSync, rmSync,
+} from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnNativeSync } from './native-command.mjs';
+
+const COMMAND_TIMEOUT_MS = 300_000;
+const WORK_PREFIX = '.stage-';
+// A work dir older than this is the leftover of a killed run (the finally never
+// ran). Ceiling: a concurrent stage that itself runs longer than 60 min would be
+// swept mid-run — npm ci is the slow step at ~minutes; revisit if that changes.
+const STALE_WORK_MS = 60 * 60 * 1000;
+
+/**
+ * Remove `.stage-*` work dirs in `parent` older than STALE_WORK_MS. Only real
+ * directories carrying this helper's exact prefix; a symlink is never followed
+ * or removed. Best effort: a sweep failure never blocks staging.
+ * @param {string} parent
+ * @param {number} [now]
+ */
+export function sweepStaleWorkDirs(parent, now = Date.now()) {
+  let entries;
+  try { entries = readdirSync(parent, { withFileTypes: true }); } catch { return; }
+  for (const entry of entries) {
+    if (!entry.name.startsWith(WORK_PREFIX) || !entry.isDirectory()) continue;
+    const dir = path.join(parent, entry.name);
+    try {
+      const st = lstatSync(dir);
+      if (st.isDirectory() && !st.isSymbolicLink() && now - st.mtimeMs > STALE_WORK_MS) {
+        rmSync(dir, { recursive: true, force: true });
+      }
+    } catch { /* best effort */ }
+  }
+}
+
+/**
+ * `<XDG_CACHE_HOME or ~/.cache>/session-orchestrator/plugin-package`. The XDG
+ * spec says a relative XDG_CACHE_HOME is invalid and must be ignored.
+ * @param {NodeJS.ProcessEnv} [env]
+ * @param {string} [home]
+ * @returns {string}
+ */
+export function resolveStageDir(env = process.env, home = os.homedir()) {
+  const xdg = (env.XDG_CACHE_HOME || '').trim();
+  return path.join(path.isAbsolute(xdg) ? xdg : path.join(home, '.cache'), 'session-orchestrator', 'plugin-package');
+}
+
+/**
+ * Tarball filename from `npm pack --json`. npm <= 11 emits `[ { filename } ]`,
+ * npm >= 12.0.2 `{ "<name>": { filename } }` (same split pack-policy-floor.test
+ * documents for `files`).
+ * @param {unknown} packJson
+ * @returns {string | null}
+ */
+export function packedFilename(packJson) {
+  const entry = Array.isArray(packJson) ? packJson[0] : Object.values(packJson ?? {})[0];
+  return typeof entry?.filename === 'string' && entry.filename !== '' ? entry.filename : null;
+}
+
+/**
+ * Minimal command runner with the shape stagePackage expects.
+ * @returns {{ok: true, stdout: string} | {ok: false, detail: string}}
+ */
+export function spawnRun(cmd, args, { cwd, env } = {}) {
+  const shown = `${cmd} ${args.join(' ')}`;
+  const r = spawnNativeSync(cmd, args, { cwd, env, encoding: 'utf8', timeout: COMMAND_TIMEOUT_MS, maxBuffer: 64 * 1024 * 1024 });
+  if (r.error) return { ok: false, detail: `${shown}: ${r.error.message}` };
+  if (r.status !== 0) {
+    return { ok: false, detail: `${shown} exited ${r.status}: ${(r.stderr || r.stdout || '').trim().slice(-400)}` };
+  }
+  return { ok: true, stdout: r.stdout };
+}
+
+/**
+ * Replace `stageDir` with the extracted `npm pack` of `soRoot`. The work dir
+ * sits beside `stageDir` so every rename stays on one filesystem, and it is
+ * removed on every path out — the previous stage is only swapped out once the
+ * new one is complete and valid, and is put back if the swap itself fails.
+ *
+ * @param {{soRoot: string, stageDir: string, run?: Function, log?: (line: string) => void,
+ *   dryRun?: boolean, installDeps?: boolean,
+ *   validate?: (dir: string) => ({ok: true} | {ok: false, detail: string})}} options
+ *   `installDeps` runs `npm ci --omit=dev --ignore-scripts` in the new copy
+ *   before the swap, for a harness that copies the marketplace as-is (Codex).
+ *   `validate` vets the new copy before the swap; a failure keeps the old stage.
+ * @returns {{ok: true} | {ok: false, detail: string}}
+ */
+export function stagePackage({
+  soRoot, stageDir, run = spawnRun, log = () => {}, dryRun = false, installDeps = false, validate,
+}) {
+  log(`packing ${soRoot} into ${stageDir} (package files only)`);
+  if (dryRun) {
+    run('npm', ['pack', '--json', '--ignore-scripts', '--pack-destination', '<work>']);
+    run('tar', ['-xzf', '<work>/<tarball>', '-C', '<work>']);
+    if (installDeps) run('npm', ['ci', '--omit=dev', '--ignore-scripts'], { cwd: '<work>/package' });
+    return { ok: true };
+  }
+  let work;
+  try {
+    mkdirSync(path.dirname(stageDir), { recursive: true });
+    sweepStaleWorkDirs(path.dirname(stageDir));
+    work = mkdtempSync(path.join(path.dirname(stageDir), WORK_PREFIX));
+    // An inherited silent loglevel suppresses the JSON parsed below.
+    const env = { ...process.env };
+    delete env.npm_config_loglevel;
+    delete env.NPM_CONFIG_LOGLEVEL;
+    // --ignore-scripts explicitly: never rely on the clone's .npmrc for prepack.
+    const pack = run('npm', ['pack', '--json', '--ignore-scripts', '--pack-destination', work], { cwd: soRoot, env });
+    if (!pack.ok) return { ok: false, detail: pack.detail };
+    let filename;
+    try { filename = packedFilename(JSON.parse(pack.stdout)); } catch { filename = null; }
+    if (!filename) return { ok: false, detail: 'npm pack --json reported no tarball filename' };
+    const untar = run('tar', ['-xzf', path.join(work, filename), '-C', work]);
+    if (!untar.ok) return { ok: false, detail: untar.detail };
+    const pkg = path.join(work, 'package');
+    // npm never packs package-lock.json, and every dependency install of the
+    // plugin copy runs `npm ci`, which refuses to run without one.
+    copyFileSync(path.join(soRoot, 'package-lock.json'), path.join(pkg, 'package-lock.json'));
+    if (installDeps) {
+      // The packed copy carries no .npmrc, so the repo's ignore-scripts=true
+      // (SEC-020) has to travel as a flag.
+      const ci = run('npm', ['ci', '--omit=dev', '--ignore-scripts'], { cwd: pkg, env });
+      if (!ci.ok) return { ok: false, detail: ci.detail };
+    }
+    if (validate) {
+      const verdict = validate(pkg);
+      if (!verdict.ok) return { ok: false, detail: verdict.detail };
+    }
+    const previous = path.join(work, 'previous');
+    const hadPrevious = existsSync(stageDir);
+    if (hadPrevious) renameSync(stageDir, previous);
+    try {
+      renameSync(pkg, stageDir);
+    } catch (error) {
+      // Put the old stage back before the finally deletes the work dir with it.
+      // If even that fails, keep the work dir: it is the only copy left.
+      if (hadPrevious) {
+        try {
+          renameSync(previous, stageDir);
+        } catch (restoreError) {
+          work = undefined;
+          throw new Error(`${error.message}; restoring the previous stage failed (${restoreError.message}) — it is kept at ${previous}`, { cause: restoreError });
+        }
+      }
+      throw error;
+    }
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, detail: `staging ${stageDir}: ${error.message}` };
+  } finally {
+    if (work) rmSync(work, { recursive: true, force: true });
+  }
+}

package/scripts/lib/plugin-surface.mjs

@@ -0,0 +1,121 @@
+/**
+ * plugin-surface.mjs — the one enumeration of the plugin's public sources
+ * (`commands/*.md`, `skills/<name>/SKILL.md`) and the one hand-written
+ * frontmatter parser the Cursor and Pi wrapper generators share (#1240).
+ *
+ * Four generators derive harness surfaces from the same sources
+ * (`generate-agents-skills.mjs`, `generate-codex-skills.mjs`,
+ * `generate-cursor-adapter.mjs`, `generate-pi-prompts.mjs`). Before this module
+ * the agents/codex pair skipped names with a leading `.` or `_` while the
+ * cursor/pi pair did not, so a `commands/_draft.md` produced Cursor and Pi
+ * wrappers but no Codex or `.agents` mirror. {@link isHiddenSourceName} is now
+ * the single NAME filter all four apply. The file/directory test is not yet
+ * shared: the list helpers here follow symlinks (statSync), while
+ * generate-codex-skills.mjs keeps its own dirent loop, which does not. No
+ * source is a symlink today (`find skills commands -maxdepth 2 -type l` → 0);
+ * revisit when one is added.
+ */
+
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * A source name with a leading `.` or `_` is private (drafts, `_shared/`
+ * helpers, dotfiles) and never becomes a public command or skill.
+ *
+ * @param {string} name file or directory name
+ * @returns {boolean}
+ */
+export function isHiddenSourceName(name) {
+  return /^[._]/.test(name);
+}
+
+function isDir(p) {
+  try { return statSync(p).isDirectory(); } catch { return false; }
+}
+
+function isFile(p) {
+  try { return statSync(p).isFile(); } catch { return false; }
+}
+
+/**
+ * Public `commands/*.md` file names (with extension), sorted.
+ *
+ * @param {string} root plugin root
+ * @returns {string[]}
+ */
+export function listCommandFiles(root) {
+  const dir = path.join(root, 'commands');
+  if (!isDir(dir)) return [];
+  return readdirSync(dir)
+    .filter((name) => name.endsWith('.md') && !isHiddenSourceName(name) && isFile(path.join(dir, name)))
+    .sort();
+}
+
+/**
+ * Public `skills/<name>` directory names that carry a SKILL.md, sorted.
+ *
+ * @param {string} root plugin root
+ * @returns {string[]}
+ */
+export function listSkillDirs(root) {
+  const dir = path.join(root, 'skills');
+  if (!isDir(dir)) return [];
+  return readdirSync(dir)
+    .filter((name) => !isHiddenSourceName(name) && isDir(path.join(dir, name)) && existsSync(path.join(dir, name, 'SKILL.md')))
+    .sort();
+}
+
+/**
+ * Parse YAML-ish frontmatter including `>` / `|` folded scalars, returning
+ * DECODED values (one layer of surrounding quotes stripped). Not js-yaml on
+ * purpose: the Cursor/Pi wrappers re-emit these values verbatim, and every
+ * merged skill uses `description: >`, which this parser folds to its text.
+ *
+ * A UTF-8 BOM before the opening `---`, or CRLF line endings, used to make the
+ * probes below miss the block entirely: the file parsed as "no frontmatter",
+ * so every flag in it (`user-invocable`, `disable-model-invocation`) silently
+ * disappeared and the skill was demoted out of the generated surface with no
+ * diagnostic anywhere. Both are normalised away first — the same treatment
+ * `parseAgentFrontmatter` (`scripts/lib/agent-frontmatter.mjs`) gives them.
+ *
+ * NOT replaced by the shared `parseSkillFrontmatter`: that one returns the
+ * `__BLOCK_SCALAR__` sentinel for a `description: >`, which would be emitted
+ * as the wrapper description.
+ *
+ * @param {string} content
+ * @returns {Record<string, string>}
+ */
+export function parseFrontmatter(content) {
+  const text = (content.charCodeAt(0) === 0xfeff ? content.slice(1) : content).replace(/\r\n?/g, '\n');
+  if (!text.startsWith('---\n')) return {};
+  const end = text.indexOf('\n---\n', 4);
+  if (end === -1) return {};
+
+  const lines = text.slice(4, end).split('\n');
+  const fields = {};
+  let i = 0;
+  while (i < lines.length) {
+    const match = lines[i].match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!match) {
+      i += 1;
+      continue;
+    }
+    const key = match[1];
+    const raw = match[2];
+    if (raw === '>' || raw === '| ' || raw === '|' || raw === '>-' || raw === '|-') {
+      const folded = [];
+      i += 1;
+      while (i < lines.length && (lines[i].startsWith(' ') || lines[i].startsWith('\t') || lines[i] === '')) {
+        folded.push(lines[i].replace(/^\s+/, ''));
+        i += 1;
+      }
+      const joiner = raw.startsWith('|') ? '\n' : ' ';
+      fields[key] = folded.filter(Boolean).join(joiner).trim();
+      continue;
+    }
+    fields[key] = raw.replace(/^["']|["']$/g, '');
+    i += 1;
+  }
+  return fields;
+}

package/scripts/lib/quality-gate.mjs

@@ -62,7 +62,7 @@
  */
 
 import { spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -75,6 +75,7 @@ import {
   spawnInGroup,
 } from './process-group.mjs';
 import { redactDiagnosticsBundle } from './quality-gate/diagnostics.mjs';
+import { atomicWriteWithBackup, writeJsonAtomicSync } from './io.mjs';
 import { readProcessLocalSessionIds } from './session-identity/own-session.mjs';
 
 export { redactDiagnosticsBundle } from './quality-gate/diagnostics.mjs';
@@ -406,12 +407,10 @@ function writeLastGreenSha(repoRoot) {
     if (sha.status !== 0 || !sha.stdout) return;
     const head = sha.stdout.trim();
     if (!head) return;
-    const runtimeDir = join(repoRoot, '.orchestrator', 'runtime');
-    mkdirSync(runtimeDir, { recursive: true });
-    const target = join(runtimeDir, 'last-green-sha.txt');
-    const tmp = `${target}.tmp-${process.pid}-${Date.now()}`;
-    writeFileSync(tmp, head + '\n', 'utf8');
-    renameSync(tmp, target);
+    // Never throws; an fs failure is the same silent best-effort as before.
+    atomicWriteWithBackup(join(repoRoot, '.orchestrator', 'runtime', 'last-green-sha.txt'), head + '\n', {
+      tmpPrefix: '.tmp-last-green-sha',
+    });
   } catch {
     // best-effort
   }
@@ -657,14 +656,12 @@ function readCorrectiveContext(repoRoot) {
 function writeDiagnosticsBundle(repoRoot, bundle) {
   try {
     const dir = join(repoRoot, '.orchestrator', 'metrics', 'verification-failures');
-    mkdirSync(dir, { recursive: true });
     // Replace colons in ISO timestamp for cross-fs portability.
     const ts = new Date().toISOString().replace(/:/g, '-');
     const target = join(dir, `${ts}.json`);
-    const tmp = `${target}.tmp-${process.pid}-${Date.now()}`;
-    writeFileSync(tmp, JSON.stringify(redactDiagnosticsBundle(bundle), null, 2) + '\n', 'utf8');
-    renameSync(tmp, target);
-    return target;
+    // Same bytes as before: indent 2 + trailing newline, mkdir -p of `dir`.
+    const res = writeJsonAtomicSync(target, redactDiagnosticsBundle(bundle), { tmpPrefix: '.tmp-diagnostics' });
+    return res.ok ? target : null;
   } catch {
     return null;
   }
@@ -842,19 +839,27 @@ export function gateKillFields(run) {
  * through two LLM hops: `skills/wave-executor/wave-loop.md` step 7 hand-writes
  * them, `skills/session-end/metrics-collection.md` § 1.7 parses them back out of
  * the STATE.md Wave History header into sessions.jsonl. `counts` is a SECOND,
- * machine-measured emission of the same fact, and as of 2026-07-31 it has zero
- * readers (`grep -c '"counts"' .orchestrator/metrics/events.jsonl` → 0 across
- * 4404 `orchestrator.quality_gate.*` records).
- *
- * Retiring the prose path needs a producer change no docblock can make:
- * `waves[].*` is PER-WAVE, and gate events carry no `wave_number` (0 of those
- * 4404 records). A session-end reader could only attribute a gate event to a
- * wave by a wall-clock window whose own boundaries (`waves[].started_at` /
- * `completed_at`) are themselves LLM-written — one LLM hop traded for another,
- * against the posture `scripts/lib/eval/session-resolve.mjs` already documents
- * for window-attributed gate events ("a contaminated window means
- * gate-attribution is unsafe"). The concrete remaining work is named in
- * `skills/session-end/metrics-collection.md` § 1.7.
+ * machine-measured emission of the same fact. Measured 2026-10-05 against this
+ * repo's `.orchestrator/metrics/events.jsonl` (main checkout @ 1386a98e; the
+ * file has been rotated since the 4404-record 2026-07-31 reading this note
+ * used to quote): 82 `orchestrator.quality_gate.*` records, 46 carrying
+ * `counts` (`grep '"orchestrator.quality_gate' <file> | grep -c '"counts"'`).
+ *
+ * `waves[].*` is PER-WAVE, so the event needs a per-wave key. The
+ * `scripts/run-quality-gate.mjs` wrapper emits `wave_number` when a wave-scope
+ * sidecar names one (#966 step 1, `resolveWaveNumber`) and OMITS it otherwise —
+ * 37 of the same 82 records carry it
+ * (`grep '"orchestrator.quality_gate' <file> | grep -c '"wave_number"'`).
+ * Readers exist: `skills/session-end/metrics-collection.md` § 1.7 reads
+ * `counts` by `wave_number` first and keeps the STATE.md header only as a
+ * fallback (#966 step 3), and `scripts/lib/convergence-monitor.mjs` folds a
+ * gate record only when it carries both. THIS emitter still sets no
+ * `wave_number` — its records are mid-wave auto-fix retries, so they fall to
+ * that fallback by design. A record without the key could only be attributed
+ * to a wave by a wall-clock window whose own boundaries (`waves[].started_at`
+ * / `completed_at`) are themselves LLM-written, against the posture
+ * `scripts/lib/eval/session-resolve.mjs` documents for window-attributed gate
+ * events ("a contaminated window means gate-attribution is unsafe").
  *
  * Note also that THIS emitter only runs under `verification-auto-fix.enabled:
  * true` (default `false`, and `false` in this repo's Session Config). The gate

package/scripts/lib/reconcile/idempotency.mjs

@@ -57,9 +57,10 @@
  *        (absence reads as `'written'`, the only outcome that existed then).
  */
 
-import { mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
-import { dirname, isAbsolute, join } from 'node:path';
-import { createHash, randomBytes } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { atomicWriteWithBackup } from '../io.mjs';
 
 /** Default repo-relative location of the reconcile-candidate work-queue. */
 export const DEFAULT_STORE_PATH = '.orchestrator/runtime/reconcile-candidates.jsonl';
@@ -159,18 +160,16 @@ function readStore(absPath) {
  * @returns {{ ok: true, lines: number } | { ok: false, reason: 'fs-error', error: string }}
  */
 function writeStore(absPath, records) {
+  let content;
   try {
-    const dir = dirname(absPath);
-    mkdirSync(dir, { recursive: true });
     const body = records.map((r) => JSON.stringify(r)).join('\n');
-    const content = records.length > 0 ? body + '\n' : '';
-    const tmpFile = join(dir, `.reconcile-candidates.${randomBytes(6).toString('hex')}.tmp`);
-    writeFileSync(tmpFile, content, { encoding: 'utf8' });
-    renameSync(tmpFile, absPath);
-    return { ok: true, lines: records.length };
+    content = records.length > 0 ? body + '\n' : '';
   } catch (err) {
     return { ok: false, reason: 'fs-error', error: err?.message ?? String(err) };
   }
+  // mkdir -p + tmp + rename; its failure envelope is this function's own.
+  const res = atomicWriteWithBackup(absPath, content, { tmpPrefix: '.reconcile-candidates.tmp' });
+  return res.ok ? { ok: true, lines: records.length } : res;
 }
 
 /**