okstra 0.131.1 → 0.133.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.131.1",
+  "version": "0.133.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.131.1",
-  "builtAt": "2026-07-22T05:33:21.666Z",
+  "package": "0.133.0",
+  "builtAt": "2026-07-22T19:29:52.565Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/prompts/lead/report-writer.md

@@ -158,8 +158,8 @@ The template renders this table in the merged record-meta shape (same pattern as
 ```
 
 Table Generation Rules:
-- The first row derives its agent identifier and role from `team-state.lead.agent` / `team-state.lead.role` and its usage data from `leadUsage`; subsequent rows follow `recommendedWorkers` / `resultContract.requiredWorkerRoles` order.
-- Every worker agent identifier and role derives from its persisted team-state entry; the common contract does not infer labels from provider names.
+- **Exactly one row per team-state entry: the lead, then one per `team-state.workers[]` — never more, never fewer.** The first row's agent / role / usage come from `team-state.lead.agent` / `team-state.lead.role` / `leadUsage`. Each later row copies its `agent`, `role`, and `model` **verbatim from a `team-state.workers[]` entry** (e.g. role `Claude worker`, `Codex worker`, `Report writer worker`), ordered to follow `recommendedWorkers` / `resultContract.requiredWorkerRoles`. Do not infer labels from provider names.
+- **Never split one worker into multiple function rows or invent role labels** (`Analysis verifier`, `Acceptance critic`, …). A provider that played several roles — e.g. codex ran both the analysis-verify pass and the acceptance-critic pass — is still **one** `team-state.workers[]` entry with **one** usage figure: name the roles it played in that row's *Summary of Key Findings* cell, not in extra rows. Extra or renamed rows break Phase-7 token attribution, which keys each row's tokens to a single team-state worker — a split or renamed row lands as `--`.
 - **Raw tokens** = `usage.totalTokens` (input + output + cache_creation + cache_read; the raw volume processed).
 - **Billable tokens** = `usage.billableEquivalentTokens` (cache reads weighted at 0.1×, cache_creation 1.25×, output 5×; useful as a single number for "how big was this session in cost terms").
 - **Cost (USD)** = `usage.estimatedCostUsd`. For Codex/Antigravity workers that actually invoked the CLI, append `(+ CLI $X.XX)` from `usage.cliEstimatedCostUsd`.
@@ -314,6 +314,8 @@ Every field MUST anchor its claim with at least one evidence reference — a `pa
 ### Writing Guidelines
 
 - Write in Markdown. **Prefer tables over prose bullet lists** for any section that enumerates multiple items with the same shape (evidence rows, risks, options, dependencies, rollback steps, follow-ups, open questions). Bullets are reserved for short, single-line standalone statements (e.g., "- No additional information requested."). When the template provides a table form, do NOT degrade it back to bullets in the rendered report. **Exception — `## Background and Rationale` (`rationale`) is deliberately prose**: it is connected narrative explaining the *why*, not a same-shape enumeration, so write full sentences there rather than forcing it into a table.
+- **Do not restate the same conclusion verbatim across sections.** The Verdict Card and Reader Summary are *digests*: give the outcome in one or two sentences and point to `## 7. Final Verdict` / `## 5.8.8 Routing Recommendation` for the full reasoning, rather than copying their multi-clause conclusion word-for-word. Only the `Verdict Token` / `Direction` / `Next Step` cells must byte-match §7 (per the Verdict Card contract above); the prose conclusion must not be a duplicate.
+- **Keep each sentence to one main idea.** A single sentence that stacks four or five clauses with em-dashes and nested parentheticals (300+ characters) is hard to read, and the renderer can only line-break at sentence ends — so break such reasoning into separate sentences. Facts, evidence, and IDs still live in the tables; prose carries only the connective *why*.
 - Write the final report body in the language passed in **Report Language**
   above (`en` or `ko`). The template's fixed labels (section asides,
   empty-states, token summary, column headers, release-handoff labels)

package/runtime/prompts/profiles/final-verification.md

@@ -27,7 +27,7 @@
 - Pre-verification entry gate (resolved & enforced by `okstra render-bundle` prep — the lead does NOT recompute it):
   - the verification target (scope / worktree / base / stages / source reports / diff stat) is injected as the `VERIFICATION_TARGET` block. The lead MUST treat it as authoritative and MUST NOT re-pick a target from the brief.
   - **whole-task scope** (`--stage auto`, default): prep has already verified every Stage Map stage is `status:done` in `consumers.jsonl`, every done stage's `head_commit` is an ancestor of the task worktree HEAD (all stage branches merged), and the worktree is clean outside `.okstra/`. If any check failed the run never started (PrepareError); a started whole-task run is therefore a fully-merged, clean target.
