okstra 0.89.0 → 0.90.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.89.0",
+  "version": "0.90.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.89.0",
-  "builtAt": "2026-06-17T10:43:53.695Z",
+  "package": "0.90.0",
+  "builtAt": "2026-06-17T18:09:19.361Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

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

@@ -218,6 +218,7 @@ if [[ -n "$caller_pane" ]]; then
     # Tag with this run's dir for `okstra-trace-cleanup.sh --run-dir`. See
     # `okstra-codex-exec.sh` for the rationale — kept in lock-step.
     [[ -n "$run_dir" ]] && tmux set-option -p -t "$trace_pane" @okstra_trace_run "$run_dir" 2>/dev/null || true
+    [[ -n "$status_path" ]] && tmux set-option -p -t "$trace_pane" @okstra_status "$status_path" 2>/dev/null || true
     tmux last-pane 2>/dev/null || true
   fi
 fi

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

@@ -280,6 +280,7 @@ if [[ -n "$caller_pane" ]]; then
     # assumption. The run-scoped tag also stops concurrent okstra runs from
     # stomping each other's trace panes.
     [[ -n "$run_dir" ]] && tmux set-option -p -t "$trace_pane" @okstra_trace_run "$run_dir" 2>/dev/null || true
+    [[ -n "$status_path" ]] && tmux set-option -p -t "$trace_pane" @okstra_status "$status_path" 2>/dev/null || true
     tmux last-pane 2>/dev/null || true
   fi
 fi

package/runtime/bin/okstra-subagent-reclaim.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+#
+# okstra-subagent-reclaim.sh — SubagentStop / TaskCompleted 훅 엔트리.
+#
+# stdin(JSON)은 읽고 버린다: 어느 worker 가 끝났든 활성 run 전체의 "완료" pane 만
+# 회수하므로 session_id 매핑이 필요 없다. active.jsonl 의 각 활성 run 에 대해
+# okstra-trace-cleanup.sh --reclaim-completed 를 호출한다 — 완료 판정(pane_reclaim)이
+# cross-run 안전을 보장하므로 다른 run 의 진행 중 pane 은 건드리지 않는다.
+#
+# 훅은 세션 진행을 절대 막지 않는다: 모든 실패는 조용히 삼키고 항상 exit 0.
+set -u
+
+cat >/dev/null 2>&1 || true   # drain stdin
+
+_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+home="${OKSTRA_HOME:-$HOME/.okstra}"
+# pane_reclaim 패키지는 repo 레이아웃(scripts/okstra_ctl)과 설치 레이아웃
+# ($OKSTRA_HOME/lib/python) 양쪽에 있을 수 있으므로 둘 다 PYTHONPATH 에 둔다.
+export PYTHONPATH="${_dir}:${home}/lib/python${PYTHONPATH:+:$PYTHONPATH}"
+
+while IFS= read -r run_dir; do
+  [[ -n "$run_dir" ]] || continue
+  "$_dir/okstra-trace-cleanup.sh" --reclaim-completed --run-dir "$run_dir" >/dev/null 2>&1 || true
+done < <(python3 -m okstra_ctl.pane_reclaim --active-dirs "$home" 2>/dev/null || true)
+
+exit 0

package/runtime/bin/okstra-trace-cleanup.sh

@@ -46,24 +46,37 @@ set -u
 _clean_script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
 [ -r "$_clean_script_dir/lib/okstra/tmux-pane.sh" ] && . "$_clean_script_dir/lib/okstra/tmux-pane.sh"
 
+# --reclaim-completed shells out to `python3 -m okstra_ctl.pane_reclaim`. The
+# package is a bin-sibling in the repo layout (scripts/okstra_ctl) and under
+# $OKSTRA_HOME/lib/python in the installed layout. Put both on PYTHONPATH so the
+# import resolves regardless of where this script runs from.
+_okstra_home="${OKSTRA_HOME:-$HOME/.okstra}"
+export PYTHONPATH="${_clean_script_dir}:${_okstra_home}/lib/python${PYTHONPATH:+:$PYTHONPATH}"
+
 MODE="kill"   # kill | list
+RECLAIM=0     # 1: trace pane 은 @okstra_status 가 완료(exited)일 때만 회수 (--reclaim-completed)
 REAP=0
 run_dir=""
 while [[ $# -gt 0 ]]; do
   case "$1" in
-    --list|--dry-run) MODE="list" ;;
-    --reap)           REAP=1 ;;
+    --list|--dry-run)    MODE="list" ;;
+    --reclaim-completed) RECLAIM=1 ;;
+    --reap)              REAP=1 ;;
     --run-dir)        shift; run_dir="${1-}" ;;
     --run-dir=*)      run_dir="${1#--run-dir=}" ;;
     -h|--help)
       cat <<'USAGE'
-usage: okstra-trace-cleanup.sh (--run-dir <RUN_DIR> [--list] | --reap)
+usage: okstra-trace-cleanup.sh (--run-dir <RUN_DIR> [--list] [--reclaim-completed] | --reap)
 
