okstra 0.173.0 → 0.175.1

package/runtime/python/okstra_ctl/write_policy.py

@@ -0,0 +1,571 @@
+"""Canonical invocation write policy and truthful runner enforcement."""
+from __future__ import annotations
+
+import hashlib
+import json
+import subprocess
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+from typing import Any, Literal
+
+BoundaryPrecision = Literal["exact-path", "directory-boundary", "none"]
+
+_PRECISION_RANK = {"none": 0, "directory-boundary": 1, "exact-path": 2}
+_POLICY_KEYS = {
+    "artifactPolicy",
+    "sourcePolicy",
+    "gitPolicy",
+    "auxiliaryPolicy",
+}
+_ENFORCEMENT_KEYS = {
+    "boundaryPrecision",
+    "mutationAudit",
+    "attribution",
+    "auditedRoots",
+    "observationCoverage",
+    "unobservedWriteSurfaces",
+}
+
+
+class WritePolicyError(ValueError):
+    """Raised when a write policy cannot be made canonical or trustworthy."""
+
+
+@dataclass(frozen=True)
+class WritePolicy:
+    artifact_policy: Mapping[str, Any]
+    source_policy: Mapping[str, Any]
+    git_policy: Mapping[str, Any]
+    auxiliary_policy: Mapping[str, Any]
+    maximum_boundary_precision: BoundaryPrecision = "none"
+
+    def to_payload(self) -> dict[str, Any]:
+        return {
+            "artifactPolicy": dict(self.artifact_policy),
+            "sourcePolicy": dict(self.source_policy),
+            "gitPolicy": dict(self.git_policy),
+            "auxiliaryPolicy": dict(self.auxiliary_policy),
+        }
+
+    @property
+    def digest(self) -> str:
+        return write_policy_digest(self.to_payload())
+
+    @property
+    def source_mode(self) -> str:
+        return str(self.source_policy["mode"])
+
+
+@dataclass(frozen=True)
+class WriteEnforcement:
+    boundary_precision: BoundaryPrecision
+    mutation_audit: Literal["none", "batch"]
+    attribution: Literal["call", "batch-unattributed"]
+    audited_roots: tuple[Path, ...]
+    observation_coverage: Literal["complete", "scoped", "partial"]
+    unobserved_write_surfaces: tuple[str, ...]
+
+    def to_payload(self) -> dict[str, Any]:
+        return {
+            "boundaryPrecision": self.boundary_precision,
+            "mutationAudit": self.mutation_audit,
+            "attribution": self.attribution,
+            "auditedRoots": [str(path) for path in self.audited_roots],
+            "observationCoverage": self.observation_coverage,
+            "unobservedWriteSurfaces": list(self.unobserved_write_surfaces),
+        }
+
+
+def build_write_policy(
+    invocation: Mapping[str, Any],
+    assignment: Mapping[str, Any],
+    worktree: Path | None,
+) -> WritePolicy:
+    """Build one provider-neutral policy from invocation and adapter authority."""
+    role = _required_text(invocation, "role")
+    project_root = Path(_required_text(invocation, "projectRoot")).resolve()
+    source_root = _trusted_root(invocation, worktree)
+    artifact_paths = _relative_paths(invocation.get("artifactPaths", ()))
+    if not artifact_paths:
+        raise WritePolicyError("artifactPaths must contain standard worker artifacts")
+    source_mode = "project-mutation" if role == "implementer" else "source-readonly"
+    source_policy: dict[str, Any] = {
+        "mode": source_mode,
+        "allowedRoot": str(source_root),
+        "plannedPaths": list(_relative_paths(invocation.get("plannedPaths", ()))),
+        "protectedPaths": list(
+            _relative_paths(invocation.get("protectedPaths", (".okstra", ".git")))
+        ),
+    }
+    git_policy = _git_policy(invocation, source_root, source_mode)
+    external_roots = _validated_auxiliary_roots(invocation, assignment)
+    auxiliary_policy = {
+        "scratchRoots": [
+            str(path) for path in _absolute_roots(invocation.get("scratchRoots", ()))
+        ],
+        "generatedPaths": list(
+            _relative_paths(invocation.get("generatedPaths", ()))
+        ),
+        "externalRoots": [str(path) for path in external_roots],
+    }
+    policy = WritePolicy(
+        artifact_policy={
+            "allowedRoot": str(project_root),
+            "allowedPaths": list(artifact_paths),
+        },
+        source_policy=source_policy,
+        git_policy=git_policy,
+        auxiliary_policy=auxiliary_policy,
+        maximum_boundary_precision=_assignment_precision(assignment),
+    )
+    validate_write_policy_payload(policy.to_payload())
+    return policy
+
+
+def build_invocation_write_contract(
+    *,
+    role: str,
+    project_root: Path,
+    worktree: Path | None,
+    artifact_paths: Sequence[Path],
+    maximum_precision: BoundaryPrecision,
+    planned_paths: Sequence[str] = (),
+    scratch_roots: Sequence[Path] = (),
+    generated_paths: Sequence[str] = (),
+    auxiliary_roots: Sequence[Path] = (),
+    validated_auxiliary_roots: Sequence[Path] = (),
+) -> tuple[WritePolicy, WriteEnforcement]:
+    """Build the single canonical contract used by every v2 dispatcher."""
+    root = project_root.resolve()
+    relative_artifacts = tuple(
+        _relative_to_root(path, root, "artifact") for path in artifact_paths
+    )
+    invocation: dict[str, Any] = {
+        "role": role,
+        "projectRoot": str(root),
+        "artifactPaths": list(relative_artifacts),
+        "plannedPaths": list(planned_paths),
+        "protectedPaths": [".okstra", ".git"],
+        "generatedPaths": list(generated_paths),
+        "scratchRoots": [str(path) for path in scratch_roots],
+        "auxiliaryRoots": [str(path) for path in auxiliary_roots],
+    }
+    source_root = worktree.resolve() if worktree is not None else root
+    if role == "implementer":
+        invocation.update({
+            "expectedBaseCommit": _git_output(source_root, "rev-parse", "HEAD"),
+            "allowedBranchRef": _git_output(
+                source_root, "symbolic-ref", "-q", "HEAD"
+            ),
+        })
+    assignment = {
+        "workerWriteCapability": {
+            "maxBoundaryPrecision": maximum_precision,
+        },
+        "validatedAuxiliaryRoots": [str(path) for path in validated_auxiliary_roots],
+    }
+    policy = build_write_policy(invocation, assignment, source_root)
+    return policy, derive_write_enforcement(policy, maximum_precision, role=role)
+
+
+def planned_paths_from_run_manifest(
+    project_root: Path, manifest: Mapping[str, Any]
+) -> tuple[str, ...]:
+    active_value = manifest.get("activeRunContextPath")
+    if not isinstance(active_value, str) or not active_value:
+        raise WritePolicyError("implementer write policy has no active run context")
+    active = _read_json(_rooted(project_root, active_value), "active run context")
+    source = active.get("sourceArtifacts")
+    run_inputs_value = source.get("runInputsPath") if isinstance(source, Mapping) else None
+    run = active.get("run")
+    stage_value = run.get("stage") if isinstance(run, Mapping) else None
+    if not isinstance(run_inputs_value, str) or not str(stage_value).isdigit():
+        raise WritePolicyError("implementer write policy has no approved stage authority")
+    inputs_payload = _read_json(_rooted(project_root, run_inputs_value), "run inputs")
+    inputs = inputs_payload.get("inputs")
+    approved = inputs.get("approvedPlanPath") if isinstance(inputs, Mapping) else None
+    if not isinstance(approved, str) or not approved:
+        raise WritePolicyError("implementer write policy has no approved plan path")
+    return _planned_paths_from_report(Path(approved), int(stage_value))
+
+
+def derive_write_enforcement(
+    policy: WritePolicy,
+    maximum_precision: BoundaryPrecision,
+    *,
+    role: str | None = None,
+) -> WriteEnforcement:
+    """Lower runner capability when policy paths cannot be enforced exactly."""
+    if role == "leader":
+        enforcement = WriteEnforcement(
+            boundary_precision="none",
+            mutation_audit="none",
+            attribution="batch-unattributed",
+            audited_roots=_audited_roots(policy),
+            observation_coverage="partial",
+            unobserved_write_surfaces=(
+                "lead-session-host-writes",
+                "other-stage-refs",
+                "shared-git-object-store",
+            ),
+        )
+        validate_write_enforcement_payload(enforcement.to_payload())
+        return enforcement
+    if maximum_precision not in _PRECISION_RANK:
+        raise WritePolicyError("worker write capability is invalid")
+    exact_policy = (
+        policy.source_mode == "source-readonly"
+        and not policy.auxiliary_policy.get("externalRoots")
+        and not policy.auxiliary_policy.get("scratchRoots")
+        and not policy.auxiliary_policy.get("generatedPaths")
+    )
+    if maximum_precision == "exact-path" and exact_policy:
+        boundary: BoundaryPrecision = "exact-path"
+    elif _PRECISION_RANK[maximum_precision] >= _PRECISION_RANK["directory-boundary"]:
+        boundary = "directory-boundary"
+    else:
+        boundary = "none"
+    exact = boundary == "exact-path" and exact_policy
+    external_roots = tuple(policy.auxiliary_policy.get("externalRoots", ()))
+    unobserved: list[str] = []
+    if boundary == "none":
+        unobserved.append("provider-process-outside-audited-roots")
+    if external_roots:
+        unobserved.append("shared-tool-cache")
+    if policy.source_mode == "project-mutation":
+        unobserved.extend(("other-stage-refs", "shared-git-object-store"))
+    coverage: Literal["complete", "scoped", "partial"]
+    if exact:
+        coverage = "complete"
+    elif unobserved:
+        coverage = "partial"
+    else:
+        coverage = "scoped"
+    enforcement = WriteEnforcement(
+        boundary_precision=boundary,
+        mutation_audit="none" if exact else "batch",
+        attribution="call" if exact else "batch-unattributed",
+        audited_roots=_audited_roots(policy),
+        observation_coverage=coverage,
+        unobserved_write_surfaces=tuple(unobserved),
+    )
+    validate_write_enforcement_payload(enforcement.to_payload())
+    return enforcement
+
+
+def write_policy_from_payload(payload: Mapping[str, Any]) -> WritePolicy:
+    validate_write_policy_payload(payload)
+    return WritePolicy(
+        artifact_policy=dict(payload["artifactPolicy"]),
+        source_policy=dict(payload["sourcePolicy"]),
+        git_policy=dict(payload["gitPolicy"]),
+        auxiliary_policy=dict(payload["auxiliaryPolicy"]),
+    )
+
+
+def write_enforcement_from_payload(
+    payload: Mapping[str, Any],
+) -> WriteEnforcement:
+    validate_write_enforcement_payload(payload)
+    return WriteEnforcement(
+        boundary_precision=payload["boundaryPrecision"],
+        mutation_audit=payload["mutationAudit"],
+        attribution=payload["attribution"],
+        audited_roots=tuple(Path(value) for value in payload["auditedRoots"]),
+        observation_coverage=payload["observationCoverage"],
+        unobserved_write_surfaces=tuple(payload["unobservedWriteSurfaces"]),
+    )
+
+
+def write_policy_digest(payload: Mapping[str, Any]) -> str:
+    validate_write_policy_payload(payload)
+    encoded = json.dumps(
+        payload,
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False,
+    ).encode("utf-8")
+    return "sha256:" + hashlib.sha256(encoded).hexdigest()
+
+
+def validate_write_policy_payload(payload: Mapping[str, Any]) -> None:
+    if set(payload) != _POLICY_KEYS:
+        raise WritePolicyError("writePolicy must contain four canonical policy sections")
+    artifact = _mapping(payload.get("artifactPolicy"), "artifactPolicy")
+    source = _mapping(payload.get("sourcePolicy"), "sourcePolicy")
+    git = _mapping(payload.get("gitPolicy"), "gitPolicy")
+    auxiliary = _mapping(payload.get("auxiliaryPolicy"), "auxiliaryPolicy")
+    if set(artifact) != {"allowedRoot", "allowedPaths"}:
+        raise WritePolicyError("artifactPolicy is incomplete")
+    _absolute_text(artifact.get("allowedRoot"), "artifactPolicy.allowedRoot")
+    _relative_paths(artifact.get("allowedPaths", ()))
+    if source.get("mode") not in {"source-readonly", "project-mutation"}:
+        raise WritePolicyError("sourcePolicy mode is invalid")
+    if set(source) != {"mode", "allowedRoot", "plannedPaths", "protectedPaths"}:
+        raise WritePolicyError("sourcePolicy is incomplete")
+    _absolute_text(source.get("allowedRoot"), "sourcePolicy.allowedRoot")
+    _relative_paths(source.get("plannedPaths", ()))
+    _relative_paths(source.get("protectedPaths", ()))
+    if git.get("mode") not in {"disabled", "fast-forward-descendant-chain"}:
+        raise WritePolicyError("gitPolicy mode is invalid")
+    if git.get("mode") == "disabled" and set(git) != {"mode"}:
+        raise WritePolicyError("disabled gitPolicy must not grant Git paths")
+    required_git = {
+        "mode", "worktreeGitDir", "gitCommonDir", "expectedBaseCommit",
+        "allowedBranchRef", "commitMode",
+    }
+    if git.get("mode") != "disabled" and set(git) != required_git:
+        raise WritePolicyError("project mutation gitPolicy is incomplete")
+    if set(auxiliary) != {"scratchRoots", "generatedPaths", "externalRoots"}:
+        raise WritePolicyError("auxiliaryPolicy is incomplete")
+    _relative_paths(auxiliary.get("generatedPaths", ()))
+    for key in ("scratchRoots", "externalRoots"):
+        for value in _text_sequence(auxiliary.get(key), f"auxiliaryPolicy.{key}"):
+            _absolute_text(value, f"auxiliaryPolicy.{key}")
+
+
+def validate_write_enforcement_payload(payload: Mapping[str, Any]) -> None:
+    if set(payload) != _ENFORCEMENT_KEYS:
+        raise WritePolicyError("writeEnforcement is incomplete")
+    boundary = payload.get("boundaryPrecision")
+    mutation_audit = payload.get("mutationAudit")
+    attribution = payload.get("attribution")
+    coverage = payload.get("observationCoverage")
+    if boundary not in _PRECISION_RANK:
+        raise WritePolicyError("writeEnforcement boundaryPrecision is invalid")
+    if mutation_audit not in {"none", "batch"}:
+        raise WritePolicyError("writeEnforcement mutationAudit is invalid")
+    if attribution not in {"call", "batch-unattributed"}:
+        raise WritePolicyError("writeEnforcement attribution is invalid")
+    if coverage not in {"complete", "scoped", "partial"}:
+        raise WritePolicyError("writeEnforcement observationCoverage is invalid")
+    if (boundary, mutation_audit, attribution) == ("exact-path", "none", "call"):
+        if coverage != "complete":
+            raise WritePolicyError("exact enforcement must have complete coverage")
+    elif (boundary, mutation_audit, attribution) == (
+        "none",
+        "none",
+        "batch-unattributed",
+    ):
+        if coverage != "partial":
+            raise WritePolicyError("host-session enforcement must be partial")
+    elif mutation_audit != "batch" or attribution != "batch-unattributed":
+        raise WritePolicyError("non-exact enforcement must use batch attribution")
+    elif boundary == "exact-path" or coverage == "complete":
+        raise WritePolicyError("batch enforcement cannot claim exact coverage")
+    for root in _text_sequence(payload.get("auditedRoots"), "auditedRoots"):
+        _absolute_text(root, "auditedRoots")
+    _text_sequence(payload.get("unobservedWriteSurfaces"), "unobservedWriteSurfaces")
+
+
+def _git_policy(
+    invocation: Mapping[str, Any], root: Path, source_mode: str
+) -> dict[str, Any]:
+    if source_mode == "source-readonly":
+        return {"mode": "disabled"}
+    git_dir = _git_path(root, "--git-dir")
+    common_dir = _git_path(root, "--git-common-dir")
+    expected_base = _required_text(invocation, "expectedBaseCommit")
+    allowed_ref = _required_text(invocation, "allowedBranchRef")
+    _require_commit(root, expected_base)
+    current_ref = _git_output(root, "symbolic-ref", "-q", "HEAD")
+    if current_ref != allowed_ref or not allowed_ref.startswith("refs/heads/"):
+        raise WritePolicyError("allowedBranchRef does not match assigned worktree")
+    return {
+        "mode": "fast-forward-descendant-chain",
+        "worktreeGitDir": str(git_dir),
+        "gitCommonDir": str(common_dir),
+        "expectedBaseCommit": expected_base,
+        "allowedBranchRef": allowed_ref,
+        "commitMode": "fast-forward-descendant-chain",
+    }
+
+
+def _audited_roots(policy: WritePolicy) -> tuple[Path, ...]:
+    values = [
+        Path(str(policy.source_policy["allowedRoot"])),
+        Path(str(policy.artifact_policy["allowedRoot"])),
+    ]
+    values.extend(Path(value) for value in policy.auxiliary_policy.get("scratchRoots", ()))
+    git_dir = policy.git_policy.get("worktreeGitDir")
+    if isinstance(git_dir, str) and git_dir:
+        values.append(Path(git_dir))
+    seen: set[Path] = set()
+    roots: list[Path] = []
+    for value in values:
+        resolved = value.resolve()
+        if resolved not in seen:
+            roots.append(resolved)
+            seen.add(resolved)
+    return tuple(roots)
+
+
+def _trusted_root(invocation: Mapping[str, Any], worktree: Path | None) -> Path:
+    raw = worktree if worktree is not None else Path(_required_text(invocation, "projectRoot"))
+    if not raw.is_absolute() or not raw.is_dir():
+        raise WritePolicyError("assigned worktree must be an existing absolute path")
+    return raw.resolve()
+
+
+def _validated_auxiliary_roots(
+    invocation: Mapping[str, Any], assignment: Mapping[str, Any]
+) -> tuple[Path, ...]:
+    requested = _absolute_roots(invocation.get("auxiliaryRoots", ()))
+    declared = set(_absolute_roots(assignment.get("validatedAuxiliaryRoots", ())))
+    if any(path not in declared for path in requested):
+        raise WritePolicyError("auxiliary root is not adapter-validated")
+    return requested
+
+
+def _assignment_precision(assignment: Mapping[str, Any]) -> BoundaryPrecision:
+    capability = assignment.get("workerWriteCapability")
+    if not isinstance(capability, Mapping):
+        raise WritePolicyError("workerWriteCapability is required")
+    value = capability.get("maxBoundaryPrecision")
+    if value not in _PRECISION_RANK:
+        raise WritePolicyError("workerWriteCapability is invalid")
+    return value
+
+
+def _absolute_roots(value: object) -> tuple[Path, ...]:
+    roots: list[Path] = []
+    for text in _text_sequence(value, "absolute roots"):
+        path = Path(text)
+        if not path.is_absolute() or not path.exists():
+            raise WritePolicyError("auxiliary root must be an existing absolute path")
+        if path.absolute() != path.resolve():
+            raise WritePolicyError("auxiliary root contains a symlink component")
+        roots.append(path.resolve())
+    if len(set(roots)) != len(roots):
+        raise WritePolicyError("auxiliary roots must be unique")
+    return tuple(roots)
+
+
+def _relative_to_root(path: Path, root: Path, label: str) -> str:
+    absolute = path if path.is_absolute() else root / path
+    try:
+        relative = absolute.absolute().relative_to(root).as_posix()
+    except ValueError as exc:
+        raise WritePolicyError(f"{label} path is outside project root") from exc
+    if not relative or relative == ".":
+        raise WritePolicyError(f"{label} path must name a file")
+    current = root
+    for part in PurePosixPath(relative).parts:
+        current /= part
+        if current.is_symlink():
+            raise WritePolicyError(f"{label} path contains a symlink component")
+    return relative
+
+
+def _planned_paths_from_report(report_path: Path, stage: int) -> tuple[str, ...]:
+    payload = _read_json(report_path.with_suffix(".data.json"), "approved plan data")
+    planning = payload.get("implementationPlanning")
+    stages = planning.get("stages") if isinstance(planning, Mapping) else None
+    selected = next(
+        (
+            row for row in stages
+            if isinstance(row, Mapping) and row.get("stage") == stage
+        ),
+        None,
+    ) if isinstance(stages, list) else None
+    steps = selected.get("stepwiseExecution") if isinstance(selected, Mapping) else None
+    paths = {
+        part.strip().strip("`")
+        for step in steps if isinstance(step, Mapping)
+        for part in str(step.get("files") or "").replace("<br>", ",").split(",")
+        if part.strip()
+    } if isinstance(steps, list) else set()
+    if not paths:
+        raise WritePolicyError("implementer write policy stage has no planned paths")
+    return _relative_paths(tuple(sorted(paths)))
+
+
+def _rooted(project_root: Path, value: str) -> Path:
+    path = Path(value)
+    return path if path.is_absolute() else project_root / path
+
+
+def _read_json(path: Path, label: str) -> Mapping[str, Any]:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        raise WritePolicyError(f"{label} is invalid: {path}") from exc
+    if not isinstance(value, Mapping):
+        raise WritePolicyError(f"{label} must be an object: {path}")
+    return value
+
+
+def _relative_paths(value: object) -> tuple[str, ...]:
+    paths: list[str] = []
+    for raw in _text_sequence(value, "relative paths"):
+        candidate = PurePosixPath(raw)
+        if candidate.is_absolute() or not candidate.parts or ".." in candidate.parts:
+            raise WritePolicyError("policy paths must be normalized relative paths")
+        normalized = candidate.as_posix()
+        if normalized in {"", "."} or normalized != raw:
+            raise WritePolicyError("policy paths must be normalized relative paths")
+        paths.append(normalized)
+    if len(set(paths)) != len(paths):
+        raise WritePolicyError("policy paths must be unique")
+    return tuple(paths)
+
+
+def _mapping(value: object, label: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise WritePolicyError(f"{label} must be an object")
+    return value
+
+
+def _text_sequence(value: object, label: str) -> tuple[str, ...]:
+    if not isinstance(value, Sequence) or isinstance(value, (str, bytes)):
+        raise WritePolicyError(f"{label} must be an array")
+    rows = tuple(value)
+    if any(not isinstance(row, str) or not row for row in rows):
+        raise WritePolicyError(f"{label} must contain non-empty strings")
+    return rows
+
+
+def _required_text(payload: Mapping[str, Any], key: str) -> str:
+    value = payload.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise WritePolicyError(f"{key} must be a non-empty string")
+    return value
+
+
+def _absolute_text(value: object, label: str) -> str:
+    if not isinstance(value, str) or not value or not Path(value).is_absolute():
+        raise WritePolicyError(f"{label} must be an absolute path")
+    return value
+
+
+def _git_path(root: Path, flag: str) -> Path:
+    raw = _git_output(root, "rev-parse", "--path-format=absolute", flag)
+    path = Path(raw).resolve()
+    if not path.exists():
+        raise WritePolicyError(f"Git projection path does not exist: {path}")
+    return path
+
+
+def _require_commit(root: Path, commit: str) -> None:
+    result = subprocess.run(
+        ["git", "-C", str(root), "cat-file", "-e", f"{commit}^{{commit}}"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        raise WritePolicyError(result.stderr.strip() or "expected base is not a commit")
+
+
+def _git_output(root: Path, *args: str) -> str:
+    result = subprocess.run(
+        ["git", "-C", str(root), *args],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0 or not result.stdout.strip():
+        detail = result.stderr.strip() or "Git command returned no value"
+        raise WritePolicyError(detail)
+    return result.stdout.strip()

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(