@lyupro/codex-bridge 0.4.0 → 0.5.1

package/src/agents/codex-scout.md

@@ -1,6 +1,6 @@
 ---
 name: codex-scout
-description: Разведка и диагностика ВНЕ подписки Claude — исследование кодовой базы, поиск причины бага, ревью, сбор фактов. Работу выполняет Codex CLI (подписка ChatGPT), Claude платит только за постановку задачи и ≤5 строк выжимки. Строго read-only: писать в репозиторий физически не может. Подробный отчёт кладёт в ~/.claude/codex-runs/, в чат — короткая выжимка + путь. {{CODEX_REQUIRED_INPUTS_SUMMARY}}
+description: Разведка и диагностика ВНЕ подписки Claude — исследование кодовой базы, поиск причины бага, ревью, сбор фактов. Работу выполняет Codex CLI (подписка ChatGPT), Claude платит только за постановку задачи и ≤5 строк выжимки. Строго read-only: писать в репозиторий физически не может. Подробный отчёт кладёт в ~/.claude/codex-runs/, в чат — короткая выжимка + путь. {{CODEX_REQUIRED_INPUTS_SUMMARY}} {{CODEX_STOP_SUMMARY}}
 model: haiku
 tools: Bash
 ---
@@ -26,7 +26,8 @@ files, do not run grep, do not retell the report, and do not reason about the ta
 - Scope patterns are globs relative to the repository root. A pattern that matches nothing there is
   refused before the run starts.
 - Optional: `effort: <none|minimal|low|medium|high|xhigh|max>` — Codex reasoning depth.
-- Optional: `slug: <short-name>` for the run folder.
+- Optional: `slug: <short-name>` for the run folder; by default, the slug is taken from the order
+  id.
 - Every input listed under **Required dispatcher inputs** above, passed on exactly as given:
   `order id` as `--order-id`. Never invent a value, never edit one, never reuse an order id from
   another order — the runner chains runs by that label, and a made-up label is how a repeat run
@@ -36,12 +37,12 @@ files, do not run grep, do not retell the report, and do not reason about the ta
   pass one `--question "<text>"` flag exactly as given. Never invent, merge, reword, or drop a
   sub-question. If the orchestrator did not give one, do not guess — start the runner without
   the flag and return its refusal verbatim.
-- `continue` — pass the `--continue` flag only when the orchestrator gave the matching `continue:`
-  grant explicitly; do not add or guess it yourself. 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. The contract is strict, like `--scope` in
-  codex-build: if this task (the same `slug` and the same repository) already had a run, the runner
-  will refuse to start without `--continue` — before starting Codex, so no quota is spent.
+- `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 only thing you do
 
@@ -62,8 +63,10 @@ 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 orchestrator gave the matching `continue:` grant, add the bare `--continue` flag to the
-command, with no value.
+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;
+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
 is passed to it: the runner accepts only `1/true/yes/0/false/no`, while a placeholder string left in
 the
@@ -119,7 +122,7 @@ The flags are proven, and they do not belong in the prompt: `--ignore-user-confi
 startup ballast (~9k quota instead of ~19k) and structurally blocks writing — no flags can override
 read-only; `--disable hooks --disable plugins` disable the operator's extensions for this call,
 so the run does not depend on what is installed in `~/.codex` today (the default, switched
-by the operator through `/codex:env`); `--model` is never passed because model IDs
+by the operator through `/codex-bridge:env`); `--model` is never passed because model IDs
 are volatile.
 The run is asynchronous, and waiting for it is a separate call. That is deliberate: while the start
 and the wait were one call, a time ceiling on that call looked exactly like a dead run, and the

package/src/commands/env.md

@@ -4,8 +4,8 @@ allowed-tools: Bash
 argument-hint: "[hooks|plugins on|off] | [reset]"
 ---
 
-<!-- Part of the agents/codex/ package. The file lives here out of necessity: the slash command name
-     is set by its location under commands/<namespace>/, and Claude Code understands neither
+<!-- Part of the agents/codex-bridge/ package. The file lives here out of necessity: the slash
+     command name is set by its location under commands/<namespace>/, and Claude Code understands neither
      symlinks nor pointer files (verified 2026-08-02). Edit it here; it travels as a copy when the
      package is installed. -->
 
