session-orchestrator 5.12.0 → 5.13.0

package/scripts/relocate-vault-corpus.mjs

@@ -53,6 +53,7 @@ import {
   _setResolverForTest,
 } from './lib/vault-relocation-rules.mjs';
 import { buildBackfillIndex, parseSessionId } from './lib/vault-repo-backfill.mjs';
+import { noteIdMatches } from './lib/vault-mirror/utils.mjs';
 import { parseColumnFlags, CliFlagError } from './lib/cli-flags.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
 import { atomicWriteText, envelopeToError } from './lib/io.mjs';
@@ -358,7 +359,7 @@ async function buildCrossRepoIndices(reposRoot) {
  * Only UNANIMOUS mappings are learned; an identity whose source-repo:/repo:
  * sessions disagree on the namespace is left unmapped (ambiguous → no remap).
  *
- * @param {{ sidIndex: Map<string, Set<string>>, parsedVaultSessions: Array<{id:string, frontmatter:object}> }} args
+ * @param {{ sidIndex: Map<string, Set<string>>, parsedVaultSessions: Array<{id:string, sid?:string, frontmatter:object}> }} args
  * @returns {Map<string, string>} identity → canonical namespace
  */
 function learnCanonicalMap({ sidIndex, parsedVaultSessions }) {
@@ -366,11 +367,11 @@ function learnCanonicalMap({ sidIndex, parsedVaultSessions }) {
   // 'AcmeWidgetV2' → 'acmewidgetv2' === 'acme-widget-v2' → 'acmewidgetv2'.
   const normalize = (s) => String(s).toLowerCase().replace(/[^a-z0-9]/g, '');
   const votes = new Map(); // identity → Map<canonicalNs, count>
-  for (const { id, frontmatter } of parsedVaultSessions) {
+  for (const { id, sid = id, frontmatter } of parsedVaultSessions) {
     if (!id || !frontmatter || !hasSessionRepoSignal(frontmatter)) continue;
     const { namespace } = namespaceForSession(frontmatter); // source-repo:/repo: → canonical
     if (!isConfident(namespace)) continue; // skip _unsorted/redacted-repo/unknown-repo
-    const identities = sidIndex.get(id);
+    const identities = sidIndex.get(sid);
     if (!identities) continue;
     // Only an UNAMBIGUOUS source-repo:/repo: note teaches: if its id appears in >1 repo's jsonl,
     // it would mis-teach every other identity its own namespace (collision pollution).
@@ -478,11 +479,14 @@ async function collectParsedVaultSessions(sessionsDir) {
       continue;
     }
     const frontmatter = parseRelocationFrontmatter(content);
+    const stem = path.basename(filePath).replace(/\.md$/, '');
     // Prefer the frontmatter id; fall back to the basename (the session id by convention).
-    const id =
-      (typeof frontmatter.id === 'string' && frontmatter.id.trim()) ||
-      path.basename(filePath).replace(/\.md$/, '');
-    if (id) out.push({ id, frontmatter });
+    const id = (typeof frontmatter.id === 'string' && frontmatter.id.trim()) || stem;
+    // #1602: a namespaced id (`<source-repo>-<session id>`) is no session id; the
+    // cross-repo index joins on the file stem it names. `id` stays the backfill
+    // key, because namespaceForSession looks that index up by `frontmatter.id`.
+    const sid = noteIdMatches(id, stem, frontmatter['source-repo']) ? stem : id;
+    if (id) out.push({ id, sid, frontmatter });
   }
 
   return out;

package/scripts/repair-invalid-sessions.mjs

@@ -47,7 +47,7 @@ import { parseArgs } from 'node:util';
 import path from 'node:path';
 
 import { repairLedger, CANONICAL_LEDGER_REL } from './lib/session-record-repair.mjs';
-import { getProjectDir } from './lib/platform.mjs';
+import { getProjectDir, resolveEventsLedgerRoot } from './lib/platform.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
 
 const USAGE =
@@ -60,7 +60,8 @@ const USAGE =
   CANONICAL_LEDGER_REL +
   ');\n' +
   '                must resolve inside <repo-root>/.orchestrator/metrics/\n' +
-  '  --repo-root   project root (default: resolved project dir)\n' +
+  '  --repo-root   project root (default: the resolved project dir\'s ledger root —\n' +
+  '                its main checkout when run from a linked worktree)\n' +
   'Exit codes: 0 completed, 1 arg error, 2 system error, 3 post-verification failed\n' +
   '            (backup restored), 4 unrepairable remain (N lines kept byte-identical;\n' +
   '            every repairable line fixed — dry-run: would remain)\n';
@@ -77,6 +78,7 @@ const USAGE =
  * @returns {{ok: true, file: string}|{ok: false, metricsDir: string, resolved: string}}
  */
 function resolveLedgerTarget(file, repoRoot) {
+  // ledger-root: explicit --repo-root by design; pre-bash-sessions-ledger-guard judges the same root
   const metricsDir = path.resolve(repoRoot, '.orchestrator', 'metrics');
   // `absFile` (normalized, `..` collapsed) is what the repair uses — NOT the
   // symlink-resolved form, so the canonical-path equality in `verifyWritten`
@@ -108,6 +110,44 @@ function resolveLedgerTarget(file, repoRoot) {
   return { ok: true, file: absFile };
 }
 
+/**
+ * Refuse an explicit `--repo-root` whose ledger path follows a symlink (#1665).
+ * The ledger guard admits the absolute `--apply` form only after
+ * `isSymlinkFreeAbsolute` (hooks/pre-bash-sessions-ledger-guard.mjs) accepted
+ * the root and the ledger, but it checks BEFORE this process runs, and
+ * {@link resolveLedgerTarget} follows symlinks via `realpathSync` — a link
+ * swapped in between the two would redirect the repair (TOCTOU).
+ *
+ * Same rule as the hook: NO component of the path may be a symlink — the root,
+ * every ancestor (so a root under macOS `/tmp` → `/private/tmp` is refused,
+ * exactly as the hook refuses it), `.orchestrator/`, `metrics/` and the ledger
+ * file — and the root must equal its own `realpath`. `lstat` judges the link
+ * itself, never its target. One deliberate difference: a MISSING component is
+ * not a symlink here; the repair reports it as the I/O error it is.
+ *
+ * @param {string} repoRoot - the explicit `--repo-root` value
+ * @param {string} ledgerFile - the requested ledger path under that root
+ * @returns {string|null} the reason to refuse, or null
+ */
+function symlinkRefusal(repoRoot, ledgerFile) {
+  for (let current = path.resolve(ledgerFile); ; current = path.dirname(current)) {
+    try {
+      if (fs.lstatSync(current).isSymbolicLink()) return `${current} is a symlink`;
+    } catch {
+      /* absent — nothing to follow */
+    }
+    if (path.dirname(current) === current) break;
+  }
+  const root = path.resolve(repoRoot);
+  try {
+    const real = fs.realpathSync.native(root);
+    if (real !== root) return `${root} resolves to ${real}`;
+  } catch {
+    /* absent — the repair reports the missing ledger */
+  }
+  return null;
+}
+
 /**
  * Human-readable summary — mirrors `scripts/backfill-abandoned-sessions.mjs`
  * `renderHuman()` so the two migration CLIs read the same way.
@@ -123,6 +163,9 @@ export function renderHuman(s) {
   lines.push(`  invalid before:  ${s.invalid_before}`);
   lines.push(`  ${s.mode === 'apply' ? 'repaired:       ' : 'would repair:   '} ${s.repaired}`);
   lines.push(`  invalid after:   ${s.invalid_after}${s.mode === 'apply' ? '' : ' (projected)'}`);
+  if (s.healed_valid > 0) {
+    lines.push(`  healed (valid):  ${s.healed_valid}`);
+  }
   if (s.unparseable > 0) {
     lines.push(`  unparseable:     ${s.unparseable} (passed through untouched)`);
   }
@@ -148,6 +191,10 @@ export function renderHuman(s) {
   }
   if (s.ok === false) {
     lines.push('  POST-VERIFICATION FAILED — backup restored, ledger unchanged.');
+    // #1670: lines appended after the rename are kept, not rolled back with the repair.
+    if (s.restore_appended_bytes > 0) {
+      lines.push(`  kept:            ${s.restore_appended_bytes} byte(s) appended concurrently after the rename`);
+    }
   } else if (s.errors.length > 0) {
     lines.push(
       s.mode === 'apply'
@@ -201,9 +248,27 @@ async function main() {
 
   // --apply is an explicit opt-in; absent it (or with --dry-run) we never write.
   const apply = values.apply === true && values['dry-run'] !== true;
-  const repoRoot = values['repo-root'] || getProjectDir();
+  // #1592: only the DEFAULT follows the ledger to the main checkout, where
+  // every writer appends. An explicit --repo-root stays the literal target: the
+  // ledger guard sanctions the absolute --apply form only for a --repo-root
+  // equal to the measured Git top-level and outside the resolved vault — mapping
+  // it would let a linked worktree of the vault write the vault's main ledger.
+  const repoRoot = values['repo-root'] || resolveEventsLedgerRoot(getProjectDir());
   const requestedFile = values.file || path.join(repoRoot, CANONICAL_LEDGER_REL);
 
+  // #1665: an explicit root is the whole target identity — never follow a
+  // symlink anywhere on the ledger path, checked BEFORE any I/O (dry-run too).
+  if (values['repo-root']) {
+    const refusal = symlinkRefusal(repoRoot, requestedFile);
+    if (refusal) {
+      process.stderr.write(
+        `repair-invalid-sessions: refusing --repo-root ${repoRoot}: ${refusal} ` +
+          `(the ledger path under an explicit --repo-root must not follow symlinks — #1665)\n`
+      );
+      process.exit(1);
+    }
+  }
+
   // MED-3: bound the target to <repoRoot>/.orchestrator/metrics/ BEFORE any I/O.
   const target = resolveLedgerTarget(requestedFile, repoRoot);
   if (!target.ok) {

package/scripts/resolve-session-invocation.mjs

@@ -1,21 +1,21 @@
 #!/usr/bin/env node
 /** Stdin-only boundary for commands/session.md; never executes task context. */
 import { accessSync, constants, readFileSync, statSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { join } from 'node:path';
 import { parseArgs } from 'node:util';
 import { resolveSessionInvocation } from './lib/session-invocation.mjs';
-import { readCanonicalSessions } from './lib/sessions-canonical.mjs';
-import { isRealSession } from './lib/session-schema/filters.mjs';
+import { readCanonicalSessions, isMeasuredSession } from './lib/sessions-canonical.mjs';
 import { resolveEventsLedgerRoot } from './lib/platform.mjs';
 
 /**
  * One ledger: `false` when absent, `undefined` when present but not a readable
- * file, else whether it holds a real session.
+ * file, else whether it holds a measured session.
  *
  * @param {string} root
  * @returns {boolean|undefined}
  */
 function ledgerHasHistory(root) {
+  // ledger-root: root is resolveEventsLedgerRoot-mapped by the only caller, measureHistory
   const file = join(root, '.orchestrator', 'metrics', 'sessions.jsonl');
   try {
     if (!statSync(file).isFile()) return undefined;
@@ -23,28 +23,21 @@ function ledgerHasHistory(root) {
   } catch (error) {
     return error?.code === 'ENOENT' ? false : undefined;
   }
-  return readCanonicalSessions({ filePath: file }).some(isRealSession);
+  return readCanonicalSessions({ filePath: file }).some(isMeasuredSession);
 }
 
 /**
- * Whether the repo holds a real session of its own: `true`/`false`, or
+ * Whether the repo holds a measured session of its own: `true`/`false`, or
  * `undefined` when that cannot be measured. sessions.jsonl is gitignored, so a
- * linked worktree also reads its main checkout's ledger (`resolveEventsLedgerRoot`);
- * one with history in either place has history. A ledger that exists but
+ * linked worktree reads its main checkout's ledger (`resolveEventsLedgerRoot`),
+ * never a worktree-local shadow. A ledger that exists but
  * cannot be read is "not measured", never "no history".
  *
  * @param {string} repoRoot
  * @returns {boolean|undefined}
  */
 function measureHistory(repoRoot) {
-  const roots = [...new Set([resolve(repoRoot), resolveEventsLedgerRoot(repoRoot)])];
-  let unmeasured = false;
-  for (const root of roots) {
-    const has = ledgerHasHistory(root);
-    if (has === true) return true;
-    if (has === undefined) unmeasured = true;
-  }
-  return unmeasured ? undefined : false;
+  return ledgerHasHistory(resolveEventsLedgerRoot(repoRoot));
 }
 
 const HELP = `Usage: node scripts/resolve-session-invocation.mjs [--json] [--repo-root <dir>] < arguments.txt
@@ -54,7 +47,7 @@ Resolve the leading housekeeping, feature, deep or ultradeep token; preserve
 the rest as task context. Empty input defaults to deep. An invalid mode emits
 a warning and resolves to deep, as the session command has always specified.
 A bare /session in a repo whose .orchestrator/metrics/sessions.jsonl holds no
-real session adds defaultReason "no-session-history": ask for task and mode
+measured session adds defaultReason "no-session-history": ask for task and mode
 before starting. A linked git worktree reads its main checkout's ledger; an
 unreadable ledger counts as not measured and adds nothing.
 

package/scripts/run-migrate-v2-cross-repo.mjs

@@ -30,6 +30,13 @@
  *   2  I/O error — incl. a store lock not acquired under --apply: that repo
  *      is left unwritten and reported `status: 'error'`, the run continues
  *      with the next repo, and exits 2 at the end
+ *   3  --apply on a host whose learnings-store role is `inbox` (#1516): no
+ *      store is rewritten; every repo is still migrated in memory and reported
+ *      `status: 'refused-store-role'`. An I/O error (2) takes precedence.
+ *   4  --apply on a host whose learnings-store role is INVALID (#1516: set but
+ *      not writer|inbox, or owner.yaml unreadable/unparseable): no store is
+ *      rewritten; every repo is still migrated in memory and reported
+ *      `status: 'refused-store-role-invalid'`. An I/O error (2) takes precedence.
  */
 
 import { existsSync, readFileSync, writeFileSync, copyFileSync } from 'node:fs';
@@ -44,6 +51,7 @@ import { LearningsLockError, withLearningsLock } from './lib/learnings/io.mjs';
 import { getCrossRepoProjects, getConfinementRoot } from './lib/config/cross-repo.mjs';
 import { validatePathInsideProject } from './lib/path-utils.mjs';
 import { atomicWriteWithBackup, envelopeToError } from './lib/io.mjs';
+import { resolveStoreRole } from './lib/learnings/store-role.mjs';
 
 const LEARNINGS_REL = '.orchestrator/metrics/learnings.jsonl';
 
@@ -65,6 +73,11 @@ Options:
   --out <path>          Write output to file instead of stdout.
 
 Exit codes:  0 success  1 input error  2 I/O error
+             3 --apply refused: this host's learnings-store role is inbox (#1516),
+               nothing written (repos reported status refused-store-role)
+             4 --apply refused: this host's learnings-store role is invalid (#1516:
+               SO_LEARNINGS_STORE_ROLE or owner.yaml learnings.store-role set but
+               unusable), nothing written (status refused-store-role-invalid)
 `);
   process.exit(0);
 }
@@ -141,7 +154,10 @@ if (reposArg) {
 /**
  * @typedef {Object} RepoResult
  * @property {string} repo       - absolute repo path
- * @property {string} status     - 'skipped' | 'dry-run' | 'applied' | 'error'
+ * @property {string} status     - 'skipped' | 'dry-run' | 'applied' | 'error' |
+ *   'refused-store-role' (--apply on an inbox-role host, #1516: migrated in
+ *   memory, nothing written) | 'refused-store-role-invalid' (--apply while the
+ *   host's store role is invalid, #1516: likewise nothing written)
  * @property {number} total      - total records parsed
  * @property {number} invalidPre - invalid records before migration
  * @property {number} invalidPost - invalid records after migration
@@ -200,6 +216,14 @@ function emptyResult(repoPath, status, error) {
 /** Repos whose store lock was not acquired under --apply (nothing written there). */
 const lockFailedRepos = [];
 
+// #1516: an inbox-role host never rewrites a canonical learnings.jsonl. The role
+// is host-wide (env / owner.yaml), so it is resolved once for every repo.
+// Fail-closed: an INVALID role (set but unusable) refuses as well, with its
+// own status and exit code — only an unset role means writer.
+const storeRole = applyFlag ? resolveStoreRole() : null;
+const refuseStoreWrites = storeRole?.role === 'inbox';
+const refuseInvalidRole = storeRole?.role === 'invalid';
+
 /**
  * Process a single repo. Returns a RepoResult.
  *
@@ -216,6 +240,18 @@ async function processRepo(repoPath, apply) {
   const learningsPath = join(repoPath, LEARNINGS_REL);
 
   if (!existsSync(learningsPath)) return emptyResult(repoPath, 'skipped', null);
+  if (apply && refuseStoreWrites) {
+    const res = migrateStore(repoPath, learningsPath, false);
+    return res.status === 'error'
+      ? res
+      : { ...res, status: 'refused-store-role', error: 'store-role inbox: write skipped' };
+  }
+  if (apply && refuseInvalidRole) {
+    const res = migrateStore(repoPath, learningsPath, false);
+    return res.status === 'error'
+      ? res
+      : { ...res, status: 'refused-store-role-invalid', error: 'store-role invalid: write skipped' };
+  }
   if (!apply) return migrateStore(repoPath, learningsPath, false);
 
   try {
@@ -524,4 +560,23 @@ if (ioFailed.length > 0) {
   exitCode = 2;
 }
 
+const refusedRepos = results.filter((r) => r.status === 'refused-store-role');
+if (refusedRepos.length > 0) {
+  process.stderr.write(
+    `run-migrate-v2: learnings store role is inbox on this host (#1516) — --apply wrote nothing ` +
+      `in ${refusedRepos.length} repo(s); run it on the writer host\n`
+  );
+  if (exitCode === 0) exitCode = 3;
+}
+
+const invalidRoleRepos = results.filter((r) => r.status === 'refused-store-role-invalid');
+if (invalidRoleRepos.length > 0) {
+  process.stderr.write(
+    `run-migrate-v2: learnings store role is invalid on this host (#1516: ${storeRole?.reason}) — ` +
+      `--apply wrote nothing in ${invalidRoleRepos.length} repo(s); fix owner.yaml learnings.store-role ` +
+      `or SO_LEARNINGS_STORE_ROLE\n`
+  );
+  if (exitCode === 0) exitCode = 4;
+}
+
 process.exit(exitCode);

package/scripts/run-quality-gate.mjs

@@ -30,7 +30,7 @@
  *       0 would be a false green (Epic #1425 A3).
  *
  * The gate sub-scripts in scripts/lib/gates/ are NOT reimplemented here; they are
- * invoked via spawnInGroup() — a detached, process-group-leading shell — with the
+ * invoked via spawnInGroup() using argv (a detached group on POSIX) with the
  * required env vars.
  *
  * References:
@@ -59,7 +59,6 @@ import { resolveWaveNumber } from './lib/quality-gate-wave.mjs';
 import { readProcessLocalSessionIds } from './lib/session-identity/own-session.mjs';
 import { gateKillFields } from './lib/quality-gate.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
-import { shellQuote } from './lib/sh-quote.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -226,6 +225,28 @@ function failedFilesFromGateStdout(stdout) {
   return named.length > 0 ? named : null;
 }
 
+/**
+ * Lift `test.rerun` (`{ files, status }`) out of a gate sub-script's JSON
+ * stdout envelope (#1673). Only `gate-full.mjs` publishes it, and only when it
+ * re-ran timeout-only failures. `null` for every other case. Never throws.
+ *
+ * @param {string} stdout — the gate sub-script's captured stdout.
+ * @returns {{ files: string[], status: 'pass'|'fail' }|null}
+ */
+function rerunFromGateStdout(stdout) {
+  if (typeof stdout !== 'string' || !stdout.trim()) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    return null;
+  }
+  const rerun = parsed?.test?.rerun;
+  if (!rerun || !Array.isArray(rerun.files) || (rerun.status !== 'pass' && rerun.status !== 'fail')) return null;
+  const files = rerun.files.filter((f) => typeof f === 'string' && f.trim());
+  return files.length > 0 ? { files, status: rerun.status } : null;
+}
+
 /**
  * The reporting variants — they exit 0 even after a failing check, so their
  * event NAME never carries the check verdict (#1459). `full-gate` exits non-zero
@@ -379,7 +400,9 @@ async function main() {
   if (config) {
     if (existsSync(config)) {
       try {
-        configJson = JSON.parse(readFileSync(config, 'utf8'));
+        // Windows PowerShell 5.1 `Set-Content -Encoding utf8` writes a BOM, which
+        // JSON.parse rejects; the gate then ran the npm defaults instead (#1612).
+        configJson = JSON.parse(readFileSync(config, 'utf8').replace(/^\uFEFF/, ''));
       } catch (err) {
         warn(`Could not parse config file '${config}': ${err.message}; using defaults`);
       }
@@ -496,9 +519,8 @@ async function main() {
   // Handing it a child with `stderr: 'inherit'` leaves `child.stderr` null, the
   // module's own `child.stderr?.on(…)` a no-op, and the gate's warnings live on
   // the operator's terminal exactly as before.
-  // Quoted: the gate path derives from `import.meta.url`, so a space in the
-  // checkout path must not split the command.
-  const gateCommand = `node ${shellQuote(gatePath)}`;
+  // argv preserves spaces and apostrophes on POSIX and Windows.
+  const gateCommand = [process.execPath, gatePath];
   // Derived from the SAME resolved per-command ceiling published as
   // `GATE_TIMEOUT_MS` above — not from `resolveGateTimeoutMs()` a second time.
   // The outer cap must stay strictly ABOVE the inner one so the inner kill fires
@@ -531,7 +553,7 @@ async function main() {
     // terminal's foreground group: the first read from an inherited TTY earns it
     // SIGTTIN, which stops the whole group until the outer ceiling kills it. An
     // ignored stdin turns that hang into an immediate EOF.
-    spawnFn: (command, options) => spawn(command, { ...options, stdio: ['ignore', 'pipe', 'inherit'] }),
+    spawnFn: (command, args, options) => spawn(command, args, { ...options, stdio: ['ignore', 'pipe', 'inherit'] }),
   });
 
   // `pid: -1` is `spawnInGroup`'s spawn-failure channel (it never rejects).
@@ -595,6 +617,9 @@ async function main() {
     // The names behind `counts.failed`. Absent, never `[]` — see
     // `failedFilesFromGateStdout`.
     const failedFiles = failedFilesFromGateStdout(gateStdout);
+    // The serial re-run of timeout-only failures (#1673): which files it named
+    // and how it ended, so the rate of load-rescued gates stays measurable.
+    const rerun = rerunFromGateStdout(gateStdout);
     // Wave-scope sidecar is read from the SAME project dir the event lands in
     // (emitEvent's own destination precedence), so a tmp-scoped run cannot pick
     // up the host repo's live wave. Mirrors the hook's projectDir resolution.
@@ -625,6 +650,7 @@ async function main() {
         ...(checkFailed !== null ? { check_failed: checkFailed } : {}),
         ...(counts ? { counts } : {}),
         ...(failedFiles ? { failed_files: failedFiles } : {}),
+        ...(rerun ? { rerun } : {}),
         ...(waveNumber !== null ? { wave_number: waveNumber } : {}),
         ...sessionAttribution(ledgerRoot ?? repoRoot),
       },

package/scripts/self-update.mjs

@@ -25,9 +25,12 @@
  *                2026-10-03). The step refuses, naming the remove + add
  *                commands, while ANY directory marketplace reads this clone;
  *                GitHub/npm sources update as before, with a one-line hint.
- *   3. codex   — only if the plugin is already installed in Codex: re-run
- *                scripts/codex-install.mjs, which installs from the same
- *                packed STAGE_DIR (#1518), never from this clone.
+ *   3. codex   — only if the plugin is already installed in Codex (under any
+ *                marketplace): re-run scripts/codex-install.mjs, which
+ *                installs from the same packed STAGE_DIR (#1518), never from
+ *                this clone. Any personal-marketplace `@local` install fails
+ *                read-only with the cleanup steps, wherever its source points
+ *                (#1608): codex-install would remove it.
  *
  * Never deletes an old plugin cache directory: the running session still
  * loads it until the harness restarts.
@@ -316,15 +319,61 @@ export function updateClaude({ run, log }, opts, ctx = {}) {
   };
 }
 
-function updateCodex({ run, log }, opts) {
-  if (!commandOnPath('codex')) return { step: 'codex', status: 'skipped', detail: 'codex not on PATH' };
+/**
+ * Installed session-orchestrator rows of the human `codex plugin list` table
+ * (`PLUGIN  STATUS  VERSION  SOURCE`, columns padded with 2+ spaces). The id
+ * carries whatever marketplace installed it — `session-orchestrator@local`
+ * from the personal marketplace (#1608) — so the name must end at `@` or the
+ * column gap: `session-orchestrator-foo@x` is a different plugin.
+ * @param {string | undefined} listText
+ * @returns {Array<{id: string, marketplace: string | undefined, source: string | undefined}>}
+ */
+function findCodexInstalls(listText) {
+  const row = new RegExp(`^${PLUGIN_NAME}(?:@(\\S+))?\\s+installed\\b`);
+  return (listText ?? '').split(/\r?\n/).flatMap((raw) => {
+    const line = raw.trim();
+    const m = row.exec(line);
+    if (!m) return [];
+    const cols = line.split(/\s{2,}/);
+    return [{ id: cols[0], marketplace: m[1], source: cols.length > 2 ? cols.at(-1) : undefined }];
+  });
+}
+
+/**
+ * The Codex step. `ctx` exists for tests (tmp clone, no PATH lookup);
+ * production passes nothing.
+ */
+export function updateCodex({ run, log }, opts, ctx = {}) {
+  const { soRoot = SO_ROOT, hasCodex = () => commandOnPath('codex') } = ctx;
+  if (!hasCodex()) return { step: 'codex', status: 'skipped', detail: 'codex not on PATH' };
   const list = run('codex', ['plugin', 'list'], { mutates: false });
   if (!list.ok) return { step: 'codex', status: 'failed', detail: list.detail };
-  if (!new RegExp(`^${PLUGIN_ID}\\s+installed`, 'm').test(list.stdout)) {
+  const installs = findCodexInstalls(list.stdout);
+  if (installs.length === 0) {
     return { step: 'codex', status: 'skipped', detail: 'plugin not installed in Codex (install: node scripts/codex-install.mjs)' };
   }
+  // `@local` comes from the personal marketplace
+  // (~/.agents/plugins/marketplace.json), whose directory source Codex caches
+  // whole, a checkout's .env.local included (#1518). codex-install would remove
+  // `@local` — a re-registration the operator owns — so this step only names
+  // the cleanup (same steps as codex-install's personal-marketplace hint),
+  // wherever the source points: run from a worktree it is the main checkout,
+  // not soRoot, and a source match would let codex-install remove it (#1608).
+  const local = installs.find((i) => i.marketplace === 'local');
+  if (local) {
+    const link = local.source ? `the link '${local.source}'` : 'its source link';
+    return {
+      step: 'codex',
+      status: 'failed',
+      detail: `${local.id} is installed from the personal marketplace${local.source ? ` via '${local.source}'` : ''} `
+        + `— its Codex cache copies the whole directory, a checkout's .env.local included (#1518). Clean up once: `
+        + `(1) node scripts/codex-install.mjs (installs ${PLUGIN_ID} from the packed copy, then removes ${local.id}); `
+        + `(2) remove that entry from ~/.agents/plugins/marketplace.json; (3) delete ${link} if it is a symlink; `
+        + `(4) after restarting Codex, delete the old cache folders under ~/.codex/plugins/cache/local/.`,
+    };
+  }
   log('codex: re-running codex-install');
-  const r = run(process.execPath, [path.join(SO_ROOT, 'scripts', 'codex-install.mjs'), '--json']);
+  const r = run(process.execPath, [path.join(soRoot, 'scripts', 'codex-install.mjs'), '--json']);
   if (!r.ok) return { step: 'codex', status: 'failed', detail: r.detail };
   if (opts.dryRun) return { step: 'codex', status: 'ok', detail: 'dry-run' };
   try {

package/scripts/session-commit-files.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * session-commit-files.mjs — which files did one session commit, in which of
+ * its own work trees (#1659).
+ *
+ * Read-only CLI over scripts/lib/session-work-trees.mjs: the session's
+ * `(tree, start_ref)` pairs come from the `orchestrator.session.work_tree`
+ * events in the default events ledger, and every tree is diffed INSIDE ITSELF
+ * against its own start ref (`git -C <tree> diff --name-only <ref>..HEAD`).
+ * Never a diff across two trees, never a write.
+ *
+ * Usage:
+ *   node scripts/session-commit-files.mjs [--session-id <raw-id>] [--json]
+ *
+ * Exit codes: 0 success (also with zero trees), 2 usage error (unknown flag,
+ * missing session id). Deviates from cli-design.md's `1` for input errors by
+ * coordinator contract (#1659); documented in `--help`.
+ */
+
+import { parseArgs } from 'node:util';
+
+import { isMainModule } from './lib/is-main-module.mjs';
+import { readSessionWorkTrees, sessionCommitFiles } from './lib/session-work-trees.mjs';
+
+const USAGE = `Usage: node scripts/session-commit-files.mjs [--session-id <raw-id>] [--json]
+
+List the files one session committed, per own work tree (#1659).
+
+Reads the session's (tree, start_ref) pairs from the
+orchestrator.session.work_tree events of the default events ledger and runs
+'git -C <tree> diff --name-only <start_ref>..HEAD' inside each tree only.
+Read-only: writes nothing.
+
+Options:
+  --session-id <id>  raw session id (default: $CLAUDE_CODE_SESSION_ID)
+  --json             print { trees, perTree, skipped, union, malformed, invalid,
+                     complete[, error] } as JSON (complete: null = no ledger found)
+  -h, --help         show this help
+
+Default output (stdout): one line per tree '<tree>\\t<start_ref>\\t<n> files',
+a blank line, then the union of files, one per line. Skipped trees and notes
+go to stderr.
+
+Exit codes:
+  0  success (also when the session recorded no trees)
+  2  usage error (unknown option, no session id)
+
+Example:
+  node scripts/session-commit-files.mjs --session-id "$CLAUDE_CODE_SESSION_ID" --json`;
+
+/**
+ * Run the CLI.
+ *
+ * @param {string[]} argv — arguments after the script path.
+ * @param {{ env?: NodeJS.ProcessEnv,
+ *           stdout?: (s: string) => void, stderr?: (s: string) => void }} [io]
+ * @returns {number} exit code
+ */
+export function main(argv, {
+  env = process.env,
+  stdout = (s) => process.stdout.write(s),
+  stderr = (s) => process.stderr.write(s),
+} = {}) {
+  let values;
+  try {
+    ({ values } = parseArgs({
+      args: argv,
+      options: {
+        'session-id': { type: 'string' },
+        json: { type: 'boolean', default: false },
+        help: { type: 'boolean', short: 'h', default: false },
+      },
+      strict: true,
+      allowPositionals: false,
+    }));
+  } catch (err) {
+    stderr(`session-commit-files: ${err.message}\n${USAGE}\n`);
+    return 2;
+  }
+  if (values.help) {
+    stdout(`${USAGE}\n`);
+    return 0;
+  }
+
+  // Process-local identity only — never a repo-global file (#1659).
+  const sessionId = (values['session-id'] ?? env.CLAUDE_CODE_SESSION_ID ?? '').trim();
+  if (sessionId === '') {
+    stderr('session-commit-files: no session id (pass --session-id or set CLAUDE_CODE_SESSION_ID)\n');
+    return 2;
+  }
+
+  const read = readSessionWorkTrees({ sessionId });
+  const files = sessionCommitFiles({ trees: read.trees });
+
+  // Notes go to stderr in BOTH modes, so `--json` never hides that the
+  // answer is partial or that no ledger exists (#1659).
+  if (read.error) stderr(`session-commit-files: ledger read failed: ${read.error}\n`);
+  if (read.complete === null && !read.error) stderr('session-commit-files: no events ledger found\n');
+  if (read.malformed > 0) stderr(`session-commit-files: ${read.malformed} unreadable ledger line(s)\n`);
+  if (read.invalid > 0) {
+    stderr(`session-commit-files: ignored ${read.invalid} own work_tree event(s) without a valid tree/start_ref\n`);
+  }
+  for (const s of files.skipped) {
+    stderr(`session-commit-files: skipped ${s.tree} (${s.start_ref}): ${s.reason}\n`);
+  }
+
+  if (values.json) {
+    stdout(`${JSON.stringify({
+      trees: read.trees,
+      perTree: files.perTree,
+      skipped: files.skipped,
+      union: files.union,
+      malformed: read.malformed,
+      invalid: read.invalid,
+      complete: read.complete,
+      ...(read.error ? { error: read.error } : {}),
+    }, null, 2)}\n`);
+    return 0;
+  }
+
+  if (read.trees.length === 0) {
+    if (read.complete !== null) stderr(`session-commit-files: no work trees recorded for session ${sessionId}\n`);
+    return 0;
+  }
+  if (files.perTree.length === 0) return 0; // every tree skipped — reported on stderr above
+  const lines = files.perTree.map((t) => `${t.tree}\t${t.start_ref}\t${t.files.length} files`);
+  stdout(`${lines.join('\n')}\n\n${files.union.map((f) => `${f}\n`).join('')}`);
+  return 0;
+}
+
+if (isMainModule(import.meta.url)) {
+  process.exitCode = main(process.argv.slice(2));
+}