codex-orchestrator 0.1.31 → 0.1.35

package/CHANGELOG.md

@@ -6,6 +6,71 @@ The format is based on Keep a Changelog, and this project follows SemVer.
 
 ## [Unreleased]
 
+## [0.1.35] - 2026-05-21
+
+### Added
+- Added a runner-validated UI Evidence Contract for Acceptance Proof reports,
+  covering workflow, viewport, freshness, layout, copy, and source-input
+  evidence for screenshot and UI-dump artifacts.
+- Added live smoke coverage for UI Evidence pass and blocking cases, including
+  missing UI Evidence and too-narrow desktop viewport proof.
+
+### Changed
+- Runner-owned visual proof no longer treats screenshot-only command success as
+  a pass path; proof commands must produce a valid machine-readable Acceptance
+  Proof report.
+- Updated the legacy `visual-proof` live smoke scenario to emit the same
+  machine-readable UI Evidence report required by the runner.
+
+## [0.1.34] - 2026-05-20
+
+### Added
+- Added an Adaptive Proof Agent Codex phase for scoped and issue-tree child
+  runs, with runner-provided proof report paths, artifact directories, changed
+  file context, and proof-owned repair policy.
+- Added durable Acceptance Proof attempt evidence in lifecycle events, run
+  summaries, blocked comments, review reports, and issue-tree PR handoff.
+- Added package-bundled Acceptance Proof workflow prompts and setup routing for
+  the new proof phase.
+
+### Changed
+- Parent `agent:plan-auto` child waves now block parent publication when a child
+  Acceptance Proof attempt fails, requests rework, or is blocked.
+- Proof attempts now use isolated Codex homes and preserve proof artifacts while
+  keeping publication authority runner-owned.
+
+## [0.1.33] - 2026-05-20
+
+### Added
+- Added canonical `reviewGates.acceptanceProof` policy with proof-owned path
+  classification and machine validation for high-confidence proof reports.
+- Added live smoke scenarios for canonical Acceptance Proof pass, proof rework,
+  low-confidence blocking, and proof-phase product-diff blocking.
+
+### Changed
+- Kept `reviewGates.visualProof` as a compatibility adapter while routing
+  runner prompts and proof policy through Acceptance Proof.
+- Proof-phase product-code changes now block publishability instead of being
+  silently committed as verification output.
+
+## [0.1.32] - 2026-05-19
+
+### Added
+- Added package-owned `visual-proof mobile`, `visual-proof android`, and
+  `visual-proof ios` commands for reusable UI launch proof across installed
+  repositories.
+- Mobile visual proof now supports Flutter Android, native Android, Flutter iOS,
+  and native iOS projects, with screenshots saved into runner proof artifacts.
+
+### Changed
+- Setup now defaults visual proof to
+  `codex-orchestrator visual-proof mobile --issue ${issueNumber}` instead of a
+  target-repo local proof script.
+- Android proof resolves SDK tools from environment variables, `PATH`, and
+  default macOS, Linux, and Windows SDK locations.
+- On macOS, mobile proof falls back to the iOS simulator when Android tooling or
+  devices are unavailable and the repo has an iOS target.
+
 ## [0.1.30] - 2026-05-18
 
 ### Added

package/README.md

@@ -1,6 +1,10 @@
 # codex-orchestrator
 
-`codex-orchestrator` turns GitHub Issues into controlled Codex work.
+## About
+
+`codex-orchestrator` turns GitHub Issues and project work into isolated,
+autonomous Codex implementation runs, allowing maintainers to manage work
+instead of supervising coding agents.
 
 Instead of starting a new Codex chat for every issue, you label the work you
 want automated. The runner creates an isolated workspace, gives Codex the issue
@@ -41,29 +45,76 @@ control to humans before anything is merged.
 - A repeatable way to send selected GitHub Issues to Codex.
 - One-off autonomous runs for scoped implementation tasks.
 - Parent planning for larger features, with child issues executed in safe waves.
-- Project-owned rules for labels, branches, prompts, checks, review gates, and
-  blocked actions.
-- Full change-set checks, including local commits, staged files, unstaged files,
-  and untracked files.
-- Durable logs and summaries when a run is interrupted, blocked, or ready for
-  review.
+- Project-owned rules for what Codex may run, how results are checked, and when
+  a human must step in.
+- Adaptive Acceptance Proof for runner-owned verification of UI, API, worker,
+  CLI, browser, mobile, and live-smoke behavior before draft PR handoff.
+- Logs, summaries, and proof artifacts when available.
+- Recovery for interrupted runner handoff when Codex finished locally but the
+  draft PR was not created yet.
 - Draft PR handoff by default. No auto-merge.
 
 ## How It Works
 
