okstra 0.133.0 → 0.135.0

package/runtime/validators/validate-run.py

@@ -96,19 +96,28 @@ def utc_now() -> str:
 _CLI_WRAPPER_AGENTS = frozenset({"codex", "antigravity"})
 
 
-def _cli_wrapper_worker_labels(team_state: dict) -> frozenset[str]:
+def _unavailable_usage_worker_labels(team_state: dict) -> frozenset[str]:
     """Token-table row labels whose `--` cells are honest.
 
-    Mirrors `scripts/okstra_token_usage/report.py` `_worker_detail_label`
-    (`"{role} ({agent}, {status})"`) so the match is on the rendered label the
-    scanner actually sees.
+    Two ways a row legitimately renders `--`: a CLI-wrapper provider (tokens
+    live inside its own CLI) and any worker whose collected
+    `usage.source` is `unavailable`. The latter is not a value a worker typed —
+    the renderer (`okstra_token_usage/report.py` `_worker_detail_row`) emits
+    null cells for it, and the collector records *why* in the same block. Gating
+    it made an in-process worker the collector could not attribute fail the whole
+    run (observed dev-10172: no subagent jsonl carried the report-writer's
+    agentName, so a completed run was reported as contract-violated).
+
+    Labels mirror `_worker_detail_label` (`"{role} ({agent}, {status})"`) so the
+    match is on the rendered label the scanner actually sees.
     """
     labels = set()
     for worker in team_state.get("workers") or []:
         if not isinstance(worker, dict):
             continue
         agent = str(worker.get("agent") or "").strip()
-        if agent not in _CLI_WRAPPER_AGENTS:
+        usage = worker.get("usage") if isinstance(worker.get("usage"), dict) else {}
+        if agent not in _CLI_WRAPPER_AGENTS and usage.get("source") != "unavailable":
             continue
         role = str(worker.get("role") or worker.get("workerId") or "Worker").strip()
         status = str(worker.get("status") or "").strip()