@@ -30,8 +30,8 @@ Call forms:
 - `plugins on` / `plugins off` — the same for plugins;
 - `reset` — back to the default (both off).
 
-The state lives in `agents/codex/run-config.json` and lands in the `meta.json` of every run, so the
-artifacts always show which environment a run went through.
+The state lives in `~/.lyupro/.codex-bridge/config.json` and lands in the `meta.json` of every run,
+so the artifacts always show which environment a run went through.
 
 If the user turns `hooks` on, say in one line: while the failing `Stop` hook of `oh-my-codex` stays
 in `~/.codex/hooks.json`, runs will again spend quota on unrelated repairs. Checking the report

package/src/commands/usage.md

@@ -3,8 +3,8 @@ description: Show the ChatGPT quota spent on runs delegated to Codex — by day,
 allowed-tools: Bash
 ---
 
-<!-- Part of the agents/codex/ package. The file lives here out of necessity: the slash command name
-     is set by its location under commands/<namespace>/, and Claude Code understands neither
+<!-- Part of the agents/codex-bridge/ package. The file lives here out of necessity: the slash
+     command name is set by its location under commands/<namespace>/, and Claude Code understands neither
      symlinks nor pointer files (verified 2026-08-02). Edit it here; it travels as a copy when the
      package is installed. -->
 