-    - **whole-task is a mutating phase, not a read-only one.** On entry, whole-task mode auto-merges (with `--no-ff`) the done stages not yet merged into the task branch to create an integration commit, then removes the cleanupable stage worktrees, registry stage-keys, and stage branches. If a merge conflict occurs it reports the conflicting files and aborts (the user resolves them manually and retries). A stage worktree with uncommitted changes remaining is preserved. Therefore the "fully-merged, clean target" the entry gate above refers to is the state after this auto-integration step completes, and whole-task final-verification must be treated as a mutating phase that creates the integration commit.
+    - **whole-task is a mutating phase, not a read-only one.** On entry, whole-task mode auto-merges (with `--no-ff`) the done stages not yet merged into the task branch to create an integration commit, then removes the cleanupable stage worktrees and marks their registry stage-keys released. The stage branches are kept as the reviewable stack (the target of `okstra handoff local-checkout --stage <N>`). If a merge conflict occurs it reports the conflicting files and aborts (the user resolves them manually and retries). A stage worktree with uncommitted changes remaining is preserved. Therefore the "fully-merged, clean target" the entry gate above refers to is the state after this auto-integration step completes, and whole-task final-verification must be treated as a mutating phase that creates the integration commit.
   - **single-stage scope** (`--stage N`): prep verified stage N is `status:done` and its isolated stage worktree exists and is clean. Other stages' state is irrelevant. A single-stage run is a partial verification: it MUST NOT recommend plain `release-handoff`, but MAY recommend `release-handoff(stage-group)` when the verdict is `accepted` — the stage becomes PR-eligible for a stage-group handoff.
   - the lead still captures `git status --short` from the injected worktree to confirm the analysis ran against the delivered work-tree state; an unexpected divergence (dirty tree outside `.okstra/`, missing worktree) is a `tool-failure`, not a silent proceed.
 - Worker verification procedure:

package/runtime/prompts/profiles/implementation.md

@@ -29,7 +29,7 @@
   - Base ref: `{{EXECUTOR_WORKTREE_BASE_REF}}` — canonical `<base>` for every `git diff` / `git log` in this run. Independent stages start from the common anchor (the task-key worktree HEAD, fixed once at first stage entry); dependent stages start from the predecessor done commit or the verified merged task worktree head.
   - Provisioning note: `{{EXECUTOR_WORKTREE_NOTE}}`
   - Treat the working-tree path as `project_root` for the duration of this run. Do NOT mutate the caller's original checkout. cwd-sensitive Bash commands MUST be prefixed `cd {{EXECUTOR_WORKTREE_PATH}} && ` in the same Bash invocation (never `bash -lc "..."` wrappers — see executor sidecar for full rules).
-  - Lifecycle: kept after the run completes as this stage's evidence worktree. Later stages get their own stage worktrees. Manual cleanup: `git worktree remove <path>` → `git branch -D <branch>` → drop the stage-key registry entry (`<task-key>#stage-<N>`). Exception: whole-task `final-verification` auto-merges every done stage and tears down its worktree/branch/registry key (`stage_integrate.integrate_stages`, `teardown=True`) — do not promise the user the worktree survives past that point.
+  - Lifecycle: kept after the run completes as this stage's evidence worktree. Later stages get their own stage worktrees. Manual cleanup: `git worktree remove <path>` → `git branch -D <branch>` → drop the stage-key registry entry (`<task-key>#stage-<N>`). Exception: whole-task `final-verification` auto-merges every done stage and removes its worktree directory (`stage_integrate.integrate_stages`, `teardown=True`) — do not promise the user the worktree survives past that point. The stage BRANCH does survive: it is kept so the stack stays reviewable and `okstra handoff local-checkout --stage <N>` still has a target.
 - Approval gate (phase-specific addendum to shared authority rule):
   - the pre-implementation gate's recorded user approval marker is the only authorised approval gate at this phase — proceed once it is satisfied without further external coordination.
 - Forbidden actions — universal (any occurrence → terminal status `contract-violated`):

package/runtime/prompts/profiles/release-handoff.md

@@ -20,13 +20,13 @@
   - the lead MUST confirm `git log --oneline <base>..HEAD` contains at least one implementation commit. If it is empty, the run MUST end with status `blocked` and route back to `implementation`.
 - User interaction protocol (Claude lead — performed in order, using `AskUserQuestion` or the equivalent interactive prompt):
   1. **Action selection** — present three choices and capture exactly one:
-     - `local checkout` (whole-task mode only) — bring the verified task branch into the MAIN worktree for local testing (no push, no PR). See step 1c. When `HANDOFF_MODE` is `stage-group`, do NOT offer this option — tell the user "`local checkout` is whole-task mode only" and re-ask.
+     - `local checkout` — bring a verified branch into the MAIN worktree for local testing (no push, no PR). Two targets: the whole-task branch (whole-task mode only), or a single stage's stack branch (`--stage N`, available in both modes since stage branches survive verification). See step 1c. When `HANDOFF_MODE` is `stage-group`, offer only the per-stage target.
      - `push + PR` — push the feature branch, then open or reuse a pull request.
      - `skip` — cancel delivery actions for now: record that release-handoff was intentionally skipped and end the run without any git command.
      If the user picks `skip`, route directly to the final-report self-review pass.
