okstra 0.173.0 → 0.174.0

package/runtime/python/okstra_ctl/team.py

@@ -1,9 +1,9 @@
 """Neutral okstra team CLI for pane-backed worker dispatch.
 
-Outside cmux this is the door onto tmux panes for hosts whose descriptor owns
-the team lifecycle. Under cmux it is every lead's door onto cmux surfaces,
-because okstra owns the panes there rather than the host. Which backend a run
-uses is read from its run manifest.
+Under cmux this is every lead's door onto cmux surfaces, because okstra owns the
+panes there rather than the host. Outside cmux a worker owns no pane at all — it
+runs as a cli-wrapper subprocess — so there is nothing for teardown to reclaim.
+Which backend a run uses is read from its run manifest.
 """
 from __future__ import annotations
 
@@ -15,14 +15,13 @@ from pathlib import Path
 from typing import Any, Mapping, Sequence
 
 from . import cmux
-from . import tmux
 from .adapters.dispatch import provider_worker_wrappers
 from .adapters.dispatch.cmux import dispatch_port_for_terminal_backend
 from .application.dispatch_assignments import dispatch_assignments
 from .dispatch_state import TEARDOWN_BEFORE_TERMINAL_REASON, mutate_team_state
 from .dispatch_core import (
+    BACKEND_CLI_WRAPPER,
     BACKEND_CMUX_PANE,
-    BACKEND_TMUX_PANE,
     DispatchError,
     DispatchPlan,
     await_dispatches,
@@ -31,6 +30,7 @@ from .dispatch_core import (
 from .ports.worker_dispatch import WorkerDispatchRequest
 from .registry.host_registry import default_host_registry
 from .registry.provider_registry import default_provider_registry
+from .session import observe_lead_session
 
 
 _SUPPORTED_WRAPPERS = provider_worker_wrappers(default_provider_registry())
@@ -100,6 +100,7 @@ def _dispatch(args) -> int:
     if args.jobs_file and args.workers:
         raise DispatchError("--jobs-file and --workers cannot be combined")
     manifest = _load_manifest(args.project_root, args.run_manifest)
+    _observe_lead_session_from_manifest(Path(args.project_root).resolve(), manifest)
     terminal_backend = _manifest_backend(manifest)
     lead_runtime = _require_string(manifest, "leadRuntime")
     fallback_port = default_host_registry().resolve(
@@ -137,6 +138,7 @@ def _dispatch(args) -> int:
 def _await(args) -> int:
     manifest = _load_manifest(args.project_root, args.run_manifest)
     _validate_team_manifest(manifest)
+    _observe_lead_session_from_manifest(Path(args.project_root).resolve(), manifest)
     plan = _plan_for_existing(Path(args.project_root), Path(args.workspace_root), Path(args.run_manifest), manifest)
     code = await_dispatches(
         plan,
@@ -157,21 +159,46 @@ def _teardown(args) -> int:
     project_root = Path(args.project_root).resolve()
     team_state_path = _resolve_project_path(project_root, _require_string(manifest, "teamStatePath"))
     team_state = _load_json(team_state_path, "team-state")
-    run_dir = _resolve_project_path(project_root, _require_string(manifest, "runDirectoryPath"))
-    panes = _reclaimable_panes(manifest, team_state, run_dir)
+    panes = _reclaimable_panes(manifest, team_state)
     if args.dry_run:
         _emit_teardown(args.json, panes)
         return 0
-    reclaim = cmux.close_surface if _is_cmux_run(manifest) else tmux.kill_pane
-    for pane in panes:
-        reclaim(pane["paneId"])
     if _is_cmux_run(manifest):
+        for pane in panes:
+            cmux.close_surface(pane["paneId"])
         _restore_lead_width()
     _mark_teardown_errors(team_state_path)
     _emit_teardown(args.json, panes)
     return 0
 
 
+def _observe_lead_session_from_manifest(
+    project_root: Path, manifest: Mapping[str, Any]
+) -> None:
+    """Collect this run's lead session generations at a phase boundary.
+
+    Resume and compaction split a lead across several session files, so the one
+    id written at prepare time can name a session holding no record of the run.
+    Dispatch and await are the boundaries a lead cannot route around, which is
+    why the observation hangs off them instead of a call the lead has to make.
+
+    `--dry-run` observes too, because the hook sits ahead of the dry-run return
+    on purpose: moving it behind would lose the generation a lead was on when a
+    dispatch failed. What gets appended is not a rehearsal either — that lead
+    really did cross this boundary, whatever the dispatch went on to do.
+
+    A manifest missing `teamStatePath` leaves nothing to observe into; that is
+    the command's own failure to report, not this side effect's.
+    """
+    try:
+        team_state_path = _resolve_project_path(
+            project_root, _require_string(manifest, "teamStatePath")
+        )
+    except DispatchError:
+        return
+    observe_lead_session(project_root, team_state_path)
+
+
 def _plan_for_existing(
     project_root: Path, workspace_root: Path, run_manifest_path: Path, manifest: Mapping[str, Any]
 ) -> DispatchPlan:
@@ -202,15 +229,16 @@ def _await_payload(plan: DispatchPlan, completed: bool) -> dict[str, Any]:
 
 
 def _reclaimable_panes(
-    manifest: Mapping[str, Any], team_state: Mapping[str, Any], run_dir: Path
+    manifest: Mapping[str, Any], team_state: Mapping[str, Any]
 ) -> list[dict[str, str]]:
     """Everything this run owns and may close.
 
-    Under cmux the recorded ids are the only candidates. There is no per-pane tag
-    API to sweep with, and scanning by title would be worse than nothing: cmux
-    labels its own agent surfaces with the same glyph okstra's tmux cleanup
-    treats as a teammate marker, so a sweep could close the lead. Only surfaces
-    okstra created are recorded, so only those can be closed.
+    The recorded ids are the only candidates. There is no per-pane tag API to
+    sweep with, and scanning by title would be worse than nothing: cmux labels
+    its own agent surfaces with the same glyph the harness uses for a teammate
+    pane, so a sweep could close the lead. Only surfaces okstra created are
+    recorded, so only those can be closed. A cli-wrapper run records no surface
+    at all, which is why it reclaims nothing.
     """
     seen: set[str] = set()
     panes: list[dict[str, str]] = []
@@ -219,17 +247,15 @@ def _reclaimable_panes(
             _append_pane(panes, seen, str(record.get("paneId", "")), "worker")
     if _is_cmux_run(manifest):
         return _still_open_surfaces(panes)
-    lead_pane = tmux.resolve_caller_pane()
-    for pane in tmux.list_run_panes(run_dir, lead_pane=lead_pane):
-        _append_pane(panes, seen, pane.pane_id, pane.kind)
     return panes
 
 
 def _still_open_surfaces(panes: list[dict[str, str]]) -> list[dict[str, str]]:
     """The recorded surfaces cmux still shows.
 
-    `workerDispatches` is append-only and nothing prunes it, so a surface closed
-    at an earlier round boundary stays recorded for the rest of the run. Taking
+    Nothing prunes `workerDispatches` — a repeat of one `dispatchId` replaces
+    that row in place, and no row is ever dropped — so a surface closed at an
+    earlier round boundary stays recorded for the rest of the run. Taking
     the ledger as the residual set makes the run-end cleanup gate offer to close
     panes that left the screen rounds ago, on a workspace holding none.
 
@@ -294,10 +320,10 @@ def _manifest_backend(manifest: Mapping[str, Any]) -> str:
     """The backend prepare recorded for this run.
 
     Deliberately not a flag on this command: the manifest already answers it,
-    and a flag would be a second answer free to disagree. A manifest written
-    before the field existed reads as tmux, which is what those runs used.
+    and a flag would be a second answer free to disagree. A manifest with no
+    recorded backend reads as cli-wrapper, the pane-less path.
     """
-    return str(manifest.get("terminalBackend") or "") or BACKEND_TMUX_PANE
+    return str(manifest.get("terminalBackend") or "") or BACKEND_CLI_WRAPPER
 
 
 def _is_cmux_run(manifest: Mapping[str, Any]) -> bool:

package/runtime/python/okstra_ctl/tmux.py

@@ -1,39 +1,32 @@
-"""tmux command helpers for okstra-owned panes."""
+"""tmux command helpers for okstra-owned container and rerun sessions.
+
+Worker dispatch does not come through here. Workers land in a cmux surface or,
+outside cmux, in a cli-wrapper subprocess — neither owns a tmux pane. What is
+left is the two places that use tmux purely as a way to hold a long-lived
+background process: the container watcher/tail panes and `cmd-rerun.sh`'s
+detached spawn.
+"""
 from __future__ import annotations
 
-import os
 import shlex
 import shutil
 import subprocess
-from dataclasses import dataclass
-from pathlib import Path
 from typing import Optional, Sequence
 
 
-# container watcher/tail pane 전용 태그. SessionEnd `--reap`
-# (scripts/okstra-trace-cleanup.sh `_tag_in_scope`)는 `@okstra_trace_run` /
-# `@okstra_worker_run` 만 스캔하므로, 이 태그가 붙은 pane 은 세션 종료 후에도
-# 생존한다 — watcher/tail 의 "세션 후 생존" 불변식의 핵심.
+# container watcher/tail pane 전용 태그. 이 태그가 붙은 pane 은 세션 종료 후에도
+# 생존한다 — watcher/tail 의 "세션 후 생존" 불변식이다. 예전에는 SessionEnd 의
+# `okstra-trace-cleanup.sh --reap` 이 다른 태그만 스캔한다는 사실이 그 생존을
+# 지탱했지만, 지금은 그 모드와 훅 자체가 없어 pane 을 세션 경계에서 회수하는
+# 주체가 아예 없다. 회수는 `down` / `stop-watcher` 의 스코프 reap 뿐이다.
 CONTAINER_TAG_OPTION = "@okstra_container_run"
 
 
-@dataclass(frozen=True)
-class TmuxPane:
-    pane_id: str
-    title: str
-    run_dir: str
-    kind: str
-
-
 def _shell_quote(s: str) -> str:
     """POSIX shell 안전 인용. shlex.quote 가 모든 메타문자를 처리한다."""
     return shlex.quote(s)
 
 
-def _canonical_run_dir(run_dir: Path) -> str:
-    return str(run_dir.resolve())
-
-
 def build_tmux_command(*, session_name: str, cwd: str, run_seq: int,
                        argv: list, okstra_script: str,
                        extra_env: Optional[dict] = None) -> list:
@@ -69,79 +62,6 @@ def run_tmux(
     )
 
 
-def resolve_caller_pane(start_pid: int | None = None) -> str:
-    try:
-        panes = run_tmux(["list-panes", "-a", "-F", "#{pane_pid} #{pane_id}"])
-    except (OSError, subprocess.SubprocessError):
-        return ""
-    if panes.returncode != 0 or not panes.stdout.strip():
-        return ""
-    pane_by_pid = _pane_ids_by_pid(panes.stdout)
-    pid = str(start_pid or os.getpid())
-    for _ in range(16):
-        if not pid or pid == "0":
-            return ""
-        if pid in pane_by_pid:
-            return pane_by_pid[pid]
-        pid = _parent_pid(pid)
-    return ""
-
-
-def _pane_ids_by_pid(output: str) -> dict[str, str]:
-    result: dict[str, str] = {}
-    for line in output.splitlines():
-        parts = line.split(maxsplit=1)
-        if len(parts) == 2:
-            result[parts[0]] = parts[1]
-    return result
-
-
-def _parent_pid(pid: str) -> str:
-    try:
-        result = subprocess.run(
-            ["ps", "-o", "ppid=", "-p", pid],
-            capture_output=True,
-            text=True,
-            timeout=3,
-            check=False,
-        )
-    except (OSError, subprocess.SubprocessError):
-        return ""
-    if result.returncode != 0:
-        return ""
-    return result.stdout.strip()
-
-
-def split_worker_pane(
-    *,
-    target_pane: str,
-    cwd: Path,
-    command: Sequence[str],
-    title: str,
-    run_dir: Path,
-) -> str:
-    result = run_tmux(
-        [
-            "split-window",
-            "-h",
-            "-P",
-            "-F",
-            "#{pane_id}",
-            "-c",
-            str(cwd),
-            "-t",
-            target_pane,
-            shlex.join(command),
-        ]
-    )
-    if result.returncode != 0:
-        raise RuntimeError(result.stderr.strip() or "tmux split-window failed")
-    pane_id = result.stdout.strip()
-    set_pane_title(pane_id, title)
-    tag_pane(pane_id, run_dir)
-    return pane_id
-
-
 def new_detached_session(
     session_name: str, cwd: str, first_cmd: str | None = None
 ) -> str:
@@ -175,9 +95,9 @@ def split_container_pane(
 ) -> Optional[str]:
     """container watcher/tail pane 을 split 하고 container 전용 태그만 부착한다.
 
-    reap 가 스캔하는 두 worker/trace 태그는 절대 부착하지 않는다 — tag_pane 의
-    기본 경로를 거치지 않고 CONTAINER_TAG_OPTION 으로 직접 set-option 한다.
-    session_pane 가 빈값/None(tmux 미사용 경로)이면 raise 없이 None 반환(degrade).
+    reap 가 스캔하는 trace 태그는 절대 부착하지 않는다 — CONTAINER_TAG_OPTION 으로
+    직접 set-option 한다. session_pane 가 빈값/None(tmux 미사용 경로)이면 raise
+    없이 None 반환(degrade).
     """
     if not session_pane:
         return None
@@ -196,9 +116,9 @@ def split_container_pane(
 def tag_container_pane(pane_id: str, scope_value: str) -> None:
     """container 전용 태그(CONTAINER_TAG_OPTION)만 부착한다.
 
-    reap 가 스캔하는 worker/trace 태그(tag_pane 기본 경로)는 절대 거치지 않는다 —
-    이 태그가 붙은 pane 은 세션 종료 후에도 생존하고 `down`/`stop-watcher` 의
-    스코프 reap 로만 회수된다. holder pane 도 이 태그로 묶어 회수 대상에 포함한다."""
+    reap 가 스캔하는 trace 태그는 절대 거치지 않는다 — 이 태그가 붙은 pane 은
+    세션 종료 후에도 생존하고 `down`/`stop-watcher` 의 스코프 reap 로만
+    회수된다. holder pane 도 이 태그로 묶어 회수 대상에 포함한다."""
     run_tmux(["set-option", "-p", "-t", pane_id, CONTAINER_TAG_OPTION, scope_value])
 
 
@@ -208,56 +128,6 @@ def set_pane_title(pane_id: str, title: str) -> None:
         raise RuntimeError(result.stderr.strip() or "tmux select-pane failed")
 
 
-def tag_pane(
-    pane_id: str, run_dir: Path, *, option: str = "@okstra_worker_run"
-) -> None:
-    result = run_tmux(
-        ["set-option", "-p", "-t", pane_id, option, _canonical_run_dir(run_dir)]
-    )
-    if result.returncode != 0:
-        raise RuntimeError(result.stderr.strip() or "tmux set-option failed")
-
-
-def capture_pane(pane_id: str, *, last_lines: int = 200) -> str:
-    result = run_tmux(
-        ["capture-pane", "-p", "-t", pane_id, "-S", f"-{last_lines}"]
-    )
-    if result.returncode != 0:
-        return ""
-    return result.stdout
-
-
-def list_run_panes(run_dir: Path, *, lead_pane: str = "") -> list[TmuxPane]:
-    canonical = _canonical_run_dir(run_dir)
-    try:
-        result = run_tmux(
-            [
-                "list-panes",
-                "-a",
-                "-F",
-                "#{pane_id}\t#{pane_title}\t#{@okstra_worker_run}\t#{@okstra_trace_run}",
-            ]
-        )
-    except (OSError, subprocess.SubprocessError):
-        return []
-    if result.returncode != 0:
-        return []
-    return _parse_run_panes(result.stdout, canonical, lead_pane)
-
-
-def _parse_run_panes(output: str, canonical: str, lead_pane: str) -> list[TmuxPane]:
-    panes: list[TmuxPane] = []
-    for line in output.splitlines():
-        pane_id, title, worker_run, trace_run = (line.split("\t") + [""] * 4)[:4]
-        if not pane_id or pane_id == lead_pane:
-            continue
-        if worker_run == canonical:
-            panes.append(TmuxPane(pane_id, title, worker_run, "worker"))
-        elif trace_run == canonical:
-            panes.append(TmuxPane(pane_id, title, trace_run, "trace"))
-    return panes
-
-
 def kill_pane(pane_id: str) -> None:
     try:
         run_tmux(["kill-pane", "-t", pane_id])

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/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(

package/runtime/skills/okstra-setup/references/project-config.md

@@ -16,6 +16,17 @@ shared state. The built-in default is `.project-docs`, `.scratch`,
 okstra-owned context and writes still stay under `<PROJECT_ROOT>/.okstra/**`
 unless the task brief explicitly authorizes a non-okstra path.
 
+`.claude` is the one entry materialised as a real directory whose children are
+symlinked one by one, instead of a single symlink for the whole directory. git
+does not follow a symlink, so a symlinked directory is one file to it, and a
+project that ignores host config by its contents (`.claude/*`) matches every
+child but never the bare `.claude` path — the directory would be invisible in
+the main checkout and `?? .claude` in the task worktree. Linking the children
+reproduces the main checkout's shape, so the project's own ignore rules decide
+the outcome in both places. The other entries stay whole-directory symlinks
+because okstra writes into them, and the directory symlink is what makes a
+newly created top-level entry land in the main checkout.
+
 To override per-project, add a `worktreeSyncDirs` array to `project.json`.
 Empty array disables the feature; the field is preserved across the runtime's
 auto-upserts (only `projectId`, `projectRoot`, `createdAt`, `updatedAt` are