wade-cli 1.0.0__tar.gz → 1.1.1__tar.gz

{wade_cli-1.0.0 → wade_cli-1.1.1}/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Conventional Commits](https://conventionalcommits.org/).
 
+## [v1.1.1] — 2026-09-08
+
+### Bug Fixes
+
+- review limitation on reviews (#500) (3479794)
+
+## [v1.1.0] — 2026-09-04
+
+### Features
+
+- diagnose sandboxed parent runtimes and keep review gates closed (#481) (4440220)
+
 ## [v1.0.0] — 2026-09-03
 
 ### Breaking Changes

{wade_cli-1.0.0 → wade_cli-1.1.1}/KNOWLEDGE.md

@@ -749,3 +749,45 @@ scripts/changelog.py's format_range is re-run by generate() for EVERY tag range
 The release version bump is derived from the PR title ALONE — .github/workflows/auto-version.yml greps only github.event.pull_request.title, never commit history — and done.py's PR-title sync overwrites that title from the ISSUE title on every done. So a `feat!:` commit with a real BREAKING CHANGE footer still ships as a MINOR release unless issue #N's own title carries the `!`; retitle the issue (gh issue edit --title, since wade task update only edits the body), not just the PR, or done reverts it.
 
 ---
+
+## 1f23c00660aa | 2026-09-04 | implementation | tags: delegation, architecture, sandbox | Issue #480
+
+`delegation_service.delegate()` is the single dispatcher for deps, standalone plan/code review, and batch review — `deps_service` and `review_delegation_service` call it directly and `batch_review_service` reaches it through the latter — so a cross-cutting launch concern belongs there ONCE, not per service. Centralising costs per-operation context, so remediation text must ride on `DelegationRequest` fields rather than being generated inside the dispatcher. `implementation_service/batch.py` is NOT a launch path: it builds ["wade", "implement", <id>] and spawns child `wade` processes that reach the `core.py` check themselves, so a check there is a dead no-op implying coverage it does not add.
+
+---
+
+## 280ed6e410b6 | 2026-09-04 | implementation | tags: delegation, sandbox, gotcha, error-handling | Issue #480
+
+`DelegationResult.never_launched` means no process ever started (absent/unknown tool, `supports_headless` rejection, `CommandError` spawn failure, `OSError` on exec) — a non-zero exit AND a real timeout must both keep it False, because "relaunch the outer session" is wrong advice for a reviewer that actually ran. `utils.process.run` maps only `FileNotFoundError` to `CommandError`, so a `PermissionError` on a binary that resolves on PATH but cannot be executed escapes `_delegate_headless` entirely unless caught explicitly — one of the exact shapes an inherited sandbox produces. The interactive path needs an explicit `launched` flag because `adapter.launch` and the post-session output-file read share one exception handler.
+
+---
+
+## 65ee7eb64d81 | 2026-09-04 | implementation | tags: testing, sandbox, gotcha | Issue #480
+
+`tests/conftest.py` carries an autouse fixture clearing `runtime_env.SANDBOX_SIGNAL_ENV_VARS`, because `utils/runtime_env.py` reads the REAL environment — without it a suite run from inside a sandboxed Codex session sees a genuine SANDBOXED verdict and takes relaunch/diagnosis branches no test asked for. It clears only the sandbox-signal vars, never the identity markers (`CODEX_CLI`, `CLAUDE_CODE`, …) that existing tests patch directly. Any test asserting on the parent-sandbox diagnosis must also clear competing identity markers, since the probe returns the FIRST one it recognises.
+
+---
+
+## 397994e37408 | 2026-09-04 | implementation | tags: delegation, error-handling, gotcha | Issue #480
+
+`DelegationResult.never_launched` means no process ever started, and an explicit `launched` flag set after `adapter.launch()` returns is NOT enough to decide it: `launch` blocks until the child exits for most runtimes, so an adapter that checks the exit status raises `CalledProcessError` from a session that ran and failed. Classify the interactive launch boundary by exception SHAPE — an `OSError` at the spawn started nothing, every `subprocess.SubprocessError` variant carries a child that was created — and keep the post-launch section in its own handler. `utils.process.run` maps only `FileNotFoundError` to `CommandError`, so a `PermissionError` on a binary that resolves on PATH but cannot be executed escapes `_delegate_headless` unless caught explicitly.
+
+---
+
+## 12dd26da8910 | 2026-09-04 | implementation | tags: testing, gotcha, e2e | Issue #480
+
+A non-executable file earlier on PATH does NOT make a later real binary unreachable: CPython builds an exec candidate from every PATH entry and keeps going past EACCES, so an E2E test that drops a chmod 644 stand-in into the mocked bin dir still runs the users real tool. To force a denial-shaped spawn failure, narrow PATH in the child env to the mocked bin plus only the dirs actually needed (`wade`, `git`, `/usr/bin`, `/bin`). `shutil.which` skips non-executables, so it is the right assertion that no real binary remains reachable.
+
+---
+
+## 4668ee29b835 | 2026-09-04 | implementation | tags: delegation, sandbox, batch | Issue #480
+
+For issue #480, delegation_service.delegate() remains the one dispatcher for deps and standalone/batch reviews, but implement-batch crosses a different terminal-broker boundary. Diagnose a known parent sandbox once in implementation_service.batch before broker shells can lose its markers; child implementation checks remain a backstop, not the sole diagnosis.
+
+---
+
+## 54236b4243bc | 2026-09-04 | implementation | tags: testing, sandbox, gotcha | Issue #480
+
+For issue #480 sandbox tests, the autouse conftest fixture clears both SANDBOX_SIGNAL_ENV_VARS and real Codex identity markers in CODEX_IDENTITY_ENV_VARS. Tests that need another enclosing runtime still set or clear competing identity markers deliberately; do not claim the fixture never clears identity markers.
+
+---

{wade_cli-1.0.0 → wade_cli-1.1.1}/KNOWLEDGE.ratings.jsonl

@@ -158,3 +158,17 @@
 {"dir": "up", "event_id": "5cde95ece3844529a88448383c60e822", "id": "d7e3010043a2", "ts": "2026-09-03T02:07:17.166938+00:00"}
 {"dir": "up", "event_id": "18179aae748f444487502929584aa632", "id": "6eb12fb5eb3a", "ts": "2026-09-03T12:24:58.444706+00:00"}
 {"dir": "up", "event_id": "0c1be71273e34c50b609348a7c09622e", "id": "1c79175312c9", "ts": "2026-09-03T12:24:58.649116+00:00"}
+{"dir": "up", "event_id": "67eb4181748e4cd2974a60ed014efe12", "id": "851bb6ec", "ts": "2026-09-04T11:02:22.496706+00:00"}
+{"dir": "up", "event_id": "b15b9eba905749c78eded32f991397a1", "id": "d7e3010043a2", "ts": "2026-09-04T11:02:22.654506+00:00"}
+{"dir": "stale", "event_id": "69e1b360de924aa5b0a27874d8be935e", "id": "8a9bfc96", "ts": "2026-09-04T11:02:22.809044+00:00"}
+{"dir": "up", "event_id": "79dac0524f60401fb457dcb44c62ac5a", "id": "1f23c00660aa", "ts": "2026-09-04T14:17:48.792141+00:00"}
+{"dir": "up", "event_id": "962d19cb9fa3460eb7f351bbdf0abe76", "id": "65ee7eb64d81", "ts": "2026-09-04T14:17:48.947672+00:00"}
+{"id": "280ed6e410b6", "superseded_by": "397994e37408", "ts": "2026-09-04T14:18:00.060874+00:00"}
+{"dir": "up", "event_id": "5aaf8dca23da43409dae899f50e04111", "id": "1f23c00660aa", "ts": "2026-09-04T16:19:49.643133+00:00"}
+{"dir": "up", "event_id": "96bedf22dcd74c3cabdace8dd850f125", "id": "280ed6e410b6", "ts": "2026-09-04T16:19:49.795516+00:00"}
+{"dir": "stale", "event_id": "de4b4ee2ffa24276a4b35d93ccb16b11", "id": "1f23c00660aa", "ts": "2026-09-04T22:14:03.557181+00:00"}
+{"dir": "stale", "event_id": "71f6ebba04cc4c86bc4e2d02ed19ea9d", "id": "65ee7eb64d81", "ts": "2026-09-04T22:14:03.707575+00:00"}
+{"id": "1f23c00660aa", "superseded_by": "4668ee29b835", "ts": "2026-09-04T22:14:10.938819+00:00"}
+{"id": "65ee7eb64d81", "superseded_by": "54236b4243bc", "ts": "2026-09-04T22:14:17.907524+00:00"}
+{"dir": "up", "event_id": "bc0cace277f74e4490f28148eafb4070", "id": "4d419ec6629c", "ts": "2026-09-07T22:30:30.110983+00:00"}
+{"dir": "up", "event_id": "0901f7e84f80422488ee976fb7f54934", "id": "fb5582aa12e0", "ts": "2026-09-08T10:26:25.322775+00:00"}

{wade_cli-1.0.0 → wade_cli-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: wade-cli
-Version: 1.0.0
+Version: 1.1.1
 Summary: WADE — Workflow for AI-Driven Engineering
 Project-URL: Homepage, https://github.com/ivanviragine/wade
 Project-URL: Repository, https://github.com/ivanviragine/wade
@@ -276,7 +276,7 @@ These are invoked by the AI during a session — you normally don't run them by
 | `wade plan-session done <plan_dir>` | Finalize a planning session |
 | `wade deps-session check` | Verify the detached dependency-analysis runtime before writing output or staging a knowledge vote |
 
-Most workflow commands accept `--ai <tool>`, `--model <model>`, `--effort <level>`, `--permission-mode <tier>`, and `--yolo` to override configured defaults. `plan`, `implement`, and `review pr-comments` accept repeatable `--skill` and `--review-skill` methodology bindings plus `--refresh-skills` for an existing frozen session; `implement-batch` forwards the same binding request to every child session. Standalone plan/code/batch review and `task deps` accept repeatable `--skill`. `plan`, `implement`, `implement-batch`, `review pr-comments`, and the `wade <N>` shorthand also accept `--sandbox` / `--no-sandbox` (see [AI runtime sandbox profile](#ai-runtime-sandbox-profile)); batch and shorthand forward an explicit flag to the child session they launch. `implement` additionally supports `--detach` (new terminal tab), `--cd` (print worktree path only), and `--base <branch>` (see [Planning & base branches](#planning--base-branches)).
+Most workflow commands accept `--ai <tool>`, `--model <model>`, `--effort <level>`, `--permission-mode <tier>`, and `--yolo` to override configured defaults. `review pr-comments` additionally accepts `--effort none` to pin the tool default instead of a configured effort across a later wait/relaunch. `plan`, `implement`, and `review pr-comments` accept repeatable `--skill` and `--review-skill` methodology bindings plus `--refresh-skills` for an existing frozen session; `implement-batch` forwards the same binding request to every child session. Standalone plan/code/batch review and `task deps` accept repeatable `--skill`. `plan`, `implement`, `implement-batch`, standalone reviews (`review plan`, `review implementation`, `review batch`), `review pr-comments`, `task deps`, and the `wade <N>` shorthand also accept `--sandbox` / `--no-sandbox` (see [AI runtime sandbox profile](#ai-runtime-sandbox-profile)); batch and shorthand forward an explicit flag to the child session they launch. `implement` additionally supports `--detach` (new terminal tab), `--cd` (print worktree path only), and `--base <branch>` (see [Planning & base branches](#planning--base-branches)).
 
 ## Planning & base branches
 
@@ -335,7 +335,11 @@ printing it does not certify that a review happened. After performing that
 self-review and addressing its findings, run
 `wade review implementation --ack-self-review` to write the current commit and
 frozen-review-binding receipt. Successful headless or interactive reviews write
-the same receipt directly.
+the same receipt directly. In an implementation session, once the active frozen
+review binding has consumed `done.max_review_passes` (default 2), `wade review
+implementation` exits successfully without launching another reviewer and directs
+you to `wade implementation-session done`. The dispatch cap does not block a
+valid `--ack-self-review`, which still writes its active-binding receipt.
 
 To fetch the unresolved comments themselves during a review session, the agent
 runs `wade review-pr-comments-session fetch <N>`; it resolves individual threads with
@@ -545,7 +549,7 @@ Decision and integrity gates deliberately require an explicit valid outcome:
 | PR-SUMMARY | `PR-SUMMARY.md` is missing, empty, or still a template placeholder (both change-producing session types) | `done.require_pr_summary: false` |
 | Documentation decision | neither an `--updated` nor reasoned `--not-needed` receipt exists for current HEAD | *no disable toggle; `docs --not-needed "<reason>"` records the explicit no-change outcome* |
 | Sync | the branch is behind main — auto-syncs first, refuses only on conflict (both change-producing session types) | `done.require_sync: false` |
-| Review ran | `wade review implementation` has no successful external-review or explicitly acknowledged self-review record for the current commit **and frozen REVIEW binding**, or the frozen workflow/skill bundle no longer matches its manifest. Bundle validation happens before receipts or pass counts are trusted. Prompt emission alone never satisfies this gate. **Implementation sessions bound this loop:** after `done.max_review_passes` (default 2) review→fix→re-review cycles for the active reviewer, `done` completes anyway with a notice instead of looping forever | `--skip-review`, `done.require_review: false` (auto-off when `ai.review_implementation.enabled: false`) |
+| Review ran | `wade review implementation` has no successful external-review or explicitly acknowledged self-review record for the current commit **and frozen REVIEW binding**, or the frozen workflow/skill bundle no longer matches its manifest. Bundle validation happens before receipts or pass counts are trusted. Prompt emission alone never satisfies this gate. **Implementation sessions bound this loop:** at `done.max_review_passes` (default 2), `wade review implementation` stops before launching an excess reviewer, while a valid `--ack-self-review` may still record its receipt; `done` remains authoritative and completes an unreviewed later commit with a cap-reached status instead of looping forever | `--skip-review`, `done.require_review: false` (auto-off when `ai.review_implementation.enabled: false`) |
 | Resolved threads | unresolved PR review threads remain (review-comments only) | `done.require_resolved_threads: false` |
 | Conventional title | the task title is not a conventional-commit title (the PR title is derived from it, so it would fail `PR Title Lint`) — blocks; when valid but the open PR's title differs, syncs the PR title to match (both session types) — if that sync fails while the PR's current title is itself non-conventional (lint would fail), `done` fails so it can be retried | `done.require_conventional_title: false` |
 | Knowledge valid | the knowledge file is structurally corrupt — duplicate entry IDs or unresolved conflict markers (e.g. from a `merge=union` merge) | *none — gated by `knowledge.enabled`; no `done.*` hatch* |
@@ -707,7 +711,7 @@ fetch`/`push`, `gh`, package installs — cannot work without it, and the profil
 is fixed at launch.
 
 Set it globally or per command, and override it on any launch command
-(`implement`, `implement-batch`, `plan`, `review pr-comments`, `smart-start`,
+(`implement`, `implement-batch`, `plan`, `review pr-comments`, `task deps`, `smart-start`,
 and the `i`/`r`/`p` aliases) with `--sandbox` / `--no-sandbox`:
 
 ```yaml
@@ -773,17 +777,87 @@ the Stop hook, and the pre-push backstop are identical in both profiles.
 #### Plan → implement handoff
 
 The sandbox is a launch-time OS property: a process started confined cannot drop
-its sandbox later. So when an accepted plan handoff runs inside a **sandboxed**
-Codex planner and the implementation profile resolves to **unrestricted**, WADE
-starts a fresh detached Codex context rather than reusing the planner process. If
-it cannot open that context, the handoff fails rather than reporting an
-implementation session ready — open a new host terminal and run the displayed
-`wade implement <issue> --no-sandbox` command. When both sessions resolve to the
-same profile there is no mismatch and the ordinary nested-launch guard applies.
-
-The comparison uses the profile the planner **actually launched under**, so a
-`wade plan --sandbox` / `--no-sandbox` override is honored here rather than
-losing out to `ai.plan.sandbox`.
+its sandbox later. An accepted plan handoff runs after the planner child exits,
+so WADE assesses the **actual parent runtime enclosing the handoff**, not the
+former planner's requested profile. When that runtime is detected as sandboxed
+and implementation resolves to **unrestricted**, WADE fails the handoff rather
+than claiming a terminal child escaped the parent boundary. It names the runtime
+it could not escape, and you open a new host terminal and run the displayed
+`wade implement <issue> --no-sandbox` command. Without a published sandbox
+signal, the ordinary nested-launch guard applies rather than guessing.
+
+#### An inner `wade` process cannot escape a parent sandbox
+
+Every `wade` command you run from inside an AI CLI session is a **child** of that
+session. If the session was launched under an OS sandbox, every descendant
+inherits the boundary — no profile WADE resolves, and no flag it passes to a
+delegated runtime, can widen it. WADE will never claim otherwise, and there is no
+setting that changes it. **The fix is always to relaunch the outer session with
+the profile you want**, from a host terminal.
+
+What WADE does instead is say so. When the resolved profile is unrestricted and
+the enclosing runtime is *known* to be sandboxed, it names that runtime when it
+can (or says **the enclosing AI runtime** when an identity marker is absent) and
+prints the exact command to re-run — on implementation, plan,
+PR-comment review, and every delegated operation (dependency analysis, plan/code
+review, batch review), plus batch implementation before it dispatches terminal
+brokers. That command preserves the resolved tool, model, effort,
+and permission mode; only the sandbox profile changes to `--no-sandbox`.
+Implementation and PR-comment retries reuse their frozen method bindings rather
+than repeating `--skill` / `--review-skill` flags, while fresh delegated
+operations carry their requested bindings. It warns and proceeds rather than
+blocking: a delegated tool whose credentials happen to be reachable from inside
+the sandbox may still
+succeed, so refusing to try would break sessions that work today.
+
+Detection is deliberately **best-effort and conservative**. WADE reads only
+sandbox signals a runtime actually publishes and never infers confinement from
+tool identity — a tool that *can* be sandboxed is not a tool that *is* sandboxed.
+Today Codex publishes `CODEX_SANDBOX` for macOS Seatbelt, but its Linux Landlock
+sandbox with network enabled publishes neither that marker nor a usable
+`CODEX_SANDBOX_NETWORK_DISABLED` marker. WADE must report that Linux environment
+as *unknown*, not unrestricted; if the distinction matters, relaunch from a host
+terminal rather than expecting a diagnostic. When there is no signal WADE stays
+silent rather than asserting a cause it cannot support. A confident wrong
+diagnosis is worse than the opaque error it would replace. Managed Codex sessions
+are still recognised when they expose session/thread markers instead of the
+legacy `CODEX_CLI` marker; their displayed identity remains **Codex CLI**.
+
+An explicit unrestricted signal (for example, Codex's
+`CODEX_SANDBOX=danger-full-access`) is different from an absent signal: WADE
+does **not** recommend relaunching the outer session for a permission- or
+network-shaped launch failure in that case. The parent has already confirmed it
+is unrestricted, so check executable permissions and network configuration
+instead.
+
+**Troubleshooting order** when a delegated tool fails to launch:
+
+1. **Read what WADE printed.** An explicit sandbox-policy denial plus a named
+   runtime and command means relaunch the outer session with that command. A
+   generic permission or network denial also needs local checks below.
+2. **Check whether the reviewer actually started.** A reviewer that ran and
+   exited non-zero is a different problem; "relaunch the outer session" is wrong
+   advice for it. WADE distinguishes the two. A generic launch denial can also
+   be bad executable permissions or network configuration; a refusal WADE made
+   itself (an unknown tool, a tool with no headless mode) never reached the
+   sandbox and gets generic remediation instead.
+3. **Check executable permissions, network, and the tool's own login/PATH** in the runtime where it must run
+   (`gh auth status`, the delegate's own auth command). A separately
+   authenticated delegate needs its *own* credentials, not WADE's.
+4. **Re-run the phase readiness check** (`wade implementation-session check`,
+   `wade review-pr-comments-session check`, …) for a narrow `reason=…` and its
+   least-privilege remediation.
+5. **Only then** widen the profile — and widen the *outer* session, not the
+   child.
+
+> **Narrow, optional exception: Codex project prefix rules.** Codex can be
+> configured to run specific command prefixes outside its sandbox, which elevates
+> a single command without relaunching the session. It is a Codex-side setting
+> WADE neither writes nor reads, it applies per command rather than to the
+> session, and it does not change anything above: the session is still sandboxed
+> and every other child still inherits that. Treat it as an escape hatch for one
+> stubborn command, **not** as WADE's path for running unrestricted — that path
+> is relaunching the outer session.
 
 #### Migrating from `ai.network_access`
 
@@ -857,11 +931,27 @@ credentials, PATH, or sandbox execution access, it does not consume a
 timeout still counts as a bounded review attempt, so the review/fix loop cannot
 run forever.
 
+A reviewer that **never started** — including a sandbox-capability refusal before
+the launch — is recorded as an *unattempted* review so the state is auditable,
+and that record is deliberately inert: it satisfies no review
+requirement, spends no review pass, cannot overwrite a real receipt already
+written for the same commit, and leaves `wade implementation-session done` and
+`wade review-pr-comments-session done` closed. An infrastructure failure must
+never be able to certify a commit. A reviewer that started and exited non-zero
+stays distinguishable from one that never ran, because the two need opposite
+remediation.
+
 For Codex, WADE launches unsandboxed by default so delegated tools keep their
 own host credentials; set `ai.sandbox: true` (or pass `--sandbox`) to keep
 `--sandbox workspace-write`, where WADE/crossby add only the linked worktree's
 private/common Git metadata directories. Every session has network access in
 both profiles for its GitHub lifecycle.
+Standalone `wade review plan`, `wade review implementation`, and `wade review
+batch` runs also accept `--sandbox` / `--no-sandbox`; an inherited-sandbox
+diagnosis gives the host-terminal relaunch command with `--no-sandbox` so it
+overrides an `ai.sandbox: true` configuration. The command also preserves the
+selected review mode, tool, model, effort, permission mode, staged scope, and
+review-skill overrides so the retry reviews the same operation.
 For Claude Code and Cursor, allowlist the worktree/Git metadata paths and only
 the GitHub domains needed by the session rather than choosing unrestricted shell
 access. Copilot and VS Code need network plus usable `gh` credentials in their

{wade_cli-1.0.0 → wade_cli-1.1.1}/README.md

@@ -240,7 +240,7 @@ These are invoked by the AI during a session — you normally don't run them by
 | `wade plan-session done <plan_dir>` | Finalize a planning session |
 | `wade deps-session check` | Verify the detached dependency-analysis runtime before writing output or staging a knowledge vote |
 
-Most workflow commands accept `--ai <tool>`, `--model <model>`, `--effort <level>`, `--permission-mode <tier>`, and `--yolo` to override configured defaults. `plan`, `implement`, and `review pr-comments` accept repeatable `--skill` and `--review-skill` methodology bindings plus `--refresh-skills` for an existing frozen session; `implement-batch` forwards the same binding request to every child session. Standalone plan/code/batch review and `task deps` accept repeatable `--skill`. `plan`, `implement`, `implement-batch`, `review pr-comments`, and the `wade <N>` shorthand also accept `--sandbox` / `--no-sandbox` (see [AI runtime sandbox profile](#ai-runtime-sandbox-profile)); batch and shorthand forward an explicit flag to the child session they launch. `implement` additionally supports `--detach` (new terminal tab), `--cd` (print worktree path only), and `--base <branch>` (see [Planning & base branches](#planning--base-branches)).
+Most workflow commands accept `--ai <tool>`, `--model <model>`, `--effort <level>`, `--permission-mode <tier>`, and `--yolo` to override configured defaults. `review pr-comments` additionally accepts `--effort none` to pin the tool default instead of a configured effort across a later wait/relaunch. `plan`, `implement`, and `review pr-comments` accept repeatable `--skill` and `--review-skill` methodology bindings plus `--refresh-skills` for an existing frozen session; `implement-batch` forwards the same binding request to every child session. Standalone plan/code/batch review and `task deps` accept repeatable `--skill`. `plan`, `implement`, `implement-batch`, standalone reviews (`review plan`, `review implementation`, `review batch`), `review pr-comments`, `task deps`, and the `wade <N>` shorthand also accept `--sandbox` / `--no-sandbox` (see [AI runtime sandbox profile](#ai-runtime-sandbox-profile)); batch and shorthand forward an explicit flag to the child session they launch. `implement` additionally supports `--detach` (new terminal tab), `--cd` (print worktree path only), and `--base <branch>` (see [Planning & base branches](#planning--base-branches)).
 
 ## Planning & base branches
 
@@ -299,7 +299,11 @@ printing it does not certify that a review happened. After performing that
 self-review and addressing its findings, run
 `wade review implementation --ack-self-review` to write the current commit and
 frozen-review-binding receipt. Successful headless or interactive reviews write
-the same receipt directly.
+the same receipt directly. In an implementation session, once the active frozen
+review binding has consumed `done.max_review_passes` (default 2), `wade review
+implementation` exits successfully without launching another reviewer and directs
+you to `wade implementation-session done`. The dispatch cap does not block a
+valid `--ack-self-review`, which still writes its active-binding receipt.
 
 To fetch the unresolved comments themselves during a review session, the agent
 runs `wade review-pr-comments-session fetch <N>`; it resolves individual threads with
@@ -509,7 +513,7 @@ Decision and integrity gates deliberately require an explicit valid outcome:
 | PR-SUMMARY | `PR-SUMMARY.md` is missing, empty, or still a template placeholder (both change-producing session types) | `done.require_pr_summary: false` |
 | Documentation decision | neither an `--updated` nor reasoned `--not-needed` receipt exists for current HEAD | *no disable toggle; `docs --not-needed "<reason>"` records the explicit no-change outcome* |
 | Sync | the branch is behind main — auto-syncs first, refuses only on conflict (both change-producing session types) | `done.require_sync: false` |
-| Review ran | `wade review implementation` has no successful external-review or explicitly acknowledged self-review record for the current commit **and frozen REVIEW binding**, or the frozen workflow/skill bundle no longer matches its manifest. Bundle validation happens before receipts or pass counts are trusted. Prompt emission alone never satisfies this gate. **Implementation sessions bound this loop:** after `done.max_review_passes` (default 2) review→fix→re-review cycles for the active reviewer, `done` completes anyway with a notice instead of looping forever | `--skip-review`, `done.require_review: false` (auto-off when `ai.review_implementation.enabled: false`) |
+| Review ran | `wade review implementation` has no successful external-review or explicitly acknowledged self-review record for the current commit **and frozen REVIEW binding**, or the frozen workflow/skill bundle no longer matches its manifest. Bundle validation happens before receipts or pass counts are trusted. Prompt emission alone never satisfies this gate. **Implementation sessions bound this loop:** at `done.max_review_passes` (default 2), `wade review implementation` stops before launching an excess reviewer, while a valid `--ack-self-review` may still record its receipt; `done` remains authoritative and completes an unreviewed later commit with a cap-reached status instead of looping forever | `--skip-review`, `done.require_review: false` (auto-off when `ai.review_implementation.enabled: false`) |
 | Resolved threads | unresolved PR review threads remain (review-comments only) | `done.require_resolved_threads: false` |
 | Conventional title | the task title is not a conventional-commit title (the PR title is derived from it, so it would fail `PR Title Lint`) — blocks; when valid but the open PR's title differs, syncs the PR title to match (both session types) — if that sync fails while the PR's current title is itself non-conventional (lint would fail), `done` fails so it can be retried | `done.require_conventional_title: false` |
 | Knowledge valid | the knowledge file is structurally corrupt — duplicate entry IDs or unresolved conflict markers (e.g. from a `merge=union` merge) | *none — gated by `knowledge.enabled`; no `done.*` hatch* |
@@ -671,7 +675,7 @@ fetch`/`push`, `gh`, package installs — cannot work without it, and the profil
 is fixed at launch.
 
 Set it globally or per command, and override it on any launch command
-(`implement`, `implement-batch`, `plan`, `review pr-comments`, `smart-start`,
+(`implement`, `implement-batch`, `plan`, `review pr-comments`, `task deps`, `smart-start`,
 and the `i`/`r`/`p` aliases) with `--sandbox` / `--no-sandbox`:
 
 ```yaml
@@ -737,17 +741,87 @@ the Stop hook, and the pre-push backstop are identical in both profiles.
 #### Plan → implement handoff
 
 The sandbox is a launch-time OS property: a process started confined cannot drop
-its sandbox later. So when an accepted plan handoff runs inside a **sandboxed**
-Codex planner and the implementation profile resolves to **unrestricted**, WADE
-starts a fresh detached Codex context rather than reusing the planner process. If
-it cannot open that context, the handoff fails rather than reporting an
-implementation session ready — open a new host terminal and run the displayed
-`wade implement <issue> --no-sandbox` command. When both sessions resolve to the
-same profile there is no mismatch and the ordinary nested-launch guard applies.
-
-The comparison uses the profile the planner **actually launched under**, so a
-`wade plan --sandbox` / `--no-sandbox` override is honored here rather than
-losing out to `ai.plan.sandbox`.
+its sandbox later. An accepted plan handoff runs after the planner child exits,
+so WADE assesses the **actual parent runtime enclosing the handoff**, not the
+former planner's requested profile. When that runtime is detected as sandboxed
+and implementation resolves to **unrestricted**, WADE fails the handoff rather
+than claiming a terminal child escaped the parent boundary. It names the runtime
+it could not escape, and you open a new host terminal and run the displayed
+`wade implement <issue> --no-sandbox` command. Without a published sandbox
+signal, the ordinary nested-launch guard applies rather than guessing.
+
+#### An inner `wade` process cannot escape a parent sandbox
+
+Every `wade` command you run from inside an AI CLI session is a **child** of that
+session. If the session was launched under an OS sandbox, every descendant
+inherits the boundary — no profile WADE resolves, and no flag it passes to a
+delegated runtime, can widen it. WADE will never claim otherwise, and there is no
+setting that changes it. **The fix is always to relaunch the outer session with
+the profile you want**, from a host terminal.
+
+What WADE does instead is say so. When the resolved profile is unrestricted and
+the enclosing runtime is *known* to be sandboxed, it names that runtime when it
+can (or says **the enclosing AI runtime** when an identity marker is absent) and
+prints the exact command to re-run — on implementation, plan,
+PR-comment review, and every delegated operation (dependency analysis, plan/code
+review, batch review), plus batch implementation before it dispatches terminal
+brokers. That command preserves the resolved tool, model, effort,
+and permission mode; only the sandbox profile changes to `--no-sandbox`.
+Implementation and PR-comment retries reuse their frozen method bindings rather
+than repeating `--skill` / `--review-skill` flags, while fresh delegated
+operations carry their requested bindings. It warns and proceeds rather than
+blocking: a delegated tool whose credentials happen to be reachable from inside
+the sandbox may still
+succeed, so refusing to try would break sessions that work today.
+
+Detection is deliberately **best-effort and conservative**. WADE reads only
+sandbox signals a runtime actually publishes and never infers confinement from
+tool identity — a tool that *can* be sandboxed is not a tool that *is* sandboxed.
+Today Codex publishes `CODEX_SANDBOX` for macOS Seatbelt, but its Linux Landlock
+sandbox with network enabled publishes neither that marker nor a usable
+`CODEX_SANDBOX_NETWORK_DISABLED` marker. WADE must report that Linux environment
+as *unknown*, not unrestricted; if the distinction matters, relaunch from a host
+terminal rather than expecting a diagnostic. When there is no signal WADE stays
+silent rather than asserting a cause it cannot support. A confident wrong
+diagnosis is worse than the opaque error it would replace. Managed Codex sessions
+are still recognised when they expose session/thread markers instead of the
+legacy `CODEX_CLI` marker; their displayed identity remains **Codex CLI**.
+
+An explicit unrestricted signal (for example, Codex's
+`CODEX_SANDBOX=danger-full-access`) is different from an absent signal: WADE
+does **not** recommend relaunching the outer session for a permission- or
+network-shaped launch failure in that case. The parent has already confirmed it
+is unrestricted, so check executable permissions and network configuration
+instead.
+
+**Troubleshooting order** when a delegated tool fails to launch:
+
+1. **Read what WADE printed.** An explicit sandbox-policy denial plus a named
+   runtime and command means relaunch the outer session with that command. A
+   generic permission or network denial also needs local checks below.
+2. **Check whether the reviewer actually started.** A reviewer that ran and
+   exited non-zero is a different problem; "relaunch the outer session" is wrong
+   advice for it. WADE distinguishes the two. A generic launch denial can also
+   be bad executable permissions or network configuration; a refusal WADE made
+   itself (an unknown tool, a tool with no headless mode) never reached the
+   sandbox and gets generic remediation instead.
+3. **Check executable permissions, network, and the tool's own login/PATH** in the runtime where it must run
+   (`gh auth status`, the delegate's own auth command). A separately
+   authenticated delegate needs its *own* credentials, not WADE's.
+4. **Re-run the phase readiness check** (`wade implementation-session check`,
+   `wade review-pr-comments-session check`, …) for a narrow `reason=…` and its
+   least-privilege remediation.
+5. **Only then** widen the profile — and widen the *outer* session, not the
+   child.
+
+> **Narrow, optional exception: Codex project prefix rules.** Codex can be
+> configured to run specific command prefixes outside its sandbox, which elevates
+> a single command without relaunching the session. It is a Codex-side setting
+> WADE neither writes nor reads, it applies per command rather than to the
+> session, and it does not change anything above: the session is still sandboxed
+> and every other child still inherits that. Treat it as an escape hatch for one
+> stubborn command, **not** as WADE's path for running unrestricted — that path
+> is relaunching the outer session.
 
 #### Migrating from `ai.network_access`
 
@@ -821,11 +895,27 @@ credentials, PATH, or sandbox execution access, it does not consume a
 timeout still counts as a bounded review attempt, so the review/fix loop cannot
 run forever.
 
+A reviewer that **never started** — including a sandbox-capability refusal before
+the launch — is recorded as an *unattempted* review so the state is auditable,
+and that record is deliberately inert: it satisfies no review
+requirement, spends no review pass, cannot overwrite a real receipt already
+written for the same commit, and leaves `wade implementation-session done` and
+`wade review-pr-comments-session done` closed. An infrastructure failure must
+never be able to certify a commit. A reviewer that started and exited non-zero
+stays distinguishable from one that never ran, because the two need opposite
+remediation.
+
 For Codex, WADE launches unsandboxed by default so delegated tools keep their
 own host credentials; set `ai.sandbox: true` (or pass `--sandbox`) to keep
 `--sandbox workspace-write`, where WADE/crossby add only the linked worktree's
 private/common Git metadata directories. Every session has network access in
 both profiles for its GitHub lifecycle.
+Standalone `wade review plan`, `wade review implementation`, and `wade review
+batch` runs also accept `--sandbox` / `--no-sandbox`; an inherited-sandbox
+diagnosis gives the host-terminal relaunch command with `--no-sandbox` so it
+overrides an `ai.sandbox: true` configuration. The command also preserves the
+selected review mode, tool, model, effort, permission mode, staged scope, and
+review-skill overrides so the retry reviews the same operation.
 For Claude Code and Cursor, allowlist the worktree/Git metadata paths and only
 the GitHub domains needed by the session rather than choosing unrestricted shell
 access. Copilot and VS Code need network plus usable `gh` credentials in their