-  1c. **Local checkout execution** (only when the user picked `local checkout`) — confirm with the user that okstra will remove the okstra task worktree and `git checkout <feature branch>` in the MAIN worktree, and that the base branch is never modified. On confirmation run:
-      `okstra handoff local-checkout --project-root <project root> --project-id <id> --task-group <g> --task-id <t>`
-      Exit 1 means a precondition failed (MAIN worktree dirty, registry entry missing, or checkout failed): show the error verbatim and re-ask the action selection. On success the okstra task worktree no longer exists — the lead's cwd is gone, so EVERY subsequent step (final-report authoring included) MUST use absolute paths or run from the MAIN worktree. Then route to the final-report self-review pass.
+  1c. **Local checkout execution** (only when the user picked `local checkout`) — first ask which target — when `HANDOFF_MODE` is `whole-task`, offer both the whole-task branch and one stage's stack branch; when it is `stage-group`, offer only the per-stage target — listing the selectable stage numbers (from the approved plan's Stage Map, since the run input document carries no Stage Map). Then confirm with the user that okstra will remove the corresponding okstra worktree (when it still exists) and `git checkout <branch>` in the MAIN worktree, and that the base branch is never modified. On confirmation run:
+      `okstra handoff local-checkout --project-root <project root> --project-id <id> --task-group <g> --task-id <t>` — append `--stage <N>` for the per-stage target.
+      Exit 1 means a precondition failed (MAIN worktree dirty, registry entry missing, or checkout failed): show the error verbatim and re-ask the action selection. On success the okstra worktree for that target no longer exists — if the lead's cwd was inside it, EVERY subsequent step (final-report authoring included) MUST use absolute paths or run from the MAIN worktree. Then route to the final-report self-review pass.
   - **stage-group mode step order** (overrides the default Q1→Q3 sequence): after Q1 picks `push + PR`, run (1) base-branch selection first — identical to Q2 below, because the dependency-closure check needs `origin/<base>`; (2) G2 stage confirmation (step 1g); (3) assemble (step 2g); then Q2b and Q3 as usual, with the collector branch as the PR head.
   1g. **G2 — stage confirmation**: the stage selection already happened before the run (wizard `handoff_stage_pick`, or the CLI `--stages` flag) and is fixed in `HANDOFF_STAGES`. Display it as a one-line confirmation (`PR target stage: <csv> — proceeding`) and proceed; do NOT re-ask the multi-select. Only if `HANDOFF_MODE` is `stage-group` but `HANDOFF_STAGES` is empty (defensive, should not happen) run `okstra handoff eligible --plan-run-root <plan-run-root> --approved-plan <approved plan path>` and ask the user to pick from the eligible stages.
   2g. **assemble**: run `okstra handoff assemble --plan-run-root <...> --approved-plan <...> --project-root <project root> --project-id <id> --task-group <g> --task-id <t> --work-category <c> --stages <csv> --base <chosen-base>`. Exit 2 means a stage-vs-stage merge conflict: show the `conflicts` paths and stop (route: reshape the group or resolve manually). Exit 1 means an eligibility/closure violation: show the error verbatim and re-ask G2. On success the returned `branch` is the PR head branch for every subsequent step.
@@ -69,6 +69,7 @@
   - **Feature Branch & Working-Tree State**: branch name from `git rev-parse --abbrev-ref HEAD`, output of `git status --short` at run start.
   - **User Selections**: a block recording each prompt and the user's verbatim answer.
     - Q1 action: `local checkout` | `push + PR` | `skip`.
