okstra 0.32.1 → 0.33.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.33.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.33.0",
+  "builtAt": "2026-05-19T16:04:42.528Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

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

@@ -170,6 +170,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 +193,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 +228,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

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

@@ -121,6 +121,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 +144,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

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):