okstra 0.133.0 → 0.134.0

package/docs/for-ai/skills/okstra-user-response.md

@@ -34,7 +34,7 @@ okstra preflight --runtime claude-code --json
 
 ## Flow
 
-1. **list**: `okstra user-response list --home <home> --project <projectId> --limit 3` → an array of `{taskKey, taskType, seq, reportPath, reportMtime, openApprovalCount, unreadable}`. If the array is empty, stop with "no open clarification". A 3-option picker (top recommendations + the final option always "Enter directly" for pasting a `reportPath`/`task-key` directly). `unreadable:true` is a §1 format drift — flag it with `⚠` and do not proceed (do not fabricate rows).
+1. **list**: `okstra user-response list --home <home> --project <projectId> --limit 3` → an array of `{taskKey, taskType, seq, reportPath, reportMtime, openBlockerCount, openApprovalCount, unreadable}` (`openBlockerCount` = open rows with `Blocks` in `{approval, next-phase}`; `openApprovalCount` = the `approval`-only subset). If the array is empty, stop with "no open clarification". A 3-option picker (top recommendations + the final option always "Enter directly" for pasting a `reportPath`/`task-key` directly). `unreadable:true` is a §1 format drift — flag it with `⚠` and do not proceed (do not fabricate rows).
 2. **show**: `okstra user-response show --report <reportPath>` → `rows[]` with `resolvedRefs` (the `definition` of internal tokens such as `RB-002`/`§4.7`). **Do not paste the raw `statement` as the question.** For each open row present: (a) a **self-contained question** with internal tokens expanded inline first, (b) `recommended` (only a recommendation) in plain language, (c) `alternatives[]`, (d) the raw `id`+`statement` as a secondary traceability aid. If `definition` is `null`, resolve the report `§`/`path:line` yourself **using Read**.
 3. **decision (4 branches)**: the user picks one per item — Answer (accept the recommendation / own answer, verbatim), Ask-to-explain (explain only and hand the decision back to the user), Free-form (narrative verbatim), Hold+reframe (`disposition:"reframe"`, does not satisfy the approval gate). Each item's JSON: `{id, kind, value, rationale?, disposition}`.
 4. **echo → confirmed gate**: before `write`, echo the whole collection (each `id`·`disposition`·`value`·`rationale`·approval) as-is and get explicit confirmation. Never `write` before `confirmed`. On any change, re-echo and re-confirm.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.133.0",
+  "version": "0.134.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.133.0",
-  "builtAt": "2026-07-22T19:29:52.565Z",
+  "package": "0.134.0",
+  "builtAt": "2026-07-23T05:31:24.504Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/workers/report-writer-worker.md

@@ -41,7 +41,9 @@ Do NOT duplicate the data.json contents here — the data.json is the canonical
 
 ## Heartbeat (BLOCKING)
 
-Write the audit sidecar at `**Audit sidecar path:**` before required reading, then append `- PROGRESS: <stage> <ISO-8601-UTC>` at a cadence no longer than five minutes. Use only: `started`, `required-reading-complete`, `synthesis-start`, `data-json-write-start`, `render-start`, and `write-result-start`. The Phase 7 validator enforces the first stage, timestamps, cadence, and this allowlist.
+Write the audit sidecar at `**Audit sidecar path:**` before required reading, then append `- PROGRESS: <stage> <ISO-8601-UTC>` at a cadence no longer than five minutes. Use only: `started`, `required-reading-complete`, `synthesis-start`, `data-json-write-start`, `render-start`, and `write-result-start`. When a stage runs longer than that, append `- PROGRESS: in-stage:<stage> <ISO-8601-UTC>` with the same stage names. The Phase 7 validator enforces the first stage, timestamps, cadence, and this allowlist.
+
+`data-json-write-start`, `render-start` and `write-result-start` open a stretch whose work is one uninterruptible tool call, so no `in-stage:` line can be appended while it runs. Those three carry a 20-minute budget instead of five; every other stage keeps the five-minute cadence.
 
 ## Execution Rules
 

