@lyupro/codex-bridge 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -4,6 +4,18 @@ 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.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,7 +7,10 @@ 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
@@ -20,6 +23,10 @@ node bin/codex-bridge.mjs prune <project>   # reclaim disk space, transport only
 node bin/codex-bridge.mjs sweep [<project>] # close running 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

package/bin/codex-bridge.mjs

@@ -27,6 +27,7 @@ Usage:
   codex-bridge sweep [<project>]
   codex-bridge read <run>
   codex-bridge stop <run>
+  codexb <same command forms as codex-bridge>
   codex-bridge --help
   codex-bridge --version
 

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,
@@ -47,6 +48,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
@@ -134,7 +163,7 @@ async function rulesCheck(host, record) {
 }
 
 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'})`));
 
@@ -173,6 +202,8 @@ export async function diagnose({ host, codexProbe = probeCodex, currentPackage }
   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 +215,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 +225,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'].includes(key) && status === 'warn'
+      ? `${WARNING}${rendered}${RESET}`
+      : rendered;
   }).join('\n');
 }

package/cli/manifest.mjs

@@ -22,10 +22,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))),

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

@@ -1,6 +1,6 @@
 {
   "name": "@lyupro/codex-bridge",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Delegate implementation, reconnaissance and code review from Claude Code to the Codex CLI: dispatcher agents, a runner that survives a dropped call, and a verdict that checks the report against the worktree.",
   "keywords": [
     "claude-code",
@@ -23,7 +23,8 @@
   "homepage": "https://github.com/lyupro/codex-bridge#readme",
   "type": "module",
   "bin": {
-    "codex-bridge": "./bin/codex-bridge.mjs"
+    "codex-bridge": "./bin/codex-bridge.mjs",
+    "codexb": "./bin/codex-bridge.mjs"
   },
   "engines": {
     "node": ">=24.0.0"

package/src/cli-names.mjs

@@ -0,0 +1,6 @@
+/** Names this CLI answers to. */
+
+// Plan_17 §5 found installer and test hook lists drifting; keep executable spellings here so a
+// new alias cannot silently bypass the prune guard. Under src/ because the installed guard reads
+// it too, and cli/ is not copied into the host.
+export const CLI_NAMES = Object.freeze(['codex-bridge', 'codexb']);

package/src/conventions.md

@@ -0,0 +1,44 @@
+# Delegated-run conventions
+
+These are the host conventions for every Codex run. Each block records a real acceptance
+violation caught in this repository and turns it into a guard for the next run.
+
+## Task boundaries - Plan_16 acceptance incident
+
+- Do not refactor code the task did not ask to change.
+- Do not delete code on your own initiative.
+- Do not change behavior branches whose behavior the task does not mention, even inside an
+  allowed file.
+
+The 2026-08-06 Plan_16 acceptance finding applied a new reason order to a transport branch that
+already named its reason. Preserve existing branches unless the task explicitly changes them.
+
+## Contracts without silent defaults - Plan_16 reasonFrom incident
+
+- Require arguments that the contract needs instead of supplying a default.
+- Fail loud when a required value is absent; do not silently fall back.
+- Keep volatile identifiers such as model IDs and API versions in configuration, not runtime code.
+
+The 2026-08-06 `reasonFrom(runDir, eventData = {})` finding replaced a required contract with a
+silent default. Missing inputs must remain visible at the boundary that can explain them.
+
+## Structure and size - 2026-08-06 projects reload incident
+
+- Keep every source file at or below 400 lines.
+- Give each module one responsibility.
+- Do not create `utils.mjs` dumping grounds.
+- Never split coherent pieces solely to reach the line limit.
+
+The 2026-08-06 `projects` reload finding exposed pseudo-duplicate exports and just-in-case code.
+Keep related code together, but remove a real responsibility or create a focused module when a
+boundary is needed.
+
+## Tests and comments - 2026-08-05 step 2b incident
+
+- Add a guard test for every invariant accepted by the task.
+- Splitting a file must delete no test case.
+- Comments explain WHY and name the incident or decision that makes the rule necessary.
+
+The 2026-08-05 step 2b acceptance found the abandoned-run check below the commit check. Test the
+ordering invariant itself, and leave the incident in the comment so a later cleanup does not
+silently undo it.

package/src/hooks/prune-guard.mjs

@@ -11,6 +11,7 @@
  * Anything unrecognised passes. A guard that misreads its input must not break unrelated host work.
  */
 import fs from 'node:fs';
+import { CLI_NAMES } from '../cli-names.mjs';
 import { SHELL_TOOLS } from '../hook-definitions.mjs';
 
 const SHELL_TOOL_NAMES = new Set(SHELL_TOOLS);
@@ -18,10 +19,17 @@ const pass = () => process.exit(0);
 
 // The binary, then the verb, with any path in front of it: an agent reaches the CLI as
 // `codex-bridge`, as `node bin/codex-bridge.mjs`, or through an absolute path, and a guard that
-// only knew the bare name would be bypassed by the spelling everyone uses inside a clone. Matching
-// a lone `prune` is not an option either — `git prune` and `npm prune` are not this package's
-// business, and a guard that breaks unrelated work is a guard that gets uninstalled.
-const PRUNE_CALL = /(^|[\s;&|(`])(\S*[\\/])?codex-bridge(\.mjs)?\s+prune(\s|$)/;
+// only knew the bare name would be bypassed by the spelling everyone uses inside a clone. Plan_19
+// adds a second executable spelling, so build this matcher from the shared list instead of
+// repeating names here. Matching a lone `prune` is not an option either — `git prune` and
+// `npm prune` are not this package's business, and a guard that breaks unrelated work is a guard
+// that gets uninstalled.
+const escapeRegex = (name) => name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const CLI_NAME_PATTERN = CLI_NAMES.map(escapeRegex).join('|');
+const PRUNE_CALL = new RegExp(
+  '(^|[\\s;&|(`])(\\S*[\\\\/])?(?:' + CLI_NAME_PATTERN
+    + ')(\\.mjs)?\\s+prune(\\s|$)',
+);
 
 let input;
 try {

package/src/runner/conventions.mjs

@@ -0,0 +1,39 @@
+/** Renders the host and repository conventions that a run must carry in its task artifact. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { CONFIG_PATH } from '../run-config.mjs';
+
+const HOST_FILE = path.join(path.dirname(CONFIG_PATH), 'conventions.md');
+const REPOSITORY_FILE = '.codex-conventions.md';
+
+function readOptional(file) {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+/**
+ * Reads both convention layers at the point of use. Plan_13 showed that a reference to a required
+ * file is not enforcement: the task must contain the bytes the run was given.
+ *
+ * A layer that is present but blank is dropped rather than rendered as an empty heading, for the
+ * same reason doctor warns about it — an empty rules file looks like a working mechanism and is
+ * not one, and in the artifact it would look like rules that were given and ignored.
+ *
+ * Duplication is impossible by construction and deliberately not guarded against: `sections`
+ * starts empty on every launch and task.md is written into a folder that is never reused, so
+ * there is nothing to append to. A guard reading the operator's task text for this heading would
+ * only find the word in a task that talks ABOUT conventions, and silently drop the section from
+ * the one run that most obviously needed it.
+ */
+export function renderConventions(repoRoot, hostFile = HOST_FILE) {
+  const layers = [];
+  const host = readOptional(hostFile);
+  if (host?.trim()) layers.push(`### Host conventions\n\n${host}`);
+  const repository = readOptional(path.join(repoRoot, REPOSITORY_FILE));
+  if (repository?.trim()) layers.push(`### Repository conventions\n\n${repository}`);
+  return layers.length ? `## Conventions\n\n${layers.join('\n\n')}` : '';
+}

package/src/runner/launcher.mjs

@@ -37,6 +37,7 @@ import { codexArgs, requireCodex, runMode, unsafeForCmd } from './codex-cmd.mjs'
 import { runsRoot } from './runs-root.mjs';
 import { resolveProjectRunsDir } from './project-dir.mjs';
 import { cleanupRetention } from '../retention.mjs';
+import { renderConventions } from './conventions.mjs';
 
 /**
  * The worker is this same program re-invoked as `--worker <runDir>`, so the path spawned
@@ -279,6 +280,8 @@ export async function launcher() {
       ].join('\n'),
     );
   }
+  const conventions = renderConventions(repoRoot);
+  if (conventions) sections.push(conventions);
   sections.push(`## Instructions for Codex\n\n${INSTRUCTIONS[opts.agent](opts, scope, questions)}`);
   fs.writeFileSync(path.join(runDir, 'task.md'), `${sections.join('\n\n')}\n`);
   fs.writeFileSync(