okstra 0.32.1 → 0.34.0

package/docs/kr/architecture.md

@@ -880,7 +880,7 @@ Phase 7 step 1.5 가 final-report MD 한 본을 입력으로 두 view 를 결정
 ### Live-log mirror (codex / gemini wrapper)
 
 - `scripts/okstra-codex-exec.sh`, `scripts/okstra-gemini-exec.sh` 는 dispatch 마다 prompt path 옆에 `<prompt>.log` sidecar 를 만들고 stdout 을 거기로 mirror 합니다 (`tee`, `PIPESTATUS[0]` 로 종료코드 보존). stderr 은 같은 파일에 append (subagent stderr 캡처 contract 보존), 매 dispatch 시 truncate. 호출 subagent 의 `BashOutput` 폴링은 60s 간격이라 long-running run (analysis 의 large-codebase scan, implementation 의 cargo / pytest) 동안 사용자가 stalled state 를 탐지할 수 없는 문제를 해소합니다.
-- `$TMUX` 가 셋팅된 lead 환경이면 wrapper 가 sibling pane 을 자동 분할해 `tail -F <log-path>` 를 띄웁니다. pane title 은 `<cli>-<role>-trace` (e.g. `codex-worker-trace`, `gemini-worker-trace`); role 은 wrapper 의 5번째 optional positional 인자이며, 누락 시 기본값 `worker` 로 떨어집니다. caller 가 다른 라벨(예: `executor`)을 원하면 5번째 인자로 명시해야 합니다. focus 는 caller pane 으로 복귀하고, CLI 종료 후 pane 은 유지돼 스크롤백 가능. `$TMUX` 미설정, split 실패, 구버전 tmux 등 모든 경로는 silent degrade.
+- `$TMUX` 가 셋팅된 lead 환경이면 wrapper 가 sibling pane 을 자동 분할해 `tail -F <log-path>` 를 띄웁니다. trace pane title 은 `<cli>-<role>-<pid>-trace` (e.g. `codex-worker-93421-trace`, `gemini-executor-93422-trace`); 동일 시점에 caller (worker) pane title 도 `<cli>-<role>-<pid>` 로 셋팅돼 worker ↔ trace 쌍을 한 눈에 매칭할 수 있습니다. `<pid>` 는 wrapper 자기 자신의 PID 라서 동일 role 의 worker 가 둘 이상 동시에 spawn 돼도 서로 구분됩니다. role 은 wrapper 의 5번째 optional positional 인자이며, 누락 시 기본값 `worker` 로 떨어집니다. caller 가 다른 라벨(예: `executor`)을 원하면 5번째 인자로 명시해야 합니다. wrapper 진입 직전의 caller pane title 은 capture 해두고 EXIT trap 에서 복원하므로, dispatch 사이의 stale title 이 남지 않습니다. focus 는 caller pane 으로 복귀하고, CLI 종료 후 pane 은 유지돼 스크롤백 가능. `$TMUX` 미설정, split 실패, 구버전 tmux 등 모든 경로는 silent degrade.
 - **Claude `/exit` 시 자동 정리**: trace pane 의 `tail -F` 는 tmux 셸의 자식이라 Claude 가 종료돼도 살아남는 문제를 막기 위해, wrapper 는 spawn 한 pane id 를 caller `$TMUX_PANE` 으로 키된 registry (`${TMPDIR:-/tmp}/okstra-trace-panes/<caller-pane>.list`) 에 append 합니다. `templates/reports/settings.template.json` 의 `hooks.SessionEnd` 가 `$HOME/.okstra/bin/okstra-trace-cleanup.sh` 를 호출해 자신의 caller pane registry 만 읽어 `tmux kill-pane` 합니다. caller pane 단위로 scope 가 잡혀 있어 같은 tmux 세션에 Claude 인스턴스가 여러 개 떠 있어도 서로의 trace pane 을 죽이지 않습니다. tmux 가 없거나 stale pane id 인 경우 silent degrade.
 - **Phase 종료 시 사용자 확인**: 매 phase 의 마지막 단계로 lead 가 `okstra-trace-cleanup.sh --list` 로 등록된 pane 목록을 출력한 뒤 사용자에게 "모두 닫기 / 그대로 두기" 양자택일을 묻고 응답대로 처리합니다 (`prompts/profiles/_common-contract.md` 의 *Phase wrap-up* 항목). `$TMUX_PANE` 미설정 환경에서는 단계 자체가 silent-skip. `--list` 모드는 pane 을 죽이지 않고 `<pane_id>\t<pane_title>` 만 출력하므로 사용자가 무엇이 닫힐지 시각적으로 확인할 수 있습니다.
 - 디스크 누적은 `okstra-logs` skill 이 read-only 로 인벤토리 + cleanup 명령을 제안합니다 (실행은 사용자 copy-paste).

