okstra 0.76.0 → 0.78.0

package/runtime/python/okstra_ctl/wrapper_status.py

@@ -0,0 +1,55 @@
+"""Reader for okstra worker wrapper status sidecars."""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Mapping
+
+
+@dataclass(frozen=True)
+class WrapperStatus:
+    path: Path
+    stage: str
+    exit_code: int | None
+    timeout: bool
+    log_path: Path | None
+    raw: Mapping[str, Any]
+
+    @property
+    def is_terminal(self) -> bool:
+        return self.stage == "exited"
+
+
+def status_path_for_prompt(prompt_path: Path) -> Path:
+    return prompt_path.with_suffix(prompt_path.suffix + ".status.json")
+
+
+def read_wrapper_status(path: Path) -> WrapperStatus | None:
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(raw, dict):
+        return None
+    stage = raw.get("stage")
+    if not isinstance(stage, str) or not stage:
+        return None
+    return WrapperStatus(
+        path=path,
+        stage=stage,
+        exit_code=_optional_int(raw.get("exit_code")),
+        timeout=raw.get("timeout") is True,
+        log_path=_optional_path(raw.get("log_path")),
+        raw=raw,
+    )
+
+
+def _optional_int(value: object) -> int | None:
+    return value if isinstance(value, int) and not isinstance(value, bool) else None
+
+
+def _optional_path(value: object) -> Path | None:
+    if not isinstance(value, str) or not value.strip():
+        return None
+    return Path(value)

package/runtime/python/okstra_token_usage/codex.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 import json
 from pathlib import Path
 from .jsonl_io import iter_jsonl
-from .paths import CODEX_SESSIONS
+from .paths import CODEX_SESSIONS, ts_in_window
 
 
 def codex_session_total(jsonl_path: Path) -> dict:
@@ -47,9 +47,15 @@ def codex_session_total(jsonl_path: Path) -> dict:
 
 
 def find_codex_session(cwd: Path, started_at: str, ended_at: str) -> Path | None:
-    """Find the codex rollout jsonl whose meta.cwd matches and timestamp falls in window."""
+    """Find the latest codex rollout jsonl in the requested window."""
+    sessions = find_codex_sessions(cwd, started_at, ended_at)
+    return sessions[-1] if sessions else None
+
+
+def find_codex_sessions(cwd: Path, started_at: str, ended_at: str) -> list[Path]:
+    """Find codex rollout jsonls whose meta.cwd matches the window."""
     if not CODEX_SESSIONS.is_dir() or not started_at or not ended_at:
-        return None
+        return []
     target_cwd = str(cwd)
     candidates: list[tuple[str, Path]] = []
     for p in CODEX_SESSIONS.rglob("rollout-*.jsonl"):
@@ -70,11 +76,10 @@ def find_codex_session(cwd: Path, started_at: str, ended_at: str) -> Path | None
         if payload.get("cwd") != target_cwd:
             continue
         ts = payload.get("timestamp") or rec.get("timestamp") or ""
-        if not (started_at <= ts <= ended_at):
+        if not ts_in_window(ts, started_at, ended_at):
             continue
         candidates.append((ts, p))
     if not candidates:
-        return None
+        return []
     candidates.sort()
-    return candidates[-1][1]
-
+    return [path for _ts, path in candidates]

package/runtime/python/okstra_token_usage/collect.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 import json
 from datetime import datetime, timezone
 from pathlib import Path
+from typing import Any
 from okstra_project.dirs import OKSTRA_RELATIVE
 
 from .blocks import na_block, usage_block
@@ -12,8 +13,8 @@ from .claude import (
     find_claude_agent_sessions,
     find_claude_team_sessions,
 )
-from .codex import codex_session_total, find_codex_session
-from .gemini import find_gemini_session, gemini_session_total
+from .codex import codex_session_total, find_codex_session, find_codex_sessions
+from .gemini import find_gemini_session, find_gemini_sessions, gemini_session_total
 from .paths import claude_project_dir, utc_now
 from .pricing import codex_cost_usd, gemini_cost_usd
 
@@ -64,6 +65,8 @@ def _aggregate_totals(items: list[dict]) -> dict:
         "totalTokens": 0, "inputTokens": 0, "outputTokens": 0,
         "cacheCreationTokens": 0, "cacheCreation5mTokens": 0, "cacheCreation1hTokens": 0,
         "cacheReadTokens": 0,