+    - Q1c checkout target (only when Q1 is `local checkout`): `whole-task branch` | `stage <N> stack branch`, plus the `--stage <N>` value this answer produced (or `no --stage` for the whole-task branch). Record it in the `User Selections` row `H1c` (`userSelections.h1c`); omit the row entirely when Q1 was not `local checkout`.
     - Q2 PR base (if applicable): the chosen branch and how it was selected (menu pick vs free-form input).
     - Q2b merge-conflict probe (if applicable): `not-run` | `clean` (no conflict, no prompt shown) | `proceed anyway` | `change base branch` | `cancel`. Record it in both the `User Selections` row `H2b` and the `Merge Conflict Probe` deliverable. When a conflict was detected, list the conflicting paths.
     - Q3 title/body: `use as-is` | `edit then proceed` (with a diff between the lead's draft and the final text) | `cancel`.
@@ -85,7 +86,9 @@
     - `- PR creation skipped: <reason>` for any user-driven cancellation
   - **Local Checkout Outcome**: one of
     - `- Not run (user picked push + PR or skip).`
-    - `- Checked out <branch> into <main worktree path>; okstra task worktree <path> removed. Next: to run a local test and then open a PR, re-enter release-handoff via okstra-run → push + PR.`
+    - `- Checked out <branch> into <main worktree path>; okstra worktree <path> removed. Next: to run a local test and then open a PR, re-enter release-handoff via okstra-run → push + PR.`
+    - `- Checked out <branch> into <main worktree path>; no okstra worktree removed (already torn down — the branch survived). Next: to run a local test and then open a PR, re-enter release-handoff via okstra-run → push + PR.`
+    - Pick between the two `Checked out` variants by the command's `removedWorktree` field: a non-empty path takes the first, an empty string takes the second. Never write a removal that did not happen.
   - **Stage Group** (stage-group mode only): selected stages, each stage's single-stage verification report path + quoted `Verdict Token` row, collector branch name, merge commit SHAs from assemble, and the dependency-closure verdict (from the assemble output / error).
   - **Routing recommendation**: explicit `done` token, since release-handoff is the terminal lifecycle phase. If the run ended in `skip` or `cancel`, the recommendation MUST also state whether re-entry into release-handoff is appropriate.
 - Self-review pass before finalising the report (`Claude lead` runs this):

package/runtime/python/okstra_ctl/handoff.py

@@ -244,11 +244,12 @@ def assemble(*, project_root, plan_run_root, stage_map, stages, base_branch,
 
 
 def _remove_task_worktree(main_wt, target: str) -> Optional[str]:
-    """clean 으로 확인된 task-key 워크트리를 제거. 이미 없으면 no-op.
-    실패하면 사람이 읽을 detail 문자열, 성공/부재면 None.
-    nested stage 워크트리가 남아있으면 제거하지 않는다 — --force 로 지우면 물리
-    디렉터리만 사라지고 git/registry 의 stage-key admin 엔트리가 고아로 남는다.
-    통합/teardown 이 끝나 nested 가 없을 때만 제거한다."""
+    """Remove an okstra worktree — task-key or stage — already confirmed clean
+    by the caller. No-op when it is already gone. Returns a human-readable
+    detail string on failure, None on success or absence.
+    Refuses while a nested worktree remains inside the target — a --force
+    removal would drop only the physical directory and leave git's and the
+    registry's stage-key admin entries orphaned."""
     if not Path(target).exists():
         return None  # 이미 teardown 됨 — checkout 으로 진행
     nested = nested_worktree_excludes(target)
@@ -260,40 +261,78 @@ def _remove_task_worktree(main_wt, target: str) -> Optional[str]:
     return None
 
 
-def local_checkout(*, project_root, project_id, task_group, task_id) -> Dict[str, Any]:
-    """whole-task: okstra task-key 워크트리를 제거하고 task 브랜치를 메인
-    워크트리에 checkout 한다(브랜치 보존). 메인·대상 워크트리가 dirty 면 거부.
-    base 브랜치는 건드리지 않는다."""
-    entry = worktree_registry.lookup(project_id, task_group, task_id)
-    if not entry or not entry.branch or not entry.worktree_path:
+def _local_checkout_target(project_id, task_group, task_id,
+                           stage: Optional[int]) -> Tuple[str, str]:
+    """Resolve (branch, worktree_path) for a local checkout. `stage` selects
+    the stage-key row; None selects the task-key row. The returned path is ""
+    only when the row carries no `worktree_path`; teardown does not clear it,
+    so a torn-down stage yields a stale path to a directory that no longer
+    exists. The caller must probe the path before acting on it.
+
+    An `active` row is refused: `status == "active"` is the occupancy SSOT a
+    concurrent run holds (`worktree_registry.list_active_stage_numbers` feeds
+    the stage resolver), and local checkout would remove that run's worktree
+    and release its reservation, letting a third `--stage auto` run claim the
+    same stage."""
+    if stage is None:
+        entry = worktree_registry.lookup(project_id, task_group, task_id)
+        if not entry or not entry.branch or not entry.worktree_path:
+            raise HandoffError(
+                "task-key worktree registry 엔트리가 없습니다 — local checkout 대상 없음")
+        if entry.status == "active":
+            raise HandoffError(
+                "task 워크트리를 실행 중인 런이 점유하고 있습니다 (status=active) — "
+                "그 런이 끝나 점유가 해제된 뒤 다시 시도하세요")
+        return entry.branch, entry.worktree_path
+    row = worktree_registry.get_stage_row(project_id, task_group, task_id, stage)
+    if not row or not row.get("branch"):
         raise HandoffError(
-            "task-key worktree registry 엔트리가 없습니다 — local checkout 대상 없음")
+            f"stage {stage} 의 worktree registry 엔트리가 없습니다 — "
+            "local checkout 대상 없음")
+    if row.get("status") == "active":
+        raise HandoffError(
+            f"stage {stage} 를 실행 중인 런이 점유하고 있습니다 (status=active) — "
+            "그 런이 끝나 점유가 해제된 뒤 다시 시도하세요")
+    return row["branch"], row.get("worktree_path") or ""
+
+
+def local_checkout(*, project_root, project_id, task_group, task_id,
+                   stage: Optional[int] = None) -> Dict[str, Any]:
+    """okstra 워크트리를 제거하고 대상 브랜치를 메인 워크트리에 checkout 한다
+    (브랜치 보존). stage 를 주면 그 stage 의 스택 브랜치가, 주지 않으면 whole-task
+    브랜치가 대상이다. 메인·대상 워크트리가 dirty 면 거부. base 브랜치는
+    건드리지 않는다."""
+    branch, wt_path = _local_checkout_target(
+        project_id, task_group, task_id, stage)
     main_wt = main_worktree_path(Path(project_root))
     if is_dirty_excluding_okstra(main_wt):
         raise HandoffError(
             f"메인 워크트리에 미커밋 변경이 있습니다 ({main_wt}) — "
             "커밋/스태시 후 다시 시도하세요")
-    # 제거 게이트는 파괴 대상인 task-key 워크트리를 검사해야 한다 (메인 아님).
-    if (Path(entry.worktree_path).exists()
-            and is_dirty_excluding_okstra(entry.worktree_path)):
-        raise HandoffError(
-            f"task 워크트리에 미커밋 변경이 있습니다 ({entry.worktree_path}) — "
-            "해당 워크트리에서 커밋/스태시 후 다시 시도하세요")
-    detail = _remove_task_worktree(main_wt, entry.worktree_path)
-    if detail is not None:
-        raise HandoffError(
-            f"task 워크트리 제거 실패 ({entry.worktree_path}): {detail} — "
-            "nested stage 워크트리가 남아있거나 통합이 미완료일 수 있습니다. "
-            "먼저 stage 통합/teardown 하거나 수동으로 "
-            f"`git worktree remove {entry.worktree_path}` 후 다시 시도하세요")
-    worktree_registry.release_status(project_id, task_group, task_id)
-    co = _git(Path(main_wt), "checkout", entry.branch)
+    removed = ""
+    # The removal gate must inspect the okstra worktree being destroyed, not main.
+    # A torn-down stage leaves a stale path in its row, so probe the directory.
+    if wt_path and Path(wt_path).exists():
+        if is_dirty_excluding_okstra(wt_path):
+            raise HandoffError(
+                f"okstra 워크트리에 미커밋 변경이 있습니다 ({wt_path}) — "
+                "해당 워크트리에서 커밋/스태시 후 다시 시도하세요")
+        detail = _remove_task_worktree(main_wt, wt_path)
+        if detail is not None:
+            raise HandoffError(
+                f"워크트리 제거 실패 ({wt_path}): {detail} — "
+                "위 사유를 해소한 뒤 다시 시도하세요")
+        removed = wt_path
+    worktree_registry.release_status(project_id, task_group, task_id,
+                                     stage_number=stage)
+    co = _git(Path(main_wt), "checkout", branch)
     if co.returncode != 0:
+        removal = f"워크트리는 제거됨({removed})" if removed else "제거된 워크트리 없음"
         raise HandoffError(
-            f"git checkout {entry.branch} 실패: {co.stderr.strip()} — 워크트리는 "
-            f"제거됨; 메인({main_wt})에서 수동 checkout 으로 복구하세요")
-    return {"ok": True, "branch": entry.branch, "mainWorktreePath": str(main_wt),
-            "removedWorktree": entry.worktree_path, "status": "checked-out"}
+            f"git checkout {branch} 실패: {co.stderr.strip()} — {removal}; "
+            f"메인({main_wt})에서 수동 checkout 으로 복구하세요")
+    return {"ok": True, "branch": branch, "mainWorktreePath": str(main_wt),
+            "removedWorktree": removed, "status": "checked-out", "stage": stage}
 
 
 def _impl_task_key_for(rows: List[Dict[str, Any]], stage: int) -> str:
