okstra 0.132.0 → 0.134.0

package/runtime/python/okstra_token_usage/report.py

@@ -36,16 +36,45 @@ class SubstituteRefusedError(RuntimeError):
     """
 
 
-def _role_match(state_role: str, data_role: str) -> bool:
-    """Loose match between team-state worker role and data.json
-    executionStatus row role. team-state uses tags like ``claude-worker``
-    or ``report-writer``; data.json uses human strings like ``Claude
-    worker``. We normalise both to ``alnum-only-lowercase`` so the two
-    line up across rephrasings.
+def _norm(s: str) -> str:
+    """alnum-only lowercase, so role / agent / model line up across
+    rephrasings (``Claude worker`` vs ``claude``; ``gpt-5.6-sol`` vs
+    ``gpt56sol``)."""
+    return "".join(ch.lower() for ch in s if ch.isalnum())
+
+
+def _match_worker_index(row: dict, workers: list, used: set[int]) -> int | None:
+    """Pick the team-state worker that owns this executionStatus row, never
+    reusing a worker an earlier row already claimed.
+
+    A contract-following report names each row after its team-state worker
+    (``Claude worker``), so role equality / containment matches. A report
+    that instead used function roles (``Analysis verifier``, ``Acceptance
+    critic``) falls back to a *unique* provider(agent)+model match. When two
+    rows share one provider aggregate (codex verifier + critic → one ``Codex
+    worker``), only the first is attributed; the second stays null because
+    team-state holds no separate figure for it.
     """
-    def normalise(s: str) -> str:
-        return "".join(ch.lower() for ch in s if ch.isalnum())
-    return normalise(state_role) == normalise(data_role)
+    role = _norm(row.get("role", ""))
+    agent = _norm(row.get("agent", ""))
+    model = _norm(row.get("model", ""))
+    for i, worker in enumerate(workers):
+        if i in used:
+            continue
+        worker_role = _norm(worker.get("role", ""))
+        if worker_role and role and (
+            worker_role == role or worker_role in role or role in worker_role
+        ):
+            return i
+    candidates = [
+        i
+        for i, worker in enumerate(workers)
+        if i not in used
+        and _norm(worker.get("agent", ""))
+        and _norm(worker.get("agent", "")) in agent
+        and _norm(worker.get("model", "")) == model
+    ]
+    return candidates[0] if len(candidates) == 1 else None
 
 
 def _populate_execution_row(row: dict, source: dict) -> None:
@@ -179,17 +208,18 @@ def populate_data_token_cells(data_path: Path, team_state: dict) -> int:
     lead_source = {"usage": team_state.get("leadUsage") or {}}
     workers = team_state.get("workers") or []
     rows = data.get("executionStatus") or []
+    used_workers: set[int] = set()
     for row in rows:
         role = row.get("role", "")
         if "lead" in role.lower():
             _populate_execution_row(row, lead_source)
             changes += 1
             continue
-        for worker in workers:
-            if _role_match(worker.get("role", ""), role):
-                _populate_execution_row(row, worker)
-                changes += 1
-                break
+        idx = _match_worker_index(row, workers, used_workers)
+        if idx is not None:
+            used_workers.add(idx)
+            _populate_execution_row(row, workers[idx])
+            changes += 1
 
     data_path.write_text(
         json.dumps(data, indent=2, ensure_ascii=False) + "\n",

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

@@ -524,6 +524,7 @@
           "additionalProperties": false,
           "properties": {
             "h1": { "enum": ["local checkout", "push + PR", "skip"] },
+            "h1c": { "type": "string" },
             "h2": { "type": "string" },
             "h2b": {
               "enum": ["not-run", "clean", "proceed anyway", "change base branch", "cancel"]

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

@@ -37,6 +37,24 @@ Present a 3-option picker (`AskUserQuestion`):
 
 ## Mode A — Generate PR
 
+### A0. Branch naming (allowlist)
+
+Whenever this skill creates or proposes a head branch name, the prefix comes
+from this list and nothing else:
+
+| work kind | prefix |
+| --- | --- |
+| feature, improvement | `feature/` |
+| bug fix | `fix/` |
+| refactor | `refactor/` |
+| ops, chore | `ops/` |
+| unclassified | `task/` |
+
+`feat/`, `bugfix/`, `chore/`, `hotfix/` are not in the allowlist — do not emit
+them. This mirrors okstra's worktree branch namespace, whose SSOT is
+`_WORK_CATEGORY_NAMESPACE` in `scripts/okstra_ctl/worktree.py`. A branch name
+the user states explicitly wins verbatim; never rewrite it.
+
 ### A1. Pick a template
 
 ```bash

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/templates/reports/final-report.template.md

@@ -483,6 +483,9 @@ Carried-forward plan items retain their prior verdicts verbatim; each such item
 | {{ t("releaseHandoff.questionsTableHeader.questionId") }} | {{ t("releaseHandoff.questionsTableHeader.questionBody") }} | {{ t("releaseHandoff.questionsTableHeader.userResponse") }} | {{ t("releaseHandoff.questionsTableHeader.allowedOptions") }} |
 |---------|-----------|--------------------|--------------------|
 | H1 | {{ t("releaseHandoff.h1Body") }} | `{{ releaseHandoff.userSelections.h1 | mdcell }}` | `local checkout` / `push + PR` / `skip` |
+{% if releaseHandoff.userSelections.h1c %}
+| H1c | Local checkout target | `{{ releaseHandoff.userSelections.h1c | mdcell }}` | `whole-task branch` / `stage <N> stack branch` |
+{% endif %}
 | H2 | {{ t("releaseHandoff.h2Body") }} | `{{ (releaseHandoff.userSelections.h2 or t("releaseHandoff.h2DefaultLabel")) | mdcell }}` | {{ t("releaseHandoff.h2OptionsLabel") }} |
 | H2b | Merge conflict probe | `{{ (releaseHandoff.userSelections.h2b or releaseHandoff.mergeConflictProbe.kind) | mdcell }}` | `not-run` / `clean` / `proceed anyway` / `change base branch` / `cancel` |
 | H3 | {{ t("releaseHandoff.h3Body") }} | `{{ releaseHandoff.userSelections.h3 | mdcell }}` | `use as-is` / `edit then proceed` / `cancel` |

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(

package/src/commands/execute/handoff.mjs

@@ -14,7 +14,7 @@ Usage:
   okstra handoff record-pr --plan-run-root <dir> --stages 2,3 \\
     --branch <b> --url <u>
   okstra handoff local-checkout --project-root <dir> --project-id <id> \\
-    --task-group <g> --task-id <t>
+    --task-group <g> --task-id <t> [--stage <N>]
 
 Exit codes: 0 ok / 1 자격·전제 위반 / 2 stage 간 merge 충돌(conflicts 동봉)
 `;