okstra 0.18.2 → 0.19.0

package/docs/kr/architecture.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.18.2",
+  "version": "0.19.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.18.2",
-  "builtAt": "2026-05-13T13:51:20.597Z",
+  "package": "0.19.0",
+  "builtAt": "2026-05-13T15:17:28.853Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

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

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

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

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

package/runtime/python/okstra_ctl/render.py

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

package/runtime/python/okstra_ctl/run.py

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

package/runtime/python/okstra_token_usage/collect.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 import json
+from datetime import datetime
 from pathlib import Path
 from .blocks import na_block, usage_block
 from .claude import claude_session_totals, find_claude_team_sessions
@@ -11,6 +12,76 @@ from .paths import claude_project_dir, utc_now
 from .pricing import codex_cost_usd, gemini_cost_usd
 
 
+def match_prefixes(worker_id: str) -> list[str]:
+    """Return the agentName prefixes that should be attributed to ``worker_id``.
+
+    The Agent harness records the `name` arg on every dispatch as `agentName`
+    in the subagent jsonl. Lead frequently appends suffixes (`-002`,
+    `-reverify-r1`, `-impl`, `-2`) when it dispatches the same role multiple
+    times or in different sub-flows. We treat every `agentName` matching one of
+    these prefixes — either exactly or as `<prefix>-<suffix>` — as belonging
+    to this worker so its tokens get aggregated. For implementation runs the
+    executor variant `<provider>-executor` is also attributed back to the
+    matching provider worker.
+    """
+    if not worker_id:
+        return []
+    if worker_id == "report-writer":
+        return ["report-writer"]
+    prefixes = [worker_id]
+    if not worker_id.endswith("-worker"):
+        prefixes.append(f"{worker_id}-worker")
+        prefixes.append(f"{worker_id}-executor")
+    return prefixes
+
+
+def agent_matches(agent_name: str, prefixes: list[str]) -> bool:
+    if not agent_name:
+        return False
+    for prefix in prefixes:
+        if agent_name == prefix or agent_name.startswith(f"{prefix}-"):
+            return True
+    return False
+
+
+def _aggregate_totals(items: list[dict]) -> dict:
+    """Sum token + tool counters across multiple session totals dicts.
+
+    `startedAt` / `endedAt` collapse to the union window; `durationMs` is
+    recomputed from that window so re-tries and convergence rounds count
+    against a single contiguous span. `model` and `agentName` keep the first
+    non-empty value (the canonical role identity).
+    """
+    aggregate: dict = {
+        "totalTokens": 0, "inputTokens": 0, "outputTokens": 0,
+        "cacheCreationTokens": 0, "cacheReadTokens": 0,
+        "toolUses": 0, "durationMs": 0,
+        "agentName": None, "model": None,
+        "startedAt": None, "endedAt": None,
+    }
+    for t in items:
+        for k in ("totalTokens", "inputTokens", "outputTokens",
+                  "cacheCreationTokens", "cacheReadTokens", "toolUses"):
+            aggregate[k] += t.get(k, 0) or 0
+        if aggregate["agentName"] is None and t.get("agentName"):
+            aggregate["agentName"] = t["agentName"]
+        if aggregate["model"] is None and t.get("model"):
+            aggregate["model"] = t["model"]
+        s, e = t.get("startedAt"), t.get("endedAt")
+        if s and (aggregate["startedAt"] is None or s < aggregate["startedAt"]):
+            aggregate["startedAt"] = s
+        if e and (aggregate["endedAt"] is None or e > aggregate["endedAt"]):
+            aggregate["endedAt"] = e
+    if aggregate["startedAt"] and aggregate["endedAt"]:
+        try:
+            a = datetime.fromisoformat(aggregate["startedAt"].replace("Z", "+00:00"))
+            b = datetime.fromisoformat(aggregate["endedAt"].replace("Z", "+00:00"))
+            aggregate["durationMs"] = max(0, int((b - a).total_seconds() * 1000))
+        except ValueError:
+            pass
+    return aggregate
+
+
 def collect(team_state_path: Path, project_root: Path | None = None) -> dict:
     state = json.loads(team_state_path.read_text())
     cwd = project_root or _infer_project_root(team_state_path, state)
@@ -26,19 +97,20 @@ def collect(team_state_path: Path, project_root: Path | None = None) -> dict:
         team_name = f"okstra-{task_id}" if task_id else ""
     lead_sid = (state.get("lead") or {}).get("sessionId")
 
