@lyupro/codex-bridge 0.6.11 → 0.6.14

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,18 +19,20 @@ 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 { handbackWitnessStatus } from './handback-witness-check.mjs';
 import { dispatcherModelChecks } from './dispatcher-model-check.mjs';
 import { dispatcherContractStatus } from './dispatcher-contract.mjs';
 import { DISPATCHER_CONTRACT_FILE, readDispatcherContract } from './dispatcher-contract-record.mjs';
 import { PROBE_COMMAND } from './host-contract.mjs';
-import { readHandbackWitness } from '../src/home/lib/handback-witness.mjs';
+import { readHandbackWitness } from '../src/home/lib/handback-witness.mjs';
 import { readDispatcherModel } from '../src/home/lib/dispatcher-model.mjs';
 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 };
 
@@ -47,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() };
   }
@@ -80,14 +86,17 @@ function dispatcherContractChecks({ record, version, stateDir }) {
 export async function diagnose({
   host,
   codexProbe = probeCodex,
+  sandbox,
   bridgeProbe = probeCodexBridge,
   launcherProbe,
   currentPackage,
   contractRecord,
-  handbackWitnessRecord,
+  handbackWitnessRecord,
   dispatcherModelRecord,
   dispatcherContractRecord,
   hostVersion,
+  activeHosts: injectedActiveHosts,
+  now,
   observations,
 } = {}) {
   const checks = [sourceCheck()];
@@ -142,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));
@@ -150,6 +161,11 @@ export async function diagnose({
   const hostObservations = observations === undefined ? readHostObservations({ stateDir }) : observations;
   const observedVersions = sessionHostVersions(hostObservations);
   const detectedHostVersion = hostVersion === undefined ? observedVersions[0] ?? null : hostVersion;
+  const witnessRecord = handbackWitnessRecord === undefined ? readHandbackWitness({ stateDir }) : handbackWitnessRecord;
+  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({
@@ -161,15 +177,15 @@ export async function diagnose({
     : hostContract.state === 'ignored' ? 'fail' : 'warn';
   checks.push(check('hostContract', hostContractStatus, hostContract.message));
   const witness = handbackWitnessStatus({
-    record: handbackWitnessRecord === undefined ? readHandbackWitness({ stateDir }) : handbackWitnessRecord,
-    hostVersion: detectedHostVersion,
+    record: witnessRecord,
+    activeHosts,
     stateDir,
   });
-  checks.push(check('handbackWitness', ['violation', 'unreadable'].includes(witness.state) ? 'warn' : 'ok', witness.message));
-  checks.push(...dispatcherModelChecks({
-    record: dispatcherModelRecord === undefined ? readDispatcherModel({ stateDir }) : dispatcherModelRecord,
-    hostVersion: detectedHostVersion,
-    stateDir,
+  checks.push(check('handbackWitness', ['violation', 'unreadable'].includes(witness.state) ? 'warn' : 'ok', witness.message));
+  checks.push(...dispatcherModelChecks({
+    record: modelRecord,
+    activeHosts,
+    stateDir,
   }));
   const dispatcherRecord = dispatcherContractRecord === undefined ? readDispatcherContract({ stateDir }) : dispatcherContractRecord;
   checks.push(...dispatcherContractChecks({
@@ -187,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/handback-witness-check.mjs

@@ -1,37 +1,41 @@
-/** Surfaces handback drift; 2026-09-25 established exact host transcript versions as identity. */
+/** Surfaces handback drift; Plan_67 D12 judges every host with recent dispatcher activity. */
 import path from 'node:path';
 import { WITNESS_FILE } from '../src/home/lib/handback-witness.mjs';
 import { entryState } from '../src/home/lib/observation-ledger.mjs';
 
-export function handbackWitnessStatus({ record, hostVersion, stateDir }) {
+export function handbackWitnessStatus({ record, activeHosts, stateDir }) {
   if (record?.corrupt) {
     return { state: 'unreadable', message: `The handback witness is unreadable; delete ${path.join(stateDir, WITNESS_FILE)} to reset it.` };
   }
   const entries = Object.values(record?.ledger?.entries || {});
+  let history = '';
+  const recovered = entries.filter((entry) => entryState(entry) === 'recovered').length;
+  const historical = entries.filter((entry) => entryState(entry) === 'violation'
+    && !activeHosts.includes(entry.lastObservation.data.hostVersion)).length;
+  const legacy = record?.legacy || [];
+  if (recovered || historical || legacy.length) {
+    const untyped = legacy.filter((entry) => entry.disposition === 'legacy-untyped-unverified').length;
+    const unclassified = legacy.filter((entry) => entry.disposition === 'unclassified').length;
+    history = ` History: ${recovered} recovered entries; ${historical} unresolved entries on hosts without dispatcher activity in the last 24 hours (history); ${untyped} older alarms without dispatcher evidence, kept for history (legacy-untyped-unverified); ${unclassified} unclassified legacy entries.`;
+  }
   const violations = entries.filter((entry) => entryState(entry) === 'violation'
-    && entry.lastObservation.data.hostVersion === hostVersion);
+    && activeHosts.includes(entry.lastObservation.data.hostVersion));
   if (violations.length > 0) {
     const details = violations.map((entry) => {
       const { data, detail, at } = entry.lastViolation;
-      return `${data.cause}${data.agentType ? ` / ${data.agentType}` : ''}: ${detail} at ${at}`;
+      return `host ${data.hostVersion}: ${data.cause}${data.agentType ? ` / ${data.agentType}` : ''}: ${detail} at ${at}`;
     });
     return {
       state: 'violation',
-      message: `Dispatcher violation(s) on host ${hostVersion ?? 'unknown host'}: ${details.join('; ')}; do not trust a dispatcher answer from that time; see Plan_62 D15.`,
+      message: `Dispatcher violation(s): ${details.join('; ')}; do not trust a dispatcher answer from that time; see Plan_62 D15.${history}`,
     };
   }
-  const intercepted = record?.intercepted?.[hostVersion || 'unknown'];
-  let message = intercepted
-    ? `Newest intercepted handback on host ${hostVersion ?? 'unknown host'} at ${intercepted}.`
-    : 'Not observed yet — a handback is seen only when a dispatcher runs in an interactive session.';
-  const recovered = entries.filter((entry) => entryState(entry) === 'recovered').length;
-  const historical = entries.filter((entry) => entryState(entry) === 'violation'
-    && entry.lastObservation.data.hostVersion !== hostVersion).length;
-  const legacy = record?.legacy || [];
-  if (recovered || historical || legacy.length) {
-    const untyped = legacy.filter((entry) => entry.disposition === 'legacy-untyped-unverified').length;
-    const unclassified = legacy.filter((entry) => entry.disposition === 'unclassified').length;
-    message += ` History: ${recovered} recovered entries; ${historical} unresolved entries on other hosts (historical, not current); ${untyped} older alarms without dispatcher evidence, kept for history (legacy-untyped-unverified); ${unclassified} unclassified legacy entries.`;
-  }
-  return { state: 'ok', message };
+  const intercepted = activeHosts.filter((host) => record?.intercepted?.[host])
+    .map((host) => `host ${host} at ${record.intercepted[host]}`);
+  const message = !activeHosts.length
+    ? 'No dispatcher activity in the last 24 hours.'
+    : intercepted.length
+      ? `Newest intercepted handback on ${intercepted.join('; ')}.`
+      : 'Not observed yet — a handback is seen only when a dispatcher runs in an interactive session.';
+  return { state: 'ok', message: message + history };
 }

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 };
   });
@@ -307,6 +309,11 @@ async function publishInstallRecord(host, next) {
   await writer.rename('install-record', temporary, target);
 }
 
+/** Plan_67 D11 / A4: changing inventory must not rebuild owners or hide fingerprint lag. */
+export function publishInstallRecordOnly(host, next) {
+  return publishInstallRecord(host, next);
+}
+
 /**
  * Publishes the record whole through a temporary and a rename: a direct write left a half-written
  * record for every host sharing the home if the process died mid-write (advice A3, risk r3).

package/cli/inventory-confirm.mjs

@@ -0,0 +1,75 @@
+/** Lets the operator declare a shared home's installation inventory complete, the one statement the package cannot prove.
+ * Plan_67 D11, OW-047: only the operator can account for unrecorded hosts using this home.
+ */
+import { isFormat2 } from '../src/home/lib/install-owner-roots.mjs';
+import { publishInstallRecordOnly, readInstallRecordFile } from './install-record.mjs';
+import { validateFormat2 } from './install-owners.mjs';
+import { registryHintLines } from './inventory-transition.mjs';
+import { withLifecycle } from './lifecycle-transaction.mjs';
+import { readRulesRegistry } from './rules-owners.mjs';
+import { askYesNo, isInteractive } from './terminal-question.mjs';
+
+export const INVENTORY_CONFIRM_COMMAND = 'codex-bridge inventory confirm';
+
+const question = 'Are these all the hosts using this home?';
+const updateHint = 'Run codex-bridge update to migrate the installation record.';
+
+async function confirmInRun(host, dryRun, questionOptions) {
+  let record;
+  try {
+    record = await readInstallRecordFile(host);
+    if (!isFormat2(record)) {
+      return { exitCode: 1, output: `No format-2 installation record was found. ${updateHint}` };
+    }
+    validateFormat2(record);
+  } catch (error) {
+    return { exitCode: 1, output: `Invalid installation record: ${error.message} ${updateHint}` };
+  }
+  const owners = Object.values(record.owners);
+  if (owners.length === 0) {
+    return { exitCode: 1, output: 'no recorded owners; install into each host first' };
+  }
+  if (record.inventory === 'complete' && !Object.hasOwn(record, 'legacy')) {
+    return { exitCode: 0, output: 'The inventory is already complete.' };
+  }
+
+  const screen = [
+    `Home: ${host.brandRoot}`,
+    'Recorded hosts:',
+    ...owners.map((owner) => `  ${owner.root}`),
+    ...registryHintLines(host, (await readRulesRegistry(host))?.owners ?? []),
+    "Confirming lets the last recorded host's uninstall remove the shared image. "
+      + 'A host that uses this home but is not listed must be enrolled first: '
+      + 'codex-bridge install --host "<path>".',
+  ].join('\n');
+  if (dryRun) return { exitCode: 0, output: `${screen}\nDry run: nothing changed.` };
+  const prompt = `${screen}\n${question}`;
+  if (!isInteractive(questionOptions)) {
+    return { exitCode: 1, output: `${prompt}\nRun this command in a terminal to answer.` };
+  }
+  const answer = await askYesNo(prompt, questionOptions);
+  if (answer === 'cancel') {
+    return { exitCode: 130, output: `${prompt}\nCancelled; nothing was changed.` };
+  }
+  if (answer !== 'yes') {
+    return { exitCode: 1, output: `${prompt}\nNothing changed: the inventory stays incomplete.` };
+  }
+
+  // A4 pre-mortem: the raw fields are evidence of lag, not material to regenerate on confirmation.
+  const next = { ...record, inventory: 'complete' };
+  delete next.legacy;
+  await publishInstallRecordOnly(host, next);
+  return { exitCode: 0, output: `${prompt}\nRecorded the inventory as complete.` };
+}
+
+export async function inventoryConfirm({ host, dryRun = false, ...questionOptions }) {
+  const action = (ticket) => {
+    // Plan_67 R2: a first install may create the home after the unlocked missing-home check.
+    if (!dryRun && ticket === undefined) {
+      return { exitCode: 1, output: `No format-2 installation record was found. ${updateHint}` };
+    }
+    return confirmInRun(host, dryRun, questionOptions);
+  };
+  // Plan_67 D11: dry-run only reads; a real declaration holds the lifecycle lock before reading.
+  return dryRun ? action() : withLifecycle(host, 'inventory', action);
+}

package/cli/inventory-transition.mjs

@@ -3,6 +3,7 @@
  * store nothing about a refusal.
  */
 import fs from 'node:fs/promises';
+import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { askYesNo, isInteractive } from './terminal-question.mjs';
 import { isFormat2 } from '../src/home/lib/install-owner-roots.mjs';
@@ -36,7 +37,8 @@ export function registryHintLines(host, candidates) {
   const otherCandidates = candidates.filter((root) => root !== owner);
   return [
     'Codex rules registry host roots are a hint only; they may be stale or belong to another home:',
-    ...(otherCandidates.length ? otherCandidates.map((root) => `  ${root}`) : ['  none found']),
+    ...(otherCandidates.length ? otherCandidates.map((root) =>
+      `  ${root}${existsSync(root) ? '' : ' (folder does not exist)'}`) : ['  none found']),
   ];
 }
 

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) {