-There are two main modes.
+At a high level, GitHub Issues are the queue, labels authorize work, isolated
+worktrees keep runs separate, and the runner owns validation and publication.
+
+```mermaid
+flowchart TD
+  A["Target repo"] --> B["codex-orchestrator setup"]
+  B --> C[".codex-orchestrator/config.json + prompts"]
+  C --> D["GitHub Issue gets agent:auto or agent:plan-auto"]
+  D --> E["status / daemon / run"]
+  E --> R{"Recover interrupted handoff?"}
+  R -- "yes" --> L
+  R -- "no" --> F{"Eligible?"}
+  F -- "no" --> G["Skipped with reason"]
+  F -- "yes" --> H["Runner claims issue: agent:running"]
+  H --> I["Create isolated branch + worktree"]
+  I --> J["Build Codex prompt from issue + repo policy"]
+  J --> K["Run Codex CLI"]
+  K --> AAP{"Adaptive Acceptance Proof required?"}
+  AAP -- "no" --> L["Runner validates the full changeset"]
+  AAP -- "yes" --> AP["Run proof phase and collect artifacts"]
+  AP --> APR{"Proof result"}
+  APR -- "passed" --> L
+  APR -- "needs rework" --> J
+  APR -- "blocked" --> N
+  L --> M{"Gates pass?"}
+  M -- "no" --> N["Mark blocked, preserve evidence"]
+  M -- "yes" --> O["Push branch"]
+  O --> P["Open draft PR"]
+  P --> Q["Move issue to agent:review + post report"]
+```
+
+The important boundary is simple: Codex writes code, but the runner decides
+whether that code can be handed to humans. The runner owns checks, acceptance
+proof, labels, comments, branch pushes, and draft PR creation.
 
-### `agent:auto`
+### Adaptive Acceptance Proof
+
+Adaptive Acceptance Proof is the runner-owned verification phase for work that
+needs observable product proof. After implementation, the runner can start a
+separate proof phase that inspects the issue, changed files, and acceptance
+criteria; runs focused browser, mobile, API, worker, CLI, or live-smoke checks;
+and writes a machine-readable proof report with artifact links.
+
+A result can reach draft PR handoff only when every required criterion maps to
+high-confidence artifact evidence. If proof finds missing behavior, it returns a
+concrete rework request and the runner loops back through implementation within
+the configured iteration limit. If proof is malformed, low-confidence, lacks
+artifacts, or changes product code during verification, the runner blocks
+publication and preserves the evidence.
+
+For UI proof, screenshots and UI dumps must also satisfy the UI Evidence
+Contract: exact workflow, viewport coverage, current artifact freshness, layout
+review, copy review, and source inputs. Screenshot-only proof cannot pass.
 
-Use `agent:auto` for one clear standalone implementation issue. Do not use it
-for child issues created by `agent:plan-auto`; those are marked with
-`agent:child` and are executed only by the parent issue-tree flow.
+There are two main ways to run work.
 
-When a daemon is allowed to run more than one scoped issue at a time, parallel
-`agent:auto` selection is conservative. An issue must include a
-`## codex-orchestrator metadata` section with an `Ownership:` bullet list, and
-same-batch issues must not overlap by exact path or supported glob. Issues
-without ownership metadata still run, but only one at a time.
+### `agent:auto`
+
+Use `agent:auto` for one clear standalone implementation issue.
 
 The runner:
 
@@ -75,18 +126,26 @@ The runner:
 6. Pushes the branch and opens a draft PR only after the gates pass.
 7. Moves the issue to review and posts the run report.
 
+When the daemon runs more than one `agent:auto` issue at once, it only batches
+issues whose declared ownership does not overlap. Issues without ownership
+metadata still run, but conservatively.
+
 ### `agent:plan-auto`
 
-Use `agent:plan-auto` for work that needs planning first.
+Use `agent:plan-auto` for larger work that should be planned before
+implementation.
 
 The runner asks Codex to plan the parent issue, break it into child issues,
