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

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

@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Conventional Commits](https://conventionalcommits.org/).
 
+## [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.0}/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.0}/KNOWLEDGE.ratings.jsonl

@@ -158,3 +158,15 @@
 {"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"}

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: wade-cli
-Version: 1.0.0
+Version: 1.1.0
 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
 
@@ -707,7 +707,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 +773,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 +927,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.0}/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
 
@@ -671,7 +671,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 +737,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 +891,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.0}/docs/dev/architecture.md

@@ -551,20 +551,174 @@ explicit-only rule — an unset value emits no flag, so a child re-resolves from
 its own config rather than freezing the parent's resolved value. `None` (unset)
 matches how a non-explicit `permission_mode` is threaded.
 
-`requires_fresh_codex_handoff` (`implementation_service/core.py`) is the restated
-form of the retired network-pin predicate. Its old premise — "the planner always
-ran network-off" — died with the per-command asymmetry, but the mismatch it
-guarded is real and now expressible directly: the sandbox is a launch-time OS
-property, so a **sandboxed** Codex planner handing off to an **unrestricted**
-Codex implementation needs a fresh detached process rather than the planner's.
-Note the **polarity flip** — the old flag fired on the permissive value being
-`True` (network on), this one fires on the permissive value being `False`
-(sandbox off), and the detached branch states the forced value (`False`)
-explicitly. A token-level rename would have silently inverted the intent. If the
-detached launch cannot be created the handoff fails closed and prints
-`wade implement <issue> --no-sandbox`; it must not fall back to an inline or
-nested agent. Matching profiles produce no handoff, and all other nested-agent
-starts retain the ordinary launch guard.
+`requires_fresh_runtime` (`implementation_service/core.py`) is the restated form
+of the retired network-pin predicate. It fires only when an accepted plan handoff
+runs inside a **detected, known-sandboxed parent runtime** while implementation
+resolves **unrestricted**. The planner child has already exited when the accepted
+handoff runs, so its requested `--sandbox`/`--no-sandbox` profile is not evidence
+about the process now enclosing implementation. Note the **polarity flip** — the
+old flag fired on the permissive value being `True` (network on), this one fires
+on the permissive value being `False` (sandbox off). A token-level rename would
+have silently inverted the intent. A new terminal launched by the confined
+process is still only its child — neither terminal-broker acceptance nor a live
+readiness probe proves it escaped the OS sandbox — so the handoff fails closed,
+names the actual parent runtime, and prints `wade implement <issue>
+--no-sandbox`; it must not launch an inline, nested, or detached child. An
+unknown parent keeps the ordinary nested-agent guard rather than guessing.
+
+The two tool-identity conjuncts it used to carry — parent is Codex, target is
+Codex — were **proxies** for "this process is confined", and they under-fired on
+exactly the cases that matter (#480): a sandboxed Codex parent handing off to
+Claude confines it just as surely, and being separately authenticated is where
+the lost host login shows first. The predicate is now the shared
+`requires_unsandboxed_relaunch()` described next.
+
+### Parent-runtime detection & conservative classification (#480)
+
+Every `wade` command started from inside an AI CLI session is a **child** of that
+session. If the parent launched under an OS sandbox, every descendant inherits
+the boundary: no profile wade resolves, and no flag it passes to a child runtime,
+widens it. **An inner wade process can never escape an existing parent sandbox** —
+the only fix is relaunching the *outer* session. Code must never imply otherwise.
+
+`utils/runtime_env.py` is the leaf module holding that knowledge, so services,
+review, and delegation paths share one probe. It answers two deliberately
+independent questions:
+
+| Question | API | Note |
+|---|---|---|
+| Which session are we inside? | `detect_ai_cli_env()` | The historical identity probe moved out of `core.py` (re-exported there as `_detect_ai_cli_env`, which `__all__` and much of the suite still patch). Drives the nested-launch guard. |
+| Is that session confined? | `assess_parent_sandbox()` → `SandboxAssessment` | Tri-state: `SANDBOXED` / `UNRESTRICTED` / `UNKNOWN`. |
+
+Keeping them independent matters in both directions: identity alone says nothing
+about confinement (Codex runs either way under the canonical `CODEX_CLI`
+identity, including managed `CODEX_SESSION_ID` / `CODEX_THREAD_ID` aliases), and
+a sandbox signal is actionable even when the tool cannot be named.
+
+**`UNKNOWN` is a first-class answer, never a fallback to a guess.** The
+assessment is read only from published signals: a present `CODEX_SANDBOX` policy
+name is high-confidence (`danger-full-access` reads `UNRESTRICTED`; another
+non-empty value reads `SANDBOXED`) and `CODEX_SANDBOX_NETWORK_DISABLED` is
+secondary. Codex currently publishes `CODEX_SANDBOX` for macOS Seatbelt, but its
+Linux Landlock sandbox with network enabled publishes neither usable marker; that
+environment deliberately reads `UNKNOWN`, not `UNRESTRICTED`. Every other
+runtime publishes nothing, so `UNKNOWN` is correct and final for them — crossby's
+static `sandboxes_writes` capability describes the *tool*, not this process's
+boundary, and inferring from tool identity is exactly the confident wrong cause
+the module exists to avoid. A requested profile of a finished child process is
+not a substitute for an OS signal on the runtime that currently encloses wade.
+The tri-state also controls launch-failure wording: an absent signal keeps a
+denial-shaped failure conditional, while an explicit unrestricted signal (such
+as `CODEX_SANDBOX=danger-full-access`) rules out inherited confinement and sends
+the user to executable-permission or network configuration instead of suggesting
+an outer-session relaunch.
+
+**One predicate, four call sites.** `requires_unsandboxed_relaunch()` is true
+only for *resolved profile unrestricted* **and** *parent known sandboxed* — a
+published signal remains enough to warn even if the separate identity probe has
+no match. Identity is required only for the nested-launch guard; an identityless
+published sandbox signal also makes the plan-handoff path fail closed.
+`ai_resolution.announce_inherited_sandbox()` is the single user-facing emitter, so
+the paths cannot drift into four explanations of one boundary. It is **advisory,
+never a block** (wade cannot prove the delegated tool will fail) and says nothing
+at all on `UNKNOWN`. Host-terminal recovery commands are built as quoted argv,
+then displayed literally, preserving each operation's supported resolved tool,
+model, effort, and permission mode (plus review mode and staged scope where
+applicable); only the sandbox profile changes to `--no-sandbox`.
+Session-based implementation and PR-comment retries omit method overrides and
+reuse the existing frozen bundle; fresh delegated operations preserve their
+bindings. In a PR-comment session, the confirmation UI's "none — use tool
+default" effort choice is distinct from an unset value: retry and host-terminal
+recovery argv carry `--effort none` so a configured effort cannot return on the
+next launch.
+
+| Launch path | Site | Relaunch command it supplies |
+|---|---|---|
+| implementation | `implementation_service/core.py` | `wade implement <id> --no-sandbox` |
+| batch implementation | `implementation_service/batch.py` | `wade implement-batch <ids> --no-sandbox` — assessed once before terminal-broker dispatch, because broker shells may not retain the parent's markers |
+| PR-comment review | `review_service.py` | `wade review pr-comments <id> --no-sandbox` |
+| plan | `plan_service.py` | `wade plan --issue <id> --no-sandbox` (or `wade plan --no-sandbox`) — built here because it calls `build_launch_command` + `run_with_transcript` directly, bypassing `delegate()`, and has no nested-AI guard |
+| deps, standalone plan/code review, batch review | `delegation_service.delegate()` | per-operation, from `DelegationRequest.operation` / `.relaunch_command` |
+
+Deps (`deps_service.py`), standalone review (`review_delegation_service.py`) and
+batch review (via `review_delegation_service`) all funnel through the one
+`delegate()` dispatcher, so this cross-cutting concern lives there **once**.
+Centralising costs per-operation context, which is why the remediation fields
+ride on `DelegationRequest` — generic advice would defeat the purpose. The
+dispatcher emits that advisory only after tool/mode validation and immediately
+before a runtime launch; a missing tool or headless-capability refusal cannot be
+fixed by relaunching the enclosing session. The command is built by
+`review_delegation_service._relaunch_command()`, which
+forces `--no-sandbox` (so the host-terminal retry overrides any sandboxed config)
+and appends the operation's own **required positional operand** (the plan path
+for `wade review plan`, the tracking issue for `wade review batch`). It withholds
+the hint entirely when it has no required operand: those base commands are
+rejected by Typer, and a line the user cannot paste is worse than no line — the
+same rule already applied to an unmapped command.
+Batch implementation diagnoses once in `implementation_service/batch.py` before
+it dispatches terminal brokers. Those brokers can start child shells without the
+enclosing process's diagnostic markers, so deferring solely to child `wade
+implement` processes can lose a known boundary and produce no remediation.
+
+**`DelegationResult.never_launched`** closes the gap that used to force hedged
+remediation: it is `True` only when no process ever started — an absent/unknown
+tool, a `supports_headless` rejection, a `CommandError` spawn failure, or an
+`OSError` on exec (`utils.process.run` maps only `FileNotFoundError` to
+`CommandError`, so a `PermissionError` on a resolvable-but-unexecutable binary
+used to escape `_delegate_headless` and abort the command with a traceback). A
+**non-zero exit** keeps it `False`: that process ran, and a timeout still sets
+`timed_out` and still consumes a pass. The interactive path splits the launch
+boundary into its own handler and classifies by **exception shape**, because
+`adapter.launch` blocks until the child exits for most runtimes: an `OSError` at
+the spawn started nothing, while every `subprocess.SubprocessError` variant
+(`CalledProcessError`, `TimeoutExpired`) carries a child that was created and so
+counts as launched even though the call never returned. Everything after the
+adapter returns — the confirm prompt, the output-file read — is post-launch by
+position, whatever it raises. The headless path matters most — this repo configures
+`mode: headless` for `deps`, `review_plan` and `review_implementation`, and the
+receipt gate excludes `PROMPT` outright.
+
+`launch_attempted` is a separate structured boundary: it becomes true only after
+dispatch has passed validation and is about to call the process launcher. A
+preflight error can be `never_launched` without being a spawn attempt (for
+example, `Unknown AI tool: seatbelt`). Specific inherited-sandbox remediation
+therefore requires both that boundary and an actual denial-shaped spawn failure;
+user-controlled error text alone cannot choose the diagnosis.
+
+Failure text is matched against sandbox-denial *shapes*
+(`looks_like_sandbox_denial`) — permission/exec denials, read-only filesystems,
+network denials. Those generic OS errors stay **hedged** even when the parent is
+known sandboxed: non-executable binaries and local network configuration can
+produce the same text. Only explicit policy markers (`sandbox policy`, `seatbelt`,
+or `landlock`) support a confident sandbox cause. "Command not found" is
+deliberately **excluded**: from inside a sandbox the host filesystem is exactly
+what is not observable, so "a binary that exists on the host but is missing here"
+is unverifiable at the point of failure and equally the signature of a genuinely
+uninstalled tool.
+
+**Review-gate outcome semantics.** `ReviewOutcome.UNATTEMPTED`
+(`models/session_manifest.py`) has `satisfies_review` **and** `consumes_pass`
+both `False`, and sits at the **bottom** of `_OUTCOME_PRECEDENCE`
+(`review_record_service.py`) — a reviewer that never started carries strictly
+less information than any outcome from one that did, so recording it can never
+downgrade or overwrite a real receipt for the same commit+binding. Budget
+protection (#462) and receipt *classification* remain separate problems: the gate
+at `review_delegation_service.py` already withheld budget, and `never_launched`
+is what now lets the remediation be trusted instead of hedged.
+`_report_failed_review()` grades it by what wade actually knows — (1) known
+sandboxed parent **and** an explicit policy denial → state the cause and exact
+relaunch command; (2) a generic denial-shaped failure → explain it might also be
+executable permissions or network configuration alongside `_HEDGED_REVIEW_FAILURE`;
+(3) anything else → that hedged wording alone, kept verbatim. `done` gates stay
+closed in every case.
+
+The denial shape is required in (1), not implied by the sandbox: a known boundary
+says the reviewer *could* have been denied, never that it *was*. Without it every
+`never_launched` result took that branch — including a configuration refusal that
+never touched the OS (`Unknown AI tool`, `No AI tool specified`) and a genuinely
+uninstalled binary — blaming inaccessible host credentials and returning before
+the more useful generic remediation. `UNATTEMPTED` is still recorded from
+`never_launched` alone; only the *explanation* is graded.
 
 **Retirement path for `ai.network_access`.** The loader deliberately never reads
 the key (an un-migrated `.wade.yml` keeps loading), `strip_retired_network_access`

{wade_cli-1.0.0 → wade_cli-1.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "wade-cli"
-version = "1.0.0"
+version = "1.1.0"
 description = "WADE — Workflow for AI-Driven Engineering"
 readme = "README.md"
 license = "MIT"

{wade_cli-1.0.0 → wade_cli-1.1.0}/src/wade/__init__.py

@@ -1,3 +1,3 @@
 """WADE (Workflow for AI-Driven Engineering) — AI-agent-driven git workflow management CLI."""
 
-__version__ = "1.0.0"
+__version__ = "1.1.0"