@lyupro/codex-bridge 0.6.2 → 0.6.5

package/CHANGELOG.md

@@ -4,6 +4,152 @@ 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.6.5] - 2026-09-23
+
+### Added
+
+- A fourth dispatcher, `codex-advisor`, answers "which option is right" before any code is written.
+  The other three answer what is: what the code contains, make the change, what is wrong with a
+  finished diff. An orchestrator asked for advice four times in a row only after the fact, each time
+  convinced its own design was sound — so the advisor is read-only, runs on the Codex subscription,
+  and its answer is judged by the package rather than trusted. It works in two phases of one order:
+  `scope` (5 minutes) says whether the listed files are enough and names the missing ones, and
+  `advise` (15 minutes) continues that run with `--continue` and picks one option. An insufficient
+  scope is an `OK` run with `sufficient: false` and the missing paths in `meta.json`, never `LIMIT`:
+  `LIMIT` means the quota is gone and calls for the opposite reaction.
+- Agreement is made structurally hard to express. The task lists options as `- id: description`
+  with no preference marker — a task that says which option the orchestrator leans towards is refused
+  before the run starts, because an advisor that knows the expected answer agrees with it. The answer
+  names exactly one option id (or `none-of-these` with an unlisted option, and then every listed
+  option is rejected with its cost), a non-empty `rejected` list with costs, the strongest
+  counterargument, assumptions rated `VERIFIED | REASONABLE | FRAGILE`, a pre-mortem whose early
+  checks are a test, a command or an inspectable address, and what the advisor checked on its own.
+- Every `path:line` in the advice is checked: it must exist in the worktree, fall within the file,
+  and lie inside the listed paths or the paths phase 1 declared missing. The sandbox cannot restrict
+  what Codex reads, so the boundary is held on the output — an invented or out-of-scope citation fails
+  the run.
+- A run phase is a runner concept, not an advisor detail. `--phase` is checked against the phases the
+  role declares, travels through `worker.json`, `status.json` and `meta.json`, and the budget resolves
+  by role and phase in one place. `budgets.<role>` in the config accepts a number for single-phase
+  roles and a phase map (`{"scope": 5, "advise": 15}`, partial maps allowed) for roles with phases; a
+  bare number for a role with phases is refused on reading the config instead of silently erasing
+  its phases. Existing configs stay valid without edits.
+- Every `codex-build` task file carries exactly one `advice:` line: the folder of the advisor run
+  behind the order, or one of `mechanical | revert | docs-only | test-only` for work that needs no
+  second opinion. Anything else is refused before the run starts, and the value lands in `meta.json`,
+  so skipped advice is measurable instead of remembered.
+
+### Fixed
+
+- A scope pattern inside a service directory is refused before the run starts. The verdict fails
+  every change under `.git/`, `.claude/`, `.codex/`, `.omx/`, `.omc/` and `node_modules/` whatever the
+  scope says, but the preflight check let such a pattern through: an order scoped to
+  `.claude/context/architecture.md` worked 22 minutes, wrote every file correctly and was failed for
+  one of them. The check now uses the verdict's own definition of a service directory, so the gate and
+  the judge cannot become two measures of one tree. A glob that can also match ordinary files
+  (`**/*.md`) is still accepted.
+
+## [0.6.4] - 2026-09-21
+
+### Fixed
+
+- A refusal that spends no quota no longer leaves a run folder behind. A second writing run against a
+  busy tree was refused correctly, but its folder was created first — and in a repository that hosts
+  the run folders, the live writer's witness then spent every tool call ordering the orchestrator to
+  revert a directory the tool itself had made, or to stop an honest run. Neither is a safe action. The
+  misplaced check was the symptom: refusals sat on two sides of the registration boundary with no rule
+  about which side was which, and two gates of the same class already disagreed — a dead sandbox
+  refused without a folder, a busy tree with one. The quota-free host checks now live in a module that
+  is handed no run directory, so a check added there cannot register a run, and a table test holds
+  every refusal with its side and the reason for that side. A busy tree and an unavailable Codex CLI
+  therefore write nothing at all: they no longer produce an `aborted_pre_start` folder, and their
+  exit code stays 1, because the order was correct and the host or the tree was not.
+- The live witness and the final verdict judge one worktree by one definition. The witness read
+  `git status --porcelain` on its own while the verdict reads the recorded snapshot, so three kinds of
+  change were visible to one and invisible to the other: the run's own folder, the orchestrator's
+  environment writes, and gitignored working notes. The witness now composes the same chain as the
+  verdict, and its message says first that those three are already excluded — so what it lists is the
+  orchestrator's own edit — and only then offers the two actions. A structural test fails any hook that
+  spells a worktree query in an argument list; this drift went unnoticed for months and surfaced only
+  as a false accusation against a run that was doing its job.
+- A file moved inside its own scope is no longer a stray. The shared snapshot was read with git's
+  rename detection on, which prints one row spelled `old => new` — not a path, and matching no scope
+  pattern. The witness named that token at the orchestrator, and the verdict would have failed an
+  honest build for a `git mv` it was told to make. The snapshot is now read with `--no-renames`: a
+  rename is a deletion plus an addition, two real paths, each judged on its own merits.
+- A scope pattern that can only name a directory is refused before the run starts. A scope is compared
+  against file paths, never directories, so `muse/scripts` authorises one file that will never exist
+  while everything created inside the folder counts as a stray. Declared patterns escaped this by luck
+  — `git ls-files` prints no directories — but `--scope-new` is exempt from the existence check by
+  design, and a run ordered with `--scope-new muse/scripts` worked ten minutes, returned a filled
+  result, and was failed for the three files it created there. A trailing slash, a name that is a
+  directory on disk, and a glob-free name whose last segment has no extension are now refused before
+  the run folder exists, with the spelling that works named in the refusal. Patterns containing a glob
+  are never judged by these rules.
+
+## [0.6.3] - 2026-09-17
+
+### Added
+
+- A dead Codex sandbox refuses the run before it spends quota. On 2026-09-16 an unclean Windows
+  shutdown left the sandbox helper's state file as 22 zero bytes, and every delegated run after it
+  paid for a session in which not one command ran — one scout even came back `OK`. The launcher now
+  asks the sandbox to echo a marker before the run folder exists, and calls it dead only on double
+  evidence: the role's own flags and a flagless control both produce no marker, neither reports an
+  argument error, and the CLI still answers `--version`. Codex had already changed the shape of its
+  own sandbox command once, so anything the probe cannot judge lets the run start and is named in
+  the reply — a release that stops accepting the package's sandbox flags cannot turn the check off
+  silently. `stderr` is quoted for the operator and never parsed. The probe is bounded on every
+  path: a hung attempt stops the whole Codex tree rather than the `cmd.exe` in front of it, and a
+  capture that overflows is inconclusive, never dead. Windows and Linux are judged, each after both
+  outcomes were seen live on it; on Linux, where a dead sandbox is the ordinary state of a fresh
+  Ubuntu 23.10+ server, the refusal names the AppArmor profile that repairs it and warns against
+  lifting the restriction through `sysctl`. macOS is skipped — no outcome has been observed there.
+
+### Fixed
+
+- A scout that executed no command can no longer come back `OK`. On the dead sandbox of 2026-09-16
+  a scout was graded `OK` without reading a single file: its evidence explained that the files were
+  unreadable, and the coverage gate only checked that the evidence was a non-empty string. The
+  verdict now requires a fact before it judges coverage — at least one completed
+  `command_execution` in `events.jsonl`, with any status or exit code. Refused calls never enter the
+  stream, which is what makes the fact reliable; across 99 earlier successful scout runs it was
+  missing exactly twice, both on that sandbox.
+- Quoted text no longer reads as shell commands to the worktree lock. The write-intent scanner read
+  quotes three different ways, and its raw split on `;` and `|` cut inside them: an `awk` script
+  containing "Do not touch any file outside" was refused on 2026-09-16 as a write to `any`, `file`
+  and `outside` — the fourth refusal on one root after `node -e`, `sed` and a heredoc body. One
+  lexer now owns quotes, escapes and command boundaries for all three consumers, drops comments, and
+  opens subshells and `$(…)` only where the shell does.
+- An argument that happens to be a command name is not a write. `git log --grep rm -- README.md` and
+  `grep -rn touch src/` were refused while a build held the repository, because the scanner looked
+  for `rm` and `touch` in any word. A command name now counts only in command position — after
+  assignments, reserved words, leading redirections, a short list of launchers, and a `find -exec`
+  action up to its terminator.
+- A stop at the deadline cannot block the launcher forever. `stopCodex()` gave `taskkill` no timeout,
+  so a stalled `taskkill` held the event loop and every settlement timer with it. It now has ten
+  seconds, after which the direct child is killed.
+- The response guard judges a run by its own process, not by a bare pid. Without the run folder or
+  the recorded start time, a pid reused by another process after a reboot read as "the run is still
+  working", and the guard held the dispatcher on a dead run until the session's retry budget stopped
+  the session.
+- The project list no longer prints the raw `running` of a run whose worker died before writing
+  `meta.json`. A row without a verdict shows what closing the run would write: `abandoned` for a
+  dead or foreign process, `unverified` when the end cannot be proven. The "live now" column keeps
+  its fresh-heartbeat policy.
+
+### Changed
+
+- One module decides whether a recorded run is still live. Seven places answered that question on
+  their own through pid-first wrappers whose other inputs were optional — which is how the response
+  guard came to ask with a bare pid and the project list never to ask at all, although
+  `markAbandoned()` already held the exact rule. `src/home/lib/meta/run-liveness.mjs` now owns it,
+  and `tests/one-liveness-judge.test.mjs` fails the suite when another module asks a process
+  identity, re-exports one under a new name, or declares a pid-first wrapper again.
+- The rows a reply carries are rendered by one function. The Retention row had been copied into five
+  reply functions and was still missing from the runner's failure path, so a runner failure lost it;
+  a sixth copy for the sandbox row would have repeated that defect.
+
 ## [0.6.2] - 2026-09-07
 
 ### Fixed