-triage them, run safe children in dependency order, and then open one
-integration draft PR.
+run safe children in dependency order, merge successful child branches into one
+integration branch, validate that integration branch, and then open one draft
+PR.
+
+Child issues created by this flow use `agent:child`, not `agent:auto`. They are
+owned by the parent run and are not picked up as standalone daemon work.
 
-Only child issues explicitly marked by the runner belong to the autonomous tree.
-Ordinary links, milestones, project fields, or casual references are not enough.
-Child issues use `agent:child`, not `agent:auto`, so the daemon cannot confuse
-parent-owned child work with standalone scoped work.
+If a runner stops after Codex finished locally but before draft PR handoff, the
+runner can recover from its local state and completed report without rerunning
+Codex. See [docs/deep-dive.md](docs/deep-dive.md) for the recovery rules.
 
 ## Basic Workflow
 
@@ -100,7 +159,13 @@ parent-owned child work with standalone scoped work.
 
 The runner never auto-merges.
 
-## Installation
+## Agent Memory
+
+Repo-local Dreaming-lite memory lives in `docs/agents/memory/`. It is a small
+curated lessons cache for repeated runner/debug/agent-workflow patterns, not a
+replacement for `AGENTS.md`, ADRs, `docs/deep-dive.md`, or package prompts.
+
+## Install
 
 Requirements:
 
@@ -129,7 +194,7 @@ You can also run it with `npx`:
 npx codex-orchestrator --help
 ```
 
-## Quick Start
+## Set Up A Repository
 
 Open the repository that should receive autonomous Codex work:
 
@@ -143,19 +208,19 @@ Run setup and create missing labels:
 codex-orchestrator setup --prepare-labels
 ```
 
-By default, setup reads the GitHub owner and repository name from `git remote
-origin` and uses the current directory as the target repository. Use `--target`,
-`--github-owner`, and `--github-repo` only when you need to override those
-defaults.
-
 Commit the generated `.codex-orchestrator/` directory to your repository. It is
 the repository-owned policy for how autonomous work should run.
 
-Check eligible work:
+By default, setup reads the GitHub owner and repo from `git remote origin`. Use
+`--target`, `--github-owner`, or `--github-repo` only when you need to override
+that.
+
+## Run Work
+
+Check what the runner can see:
 
 ```sh
 codex-orchestrator status --target .
-codex-orchestrator status --target . --json
 codex-orchestrator doctor --target .
 ```
 
