@lyupro/codex-bridge 0.6.9 → 0.6.10

package/CHANGELOG.md

@@ -4,6 +4,57 @@ 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.10] - 2026-10-04
+
+### Added
+
+- `UNAVAILABLE` is a status of its own, with exit code `5`. Before any quota is spent, a bounded
+  `codex --version` and `codex login status` tell a missing or signed-out Codex from an unclear answer.
+  Only a missing or signed-out Codex refuses as `UNAVAILABLE`, without a run folder. After the start,
+  only a measured sample (a final `401 Unauthorized` turn failure) ends a run `UNAVAILABLE`. Any other
+  error stays `FAIL` with its raw text, so a lost subscription is never mistaken for a failed task.
+- A failed pass can be repeated once: `retry: <failed run> — <reason>` in the task header, with `--continue`.
+  The retry is accepted only for the last run of the chain, with a finished non-`OK` verdict and a worker
+  proven dead. It keeps the order id, agent, phase and continuation base, and does not spend another
+  continuation of the order. The reply says `Attempt: N of this pass`. Refusals met at a failed last run
+  print a ready `retry:` line.
+- One order id admits one paid worker. A launcher takes a kernel-held claim on the project's run store and
+  the exact order id (named pipe on Windows, abstract socket on Linux). It holds the claim until its worker is
+  registered, and the worker admits itself under the same claim before Codex starts. A second launch of the
+  same order attaches to the first run instead of paying again. A claim that stays busy for 60 seconds is a
+  free refusal, never a second start. On 2026-09-24 two launchers of one order started 2.8 s apart and
+  both paid.
+- A scout question can be marked `[context-only]` by its orderer. Such questions are about startup
+  context and pass without commands. An answer must cite `startup:<source>`, and a repository `path:line`
+  read by no command fails as an unread address. `questions.json` records `{id, text, kind}`.
+- The build reply adds a `Flags coverage: incomplete` line when the start content of a file could not be
+  judged. The status stays as it is.
+
+### Changed
+
+- Every runner exit code comes from one table, and a guard ties it to the docs and the prompts:
+  `0` OK, `1` FAIL, `2` usage error, `3` LIMIT, `4` still running or no run (`--no-wait`), `5` UNAVAILABLE.
+- Service lines of a task file live only in its header: consecutive `advice:`, `continue:` and `retry:`
+  lines from the first line. One parser serves the runner, the task hash and the `order-gate` hook. The task
+  hash covers the body only, and new runs record `task_hash_scheme: 2`. A label line below the header that
+  looks like metadata is refused for free, with its line number and the repair. **Orchestrators that write
+  `advice:` further down a build task must move it to the top.**
+- TODO, FIXME, skip and only flags judge only the lines a build run added. Before the run, the start content
+  of every dirty and untracked file is recorded, and only that run's additions are compared. Before this
+  change, a run was accused of markers it found in the tree.
+- A scope refusal names the flag the pattern came from (`--scope` or `--scope-new`). When git cannot list
+  the folder the run started in, the refusal says so instead of claiming a tracked file does not exist.
+
+### Fixed
+
+- A grant line no longer changes the task hash, so a run named in `continue:` is found again under a new
+  order id (it used to answer "the current last run is none").
+- An order owned by a run from before the task header is refused truthfully, not as a different task.
+- `codex-bridge read` on a run refused before Codex started now names that refusal. It no longer says
+  the run predates the event stream.
+- A reply no longer repeats its verdict (`OK — OK —`) when the model began its own summary with one.
+- An unparsable scope pattern is named in its refusal instead of printing `undefined`.
+
 ## [0.6.9] - 2026-10-02
 
 ### Added

package/README.md

@@ -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 **2570 automated tests: 2569 passing and 1 skipped**.
+The current suite contains **2848 automated tests: 2847 passing and 1 skipped**.
 
 ## Verify
 

package/cli/lifecycle-lock-inspect.mjs

@@ -5,8 +5,9 @@
  */
 import fsp from 'node:fs/promises';
 import net from 'node:net';