+        "cachedInputTokens": 0, "reasoningOutputTokens": 0,
+        "cachedTokens": 0, "thoughtsTokens": 0, "toolTokens": 0,
         "toolUses": 0, "durationMs": 0,
         "agentName": None, "model": None,
         "startedAt": None, "endedAt": None,
@@ -71,7 +74,8 @@ def _aggregate_totals(items: list[dict]) -> dict:
     for t in items:
         for k in ("totalTokens", "inputTokens", "outputTokens",
                   "cacheCreationTokens", "cacheCreation5mTokens", "cacheCreation1hTokens",
-                  "cacheReadTokens", "toolUses"):
+                  "cacheReadTokens", "cachedInputTokens", "reasoningOutputTokens",
+                  "cachedTokens", "thoughtsTokens", "toolTokens", "toolUses"):
             aggregate[k] += t.get(k, 0) or 0
         if aggregate["agentName"] is None and t.get("agentName"):
             aggregate["agentName"] = t["agentName"]
@@ -207,6 +211,233 @@ def resolve_team_name(state: dict) -> str:
     return team_name
 
 
+def _resolve_project_path(project_root: Path, raw_path: str) -> Path | None:
+    if not raw_path:
+        return None
+    path = Path(raw_path)
+    return path if path.is_absolute() else project_root / path
+
+
+def _load_lead_event_records(project_root: Path, state: dict) -> list[dict]:
+    path = _resolve_project_path(project_root, state.get("leadEventsPath", ""))
+    if path is None or not path.is_file():
+        return []
+    records = []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        if not line.strip():
+            continue
+        try:
+            record = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(record, dict):
+            records.append(record)
+    return records
+
+
+def _codex_worker_windows(project_root: Path, state: dict) -> dict[str, list[tuple[str, str]]]:
+    active: dict[tuple[str, str], str] = {}
+    windows: dict[str, list[tuple[str, str]]] = {}
+    for event in _load_lead_event_records(project_root, state):
+        details = event.get("details") or {}
+        if not isinstance(details, dict):
+            continue
+        worker_id = str(details.get("workerId") or "").strip()
+        if not worker_id:
+            continue
+        attempt = str(details.get("attempt") or "")
+        key = (worker_id, attempt)
+        event_type = event.get("eventType")
+        timestamp = str(event.get("timestamp") or "").strip()
+        if not timestamp:
+            continue
+        if event_type == "worker-dispatched":
+            active[key] = timestamp
+        elif event_type in {"worker-result-collected", "worker-failed"}:
+            started_at = active.pop(key, "")
+            if started_at:
+                windows.setdefault(worker_id, []).append((started_at, timestamp))
+    running_workers = {
+        str(worker.get("workerId") or "").strip()
+        for worker in state.get("workers", [])
+        if isinstance(worker, dict) and worker.get("status") == "running"
+    }
+    if running_workers:
+        open_until = utc_now()
+        for (worker_id, _attempt), started_at in active.items():
+            if worker_id in running_workers:
+                windows.setdefault(worker_id, []).append((started_at, open_until))
+    return windows
+
+
+def _codex_runtime_provider(worker: dict) -> str:
+    worker_id = str(worker.get("workerId") or "").strip()
+    agent = str(worker.get("agent") or "").strip()
+    if worker_id == "report-writer":
+        return "codex"
+    if agent in {"codex", "gemini"}:
+        return agent
+    return ""
+
+
+def _cli_sessions_for_windows(
+    provider: str,
+    project_root: Path,
+    windows: list[tuple[str, str]],
+) -> list[Path]:
+    sessions: list[Path] = []
+    seen: set[Path] = set()
+    for started_at, ended_at in windows:
+        if provider == "codex":
+            matches = find_codex_sessions(project_root, started_at, ended_at)
+        elif provider == "gemini":
+            matches = find_gemini_sessions(project_root, started_at, ended_at)
+        else:
+            matches = []
+        for path in matches:
+            if path not in seen:
+                seen.add(path)
+                sessions.append(path)
+    return sessions
+
+
+def _cli_session_totals(provider: str, session_paths: list[Path]) -> list[dict]:
+    totals = []
+    for session_path in session_paths:
+        if provider == "codex":
+            total = codex_session_total(session_path)
+        else:
+            total = gemini_session_total(session_path)
+        if total.get("available"):
+            totals.append(total)
+    return totals
+
+
+def _cli_usage_block(provider: str, totals: dict, session_paths: list[Path]) -> dict:
+    block = usage_block(totals, source=f"{provider}-cli")
+    block["cliTotalTokens"] = totals.get("totalTokens", 0) or 0
+    block["cliSessionPaths"] = [str(path) for path in session_paths]
+    if totals.get("model"):
+        block["model"] = totals["model"]
+        block["cliModel"] = totals["model"]
+    if provider == "codex":
+        cost = codex_cost_usd(
+            totals.get("model"),
+            totals.get("inputTokens", 0) or 0,
+            totals.get("cachedInputTokens", 0) or 0,
+            totals.get("outputTokens", 0) or 0,
+        )
+    else:
+        cost = gemini_cost_usd(
+            totals.get("model"),
+            totals.get("inputTokens", 0) or 0,
+            totals.get("outputTokens", 0) or 0,
+        )
+    if cost is not None:
+        block["cliEstimatedCostUsd"] = cost
+    return block
+
+
+def _collect_codex_runtime_usage(state: dict, project_root: Path) -> dict:
+    windows_by_worker = _codex_worker_windows(project_root, state)
+    state["leadUsage"] = na_block(
+        "Codex lead token accounting is not available yet; worker CLI usage is collected from provider logs."
+    )
+    for worker in state.get("workers", []):
+        if not isinstance(worker, dict):
+            continue
+        provider = _codex_runtime_provider(worker)
+        if not provider:
+            worker["usage"] = na_block(
+                f"worker provider is not CLI-backed in Codex runtime: {worker.get('agent') or worker.get('workerId')}"
+            )
+            continue
+        worker_id = str(worker.get("workerId") or "").strip()
+        windows = windows_by_worker.get(worker_id, [])
+        if not windows:
+            worker["usage"] = na_block(
+                f"no lead-events dispatch window found for workerId={worker_id}"
+            )
+            continue
+        session_paths = _cli_sessions_for_windows(provider, project_root, windows)
+        totals = _cli_session_totals(provider, session_paths)
+        if not totals:
+            worker["usage"] = na_block(
+                f"no {provider} CLI session found in lead-events dispatch window"
+            )
+            continue
+        worker["usage"] = _cli_usage_block(
+            provider,
+            _aggregate_totals(totals),
+            session_paths,
+        )
+    _populate_usage_summary(state, team_name=resolve_team_name(state), sessions_found=0)
+    return state
+
+
+def _populate_usage_summary(
+    state: dict,
+    *,
+    team_name: str,
+    sessions_found: int,
+    unattributed_sessions: list[str] | None = None,
+    unattributed_usage: dict[str, Any] | None = None,
+) -> None:
+    workers = state.get("workers", [])
+    lead = state.get("leadUsage") or {}
+    lead_total = lead.get("totalTokens", 0) or 0
+    lead_billable = lead.get("billableEquivalentTokens", 0) or 0
+    lead_cost = lead.get("estimatedCostUsd", 0) or 0
+    worker_total = sum((w.get("usage") or {}).get("totalTokens", 0) or 0 for w in workers)
+    worker_billable = sum((w.get("usage") or {}).get("billableEquivalentTokens", 0) or 0 for w in workers)
+    worker_cost = sum((w.get("usage") or {}).get("estimatedCostUsd", 0) or 0 for w in workers)
+    cli_cost = sum((w.get("usage") or {}).get("cliEstimatedCostUsd", 0) or 0 for w in workers)
+    if unattributed_usage is not None:
+        worker_total += unattributed_usage.get("totalTokens", 0) or 0
+        worker_billable += unattributed_usage.get("billableEquivalentTokens", 0) or 0
+        worker_cost += unattributed_usage.get("estimatedCostUsd", 0) or 0
+
+    unmatched_models: list[str] = []
+    if lead.get("model") and lead.get("estimatedCostUsd") is None and (lead.get("totalTokens") or 0) > 0:
+        unmatched_models.append(lead["model"])
+    for w in workers:
+        u = w.get("usage") or {}
+        if (
+            u.get("source") not in {"codex-cli", "gemini-cli"}
+            and u.get("model")
+            and u.get("estimatedCostUsd") is None
+            and (u.get("totalTokens") or 0) > 0
+        ):
+            unmatched_models.append(u["model"])
+        if u.get("cliModel") and u.get("cliEstimatedCostUsd") is None and (u.get("cliTotalTokens") or 0) > 0:
+            unmatched_models.append(u["cliModel"])
+    state["usageSummary"] = {
+        "leadTotalTokens": lead_total,
+        "workerTotalTokens": worker_total,
+        "grandTotalTokens": lead_total + worker_total,
+        "leadBillableEquivalentTokens": lead_billable,
+        "workerBillableEquivalentTokens": worker_billable,
+        "grandBillableEquivalentTokens": lead_billable + worker_billable,
+        "estimatedCostUsd": {
+            "lead": round(lead_cost, 4),
+            "claudeWorkers": round(worker_cost, 4),
+            "cliWorkers": round(cli_cost, 4),
+            "grandTotal": round(lead_cost + worker_cost + cli_cost, 4),
+        },
+        "collectedAt": utc_now(),
+        "teamName": team_name,
+        "sessionsFound": sessions_found,
+        "unmatchedModels": sorted(set(unmatched_models)),
+        "unattributedTeamSessions": unattributed_sessions or [],
+        "unattributedWorkerUsage": unattributed_usage,
+        "definitions": {
+            "totalTokens": "Sum of input + output + cache_creation + cache_read tokens (raw processed volume; matches Anthropic API breakdown). Cache reads are 95%+ in long sessions.",
+            "billableEquivalentTokens": "Tokens normalized to base-input-price units (cache_creation_5m x1.25, cache_creation_1h x2.0, cache_read x0.1, output x5). 5m vs 1h is split from usage.cache_creation when the API breakdown is present; otherwise all cache_creation falls into 5m.",
+            "estimatedCostUsd": "USD cost using public list pricing for the model recorded in the session. cliWorkers covers Codex/Gemini CLI calls billed under those providers.",
+        },
+    }
+
+
 def collect(team_state_path: Path, project_root: Path | None = None, *,
             incremental: bool = True) -> dict:
     # incremental: 세션 jsonl 스캔에 byte cursor 캐시 사용 (P6). 캐시는 윈도우
