@lyupro/codex-bridge 0.1.4 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,54 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-08-07
+
+### Added
+
+- `codex-bridge sweep [<project>]` closes running records whose runner pid is dead, across the whole store or one project. It changes state but deletes no run folder or transport, never touches a live pid, and lists every stalled-but-live run with the exact `codex-bridge stop <run>` line that ends it. A dead record can therefore be cleared without paying for another run, while a live worker remains the sole writer until `stop` kills it first.
+- Every new run folder carries a `heartbeat` file, and `status.json` carries `stdio_drained`. The heartbeat records movement from Codex output and the still-running child rather than a timer that would keep an orphan alive; `stdio_drained` says whether stdout/stderr closed normally or the bounded drain grace had to end the run.
+
+### Changed
+
+- Hook liveness now requires `state: running`, a live runner pid and a heartbeat no older than five minutes. A stalled run therefore stops holding the worktree lock instead of holding it until the deadline; the refusal that remains — always about a working run — says how long ago it last made progress and prints `codex-bridge stop <run>` for taking the repository back early. Record cleanup and the second-writing-run check still judge by pid alone, so a stale but live run is released to the operator, not closed underneath its worker.
+- The worker closes a run after `exit` with a bounded 30-second grace for stdio drain instead of waiting for `close`, which a grandchild can hold open forever. Healthy runs keep the event tail that carries their result and record `stdio_drained: true`; only the fallback records `false`.
+- The three dispatcher prompts now open with one shared no-self-execution block rendered through `{{CODEX_NO_SELF_EXECUTION}}`. If `run-codex.mjs` does not start a run, the dispatcher must return `FAIL` and stop, and a reply with no run folder is blocked by the guard. The installed prompts change only when the host runs `codex-bridge update`; a host that does not update keeps the old prompts.
+
+### Fixed
+
+- A dispatcher that cannot start Codex can no longer read the code, write the files or fix the tests itself and claim a result. The guard also rejects a made-up reply with no `RUN=` or `ATTACH=` behind it: no run, no result.
+
+## [0.2.0] - 2026-08-06
+
+### Added
+
+- `codex-bridge projects` gives the run store a way to look at itself: one line per project — runs, weight, tokens spent, how many are running right now, when the last one started — and one line per run under a project name, plus `--json` for scripts. The store had grown to 12 projects, 152 runs and 80 MB with no command that could answer "what has Codex been working on"; the only way in was a file manager. The count of live runs is computed by the same module the reply guard and the worktree lock use, because a second detector of a live run sitting next to the first would drift from it silently.
+- `codex-bridge prune` reclaims that space, and it is built to be hard to fire by accident: without `-f` it prints a plan and deletes nothing, `-f` still asks before each step, and with no terminal it refuses outright — deletion is an operator action, and the bypass flag that would undo this is deliberately absent. A gentle prune removes transport only (event streams, stderr, the archived `raw.log` of older runs) and leaves accounting, reports and worktree snapshots in place, so a task can still be continued and still be read after its megabytes are gone; `--purge` is what takes a folder whole, and it is refused together with `--all-projects`, because deleting a dozen projects with one command has no second line of defence. A live run is never a target — it is recognised by its process, not by a status file, since the file that would be deleted is the verdict being written right now.
+- Run transport is dropped automatically from runs older than 30 days when a new run starts, and the dispatcher's reply says how much was freed: a rare event that goes unexplained sends someone looking for a fault. Automatic cleanup can only shed weight — the code to remove `meta.json` or a folder does not exist on that path at all, so it cannot be switched on by mistake — and `retention` in `run-config.json` changes the age or turns it off. Both `install` and `doctor` say out loud that it is on, because an installer that quietly starts deleting files is a surprise, not a convenience.
+- A fourth hook refuses `codex-bridge prune` in an agent's shell command before the deleting process exists. Mentioning the command is not calling it: heredoc bodies and quoted text are stripped before the check, after the guard rejected the very commit that introduced it over a command name in the message. `git prune` and `npm prune` are left alone — a guard that breaks unrelated work is a guard that gets removed, and then it protects nothing.
+- `codex-bridge read <run>` renders a run's events as text on demand. Readability is now something the package produces when asked rather than a file it keeps, and a rendering that is not stored cannot disagree with the facts.
+
+### Changed
+
+- Runs go through `codex exec --json`, and `events.jsonl` is the single source of the quota signal, the token count, the session id and the failure reason. The stream is written by the CLI, not by the model, so a quotation out of a source file can no longer reach it. `tokens` is input plus output with the CLI's whole `usage` object beside it, and `session_id` comes from `thread.started` instead of a line matched in a log.
+- The reason for a `FAIL` is taken from the run's own error event rather than from `stderr.log`. A live probe showed `stderr.log` is not empty even for a clean run — 488 bytes of execpolicy refusals, repository paths included — which made the reason a random blocked call instead of the real one. The transport branch keeps the reason the CLI itself gave with its status code: a `LIMIT` whose reason does not mention the quota is the same class of defect.
+- A run that never began is one with no events *and* no stderr. Stderr with no events is a CLI that did not understand a flag — a different diagnosis, calling for a different action, and the two no longer collapse into one.
+- `log_bytes` in `meta.json` is replaced by `events_bytes` and `stderr_bytes`.
+
+### Removed
+
+- `raw.log` is gone. Under `--json` it would have been a byte-for-byte copy of `events.jsonl` — a second source of truth with no role of its own — and the package already declared it ephemeral and safe to delete while resting the "abandoned at start" verdict on it. An artifact one is allowed to remove cannot be the ground of a verdict.
+- The text detector of the quota signal is removed entirely rather than kept as a fallback. While the regular expressions live, so does the class of defect they caused.
+
+### Fixed
+
+- `LIMIT` is set only by an error event from the CLI carrying `status: 429` or an error type naming the limit. A `codex-build` run that had finished its work grepped the package's own test fixtures, printed a line where `ERROR` and `rate limit` stand together, and was closed as quota-exhausted — the work was complete and the suite was green, and the verdict threw it away.
+- A run killed by its time budget says so. It records `stopped_on_deadline` and answers `FAIL — run stopped on its deadline`, instead of inventing a reason out of whatever text was nearest.
+- A log file that cannot be written no longer leaves Codex orphaned. An unhandled stream error used to kill the worker while the CLI kept burning quota with nothing left to close it; now either stream failing takes down the process tree, so the run dies with its process rather than instead of it.
+- A run that exited honestly is no longer marked as killed by its deadline. The timer judged by `close`, which a grandchild process can hold open long after the run is over; it now watches `exit`.
+- A verdict is never shortened to fit the terminal. In a narrow window `running` was printed as `…nning`, which reads as a damaged run rather than one still in flight; a verdict is one word from a known set, like a number or a date, and the run name is what a narrow table gives up instead.
+- The CLI's own warnings are no longer read as the model's complaint about the order. `codex-cli` announces a deprecated configuration key through the same event shape the model uses for a content error, before the turn even opens — so a failed run on such a host would have answered "`[features].codex_hooks` is deprecated" when asked why it failed. Only events after the first `turn.started` are the model's; a complaint about the order cannot predate the model's first thought.
+
 ## [0.1.4] - 2026-08-05
 
 ### Added

