@lyupro/codex-bridge 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,66 @@ 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).
 
+## [Unreleased]
+
+## [0.4.0] - 2026-08-09
+
+### Added
+
+- Scope patterns are checked before Codex starts. A pattern that cannot match anything — an
+  absolute or drive-qualified path, backslash separators, a `..` segment, or a spelling no
+  repository file answers to — is refused with no run folder and no quota spent, for all three
+  dispatchers. The file list comes from `git ls-files --cached --others --exclude-standard`, so
+  ignored output does not count as repository content. A file the run is meant to create is
+  declared with `--scope-new`, accepted only by `codex-build` and recorded in `worker.json`.
+- `codex-bridge permissions` reports, adds, and removes the optional shell permission rules for
+  both CLI names and the clone entry point. The exact allow and deny strings merge into
+  `settings.json`, preserve foreign rules, and are also removed by `uninstall`; `doctor` reports
+  an absent or partial set as an optional warning.
+
+### Changed
+
+- `codex-bridge sweep` is now `codex-bridge unlock`. The default scope is the current repository;
+  a bare project name remains addressable, and `--all` is now required for the whole store. The
+  report shows age, silence, and `alive` / `dead` / `foreign` / `unverified` identity verdicts;
+  confirmed-alive records are refused with `codex-bridge stop <run>` instead of being closed.
+
+### Fixed
+
+- Run records now verify that a pid still belongs to the process that started the run, using the
+  process start time and a fresh heartbeat before falling back to an OS probe. A reused or
+  unverified pid is never signalled by `stop`; `codex-bridge unlock` remains the non-killing way to
+  close a record whose process identity cannot be confirmed.
+- JSON files written by PowerShell with a UTF-8 BOM are now read consistently by the CLI and
+  installed hooks, and one command run creates at most one settings backup without deleting older
+  backups.
+- A run a guard refused before Codex ever started no longer costs the next attempt a round trip. Such a folder now closes as `aborted_pre_start` instead of the same `failed` a twenty-minute paid run gets, and the chain gate, the continuation limit and the tree baseline all skip it: the same order id starts as a first run, silently, with no `continue:` grant. Reported from a parallel `codex-build` launch — the second run was correctly refused with "two writing runs in one tree are prohibited", and its one-millisecond folder then made the retry demand a grant for work that never happened. Folders written before this release are recognised by what `meta.json` records — `exit`, `session_id`, `events_bytes`, `stderr_bytes`, `tokens_reported` — rather than by whether `events.jsonl` is still on disk, because retention deletes that file from paid runs too. The folder itself is kept: it is the audit trail of who was refused and why.
+- `chainBaseline()` takes the first run of the chain that actually started, so a pre-start folder sorting first no longer leaves the next pass without the `state-before.txt` its work is measured against.
+- `uninstall --dry-run` names each hook by its own matcher. Three of the four hooks are PreToolUse,
+  and a lookup by event alone reported `Agent|Task` for the worktree lock and the prune guard too —
+  in the one line an operator reads to see what a removal is about to touch. The removal itself was
+  never affected: hooks are found by command, not by matcher.
+- The order gate's refusal now shows the line it found. A caller who wrote
+  `scope (you may create/modify ONLY these):` was told scope was missing, re-read their own prompt,
+  saw it written there, and had nothing to act on; an autonomous run rewrites the same text forever.
+  The refusal names the candidate line under the input it belongs to and says why it was not
+  accepted — a qualifier between the label and the colon, a value that is still a placeholder, or no
+  separator at all — and stays silent when no candidate exists, because then "the input is missing"
+  is the truth. The parser accepts exactly what it accepted before: deriving scope from prose would
+  give away the only guarantee that a run cannot touch files nobody listed.
+
+## [0.3.1] - 2026-08-07
+
+### Added
+
+- The CLI answers to `codexb` as well as `codex-bridge`, and README now documents the global install that puts both names on `PATH`. Every spelling that can reach deletion comes from one frozen list, and the prune guard builds its matcher from that list rather than repeating the names — two independent lists drift silently, which is exactly how the installer and test hook lists had already drifted. The full name stays primary: the docs, checklists and three agent prompts are written with it.
+- Every run carries the rules it is judged by. A seeded `conventions.md` beside `run-config.json` and an optional `.codex-conventions.md` in the repository being worked on are pasted into `task.md` verbatim, under one `## Conventions` section. Either file missing is not an error, and a blank one produces no section at all — rules handed over as an empty heading read as rules ignored. Until now project rules reached a run only when the orchestrator remembered to write "read CLAUDE.md" into the task, and six acceptance passes in a row caught the same class of violation: the rule existed, applied, and had not travelled. Pasting rather than referencing is the point — "read file X" is hope, and a run is free not to.
+- `doctor` opens with the path of the package copy answering, marked `clone` or `installed package`, and reports whether the host conventions file was found, warning when it exists but is empty. A global install puts a second copy of the package beside any clone, and `update` copies host files from whichever copy launched it — so two diagnoses of the same host were previously indistinguishable.
+
+### Fixed
+
+- `codex-bridge projects` printed the `last run` column on two clocks. Folder names are written in local time and `meta.finished_at` is an ISO stamp in UTC, and each reached the column through its own branch, so a run whose folder says `144243` was listed as `12:46` — the operator's own zone offset, indistinguishable from a different run. Which run is newest was never affected, only how it printed.
+
 ## [0.3.0] - 2026-08-07
 
 ### Added