package/docs/kr/cli.md

@@ -546,5 +546,5 @@ chmod +x ~/.local/bin/okstra-ctl
 
 ### Live-log sidecar
 
-codex / gemini wrapper 는 매 dispatch 마다 `runs/<task-type>/prompts/<worker>-prompt-<phase>-<seq>.log` sidecar 를 만들고 stdout / stderr 를 mirror 합니다. tmux 안에서 lead 를 띄우면 wrapper 가 자동으로 `tail -F` pane 을 분할합니다 (title: `<cli>-<role>-trace`). 분할된 trace pane 은 caller `$TMUX_PANE` 으로 키된 registry 에 등록돼, Claude `/exit` 시 `SessionEnd` 훅이 `okstra-trace-cleanup.sh` 로 자동 정리합니다. 사용량 인벤토리와 `find … -delete` cleanup 명령은 `okstra-logs` skill 이 read-only 로 제안합니다. 자세한 와이어링은 [`docs/kr/architecture.md`](architecture.md) 의 *Live-log mirror* 절 참고.
+codex / gemini wrapper 는 매 dispatch 마다 `runs/<task-type>/prompts/<worker>-prompt-<phase>-<seq>.log` sidecar 를 만들고 stdout / stderr 를 mirror 합니다. tmux 안에서 lead 를 띄우면 wrapper 가 자동으로 `tail -F` pane 을 분할합니다 (trace pane title: `<cli>-<role>-<pid>-trace`, caller (worker) pane title: `<cli>-<role>-<pid>` — wrapper PID 가 동일 role 의 동시 dispatch 를 구분합니다). 분할된 trace pane 은 caller `$TMUX_PANE` 으로 키된 registry 에 등록돼, Claude `/exit` 시 `SessionEnd` 훅이 `okstra-trace-cleanup.sh` 로 자동 정리합니다. 사용량 인벤토리와 `find … -delete` cleanup 명령은 `okstra-logs` skill 이 read-only 로 제안합니다. 자세한 와이어링은 [`docs/kr/architecture.md`](architecture.md) 의 *Live-log mirror* 절 참고.
 

package/package.json

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

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.32.1",
-  "builtAt": "2026-05-19T14:15:13.766Z",
+  "package": "0.34.0",
+  "builtAt": "2026-05-19T16:31:42.883Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/SKILL.md

@@ -82,6 +82,27 @@ User-utterance interpretation rule:
 - If the current phase's outputs are already complete and the user clearly wants to advance, reply with the phase-transition checklist above and the exact next-run command. Wait for explicit user confirmation before any action that belongs to the next phase.
 - If `nextRecommendedPhase` is `implementation-planning`, the next run produces a **plan**, not code. The next run after that is `implementation`.
 
+## Progress reporting (BLOCKING)
+
+A single okstra run frequently spans 30–120 minutes of wall-clock time with multi-minute silent windows while workers run. Without explicit progress signals the user cannot distinguish "still working" from "hung", so Lead MUST emit a single short progress line at each of the checkpoints below — as plain user-facing text in a separate brief message (not buried inside a tool call). One line per checkpoint, format: `PROGRESS: <phase-id> <verb-phrase>`.
+
+Required checkpoints:
+
+- `PROGRESS: phase-1-intake reading task bundle` — at the start of Phase 1, before issuing parallel Read calls.
+- `PROGRESS: phase-1-intake complete` — after all intake reads return.
+- `PROGRESS: phase-2-prompts preparing <N> worker prompts` — at the start of Phase 2, before any `Write` to the assigned prompt paths.
+- `PROGRESS: phase-3-team-create attempting TeamCreate` — immediately before the `TeamCreate` call.
+- `PROGRESS: phase-4-dispatch worker=<role> model=<model>` — once per worker, immediately before the `Agent` / wrapper call.
+- `PROGRESS: phase-5-collect worker=<role> status=<terminal-status>` — once per worker, immediately after the result file is verified.
+- `PROGRESS: phase-5.5-convergence round=<N> queue=<count>` — at the start of each convergence round (Phase 5.5).
+- `PROGRESS: phase-6-synthesis dispatching report-writer-worker` — at the start of Phase 6.
+- `PROGRESS: phase-7-persist updating manifests` — at the start of Phase 7.
+- `PROGRESS: complete final-report=<relative-path>` — final summary line, after all persistence.
+
+These lines are the only structured signal the user has during a long run. Do NOT replace them with prose ("Now I'm starting Phase 2..."), do NOT skip a checkpoint because "the previous message already said that", and do NOT batch multiple checkpoints into one. Each line stands alone so the user (or any operator scraping stdout) can timestamp it externally.
+
+`okstra-run` (in-session) surfaces these lines to the user directly; the bash-spawned path leaves them in the session jsonl for post-hoc retrieval. Neither path requires any additional formatting from Lead — emit the literal `PROGRESS:` prefix and the rest of the line as plain text.
+
 ## Default model assignments
 
 Unless the task bundle overrides:
