okstra 0.38.1 → 0.40.0

package/docs/superpowers/plans/2026-06-02-okstra-run-phase-pane-cleanup.md

@@ -0,0 +1,410 @@
+# okstra-run phase 전환 시 tmux pane 정리 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** okstra-run 에서 새 내부 phase 가 시작될 때 이전 phase 의 okstra pane(worker-agent + trace)을 자동으로 닫아 좀비 pane 누적을 없앤다.
+
+**Architecture:** `okstra-trace-cleanup.sh` 의 pane 식별을 "registry trace pane ∪ title-allowlist worker-agent pane (lead pane 제외)" 합집합으로 통일한다. lead 는 `_common-contract.md` 규약에 따라 phase 전환 직전 이 스크립트를 무인자(kill) 모드로 호출한다. 최종 run 종료 prompt 와 SessionEnd 훅은 같은 스크립트를 공유한다.
+
+**Tech Stack:** Bash (tmux), Python pytest (실 tmux 서버 기반 단위 테스트), okstra 빌드 파이프라인(`npm run build`).
+
+설계 근거: [docs/superpowers/specs/2026-06-02-okstra-run-phase-pane-cleanup-design.md](../specs/2026-06-02-okstra-run-phase-pane-cleanup-design.md)
+
+---
+
+## File Structure
+
+- Modify: `scripts/okstra-trace-cleanup.sh` — pane 식별을 통합 합집합으로 확장. 단일 참조점(SessionEnd 훅 / phase 자동정리 / 최종 prompt 공용).
+- Modify: `tests/test_okstra_trace_cleanup.py` — title-allowlist kill / lead·비-okstra pane 보존 회귀 가드 추가.
+- Modify: `prompts/profiles/_common-contract.md` — phase-start 자동정리 규약 추가 + 최종 prompt 대상 통합.
+- Modify: `docs/kr/architecture.md` — Live-log mirror 절에 phase-start 정리 + worker-agent pane 식별 명시.
+- Modify: `CHANGES.md` — 사용자 영향 엔트리.
+
+`runtime/` 는 빌드 출력이므로 직접 수정 금지 — 위 source 수정 후 `npm run build` 로 동기화.
+
+---
+
+## Task 1: `okstra-trace-cleanup.sh` 를 worker-agent pane 까지 정리하도록 확장
+
+**Files:**
+- Modify: `scripts/okstra-trace-cleanup.sh` (전체 본문 재작성)
+- Test: `tests/test_okstra_trace_cleanup.py`
+
+- [ ] **Step 1: 실패하는 테스트 추가**
+
+`tests/test_okstra_trace_cleanup.py` 의 맨 끝(파일 마지막 줄 `assert other_file.exists(), ...` 다음)에 아래 헬퍼와 4개 테스트를 추가한다.
+
+```python
+def _split_pane_titled(session: str, title: str) -> str:
+    """split 으로 pane 을 만들고 지정한 title 을 셋팅한 뒤 pane id 반환."""
+    pid = _split_pane(session)
+    res = _tmux("select-pane", "-t", pid, "-T", title)
+    assert res.returncode == 0, res.stderr
+    return pid
+
+
+def test_kills_worker_agent_panes_by_title(
+    tmp_path: Path, session_name: str
+) -> None:
+    """registry 없이도 worker-agent pane 은 title allowlist 로 식별돼 죽는다."""
+    lead_pane = _new_detached_session(session_name)
+    agent_claude = _split_pane_titled(session_name, "✳ claude-worker")
+    agent_codex = _split_pane_titled(session_name, "codex-worker")
+    agent_report = _split_pane_titled(session_name, "report-writer-worker")
+
+    result = _run_cleanup({
+        "TMPDIR": str(tmp_path),  # registry 디렉터리 없음
+        "TMUX_PANE": lead_pane,
+    })
+    assert result.returncode == 0, result.stderr
+
+    remaining = set(_list_pane_ids(session_name))
+    assert lead_pane in remaining, "lead pane 은 보존되어야 한다"
+    assert agent_claude not in remaining
+    assert agent_codex not in remaining
+    assert agent_report not in remaining
+
+
+def test_preserves_non_okstra_panes(
+    tmp_path: Path, session_name: str
+) -> None:
+    """allowlist 외 title pane(사용자 메인/개발 pane)은 절대 죽이지 않는다."""
+    lead_pane = _new_detached_session(session_name)
+    user_dev = _split_pane_titled(session_name, "가격 계산 기능 개발")
+    editor = _split_pane_titled(session_name, "vim")
+    agent_codex = _split_pane_titled(session_name, "codex-worker")
+
+    result = _run_cleanup({
+        "TMPDIR": str(tmp_path),
+        "TMUX_PANE": lead_pane,
+    })
+    assert result.returncode == 0, result.stderr
+
+    remaining = set(_list_pane_ids(session_name))
+    assert user_dev in remaining, "사용자 dev pane 은 보존"
+    assert editor in remaining, "무관한 pane 은 보존"
+    assert agent_codex not in remaining, "okstra agent pane 만 죽는다"
+
+
+def test_excludes_lead_pane_even_if_title_matches(
+    tmp_path: Path, session_name: str
+) -> None:
+    """lead 자신의 pane 은 title 이 allowlist 에 걸려도 죽이지 않는다 (불변)."""
+    lead_pane = _new_detached_session(session_name)
+    _tmux("select-pane", "-t", lead_pane, "-T", "claude-worker")
+    sibling = _split_pane_titled(session_name, "codex-worker")
+
+    result = _run_cleanup({
+        "TMPDIR": str(tmp_path),
+        "TMUX_PANE": lead_pane,
+    })
+    assert result.returncode == 0, result.stderr
+
+    remaining = set(_list_pane_ids(session_name))
+    assert lead_pane in remaining, "lead pane 은 title 매칭돼도 보존"
+    assert sibling not in remaining
+
+
+def test_list_includes_agent_and_trace(
+    tmp_path: Path, session_name: str
+) -> None:
+    """--list 는 registry trace pane + title-match agent pane 을 합쳐 출력."""
+    lead_pane = _new_detached_session(session_name)
+    trace = _split_pane_titled(session_name, "codex-worker-93421-trace")
+    agent = _split_pane_titled(session_name, "report-writer-worker")
+
+    safe = "".join(c if c.isalnum() else "_" for c in lead_pane)
+    registry_dir = tmp_path / "okstra-trace-panes"
+    registry_dir.mkdir()
+    (registry_dir / f"{safe}.list").write_text(f"{trace}\n")
+
+    result = _run_cleanup_with_mode(tmp_path, lead_pane, "--list")
+    assert result.returncode == 0, result.stderr
+    lines = [line for line in result.stdout.splitlines() if line]
+    ids = {line.split("\t", 1)[0] for line in lines}
+    assert trace in ids
+    assert agent in ids
+    assert lead_pane not in ids
+
+    # --list 는 죽이지 않는다.
+    remaining = set(_list_pane_ids(session_name))
+    assert {trace, agent}.issubset(remaining)
+```
+
+- [ ] **Step 2: 테스트 실행해서 실패 확인**
+
+Run: `python3 -m pytest tests/test_okstra_trace_cleanup.py -v`
+Expected: 새 4개 테스트 FAIL — 현재 스크립트는 title-match 를 모르고, registry 가 없으면 조기 종료(`test_kills_worker_agent_panes_by_title` 가 agent pane 을 못 죽임). 기존 테스트는 PASS.
+
+- [ ] **Step 3: 스크립트 전체 재작성**
+
+`scripts/okstra-trace-cleanup.sh` 의 **전체 내용**을 아래로 교체한다.
+
+```bash
+#!/usr/bin/env bash
+#
+# okstra-trace-cleanup.sh — manage tmux panes created during an okstra run for
+# the current Claude Code (lead) session.
+#
+# Two pane sources are cleaned for the lead's session:
+#   1. Trace panes — `tail -F` siblings spawned by the codex/gemini wrappers
+#      (`okstra-codex-exec.sh`, `okstra-gemini-exec.sh`). Tracked in a registry
+#      keyed by the lead's `$TMUX_PANE`.
+#   2. Worker-agent panes — panes the harness gives to dispatched okstra
+#      subagents (`claude-worker`, `codex-worker`, `gemini-worker`,
+#      `report-writer-worker`). Not registered anywhere by okstra; identified by
+#      a title allowlist within the lead's tmux session.
+#
+# The lead's own pane (`$TMUX_PANE`) is NEVER killed, even if its title matches
+# the allowlist. The scan is scoped to the lead's session (`list-panes -s`),
+# never the whole server (`-a`).
+#
+# Two modes:
+#   (default)  kill every okstra pane (sources 1+2) and remove the registry
+#              file. Used by the `SessionEnd` hook, by the lead's per-phase
+#              auto-clean, and by the lead's end-of-run prompt (yes-branch).
+#   --list     print one line per okstra pane (`<pane_id>\t<pane_title>`) so the
+#              lead can show the user what would be closed. Empty stdout when
+#              nothing is tracked.
+#
+# Failures are tolerated silently — a stale pane id, missing $TMUX, or a locked
+# tmux client must never prevent Claude from exiting cleanly.
+
+set -u
+
+MODE="kill"
+case "${1:-}" in
+  "")        MODE="kill" ;;
+  --list)    MODE="list" ;;
+  --dry-run) MODE="list" ;;  # alias
+  -h|--help)
+    cat <<'USAGE'
+usage: okstra-trace-cleanup.sh [--list]
+
+  (no args)   kill every okstra pane for $TMUX_PANE (trace + worker-agent);
+              remove the trace registry file.
+  --list      print "<pane_id>\t<pane_title>" per okstra pane; no kill.
+  --dry-run   alias for --list.
+USAGE
+    exit 0 ;;
+  *)
+    printf 'okstra-trace-cleanup.sh: unknown option: %s\n' "$1" >&2
+    exit 2 ;;
+esac
+
+# No tmux pane context → nothing to clean / list.
+if [[ -z "${TMUX_PANE:-}" ]]; then
+  exit 0
+fi
+
+registry_dir="${TMPDIR:-/tmp}/okstra-trace-panes"
+safe_pane="${TMUX_PANE//[^A-Za-z0-9]/_}"
+registry_file="$registry_dir/${safe_pane}.list"
+
+# Collect okstra pane ids for the lead session: registered trace panes ∪
+# title-allowlisted worker-agent panes, always excluding the lead pane itself.
+collect_okstra_panes() {
+  local -a panes=()
+  local pid title
+
+  # (1) Registered trace panes — scoped to THIS lead's registry only, so
+  # concurrent Claude instances do not stomp each other's trace panes.
+  if [[ -f "$registry_file" ]]; then
+    while IFS= read -r pid; do
+      [[ -n "$pid" ]] || continue
+      [[ "$pid" == "$TMUX_PANE" ]] && continue
+      panes+=("$pid")
+    done < "$registry_file"
+  fi
+
+  # (2) Title-allowlisted worker-agent panes in the lead's session.
+  # `list-panes -s -t <pane>` resolves the session containing that pane, so the
+  # scan never reaches other sessions (no `-a`).
+  while IFS=$'\t' read -r pid title; do
+    [[ -n "$pid" ]] || continue
+    [[ "$pid" == "$TMUX_PANE" ]] && continue
+    case "$title" in
+      *claude-worker*|*codex-worker*|*gemini-worker*|*report-writer-worker*)
+        panes+=("$pid") ;;
+    esac
+  done < <(tmux list-panes -s -t "$TMUX_PANE" \
+             -F '#{pane_id}'$'\t''#{pane_title}' 2>/dev/null || true)
+
+  # Dedupe — a live trace pane can match both the registry and the title scan.
+  if (( ${#panes[@]} )); then
+    printf '%s\n' "${panes[@]}" | awk 'NF && !seen[$0]++'
+  fi
+}
+
+if [[ "$MODE" == "list" ]]; then
+  while IFS= read -r pane_id; do
+    [[ -n "$pane_id" ]] || continue
+    # `display-message -p` resolves a *live* pane's title; for stale ids tmux
+    # exits non-zero — fall back to an empty title rather than failing.
+    title=$(tmux display-message -p -t "$pane_id" '#{pane_title}' 2>/dev/null || true)
+    printf '%s\t%s\n' "$pane_id" "$title"
+  done < <(collect_okstra_panes)
+  exit 0
+fi
+
+while IFS= read -r pane_id; do
+  [[ -n "$pane_id" ]] || continue
+  tmux kill-pane -t "$pane_id" 2>/dev/null || true
+done < <(collect_okstra_panes)
+
+rm -f "$registry_file" 2>/dev/null || true
+exit 0
+```
+
+- [ ] **Step 4: 테스트 실행해서 통과 확인**
+
+Run: `python3 -m pytest tests/test_okstra_trace_cleanup.py -v`
+Expected: 신규 4개 + 기존 7개 모두 PASS. (tmux 없는 환경이면 모듈 전체 skip — 그 경우 tmux 있는 환경에서 재확인.)
+
+- [ ] **Step 5: 빌드 동기화 + 커밋**
+
+```bash
+cd /Volumes/Workspaces/workspace/projects/Okstra
+npm run build
+git add scripts/okstra-trace-cleanup.sh tests/test_okstra_trace_cleanup.py runtime/
+git commit -m "feat(scripts/okstra-trace-cleanup): worker-agent pane 까지 title allowlist 로 정리"
+```
+
+---
+
+## Task 2: `_common-contract.md` 에 phase-start 자동정리 규약 추가
+
+**Files:**
+- Modify: `prompts/profiles/_common-contract.md` (현재 32–43행 wrap-up 섹션 주변)
+
+- [ ] **Step 1: wrap-up 섹션 헤더와 첫 bullet 을 두 pane 종류로 확장**
+
+아래 old 를 new 로 교체한다 (`Edit`).
+
+old:
+```
+- 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, 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.
+```
+
+new:
+```
+- Phase-start pane reset (shared — runs BEFORE dispatching each new worker batch):
+  - okstra creates two kinds of tmux pane per run: (a) **worker-agent panes** the harness gives to dispatched subagents (titled `claude-worker` / `codex-worker` / `gemini-worker` / `report-writer-worker`), and (b) **trace panes** the codex/gemini wrappers spawn (`<cli>-<role>-<pid>-trace`). Both accumulate across internal phases because each new phase dispatches a fresh worker batch and the prior panes are never reclaimed.
+  - When `$TMUX_PANE` is set, the lead MUST run `$HOME/.okstra/bin/okstra-trace-cleanup.sh` (no args) **immediately before** dispatching the next phase's workers — i.e. just before emitting each `PROGRESS: phase-5.5-convergence round=<N>` marker and just before `PROGRESS: phase-6-synthesis dispatching report-writer-worker`. This closes every prior-phase okstra pane (worker-agent + trace) for the lead session, while NEVER killing the lead's own pane.
+  - This is **automatic and silent** — NO user prompt. Report it in one short line (e.g. `이전 phase okstra pane 3개 정리`) and proceed. It is silent-skipped when `$TMUX_PANE` is unset; the lead MUST NOT fabricate a synthetic pane list in that case.
+- Phase wrap-up — okstra pane disposition (shared, MUST be the *last* step before returning control to the user):
+  - At run end the only residual okstra panes are the LAST phase's (e.g. the `report-writer-worker` agent pane and any codex/gemini trace pane). `okstra-trace-cleanup.sh --list` returns one tab-separated `<pane_id>\t<pane_title>` line per residual okstra pane (worker-agent + trace) for this lead session.
+```
+
+- [ ] **Step 2: 최종 prompt bullet 들의 "trace pane" 문구를 "okstra pane" 으로 정합화**
+
+같은 섹션의 후속 bullet 들에서 아래 old 를 new 로 교체한다 (`Edit`).
+
+old:
+```
+  - 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):
+    > 현재 phase 종료 시점입니다. 다음 worker trace pane 이 열려 있습니다 — 닫을까요?
+    > <인용된 `--list` 출력>
+    > (예) 모두 닫기 / (아니오) 그대로 두기
+```
+
+new:
+```
+  - 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 lists every residual okstra pane (worker-agent + trace) for this Claude session, never the lead's own pane.
+  - If the list is empty, skip the question — there is nothing to ask about (the phase-start resets above usually already cleared prior phases).
+  - 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):
+    > 현재 phase 종료 시점입니다. 다음 okstra pane 이 열려 있습니다 — 닫을까요?
+    > <인용된 `--list` 출력>
+    > (예) 모두 닫기 / (아니오) 그대로 두기
+```
+
+- [ ] **Step 3: 검증 — 렌더링 + 워크플로 validator**
+
+Run:
+```bash
+cd /Volumes/Workspaces/workspace/projects/Okstra
+bash validators/validate-workflow.sh
+grep -n "Phase-start pane reset" prompts/profiles/_common-contract.md
+```
+Expected: validator 통과(exit 0), grep 가 신규 규약 1행 매칭.
+
+- [ ] **Step 4: 빌드 동기화 + 커밋**
+
+```bash
+cd /Volumes/Workspaces/workspace/projects/Okstra
+npm run build
+git add prompts/profiles/_common-contract.md runtime/
+git commit -m "feat(prompts/profiles): phase 시작 시 이전 phase okstra pane 자동 정리 규약"
+```
+
+---
+
+## Task 3: 문서 갱신 (architecture.md + CHANGES.md)
+
+**Files:**
+- Modify: `docs/kr/architecture.md` (Live-log mirror 절, 약 912–913행)
+- Modify: `CHANGES.md` (최상단 신규 엔트리)
+
+- [ ] **Step 1: architecture.md Live-log mirror 절에 phase-start 정리 문단 추가**
+
+`docs/kr/architecture.md` 의 913행(현재 "**Claude `/exit` 시 자동 정리**: …" 로 시작하는 bullet) **바로 다음 줄**에 아래 bullet 을 삽입한다 (`Edit` — 913행 bullet 끝의 줄바꿈 뒤에 추가).
+
+```
+- **phase 전환 시 자동 정리 + worker-agent pane 포함**: `okstra-trace-cleanup.sh` 는 trace pane(registry) 뿐 아니라 dispatch 된 서브에이전트가 점유하는 worker-agent pane(title `claude-worker` / `codex-worker` / `gemini-worker` / `report-writer-worker`)도 lead 세션(`list-panes -s`) 범위에서 title allowlist 로 식별해 닫는다. lead 자신의 pane(`$TMUX_PANE`)은 title 이 걸려도 절대 죽이지 않는다. lead 는 새 phase 의 worker 를 dispatch 하기 직전(`PROGRESS: phase-5.5-convergence` / `phase-6-synthesis` 마커 직전) 이 스크립트를 무인자로 호출해 이전 phase pane 을 prompt 없이 정리한다. run 최종 종료 시점의 잔여만 기존 `--list` + 이진 prompt 로 확인한다.
+```
+
+- [ ] **Step 2: CHANGES.md 에 사용자 영향 엔트리 추가**
+
+`CHANGES.md` 최상단(가장 최근 엔트리 위)에 아래를 추가한다 (`Edit` — 파일 첫 엔트리 헤더 바로 위에 삽입). 날짜·형식은 기존 엔트리 컨벤션을 따른다.
+
+```
+## 2026-06-02 — okstra-run phase 전환 시 tmux pane 자동 정리
+
+- **증상**: okstra-run 진행 중 lead 가 phase 마다 새 worker(claude/codex/gemini/report-writer)를 dispatch 하면, 이전 phase 의 worker-agent pane 과 wrapper trace pane 이 닫히지 않고 누적돼 화면이 좀비 pane 으로 채워졌다. 정리는 run 맨 끝 1회뿐이었고 worker-agent pane 은 아예 관리 대상이 아니었다.
+- **변경**: `okstra-trace-cleanup.sh` 가 trace pane(registry) + worker-agent pane(title allowlist, lead 세션 범위, lead pane 제외)을 합쳐 정리하도록 확장. lead 는 새 phase dispatch 직전 이 스크립트를 무인자로 호출해 이전 phase pane 을 자동(무콜) 정리하고, run 최종 종료 시점의 잔여만 기존 이진 prompt 로 확인한다.
+- **사용자 영향**: tmux 안에서 okstra-run 을 돌릴 때 새 phase 가 시작되면 이전 phase 의 worker/trace pane 이 자동으로 닫혀 화면에 좀비 pane 이 쌓이지 않는다. 사용자가 무관한 pane(메인/개발)은 건드리지 않는다.
+```
+
+- [ ] **Step 3: 커밋**
+
+```bash
+cd /Volumes/Workspaces/workspace/projects/Okstra
+git add docs/kr/architecture.md CHANGES.md
+git commit -m "docs(architecture,changes): phase 전환 시 okstra pane 자동 정리 문서화"
+```
+
+---
+
+## Task 4: 전체 검증
+
+- [ ] **Step 1: 전체 단위 테스트**
+
+Run: `python3 -m pytest tests/ -q`
+Expected: 전부 PASS (또는 tmux 미존재로 trace-cleanup 모듈만 skip — 그 경우 tmux 환경에서 Task 1 Step 4 재확인 필요).
+
+- [ ] **Step 2: 워크플로 validator + CLI 스모크**
+
+Run:
+```bash
+cd /Volumes/Workspaces/workspace/projects/Okstra
+bash validators/validate-workflow.sh
+node bin/okstra --version
+```
+Expected: validator exit 0, 버전 출력.
+
+- [ ] **Step 3: diff 리뷰 (critique mode)**
+
+Run: `git log --oneline main..HEAD && git diff main..HEAD --stat`
+점검: (a) `runtime/` 가 source 변경과 일치하게 재생성됐는지, (b) 새 토큰 `Phase-start pane reset` 의 grep 일관성, (c) `okstra-trace-cleanup.sh` 의 lead-pane 제외 불변이 list/kill 양쪽에 적용됐는지.
+
+---
+
+## Self-Review (작성자 체크 완료)
+
+- **Spec coverage**: 스크립트 통합(§스크립트 변경)=Task 1, contract(§contract 변경)=Task 2, 테스트(§테스트)=Task 1 Step 1, 문서/전파(§영향)=Task 3. 모든 spec 섹션이 task 로 매핑됨.
+- **Placeholder scan**: TBD/TODO 없음. 모든 코드 step 에 완전한 코드 포함.
+- **Type/식별자 consistency**: `collect_okstra_panes`, allowlist 4개 title, `okstra-trace-cleanup.sh` 인터페이스(`--list`/무인자)가 Task 1·2·3 에서 동일 명칭으로 일관.
+- **알려진 한계**(동시-run title 충돌, 선언적 enforcement)는 spec 에 명시 — 코드 변경 없음.