package/README.md

@@ -7,19 +7,29 @@ subscription instead of the Claude one.
 ## Install
 
 ```bash
-npx @lyupro/codex-bridge install        # into ~/.claude
+npx @lyupro/codex-bridge install        # one-off, into ~/.claude
+npm i -g @lyupro/codex-bridge           # install both command names globally
+codex-bridge install                    # full name, from any directory
+codexb install                          # short name, same command
 node bin/codex-bridge.mjs install       # from a clone, same thing
 node bin/codex-bridge.mjs install --scope project   # into <repo>/.claude
 node bin/codex-bridge.mjs update        # bring an installation up to the current version
+node bin/codex-bridge.mjs permissions   # show optional shell permission rules
+node bin/codex-bridge.mjs permissions add # add the complete allow/deny rule set
+node bin/codex-bridge.mjs permissions remove # remove only codex-bridge's rule strings
 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
+node bin/codex-bridge.mjs unlock [<project>|--all] # close records whose runner is gone
 ```
 
+When a global install and a clone coexist, there are two copies of the package. `codex-bridge update`
+and `codexb update` copy host files from whichever copy launched the command, so `codexb update`
+from `PATH` can silently revert a host that `npm run dev:install` from the clone just updated.
+
 `install` copies the package into the host's `agents/codex/`, its slash commands into
 `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
@@ -31,6 +41,13 @@ version: outdated files are refreshed silently, files you changed by hand stop t
 named, and `--force` is what overwrites them. A file the package no longer ships is removed only
 if you never touched it.
 
+`permissions` manages the optional shell rules in the selected host's `settings.json`. `add`
+merges the exact allow and deny strings for both CLI names, the clone entry point, Bash and
+PowerShell; it preserves foreign rules and is safe to repeat. `remove` takes back those exact
+strings from `allow`, `deny`, or `ask`, so an operator-authored lookalike is left alone. With no
+action it reports whether the rule set is installed, partial, or absent. The command accepts the
+same `--scope` and `--host` selectors as `install`, and `uninstall` removes the same strings too.
+
 `uninstall` removes only what the install recorded: a file you put in `agents/codex/` yourself
 stays, and `codex-runs/` is never touched — those are your run artifacts, not the package.
 
@@ -55,11 +72,14 @@ accounting, reports and worktree snapshots alone; `--purge` is what takes a fold
 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.
+`unlock` is housekeeping for records left by a dead runner. With no argument it acts on the current
+repository; a bare project name limits the scan to that folder, and `--all` explicitly scans the
+whole store. It uses the same process-identity decision as start-of-run cleanup, closes only
+`dead` or `foreign` records, and reports each record's age, silence duration, and identity verdict.
+A confirmed `alive` record is refused rather than closed and is named with the exact
+`codex-bridge stop <run>` command needed to end it; `unverified` records stay untouched with the
+reason visible. The command never deletes run artifacts. The old spelling `sweep` is recognized and
+refused with the rename to `unlock`, rather than treated as an unknown command.
 
 ## What it gives you
 

package/bin/codex-bridge.mjs

@@ -8,9 +8,10 @@ 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 { permissions } from '../cli/permissions.mjs';
 import { prune } from '../cli/prune.mjs';
 import { stop } from '../cli/stop.mjs';
-import { sweep } from '../cli/sweep.mjs';
+import { unlock } from '../cli/unlock.mjs';
 import { uninstall } from '../cli/uninstall.mjs';
 import { update } from '../cli/update.mjs';
 
@@ -19,25 +20,28 @@ export const HELP = `codex-bridge — Claude Code dispatchers for Codex
 Usage:
   codex-bridge install [--scope user|project] [--host <path>] [--dry-run] [--force]
   codex-bridge update [--scope user|project] [--host <path>] [--dry-run] [--force]
