@lyupro/codex-bridge 0.3.1 → 0.5.0

package/cli/unlock.mjs

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+/** Closes dead-pid running records without deleting any run artifacts. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { formatSilence, heartbeatAge, HEARTBEAT_STALE_MS } from '../src/heartbeat.mjs';
+import { markAbandoned } from '../src/meta/run-state.mjs';
+import {
+  IDENTITY_ALIVE,
+  IDENTITY_UNVERIFIED,
+  processIdentity,
+} from '../src/process-identity.mjs';
+import { git } from '../src/runner/git-state.mjs';
+import { resolveProjectRunsDir } from '../src/runner/project-dir.mjs';
+import { runsRoot } from '../src/runner/runs-root.mjs';
+import { readJson } from '../src/write-meta.mjs';
+import { renderTable } from './table.mjs';
+
+const CLOSED_COLUMNS = [
+  { key: 'project', label: 'project' },
+  { key: 'run', label: 'run' },
+  { key: 'state', label: 'state' },
+];
+const RECORD_COLUMNS = [
+  { key: 'project', label: 'project', truncate: null },
+  { key: 'run', label: 'run', truncate: null },
+  { key: 'age', label: 'age', truncate: null },
+  { key: 'silence', label: 'silent for', truncate: null },
+  { key: 'identity', label: 'identity', truncate: null },
+  { key: 'state', label: 'state', truncate: null },
+];
+
+function result(exitCode, output) {
+  return { exitCode, output };
+}
+
+function parseArgs(argv) {
+  const positional = [];
+  let all = false;
+  for (const arg of argv) {
+    if (arg === '--all') {
+      if (all) return { error: 'codex-bridge unlock accepts --all only once.' };
+      all = true;
+      continue;
+    }
+    if (typeof arg !== 'string' || arg.startsWith('-')) {
+      return { error: `codex-bridge unlock: unknown option "${arg}".` };
+    }
+    positional.push(arg);
+  }
+  if (all && positional.length) {
+    return { error: 'codex-bridge unlock accepts either --all or one project name.' };
+  }
+  if (positional.length > 1) {
+    return { error: 'codex-bridge unlock accepts at most one project name.' };
+  }
+  const project = positional[0] || null;
+  if (project && (path.isAbsolute(project) || path.dirname(project) !== '.')) {
+    return { error: 'codex-bridge unlock requires a bare project name.' };
+  }
+  return { all, project };
+}
+
+function directories(root) {
+  try {
+    return fs.readdirSync(root, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .sort((left, right) => left.name.localeCompare(right.name));
+  } catch {
+    return [];
+  }
+}
+
+function allProjects(root) {
+  return directories(root).map((entry) => ({ name: entry.name, dir: path.join(root, entry.name) }));
+}
+
+function namedProject(root, projectName) {
+  const entry = directories(root).find((candidate) => candidate.name === projectName);
+  if (!entry) return { error: `codex-bridge unlock: unknown project "${projectName}".` };
+  return [{ name: entry.name, dir: path.join(root, entry.name) }];
+}
+
+function currentRepository(cwd) {
+  const result = git(cwd, ['rev-parse', '--show-toplevel']);
+  const output = String(result.stdout ?? '').trim();
+  return result.status === 0 && output ? output : cwd;
+}
+
+function selectedProjects(root, parsed, cwd) {
+  if (parsed.all) return allProjects(root);
+  if (parsed.project) return namedProject(root, parsed.project);
+  const resolved = resolveProjectRunsDir(root, currentRepository(cwd), { create: false });
+  return [{ name: resolved.name, dir: resolved.dir }];
+}
+
+export function unlockPlan(argv = [], options = {}) {
+  const parsed = parseArgs(argv);
+  if (parsed.error) return parsed;
+  const root = path.resolve(options.runsRootPath || runsRoot());
+  const projects = selectedProjects(root, parsed, options.cwd || process.cwd());
+  if (projects.error) return projects;
+  return {
+    root,
+    all: parsed.all,
+    project: parsed.project,
+    currentRepository: !parsed.all && !parsed.project,
+    projects,
+  };
+}
+
+function timestamp(value) {
+  const parsed = Date.parse(value || '');
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function runAge(startedAt, now) {
+  const started = timestamp(startedAt);
+  return formatSilence(started === null ? null : Math.max(0, now - started));
+}
+
+function identityOptions(runDir, status, options, now) {
+  return {
+    runDir,
+    status,
+    now,
+    kill: options.kill,
+    probe: options.probe,
+    processStartProbe: options.processStartProbe,
+    commandRunner: options.commandRunner,
+  };
+}
+
+function inspectRuns(project, options) {
+  const now = options.now ?? Date.now();
+  const records = [];
+  for (const entry of directories(project.dir)) {
+    const dir = path.join(project.dir, entry.name);
+    const status = readJson(path.join(dir, 'status.json'));
+    if (!status || status.state !== 'running') continue;
+    const silenceAge = heartbeatAge(dir, now);
+    records.push({
+      project: project.name,
+      run: entry.name,
+      age: runAge(status.started_at, now),
+      silence: formatSilence(silenceAge),
+      silenceAge,
+      identity: processIdentity(identityOptions(dir, status, options, now)),
+      state: status.state,
+    });
+  }
+  return records;
+}
+
+function closeDeadRuns(plan) {
+  const closed = [];
+  const failures = [];
+  for (const project of plan.projects) {
+    try {
+      // No worktree snapshot is passed, and that is the choice rather than an omission: `stop`
+      // closes one named run and knows which repository to look at, while an unlock over the
+      // store would have to run git in every repository ever pointed at. The runs it closes died
+      // long ago, so a current tree would describe today's work, not their abandoned run.
+      for (const change of markAbandoned(project.dir)) {
+        closed.push({ project: project.name, run: change.run, state: change.state });
+      }
+    } catch (error) {
+      failures.push({ project: project.name, message: error.message });
+    }
+  }
+  return { closed, failures };
+}
+
+function reportRows(records, closed) {
+  const closedByRun = new Map(closed.map((change) => [`${change.project}\u0000${change.run}`, change.state]));
+  return records.map((record) => ({
+    ...record,
+    state: closedByRun.get(`${record.project}\u0000${record.run}`) || record.state,
+  }));
+}
+
+function renderReport(plan, records, closed, failures, options) {
+  const scope = plan.all ? 'all projects' : plan.project ? `project "${plan.project}"` : 'the current repository';
+  const rows = reportRows(records, closed);
+  const stalled = records.filter((record) => (
+    record.identity === IDENTITY_ALIVE
+      && Number.isFinite(record.silenceAge)
+      && record.silenceAge > HEARTBEAT_STALE_MS
+  ));
+  const alive = records.filter((record) => record.identity === IDENTITY_ALIVE);
+  const unverified = records.filter((record) => record.identity === IDENTITY_UNVERIFIED);
+  const lines = [`Unlock of ${scope} completed.`];
+  if (closed.length) {
+    lines.push(`Closed ${closed.length} running record${closed.length === 1 ? '' : 's'}:`);
+    lines.push(renderTable(CLOSED_COLUMNS, closed, options));
+  } else {
+    lines.push('Nothing to close; the store is unchanged.');
+  }
+  if (rows.length) {
+    lines.push('Running records inspected:');
+    lines.push(renderTable(RECORD_COLUMNS, rows, options));
+  } else {
+    lines.push('Running records inspected: none.');
+  }
+  if (alive.length) {
+    lines.push(
+      `Refused to close ${alive.length} confirmed-alive run${alive.length === 1 ? '' : 's'}; `
+        + 'use codex-bridge stop <run> instead.',
+    );
+    for (const run of alive) lines.push(`  codex-bridge stop ${run.run}`);
+  }
+  if (unverified.length) {
+    lines.push(
+      `Left ${unverified.length} run${unverified.length === 1 ? '' : 's'} untouched because `
+        + 'process identity is unverified.',
+    );
+  }
+  if (stalled.length) {
+    lines.push(`Left ${stalled.length} live-pid run${stalled.length === 1 ? '' : 's'} with stale heartbeats untouched:`);
+    lines.push(renderTable(RECORD_COLUMNS, stalled, options));
+  } else {
+    lines.push('Live-pid runs with stale heartbeats left untouched: none.');
+  }
+  if (failures.length) {
+    lines.push('Some project records could not be unlocked:');
+    for (const failure of failures) lines.push(`  ${failure.project}: ${failure.message}`);
+  }
+  return lines.join('\n');
+}
+
+export function unlock(argv = [], options = {}) {
+  const plan = unlockPlan(argv, options);
+  if (plan.error) return result(2, plan.error);
+  const records = plan.projects.flatMap((project) => inspectRuns(project, options));
+  const { closed, failures } = closeDeadRuns(plan);
+  return result(
+    failures.length ? 1 : 0,
+    renderReport(plan, records, closed, failures, options),
+  );
+}

package/cli/update.mjs

@@ -1,4 +1,4 @@
-/** Updates a recorded codex-bridge installation without overwriting unapproved host changes. */
+/** Updates a recorded installation without overwriting unapproved host changes. */
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { install } from './install.mjs';
@@ -7,14 +7,26 @@ import {
   fileFingerprint,
   HOOK_DEFINITIONS,
   installedHookPath,
+  legacyInstallRecordPath,
   packageInfo,
+  recordFileKey,
   readInstallRecord,
   recordMatchesPackage,
+  recordTarget,
   rulesPlan,
 } from './manifest.mjs';
 import { targetMatches } from './copy.mjs';