package/runtime/python/okstra_ctl/clarification_items.py

@@ -258,23 +258,44 @@ def parse_clarification_rows(report_text: str) -> list[dict]:
 
 UNRESOLVED_STATUSES = {"open", "answered"}
 
+# `Blocks` values that gate the user's `approved: true` flip.
+APPROVAL_BLOCKS = frozenset({"approval"})
+# `Blocks` values that owe the user an answer at all. `next-phase` rows never
+# gate approval, but the next phase cannot start with them open either, so the
+# user-response skill must list them — counting only `approval` made a report
+# whose open items were all `next-phase` look like it had none.
+USER_INPUT_BLOCKS = frozenset({"approval", "next-phase"})
+
 
 @dataclass(frozen=True)
-class ApprovalGateScan:
-    """Fail-closed read of the §1 approval gate.
+class ClarificationScan:
+    """Fail-closed read of §1 for rows blocking on one `Blocks` value set.
 
     ``unreadable_reason`` is ``None`` only when the scan is confident: §1
     parsed cleanly (or is the legitimate table-less placeholder) and
     ``blockers`` is therefore authoritative. A non-None reason means the
-    gate must refuse approval — never soft-pass.
+    caller must refuse to act — never soft-pass.
     """
     blockers: list[ClarificationItem]
     unreadable_reason: Optional[str]
 
 
-def scan_approval_gate(report_text: str) -> ApprovalGateScan:
+def scan_approval_gate(report_text: str) -> ClarificationScan:
     """Scan §1 for unresolved ``Blocks=approval`` rows (``Status`` in
     ``{open, answered}``), refusing to guess whenever the schema drifted."""
+    return scan_clarification_blockers(report_text, APPROVAL_BLOCKS)
+
+
+def scan_open_user_input(report_text: str) -> ClarificationScan:
+    """Scan §1 for every unresolved row that still owes the user an answer
+    (``Blocks`` in ``{approval, next-phase}``)."""
+    return scan_clarification_blockers(report_text, USER_INPUT_BLOCKS)
+
+
+def scan_clarification_blockers(
+    report_text: str, blocking_values: frozenset[str]
+) -> ClarificationScan:
+    """Shared fail-closed §1 walk for both gates above."""
     section = _section_1_slice(report_text)
     if section is None:
         if _LOOSE_SECTION_1_RE.search(report_text):
@@ -283,32 +304,33 @@ def scan_approval_gate(report_text: str) -> ApprovalGateScan:
                 "the schema heading format (anchor/format drift)"
             )
         else:
+            expected = "/".join(sorted(blocking_values))
             reason = (
                 "report has no `## 1. Clarification Items` section — the gate "
-                "cannot confirm there are no unresolved `Blocks=approval` rows"
+                f"cannot confirm there are no unresolved `Blocks={expected}` rows"
             )
-        return ApprovalGateScan([], reason)
+        return ClarificationScan([], reason)
     table = _walk_section_1_table(section)
     if table.items is None:
         if table.has_pipe_lines:
-            return ApprovalGateScan([], (
+            return ClarificationScan([], (
                 "§1 contains a table but its header row is not the schema "
                 "header (`| ... | Statement | Expected form | User input |`)"
             ))
         # Renderer's emptyState placeholder: heading is intact and no table
-        # was emitted — confidently "no approval-blocking items".
-        return ApprovalGateScan([], None)
+        # was emitted — confidently "no blocking items".
+        return ClarificationScan([], None)
     if table.unparsed_row_count:
-        return ApprovalGateScan([], (
+        return ClarificationScan([], (
             f"§1 table has {table.unparsed_row_count} row(s) whose metadata "
             "cell could not be parsed (Blocks/Status markers missing or "
             "malformed)"
         ))
     blockers = [
         it for it in table.items
-        if it.blocks == "approval" and it.status in UNRESOLVED_STATUSES
+        if it.blocks in blocking_values and it.status in UNRESOLVED_STATUSES
     ]
-    return ApprovalGateScan(blockers, None)
+    return ClarificationScan(blockers, None)
 
 
 # 느슨한 §1 헤딩 탐지: 엄격한 SECTION_HEADING_PATTERN 이 실패해도 이게 매칭되면

package/runtime/python/okstra_ctl/run.py

@@ -1326,7 +1326,12 @@ def _resolve_pr_template(inp: PrepareInputs) -> tuple[str, str]:
 
 @dataclass
 class _ModelBindings:
-    """이 run 의 lead/worker 모델 + critic + executor 바인딩."""
+    """이 run 의 lead/worker 모델 + critic + executor 바인딩.
+
+    `*_execution` 은 dispatch 에 쓰이는 CLI 신원 철자다. 카탈로그 값과 달리
+    provider CLI 조회를 거치므로 실패할 수 있고, 그래서 이 묶음에서 함께
+    해소한다 — prepare 가 run seq 를 할당하거나 worktree 를 만들기 전에.
+    """
 
     lead: ModelAssignment
     cw: ModelAssignment
@@ -1338,6 +1343,9 @@ class _ModelBindings:
     executor_display_name: str
     executor_worker_agent: str
     executor_model_meta: ModelAssignment
+    codex_worker_execution: str
+    antigravity_worker_execution: str
+    executor_execution: str
 
 
 def recommended_role_models() -> dict[str, str]:
@@ -1413,6 +1421,12 @@ def _resolve_model_bindings(inp: PrepareInputs, workers: list[str]) -> _ModelBin
         executor_display_name=display_name,
         executor_worker_agent=worker_agent,
         executor_model_meta=model_meta,
+        codex_worker_execution=_worker_execution_value(
+            m["co"], "codex", "worker", workers),
+        antigravity_worker_execution=_worker_execution_value(
+            m["ge"], "antigravity", "worker", workers),
+        executor_execution=_normalized_execution(
+            model_meta, provider=executor_provider, role="executor"),
     )
 
 
@@ -2176,22 +2190,16 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         "CLAUDE_WORKER_MODEL": cw.display,
         "CLAUDE_WORKER_MODEL_EXECUTION_VALUE": cw.execution,
         "CODEX_WORKER_MODEL": co.display,
-        "CODEX_WORKER_MODEL_EXECUTION_VALUE": _worker_execution_value(
-            co, "codex", "worker", workers,
-        ),
+        "CODEX_WORKER_MODEL_EXECUTION_VALUE": models.codex_worker_execution,
         "ANTIGRAVITY_WORKER_MODEL": ge.display,
-        "ANTIGRAVITY_WORKER_MODEL_EXECUTION_VALUE": _worker_execution_value(
-            ge, "antigravity", "worker", workers,
-        ),
+        "ANTIGRAVITY_WORKER_MODEL_EXECUTION_VALUE": models.antigravity_worker_execution,
         "REPORT_WRITER_MODEL": rw.display,
         "REPORT_WRITER_MODEL_EXECUTION_VALUE": rw.execution,
         "EXECUTOR_PROVIDER": executor_provider,
         "EXECUTOR_DISPLAY_NAME": executor_display_name,
         "EXECUTOR_WORKER_AGENT": executor_worker_agent,
         "EXECUTOR_MODEL_DISPLAY": executor_model_meta.display,
-        "EXECUTOR_MODEL_EXECUTION_VALUE": _normalized_execution(
-            executor_model_meta, provider=executor_provider, role="executor",
-        ),
+        "EXECUTOR_MODEL_EXECUTION_VALUE": models.executor_execution,
         "CRITIC_CHOICE": critic_choice,
         "RELATED_TASKS_JSON": related_tasks_json_str,
         "RELATED_TASKS_BULLETS": bullets,

package/runtime/python/okstra_ctl/session.py

@@ -65,17 +65,46 @@ def _session_has_agent_name(jsonl_path: Path) -> bool:
     return False
 
 
+def _session_mentions(jsonl_path: Path, needle: str) -> bool:
+    """세션 transcript 어딘가에 *needle* 문자열이 등장하는가."""
+    try:
+        with jsonl_path.open(encoding="utf-8", errors="ignore") as fh:
+            return any(needle in line for line in fh)
+    except OSError:
+        return False
+
+
+def resolve_lead_session_id_for_run(project_root: Path, run_dir: Path) -> str:
+    """`run_dir` 를 다룬 lead 세션 중 가장 최근 수정된 것의 id, 없으면 ''.
+
+    프로젝트 디렉토리의 최신 jsonl 을 그대로 집으면(``resolve_inproc_lead_session_id``)
+    같은 프로젝트에서 동시에 도는 **다른 태스크의 세션**이 잡힌다 — 실측
+    (dev-10172): 남의 세션이 `leadSessionIds` 에 들어가 run 비용이 $80 → $207 로
+    부풀고, 그 세션의 PROGRESS 라인이 conformance 스캔에 섞여 오탐을 냈다.
+    자기 run 의 산출물 경로를 언급한 세션만 후보로 인정해 그 오염을 막는다.
+    """
+    proj_dir = _claude_projects_dir_for(project_root)
+    try:
+        candidates = [p for p in proj_dir.iterdir() if p.suffix == ".jsonl"]
+    except OSError:
+        return ""
+    needle = str(run_dir)
+    for path in sorted(candidates, key=lambda p: p.stat().st_mtime, reverse=True):
+        if _session_has_agent_name(path):
+            continue
+        if _session_mentions(path, needle):
+            return path.stem
+    return ""
+
+
 def record_observed_lead_session(project_root: Path, team_state_path: Path) -> str:
-    """현재 live lead 세션을 관측해 team-state 에 append(멱등). 워커 세션이거나
-    관측 실패·중복이면 '' 반환. 재발급으로 갈린 세대를 축1 이 여기에 모은다.
+    """이 run 의 live lead 세션을 관측해 team-state 에 append(멱등). 이 run 을
+    다룬 lead 세션을 못 찾거나 중복이면 '' 반환. 재발급으로 갈린 세대를 축1 이
+    여기에 모은다.
     """
