okstra 0.14.0 → 0.14.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.14.0",
-  "builtAt": "2026-05-13T02:55:11.516Z",
+  "package": "0.14.1",
+  "builtAt": "2026-05-13T03:17:50.448Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/workers/codex-worker.md

@@ -18,7 +18,7 @@ description: |
   </example>
 model: inherit
 color: cyan
-tools: ["Bash", "Read", "Write", "Glob", "Grep"]
+tools: ["Bash", "BashOutput", "KillShell", "Read", "Write", "Glob", "Grep"]
 ---
 
 You are a Codex worker agent. Your job is to execute the OpenAI Codex CLI and return the analysis result.
@@ -27,12 +27,14 @@ You are a Codex worker agent. Your job is to execute the OpenAI Codex CLI and re
 
 **Required form (uses the okstra wrapper to avoid redirect-triggered permission prompts):**
 ```bash
-$HOME/.okstra/bin/okstra-codex-exec.sh "<absolute-project-root>" "<assigned-model-execution-value>" "<absolute-prompt-history-path>"
+$HOME/.okstra/bin/okstra-codex-exec.sh "<absolute-project-root>" "<assigned-model-execution-value>" "<absolute-prompt-history-path>" [<absolute-worktree-path>]
 ```
 
+The fourth argument is **mandatory for implementation phase** and optional otherwise. It must be the literal `EXECUTOR_WORKTREE_PATH` recorded in the run context; the wrapper forwards it to codex as `--add-dir`, which grants the codex sandbox write access to the worktree (where all implementation-phase mutations occur). Without it, codex's `workspace-write` sandbox is anchored only at `<project-root>` and rejects every Edit/Write that targets the worktree (EPERM), which is the failure pattern that originally motivated this argument.
+
 The wrapper internally runs:
 ```bash
-codex exec -C "<project-root>" --model "<model>" --sandbox workspace-write - < "<prompt-path>" 2>/dev/null
+codex exec -C "<project-root>" [--add-dir "<worktree-path>"] --model "<model>" --sandbox workspace-write - < "<prompt-path>" 2>/dev/null
 ```
 
 The wrapper exists because Claude Code's Bash permission matcher rejects simple-prefix matches when the command contains stdin/stderr redirects. Calling `codex exec ... - < <path> 2>/dev/null` directly triggers a permission prompt every dispatch even when `Bash(codex exec:*)` is allowlisted. The wrapper folds the redirects inside, so the harness sees a single non-redirect command that matches `Bash($HOME/.okstra/bin/okstra-codex-exec.sh:*)`.
@@ -67,20 +69,34 @@ The wrapper exists because Claude Code's Bash permission matcher rejects simple-
    - If neither is available, immediately return `CODEX_MODEL_MISSING: assigned Codex model execution value was not provided`. Do NOT fall back to training-data defaults — historical codex defaults like `o4-mini` are NOT acceptable substitutes for the assigned model. Returning the sentinel is the correct behavior; the lead is responsible for fixing its prompt and redispatching.
    - This rule applies equally to convergence reverify rounds. The reverify prompt MUST carry the same `**Model:**` line as the initial run (see `okstra-convergence` skill, "Required reverify-prompt anchor headers"). If the line is absent in a reverify prompt, return `CODEX_MODEL_MISSING` rather than guessing.
 
-7. If installed, execute the prompt through the wrapper as a single command with a Bash timeout of 120000 ms. Pass the three positional arguments verbatim — do NOT use environment variables, `cd`, `&&` chains, or pipes from `cat`:
+7. If installed, dispatch the wrapper as a **background** Bash command and poll for completion. The two-minute foreground Bash timeout is insufficient for implementation-phase Codex runs and forced workers into ad-hoc background dispatch with lost output. The polling contract below is the formal replacement.
+
+   **Dispatch (background, no foreground timeout):**
    ```bash
-   $HOME/.okstra/bin/okstra-codex-exec.sh "<absolute-project-root>" "<assigned-model-execution-value>" "<absolute-prompt-history-path>"
+   $HOME/.okstra/bin/okstra-codex-exec.sh "<absolute-project-root>" "<assigned-model-execution-value>" "<absolute-prompt-history-path>" "<absolute-worktree-path>"
    ```
