@lyupro/codex-bridge 0.6.11 → 0.6.14

package/src/home/lib/host-version.mjs

@@ -1,24 +1,43 @@
-/** Reads the host version from the transcript tail after the 2026-09-25 PATH host identity incident. */
+/** Reads the host version from a session transcript after the 2026-09-25 PATH host identity incident. */
 import fs from 'node:fs/promises';
 import { parseJsonText } from './json-file.mjs';
 
-export async function transcriptHostVersion(transcriptPath, { tailBytes = 65536 } = {}) {
+const VERSION = /^\d+\.\d+\.\d+/;
+
+function versionIn(transcriptPath, lines, sessionId, newestFirst) {
+  const order = newestFirst ? [...lines.keys()].reverse() : lines.keys();
+  for (const index of order) {
+    try {
+      const entry = parseJsonText(transcriptPath, lines[index]);
+      // Plan_64 D11: a neighboring session's version cannot identify this load witness.
+      if (sessionId && entry?.sessionId !== sessionId) continue;
+      if (typeof entry?.version === 'string' && VERSION.test(entry.version)) return entry.version;
+    } catch {}
+  }
+  return null;
+}
+
+async function slice(handle, position, length) {
+  const buffer = Buffer.alloc(length);
+  await handle.read(buffer, 0, length, position);
+  return buffer.toString('utf8').split(/\r?\n/);
+}
+
+/**
+ * A live session's newest lines name its host, so the tail answers the shell-command observers. A finished session
+ * may end in a 135 KB attachment line and metadata without `version` (B6b live run, 2026-10-10), so a named session is
+ * also looked up from the head: one session runs on one host, and its first user line already carries the version.
+ */
+export async function transcriptHostVersion(transcriptPath, { tailBytes = 65536, headBytes = 1048576, sessionId } = {}) {
+  const session = typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : null;
   try {
     const handle = await fs.open(transcriptPath, 'r');
     try {
       const { size } = await handle.stat();
-      const length = Math.min(size, tailBytes);
-      const buffer = Buffer.alloc(length);
-      await handle.read(buffer, 0, length, size - length);
-      const lines = buffer.toString('utf8').split(/\r?\n/);
-      for (let index = lines.length - 1; index >= 0; index -= 1) {
-        try {
-          const entry = parseJsonText(transcriptPath, lines[index]);
-          if (typeof entry?.version === 'string' && /^\d+\.\d+\.\d+/.test(entry.version)) {
-            return entry.version;
-          }
-        } catch {}
-      }
+      const tailLength = Math.min(size, tailBytes);
+      const fromTail = versionIn(transcriptPath, await slice(handle, size - tailLength, tailLength), session, true);
+      if (fromTail !== null || !session) return fromTail;
+      return versionIn(transcriptPath, await slice(handle, 0, Math.min(size, headBytes)), session, false);
     } finally {
       await handle.close();
     }

package/src/home/lib/install-owner-roots.mjs

@@ -1,53 +1,55 @@
-/**
- * Reads which host roots own this home from the installation record, read-only, for hooks.
- * Plan_67 D10 needs every recorded owner; the home image has no cli/ modules.
- */
-import fs from 'node:fs';
-import path from 'node:path';
-import { homeArtifact } from './home-registry.mjs';
-import { parseJsonText } from './json-file.mjs';
-
-const isObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
-
-export function isFormat2(parsed) {
-  return isObject(parsed) && parsed.format === 2;
-}
-
-export function readOwnerRoots({ brandRoot }) {
-  const file = path.join(brandRoot, homeArtifact('install-record').primary[0]);
-  let raw;
-  try {
-    raw = fs.readFileSync(file, 'utf8');
-  } catch (error) {
-    return error.code === 'ENOENT'
-      ? { problem: 'missing', detail: `Installation record at ${file} is missing.` }
-      : { problem: 'unreadable', detail: `Installation record at ${file} cannot be read.` };
-  }
-
-  let parsed;
-  try {
-    parsed = parseJsonText(file, raw);
-  } catch {
-    return { problem: 'unreadable', detail: `Installation record at ${file} contains invalid JSON.` };
-  }
-  if (!isFormat2(parsed)) {
-    return { problem: 'not-format-2', detail: `Installation record at ${file} is not format 2.` };
-  }
-  if (parsed.inventory !== 'complete') {
-    return { problem: 'inventory-incomplete', detail: `Installation record at ${file} has an incomplete inventory.` };
-  }
-  if (Object.hasOwn(parsed, 'legacy')) {
-    return { problem: 'legacy-partition', detail: `Installation record at ${file} contains a legacy partition.` };
-  }
-  if (!isObject(parsed.owners) || Object.keys(parsed.owners).length === 0) {
-    return { problem: 'no-owners', detail: `Installation record at ${file} has no owners.` };
-  }
-  const roots = [];
-  for (const owner of Object.values(parsed.owners)) {
-    if (typeof owner?.root !== 'string' || owner.root.trim().length === 0) {
-      return { problem: 'malformed-owner', detail: `Installation record at ${file} has an owner without a non-empty root.` };
-    }
-    roots.push(owner.root);
-  }
-  return { roots: roots.sort() };
-}
+/**
+ * Reads which host roots own this home from the installation record, read-only, for hooks.
+ * Plan_67 D10 needs every recorded owner; the home image has no cli/ modules.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { homeArtifact } from './home-registry.mjs';
+import { parseJsonText } from './json-file.mjs';
+
+const isObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+
+export function isFormat2(parsed) {
+  return isObject(parsed) && parsed.format === 2;
+}
+
+export function readOwnerRoots({ brandRoot }) {
+  const file = path.join(brandRoot, homeArtifact('install-record').primary[0]);
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (error) {
+    return error.code === 'ENOENT'
+      ? { problem: 'missing', detail: `Installation record at ${file} is missing.` }
+      : { problem: 'unreadable', detail: `Installation record at ${file} cannot be read.` };
+  }
+
+  let parsed;
+  try {
+    parsed = parseJsonText(file, raw);
+  } catch {
+    return { problem: 'unreadable', detail: `Installation record at ${file} contains invalid JSON.` };
+  }
+  if (!isFormat2(parsed)) {
+    return { problem: 'not-format-2', detail: `Installation record at ${file} is not format 2.` };
+  }
+  // Plan_67 R2: confirmation refuses ownerless records; enrollment must come first.
+  if (!isObject(parsed.owners) || Object.keys(parsed.owners).length === 0) {
+    return { problem: 'no-owners', detail: `Installation record at ${file} has no owners.` };
+  }
+  if (parsed.inventory !== 'complete') {
+    // Plan_67 D11: match cli/inventory-confirm.mjs INVENTORY_CONFIRM_COMMAND; hooks cannot import cli/.
+    return { problem: 'inventory-incomplete', detail: `Installation record at ${file} has an incomplete inventory; if the recorded hosts are all the hosts using this home, run codex-bridge inventory confirm.` };
+  }
+  if (Object.hasOwn(parsed, 'legacy')) {
+    return { problem: 'legacy-partition', detail: `Installation record at ${file} contains a legacy partition.` };
+  }
+  const roots = [];
+  for (const owner of Object.values(parsed.owners)) {
+    if (typeof owner?.root !== 'string' || owner.root.trim().length === 0) {
+      return { problem: 'malformed-owner', detail: `Installation record at ${file} has an owner without a non-empty root.` };
+    }
+    roots.push(owner.root);
+  }
+  return { roots: roots.sort() };
+}

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/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/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).
+  }
+}