-    sid = resolve_inproc_lead_session_id(project_root)
+    sid = resolve_lead_session_id_for_run(project_root, team_state_path.parent.parent)
     if not sid:
         return ""
-    proj_dir = _claude_projects_dir_for(project_root)
-    jsonl = proj_dir / f"{sid}.jsonl"
-    if _session_has_agent_name(jsonl):
-        return ""
     try:
         state = json.loads(team_state_path.read_text(encoding="utf-8"))
     except (OSError, json.JSONDecodeError):

package/runtime/python/okstra_ctl/user_response.py

@@ -24,7 +24,7 @@ from okstra_ctl.report_view_artifacts import user_responses_dir_for_report
 from okstra_ctl.listing import list_runs, absolute_final_report_path
 from okstra_ctl.clarification_items import (
     parse_clarification_rows,
-    scan_approval_gate,
+    scan_open_user_input,
     section_1_present_but_unparsed,
     _section_1_slice,
 )
@@ -118,7 +118,13 @@ def _seq_from_report(report: Path) -> str:
 
 
 def list_awaiting_tasks(home: Path, project_id: str, limit: int) -> list[dict]:
-    """approval-open clarification 이 있는 태스크를 최신 report mtime 순으로."""
+    """사용자 답변을 기다리는 clarification 이 있는 태스크를 최신 report mtime 순으로.
+
+    `Blocks=approval` 만 세면 열린 항목이 전부 `Blocks=next-phase` 인 리포트가
+    빈 목록으로 보이고, 스킬의 picker 자체에 진입할 수 없다(실측: dev-10172 —
+    열린 4건이 모두 next-phase 라 `list` 가 `[]` 를 냈다). 승인 게이트 판정은
+    `scan_approval_gate` 쪽 소비자들의 몫이고, 여기서는 답변 대기 전체를 센다.
+    """
     seen: set[str] = set()
     out: list[dict] = []
     for row in list_runs(home, project=project_id, limit=0):  # startedAt desc
