@lyupro/codex-bridge 0.6.12 → 0.6.14

package/src/{agents → claude/agents}/codex-build.md

@@ -1,6 +1,6 @@
 ---
 name: codex-build
-description: Имплементация ВНЕ подписки Claude — правки кода, новые модули, рефакторинг по образцу, починка тестов. Работу выполняет Codex CLI (подписка ChatGPT) с правом записи в репозиторий строго в пределах обязательного `scope`, Claude платит только за постановку задачи и ≤5 строк выжимки. Отчёт и полный лог кладёт в ~/.claude/codex-runs/, в чат — короткая выжимка + путь. Ревью и приёмку делает отдельный агент Claude, не этот. {{CODEX_REQUIRED_INPUTS_SUMMARY}} {{CODEX_STOP_SUMMARY}}
+description: Имплементация ВНЕ подписки Claude — правки кода, новые модули, рефакторинг по образцу, починка тестов. Работу выполняет Codex CLI (подписка ChatGPT) с правом записи в репозиторий строго в пределах обязательного `scope`, Claude платит только за постановку задачи и ≤5 строк выжимки. Отчёт и полный лог кладёт в корень прогонов (`codex-bridge doctor` → `runsRoot`; по умолчанию `~/.lyupro/.codex-bridge/runs/`), в чат — короткая выжимка + путь. Ревью и приёмку делает отдельный агент Claude, не этот. {{CODEX_REQUIRED_INPUTS_SUMMARY}} {{CODEX_STOP_SUMMARY}}
 model: haiku
 tools: Bash
 ---
@@ -102,7 +102,7 @@ some files could not be judged.
   separate
   line, the runner reports whether the worktree was left touched, because a run interrupted
   halfway is more dangerous than one that never happened. Do not restart.