-    # 1) Claude sessions (lead + claude-side workers).
+    # 1) Claude sessions (lead + claude-side workers). Cache totals at scan
+    # time so we don't re-read the jsonl when a worker matches multiple
+    # sessions.
     claude_sessions = find_claude_team_sessions(cwd, team_name, lead_sid)
-    by_agent: dict[str, tuple[str, Path]] = {}
+    by_agent: dict[str, list[tuple[str, Path, dict]]] = {}
     lead_path: Path | None = None
     for sid, path in claude_sessions.items():
         if sid == lead_sid:
             lead_path = path
             continue
-        # Read agentName lazily.
         totals = claude_session_totals(path)
         agent = totals.get("agentName")
         if agent:
-            by_agent[agent] = (sid, path)
+            by_agent.setdefault(agent, []).append((sid, path, totals))
 
     # Lead.
     if lead_path is not None:
@@ -50,35 +122,39 @@ def collect(team_state_path: Path, project_root: Path | None = None) -> dict:
             f"lead session jsonl not found under {claude_project_dir(cwd)} (sessionId={lead_sid})"
         )
 
-    # Workers.
+    # Workers — match by prefix and aggregate every session that belongs to
+    # the same role (re-dispatches with `-002`, convergence `-reverify-r1`,
+    # implementation `-executor`, report-writer `-impl` / `-2`, etc.).
     for worker in state.get("workers", []):
         worker_id = worker.get("workerId")
         agent = worker.get("agent")
-        # Subagent agentName convention: workerId itself is "claude" but agentName is "claude-worker"; report-writer == "report-writer".
-        agent_name_candidates = []
-        if worker_id:
-            agent_name_candidates.append(worker_id)
-            if not worker_id.endswith("-worker") and worker_id != "report-writer":
-                agent_name_candidates.append(f"{worker_id}-worker")
-
-        # Claude wrapper jsonl (also for codex/gemini-worker, since these are Claude subagents).
-        wrapper = None
-        for cand in agent_name_candidates:
-            if cand in by_agent:
-                wrapper = by_agent[cand]
-                break
-        if wrapper is None:
-            worker["usage"] = na_block(f"no Claude subagent jsonl found with agentName matching {agent_name_candidates}")
+        prefixes = match_prefixes(worker_id) if worker_id else []
+
+        matched: list[tuple[str, Path, dict]] = []
+        for agent_name, entries in by_agent.items():
+            if agent_matches(agent_name, prefixes):
+                matched.extend(entries)
+
+        if not matched:
+            worker["usage"] = na_block(
+                f"no Claude subagent jsonl found with agentName matching prefixes {prefixes}"
+            )
             continue
-        sid, path = wrapper
-        totals = claude_session_totals(path)
-        block = usage_block(totals, source="claude-jsonl")
-        block["sessionId"] = sid
 
-        # For codex/gemini workers, also try to find the underlying CLI session
-        # within the wrapper subagent's time window.
-        wrapper_start = totals.get("startedAt") or ""
-        wrapper_end = totals.get("endedAt") or ""
+        # Stable order by startedAt so the "primary" session is the first one.
+        matched.sort(key=lambda x: x[2].get("startedAt") or "")
+        primary_sid, _primary_path, _primary_totals = matched[0]
+        aggregate = _aggregate_totals([t for _, _, t in matched])
+        block = usage_block(aggregate, source="claude-jsonl")
+        block["sessionId"] = primary_sid
+        if len(matched) > 1:
+            block["additionalSessionIds"] = [sid for sid, _, _ in matched[1:]]
+            block["matchedAgentNames"] = sorted({t.get("agentName") for _, _, t in matched if t.get("agentName")})
+
+        # For codex/gemini workers, find every CLI session that fell inside the
+        # aggregated wrapper window.
+        wrapper_start = aggregate.get("startedAt") or ""
+        wrapper_end = aggregate.get("endedAt") or ""
         if agent in ("codex", "gemini"):
             if agent == "codex":
                 cli = find_codex_session(cwd, wrapper_start, wrapper_end)

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

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

package/runtime/skills/okstra-report-writer/SKILL.md