@@ -131,18 +137,21 @@ def list_awaiting_tasks(home: Path, project_id: str, limit: int) -> list[dict]:
         if report is None or not report.is_file():
             continue
         text = report.read_text(encoding="utf-8")
-        scan = scan_approval_gate(text)
+        scan = scan_open_user_input(text)
         base = {"taskKey": key, "taskType": row.get("taskType", ""),
                 "seq": _seq_from_report(report), "reportPath": str(report),
                 "reportMtime": report.stat().st_mtime}
         if scan.unreadable_reason is not None:
             # §1 heading exists but drifted → real warning; §1 simply absent → skip.
             if section_1_present_but_unparsed(text):
-                out.append({**base, "openApprovalCount": 0, "unreadable": True})
+                out.append({**base, "openBlockerCount": 0, "openApprovalCount": 0,
+                            "unreadable": True})
             continue
         if not scan.blockers:
             continue
-        out.append({**base, "openApprovalCount": len(scan.blockers), "unreadable": False})
+        approval_count = sum(1 for it in scan.blockers if it.blocks == "approval")
+        out.append({**base, "openBlockerCount": len(scan.blockers),
+                    "openApprovalCount": approval_count, "unreadable": False})
     out.sort(key=lambda t: t["reportMtime"], reverse=True)
     return out[:limit] if limit > 0 else out
 