@@ -316,6 +337,7 @@ After persistence, reply briefly in Korean with: completion status, final report
 | Letting `convergence.maxRounds` default to 2 for `requirements-discovery` | Resolve effective default to `1` for discovery and record in convergence state artifact |
 | Issuing serial Read calls in Phase 1 | The intake files are independent — issue all Read calls in a single message (parallel) |
 | Flagging the claude-worker dispatch prompt as "incomplete" because it lacks `[Required reading]` / `[Error reporting]` blocks | Intentional asymmetry — see [okstra-team-contract](./skills/okstra-team-contract/SKILL.md) "Asymmetry between claude-worker and codex/gemini-worker prompts" |
+| Waiting silently while the dispatched `claude-worker` Agent call returns nothing for many minutes (the dev-9495 pattern: two 28+25-minute hangs before lead manually `tmux kill-pane`d) | The claude-worker MUST append a `- PROGRESS: <stage> <ISO-UTC>` line to its audit sidecar (`runs/<task-type>/worker-results/claude-worker-audit-<task-type>-<seq>.md`) at least every 5 minutes (see `agents/workers/claude-worker.md` "Heartbeat" rule). If the sidecar is absent or its mtime is >5 minutes stale, treat the dispatch as `timeout` and redispatch once with a byte-identical prompt; after a second silent hang, record terminal status `timeout` with the missing-sidecar reason in team-state. Lead cannot poll mid-Agent-call but MUST inspect the audit sidecar immediately when the Agent call finally returns — a missing sidecar after `completed` is itself a contract violation per the heartbeat rule |
 | Re-sending confirmed findings (`full-consensus`/`partial-consensus`/`worker-unique`) to a worker in Round 2 | Queue pruning rule — see [okstra-convergence](./skills/okstra-convergence/SKILL.md) "Round 1-N: Re-verification Loop (queue-pruned)" |
 | Aggregating a `timeout`/`error` reverify dispatch as `DISAGREE` | Worker failure handling — record as `verification-error` and add to `skippedWorkers[]`. See [okstra-convergence](./skills/okstra-convergence/SKILL.md) "Worker failure handling in reverify" |
 | Skipping `--substitute-data` in the Phase 7 collector run | Always pass the flag — see [okstra-report-writer](./skills/okstra-report-writer/SKILL.md) "Phase 7 token-usage collector" |

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

@@ -59,6 +59,7 @@ Before producing any output, you MUST read every input file enumerated in the `[
 - Use a single `Read` call per file with no `offset` and no `limit`. If a file is genuinely too large for one read, page through it with explicit `offset` / `limit` calls that together cover the entire file, and record the page boundaries in your Findings.
 - For the carry-in clarification response, walk every row of `## 5. Clarification Items` (`C-001`, `C-002`, ...) in full, including rows whose `User input` cell is blank — a blank `User input` with `Status=open` is itself a signal you must surface, not skip. Skimming these rows is the most common failure mode here; the fact that the file you will eventually contribute to has a structurally similar section 5 is NOT a license to skim.
 - Before listing any Findings, write a Reading Confirmation block to your **audit sidecar** at `runs/<task-type>/worker-results/claude-worker-audit-<task-type>-<seq>.md` (sibling to your main worker-results file — substitute `claude-worker-<task-type>-<seq>.md` → `claude-worker-audit-<task-type>-<seq>.md`). The sidecar's body begins with `# Claude Worker Audit — <task-key>` followed by one short line per input file confirming end-to-end reading (e.g. `- Read task-brief.md end-to-end (147 lines).`). Do NOT include a `## 0. Reading Confirmation` heading in the main worker-results file — the validator now fails worker-results that contain one. If you cannot truthfully confirm a file end-to-end, record a `tool-failure` in the errors sidecar instead of fabricating Findings.