-  --run-dir   okstra run directory; closes that run's trace + worker-agent panes.
-  --list      with --run-dir: print "<pane_id>\t<pane_title>" per pane; no kill.
-  --dry-run   alias for --list.
-  --reap      close every okstra trace pane under $CLAUDE_PROJECT_DIR/.okstra
-              (SessionEnd hook; no single run-dir applies).
+  --run-dir            okstra run directory; closes that run's trace + worker-agent panes.
+  --list               with --run-dir: print "<pane_id>\t<pane_title>" per pane; no kill.
+  --dry-run            alias for --list.
+  --reclaim-completed  with --run-dir: restrict trace panes to those whose
+                       @okstra_status sidecar is terminal (stage=exited); in-flight
+                       and teammate panes are preserved. Skips the title-allowlist
+                       teammate scan. Combinable with --list.
+  --reap               close every okstra trace pane under $CLAUDE_PROJECT_DIR/.okstra
+                       (SessionEnd hook; no single run-dir applies).
 USAGE
       exit 0 ;;
     *)
@@ -117,24 +130,39 @@ _tag_in_scope() {
 
 collect_okstra_panes() {
   local -a panes=()
-  local pid trace_tag worker_tag title
+  local pid trace_tag worker_tag status_tag title
 
   # (1) Trace and worker-compute panes tagged in scope — found server-wide by
-  # tag, so no tmux env var or pane-id registry is needed.
-  while IFS=$'\t' read -r pid trace_tag worker_tag; do
+  # tag, so no tmux env var or pane-id registry is needed. Each `@okstra_*`
+  # column carries a leading `x` sentinel (stripped after read): tmux's `-F`
+  # drops an UNSET user option AND its adjacent tab, which would otherwise
+  # shift later columns left (e.g. an empty worker tag stealing the status
+  # value). The sentinel keeps every column present so positional parsing holds.
+  # `#x` strip 은 실제 태그 값을 깎지 않는다: 모든 태그 값(trace_run/worker_run/
+  # status)은 절대경로라 `/` 로 시작 → `x` 로 시작하는 일이 없어 sentinel 만 벗겨진다.
+  while IFS=$'\t' read -r pid trace_tag worker_tag status_tag; do
+    trace_tag="${trace_tag#x}"; worker_tag="${worker_tag#x}"; status_tag="${status_tag#x}"
     [[ -n "$pid" ]] || continue
     [[ "$pid" == "$lead_pane" ]] && continue
     if _tag_in_scope "$trace_tag" || _tag_in_scope "$worker_tag"; then
+      if [[ "$RECLAIM" -eq 1 ]]; then
+        # reclaim 모드: 완료(stage=exited)된 worker 의 pane 만. status 태그가
+        # 없거나(teammate/비-wrapper pane) 미완료면 보존.
+        [[ -n "$status_tag" ]] || continue
+        python3 -m okstra_ctl.pane_reclaim "$status_tag" || continue
+      fi
       panes+=("$pid")
     fi
   done < <(tmux list-panes -a \
-             -F '#{pane_id}'$'\t''#{@okstra_trace_run}'$'\t''#{@okstra_worker_run}' \
+             -F '#{pane_id}'$'\t''x#{@okstra_trace_run}'$'\t''x#{@okstra_worker_run}'$'\t''x#{@okstra_status}' \
              2>/dev/null || true)
   # (2) Title-allowlisted worker-agent panes in the lead's session. Only for a
   # run (reap leaves these harness-owned panes to the harness). `list-panes -s
   # -t <pane>` resolves the session containing that pane, so the scan never
   # reaches other sessions (no `-a`). Skipped when the lead pane is unknown.
-  if [[ "$REAP" -eq 0 && -n "$lead_pane" ]]; then
+  # reclaim 모드는 teammate pane 을 회수하지 않으므로(완료 판정 불가, trace-only)
+  # 이 스캔을 건너뛴다.
+  if [[ "$REAP" -eq 0 && "$RECLAIM" -eq 0 && -n "$lead_pane" ]]; then
     while IFS=$'\t' read -r pid title; do
       [[ -n "$pid" ]] || continue
       [[ "$pid" == "$lead_pane" ]] && continue

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

@@ -16,6 +16,7 @@ profile document.
   - **Phase 4 / 5 (independent analysis)**: analyser workers (`claude`, `codex`, `antigravity` when opted in) produce findings independently and have no access to one another's outputs. `report-writer` does not analyse.
   - **Phase 5.5 (convergence — peer review by workers)**: the lead replays each analyser's findings to the *other* analysers and collects `AGREE` / `DISAGREE` / `SUPPLEMENT` verdicts across up to `effectiveMaxRounds` rounds. Workers act as peer reviewers of each other's findings in this phase; the lead mediates but does not vote. See `prompts/lead/convergence.md` for the round protocol, queue invariants, and final classification (`full-consensus` / `partial-consensus` / `contested` / `worker-unique`). For `requirements-discovery`, `error-analysis`, and `implementation-planning` this phase runs in **adversarial mode** (`convergence.adversarial=true`): verifiers try to refute each finding against its cited evidence and the burden of proof sits on the claim — see that skill's §"Adversarial Verification Mode".
   - Do NOT conclude "no peer review happens" from the roster alone — every profile that lists ≥2 analyser workers runs convergence by default (`convergence.enabled=true` in `task-manifest.json`).
+  - **Pane-budget fallback (tolerance).** If a worker dispatch is rejected with `no room for another tmux split` (or an equivalent teammate-pane creation failure), the lead retries that worker in-process without `run_in_background`, or — if it was an external CLI worker — **substitutes** an in-process `claude` analysis, and records that fact (provider unavailable) in the run log and the convergence notes. Completed external-CLI worker trace panes are reclaimed automatically by the `SubagentStop` hook, but okstra cannot directly reclaim the teammate panes the harness creates, so this fallback is the last line of defence against pane-budget exhaustion. (This is a prompt instruction, not a code-enforced gate.)
 - Tooling — read-only MCP availability (shared):
   - MCP is not implicit okstra context. Query an MCP server only when the task brief explicitly lists it as source material for this run. Any MCP-derived finding MUST cite server, table, and the SELECT used. MCP MUST NEVER be used as a write path — schema/data mutations go through repository migration files reviewed by humans.
 - Resource boundary (shared — artifact-home rule):
@@ -30,11 +31,11 @@ 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.
 - Run-start pane recording (shared — runs ONCE at run start, before the FIRST worker dispatch):
-  - The codex/antigravity wrappers now self-anchor their trace pane by walking their own ancestor PIDs against tmux `pane_pid`s (see `lib/okstra/tmux-pane.sh`), so they no longer depend on this file. The lead still records its own pane id here for the cleanup steps below (which-pane-to-never-kill) and as the "am I in tmux" gate. A bare `tmux display-message -p '#{pane_id}'` is NOT reliable for this — Claude Code's Bash tool strips `$TMUX`/`$TMUX_PANE`, so that command returns the most-recently-active *client's* pane (often a different session, or a foreign pane when the lead is launched outside tmux entirely). The lead therefore records via the same ancestry resolver.
-  - The lead MUST run once, at run start: `mkdir -p "<RUN_DIR>/state" && { . "$HOME/.okstra/bin/lib/okstra/tmux-pane.sh" 2>/dev/null && okstra_resolve_caller_pane; } > "<RUN_DIR>/state/lead-pane.id" 2>/dev/null || true` (substitute the run's absolute `RUN_DIR`). When the lead is not inside a tmux pane (e.g. Claude launched from the GUI app) no ancestor matches a pane, the file is empty, and every pane step below silently no-ops — that empty/absent file is the single signal that the lead is not in tmux.
-  - This recording is **silent internal setup**: the lead MUST emit NOTHING to the user about it — no pane id, no `%NNN`, no `lead-pane.id` path, no announcement that the phase-start-cleanup / wrap-up-disposition steps "activate". Just record the file and proceed.
+  - The codex/antigravity wrappers now self-anchor their trace pane by walking their own ancestor PIDs against tmux `pane_pid`s (see `lib/okstra/tmux-pane.sh`), so they no longer depend on this file. The lead still records its own pane id here so the cleanup script below can know which pane to never kill and can detect tmux absence itself — the lead does NOT read it back to gate those steps. A bare `tmux display-message -p '#{pane_id}'` is NOT reliable for this — Claude Code's Bash tool strips `$TMUX`/`$TMUX_PANE`, so that command returns the most-recently-active *client's* pane (often a different session, or a foreign pane when the lead is launched outside tmux entirely). The lead therefore records via the same ancestry resolver.
+  - The lead MUST run once, at run start: `mkdir -p "<RUN_DIR>/state" && { . "$HOME/.okstra/bin/lib/okstra/tmux-pane.sh" 2>/dev/null && okstra_resolve_caller_pane; } > "<RUN_DIR>/state/lead-pane.id" 2>/dev/null || true` (substitute the run's absolute `RUN_DIR`). When the lead is not inside a tmux pane (e.g. Claude launched from the GUI app) no ancestor matches a pane and the file is empty. The cleanup steps below do NOT read this file to decide whether to run — they always run, and the script itself reads `lead-pane.id` (with its own ancestry fallback) only to know which pane to never kill and to detect tmux absence. The lead never interprets this file to gate a pane step.
+  - This recording is **silent internal setup**: the lead MUST emit NOTHING to the user about it — no pane id, no `%NNN`, no `lead-pane.id` path, no announcement of the phase-start-cleanup / wrap-up-disposition steps. Just record the file and proceed.
 - Phase-start cleanup — prior-batch panes + completed teammates (shared — runs BEFORE dispatching each new worker batch, at the SAME boundaries: just before each `PROGRESS: phase-5.5-convergence round=<N>` marker and just before `PROGRESS: phase-6-synthesis dispatching report-writer-worker`):
-  - **(a) tmux panes.** okstra creates two kinds of tmux pane per run: **worker-agent panes** the harness gives to dispatched subagents (titled `claude-worker` / `codex-worker` / `antigravity-worker` / `report-writer-worker`), and **trace panes** the codex/antigravity wrappers spawn (`<cli>-<role>-<pid>-tail`). Both accumulate because each new batch spawns fresh panes and the prior ones are never reclaimed. When `<RUN_DIR>/state/lead-pane.id` is non-empty (the lead is in tmux), the lead MUST run `$HOME/.okstra/bin/okstra-trace-cleanup.sh --run-dir "<RUN_DIR>"` immediately before dispatching the next batch. This closes every prior-batch okstra pane (worker-agent + trace) for this run, while NEVER killing the lead's own pane. Silent-skipped when the lead is not in tmux; the lead MUST NOT fabricate a synthetic pane list in that case.
+  - **(a) tmux panes.** okstra creates two kinds of tmux pane per run: **worker-agent panes** the harness gives to dispatched subagents (titled `claude-worker` / `codex-worker` / `antigravity-worker` / `report-writer-worker`), and **trace panes** the codex/antigravity wrappers spawn (`<cli>-<role>-<pid>-tail`). Both accumulate because each new batch spawns fresh panes and the prior ones are never reclaimed. The lead MUST ALWAYS run `$HOME/.okstra/bin/okstra-trace-cleanup.sh --run-dir "<RUN_DIR>"` immediately before dispatching the next batch — NEVER gating this call on its own reading of `lead-pane.id`. The script self-resolves the lead pane and is a safe no-op outside tmux (it returns an empty pane list), so an always-run call cannot do harm; it closes every prior-batch okstra pane (worker-agent + trace) for this run while NEVER killing the lead's own pane. The lead MUST NOT fabricate a synthetic pane list.
   - **(b) completed teammates (Teams mode only).** Each convergence round / critic / gap-verification / report-writer dispatch spawns teammates under fresh Agent `name`s (`<role>-reverify-r<N>`, `<provider>-worker-critic`, `report-writer-worker`, …); completed teammates do NOT leave the FleetView roster on their own — they linger as idle pills until run-end teardown, so a long run's roster grows unreadable. Before dispatching the next batch, the lead MUST send `SendMessage(to: <name>, message: { type: "shutdown_request" })` — the `message` MUST be the object literal shown, NEVER a JSON string stuffed into a text field — to every teammate it spawned earlier in THIS run **whose completion is already confirmed** (its Result Path exists / it is in the self-scheduled-polling done set). This is the same graceful-shutdown primitive used at `Run-end teammate teardown`, applied per batch instead of once at the end.
     - **Only confirmed-complete teammates, never the lead.** NEVER send a shutdown_request to a teammate whose result file has not yet appeared. In particular the critic runs CONCURRENTLY with the first reverify round (see `convergence` "Coverage critic pass"), so it MUST NOT be shut down until its own result is collected. NEVER target the lead's own session.
     - **Do NOT call `TeamDelete` here.** The team stays alive for the remaining batches; only individual completed teammates are dismissed. `TeamDelete` remains a run-end-only step (`Run-end teammate teardown`).
@@ -42,7 +43,7 @@ profile document.
   - Both (a) and (b) are **automatic and silent** — NO user prompt. Report the pair in one short, plain-language line (e.g. `이전 배치 okstra pane 3개 · teammate 2명 정리`) and proceed — never expose internal identifiers (`%NNN`, `lead-pane.id`, raw Agent names, step names like "phase-start cleanup"). **Effect caveat:** Claude Code exposes no tool to surgically delete a roster entry mid-run, so a dismissed teammate may still show as an idle pill; the shutdown still reclaims its session and prevents the roster from growing with live members. On the FIRST batch of a run nothing has been dispatched yet — both steps no-op.
 - Phase wrap-up — okstra pane disposition (shared, runs AFTER Phase 7 persistence/token collection and BEFORE teammate teardown):
   - At run end the only residual okstra panes are the LAST phase's (e.g. the `report-writer-worker` agent pane and any codex/antigravity trace pane). `okstra-trace-cleanup.sh --list --run-dir "<RUN_DIR>"` returns one tab-separated `<pane_id>\t<pane_title>` line per residual okstra pane (worker-agent + trace) for this run.
-  - When `<RUN_DIR>/state/lead-pane.id` is non-empty, 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 --run-dir "<RUN_DIR>"` exactly once. The output lists every residual okstra pane (worker-agent + trace) for this run, never the lead's own pane.
+  - After the final-report file has been written and the routing recommendation has been issued, the lead MUST ALWAYS run `$HOME/.okstra/bin/okstra-trace-cleanup.sh --list --run-dir "<RUN_DIR>"` exactly once — NEVER gating this call on its own reading of `lead-pane.id`. The output lists every residual okstra pane (worker-agent + trace) for this run, never the lead's own pane; outside tmux it is a safe no-op (empty output).
   - 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 이 열려 있습니다 — 닫을까요?
@@ -51,7 +52,7 @@ profile document.
   - On `예` / `y` / `close` → run `$HOME/.okstra/bin/okstra-trace-cleanup.sh --run-dir "<RUN_DIR>"` and report the kill count back in one sentence.
   - On `아니오` / `n` / `keep` → leave the panes intact; remind the user that they will be cleaned up automatically when Claude `/exit` fires the `SessionEnd` hook (`--reap`).
   - The question MUST be a clean yes/no — do NOT offer "close some / keep some" partial answers, do NOT propose alternatives like "close only codex panes". The whole-set decision keeps the wrap-up predictable.
-  - This step is mandatory for every phase (`requirements-discovery`, `error-analysis`, `implementation-planning`, `implementation`, `final-verification`, `release-handoff`). It is silent-skipped when `<RUN_DIR>/state/lead-pane.id` is empty/absent (lead running outside tmux); the lead MUST NOT fabricate a synthetic pane list in that case.
+  - This step is mandatory for every phase (`requirements-discovery`, `error-analysis`, `implementation-planning`, `implementation`, `final-verification`, `release-handoff`). Whether there is anything to ask about is decided by the `--list` output, NOT by the lead's reading of `lead-pane.id`: an empty list → skip the question (above); the lead MUST NOT fabricate a synthetic pane list.
 - Run-end teammate teardown (shared — MUST run AFTER the pane disposition question and BEFORE `PROGRESS: complete`):
   - The lead created the worker team in Phase 3 (`TeamCreate` with the name recorded as team-state `teamName` — `okstra-<task-key>`, implementation stage runs `okstra-<task-key>-s<N>`). Worker teammates are NOT reclaimed on their own — without an explicit teardown they linger in the FleetView roster across this and later runs in the session. A lingering team also makes the next run of the same task-key collide on `TeamCreate` ("team already exists"), forcing the stale-team recovery path.
   - **Whether to run this step is decided by on-disk fact, NOT by `teamCreate.status` alone.** A mid-run context compaction can make the lead wrongly conclude Agent Teams is unavailable and record `teamCreate.status: "error"` even though `TeamCreate` had succeeded and workers joined — so at run-end `status` is not a trustworthy "is there a team" signal. The harness names the team directory `session-<leadSessionId-prefix>` (NOT `okstra-<task-key>`; the `team_name` passed to `TeamCreate` is a logical label that never becomes a directory name). Resolve existence from disk: find the `~/.claude/teams/session-*/config.json` whose `leadSessionId` equals team-state `lead.sessionId`.

package/runtime/python/okstra_ctl/pane_reclaim.py

@@ -0,0 +1,55 @@
+"""완료(terminal) worker 판정 — pane 회수용. 판정 SSOT 는
+wrapper_status.read_wrapper_status 이며 여기서 재사용한다."""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+from .reconcile import NON_TERMINAL_RECENT_STATUSES
+from .wrapper_status import read_wrapper_status
+
+
+def is_completed_status(status_path: str) -> bool:
+    status = read_wrapper_status(Path(status_path))
+    return status is not None and status.is_terminal
+
+
+def active_run_dirs(home: Path) -> list[Path]:
+    """active.jsonl 의 진행 중 run 들의 절대 run-dir 목록.
+    runDirRel 의 base 는 projectRoot(paths.compute_run_paths 의 _rel 기준)."""
+    path = home / "active.jsonl"
+    if not path.is_file():
+        return []
+    dirs: list[Path] = []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            row = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        rel = row.get("runDirRel")
+        root = row.get("projectRoot")
+        # 회수 대상(진행 중) 집합은 reconcile 의 NON_TERMINAL_RECENT_STATUSES 가
+        # SSOT. reserving 은 아직 run-dir 산출물이 없어(= 회수할 pane 이 없어) 이
+        # 집합에 들어있지 않으므로 자연히 제외된다(allowlist).
+        if not rel or not root or row.get("status") not in NON_TERMINAL_RECENT_STATUSES:
+            continue
+        dirs.append(Path(root) / rel)
+    return dirs
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) == 2 and argv[0] == "--active-dirs":
+        for run_dir in active_run_dirs(Path(argv[1])):
+            print(run_dir)
+        return 0
+    if len(argv) == 1:
+        return 0 if is_completed_status(argv[0]) else 1
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/runtime/python/okstra_ctl/report_views.py

@@ -140,7 +140,7 @@ def render_html(
         f"  <button type=\"button\" data-action=\"export-user-response\">Export user response</button>\n"
         f"</header>\n"
         f"<main>{body_html}</main>\n"
-        f"{_plan_approval_section(approval_ctx) if approval_ctx else ''}"
+        f"{_plan_approval_section(approval_ctx, run_meta) if approval_ctx else ''}"
         f"<footer class=\"report-footer\">\n"
         f"  <button type=\"button\" data-action=\"export-user-response\">Export user response</button>\n"
         f"  <p class=\"user-response-hint\">Export 클릭 시 <code>{sidecar_name}</code> 가 다운로드됩니다 — "
@@ -821,10 +821,13 @@ def report_has_clarification_items(src_md: str) -> bool:
 @dataclass(frozen=True)
 class PlanApprovalContext:
     """Plan Approval 위젯 렌더 입력. ``disabled_reason`` 이 비어 있지 않으면
-    위젯은 disabled 로 렌더된다 (run-prep 승인 게이트와 동일한 fail-closed 기준)."""
+    위젯은 disabled 로 렌더된다 (run-prep 승인 게이트와 동일한 fail-closed 기준).
+    ``blocker_ids`` 는 §1 미해소 승인-차단 항목 ID 목록 — 화면 안내가 사용자에게
+    '어느 항목을 답해야 하는지' 를 보여주는 데 쓴다 (unreadable 사유면 빈 튜플)."""
     option_names: tuple[str, ...]
     recommended_option: str
     disabled_reason: str
+    blocker_ids: tuple[str, ...]
 
 
 def plan_approval_context(
@@ -853,28 +856,71 @@ def plan_approval_context(
     )
     if not names:
         return None
-    recommended = ""
     rec = planning.get("recommendedOption")
-    if isinstance(rec, dict):
-        recommended = rec.get("name") or ""
-    if recommended not in names:
-        recommended = names[0]
+    rec_name = rec.get("name") or "" if isinstance(rec, dict) else ""
+    recommended = _resolve_recommended_option(rec_name, names)
     scan = scan_approval_gate(src_text)
+    blocker_ids: tuple[str, ...] = ()
     if scan.unreadable_reason:
         reason = "§1 승인 게이트를 읽을 수 없어 승인이 비활성화되었습니다 — 보고서를 재렌더하세요."
     elif scan.blockers:
-        reason = (
-            f"§1 승인 차단 항목 {len(scan.blockers)}건 미해소 — 답변을 채워 Export 한 뒤 "
-            "resume-clarification 으로 해소한 다음 보고서에서 승인하세요."
-        )
+        blocker_ids = tuple(b.row_id for b in scan.blockers)
+        reason = f"§1 승인 차단 항목 {len(scan.blockers)}건 미해소"
     else:
         reason = ""
     return PlanApprovalContext(
-        option_names=names, recommended_option=recommended, disabled_reason=reason
+        option_names=names,
+        recommended_option=recommended,
+        disabled_reason=reason,
+        blocker_ids=blocker_ids,
+    )
+
+
+def _resolve_recommended_option(rec_name: str, names: tuple[str, ...]) -> str:
+    """``recommendedOption.name`` 을 후보 이름에 맞춘다. 정확 일치가 없으면
+    접두 일치(후보가 ``(RECOMMENDED)`` 같은 표식 접미를 더 달고 있는 흔한 경우)를
+    허용하고, 그래도 없으면 첫 후보로 폴백한다 — 항상 정확히 한 옵션이 selected 가
+    되어 브라우저 자동선택분의 묵시 Export 를 차단한다."""
+    if rec_name in names:
+        return rec_name
+    if rec_name:
+        for name in names:
+            if name.startswith(rec_name) or rec_name.startswith(name):
+                return name
+    return names[0]
+
+
+def _approval_blocked_guidance(ctx: PlanApprovalContext, run_meta: RunMeta) -> str:
+    """disabled 사유를 화면에서 바로 따라할 수 있는 단계별 안내로 렌더한다.
+    핵심: 이 화면에서 답을 입력하는 것만으로는 승인이 풀리지 않으며,
+    Export → 저장 → resume-clarification → 재렌더 라운드트립이 필요하다는 것."""
+    if not ctx.blocker_ids:  # unreadable 사유 — 재렌더 외에 따라할 단계가 없다.
+        return f'<p class="approval-disabled-reason">{html.escape(ctx.disabled_reason)}</p>'
+    sidecar_dir = f"runs/{run_meta.task_type}/user-responses/"
+    ids = ", ".join(ctx.blocker_ids)
+    steps = [
+        f"위 <strong>§1 Clarification Items</strong> 표에서 차단 항목 "
+        f"<strong>{html.escape(ids)}</strong> 의 'User input' 칸에 답을 입력합니다.",
+        "헤더 또는 맨 아래의 <strong>[Export user response]</strong> 버튼을 눌러 응답 파일을 내려받습니다.",
+        f"내려받은 파일을 <code>{html.escape(sidecar_dir)}</code> 에 그대로 저장합니다.",
+        f"터미널에서 <code>scripts/okstra.sh --resume-clarification --task-key "
+        f"{html.escape(run_meta.task_key)}</code> (Claude Code 에서는 "
+        f"<code>/okstra-run resume-clarification task-key={html.escape(run_meta.task_key)}</code>) "
+        "을 실행합니다.",
+        "명령이 끝나면 <strong>새로 생성된 보고서</strong>를 여세요 — "
+        "그 보고서에서 이 체크박스가 활성화됩니다.",
+    ]
+    lis = "".join(f"<li>{s}</li>" for s in steps)
+    return (
+        '<div class="approval-disabled-reason">'
+        f"<p><strong>{html.escape(ctx.disabled_reason)}</strong>라 아직 승인할 수 없습니다. "
+        "이 화면에서 답만 입력해서는 풀리지 않습니다 — 아래 순서로 해소하세요:</p>"
+        f'<ol class="approval-steps">{lis}</ol>'
+        "</div>"
     )
 
 
-def _plan_approval_section(ctx: PlanApprovalContext) -> str:
+def _plan_approval_section(ctx: PlanApprovalContext, run_meta: RunMeta) -> str:
     disabled = " disabled" if ctx.disabled_reason else ""
     opts: list[str] = []
     for name in ctx.option_names:
@@ -883,8 +929,7 @@ def _plan_approval_section(ctx: PlanApprovalContext) -> str:
         attrs = ' data-recommended="true" selected' if is_rec else ""
         opts.append(f'<option value="{html.escape(name)}"{attrs}>{html.escape(label)}</option>')
     reason_html = (
-        f'\n  <p class="approval-disabled-reason">{html.escape(ctx.disabled_reason)}</p>'
-        if ctx.disabled_reason else ""
+        "\n  " + _approval_blocked_guidance(ctx, run_meta) if ctx.disabled_reason else ""
     )
     return (
         '<section id="plan-approval">\n'

package/runtime/python/okstra_ctl/wizard.py

@@ -18,7 +18,9 @@ imports this module directly.
 """
 from __future__ import annotations
 
+import copy
 import json
+import math
 import re
 import subprocess
 from dataclasses import asdict, dataclass, field
@@ -3235,6 +3237,83 @@ def next_prompt(state: WizardState) -> Prompt:
     return Prompt(step=S_DONE, kind="done")
 
 
+def _passed_screens(state: WizardState) -> int:
+    """이미 답한 화면 수. pick_group 멤버는 GROUP_MAX_TABS 묶음당 1화면으로 환산."""
+    count = 0
+    group_hits: dict[str, int] = {}
+    for sid in state.answered:
+        gid = _STEP_TO_GROUP.get(sid)
+        if gid is None:
+            count += 1
+        else:
+            group_hits[gid] = group_hits.get(gid, 0) + 1
+    for hits in group_hits.values():
+        count += math.ceil(hits / GROUP_MAX_TABS)
+    return count
+
+
+def _sim_answer(prompt: Prompt) -> str:
+    """분모 추정 시뮬레이션의 기본답: pick 은 첫 옵션(추천), text 는 빈 값."""
+    if prompt.kind == "pick" and prompt.options:
+        return prompt.options[0].value
+    return ""
+
+
+def _sim_advance(state: WizardState, prompt: Prompt) -> None:
+    """기본답으로 한 화면 전진한다. progress 를 재계산하는 submit()/
+    _submit_group() 은 호출하지 않고 step.submit 만 직접 호출해 재귀를 막는다."""
+    try:
+        if prompt.kind == "pick_group":
+            for q in prompt.questions:
+                STEP_BY_ID[q.step].submit(state, _sim_answer(q))
+            for q in prompt.questions:
+                if q.step not in state.answered:
+                    state.answered.append(q.step)
+            return
+        STEP_BY_ID[prompt.step].submit(state, _sim_answer(prompt))
+        if prompt.step not in state.answered:
+            state.answered.append(prompt.step)
+    except Exception:
+        # 추천 경로가 막히는 드문 text 분기: answered 마킹만으로 전진시킨다.
+        members = prompt.questions if prompt.kind == "pick_group" else [prompt]
+        for p in members:
+            if p.step not in state.answered:
+                state.answered.append(p.step)
+
+
+def _remaining_screens(state: WizardState) -> int:
+    """현재 화면부터 confirm(=done 직전)까지 남은 화면 수를 시뮬레이션으로 센다."""
+    sim = copy.deepcopy(state)
+    screens = 0
+    for _ in range(len(STEPS) * 2 + 5):  # Edit 루프 등에 대한 상한 가드
+        try:
+            prompt = next_prompt(sim)
+        except Exception:
+            break
+        if prompt.kind in ("done", "aborted"):
+            break
+        screens += 1
+        _sim_advance(sim, prompt)
+        if prompt.step == S_CONFIRM:  # confirm 이후는 done — Edit 는 가정하지 않는다
+            break
+    return screens
+
+
+def _screen_progress(state: WizardState) -> dict[str, int]:
+    passed = _passed_screens(state)
+    total = passed + _remaining_screens(state)
+    index = passed + 1
+    return {"index": index, "total": total, "remaining": max(0, total - index)}
+
+
+def prompt_payload(state: WizardState, prompt: Prompt) -> dict[str, Any]:
+    """Prompt JSON 에 진행 카운터를 덧붙인다. done/aborted 는 progress 를 생략."""
+    out = prompt.to_json()
+    if prompt.kind not in ("done", "aborted"):
+        out["progress"] = _screen_progress(state)
+    return out
+
+
 def _submit_group(state: WizardState, prompt: Prompt, value: str) -> dict[str, Any]:
     """pick_group 답(JSON 객체)을 각 멤버 submit() 으로 라우팅한다.
 
@@ -3258,7 +3337,7 @@ def _submit_group(state: WizardState, prompt: Prompt, value: str) -> dict[str, A
         if q.step not in state.answered:
             state.answered.append(q.step)
     nxt = next_prompt(state)
-    return {"echo": "; ".join(echoes), "next": nxt.to_json()}
+    return {"echo": "; ".join(echoes), "next": prompt_payload(state, nxt)}
 
 
 def submit(state: WizardState, value: str) -> dict[str, Any]:
@@ -3269,7 +3348,7 @@ def submit(state: WizardState, value: str) -> dict[str, Any]:
     """
     prompt = next_prompt(state)
     if prompt.kind in ("done", "aborted"):
-        return {"echo": "", "next": prompt.to_json()}
+        return {"echo": "", "next": prompt_payload(state, prompt)}
     if prompt.kind == "pick_group":
         return _submit_group(state, prompt, value)
     step = STEP_BY_ID[prompt.step]
@@ -3277,7 +3356,7 @@ def submit(state: WizardState, value: str) -> dict[str, Any]:
     if prompt.step not in state.answered:
         state.answered.append(prompt.step)
     nxt = next_prompt(state)
-    return {"echo": echo or "", "next": nxt.to_json()}
+    return {"echo": echo or "", "next": prompt_payload(state, nxt)}
 
 
 def render_args(state: WizardState) -> dict[str, str]:
@@ -3471,7 +3550,7 @@ def _cli(argv: list[str]) -> int:
             state.critic = args.critic
         save_state_file(state_path, state)
         first = next_prompt(state)
-        print(json.dumps({"ok": True, "next": first.to_json()},
+        print(json.dumps({"ok": True, "next": prompt_payload(state, first)},
                          ensure_ascii=False, indent=2))
         return 0
 
@@ -3497,13 +3576,13 @@ def _cli(argv: list[str]) -> int:
             return 2
         try:
             if args.no_submit:
-                result = {"echo": "", "next": next_prompt(state).to_json()}
+                result = {"echo": "", "next": prompt_payload(state, next_prompt(state))}
             else:
                 result = submit(state, args.answer)
         except WizardError as exc:
             save_state_file(state_path, state)
             print(json.dumps({"ok": False, "error": str(exc),
-                              "current": next_prompt(state).to_json()},
+                              "current": prompt_payload(state, next_prompt(state))},
                              ensure_ascii=False, indent=2))
             return 0
         save_state_file(state_path, state)

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

@@ -28,9 +28,12 @@ Every wizard call returns JSON. The two shapes you'll see:
 
 ```json
 { "ok": true, "echo": "task-group: backend-api",
-  "next": { "step": "task_id", "kind": "text", "label": "...", "options": [], "echoTemplate": "..." } }
+  "next": { "step": "task_id", "kind": "text", "label": "...", "options": [], "echoTemplate": "...",
+            "progress": { "index": 5, "total": 11, "remaining": 6 } } }
 ```
 
+Every non-terminal `next` carries a `progress` object (`done` / `aborted` omit it). `index` is the 1-based number of the **current screen** (pick_group counts as one screen), `total` is the wizard's estimate of the full screen count, and `remaining` = `total − index`. The total is a forward estimate from the current answers, so it may grow by a few when the user opens a branch (e.g. choosing *Customize* adds the model screen). **Always suffix the rendered prompt with the progress marker** — see Step 3.
+
 ```json
 { "ok": false, "error": "approved plan has no APPROVED marker: ...",
   "current": { "step": "approved_plan", "kind": "text", "label": "..." } }
@@ -93,7 +96,7 @@ Output: the same `{ok, next}` JSON described above. The first `next` is always `
 
 Repeat until `next.kind == "done"` (or `"aborted"` — terminal cancel, see "How the wizard talks to you"):
 
-1. **Render** the prompt according to `kind` (and `multi` for pick):
+1. **Render** the prompt according to `kind` (and `multi` for pick). **Always append the progress marker to the rendered question label** (the `AskUserQuestion` question text, or the `text`-prompt message): suffix `label` with ` (Step <index>/<total> · 남은 <remaining>단계)`, using `next.progress`. When `remaining == 0` (the final `confirm` screen), use `(Step <index>/<total> · 마지막 단계)` instead. Example: `모델을 선택하세요 (Step 8/11 · 남은 3단계)`. Re-prompts after `ok: false` reuse `current.progress` the same way. The progress marker is presentation-only — never send it back to the wizard as part of an answer.
    - `pick` + `multi: false` → `AskUserQuestion` with `multiSelect: false`, `label`, and `options`. The user's chosen option's `value` is the answer string.
    - `pick` + `multi: true` → `AskUserQuestion` with `multiSelect: true`, `label`, and `options`. Join the selected `value`s with `,` into a single literal CSV string (e.g. `"claude,codex,antigravity"`) and submit it as a single `--answer "claude,codex,antigravity"`. Empty selection submits `--answer ""` and the wizard re-prompts.
    - `pick_group` → one `AskUserQuestion` with one question per `questions[]` entry (tab). Map each tab's selected `value` back by `questions[].step`, assemble a JSON object, and submit it as a single literal `--answer '<json>'`.

package/runtime/templates/reports/report.css

@@ -207,7 +207,16 @@ button[data-action]:hover { background: color-mix(in srgb, Highlight 20%, Button
 #plan-approval h2 { margin-top: 0; }
 #plan-approval label { display: block; margin: 0.4em 0; }
 #plan-approval select { font: inherit; max-width: 100%; }
-.approval-disabled-reason { color: GrayText; margin: 0.4em 0 0; }
+.approval-disabled-reason {
+  margin: 0.6em 0 0;
+  padding: 0.7em 0.9em;
+  border-radius: 4px;
+  background: color-mix(in srgb, Highlight 12%, transparent);
+  border: 1px solid color-mix(in srgb, Highlight 45%, transparent);
+}
+.approval-disabled-reason p { margin: 0 0 0.5em; }
+.approval-steps { margin: 0.3em 0 0; padding-left: 1.4em; }
+.approval-steps li { margin: 0.25em 0; }
 
 @media print {
   .report-header, .report-footer { position: static; }

package/runtime/templates/reports/settings.template.json

@@ -48,6 +48,26 @@
           }
         ]
       }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$HOME/.okstra/bin/okstra-subagent-reclaim.sh"
+          }
+        ]
+      }
+    ],
+    "TaskCompleted": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$HOME/.okstra/bin/okstra-subagent-reclaim.sh"
+          }
+        ]
+      }
     ]
   }
 }