session-orchestrator 5.7.0 → 5.9.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-wave.mjs

@@ -0,0 +1,40 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { classifyManifestSession, readProcessLocalSessionIds } from './session-identity/own-session.mjs';
+import { findOwnScopeFile } from './scope-gate.mjs';
+
+/**
+ * Resolve the active wave number from the wave-scope sidecar (#966 step 1).
+ *
+ * Mirrors `resolveWave()` in `hooks/pre-bash-memory-propose-audit.mjs` — the
+ * same `.{pi,cursor,codex,claude}/wave-scope.json` precedence via
+ * {@link findOwnScopeFile}, skipping a PEER session's manifest in the same
+ * working copy (#1504: a peer-only result is no wave of ours, never the peer's
+ * number) — with ONE deliberate difference: the hook returns `0` for "no
+ * wave-scope file", this returns `null`.
+ *
+ * Absent is not zero. A human running `npm run quality-gate` from a `git push`
+ * has no wave at all, and that is the common case; publishing `wave_number: 0`
+ * would invent a wave 0 that every consumer then has to special-case. The
+ * caller spreads the result so the KEY is omitted, exactly as `counts` is.
+ *
+ * A non-positive, unsafe or non-integer `wave` field is treated the same way — waves
+ * are 1-indexed, so `0` on disk carries no more information than an absent file.
+ *
+ * Never throws.
+ *
+ * @param {string} projectDir — directory whose wave-scope sidecar to read.
+ * @returns {number|null} positive safe integer wave number, or `null` when there is no wave.
+ */
+export function resolveWaveNumber(projectDir) {
+  try {
+    const ownIds = new Set(readProcessLocalSessionIds({ env: process.env, hookInput: null }));
+    const { path: waveFile } = findOwnScopeFile(projectDir, ownIds, classifyManifestSession);
+    if (!waveFile || !existsSync(waveFile)) return null;
+    const wave = JSON.parse(readFileSync(waveFile, 'utf8'))?.wave;
+    if (!Number.isSafeInteger(wave) || wave <= 0) return null;
+    return wave;
+  } catch {
+    return null;
+  }
+}
+

package/scripts/lib/quality-gate.mjs

@@ -62,11 +62,12 @@
  */
 
 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';
 
 import { emitEvent, sessionAttribution } from './events.mjs';
+import { resolveWaveNumber } from './quality-gate-wave.mjs';
 import { parsePorcelainZ } from './git-porcelain.mjs';
 import { admitSuiteCounts, extractTestCounts } from './gates/gate-helpers.mjs';
 import {
@@ -75,6 +76,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 +408,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 +657,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;
   }
@@ -837,24 +835,30 @@ export function gateKillFields(run) {
  * test gate (fail-fast on lint/typecheck) or its output carried no parseable
  * count. See {@link suiteCountsFromOutput}.
  *
- * IT DOES NOT YET REPLACE THE PROSE PATH (#957/F1 — the earlier wording here
- * claimed it did). `waves[].suite_passed` / `suite_failed` still travel as prose
- * 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.
+ * Both skill readers now take `counts` from `orchestrator.quality_gate.*`:
+ * `skills/wave-executor/references/wave-loop-review.md` step 7 and
+ * `skills/session-end/metrics-collection.md` § 1.7. They filter the flat record
+ * by the same `semantic_session_id` + `wave_number` and select the last
+ * matching gate run; `counts.passed` / `counts.failed` supply the per-wave
+ * `suite_passed` / `suite_failed`. A third reader,
+ * `scripts/lib/convergence-monitor.mjs`, folds `counts` from gate records
+ * that also carry `wave_number`. This library emits ONE record per
+ * `runQualityGateWithRetry` call, not per retry; `attempts` carries retries.
+ *
+ * Both emitters resolve `wave_number` from the existing own-session manifest
+ * at the event's repoRoot and omit it without a usable source. No wall-clock
+ * attribution or guessed wave number is added. Missing counts are not zeros.
+ * Count fallback is limited to pre-#954 sessions, gates outside the event
+ * wrapper, or missing wave attribution; step 7 falls back to this wave's own
+ * gate output (its header is not written yet), session end to the header. Auto-fix with a known wave
+ * uses the event; missing counts alone do not permit header fallback.
+ *
+ * `suite_platform` comes from this wave's gate run (step 7) or the STATE.md
+ * Wave History header `— suite <passed>/<failed> on <platform>` (session end);
+ * the payload has NO platform field.
+ * Event-derived counts may be mirrored into that existing header as
+ * compatibility output, not a second measurement source. Neither the header
+ * nor sessions.jsonl changes its contract.
  *
  * 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
@@ -886,12 +890,14 @@ export function gateKillFields(run) {
  */
 async function emitGateEvent(repoRoot, ok, attempts, gate, counts, killRun = null) {
   try {
+    const waveNumber = resolveWaveNumber(repoRoot);
     await emitEvent(
       `orchestrator.quality_gate.${ok ? 'passed' : 'failed'}`,
       {
         variant: 'auto-fix-loop',
         exit_code: ok ? 0 : 1,
         attempts,
+        ...(waveNumber !== null ? { wave_number: waveNumber } : {}),
         ...(gate ? { gate } : {}),
         ...(counts ? { counts } : {}),
         ...gateKillFields(killRun),