package/README.md

@@ -14,11 +14,14 @@ node bin/codex-bridge.mjs update        # bring an installation up to the curren
 node bin/codex-bridge.mjs doctor        # what is installed, where it points, is codex alive
 node bin/codex-bridge.mjs uninstall     # removes exactly what was installed
 node bin/codex-bridge.mjs stop <run>    # close a hanging run by hand, without hunting for a pid
+node bin/codex-bridge.mjs read <run>   # read a run: its events rendered as text, on demand
+node bin/codex-bridge.mjs projects     # what the run store holds: projects, runs, weight, tokens
+node bin/codex-bridge.mjs prune <project>   # reclaim disk space, transport only unless told otherwise
+node bin/codex-bridge.mjs sweep [<project>] # close running records whose runner is gone
 ```
 
 `install` copies the package into the host's `agents/codex/`, its slash commands into
-`commands/codex/`, and registers both the stop hook and the pre-dispatch order gate in
-`settings.json` — **merged**, so hooks that
+`commands/codex/`, and registers its four hooks in `settings.json` — **merged**, so hooks that
 are already there survive, and the file is backed up before every write. Run it twice and the
 second run does nothing. `--dry-run` prints the plan and touches nothing.
 
@@ -42,6 +45,22 @@ Run artifacts live in `codex-runs/<project>/`, one folder per repository, marked
 different `api` — therefore get `api` and `api-2` instead of one mixed history. `doctor` prints
 which folder the current repository writes to.
 
+`projects` reads that store back: without an argument, one line per project — runs, weight, tokens
+spent, how many are running right now; with a project name, one line per run. `prune` is the only
+command in the package that destroys data, and it is built to be hard to fire by accident: without
+`-f` it prints a plan and deletes nothing, `-f` still asks before each step, and with no terminal
+it refuses outright, because deletion is an operator action and there is no flag around it.
+By default it removes transport only — event streams and stderr, the megabytes — and leaves
+accounting, reports and worktree snapshots alone; `--purge` is what takes a folder whole.
+The same transport is dropped automatically from runs older than 30 days when a new run starts,
+which the reply says out loud; `retention` in `run-config.json` changes the age or turns it off.
+
+`sweep` is housekeeping for records left by a dead runner. With no project it scans the whole
+store; with one project it limits the scan to that folder. It uses the same dead-pid decision as
+start-of-run cleanup, never closes a live pid even when its heartbeat is stale, and never deletes
+run artifacts. A stale live-pid record is named with the exact `codex-bridge stop <run>` command
+needed to close it.
+
 ## What it gives you
 
 - **Three dispatcher agents** for Claude Code — reconnaissance (read-only), implementation
@@ -52,8 +71,10 @@ which folder the current repository writes to.
 - **A verdict that checks the report against the worktree.** The agent's own account of what
   it changed is compared with what git says actually changed, and a mismatch is a failed run
   rather than a nicer-sounding summary.
-- **A stop hook** that refuses a dispatcher reply which does not match the recorded state of
-  the run.
+- **Four hooks that hold the rules the prompts only ask for**: a reply is refused when it does not
+  match the recorded state of the run, a dispatcher call is refused when it carries no order id, a
+  file edit is refused inside a repository a live run holds, and deletion of the run store is
+  refused when an agent is the one asking.
 
 ## Requirements
 

package/bin/codex-bridge.mjs

@@ -5,8 +5,12 @@ import { fileURLToPath } from 'node:url';
 import { diagnose, renderDoctor } from '../cli/doctor.mjs';
 import { resolveHost } from '../cli/hosts.mjs';
 import { install } from '../cli/install.mjs';
+import { projects } from '../cli/projects.mjs';
+import { read } from '../cli/read.mjs';
 import { packageInfo } from '../cli/manifest.mjs';
+import { prune } from '../cli/prune.mjs';
 import { stop } from '../cli/stop.mjs';
+import { sweep } from '../cli/sweep.mjs';
 import { uninstall } from '../cli/uninstall.mjs';
 import { update } from '../cli/update.mjs';
 
@@ -17,6 +21,11 @@ Usage:
   codex-bridge update [--scope user|project] [--host <path>] [--dry-run] [--force]
   codex-bridge uninstall [--scope user|project] [--host <path>] [--dry-run]
   codex-bridge doctor [--scope user|project] [--host <path>]
+  codex-bridge projects [<name>] [--json]
+  codex-bridge prune <project> [<run>] [--purge] [--older-than <age>] [-f] [--json]
+  codex-bridge prune --all-projects [--older-than <age>] [-f] [--json]
+  codex-bridge sweep [<project>]
+  codex-bridge read <run>
   codex-bridge stop <run>
   codex-bridge --help
   codex-bridge --version
@@ -26,6 +35,10 @@ Commands:
   update    Update a recorded codex-bridge installation
   uninstall Remove installed files while preserving run artifacts
   doctor    Diagnose the selected Claude Code host
+  projects  List projects or runs from the run store
+  prune     Remove archived transport, or purge selected run folders
+  sweep     Close running records whose runner is gone
+  read      Render a run's structured event stream
   stop      Stop a running Codex run and record FAIL`;
 
 function commandOptions(command, argv) {
@@ -76,6 +89,30 @@ export async function main(argv, io = console) {
     io.log(result.output);
     return result.exitCode;
   }
+  if (command === 'read') {
+    if (rest.length !== 1) {
+      io.error('codex-bridge read requires exactly one run folder (full path or bare name).');
+      return 2;
+    }
+    const result = read({ run: rest[0] });
+    io.log(result.output);
+    return result.exitCode;
+  }
+  if (command === 'projects') {
+    const result = projects(rest);
+    io.log(result.output);
+    return result.exitCode;
+  }
+  if (command === 'prune') {
+    const result = await prune(rest);
+    io.log(result.output);
+    return result.exitCode;
+  }
+  if (command === 'sweep') {
+    const result = sweep(rest);
+    io.log(result.output);
+    return result.exitCode;
+  }
   if (command === 'install' || command === 'update' || command === 'uninstall') {
     const options = commandOptions(command, rest);
     const host = resolveHost(options);

package/cli/doctor.mjs

@@ -10,9 +10,13 @@ import {
 } from './manifest.mjs';
 import { commandFor, inspectHook } from './settings-merge.mjs';
 import { readRulesRegistry } from './rules-owners.mjs';
+import { readRunConfig, retentionNotice } from '../src/run-config.mjs';
 import { runsRoot } from '../src/runner/runs-root.mjs';
 import { resolveProjectRunsDir } from '../src/runner/project-dir.mjs';
 
+const WARNING = '\u001b[33m';
+const RESET = '\u001b[0m';
+
 async function exists(target) {
   try {
     await fs.access(target);
@@ -34,6 +38,15 @@ function check(key, status, value) {
   return { key, status, value };
 }
 
+function retentionCheck(host) {
+  try {
+    const notice = retentionNotice(readRunConfig(path.join(host.agentsDir, 'run-config.json')));
+    return check('retention', notice.enabled ? 'warn' : 'ok', notice.text);
+  } catch (err) {
+    return check('retention', 'fail', `invalid configuration: ${err.message}`);
+  }
+}
+
 /**
  * The runner asks git for the repository root before it picks a runs folder, so doctor has to
  * ask the same question: run from `src/runner`, a plain cwd would name the folder `runner` and
@@ -158,6 +171,8 @@ export async function diagnose({ host, codexProbe = probeCodex, currentPackage }
   const rules = await rulesCheck(host, record);
   checks.push(rules);
   checks.push(...await hookChecks(host, record));
+  const retention = retentionCheck(host);
+  checks.push(retention);
 
   const codex = codexProbe();
   checks.push(check('codex', codex.available ? 'ok' : 'warn', codex.value || 'available'));
@@ -169,7 +184,7 @@ export async function diagnose({ host, codexProbe = probeCodex, currentPackage }
 
   return {
     exitCode: !record || recordBroken || missingFiles.length || rules.status === 'fail'
-      || projectRuns.status === 'fail' ? 1 : 0,
+      || retention.status === 'fail' || projectRuns.status === 'fail' ? 1 : 0,
     checks,
     record,
     missingFiles,
@@ -177,5 +192,8 @@ export async function diagnose({ host, codexProbe = probeCodex, currentPackage }
 }
 
 export function renderDoctor(result) {
-  return result.checks.map(({ key, status, value }) => `[${status}] ${key}: ${value}`).join('\n');
+  return result.checks.map(({ key, status, value }) => {
+    const rendered = `[${status}] ${key}: ${value}`;
+    return key === 'retention' && status === 'warn' ? `${WARNING}${rendered}${RESET}` : rendered;
+  }).join('\n');
 }

package/cli/install.mjs

@@ -16,6 +16,10 @@ import {
 import { copyPlannedFile, targetMatches } from './copy.mjs';
 import { commandFor, inspectHook, mergeHook } from './settings-merge.mjs';
 import { addRulesOwner, readRulesRegistry } from './rules-owners.mjs';
+import { readRunConfig, retentionNotice } from '../src/run-config.mjs';
+
+const WARNING = '\u001b[33m';
+const RESET = '\u001b[0m';
 
 async function targetExists(target) {
   try {
@@ -45,9 +49,19 @@ function recordHasHooks(record, targets) {
       hook.event === definition.event && hook.path === relative));
 }
 
+function retentionLine(host) {
+  const notice = retentionNotice(readRunConfig(path.join(host.agentsDir, 'run-config.json')));
+  return notice.enabled ? `${WARNING}${notice.text}${RESET}` : notice.text;
+}
+
+function retentionOutput(line, output) {
+  return `${output}\n${line}`;
+}
+
 export async function install({ host, dryRun = false, force = false, packageRoot } = {}) {
   // Validate the shared registry before writes; package removal on a broken registry left the host without its watchdog.
   await readRulesRegistry(host);
+  const configuredRetentionLine = retentionLine(host);
   const plan = await buildInstallPlan(host, packageRoot);
   const rule = { ...rulesPlan(host, packageRoot), processing: 'copy' };
   const currentPackage = await packageInfo(packageRoot);
@@ -83,7 +97,7 @@ export async function install({ host, dryRun = false, force = false, packageRoot
     const files = conflicts.map(({ item }) => `  ${item.relativeToHost || item.name}`).join('\n');
     return {
       exitCode: 1,
-      output: `Conflicting files:\n${files}\nRun install again with --force to overwrite them.`,
+      output: retentionOutput(configuredRetentionLine, `Conflicting files:\n${files}\nRun install again with --force to overwrite them.`),
     };
   }
 
@@ -95,7 +109,7 @@ export async function install({ host, dryRun = false, force = false, packageRoot
   if (!changedFiles.length && !changedRule && inspectedHooks.every((state) => state.present)
     && recordHasHooks(record, targets) && sameRecord) {
     if (!dryRun) await addRulesOwner(host);
-    return { exitCode: 0, output: 'codex-bridge is already installed; nothing to do.' };
+    return { exitCode: 0, output: retentionOutput(configuredRetentionLine, 'codex-bridge is already installed; nothing to do.') };
   }
 
   if (dryRun) {
@@ -111,7 +125,7 @@ export async function install({ host, dryRun = false, force = false, packageRoot
         : `Would register ${definition.event} hook for matcher ${definition.matcher}.`);
     });
     lines.push('Would write installation record.');
-    return { exitCode: 0, output: lines.join('\n') };
+    return { exitCode: 0, output: retentionOutput(configuredRetentionLine, lines.join('\n')) };
   }
 
   // Claim ownership of the shared rules file before writing anything. Claiming it last meant a
@@ -146,6 +160,6 @@ export async function install({ host, dryRun = false, force = false, packageRoot
   });
   return {
     exitCode: 0,
-    output: `Installed ${plan.length + 1} files and registered the ${targets.map(({ definition }) => definition.event).join(' and ')} hooks.`,
+    output: retentionOutput(configuredRetentionLine, `Installed ${plan.length + 1} files and registered the ${targets.map(({ definition }) => definition.event).join(' and ')} hooks.`),
   };
 }

package/cli/manifest.mjs

@@ -10,6 +10,7 @@ import {
   renderRequiredInputSummary,
   renderRequiredInputs,
 } from '../src/required-inputs.mjs';
+import { renderNoSelfExecution } from '../src/no-self-execution.mjs';
 
 export { HOOK_DEFINITIONS };
 
@@ -42,7 +43,8 @@ export function replacePlaceholders(content, agentsDir) {
   return content
     .replaceAll('{{CODEX_BRIDGE_DIR}}', posix(path.resolve(agentsDir)))
     .replaceAll('{{CODEX_REQUIRED_INPUTS_SUMMARY}}', renderRequiredInputSummary(agentType))
-    .replaceAll('{{CODEX_REQUIRED_INPUTS}}', renderRequiredInputs(agentType));
+    .replaceAll('{{CODEX_REQUIRED_INPUTS}}', renderRequiredInputs(agentType))
+    .replaceAll('{{CODEX_NO_SELF_EXECUTION}}', renderNoSelfExecution());
 }
 
 export async function packageInfo(packageRoot = PACKAGE_ROOT) {

package/cli/projects.mjs

@@ -0,0 +1,92 @@
+/** Implements the projects command. */
+import { listProjectRuns, listProjects } from './runs-inventory.mjs';
+import { renderTable } from './table.mjs';
+
+// The table renders whatever it is given; how a byte count or a timestamp reads is this command's
+// business. Raw bytes and ISO milliseconds are technically exact and practically unreadable — an
+// inventory exists to be scanned by eye, and 8468429 has to be counted digit by digit.
+const SIZE_UNITS = [['GB', 1024 ** 3], ['MB', 1024 ** 2], ['KB', 1024]];
+
+function formatSize(bytes) {
+  if (typeof bytes !== 'number' || !Number.isFinite(bytes)) return null;
+  for (const [unit, scale] of SIZE_UNITS) {
+    if (bytes >= scale) return `${(bytes / scale).toFixed(bytes >= 10 * scale ? 0 : 1)} ${unit}`;
+  }
+  return `${bytes} B`;
+}
+
+/** Both timestamp shapes in the store: an ISO stamp from artifacts, a folder name otherwise. */
+function formatStamp(value) {
+  if (typeof value !== 'string' || !value.trim()) return null;
+  const iso = /^(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2})/.exec(value);
+  if (iso) return `${iso[1]} ${iso[2]}`;
+  const folder = /^(\d{4}-\d{2}-\d{2})_(\d{2})(\d{2})/.exec(value);
+  return folder ? `${folder[1]} ${folder[2]}:${folder[3]}` : value;
+}
+
+const PROJECT_COLUMNS = [
+  { key: 'project', header: 'project', truncate: 'start' },
+  { key: 'runs', header: 'runs', kind: 'number' },
+  { key: 'size', header: 'size', kind: 'number', value: (row) => formatSize(row.size) },
+  { key: 'totalTokens', header: 'total tokens', kind: 'number' },
+  { key: 'liveNow', header: 'live now', kind: 'number' },
+  { key: 'lastRun', header: 'last run', kind: 'date', value: (row) => formatStamp(row.lastRun) },
+];
+
+// The verdict is never shortened, for the same reason numbers and dates are not: it is one whole
+// word from a known set, and half of it is not half an answer. A narrow terminal turned `running`
+// into `…nning`, which reads as damage rather than as a run in flight. The agent column keeps the
+// tail because that is exactly what tells `codex-build` from `codex-scout`.
+const RUN_COLUMNS = [
+  { key: 'run', header: 'run', truncate: 'start' },
+  { key: 'agent', header: 'agent', truncate: 'start' },
+  { key: 'verdict', header: 'verdict', fixed: true },
+  { key: 'tokens', header: 'tokens', kind: 'number' },
+  { key: 'size', header: 'size', kind: 'number', value: (row) => formatSize(row.size) },
+];
+
+function parseArgs(args) {
+  const positional = [];
+  let json = false;
+  for (const arg of args) {
+    if (arg === '--json') {
+      json = true;
+      continue;
+    }
+    if (arg.startsWith('-')) return { error: `codex-bridge projects: unknown option "${arg}"` };
+    positional.push(arg);
+  }
+  if (positional.length > 1) {
+    return { error: 'codex-bridge projects accepts at most one project name.' };
+  }
+  return { json, projectName: positional[0] || null };
+}
+
+function output(rows, columns, options) {
+  if (options.json) return JSON.stringify(rows, null, 2);
+  return renderTable(columns, rows, options.terminalWidth);
+}
+
+/** Lists projects or runs for one project. */
+export function projects(argv = [], options = {}) {
+  const parsed = parseArgs(argv);
+  if (parsed.error) return { exitCode: 2, output: parsed.error };
+
+  const { projectName } = parsed;
+  const root = options.runsRootPath;
+  const renderOptions = { json: parsed.json, terminalWidth: options.terminalWidth };
+
+  if (projectName) {
+    const rows = listProjectRuns(root, projectName);
+    if (rows === null) {
+      return {
+        exitCode: 1,
+        output: `codex-bridge projects: unknown project "${projectName}"`,
+      };
+    }
+    return { exitCode: 0, output: output(rows, RUN_COLUMNS, renderOptions) };
+  }
+
+  const rows = listProjects(root);
+  return { exitCode: 0, output: output(rows, PROJECT_COLUMNS, renderOptions) };
+}

package/cli/prune-args.mjs

@@ -0,0 +1,133 @@
+/** Parses prune scopes and refuses combinations that could widen destructive reach. */
+import path from 'node:path';
+
+const DURATION = /^(\d+)([dh])$/;
+const DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
+
+function error(message) {
+  return { error: `codex-bridge prune: ${message}` };
+}
+
+function validCalendarDate(value) {
+  const match = DATE.exec(value);
+  if (!match) return false;
+  const [, year, month, day] = match;
+  const timestamp = Date.UTC(Number(year), Number(month) - 1, Number(day));
+  const date = new Date(timestamp);
+  return date.getUTCFullYear() === Number(year)
+    && date.getUTCMonth() === Number(month) - 1
+    && date.getUTCDate() === Number(day);
+}
+
+/** Parses 30d, 12h, or a calendar date without consulting the filesystem. */
+export function parseOlderThan(value) {
+  const text = String(value ?? '').trim();
+  const duration = DURATION.exec(text);
+  if (duration) {
+    const amount = Number(duration[1]);
+    if (amount > 0 && Number.isSafeInteger(amount)) {
+      return { kind: 'duration', amount, unit: duration[2] };
+    }
+  }
+  if (validCalendarDate(text)) return { kind: 'date', date: text };
+  return { error: `--older-than must be a positive duration like 30d or 12h, or an exact date YYYY-MM-DD; got "${text}"` };
+}
+
+function validateName(label, value) {
+  if (!value || value === '.' || value === '..' || path.isAbsolute(value) || path.dirname(value) !== '.') {
+    return error(`${label} must be a bare folder name`);
+  }
+  return null;
+}
+
+/** Parses prune's positional scopes and safety flags. */
+export function parsePruneArgs(argv = []) {
+  const positional = [];
+  let allProjects = false;
+  let purge = false;
+  let force = false;
+  let json = false;
+  let olderThan = null;
+  let olderThanExplicit = false;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--all-projects') {
+      allProjects = true;
+      continue;
+    }
+    if (arg === '--purge') {
+      purge = true;
+      continue;
+    }
+    if (arg === '--force' || arg === '-f') {
+      force = true;
+      continue;
+    }
+    if (arg === '--json') {
+      json = true;
+      continue;
+    }
+    if (arg === '--older-than' || arg === '--older-than=') {
+      const value = argv[index + 1];
+      if (value === undefined || value.startsWith('-')) return error('--older-than requires a value');
+      const parsed = parseOlderThan(value);
+      if (parsed.error) return error(parsed.error.replace(/^--older-than\s*/, '--older-than '));
+      olderThan = parsed;
+      olderThanExplicit = true;
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith('--older-than=')) {
+      const value = arg.slice('--older-than='.length);
+      if (!value) return error('--older-than requires a value');
+      const parsed = parseOlderThan(value);
+      if (parsed.error) return error(parsed.error.replace(/^--older-than\s*/, '--older-than '));
+      olderThan = parsed;
+      olderThanExplicit = true;
+      continue;
+    }
+    if (arg.startsWith('-')) return error(`unknown option "${arg}"`);
+    positional.push(arg);
+  }
+
+  if (allProjects && purge) {
+    return error('--all-projects cannot be combined with --purge; all-projects is gentle only');
+  }
+  if (allProjects && positional.length) {
+    return error('--all-projects does not accept a project or run name');
+  }
+  if (!allProjects && (positional.length < 1 || positional.length > 2)) {
+    return error('expected <project>, optional <run>, or --all-projects');
+  }
+
+  const projectName = positional[0] || null;
+  const runName = positional[1] || null;
+  if (projectName) {
+    const invalid = validateName('project', projectName);
+    if (invalid) return invalid;
+  }
+  if (runName) {
+    const invalid = validateName('run', runName);
+    if (invalid) return invalid;
+  }
+
+  // The 30-day default belongs to the gentle sweep, which searches history for weight to shed.
+  // A purge is never implicitly aged: `prune sbx2 --purge` means that folder, now. Defaulting it
+  // made the plan's own fourth scenario unreachable — a young project answered "nothing to
+  // remove", which reads as a broken command, not as a refusal.
+  if (!olderThan && !purge && (allProjects || !runName)) {
+    olderThan = { kind: 'duration', amount: 30, unit: 'd' };
+  }
+
+  return {
+    allProjects,
+    projectName,
+    runName,
+    purge,
+    force,
+    json,
+    olderThan,
+    olderThanExplicit,
+  };
+}