-   Substitute the literal extracted Project Root, model execution value, and prompt-history path in place of the placeholders above. The wrapper handles `-C`, `--model`, `--sandbox workspace-write`, the stdin redirect from the prompt file, and stderr suppression internally. Calling `codex exec` directly (without the wrapper) is an error in this skill: the redirect tokens disqualify the prefix match against `Bash(codex exec:*)` and produce a permission prompt every dispatch.
+   Call `Bash` with `run_in_background: true`. Capture the returned `bash_id` (a.k.a. `shell_id`). Pass the positional arguments verbatim — do NOT use environment variables, `cd`, `&&` chains, or pipes from `cat`. Substitute the literal extracted Project Root, model execution value, prompt-history path, and worktree path. The fourth argument is **mandatory for implementation phase** (extract from `EXECUTOR_WORKTREE_PATH` in the lead prompt's run context or the `**Worktree:**` / `cwd for every mutating command:` line) and **may be omitted only for non-implementation analysis phases** that do not mutate the worktree. Omitting it during implementation will cause every Edit/Write to fail with EPERM. The wrapper handles `-C`, `--add-dir`, `--model`, `--sandbox workspace-write`, the stdin redirect from the prompt file, and stderr suppression internally. Calling `codex exec` directly (without the wrapper) is an error in this skill: the redirect tokens disqualify the prefix match against `Bash(codex exec:*)` and produce a permission prompt every dispatch.
+
+   **Poll loop (60-second cadence, 30-minute hard cap):**
+   - Record `start_ts` at dispatch time.
+   - Repeat:
+     1. Foreground `Bash` call: `sleep 60` (or shorter on the first iteration if you expect a fast finish).
+     2. Call `BashOutput(bash_id: <shell_id>)`. Inspect `status`.
+     3. If `status == "completed"`: break out of the loop and proceed to step 8.
+     4. If `now - start_ts > 1800` seconds: call `KillShell(shell_id: <shell_id>)`, then record a `cli-failure` event with `--error-type cli-failure`, `--exit-code 124`, `--duration-ms 1800000`, `--message "okstra-codex-exec.sh exceeded 30m polling cap"`, and return `CODEX_CLI_TIMEOUT: codex exec exceeded 30-minute polling cap`.
+     5. Otherwise continue polling.
+   - Do NOT abort the loop on transient `running` status. Only `completed` or the 30-minute cap end it.
+   - Do NOT issue parallel `BashOutput` calls or speculate about progress between polls.
 
-8. Return the codex output as-is without modification.
+8. Concatenate the wrapper's accumulated stdout from `BashOutput` and return it as-is without modification. If the final `BashOutput` reports a non-zero `exit_code`, follow the **CLI failure** rule in §"Error reporting" before returning.
 
 ## Stop Condition
 
 This wrapper is a thin Bash-execution shell over the Codex CLI (via `okstra-codex-exec.sh`). The CLI process itself is the analysis engine; this subagent's only job is to dispatch it and forward output. Therefore:
 
-- Return immediately after the wrapper script call returns (or after recording any required `cli-failure` event for a non-zero exit / timeout / rate-limit).
-- Do NOT perform additional `Read`, `Grep`, `Glob`, or other tool calls before or after the CLI dispatch beyond what is strictly required by steps 1–7 (prompt persistence, Project Root extraction, model resolution).
+- Return immediately after the polling loop exits with `completed` (or after recording any required `cli-failure` event for a non-zero exit / 30-minute cap / rate-limit).
+- The only tool calls permitted during the polling loop are `Bash` (for `sleep`), `BashOutput`, and — on the timeout path only — `KillShell`. Do NOT perform additional `Read`, `Grep`, `Glob` calls between polls; do NOT inspect intermediate wrapper output mid-run.
+- Outside the polling loop, no `Read`, `Grep`, or `Glob` beyond what is strictly required by steps 1–7 (prompt persistence, Project Root extraction, model resolution).
 - Do NOT re-invoke `okstra-codex-exec.sh` to "double-check" or "rerun for safety" — convergence (Phase 5.5) handles cross-worker reconciliation. A single CLI dispatch per dispatched-prompt is the contract.
 
 The Codex CLI's own exit terminates the underlying analysis; this wrapper terminates by returning its captured output (or sentinel).
@@ -96,9 +112,9 @@ This wrapper does NOT invoke MCP tools directly. MCP availability inside the Cod
 - The assigned model execution value is canonical for CLI execution. Do not substitute a different Codex model unless the task bundle explicitly changes it.
 - Pass the prompt received from Lead directly to codex after persisting the exact prompt to the assigned path.
 - Include context (code, diff, file paths) if provided.
-- For long prompts, the wrapper script reads from the saved project-local prompt history file via stdin redirect internally. The caller invokes the wrapper with three positional args:
+- For long prompts, the wrapper script reads from the saved project-local prompt history file via stdin redirect internally. The caller invokes the wrapper with three required positional args + the worktree path for implementation phase:
   ```bash
-  $HOME/.okstra/bin/okstra-codex-exec.sh "<literal-project-root>" "<assigned-model-execution-value>" "<literal-prompt-history-path>"
+  $HOME/.okstra/bin/okstra-codex-exec.sh "<literal-project-root>" "<assigned-model-execution-value>" "<literal-prompt-history-path>" "<literal-worktree-path>"
   ```
 - If the parent directory does not exist yet, create it before writing the prompt file.
 
@@ -146,9 +162,12 @@ two kinds of errors via `scripts/okstra-error-log.py`:
    then append. Lead will dump it to the run error log after this subagent
    terminates.
 
-2. **CLI failure (lead-observed)** — if `codex exec` returns non-zero, times
-   out (Bash 120000ms), or returns a rate-limit/auth message, immediately
-   append a `cli-failure` event directly to the run error log:
+2. **CLI failure (lead-observed)** — if the wrapper's final `BashOutput`
+   reports a non-zero `exit_code`, the 30-minute polling cap is hit, or the
+   captured stdout/stderr carries a rate-limit/auth message, immediately
+   append a `cli-failure` event directly to the run error log. The
+   30-minute-cap path additionally requires a prior `KillShell` call against
+   the dispatched `bash_id`:
 
    ```bash
    python3 scripts/okstra-error-log.py append-observed \
@@ -158,7 +177,7 @@ two kinds of errors via `scripts/okstra-error-log.py`:
      --agent codex-worker --agent-role worker \
      --model "<assigned-model-execution-value>" \
      --error-type cli-failure \
-     --command "$HOME/.okstra/bin/okstra-codex-exec.sh <project-root> <m> <prompt-path>" \
+     --command "$HOME/.okstra/bin/okstra-codex-exec.sh <project-root> <m> <prompt-path> <worktree-path>" \
      --command-kind cli-invoke \
      --exit-code <N> --duration-ms <ms> \
      --message "<one-line summary>" \

package/runtime/agents/workers/gemini-worker.md

@@ -18,7 +18,7 @@ description: |
   </example>
 model: inherit
 color: green
-tools: ["Bash", "Read", "Write", "Glob", "Grep"]
+tools: ["Bash", "BashOutput", "KillShell", "Read", "Write", "Glob", "Grep"]
 ---
 
 You are a Gemini worker agent. Your job is to execute the Google Gemini CLI and return the analysis result.
@@ -27,12 +27,14 @@ You are a Gemini worker agent. Your job is to execute the Google Gemini CLI and
 
 **Required form (uses the okstra wrapper to avoid redirect-triggered permission prompts):**
 ```bash
-$HOME/.okstra/bin/okstra-gemini-exec.sh "<absolute-project-root>" "<assigned-model-execution-value>" "<absolute-prompt-history-path>"
+$HOME/.okstra/bin/okstra-gemini-exec.sh "<absolute-project-root>" "<assigned-model-execution-value>" "<absolute-prompt-history-path>" [<absolute-worktree-path>]
 ```
 
+The fourth argument is **mandatory for implementation phase** and optional otherwise. It must be the literal `EXECUTOR_WORKTREE_PATH` recorded in the run context; the wrapper appends it to gemini's `--include-directories` list so the model can both read and operate on the worktree alongside project-root.
+
 The wrapper internally runs:
 ```bash
-gemini -p - -m "<model>" -o text --include-directories "<project-root>" < "<prompt-path>" 2>/dev/null
+gemini -p - -m "<model>" -o text --include-directories "<project-root>[,<worktree-path>]" < "<prompt-path>" 2>/dev/null
 ```
 
 The wrapper exists because Claude Code's Bash permission matcher rejects simple-prefix matches when the command contains stdin/stderr redirects. Calling `gemini -p - ... < <path> 2>/dev/null` directly triggers a permission prompt every dispatch even when `Bash(gemini:*)` is allowlisted. The wrapper folds the redirects inside, so the harness sees a single non-redirect command that matches `Bash($HOME/.okstra/bin/okstra-gemini-exec.sh:*)`.
@@ -67,20 +69,34 @@ The wrapper exists because Claude Code's Bash permission matcher rejects simple-
    - If no assigned model execution value can be determined, immediately return `GEMINI_MODEL_MISSING: assigned Gemini model execution value was not provided`. Do NOT fall back to training-data defaults — historical Gemini defaults (e.g. `gemini-1.5-flash`) are NOT acceptable substitutes for the assigned model. Returning the sentinel is the correct behavior; the lead is responsible for fixing its prompt and redispatching.
    - This rule applies equally to convergence reverify rounds. The reverify prompt MUST carry the same `**Model:**` line as the initial run (see `okstra-convergence` skill, "Required reverify-prompt anchor headers"). If the line is absent in a reverify prompt, return `GEMINI_MODEL_MISSING` rather than guessing.
 
-7. If installed, execute the prompt through the wrapper as a single command with a Bash timeout of 120000 ms. Pass the three positional arguments verbatim — do NOT use environment variables, `cd`, `&&` chains, or pipes from `cat`:
+7. If installed, dispatch the wrapper as a **background** Bash command and poll for completion. The two-minute foreground Bash timeout is insufficient for implementation-phase Gemini runs and forced workers into ad-hoc background dispatch with lost output. The polling contract below is the formal replacement.
+
+   **Dispatch (background, no foreground timeout):**
    ```bash
-   $HOME/.okstra/bin/okstra-gemini-exec.sh "<absolute-project-root>" "<assigned-model-execution-value>" "<absolute-prompt-history-path>"
+   $HOME/.okstra/bin/okstra-gemini-exec.sh "<absolute-project-root>" "<assigned-model-execution-value>" "<absolute-prompt-history-path>" "<absolute-worktree-path>"
    ```
-   Substitute the literal extracted Project Root, model execution value, and prompt-history path in place of the placeholders above. The wrapper handles `-p -`, `-m`, `-o text`, `--include-directories`, the stdin redirect from the prompt file, and stderr suppression internally. Calling `gemini` directly (without the wrapper) is an error in this skill: the redirect tokens disqualify the prefix match against `Bash(gemini:*)` and produce a permission prompt every dispatch.
+   Call `Bash` with `run_in_background: true`. Capture the returned `bash_id` (a.k.a. `shell_id`). Pass the positional arguments verbatim — do NOT use environment variables, `cd`, `&&` chains, or pipes from `cat`. Substitute the literal extracted Project Root, model execution value, prompt-history path, and worktree path. The fourth argument is **mandatory for implementation phase** (extract from `EXECUTOR_WORKTREE_PATH` in the lead prompt's run context or the `**Worktree:**` / `cwd for every mutating command:` line) and **may be omitted only for non-implementation analysis phases** that do not mutate the worktree. The wrapper handles `-p -`, `-m`, `-o text`, `--include-directories`, the stdin redirect from the prompt file, and stderr suppression internally. Calling `gemini` directly (without the wrapper) is an error in this skill: the redirect tokens disqualify the prefix match against `Bash(gemini:*)` and produce a permission prompt every dispatch.
+
+   **Poll loop (60-second cadence, 30-minute hard cap):**
+   - Record `start_ts` at dispatch time.
+   - Repeat:
+     1. Foreground `Bash` call: `sleep 60` (or shorter on the first iteration if you expect a fast finish).
+     2. Call `BashOutput(bash_id: <shell_id>)`. Inspect `status`.
+     3. If `status == "completed"`: break out of the loop and proceed to step 8.
+     4. If `now - start_ts > 1800` seconds: call `KillShell(shell_id: <shell_id>)`, then record a `cli-failure` event with `--error-type cli-failure`, `--exit-code 124`, `--duration-ms 1800000`, `--message "okstra-gemini-exec.sh exceeded 30m polling cap"`, and return `GEMINI_CLI_TIMEOUT: gemini exec exceeded 30-minute polling cap`.
+     5. Otherwise continue polling.
+   - Do NOT abort the loop on transient `running` status. Only `completed` or the 30-minute cap end it.
+   - Do NOT issue parallel `BashOutput` calls or speculate about progress between polls.
 
-8. Return the gemini output as-is without modification.
+8. Concatenate the wrapper's accumulated stdout from `BashOutput` and return it as-is without modification. If the final `BashOutput` reports a non-zero `exit_code`, follow the **CLI failure** rule in §"Error reporting" before returning.
 
 ## Stop Condition
 
 This wrapper is a thin Bash-execution shell over the Gemini CLI (via `okstra-gemini-exec.sh`). The CLI process itself is the analysis engine; this subagent's only job is to dispatch it and forward output. Therefore:
 
-- Return immediately after the wrapper script call returns (or after recording any required `cli-failure` event for a non-zero exit / timeout / rate-limit).
-- Do NOT perform additional `Read`, `Grep`, `Glob`, or other tool calls before or after the CLI dispatch beyond what is strictly required by steps 1–7 (prompt persistence, Project Root extraction, model resolution).
+- Return immediately after the polling loop exits with `completed` (or after recording any required `cli-failure` event for a non-zero exit / 30-minute cap / rate-limit).
+- The only tool calls permitted during the polling loop are `Bash` (for `sleep`), `BashOutput`, and — on the timeout path only — `KillShell`. Do NOT perform additional `Read`, `Grep`, `Glob` calls between polls; do NOT inspect intermediate wrapper output mid-run.
+- Outside the polling loop, no `Read`, `Grep`, or `Glob` beyond what is strictly required by steps 1–7 (prompt persistence, Project Root extraction, model resolution).
 - Do NOT re-invoke `okstra-gemini-exec.sh` to "double-check" or "rerun for safety" — convergence (Phase 5.5) handles cross-worker reconciliation. A single CLI dispatch per dispatched-prompt is the contract.
 
 The Gemini CLI's own exit terminates the underlying analysis; this wrapper terminates by returning its captured output (or sentinel).
@@ -96,9 +112,9 @@ This wrapper does NOT invoke MCP tools directly. MCP availability inside the Gem
 - The assigned model execution value is canonical for CLI execution. Do not substitute a different Gemini model unless the task bundle explicitly changes it.
 - Pass the prompt received from Lead directly to gemini after persisting the exact prompt to the assigned path.
 - Include context (code, diff, file paths) if provided.
-- For long prompts, dispatch through the wrapper with literal absolute paths:
+- For long prompts, dispatch through the wrapper with literal absolute paths (plus the worktree path for implementation phase):
   ```bash
-  $HOME/.okstra/bin/okstra-gemini-exec.sh "<literal-project-root>" "<assigned-model-execution-value>" "<literal-prompt-history-path>"
+  $HOME/.okstra/bin/okstra-gemini-exec.sh "<literal-project-root>" "<assigned-model-execution-value>" "<literal-prompt-history-path>" "<literal-worktree-path>"
   ```
 - If the parent directory does not exist yet, create it before writing the prompt file.
 
@@ -146,9 +162,12 @@ two kinds of errors via `scripts/okstra-error-log.py`:
    then append. Lead will dump it to the run error log after this subagent
    terminates.
 
-2. **CLI failure (lead-observed)** — if `gemini` returns non-zero, times out
-   (Bash 120000ms), or returns a rate-limit/auth message, immediately append
-   a `cli-failure` event directly to the run error log:
+2. **CLI failure (lead-observed)** — if the wrapper's final `BashOutput`
+   reports a non-zero `exit_code`, the 30-minute polling cap is hit, or the
+   captured stdout/stderr carries a rate-limit/auth message, immediately
+   append a `cli-failure` event directly to the run error log. The
+   30-minute-cap path additionally requires a prior `KillShell` call against
+   the dispatched `bash_id`:
 
    ```bash
    python3 scripts/okstra-error-log.py append-observed \
@@ -158,7 +177,7 @@ two kinds of errors via `scripts/okstra-error-log.py`:
      --agent gemini-worker --agent-role worker \
      --model "<assigned-model-execution-value>" \
      --error-type cli-failure \
-     --command "$HOME/.okstra/bin/okstra-gemini-exec.sh <project-root> <m> <prompt-path>" \
+     --command "$HOME/.okstra/bin/okstra-gemini-exec.sh <project-root> <m> <prompt-path> <worktree-path>" \
      --command-kind cli-invoke \
      --exit-code <N> --duration-ms <ms> \
      --message "<one-line summary>" \

package/runtime/bin/okstra-codex-exec.sh

@@ -13,20 +13,29 @@
 #   Bash($HOME/.okstra/bin/okstra-codex-exec.sh:*)
 #
 # Usage:
-#   okstra-codex-exec.sh <project-root> <model-execution-value> <prompt-path>
+#   okstra-codex-exec.sh <project-root> <model-execution-value> <prompt-path> [worktree-path]
 #
-# All three arguments are required and must be absolute paths or literal model
-# strings. The wrapper exits non-zero on any preflight failure.
+# project-root / model-execution-value / prompt-path are required.
+#
+# worktree-path is optional and used for okstra implementation phase, where the
+# executor must mutate files inside a git worktree that lives outside
+# project-root. When supplied (non-empty), it is forwarded to codex as
+# `--add-dir <worktree-path>` so the codex sandbox grants write access to that
+# directory alongside the primary workspace anchored at project-root. When
+# omitted or empty, no `--add-dir` is added (existing analysis-phase behavior).
+#
+# The wrapper exits non-zero on any preflight failure.
 set -euo pipefail
 
-if [[ $# -ne 3 ]]; then
-  printf 'usage: %s <project-root> <model-execution-value> <prompt-path>\n' "$(basename "$0")" >&2
+if [[ $# -lt 3 || $# -gt 4 ]]; then
+  printf 'usage: %s <project-root> <model-execution-value> <prompt-path> [worktree-path]\n' "$(basename "$0")" >&2
   exit 64
 fi
 
 project_root="$1"
 model="$2"
 prompt_path="$3"
+worktree_path="${4-}"
 
 if [[ -z "$project_root" || ! -d "$project_root" ]]; then
   printf 'okstra-codex-exec: project-root is missing or not a directory: %q\n' "$project_root" >&2
@@ -48,6 +57,16 @@ if ! command -v codex >/dev/null 2>&1; then
   exit 127
 fi
 
+if [[ -n "$worktree_path" && ! -d "$worktree_path" ]]; then
+  printf 'okstra-codex-exec: worktree-path was provided but is not a directory: %q\n' "$worktree_path" >&2
+  exit 68
+fi
+
+extra_args=()
+if [[ -n "$worktree_path" ]]; then
+  extra_args+=(--add-dir "$worktree_path")
+fi
+
 # stdin redirect and stderr suppression are intentionally inside the wrapper —
 # this is the entire reason this script exists.
-exec codex exec -C "$project_root" --model "$model" --sandbox workspace-write - < "$prompt_path" 2>/dev/null
+exec codex exec -C "$project_root" ${extra_args[@]+"${extra_args[@]}"} --model "$model" --sandbox workspace-write - < "$prompt_path" 2>/dev/null

package/runtime/bin/okstra-gemini-exec.sh

@@ -13,20 +13,29 @@
 #   Bash($HOME/.okstra/bin/okstra-gemini-exec.sh:*)
 #
 # Usage:
-#   okstra-gemini-exec.sh <project-root> <model-execution-value> <prompt-path>
+#   okstra-gemini-exec.sh <project-root> <model-execution-value> <prompt-path> [worktree-path]
 #
-# All three arguments are required and must be absolute paths or literal model
-# strings. The wrapper exits non-zero on any preflight failure.
+# project-root / model-execution-value / prompt-path are required.
+#
+# worktree-path is optional and used for okstra implementation phase, where the
+# executor must mutate files inside a git worktree that lives outside
+# project-root. When supplied (non-empty), it is appended to gemini's
+# `--include-directories` list (comma-separated) so the model can see and
+# operate on the worktree alongside the primary workspace. When omitted or
+# empty, only project-root is included (existing analysis-phase behavior).
+#
+# The wrapper exits non-zero on any preflight failure.
 set -euo pipefail
 
-if [[ $# -ne 3 ]]; then
-  printf 'usage: %s <project-root> <model-execution-value> <prompt-path>\n' "$(basename "$0")" >&2
+if [[ $# -lt 3 || $# -gt 4 ]]; then
+  printf 'usage: %s <project-root> <model-execution-value> <prompt-path> [worktree-path]\n' "$(basename "$0")" >&2
   exit 64
 fi
 
 project_root="$1"
 model="$2"
 prompt_path="$3"
+worktree_path="${4-}"
 
 if [[ -z "$project_root" || ! -d "$project_root" ]]; then
   printf 'okstra-gemini-exec: project-root is missing or not a directory: %q\n' "$project_root" >&2
@@ -48,8 +57,18 @@ if ! command -v gemini >/dev/null 2>&1; then
   exit 127
 fi
 
+if [[ -n "$worktree_path" && ! -d "$worktree_path" ]]; then
+  printf 'okstra-gemini-exec: worktree-path was provided but is not a directory: %q\n' "$worktree_path" >&2
+  exit 68
+fi
+
+include_dirs="$project_root"
+if [[ -n "$worktree_path" ]]; then
+  include_dirs="$project_root,$worktree_path"
+fi
+
 # stdin redirect and stderr suppression are intentionally inside the wrapper —
 # this is the entire reason this script exists. Gemini CLI has no `--cd` flag,
 # so workspace correctness is anchored via `--include-directories` plus the
 # Project Root referenced in the prompt body itself.
-exec gemini -p - -m "$model" -o text --include-directories "$project_root" < "$prompt_path" 2>/dev/null
+exec gemini -p - -m "$model" -o text --include-directories "$include_dirs" < "$prompt_path" 2>/dev/null

package/runtime/skills/okstra-team-contract/SKILL.md

@@ -270,6 +270,12 @@ Workers MUST omit `source` / `recordedAt` / `agent` / `agentRole` / `model` /
 Workers MUST use only `errorType: "tool-failure"` in the **sidecar file**.
 
 - `cli-failure` events are recorded by the wrapper subagent itself (Codex / Gemini), but **directly to the run-level error log** via `okstra-error-log.py append-observed --error-type cli-failure ...` — NOT via the sidecar. The sidecar is an in-process tool-failure channel only.
+- **Wrapper invocation arity.** Both `okstra-codex-exec.sh` and `okstra-gemini-exec.sh` accept four positional arguments: `<project-root> <model> <prompt-path> [<worktree-path>]`. The fourth (worktree) argument is **mandatory for implementation phase** and optional otherwise. For codex it becomes `--add-dir <worktree>` (sandbox write access); for gemini it is appended to `--include-directories`. Omitting it during implementation causes the codex sandbox to reject every Edit/Write targeting the worktree with EPERM. Workers extract the path from the `**Worktree:**` / `EXECUTOR_WORKTREE_PATH` / `cwd for every mutating command:` line in the lead prompt.
+- **Background dispatch + polling contract (Codex / Gemini wrappers).** Both wrapper subagents MUST dispatch `okstra-codex-exec.sh` / `okstra-gemini-exec.sh` via `Bash(run_in_background: true)` and poll with `BashOutput(bash_id)` on a 60-second cadence, capped at 30 minutes (1800s). The legacy "single foreground `Bash` with 120000ms timeout" rule is retired — it forced workers into ad-hoc background dispatch that lost stdout and silently broke Phase 5 synthesis. The new rule applies in **every phase** (analysis runs typically complete in 1–2 polls, so there is no regression for short jobs). Recording responsibilities:
+  - Successful completion: return the wrapper's accumulated stdout from the final `BashOutput`. No log entry.
+  - Non-zero `exit_code` reported by `BashOutput`: record a `cli-failure` to the run-level error log with the real `exit_code` and observed `duration-ms`.
+  - 30-minute polling cap exceeded: call `KillShell(shell_id)` first, then record `cli-failure` with `--exit-code 124 --duration-ms 1800000 --message "<wrapper> exceeded 30m polling cap"`, then return the language-specific `*_CLI_TIMEOUT` sentinel.
+  - Token-usage matching is unaffected: the wrapper subagent stays alive throughout polling, so the wrapper's jsonl timestamp window continues to cover the underlying CLI rollout's full duration (see §"Token-usage accounting" below).
 - `contract-violation` events (C) are recorded by Lead via `okstra-error-log.py append-observed --error-type contract-violation ...` after inspecting worker outputs.
 - Lead's responsibility regarding the sidecar is to dump it to the run-level error log via `okstra-error-log.py append-from-worker` after each worker terminates; Lead does not write into the sidecar.