package/runtime/python/okstra_ctl/worker_heartbeat.py

@@ -9,6 +9,7 @@ the cadence budget live here rather than in either consumer.
 from __future__ import annotations
 
 import re
+from dataclasses import dataclass
 from datetime import datetime, timezone
 from pathlib import Path
 
@@ -21,6 +22,36 @@ HEARTBEAT_LINE_RE = re.compile(
 # 고정 grace 60초를 더한다.
 HEARTBEAT_MAX_GAP_SECONDS = 5 * 60 + 60
 
+# 단일 도구 호출이 구간 전체를 차지해 워커가 하트비트를 끼워 넣을 수 없는 단계.
+# 한 번의 Write 가 진행되는 동안에는 `in-stage:` 라인도 append 할 수 없으므로
+# 5분 예산으로는 살아 있는 워커가 stalled 로 판정된다 (실측 dev-10172:
+# report-writer 가 74KB data.json 한 개를 쓰는 11분 동안 무하트비트).
+SINGLE_WRITE_STAGES = frozenset({
+    "data-json-write-start",
+    "render-start",
+    "write-result-start",
+})
+SINGLE_WRITE_MAX_GAP_SECONDS = 20 * 60 + 60
+
+
+def max_gap_seconds_after(stage: str) -> int:
+    """*stage* 를 알린 뒤 다음 하트비트까지 허용되는 최대 공백(초).
+
+    간격이 재는 것은 직전에 선언된 단계의 작업 시간이므로, 예산은 언제나
+    구간을 *여는* 단계에서 고른다."""
+    return (
+        SINGLE_WRITE_MAX_GAP_SECONDS
+        if stage in SINGLE_WRITE_STAGES
+        else HEARTBEAT_MAX_GAP_SECONDS
+    )
+
+
+@dataclass(frozen=True)
+class Heartbeat:
+    """사이드카에 기록된 하나의 heartbeat."""
+    stage: str
+    at: datetime
+
 
 def parse_timestamp(raw: str) -> datetime | None:
     """A heartbeat's ISO-8601 timestamp as an aware datetime, or None."""
@@ -31,7 +62,7 @@ def parse_timestamp(raw: str) -> datetime | None:
     return parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc)
 
 