+import { tryHoldSocket } from '../src/home/lib/kernel-lock.mjs';
 import {
-  holderLiveness, lifecycleLockAddress, lifecycleLockStrategy, parseHolder, tryHoldSocket,
+  holderLiveness, lifecycleLockAddress, lifecycleLockStrategy, parseHolder,
 } from './lifecycle-lock.mjs';
 
 const refusedCodes = new Set(['ECONNREFUSED', 'ENOENT']);
@@ -81,7 +82,7 @@ export async function inspectLifecycleLock(homeRoot, {
     const answer = await readSocketAnswer(target.address, answerTimeoutMs, createConnection);
     if (answer.kind === 'answer') return result({ state: 'held', holder: answer.holder });
     if (answer.kind !== 'refused') return result({ state: 'unverified', reason: answer.reason });
-    const release = await tryHoldSocket(target.address, createServer);
+    const release = await tryHoldSocket(target.address, createServer, 'lifecycle lock');
     if (release === 'in-use') return result({ state: 'held', holder: null });
     await release();
     return result({ state: 'free' });

package/cli/lifecycle-lock.mjs

@@ -17,12 +17,14 @@
  * the holder must fail, or the platform did not give exclusivity and the call refuses rather than
  * switch protocols. What the holder answers a waiter is diagnosis only — it never grants anything.
  */
-import { createHash, randomUUID } from 'node:crypto';
-import fs from 'node:fs';
+import { randomUUID } from 'node:crypto';
 import fsp from 'node:fs/promises';
 import net from 'node:net';
 import path from 'node:path';
 import { createHomeWriter } from '../src/home/lib/home-write.mjs';
+import {
+  acquireKernelLock, directoryDigest, kernelLockAddress, kernelLockStrategy,
+} from '../src/home/lib/kernel-lock.mjs';
 import { parseJsonText } from '../src/home/lib/json-file.mjs';
 import { processIdentity } from '../src/home/lib/process-identity.mjs';
 
@@ -46,25 +48,23 @@ function validateOptions(homeRoot, { command, hostRoot, waitMs, retryMs, answerT
 
 function statIdentity(homeRoot) {
   try {
-    const stat = fs.statSync(homeRoot, { bigint: true });
-    if (!stat.isDirectory()) throw new Error(`lifecycle lock home is not a directory: ${homeRoot}`);
-    return createHash('sha256').update(`${stat.dev}:${stat.ino}`).digest('hex');
+    return directoryDigest(homeRoot);
   } catch (error) {
-    if (error && error.code !== 'ENOENT') throw error;
-    return null;
+    if (error.message === `${homeRoot} is not a directory`) {
+      throw new Error(`lifecycle lock home is not a directory: ${homeRoot}`);
+    }
+    throw error;
   }
 }
 
 export function lifecycleLockStrategy(platform = process.platform) {
-  if (platform === 'win32') return 'named-pipe';
-  return platform === 'linux' ? 'abstract-socket' : 'file';
+  return kernelLockStrategy(platform) ?? 'file';
 }
 
 function lockAddress(homeRoot, digest, platform) {
   const strategy = lifecycleLockStrategy(platform);
-  if (strategy === 'named-pipe') return { strategy, address: `\\\\.\\pipe\\codex-bridge-lifecycle-${digest}` };
-  if (strategy === 'abstract-socket') return { strategy, address: `\0codex-bridge-lifecycle-${digest}` };
-  return { strategy, address: path.join(homeRoot, LOCK_NAME) };
+  const address = kernelLockAddress('lifecycle', digest, platform);
+  return { strategy, address: address ?? path.join(homeRoot, LOCK_NAME) };
 }
 
 export function lifecycleLockAddress(homeRoot, { platform = process.platform } = {}) {
@@ -87,73 +87,6 @@ async function prepareHome(homeRoot) {
   return { writer, digest };
 }
 
-function listen(server, address) {
-  return new Promise((resolve, reject) => {
-    const listening = () => { server.removeListener('error', failed); resolve(); };
-    const failed = (error) => { server.removeListener('listening', listening); reject(error); };
-    server.once('listening', listening);
-    server.once('error', failed);
-    try {
-      server.listen(address);
-    } catch (error) {
-      server.removeListener('listening', listening);
-      server.removeListener('error', failed);
-      reject(error);
-    }
-  });
-}
-
-function closeServer(server) {
-  if (!server) return Promise.resolve();
-  return new Promise((resolve, reject) => {
-    try {
-      server.close((error) => {
-        if (error && error.code !== 'ERR_SERVER_NOT_RUNNING') reject(error);
-        else resolve();
-      });
-    } catch (error) {
-      if (error.code === 'ERR_SERVER_NOT_RUNNING') resolve();
-      else reject(error);
-    }
-  });
-}
-
-async function closeQuietly(server) {
-  try { await closeServer(server); } catch { /* Preserve the original failure. */ }
-}
-
-async function selfCheck(server, address, createServer) {
-  let probe;
-  let detail;
-  try {
-    probe = createServer();
-    await listen(probe, address);
-    detail = 'a second listener succeeded';
-  } catch (error) {
-    if (!error || error.code !== 'EADDRINUSE') detail = (error && (error.code || error.message)) || String(error);
-  }
-  if (detail === undefined) {
-    await closeQuietly(probe);
-    return;
-  }
-  await Promise.all([closeQuietly(probe), closeQuietly(server)]);
-  throw new Error(`lifecycle lock self-check failed: ${detail}`);
-}
-
-export async function tryHoldSocket(address, createServer = net.createServer) {
-  const server = createServer((socket) => socket.destroy());
-  try {
-    await listen(server, address);
-    await selfCheck(server, address, createServer);
-    let releasePromise;
-    return () => (releasePromise ??= closeServer(server));
-  } catch (error) {
-    await closeQuietly(server);
-    if (error?.code === 'EADDRINUSE') return 'in-use';
-    throw error;
-  }
-}
-
 function validHolder(value) {
   return value && Number.isInteger(value.pid) && value.pid > 0
     && typeof value.command === 'string' && value.command.length > 0
@@ -188,29 +121,6 @@ function busyMessage(homeRoot, holder, hint = '') {
   return new Error(`lifecycle lock busy for ${homeRoot}: ${details}; nothing was changed${hint}`);
 }
 
-function readSocketHolder(address, timeoutMs) {
-  return new Promise((resolve) => {
-    let data = '';
-    let settled = false;
-    const socket = net.createConnection(address);
-    const timer = setTimeout(() => finish(null), timeoutMs);
-    const finish = (holder) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      socket.destroy();
-      resolve(holder);
-    };
-    socket.on('data', (chunk) => {
-      data += chunk.toString('utf8');
-      const newline = data.indexOf('\n');
-      if (newline !== -1) finish(parseHolder(data.slice(0, newline)));
-    });
-    socket.once('end', () => finish(parseHolder(data)));
-    socket.once('error', () => finish(null));
-  });
-}
-
 function lockResult(token, strategy, releaseAction) {
   let releasePromise;
   return {
@@ -226,36 +136,13 @@ function lockResult(token, strategy, releaseAction) {
 async function acquireSocketLock(homeRoot, holder, {
   address, strategy, waitMs, retryMs, answerTimeoutMs, createServer,
 }) {
-  const accepted = new Set();
-  const onConnection = (socket) => {
-    accepted.add(socket);
-    socket.once('close', () => accepted.delete(socket));
-    socket.end(`${JSON.stringify(holder)}\n`);
-  };
-  const deadline = Date.now() + waitMs;
-
-  for (;;) {
-    const server = createServer(onConnection);
-    try {
-      await listen(server, address);
-      holder.acquiredAt = new Date().toISOString();
-      await selfCheck(server, address, createServer);
-      server.unref();
-      return lockResult(holder.token, strategy, async () => {
-        const closing = closeServer(server);
-        for (const socket of accepted) socket.destroy();
-        await closing;
-      });
-    } catch (error) {
-      await closeQuietly(server);
-      if (!error || error.code !== 'EADDRINUSE') throw error;
-      const remaining = deadline - Date.now();
-      if (remaining <= 0) break;
-      await wait(Math.min(retryMs, remaining));
-    }
-  }
-
-  throw busyMessage(homeRoot, await readSocketHolder(address, answerTimeoutMs));
+  const result = await acquireKernelLock({
+    address, holder, waitMs, retryMs, answerTimeoutMs, createServer,
+    parseAnswer: parseHolder,
+    label: 'lifecycle lock',
+  });
+  if (!result.held) throw busyMessage(homeRoot, result.holder);
+  return lockResult(holder.token, strategy, result.release);
 }
 
 async function acquireFileLock(homeRoot, writer, holder, { waitMs, retryMs }) {

package/cli/read.mjs

@@ -1,4 +1,6 @@
 /** Renders a run's structured Codex transport as a readable event-by-event report. */
+import path from 'node:path';
+import { readJsonFileSync } from '../src/home/lib/json-file.mjs';
 import { readEvents } from '../src/home/lib/meta/events.mjs';
 import { safeSlice } from '../src/home/lib/meta/paths.mjs';
 import { runsRoot } from '../src/home/lib/runner/runs-root.mjs';
@@ -92,6 +94,24 @@ export function read({ run, cwd = process.cwd(), runsRootPath = runsRoot() } = {
   // run from before the event stream existed has no file, while a run killed before the CLI
   // spoke has an empty one. Reporting both as "predates this change" would hide the second.
   if (!eventData.hasStream) {
+    let state;
+    try {
+      state = readJsonFileSync(path.join(lookup.runDir, 'status.json'))?.state;
+    } catch {
+      // The 2026-09-06 refusal needs its state; unreadable status keeps the legacy explanation.
+    }
+    if (state === 'aborted_pre_start') {
+      return result(
+        1,
+        `Run ${lookup.runDir} was refused before Codex started (state aborted_pre_start), so it has no events.jsonl.`,
+      );
+    }
+    if (state === 'running') {
+      return result(
+        1,
+        `Run ${lookup.runDir} has no events.jsonl yet: Codex has not started; repeat the command shortly.`,
+      );
+    }
     return result(1, `Run ${lookup.runDir} has no events.jsonl; it predates the event stream.`);
   }
   if (!eventData.hasEvents) {

package/cli/settings-merge.mjs

@@ -1,11 +1,11 @@
 /** Merges and removes named codex-bridge hooks without disturbing host settings. */
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { spawnSync } from 'node:child_process';
-import { existsSync, statSync } from 'node:fs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { readJsonFileWithRaw } from '../src/home/lib/json-file.mjs';
+import { envValue, resolveCommandOnPath } from '../src/home/lib/command-path.mjs';
 
 const LEGACY_SPEC = { event: 'SubagentStop', matcher: '*' };
 const settingsRuns = new AsyncLocalStorage();
@@ -18,34 +18,8 @@ export function shortCommandFor(name) {
   return `codex-bridge hook ${name}`;
 }
 
-function envValue(env, name) {
-  const key = Object.keys(env).find((entry) => entry.toLowerCase() === name);
-  return key ? env[key] : '';
-}
-
-function pathValue(env) {
-  return envValue(env, 'path');
-}
-
-function resolveCommand(name, env) {
-  const extensions = process.platform === 'win32'
-    ? (env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';')
-    : [''];
-  for (const directory of pathValue(env).split(path.delimiter).filter(Boolean)) {
-    for (const extension of extensions) {
-      const candidate = path.join(path.resolve(directory), `${name}${extension}`);
-      try {
-        if (existsSync(candidate) && statSync(candidate).isFile()) return candidate;
-      } catch {
-        continue;
-      }
-    }
-  }
-  return null;
-}
-
 export function commandReachable(name = 'codex-bridge', env = process.env) {
-  return Boolean(resolveCommand(name, env));
+  return Boolean(resolveCommandOnPath(name, env));
 }
 
 /**
@@ -63,7 +37,7 @@ export function reachableCommandVersion(name = 'codex-bridge', env = process.env
 }
 
 export function runReachableCommand(name, args, env = process.env) {
-  const shimPath = resolveCommand(name, env);
+  const shimPath = resolveCommandOnPath(name, env);
   if (!shimPath) return null;
   // Node 24 warned with DEP0190 during update (2026-09-07): invoke cmd explicitly for npm shims.
   // Live probes covered plain, bin with space, Program Files (x86), weird & name, and caret^dir.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lyupro/codex-bridge",
-  "version": "0.6.9",
-  "description": "Claude Code-to-Codex delegation with 7 guards, 2570 tests, zero runtime dependencies, and zero build steps.",
+  "version": "0.6.10",
+  "description": "Claude Code-to-Codex delegation with 7 guards, 2848 tests, zero runtime dependencies, and zero build steps.",
   "keywords": [
     "claude-code",
     "codex",

package/scripts/home-write-inventory.mjs

@@ -37,13 +37,23 @@ export const HOME_WRITE_INVENTORY = Object.freeze([
   outside('src/home/lib/retention.mjs', 'fs-binding-escape', 1, 'The injected filesystem falls back to fs while cleaning run folders under the runs root, outside package home.'),
   outside('src/home/lib/retention.mjs', 'unlinkSync', 1, 'Removes transport files inside run folders under the runs root, outside package home.'),
   outside('src/home/lib/runner/git-state.mjs', 'openSync', 1, 'Read-only open with the r flag, hashing an untracked file of the worked repository in chunks (Plan_73 B4b).'),
+  outside('src/home/lib/runner/build-evidence.mjs', 'writeFileSync', 11, 'Writes the before and after tree evidence of a build run, flags.txt and flags-coverage.txt inside a run folder.'),
   outside('src/home/lib/runner/codex-cmd.mjs', 'createWriteStream', 2, 'Appends stderr.log and events.jsonl inside a run folder.'),
+  outside('src/home/lib/runner/flag-baseline.mjs', 'mkdirSync', 1, 'Creates the start-content copy folder inside a run folder (Plan_60 D3a).'),
+  outside('src/home/lib/runner/flag-baseline.mjs', 'rmSync', 1, 'Removes the start-content copies inside a run folder after the flag scan; the manifest stays.'),
+  outside('src/home/lib/runner/flag-baseline.mjs', 'writeFileSync', 2, 'Writes start-content copies and the flag baseline manifest inside a run folder.'),
+  outside('src/home/lib/runner/flag-scan.mjs', 'mkdirSync', 1,
+    'Creates the temporary HEAD-content folder inside a run folder (Plan_60 D3a).'),
+  outside('src/home/lib/runner/flag-scan.mjs', 'unlinkSync', 1,
+    'Removes a temporary HEAD-content file immediately after its flag comparison.'),
+  outside('src/home/lib/runner/flag-scan.mjs', 'writeFileSync', 1,
+    'Writes temporary HEAD bytes inside a run folder for the added-line flag comparison.'),
   outside('src/home/lib/runner/launcher.mjs', 'mkdirSync', 2, 'Creates project and run folders under the runs root.'),
-  outside('src/home/lib/runner/launcher.mjs', 'writeFileSync', 11, 'Writes run prompt, environment, scope, schema, and launch evidence into a run folder.'),
+  outside('src/home/lib/runner/launcher.mjs', 'writeFileSync', 7, 'Writes run prompt, environment, scope and schema into a run folder.'),
   outside('src/home/lib/runner/project-dir.mjs', 'mkdirSync', 2, 'Creates the runs root and a project folder under the runs root.'),
   outside('src/home/lib/runner/project-dir.mjs', 'writeFileSync', 1, 'Writes the project ownership marker under the runs root.'),
   outside('src/home/lib/runner/run-context.mjs', 'writeFileSync', 1, 'Writes a worker reply inside a run folder.'),
   outside('src/home/lib/runner/worker-order.mjs', 'writeFileSync', 1, 'Writes worker.json inside a run folder.'),
-  outside('src/home/lib/runner/worker.mjs', 'writeFileSync', 7, 'Writes worker git snapshots and report.md inside a run folder.'),
+  outside('src/home/lib/runner/worker.mjs', 'writeFileSync', 1, 'Writes report.md inside a run folder.'),
   outside('src/home/lib/write-meta.mjs', 'writeFileSync', 1, 'Writes meta.json inside a run folder under the runs root.'),
 ].map((entry) => Object.freeze(entry)));

package/src/agents/codex-advisor.md

@@ -46,9 +46,11 @@ and do not reason about the design yourself.
   `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
+- `continue` — when the orchestrator's call carries a line beginning with `continue:` or `retry:`,
+  pass the bare `--continue` flag even when its run name or reason looks malformed. A `retry:`
+  grant lets the orchestrator repeat a failed pass (FAIL, LIMIT, UNAVAILABLE) of the same order
+  once; it is not the next pass. 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.
@@ -82,10 +84,11 @@ unmatchable by construction. Reaching for one does not rescue the run; it guaran
 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:`; the flag itself takes no value (the runner accepts only
-`1/true/yes/0/false/no` there). The grant line names a run folder and a reason, and the runner parses
-it, so a malformed grant is passed through for the runner to refuse. If
+That is one command line. Add only the bare `--continue` when the orchestrator's call carries a line
+beginning with `continue:` or `retry:`; the flag itself takes no value (the runner accepts only
+`1/true/yes/0/false/no` there). The grant line names a run folder and a reason; never inspect, repair,
+or swallow it. The runner parses it, 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.
@@ -142,9 +145,13 @@ path.
 - `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.
+- `UNAVAILABLE` — Codex is missing or 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.
 
-The script return code mirrors the status: `0` / `1` / `3`. A nonzero code is not a reason to
+The script return code mirrors the status: `0` / `1` / `3` / `5`. A nonzero code is not a reason to
 retry, change the command, or investigate on your own.
+Code `5` means `UNAVAILABLE`.
 
 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;
@@ -159,14 +166,17 @@ 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.
-The orchestrator repeats a failed scope under a NEW order id, never with `continue:` or `--continue`:
+The orchestrator repeats a failed scope or a failed advise with a `retry:` grant naming that failed
+run, under the same order id. A successful scope is never continued as scope:
 the runner refuses a continued scope, because it would spend the continuation that advise needs.
 
 ## 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.
+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.
+Performing the task manually instead of Codex is prohibited for any reason it fails.
 
 ## What a violation looks like
 

package/src/agents/codex-build.md

@@ -39,9 +39,11 @@ job is to report the run status honestly, including failure.
   reuse an order id from another order — the runner chains runs by that label, and a made-up label
   is how a repeat run hides. If the orchestrator did not give a required input, do not guess: start
   the runner without its flag and return the runner's refusal exactly.
-- `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
+- `continue` — when the orchestrator's call carries a line beginning with `continue:` or `retry:`,
+  pass the bare `--continue` flag even when its run name or reason looks malformed. A `retry:`
+  grant lets the orchestrator repeat a failed pass (FAIL, LIMIT, UNAVAILABLE) of the same order
+  once; it is not the next pass. 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.
@@ -51,11 +53,13 @@ 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
+- Every build task file must start with a header of consecutive lowercase `label: value` lines
+  from the first line: exactly one `advice:` line from the orchestrator and the `continue:` or
+  `retry:` grant when there is one, then a blank line. The `advice:` 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. Pass the task file as supplied; the orchestrator owns this line.
+  starts. Pass the task file as supplied and never edit it; the orchestrator owns this header.
 
 ## When the host refuses the command
 
@@ -90,8 +94,9 @@ Add `--effort "<value>"` only when the orchestrator named a depth, and only with
 decides, which is the intended default — a placeholder copied from this template is refused before
 Codex starts.
 
-If the task text contains a line beginning with the `continue:` label, add the bare `--continue`
-flag even when its run name or reason looks malformed. Do not inspect, repair, or swallow the line;
+If the orchestrator's call carries a line beginning with `continue:` or `retry:`, add the bare
+`--continue` flag even when its run name or reason looks malformed. Do not inspect, repair, or
+swallow the line;
 the runner parses it and issues the refusal. If no such grant line is present, the flag must not be
 present in the command.
 No value
@@ -191,8 +196,9 @@ anything.
 An empty `summary` is FAIL.
 
 The `Flags` line in the response lists `TODO`, `FIXME`, `test.skip`/`.only`, and
-`NotImplemented` found in the diff. They are not hidden: false completion must be visible to the
-orchestrator.
+`NotImplemented` markers on lines THIS run added, compared with its start content. They are not
+hidden: false completion must be visible to the orchestrator. `Flags coverage: incomplete` means
+some files could not be judged.
 
 ## The script determines status, not you
 
@@ -214,6 +220,9 @@ orchestrator.
   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
+  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.
 
 A failed verification and a mismatch between the report and worktree cancel `OK` status — the
 orchestrator branches on
@@ -221,7 +230,8 @@ the first word, so failure must not be buried on the third line. Found placehold
 it, but they
 are visible in the `Flags` line — the orchestrator decides what to do with them. The script return
 code mirrors
-the status: `0` / `1` / `3`. A nonzero code is not a reason to retry or finish the code yourself.
+the status: `0` / `1` / `3` / `5`. A nonzero code is not a reason to retry or finish the code yourself.
+Code `5` means `UNAVAILABLE`.
 
 The run folder contains `status.json` (`running` / `finished` / `failed` / `abandoned`) and the
 runner pid.
@@ -231,10 +241,10 @@ without the `--continue` it issued, the runner will reject that repeat run itsel
 
 ## 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. Your job is to return that
-output.
+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.
 Implementing the task instead of Codex is prohibited for any reason it fails.
 
 ## What a violation looks like

package/src/agents/codex-review.md

@@ -38,9 +38,11 @@ opinion, not a verdict.
   another order — the runner chains runs by that label, and a made-up label is how a repeat run
   hides. If the orchestrator did not give a required input, do not guess — start the runner without
   its flag and return the runner's 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
+- `continue` — when the orchestrator's call carries a line beginning with `continue:` or `retry:`,
+  pass the bare `--continue` flag even when its run name or reason looks malformed. A `retry:`
+  grant lets the orchestrator repeat a failed pass (FAIL, LIMIT, UNAVAILABLE) of the same order
+  once; it is not the next pass. 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.
@@ -90,8 +92,9 @@ If the runner refuses with an order id collision — the id already belongs to a
 differs — that refusal is the whole answer: return `FAIL` with the runner's text, which names the
 remedy. Never retry under a different id of your own choosing; the order id is the orchestrator's.
 
-If the task text contains a line beginning with the `continue:` label, add the bare `--continue`
-flag even when its run name or reason looks malformed. Do not inspect, repair, or swallow the line;
+If the orchestrator's call carries a line beginning with `continue:` or `retry:`, add the bare
+`--continue` flag even when its run name or reason looks malformed. Do not inspect, repair, or
+swallow the line;
 the runner parses it and issues the refusal. If no such grant line is present, the flag must not be
 present in the command at all.
 
@@ -176,9 +179,13 @@ 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
+  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.
 
-The script return code mirrors the status: `0` / `1` / `3`. A nonzero code is not a reason to retry,
+The script return code mirrors the status: `0` / `1` / `3` / `5`. A nonzero code is not a reason to retry,
 not a reason to change the command, and not a reason to review it yourself.
+Code `5` means `UNAVAILABLE`.
 
 The run folder contains `status.json` (`running` / `finished` / `failed` / `abandoned`) and the
 runner pid.
@@ -190,10 +197,10 @@ Token spending now goes into `meta.json` (the `review` subcommand did not print
 
 ## 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. Your job is to return that
-output.
+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.
 
 ## What a violation looks like