+- **Heartbeat — write the audit sidecar EARLY and APPEND per stage (BLOCKING).** Because this worker runs as an in-process Agent or a fresh-session tmux pane, the lead has no `BashOutput`-style liveness signal while waiting for your return. The audit sidecar is the only signal that survives a silent hang. Write the sidecar immediately after extracting `Project Root` and the assigned paths — BEFORE the per-file end-to-end reads — with just the heading line (`# Claude Worker Audit — <task-key>`) and one `- PROGRESS: started <ISO-8601-UTC>` line. Then APPEND one short progress line per stage as you advance: `read-<filename>`, `analysis-start`, `findings-draft-start`, `findings-draft-complete`, `write-result-start`. Each line: `- PROGRESS: <stage> <ISO-8601-UTC>`. The append cadence MUST NOT exceed 5 minutes — if a single analysis stage is taking longer, emit a `- PROGRESS: in-stage:<stage> <ISO-8601-UTC>` heartbeat. A 5-minute stale sidecar mtime is the canonical "this worker has hung" signal for the operator (the lead is blocked on the Agent call and cannot detect this itself, but a human watching via `tail -F <audit-sidecar>` from another terminal can). Sidecar write/append uses `Write` (for the initial creation) and `Edit` / heredoc `>>` for the per-stage append — heredoc append is the lighter option once the file exists.
 - Do not skip a file because its name suggests its content is already familiar from a prior run. Each file is canonical for the current run only.
 
 ## Worker Output Structure

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

@@ -30,7 +30,7 @@ You are a Codex worker agent. Your job is to execute the OpenAI Codex CLI and re
 $HOME/.okstra/bin/okstra-codex-exec.sh "<absolute-project-root>" "<assigned-model-execution-value>" "<absolute-prompt-history-path>" [<absolute-worktree-path>] [<role>]
 ```
 
-The fifth argument `<role>` is the trace-pane label suffix (`codex-<role>-trace`); pass the literal string `worker` for every dispatch from this subagent. The wrapper defaults to `worker` when the argument is omitted, but pass it explicitly so the dispatch is self-describing.
+The fifth argument `<role>` is folded into both the caller (worker) pane title `codex-<role>-<pid>` and the sibling trace-pane title `codex-<role>-<pid>-trace` (`<pid>` = the wrapper's PID, present so concurrent dispatches of the same role can be told apart). Pass the literal string `worker` for every dispatch from this subagent. The wrapper defaults to `worker` when the argument is omitted, but pass it explicitly so the dispatch is self-describing.
 
 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.
 

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

@@ -30,7 +30,7 @@ You are a Gemini worker agent. Your job is to execute the Google Gemini CLI and
 $HOME/.okstra/bin/okstra-gemini-exec.sh "<absolute-project-root>" "<assigned-model-execution-value>" "<absolute-prompt-history-path>" [<absolute-worktree-path>] [<role>]
 ```
 