-def latest_heartbeat(sidecar: Path) -> datetime | None:
+def latest_heartbeat(sidecar: Path) -> Heartbeat | None:
     """The newest parseable heartbeat in *sidecar*, or None when it has none.
 
     Takes the maximum rather than the last line: a regressing timestamp is the
@@ -42,9 +73,9 @@ def latest_heartbeat(sidecar: Path) -> datetime | None:
         text = sidecar.read_text(encoding="utf-8")
     except OSError:
         return None
-    stamps = [
-        parsed
+    beats = [
+        Heartbeat(match.group("stage"), parsed)
         for match in HEARTBEAT_LINE_RE.finditer(text)
         if (parsed := parse_timestamp(match.group("ts"))) is not None
     ]
-    return max(stamps) if stamps else None
+    return max(beats, key=lambda beat: beat.at) if beats else None

package/runtime/python/okstra_ctl/worker_liveness.py

@@ -28,7 +28,11 @@ import sys
 from datetime import datetime, timezone
 from pathlib import Path
 
-from okstra_ctl.worker_heartbeat import HEARTBEAT_MAX_GAP_SECONDS, latest_heartbeat
+from okstra_ctl.worker_heartbeat import (
+    HEARTBEAT_MAX_GAP_SECONDS,
+    latest_heartbeat,
+    max_gap_seconds_after,
+)
 
 DEFAULT_LAUNCH_GRACE_SECONDS = 60
 
@@ -39,7 +43,12 @@ def _log_path(prompt: Path) -> Path:
 
 
 def probe_heartbeat(sidecar: Path, now: datetime, max_idle: float) -> dict:
-    """Liveness of one in-process worker, read from its audit sidecar."""
+    """Liveness of one in-process worker, read from its audit sidecar.
+
+    ``max_idle`` is the floor. A stage whose work is one uninterruptible tool
+    call carries its own, longer budget (``max_gap_seconds_after``) — during a
+    single large Write the worker cannot append a heartbeat at all.
+    """
     probe = {"kind": "heartbeat", "path": str(sidecar)}
     if not sidecar.is_file():
         # The worker writes the sidecar early but not instantly; absence is the
@@ -52,15 +61,19 @@ def probe_heartbeat(sidecar: Path, now: datetime, max_idle: float) -> dict:
             "state": "stalled",
             "reason": "audit sidecar carries no `- PROGRESS:` heartbeat",
         }
-    idle = (now - beat).total_seconds()
-    state = "stalled" if idle > max_idle else "live"
+    budget = max(max_idle, max_gap_seconds_after(beat.stage))
+    idle = (now - beat.at).total_seconds()
+    state = "stalled" if idle > budget else "live"
     return {
         **probe,
         "state": state,
         "idleSeconds": int(idle),
-        "lastHeartbeat": beat.isoformat(),
+        "lastHeartbeat": beat.at.isoformat(),
+        "lastStage": beat.stage,
+        "budgetSeconds": int(budget),
         "reason": (
-            f"no heartbeat for {int(idle)}s (budget {int(max_idle)}s)"
+            f"no heartbeat for {int(idle)}s after stage `{beat.stage}` "
+            f"(budget {int(budget)}s)"
             if state == "stalled"
             else ""
         ),

package/runtime/python/okstra_ctl/worktree.py

@@ -284,6 +284,43 @@ def _branch_exists(project_root: Path, branch: str) -> bool:
     return res.returncode == 0
 
 
+def _branch_checkout_path(project_root: Path, branch: str) -> str:
+    """The worktree that currently has *branch* checked out, or "" when none does.
+
+    `git branch -D` refuses to delete a checked-out branch, so an existing-branch
+    error that only recommends `-D` is unfollowable whenever the branch is the
+    main checkout's HEAD. Callers use this to name the extra step instead.
+    """
+    res = _git(project_root, "worktree", "list", "--porcelain")
+    if res.returncode != 0:
+        return ""
+    current = ""
+    for line in res.stdout.splitlines():
+        if line.startswith("worktree "):
+            current = line[len("worktree "):].strip()
+        elif line.strip() == f"branch refs/heads/{branch}":
+            return current
+    return ""
+
+
+def _branch_exists_message(project_root: Path, branch: str, kind: str) -> str:
+    """Existing-branch error text whose remedy is actually runnable."""
+    checkout = _branch_checkout_path(project_root, branch)
+    if checkout:
+        return (
+            f"{kind} worktree branch already exists: {branch}, and it is checked "
+            f"out at {checkout}. `git branch -D {branch}` will refuse while it is "
+            f"checked out — switch that checkout to another branch first "
+            f"(`git -C {checkout} switch <other-branch>`), then delete it, or "
+            "choose a different work-category before retrying."
+        )
+    return (
+        f"{kind} worktree branch already exists: {branch}. "
+        f"Delete it (`git branch -D {branch}`) or choose a different "
+        "work-category before retrying."
+    )
+
+
 def _head_sha(cwd: Path) -> str:
     res = _git(cwd, "rev-parse", "HEAD")
     if res.returncode != 0:
@@ -768,11 +805,7 @@ def provision_task_worktree(
             "(or `rm -rf` if it is not a registered worktree) before retrying."
         )
     if _branch_exists(project_root, branch):
-        raise RuntimeError(
-            f"task worktree branch already exists: {branch}. "
-            "Delete it (`git branch -D <branch>`) or choose a different "
-            "work-category before retrying."
-        )
+        raise RuntimeError(_branch_exists_message(project_root, branch, "task"))
 
     main_root = main_worktree_path(project_root)
     requested_base = (base_ref or "").strip()
@@ -921,10 +954,7 @@ def provision_stage_worktree(
             f"{worktree_path}. Remove it before retrying."
         )
     if _branch_exists(project_root, branch):
-        raise RuntimeError(
-            f"stage worktree branch already exists: {branch}. "
-            "Delete it (`git branch -D <branch>`) before retrying."
-        )
+        raise RuntimeError(_branch_exists_message(project_root, branch, "stage"))
 
     main_root = main_worktree_path(project_root)
     resolved_sha = _resolve_commit_sha(main_root, base_commit)

package/runtime/python/okstra_token_usage/collect.py

@@ -178,6 +178,55 @@ def _earliest_lead_session_ts(state: dict, team_state_path: Path) -> str | None:
     return earliest
 
 
+def _previous_run_suffix(run_dir: Path, suffix: str) -> str | None:
+    """같은 task-type 에서 이 run 직전에 실행된 run 의 접미사, 없으면 None.
+
+    seq 는 연속이 아닐 수 있으므로(실패한 prep 이 번호를 소모한다) manifest 를
+    실제로 스캔해 현재 seq 미만 중 최대를 고른다."""
+    task_type, _, raw_seq = suffix.rpartition("-")
+    if not task_type or not raw_seq.isdigit():
+        return None
+    current = int(raw_seq)
+    prefix, width = f"run-manifest-{task_type}-", len(raw_seq)
+    earlier = []
+    try:
+        names = [p.name for p in (run_dir / "manifests").iterdir()]
+    except OSError:
+        return None
+    for name in names:
+        if not (name.startswith(prefix) and name.endswith(".json")):
+            continue
+        candidate = name[len(prefix):-len(".json")]
+        if candidate.isdigit() and int(candidate) < current:
+            earlier.append(int(candidate))
+    if not earlier:
+        return None
+    return f"{task_type}-{max(earlier):0{width}d}"
+
+
+def _previous_run_end(run_dir: Path, suffix: str) -> str | None:
+    """직전 run 의 종료 시각 — 종료 산출물이 없으면 그 run 의 시작 시각.
+
+    `since` 완화의 하한이다. 한 세션에서 같은 task-type 을 두 번 돌리면
+    `leadSessionIds` 의 세션 jsonl 첫 ts 는 *첫 run* 의 시작을 가리키므로,
+    완화를 그대로 두면 seq002 의 윈도우가 seq001 구간을 통째로 삼킨다 —
+    seq001 의 PROGRESS 체크포인트가 seq002 검증에 섞여 순서 오탐을 낸다
+    (관측: dev-10172 — seq002 검증이 seq001 의 phase-6 타임스탬프를 인용)."""
+    prev = _previous_run_suffix(run_dir, suffix)
+    if prev is None:
+        return None
+    try:
+        prev_state = json.loads(
+            (run_dir / "state" / f"team-state-{prev}.json").read_text()
+        )
+        ended_at = prev_state.get("runEndedAt")
+        if ended_at:
+            return str(ended_at)
+    except (OSError, json.JSONDecodeError):
+        pass
+    return _run_end_estimate(run_dir, prev) or _run_manifest_created_at(run_dir, prev)
+
+
 def resolve_run_window(team_state_path: Path, state: dict) -> tuple[str | None, str | None]:
     """이 run 의 [시작, 종료] ISO 윈도우.
 
