@lyupro/codex-bridge 0.6.12 → 0.6.14

package/cli/doctor-load-witness.mjs

@@ -0,0 +1,75 @@
+/**
+ * Plan_64 D11: the 2026-10-10 live run proved memory_type and entrypoint unreliable;
+ * A6 showed a lost hook record cannot prove failure. Judge one host's rules-core load evidence.
+ */
+import path from 'node:path';
+import { buildInstallPlan, contentFingerprint } from './manifest.mjs';
+import { plannedContent } from './copy.mjs';
+import { check } from './doctor-format.mjs';
+import { LOAD_WITNESS_FILE, readLoadWitness } from '../src/home/lib/load-witness.mjs';
+import { transcriptHostVersion } from '../src/home/lib/host-version.mjs';
+
+function normalizedPath(target) {
+  const resolved = path.resolve(target).replaceAll('\\', '/');
+  return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+
+export async function loadWitnessChecks({ host, record, stateDir, activeHosts, readVersion = transcriptHostVersion }) {
+  if (!record) return [check('claudeRulesLoad', 'warn', 'not checked before installation')];
+  const witness = readLoadWitness({ stateDir });
+  if (witness.corrupt) {
+    return [check('claudeRulesLoad', 'warn', `load witness is unreadable: ${path.join(stateDir, LOAD_WITNESS_FILE)}`)];
+  }
+  const plan = await buildInstallPlan(host);
+  const expected = new Map();
+  for (const item of plan.filter((item) => path.dirname(item.target) === host.rulesDir)) {
+    expected.set(normalizedPath(item.target), contentFingerprint(await plannedContent(item, host.brandRoot)));
+  }
+  const byVersion = new Map();
+  let pending = 0;
+  for (const [sessionId, session] of Object.entries(witness.sessions)) {
+    if (!Array.isArray(session?.loads)) continue;
+    const loads = session.loads.filter((load) => typeof load?.path === 'string'
+      && expected.has(normalizedPath(load.path)));
+    if (!loads.length) continue;
+    // D11: use the witness session, never a neighboring transcript entry or the current PATH host.
+    const version = await readVersion(session.transcriptPath, { sessionId });
+    if (version === null) {
+      if (loads.some((load) => load.sha256 === expected.get(normalizedPath(load.path)))) pending += 1;
+      continue;
+    }
+    const entries = byVersion.get(version) ?? [];
+    for (const load of loads) {
+      entries.push({ sessionId, at: load.at, matches: load.sha256 === expected.get(normalizedPath(load.path)),
+        hashSkippedReason: load.hashSkippedReason });
+    }
+    byVersion.set(version, entries);
+  }
+  const pendingNote = pending ? ` (${pending} session(s) awaiting their transcript)` : '';
+  const versions = activeHosts.length ? [...new Set(activeHosts)]
+    : [...byVersion].filter(([, entries]) => entries.some((entry) => entry.matches
+      || entry.hashSkippedReason === 'core-too-large')).map(([version]) => version);
+  if (!versions.length) {
+    return [check('claudeRulesLoad', 'warn',
+      `no session has witnessed the rules core loading yet; open a new Claude Code session${pendingNote}`)];
+  }
+  return versions.map((version) => {
+    const entries = byVersion.get(version) ?? [];
+    const verified = entries.filter((entry) => entry.matches);
+    const latest = [...entries].sort((a, b) => String(b.at).localeCompare(String(a.at)))[0];
+    // D15 / review B8: an oversized newest load cannot be proof, even after an older matching load.
+    if (latest?.hashSkippedReason === 'core-too-large') {
+      return check(`claudeRulesLoad:${version}`, 'warn',
+        `rules core hash skipped: core-too-large (host ${version}, latest ${latest.at})${pendingNote}`);
+    }
+    // D11: a newer load of another package hash invalidates the older positive witness.
+    if (latest?.matches && verified.length) {
+      const count = new Set(verified.map((entry) => entry.sessionId)).size;
+      return check(`claudeRulesLoad:${version}`, 'ok',
+        `rules core load witnessed (${count} session(s), latest ${latest.at})${pendingNote}`);
+    }
+    const stale = latest && !latest.matches ? '; witnessed core differs from this package (stale)' : '';
+    return check(`claudeRulesLoad:${version}`, 'warn',
+      `no session on host ${version} has witnessed the rules core loading yet${stale}; open a new Claude Code session, then rerun codex-bridge doctor${pendingNote}`);
+  });
+}

package/cli/doctor-runs.mjs

@@ -1,9 +1,11 @@
 /** Reports the state of run storage on this machine: location, live count, retention. */
 import path from 'node:path';
+import fs from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { readRunConfig, retentionNotice } from '../src/home/lib/run-config.mjs';
-import { runsRoot } from '../src/home/lib/runner/runs-root.mjs';
-import { resolveProjectRunsDir } from '../src/home/lib/runner/project-dir.mjs';
+import { runsRootResolution, staleOverrideRefusal } from '../src/home/lib/runner/runs-root.mjs';
+import { normalizeRepoPath, resolveProjectRunsDir } from '../src/home/lib/runner/project-dir.mjs';
+import { resolveBrandHome } from '../src/home/lib/brand-home.mjs';
 import { allLiveRuns } from '../src/home/hooks/live-runs.mjs';
 import { STOP_COMMAND_TEMPLATE } from '../src/home/lib/stop-contract.mjs';
 import { check } from './doctor-format.mjs';
@@ -27,14 +29,47 @@ function repoRoot(cwd) {
   return top.status === 0 && top.stdout.trim() ? top.stdout.trim() : cwd;
 }
 
+function runsGitTop(dir) {
+  if (!fs.existsSync(dir)) return null;
+  const top = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd: dir, encoding: 'utf8', windowsHide: true });
+  return top.status === 0 && top.stdout.trim() ? top.stdout.trim() : null;
+}
+
+export function runsRootCheck(options = {}) {
+  try {
+    const resolution = options.resolution ?? runsRootResolution();
+    const gitTop = options.gitTop ?? runsGitTop;
+    const root = path.resolve(resolution.root);
+    const value = root + ' (' + resolution.source + ')';
+    if (resolution.staleOverride) {
+      return check('runsRoot', 'fail', value + ' — ' + staleOverrideRefusal(resolution));
+    }
+    if (resolution.source === 'legacy') {
+      return check('runsRoot', 'warn', value + ' — move pending: run codex-bridge runs move when no other project is running.');
+    }
+    if (resolution.source === 'moved' && fs.existsSync(resolution.legacyRoot)
+      && fs.statSync(resolution.legacyRoot).isDirectory()) {
+      return check('runsRoot', 'warn', value + ' — the old folder ' + resolution.legacyRoot + ' still exists; codex-bridge runs move removes it.');
+    }
+    const top = gitTop(root);
+    if (top && normalizeRepoPath(top) !== normalizeRepoPath(root)
+      && normalizeRepoPath(top) !== normalizeRepoPath(resolveBrandHome().root)) {
+      return check('runsRoot', 'warn', value + ' — run records land in the git repository ' + top + ', which is not their own; they accumulate there uncommitted.');
+    }
+    return check('runsRoot', 'ok', value);
+  } catch (err) {
+    return check('runsRoot', 'fail', err.message);
+  }
+}
+
 /**
  * A marker that cannot be read is exactly what doctor exists to report, so it is caught here.
  * Left to propagate it would kill the whole diagnosis and hide the seven checks around it.
  */