@@ -218,6 +449,8 @@ def collect(team_state_path: Path, project_root: Path | None = None, *,
     task_key = state.get("taskKey", "")
     team_name = resolve_team_name(state)
     lead_sid = (state.get("lead") or {}).get("sessionId")
+    if state.get("leadRuntime") == "codex":
+        return _collect_codex_runtime_usage(state, cwd)
 
     # 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
@@ -372,56 +605,13 @@ def collect(team_state_path: Path, project_root: Path | None = None, *,
             "cannot be mapped to a specific workerId."
         )
 
-    # Aggregate summary.
-    lead = state.get("leadUsage") or {}
-    workers = state.get("workers", [])
-    lead_total = lead.get("totalTokens", 0) or 0
-    lead_billable = lead.get("billableEquivalentTokens", 0) or 0
-    lead_cost = lead.get("estimatedCostUsd", 0) or 0
-    worker_total = sum((w.get("usage") or {}).get("totalTokens", 0) or 0 for w in workers)
-    worker_billable = sum((w.get("usage") or {}).get("billableEquivalentTokens", 0) or 0 for w in workers)
-    worker_cost = sum((w.get("usage") or {}).get("estimatedCostUsd", 0) or 0 for w in workers)
-    cli_cost = sum((w.get("usage") or {}).get("cliEstimatedCostUsd", 0) or 0 for w in workers)
-    if unattributed_usage is not None:
-        worker_total += unattributed_usage.get("totalTokens", 0) or 0
-        worker_billable += unattributed_usage.get("billableEquivalentTokens", 0) or 0
-        worker_cost += unattributed_usage.get("estimatedCostUsd", 0) or 0
-
-    # Surface models whose pricing lookup failed so the silent-zero case is visible.
-    unmatched_models: list[str] = []
-    if lead.get("model") and lead.get("estimatedCostUsd") is None and (lead.get("totalTokens") or 0) > 0:
-        unmatched_models.append(lead["model"])
-    for w in workers:
-        u = w.get("usage") or {}
-        if u.get("model") and u.get("estimatedCostUsd") is None and (u.get("totalTokens") or 0) > 0:
-            unmatched_models.append(u["model"])
-        if u.get("cliModel") and u.get("cliEstimatedCostUsd") is None and (u.get("cliTotalTokens") or 0) > 0:
-            unmatched_models.append(u["cliModel"])
-    state["usageSummary"] = {
-        "leadTotalTokens": lead_total,
-        "workerTotalTokens": worker_total,
-        "grandTotalTokens": lead_total + worker_total,
-        "leadBillableEquivalentTokens": lead_billable,
-        "workerBillableEquivalentTokens": worker_billable,
-        "grandBillableEquivalentTokens": lead_billable + worker_billable,
-        "estimatedCostUsd": {
-            "lead": round(lead_cost, 4),
-            "claudeWorkers": round(worker_cost, 4),
-            "cliWorkers": round(cli_cost, 4),
-            "grandTotal": round(lead_cost + worker_cost + cli_cost, 4),
-        },
-        "collectedAt": utc_now(),
-        "teamName": team_name,
-        "sessionsFound": len(claude_sessions),
-        "unmatchedModels": sorted(set(unmatched_models)),
-        "unattributedTeamSessions": unattributed_sessions,
-        "unattributedWorkerUsage": unattributed_usage,
-        "definitions": {
-            "totalTokens": "Sum of input + output + cache_creation + cache_read tokens (raw processed volume; matches Anthropic API breakdown). Cache reads are 95%+ in long sessions.",
-            "billableEquivalentTokens": "Tokens normalized to base-input-price units (cache_creation_5m x1.25, cache_creation_1h x2.0, cache_read x0.1, output x5). 5m vs 1h is split from usage.cache_creation when the API breakdown is present; otherwise all cache_creation falls into 5m.",
-            "estimatedCostUsd": "USD cost using public list pricing for the model recorded in the session. cliWorkers covers Codex/Gemini CLI calls billed under those providers.",
-        },
-    }
+    _populate_usage_summary(
+        state,
+        team_name=team_name,
+        sessions_found=len(claude_sessions),
+        unattributed_sessions=unattributed_sessions,
+        unattributed_usage=unattributed_usage,
+    )
     return state
 
 
@@ -435,4 +625,3 @@ def _infer_project_root(team_state_path: Path, state: dict) -> Path:
             return p
         p = p.parent
     raise SystemExit(f"could not infer project root from {team_state_path}")
-

package/runtime/python/okstra_token_usage/gemini.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 
 import json
 from pathlib import Path
-from .paths import GEMINI_TMP
+from .paths import GEMINI_TMP, ts_in_window
 
 
 def gemini_session_total(json_path: Path) -> dict:
@@ -40,9 +40,15 @@ def gemini_session_total(json_path: Path) -> dict:
 
 
 def find_gemini_session(project_root: Path, started_at: str, ended_at: str) -> Path | None:
-    """Find the gemini chat session whose first user message references the project."""
+    """Find the latest gemini chat session in the requested window."""
+    sessions = find_gemini_sessions(project_root, started_at, ended_at)
+    return sessions[-1] if sessions else None
+
+
+def find_gemini_sessions(project_root: Path, started_at: str, ended_at: str) -> list[Path]:
+    """Find gemini chat sessions whose first user message references the project."""
     if not GEMINI_TMP.is_dir() or not started_at or not ended_at:
-        return None
+        return []
     project_str = str(project_root)
     candidates: list[tuple[str, Path]] = []
     for p in GEMINI_TMP.glob("*/chats/session-*.json"):
@@ -51,7 +57,7 @@ def find_gemini_session(project_root: Path, started_at: str, ended_at: str) -> P
         except (OSError, json.JSONDecodeError):
             continue
         start = data.get("startTime") or ""
-        if not (started_at <= start <= ended_at):
+        if not ts_in_window(start, started_at, ended_at):
             continue
         # Match by content: first user message should mention project root or task path.
         msgs = data.get("messages") or []
@@ -71,7 +77,6 @@ def find_gemini_session(project_root: Path, started_at: str, ended_at: str) -> P
                 candidates.append((start, p))
             break
     if not candidates:
-        return None
+        return []
     candidates.sort()
-    return candidates[-1][1]
-
+    return [path for _start, path in candidates]

package/runtime/schemas/final-report-v1.0.schema.json

@@ -745,7 +745,7 @@
       }
     },
     {
-      "description": "final-verification verdict token must be one of accepted / conditional-accept / blocked.",
+      "description": "final-verification verdict token must be one of accepted / conditional-accept / blocked and must explicitly list conditional acceptance conditions.",
       "if": {
         "properties": { "header": { "properties": { "taskType": { "const": "final-verification" } } } },
         "required": ["header"]
@@ -753,6 +753,7 @@
       "then": {
         "properties": {
           "finalVerdict": {
+            "required": ["conditionalAcceptanceConditions"],
             "properties": {
               "verdictToken": { "enum": ["accepted", "conditional-accept", "blocked"] }
             }
@@ -775,6 +776,7 @@
       "then": {
         "properties": {
           "finalVerdict": {
+            "not": { "required": ["conditionalAcceptanceConditions"] },
             "properties": {
               "verdictToken": { "const": "not-applicable" }
             }

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

@@ -273,6 +273,9 @@ Agent(
 - Agent Teams mode: Spawn within an existing team
 - Fallback mode: Spawn with `run_in_background: true` and no `team_name`
 
+For `tmux-pane` backend runs, do not use the Agent snippet. For each reverify round, write a jobs file at `runs/<task-type>/state/reverify-jobs-r<N>-<task-type>-<seq>.json` with `dispatchKind: "reverify-r<N>"` and worker entries containing `workerId`, `provider`, `role`, `modelExecutionValue`, `promptPath`, `resultPath`, `workerResultPath`, and `completionPaths`; then run `okstra team dispatch --project-root <dir> --run-manifest <path> --dispatch-kind reverify-r<N> --jobs-file <jobs-file>` followed by `okstra team await --project-root <dir> --run-manifest <path>`.
+
+
 **Completion detection per round (BLOCKING).** Each round dispatches a variable set (1..N) of reverify workers asynchronously; the `Agent(... team_name ...)` calls return `Spawned successfully` immediately, which is NOT completion. Lead MUST detect each round's completion via the self-scheduled polling protocol in [okstra-team-contract](../okstra-team-contract/SKILL.md) "Worker-completion detection (self-scheduled polling)", with the pending set reconstructed from that round's dispatched workers' Result Paths — do NOT restate the algorithm here. Lead MUST NOT treat the spawn ack as completion and MUST NOT end its turn with a prose "waiting" statement.
 
 ### Required reverify-prompt anchor headers (BLOCKING)

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

@@ -82,6 +82,9 @@ Except for `release-handoff` (which is single-lead by design and never dispatche
 
 Speculative reasons such as "session resume constraint", "team object no longer exists", or "lead can do it faster" are NOT valid.
 
+For `tmux-pane` backend runs, do not use the Agent template. Create a one-job jobs file for the `report-writer` with `dispatchKind: "report-writer"` and the same `workerId`, `provider`, `role`, `modelExecutionValue`, `promptPath`, `resultPath`, `workerResultPath`, and `completionPaths` fields used by reverify jobs. Then call `okstra team dispatch --project-root <dir> --run-manifest <path> --jobs-file <jobs-file>` followed by `okstra team await --project-root <dir> --run-manifest <path>`. Completion requires both the report data.json and the report-writer worker-results audit file.
+
+
 ## Phase 6 → Phase 7 execution sequence (BLOCKING order)
 
 The four steps below MUST execute in this exact order. Reordering them is the recurring root cause of reports shipping with `--` token cells (Phase 7 not run yet), Section 3 missing follow-up entries, or Section 4 rows never spawning.

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

@@ -251,7 +251,7 @@ back it up as `.bak.<timestamp>` rather than overwriting silently.
 
 `release-handoff` fills the PR body from a template. By default it uses the
 bundled skill template at
-`~/.claude/skills/okstra-run/templates/pr-body.template.md`. Most projects
+`~/.claude/skills/templates/prd/pr-body.template.md`. Most projects
 want their own — e.g. the repo's `.github/PULL_REQUEST_TEMPLATE.md` — to
 keep PRs consistent with what the team already merges manually.
 

package/runtime/skills/okstra-team-contract/SKILL.md

@@ -127,6 +127,18 @@ Terminal statuses that can be recorded for a worker:
 
 Lead dispatches workers asynchronously: an `Agent` call carrying `team_name` returns `Spawned successfully` **immediately** — that ack is NOT a completion. Lead MUST NOT treat the spawn ack as completion, and MUST NOT end its turn with a prose "waiting for ..." statement (that path stalls the run — the Agent Teams idle-notification is experimental and can be dropped, leaving Lead parked until the user manually nudges it). Instead:
 
+For `tmux-pane` backend runs, Lead MUST use exactly one background wait command instead of raw result-file polling:
+
+```bash
+okstra team await --project-root <dir> --run-manifest <path>
+```
+
+This command checks both result files and wrapper status sidecars. Raw result-file-only polling is forbidden for `tmux-pane` because pane creation and file presence alone are not terminal worker completion.
+
+For the Claude Code `team` backend, use the self-scheduled polling protocol below.
+
+
+
 1. Record the dispatched workers' Result Paths as the **pending set** (resolved to absolute from each launch prompt's `**Result Path:**` anchor header against `**Project Root:**`; the same paths recorded in run-manifest / team-state).
 2. Arm a SINGLE self-wakeup: one `Bash(run_in_background: true)` poll covering ALL dispatched workers (not one background task per worker):