+  codex-bridge permissions [add|remove] [--scope user|project] [--host <path>]
   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 unlock [<project>|--all]
   codex-bridge read <run>
   codex-bridge stop <run>
+  codexb <same command forms as codex-bridge>
   codex-bridge --help
   codex-bridge --version
 
 Commands:
   install   Install codex-bridge into the selected Claude Code host
   update    Update a recorded codex-bridge installation
+  permissions Show, add, or remove optional shell permission rules
   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
+  unlock    Close running records whose runner is gone
   read      Render a run's structured event stream
   stop      Stop a running Codex run and record FAIL`;
 
@@ -109,7 +113,27 @@ export async function main(argv, io = console) {
     return result.exitCode;
   }
   if (command === 'sweep') {
-    const result = sweep(rest);
+    io.error('codex-bridge sweep was renamed to codex-bridge unlock; use the new command.');
+    return 2;
+  }
+  if (command === 'unlock') {
+    const result = unlock(rest);
+    io.log(result.output);
+    return result.exitCode;
+  }
+  if (command === 'permissions') {
+    let action;
+    let optionArgs = rest;
+    if (rest[0] && !rest[0].startsWith('-')) {
+      action = rest[0];
+      optionArgs = rest.slice(1);
+    }
+    if (action && !['add', 'remove'].includes(action)) {
+      throw new Error(`unknown permissions action "${action}"`);
+    }
+    const options = commandOptions(command, optionArgs);
+    const host = resolveHost(options);
+    const result = await permissions({ host, action });
     io.log(result.output);
     return result.exitCode;
   }

package/cli/doctor.mjs

@@ -1,6 +1,7 @@
 /** Diagnoses a Claude Code host without modifying it. */
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import {
   fileFingerprint,
@@ -8,6 +9,7 @@ import {
   readInstallRecord,
   packageInfo,
 } from './manifest.mjs';
+import { inspectPermissions } from './permissions.mjs';
 import { commandFor, inspectHook } from './settings-merge.mjs';
 import { readRulesRegistry } from './rules-owners.mjs';
 import { readRunConfig, retentionNotice } from '../src/run-config.mjs';
@@ -47,6 +49,34 @@ function retentionCheck(host) {
   }
 }
 
+async function conventionsCheck(host) {
+  const file = path.join(host.agentsDir, 'conventions.md');
+  let content;
+  try {
+    content = await fs.readFile(file, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return check('conventions', 'ok', `${file} (not found; optional)`);
+    return check('conventions', 'fail', `cannot read ${file}: ${err.message}`);
+  }
+  return content.trim()
+    ? check('conventions', 'ok', `${file} (found)`)
+    : check('conventions', 'warn', `${file} (found but empty)`);
+}
+
+/**
+ * Which copy of the package is answering. Plan_19 gives the CLI a second name, and a global install
+ * puts a second copy of the package on the machine beside any clone. `update` copies host files
+ * from whichever copy launched it, so `codexb update` from PATH silently reverts a host that
+ * `npm run dev:install` from the clone had just refreshed — and every line below this one describes
+ * the host as seen by THIS copy. An operator comparing two diagnoses has no other way to tell them
+ * apart.
+ */
+function sourceCheck() {
+  const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+  const installed = root.split(/[\\/]/).includes('node_modules');
+  return check('source', 'ok', `${root} (${installed ? 'installed package' : 'clone'})`);
+}
+
 /**
  * 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
@@ -133,8 +163,23 @@ async function rulesCheck(host, record) {
     : check('rules', 'warn', `${record.rules.path} (modified after installation${ownerNote})`);
 }
 
+async function permissionsCheck(host) {
+  try {
+    const status = await inspectPermissions(host.settingsPath);
+    // Permission rules are an optional operator action; Plan_22 keeps their absence a warning so
+    // doctor does not turn a healthy installation red merely because hardening was not requested.
+    // The ask count is part of the line because a full set shadowed by `ask` reads as working and
+    // is not: the live run of Plan_22-1 found this line saying `installed (24/24)` over it.
+    const shadow = status.askCount ? `, ${status.askCount} shadowed by ask` : '';
+    return check('permissions', status.state === 'installed' ? 'ok' : 'warn',
+      `${status.state} (${status.present}/${status.total} own strings in allow/deny${shadow})`);
+  } catch (err) {
+    return check('permissions', 'warn', `cannot inspect permission rules: ${err.message}`);
+  }
+}
+
 export async function diagnose({ host, codexProbe = probeCodex, currentPackage } = {}) {
-  const checks = [];
+  const checks = [sourceCheck()];
   const hostExists = await exists(host.root);
   checks.push(check('host', hostExists ? 'ok' : 'warn', `${host.root} (${host.scope}, ${hostExists ? 'exists' : 'absent'})`));
 
@@ -170,9 +215,12 @@ export async function diagnose({ host, codexProbe = probeCodex, currentPackage }
   ));
   const rules = await rulesCheck(host, record);
   checks.push(rules);
+  checks.push(await permissionsCheck(host));
   checks.push(...await hookChecks(host, record));
   const retention = retentionCheck(host);
   checks.push(retention);
+  const conventions = await conventionsCheck(host);
+  checks.push(conventions);
 
   const codex = codexProbe();
   checks.push(check('codex', codex.available ? 'ok' : 'warn', codex.value || 'available'));
@@ -184,7 +232,7 @@ export async function diagnose({ host, codexProbe = probeCodex, currentPackage }
 
   return {
     exitCode: !record || recordBroken || missingFiles.length || rules.status === 'fail'
-      || retention.status === 'fail' || projectRuns.status === 'fail' ? 1 : 0,
+      || retention.status === 'fail' || conventions.status === 'fail' || projectRuns.status === 'fail' ? 1 : 0,
     checks,
     record,
     missingFiles,
@@ -194,6 +242,8 @@ export async function diagnose({ host, codexProbe = probeCodex, currentPackage }
 export function renderDoctor(result) {
   return result.checks.map(({ key, status, value }) => {
     const rendered = `[${status}] ${key}: ${value}`;
-    return key === 'retention' && status === 'warn' ? `${WARNING}${rendered}${RESET}` : rendered;
+    return ['retention', 'conventions', 'permissions'].includes(key) && status === 'warn'
+      ? `${WARNING}${rendered}${RESET}`
+      : rendered;
   }).join('\n');
 }

package/cli/install.mjs

@@ -14,7 +14,7 @@ import {
   writeInstallRecord,
 } from './manifest.mjs';
 import { copyPlannedFile, targetMatches } from './copy.mjs';
-import { commandFor, inspectHook, mergeHook } from './settings-merge.mjs';
+import { commandFor, inspectHook, mergeHook, withSettingsRun } from './settings-merge.mjs';
 import { addRulesOwner, readRulesRegistry } from './rules-owners.mjs';
 import { readRunConfig, retentionNotice } from '../src/run-config.mjs';
 
@@ -58,7 +58,7 @@ function retentionOutput(line, output) {
   return `${output}\n${line}`;
 }
 
-export async function install({ host, dryRun = false, force = false, packageRoot } = {}) {
+async function installInRun({ 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);
@@ -163,3 +163,9 @@ export async function install({ host, dryRun = false, force = false, packageRoot
     output: retentionOutput(configuredRetentionLine, `Installed ${plan.length + 1} files and registered the ${targets.map(({ definition }) => definition.event).join(' and ')} hooks.`),
   };
 }
+
+export async function install(options = {}) {
+  const host = options?.host;
+  if (!host?.settingsPath) return installInRun(options);
+  return withSettingsRun(host.settingsPath, () => installInRun(options));
+}

package/cli/manifest.mjs

@@ -11,9 +11,23 @@ import {
   renderRequiredInputs,
 } from '../src/required-inputs.mjs';
 import { renderNoSelfExecution } from '../src/no-self-execution.mjs';
+import { readJsonFile } from '../src/json-file.mjs';
 
 export { HOOK_DEFINITIONS };
 
+/**
+ * Finds the definition a recorded hook belongs to. The event alone does not identify one: three of
+ * the four hooks are PreToolUse, so `find(d => d.event === hook.event)` returns the order gate for
+ * all three. `doctor` was fixed for exactly this and kept its own inline matching; `uninstall` was
+ * not, and its dry-run announced matcher `Agent|Task` for the worktree lock and the prune guard —
+ * the operator's only view of what a removal is about to touch. One function, so a third caller
+ * cannot repeat it.
+ */
+export function definitionForRecordedHook(hook) {
+  return HOOK_DEFINITIONS.find((definition) => definition.event === hook?.event
+    && path.basename(String(hook?.path ?? '')) === definition.file);
+}
+
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 export const PACKAGE_ROOT = path.resolve(HERE, '..');
 export const INSTALL_RECORD_NAME = '.codex-bridge-install.json';
@@ -22,10 +36,11 @@ const RULES_SOURCE = `src/rules/${RULES_NAME}`;
 /**
  * Files the operator owns once they exist. Seeded on first install so the defaults are
  * visible and editable, then never written, never compared, never removed: run-config.json
- * is where a host states which model each mode runs on, and an installer that overwrites it
- * would erase that on the next update — the same way overwriting a .env would.
+ * is where a host states which model each mode runs on, conventions.md is the rule set it hands
+ * every run, and an installer that overwrites either would erase host decisions on the next
+ * update — the same way overwriting a .env would.
  */
-export const SEEDED_SOURCES = Object.freeze(['src/run-config.json']);
+export const SEEDED_SOURCES = Object.freeze(['src/run-config.json', 'src/conventions.md']);
 const seededTargets = (host) =>
   new Set(SEEDED_SOURCES.map((source) => posix(
     path.relative(host.root, path.join(host.agentsDir, path.relative('src', source))),
@@ -48,7 +63,7 @@ export function replacePlaceholders(content, agentsDir) {
 }
 
 export async function packageInfo(packageRoot = PACKAGE_ROOT) {
-  const parsed = JSON.parse(await fs.readFile(path.join(packageRoot, 'package.json'), 'utf8'));
+  const parsed = await readJsonFile(path.join(packageRoot, 'package.json'));
   return { name: parsed.name, version: parsed.version };
 }
 
@@ -190,19 +205,16 @@ export function normalizeInstallRecord(record) {
 }
 
 export async function readInstallRecord(host) {
-  let raw;
+  let parsed;
   try {
-    raw = await fs.readFile(installRecordPath(host), 'utf8');
+    parsed = await readJsonFile(installRecordPath(host));
   } catch (err) {
     if (err.code === 'ENOENT') return null;
+    if (err.cause) {
+      throw new Error(`invalid installation record JSON: ${err.cause.message}`, { cause: err.cause });
+    }
     throw err;
   }
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch (err) {
-    throw new Error(`invalid installation record JSON: ${err.message}`);
-  }
   const record = normalizeInstallRecord(parsed);
   // Earlier versions installed the config as a package file and recorded it. Dropping it here
   // is what stops the next update from calling the operator's edited config an orphan and

package/cli/permissions.mjs

@@ -0,0 +1,179 @@
+/** Manages the optional shell permission rules for every codex-bridge command spelling. */
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CLI_NAMES } from '../src/cli-names.mjs';
+import { SHELL_TOOLS } from '../src/hook-definitions.mjs';
+import { readSettings, updateSettings, withSettingsRun } from './settings-merge.mjs';
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const entryPoint = fileURLToPath(new URL('../bin/codex-bridge.mjs', import.meta.url));
+const nodeCommand = `node ${path.relative(packageRoot, entryPoint).split(path.sep).join('/')}`;
+const commandNames = Object.freeze([...CLI_NAMES, nodeCommand]);
+const formsFor = (command) => [command, `${command}:*`];
+
+function buildRules(commandTransform) {
+  return Object.freeze(SHELL_TOOLS.flatMap((tool) => commandNames.flatMap((command) =>
+    formsFor(commandTransform(command)).map((form) => `${tool}(${form})`))));
+}
+
+/**
+ * The executable names stay owned by cli-names.mjs; only the clone entry point is derived here.
+ * Plan_22 records the incident because repeating the node spelling in CLI_NAMES would make the
+ * source list answer two different questions and let a future alias bypass one of them.
+ *
+ * The deny half subtracts `prune` from the allow half rather than guarding it: `Bash(codex-bridge:*)`
+ * would otherwise hand out the deletion this package refuses to give an agent. Its refusal is never
+ * seen in a live session — a PreToolUse hook answers before permissions are consulted, and
+ * prune-guard is installed always while these rules are optional. The 2026-08-09 run held that
+ * observation open as a checklist item until it turned out to be the answer, not the obstacle.
+ */
+export const PERMISSION_RULES = Object.freeze({
+  allow: buildRules((command) => command),
+  deny: buildRules((command) => `${command} prune`),
+});
+
+const allRules = new Set([...PERMISSION_RULES.allow, ...PERMISSION_RULES.deny]);
+const ruleLists = Object.freeze(['allow', 'deny', 'ask']);
+const activeLists = Object.freeze(['allow', 'deny']);
+const totalRules = PERMISSION_RULES.allow.length + PERMISSION_RULES.deny.length;
+
+function listValue(settings, name) {
+  const list = settings?.permissions?.[name];
+  return Array.isArray(list) ? list : [];
+}
+
+function matchingRules(list, rules) {
+  return rules.filter((rule) => list.includes(rule)).length;
+}
+
+/**
+ * A count of strings in allow and deny is not the state of the set, because `ask` outranks `allow`:
+ * a copy sitting there keeps asking the question the rule was added to end. The live run of
+ * Plan_22-1 caught doctor reporting `installed (24/24)` over exactly that arrangement — the number
+ * was true and the conclusion drawn from it was false. Every consumer reads the state, so the
+ * shadow has to live in the state rather than in one command's wording.
+ */
+function permissionStatus(settings) {
+  const counts = Object.fromEntries(activeLists.map((name) => [
+    name,
+    matchingRules(listValue(settings, name), PERMISSION_RULES[name]),
+  ]));
+  const askCount = matchingRules(listValue(settings, 'ask'), [...allRules]);
+  const present = counts.allow + counts.deny;
+  const complete = present === totalRules;
+  const state = askCount
+    ? (complete ? 'shadowed by ask' : 'partially installed, shadowed by ask')
+    : complete ? 'installed' : present === 0 ? 'absent' : 'partially installed';
+  return {
+    state,
+    complete,
+    counts,
+    askCount,
+    present,
+    total: totalRules,
+  };
+}
+
+function ensureList(settings, name) {
+  if (settings.permissions === undefined) settings.permissions = {};
+  if (!settings.permissions || typeof settings.permissions !== 'object'
+    || Array.isArray(settings.permissions)) {
+    throw new TypeError('settings.permissions must be an object');
+  }
+  if (settings.permissions[name] === undefined) settings.permissions[name] = [];
+  if (!Array.isArray(settings.permissions[name])) {
+    throw new TypeError(`settings.permissions.${name} must be an array`);
+  }
+  return settings.permissions[name];
+}
+
+function countRemovable(settings) {
+  return ruleLists.reduce((total, name) => total + listValue(settings, name)
+    .filter((entry) => allRules.has(entry)).length, 0);
+}
+
+export async function inspectPermissions(settingsPath) {
+  const state = await readSettings(settingsPath);
+  return { ...state, ...permissionStatus(state.settings) };
+}
+
+export async function addPermissionRules(settingsPath) {
+  return updateSettings(settingsPath, (settings) => {
+    let added = 0;
+    for (const name of activeLists) {
+      const list = ensureList(settings, name);
+      for (const rule of PERMISSION_RULES[name]) {
+        if (list.includes(rule)) continue;
+        list.push(rule);
+        added += 1;
+      }
+    }
+    return { changed: added > 0, added };
+  });
+}
+
+export async function removePermissionRules(settingsPath, { dryRun = false } = {}) {
+  if (dryRun) {
+    const state = await readSettings(settingsPath);
+    return { changed: false, removed: countRemovable(state.settings) };
+  }
+  return updateSettings(settingsPath, (settings) => {
+    let removed = 0;
+    for (const name of ruleLists) {
+      const list = settings?.permissions?.[name];
+      if (!Array.isArray(list)) continue;
+      settings.permissions[name] = list.filter((entry) => {
+        if (!allRules.has(entry)) return true;
+        removed += 1;
+        return false;
+      });
+    }
+    return { changed: removed > 0, removed };
+  });
+}
+
+function statusOutput(status) {
+  const moved = status.askCount
+    ? `; ${status.askCount} own string(s) in ask, which outranks allow`
+    : '';
+  return `Permissions: ${status.state} (${status.present}/${status.total} own strings in allow/deny${moved}).`;
+}
+
+async function permissionsInRun({ host, action } = {}) {
+  if (!host?.settingsPath) throw new TypeError('permissions requires a resolved host');
+  if (!action) {
+    const status = await inspectPermissions(host.settingsPath);
+    return { exitCode: 0, output: statusOutput(status), ...status };
+  }
+  if (action === 'add') {
+    const result = await addPermissionRules(host.settingsPath);
+    // A string the operator moved into `ask` outranks the copy `add` just put into `allow`, so the
+    // command would report a complete set while the questions it was run to end keep appearing.
+    // `ask` stays untouched — it is a hand-made decision — but silence about it is a false success.
+    const status = await inspectPermissions(host.settingsPath);
+    const conflict = status.askCount
+      ? ` ${status.askCount} own string(s) also sit in ask, which outranks allow; they were left there.`
+      : '';
+    return {
+      exitCode: 0,
+      output: `Added ${result.added} permission rule string${result.added === 1 ? '' : 's'}.${conflict}`,
+      ...result,
+      askCount: status.askCount,
+    };
+  }
+  if (action === 'remove') {
+    const result = await removePermissionRules(host.settingsPath);
+    return {
+      exitCode: 0,
+      output: `Removed ${result.removed} permission rule string${result.removed === 1 ? '' : 's'}.`,
+      ...result,
+    };
+  }
+  throw new Error(`unknown permissions action "${action}"`);
+}
+
+export async function permissions(options = {}) {
+  const host = options?.host;
+  if (!host?.settingsPath) return permissionsInRun(options);
+  return withSettingsRun(host.settingsPath, () => permissionsInRun(options));
+}

package/cli/projects.mjs

@@ -15,13 +15,26 @@ function formatSize(bytes) {
   return `${bytes} B`;
 }
 
-/** Both timestamp shapes in the store: an ISO stamp from artifacts, a folder name otherwise. */
+const pad = (value) => String(value).padStart(2, '0');
+
+/**
+ * Both timestamp shapes in the store, printed on one clock. A run folder is named in local time
+ * (`2026-08-07_144243`); `meta.finished_at` is an ISO stamp in UTC. Reading the ISO one with a
+ * regular expression printed its UTC hours in the same column as local ones, and the 2026-08-07
+ * live check (Plan_17-1 §1) saw the run whose folder says `144243` listed as `12:46` — the
+ * operator's own zone offset, looking exactly like a different run. Slicing a timestamp is cheaper
+ * than parsing it only until the value carries a zone. The folder name stays text because it is
+ * already local; parsing it would invent a zone it never had.
+ */
 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;
+  if (folder) return `${folder[1]} ${folder[2]}:${folder[3]}`;
+  const moment = Date.parse(value);
+  if (Number.isNaN(moment)) return value;
+  const at = new Date(moment);
+  return `${at.getFullYear()}-${pad(at.getMonth() + 1)}-${pad(at.getDate())}`
+    + ` ${pad(at.getHours())}:${pad(at.getMinutes())}`;
 }
 
 const PROJECT_COLUMNS = [

package/cli/prune-args.mjs

@@ -112,7 +112,7 @@ export function parsePruneArgs(argv = []) {
     if (invalid) return invalid;
   }
 
-  // The 30-day default belongs to the gentle sweep, which searches history for weight to shed.
+  // The 30-day default belongs to the gentle cleanup, 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.