@lyupro/codex-bridge 0.1.3 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,50 @@ 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.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
+
+- A continuation has to prove the orchestrator ordered it. `--continue` is refused unless the task text carries a `continue:` grant naming the run being continued and why, and the refusal costs nothing: no run folder is created and Codex is never started. The grant is single-use by construction rather than by a counter — continuing the last run of a chain appends a later one, so the same line stops matching by itself. Until this release a dispatcher could decide on a second pass alone: one did, spent 75 691 tokens of the Codex subscription and created a module the order never asked for.
+- A reply that stays silent about a live `codex-build` run of the same project is blocked. The guard reads the project's runs folder from disk instead of trusting the paths the reply chose to mention, so a second run can no longer be left working in the background while the verdict of the first is handed back. Runs of `codex-scout` and `codex-review` are not counted: they hold a read-only sandbox, and blocking a reply over one would spend the guard's budget on a run that touches nothing.
+- A `PreToolUse` lock refuses file edits inside a repository held by a live `codex-build` run. Knowing that a run is live is not the same as being unable to disturb it — edits made during that window land in the runner's before/after snapshot and fail an honest run for work it never did. An edit made through `Bash` still walks past the lock; parsing a command line is not something a guard can do reliably.
+
+### Fixed
+
+- `doctor` names the file each hook was registered for. With two hooks on one event it matched the installation record by event alone and reported the worktree lock's matcher as pointing at `order-gate.mjs` — the one line where an operator can check what is installed, showing the wrong file.
+- Hook presence is decided by this package's own command rather than by the matcher it currently sits under. The matcher is generated from the list of host tool names and grows whenever a spelling is added, so a host installed under the previous matcher would collect a duplicate hook on update and keep a hook pointing at a deleted file after uninstall.
+
 ## [0.1.3] - 2026-08-05
 
 ### Added

package/README.md

@@ -14,11 +14,13 @@ 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
 ```
 
 `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 +44,16 @@ 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.
+
 ## What it gives you
 
 - **Three dispatcher agents** for Claude Code — reconnaissance (read-only), implementation
@@ -52,8 +64,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,7 +5,10 @@ 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 { uninstall } from '../cli/uninstall.mjs';
 import { update } from '../cli/update.mjs';
@@ -17,6 +20,10 @@ 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 read <run>
   codex-bridge stop <run>
   codex-bridge --help
   codex-bridge --version
@@ -26,6 +33,9 @@ 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
+  read      Render a run's structured event stream
   stop      Stop a running Codex run and record FAIL`;
 
 function commandOptions(command, argv) {
@@ -76,6 +86,25 @@ 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 === '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
@@ -73,7 +86,12 @@ async function hookChecks(host, record) {
   return Promise.all(HOOK_DEFINITIONS.map(async (definition) => {
     const key = `hook:${definition.event}`;
     if (!record) return check(key, 'warn', 'cannot check before installation');
-    const recorded = record.hooks.find((hook) => hook.event === definition.event);
+    // The file, not just the event: PreToolUse carries two hooks of this package, and matching
+    // by event alone reported the worktree lock's matcher as pointing at order-gate.mjs. The
+    // hook line is the only place an operator can see WHICH file a matcher was registered for,
+    // so a wrong name here is worse than no line at all.
+    const recorded = record.hooks.find((hook) => hook.event === definition.event
+      && path.basename(hook.path) === definition.file);
     if (!recorded) {
       return check(key, 'warn', `${definition.event} hook is not present in the installation record`);
     }
@@ -153,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'));
@@ -164,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,
@@ -172,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

@@ -164,15 +164,17 @@ export function validateInstallRecord(record) {
     if (!hook || typeof hook !== 'object' || Array.isArray(hook)) {
       throw new Error('installation record hook must be an object');
     }
-    const definition = HOOK_DEFINITIONS.find((entry) => entry.event === hook.event);
-    if (!definition || typeof hook.path !== 'string' || !hook.path) {
+    const definitions = HOOK_DEFINITIONS.filter((entry) => entry.event === hook.event);
+    if (!definitions.length || typeof hook.path !== 'string' || !hook.path) {
       throw new Error('installation record hook must identify a supported event and its path');
     }
     if (path.isAbsolute(hook.path) || hook.path.split(/[\\/]/).includes('..')) {
       throw new Error('installation record hook path must stay relative to the host root');
     }
-    if (path.basename(hook.path) !== definition.file || !record.files.includes(hook.path)) {
-      throw new Error(`installation record hook path must name the installed ${definition.file}`);
+    const definition = definitions.find((entry) => path.basename(hook.path) === entry.file);
+    if (!definition || !record.files.includes(hook.path)) {
+      const files = definitions.map((entry) => entry.file).join(' or ');
+      throw new Error(`installation record hook path must name the installed ${files}`);
     }
   }
   return record;

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,
+  };
+}