okstra 0.132.0 → 0.134.0

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

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

package/package.json

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

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.132.0",
-  "builtAt": "2026-07-22T06:44:24.538Z",
+  "package": "0.134.0",
+  "builtAt": "2026-07-23T05:31:24.504Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

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

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

package/runtime/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/clarification_items.py

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

package/runtime/python/okstra_ctl/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

@@ -325,46 +325,93 @@ _ABBREV = {
 }
 
 
-def _ventilate_segment(seg: str) -> str:
-    def replace_boundary(match: re.Match) -> str:
-        mark = match.start()
-        prev = seg[mark - 1] if mark > 0 else ""
+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 == ".":
-            return match.group(0)
-        tail = re.search(r"[A-Za-z.]+$", seg[: mark + 1])
+            continue
+        tail = re.search(r"[A-Za-z.]+$", text[: mark + 1])
         if tail and tail.group(0).rstrip(".").lower() in _ABBREV:
-            return match.group(0)
-        return seg[mark] + "\n"
+            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)
+
 
-    return _SENT_BOUNDARY_RE.sub(replace_boundary, seg)
+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 _split_prose_line(line: str) -> str:
-    parts = line.split("`")
-    for even in range(0, len(parts), 2):  # segments outside backtick code spans
-        parts[even] = _ventilate_segment(parts[even])
-    return "`".join(parts)
+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 paragraphs into one sentence per line. Idempotent: a line
-    already holding a single sentence has no internal boundary to split."""
+    """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]:  # frontmatter / fenced code
-            continue
-        if not line or line != line.lstrip():  # blank or indented continuation
+        if mask[i] or not line:  # frontmatter / fenced code / blank
             continue
-        if (
-            _HEADING_RE.match(line)
-            or line.startswith("|")
-            or line.startswith(">")
-            or _LIST_LINE_RE.match(line)
-        ):
+        if _HEADING_RE.match(line) or line.startswith(">"):
             continue
-        lines[i] = _split_prose_line(line)
+        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)