okstra 0.133.0 → 0.135.0

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_artifact_paths.py

@@ -17,7 +17,11 @@ def audit_sidecar_rel(worker_result_rel: str) -> str:
     prefix, separator, suffix = basename.partition("-worker-")
     if not separator:
         raise WorkerArtifactPathError(
-            f"worker result path has no canonical -worker- token: {worker_result_rel}"
+            "worker result path has no canonical -worker- token: "
+            f"{worker_result_rel}. The audit sidecar is derived from the "
+            "canonical worker-result name `<role>-worker-<task-type>-<seq>.md` "
+            "(e.g. `codex-worker-implementation-001.md`); name the result that "
+            "way — a role label like `codex-verifier-...` drops the -worker- token."
         )
     audit_filename = f"{prefix}-worker-audit-{suffix}"
     return f"{directory}{slash}{audit_filename}" if slash else audit_filename

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,7 +178,58 @@ def _earliest_lead_session_ts(state: dict, team_state_path: Path) -> str | None:
     return earliest
 
 
-def resolve_run_window(team_state_path: Path, state: dict) -> tuple[str | None, str | None]:
+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, *, relax_start: bool = True
+) -> tuple[str | None, str | None]:
     """이 run 의 [시작, 종료] ISO 윈도우.
 
     in-session lead 는 자기 run 을 사용자의 *세션 전체* jsonl 에 기록하므로,
@@ -189,19 +240,34 @@ def resolve_run_window(team_state_path: Path, state: dict) -> tuple[str | None,
     status mtime → 현재 시각(아직 진행 중) 순으로 해소한다. 접미사를 못 뽑으면
     (None, None) — 윈도우 없이 전체를 세는 기존 동작으로 안전 폴백.
 
-    시작 완화: run-manifest createdAt 이 이 run 의 실제 lead/worker 세션보다
-    늦게 찍히면(관측: dev-9902 — createdAt 11:43Z 가 05:34Z 시작 세션보다 늦음)
-    since 가 앞선 세션을 잘라낸다. Task 3 이 기록한 `leadSessionIds[]` 세션의
-    첫 ts 최소값이 createdAt 보다 앞서면 그 값으로 since 를 앞당긴다.
-    `leadSessionIds` 부재(legacy)면 createdAt 그대로 — 기존 동작 불변."""
+    시작 완화(`relax_start`, 기본 True — 토큰 수집용): run-manifest createdAt 이
+    이 run 의 실제 lead/worker 세션보다 늦게 찍히면(관측: dev-9902 — createdAt
+    11:43Z 가 05:34Z 시작 세션보다 늦음) since 가 앞선 세션을 잘라낸다. Task 3 이
+    기록한 `leadSessionIds[]` 세션의 첫 ts 최소값이 createdAt 보다 앞서면 그 값으로
+    since 를 앞당긴다. `leadSessionIds` 부재(legacy)면 createdAt 그대로 — 기존
+    동작 불변. 완화 하한: 직전 run 의 종료 시각 이전으로는 내려가지 않는다
+    (`_previous_run_end`). 세션 jsonl 은 run 마다 새로 생기지 않으므로 하한이
+    없으면 같은 세션의 이전 run 이 이 윈도우에 통째로 들어온다.
+
+    `relax_start=False` (세션 스코프 검증기 전용 — session-conformance /
+    forbidden-actions): 완화를 건너뛰고 since 를 createdAt 에 고정한다. createdAt
+    은 prep 시각이라 이 run 의 lead·worker 활동보다 반드시 앞서므로 건전한 하한이고,
+    재사용 세션에 섞인 같은 세션의 이전 run·다른 task 활동을 창에서 배제한다
+    (dev-10172 D-3: 이전 planning run 의 phase-6/7 앵커, 다른 task 의 git push 를
+    이 run 의 위반으로 오탐하던 근본 원인). 완화는 토큰을 놓치지 않으려고 세션
+    birth 까지 내려가지만, 검증기에는 그 관대함이 곧 오탐이다."""
     suffix = run_artifact_suffix(team_state_path)
     if not suffix:
         return None, None
     run_dir = team_state_path.parent.parent
     since = _run_manifest_created_at(run_dir, suffix)
-    earliest = _earliest_lead_session_ts(state, team_state_path)
-    if earliest and (since is None or earliest < since):
-        since = earliest
+    if relax_start:
+        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/python/okstra_token_usage/pricing.py

@@ -4,7 +4,7 @@ Pricing is matched by substring against the model id recorded in the session
 transcript, so keys must reflect the *actual* model id form emitted by each
 provider:
 
-  * Anthropic — `claude-fable-5*`, `claude-opus-4-*`, `claude-sonnet-4-*`,
+  * Anthropic — `claude-fable-5*`, `claude-opus-5*`, `claude-opus-4-*`, `claude-sonnet-4-*`,
     `claude-haiku-4-5-*`, `claude-3-5-sonnet-*`, `claude-3-5-haiku-*`,
     `claude-3-opus-*`, `claude-3-haiku-*`.
   * OpenAI / Codex — `gpt-5*`, `gpt-4o*`, `gpt-4*`.
@@ -52,6 +52,9 @@ CLAUDE_PRICING = {
     # Claude Fable 5 (tier above Opus).
     "fable-5":    (10.0, 12.5, 1.0, 50.0),     # Fable 5 (cache prices derived from ratios)
 
+    # Claude Opus 5.
+    "opus-5":     (5.0, 6.25, 0.50, 25.0),     # Opus 5 (cache prices derived from ratios)
+
     # Claude 4 point releases (explicit so future divergence is easy to see).
     "opus-4-8":   (5.0, 6.25, 0.50, 25.0),     # Opus 4.8 (cache prices derived from ratios)
     "opus-4-7":   (5.0, 6.25, 0.50, 25.0),     # Opus 4.7 (cache prices derived from ratios)

package/runtime/skills/okstra-pr-gen/SKILL.md

@@ -96,6 +96,30 @@ diff and commits: describe only what actually changed. Mark checklist boxes
 docs box). If `commits`/`diffStat` are empty, tell the user there is nothing to
 describe and stop. **Never** append AI trailers/footers.
 
+### A3b. Identifier allowlist for the body
+
+Reviewers have never seen okstra, so an okstra-internal id reads as a nonsense
+token. Identifiers in the PR title and body come from this list and nothing else:
+
+| allowed | example |
+| --- | --- |
+| repo-relative source path, optionally with a line | `src/commands/pr/pr.mjs:42` |
+| symbol name that exists in the diff | `resolveTemplate()` |
+| branch name, commit subject, commit SHA | `feature/dev-9436`, `a1b2c3d` |
+| issue-tracker ticket id the reviewer can open | `dev-9436` |
+
+okstra's own artifact identifiers are out of the allowlist — drop them:
+
+- report item ids — `F-001`, `C-001`, `R-001`, `D-0001`, `PREP-001`
+- run artifact names and their `<task-type>-<seq>` suffixes —
+  `final-report-implementation-3.md`, `run-manifest-implementation-3.json`
+- phase / stage / worker labels — `final-verification`, `stage-2`, `codex-worker`
+- any path under `.okstra/` — reports, decisions, glossary, user-response sidecars
+
+When the only source for a claim is such an artifact, restate its substance in
+the reviewer's terms — what changed in the code, and why — instead of citing the
+id.
+
 ### A4. Output and offer to create the PR
 
 Print the filled PR body to chat as a single fenced markdown block. Then ask the

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

@@ -1,14 +1,16 @@
 ---
 name: okstra-user-response
 description: >-
-  Use this to answer an okstra task's open clarification questions in-session, without hand-editing any file. The tell is a request to respond to an okstra run's clarification items or its approval gate — "answer okstra", "I'll answer the questions", "clarification response", "user response", "approve and move on". This skill lists tasks whose latest report still has open clarification blockers, presents each open C-id (statement + recommended answer + alternatives), collects the user's own verbatim answers (or a reframe/hold), echoes the full sidecar back for an explicit "confirmed" acknowledgement, optionally records approval, and writes the `user-responses/` sidecar via `okstra user-response write`. NOT for starting a run (okstra-run), inspecting a finished task (okstra-inspect), or generating a brief (okstra-brief-gen). The skill never picks an answer for the user — it only relays recommendations and transcribes what the user decides.
+  Use this to answer an okstra task's open clarification questions in-session, without hand-editing any file. The tell is a request to respond to an okstra run's clarification items or its approval gate — "answer okstra", "I'll answer the questions", "clarification response", "user response", "approve and move on". This skill lists tasks whose latest report still has open clarification blockers, then walks the open C-ids one at a time — each rewritten as a self-contained question with background, three concrete answers (recommendation first) plus "Enter directly" — echoes the collected answers back for an explicit "confirmed" acknowledgement, optionally records approval, and writes the `user-responses/` sidecar via `okstra user-response write`. NOT for starting a run (okstra-run), inspecting a finished task (okstra-inspect), or generating a brief (okstra-brief-gen). The skill never picks an answer — it builds the option board and transcribes what the user decides.
 ---
 
 # OKSTRA User Response
 
 Single entry point for answering the clarification questions an okstra run left behind (the open `C-*` rows under the final report's `## 1. Clarification Items`) **in-session**, and recording those answers as a `runs/<type>/user-responses/` sidecar. The next `/okstra-run` auto-attaches this sidecar via `--clarification-response`.
 
-**Core principle — the skill never picks an answer for the user.** This skill only *presents* recommendations and alternatives; every `value` is the user's own verbatim input. It never calls `write` until the user has explicitly confirmed.
+**Core principle — the skill never picks an answer for the user.** It builds the option board — background, a self-contained question, three concrete answers, `Enter directly` — and the user alone picks from it; every `value` is what the user chose or typed. It never calls `write` until the user has explicitly confirmed.
+
+**Second principle — one question at a time.** Never batch two clarification items into one question, and never dump the whole open list at the user. Ask item 1, transcribe the answer, then ask item 2.
 
 | Sub-command | What it does |
 |---|---|
@@ -55,15 +57,15 @@ 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.
 
-## Step 2: Show open rows
+## Step 2: Fetch the open rows (data only — ask nothing yet)
 
 ```bash
 okstra user-response show --report <reportPath>
@@ -71,33 +73,79 @@ okstra user-response show --report <reportPath>
 
 Returns `{reportPath, rows: [{id, kind, blocks, status, statement, recommended, alternatives, contextRefs, resolvedRefs}]}`. `resolvedRefs` is `[{ref, definition}]` — the CLI has already looked up what each internal token (`RB-002`, `FU-001`, `§4.7`, …) means in the report body; `definition` is `null` only when the report text alone could not resolve it (e.g. a `path:line` pointer).
 
-**Do NOT paste the raw `statement` as the question.** A `statement` like `Rewrite RB-002 rollback (see §4.7)` is meaningless to the user on its own — that is the whole reason this skill exists. For each open `C-*` row, you MUST present:
+This call is a **data fetch, not a presentation step**. Do not print `rows` at the user, and do not paste a raw `statement` as a question — a `statement` like `Rewrite RB-002 rollback (see §4.7)` is meaningless on its own, which is the whole reason this skill exists. Announce only the count and the plan:
+
+> `<N>` open items — I'll go through them one at a time.
+
+Step 3 then turns exactly one row at a time into a question.
+
+## Step 3: Ask one item at a time (loop)
+
+Walk the open rows in report order. **One item per `AskUserQuestion` call** — never batch two items into one call, and never pre-announce the items still to come. Ask, transcribe, move on. Head each item with its position and what it is holding up:
+
+> **[2/5] C-014** — blocks: approval gate
+
+### 3a. Background first (plain text, above the picker)
+
+`AskUserQuestion` carries one sentence of question, so the background goes in the message text right before the call. Write these three blocks, **3–6 lines total** — enough that someone who never read the report can answer:
+
+1. **Situation** — what the run was doing when it stopped at this item, in the user's own domain terms.
+2. **What is undecided** — the actual fork, with every internal token expanded inline from `resolvedRefs[].definition`; the user must never need to know what `RB-002` is to answer. Say what is stuck right now in plain words: `blocks: approval` → the approval gate stays shut and `implementation` cannot start; `blocks: next-phase` → the next phase cannot begin.
+3. **What changes with your answer** — what each direction actually causes downstream.
+
+Where the background comes from — in this order:
+
+- `resolvedRefs[].definition`, which is already resolved and needs no file read;
+- when a `definition` is `null`, or the three blocks would otherwise be empty, **Read** the report `§`/`path:line` that this item's `contextRefs[]` points at and take it from there;
+- **never invent it.** If the report genuinely does not say why, write `The report states nothing beyond the statement itself.` and go straight to the question. Fabricated background corrupts the answer it collects.
+
+Close the background with the raw source on one line, so the mapping back to the report stays visible:
+
+> Source: `C-014` — "<raw statement>"
+
+### 3b. The picker — three answers plus `Enter directly`
+
+One `AskUserQuestion` (single-select), with exactly four options in this order:
+
+1. **The recommendation** — the answer from `recommended` restated in plain language, label suffixed `(Recommended)`; its description carries the rationale (the part of the `recommended` cell after `—`).
+2. **Alternative** — `alternatives[0]`.
+3. **Alternative** — `alternatives[1]`.
+4. **`Enter directly`** — always last, always present.
+
+Slots 2–3 fill from `alternatives[]` first. When `alternatives[]` is short, fill each remaining slot with the first of these that applies:
+
+- **a concrete candidate the report itself names** — another option row, an approach §2 rejected, a value already in use elsewhere. Its description must open with `Not an okstra proposal — from <where>` and cite that source.
+- **`Reframe this question`** — the item is held rather than answered, and the next run re-asks it.
+
+That last entry is what guarantees the picker always reaches three answers plus `Enter directly`. Never pad a slot with an option no source supports, and never mark anything but `recommended` as recommended.
+
+Keep each `label` to the answer itself (1–5 words); the description carries the consequence.
+
+### 3c. Transcribe the decision, then move on
 
-- **A rewritten, self-contained question** (lead with this): rewrite `statement` in plain language with **every internal token expanded inline** from its `resolvedRefs` `definition` — the user must never have to know what `RB-002` is to answer. If a token's `definition` is `null`, resolve it yourself **using Read** on the report `§`/`path:line` before asking; only if it is genuinely unresolvable do you say so plainly.
-- **`recommended`** — the answer okstra proposed (+ rationale), also stated in plain language. It is only a recommendation.
-- **`alternatives[]`** — list them if present, each in plain language.
-- **Raw source** (secondary, for traceability): the raw `id` + `statement` so the mapping back to the report stays visible.
+Record one entry — `{id, kind, value, rationale?, disposition}`, `kind` copied from the row `show` returned:
 
-## Step 3: Per-item — collect the user's decision (4 branches)
+| The user picks | `value` | `disposition` |
+|---|---|---|
+| Option 1–3 | that option's full answer text, not its short label | `answer` |
+| `Enter directly` → their own answer | the user's utterance verbatim (rationale into `rationale`) | `answer` |
+| `Reframe this question`, or free text asking for it to be re-asked | what the user wants re-asked, verbatim (empty → the raw statement) | `reframe` |
 
-For each open item, the user picks one of four dispositions. You relay and transcribe; you never choose:
+A reframe is not an answer, so it does not satisfy the approval gate.
 
-1. **Answer** — the user accepts the recommendation or gives their own answer. `disposition: "answer"`, `value` = the user's utterance verbatim.
-2. **Ask-to-explain (fallback)** — Step 2 already expanded every internal token, so the question should already be self-contained. If the user still asks "what does this mean?" or a `resolvedRefs` `definition` was `null`, open the report `§`/`path:line` that this item's `contextRefs[]` points at **using Read** and explain it in plain language. Only explain — **do not pick the answer for the user**; after explaining, hand the decision back to the user.
-3. **Free-form** — the user gives a narrative answer that matches neither a recommendation nor an alternative. `value` = that narrative verbatim, with the rationale in `rationale` if needed. `disposition: "answer"`.
-4. **Hold + reframe** — if the user asks to "re-frame this question itself", record it as `disposition: "reframe"`. Put what the user wants re-asked into `value` verbatim. A reframe is not an answer, so it does not satisfy the approval gate — the next run re-frames that question.
+If the user replies with a question instead of an answer ("what does this mean?"), record nothing: **Read** the `§`/`path:line` from `contextRefs[]`, explain it in plain language, and re-ask the same item with the same four options. Explain only — **do not resolve it for them**; the decision goes back to the user.
 
-Each answer item's JSON shape: `{id, kind, value, rationale?, disposition}`. `kind` uses the same `kind` that `show` gave for that row.
+Echo one line per finished item (`[2/5] C-014 → answer: 60s`), then ask the next one. Do not summarize the whole set until Step 4.
 
 ## Step 4: Echo the full sidecar back → explicit "confirmed" gate
 
-Once every open item is handled, **before** calling `write`, **echo back** everything collected (each `id`, `disposition`, `value`, `rationale` if present, and the approval decision from Step 5 below) to the user as-is. Then ask for explicit confirmation:
+Once the loop has covered every open item, **before** calling `write`, **echo back** everything collected (each `id`, `disposition`, `value`, `rationale` if present, and the approval decision from Step 5 below) to the user as-is. Then ask for explicit confirmation:
 
 > Record it as shown above? (Reply `confirmed` to write the sidecar.)
 
 - **Never call `write`** until the user says `confirmed` (or gives clear approval).
 - If the user changes any item, show the echo-back again with the changed value and re-confirm.
-- Every `value` must be the user's utterance verbatim — this gate guarantees that.
+- Every `value` must be what the user picked or typed, never a wording you settled on for them — this gate guarantees that.
 
 ## Step 5: (Optional) Record approval
 

package/runtime/validators/forbidden_actions.py

@@ -166,7 +166,7 @@ def scan_forbidden_actions(
         resolve_team_needles_with_source,
     )
 
-    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=claude_projects_dir