-import { commandFor, inspectHook } from './settings-merge.mjs';
+import { hookTargets } from './hook-targets.mjs';
+import { definitionForRecordedHook, fileEntry, fingerprintFor } from './install-record.mjs';
+import {
+  commandFor,
+  hookRegistration,
+  inspectHook,
+  removeHook,
+  withSettingsRun,
+} from './settings-merge.mjs';
 import { addRulesOwner, readRulesRegistry } from './rules-owners.mjs';
+import { claudeBoundary, removeEmptyLayout, removeEmptyParents } from './remove-layout.mjs';
 
 async function exists(target) {
   try {
@@ -25,7 +37,19 @@ async function exists(target) {
   }
 }
 
-function classifyPlanned(state, record) {
+/** Drops the previous layout's record and its emptied directories; safe to run when both are gone. */
+async function retireLegacyLayout(host) {
+  await fs.rm(legacyInstallRecordPath(host), { force: true });
+  await removeEmptyLayout(host.legacyAgentsDir);
+  await removeEmptyLayout(host.legacyCommandsDir);
+}
+
+function displayFile(file) {
+  const entry = fileEntry(file);
+  return `${entry.root}/${entry.path}`;
+}
+
+function classifyPlanned(state) {
   if (!state.recorded) return 'new';
   if (!state.exists) return 'missing';
   if (state.matchesPackage) return 'up-to-date';
@@ -33,40 +57,24 @@ function classifyPlanned(state, record) {
   return 'modified';
 }
 
-function classifyOrphan(state, record) {
+function classifyOrphan(state) {
   if (!state.exists) return 'orphaned';
-  if (record.fingerprints?.[state.relative] === state.fingerprint) return 'orphaned';
+  if (state.recordedFingerprint === state.fingerprint) return 'orphaned';
   return 'modified';
 }
 
-function hookTargets(host) {
-  return HOOK_DEFINITIONS.map((definition) => {
-    const target = installedHookPath(host, definition);
-    return {
-      definition,
-      relative: path.relative(host.root, target).split(path.sep).join('/'),
-      spec: { event: definition.event, matcher: definition.matcher, command: commandFor(target) },
-    };
-  });
-}
-
 function recordHasHooks(record, targets) {
   return Boolean(record)
     && targets.every(({ definition, relative }) => record.hooks?.some((hook) =>
-      hook.event === definition.event && hook.path === relative));
+      hook.event === definition.event && hook.root === 'brand' && hook.path === relative));
 }
 
-/**
- * What the run actually did, counted by outcome. `Updated codex-bridge.` alone told the operator
- * nothing about the files that were rewritten or removed on their behalf.
- */
 function appliedOutput(states) {
   const count = (status) => states.filter((state) => state.status === status).length;
   const parts = [
     [count('outdated'), 'updated'],
     [count('new'), 'added'],
     [count('missing'), 'restored'],
-    // A modified orphan is preserved rather than rewritten, so it is not counted here.
     [states.filter((state) => state.status === 'modified' && state.item).length, 'overwritten'],
     [states.filter((state) => state.status === 'orphaned' && state.exists).length, 'removed'],
   ].filter(([total]) => total > 0).map(([total, label]) => `${total} ${label}`);
@@ -81,7 +89,7 @@ function conflictOutput(conflicts, legacy, dryRun) {
   return [heading, ...lines].join('\n');
 }
 
-function dryRunOutput(states, hookStates, legacy) {
+function dryRunOutput(states, hookStates, legacy, oldHooks) {
   const lines = [];
   for (const state of states) {
     if (state.status === 'outdated') lines.push(`Would update ${state.relative}.`);
@@ -91,18 +99,47 @@ function dryRunOutput(states, hookStates, legacy) {
     if (state.status === 'orphaned' && state.exists) lines.push(`Would remove ${state.relative}.`);
     if (state.status === 'modified' && !state.item) lines.push(`Would preserve modified orphan ${state.relative}.`);
   }
+  // previousHooks() returns {hook, definition, spec}, and reading .event off that wrapper printed
+  // "the previous undefined hook registration" five times during the Plan_25 migration — the one
+  // dry run where the operator most needed to see which registrations were about to be taken away.
+  oldHooks.forEach(({ hook, definition }) => lines.push(
+    `Would remove the previous ${hook.event} hook registration for matcher ${definition.matcher}.`,
+  ));
   hookStates.forEach(({ state, target }) => {
-    const { definition } = target;
-    if (!state.present) lines.push(`Would register ${definition.event} hook for matcher ${definition.matcher}.`);
+    const { definition, registration } = target;
+    if (!state.present) {
+      lines.push(`Would register ${definition.event} hook for matcher ${definition.matcher} with ${registration.form} command.`);
+    }
   });
-  lines.push('Would write installation record with new fingerprints.');
+  lines.push('Would write installation record with new fingerprints in both roots.');
   if (legacy && states.some((state) => state.status === 'modified')) {
     lines.push('Installation record has no fingerprints; differing files are treated as modified.');
   }
   return lines.join('\n');
 }
 
-export async function update({ host, dryRun = false, force = false, packageRoot } = {}) {
+function previousHooks(host, record, targets) {
+  return record.hooks.filter((hook) => {
+    const current = targets.find(({ definition, relative }) =>
+      definition.event === hook.event && hook.root === 'brand' && relative === hook.path);
+    return !current;
+  }).map((hook) => {
+    const definition = definitionForRecordedHook(hook);
+    const target = recordTarget(host, hook);
+    return {
+      hook,
+      definition,
+      spec: {
+        event: hook.event,
+        matcher: definition.matcher,
+        command: hook.command || commandFor(target),
+        alternateCommands: [commandFor(target), `codex-bridge hook ${definition.name}`],
+      },
+    };
+  });
+}
+
+async function updateInRun({ host, dryRun = false, force = false, packageRoot, env = process.env } = {}) {
   await readRulesRegistry(host);
   const record = await readInstallRecord(host);
   if (!record) {
@@ -111,20 +148,20 @@ export async function update({ host, dryRun = false, force = false, packageRoot
 
   const plan = await buildInstallPlan(host, packageRoot);
   const rule = { ...rulesPlan(host, packageRoot), processing: 'copy' };
-  const planned = new Map(plan.map((item) => [item.relativeToHost, item]));
+  const planned = new Map(plan.map((item) => [recordFileKey(item), item]));
   const plannedStates = await Promise.all(plan.map(async (item) => {
-    const relative = item.relativeToHost;
+    const relative = displayFile(item);
     const targetExists = await exists(item.target);
     const state = {
       relative,
       item,
-      recorded: record.files.includes(relative),
-      recordedFingerprint: record.fingerprints?.[relative],
+      recorded: record.files.some((file) => recordFileKey(file) === recordFileKey(item)),
+      recordedFingerprint: fingerprintFor(record, item),
       exists: targetExists,
-      matchesPackage: targetExists && await targetMatches(item, host.agentsDir),
+      matchesPackage: targetExists && await targetMatches(item, host.brandRoot),
       fingerprint: targetExists ? await fileFingerprint(item.target) : null,
     };
-    return { ...state, status: classifyPlanned(state, record) };
+    return { ...state, status: classifyPlanned(state) };
   }));
   const ruleExists = await exists(rule.target);
   const ruleState = {
@@ -133,22 +170,24 @@ export async function update({ host, dryRun = false, force = false, packageRoot
     recorded: Boolean(record.rules),
     recordedFingerprint: record.rules?.fingerprint,
     exists: ruleExists,
-    matchesPackage: ruleExists && await targetMatches(rule, host.agentsDir),
+    matchesPackage: ruleExists && await targetMatches(rule, host.brandRoot),
     fingerprint: ruleExists ? await fileFingerprint(rule.target) : null,
   };
-  ruleState.status = classifyPlanned(ruleState, record);
+  ruleState.status = classifyPlanned(ruleState);
   const orphanStates = await Promise.all(record.files
-    .filter((relative) => !planned.has(relative))
-    .map(async (relative) => {
-      const target = path.join(host.root, relative);
+    .filter((file) => !planned.has(recordFileKey(file)))
+    .map(async (file) => {
+      const target = recordTarget(host, file);
       const targetExists = await exists(target);
       const state = {
-        relative,
+        relative: displayFile(file),
+        entry: fileEntry(file),
         item: null,
         exists: targetExists,
+        recordedFingerprint: fingerprintFor(record, file),
         fingerprint: targetExists ? await fileFingerprint(target) : null,
       };
-      return { ...state, status: classifyOrphan(state, record) };
+      return { ...state, status: classifyOrphan(state) };
     }));
   const states = [...plannedStates, ruleState, ...orphanStates];
   const conflicts = states.filter((state) => state.status === 'modified' || state.status === 'missing');
@@ -157,29 +196,51 @@ export async function update({ host, dryRun = false, force = false, packageRoot
     return { exitCode: 1, output: conflictOutput(conflicts, legacy, dryRun) };
   }
 
-  const targets = hookTargets(host);
+  const currentPackage = await packageInfo(packageRoot);
+  const targets = hookTargets(host, env, currentPackage.version);
   const inspectedHooks = await Promise.all(targets.map(async (target) => ({
     target,
     state: await inspectHook(host.settingsPath, target.spec),
   })));
-  const currentPackage = await packageInfo(packageRoot);
+  const oldHooks = previousHooks(host, record, targets);
   const recordCurrent = recordMatchesPackage(record, plan, currentPackage,
-    new Map(plannedStates.map((state) => [state.relative, state.fingerprint])),
+    new Map(plannedStates.map((state) => [recordFileKey(state.item), state.fingerprint])),
     { path: rule.target, fingerprint: ruleState.fingerprint });
-  const changed = states.some((state) => state.status !== 'up-to-date');
+  const changed = states.some((state) => state.status !== 'up-to-date') || oldHooks.length > 0;
   if (!changed && inspectedHooks.every(({ state }) => state.present)
     && recordHasHooks(record, targets) && recordCurrent) {
-    if (!dryRun) await addRulesOwner(host);
+    if (!dryRun) {
+      await addRulesOwner(host);
+      // An update that installed the new layout but stopped before retiring the old one used to
+      // land here forever after: everything it compares is current, so it reported "up to date"
+      // while agents/codex sat next to agents/codex-bridge. Retirement is idempotent, so running
+      // it on this path costs nothing when there is nothing left to retire.
+      await retireLegacyLayout(host);
+    }
     return { exitCode: 0, output: 'codex-bridge is up to date' };
   }
   if (dryRun) {
-    return { exitCode: 0, output: dryRunOutput(states, inspectedHooks, legacy) };
+    return { exitCode: 0, output: dryRunOutput(states, inspectedHooks, legacy, oldHooks) };
   }
 
   for (const state of orphanStates) {
-    if (state.status === 'orphaned' && state.exists) await fs.rm(path.join(host.root, state.relative));
+    if (state.status !== 'orphaned' || !state.exists) continue;
+    const target = recordTarget(host, state.entry);
+    await fs.rm(target, { force: true });
+    const boundary = state.entry.root === 'brand' ? host.brandRoot : claudeBoundary(host, target);
+    await removeEmptyParents(target, boundary);
+  }
+  for (const { spec, hook } of oldHooks) {
+    await removeHook(host.settingsPath, spec, { createdGroup: hook.createdGroup === true });
   }
-  const installed = await install({ host, force: true, packageRoot });
+  const installed = await install({ host, force: true, packageRoot, env });
   if (installed.exitCode !== 0) return installed;
+  await retireLegacyLayout(host);
   return { exitCode: 0, output: appliedOutput(states) };
 }
+
+export async function update(options = {}) {
+  const host = options?.host;
+  if (!host?.settingsPath) return updateInRun(options);
+  return withSettingsRun(host.settingsPath, () => updateInRun(options));
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lyupro/codex-bridge",
-  "version": "0.3.1",
-  "description": "Delegate implementation, reconnaissance and code review from Claude Code to the Codex CLI: dispatcher agents, a runner that survives a dropped call, and a verdict that checks the report against the worktree.",
+  "version": "0.5.0",
+  "description": "Claude Code-to-Codex delegation with 5 guards, 603 tests, zero runtime dependencies, and zero build steps.",
   "keywords": [
     "claude-code",
     "codex",

package/scripts/check-file-size.mjs

@@ -13,7 +13,7 @@
  * error mode, 2 internal error (config missing/malformed, or an exclude entry has no
  * matching exclusionRationale).
  *
- * Every exclude entry is classified as either a "pattern" (contains a `*`, sweeps a
+ * Every exclude entry is classified as either a "pattern" (contains a `*`, covers a
  * whole category — e.g. `**\/node_modules/**`) or a "specific path" (no `*`, names one
  * file). Specific paths must carry an exclusionRationale entry; patterns are exempt. This
  * is the structural guard against silently hiding a file in exclude without saying why.
@@ -21,6 +21,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { readJsonFile } from '../src/json-file.mjs';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 export const REPO_ROOT = path.resolve(HERE, '..');
@@ -31,17 +32,14 @@ const VALID_MODES = ['error', 'warning'];
 
 /** Reads and structurally validates .file-size-limit.json. Throws on anything wrong. */
 export async function loadConfig(configPath = CONFIG_PATH) {
-  let raw;
-  try {
-    raw = await fs.readFile(configPath, 'utf8');
-  } catch (err) {
-    throw new Error(`cannot read ${configPath}: ${err.message}`);
-  }
   let parsed;
   try {
-    parsed = JSON.parse(raw);
+    parsed = await readJsonFile(configPath);
   } catch (err) {
-    throw new Error(`${configPath} is not valid JSON: ${err.message}`);
+    if (err.cause) {
+      throw new Error(`${configPath} is not valid JSON: ${err.cause.message}`, { cause: err.cause });
+    }
+    throw new Error(`cannot read ${configPath}: ${err.message}`);
   }
   if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
     throw new Error(`${configPath} must contain a JSON object`);
@@ -69,7 +67,7 @@ export async function loadConfig(configPath = CONFIG_PATH) {
   return parsed;
 }
 
-/** A pattern (contains `*`) sweeps a category; a specific path (no `*`) names one file. */
+/** A pattern (contains `*`) covers a category; a specific path (no `*`) names one file. */
 export function isSpecificExclude(entry) {
   return !entry.includes('*');
 }

package/scripts/isolated-roots.mjs

@@ -0,0 +1,13 @@
+/** Names every root outside the repository that the suite must never run against for real. */
+
+/**
+ * A fixture that does not name a root falls back to one of these variables, so the suite runner
+ * replaces all of them and the isolation test asserts each one. Two incidents put entries here:
+ * `~/.codex` collected a rules file on 2026-08-03, and `~/.lyupro/.codex-bridge` collected a
+ * config, conventions and an obsolete-file fixture on 2026-08-11, where the stray config then
+ * stood in the way of the seeded-file migration the release was about.
+ *
+ * It sits in its own module because the isolation test imports it, and importing the runner would
+ * start a second suite inside the first.
+ */
+export const ISOLATED_ROOTS = Object.freeze(['CODEX_HOME', 'CODEX_BRIDGE_HOME']);

package/scripts/run-tests.mjs

@@ -1,26 +1,36 @@
 /**
- * Runs the test suite with a Codex home of its own.
+ * Runs the test suite with every root it can install into replaced by a throwaway one.
  *
  * The installer writes its execpolicy file under `$CODEX_HOME/rules`, so a test that builds a host
  * without naming a Codex home installs into the real one: on 2026-08-03 the suite dropped
  * `codex-bridge.rules` into the operator's `~/.codex/rules/` and the next run failed on the file it
  * had left behind. Passing the isolation through the one command that starts the suite is what
  * makes it unforgettable — a fixture can omit it, this cannot.
+ *
+ * Plan_25 gave the package a second root outside the repository, and this file was not extended
+ * with it: on 2026-08-11 the suite wrote config.json, conventions.md and a lib/obsolete.txt fixture
+ * straight into the operator's real `~/.lyupro/.codex-bridge/`, where the stray config then stood
+ * in the way of the very migration the release was about. Roots live in one list here so a third
+ * one cannot be added without this file being the place it is declared.
  */
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { ISOLATED_ROOTS } from './isolated-roots.mjs';
 
-const codexHome = fs.mkdtempSync(path.join(os.tmpdir(), 'codex-bridge-test-home-'));
+const created = ISOLATED_ROOTS.map((name) => [
+  name,
+  fs.mkdtempSync(path.join(os.tmpdir(), `codex-bridge-test-${name.toLowerCase()}-`)),
+]);
 const pattern = process.argv[2] || 'tests/**/*.test.mjs';
 
 try {
   const result = spawnSync(process.execPath, ['--test', pattern], {
     stdio: 'inherit',
-    env: { ...process.env, CODEX_HOME: codexHome },
+    env: { ...process.env, ...Object.fromEntries(created) },
   });
   process.exitCode = result.status ?? 1;
 } finally {
-  fs.rmSync(codexHome, { recursive: true, force: true });
+  for (const [, directory] of created) fs.rmSync(directory, { recursive: true, force: true });
 }