-- `UNAVAILABLE` — Codex is missing or signed out (checked before start, or recognised from the CLI's own
+- `UNAVAILABLE` — Codex is signed out (checked before start, or recognised from the CLI's own
   sign-in refusal after start). The task was not attempted or could not run; this is not a task failure and
   not a reason to restart — return the block as is, the orchestrator hands the task to the next executor.
 
@@ -123,10 +123,11 @@ without the orchestrator's `continue:` or `retry:` grant in the task-file header
 
 ## Codex is unavailable
 
-The runner looks `codex` up on PATH and asks `codex login status` before starting. A missing binary
-or the measured "Not logged in" answer prints a ready-made `UNAVAILABLE` block (first line
-`UNAVAILABLE — `, exit 5, no run folder). An unclear probe prints an ordinary refusal starting
-`Codex CLI unavailable:` (exit 1). Return that output verbatim.
+The runner looks `codex` up on PATH and retries once after ~1 s. If the lookup still fails, it prints
+an ordinary refusal starting `Codex CLI readiness unconfirmed:` (exit 1, no run folder).
+When found, it asks `codex login status` before starting. The measured "Not logged in" answer prints
+a ready-made `UNAVAILABLE` block (first line `UNAVAILABLE — `, exit 5, no run folder). Any other unclear
+probe prints an ordinary refusal starting `Codex CLI unavailable:` (exit 1). Return that output verbatim.
 Implementing the task instead of Codex is prohibited for any reason it fails.
 
 ## What a violation looks like

package/src/{agents → claude/agents}/codex-review.md

@@ -80,7 +80,7 @@ and the wait can be repeated for free, so neither has any reason to restart anyt
 - `LIMIT` — the result is empty and the log signals a limit. The ChatGPT quota is exhausted, and the
   review was not
   completed; this is not a review failure and not a reason to restart.
-- `UNAVAILABLE` — Codex is missing or signed out (checked before start, or recognised from the CLI's own
+- `UNAVAILABLE` — Codex is signed out (checked before start, or recognised from the CLI's own
   sign-in refusal after start). The task was not attempted or could not run; this is not a task failure and
   not a reason to restart — return the block as is, the orchestrator hands the task to the next executor.
 
@@ -98,10 +98,11 @@ Token spending now goes into `meta.json` (the `review` subcommand did not print
 
 ## Codex is unavailable
 
-The runner looks `codex` up on PATH and asks `codex login status` before starting. A missing binary
-or the measured "Not logged in" answer prints a ready-made `UNAVAILABLE` block (first line
-`UNAVAILABLE — `, exit 5, no run folder). An unclear probe prints an ordinary refusal starting
-`Codex CLI unavailable:` (exit 1). Return that output verbatim.
+The runner looks `codex` up on PATH and retries once after ~1 s. If the lookup still fails, it prints
+an ordinary refusal starting `Codex CLI readiness unconfirmed:` (exit 1, no run folder).
+When found, it asks `codex login status` before starting. The measured "Not logged in" answer prints
+a ready-made `UNAVAILABLE` block (first line `UNAVAILABLE — `, exit 5, no run folder). Any other unclear
+probe prints an ordinary refusal starting `Codex CLI unavailable:` (exit 1). Return that output verbatim.
 
 ## What a violation looks like
 

package/src/{agents → claude/agents}/codex-scout.md

@@ -1,6 +1,6 @@
 ---
 name: codex-scout
-description: Разведка и диагностика ВНЕ подписки Claude — исследование кодовой базы, поиск причины бага, ревью, сбор фактов. Работу выполняет Codex CLI (подписка ChatGPT), Claude платит только за постановку задачи и ≤5 строк выжимки. Строго read-only: писать в репозиторий физически не может. Подробный отчёт кладёт в ~/.claude/codex-runs/, в чат — короткая выжимка + путь. {{CODEX_REQUIRED_INPUTS_SUMMARY}} {{CODEX_STOP_SUMMARY}}
+description: Разведка и диагностика ВНЕ подписки Claude — исследование кодовой базы, поиск причины бага, ревью, сбор фактов. Работу выполняет Codex CLI (подписка ChatGPT), Claude платит только за постановку задачи и ≤5 строк выжимки. Строго read-only: писать в репозиторий физически не может. Подробный отчёт кладёт в корень прогонов (`codex-bridge doctor` → `runsRoot`; по умолчанию `~/.lyupro/.codex-bridge/runs/`), в чат — короткая выжимка + путь. {{CODEX_REQUIRED_INPUTS_SUMMARY}} {{CODEX_STOP_SUMMARY}}
 model: haiku
 tools: Bash
 ---
@@ -67,7 +67,7 @@ An empty `answer` is FAIL with a path to the log, not a reason to choose differe
 - `LIMIT` — the result is empty and the log signals a limit. The ChatGPT quota is exhausted, and the
   task was not
   completed; this is not a task failure and not a reason to restart.
-- `UNAVAILABLE` — Codex is missing or signed out (checked before start, or recognised from the CLI's own
+- `UNAVAILABLE` — Codex is signed out (checked before start, or recognised from the CLI's own
   sign-in refusal after start). The task was not attempted or could not run; this is not a task failure and
   not a reason to restart — return the block as is, the orchestrator hands the task to the next executor.
 
@@ -85,10 +85,11 @@ which is the runner telling you the answer is on disk already.
 
 ## Codex is unavailable
 
-The runner looks `codex` up on PATH and asks `codex login status` before starting. A missing binary
-or the measured "Not logged in" answer prints a ready-made `UNAVAILABLE` block (first line
-`UNAVAILABLE — `, exit 5, no run folder). An unclear probe prints an ordinary refusal starting
-`Codex CLI unavailable:` (exit 1). Return that output verbatim.
+The runner looks `codex` up on PATH and retries once after ~1 s. If the lookup still fails, it prints
+an ordinary refusal starting `Codex CLI readiness unconfirmed:` (exit 1, no run folder).
+When found, it asks `codex login status` before starting. The measured "Not logged in" answer prints
+a ready-made `UNAVAILABLE` block (first line `UNAVAILABLE — `, exit 5, no run folder). Any other unclear
+probe prints an ordinary refusal starting `Codex CLI unavailable:` (exit 1). Return that output verbatim.
 Performing the task manually instead of Codex is prohibited for any reason it fails.
 
 ## What a violation looks like

package/src/{commands → claude/commands}/usage.md

@@ -11,9 +11,9 @@ allowed-tools: Bash
 Count how much ChatGPT quota the runs delegated to Codex burned. This is spending on the Codex side,
 not on the Claude side.
 
-The root of the run folders comes from `CODEX_RUNS_ROOT` when it is set, otherwise from
-`~/.claude/codex-runs` — the same order the runner itself uses, because otherwise the accounting
-would stop seeing runs whenever the root is overridden.
+The root of the run folders comes from the runner's own resolver, so usage counts exactly where
+runs are written: the `CODEX_RUNS_ROOT` override, `~/.lyupro/.codex-bridge/runs/` after the move,
+or `~/.claude/codex-runs/` while the move is pending.
 
 The source is the `meta.json` in each run folder: it holds the spending, the model and the sandbox.
 Transport files are not kept in git and may be deleted, so parsing them is not allowed — the
@@ -33,11 +33,14 @@ Run exactly this command and recompute nothing by hand:
 
 ```bash
 node -e "
-const fs=require('fs'),path=require('path');
-const root=(process.env.CODEX_RUNS_ROOT||'').trim()||path.join(process.env.USERPROFILE||process.env.HOME,'.claude','codex-runs');
+const fs=require('fs'),path=require('path'),os=require('os');
+const home=(process.env.CODEX_BRIDGE_HOME||'').trim()||path.join(os.homedir(),'.lyupro','.codex-bridge');
+import(require('url').pathToFileURL(path.join(home,'lib','runner','runs-root.mjs')).href).then(m=>{
+const root=m.runsRoot();
 if(!fs.existsSync(root)){console.log('No runs yet.');process.exit(0)}
 const runs=[],unknown=[];
 for(const proj of fs.readdirSync(root)){
+  if(proj==='.git')continue;
   const pdir=path.join(root,proj);
   if(!fs.statSync(pdir).isDirectory())continue;
   let repo=null;
@@ -81,6 +84,7 @@ if(runs.length){
   console.log('');console.log('Most expensive runs:');
   runs.sort((a,b)=>b.tokens-a.tokens).slice(0,5).forEach(r=>console.log('  '+fmt(r.tokens).padStart(11)+'  '+r.proj+'/'+r.run));
 }
+}).catch(e=>{console.error(e.message);process.exit(1)});
 "
 ```
 

package/src/claude/rules/core.md

@@ -0,0 +1,29 @@
+# codex-bridge — delegation core
+
+Installed and removed by the `codex-bridge` package; `codex-bridge update` keeps it equal to the package. Change the
+package, not this file.
+
+Four dispatcher agents run work on a Codex CLI subscription: `codex-scout` (read-only research), `codex-build`
+(writes code inside its `scope`), `codex-review` (second opinion on a diff) and `codex-advisor` (design advice before
+code: a `scope` phase, then `advise`).
+
+- The call is one line, `task file: <absolute path>`. Labels go in the task-file header, free text in its body. A
+  refused call costs nothing: read the refusal, fix the task file, call again.
+- Before writing a task file, run `codex-bridge guidance <topic>` and follow it: `order` (header labels, scope),
+  `advisor` (two phases, the `continue:` grant), `budget` (run deadline, slicing), `records` (finding and reading
+  runs), `concurrency` (parallel and writing runs). `codex-bridge guidance` lists the topics. If it fails, stop and
+  show its output to the operator — never guess the contract.
+- Every `codex-build` task file carries exactly one `advice:` line.
+- A writing run has a hard deadline: slice the task before the launch, not after a failure. After a deadline `FAIL`,
+  look at `git status` before deciding anything.
+- One writing run per working tree; read-only runs may go alongside it.
+- `LIMIT` means the ChatGPT quota window is spent, `UNAVAILABLE` means Codex is signed out on this host. Neither is a
+  task error: do not retry the same bridge.
+  A refusal starting `Codex CLI readiness unconfirmed` is not `UNAVAILABLE`: do not skip the bridge; follow its second
+  line — check `codex --version` for up to ~2 minutes, then repeat the same order exactly once if it answers, otherwise
+  hand it to the next executor and name that in the summary. If the repeat gets the same refusal, hand it to the next
+  executor too; no second repeat.
+- `OK — scope: insufficient` from `codex-advisor` is a success: it names the paths the `advise` phase needs.
+- Stop a live run with `codex-bridge stop <run>` before `TaskStop`; `TaskStop` alone leaves the run writing.
+- A run's folder is the `ATTACH=` path in the dispatcher's reply. Earlier runs: `codex-bridge projects [<project>]
+  --json`; render one with `codex-bridge read <run>`. Never derive the run root from where the package is installed.

package/src/{rules → codex/rules}/codex-bridge.rules

@@ -1,6 +1,6 @@
 # codex-bridge installs this file to constrain delegated Codex runs.
 # It exists because a delegated run must not rewrite the operator's repository history or branches.
-# Check it with: codex execpolicy check --rules src/rules/codex-bridge.rules -- <command> <args>.
+# Check it with: codex execpolicy check --rules src/codex/rules/codex-bridge.rules -- <command> <args>.
 # Codex combines this file with other active rule files, and the strictest matching decision wins.
 # Known limit: prefix rules cannot detect shell redirection into .git/HEAD or equivalent indirect writes.
 

package/src/home/guidance/advisor.md

@@ -0,0 +1,42 @@
+# advisor
+
+Use a scope pass and a granted advise pass under one order id to obtain an evidence-backed design recommendation.
+
+## Two phases, one order
+
+Start with `phase: scope`. This read-only pass checks whether the supplied paths cover the question and names missing paths and expected risks.
+
+Continue with `phase: advise` under the same order id. Its task-file header must contain a `continue:` grant naming the successful scope run by its bare run-folder name (the last segment of the `RUN=`/`ATTACH=` path, never a path), with a reason for proceeding: `continue: <run folder> — <reason>`. The grant authorizes the second phase; a successful scope result alone does not grant it.
+
+`OK — scope: sufficient` means the supplied context covers the question. `OK — scope: insufficient; N paths named` with a `Missing:` line is also success: it identifies the context advise needs. It is not FAIL or LIMIT. The advise boundary includes the original paths and that scope result's `missing_paths`.
+
+Never continue a successful scope as another scope: that would consume the continuation intended for advise. A failed scope or advise pass is repeated only with a `retry:` grant naming that failed run, under the same order id. A changed question needs a new scope pass.
+
+## Task-file bodies
+
+Both phases use the following body form after the lowercase header and a blank line:
+
+```markdown
+## Question
+Which boundary should own the validation contract?
+
+## Options
+- local-boundary: Keep validation within the owning component.
+- shared-contract: Share validation between the consuming components.
+
+## Paths
+- src/component.mjs
+- tests/component.test.mjs
+```
+
+`## Question` contains the design question. `## Options` contains at least two unique option ids matching `[a-z0-9][a-z0-9-]*`, each on a `- <option_id>: <description>` line. Keep options neutral: no preference markers or wording such as `recommend`, `prefer`, `рекоменд`, `предпочт`, `(✓)` or `★`. Biased or malformed options are refused before quota is spent.
+
+`## Paths` contains at least one repository-relative path, one per list line. In scope, these are the read boundary. In advise, the successful scope run's `missing_paths` are also available. Citations must be real `path:line` addresses within that boundary; invented or out-of-list addresses fail validation.
+
+For the scope task, declare the scope phase in the header and supply this question, neutral options and initial paths. For the advise task, declare the advise phase and the continuation grant in the header, preserving the question and options and incorporating the scope findings.
+
+## Use the answer
+
+An advise answer recommends one option id and explains the choice, rejects alternatives with their costs, gives the strongest counterargument and a pre-mortem of risks. Its short form begins `OK — recommend <option_id>: …` and includes `Rejected:`, `Counter:` and `Risks:`. The full structured result and report stay in the run folder.
+
+To cite it in a build task, use exactly one `advice:` line whose value is the absolute folder of the successful advise run. Its `meta.json` must identify `codex-advisor`, phase advise, status OK. A scope folder, report filename, failed advise or recommendation text is not a valid advice reference.

package/src/home/guidance/budget.md

@@ -0,0 +1,37 @@
+# budget
+
+Slice each order before launch so its work and verification fit the agent's hard wall-clock deadline.
+
+## Budgets
+
+The agent registry defines these budgets:
+
+| Agent | Phase | Minutes |
+| --- | --- | --- |
+| codex-scout | — | 15 |
+| codex-build | — | 25 |
+| codex-review | — | 20 |
+| codex-advisor | scope | 10 |
+| codex-advisor | advise | 25 |
+
+Advisor phases have separate deadlines; scope and advise are not one combined writing budget. The deadline is enforced by the runner, not an estimate to extend while work is in progress.
+
+## Slice a writing run
+
+Keep a build order to one layer and a few writing files, normally 1–3 plus their targeted tests. Split cross-layer changes into separately verifiable orders before launch. Account for reading, implementation and verification within the same 25 minutes.
+
+The task file must say:
+
+- The concrete result and exact write scope, including any new files.
+- The budget, the small set of sources to read, and an instruction to implement immediately without exploring beyond those sources.
+- The behavior to preserve and what remains outside this slice.
+- The targeted check under `## Verify`, as one command line.
+- No full suite, build or smoke inside the run; leave broad integration checks outside this slice.
+
+Do not turn a small implementation order into a repository audit. Narrow the order rather than hoping the deadline will spare unfinished work.
+
+## After a deadline FAIL
+
+Inspect `git status` and the working-tree diff first: deadline termination can leave useful or incomplete changes. Then inspect the available result, report and events, using `codex-bridge read <run>` to render the event stream. Check which requested work and verification actually completed before deciding the next order.
+
+Never resend the same order unchanged. Preserve the existing work and define a smaller remaining slice with an appropriate `continue:` or `retry:` grant and its reason. A deadline FAIL is not evidence that nothing was written or that the work is complete.

package/src/home/guidance/concurrency.md

@@ -0,0 +1,17 @@
+# concurrency
+
+Run readers in parallel while keeping every writing run exclusive to its working tree.
+
+## Readers and writers
+
+Read-only `codex-scout`, `codex-review` and both `codex-advisor` phases may run in parallel freely, including alongside a writing run.
+
+Only one writing run may be active in a working tree. A second writing run in that tree is refused, even when the two orders name different files. Parallel writers require separate worktrees, each with its own working tree and write boundary.
+
+The writing runner snapshots the tree before and after its run, then compares the actual changes with the reported files and order scope. Another writer's edits enter that same snapshot and appear to belong to this run. Disjoint file lists therefore do not isolate writers in one tree. Keep other file-changing operations out of a live writer's tree as well.
+
+## Stop a live run
+
+Use the run path from its receipt and call `codex-bridge stop <run>` before `TaskStop`. The bridge stop terminates the Codex run and records FAIL. `TaskStop` alone stops the dispatcher task while the Codex process can keep writing.
+
+Inspect the resulting status and working-tree changes before launching another writer. Stopping a run does not undo the files it already changed.

package/src/home/guidance/order.md

@@ -0,0 +1,66 @@
+# order
+Write a task file that gives each dispatcher the complete order and the build's file boundary.
+
+## Call and header
+
+The call is exactly one line: `task file: <task-file path from the orchestrator>`.
+The path must be absolute and name a file the orchestrator wrote with its file tool.
+The dispatcher never creates, reads or rewrites it. The whole order lives in that file's header.
+The runner checks the header, never the dispatcher. Free text belongs in the task file.
+
+Start at the first line with consecutive lowercase `label: value` lines, then a blank line and the task body.
+Labels must use their exact spelling, start at column one and have a non-empty value; duplicates are refused.
+The header ends at the first line that is not a recognized label line, including a blank line.
+Do not put grants or advice below the header, even in a code fence; quote examples with `>` or reword them inside a sentence.
+
+| Agent | Required labels | Conditional labels | Optional labels |
+| --- | --- | --- | --- |
+| codex-scout | `order id` | `continue`, `retry` | `repository`, `slug`, `effort` |
+| codex-build | `order id`, `scope`, `advice` | `continue`, `retry` | `repository`, `scope new`, `slug`, `effort` |
+| codex-review | `order id` | `continue`, `retry` | `repository`, `slug`, `effort`, `changeset` |
+| codex-advisor | `order id`, `phase` | `continue`, `retry` | `repository`, `slug`, `effort` |
+
+Both grant labels are conditional when this pass continues or repeats a named run. Keep exactly one grant label:
+`continue` names the continued run; `retry` repeats a failed pass and does not authorize the next pass.
+Each value names a bare run folder (not a path, `.` or `..`) and a non-placeholder reason, separated by ` — `, ` - ` or `:`.
+For advisor, pass `scope` first, then `advise` with a `continue:` grant naming the scope run of the same order.
+
+`repository` is the repository path; `slug` names this pass without replacing the order id.
+The runner checks accepted `effort` values. `changeset` is `uncommitted`, `base:<branch>` or `commit:<sha>`.
+Keep header values short and free of forbidden shell sequences. Empty or placeholder values are refused;
+`phase: scope` and `effort: none` are real values.
+
+## File boundary
+
+`scope`: Comma-separated globs relative to the repository root, listing every file the run may touch — including each caller of what changes, not only the file being edited. Anything outside the list fails the run.
+
+`scope new`: Comma-separated globs for new files this build may create, relative to the repository root.
+`scope` must declare at least one existing path pattern; `scope new` does not replace it.
+Never name service folders in scope: `.git/`, `.claude/`, `.codex/`, `.omx/`, `node_modules/`.
+
+Example build header:
+
+```text
+order id: guidance-order-text
+scope: tests/guidance-topics.test.mjs
+scope new: src/home/guidance/order.md
+advice: docs-only
+
+```
+
+## Advice
+
+Every build task header contains exactly one `advice:` line. Its value is an absolute path to an existing run folder
+whose `meta.json` identifies a `codex-advisor` advise pass with status `OK`, or exactly `mechanical`, `revert`,
+`docs-only`, or `test-only`. Anything else is refused before the run starts.
+
+## Verify
+
+Put the verification command in the task file under a `## Verify` heading, one line.
+The dispatcher never reads that file and never puts the command on the command line.
+
+## Free refusals
+
+A pre-start refusal creates no run folder and spends no quota; the same order id remains reusable for the corrected order.
+A refusal is the dispatcher's whole answer, not a reason to change the call or task file and retry itself.
+Repeating the same call for a run already in flight joins that run and costs no quota; a different piece of work needs a new label.

package/src/home/guidance/records.md

@@ -0,0 +1,32 @@
+# records
+
+Find run artifacts through runner receipts and the project inventory without naming or deriving a run-store root.
+
+## Find a run
+
+Use the absolute run-folder path printed in the runner's `RUN=` or `ATTACH=` line. Keep that returned path as the run identity; do not reconstruct it from a timestamp, project name, package installation, home directory or another run.
+
+For earlier runs, use `codex-bridge projects [<project>] --json`. Use the run object's `path` field, which is the absolute run-folder path. If no project is supplied, first find the project in the inventory; do not concatenate names to invent a path.
+
+Render the selected run with `codex-bridge read <run>`, passing the returned run path. This renders its structured event stream. The inventory and receipt are the lookup contract; diagnostics are not a substitute for them.
+
+## Read the artifacts
+
+A started run records its lifecycle and output in its run folder:
+
+- `meta.json`: agent, phase and final status; use it to identify an advisor advise pass before citing it in `advice:`.
+- `status.json`: lifecycle state (`running`, `finished`, `failed` or `abandoned`) and runner PID.
+- `result.json`: structured scout, build or advisor result; build includes `summary`, `changes`, `verify_command`, `verify_passed`, `leftovers` and `report_markdown`.
+- `review.json`: the review agent's structured result instead of `result.json`.
+- `report.md`: the full report; the runner expands a build result's `report_markdown` into this file.
+- `events.jsonl` and `stderr.log`: transport evidence for progress, deadline or startup failures.
+
+A failed or interrupted run may have no complete result. Read the recorded status and available evidence rather than treating a missing report as an empty successful run.
+
+## Availability verdicts
+
+`LIMIT` means the ChatGPT quota window is exhausted, not a task defect. For a writing run, also check the runner's indication of whether the tree was touched.
+
+`UNAVAILABLE` means Codex is signed out on this host; the task could not run. A pre-start availability refusal may leave no run folder. Neither verdict is a reason to retry the same bridge. Preserve the verdict and any existing artifacts.
+
+A refusal starting `Codex CLI readiness unconfirmed:` is not `UNAVAILABLE`: it leaves no run folder and costs no quota. Do not skip the bridge; follow its second line — check `codex --version` for up to ~2 minutes. When it answers, repeat the same order exactly once; if it does not, hand the order to the next executor and name that in the summary. If the repeat gets the same refusal, hand the order to the next executor as well; no second repeat.

package/src/home/hooks/live-runs.mjs

@@ -107,7 +107,8 @@ export function allLiveRuns(runsRoot, options = {}) {
   }
   const result = [];
   for (const project of projects) {
-    if (!project.isDirectory()) continue;
+    // Plan_77 B5b makes the moved store a git repository; its metadata is not a project.
+    if (!project.isDirectory() || project.name === '.git') continue;
     result.push(...liveRuns(path.join(runsRoot, project.name), options));
   }
   return result;

package/src/home/hooks/load-witness.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/**
+ * Plan_64 D11: only InstructionsLoaded witnesses the host loading the rules core.
+ * The 2026-10-10 live run fired before the transcript existed, so persist now and resolve later.
+ * Observation must never refuse a host action, including doctor's empty-stdin dry run.
+ */
+import fs from 'node:fs';
+import { BRAND_STATE_DIR } from '../lib/brand-home.mjs';
+import { parseJsonText } from '../lib/json-file.mjs';
+import { recordCoreLoad } from '../lib/load-witness.mjs';
+
+try {
+  const raw = fs.readFileSync(0, 'utf8');
+  if (raw.trim()) {
+    const input = parseJsonText('stdin', raw);
+    if (input && typeof input === 'object' && !Array.isArray(input)) {
+      await recordCoreLoad({ stateDir: BRAND_STATE_DIR, input });
+    }
+  }
+} catch {
+  // D11: lost evidence is not a refusal; preserve corrupt state for inspection.
+}
+process.exit(0);

package/src/home/lib/claude-layout.mjs

@@ -8,6 +8,7 @@ export function claudePaths(root) {
   return {
     agentsDir: path.join(root, 'agents', 'codex-bridge'),
     commandsDir: path.join(root, 'commands', 'codex-bridge'),
+    rulesDir: path.join(root, 'rules', 'codex-bridge'),
     legacyAgentsDir: path.join(root, 'agents', 'codex'),
     legacyCommandsDir: path.join(root, 'commands', 'codex'),
   };

package/src/home/lib/codex-home.mjs

@@ -0,0 +1,8 @@
+/** Keeps one Codex home resolver for readers and the path currently built inline in cli/hosts.mjs:26. */
+import os from 'node:os';
+import path from 'node:path';
+
+export function resolveCodexHome({ env = process.env, homedir = os.homedir() } = {}) {
+  return typeof env.CODEX_HOME === 'string' && env.CODEX_HOME.length > 0
+    ? env.CODEX_HOME : path.join(homedir, '.codex');
+}

package/src/home/lib/home-registry.mjs

@@ -90,6 +90,13 @@ const entries = [
     primary: ['state/dispatcher-model.json'],
     sides: ['lock', 'atomic-temporary'],
   },
+  {
+    id: 'runs-move-record',
+    removal: 'purge-only',
+    consequence: 'The package forgets that run records moved, and new runs write to the old store again while it still exists.',
+    primary: ['state/runs-root.json'],
+    sides: ['atomic-temporary'],
+  },
   {
     id: 'host-observations',
     removal: 'purge-only',
@@ -97,6 +104,13 @@ const entries = [
     primary: ['state/host-observations.json'],
     sides: ['lock', 'atomic-temporary'],
   },
+  {
+    id: 'load-witness',
+    removal: 'purge-only',
+    consequence: 'Doctor forgets which sessions witnessed the rules core loading until the next session start.',
+    primary: ['state/load-witness.json'],
+    sides: ['lock', 'atomic-temporary'],
+  },
   {
     id: 'guard-tries',
     removal: 'purge-only',
@@ -124,6 +138,13 @@ export const HOME_ARTIFACTS = Object.freeze(entries.map((entry) => Object.freeze
   sides: Object.freeze([...entry.sides]),
 })));
 
+/**
+ * Plan_77 D1: run records live in this folder of the home once they move out of ~/.claude. They are
+ * operator data, not an artifact of the package: the folder is never walked or removed, and naming it
+ * here keeps the resolver and the removal plan on one spelling.
+ */
+export const RUN_RECORDS_DIR = 'runs';
+
 export const HOME_DIRECTORIES = Object.freeze([
   'state',
   'state/dispatchers',

package/src/home/lib/hook-definitions.mjs

@@ -67,6 +67,8 @@ export const LOCKED_TOOL_MATCHER = [...WRITE_TOOLS, ...SHELL_TOOLS].join('|');
  * dispatcher must consume this one list instead of guessing a name from a path at its call site.
  */
 export const HOOK_DEFINITIONS = Object.freeze([
+  // Plan_64 D11: loading evidence observes only; this hook can never refuse anything.
+  Object.freeze({ name: 'load-witness', event: 'InstructionsLoaded', matcher: '*', file: 'load-witness.mjs' }),
   Object.freeze({ name: 'reply-guard', event: 'SubagentStop', matcher: '*', file: 'reply-guard.mjs' }),
   Object.freeze({ name: 'order-gate', event: 'PreToolUse', matcher: SUBAGENT_TOOL_MATCHER, file: 'order-gate.mjs' }),
   Object.freeze({ name: 'worktree-lock', event: 'PreToolUse', matcher: LOCKED_TOOL_MATCHER, file: 'worktree-lock.mjs' }),

package/src/home/lib/host-version.mjs

@@ -1,24 +1,43 @@
-/** Reads the host version from the transcript tail after the 2026-09-25 PATH host identity incident. */
+/** Reads the host version from a session transcript after the 2026-09-25 PATH host identity incident. */
 import fs from 'node:fs/promises';
 import { parseJsonText } from './json-file.mjs';
 
-export async function transcriptHostVersion(transcriptPath, { tailBytes = 65536 } = {}) {
+const VERSION = /^\d+\.\d+\.\d+/;
+
+function versionIn(transcriptPath, lines, sessionId, newestFirst) {
+  const order = newestFirst ? [...lines.keys()].reverse() : lines.keys();
+  for (const index of order) {
+    try {
+      const entry = parseJsonText(transcriptPath, lines[index]);
+      // Plan_64 D11: a neighboring session's version cannot identify this load witness.
+      if (sessionId && entry?.sessionId !== sessionId) continue;
+      if (typeof entry?.version === 'string' && VERSION.test(entry.version)) return entry.version;
+    } catch {}
+  }
+  return null;
+}
+
+async function slice(handle, position, length) {
+  const buffer = Buffer.alloc(length);
+  await handle.read(buffer, 0, length, position);
+  return buffer.toString('utf8').split(/\r?\n/);
+}
+
+/**
+ * A live session's newest lines name its host, so the tail answers the shell-command observers. A finished session
+ * may end in a 135 KB attachment line and metadata without `version` (B6b live run, 2026-10-10), so a named session is
+ * also looked up from the head: one session runs on one host, and its first user line already carries the version.
+ */
+export async function transcriptHostVersion(transcriptPath, { tailBytes = 65536, headBytes = 1048576, sessionId } = {}) {
+  const session = typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : null;
   try {
     const handle = await fs.open(transcriptPath, 'r');
     try {
       const { size } = await handle.stat();
-      const length = Math.min(size, tailBytes);
-      const buffer = Buffer.alloc(length);
-      await handle.read(buffer, 0, length, size - length);
-      const lines = buffer.toString('utf8').split(/\r?\n/);
-      for (let index = lines.length - 1; index >= 0; index -= 1) {
-        try {
-          const entry = parseJsonText(transcriptPath, lines[index]);
-          if (typeof entry?.version === 'string' && /^\d+\.\d+\.\d+/.test(entry.version)) {
-            return entry.version;
-          }
-        } catch {}
-      }
+      const tailLength = Math.min(size, tailBytes);
+      const fromTail = versionIn(transcriptPath, await slice(handle, size - tailLength, tailLength), session, true);
+      if (fromTail !== null || !session) return fromTail;
+      return versionIn(transcriptPath, await slice(handle, 0, Math.min(size, headBytes)), session, false);
     } finally {
       await handle.close();
     }