-export function projectRunsCheck() {
+export function projectRunsCheck(resolution) {
   let resolved;
   try {
-    resolved = resolveProjectRunsDir(runsRoot(), repoRoot(process.cwd()), { create: false });
+    resolved = resolveProjectRunsDir(resolution.root, repoRoot(process.cwd()), { create: false });
   } catch (err) {
     return check('projectRuns', 'fail', err.message);
   }
@@ -42,10 +77,10 @@ export function projectRunsCheck() {
   return check('projectRuns', 'ok', `${path.resolve(resolved.dir)} (${note})`);
 }
 
-export function liveRunsCheck() {
+export function liveRunsCheck(resolution) {
   let count;
   try {
-    count = allLiveRuns(runsRoot(), { requireConfirmedIdentity: true }).length;
+    count = allLiveRuns(resolution.root, { requireConfirmedIdentity: true }).length;
   } catch (err) {
     return check('liveRuns', 'warn', `working-run count unavailable: ${err.message}`);
   }

package/cli/doctor-sandbox.mjs

@@ -0,0 +1,64 @@
+/** Detects the dead sandbox before an order, after the 2026-09-16, 2026-09-25 and 2026-10-10 refusals. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { check } from './doctor-format.mjs';
+import { repositoryRoot } from './hosts.mjs';
+import { sandboxModeFor } from '../src/home/lib/runner/codex-args.mjs';
+import { probeSandbox } from '../src/home/lib/runner/sandbox-probe.mjs';
+import { formatSandboxDiagnosis } from '../src/home/lib/runner/sandbox-diagnosis.mjs';
+
+// Probe reasons are full sentences; joining one to "; probed folder" printed "process.; probed" live.
+const clause = (reason) => String(reason).replace(/\.$/, '');
+
+// Plan_78 B4a: a timed-out attempt ends its form: at most 15 s plus ~15 s stopping
+// (taskkill 10 s, then stop grace). Only one form can time out with the guard below;
+// including the version check, the worst case stays well under the host shell's 120 s default.
+export async function sandboxChecks({
+  codexAvailable, cwd = process.cwd(), probe = probeSandbox, platform = process.platform,
+  timeoutMs = 15_000,
+} = {}) {
+  const root = repositoryRoot(cwd);
+  const folder = `${root} (${fs.existsSync(path.join(root, '.git')) ? 'git repository' : 'current folder'})`;
+  const rows = [];
+  let readOnlyInconclusive = false;
+  // Plan_57: concurrent helper setups race on one access-rights state file. Keep both forms sequential.
+  for (const agent of ['codex-scout', 'codex-build']) {
+    const key = `sandbox:${sandboxModeFor(agent)}`;
+    if (codexAvailable === false) {
+      rows.push(check(key, 'warn', `not probed: Codex CLI is unavailable; folder: ${folder}`));
+      continue;
+    }
+    // Plan_57: if taskkill fails, only cmd.exe dies; Codex may still update shared sandbox state.
+    if (agent === 'codex-build' && readOnlyInconclusive) {
+      rows.push(check(key, 'warn', `not probed: the read-only probe was inconclusive; rerun codex-bridge doctor; probed folder: ${folder}`));
+      continue;
+    }
+    const result = await probe({ agent, repo: root, platform, timeoutMs });
+    if (agent === 'codex-scout') readOnlyInconclusive = result.outcome === 'inconclusive';
+    switch (result.outcome) {
+      case 'alive':
+        rows.push(check(key, 'ok', `${clause(result.reason)}; probed folder: ${folder}`));
+        break;
+      case 'dead': {
+        const diagnosis = result.diagnosis == null
+          ? ['No sandbox log diagnosis is available.'] : formatSandboxDiagnosis(result.diagnosis);
+        rows.push(check(key, 'fail', [
+          result.reason,
+          ...diagnosis.map((line) => `    ${line}`),
+          '    Repair the host sandbox and rerun codex-bridge doctor.',
+          `    Probed folder: ${folder}`,
+        ].join('\n')));
+        break;
+      }
+      case 'inconclusive':
+        rows.push(check(key, 'warn', `readiness not established: ${clause(result.reason)}; probed folder: ${folder}`));
+        break;
+      case 'skipped':
+        rows.push(check(key, 'warn', `not probed on ${platform}: the package has never observed this platform's sandbox; folder: ${folder}`));
+        break;
+      default:
+        throw new Error(`unknown sandbox probe outcome: ${result.outcome}`);
+    }
+  }
+  return rows;
+}

package/cli/doctor.mjs

@@ -5,12 +5,13 @@ import { spawnSync } from 'node:child_process';
 import { packageSource } from './package-source.mjs';
 import { readInstallRecord, packageInfo } from './manifest.mjs';
 import { readInstallRecordFile, recordTarget } from './install-record.mjs';
-import { runsRoot } from '../src/home/lib/runner/runs-root.mjs';
+import { runsRootResolution } from '../src/home/lib/runner/runs-root.mjs';
 import { check, renderDoctor } from './doctor-format.mjs';
 import { homeOwnersCheck, hostSideCheck, ownerEntry, ownersInSyncCheck } from './doctor-host-side.mjs';
 import { inspectHost } from './host-inspection.mjs';
 import {
   agentsCheck,
+  claudeRulesCheck,
   conventionsCheck,
   exists,
   isFile,
@@ -18,6 +19,7 @@ import {
   rulesCheck,
 } from './doctor-installation.mjs';
 import { hookChecks } from './doctor-hooks.mjs';
+import { loadWitnessChecks } from './doctor-load-witness.mjs';
 import { contractStatus, readHostContract } from './host-contract.mjs';
 import { handbackWitnessStatus } from './handback-witness-check.mjs';
 import { dispatcherModelChecks } from './dispatcher-model-check.mjs';
@@ -30,7 +32,7 @@ import { brandStateDir } from '../src/home/lib/brand-home.mjs';
 import { readHostObservations } from '../src/home/lib/host-observations.mjs';
 import { activeHostVersions } from './active-hosts.mjs';
 import { otherHostCheck, sessionHostCheck, sessionHostVersions } from './session-hosts.mjs';
-import { liveRunsCheck, projectRunsCheck, retentionCheck } from './doctor-runs.mjs';
+import { liveRunsCheck, projectRunsCheck, retentionCheck, runsRootCheck } from './doctor-runs.mjs';
 
 export { renderDoctor };
 
@@ -48,7 +50,10 @@ function sourceCheck() {
 export function probeCodex() {
   const command = process.platform === 'win32' ? process.env.ComSpec || 'cmd.exe' : 'codex';
   const args = process.platform === 'win32' ? ['/d', '/s', '/c', 'codex --version'] : ['--version'];
-  const result = spawnSync(command, args, { encoding: 'utf8', windowsHide: true });
+  const result = spawnSync(command, args, { encoding: 'utf8', windowsHide: true, timeout: 15_000 });
+  if (result.error?.code === 'ETIMEDOUT') {
+    return { available: false, value: 'Codex CLI version check timed out after 15000 ms.' };
+  }
   if (result.error || result.status !== 0) {
     return { available: false, value: (result.stderr || result.error?.message || 'not found').trim() };
   }
@@ -81,6 +86,7 @@ function dispatcherContractChecks({ record, version, stateDir }) {
 export async function diagnose({
   host,
   codexProbe = probeCodex,
+  sandbox,
   bridgeProbe = probeCodexBridge,
   launcherProbe,
   currentPackage,
@@ -145,6 +151,8 @@ export async function diagnose({
   checks.push(agents);
   const rules = await rulesCheck(host, record);
   checks.push(rules);
+  const claudeRules = await claudeRulesCheck(host, record);
+  checks.push(claudeRules);
   checks.push(await permissionsCheck(host));
   const bridge = bridgeProbe();
   checks.push(bridgeCommandCheck(bridge));
@@ -157,6 +165,7 @@ export async function diagnose({
   const modelRecord = dispatcherModelRecord === undefined ? readDispatcherModel({ stateDir }) : dispatcherModelRecord;
   const activeHosts = injectedActiveHosts ?? (hostVersion !== undefined ? [hostVersion].filter(Boolean)
     : activeHostVersions({ observations: hostObservations, witnessRecord, modelRecord, now }));
+  checks.push(...await loadWitnessChecks({ host, record, stateDir, activeHosts }));
   checks.push(sessionHostCheck(observedVersions, hostObservations));
   const refusalRecord = contractRecord === undefined ? await readHostContract(host) : contractRecord;
   const hostContract = contractStatus({
@@ -194,18 +203,27 @@ export async function diagnose({
 
   const codex = codexProbe();
   checks.push(check('codex', codex.available ? 'ok' : 'warn', codex.value || 'available'));
+  if (typeof sandbox === 'function') checks.push(...await sandbox({ codexAvailable: codex.available }));
   const nodeMajor = Number.parseInt(process.versions.node.split('.')[0], 10);
   checks.push(check('node', nodeMajor >= 24 ? 'ok' : 'fail', `${process.versions.node} (requires >=24)`));
-  checks.push(check('runsRoot', 'ok', path.resolve(runsRoot())));
-  const projectRuns = projectRunsCheck();
-  checks.push(liveRunsCheck());
+  // Plan_77 D6: catch a corrupt move record without aborting doctor, and share one resolution.
+  let resolution;
+  const runsRoot = runsRootCheck({ get resolution() { return (resolution = runsRootResolution()); } });
+  checks.push(runsRoot);
+  const unavailable = 'unavailable: CODEX_RUNS_ROOT points under a retired runs root';
+  const projectRuns = resolution?.staleOverride ? check('projectRuns', 'fail', unavailable)
+    : resolution ? projectRunsCheck(resolution) : check('projectRuns', 'fail', runsRoot.value);
+  checks.push(resolution?.staleOverride ? check('liveRuns', 'fail', unavailable)
+    : resolution ? liveRunsCheck(resolution)
+      : check('liveRuns', 'warn', `working-run count unavailable: ${runsRoot.value}`));
   checks.push(projectRuns);
 
   return {
     exitCode: !record || recordBroken || missingFiles.length || agents.status === 'fail' || rules.status === 'fail'
+      || claudeRules.status === 'fail'
       || hostContractStatus === 'fail' || retention.status === 'fail' || conventions.status === 'fail'
-      || projectRuns.status === 'fail'
-      || checks.some((item) => /^(hook|dispatcherContract|dispatcherModel):/.test(item.key) && item.status === 'fail')
+      || runsRoot.status === 'fail' || projectRuns.status === 'fail'
+      || checks.some((item) => /^(hook|dispatcherContract|dispatcherModel|sandbox):/.test(item.key) && item.status === 'fail')
       || checks.some((item) => item.key.startsWith('otherHost:') && item.status === 'fail') ? 1 : 0,
     checks,
     record,

package/cli/guidance.mjs

@@ -0,0 +1,42 @@
+/** Prints detailed package guidance from the installed brand home. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveBrandHome } from '../src/home/lib/brand-home.mjs';
+
+export const GUIDANCE_TOPICS = Object.freeze({
+  order: 'Task file, header labels, and scope.',
+  advisor: 'Scope and advise phases, and the continue grant.',
+  budget: 'Run deadline and slicing.',
+  records: 'Finding and reading runs.',
+  concurrency: 'Parallel and writing runs.',
+});
+
+const topicList = () => [
+  'Topics:',
+  ...Object.entries(GUIDANCE_TOPICS).map(([topic, summary]) => `  ${topic} — ${summary}`),
+  '',
+  'Usage: codex-bridge guidance [<topic>]',
+].join('\n');
+
+export function guidance(argv, { env = process.env, homedir } = {}) {
+  if (argv.length === 0) return { exitCode: 0, output: topicList() };
+  if (argv.length > 1) {
+    return { exitCode: 2, output: `codex-bridge guidance accepts at most one topic.\n${topicList()}` };
+  }
+  const [topic] = argv;
+  if (!Object.hasOwn(GUIDANCE_TOPICS, topic)) {
+    return { exitCode: 2, output: `Unknown guidance topic "${topic}".\n${topicList()}` };
+  }
+
+  // The 2026-08-26 seeded-config incident forbids reading installed files from the clone.
+  const { root } = resolveBrandHome({ homedir, env });
+  const file = path.join(root, 'guidance', `${topic}.md`);
+  try {
+    return { exitCode: 0, output: fs.readFileSync(file, 'utf8') };
+  } catch (error) {
+    return {
+      exitCode: 1,
+      output: `Cannot read guidance file ${file}: ${error.message}\nrun codex-bridge update`,
+    };
+  }
+}

package/cli/host-inspection.mjs

@@ -144,6 +144,7 @@ export async function inspectHost(host, { owner = null, packageRoot } = {}) {
   };
   await walk(context, host.agentsDir);
   await walk(context, host.commandsDir);
+  await walk(context, host.rulesDir);
   await inspectLegacyDirectory(context, host.legacyAgentsDir, plan.filter((item) => isWithin(host.agentsDir, item.target)));
   await inspectLegacyDirectory(context, host.legacyCommandsDir, plan.filter((item) => isWithin(host.commandsDir, item.target)));
   await inspectLegacyRecord(context);

package/cli/hosts.mjs

@@ -3,9 +3,10 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { resolveBrandHome } from '../src/home/lib/brand-home.mjs';
-import { claudePaths } from '../src/home/lib/claude-layout.mjs';
+import { claudePaths } from '../src/home/lib/claude-layout.mjs';
+import { resolveCodexHome } from '../src/home/lib/codex-home.mjs';
 
-function repositoryRoot(start) {
+export function repositoryRoot(start) {
   let current = path.resolve(start);
   while (true) {
     if (fs.existsSync(path.join(current, '.git'))) return current;
@@ -23,7 +24,7 @@ export function resolveHost({
   codexHome,
   brandRoot,
 } = {}) {
-  const resolvedCodexHome = codexHome || process.env.CODEX_HOME || path.join(homedir, '.codex');
+  const resolvedCodexHome = codexHome || resolveCodexHome({ homedir });
   const codexRulesDir = path.join(resolvedCodexHome, 'rules');
   // Plan_25 moves package-owned runtime files out of foreign Claude settings, whose absolute
   // hook paths caused the package-file-layout incident. Keep the brand root overrideable so tests

package/cli/install-record.mjs

@@ -78,8 +78,10 @@ function normalizedFiles(record) {
     validPath(entry.path, 'installation record file path');
     // Run artifacts are the user's data, not ours. Refusing them here means neither uninstall nor
     // update needs its own guard against deleting a run folder someone listed as an installed file.
-    if (entry.path === 'codex-runs' || entry.path.split(/[\\/]/)[0] === 'codex-runs') {
-      throw new Error('installation record files must not name run artifacts under codex-runs');
+    // Plan_77 D1: the records move to runs/ of the brand home, so that folder is refused too.
+    const top = entry.path.split(/[\\/]/)[0];
+    if (top === 'codex-runs' || (entry.root === 'brand' && top === 'runs')) {
+      throw new Error(`installation record files must not name run artifacts under ${top}`);
     }
     return { root: entry.root, path: entry.path };
   });

package/cli/manifest.mjs

@@ -45,7 +45,7 @@ export {
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 export const PACKAGE_ROOT = path.resolve(HERE, '..');
-const RULES_SOURCE = `src/rules/${RULES_NAME}`;
+const RULES_SOURCE = `src/codex/rules/${RULES_NAME}`;
 
 /**
  * Files the operator owns once they exist. Seeded on first install so the defaults are
@@ -57,8 +57,9 @@ const RULES_SOURCE = `src/rules/${RULES_NAME}`;
 export const SEEDED_SOURCES = Object.freeze(['src/home/config.json', 'src/home/conventions.md']);
 
 export const INSTALL_TABLE = Object.freeze([
-  { source: 'src/agents/*.md', root: 'claude', target: 'agentsDir', processing: 'placeholders' },
-  { source: 'src/commands/*.md', root: 'claude', target: 'commandsDir', processing: 'placeholders' },
+  { source: 'src/claude/agents/*.md', root: 'claude', target: 'agentsDir', processing: 'placeholders' },
+  { source: 'src/claude/commands/*.md', root: 'claude', target: 'commandsDir', processing: 'placeholders' },
+  { source: 'src/claude/rules/*.md', base: 'src/claude/rules', root: 'claude', target: 'rulesDir', processing: 'copy' },
   // The source is the host image. Keeping one source root and one target root makes any future
   // remapping visible as a test failure instead of another clone-only import success.
   { source: 'src/home/**', root: 'brand', target: 'brandRoot', processing: 'copy' },
@@ -139,6 +140,8 @@ function rootFor(host, mapping) {
 }
 
 function targetRelative(packageRoot, source, mapping) {
+  // Plan_64 D9: copy rows outside src/home need their own base to avoid escaping the target directory.
+  if (mapping.base) return path.relative(path.join(packageRoot, mapping.base), source);
   if (mapping.processing === 'placeholders' || mapping.source === 'package.json') {
     return path.basename(source);
   }

package/cli/read.mjs

@@ -3,7 +3,6 @@ import path from 'node:path';
 import { readJsonFileSync } from '../src/home/lib/json-file.mjs';
 import { readEvents } from '../src/home/lib/meta/events.mjs';
 import { safeSlice } from '../src/home/lib/meta/paths.mjs';
-import { runsRoot } from '../src/home/lib/runner/runs-root.mjs';
 import { resolveRunFolder } from './run-lookup.mjs';
 
 const result = (exitCode, output) => ({ exitCode, output });
@@ -85,7 +84,7 @@ function renderEvent(event, transportError) {
   }
 }
 
-export function read({ run, cwd = process.cwd(), runsRootPath = runsRoot() } = {}) {
+export function read({ run, cwd = process.cwd(), runsRootPath } = {}) {
   const lookup = resolveRunFolder({ command: 'read', run, cwd, runsRootPath });
   if (lookup.error) return result(1, lookup.error);
 

package/cli/removal-outcomes.mjs

@@ -4,7 +4,7 @@
  * Plan_65 D12 item 7 requires actual counts and named keeps: planned removal must not claim
  * that edited image files disappeared, or confuse removing an owner with deleting its record.
  */
-import { runsRoot } from '../src/home/lib/runner/runs-root.mjs';
+import { runsRootResolution } from '../src/home/lib/runner/runs-root.mjs';
 
 const unsafeReason = (reason) => reason.startsWith('link') || reason.startsWith('unreadable');
 // An image file kept by content evidence is named; one kept by policy (another owner, an incomplete
@@ -12,7 +12,10 @@ const unsafeReason = (reason) => reason.startsWith('link') || reason.startsWith(
 const EVIDENCE_KEEP = new Set(['changed', 'link']);
 const namedKeep = (entry) => unsafeReason(entry.reason) || entry.id === null
   || (entry.id === 'install-image' && EVIDENCE_KEEP.has(entry.reason));
-const artifactsLine = () => `Run artifacts in ${runsRoot()} are outside uninstall and stay.`;
+const artifactsLine = () => {
+  const resolution = runsRootResolution();
+  return `Run artifacts in ${resolution.staleOverride ? resolution.homeRoot : resolution.root} are outside uninstall and stay.`;
+};
 
 function fileLines(files, host, dryRun) {
   const lines = [];

package/cli/removal-plan.mjs

@@ -8,6 +8,7 @@
 import {
   HOME_ARTIFACTS,
   HOME_DIRECTORIES,
+  RUN_RECORDS_DIR,
   classifyHomePath,
   homeArtifact,
 } from '../src/home/lib/home-registry.mjs';
@@ -99,7 +100,9 @@ export function planHomeFiles({ command, inspection, imageMembers, imageEvidence
   }
   for (const entry of inspection.unknown) {
     add(entry.relative, { id: null, role: null, removal: null }, {
-      action: 'keep', reason: entry.kind === 'directory' ? 'unknown directory' : 'unknown',
+      // The inspection never walks an undeclared folder; the run records folder is one, by design.
+      action: 'keep', reason: entry.relative === RUN_RECORDS_DIR && entry.kind === 'directory' ? 'run records'
+        : entry.kind === 'directory' ? 'unknown directory' : 'unknown',
     });
   }
   for (const file of inspection.files) {

package/cli/remove-layout.mjs

@@ -33,15 +33,15 @@ export async function removeEmptyParents(target, boundary) {
 }
 
 /**
- * The directory an emptied-parent walk must stop at. Plan_25 gave the host four package-owned
- * directories at once — the current agents and commands subdirectories and the two the previous
- * layout used — and a walk that started inside one of them but stopped at host.root would delete
- * the operator's own emptied directories on the way up.
+ * The directory an emptied-parent walk must stop at: five package-owned directories: current
+ * agents, commands and rules (Plan_64 D5, D9), plus the two legacy directories (Plan_25).
+ * Stopping there preserves the operator's own emptied parent directories.
  */
 export function claudeBoundary(host, target) {
   const directories = [
     host.agentsDir,
     host.commandsDir,
+    host.rulesDir,
     host.legacyAgentsDir,
     host.legacyCommandsDir,
   ].filter(Boolean);

package/cli/run-lookup.mjs

@@ -3,7 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { git } from '../src/home/lib/runner/git-state.mjs';
 import { resolveProjectRunsDir } from '../src/home/lib/runner/project-dir.mjs';
-import { runsRoot } from '../src/home/lib/runner/runs-root.mjs';
+import { retiredPathRefusal, runsRootResolution, staleOverrideRefusal } from '../src/home/lib/runner/runs-root.mjs';
 
 function projectRoot(cwd) {
   const result = git(cwd, ['rev-parse', '--show-toplevel']);
@@ -23,7 +23,8 @@ export function resolveRunFolder({
   command = 'stop',
   run,
   cwd = process.cwd(),
-  runsRootPath = runsRoot(),
+  runsRootPath,
+  resolution = runsRootResolution(),
 } = {}) {
   const commandName = String(command || 'stop');
   const value = String(run ?? '').trim();
@@ -31,6 +32,17 @@ export function resolveRunFolder({
     return refusal(commandName, `${commandName} requires a run folder (full path or bare folder name)`);
   }
 
+  // Plan_77 D6: run-lookup.mjs:51-55 only said "Run folder not found" after stat on an old path.
+  if (path.isAbsolute(value)) {
+    const retired = retiredPathRefusal(value, resolution);
+    if (retired) return refusal(commandName, retired);
+  }
+  if (runsRootPath === undefined) {
+    const stale = staleOverrideRefusal(resolution);
+    if (stale) return refusal(commandName, stale);
+    runsRootPath = resolution.root;
+  }
+
   let runDir;
   try {
     if (path.isAbsolute(value)) runDir = path.resolve(value);

package/cli/runs-inventory.mjs

@@ -108,6 +108,7 @@ function readRun(runDir, livePaths) {
   const live = livePaths.has(pathKey(runDir));
   return {
     run: path.basename(runDir),
+    path: path.resolve(runDir),
     agent: text(facts?.agent),
     verdict: live ? 'running' : text(meta ? meta.status : runLiveness({ runDir, status }).state),
     tokens: meta ? number(meta.tokens) : null,
@@ -120,6 +121,8 @@ function readRun(runDir, livePaths) {
 function publicRun(run) {
   return {
     run: run.run,
+    // D10: the core names no run root, so each JSON row must carry its address.
+    path: run.path,
     agent: run.agent,
     verdict: run.verdict,
     tokens: run.tokens,
@@ -155,16 +158,21 @@ function buildProject(projectDir) {
 }
 
 function projectDirectory(root, name) {
-  return directoryEntries(root)
+  return projectEntries(root)
     .find((entry) => entry.name === name)
     ? path.join(root, name)
     : null;
 }
 
+function projectEntries(root) {
+  // Plan_77 B5b makes the moved store a git repository; its metadata is not a project.
+  return directoryEntries(root).filter((entry) => entry.name !== '.git');
+}
+
 /** Lists one summary row per project directory. */
 export function listProjects(runsRootPath = runsRoot()) {
   const root = normalizeRoot(runsRootPath);
-  return directoryEntries(root).map((entry) => buildProject(path.join(root, entry.name)).summary);
+  return projectEntries(root).map((entry) => buildProject(path.join(root, entry.name)).summary);
 }
 
 /** Lists one detail row per run directory in a named project, or null when there is no such project. */