okstra 0.18.3 → 0.19.1

package/docs/kr/architecture.md

@@ -105,10 +105,20 @@ okstra 의 prepare 책임은 단일 python 진입점 [`okstra_ctl.run.prepare_ta
 
 ### Python module 진입점 (single authority)
 
-- [`okstra_ctl.run`](scripts/okstra_ctl/run.py) — `prepare_task_bundle()` orchestrator + argparse CLI (`python3 -m okstra_ctl.run --workspace-root ... --project-root ... ...`).
+> **호출 규약.** 아래 `python3 -m okstra_ctl.*` / `python3 -m okstra_project.*` 형태는 **모듈 식별자**일 뿐이며, 시스템 site-packages에 설치되지 않습니다. 직접 셸에서 호출하려면 먼저 `PYTHONPATH` 를 `~/.okstra/lib/python` 으로 export 해야 합니다:
+>
+> ```bash
+> eval "$(okstra paths --shell)"      # OKSTRA_PYTHONPATH 등을 export
+> export PYTHONPATH="$OKSTRA_PYTHONPATH"
+> python3 -m okstra_ctl.run --help    # 이제 동작
+> ```
+>
+> 위 두 줄을 생략하면 `ModuleNotFoundError: No module named 'okstra_ctl'` 로 즉시 실패합니다 (실제 implementation phase 워커가 docs 만 보고 직접 호출하다가 자주 겪는 패턴). 일반 사용자/워커는 모듈을 직접 부르지 말고 `scripts/okstra.sh` 또는 `/okstra-run` 진입점을 사용하세요 — 그 wrapper 들이 PYTHONPATH 세팅을 자동으로 해 줍니다.
+
+- [`okstra_ctl.run`](scripts/okstra_ctl/run.py) — `prepare_task_bundle()` orchestrator + argparse CLI (`python3 -m okstra_ctl.run --workspace-root ... --project-root ... ...`, **PYTHONPATH 세팅 필요 — 위 호출 규약 참조**).
 - [`okstra_ctl.paths`](scripts/okstra_ctl/paths.py) — `compute_run_paths()` pure path/seq 계산.
 - [`okstra_ctl.run_context`](scripts/okstra_ctl/run_context.py) — `compute_and_write_run_context()`, `write_run_inputs()`, per-task mutex.
-- [`okstra_ctl.render`](scripts/okstra_ctl/render.py) — task-manifest / run-manifest / timeline / task-index / team-state / launch.template / reference-expectations / discovery 9개 render 함수 + `python3 -m okstra_ctl.render <subcommand>` dispatcher.
+- [`okstra_ctl.render`](scripts/okstra_ctl/render.py) — task-manifest / run-manifest / timeline / task-index / team-state / launch.template / reference-expectations / discovery 9개 render 함수 + `python3 -m okstra_ctl.render <subcommand>` dispatcher (**PYTHONPATH 세팅 필요 — 위 호출 규약 참조**).
 - [`okstra_ctl.workers`](scripts/okstra_ctl/workers.py) · [`okstra_ctl.models`](scripts/okstra_ctl/models.py) — worker / model 해소.
 - [`okstra_ctl.workflow`](scripts/okstra_ctl/workflow.py) — phase rules (PHASE_ALLOWED_OUTPUTS / PHASE_FORBIDDEN_ACTIONS).
 - [`okstra_ctl.material`](scripts/okstra_ctl/material.py) — `analysis-material.md` 본문 + related-tasks 빌더.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.18.3",
+  "version": "0.19.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.18.3",
-  "builtAt": "2026-05-13T13:59:58.844Z",
+  "package": "0.19.1",
+  "builtAt": "2026-05-13T15:21:25.918Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

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

@@ -77,16 +77,16 @@ The wrapper exists because Claude Code's Bash permission matcher rejects simple-
    ```
    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.
+   **Poll loop (BashOutput-only, 30-minute hard cap):**
+   - Record `start_ts` at dispatch time via a single `Bash` call: `date +%s` (output captured).
    - 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.
+     1. Call `BashOutput(bash_id: <shell_id>)`. Inspect `status`. The harness's `BashOutput` primitive already waits internally for new output before returning; back-to-back calls are the canonical wait mechanism for a background shell.
+     2. If `status == "completed"`: break out of the loop and proceed to step 8.
+     3. If wall-clock elapsed (`current_ts - start_ts`) exceeds `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`.
+     4. Otherwise continue polling. Read `current_ts` cheaply via another `Bash` call (`date +%s`) at most once per poll iteration.
    - 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.
+   - **No standalone `sleep` between polls.** The harness blocks `sleep` calls of 5 seconds or longer as a circumvention vector and explicitly forbids chaining shorter sleeps to work around it. `BashOutput` itself is the wait primitive — calling it again immediately after a `running` status is correct. If you find yourself wanting to "slow down" the loop, that desire is a leftover from the retired 60-second-cadence rule and should be ignored.
 
 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.
 
@@ -95,7 +95,7 @@ The wrapper exists because Claude Code's Bash permission matcher rejects simple-
 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 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.
+- The only tool calls permitted during the polling loop are `BashOutput`, a single `Bash` call per iteration for `date +%s` (timeout bookkeeping only — no `sleep`), 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.
 

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

@@ -77,16 +77,16 @@ The wrapper exists because Claude Code's Bash permission matcher rejects simple-
    ```
    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.
+   **Poll loop (BashOutput-only, 30-minute hard cap):**
+   - Record `start_ts` at dispatch time via a single `Bash` call: `date +%s` (output captured).
    - 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.
+     1. Call `BashOutput(bash_id: <shell_id>)`. Inspect `status`. The harness's `BashOutput` primitive already waits internally for new output before returning; back-to-back calls are the canonical wait mechanism for a background shell.
+     2. If `status == "completed"`: break out of the loop and proceed to step 8.
+     3. If wall-clock elapsed (`current_ts - start_ts`) exceeds `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`.
+     4. Otherwise continue polling. Read `current_ts` cheaply via another `Bash` call (`date +%s`) at most once per poll iteration.
    - 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.
+   - **No standalone `sleep` between polls.** The harness blocks `sleep` calls of 5 seconds or longer as a circumvention vector and explicitly forbids chaining shorter sleeps to work around it. `BashOutput` itself is the wait primitive — calling it again immediately after a `running` status is correct. If you find yourself wanting to "slow down" the loop, that desire is a leftover from the retired 60-second-cadence rule and should be ignored.
 
 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.
 
@@ -95,7 +95,7 @@ The wrapper exists because Claude Code's Bash permission matcher rejects simple-
 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 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.
+- The only tool calls permitted during the polling loop are `BashOutput`, a single `Bash` call per iteration for `date +%s` (timeout bookkeeping only — no `sleep`), 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.
 

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

@@ -13,7 +13,7 @@
 #   Bash($HOME/.okstra/bin/okstra-codex-exec.sh:*)
 #
 # Usage:
-#   okstra-codex-exec.sh <project-root> <model-execution-value> <prompt-path> [worktree-path]
+#   okstra-codex-exec.sh <project-root> <model-execution-value> <prompt-path> [worktree-path] [role]
 #
 # project-root / model-execution-value / prompt-path are required.
 #
@@ -24,11 +24,28 @@
 # directory alongside the primary workspace anchored at project-root. When
 # omitted or empty, no `--add-dir` is added (existing analysis-phase behavior).
 #
+# role is optional and used only to label the auto-spawned tmux trace pane
+# (see "trace pane" section below). When omitted, it defaults to `executor`
+# if worktree-path is non-empty (the implementation-phase invariant) and
+# `worker` otherwise.
+#
+# For linked worktrees (the okstra implementation default), the per-worktree
+# git metadata (index, HEAD, refs) and the shared object database live in the
+# main repository's `.git` directory — OUTSIDE the worktree-path. Without
+# write access there, `git add` / `git commit` from inside the worktree fails
+# with EPERM on `.git/worktrees/<name>/index.lock`, which is the documented
+# failure pattern for linked-worktree commits under `workspace-write`. The
+# wrapper resolves the main repo's git-common-dir via `git rev-parse` against
+# the supplied worktree-path and forwards it as an additional `--add-dir`. If
+# resolution fails (not a linked worktree, or git unavailable), the extra
+# add-dir is silently omitted — the caller still gets the worktree add-dir
+# and any commit failure surfaces as a normal sandbox EPERM.
+#
 # The wrapper exits non-zero on any preflight failure.
 set -euo pipefail
 
-if [[ $# -lt 3 || $# -gt 4 ]]; then
-  printf 'usage: %s <project-root> <model-execution-value> <prompt-path> [worktree-path]\n' "$(basename "$0")" >&2
+if [[ $# -lt 3 || $# -gt 5 ]]; then
+  printf 'usage: %s <project-root> <model-execution-value> <prompt-path> [worktree-path] [role]\n' "$(basename "$0")" >&2
   exit 64
 fi
 
@@ -36,6 +53,10 @@ project_root="$1"
 model="$2"
 prompt_path="$3"
 worktree_path="${4-}"
+role="${5-}"
+if [[ -z "$role" ]]; then
+  if [[ -n "$worktree_path" ]]; then role="executor"; else role="worker"; fi
+fi
 
 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
@@ -65,8 +86,76 @@ fi
 extra_args=()
 if [[ -n "$worktree_path" ]]; then
   extra_args+=(--add-dir "$worktree_path")
+  # For linked worktrees, also open the main repo's `.git` so `git add` /
+  # `git commit` can write the per-worktree index/refs (under
+  # `.git/worktrees/<name>/`) and the shared object DB (`.git/objects/`).
+  # `--git-common-dir` resolves to the main repo's `.git` for any worktree
+  # (linked or main); for a main checkout it equals `<worktree>/.git` and is
+  # redundant-but-harmless. Failures (not-a-git-repo, git missing) are
+  # tolerated silently so analysis-phase callers stay unaffected.
+  if command -v git >/dev/null 2>&1; then
+    common_git_dir=$(git -C "$worktree_path" rev-parse --git-common-dir 2>/dev/null || true)
+    if [[ -n "$common_git_dir" ]]; then
+      # `rev-parse --git-common-dir` may return a path relative to the
+      # worktree; normalise to an absolute directory before forwarding.
+      if [[ "$common_git_dir" != /* ]]; then
+        common_git_dir="$worktree_path/$common_git_dir"
+      fi
+      if [[ -d "$common_git_dir" ]]; then
+        # Resolve `..` / symlinks so codex sees a canonical path.
+        common_git_dir=$(cd "$common_git_dir" && pwd -P)
+        extra_args+=(--add-dir "$common_git_dir")
+      fi
+    fi
+  fi
 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" ${extra_args[@]+"${extra_args[@]}"} --model "$model" --sandbox workspace-write - < "$prompt_path" 2>/dev/null
+# Derive a live-progress log path next to the prompt. The codex CLI streams
+# its progress over stdout/stderr, but the caller (codex-worker subagent)
+# only polls `BashOutput` on a 60s cadence — so without a sideband, a 10–30
+# minute implementation run produces no visible output until the very end.
+# Mirroring both streams into a file alongside the prompt lets the human
+# operator `tail -f <log-path>` from a separate pane and watch progress in
+# real time, and leaves a post-mortem record on disk regardless of how the
+# subagent renders the dispatch.
+log_path="${prompt_path%.md}.log"
+[[ "$log_path" == "$prompt_path" ]] && log_path="${prompt_path}.log"
+: > "$log_path"
+
+# When a tmux session is reachable, split a sibling pane that tails the live
+# log so the operator can watch codex's progress in real time without waiting
+# for the wrapper to exit. This fires in every phase the wrapper is invoked
+# from (analysis, error-analysis, implementation-planning, implementation,
+# …) — long-running codex dispatches are not implementation-specific. The
+# new pane carries the title `codex-<role>-trace` (e.g. `codex-worker-trace`
+# in analysis, `codex-executor-trace` in implementation) and uses `tail -F`
+# (follow-by-name) so it survives any truncation a re-dispatch performs on
+# the same log path. Failures are tolerated silently: missing $TMUX, a tmux
+# that refuses to split (size constraints, locked client), or a stale socket
+# all degrade to "log file is still on disk; the operator can tail it
+# manually from any terminal." The wrapper does NOT switch focus to the new
+# pane — control returns to the caller's pane via `tmux last-pane`.
+if [[ -n "${TMUX:-}" ]]; then
+  trace_pane=$(tmux split-window -h -P -F '#{pane_id}' \
+    -c "$(dirname "$log_path")" \
+    "tail -F $(printf '%q' "$log_path")" 2>/dev/null || true)
+  if [[ -n "$trace_pane" ]]; then
+    tmux select-pane -t "$trace_pane" -T "codex-${role}-trace" 2>/dev/null || true
+    tmux last-pane 2>/dev/null || true
+  fi
+fi
+
+# stdin redirect, stderr capture, and pipeline mirroring are intentionally
+# inside the wrapper — this is the entire reason this script exists.
+#
+# stdout: tee'd to both the log file (for `tail -f`) AND the wrapper's own
+#         stdout (so the subagent's `BashOutput` still captures the final
+#         text verbatim for Phase 5 synthesis).
+# stderr: appended to the log file only — mirrors the prior `2>/dev/null`
+#         contract of keeping the wrapper's stderr stream clean.
+# exit:   `PIPESTATUS[0]` preserves codex's own exit code (tee always 0).
+{
+  codex exec -C "$project_root" ${extra_args[@]+"${extra_args[@]}"} --model "$model" --sandbox workspace-write - \
+    < "$prompt_path" 2>> "$log_path"
+} | tee -a "$log_path"
+exit "${PIPESTATUS[0]}"

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

@@ -13,7 +13,7 @@
 #   Bash($HOME/.okstra/bin/okstra-gemini-exec.sh:*)
 #
 # Usage:
-#   okstra-gemini-exec.sh <project-root> <model-execution-value> <prompt-path> [worktree-path]
+#   okstra-gemini-exec.sh <project-root> <model-execution-value> <prompt-path> [worktree-path] [role]
 #
 # project-root / model-execution-value / prompt-path are required.
 #
@@ -24,11 +24,20 @@
 # operate on the worktree alongside the primary workspace. When omitted or
 # empty, only project-root is included (existing analysis-phase behavior).
 #
+# For linked worktrees, the per-worktree git metadata (index, HEAD, refs) and
+# the shared object database live in the main repository's `.git` directory —
+# OUTSIDE the worktree-path. Without access there, `git add` / `git commit`
+# from inside the worktree fails on `.git/worktrees/<name>/index.lock`. The
+# wrapper resolves the main repo's git-common-dir via `git rev-parse` against
+# the supplied worktree-path and appends it to `--include-directories`. If
+# resolution fails (not a linked worktree, or git unavailable), the extra
+# include is silently omitted.
+#
 # The wrapper exits non-zero on any preflight failure.
 set -euo pipefail
 
-if [[ $# -lt 3 || $# -gt 4 ]]; then
-  printf 'usage: %s <project-root> <model-execution-value> <prompt-path> [worktree-path]\n' "$(basename "$0")" >&2
+if [[ $# -lt 3 || $# -gt 5 ]]; then
+  printf 'usage: %s <project-root> <model-execution-value> <prompt-path> [worktree-path] [role]\n' "$(basename "$0")" >&2
   exit 64
 fi
 
@@ -36,6 +45,10 @@ project_root="$1"
 model="$2"
 prompt_path="$3"
 worktree_path="${4-}"
+role="${5-}"
+if [[ -z "$role" ]]; then
+  if [[ -n "$worktree_path" ]]; then role="executor"; else role="worker"; fi
+fi
 
 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
@@ -65,10 +78,68 @@ fi
 include_dirs="$project_root"
 if [[ -n "$worktree_path" ]]; then
   include_dirs="$project_root,$worktree_path"
+  # For linked worktrees, also open the main repo's `.git` so `git add` /
+  # `git commit` can write the per-worktree index/refs and the shared
+  # object DB. `--git-common-dir` resolves to the main repo's `.git` for
+  # any worktree (linked or main); for a main checkout it equals
+  # `<worktree>/.git` and is redundant-but-harmless. Failures are tolerated
+  # silently so analysis-phase callers stay unaffected.
+  if command -v git >/dev/null 2>&1; then
+    common_git_dir=$(git -C "$worktree_path" rev-parse --git-common-dir 2>/dev/null || true)
+    if [[ -n "$common_git_dir" ]]; then
+      if [[ "$common_git_dir" != /* ]]; then
+        common_git_dir="$worktree_path/$common_git_dir"
+      fi
+      if [[ -d "$common_git_dir" ]]; then
+        common_git_dir=$(cd "$common_git_dir" && pwd -P)
+        include_dirs="$include_dirs,$common_git_dir"
+      fi
+    fi
+  fi
+fi
+
+# Derive a live-progress log path next to the prompt. The gemini CLI streams
+# its progress over stdout/stderr, but the caller (gemini-worker subagent)
+# only polls `BashOutput` on a 60s cadence — so without a sideband, a long
+# implementation run produces no visible output until the very end. Mirroring
+# both streams into a file alongside the prompt lets the human operator
+# `tail -f <log-path>` from a separate pane and watch progress in real time,
+# and leaves a post-mortem record on disk.
+log_path="${prompt_path%.md}.log"
+[[ "$log_path" == "$prompt_path" ]] && log_path="${prompt_path}.log"
+: > "$log_path"
+
+# When a tmux session is reachable, split a sibling pane tailing the log so
+# the operator can watch progress live. This fires in every phase the
+# wrapper is invoked from — long-running gemini dispatches are not
+# implementation-specific. Title `gemini-<role>-trace` (e.g.
+# `gemini-worker-trace` in analysis, `gemini-executor-trace` in
+# implementation). See the codex wrapper for the full design rationale and
+# the silent-degrade failure model.
+if [[ -n "${TMUX:-}" ]]; then
+  trace_pane=$(tmux split-window -h -P -F '#{pane_id}' \
+    -c "$(dirname "$log_path")" \
+    "tail -F $(printf '%q' "$log_path")" 2>/dev/null || true)
+  if [[ -n "$trace_pane" ]]; then
+    tmux select-pane -t "$trace_pane" -T "gemini-${role}-trace" 2>/dev/null || true
+    tmux last-pane 2>/dev/null || true
+  fi
 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 "$include_dirs" < "$prompt_path" 2>/dev/null
+# stdin redirect, stderr capture, and pipeline mirroring 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.
+#
+# stdout: tee'd to both the log file (for `tail -f`) AND the wrapper's own
+#         stdout (so the subagent's `BashOutput` still captures the final
+#         text verbatim for Phase 5 synthesis).
+# stderr: appended to the log file only — mirrors the prior `2>/dev/null`
+#         contract of keeping the wrapper's stderr stream clean.
+# exit:   `PIPESTATUS[0]` preserves gemini's own exit code (tee always 0).
+{
+  gemini -p - -m "$model" -o text --include-directories "$include_dirs" \
+    < "$prompt_path" 2>> "$log_path"
+} | tee -a "$log_path"
+exit "${PIPESTATUS[0]}"

package/runtime/python/okstra_ctl/render.py

@@ -1156,7 +1156,12 @@ def render_template_file(template_path: str, output_path: str, ctx: dict) -> Non
 
 def main(argv: list[str]) -> int:
     if not argv:
-        print("usage: python3 -m okstra_ctl.render <subcommand> ...", file=sys.stderr)
+        print(
+            "usage: python3 -m okstra_ctl.render <subcommand> ...\n"
+            "  (requires PYTHONPATH=$(okstra paths --field python); "
+            "normal callers go through scripts/okstra.sh instead)",
+            file=sys.stderr,
+        )
         return 2
     sub = argv[0]
     rest = argv[1:]

package/runtime/python/okstra_ctl/run.py

@@ -61,9 +61,18 @@ from .workers import normalize_workers, resolve_profile_workers
 from .workflow import compute_workflow_state
 from .worktree import provision_task_worktree
 
+# Validator regex for the approval marker.
+#
+# Tolerates a single optional backtick on either side of the approval token,
+# because the report template instructs the user to flip `[ ]` to `[x]` inside
+# a markdown code span and the report-writer worker often emits a standalone
+# marker line wrapped the same way (e.g. `- ` + backtick + `[x] Approved` +
+# backtick). Backticks carry no semantic content here — stripping them at the
+# parser level is simpler than threading a "please remove formatting" rule
+# through every authoring surface.
 APPROVED_PLAN_PATTERN = re.compile(
-    r"^[ \t]*(?:[-*+][ \t]+)?(APPROVED([ \t]|:|$)|\[x\][ \t]*Approved|"
-    r"User[ \t]+Approval[ \t]*:[ \t]*(APPROVED|granted|yes))",
+    r"^[ \t]*(?:[-*+][ \t]+)?`?(APPROVED([ \t]|:|$|`)|\[x\][ \t]*Approved`?|"
+    r"User[ \t]+Approval[ \t]*:[ \t]*(APPROVED|granted|yes)`?)",
     re.IGNORECASE | re.MULTILINE,
 )
 
@@ -127,8 +136,14 @@ def _validate_approved_plan(path: str) -> None:
 
 # `- [ ] Approved` 라인을 정확히 한 번만 매치한다. 좌측 leading whitespace 와
 # 옵션 bullet 은 보존된 채 체크박스 안쪽 공백만 `x` 로 갱신된다.
+#
+# Group 1: leading whitespace + optional bullet + optional opening backtick.
+# Group 2: optional closing backtick + trailing whitespace.
+# Both groups are preserved verbatim in the replacement so a backtick-wrapped
+# `- \`[ ] Approved\`` flips to `- \`[x] Approved\`` without losing the
+# surrounding code span — the validator regex tolerates either form.
 APPROVAL_UNCHECKED_PATTERN = re.compile(
-    r"^([ \t]*(?:[-*+][ \t]+)?)\[[ \t]\][ \t]*Approved[ \t]*$",
+    r"^([ \t]*(?:[-*+][ \t]+)?`?)\[[ \t]\][ \t]*Approved(`?[ \t]*)$",
     re.IGNORECASE | re.MULTILINE,
 )
 
@@ -162,7 +177,7 @@ def _apply_cli_approval(path: str) -> str:
 
     if APPROVAL_UNCHECKED_PATTERN.search(body):
         new_body, count = APPROVAL_UNCHECKED_PATTERN.subn(
-            lambda m: f"{m.group(1)}[x] Approved", body, count=1,
+            lambda m: f"{m.group(1)}[x] Approved{m.group(2)}", body, count=1,
         )
         new_body = new_body.rstrip("\n") + "\n" + audit_line + "\n"
         p.write_text(new_body, encoding="utf-8")

package/runtime/skills/okstra-logs/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: okstra-logs
+description: Use when the user asks about okstra worker wrapper log files — listing, sizes, ages, disk usage, or wants to know what `*.log` sidecars exist for past dispatches and which ones are safe to clean up. Trigger words include "okstra logs", "로그 현황", "로그 파일", "log files", "log size", "log status", "로그 정리", "log cleanup".
+---
+
+# OKSTRA Logs
+
+Read-only inventory of codex/gemini wrapper log files written next to each
+prompt history file (`<prompt>.log`). Reports sizes, ages, totals, and
+suggests cleanup commands. **Does not delete** — the user runs whichever
+`find … -delete` line they like.
+
+## When to Use
+
+- The user wants to see how much disk space okstra wrapper logs consume.
+- The user wants to know which tasks / phases / workers have lingering log
+  sidecars from past dispatches.
+- The user is planning a cleanup and wants ready-to-run `find` commands
+  scoped by age, task-id, or task-group.
+
+## Background
+
+Codex/gemini wrappers (`okstra-codex-exec.sh`, `okstra-gemini-exec.sh`)
+write a sidecar log next to each prompt history file:
+
+```
+.project-docs/okstra/tasks/<task-group>/<task-id>/runs/<phase>/prompts/
+  <worker>-prompt-<phase>-<seq>.md    <-- prompt (git-tracked)
+  <worker>-prompt-<phase>-<seq>.log   <-- live stdout+stderr mirror
+```
+
+The log is truncated at each dispatch (`: > "$log_path"`) — only the latest
+run for a given seq is preserved. Different seqs (`-001`, `-002`, …) keep
+separate files. Long-running implementation dispatches can produce
+multi-MB logs; analysis-phase dispatches are typically smaller.
+
+## Step 0: Verify okstra runtime + project setup
+
+```bash
+if command -v okstra >/dev/null 2>&1; then
+  OKSTRA_CMD="okstra"
+else
+  OKSTRA_CMD="npx -y okstra@latest"
+fi
+$OKSTRA_CMD ensure-installed >/dev/null 2>&1 || {
+  echo "FAIL: okstra not installed; tell the user to run: npx okstra@latest install" >&2
+  exit 1
+}
+OKSTRA_PROJECT_INFO="$($OKSTRA_CMD check-project --json)" || {
+  echo "FAIL: this project has no okstra setup. Tell the user to run /okstra-setup first." >&2
+  echo "$OKSTRA_PROJECT_INFO" >&2
+  exit 1
+}
+```
+
+Parse `projectRoot` from the JSON and use it as the search root for the
+steps below.
+
+## Step 1: Inventory
+
+Find all wrapper log files and collect metadata. Use a single `find` to
+keep the I/O cost predictable, then format the results.
+
+```bash
+PROJECT_ROOT=$(echo "$OKSTRA_PROJECT_INFO" | python3 -c 'import sys,json;print(json.load(sys.stdin)["projectRoot"])')
+LOGS_ROOT="$PROJECT_ROOT/.project-docs/okstra/tasks"
+
+# columns: size_bytes | mtime_epoch | path
+find "$LOGS_ROOT" -type f -path '*/runs/*/prompts/*.log' \
+  -printf '%s\t%T@\t%p\n' 2>/dev/null \
+  | sort -k2,2nr
+```
+
+On macOS, `find -printf` is unavailable. Fall back to `stat`:
+
+```bash
+find "$LOGS_ROOT" -type f -path '*/runs/*/prompts/*.log' 2>/dev/null \
+  | while IFS= read -r p; do
+      stat -f '%z%t%m%t%N' "$p"
+    done \
+  | sort -k2,2nr
+```
+
+If the result is empty, report `No wrapper log files found under <PROJECT_ROOT>` and exit.
+
+## Step 2: Summary table
+
+Group results and emit two tables.
+
+### Table A — Top 20 largest logs
+
+| # | Task | Phase | Worker | Seq | Size | Age | Path |
+|---|------|-------|--------|-----|------|-----|------|
+
+Parse fields from the path:
+- task-group / task-id: from the `tasks/<task-group>/<task-id>/` segment
+- phase: from `runs/<phase>/`
+- worker: from filename prefix before `-prompt-`
+- seq: from filename suffix (last 3-digit segment)
+
+Format sizes as human-readable (KB / MB). Format age as `Nd` (days) or
+`Nh` (hours) from `mtime` relative to "now".
+
+### Table B — Per-task totals
+
+| Task Key | Files | Total Size | Oldest | Newest |
+|----------|-------|-----------:|--------|--------|
+
+Sort by total size descending. "Task Key" = `<project-id>:<task-group>:<task-id>` for consistency with other okstra skills.
+
+### Footer line
+
+```
+Total: N files, X.X MB across M tasks under <PROJECT_ROOT>
+```
+
+## Step 3: Suggested cleanup commands
+
+Emit a fenced bash block the user can copy-paste. Do NOT execute these.
+
+```markdown
+## Cleanup options (manual)
+
+# 7일 이상 된 로그만 삭제
+find <PROJECT_ROOT>/.project-docs/okstra/tasks \
+  -type f -path '*/runs/*/prompts/*.log' -mtime +7 -delete
+
+# 30일 이상 된 로그만 삭제
+find <PROJECT_ROOT>/.project-docs/okstra/tasks \
+  -type f -path '*/runs/*/prompts/*.log' -mtime +30 -delete
+
+# 특정 task-group 의 로그 일괄 삭제 (예: dev-9388)
+find <PROJECT_ROOT>/.project-docs/okstra/tasks/dev-9388 \
+  -type f -name '*.log' -delete
+
+# 특정 task-id 의 로그 일괄 삭제 (예: dev-9428)
+find <PROJECT_ROOT>/.project-docs/okstra/tasks/*/dev-9428 \
+  -type f -name '*.log' -delete
+
+# 전체 일괄 삭제 (주의)
+find <PROJECT_ROOT>/.project-docs/okstra/tasks \
+  -type f -path '*/runs/*/prompts/*.log' -delete
+```
+
+Substitute the literal `<PROJECT_ROOT>` with the resolved absolute path so
+the commands are directly copy-pasteable.
+
+## Step 4: Notes for the user
+
+End the response with these short reminders:
+
+- Logs are truncated on each re-dispatch of the same `seq`, so deleting an
+  in-flight run's log will cause the wrapper to recreate an empty file on
+  the next dispatch — no data loss beyond the current trace.
+- Prompt history files (`.md`) are separate and are NOT touched by these
+  commands — only `.log` sidecars.
+- This skill does not modify `.gitignore`. If the project commits
+  `.project-docs/okstra/`, the user may want to add
+  `.project-docs/okstra/tasks/**/runs/**/prompts/*.log` to `.gitignore`
+  manually to keep large logs out of git.
+
+## What this skill is NOT
+
+- Does NOT delete log files. Only inventories and suggests commands.
+- Does NOT touch prompt history files (`.md`), worker results, manifests,
+  or any other okstra state.
+- Does NOT run on a schedule. Invoke explicitly when needed.

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

@@ -295,7 +295,7 @@ empty run-level error logs in production.
 
 - `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:
+- **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)` until the shell reports `status == "completed"`, capped at 30 minutes (1800s) of wall-clock elapsed time. `BashOutput` itself is the wait primitive — call it back-to-back; do NOT insert a standalone `sleep` between polls. The Claude Code harness blocks `sleep` calls of 5 seconds or longer as a circumvention vector and explicitly forbids chaining shorter sleeps inside until-loops to work around the block. Workers that hit the contract bug must NOT self-recover with `until ...; do sleep 2; done` wrappers — that path violates the harness anti-circumvention rule, even though it superficially "works". The legacy "single foreground `Bash` with 120000ms timeout" rule, and the subsequent "60-second cadence with `sleep 60` between polls" rule, are both retired. The current rule applies in **every phase** (analysis runs typically complete in 1–2 `BashOutput` calls, 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.