-The fifth argument `<role>` is the trace-pane label suffix (`gemini-<role>-trace`); pass the literal string `worker` for every dispatch from this subagent. The wrapper defaults to `worker` when the argument is omitted, but pass it explicitly so the dispatch is self-describing.
+The fifth argument `<role>` is folded into both the caller (worker) pane title `gemini-<role>-<pid>` and the sibling trace-pane title `gemini-<role>-<pid>-trace` (`<pid>` = the wrapper's PID, present so concurrent dispatches of the same role can be told apart). Pass the literal string `worker` for every dispatch from this subagent. The wrapper defaults to `worker` when the argument is omitted, but pass it explicitly so the dispatch is self-describing.
 
 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.
 

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

@@ -13,10 +13,21 @@
 #   Bash($HOME/.okstra/bin/okstra-codex-exec.sh:*)
 #
 # Usage:
-#   okstra-codex-exec.sh <project-root> <model-execution-value> <prompt-path> [worktree-path] [role]
+#   okstra-codex-exec.sh <project-root> <model-execution-value> <prompt-path> [worktree-path] [role] [idle-timeout-seconds]
 #
 # project-root / model-execution-value / prompt-path are required.
 #
+# idle-timeout-seconds is optional (default 600 = 10 minutes). When > 0, an
+# in-process watchdog polls the live-log mtime; if no stdout/stderr write
+# occurs for that many seconds, the underlying `codex exec` is SIGTERM'd
+# (then SIGKILL'd after a 5-second grace), the status sidecar gets a
+# `{timeout: true, idle_seconds, idle_at_ts, terminated_by: "idle-watchdog"}`
+# marker, and the wrapper exits non-zero. Pass `0` to disable. Default
+# exists because silent worker hangs are the dominant lead-time waste —
+# observed 28+25 minutes on hung claude-worker dispatches before manual
+# kill; a 10-minute cap costs ≤10m per hang while leaving long but live
+# runs untouched.
+#
 # 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
@@ -56,8 +67,8 @@
 # The wrapper exits non-zero on any preflight failure.
 set -euo pipefail
 
-if [[ $# -lt 3 || $# -gt 5 ]]; then
-  printf 'usage: %s <project-root> <model-execution-value> <prompt-path> [worktree-path] [role]\n' "$(basename "$0")" >&2
+if [[ $# -lt 3 || $# -gt 6 ]]; then
+  printf 'usage: %s <project-root> <model-execution-value> <prompt-path> [worktree-path] [role] [idle-timeout-seconds]\n' "$(basename "$0")" >&2
   exit 64
 fi
 
@@ -66,6 +77,12 @@ model="$2"
 prompt_path="$3"
 worktree_path="${4-}"
 role="${5:-worker}"
+idle_timeout_secs="${6:-600}"
+
+if ! [[ "$idle_timeout_secs" =~ ^[0-9]+$ ]]; then
+  printf 'okstra-codex-exec: idle-timeout-seconds must be a non-negative integer: %q\n' "$idle_timeout_secs" >&2
+  exit 69
+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
@@ -170,6 +187,21 @@ python3 "$script_dir/okstra-wrapper-status.py" \
   init "$status_path" "$(basename "$0")" "$role" "$$" "$started_ts" "$log_path" \
   >>"$log_path" 2>&1 || true
 
+# Pane titles: worker (caller) pane gets `codex-<role>-<pid>`; the sibling
+# trace pane appends `-trace`. The wrapper PID disambiguates concurrent
+# dispatches of the same role (e.g. two `codex-worker` panes spawned in
+# parallel) so the operator can match worker ↔ trace at a glance.
+pane_label="codex-${role}-$$"
+trace_label="${pane_label}-trace"
+
+# Capture the caller pane's current title so the EXIT trap can restore it
+# once the wrapper returns. Empty when not in tmux or capture fails — the
+# restore step degrades to a no-op in that case.
+original_caller_title=""
+if [[ -n "${TMUX_PANE:-}" ]]; then
+  original_caller_title=$(tmux display-message -p -t "$TMUX_PANE" '#{pane_title}' 2>/dev/null || true)
+fi
+
 _okstra_status_finish() {
   local exit_code=$?
   local ended_ts
@@ -178,17 +210,29 @@ _okstra_status_finish() {
   python3 "$script_dir/okstra-wrapper-status.py" \
     finish "$status_path" "$exit_code" "$ended_ts" "$duration_ms" \
     >>"$log_path" 2>&1 || true
+  if [[ -n "${TMUX_PANE:-}" && -n "$original_caller_title" ]]; then
+    tmux select-pane -t "$TMUX_PANE" -T "$original_caller_title" 2>/dev/null || true
+  fi
 }
 trap _okstra_status_finish EXIT
 
+# Label the caller (worker) pane now that the restore trap is armed. Any
+# failure after this point still rewinds the title to its prior value.
+if [[ -n "${TMUX_PANE:-}" ]]; then
+  tmux select-pane -t "$TMUX_PANE" -T "$pane_label" 2>/dev/null || true
+fi
+
 # 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` — `role` is the optional
-# 5th positional arg (defaults to `worker`); callers that dispatch a
-# different role (e.g. `executor`) must pass it explicitly. The pane uses
+# new pane carries the title `codex-<role>-<pid>-trace` (matching the
+# caller pane's `codex-<role>-<pid>` label so worker ↔ trace pairs are
+# greppable); `role` is the optional 5th positional arg (defaults to
+# `worker`); callers that dispatch a different role (e.g. `executor`) must
+# pass it explicitly. The `<pid>` suffix is the wrapper's PID and
+# disambiguates concurrent dispatches of the same role. The pane 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
@@ -201,7 +245,7 @@ if [[ -n "${TMUX:-}" ]]; then
     -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 select-pane -t "$trace_pane" -T "$trace_label" 2>/dev/null || true
     tmux last-pane 2>/dev/null || true
     # Register the spawned pane so the `SessionEnd` hook (see
     # `okstra-trace-cleanup.sh`) can kill it when the caller's Claude
@@ -220,14 +264,64 @@ 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: tee'd to both the live log (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`
+#         text verbatim for Phase 5 synthesis). Implemented via process
+#         substitution so codex itself stays a single addressable PID we
+#         can SIGTERM from the watchdog.
+# stderr: appended to the live log 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]}"
+# exit:   codex's own exit code is preserved by `wait`.
+codex exec -C "$project_root" ${extra_args[@]+"${extra_args[@]}"} --model "$model" --sandbox workspace-write - \
+  < "$prompt_path" \
+  2>> "$log_path" \
+  > >(tee -a "$log_path") &
+codex_pid=$!
+
+# Idle watchdog: poll the live log's mtime; if no write (stdout or stderr)
+# arrives for $idle_timeout_secs, SIGTERM codex, give it a 5-second grace,
+# then SIGKILL. Record the termination cause in the status sidecar so the
+# caller (lead) can distinguish "ran to completion with non-zero exit" from
+# "killed because it went silent". Set 0 to disable entirely.
+watchdog_pid=""
+if (( idle_timeout_secs > 0 )); then
+  poll_interval=$(( idle_timeout_secs / 20 ))
+  (( poll_interval < 5 )) && poll_interval=5
+  (( poll_interval > 30 )) && poll_interval=30
+  (
+    while kill -0 "$codex_pid" 2>/dev/null; do
+      sleep "$poll_interval"
+      kill -0 "$codex_pid" 2>/dev/null || exit 0
+      last_mtime=$(stat -f %m "$log_path" 2>/dev/null || stat -c %Y "$log_path" 2>/dev/null || printf '0')
+      now=$(date +%s)
+      idle=$(( now - last_mtime ))
+      if (( idle >= idle_timeout_secs )); then
+        printf '\n[okstra wrapper] idle-watchdog: %ds without stdout — terminating codex (pid=%d)\n' \
+          "$idle" "$codex_pid" >> "$log_path" 2>&1 || true
+        python3 "$script_dir/okstra-wrapper-status.py" \
+          timeout "$status_path" "$now" "$idle" >>"$log_path" 2>&1 || true
+        kill -TERM "$codex_pid" 2>/dev/null || true
+        sleep 5
+        kill -KILL "$codex_pid" 2>/dev/null || true
+        exit 0
+      fi
+    done
+  ) &
+  watchdog_pid=$!
+fi
+
+set +e
+wait "$codex_pid"
+codex_exit=$?
+set -e
+
+if [[ -n "$watchdog_pid" ]]; then
+  kill "$watchdog_pid" 2>/dev/null || true
+  wait "$watchdog_pid" 2>/dev/null || true
+fi
+
+# Drain the process-substitution tee so the final lines reach the live log
+# and the caller's stdout before exit.
+wait 2>/dev/null || true
+
+exit "$codex_exit"

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

@@ -13,10 +13,19 @@
 #   Bash($HOME/.okstra/bin/okstra-gemini-exec.sh:*)
 #
 # Usage:
-#   okstra-gemini-exec.sh <project-root> <model-execution-value> <prompt-path> [worktree-path] [role]
+#   okstra-gemini-exec.sh <project-root> <model-execution-value> <prompt-path> [worktree-path] [role] [idle-timeout-seconds]
 #
 # project-root / model-execution-value / prompt-path are required.
 #
+# idle-timeout-seconds is optional (default 600 = 10 minutes). When > 0, an
+# in-process watchdog polls the live-log mtime; if no stdout/stderr write
+# occurs for that many seconds, the underlying `gemini` is SIGTERM'd (then
+# SIGKILL'd after a 5-second grace), the status sidecar gets a
+# `{timeout: true, idle_seconds, idle_at_ts, terminated_by: "idle-watchdog"}`
+# marker, and the wrapper exits non-zero. Pass `0` to disable. Kept in
+# lock-step with `okstra-codex-exec.sh` — see that wrapper for the full
+# design rationale.
+#
 # 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
@@ -36,8 +45,8 @@
 # The wrapper exits non-zero on any preflight failure.
 set -euo pipefail
 
-if [[ $# -lt 3 || $# -gt 5 ]]; then
-  printf 'usage: %s <project-root> <model-execution-value> <prompt-path> [worktree-path] [role]\n' "$(basename "$0")" >&2
+if [[ $# -lt 3 || $# -gt 6 ]]; then
+  printf 'usage: %s <project-root> <model-execution-value> <prompt-path> [worktree-path] [role] [idle-timeout-seconds]\n' "$(basename "$0")" >&2
   exit 64
 fi
 
@@ -46,6 +55,12 @@ model="$2"
 prompt_path="$3"
 worktree_path="${4-}"
 role="${5:-worker}"
+idle_timeout_secs="${6:-600}"
+
+if ! [[ "$idle_timeout_secs" =~ ^[0-9]+$ ]]; then
+  printf 'okstra-gemini-exec: idle-timeout-seconds must be a non-negative integer: %q\n' "$idle_timeout_secs" >&2
+  exit 69
+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
@@ -121,6 +136,21 @@ python3 "$script_dir/okstra-wrapper-status.py" \
   init "$status_path" "$(basename "$0")" "$role" "$$" "$started_ts" "$log_path" \
   >>"$log_path" 2>&1 || true
 
+# Pane titles: worker (caller) pane gets `gemini-<role>-<pid>`; the sibling
+# trace pane appends `-trace`. The wrapper PID disambiguates concurrent
+# dispatches of the same role (e.g. two `gemini-worker` panes spawned in
+# parallel) so the operator can match worker ↔ trace at a glance.
+pane_label="gemini-${role}-$$"
+trace_label="${pane_label}-trace"
+
+# Capture the caller pane's current title so the EXIT trap can restore it
+# once the wrapper returns. Empty when not in tmux or capture fails — the
+# restore step degrades to a no-op in that case.
+original_caller_title=""
+if [[ -n "${TMUX_PANE:-}" ]]; then
+  original_caller_title=$(tmux display-message -p -t "$TMUX_PANE" '#{pane_title}' 2>/dev/null || true)
+fi
+
 _okstra_status_finish() {
   local exit_code=$?
   local ended_ts
@@ -129,23 +159,34 @@ _okstra_status_finish() {
   python3 "$script_dir/okstra-wrapper-status.py" \
     finish "$status_path" "$exit_code" "$ended_ts" "$duration_ms" \
     >>"$log_path" 2>&1 || true
+  if [[ -n "${TMUX_PANE:-}" && -n "$original_caller_title" ]]; then
+    tmux select-pane -t "$TMUX_PANE" -T "$original_caller_title" 2>/dev/null || true
+  fi
 }
 trap _okstra_status_finish EXIT
 
+# Label the caller (worker) pane now that the restore trap is armed. Any
+# failure after this point still rewinds the title to its prior value.
+if [[ -n "${TMUX_PANE:-}" ]]; then
+  tmux select-pane -t "$TMUX_PANE" -T "$pane_label" 2>/dev/null || true
+fi
+
 # 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` — `role` is the
-# optional 5th positional arg (defaults to `worker`); callers that
-# dispatch a different role must pass it explicitly. See the codex
-# wrapper for the full design rationale and the silent-degrade failure
-# model.
+# implementation-specific. Title `gemini-<role>-<pid>-trace` (matching the
+# caller pane's `gemini-<role>-<pid>` label so worker ↔ trace pairs are
+# greppable). `role` is the optional 5th positional arg (defaults to
+# `worker`); callers that dispatch a different role must pass it
+# explicitly. The `<pid>` suffix is the wrapper's PID and disambiguates
+# concurrent dispatches of the same role. 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 select-pane -t "$trace_pane" -T "$trace_label" 2>/dev/null || true
     tmux last-pane 2>/dev/null || true
     # See `okstra-codex-exec.sh` for the registry rationale — kept in lock-step.
     if [[ -n "${TMUX_PANE:-}" ]]; then
@@ -163,14 +204,58 @@ fi
 # `--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: tee'd to both the live log (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`
+#         text verbatim for Phase 5 synthesis). Implemented via process
+#         substitution so gemini itself stays a single addressable PID we
+#         can SIGTERM from the watchdog.
+# stderr: appended to the live log 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]}"
+# exit:   gemini's own exit code is preserved by `wait`.
+gemini -p - -m "$model" -o text --include-directories "$include_dirs" \
+  < "$prompt_path" \
+  2>> "$log_path" \
+  > >(tee -a "$log_path") &
+gemini_pid=$!
+
+# Idle watchdog — see `okstra-codex-exec.sh` for the full rationale.
+watchdog_pid=""
+if (( idle_timeout_secs > 0 )); then
+  poll_interval=$(( idle_timeout_secs / 20 ))
+  (( poll_interval < 5 )) && poll_interval=5
+  (( poll_interval > 30 )) && poll_interval=30
+  (
+    while kill -0 "$gemini_pid" 2>/dev/null; do
+      sleep "$poll_interval"
+      kill -0 "$gemini_pid" 2>/dev/null || exit 0
+      last_mtime=$(stat -f %m "$log_path" 2>/dev/null || stat -c %Y "$log_path" 2>/dev/null || printf '0')
+      now=$(date +%s)
+      idle=$(( now - last_mtime ))
+      if (( idle >= idle_timeout_secs )); then
+        printf '\n[okstra wrapper] idle-watchdog: %ds without stdout — terminating gemini (pid=%d)\n' \
+          "$idle" "$gemini_pid" >> "$log_path" 2>&1 || true
+        python3 "$script_dir/okstra-wrapper-status.py" \
+          timeout "$status_path" "$now" "$idle" >>"$log_path" 2>&1 || true
+        kill -TERM "$gemini_pid" 2>/dev/null || true
+        sleep 5
+        kill -KILL "$gemini_pid" 2>/dev/null || true
+        exit 0
+      fi
+    done
+  ) &
+  watchdog_pid=$!
+fi
+
+set +e
+wait "$gemini_pid"
+gemini_exit=$?
+set -e
+
+if [[ -n "$watchdog_pid" ]]; then
+  kill "$watchdog_pid" 2>/dev/null || true
+  wait "$watchdog_pid" 2>/dev/null || true
+fi
+
+wait 2>/dev/null || true
+
+exit "$gemini_exit"

package/runtime/prompts/launch.template.md

@@ -3,6 +3,10 @@
 You are `Claude lead` for project `{{PROJECT_ID}}`.
 Invoke the `okstra` skill now. Read the manifests below for all task metadata, paths, model assignments, and worker roster.
 
+## Progress reporting (BLOCKING)
+
+Emit one `PROGRESS: <phase-id> <verb-phrase>` line as plain user-facing text at every checkpoint enumerated in `agents/SKILL.md` "Progress reporting (BLOCKING)" — phase-1-intake start/complete, phase-2-prompts, phase-3-team-create, phase-4-dispatch (per worker), phase-5-collect (per worker), phase-5.5-convergence (per round), phase-6-synthesis, phase-7-persist, and final `complete`. One line per checkpoint, never batched, never replaced with prose. This is the only signal the user has during multi-minute silent windows.
+
 ## Current Phase Boundary
 
 - Current lifecycle phase: `{{WORKFLOW_CURRENT_PHASE}}`

package/runtime/prompts/profiles/_common-contract.md

@@ -26,7 +26,7 @@ profile document.
 - Anti-escalation rule (shared):
   - treating "다음 단계 진행해" or equivalent user phrases as authorisation to start a *different* lifecycle phase is forbidden. The next phase begins only in a separate okstra run launched with the new `--task-type`. Per-profile documents may further restrict this within their own scope.
 - Phase wrap-up — worker trace pane disposition (shared, MUST be the *last* step before returning control to the user):
-  - Codex / Gemini worker wrappers spawn `tail -F` trace panes in the lead's tmux session (`codex-<role>-trace`, `gemini-<role>-trace`). They survive every worker invocation by design so the operator can scroll back through the final output, but accumulate across phases and clutter the screen.
+  - Codex / Gemini worker wrappers spawn `tail -F` trace panes in the lead's tmux session, titled `<cli>-<role>-<pid>-trace` (e.g. `codex-worker-93421-trace`, `gemini-executor-93422-trace`) — the matching caller (worker) pane is titled `<cli>-<role>-<pid>` so worker ↔ trace pairs can be matched by the shared `<pid>` suffix. They survive every worker invocation by design so the operator can scroll back through the final output, but accumulate across phases and clutter the screen.
   - When `$TMUX_PANE` is set, after the final-report file has been written and the routing recommendation has been issued, the lead MUST run `$HOME/.okstra/bin/okstra-trace-cleanup.sh --list` exactly once. The output is a tab-separated `<pane_id>\t<pane_title>` list of every trace pane registered for this Claude session.
   - If the list is empty, skip the question — there is nothing to ask about.
   - Otherwise the lead MUST present the user with a strict binary choice **before** declaring the phase complete. Use one prompt of this shape (Korean preferred, English acceptable if the rest of the run is in English):