@lyupro/codex-bridge 0.6.9 → 0.6.11

package/cli/install-owners.mjs

@@ -11,6 +11,7 @@
  */
 import { createHash } from 'node:crypto';
 import { normalizeRepoPath } from '../src/home/lib/runner/project-dir.mjs';
+import { isFormat2 } from '../src/home/lib/install-owner-roots.mjs';
 import {
   fileEntry,
   INSTALL_METHOD_COPY,
@@ -20,10 +21,6 @@ import {
 
 const isObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 
-export function isFormat2(parsed) {
-  return isObject(parsed) && parsed.format === 2;
-}
-
 export function imageFingerprint(image) {
   const brand = image.fingerprints?.brand;
   if (brand === undefined) return null;

package/cli/install-record.mjs

@@ -4,7 +4,8 @@ import { randomUUID } from 'node:crypto';
 import { createHomeWriter } from '../src/home/lib/home-write.mjs';
 import { readJsonFile } from '../src/home/lib/json-file.mjs';
 import { HOOK_DEFINITIONS } from '../src/home/lib/hook-definitions.mjs';
-import { isFormat2, ownerView, validateFormat2, withOwner, withoutOwner } from './install-owners.mjs';
+import { isFormat2 } from '../src/home/lib/install-owner-roots.mjs';
+import { ownerView, validateFormat2, withOwner, withoutOwner } from './install-owners.mjs';
 
 /**
  * The record's own spelling of the field saying how the package was installed, and its one value.

package/cli/inventory-transition.mjs

@@ -5,7 +5,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { askYesNo, isInteractive } from './terminal-question.mjs';
-import { isFormat2 } from './install-owners.mjs';
+import { isFormat2 } from '../src/home/lib/install-owner-roots.mjs';
 import { readInstallRecordFile } from './install-record.mjs';
 import { normalizedRulesOwner, readRulesRegistry } from './rules-owners.mjs';
 

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/manifest.mjs

@@ -4,14 +4,13 @@ import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { HOOK_DEFINITIONS } from '../src/home/lib/hook-definitions.mjs';
-import {
-  renderRequiredInputSummary,
-  renderRequiredInputs,
-} from '../src/home/lib/required-inputs.mjs';
+import { renderRequiredInputSummary } from '../src/home/lib/dispatcher-call.mjs';
 import { renderNoSelfExecution } from '../src/home/lib/no-self-execution.mjs';
+import { renderDispatcherProtocol } from '../src/home/lib/dispatcher-protocol.mjs';
+import { ORDER_AGENTS } from '../src/home/lib/order-schema.mjs';
 import { renderStopSummary } from '../src/home/lib/stop-contract.mjs';
 import { readJsonFile } from '../src/home/lib/json-file.mjs';
-import { normalizeFrontmatter } from './frontmatter.mjs';
+import { normalizeFrontmatter } from '../src/home/lib/frontmatter.mjs';
 import {
   INSTALL_RECORD_NAME,
   RULES_NAME,
@@ -77,7 +76,8 @@ export function replacePlaceholders(content, installationRoot) {
   const replaced = content
     .replaceAll('{{CODEX_BRIDGE_DIR}}', posix(path.resolve(installationRoot)))
     .replaceAll('{{CODEX_REQUIRED_INPUTS_SUMMARY}}', renderRequiredInputSummary(agentType))
-    .replaceAll('{{CODEX_REQUIRED_INPUTS}}', renderRequiredInputs(agentType))
+    .replaceAll('{{CODEX_DISPATCHER_PROTOCOL}}', ORDER_AGENTS.includes(agentType)
+      ? renderDispatcherProtocol(agentType) : '{{CODEX_DISPATCHER_PROTOCOL}}')
     .replaceAll('{{CODEX_NO_SELF_EXECUTION}}', renderNoSelfExecution())
     .replaceAll('{{CODEX_STOP_SUMMARY}}', renderStopSummary());
   return normalizeFrontmatter(replaced);

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.11",
+  "description": "Claude Code-to-Codex delegation with 7 guards, 3199 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

@@ -1,6 +1,6 @@
 ---
 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}}
+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
 ---
@@ -14,119 +14,29 @@ ChatGPT subscription. All design reading and reasoning must happen on the Codex
 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>"
-```
+{{CODEX_DISPATCHER_PROTOCOL}}
+
+## Role notes
+
+The advisor performs two passes of one order: `phase: scope` first, then `phase: advise`
+as the continuation of that same order's successful advisor scope run. The orchestrator
+writes both phases in the task-file header; the `advise` header includes a `continue:`
+grant naming the scope run. Never choose or change the phase or grant 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).
 
-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
-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 the attaching call is killed by a time ceiling, run the identical command again: it attaches to the same
-run and keeps waiting. Never add a flag — the host allows exactly the one command your
-order yields and refuses every other. 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.
+The advisor's file boundary is the explicit `## Paths` list and, for `advise`, the
+successful scope run's `missing_paths`.
 
 ## What you return
 
@@ -142,12 +52,16 @@ 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;
+the `advise` phase only when the orchestrator's task-file header grants 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.
 
@@ -157,16 +71,18 @@ For `advise`, expect `OK — recommend <option_id>: …`, followed by `Rejected:
 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`:
+yourself: the orchestrator decides whether to continue, and without the orchestrator's `continue:` or `retry:` grant in the task-file header, the runner will reject that repeat run itself.
+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