okstra 0.172.0 → 0.174.0

package/runtime/python/okstra_ctl/wizard.py

@@ -82,6 +82,11 @@ from okstra_ctl.design_prep import (
     resolve_design_prep,
     write_design_prep_input,
 )
+from okstra_ctl.implementation_direction import (
+    DirectionSelectionError,
+    lexical_absolute_path,
+    validate_task_artifact_path,
+)
 from okstra_ctl.final_report_paths import final_report_data_path
 from okstra_ctl.plan_run_root import list_implementation_planning_reports
 from okstra_ctl.pr_template import PrTemplateError, resolve_pr_template_path
@@ -154,6 +159,7 @@ TASK_TYPES: list[tuple[str, str]] = [
     ("improvement-discovery", "Find improvement candidates within a codebase scope and lens whitelist"),
     *zip(ANALYSIS_TASK_TYPES, _ANALYSIS_TASK_TYPE_DESCRIPTIONS),
     ("error-analysis", "Evidence-based root-cause analysis (no code changes)"),
+    ("implementation-option-selection", "Compare implementation options (read-only)"),
     ("implementation-planning", "Plan options + request user approval"),
     ("implementation", "Execute approved plan (requires approved final-report)"),
     ("final-verification", "Acceptance + residual-risk review"),
@@ -331,6 +337,7 @@ S_ANALYSIS_TARGET_PICK = "analysis_target_pick"
 S_ANALYSIS_TARGET = "analysis_target"
 S_BASE_REF_PICK = "base_ref_pick"
 S_BASE_REF_TEXT = "base_ref_text"
+S_SELECTED_DIRECTION_PICK = "selected_direction_pick"
 S_APPROVED_PLAN_PICK = "approved_plan_pick"
 S_APPROVED_PLAN = "approved_plan"
 S_APPROVE_PLAN_CONFIRM = "approve_plan_confirm"
@@ -495,6 +502,7 @@ class WizardState:
     clarification_response_path: str = ""
     clarification_pending_text: bool = False
     last_final_report_cached: str = ""
+    selected_direction_path: str = ""
     # "" | "auto" | "full" | "<stage csv>" — 사용자가 고른 이번 재실행의 재검증
     # 범위. implementation-planning 재실행에서 좁힐 여지가 있을 때만 채워진다.
     reverify_scope: str = ""
@@ -595,6 +603,105 @@ def _require_file(path_str: str, project_root: Path, label: str) -> Path:
     return p
 
 
+_SELECTION_REPORT_RE = re.compile(
+    r"^final-report-implementation-option-selection-(?P<seq>\d{3,})\.md$"
+)
+
+
+def _selected_direction_candidates(state: WizardState) -> list[str]:
+    if not state.project_root or not state.task_group or not state.task_id:
+        return []
+    project_root = Path(state.project_root).resolve()
+    task_root = lexical_absolute_path(
+        task_dir(project_root, state.task_group, state.task_id)
+    )
+    reports = (
+        task_runs_dir(project_root, state.task_group, state.task_id)
+        / "implementation-option-selection"
+        / "reports"
+    )
+    candidates: list[tuple[int, Path]] = []
+    for report in reports.glob("final-report-implementation-option-selection-*.md"):
+        match = _SELECTION_REPORT_RE.fullmatch(report.name)
+        if match is None:
+            continue
+        try:
+            validated = validate_task_artifact_path(
+                report, task_root, "selection report"
+            )
+        except DirectionSelectionError:
+            continue
+        candidates.append((int(match.group("seq")), validated))
+    return [
+        _project_relative_path(path, project_root)
+        for _, path in sorted(candidates, reverse=True)[:3]
+    ]
+
+
+def _planning_rerun_selected(state: WizardState) -> bool:
+    if (
+        not state.clarification_response_path
+        or not state.project_root
+        or not state.task_group
+        or not state.task_id
+    ):
+        return False
+    project_root = Path(state.project_root).resolve()
+    raw_path = Path(state.clarification_response_path).expanduser()
+    path = lexical_absolute_path(
+        raw_path if raw_path.is_absolute() else project_root / raw_path
+    )
+    task_root = lexical_absolute_path(
+        task_dir(project_root, state.task_group, state.task_id)
+    )
+    reports = lexical_absolute_path(
+        task_runs_dir(project_root, state.task_group, state.task_id)
+        / "implementation-planning"
+        / "reports"
+    )
+    try:
+        validate_task_artifact_path(path, task_root, "planning report")
+    except DirectionSelectionError:
+        return False
+    return (
+        path.is_file()
+        and not path.is_symlink()
+        and re.fullmatch(
+            r"final-report-implementation-planning-\d{3,}\.md", path.name
+        )
+        is not None
+        and path.parent == reports
+    )
+
+
+def _build_selected_direction_pick(state: WizardState) -> Prompt:
+    candidates = _selected_direction_candidates(state)
+    t = _p(state.workspace_root, S_SELECTED_DIRECTION_PICK)
+    if not candidates:
+        raise WizardError(t["errors"]["none"])
+    return Prompt(
+        step=S_SELECTED_DIRECTION_PICK,
+        kind="pick",
+        label=t["label"],
+        options=[_opt(path, path) for path in candidates],
+        echo_template=t["echo_template"],
+    )
+
+
+def _submit_selected_direction_pick(
+    state: WizardState, value: str
+) -> Optional[str]:
+    candidates = _selected_direction_candidates(state)
+    if value not in candidates:
+        raise WizardError(
+            _p(state.workspace_root, S_SELECTED_DIRECTION_PICK)["errors"][
+                "unknown"
+            ].format(value=value)
+        )
+    state.selected_direction_path = value
+    return f"selected-direction: {value}"
+
+
 def _data_json_approved_state(plan_path: Path) -> Optional[bool]:
     """`approved` flag of the sibling final-report data.json (the SSOT).
 
@@ -621,6 +728,18 @@ def _classify_approved_plan(path_str: str, project_root: Path) -> tuple[Path, bo
     ``already_fully_approved=False`` — the approve-confirm step offers to flip it.
     """
     p = _require_file(path_str, project_root, "approved plan")
+    loaded = _load_final_report_data_if_present(p)
+    if loaded is not None:
+        planning = loaded[1].get("implementationPlanning")
+        if (
+            isinstance(planning, dict)
+            and planning.get("planningContract") == "selected-direction"
+            and planning.get("outcome") == "direction-invalidated"
+        ):
+            raise WizardError(
+                "direction-invalidated planning reports are not approvable; "
+                "re-enter implementation-option-selection"
+            )
     body = p.read_text(encoding="utf-8", errors="replace")
     frontmatter = _extract_frontmatter_block(body)
     if frontmatter is None:
@@ -690,6 +809,14 @@ def _find_html_approval_sidecar(
     승인이 아닌 판정(반려·재작업 요청)은 여기서 걸러진다 — 이 단계가 묻는 것은
     "사용자가 이 plan 을 승인해 두었는가" 뿐이고, 반려 사유는 다음 planning
     run 이 sidecar 를 통째로 읽어 처리한다."""
+    loaded = _load_final_report_data_if_present(plan_path)
+    if loaded is not None:
+        planning = loaded[1].get("implementationPlanning")
+        if (
+            isinstance(planning, dict)
+            and planning.get("planningContract") == "selected-direction"
+        ):
+            return None
     responses_dir = plan_path.parent.parent / "user-responses"
     if not responses_dir.is_dir():
         return None
@@ -4175,6 +4302,19 @@ STEPS: list[Step] = [
          applies=lambda s: s.base_ref_pending_text,
          build=_build_base_ref_text, submit=_submit_base_ref_text,
          owns=("base_ref", "base_ref_pending_text")),
+    Step(S_SELECTED_DIRECTION_PICK,
+         applies=lambda s: (
+             s.task_type == "implementation-planning"
+             and not s.selected_direction_path
+             and not _planning_rerun_selected(s)
+             and _brief_resolved(s)
+             and _base_ref_ready(s)
+             and not s.base_ref_pending_text
+             and S_SELECTED_DIRECTION_PICK not in s.answered
+         ),
+         build=_build_selected_direction_pick,
+         submit=_submit_selected_direction_pick,
+         owns=("selected_direction_path",)),
     Step(S_APPROVED_PLAN_PICK,
          applies=lambda s: (s.task_type in _STAGE_SCOPED_TASK_TYPES
                             and not s.approved_plan_path
@@ -4556,6 +4696,7 @@ _FIELD_DEFAULTS: dict[str, Any] = {
     "directive_pending_text": False,
     "related_tasks_raw": "", "related_tasks_pending_text": False,
     "clarification_response_path": "", "clarification_pending_text": False,
+    "selected_direction_path": "",
     "reverify_scope": "", "reverify_scope_pending_text": False,
     "pr_template_path": "", "pr_template_pending_text": False,
     "pr_template_scope": "",
@@ -4924,6 +5065,7 @@ def render_args(state: WizardState) -> dict[str, str]:
         "report-writer-model": state.report_writer_model,
         "related-tasks": state.related_tasks_raw,
         "clarification-response": state.clarification_response_path,
+        "selected-direction": state.selected_direction_path,
         "reverify-scope": (
             state.reverify_scope
             if state.task_type == "implementation-planning" else ""
@@ -5080,6 +5222,8 @@ def confirmation_block(state: WizardState) -> str:
         reverify_line = _reverify_scope_line(state)
         if reverify_line is not None:
             lines.append(reverify_line)
+    if state.selected_direction_path:
+        lines.append(f"  selected-direction: {state.selected_direction_path}")
     if state.task_type == "release-handoff" and state.handoff_mode:
         scope = (
             _msg(state.workspace_root, "confirmation",

package/runtime/python/okstra_ctl/worker_prompt_policy.py

@@ -51,6 +51,7 @@ FINAL_VERIFICATION_HEADERS = (
 SUPPORTED_TASK_TYPES = frozenset({
     "requirements-discovery",
     "error-analysis",
+    "implementation-option-selection",
     "implementation-planning",
     "improvement-discovery",
     "implementation",
@@ -67,6 +68,7 @@ ANALYSIS_DUTY_BY_TASK_TYPE: dict[str, AgentAudience] = {
     "requirements-discovery": "discovery-worker",
     "improvement-discovery": "discovery-worker",
     "error-analysis": "diagnosis-worker",
+    "implementation-option-selection": "direction-selection-worker",
     "implementation-planning": "planning-worker",
 }
 WORKER_PREAMBLE_FILENAME_BY_AUDIENCE = {

package/runtime/python/okstra_ctl/worker_request.py

@@ -35,6 +35,7 @@ def build_request(
     worktree_path: Path | None,
     role: str,
     idle_timeout_seconds: int,
+    session_id: str = "",
 ) -> WorkerExecRequest:
     """One dispatch, with every value the strategies will not re-derive.
 
@@ -55,6 +56,7 @@ def build_request(
             auto_approve=True, write_scope=write_scope(root, worktree, role)
         ),
         idle_timeout_seconds=idle_timeout_seconds,
+        session_id=session_id,
     )
 
 

package/runtime/python/okstra_ctl/workflow.py

@@ -17,22 +17,34 @@ from okstra_ctl.analysis_inputs import ANALYSIS_TASK_TYPES
 PHASE_SEQUENCE = [
     "requirements-discovery",
     "error-analysis",
+    "implementation-option-selection",
     "implementation-planning",
     "implementation",
     "final-verification",
     "release-handoff",
 ]
 
+REQUIREMENTS_DISCOVERY_ROUTING_TARGETS = frozenset(
+    {"error-analysis", "implementation-option-selection"}
+)
+
+ERROR_ANALYSIS_ROUTING_DIRECTIONS = {
+    "error-analysis": "continue-investigation",
+    "implementation-option-selection": "begin-option-selection",
+}
+
 DEFAULT_NEXT_PHASE = {
-    "requirements-discovery": "pending-routing-decision",
+    "requirements-discovery": "implementation-option-selection",
     "improvement-discovery": "pending-routing-decision",
     **{task_type: "pending-routing-decision" for task_type in ANALYSIS_TASK_TYPES},
-    "error-analysis": "implementation-planning",
+    "error-analysis": "implementation-option-selection",
+    "implementation-option-selection": "implementation-planning",
     "implementation-planning": "implementation",
     "implementation": "final-verification",
     # final-verification 의 다음 단계는 verdict 에 따라 갈리므로 정적 매핑은
     # `pending-release-handoff` 로 둔다 (accepted 일 때만 release-handoff 로
-    # 진입; 그 외에는 error-analysis / implementation-planning 으로 리라우팅).
+    # 진입; 그 외에는 error-analysis / implementation-option-selection /
+    # implementation-planning 으로 리라우팅).
     "final-verification": "pending-release-handoff",
     "release-handoff": "done-or-follow-up",
 }
@@ -87,12 +99,22 @@ PHASE_RULES: dict[str, dict[str, str]] = {
             "  - one endStateCoverage row per brief end-state id (this phase authors no goal of its own)"
         ),
     },