@@ -44,14 +44,14 @@ for(const proj of fs.readdirSync(root)){
   try{repo=JSON.parse(fs.readFileSync(path.join(pdir,'.project.json'),'utf8')).repo||null}catch{}
   for(const run of fs.readdirSync(pdir)){
     const dir=path.join(pdir,run),meta=path.join(dir,'meta.json'),log=path.join(dir,'raw.log');
-    let tokens=null,agent=null,sandbox=null;
+    let tokens=null,agent=null,sandbox=null,runnerVersion=false;
     if(fs.existsSync(meta)){
-      try{const m=JSON.parse(fs.readFileSync(meta,'utf8'));tokens=m.tokens??null;agent=m.agent||null;sandbox=m.sandbox||null}catch{}
+      try{const m=JSON.parse(fs.readFileSync(meta,'utf8'));tokens=m.tokens??null;agent=m.agent||null;sandbox=m.sandbox||null;runnerVersion=Object.hasOwn(m,'runner_version')}catch{}
     } else if(fs.existsSync(log)){
       const hit=[...fs.readFileSync(log,'utf8').matchAll(/tokens used[\r\n]+([^\r\n]+)/g)].pop();
       tokens=hit?parseInt(hit[1].replace(/\D/g,''),10)||null:null;
     } else continue;
-    const entry={proj,repo,run,day:run.slice(0,10),agent:agent||(/review/.test(run)?'codex-review':/build/.test(run)?'codex-build':'codex-scout'),sandbox};
+    const entry={proj,repo,run,day:run.slice(0,10),agent:agent||(/review/.test(run)?'codex-review':/build/.test(run)?'codex-build':'codex-scout'),sandbox,runnerVersion};
     if(tokens===null){unknown.push(entry);continue}
     runs.push({...entry,tokens});
   }
@@ -63,7 +63,9 @@ const fmt=n=>n.toLocaleString('en-US');
 const row=(l,rs)=>'  '+String(l).padEnd(22)+String(rs.length).padStart(3)+' runs  '+fmt(sum(rs)).padStart(11)+'  average '+fmt(Math.round(sum(rs)/rs.length));
 if(runs.length)console.log('TOTAL: '+fmt(sum(runs))+' tokens over '+runs.length+' runs · average '+fmt(Math.round(sum(runs)/runs.length)));
 if(unknown.length)console.log('Unaccounted: '+unknown.length+' runs (Codex reported no spending) — the total is understated');
-const risky=[...runs,...unknown].filter(r=>r.sandbox&&r.sandbox!=='read-only'&&r.sandbox!=='workspace-write');
+const legacy=[...runs,...unknown].filter(r=>!r.runnerVersion);
+if(legacy.length)console.log('Before the runner: '+legacy.length+' runs carry no runner version and are not judged by the sandbox contract');
+const risky=[...runs,...unknown].filter(r=>r.runnerVersion&&r.sandbox&&r.sandbox!=='read-only'&&r.sandbox!=='workspace-write');
 if(risky.length)console.log('WARNING: '+risky.length+' runs went outside the usual sandbox: '+risky.map(r=>r.run+' ('+r.sandbox+')').join(', '));
 if(runs.length){
   console.log('');console.log('By day:');

package/src/hook-definitions.mjs

@@ -39,9 +39,22 @@ export const SHELL_TOOLS = Object.freeze(['Bash', 'PowerShell']);
 /** A PreToolUse matcher is a regular expression over tool names, so alternation covers both. */
 export const SHELL_TOOL_MATCHER = SHELL_TOOLS.join('|');
 
+// Plan_31 routes host stop requests through the package guard; keep the matcher derived from
+// the tool list so registration and uninstall cannot drift from the host event spelling.
+export const STOP_TOOLS = Object.freeze(['TaskStop']);
+
+/** A PreToolUse matcher is a regular expression over tool names, so the list remains authoritative. */
+export const STOP_TOOL_MATCHER = STOP_TOOLS.join('|');
+
+/**
+ * Stable CLI names live beside each event and file because the Plan_19 drift incident left
+ * registration, diagnostics, and the guard itself carrying different hook identities. The
+ * dispatcher must consume this one list instead of guessing a name from a path at its call site.
+ */
 export const HOOK_DEFINITIONS = Object.freeze([
-  Object.freeze({ event: 'SubagentStop', matcher: '*', file: 'reply-guard.mjs' }),
-  Object.freeze({ event: 'PreToolUse', matcher: SUBAGENT_TOOL_MATCHER, file: 'order-gate.mjs' }),
-  Object.freeze({ event: 'PreToolUse', matcher: WRITE_TOOL_MATCHER, file: 'worktree-lock.mjs' }),
-  Object.freeze({ event: 'PreToolUse', matcher: SHELL_TOOL_MATCHER, file: 'prune-guard.mjs' }),
+  Object.freeze({ name: 'reply-guard', event: 'SubagentStop', matcher: '*', file: 'reply-guard.mjs' }),
+  Object.freeze({ name: 'order-gate', event: 'PreToolUse', matcher: SUBAGENT_TOOL_MATCHER, file: 'order-gate.mjs' }),
+  Object.freeze({ name: 'worktree-lock', event: 'PreToolUse', matcher: WRITE_TOOL_MATCHER, file: 'worktree-lock.mjs' }),
+  Object.freeze({ name: 'prune-guard', event: 'PreToolUse', matcher: SHELL_TOOL_MATCHER, file: 'prune-guard.mjs' }),
+  Object.freeze({ name: 'stop-guard', event: 'PreToolUse', matcher: STOP_TOOL_MATCHER, file: 'stop-guard.mjs' }),
 ]);

package/src/hooks/guard-tries.mjs

@@ -0,0 +1,59 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { readJsonFileSync } from '../json-file.mjs';
+
+const LOG_DIR = path.join(os.homedir(), '.claude', 'logs');
+/**
+ * The file keeps its reply-guard name although two guards now share it: renaming would abandon the
+ * budgets already spent on hosts in the field, and a guard that forgets its refusals starts
+ * refusing the same call again.
+ */
+export const BLOCKED_FILE = path.join(LOG_DIR, 'codex-reply-guard.blocked.json');
+export const FORM = 'form';
+export const STATE = 'state';
+export const MAX_FORM_BLOCKS = 3;
+export const MAX_STATE_BLOCKS = 3;
+
+const wholeCount = (value) => (Number.isInteger(value) && value > 0 ? value : 0);
+
+function priorCount(prior, kind) {
+  if (prior && typeof prior === 'object' && !Array.isArray(prior)) {
+    return wholeCount(prior[kind]);
+  }
+  if (kind === FORM && typeof prior === 'number') return wholeCount(prior);
+  if (kind === FORM) return prior ? 1 : 0;
+  return 0;
+}
+
+// Plan_31 reuses this persisted try budget so the TaskStop guard cannot grow a second,
+// divergent counter beside reply-guard's existing per-agent escape hatch.
+export function takeTry(agentId, kind, maxBlocks = kind === STATE ? MAX_STATE_BLOCKS : MAX_FORM_BLOCKS) {
+  if (!agentId) return 'untracked';
+
+  let seen;
+  try {
+    seen = readJsonFileSync(BLOCKED_FILE);
+  } catch {
+    seen = {};
+  }
+  if (!seen || typeof seen !== 'object' || Array.isArray(seen)) seen = {};
+
+  const current = priorCount(seen[agentId], kind);
+  if (current >= maxBlocks) return 'exhausted';
+
+  const prior = seen[agentId];
+  const next = prior && typeof prior === 'object' && !Array.isArray(prior) ? { ...prior } : {};
+  next[kind] = current + 1;
+  seen[agentId] = next;
+
+  const ids = Object.keys(seen);
+  if (ids.length > 200) ids.slice(0, ids.length - 200).forEach((id) => delete seen[id]);
+  try {
+    fs.mkdirSync(path.dirname(BLOCKED_FILE), { recursive: true });
+    fs.writeFileSync(BLOCKED_FILE, `${JSON.stringify(seen)}\n`);
+  } catch {
+    return 'untracked';
+  }
+  return 'granted';
+}

package/src/hooks/live-runs.mjs

@@ -13,17 +13,25 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { isHeartbeatFresh } from '../heartbeat.mjs';
+import { heartbeatAge, isHeartbeatFresh } from '../heartbeat.mjs';
 import { readJsonFileSync } from '../json-file.mjs';
-import { IDENTITY_DEAD, IDENTITY_FOREIGN, processIdentity } from '../process-identity.mjs';
+import {
+  IDENTITY_ALIVE,
+  IDENTITY_DEAD,
+  IDENTITY_FOREIGN,
+  processIdentity,
+} from '../process-identity.mjs';
 
 /**
  * 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.
  */
-export const isPidAlive = (pid, 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.
+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;
 };
 
@@ -48,7 +56,9 @@ function isNonEmptyString(value) {
   return typeof value === 'string' && Boolean(value.trim());
 }
 
-function recognizedStatus(runDir, status) {
+function recognizedStatus(runDir, status, options) {
+  const heartbeatFresh = isHeartbeatFresh(runDir)
+    && (options.requireConfirmedIdentity !== true || heartbeatAge(runDir) !== null);
   return Boolean(status)
     && typeof status === 'object'
     && !Array.isArray(status)
@@ -57,8 +67,8 @@ function recognizedStatus(runDir, status) {
     && isNonEmptyString(status.agent)
     && isNonEmptyString(status.slug)
     && isNonEmptyString(status.repo)
-    && isHeartbeatFresh(runDir)
-    && isPidAlive(status.pid, runDir, status);
+    && heartbeatFresh
+    && isPidAlive(status.pid, runDir, status, options);
 }
 
 function readStatus(runDir) {
@@ -70,7 +80,7 @@ function readStatus(runDir) {
 }
 
 /** Scan one project's direct run folders; unreadable or unfamiliar entries are ignored. */
-export function liveRuns(runsDir) {
+export function liveRuns(runsDir, options = {}) {
   if (typeof runsDir !== 'string' || !runsDir.trim()) return [];
   let entries;
   try {
@@ -83,13 +93,13 @@ export function liveRuns(runsDir) {
     if (!entry.isDirectory()) continue;
     const dir = path.join(runsDir, entry.name);
     const status = readStatus(dir);
-    if (recognizedStatus(dir, status)) result.push({ dir, status });
+    if (recognizedStatus(dir, status, options)) result.push({ dir, status });
   }
   return result;
 }
 
 /** Scan every project under the configured runs root for worktree ownership. */
-export function allLiveRuns(runsRoot) {
+export function allLiveRuns(runsRoot, options = {}) {
   if (typeof runsRoot !== 'string' || !runsRoot.trim()) return [];
   let projects;
   try {
@@ -100,7 +110,7 @@ export function allLiveRuns(runsRoot) {
   const result = [];
   for (const project of projects) {
     if (!project.isDirectory()) continue;
-    result.push(...liveRuns(path.join(runsRoot, project.name)));
+    result.push(...liveRuns(path.join(runsRoot, project.name), options));
   }
   return result;
 }

package/src/hooks/reply-guard.mjs

@@ -31,10 +31,10 @@ import os from 'node:os';
 import path from 'node:path';
 import { readJsonFileSync } from '../json-file.mjs';
 import { isPidAlive, liveRuns, normalizePath } from './live-runs.mjs';
+import { FORM, MAX_STATE_BLOCKS, STATE, takeTry } from './guard-tries.mjs';
 
 const HOME = os.homedir();
 const LOG_DIR = path.join(HOME, '.claude', 'logs');
-const BLOCKED_FILE = path.join(LOG_DIR, 'codex-reply-guard.blocked.json');
 const GUARDED = new Set(['codex-scout', 'codex-build', 'codex-review']);
 const STATUSES = ['OK', 'FAIL', 'LIMIT'];
 
@@ -48,8 +48,6 @@ const STATUSES = ['OK', 'FAIL', 'LIMIT'];
  * quota on retries that never converge. Three tries, then let it through so the operator
  * sees a reply with substance in it and judges for himself.
  */
-const MAX_FORM_BLOCKS = 3;
-
 /**
  * The same allowance for blocks caused by EXTERNAL state — the run is still going, or its
  * runner died. Counted separately because the two run out for unrelated reasons: three
@@ -61,11 +59,6 @@ const MAX_FORM_BLOCKS = 3;
  * orchestrator got a promise from a process that no longer existed and never learned the
  * worktree was busy.
  */
-const MAX_STATE_BLOCKS = 3;
-
-const FORM = 'form';
-const STATE = 'state';
-
 /** Never let a guard failure break real work: on any doubt, stay silent. */
 const pass = () => process.exit(0);
 
@@ -91,56 +84,6 @@ if (!GUARDED.has(input.agent_type)) pass();
 const reply = String(input.last_assistant_message || '').trim();
 if (!reply) pass();
 
-/**
- * Reads one stored entry into {form, state}. Three shapes live in this file at once and all
- * three must keep their meaning: the current pair, the single number written by the previous
- * version, and an ISO string from the version before that (it meant "blocked once"). A
- * number is read as form tries — that budget is the one the old counter mostly guarded.
- * Anything else counts as one form try already spent, so an agent recorded before this fix
- * does not silently get its tries back.
- */
-const readCounts = (prior) => {
-  const whole = (value) => (Number.isInteger(value) && value > 0 ? value : 0);
-  if (prior && typeof prior === 'object' && !Array.isArray(prior)) {
-    return { form: whole(prior.form), state: whole(prior.state) };
-  }
-  if (typeof prior === 'number') return { form: whole(prior), state: 0 };
-  return { form: prior ? 1 : 0, state: 0 };
-};
-
-/**
- * Spends one try of the named budget. stop_hook_active is not reliable here (it already
- * arrives true in normal runs), so the loop protection is our own.
- *
- *   'granted'   — block normally, a try was recorded;
- *   'exhausted' — this budget is used up, the caller decides what that means;
- *   'untracked' — the guard cannot count at all (no agent id, log not writable). A guard
- *                 that cannot count must not decide anything, least of all end a session.
- */
-const takeTry = (agentId, kind) => {
-  if (!agentId) return 'untracked';
-  let seen;
-  try {
-    seen = readJsonFileSync(BLOCKED_FILE);
-  } catch {
-    seen = {};
-  }
-  if (!seen || typeof seen !== 'object' || Array.isArray(seen)) seen = {};
-  const counts = readCounts(seen[agentId]);
-  if (counts[kind] >= (kind === STATE ? MAX_STATE_BLOCKS : MAX_FORM_BLOCKS)) return 'exhausted';
-  counts[kind] += 1;
-  seen[agentId] = counts;
-  // Keep the file from growing without bound; order of insertion is good enough.
-  const ids = Object.keys(seen);
-  if (ids.length > 200) ids.slice(0, ids.length - 200).forEach((id) => delete seen[id]);
-  try {
-    fs.writeFileSync(BLOCKED_FILE, `${JSON.stringify(seen)}\n`);
-  } catch {
-    return 'untracked';
-  }
-  return 'granted';
-};
-
 const emit = (payload) => {
   process.stdout.write(JSON.stringify(payload));
   process.exit(0);

package/src/hooks/stop-guard.mjs

@@ -0,0 +1,71 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { STOP_TOOLS } from '../hook-definitions.mjs';
+import { runsRoot } from '../runner/runs-root.mjs';
+import { renderStopCommand, STOP_REASON } from '../stop-contract.mjs';
+import { allLiveRuns, normalizePath } from './live-runs.mjs';
+import { takeTry } from './guard-tries.mjs';
+
+/**
+ * Plan_31 catches TaskStop killing the dispatcher wrapper while the runner keeps writing. It
+ * must stay silent on malformed input or uncertain liveness, and the second denial budget keeps
+ * an unrelated host task from becoming impossible to stop.
+ */
+
+const pass = () => process.exit(0);
+const isObject = (value) => value && typeof value === 'object' && !Array.isArray(value);
+
+function readInput() {
+  try {
+    return JSON.parse(fs.readFileSync(0, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function runForRepository(cwd) {
+  const repository = normalizePath(cwd);
+  if (!repository) return null;
+
+  let live;
+  try {
+    live = allLiveRuns(runsRoot(), { requireConfirmedIdentity: true });
+  } catch {
+    return null;
+  }
+
+  return live
+    .filter(({ status }) => {
+      const runRepository = normalizePath(status.repo);
+      return runRepository === repository || repository.startsWith(`${runRepository}/`);
+    })
+    .sort(({ status: left }, { status: right }) => right.repo.length - left.repo.length)[0] ?? null;
+}
+
+function deny(run) {
+  const runName = path.basename(run.dir);
+  // Key by run folder: the host task_id can belong to an unrelated background build, so it cannot
+  // safely identify the dispatcher this guard just warned about.
+  if (takeTry(normalizePath(run.dir), 'stop', 1) !== 'granted') pass();
+
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason:
+        `TaskStop denied: live run ${runName} is working. `
+        + `Use ${renderStopCommand(runName)}. ${STOP_REASON}`,
+    },
+  }));
+}
+
+const input = readInput();
+if (!isObject(input) || !STOP_TOOLS.includes(input.tool_name)) pass();
+if (!isObject(input.tool_input) || typeof input.tool_input.task_id !== 'string' || !input.tool_input.task_id) {
+  pass();
+}
+if (typeof input.cwd !== 'string' || !input.cwd) pass();
+
+const run = runForRepository(input.cwd);
+if (!run) pass();
+deny(run);

package/src/runner/args.mjs

@@ -97,7 +97,16 @@ export function parseArgs(argv) {
     die(`--effort must be one of: ${allowedEfforts}; got ${JSON.stringify(opts.effort)}`);
   }
   opts.repo = path.resolve(opts.repo || process.cwd());
-  opts.slug = (opts.slug || opts.agent.replace(/^codex-/, '')).replace(/[^A-Za-z0-9._-]+/g, '-');
+  const slugSource = opts.slug ? '--slug' : '--order-id';
+  opts.slug = (opts.slug || opts.orderId).replace(/[^A-Za-z0-9._-]+/g, '-');
+  // Plan_29 incident: the generic `build` slug made an honest order inherit a days-old chain;
+  // reject a value with no alphanumeric anchor instead of creating an empty or dot-only folder.
+  if (!/[A-Za-z0-9]/.test(opts.slug)) {
+    die(
+      `${slugSource} produces an unusable run folder name after sanitization: ` +
+        `${JSON.stringify(opts.slug)} must contain a letter or digit.`,
+    );
+  }
   opts.mode = opts.mode || 'uncommitted';
   // A writing run without a declared scope is how `!Plans/*.md` got edited by a run that was
   // told in prose not to touch them: prose does not bind, a file list does. Required rather

package/src/runner/attach.mjs

@@ -10,6 +10,13 @@ import { exitCodeFor, writeFailure, chainRuns } from '../write-meta.mjs';
 const POLL_MS = 500;
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
+// The 2026-08-10_220535_plan25-2-install-table-two-roots incident showed that ATTACH alone
+// can be mistaken for this pass; state the previous run and the fact that no work was started.
+function announceAttach(runDir, startedAt) {
+  console.log(`ATTACH=${runDir} started=${startedAt}`);
+  console.log(`This is the answer of the previous run started at ${startedAt}; no new work was started.`);
+}
+
 export const readJsonFile = (file) => {
   try {
     return readJsonFileSync(file);
@@ -86,7 +93,7 @@ export async function attach({ runsRoot, repo, slug, taskHash, orderId, chain, i
     const entry = sameOrder[i];
     const dir = path.join(runsRoot, entry.run);
     if (fs.existsSync(path.join(dir, 'reply.txt'))) {
-      console.log(`ATTACH=${dir} started=${entry.status.started_at}`);
+      announceAttach(dir, entry.status.started_at);
       console.log(fs.readFileSync(path.join(dir, 'reply.txt'), 'utf8').replace(/\s+$/, ''));
       return exitCodeFor(readJsonFile(path.join(dir, 'meta.json'))?.status);
     }
@@ -98,7 +105,7 @@ export async function attach({ runsRoot, repo, slug, taskHash, orderId, chain, i
   if (!candidate) return null;
 
   const runDir = path.join(runsRoot, candidate.run);
-  console.log(`ATTACH=${runDir} started=${candidate.status.started_at}`);
+  announceAttach(runDir, candidate.status.started_at);
   const replyText = await waitForReply(runDir, candidate.status.pid, candidate.status);
   if (replyText !== null) {
     console.log(replyText);

package/src/runner/continuation.mjs

@@ -37,6 +37,28 @@ const grantExample = `Example: \`continue: ${CONTINUATION_INPUT.example}\`.`;
 const grantAction =
   'Action: ask the orchestrator for an explicit grant naming the run and reason; do not invent or reuse a continuation.';
 
+// The 2026-08-10_220535_plan25-2-install-table-two-roots incident showed that a refusal must
+// carry the repair line; otherwise a typo forces an unnecessary directory listing and retry.
+function lastRunOutcome(runsRootPath, chain) {
+  const run = chain[chain.length - 1];
+  if (!run) return null;
+  const status = readJson(path.join(runsRootPath, run, 'status.json')) || {};
+  const meta = readJson(path.join(runsRootPath, run, 'meta.json')) || {};
+  const outcomeStatus = String(meta.status ?? status.status ?? status.state ?? 'unknown').trim() || 'unknown';
+  const outcomeReason = String(meta.reason ?? status.reason ?? 'reason not recorded').trim() || 'reason not recorded';
+  return { run, status: outcomeStatus, reason: outcomeReason };
+}
+
+function lastRunHints(runsRootPath, chain, grantReason) {
+  const last = lastRunOutcome(runsRootPath, chain);
+  if (!last) {
+    return 'Last run: none. Outcome: none. Ready grant line: none (there is no run to continue).';
+  }
+  const reason = String(grantReason ?? last.reason).trim() || last.reason;
+  return `Last run: ${last.run}. Outcome: ${last.status} — ${last.reason}. ` +
+    `Ready grant line: continue: ${last.run} — ${reason}.`;
+}
+
 /**
  * Applies the one-continuation limit and all continuation safety gates before a folder is created.
  *
@@ -49,9 +71,16 @@ const grantAction =
  * unrunnable, which is a worse failure than the retry storm this limit exists to stop.
  */
 export function continuationRefusal(runsRootPath, chain, isContinue, orderId, grant) {
-  if (!isContinue) return null;
-
   const continuation = normalizeGrant(grant);
+  if (!isContinue) {
+    if (!continuation) return null;
+    return (
+      '--continue is required when the task text contains a `continue:` grant. ' +
+      `${lastRunHints(runsRootPath, chain, continuation.reason)} ` +
+      'The submitted grant was not rewritten. The run folder was not created; quota was not spent.'
+    );
+  }
+
   if (!continuation) {
     return (
       '--continue is refused: the orchestrator did not provide a `continue:` grant in the task text. ' +
@@ -64,7 +93,9 @@ export function continuationRefusal(runsRootPath, chain, isContinue, orderId, gr
     return (
       `--continue is refused: the orchestrator named run “${continuation.run}”, but it does not ` +
       `exist as a run folder in this project's runs directory ${runsRootPath}. ` +
-      `${grantExample} ${grantAction} The run folder was not created; quota was not spent.`
+      `${lastRunHints(runsRootPath, chain, continuation.reason)} ` +
+      `${grantExample} ${grantAction} The submitted grant was not rewritten. ` +
+      'The run folder was not created; quota was not spent.'
     );
   }
 

package/src/runner/launcher.mjs

@@ -135,7 +135,21 @@ export async function launcher() {
   const taskHash = taskFingerprint(taskText);
   const chain = chainRuns(projectRunsRoot, repoRoot, opts.slug, taskHash, opts.orderId);
   const startedChain = startedRuns(projectRunsRoot, chain);
-  const continuationGrant = opts.continue ? parseContinuationGrant(taskText) : null;
+  const continuationGrant = parseContinuationGrant(taskText);
+
+  // The 2026-08-10_220535_plan25-2-install-table-two-roots incident exposed this ordering:
+  // a grant without its flag must refuse before attach can print an older run's verdict.
+  // markAbandoned() ran before this gate, so a dead runner already has meta.json with FAIL.
+  // A run without a verdict can therefore only still be in flight; ordinary repeats go through
+  // attach(), while --continue must refuse to overlap that live work.
+  const continuationError = continuationRefusal(
+    projectRunsRoot,
+    startedChain,
+    opts.continue,
+    opts.orderId,
+    continuationGrant,
+  );
+  if (continuationError) die(continuationError);
 
   // One order produced six Codex runs on 2026-08-03 because the caller's time ceiling made it
   // restart the synchronous launcher. A live same-order run is now the repeat target: attach
@@ -151,18 +165,6 @@ export async function launcher() {
   });
   if (attachedExitCode !== null) process.exit(attachedExitCode);
 
-  // markAbandoned() ran before this gate, so a dead runner already has meta.json with FAIL.
-  // A run without a verdict can therefore only still be in flight; ordinary repeats go through
-  // attach(), while --continue must refuse to overlap that live work.
-  const continuationError = continuationRefusal(
-    projectRunsRoot,
-    startedChain,
-    opts.continue,
-    opts.orderId,
-    continuationGrant,
-  );
-  if (continuationError) die(continuationError);
-
   if (startedChain.length && !opts.continue) {
     const last = startedChain[startedChain.length - 1];
     const lastSlug = String(readJson(path.join(projectRunsRoot, last, 'status.json'))?.slug || '');

package/src/stop-contract.mjs

@@ -0,0 +1,15 @@
+export const STOP_COMMAND = 'codex-bridge stop';
+export const STOP_COMMAND_TEMPLATE = `${STOP_COMMAND} <run>`;
+export const STOP_REASON =
+  'TaskStop removes the wrapper while the run keeps writing to the worktree.';
+
+export function renderStopCommand(run) {
+  if (typeof run !== 'string' || !run.trim()) {
+    throw new TypeError('A run folder name is required to render the stop command.');
+  }
+  return `${STOP_COMMAND} ${run.trim()}`;
+}
+
+export function renderStopSummary() {
+  return `Stop live runs with \`${STOP_COMMAND_TEMPLATE}\` before \`TaskStop\`: ${STOP_REASON}`;
+}

package/src/write-meta.mjs

@@ -22,6 +22,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { readJsonFileSync } from './json-file.mjs';
 import { changedPaths, readJson, readText, size } from './meta/paths.mjs';
 import { splitRunChanges } from './meta/environment.mjs';
 import { readEvents } from './meta/events.mjs';
@@ -29,6 +30,8 @@ import { writeStatus } from './meta/run-state.mjs';
 import { resolveStatus } from './meta/verdict.mjs';
 import { AGENTS, failReply, limitReply } from './meta/reply.mjs';
 
+const RUNNER_VERSION = readJsonFileSync(new URL('../package.json', import.meta.url)).version;
+
 export { expandDeclared, globToRegExp, readJson } from './meta/paths.mjs';
 export { chainBaseline, chainRuns, taskFingerprint } from './meta/chain.mjs';
 export { abortedPreStart, startedRuns } from './meta/pre-start.mjs';
@@ -84,6 +87,7 @@ export function collect(runDir, agent, exitCode) {
 
   const meta = {
     agent,
+    runner_version: RUNNER_VERSION,
     project: path.basename(path.dirname(runDir)),
     run: path.basename(runDir),
     finished_at: new Date().toISOString(),