@@ -171,12 +236,16 @@ Run the daemon:
 codex-orchestrator daemon --target .
 ```
 
-Run up to three independent scoped issues in one daemon batch:
+Run up to three independent scoped issues at once:
 
 ```sh
 codex-orchestrator daemon --target . --concurrency 3
 ```
 
+`status` and `doctor` are read-only. `run` executes one selected issue.
+`daemon` polls for eligible work and starts safe runs according to the policy in
+`.codex-orchestrator/config.json`.
+
 ## Agent-Assisted Setup
 
 You do not need a long prompt. You can ask an agent:
@@ -205,126 +274,60 @@ working in the repository can find repository-local setup guidance.
 Use `--dry-run` only when you want a preview without writing files or creating
 labels.
 
-## Project Policy
+## What The Runner Checks
 
-Every installed repository owns its config:
+Before a result becomes a draft PR, the runner checks the whole local result:
 
-```sh
-.codex-orchestrator/config.json
-```
+- committed changes;
+- staged changes;
+- unstaged changes;
+- untracked files;
+- the completion report Codex was required to write;
+- configured commands such as tests or type checks;
+- review gates such as TDD evidence, changed tests, cleanup review, code review,
+  or acceptance proof when enabled;
+- blocked paths and unsafe actions.
 
-That config is where the repo decides how strict automation should be. It
-controls the GitHub repo, labels, base branch, branch names, validation checks,
-review gates, blocked paths, child issue concurrency, durable logs, PR titles,
-and the prompts used for planning and implementation.
-
-The package ships bundled workflow prompts, so a repository does not need local
-Codex `SKILL.md` files installed on the user's machine. Setup copies those
-prompts into `.codex-orchestrator/prompts/workflows/`, and the runner reads the
-copied prompt files during `agent:auto` and `agent:plan-auto` runs. Workflow
-`skillName` values in config are descriptive metadata for the workflow role;
-they are not a runtime dependency on the user's local Codex skill directory.
-Setup also writes `.codex-orchestrator/prompts/manifest.json`, which lets later
-setup runs tell apart untouched package prompts from prompts edited by the
-project. By default, setup refreshes untouched prompts and reports conflicts for
-locally edited prompts.
-
-Configured checks run before publication. By default, missing
-`npm run <script>` checks are reported as skipped warnings, not failures. You can
-change that with `checksPolicy.missingNpmScript`.
-
-For repos with existing lint debt, `checksPolicy.lintBaseline.mode` can be set
-to `touched-only`. That lets a repo-wide lint failure be downgraded when a
-separate touched-files lint command passes.
-
-The default quality gate is conservative for runtime code changes. It can
-require TDD evidence, changed tests, code review, cleanup review for larger
-changes, and visual proof for UI work.
-
-## Diagnostics
-
-`doctor` is a read-only readiness check for operators. It validates the target
-config, GitHub label visibility, git/base branch access, runner state paths,
-configured checks, the Codex command, phase profiles, and visual proof settings.
-It never launches Codex, creates worktrees, edits labels, or changes issues.
+If the result passes, the runner pushes the branch and opens a draft PR. If it
+does not pass, the runner marks the issue blocked, keeps the useful local
+evidence, and explains what needs attention.
 
-```sh
-codex-orchestrator doctor --target .
-codex-orchestrator doctor --target . --json
-```
+Acceptance proof is runner-owned. Codex can change product behavior, but the
+runner runs proof afterwards and attaches screenshots, UI dumps, logs, smoke
+outputs, or other artifacts to the PR and issue report. The proof phase must
+produce a structured report that maps each required criterion to high-confidence
+evidence. UI artifacts must include UI Evidence Contract mapping, and legacy
+visual proof config only supplies migration inputs for report-producing proof.
 
-`status --json` returns the same queue view as text status plus active local
-runs and recent lifecycle events. The JSON is designed for wrappers and
-dashboards; it includes bounded artifact paths such as context snapshots, but
-not raw Codex transcripts, secrets, prompt text, or full issue comments.
-
-Codex command profiles can be set per runner phase under `codex.profiles`.
-Supported phases are `plan-parent`, `scoped-issue`, `tree-child`,
-`fresh-context-review`, `visual-proof`, and `quality-review`. Missing profile
-fields fall back to the global `codex.command`, `codex.args`, `timeoutMs`, and
-`idleTimeoutMs`, so existing configs keep working.
-
-Each Codex session writes a bounded context snapshot before invocation and links
-it from lifecycle events under the runner state directory. Snapshots record the
-issue identity, runner decision, selected profile, workspace paths, and
-publication boundaries so a maintainer can reproduce why a session started
-without reading raw logs.
-
-## Visual Proof
-
-For browser UI work, configure a runner-owned proof command, usually a
-Playwright script:
-
-```json
-{
-  "reviewGates": {
-    "visualProof": {
-      "runnerValidationCommand": "npm run visual-proof -- --issue ${issueNumber}",
-      "runnerTimeoutMs": 900000,
-      "envPassthrough": [
-        "CODEX_ORCHESTRATOR_LOGIN_EMAIL",
-        "CODEX_ORCHESTRATOR_LOGIN_PASSWORD"
-      ]
-    }
-  }
-}
-```
+## Repository Policy
+
+Every installed repository owns its automation policy in:
 
-The runner executes this command from the issue worktree after Codex finishes
-and before review-gate evaluation. It sets environment variables for the issue
-number, artifact directory, proof directory, Playwright profile directory,
-worktree path, and changed files.
+```sh
+.codex-orchestrator/config.json
+```
 
-Screenshots created under `CODEX_ORCHESTRATOR_PROOF_DIR` are attached to the PR
-and issue review report. Keep login credentials outside config and expose only
-their variable names through `envPassthrough`.
+That config controls labels, branch names, checks, review gates, blocked paths,
+prompt files, child concurrency, and PR titles. The package provides defaults;
+the target repository decides how strict they should be.
 
-For Android UI work, the implementation prompt asks Codex to use `adb` or an
-emulator-backed proof path instead of browser proof. Missing Android tooling or
-no usable device is reported as a warning with the concrete reason, not as an
-automatic release blocker. Native Android proof uses the project Gradle wrapper
-with a writable Gradle cache; Flutter-specific SDK cache recovery is used only
-for Flutter projects and only through a preconfigured writable SDK path in
-`CODEX_ORCHESTRATOR_FLUTTER_ROOT`. Native iOS proof uses Xcode simulator/device
-tooling with a writable DerivedData path.
+For the full config surface and technical behavior, see
+[docs/deep-dive.md](docs/deep-dive.md).
 
 ## Safety Model
 
 The package is PR-first and human-reviewed. The important guardrails are:
 
-- no automatic merge, and only draft PRs are opened;
+- no automatic merge;
+- draft PRs only;
 - Codex may change files, but the runner owns remote publication and GitHub
-  state;
+  state changes;
 - only explicitly authorized issues run;
 - child issues are never inferred from ordinary links or references;
-- committed and uncommitted changes are checked before publication;
-- secret files, destructive data/cache actions, and production deploy/release
-  actions are blocked by default;
-- malformed or missing completion reports block publication;
-- bounded rework stops at the configured limit;
-- Policy Suggestions are recommendations only;
-- underspecified work can be blocked for maintainer clarification instead of
-  letting Codex invent product decisions.
+- committed and uncommitted changes are checked;
+- missing or malformed completion reports block publication;
+- secret files, destructive data/cache actions, and production deploy or release
+  actions are blocked by default.
 
 ## Labels
 
@@ -352,47 +355,15 @@ codex-orchestrator setup [--target <path>] [--github-owner <owner>] \
   [--github-repo <repo>] [--dry-run] [--prepare-labels]
 codex-orchestrator status --target <path> [--dry-run] [--json]
 codex-orchestrator run --target <path> --issue <number>
+codex-orchestrator visual-proof mobile --issue <number> [--target <path>]
+codex-orchestrator visual-proof android --issue <number> [--target <path>]
+codex-orchestrator visual-proof ios --issue <number> [--target <path>]
 codex-orchestrator daemon --target <path> [--once] \
   [--interval-seconds <seconds>] [--max-runs <count>] \
   [--concurrency <count>]
 ```
 