@@ -90,7 +90,7 @@ Behaviour contract:
 After the spawner completes, the report-writer worker MUST update Section 6 ("Recommended Next Steps") to list every newly created task-key together with its entry command, so the user can pick the follow-up up immediately:
 
 ```
-- Follow-up: `<task-group>/<new-task-id>` — `okstra --task-key <task-group>/<new-task-id> --task-type <suggested>`
+- Follow-up: `<task-group>/<new-task-id>` — Claude Code 세션 안 `/okstra-run task-key=<task-group>/<new-task-id> task-type=<suggested>` / 별도 터미널 `scripts/okstra.sh --task-key <task-group>/<new-task-id> --task-type <suggested>`
 ```
 
 ## Phase 7 token-usage collector (BLOCKING)

package/runtime/templates/reports/final-report.template.md

@@ -13,8 +13,12 @@
 > 다음 `implementation` run은 아래 체크박스가 `[x]`로 표시되어 있을 때에만 진입할 수 있습니다 (`okstra_ctl.run._validate_approved_plan` 가 이 마커를 line-anchored 정규식으로 검사하여 통과/거부합니다). 본문(`Sections 1`–`4.5`)을 끝까지 읽고, `4.5.9 Open Questions`가 비어 있거나 모두 해소된 뒤 승인해 주세요.
 
 - 승인 여부 (사용자가 직접 편집): `- [ ] Approved` ← 승인하려면 `[ ]` 를 `[x]` 로 변경하여 저장하세요.
-- 승인 후 다음 단계 명령어 (방법 A — 수동 편집): `okstra --task-key {{TASK_KEY}} --task-type implementation --approved-plan <이 보고서 경로>`
-- 승인 + 실행 한 번에 (방법 B — CLI 자체를 승인 의사로): `okstra --task-key {{TASK_KEY}} --task-type implementation --approved-plan <이 보고서 경로> --approve`
+- 승인 후 다음 단계 명령어 (방법 A — 수동 편집):
+  - Claude Code 세션 안: `/okstra-run task-key={{TASK_KEY}} task-type=implementation approved-plan=<이 보고서 경로>`
+  - 별도 터미널: `scripts/okstra.sh --task-key {{TASK_KEY}} --task-type implementation --approved-plan <이 보고서 경로>`
+- 승인 + 실행 한 번에 (방법 B — 진입 명령 자체를 승인 의사로):
+  - Claude Code 세션 안: `/okstra-run task-key={{TASK_KEY}} task-type=implementation approved-plan=<이 보고서 경로> approve`
+  - 별도 터미널: `scripts/okstra.sh --task-key {{TASK_KEY}} --task-type implementation --approved-plan <이 보고서 경로> --approve`
   - 방법 B 는 `--approve` 입력 행위 자체를 승인 의사로 모델링합니다. 런타임이 본 블록의 체크박스를 자동으로 `[x]` 로 바꾸고, 본 섹션 하단에 `승인 일시 (CLI ack): <ISO8601>` audit 라인을 한 줄 덧붙입니다.
 - 승인을 보류하거나 거부하려면 체크박스는 `[ ]` 로 두고 `--approve` 도 사용하지 마세요. 필요한 변경 사항은 `4.5.9 Open Questions` 또는 `Section 5 Clarification Requests` 에 기록한 뒤 같은 phase 를 재실행해 주세요.
 
@@ -270,7 +274,11 @@ H1 이 `skip` 이거나 H3 가 `cancel` 인 경우, 본 섹션 다음의 4.6.4 ~
   - `resolved`: 다음 run에서 lead가 답변을 받아 검증을 마쳤습니다.
   - `obsolete`: 이후 분석 결과로 더 이상 필요 없어진 항목입니다.
 
-이 보고서에 답을 채우신 뒤에는 `okstra --resume-clarification --task-key {{TASK_KEY}}` 한 줄로 같은 phase를 다시 실행하실 수 있습니다(자동으로 `$EDITOR`가 이 파일을 열고, 저장하면 같은 phase가 `--clarification-response`로 carry-in 되어 재실행됩니다). 스크립트로 자동화하실 때는 기존 형식 `okstra --task-key {{TASK_KEY}} --task-type {{TASK_TYPE}} --clarification-response <이 파일 경로>`도 그대로 사용하실 수 있습니다.
+이 보고서에 답을 채우신 뒤에는 한 줄로 같은 phase를 다시 실행하실 수 있습니다(자동으로 `$EDITOR`가 이 파일을 열고, 저장하면 같은 phase가 `--clarification-response`로 carry-in 되어 재실행됩니다).
+- Claude Code 세션 안: `/okstra-run resume-clarification task-key={{TASK_KEY}}`
+- 별도 터미널: `scripts/okstra.sh --resume-clarification --task-key {{TASK_KEY}}`
+
+스크립트로 자동화하실 때는 셸 형식 `scripts/okstra.sh --task-key {{TASK_KEY}} --task-type {{TASK_TYPE}} --clarification-response <이 파일 경로>`도 그대로 사용하실 수 있습니다. Node `okstra` admin CLI 는 `--task-key`/`--task-type`/`--resume-clarification` 을 받지 않으므로 위 두 진입점 중 하나를 사용하세요.
 
 ### 5.1 추가 자료 요청 (Additional Materials Requested)
 