@@ -3488,8 +3497,17 @@ def _validate_stage_carry_sidecar_exists(
     stage = evidence.get("stageNumber")
     if not isinstance(stage, int):
         return
-    # `report_path` is `runs/implementation/reports/final-report-...md`.
-    carry_path = report_path.parent.parent / "carry" / f"stage-{stage}.json"
+    # Carry sidecars are stage-SHARED: they live flat at
+    # `runs/implementation/carry/stage-<N>.json`, NOT under the stage-<N>/ run
+    # dir, because the next stage's carry-in and `consumers.backfill_done_from_carry`
+    # glob them without knowing the producing run's layout (storage-model.md
+    # §"representative files"). `report_path` is
+    # `runs/implementation/stage-<N>/reports/final-report-...md`, so drop the
+    # stage-<N>/ segment to reach the flat carry dir that `consumers` reads —
+    # resolving it under the stage run dir forced the lead to write the file twice.
+    run_dir = report_path.parent.parent
+    carry_root = run_dir.parent if _stage_isolated_name(run_dir) else run_dir
+    carry_path = carry_root / "carry" / f"stage-{stage}.json"
     if not carry_path.exists():
         failures.append(
             f"implementation run declares stage-{stage} sidecar evidence but "
@@ -5778,7 +5796,7 @@ def main() -> int:
         contract["required_agent_status_entries"],
         failures,
         allow_unavailable_token_usage=_session_accounting(team_state) == "artifact-only",
-        unavailable_ok_labels=_cli_wrapper_worker_labels(team_state),
+        unavailable_ok_labels=_unavailable_usage_worker_labels(team_state),
     )
     validate_team_state_usage(team_state, failures)
 

package/runtime/validators/validate_session_conformance.py

@@ -36,7 +36,7 @@ for _ssot_dir in (_VALIDATORS_DIR.parent / "scripts", _VALIDATORS_DIR.parent / "
 
 from okstra_ctl.worker_heartbeat import (  # noqa: E402
     HEARTBEAT_LINE_RE,
-    HEARTBEAT_MAX_GAP_SECONDS,
+    max_gap_seconds_after,
 )
 from okstra_ctl.wrapper_status import read_wrapper_status  # noqa: E402
 
@@ -66,7 +66,9 @@ _PROGRESS_LINE_RE = re.compile(
 # heartbeat 라인 shape 과 cadence 예산은 okstra_ctl.worker_heartbeat 정본을 쓴다 —
 # `okstra worker-liveness` 가 run 도중 같은 판정을 내리므로 정의가 갈리면 안 된다.
 _HEARTBEAT_LINE_RE = HEARTBEAT_LINE_RE
-_HEARTBEAT_MAX_GAP_SECONDS = HEARTBEAT_MAX_GAP_SECONDS
+
+# 장기 단계 중 append 되는 진행 라인 (claude-worker.md "Heartbeat").
+_IN_STAGE_PREFIX = "in-stage:"
 
 # Phase 5/6 진입 전 lead 가 Read 해야 하는 implementation 프로파일 sidecar.
 # 절대 경로는 레이어(repo / runtime / 설치본)마다 다르지만 basename 은 동일하다.
@@ -192,7 +194,7 @@ def _collect_lead_evidence(
     )
     from okstra_token_usage.paths import claude_project_dir
 
-    since, until = resolve_run_window(team_state_path, team_state)
+    since, until = resolve_run_window(team_state_path, team_state, relax_start=False)
     lead_sid = (team_state.get("lead") or {}).get("sessionId") or ""
     team_needles, _needle_source = resolve_team_needles_with_source(
         team_state, project_root, since, until, projects_root=projects_root
@@ -546,7 +548,10 @@ def _check_heartbeat_sidecar(path: Path, worker_id: str, errors: list[str]) -> N
         )
     if worker_id == "report-writer":
         for stage, _raw_ts in entries:
-            if stage not in _REPORT_WRITER_HEARTBEAT_STAGES:
+            # `in-stage:<stage>` 는 계약이 장기 단계에 요구하는 진행 라인이다 —
+            # allowlist 가 이를 배제하면 워커는 cadence 를 지킬 방법이 없다.
+            base = stage[len(_IN_STAGE_PREFIX):] if stage.startswith(_IN_STAGE_PREFIX) else stage
+            if base not in _REPORT_WRITER_HEARTBEAT_STAGES:
                 errors.append(
                     f"`{rel}`: heartbeat stage `{stage}` is not allowed for report-writer."
                 )
@@ -560,6 +565,7 @@ def _check_heartbeat_sidecar(path: Path, worker_id: str, errors: list[str]) -> N
             "stage must append its own line (agents/workers/claude-worker.md 'Heartbeat')."
         )
     prev: datetime | None = None
+    prev_stage = ""
     for stage, raw_ts in entries:
         ts = _parse_iso(raw_ts)
         if ts is None:
@@ -569,18 +575,22 @@ def _check_heartbeat_sidecar(path: Path, worker_id: str, errors: list[str]) -> N
             )
             continue
         if prev is not None:
+            # 예산은 구간을 여는 단계에서 고른다 — 이 공백이 재는 것은 직전에
+            # 선언된 단계의 작업 시간이다.
+            budget = max_gap_seconds_after(prev_stage)
             gap = (ts - prev).total_seconds()
             if gap < 0:
                 errors.append(
                     f"`{rel}`: heartbeat timestamps regress at stage `{stage}` ({raw_ts})."
                 )
-            elif gap > _HEARTBEAT_MAX_GAP_SECONDS:
+            elif gap > budget:
                 errors.append(
-                    f"`{rel}`: heartbeat gap before stage `{stage}` is {int(gap)}s — "
-                    "the append cadence MUST NOT exceed 5 minutes (+60s grace); emit "
+                    f"`{rel}`: heartbeat gap after stage `{prev_stage}` is {int(gap)}s "
+                    f"(budget {budget}s) — emit "
                     "`- PROGRESS: in-stage:<stage> <ISO>` during long stages."
                 )
         prev = ts
+        prev_stage = stage
 
 
 def _check_worker_liveness(