-`setup` creates project-local config and prompt files under
-`.codex-orchestrator/`. Useful flags:
-
-- `--dry-run` - show the setup plan without writing files or creating labels;
-- `--prepare-labels` - create missing GitHub labels;
-- `--target <path>` - override the target directory, which defaults to the current directory;
-- `--github-owner <owner>` - override the GitHub owner inferred from `origin`;
-- `--github-repo <repo>` - override the GitHub repo inferred from `origin`;
-- `--sync-prompts <auto|keep|replace|merge>` - choose how package-bundled
-  prompt updates are applied. `auto` refreshes untouched prompts and reports
-  local-edit conflicts, `keep` preserves existing prompts, `replace` overwrites
-  with bundled prompts, and `merge` appends bundled updates to locally edited
-  prompts;
-- `--replace-package-skills` - refresh package-bundled prompt files. The flag
-  name is kept for compatibility and behaves like `--sync-prompts=replace`; it
-  does not install or require local Codex skills.
-
-Setup does not launch Codex, commit changes, or open pull requests.
-When the target repository already has a `package.json`, setup also adds
-`orchestrator:*` npm scripts. Daemon scripts run `doctor` first, then start the
-daemon only if the readiness check passes.
-
-`status` is read-only. It shows eligible issues, skipped issues with reasons,
-and local recovery state.
-
-`run` executes one selected issue when labels and state allow it. `agent:auto`
-opens one scoped draft PR. `agent:plan-auto` runs parent planning, child waves,
-final validation, and one integration draft PR.
-
-`daemon` polls for eligible work. By default, fresh setup config allows up to
-three scoped issues per batch through `runner.maxParallelScopedIssues`; legacy
-configs without that field remain sequential unless `--concurrency` is passed.
-Only scoped issues with non-overlapping ownership metadata can share a batch.
-`agent:plan-auto` runs remain exclusive. The daemon also cleans up runner-owned
-worktrees after their PRs are merged, while preserving dirty, blocked, active,
-or unpublished worktrees for inspection.
+Use `codex-orchestrator <command> --help` for command-specific flags.
 
 ## Current Scope
 

package/dist/src/cli.js

@@ -8,7 +8,11 @@ import { runDaemonCommand } from './runner/daemon-command.js';
 import { runDoctorCommand } from './runner/doctor-command.js';
 import { runPlanAutoCommand } from './runner/plan-auto-command.js';
 import { runScopedAutoCommand } from './runner/scoped-auto-command.js';