+    "implementation-option-selection": {
+        "allowed": (
+            "  - candidate-comparison evidence for up to three options per worker\n"
+            "  - preselected-validation that re-evaluates the merged candidate set\n"
+            "  - a ranked display of at most three options with requirement mappings\n"
+            "  - an audit record for every rejected candidate\n"
+            "  - one endStateCoverage row per brief end-state id (this phase authors no goal of its own)"
+        ),
+    },
     "implementation-planning": {
         "allowed": (
             "  - pre-planning context exploration notes (files/interfaces inspected, recent commits scanned, ambiguities flagged)\n"
-            "  - at least two implementation option candidates, each with a File Structure list (Create/Modify/Delete with one-line responsibility per file), affected interfaces, and blast-radius estimate\n"
-            "  - trade-off matrix across options (complexity, risk, reversibility, test cost, rollout cost) and recommended option with rationale tied to isolation / single-responsibility / YAGNI principles\n"
-            "  - bite-sized stepwise execution order for the recommended option (each step ~2-5 min, exact file paths and commands, TDD ordering when applicable, no placeholders)\n"
+            "  - selected-direction planning: realize the one validated selected direction without reopening candidate comparison, with a File Structure list (Create/Modify/Delete with one-line responsibility per file), affected interfaces, and blast-radius estimate\n"
+            "  - legacy candidate-comparison planning only: at least two implementation option candidates, each with a File Structure list (Create/Modify/Delete with one-line responsibility per file), affected interfaces, and blast-radius estimate\n"
+            "  - legacy candidate-comparison planning only: a trade-off matrix across options (complexity, risk, reversibility, test cost, rollout cost) and recommended option with rationale tied to isolation / single-responsibility / YAGNI principles\n"
+            "  - bite-sized stepwise execution order for the selected direction or legacy recommended option (each step ~2-5 min, exact file paths and commands, TDD ordering when applicable, no placeholders)\n"
             "  - dependency / migration risk assessment, validation checklist (pre / mid / post with exact commands), rollback strategy with revert path and trigger signal\n"
             "  - every unresolved ambiguity registered as a `Blocks=approval` row in the `## 1. Clarification Items` table (do NOT create a separate `Open Questions` block under `5.5.x` — the unified table is the single home)\n"
             "  - YAML frontmatter line `approved: false` awaiting human flip to `true`\n"
@@ -117,7 +139,7 @@ PHASE_RULES: dict[str, dict[str, str]] = {
         "allowed": (
             "  - acceptance verdict with requirement coverage assessment\n"
             "  - residual risk and regression notes\n"
-            "  - recommended follow-up routing (`error-analysis` / `implementation-planning` / `release-handoff`) for any defects detected"
+            "  - recommended follow-up routing (`error-analysis` / `implementation-option-selection` / `implementation-planning` / `release-handoff`) for any defects detected"
         ),
     },
     "release-handoff": {

package/runtime/python/okstra_ctl/worktree.py

@@ -77,6 +77,27 @@ DEFAULT_WORKTREE_SYNC_DIRS: tuple[str, ...] = (
 )
 
 
+# Sync dirs materialised as a REAL directory whose children are symlinked one
+# by one, instead of a single symlink standing in for the whole directory.
+#
+# Why the split exists: git does not follow a symlink, so a symlinked directory
+# is one *file* to it. A project that ignores host config by its contents
+# (`.claude/*`) matches every child but never the bare `.claude` path, so the
+# symlink lands in `git status` as
+# `?? .claude` while the same directory is invisible in the main checkout. Any
+# plan step asserting a clean worktree then fails on okstra's own provisioning.
+# Linking the children instead reproduces the main checkout's shape, so
+# whatever the project's ignore rules do there, they do here too.
+#
+# Only `.claude` qualifies. The other sync dirs are shared okstra state that
+# okstra WRITES into, and a directory symlink is what makes a newly created
+# top-level entry land in the main checkout rather than diverging inside the
+# worktree. `.claude` is host configuration okstra reads; its one okstra write
+# is the fixed `settings.local.json` child seeded by
+# `_seed_worktree_settings_symlink`.
+CHILD_LINKED_SYNC_DIRS: tuple[str, ...] = (".claude",)
+
+
 # Project-root-relative FILES (not dirs) symlinked from MAIN → task worktree
 # at provision time. Same symlink semantics as `DEFAULT_WORKTREE_SYNC_DIRS`:
 # every task sees the live shared file. The split exists because the original
@@ -522,16 +543,27 @@ def is_ancestor(cwd, commit: str, head: str) -> bool:
     return _git(Path(cwd), "merge-base", "--is-ancestor", commit, head).returncode == 0
 
 
-def is_dirty_excluding_okstra(cwd) -> bool:
-    """True iff the worktree has changes outside okstra-owned paths.
+def dirty_entries_excluding_okstra(cwd) -> list[str]:
+    """`git status --short` rows for changes outside okstra-owned paths.
 
     okstra-owned = `okstra_clean_gate_excludes` (e.g. `.okstra`, synced dirs)
     plus `nested_worktree_excludes` (stage worktrees nested under `cwd`).
+
+    This is the clean-worktree question every okstra gate asks, and the one a
+    plan step must ask through `okstra worktree-status` rather than through a
+    bare `git status --porcelain`: okstra provisions `.okstra` plus the synced
+    entries into every task worktree, so a bare status is never empty there and
+    an assertion built on it fails on okstra's own scaffolding.
     """
     owned = (*okstra_clean_gate_excludes(Path(cwd)), *nested_worktree_excludes(cwd))
     excludes = [f":(exclude){p}" for p in owned]
     out = _git(Path(cwd), "status", "--short", "--", ".", *excludes).stdout
-    return bool(out.strip())
+    return [line for line in out.splitlines() if line.strip()]
+
+
+def is_dirty_excluding_okstra(cwd) -> bool:
+    """True iff the worktree has changes outside okstra-owned paths."""
+    return bool(dirty_entries_excluding_okstra(cwd))
 
 
 class MergeError(RuntimeError):
@@ -580,6 +612,9 @@ def _link_sync_dirs(source_root: Path, worktree_path: Path) -> list[str]:
         version-controlled files.
       - Parent directories are created as needed for nested entries.
 
+    Entries listed in `CHILD_LINKED_SYNC_DIRS` are materialised as a real
+    directory of per-child symlinks instead (see that constant).
+
     Returns a list of human-readable notes (one per linked entry) so the
     caller can include them in the provisioning note.
     """
@@ -592,6 +627,10 @@ def _link_sync_dirs(source_root: Path, worktree_path: Path) -> list[str]:
         if dst.exists() or dst.is_symlink():
             continue
         dst.parent.mkdir(parents=True, exist_ok=True)
+        if rel in CHILD_LINKED_SYNC_DIRS and src.is_dir():
+            _link_dir_children(src, dst)
+            notes.append(rel)
+            continue
         try:
             os.symlink(src, dst)
         except FileExistsError:
@@ -600,6 +639,33 @@ def _link_sync_dirs(source_root: Path, worktree_path: Path) -> list[str]:
     return notes
 
 
+def _link_dir_children(src: Path, dst: Path) -> None:
+    """Create `dst` as a real directory whose entries symlink to `src`'s
+    children, so git sees the same directory shape it sees in the main
+    checkout (`CHILD_LINKED_SYNC_DIRS`).
+
+    Each link points at the MAIN checkout's child rather than its resolved
+    target, so a child that is itself a symlink (e.g. `.claude/settings.local.json`
+    → `~/.okstra/templates/settings.local.json`) keeps following whatever the
+    main checkout currently points at. An unreadable source or a child that
+    cannot be linked degrades to "that child is absent in this worktree" —
+    provisioning is not worth failing over host config.
+    """
+    dst.mkdir(parents=True, exist_ok=True)
+    try:
+        children = sorted(src.iterdir())
+    except OSError:
+        return
+    for child in children:
+        link = dst / child.name
+        if link.exists() or link.is_symlink():
+            continue
+        try:
+            os.symlink(child, link)
+        except OSError:
+            continue
+
+
 def _link_sync_files(source_root: Path, worktree_path: Path) -> list[str]:
     """File-level counterpart to `_link_sync_dirs` (FU-V2).
 

package/runtime/python/okstra_token_usage/cli.py

@@ -57,7 +57,7 @@ def main() -> int:
             "from the freshly computed usageSummary, then re-render the "
             "sibling final-report markdown via the renderer. The data.json "
             "is the SSOT; the markdown is regenerated from it. "
-            "See schemas/final-report-v1.0.schema.json for the data shape."
+            "See schemas/final-report-v2.0.schema.json for the data shape."
         ),
     )
     parser.add_argument(

package/runtime/python/okstra_token_usage/collect.py

@@ -21,6 +21,7 @@ from .antigravity import (
 )
 from .paths import claude_project_dir, utc_now
 from .pricing import antigravity_cost_usd, provider_cost_usd
+from okstra_ctl.dispatch_state import worker_session_ids
 from okstra_ctl.models import provider_wrappers
 from okstra_ctl.wrapper_status import read_wrapper_status, status_path_for_prompt
 
@@ -864,22 +865,66 @@ def collect_claude_runtime_usage(
             f"lead session jsonl not found under {claude_project_dir(cwd)} (sessionId={lead_sid})"
         )
 
-    # 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.).
+    # Workers — dispatch 가 기록한 세션 id 로 짚은 세션과 agentName prefix 로
+    # 찾은 세션의 합집합을 합산한다(재배치 `-002`, convergence `-reverify-r1`,
+    # implementation `-executor`, report-writer `-impl` / `-2` 등).
+    sessions_dir = claude_project_dir(cwd)
+    # sid 로 귀속한 세션 id 전체 — 아래 unattributed 폴드에서 빼는 데 쓴다.
+    attributed_sids: set[str] = set()
     for worker in state.get("workers", []):
         worker_id = worker.get("workerId")
         agent = worker.get("agent")
         prefixes = match_prefixes(worker_id) if worker_id else []
 
+        # pane 워커는 별도 `claude -p` 프로세스라 jsonl 에 agentName 도 teamName
+        # 도 안 남긴다 — 아래 prefix 경로로는 영원히 매칭되지 않는다. dispatch 가
+        # 발급해 적어 둔 이 id 가 그 세션을 짚는 유일한 결정적 단서다. 재시도는
+        # attempt 마다 새 세션이므로 기록된 id 를 전부 합산한다.
+        # 헬퍼에서 worker_id=None 은 "run 전체"라, 이름 없는 워커에 그대로 넘기면
+        # 그 워커가 run 의 모든 세션을 흡수한다.
+        dispatched_sids = worker_session_ids(state, worker_id) if worker_id else []
         matched: list[tuple[str, Path, dict]] = []
+        matched_sids: set[str] = set()
+        for sid in dispatched_sids:
+            path = sessions_dir / f"{sid}.jsonl"
+            if not path.is_file():
+                continue
+            totals = claude_session_totals(path, since=run_since, until=run_until,
+                                           incremental=incremental)
+            # 창 밖 세션은 여기서 버린다 — agentName 발견 경로가 위에서 같은
+            # `startedAt` 검사로 거르는 것과 같은 이유다. 넣으면 0 토큰 totals 가
+            # usage_block 을 타고 "이 워커는 0 을 썼다"로 보고되어, unavailable 로
+            # 남아야 할 상태를 허위 0 이 덮는다.
+            if not totals.get("startedAt"):
+                continue
+            matched.append((sid, path, totals))
+            matched_sids.add(sid)
+            attributed_sids.add(sid)
+
+        # 조건부 폴백이 아니라 합집합이다. 한 워커의 attempt 1 이 pane(sid 로만
+        # 찾힌다), attempt 2 가 in-process 서브에이전트(agentName 으로만 찾힌다)일
+        # 수 있고, `if not matched:` 로 두면 sid 가 하나라도 맞는 순간 attempt 2 의
+        # 토큰이 통째로 누락된다. 양쪽에서 온 같은 세션은 sid 로 한 번만 센다.
         for agent_name, entries in by_agent.items():
-            if agent_matches(agent_name, prefixes):
-                matched.extend(entries)
+            if not agent_matches(agent_name, prefixes):
+                continue
+            for entry in entries:
+                if entry[0] in matched_sids:
+                    continue
+                # team-needle 경로는 창 검사 없이 by_agent 를 채운다. 같은 리드
+                # 세션의 다음 run 이 띄운 워커도 같은 needle 에 걸리는데, 창 밖이라
+                # startedAt 이 없어 아래 정렬에서 맨 앞에 서고 `sessionId` 를
+                # 차지한다 — 토큰은 0 이라 합계는 안 틀리고 리포트가 가리키는
+                # 세션만 남의 것이 된다.
+                if not entry[2].get("startedAt"):
+                    continue
+                matched.append(entry)
+                matched_sids.add(entry[0])
 
         if not matched:
             worker["usage"] = na_block(
-                f"no Claude subagent jsonl found with agentName matching prefixes {prefixes}"
+                "no Claude session jsonl in the run window for dispatched "
+                f"sessionIds {dispatched_sids} or agentName prefixes {prefixes}"
             )
             continue
 
@@ -919,6 +964,21 @@ def collect_claude_runtime_usage(
     # session the harness never tagged with `name`. Without this, the run-level
     # Worker total reads 0 and the report validator hard-fails a legitimate run.
     # Attribution is aggregate, not per-worker; usageSummary records it openly.
+    #
+    # 먼저 sid 로 귀속된 세션을 뺀다. 이 두 집합은 `agentName` 유무로 배타적이었지만
+    # (by_agent 는 있어야 들어가고 unattributed 는 없어야 들어간다) sid 경로는
+    # agentName 을 안 보므로 그 배타성이 더는 성립하지 않는다. team needle 에
+    # 걸리면서 agentName 이 없는 세션이 동시에 기록된 dispatch sid 이기도 하면,
+    # 빼지 않을 경우 그 토큰이 워커 usage 와 이 폴드 양쪽에 들어가 `_populate_usage_summary`
+    # 의 workerTotalTokens 를 부풀린다. 두 리스트는 인덱스가 대응하므로 함께 거른다.
+    kept = [
+        (sid, totals)
+        for sid, totals in zip(unattributed_sessions, unattributed_totals)
+        if sid not in attributed_sids
+    ]
+    unattributed_sessions = [sid for sid, _ in kept]
+    unattributed_totals = [totals for _, totals in kept]
+
     unattributed_usage = None
     if unattributed_totals:
         unattributed_usage = usage_block(