session-orchestrator 5.6.0 → 5.8.0

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 */
   }
@@ -413,7 +411,10 @@ export async function appendProposal({
  * Reads proposals.jsonl without acquiring the lock — suitable for diagnostics
  * and reads where eventual consistency is acceptable.
  *
- * Returns 0 when the file does not exist.
+ * Returns 0 when the file does not exist (silently — `countWaveLines` maps
+ * ENOENT to 0). Any other read failure also returns 0, but with a stderr WARN
+ * so a 0 caused by an unreadable file is distinguishable from an empty queue
+ * (#1216).
  *
  * @param {object} opts
  * @param {string} opts.repoRoot
@@ -424,7 +425,11 @@ export async function countProposalsForWave({ repoRoot, waveId }) {
   const jsonlPath = jsonlPathFor(repoRoot);
   try {
     return countWaveLines(jsonlPath, waveId);
-  } catch {
+  } catch (err) {
+    process.stderr.write(
+      `[memory-proposals] WARN: countProposalsForWave: ` +
+        `${err?.code ?? '?'}: ${err?.message ?? String(err)} — returning 0\n`,
+    );
     return 0;
   }
 }

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 {

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 });
+  }
+}