+import { recoverScopedRun } from './runner/scoped-recovery.js';
 import { runStatusCommand } from './runner/status-command.js';
+import { parseAndroidVisualProofArgs, runAndroidVisualProofCommand } from './runner/android-visual-proof-command.js';
+import { parseIosVisualProofArgs, runIosVisualProofCommand } from './runner/ios-visual-proof-command.js';
+import { parseMobileVisualProofArgs, runMobileVisualProofCommand } from './runner/mobile-visual-proof-command.js';
 import { runSetupCommand } from './setup/setup-command.js';
 import { promptSyncModes } from './setup/prompt-sync.js';
 const helpText = `codex-orchestrator
@@ -22,6 +26,9 @@ Usage:
   codex-orchestrator status --target <path> [--dry-run] [--json]
   codex-orchestrator run --target <path> --issue <number>
   codex-orchestrator daemon --target <path> [--interval-seconds <number>] [--once] [--max-runs <number>] [--concurrency <number>]
+  codex-orchestrator visual-proof mobile --issue <number> [--target <path>]
+  codex-orchestrator visual-proof android --issue <number> [--target <path>]
+  codex-orchestrator visual-proof ios --issue <number> [--target <path>]
 
 Commands:
   health       Run a no-op local health check.
@@ -30,6 +37,7 @@ Commands:
   status       Show eligible/skipped issue work and local recovery state.
   run          Execute one authorized issue: scoped agent:auto or full agent:plan-auto issue tree.
   daemon       Poll GitHub Issues and execute eligible autonomous work until stopped.
+  visual-proof Run package-owned proof commands used by review gates.
 
 Options:
   --help, -h      Show this help.
@@ -164,6 +172,48 @@ async function main(args) {
             return 1;
         }
     }
+    if (command === 'visual-proof') {
+        const [kind, ...rest] = args.slice(1);
+        if (kind !== 'mobile' && kind !== 'android' && kind !== 'ios') {
+            process.stderr.write('visual-proof requires a supported kind: mobile, android, or ios\nRun codex-orchestrator --help for usage.\n');
+            return 2;
+        }
+        try {
+            if (kind === 'mobile') {
+                const parsed = parseMobileVisualProofArgs(rest);
+                if (!parsed.ok) {
+                    process.stderr.write(`${parsed.error}\nRun codex-orchestrator --help for usage.\n`);
+                    return 2;
+                }
+                await runMobileVisualProofCommand(parsed.value);
+                process.stdout.write(`mobile visual proof captured for issue #${parsed.value.issueNumber}\n`);
+            }
+            else if (kind === 'ios') {
+                const parsed = parseIosVisualProofArgs(rest);
+                if (!parsed.ok) {
+                    process.stderr.write(`${parsed.error}\nRun codex-orchestrator --help for usage.\n`);
+                    return 2;
+                }
+                await runIosVisualProofCommand(parsed.value);
+                process.stdout.write(`ios visual proof captured for issue #${parsed.value.issueNumber}\n`);
+            }
+            else {
+                const parsed = parseAndroidVisualProofArgs(rest);
+                if (!parsed.ok) {
+                    process.stderr.write(`${parsed.error}\nRun codex-orchestrator --help for usage.\n`);
+                    return 2;
+                }
+                await runAndroidVisualProofCommand(parsed.value);
+                process.stdout.write(`android visual proof captured for issue #${parsed.value.issueNumber}\n`);
+            }
+            return 0;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'visual proof failed';
+            process.stderr.write(`${message}\n`);
+            return 1;
+        }
+    }
     process.stderr.write(`Unknown command: ${command}\nRun codex-orchestrator --help for usage.\n`);
     return 1;
 }
@@ -177,6 +227,15 @@ async function runIssueCommand(targetRootInput, issueNumber) {
     }
     const decision = discoverIssueWork([issue], config)[0];
     if (!decision || decision.kind !== 'eligible') {
+        const recovered = await recoverScopedRun({
+            targetRoot,
+            issueNumber,
+            invocation: 'targeted',
+            issueAdapter,
+        });
+        if (recovered.status !== 'not-recoverable') {
+            return { reportComment: recovered.reportComment };
+        }
         const reason = decision?.kind === 'skipped' ? decision.reason : 'not eligible';
         throw new Error(`Issue #${issueNumber} is not eligible for autonomous work: ${reason}`);
     }