@@ -193,7 +242,11 @@ def resolve_run_window(team_state_path: Path, state: dict) -> tuple[str | None,
     늦게 찍히면(관측: dev-9902 — createdAt 11:43Z 가 05:34Z 시작 세션보다 늦음)
     since 가 앞선 세션을 잘라낸다. Task 3 이 기록한 `leadSessionIds[]` 세션의
     첫 ts 최소값이 createdAt 보다 앞서면 그 값으로 since 를 앞당긴다.
-    `leadSessionIds` 부재(legacy)면 createdAt 그대로 — 기존 동작 불변."""
+    `leadSessionIds` 부재(legacy)면 createdAt 그대로 — 기존 동작 불변.
+
+    완화 하한: 직전 run 의 종료 시각 이전으로는 내려가지 않는다
+    (`_previous_run_end`). 세션 jsonl 은 run 마다 새로 생기지 않으므로 하한이
+    없으면 같은 세션의 이전 run 이 이 윈도우에 통째로 들어온다."""
     suffix = run_artifact_suffix(team_state_path)
     if not suffix:
         return None, None
@@ -202,6 +255,9 @@ def resolve_run_window(team_state_path: Path, state: dict) -> tuple[str | None,
     earliest = _earliest_lead_session_ts(state, team_state_path)
     if earliest and (since is None or earliest < since):
         since = earliest
+    floor = _previous_run_end(run_dir, suffix)
+    if floor and since and since < floor:
+        since = floor
     until = state.get("runEndedAt") or _run_end_estimate(run_dir, suffix) or utc_now()
     return since, until
 

package/runtime/skills/okstra-user-response/SKILL.md

@@ -55,10 +55,10 @@ okstra user-response list --home <resolved-home> --project <projectId> --limit 3
 ```
 
 Returns a JSON array (latest report mtime first); each entry:
-`{taskKey, taskType, seq, reportPath, reportMtime, openApprovalCount, unreadable}`.
+`{taskKey, taskType, seq, reportPath, reportMtime, openBlockerCount, openApprovalCount, unreadable}`. `openBlockerCount` counts every open row that still owes the user an answer (`Blocks` = `approval` or `next-phase`); `openApprovalCount` is the `approval`-only subset that gates the frontmatter `approved` flip.
 
 - Empty array → answer `No task has open clarification items.` and stop.
-- Otherwise present a **3-option picker**: the top recommendations from the list (each shown as `taskKey (taskType, N open items)`), and the **final option is always "Enter directly"** — where the user pastes a `reportPath` or a `task-key` directly (for a task not in the top-3 window).
+- Otherwise present a **3-option picker**: the top recommendations from the list (each shown as `taskKey (taskType, <openBlockerCount> open items)`), and the **final option is always "Enter directly"** — where the user pastes a `reportPath` or a `task-key` directly (for a task not in the top-3 window).
 - An entry with `unreadable: true` means its `## 1. Clarification Items` heading exists but drifted from the expected format. Flag it as `⚠ §1 format drift — the CLI could not parse its items` and do not proceed on it until the report is regenerated; do not fabricate rows for it.
 
 Carry the chosen entry's `reportPath` and `taskKey` forward.

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()
@@ -5778,7 +5787,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 은 동일하다.
@@ -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(