@@ -298,16 +306,22 @@ H1 이 `skip` 이거나 H3 가 `cancel` 인 경우, 본 섹션 다음의 4.6.4 ~
 
 This section is **always present** in every final report — never omit the heading. If there are no concrete actions to take, write the single line `- No further action required. Final verdict in section 2 stands.` under the heading and stop.
 
-When concrete actions exist, list them as a numbered list using the rules below. Each item must include the exact command(s) the user can copy-paste. Prefer the `--task-key` shorthand for follow-up runs and `--resume-clarification` for clarification answer turn-arounds; show the equivalent full-args form only when useful.
+When concrete actions exist, list them as a numbered list using the rules below. Each item must include the exact command(s) the user can copy-paste. Show **both** the Claude Code in-session form (`/okstra-run …`) and the external-terminal shell form (`scripts/okstra.sh …`) — the Node `okstra` admin CLI does NOT accept `--task-key` / `--task-type` / `--resume-clarification`. Prefer the `task-key` shorthand for follow-up runs and `resume-clarification` for clarification answer turn-arounds; show the equivalent full-args form only when useful.
 
 1. **Highest-priority next action.** State what to do and why in one sentence, then the command. Example shortcut forms:
-   - Same phase rerun: `okstra --task-key {{TASK_KEY}} --task-type {{TASK_TYPE}}`
-   - Next phase: `okstra --task-key {{TASK_KEY}} --task-type <next-phase>` (omit `--task-type` to use the manifest's `workflow.nextRecommendedPhase` automatically when it is a concrete phase, not `pending-routing-decision` / `done-or-follow-up`).
+   - Same phase rerun:
+     - Claude Code 세션 안: `/okstra-run task-key={{TASK_KEY}} task-type={{TASK_TYPE}}`
+     - 별도 터미널: `scripts/okstra.sh --task-key {{TASK_KEY}} --task-type {{TASK_TYPE}}`
+   - Next phase (omit `task-type` to use the manifest's `workflow.nextRecommendedPhase` automatically when it is a concrete phase, not `pending-routing-decision` / `done-or-follow-up`):
+     - Claude Code 세션 안: `/okstra-run task-key={{TASK_KEY}} task-type=<next-phase>`
+     - 별도 터미널: `scripts/okstra.sh --task-key {{TASK_KEY}} --task-type <next-phase>`
 2. **Additional verification needed before implementation or release.** List read-only checks (test commands, log queries, dashboard URLs) that the user should run before moving to the next phase. No state-mutating commands here.
 3. **Follow-up tasks or related tasks if needed.** Reference them by `task-key` when they already exist; otherwise describe the new brief to draft.
 4. **If section 5 has any `open` rows**, the highest-priority next step MUST be the clarification turn-around. Show both forms:
-   - Preferred (interactive): `okstra --resume-clarification --task-key {{TASK_KEY}}` — opens this file in `$EDITOR`, then auto-reruns the same phase with `--clarification-response` carry-in.
-   - Scripted: `okstra --task-key {{TASK_KEY}} --task-type {{TASK_TYPE}} --clarification-response <path-to-this-file-after-editing>`.
+   - Preferred (interactive) — opens this file in `$EDITOR`, then auto-reruns the same phase with `--clarification-response` carry-in:
+     - Claude Code 세션 안: `/okstra-run resume-clarification task-key={{TASK_KEY}}`
+     - 별도 터미널: `scripts/okstra.sh --resume-clarification --task-key {{TASK_KEY}}`
+   - Scripted: `scripts/okstra.sh --task-key {{TASK_KEY}} --task-type {{TASK_TYPE}} --clarification-response <path-to-this-file-after-editing>`.
 
 Empty-state placeholder, copy verbatim when nothing else applies: