@lyupro/codex-bridge 0.6.12 → 0.6.15

package/src/home/lib/load-witness.mjs

@@ -0,0 +1,113 @@
+/** Records the host's rules-core loading evidence (Plan_64 D11), without resolving owners or versions. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { writeHomeJsonAtomic } from './atomic-json.mjs';
+import { withHomeFileLock } from './file-lock.mjs';
+import { stateDirWriter } from './home-write.mjs';
+import { parseJsonText } from './json-file.mjs';
+
+export const LOAD_WITNESS_FILE = 'load-witness.json';
+// Plan_64 D15 / review B8: larger files cannot be the package core; each UTF-16 unit needs at most 3 UTF-8 bytes.
+export const CORE_CHARACTER_CEILING = 2400;
+export const CORE_BYTE_CEILING = 3 * CORE_CHARACTER_CEILING;
+const RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+
+function readBoundedCoreBytes(filePath) {
+  const buffer = Buffer.alloc(CORE_BYTE_CEILING + 1);
+  const descriptor = fs.openSync(filePath, 'r');
+  try {
+    let length = 0;
+    while (length < buffer.length) {
+      const count = fs.readSync(descriptor, buffer, length, buffer.length - length, null);
+      if (count === 0) return buffer.subarray(0, length);
+      length += count;
+    }
+    return null;
+  } finally {
+    fs.closeSync(descriptor);
+  }
+}
+
+export function readLoadWitness({ stateDir }) {
+  const file = path.join(stateDir, LOAD_WITNESS_FILE);
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return { sessions: {} };
+    return { sessions: {}, corrupt: true };
+  }
+  try {
+    const record = parseJsonText(file, raw);
+    if (!record || typeof record !== 'object' || Array.isArray(record)
+      || !record.sessions || typeof record.sessions !== 'object' || Array.isArray(record.sessions)) {
+      return { sessions: {}, corrupt: true };
+    }
+    return { sessions: record.sessions };
+  } catch {
+    return { sessions: {}, corrupt: true };
+  }
+}
+
+export function isCoreLoadCandidate(filePath) {
+  return typeof filePath === 'string'
+    && filePath.replaceAll('\\', '/').toLowerCase().endsWith('/rules/codex-bridge/core.md');
+}
+
+export async function recordCoreLoad({ stateDir, input, now = new Date(), readCore = readBoundedCoreBytes }) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    return { recorded: false, reason: 'invalid-input' };
+  }
+  if (input.hook_event_name !== 'InstructionsLoaded') return { recorded: false, reason: 'other-event' };
+  if (input.load_reason !== 'session_start') return { recorded: false, reason: 'other-load-reason' };
+  if (typeof input.session_id !== 'string' || !input.session_id.trim()) {
+    return { recorded: false, reason: 'missing-session-id' };
+  }
+  if (typeof input.file_path !== 'string' || !input.file_path.trim()) {
+    return { recorded: false, reason: 'missing-file-path' };
+  }
+  if (!isCoreLoadCandidate(input.file_path)) return { recorded: false, reason: 'other-file' };
+
+  let sha256 = null;
+  let readError;
+  let hashSkippedReason;
+  try {
+    const bytes = readCore(input.file_path);
+    if (bytes === null) hashSkippedReason = 'core-too-large';
+    else sha256 = createHash('sha256').update(bytes).digest('hex');
+  } catch (error) {
+    readError = error.code ?? null;
+  }
+  const file = path.join(stateDir, LOAD_WITNESS_FILE);
+  const writer = stateDirWriter(stateDir);
+  return withHomeFileLock(writer, 'load-witness', `${file}.lock`, async () => {
+    const current = readLoadWitness({ stateDir });
+    if (current.corrupt) throw new Error(`Cannot update corrupt load witness: ${file}`);
+    const at = new Date(now).toISOString();
+    const cutoff = Date.parse(at) - RETENTION_MS;
+    // A hand-edited entry without a loads array is dropped, not allowed to throw: one bad row would
+    // otherwise lose every later witness, and a lost witness reads as "not verified" forever (D11).
+    const sessions = Object.fromEntries(Object.entries(current.sessions).filter(([, entry]) => {
+      if (!Array.isArray(entry?.loads)) return false;
+      const newest = Math.max(...entry.loads.map((load) => Date.parse(load?.at)));
+      return newest >= cutoff;
+    }));
+    const session = Object.hasOwn(sessions, input.session_id)
+      ? sessions[input.session_id] : { loads: [] };
+    const duplicate = session.loads.some((load) => load.path === input.file_path);
+    if (!duplicate) {
+      session.loads.push({
+        path: input.file_path, loadReason: input.load_reason, memoryType: input.memory_type ?? null,
+        sha256, at, ...(readError !== undefined ? { readError } : {}),
+        ...(hashSkippedReason !== undefined ? { hashSkippedReason } : {}),
+      });
+    }
+    session.transcriptPath ??= input.transcript_path;
+    session.cwd ??= input.cwd;
+    // Defining the key preserves host-provided session ids such as __proto__ as ordinary data.
+    Object.defineProperty(sessions, input.session_id, { value: session, enumerable: true, configurable: true, writable: true });
+    writeHomeJsonAtomic(writer, 'load-witness', file, { sessions });
+    return duplicate ? { recorded: false, reason: 'duplicate-path' } : { recorded: true };
+  }, { description: 'load witness' });
+}

package/src/home/lib/meta/paths.mjs

@@ -89,7 +89,12 @@ export const changedPaths = (before, after) => {
 };
 
 /** Directories a delegated build has no business editing, whatever the task says. */
-export const SERVICE_RE = /^(\.omx|\.omc|\.claude|\.codex|\.git|node_modules)\//;
+export const SERVICE_FOLDERS = Object.freeze([
+  '.omx', '.omc', '.claude', '.codex', '.git', 'node_modules',
+]);
+export const SERVICE_RE = new RegExp(
+  `^(${SERVICE_FOLDERS.map((name) => name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|')})/`,
+);
 
 /**
  * Paths arrive from two sides that spell them differently: git prints repo-relative with

package/src/home/lib/meta/reply.mjs

@@ -238,7 +238,7 @@ export function limitReply(ctx, meta) {
 /** Plan_60 D2: pre-start and post-start refusals share the same handoff contract. */
 export function unavailableRows(signal) {
   return [
-    'UNAVAILABLE — Codex is not available (missing or signed out); ' +
+    'UNAVAILABLE — Codex is not available (signed out); ' +
       'hand the task to the next executor, do not retry',
     `Signal: ${line(signal, 170)}`,
     'Operator check: codex --version; codex login status (sign in with codex login)',

package/src/home/lib/runner/codex-availability.mjs

@@ -1,5 +1,5 @@
 /**
- * Decides from conclusive evidence only whether Codex is missing, signed out, available, or cannot be judged.
+ * Decides from conclusive evidence only whether Codex is signed out, available, or cannot be judged.
  * Plan_60 D2: an inconclusive probe must never become "do not retry".
  */
 import { resolveCommandOnPath } from '../command-path.mjs';
@@ -21,10 +21,19 @@ function failureDetail(result, command) {
 export async function probeCodexAvailability({
   env = process.env, platform = process.platform,
   run = spawnCaptured, resolve = resolveCommandOnPath, timeoutMs = PROBE_TIMEOUT_MS,
+  retryDelayMs = 1_000, delay = (ms) => new Promise((done) => setTimeout(done, ms)),
 } = {}) {
   try {
     if (resolve('codex', env) === null) {
-      return { state: 'missing', detail: 'codex is not on PATH' };
+      // Plan_78 D5: the 2026-10-10 TradeForge refusal during an npm update showed that
+      // a transient PATH miss cannot prove absence; retry once before leaving readiness unconfirmed.
+      await delay(retryDelayMs);
+      if (resolve('codex', env) === null) {
+        return {
+          state: 'inconclusive', pathMiss: true,
+          detail: 'codex could not be resolved in this process PATH; readiness is unconfirmed',
+        };
+      }
     }
     const capture = (args) => {
       const spec = codexSpawnSpec(args, platform);

package/src/home/lib/runner/exit-codes.mjs

@@ -9,5 +9,5 @@ export const EXIT = Object.freeze({
   USAGE: 2,       // argument error: the order itself must be rewritten
   LIMIT: 3,       // ChatGPT quota exhausted; not a task failure
   PENDING: 4,     // --no-wait only: the run is still in progress, or no run exists (a call outcome, not a status)
-  UNAVAILABLE: 5, // Codex missing or signed out; hand the task to the next executor
+  UNAVAILABLE: 5, // Codex signed out (a PATH miss is a free refusal, Plan_78 D5); hand the task to the next executor
 });

package/src/home/lib/runner/launcher.mjs

@@ -33,7 +33,7 @@ import { agentRole } from '../agents.mjs';
 import { codexArgs, runProfile } from './codex-args.mjs';
 import { writeWorkerOrder } from './worker-order.mjs';
 import { unsafeForCmd } from './codex-cmd.mjs';
-import { runsRoot } from './runs-root.mjs';
+import { runsRootResolution, staleOverrideRefusal } from './runs-root.mjs';
 import { resolveProjectRunsDir } from './project-dir.mjs';
 import { cleanupRetention } from '../retention.mjs';
 import { renderConventions } from './conventions.mjs';
@@ -95,8 +95,9 @@ export async function launcher(argv = process.argv.slice(2)) {
   const opts = parseArgs(argv);
   const { task: taskText, header } = settleTaskInput(opts);
   opts.phase = resolveRunPhase(opts, RUN_ENV.budgets);
+  const resolution = runsRootResolution();
   // Plan_59 D5/D6: blind choices and design authority must be checked before the paid probe.
-  const taskGate = taskPreflight({ agent: opts.agent, taskText, header });
+  const taskGate = taskPreflight({ agent: opts.agent, taskText, header, resolution });
   if (taskGate.refusal) die(taskGate.refusal, EXIT.FAIL);
   const topLevel = git(opts.repo, ['rev-parse', '--show-toplevel']);
   const isGitRepo = topLevel.status === 0;
@@ -113,7 +114,11 @@ export async function launcher(argv = process.argv.slice(2)) {
         `Action: ${scopeRefusal.action}. The run folder was not created; quota was not spent.`,
     );
   }
-  const projectRunsRoot = resolveProjectRunsDir(runsRoot(), repoRoot).dir;
+  // Plan_77 D6: project-dir.mjs:84 recursively recreated a retired CODEX_RUNS_ROOT.
+  // Refuse before that mkdir, using the same resolution that checked the advice header.
+  const stale = staleOverrideRefusal(resolution);
+  if (stale) die(`${stale}\nThe run folder was not created; quota was not spent.`, EXIT.FAIL);
+  const projectRunsRoot = resolveProjectRunsDir(resolution.root, repoRoot).dir;
   // Plan_60 D4c, 2026-09-24: two launchers of one order both billed. The claim comes before markAbandoned, or a
   // contender could close a run whose worker is admitting itself and start a second paid one.
   const claim = await acquireOrderClaim({ projectRunsRoot, orderId: opts.orderId, role: 'launcher' });
@@ -141,7 +146,8 @@ export async function launcher(argv = process.argv.slice(2)) {
     if ('exitCode' in gate) return gate.exitCode;
     const { taskHash, chain, startedChain, continuationGrant, advisorTask, retryOf } = gate;
 
-    // Plan_60 D2: a missing or signed-out Codex answers UNAVAILABLE (exit 5) before the paid sandbox probe.
+    // Plan_60 D2: a signed-out Codex answers UNAVAILABLE (exit 5) before the paid sandbox probe;
+    // a PATH miss, after one retry, is the free readiness-unconfirmed refusal (exit 1, Plan_78 D5).
     const availability = await codexAvailabilityRefusal();
     if (availability?.unavailable) { process.stdout.write(`${availability.text}\n`); return EXIT.UNAVAILABLE; }
     if (availability) die(availability.text, EXIT.FAIL);

package/src/home/lib/runner/preflight.mjs

@@ -12,13 +12,17 @@ import { probeCodexAvailability } from './codex-availability.mjs';
 import { agentRole } from '../agents.mjs';
 import { die } from './args.mjs';
 import { orderInputName } from '../order-schema.mjs';
+import { retiredPathRefusal, runsRootResolution } from './runs-root.mjs';
 
-/** Plan_60 D2: only conclusive evidence says UNAVAILABLE; an unclear probe stays an ordinary refusal. */
+/** Plan_60 D2: only conclusive evidence says UNAVAILABLE; a PATH miss is inconclusive (Plan_78 D5). */
 export async function codexAvailabilityRefusal({ probe = probeCodexAvailability } = {}) {
   const result = await probe();
   if (result.state === 'available') return null;
-  const unavailable = result.state === 'missing' || result.state === 'logged-out';
-  const rows = unavailable ? unavailableRows(result.detail) : [
+  const unavailable = result.state === 'logged-out';
+  const rows = unavailable ? unavailableRows(result.detail) : result.pathMiss === true ? [
+    `Codex CLI readiness unconfirmed: ${result.detail}`,
+    'Do not skip this bridge: check codex --version for up to about 2 minutes; when it answers, repeat the same order exactly once; if it does not answer, hand the order to the next executor and name that in the summary.',
+  ] : [
     `Codex CLI unavailable: ${result.detail}`,
     'Operator check: codex --version (and codex login if authorization is rejected)',
   ];
@@ -29,7 +33,7 @@ export async function codexAvailabilityRefusal({ probe = probeCodexAvailability
 }
 
 /** Plan_59 D5/D6: settle design authority before any probe can spend quota. */
-export function taskPreflight({ agent, taskText, header }) {
+export function taskPreflight({ agent, taskText, header, resolution = runsRootResolution() }) {
   const freeRefusal = (reason) => ({
     refusal: `${reason}\nThe run folder was not created; quota was not spent.`,
   });
@@ -44,6 +48,10 @@ export function taskPreflight({ agent, taskText, header }) {
       return { refusal: null, advice };
     }
     if (path.isAbsolute(advice)) {
+      // Plan_77 D6: preflight.mjs:46-58 swallowed the old-path read failure as missing advice.
+      // Diagnose before stat/read so neither existing nor absent retired evidence is opened.
+      const retired = retiredPathRefusal(advice, resolution);
+      if (retired) return freeRefusal(retired);
       try {
         // Plan_59 D26: only a judged advice authorizes a construction. On 2026-09-24 the gate took
         // any codex-advisor folder, so a scope run or a FAIL advice would have passed as a second opinion.

package/src/home/lib/runner/prompts.mjs

@@ -8,6 +8,7 @@
  * (`…cli/install.mjs:` + U+0000) and 2026-09-28 (`…(docs/plans/Plan_` + `恋`).
  */
 import { DEFAULTS } from '../run-config.mjs';
+import { SERVICE_FOLDERS } from '../meta/paths.mjs';
 import { RUN_ENV } from './run-env.mjs';
 import { advisorSchema, schemaFor } from './schemas.mjs';
 import { QUESTION_KIND } from './question-kind.mjs';
@@ -140,8 +141,7 @@ Working rules:
   (\`dir/{a,b}.ts\`), and lists separated by \`;\` or \`,\` are prohibited: a collapsed entry will
   match no file when the report is checked against the worktree and will fail the run even if
   the work was done honestly.
-- Do not fix the environment. Service directories (\`.omx/\`, \`.claude/\`, \`.codex/\`, \`.git/\`,
-  \`node_modules/\`) and other sessions are not your task, even if they prevent you from working
+- Do not fix the environment. Service directories (${SERVICE_FOLDERS.map((name) => `\`${name}/\``).join(', ')}) and other sessions are not your task, even if they prevent you from working
   or finishing. Put the obstacle in leftovers instead of changing them.
 - report_markdown is a full markdown report with sections: “What was done”, “Changes”
   (file / what changed / why table), “Verification” (command and its actual output),

package/src/home/lib/runner/retired-roots.mjs

@@ -0,0 +1,81 @@
+/**
+ * Knows the run roots the records moved away from and says where a path under one of them lives now.
+ *
+ * Plan_77's “Why” paragraph: on 2026-10-07 thousands of run records in another project's
+ * git tree made a VaultForge journal compile cost $16.57 instead of $0.3-0.8. D6 forbids
+ * redirect links or silent remapping; a corrupt move record must never revive that store.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { writeHomeJsonAtomic } from '../atomic-json.mjs';
+import { stateDirWriter } from '../home-write.mjs';
+import { parseJsonText } from '../json-file.mjs';
+import { normalizeRepoPath } from './project-dir.mjs';
+
+export const RUNS_MOVE_RECORD = 'runs-root.json';
+
+export function readRunsMoveRecord(stateDir) {
+  const file = path.join(stateDir, RUNS_MOVE_RECORD);
+  let text;
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw new Error(`Cannot read runs move record ${file}: ${error.message}`, { cause: error });
+  }
+  let record;
+  try {
+    record = parseJsonText(file, text);
+  } catch (error) {
+    throw new Error(`Invalid runs move record ${file}: ${error.message}`, { cause: error });
+  }
+  const invalid = (defect) => { throw new Error(`Invalid runs move record ${file}: ${defect}`); };
+  if (record?.version !== 1) invalid('version must be 1');
+  if (!Array.isArray(record.retired) || record.retired.length === 0) {
+    invalid('retired must be a non-empty array');
+  }
+  for (const [index, entry] of record.retired.entries()) {
+    if (typeof entry?.root !== 'string' || !path.isAbsolute(entry.root)) {
+      invalid(`retired[${index}].root must be an absolute path`);
+    }
+    if (typeof entry.movedAt !== 'string' || !Number.isFinite(Date.parse(entry.movedAt))) {
+      invalid(`retired[${index}].movedAt must be a parseable ISO time`);
+    }
+  }
+  return record;
+}
+
+export function retiredRootOf(candidate, retiredRoots) {
+  if (typeof candidate !== 'string' || candidate.length === 0) return null;
+  const normalized = normalizeRepoPath(candidate);
+  for (const { root } of retiredRoots) {
+    const retired = normalizeRepoPath(root);
+    if (normalized === retired) return { root, suffix: '' };
+    if (normalized.startsWith(`${retired}/`)) {
+      // Compare normalized paths, but keep the candidate's segment spelling for the advice. Cut by
+      // segment count, not by string length: lower-casing can change the length of a non-ASCII name.
+      const spelled = path.resolve(candidate).replaceAll('\\', '/').replace(/\/$/, '').split('/');
+      return { root, suffix: spelled.slice(retired.split('/').length).join('/') };
+    }
+  }
+  return null;
+}
+
+export function retiredRootRefusal({ candidate, retired, destination }) {
+  const equivalent = retired.suffix ? path.join(destination, retired.suffix) : destination;
+  return `Run records moved from ${retired.root} to ${destination}. Equivalent path: ${equivalent}. ` +
+    'Update advice: or pass this new path explicitly. No path was remapped.';
+}
+
+/**
+ * Plan_77 D7: the move record is written last, by the move command, after the copy is verified — its
+ * presence is what switches the resolver. A later move appends to the list instead of replacing it, so
+ * every root the records ever left keeps answering with a refusal rather than an empty lookup.
+ */
+export function writeRunsMoveRecord(stateDir, { root, movedAt = new Date().toISOString() }) {
+  const previous = readRunsMoveRecord(stateDir);
+  const retired = [...(previous?.retired ?? []), { root, movedAt }];
+  const record = { version: 1, retired };
+  writeHomeJsonAtomic(stateDirWriter(stateDir), 'runs-move-record', path.join(stateDir, RUNS_MOVE_RECORD), record);
+  return record;
+}

package/src/home/lib/runner/run-autocommit.mjs

@@ -0,0 +1,109 @@
+/**
+ * Commits a finished run's folder when the run store is a git repository of its own.
+ *
+ * Plan_77 D1/D5: on 2026-10-07 thousands of uncommitted runs in ~/.claude made a
+ * VaultForge journal compile cost $16.57 instead of $0.3-0.8. Commit only in the
+ * store's own repository, preserve the operator's staged paths, and never remove index.lock.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { resolveBrandHome } from '../brand-home.mjs';
+import { readJsonFileSync } from '../json-file.mjs';
+import { normalizeRepoPath, PROJECT_MARKER } from './project-dir.mjs';
+
+function runGit(cwd, args) {
+  return spawnSync('git', ['-C', cwd, ...args], {
+    encoding: 'utf8', windowsHide: true, timeout: 120_000,
+  });
+}
+
+function waitSync(milliseconds) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+}
+
+const QUIET_REASONS = new Set(['not in git', 'repository is not the run store', 'nothing to commit']);
+
+export function commitRunRecord(options) {
+  let runDir;
+  try {
+    let brandRoot, git, sleep, attempts, waitMs;
+    ({ runDir, brandRoot = resolveBrandHome().root, git = runGit,
+      sleep = waitSync, attempts = 10, waitMs = 500 } = options);
+    const storeRoot = path.dirname(path.dirname(runDir));
+    const step = (cwd, args) => {
+      for (let attempt = 1; ; attempt += 1) {
+        let result;
+        try {
+          result = git(cwd, args);
+        } catch (error) {
+          result = { status: null, stderr: error.message, error };
+        }
+        const locked = String(result.stderr).includes('index.lock');
+        if (locked && attempt < attempts) {
+          sleep(waitMs);
+          continue;
+        }
+        return { ...result, locked };
+      }
+    };
+    const failure = (name, result) => {
+      const firstLine = String(result.stderr || result.error?.message || '').trim().split(/\r?\n/)[0];
+      return { committed: false,
+        reason: `git ${name} failed (exit ${result.status ?? 'unknown'}): ${firstLine}` };
+    };
+    const perform = () => {
+      const repo = step(storeRoot, ['rev-parse', '--show-toplevel']);
+      if (repo.locked || repo.status !== 0) {
+        return !repo.locked && /not a git repository/i.test(repo.stderr || '')
+          ? { committed: false, reason: 'not in git' } : failure('rev-parse', repo);
+      }
+      const top = repo.stdout.trim();
+      const normalizedTop = normalizeRepoPath(top);
+      const normalizedStore = normalizeRepoPath(storeRoot);
+      const normalizedBrand = normalizeRepoPath(brandRoot);
+      if (normalizedTop !== normalizedStore && !(normalizedTop === normalizedBrand &&
+          normalizedStore.startsWith(`${normalizedBrand}/`))) {
+        return { committed: false, reason: 'repository is not the run store' };
+      }
+
+      const relative = (file) => path.relative(top, file).replaceAll(path.sep, '/');
+      const paths = [relative(runDir)];
+      const marker = path.join(path.dirname(runDir), PROJECT_MARKER);
+      if (fs.existsSync(marker)) paths.push(relative(marker));
+      const added = step(top, ['add', '-A', '--', ...paths]);
+      if (added.locked || added.status !== 0) return failure('add', added);
+      const diff = step(top, ['diff', '--cached', '--quiet', '--', ...paths]);
+      if (diff.locked) return failure('diff', diff);
+      if (diff.status === 0) return { committed: false, reason: 'nothing to commit' };
+      if (diff.status !== 1) return failure('diff', diff);
+
+      let status = 'unknown';
+      try {
+        status = readJsonFileSync(path.join(runDir, 'meta.json'))?.status ?? 'unknown';
+      } catch {
+        // An unreadable verdict must not prevent preserving the finished record (Plan_77 B6).
+      }
+      const message = `${path.basename(path.dirname(runDir))}/${path.basename(runDir)}: ${status}`;
+      // D5: the pathspec keeps every unrelated staged entry out of this commit and in the index.
+      const committed = step(top, ['commit', '--quiet', '-m', message, '--', ...paths]);
+      return !committed.locked && committed.status === 0
+        ? { committed: true, reason: 'committed' } : failure('commit', committed);
+    };
+    const result = perform();
+    if (!result.committed && !QUIET_REASONS.has(result.reason)) appendFailure(runDir, result.reason);
+    return result;
+  } catch (error) {
+    const reason = `autocommit failed: ${String(error?.message || error).split(/\r?\n/)[0]}`;
+    appendFailure(runDir, reason);
+    return { committed: false, reason };
+  }
+}
+
+function appendFailure(runDir, reason) {
+  try {
+    fs.appendFileSync(path.join(runDir, 'stderr.log'), `autocommit: ${reason}\n`);
+  } catch {
+    // Even an unwritable diagnostic log cannot change the run's verdict (Plan_77 B6).
+  }
+}

package/src/home/lib/runner/runs-root.mjs

@@ -1,16 +1,56 @@
 /**
- * Says where run artifacts live.
+ * One resolver says where run artifacts live: CODEX_RUNS_ROOT, moved, legacy, or default.
  *
- * The path used to be built from os.homedir() in two places, which taught the package that it
- * lives inside ~/.claude — outside that folder it had nowhere to write. The value is read on
- * every call, not frozen into a constant, because tests override the variable per case.
+ * Plan_77 D7 ships code before the move: an existing legacy directory stays active until
+ * the move record exists; a clean installation uses the package home immediately. Records
+ * in another project's git tree cost a VaultForge journal compile $16.57 instead of $0.3-0.8
+ * on 2026-10-07. The value is read on every call, not frozen into a constant, because tests
+ * override the variable per case and a verified move must take effect without a restart.
  */
+import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { resolveBrandHome } from '../brand-home.mjs';
+import { RUN_RECORDS_DIR } from '../home-registry.mjs';
+import { readRunsMoveRecord, retiredRootOf, retiredRootRefusal } from './retired-roots.mjs';
 
-export function runsRoot() {
-  const configured = process.env.CODEX_RUNS_ROOT;
+export function runsRootResolution({ env = process.env, homedir = os.homedir() } = {}) {
+  const brandHome = resolveBrandHome({ env, homedir });
+  const homeRoot = path.join(brandHome.root, RUN_RECORDS_DIR);
+  const legacyRoot = path.join(homedir, '.claude', 'codex-runs');
+  const record = readRunsMoveRecord(brandHome.stateDir);
+  const retired = record?.retired ?? [];
+  const configured = env.CODEX_RUNS_ROOT;
   // Trimmed, not taken literally: a path with a leading or trailing space creates a folder
   // Windows tooling cannot address, and the value usually arrives from a shell or an .env line.
-  return configured?.trim() ? configured.trim() : path.join(os.homedir(), '.claude', 'codex-runs');
+  if (configured?.trim()) {
+    const root = configured.trim();
+    return { root, source: 'CODEX_RUNS_ROOT', legacyRoot, homeRoot, retired,
+      staleOverride: retiredRootOf(root, retired) };
+  }
+  if (record) {
+    return { root: homeRoot, source: 'moved', legacyRoot, homeRoot, retired, staleOverride: null };
+  }
+  const legacyExists = fs.existsSync(legacyRoot) && fs.statSync(legacyRoot).isDirectory();
+  return { root: legacyExists ? legacyRoot : homeRoot, source: legacyExists ? 'legacy' : 'default',
+    legacyRoot, homeRoot, retired, staleOverride: null };
+}
+
+export function runsRoot() {
+  const resolution = runsRootResolution();
+  if (resolution.staleOverride) throw new Error(staleOverrideRefusal(resolution));
+  return resolution.root;
+}
+
+/** Plan_77 D6: diagnose the old address before callers read it; never silently remap it. */
+export function retiredPathRefusal(candidate, resolution = runsRootResolution()) {
+  const retired = retiredRootOf(candidate, resolution.retired);
+  return retired ? retiredRootRefusal({ candidate, retired, destination: resolution.homeRoot }) : null;
+}
+
+export function staleOverrideRefusal(resolution = runsRootResolution()) {
+  if (!resolution.staleOverride) return null;
+  return retiredRootRefusal({ candidate: resolution.root, retired: resolution.staleOverride,
+    destination: resolution.homeRoot }) + '\n' +
+    'CODEX_RUNS_ROOT points under a retired runs root; remove it or set it to the new location.';
 }