@@ -413,6 +452,7 @@ def main(argv: Optional[list] = None) -> int:
     sp.add_argument("--project-id", required=True)
     sp.add_argument("--task-group", required=True)
     sp.add_argument("--task-id", required=True)
+    sp.add_argument("--stage", type=int, default=None)
 
     a = p.parse_args(argv)
     try:
@@ -436,7 +476,7 @@ def main(argv: Optional[list] = None) -> int:
             out = local_checkout(
                 project_root=Path(a.project_root).resolve(),
                 project_id=a.project_id, task_group=a.task_group,
-                task_id=a.task_id)
+                task_id=a.task_id, stage=a.stage)
         else:
             out = record_pr(plan_run_root=Path(a.plan_run_root),
                             stages=_parse_stages_csv(a.stages),

package/runtime/python/okstra_ctl/model_discovery.py

@@ -71,11 +71,12 @@ def codex_availability(config_path: Path | None = None) -> tuple[str, ...]:
 
 
 def normalize_execution_for_dispatch(
-    *, provider: str, execution: str, display: str, role: str,
+    *, provider: str, execution: str, role: str,
 ) -> str:
-    """Return the CLI-accepted spelling of `execution`, or the value unchanged
-    when discovery is unavailable. Raise ModelUnavailableError when the identity
-    is definitely not offered (never substitute a different model)."""
+    """Return the CLI-accepted spelling of `execution`. When discovery is
+    unavailable, fall back to the best-known dispatchable spelling rather than
+    blocking. Raise ModelUnavailableError when the identity is definitely not
+    offered (never substitute a different model)."""
     if provider == "codex":
         available = codex_availability()
         if not available or execution in available:
@@ -86,13 +87,19 @@ def normalize_execution_for_dispatch(
         )
     if provider != "antigravity":
         return execution  # claude runs via the Agent tool
+    # agy bakes the tier into the model identity as a slug suffix
+    # (`gemini-3.1-pro-high`) and rejects the bare slug with "requires --effort"
+    # — a flag the wrapper never sends. So the suffixed form is the only
+    # dispatchable spelling, including on the un-verified fallback below.
+    tiered = f"{execution}-{role_effort(role).lower()}"
     available = agy_models()
     if not available:
-        return execution  # discovery unavailable → status quo, wrapper still guards
-    want = f"{display} ({role_effort(role)})"
-    if want in available:
-        return want
+        return tiered  # discovery unavailable → dispatch anyway, wrapper still guards
+    if execution in available:
+        return execution  # identity already carries its tier (agy's Claude models)
+    if tiered in available:
+        return tiered
     raise ModelUnavailableError(
-        f"antigravity model {want!r} (from catalog {execution!r}, role {role!r}) "
+        f"antigravity model {tiered!r} (from catalog {execution!r}, role {role!r}) "
         f"is not offered by this agy install. Available: {', '.join(available)}"
     )

package/runtime/python/okstra_ctl/models.py

@@ -36,11 +36,12 @@ CLAUDE = {
     "claude-haiku-4-5": ModelSpec("haiku-4-5", "claude-haiku-4-5"),
     "claude-haiku-4-5-20251001": ModelSpec("haiku-4-5", "claude-haiku-4-5-20251001"),
 }
-# The `agy` CLI accepts DISPLAY names with an effort suffix (e.g.
-# "Gemini 3.1 Pro (High)"), not `gemini-3.x` slugs, and its list is
-# host/version-specific. model_discovery.normalize_execution_for_dispatch maps
-# each ModelSpec.display + role effort to the exact `agy models` identifier at
-# dispatch time. agy also serves Claude/GPT-OSS models on some installs.
+# `agy` rejects a bare execution slug — it demands a tier, spelled as a suffix
+# on the slug itself ("gemini-3.1-pro-high"), and its list is host/version-
+# specific. model_discovery.normalize_execution_for_dispatch appends the role's
+# effort to ModelSpec.execution at dispatch time. `display` is okstra-facing
+# only and never reaches agy. agy also serves Claude/GPT-OSS models on some
+# installs; those carry their tier inline and take no suffix.
 ANTIGRAVITY = {
     "gemini-3.1-pro": ModelSpec("Gemini 3.1 Pro", "gemini-3.1-pro", in_picker=True),
     "gemini 3.1 pro": ModelSpec("Gemini 3.1 Pro", "gemini-3.1-pro"),

package/runtime/python/okstra_ctl/render_final_report.py

@@ -308,6 +308,113 @@ def _build_index(headings: list, definitions: list, labels: dict) -> list[str]:
     return block
 
 
+# --- Prose ventilation post-render pass -----------------------------------
+# Split prose paragraphs at sentence boundaries so raw markdown reads one
+# sentence per line; the HTML view turns those newlines into <br>
+# (report_views._markdown_to_html). Prose only — table cells already carry
+# their own <br>, and headings / lists / code / blockquotes must stay intact.
+# A leading-whitespace line is a list continuation, not a prose paragraph:
+# only column-0 non-block lines are treated as prose (allowlist).
+_LIST_LINE_RE = re.compile(r"^\s*(?:[-*]\s|\d+\.\s)")
+_SENT_BOUNDARY_RE = re.compile(r"[.?!][ \t]+(?=\S)")
+# Trailing tokens whose dot is not a sentence end (compared lowercased with
+# the trailing dot stripped).
+_ABBREV = {
+    "e.g", "i.e", "etc", "cf", "vs", "al", "no", "fig",
+    "dr", "mr", "ms", "inc", "ltd", "jr", "sr",
+}
+
+
+def _code_span_mask(text: str) -> list[bool]:
+    """Mark every char inside an inline-code span (and the backticks that
+    fence it) so sentence detection never fires on a `.` in a path or id."""
+    mask = [False] * len(text)
+    in_code = False
+    for i, ch in enumerate(text):
+        if ch == "`":
+            in_code = not in_code
+            mask[i] = True
+        else:
+            mask[i] = in_code
+    return mask
+
+
+def _ventilate_text(text: str, *, sep: str) -> str:
+    """Insert ``sep`` after each sentence-ending ``.``/``?``/``!`` that is
+    followed by whitespace. Skips marks inside inline-code spans, numbers /
+    decimals, ellipses, and known abbreviations. ``sep`` is ``"\\n"`` for
+    prose lines (raw-markdown ventilation) and ``"<br>"`` for table cells /
+    list items, where a bare newline would break the row / list structure.
+
+    Masking code spans (rather than splitting on backticks and ventilating
+    each segment) is what lets a boundary sitting right before an inline-code
+    span split — the segment approach missed it at the segment edge.
+    """
+    if not text:
+        return text
+    mask = _code_span_mask(text)
+    out: list[str] = []
+    last = 0
+    for match in _SENT_BOUNDARY_RE.finditer(text):
+        mark = match.start()  # index of the punctuation
+        if mask[mark]:
+            continue
+        prev = text[mark - 1] if mark > 0 else ""
+        # A number, a bare-digit, or an ellipsis dot is not a sentence end.
+        if not prev or prev.isspace() or prev.isdigit() or prev == ".":
+            continue
+        tail = re.search(r"[A-Za-z.]+$", text[: mark + 1])
+        if tail and tail.group(0).rstrip(".").lower() in _ABBREV:
+            continue
+        out.append(text[last : mark + 1])  # up to and including the mark
+        out.append(sep)
+        last = match.end()  # drop the inter-sentence whitespace
+    out.append(text[last:])
+    return "".join(out)
+
+
+def _ventilate_table_row(line: str) -> str:
+    """Ventilate each cell of a pipe-table row with ``<br>``. A newline
+    would truncate the row, so table cells (which already carry ``<br>`` for
+    stacked meta) use ``<br>``. The header separator row (``|---|:--:|``) has
+    no prose and is left alone."""
+    if set(line.strip()) <= set("|-: "):
+        return line
+    cells = UNESCAPED_PIPE_RE.split(line)
+    for k in range(1, len(cells)):  # skip cells[0] (indent / pre-border)
+        cells[k] = _ventilate_text(cells[k], sep="<br>")
+    return "|".join(cells)
+
+
+def _ventilate_list_item(line: str) -> str:
+    """Ventilate a list item's body with ``<br>`` (a newline would end the
+    item), preserving the bullet / number marker and any indent."""
+    marker = _LIST_LINE_RE.match(line).group(0)
+    return marker + _ventilate_text(line[len(marker):], sep="<br>")
+
+
+def _ventilate_prose(markdown: str) -> str:
+    """Break prose into one sentence per line. Column-0 paragraphs split on a
+    newline (clean raw markdown); table cells and list items split on ``<br>``
+    (a newline there would break the row / list). Headings, blockquotes, and
+    indented continuation lines are left intact. Idempotent: a single-sentence
+    span has no internal boundary to split."""
+    lines = markdown.split("\n")
+    mask = _code_line_mask(lines)
+    for i, line in enumerate(lines):
+        if mask[i] or not line:  # frontmatter / fenced code / blank
+            continue
+        if _HEADING_RE.match(line) or line.startswith(">"):
+            continue
+        if line.lstrip().startswith("|"):
+            lines[i] = _ventilate_table_row(line)
+        elif _LIST_LINE_RE.match(line):
+            lines[i] = _ventilate_list_item(line)
+        elif line == line.lstrip():  # column-0 prose (not indented continuation)
+            lines[i] = _ventilate_text(line, sep="\n")
+    return "\n".join(lines)
+
+
 def _inject_index_and_anchors(markdown: str, dictionary: dict | None) -> str:
     """Append scroll anchors + a top-of-report index to a rendered report.
     Idempotent: re-running on already-anchored markdown is a no-op for
@@ -500,7 +607,8 @@ def render(
     try:
         template = env.get_template(template_path.name)
         rendered = template.render(**data)
-        return _inject_index_and_anchors(rendered, dictionary)
+        rendered = _inject_index_and_anchors(rendered, dictionary)
+        return _ventilate_prose(rendered)
     except I18nError as exc:
         raise FinalReportRenderError(
             f"i18n lookup failed while rendering {template_path.name}: {exc}"

package/runtime/python/okstra_ctl/report_views.py

@@ -399,7 +399,9 @@ def _markdown_to_html(
             para_lines.append(ln)
             i += 1
         if para_lines:
-            out.append("<p>" + _inline(" ".join(para_lines)) + "</p>")
+            # The renderer's prose ventilation puts one sentence per source
+            # line; join with <br> so those breaks survive into the HTML.
+            out.append("<p>" + _inline("<br>".join(para_lines)) + "</p>")
 
     return "\n".join(out), headings
 

package/runtime/python/okstra_ctl/run.py

@@ -1421,7 +1421,7 @@ def _normalized_execution(meta: ModelAssignment, provider: str, role: str) -> st
     so the manifest carries the dispatch-correct spelling. SSOT for the mapping
     lives in model_discovery; this is only the run.py call seam."""
     return normalize_execution_for_dispatch(
-        provider=provider, execution=meta.execution, display=meta.display, role=role,
+        provider=provider, execution=meta.execution, role=role,
     )
 
 

package/runtime/python/okstra_ctl/stage_integrate.py

@@ -2,7 +2,8 @@
 
 Phase A: stage done commit 을 task 브랜치에 위상순 --no-ff 머지(이미 머지면
 skip, 충돌이면 해당 머지만 abort 후 IntegrateError). Phase B: 머지/skip 된
-stage 의 worktree·registry 키·stage 브랜치를 정리(dirty 면 skip).
+stage 의 worktree 디렉터리와 registry 키를 정리(dirty 면 skip). stage 브랜치는
+스택 보존을 위해 삭제하지 않는다.
 설계: docs/superpowers/specs/2026-06-20-stage-auto-integrate-teardown-design.md
 """
 from __future__ import annotations
@@ -64,7 +65,7 @@ def integrate_stages(
 ) -> IntegrateResult:
     """whole-task 통합: Phase A 머지 → Phase B teardown.
 
-    teardown=False 면 Phase B(stage worktree·브랜치·registry 키 정리)를 건너뛴다 —
+    teardown=False 면 Phase B(stage worktree 디렉터리·registry 키 정리)를 건너뛴다 —
     container 는 머지만 하고 stage 트리를 보존한다(스펙 §10). final-verification
     호출은 기본값(True)으로 기존 행위를 유지한다."""
     from .consumers import latest_done_by_stage
@@ -137,11 +138,39 @@ def _remove_clean_worktree(task_wt: str, wt: str, stage_n: int) -> tuple[str, st
     return None
 
 
+def _unmerged_branch_tip_warning(task_wt: str, stage_n: int, branch: str) -> str:
+    """Warn text when the stage branch tip is not an ancestor of the task
+    worktree HEAD, or "" when it is (or cannot be resolved).
+
+    Phase A merges `done.head_commit`, never the branch ref, so a stage branch
+    can carry commits that whole-task verification never saw. `local-checkout
+    --stage <N>` hands that branch to the user as a verified branch, so the
+    divergence has to be reported."""
+    from .worktree import is_ancestor
+
+    tip = _git(task_wt, "rev-parse", "--verify", "--quiet", branch)
+    if tip.returncode != 0:
+        return ""
+    sha = tip.stdout.strip()
+    head = _git(task_wt, "rev-parse", "HEAD").stdout.strip()
+    if is_ancestor(task_wt, sha, head):
+        return ""
+    return (f"stage {stage_n} 브랜치 {branch} 의 tip {sha[:12]} 이 검증된 task "
+            f"HEAD 에 포함되지 않습니다 — 검증에 포함되지 않은 커밋이 있습니다")
+
+
 def _teardown_stage(project_id, task_group, task_id, task_wt, stage_n, row):
-    """clean stage worktree 를 제거 + registry release + branch -d.
-    branch -d 가 성공한 뒤에만 branch 슬롯을 free 한다 — 물리 브랜치가
-    살아있는 채로 슬롯이 풀려 동시 run 이 같은 이름을 재예약하는 윈도우를
-    막기 위함. 반환 ('torn_down'|'skipped'|'warn', detail)."""
+    """Remove the clean stage worktree directory and mark the registry row
+    released. The stage branch is deliberately kept: the per-stage stack
+    branches must survive whole-task verification so that
+    `okstra handoff local-checkout --stage <N>` still has a target. The
+    branch's registry slot is not touched here — `consumers`'
+    `_release_stage_reservation` already freed it at stage-done time.
+
+    Warns when the surviving branch tip carries commits the verified merge
+    never included. Teardown itself is already complete at that point, so the
+    warning reports the divergence rather than undoing the cleanup. Returns
+    ('torn_down'|'skipped'|'warn', detail)."""
     from . import worktree_registry
 
     wt = (row or {}).get("worktree_path") or ""
@@ -152,12 +181,9 @@ def _teardown_stage(project_id, task_group, task_id, task_wt, stage_n, row):
             return outcome
     worktree_registry.release_status(project_id, task_group, task_id, stage_number=stage_n)
     if branch:
-        bd = _git(task_wt, "branch", "-d", branch)
-        if bd.returncode != 0:
-            return ("warn", f"stage {stage_n} branch -d {branch} 실패(미머지?): "
-                            f"{bd.stderr.strip()}")
-        worktree_registry.free_branch_slot(project_id, task_group, task_id,
-                                           stage_number=stage_n)
+        warning = _unmerged_branch_tip_warning(task_wt, stage_n, branch)
+        if warning:
+            return ("warn", warning)
     return ("torn_down", "")
 
 

package/runtime/python/okstra_ctl/worker_prompt_contract.py

@@ -41,6 +41,7 @@ _NON_BODY_PREFIXES = (
     "**Worker Preamble Path:**",
     *ERRORS_PATH_HEADERS,
     "**Read scope:**",
+    "**File write mode:**",
     "**Worktree:**",
     "**Verification scope:**",
     "**Verification base ref:**",
@@ -63,6 +64,9 @@ _WORKER_SPECIFIC_PREFIXES = (
     "Assigned worker prompt history path:",
     "**Errors sidecar path:**",
     "**Worker Result Path:**",
+    # Only antigravity carries this (worker_prompt_headers.PLAIN_FILE_WRITE_HEADER)
+    # because only agy has an artifact store; unstripped it reads as divergence.
+    "**File write mode:**",
     "**Model:**",
     "**Pane role:**",
 )

package/runtime/python/okstra_ctl/worker_prompt_headers.py

@@ -37,6 +37,24 @@ READ_SCOPE_HEADER = (
     "or Assumptions* instead of reading it."
 )
 
+# `agy`'s write tool validates the target against the Gemini artifact store
+# whenever the model attaches ArtifactMetadata, and rejects every path outside
+# `~/.gemini/antigravity-cli/brain/<uuid>/`. All okstra worker outputs live under
+# `<PROJECT_ROOT>/.okstra/`, so an attached ArtifactMetadata fails the write —
+# usually on the audit sidecar, after which the CLI exits 0 having persisted no
+# result file. Only antigravity carries this: codex and claude have no artifact
+# store, and a shared header would break the cross-worker prompt-body equality
+# that `worker_prompt_contract` enforces.
+PLAIN_FILE_WRITE_HEADER = (
+    "**File write mode:** Write every okstra output (result file, audit "
+    "sidecar, errors sidecar) as a plain project file at the absolute path this "
+    "prompt gives. Do NOT attach ArtifactMetadata and do NOT route these writes "
+    "through the Gemini artifact store — artifact paths are restricted to the "
+    "brain folder, so an artifact write under `<PROJECT_ROOT>/.okstra/` is "
+    "rejected and the run ends with no result file."
+)
+ANTIGRAVITY_WORKER_ID = "antigravity"
+
 
 def worker_prompt_headers(
     *,
@@ -81,6 +99,8 @@ def worker_prompt_headers(
         f"**Errors sidecar path:** {errors_sidecar_path}",
         READ_SCOPE_HEADER,
     ])
+    if worker_id == ANTIGRAVITY_WORKER_ID:
+        headers.append(PLAIN_FILE_WRITE_HEADER)
     if _string_value(manifest.get("taskType")) == "improvement-discovery":
         headers.append(
             f"{GRILLING_LOG_HEADER} "

package/runtime/python/okstra_ctl/worktree_registry.py

@@ -275,10 +275,11 @@ def release_status(
 ) -> Optional[WorktreeEntry]:
     """Mark the entry as `released` WITHOUT freeing its branch index slot.
 
-    Use when the physical branch still exists and its name must stay
-    reserved — e.g. teardown defers the slot-free until `git branch -d`
-    actually succeeds, so the registry never advertises a free branch
-    name that is still alive on disk. Returns the prior entry, or None.
+    Use when the caller must not touch the branch index — either the slot is
+    still needed, or another caller owns its lifetime. Stage teardown is the
+    latter case: `consumers._release_stage_reservation` already ran `release()`
+    at stage-done time, so teardown only flips the status. Returns the prior
+    entry, or None.
     """
     key = task_key(project_id, task_group, task_id, stage_number, group_id)
     with _registry_lock():
@@ -323,11 +324,12 @@ def release(
     group_id: Optional[str] = None,
 ) -> Optional[WorktreeEntry]:
     """Mark the entry as `released` and free its branch slot (worktree dir
-    intact — preservation is the project's policy). Used by callers that
-    release at a point where the branch is gone or intentionally orphaned
-    (done-time reservation release, group cleanup). Teardown of a physical
-    branch must instead pair `release_status` + `free_branch_slot` so the
-    slot is freed only after `git branch -d` succeeds.
+    intact — preservation is the project's policy). Used at the points that
+    end a reservation's life: done-time stage release
+    (`consumers._release_stage_reservation`) and group cleanup. Both free the
+    slot even when the physical branch survives — stage stack branches are
+    deliberately kept, and their names are task-scoped, so a freed slot cannot
+    collide with a live branch from another task.
     Returns the prior entry, or None when not found.
     """
     entry = release_status(project_id, task_group, task_id, stage_number, group_id)

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/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/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 동봉)
 `;