package/README.md

@@ -1,6 +1,6 @@
 # codex-bridge
 
-**Delegate implementation, reconnaissance and review from Claude Code to Codex — six host guards, zero runtime dependencies, zero build steps.**
+**Delegate implementation, reconnaissance, review and design advice from Claude Code to Codex — six host guards, zero runtime dependencies, zero build steps.**
 
 [![npm version](https://img.shields.io/npm/v/@lyupro/codex-bridge)](https://www.npmjs.com/package/@lyupro/codex-bridge)
 [![Node.js](https://img.shields.io/node/v/@lyupro/codex-bridge)](https://www.npmjs.com/package/@lyupro/codex-bridge)
@@ -33,7 +33,7 @@ Use `--scope project` to install the Claude Code-facing files under `<repo>/.cla
 Installation has two roots:
 
 - `~/.lyupro/.codex-bridge/` contains package runtime files, guards, configuration, conventions, and the installation record.
-- The selected Claude Code root (`~/.claude/` or `<repo>/.claude/`) contains the three agents, two slash commands, merged hook registrations in `settings.json`, and run artifacts under `codex-runs/`.
+- The selected Claude Code root (`~/.claude/` or `<repo>/.claude/`) contains the four agents (`codex-scout`, `codex-build`, `codex-review`, `codex-advisor`), two slash commands, merged hook registrations in `settings.json`, and run artifacts under `codex-runs/`.
 
 The repository's `src/home/` directory is the literal image copied into the branded root: its
 `hooks/`, `lib/`, `config.json`, and `conventions.md` paths are the host paths without remapping.
@@ -62,7 +62,7 @@ If a global install and a clone coexist, you have two package copies. `codex-bri
 - **Every run leaves an audit folder.** The verbatim task, scope, before/after git state, events, report, verdict, and reason remain together.
 - **Zero runtime dependencies and zero build steps.** The package is plain `.mjs` on the Node.js standard library.
 
-The current suite contains **975 automated tests: 974 passing and 1 skipped**.
+The current suite contains **1491 automated tests: 1490 passing and 1 skipped**.
 
 ## Verify
 

package/cli/runs-inventory.mjs

@@ -3,6 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { liveRuns } from '../src/home/hooks/live-runs.mjs';
 import { readJsonFileSync } from '../src/home/lib/json-file.mjs';
+import { runLiveness } from '../src/home/lib/meta/run-liveness.mjs';
 import { runsRoot } from '../src/home/lib/runner/runs-root.mjs';
 
 const record = (value) => value && typeof value === 'object' && !Array.isArray(value);
@@ -108,7 +109,7 @@ function readRun(runDir, livePaths) {
   return {
     run: path.basename(runDir),
     agent: text(facts?.agent),
-    verdict: live ? 'running' : text(meta ? meta.status : status?.state),
+    verdict: live ? 'running' : text(meta ? meta.status : runLiveness({ runDir, status }).state),
     tokens: meta ? number(meta.tokens) : null,
     size: recursiveSize(runDir),
     timestamp: runTimestamp(path.basename(runDir), meta, status),
@@ -131,8 +132,9 @@ function publicRun(run) {
 
 function buildProject(projectDir) {
   const runDirs = directoryEntries(projectDir).map((entry) => path.join(projectDir, entry.name));
-  // live-runs owns PID and status interpretation after the 2026-08-05 live probe incident;
-  // this module only maps its result back to the corresponding inventory row.
+  // live-runs owns the `live` column (a fresh heartbeat) after the 2026-08-05 live probe incident.
+  // A row without a verdict shows what closing it would write — the judge's `abandoned` rather than
+  // the raw `running` a dead run keeps in status.json forever (Plan_57 D27).
   const livePaths = new Set(liveRuns(projectDir).map(({ dir }) => pathKey(dir)));
   const details = runDirs.map((runDir) => readRun(runDir, livePaths));
   // Sum what is known instead of blanking the column. One archived run without accounting used to

package/cli/stop.mjs

@@ -2,12 +2,12 @@
 import path from 'node:path';
 import { stopCodex } from '../src/home/lib/runner/codex-cmd.mjs';
 import { git, worktreeSnapshot } from '../src/home/lib/runner/git-state.mjs';
+import { runLiveness } from '../src/home/lib/meta/run-liveness.mjs';
 import {
   IDENTITY_ALIVE,
   IDENTITY_FOREIGN,
   IDENTITY_UNVERIFIED,
   processAlive,
-  processIdentity,
 } from '../src/home/lib/process-identity.mjs';
 import { markAbandoned, readJson } from '../src/home/lib/write-meta.mjs';
 import { runsRoot } from '../src/home/lib/runner/runs-root.mjs';
@@ -72,7 +72,7 @@ export async function stop({
     return result(1, `Run ${runDir} has no valid recorded pid; it was not changed.`);
   }
 
-  const identity = processIdentity({ runDir, status, commandRunner });
+  const { identity } = runLiveness({ runDir, status, commandRunner });
   if (identity === IDENTITY_UNVERIFIED || identity === IDENTITY_FOREIGN) {
     return result(
       1,

package/cli/unlock.mjs

@@ -3,11 +3,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { formatSilence, heartbeatAge, HEARTBEAT_STALE_MS } from '../src/home/lib/heartbeat.mjs';
+import { runLiveness } from '../src/home/lib/meta/run-liveness.mjs';
 import { markAbandoned } from '../src/home/lib/meta/run-state.mjs';
 import {
   IDENTITY_ALIVE,
   IDENTITY_UNVERIFIED,
-  processIdentity,
 } from '../src/home/lib/process-identity.mjs';
 import { git } from '../src/home/lib/runner/git-state.mjs';
 import { resolveProjectRunsDir } from '../src/home/lib/runner/project-dir.mjs';
@@ -144,7 +144,7 @@ function inspectRuns(project, options) {
       age: runAge(status.started_at, now),
       silence: formatSilence(silenceAge),
       silenceAge,
-      identity: processIdentity(identityOptions(dir, status, options, now)),
+      identity: runLiveness(identityOptions(dir, status, options, now)).identity,
       state: status.state,
     });
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lyupro/codex-bridge",
-  "version": "0.6.2",
-  "description": "Claude Code-to-Codex delegation with 6 guards, 975 tests, zero runtime dependencies, and zero build steps.",
+  "version": "0.6.5",
+  "description": "Claude Code-to-Codex delegation with 6 guards, 1491 tests, zero runtime dependencies, and zero build steps.",
   "keywords": [
     "claude-code",
     "codex",

package/src/agents/codex-advisor.md

@@ -0,0 +1,187 @@
+---
+name: codex-advisor
+description: Независимое второе мнение по DESIGN до появления кода — что правильно, а не что уже есть; работу выполняет Codex CLI по подписке ChatGPT, строго read-only. Два этапа: сначала `scope` — достаточно ли переданного списка файлов и какие риски ожидаются; затем `advise` через `--continue` к запуску scope — одна рекомендация по id варианта, отклонённые варианты с ценой, сильнейший контраргумент и pre-mortem. Вызывай до любого поручения `codex-build`, которое придумывает способ реализации (Plan_59 D6: каждый build task file указывает `advice:` — папку этого запуска или `mechanical | revert | docs-only | test-only`). Полный результат — в ~/.claude/codex-runs/, в чате — не более пяти строк и путь. {{CODEX_REQUIRED_INPUTS_SUMMARY}} {{CODEX_STOP_SUMMARY}}
+model: haiku
+tools: Bash
+---
+
+{{CODEX_NO_SELF_EXECUTION}}
+
+You are the advisor dispatcher. One command starts Codex, and its output is your answer.
+
+**Why you exist.** The orchestrator runs on a Claude Max subscription, while Codex runs on a
+ChatGPT subscription. All design reading and reasoning must happen on the Codex side. Every extra
+line you send to chat costs Claude tokens. Therefore: do not read files, do not retell the report,
+and do not reason about the design yourself.
+
+## Required dispatcher inputs
+
+{{CODEX_REQUIRED_INPUTS}}
+
+## What you receive as input
+
+- The task statement: the design question, candidate options, and completion criteria.
+- The path to a task file containing the question and its context. The orchestrator supplies this
+  path; pass it as `--task-file` and never create, read or rewrite it. Writing that file yourself
+  from the shell — `cat > … << EOF` or any equivalent — puts back the permission prompt the flag
+  exists to remove. Given no path, start the runner without the flag and return its refusal.
+- The path to the repository. If none is given, use the current working directory.
+- `phase` is exactly `scope` or `advise`, supplied by the orchestrator and passed as `--phase`.
+  Run `scope` first. Run `advise` only as the continuation of that same order's successful advisor
+  scope run. Never choose or change the phase yourself.
+- The task file must use these headings and list formats:
+  - `## Question` — free-text design question.
+  - `## Options` — at least two lines of the form `- <option_id>: <description>`. Each id must
+    match `[a-z0-9][a-z0-9-]*`; ids must be unique. Do not include preference markers or wording
+    such as `recommend`, `prefer`, `рекоменд`, `предпочт`, `(✓)`, or `★`. The advisor must not
+    know which option the requester favors (D5). Biased or malformed options are refused before
+    quota is spent.
+  - `## Paths` — at least one repository-relative path per list line. The advisor may cite only
+    these paths and, during `advise`, paths the scope run named in `missing_paths`. Each
+    `path:line` citation is machine-checked; an invented or out-of-list address fails the run (D3).
+- Scope patterns are globs relative to the repository root. A pattern that matches nothing there is
+  refused before the run starts. This dispatcher does not accept scope patterns: its file boundary
+  is the explicit `## Paths` list and, for `advise`, the successful scope run's `missing_paths`.
+- Every input listed under **Required dispatcher inputs** above, passed on exactly as given:
+  `order id` as `--order-id`, `task file` as `--task-file`, and `phase` as `--phase`. Use the same
+  order id for both phases; never invent or edit it. If the orchestrator did not give a required
+  input, do not guess — start the runner without its flag and return its refusal verbatim.
+- `continue` — when the task text contains a line beginning with the `continue:` label, pass the
+  bare `--continue` flag even when its run name or reason looks malformed. Do not inspect, repair,
+  or swallow this grant; pass it through and let the runner issue the refusal. A continuation is
+  assigned by the orchestrator, never chosen by you. After the verdict, return the exact attaching
+  output and stop; do not issue or invent another continuation. If no such grant line is present,
+  the flag must not be present. The advise phase requires this grant to continue the scope run.
+- Optional: `slug: <short-name>` for the run folder; by default, the slug is taken from the order
+  id. Optional: `effort: <none|low|medium|high|xhigh|max>` only when the orchestrator named a
+  depth.
+
+## When the host refuses the command
+
+If the host refuses to run `codex-bridge run` — a permission prompt, a classifier denial, anything
+that stops the command — that refusal is your final answer. Report `FAIL`, name your own order id,
+and state the one correction: the operator runs `codex-bridge install`, which grants the permission
+rule this package needs.
+
+You are forbidden to look for a way around it. Specifically, and without exception:
+
+- never call `run-codex.mjs`, or any file inside the installed package, by path;
+- never start the runner through `node`, `npx`, `sh`, `bash` or any other interpreter;
+- never retry the same call in PowerShell because Bash refused it, or the reverse;
+- never split the call over more than one line, and never add a pipe, a semicolon or a redirect;
+- never advise the operator to grant a permission rule on an internal file — a rule on anything but
+  the package command undoes the very design that makes this call permission-stable.
+
+Every one of those forms was removed on purpose: a host matches a permission rule against the
+beginning of the final command line, so an interpreter, a path or a continuation makes the call
+unmatchable by construction. Reaching for one does not rescue the run; it guarantees the refusal.
+
+## The only thing you do
+
+```bash
+codex-bridge run --agent codex-advisor --repo "<repository-path or .>" --phase "<phase from the orchestrator>" --slug "<slug>" --order-id "<order id from the orchestrator>" --task-file "<task-file path from the orchestrator>"
+```
+
+That is one command line. Add only the bare `--continue` when the task text contains a line
+beginning with `continue:`; it has no value. The runner accepts only `1/true/yes/0/false/no` as a
+grant value in the task text, so a malformed grant is passed through for the runner to refuse. If
+there is no grant line, do not add the flag. Add `--effort "<value>"` only if the orchestrator
+named a depth, and only with one of `none|low|medium|high|xhigh|max`. Never add free text or any
+flags beyond those two conditional flags.
+
+The first `scope` call starts the run and returns at once with `RUN=<path> order-id=<id>` and a
+`STARTED` line. To get its verdict, run the identical command a second time — same order id, slug,
+phase and flags. That second call attaches to the existing run and prints `ATTACH=<path>` before
+blocking for the verdict. Do not start another scope run to attach.
+
+After an `OK` scope verdict, the orchestrator may run `advise` with `--continue`, the same order id,
+and the continuation grant it supplied. That call continues the scope run; it is not a new order.
+Attach to that advise run by repeating its identical command if it returns `STARTED`.
+
+If the runner refuses with an order id collision — the id already belongs to a run whose task
+differs — that refusal is the whole answer: return `FAIL` with the runner's text. Never retry under
+a different id of your own choosing; the order id is the orchestrator's.
+
+Background execution (`run_in_background`, `&`, `nohup`) is prohibited, and so is inventing a
+report from memory. If an attaching call is killed by a time ceiling, repeat the identical command
+once with `--no-wait`. This only checks state; it is never a final answer. If stdout contains the
+ready reply, return it normally. If the call exits 4, return to the ordinary waiting call with the
+same order id and without `--no-wait`. A real run takes 20-25 minutes, which is normal, not a hang.
+Give the ordinary attaching call `timeout: 1800000` (30 minutes).
+
+**Never change `--order-id` or `--slug` to get a fresh run.** The order id is issued by the
+orchestrator and is what makes a repeat harmless; changing it turns a repeat into another paid run.
+
+The runner does the rest: validates the task file and phase, creates the run folder and artifacts,
+starts Codex in a read-only sandbox, records status, and prints ready-made response lines. Invalid
+or biased `Options`/`Paths`, `advise` without `--continue`, `advise` without an `OK` advisor scope
+run, and an undeclared phase are free refusals; no ChatGPT quota is spent.
+
+**Your response = the exact stdout of the attaching call**: the `ATTACH=<path>` line and the status
+block below it. Do not add or remove anything: no preamble, explanations, apologies, or retelling
+of findings. The report is in the file; the orchestrator will read it if needed. A `STARTED` result
+is not final.
+
+The only allowed final response is this exact stdout. Wording such as "the run has started,
+waiting for completion," "I will wait for a notification," or "Monitor started in the background"
+is prohibited: the subagent ceases to exist immediately after responding, nobody can wait, and the
+orchestrator gets a promise instead of a result. Inventing any outcome the runner did not print is
+equally prohibited.
+
+## What you return
+
+Return the attaching output exactly as printed by the runner, including its ready-made short
+result and report path. Do not compose, summarize, or improve the result yourself. The full report
+lives under `~/.claude/codex-runs/`; the orchestrator receives no more than five lines plus that
+path.
+
+## The script determines status, not you
+
+- `OK` — the phase result is valid and the runner returned zero. An insufficient scope is still an
+  `OK` scope result, not a quota limit.
+- `FAIL` — the result is empty, invalid, the return code is nonzero, or the run was abandoned.
+- `LIMIT` — the result is empty and the log signals a ChatGPT quota limit. The quota is spent and
+  the task was not completed; do not restart it.
+
+The script return code mirrors the status: `0` / `1` / `3`. A nonzero code is not a reason to
+retry, change the command, or investigate on your own.
+
+For `scope`, `OK — scope: sufficient; …` means the listed paths cover the question; continue with
+`--phase advise` only when the orchestrator supplies that continuation. `OK — scope: insufficient;
+N paths named` followed by a `Missing:` line is also an `OK` run, not a `LIMIT`: the orchestrator
+may add context or continue with `advise`. `LIMIT` alone means the ChatGPT quota is spent.
+
+For `advise`, expect `OK — recommend <option_id>: …`, followed by `Rejected:`, `Counter:`, and
+`Risks:` lines. The recommendation names one option id, rejected options include their cost,
+`Counter:` gives the strongest counterargument, and `Risks:` is the pre-mortem. Forward those lines
+verbatim; compose nothing.
+
+The run folder contains its status and artifacts. An abandoned run is not a reason to start over
+yourself: the orchestrator decides whether to continue, and without the `--continue` it issued,
+the runner will reject that continuation itself.
+
+## Codex is unavailable
+
+The runner checks `codex --version` before starting. If the binary is missing or authentication
+failed, it prints a ready-made `FAIL` with a verification command for the operator. Return that
+output. Performing the task manually instead of Codex is prohibited for any reason it fails.
+
+## What a violation looks like
+
+Correct (runner output copied exactly):
+
+```
+ATTACH=<artifact root>\myproject\2026-09-22_1412_advisor started=2026-09-22T14:12:03.000Z
+OK — recommend service-boundary: the interface keeps ownership local
+Rejected: shared-kernel — every consumer now pays for cross-domain coupling
+Counter: a shared contract could reduce duplicated validation
+Risks: the boundary may be wrong if a second consumer needs synchronous access
+Report: ...\report.md · Log: ...\2026-09-22_1412_advisor
+```
+
+Incorrect — "Codex started in the background. Waiting for the advice to finish — I will notify
+you." There will be no notification: as a dispatcher, you terminate with the response, so nobody
+can wait and send one. Background execution is prohibited above.
+
+Incorrect — "I reviewed the design manually because Codex could not read one of the paths," followed
+by recommendations. This defeats the boundary: all reading and reasoning belong to the Codex run.

package/src/agents/codex-build.md

@@ -51,6 +51,10 @@ job is to report the run status honestly, including failure.
   heading, one line. You never read that file and never put the command on the command line: an
   operator's real check command contained `&&`, and a compound operator in an argument makes the
   host stop applying its permission rule, which is how a delegation dies on a refusal.
+- Every build task file must contain exactly one `advice:` line from the orchestrator: an absolute
+  path to an existing run folder whose `meta.json` identifies `codex-advisor`, or exactly
+  `mechanical`, `revert`, `docs-only`, or `test-only`. Anything else is refused before the run
+  starts. Pass the task file as supplied; the orchestrator owns this line.
 
 ## When the host refuses the command
 

package/src/commands/env.md

@@ -9,10 +9,11 @@ argument-hint: "[hooks|plugins on|off] | [reset]"
      symlinks nor pointer files (verified 2026-08-02). Edit it here; it travels as a copy when the
      package is installed. -->
 
-Environment switches for `codex-scout` / `codex-build` / `codex-review` runs. By default the hooks
-and plugins from `~/.codex` do not reach a delegated run: they are written for interactive work and
-do harm in an automated one — the failing `Stop` hook of `oh-my-codex` would not let Codex leave the
-session, and instead of doing the task it quarantined `.omx/state/session.json`. The operator's
+Environment switches for `codex-scout` / `codex-build` / `codex-review` / `codex-advisor` runs.
+By default the hooks and plugins from `~/.codex` do not reach a delegated run: they are written for
+interactive work and do harm in an automated one — the failing `Stop` hook of `oh-my-codex` would
+not let Codex leave the session, and instead of doing the task it quarantined
+`.omx/state/session.json`. The operator's
 interactive Codex is untouched: the flags are set on one specific runner invocation,
 `~/.codex/hooks.json` is not modified.
 

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

@@ -9,34 +9,17 @@
  *
  * The heartbeat is required here and deliberately NOT in meta/run-state.mjs: releasing a lock
  * early costs an operator one knowing edit, while closing a record early makes a second writer
- * of its meta.json. See the comment above pidAlive() there.
+ * of its meta.json. See the comment above markAbandoned() in meta/run-state.mjs.
  */
 import fs from 'node:fs';
 import path from 'node:path';
 import { heartbeatAge, isHeartbeatFresh } from '../lib/heartbeat.mjs';
 import { readJsonFileSync } from '../lib/json-file.mjs';
-import {
-  IDENTITY_ALIVE,
-  IDENTITY_DEAD,
-  IDENTITY_FOREIGN,
-  processIdentity,
-} from '../lib/process-identity.mjs';
+import { runLiveness } from '../lib/meta/run-liveness.mjs';
+import { IDENTITY_ALIVE } from '../lib/process-identity.mjs';
 
 export const RECENT_RUN_MAX_AGE_MS = 24 * 60 * 60 * 1_000;
 
-/**
- * The hook requires pid judgment plus a fresh heartbeat. Identity uncertainty stays live here
- * (fail-open), while the identity module deliberately treats a missing heartbeat as unverified;
- * isHeartbeatFresh() keeps its pre-Plan_20 missing-file compatibility for this separate question.
- */
-// Plan_31 needs confirmed process identity before warning about paid work that TaskStop leaves
-// behind; existing lock/reply guards retain the fail-open default for uncertain identities.
-export const isPidAlive = (pid, runDir, status = {}, options = {}) => {
-  const identity = processIdentity({ runDir, status: { ...status, pid } });
-  if (options.requireConfirmedIdentity === true) return identity === IDENTITY_ALIVE;
-  return identity !== IDENTITY_DEAD && identity !== IDENTITY_FOREIGN;
-};
-
 /**
  * Match the package's repository comparison without resolving symlinks: Windows realpath adds
  * `\\?\\` and UNC spellings, turning equal paths into unequal ones. A null result is uncertainty,
@@ -58,9 +41,24 @@ function isNonEmptyString(value) {
   return typeof value === 'string' && Boolean(value.trim());
 }
 
+/**
+ * The hook requires pid judgment plus a fresh heartbeat. Identity uncertainty stays live here
+ * (fail-open), while the identity module deliberately treats a missing heartbeat as unverified;
+ * isHeartbeatFresh() keeps its pre-Plan_20 missing-file compatibility for this separate question.
+ */
 function recognizedStatus(runDir, status, options) {
   const heartbeatFresh = isHeartbeatFresh(runDir)
     && (options.requireConfirmedIdentity !== true || heartbeatAge(runDir) !== null);
+  // Judged last: an identity probe can spawn PowerShell, and every hook call scans every project,
+  // so a record already ruled out by its fields or a stale heartbeat must never pay for one.
+  const judged = () => {
+    const liveness = runLiveness({ runDir, status });
+    // Plan_31 needs confirmed process identity before warning about paid work that TaskStop leaves
+    // behind; existing lock/reply guards retain the fail-open default for uncertain identities.
+    return options.requireConfirmedIdentity === true
+      ? liveness.identity === IDENTITY_ALIVE
+      : liveness.processMayBeAlive === true;
+  };
   return Boolean(status)
     && typeof status === 'object'
     && !Array.isArray(status)
@@ -70,7 +68,7 @@ function recognizedStatus(runDir, status, options) {
     && isNonEmptyString(status.slug)
     && isNonEmptyString(status.repo)
     && heartbeatFresh
-    && isPidAlive(status.pid, runDir, status, options);
+    && judged();
 }
 
 function readStatus(runDir) {

package/src/home/hooks/reply-guard.mjs

@@ -33,9 +33,10 @@ import { AGENTS } from '../lib/agents.mjs';
 import { runOrderMismatch, transcriptOrderId } from '../lib/dispatcher-order.mjs';
 import { recognizeHostRefusal } from '../lib/host-refusal.mjs';
 import { readJsonFileSync } from '../lib/json-file.mjs';
+import { runLiveness } from '../lib/meta/run-liveness.mjs';
 import { resolveProjectRunsDir } from '../lib/runner/project-dir.mjs';
 import { runsRoot } from '../lib/runner/runs-root.mjs';
-import { isPidAlive, liveRuns, normalizePath, recentRuns } from './live-runs.mjs';
+import { liveRuns, normalizePath, recentRuns } from './live-runs.mjs';
 import { FORM, MAX_STATE_BLOCKS, STATE, takeTry } from './guard-tries.mjs';
 import { parseReply } from './reply-parser.mjs';
 import {
@@ -233,7 +234,9 @@ if (fs.existsSync(statusPath)) {
   }
 
   if (runStatus?.state === 'running') {
-    if (isPidAlive(runStatus.pid)) {
+    // Plan_57 D5/D27: a bare pid mistook a reused foreign process for this run's worker.
+    // The shared judge uses run identity and keeps unverified processes live (fail open).
+    if (runLiveness({ runDir, status: runStatus }).processMayBeAlive) {
       blockState(
         liveRunReason,
         liveRunStop(MAX_STATE_BLOCKS, runStatus, runDir),