@lyupro/codex-bridge 0.3.1 → 0.4.0

package/cli/settings-merge.mjs

@@ -1,9 +1,12 @@
 /** Merges and removes named codex-bridge hooks without disturbing host settings. */
+import { AsyncLocalStorage } from 'node:async_hooks';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
+import { readJsonFileWithRaw } from '../src/json-file.mjs';
 
 const LEGACY_SPEC = { event: 'SubagentStop', matcher: '*' };
+const settingsRuns = new AsyncLocalStorage();
 
 export function commandFor(guardPath) {
   return `node "${path.resolve(guardPath)}"`;
@@ -26,18 +29,13 @@ function normalizeSpec(specOrPath) {
   };
 }
 
-async function readSettings(settingsPath) {
+export async function readSettings(settingsPath) {
   try {
-    const raw = await fs.readFile(settingsPath, 'utf8');
-    try {
-      const parsed = JSON.parse(raw);
-      if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-        throw new Error('top level must be an object');
-      }
-      return { exists: true, raw, settings: parsed };
-    } catch (err) {
-      throw new Error(`cannot parse ${settingsPath}: ${err.message}`);
+    const { raw, value: settings } = await readJsonFileWithRaw(settingsPath);
+    if (!settings || typeof settings !== 'object' || Array.isArray(settings)) {
+      throw new Error(`cannot parse ${settingsPath}: top level must be an object`);
     }
+    return { exists: true, raw, settings };
   } catch (err) {
     if (err.code === 'ENOENT') return { exists: false, raw: null, settings: {} };
     throw err;
@@ -83,9 +81,38 @@ function backupName(settingsPath) {
   return `${settingsPath}.codex-bridge-backup-${stamp}-${randomUUID()}`;
 }
 
+function runKey(settingsPath) {
+  return path.resolve(settingsPath);
+}
+
+/**
+ * A command gets one in-memory backup scope. AsyncLocalStorage keeps concurrent commands separate
+ * in one process, while nested install calls reuse their caller's scope (Plan_24).
+ */
+export async function withSettingsRun(settingsPath, action) {
+  if (typeof action !== 'function') throw new TypeError('settings run action must be a function');
+  const key = runKey(settingsPath);
+  const active = settingsRuns.getStore();
+  if (active?.key === key) return action();
+  return settingsRuns.run({ key, backupTaken: false }, action);
+}
+
+function withMutationRun(settingsPath, action) {
+  const active = settingsRuns.getStore();
+  return active?.key === runKey(settingsPath)
+    ? action()
+    : withSettingsRun(settingsPath, action);
+}
+
 async function atomicWrite(settingsPath, settings, previous) {
   await fs.mkdir(path.dirname(settingsPath), { recursive: true });
-  if (previous.exists) await fs.writeFile(backupName(settingsPath), previous.raw, { flag: 'wx' });
+  const active = settingsRuns.getStore();
+  const ownsScope = active?.key === runKey(settingsPath);
+  const shouldBackup = !ownsScope || !active.backupTaken;
+  if (ownsScope) active.backupTaken = true;
+  if (shouldBackup && previous.exists) {
+    await fs.writeFile(backupName(settingsPath), previous.raw, { flag: 'wx' });
+  }
   const temporary = `${settingsPath}.${randomUUID()}.tmp`;
   try {
     await fs.writeFile(temporary, `${JSON.stringify(settings, null, 2)}\n`, { flag: 'wx' });
@@ -96,42 +123,63 @@ async function atomicWrite(settingsPath, settings, previous) {
   }
 }
 
+/**
+ * Runs a settings mutation through the hook writer's backup and atomic-write boundary.
+ * Plan_22 requires permissions to preserve the same recovery guarantee after the settings merge
+ * incident: a second writer must not grow its own backup or serialization path.
+ */
+export async function updateSettings(settingsPath, edit) {
+  if (typeof edit !== 'function') throw new TypeError('settings edit must be a function');
+  return withMutationRun(settingsPath, async () => {
+    const previous = await readSettings(settingsPath);
+    const settings = structuredClone(previous.settings);
+    const result = await edit(settings);
+    if (!result?.changed) return result || { changed: false };
+    await atomicWrite(settingsPath, settings, previous);
+    return result;
+  });
+}
+
 export async function mergeHook(settingsPath, specOrPath, inspected) {
-  const spec = normalizeSpec(specOrPath);
-  const state = inspected || await inspectHook(settingsPath, spec);
-  if (state.present) return { changed: false, createdGroup: false };
-  const settings = structuredClone(state.settings);
-  settings.hooks ??= {};
-  if (!Array.isArray(settings.hooks[spec.event])) settings.hooks[spec.event] = [];
-  let group = settings.hooks[spec.event].find((entry) => entry?.matcher === spec.matcher);
-  const createdGroup = !group;
-  if (!group) {
-    group = { matcher: spec.matcher, hooks: [] };
-    settings.hooks[spec.event].push(group);
-  }
-  if (!Array.isArray(group.hooks)) group.hooks = [];
-  group.hooks.push(ownHook(spec.command));
-  await atomicWrite(settingsPath, settings, state);
-  return { changed: true, createdGroup };
+  return withMutationRun(settingsPath, async () => {
+    const spec = normalizeSpec(specOrPath);
+    const state = inspected || await inspectHook(settingsPath, spec);
+    if (state.present) return { changed: false, createdGroup: false };
+    const settings = structuredClone(state.settings);
+    settings.hooks ??= {};
+    if (!Array.isArray(settings.hooks[spec.event])) settings.hooks[spec.event] = [];
+    let group = settings.hooks[spec.event].find((entry) => entry?.matcher === spec.matcher);
+    const createdGroup = !group;
+    if (!group) {
+      group = { matcher: spec.matcher, hooks: [] };
+      settings.hooks[spec.event].push(group);
+    }
+    if (!Array.isArray(group.hooks)) group.hooks = [];
+    group.hooks.push(ownHook(spec.command));
+    await atomicWrite(settingsPath, settings, state);
+    return { changed: true, createdGroup };
+  });
 }
 
 export async function removeHook(settingsPath, specOrPath, { createdGroup = false } = {}) {
-  const spec = normalizeSpec(specOrPath);
-  const state = await inspectHook(settingsPath, spec);
-  if (!state.present) return { changed: false };
-  const settings = structuredClone(state.settings);
-  const eventGroups = groups(settings, spec.event);
-  // Removal follows the same rule as the lookup above: our command, whatever matcher it is
-  // filed under. A foreign hook is left alone because its command is not ours, not because it
-  // sits in another group.
-  for (let index = eventGroups.length - 1; index >= 0; index -= 1) {
-    const group = eventGroups[index];
-    if (!hasOwnCommand(group, spec.command)) continue;
-    if (!Array.isArray(group?.hooks)) continue;
-    group.hooks = group.hooks.filter((hook) =>
-      !(hook?.type === 'command' && hook.command === spec.command));
-    if (createdGroup && group.hooks.length === 0) eventGroups.splice(index, 1);
-  }
-  await atomicWrite(settingsPath, settings, state);
-  return { changed: true };
+  return withMutationRun(settingsPath, async () => {
+    const spec = normalizeSpec(specOrPath);
+    const state = await inspectHook(settingsPath, spec);
+    if (!state.present) return { changed: false };
+    const settings = structuredClone(state.settings);
+    const eventGroups = groups(settings, spec.event);
+    // Removal follows the same rule as the lookup above: our command, whatever matcher it is
+    // filed under. A foreign hook is left alone because its command is not ours, not because it
+    // sits in another group.
+    for (let index = eventGroups.length - 1; index >= 0; index -= 1) {
+      const group = eventGroups[index];
+      if (!hasOwnCommand(group, spec.command)) continue;
+      if (!Array.isArray(group?.hooks)) continue;
+      group.hooks = group.hooks.filter((hook) =>
+        !(hook?.type === 'command' && hook.command === spec.command));
+      if (createdGroup && group.hooks.length === 0) eventGroups.splice(index, 1);
+    }
+    await atomicWrite(settingsPath, settings, state);
+    return { changed: true };
+  });
 }

package/cli/stop.mjs

@@ -1,7 +1,14 @@
-/** Stops a live run and records the same abandoned FAIL artifacts as the normal sweep. */
+/** Stops a live run and records the same abandoned FAIL artifacts as the normal unlock. */
 import path from 'node:path';
 import { stopCodex } from '../src/runner/codex-cmd.mjs';
 import { git, worktreeSnapshot } from '../src/runner/git-state.mjs';
+import {
+  IDENTITY_ALIVE,
+  IDENTITY_FOREIGN,
+  IDENTITY_UNVERIFIED,
+  processAlive,
+  processIdentity,
+} from '../src/process-identity.mjs';
 import { markAbandoned, readJson } from '../src/write-meta.mjs';
 import { runsRoot } from '../src/runner/runs-root.mjs';
 import { resolveRunFolder } from './run-lookup.mjs';
@@ -32,27 +39,22 @@ function processHandle(pid) {
   };
 }
 
-function alive(pid) {
-  if (!Number.isInteger(pid) || pid <= 0) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    return err.code === 'EPERM';
-  }
-}
-
 async function waitForExit(pid) {
   const deadline = Date.now() + EXIT_WAIT_MS;
-  while (alive(pid) && Date.now() < deadline) await sleep(EXIT_POLL_MS);
-  return !alive(pid);
+  while (processAlive(pid) && Date.now() < deadline) await sleep(EXIT_POLL_MS);
+  return !processAlive(pid);
 }
 
 function result(exitCode, output) {
   return { exitCode, output };
 }
 
-export async function stop({ run, cwd = process.cwd(), runsRootPath = runsRoot() } = {}) {
+export async function stop({
+  run,
+  cwd = process.cwd(),
+  runsRootPath = runsRoot(),
+  commandRunner,
+} = {}) {
   const lookup = resolveRunFolder({ command: 'stop', run, cwd, runsRootPath });
   if (lookup.error) return result(1, lookup.error);
   const { runDir } = lookup;
@@ -70,13 +72,24 @@ export async function stop({ run, cwd = process.cwd(), runsRootPath = runsRoot()
     return result(1, `Run ${runDir} has no valid recorded pid; it was not changed.`);
   }
 
-  try {
-    stopCodex(processHandle(status.pid));
-    if (!(await waitForExit(status.pid))) {
-      return result(1, `Run ${runDir} did not stop within ${EXIT_WAIT_MS}ms; it was not closed.`);
+  const identity = processIdentity({ runDir, status, commandRunner });
+  if (identity === IDENTITY_UNVERIFIED || identity === IDENTITY_FOREIGN) {
+    return result(
+      1,
+      `Process identity could not be confirmed for run ${runDir} (${identity}); no signal was sent. ` +
+        '"codex-bridge unlock" closes the record without killing a process.',
+    );
+  }
+
+  if (identity === IDENTITY_ALIVE) {
+    try {
+      stopCodex(processHandle(status.pid));
+      if (!(await waitForExit(status.pid))) {
+        return result(1, `Run ${runDir} did not stop within ${EXIT_WAIT_MS}ms; it was not closed.`);
+      }
+    } catch (err) {
+      return result(1, `Could not stop run ${runDir}: ${err.message}; it was not closed.`);
     }
-  } catch (err) {
-    return result(1, `Could not stop run ${runDir}: ${err.message}; it was not closed.`);
   }
 
   // The snapshot is what turns the verdict from a bare label into a list of what the stopped run

package/cli/uninstall.mjs

@@ -2,12 +2,13 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import {
+  definitionForRecordedHook,
   fileFingerprint,
-  HOOK_DEFINITIONS,
   installRecordPath,
   readInstallRecord,
 } from './manifest.mjs';
-import { commandFor, removeHook } from './settings-merge.mjs';
+import { removePermissionRules } from './permissions.mjs';
+import { commandFor, removeHook, withSettingsRun } from './settings-merge.mjs';
 import { readRulesRegistry, removeRulesOwner, remainingRulesOwners } from './rules-owners.mjs';
 
 async function removeEmpty(directory) {
@@ -30,11 +31,13 @@ function remainingOwnersText(count) {
   return `${count} other owner${count === 1 ? '' : 's'} ${count === 1 ? 'remains' : 'remain'}`;
 }
 
-function hookDefinition(event) {
-  return HOOK_DEFINITIONS.find((definition) => definition.event === event);
+function permissionOutput(host, removed, dryRun) {
+  const verb = dryRun ? 'Would remove' : 'Removed';
+  const plural = removed === 1 ? 'string' : 'strings';
+  return `${verb} ${removed} permission rule ${plural} from ${host.settingsPath}.`;
 }
 
-export async function uninstall({ host, dryRun = false } = {}) {
+async function uninstallInRun({ host, dryRun = false } = {}) {
   // Preflight before removing the hook: package removal on a broken registry left the host without its watchdog.
   let registry = null;
   let registryError = null;
@@ -43,13 +46,17 @@ export async function uninstall({ host, dryRun = false } = {}) {
   } catch (err) {
     registryError = err;
   }
+  const permissionResult = await removePermissionRules(host.settingsPath, { dryRun });
+  const permissionLine = permissionOutput(host, permissionResult.removed, dryRun);
   const record = await readInstallRecord(host);
   const preservation = `Run artifacts in ${path.join(host.root, 'codex-runs')} and the run `
     + `configuration in ${path.join(host.agentsDir, 'run-config.json')} are preserved.`;
-  if (!record) return { exitCode: 1, output: `codex-bridge is not installed.\n${preservation}` };
+  if (!record) {
+    return { exitCode: 1, output: `${permissionLine}\ncodex-bridge is not installed.\n${preservation}` };
+  }
 
   if (dryRun) {
-    const lines = record.files.map((file) => `Would remove ${file}`);
+    const lines = [permissionLine, ...record.files.map((file) => `Would remove ${file}`)];
     if (record.rules) {
       if (registryError) {
         lines.push(`Would leave ${record.rules.path} because the rules ownership registry is invalid; ownership is unknown.`);
@@ -71,7 +78,7 @@ export async function uninstall({ host, dryRun = false } = {}) {
       }
     }
     for (const hook of record.hooks) {
-      const definition = hookDefinition(hook.event);
+      const definition = definitionForRecordedHook(hook);
       lines.push(`Would remove the ${hook.event} hook for matcher ${definition.matcher}.`);
     }
     lines.push('Would remove the installation record.');
@@ -80,7 +87,7 @@ export async function uninstall({ host, dryRun = false } = {}) {
   }
 
   for (const hook of record.hooks) {
-    const definition = hookDefinition(hook.event);
+    const definition = definitionForRecordedHook(hook);
     const target = path.join(host.root, hook.path);
     await removeHook(host.settingsPath, {
       event: hook.event,
@@ -127,6 +134,12 @@ export async function uninstall({ host, dryRun = false } = {}) {
   await removeEmpty(host.agentsDir);
   return {
     exitCode: 0,
-    output: [`Uninstalled codex-bridge.`, ...rulesOutput, preservation].join('\n'),
+    output: [`Uninstalled codex-bridge.`, permissionLine, ...rulesOutput, preservation].join('\n'),
   };
 }
+
+export async function uninstall(options = {}) {
+  const host = options?.host;
+  if (!host?.settingsPath) return uninstallInRun(options);
+  return withSettingsRun(host.settingsPath, () => uninstallInRun(options));
+}

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lyupro/codex-bridge",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "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.",
   "keywords": [
     "claude-code",

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/src/agents/codex-build.md

@@ -28,6 +28,8 @@ job is to report the run status honestly, including failure.
 
 - The task statement: what to change and the completion criteria.
 - The path to the repository. If none is given, use the current working directory.
+- Scope patterns are globs relative to the repository root. A pattern that matches nothing there is
+  refused before the run starts; a file this task is meant to create is declared with `--scope-new`.
 - Every input listed under **Required dispatcher inputs** above, passed on exactly as given:
   `order id` as `--order-id`, `scope` as `--scope`. Never invent a value, never edit one, never
   reuse an order id from another order — the runner chains runs by that label, and a made-up label

package/src/agents/codex-review.md

@@ -27,6 +27,8 @@ opinion, not a verdict.
   - branch against base — `--mode base:<branch>`;
   - specific commit — `--mode commit:<sha>`.
 - The path to the repository. If none is given, use the current working directory.
+- Scope patterns are globs relative to the repository root. A pattern that matches nothing there is
+  refused before the run starts.
 - Every input listed under **Required dispatcher inputs** above, passed on exactly as given:
   `order id` as `--order-id`. Never invent a value, never edit one, never reuse an order id from
   another order — the runner chains runs by that label, and a made-up label is how a repeat run

package/src/agents/codex-scout.md

@@ -23,6 +23,8 @@ files, do not run grep, do not retell the report, and do not reason about the ta
 
 - The task statement (what to find out / what to diagnose / what to review).
 - The path to the repository. If none is given, work in the current working directory.
+- Scope patterns are globs relative to the repository root. A pattern that matches nothing there is
+  refused before the run starts.
 - Optional: `effort: <none|minimal|low|medium|high|xhigh|max>` — Codex reasoning depth.
 - Optional: `slug: <short-name>` for the run folder.
 - Every input listed under **Required dispatcher inputs** above, passed on exactly as given: