okstra 0.163.0 → 0.163.2

package/docs/project-structure-overview.md

@@ -294,6 +294,7 @@ Important modules:
 | `manager_sync.py` | One-way child project `.okstra` snapshot reader; corrupt child state becomes row-level `error` so other children continue |
 | `manager_launch.py` | Child launch packet and manager child context renderer; records `prepared` launch metadata/events without changing project-local task state |
 | `dispatch_core.py` | Backend-neutral worker dispatch core — worker execution/collection logic shared by any lead runtime (Claude/Codex/Antigravity/external); gates selected initial prompts through the shared cross-task contract before launch |
+| `cmux.py` | cmux-pane worker backend — mirrors the tmux backend's contract (a worker that gets a pane frees the lead process; anything that stops a pane opening degrades quietly to the blocking wrapper, recording a surface UUID rather than a tmux pane id). Detects a usable cmux session before selecting the backend (CLI resolves + ping answers PONG + the lead's workspace is resolvable), derives placement from the workspace geometry each dispatch, relays lead/worker events to the cmux sidebar, and records the run's terminal backend in the manifest so both phases of a run land on one backend. A sandbox that hides cmux (`PermissionError` on the socket) stops dispatch with the remedy instead of degrading into the same broken fallback; a quit app (`FileNotFoundError`) still degrades |
 | `codex_dispatch.py` | Codex lead CLI-worker dispatcher — the `okstra codex-dispatch` backend. Reads the run manifest to run the Codex-side supported worker subset, applies the same cross-task initial-prompt gate, and performs token-usage substitution, view render, follow-up, and validation |
 | `analysis_packet.py` | assembles the compact analysis-worker input packet for a task run from worker-owned profile sections; report/lead procedure stays outside the packet |
 | `analysis_inputs.py` | shared input boundary for `project-analysis`, `feature-analysis`, and `change-impact-analysis` — validates evidence-report identity and review status, enforces the type-to-type relation allowlist, computes `exact`/`stale` freshness, and resolves free-text or `PF-NNN` feature targets for both wizard and prepare paths |
@@ -431,7 +432,7 @@ Boilerplate shared by several skills (bash invocation rule, outdated-CLI preflig
 | `agents/workers/kimi-worker.params.json` | Kimi read-only analyser/critic wrapper params |
 | `agents/workers/report-writer-worker.md` | data.json SSOT author and audit sidecar writer |
 
-The neutral lead lifecycle contract lives at `prompts/lead/okstra-lead-contract.md`. Host mappings live under `prompts/lead/adapters/`: `claude-code.md`, `codex.md`, `antigravity.md`, and `external.md`. All are runtime resources installed under `~/.okstra/prompts/lead/`, not agent skills.
+The neutral lead lifecycle contract lives at `prompts/lead/okstra-lead-contract.md`. Host mappings live under `prompts/lead/adapters/`: `claude-code.md`, `codex.md`, `antigravity.md`, `external.md`, and `cmux.md` (the environment-selected cmux worker backend, read by every task type regardless of lead runtime). All are runtime resources installed under `~/.okstra/prompts/lead/`, not agent skills.
 
 ### 4.12 `tests/` and `tests-e2e/`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.163.0",
+  "version": "0.163.2",
   "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.163.0",
-  "builtAt": "2026-08-09T07:22:48.148Z",
+  "package": "0.163.2",
+  "builtAt": "2026-08-09T12:57:56.931Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/prompts/profiles/implementation-planning.md

@@ -200,4 +200,7 @@
   9. **Cross-project dependency check** — confirm you have not missed a dependency on another repo / another top-level deployable module / a published package. If `dependencyMigrationRisk` has a `kind: cross-project` row, confirm a matching `direction: upstream-precondition` `XP-NNN` row exists in `crossProjectDependencies`, and re-read as a reviewer whether its `requiredWork` is the concrete work the other side must actually build rather than an abstract phrase ("other side's work done") — validator S only checks existence, so concreteness is the self-review's responsibility. Confirm cross-repo work is split into a separate run + XP row instead of being crammed into one task's stages, and that the cross-project substance is not duplicated in `§3 Recommended Next Steps` but lives only in `§5.4 Cross-Project Dependencies`.
   10. **Decision-draft materialization check** — when `decisionDrafts` is non-empty, confirm as a reviewer which stage's stepwise order contains the matching materialization step (creating `.okstra/decisions/<NNNN>-<slug>.md`) and that the number of drafts corresponds 1:1 with the materialization steps. The validator only checks the *existence* of the step, so the `<NNNN>-<slug>` correctness and count correspondence are the self-review's responsibility.
   11. **Variation-point & seam check** — read `variationPointAnalysis` as a skeptic. Is `hasMultipleImplementations` honest against the brief and the sibling code you inspected during pre-planning, or was `false` chosen because it is the cheaper field to fill? For every point with `extract: true`, confirm the `extractionDecision` names a real interface (a `port` for a hexagonal project, not a shared helper) and a `coveredBy` stage that exists in the Stage Map — an interface no stage builds is a decision nobody executes. Then read the recommended option's `testSeams`: each `injectedAs` must name a construction or wiring point a test can actually substitute at, not a symbol the test would have to re-implement — a seam nothing can be injected into leaves the executor writing self-mocks. An empty `testSeams` array is only acceptable when you can defend it in one sentence; the validator accepts it either way, so this is the check that catches an unfilled field posing as a decision.
-  12. **Approval blast-radius check (BLOCKING).** Every `Blocks=approval` clarification row must be reachable *from* the plan, not only *into* it: at least one `planItems[]` entry carrying that id as `clarificationId`, or one `requirementCoverage` row blocked on it in `status` or `approvalDisposition`. Item 7 covers only rows this run promoted from a majority-disagree plan item; a blocker raised any other way can still withhold approval while recording nothing it affects. The cost lands on the re-run: `okstra incremental-scope` resolves impacted stages from exactly these two links and treats an id that traces to no stage as grounds to re-verify every stage, so one unlinked blocker turns an incremental re-run into a full one. **Enforced:** `validators/validate-run.py` `_validate_approval_clarification_backtrace`.
+  12. **Approval blast-radius check (BLOCKING).** Every `Blocks=approval` clarification row must be reachable *from* the plan, not only *into* it: at least one `planItems[]` entry carrying that id as `clarificationId`, or one `requirementCoverage` row blocked on it in `status` or `approvalDisposition`. Item 7 covers only rows this run promoted from a majority-disagree plan item; a blocker raised any other way can still withhold approval while recording nothing it affects. The cost lands on the re-run: `okstra incremental-scope` resolves impacted stages from exactly these two links and treats an id that traces to no stage as grounds to re-verify every stage, so one unlinked blocker turns an incremental re-run into a full one.
+      - **The link must resolve to a stage, not merely exist.** `incremental-scope` reads the stage number out of a `P-Step-<stage>.<step>` / `P-Prep-S<stage>-<kind>` plan-item id, or out of a `Stage N` citation in the blocked coverage row's `coveredBy`. Every other plan-item prefix (`P-Req-*`, `P-Val-*`, `P-Opt-*`, `P-Dep-*`, `P-Rb-*`) is numbered by position in its own array and carries no stage, so a blocker linked only that way MUST also have its coverage row cite the stage in `coveredBy`. Writing the blocked row's `coveredBy` as prose with no `Stage N` in it — `No stage.`, `Partly covered — …` — satisfies nothing: the row passes the link check and the re-run still re-verifies everything.
+      - What to write when no stage covers the requirement yet: name the stage the answer will change, not the stage that satisfies the requirement today. A `Blocks=approval` row is admissible only when, absent an answer, `implementation` would produce wrong or unsafe code (see the admissibility rule above) — so some stage's code is at stake by construction. If you genuinely cannot name one, the row fails the admissibility test and belongs in `## 5. Missing Information and Risks` with `Blocks=none`, not in the approval gate.
+      **Enforced:** `validators/validate-run.py` `_validate_approval_clarification_backtrace` — one failure for a missing link, a separate one for a link that resolves to no stage.

package/runtime/prompts/wizard/prompts.ko.json

@@ -589,9 +589,12 @@
     "worktree_impl_new": "  worktree      : stage {stage} 새 worktree `{path}` (브랜치 `{branch}`, base 는 run 준비 시 해소)",
     "worktree_impl_reuse": "  worktree      : 기존 stage {stage} worktree `{path}` (브랜치 `{branch}`)",
     "worktree_impl_auto": "  worktree      : stage 자동 선택 — `{path}` 아래 stage-<N>/ worktree 생성/재사용",
+    "clarification_sidecars_empty": "  user-responses: 없음 — final-report 만 첨부됩니다",
+    "clarification_sidecars_attached": "  user-responses: 사이드카 {files}개 · 답변 {count}개 함께 첨부 — {ids}",
+    "clarification_sidecars_none_parsed": "답변으로 셀 항목 없음 (reframe 등)",
     "reverify_scope_incremental": "  reverify-scope: incremental 가능 — 답변된 항목이 모두 직전 리포트의 stage 에 연결됨 (최종 확정은 run 시점 base-ref 비교)",
-    "reverify_scope_unlinked": "  reverify-scope: full 예상 — {ids} 이(가) 직전 리포트의 어느 stage 에도 연결되지 않아 범위를 좁힐 수 없음",
-    "reverify_scope_full": "  reverify-scope: full 예상 — {reason}",
+    "reverify_scope_unlinked": "  reverify-scope: full 예상 — {ids} 이(가) 직전 리포트의 어느 stage 에도 연결되지 않아 범위를 좁히지 못함\n                  (좁히지 못하는 것은 재검증 범위이지 답변이 아닙니다 — 답변은 모두 carry-in 되어 반영되고, 대신 stage 전체를 다시 검증합니다)",
+    "reverify_scope_full": "  reverify-scope: full 예상 — {reason}\n                  (좁히지 못하는 것은 재검증 범위이지 답변이 아닙니다 — 답변은 모두 carry-in 되어 반영되고, 대신 stage 전체를 다시 검증합니다)",
     "reverify_scope_user_full": "  reverify-scope: full (사용자 지정 — 전체 재검증)",
     "reverify_scope_user_stages": "  reverify-scope: stage {stages} 재검증 지정 (사용자 지정 — 하위 stage 포함, 나머지는 직전 판정 이월)",
     "stage_whole_task": "전체 task",

package/runtime/python/okstra_ctl/cmux.py

@@ -14,7 +14,7 @@ import socket
 import subprocess
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Sequence
+from typing import Any, Collection, Sequence
 
 PING_OK = "PONG"
 
@@ -165,15 +165,31 @@ class Placement:
 
 
 def plan_worker_placement(
-    panes: Sequence[PaneGeometry], *, lead_pane_id: str, min_columns: int
+    panes: Sequence[PaneGeometry],
+    *,
+    lead_pane_id: str,
+    owned_surface_ids: Collection[str],
+    min_columns: int,
 ) -> Placement:
     """Pick the next worker slot from the workspace's current geometry.
 
     Stateless by design: okstra records surface UUIDs, never a layout, so a
     resumed or crashed run cannot carry a layout model that no longer matches
     the screen. Every dispatch re-reads the panes and derives the next slot.
+
+    Those same UUIDs say which panes okstra may place into. A workspace also
+    holds panes okstra never opened — another agent session, a shell the user
+    keeps around — and "not the lead" does not make a pane a worker slot. Taken
+    as one, a stranger's pane is split or, when it is too narrow to split,
+    stacked into: the workers land as background tabs in someone else's window,
+    so nothing appears on screen and that window grows tabs it did not ask for.
     """
-    workers = [pane for pane in panes if pane.pane_id != lead_pane_id]
+    workers = [
+        pane
+        for pane in panes
+        if pane.pane_id != lead_pane_id
+        and _holds_an_okstra_surface(pane, owned_surface_ids)
+    ]
     if not workers:
         return Placement(pane_id=lead_pane_id, direction="right", stack_as_tab=False)
 
@@ -196,6 +212,17 @@ def lead_shrink_points(lead: PaneGeometry, *, target_columns: int) -> int:
     return surplus * lead.cell_width_points
 
 
+def _holds_an_okstra_surface(
+    pane: PaneGeometry, owned_surface_ids: Collection[str]
+) -> bool:
+    """Whether okstra opened anything in this pane.
+
+    Any one recorded surface is enough: workers that stacked as tabs share a
+    pane, and only the tab that opened it carries the UUID okstra split on.
+    """
+    return any(surface_id in owned_surface_ids for surface_id in pane.surface_ids)
+
+
 def _widen_the_grid(
     workers: Sequence[PaneGeometry], *, min_columns: int
 ) -> Placement:
@@ -270,18 +297,30 @@ def list_panes(workspace: str) -> list[PaneGeometry]:
 
 
 def spawn_worker_surface(
-    *, workspace: str, cwd: Path, command: Sequence[str], title: str
+    *,
+    workspace: str,
+    cwd: Path,
+    command: Sequence[str],
+    title: str,
+    owned_surface_ids: Collection[str],
 ) -> str:
     """Start one worker beside the lead and return its surface UUID.
 
     The UUID is what okstra records and later closes by. Positional refs cannot
     serve that purpose: cmux renumbers them as surfaces open and close, so a
     close by ref can land on a pane okstra never created.
+
+    `owned_surface_ids` are the UUIDs earlier dispatches returned. They are what
+    keeps this placement inside okstra's own panes; the workspace belongs to the
+    user and may hold anything.
     """
     panes = list_panes(workspace)
     lead = _lead_pane(panes)
     placement = plan_worker_placement(
-        panes, lead_pane_id=lead.pane_id, min_columns=WORKER_MIN_COLUMNS
+        panes,
+        lead_pane_id=lead.pane_id,
+        owned_surface_ids=owned_surface_ids,
+        min_columns=WORKER_MIN_COLUMNS,
     )
     target = _pane_by_id(panes, placement.pane_id)
     surface_uuid = _open_worker_surface(workspace, placement, target)

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -452,6 +452,7 @@ def _start_cmux_or_degrade(plan: DispatchPlan, job: WorkerJob) -> WorkerHandle:
             cwd=plan.project_root,
             command=job.command,
             title=f"{job.worker_id}-worker",
+            owned_surface_ids=_opened_cmux_surfaces(plan.team_state_path),
         )
     except (RuntimeError, OSError, subprocess.SubprocessError):
         return _run_cli_wrapper(plan, job, BACKEND_CMUX_PANE)
@@ -460,6 +461,28 @@ def _start_cmux_or_degrade(plan: DispatchPlan, job: WorkerJob) -> WorkerHandle:
     )
 
 
+def _opened_cmux_surfaces(team_state_path: Path) -> tuple[str, ...]:
+    """The surfaces this run has already opened in the user's cmux workspace.
+
+    Placement needs them to tell okstra's own panes from the rest of the
+    workspace, which belongs to the user and may hold another agent session or
+    a shell okstra must not split or stack into. A degraded dispatch opened no
+    surface and records an empty id, which would name no pane at all.
+    """
+    payload = _load_json_object(team_state_path, "team-state")
+    dispatches = payload.get("workerDispatches")
+    if not isinstance(dispatches, list):
+        return ()
+    opened = []
+    for record in dispatches:
+        if not isinstance(record, dict):
+            continue
+        surface_id = str(record.get("paneId", ""))
+        if surface_id:
+            opened.append(surface_id)
+    return tuple(opened)
+
+
 def _start_tmux_or_degrade(plan: DispatchPlan, job: WorkerJob) -> WorkerHandle:
     lead_pane = tmux.resolve_caller_pane()
     if not lead_pane:

package/runtime/python/okstra_ctl/wizard.py

@@ -4809,6 +4809,33 @@ def render_args(state: WizardState) -> dict[str, str]:
     }
 
 
+def _clarification_sidecar_line(state: WizardState) -> Optional[str]:
+    """확인 블록에 찍는 `user-responses/` 첨부 현황.
+
+    picker 단계의 옵션 라벨에도 같은 사실이 붙지만 그 화면을 지나면 사라지고,
+    확인 블록에는 final-report 경로만 남았다. 그 줄 바로 밑에 "범위를 좁히지
+    못함" 이 오니 두 줄이 겹쳐 "답변이 안 붙었다" 로 읽혔다 — 실제로는 첨부돼
+    반영되고 있었다. 실행 직전 화면에서 답변 id 를 직접 보여 그 오해를 없앤다.
+    """
+    if not state.clarification_response_path or not state.project_root:
+        return None
+    report = _resolve_path(
+        state.clarification_response_path, Path(state.project_root)
+    )
+    files = user_response_sidecars(report)
+    if not files:
+        return _msg(state.workspace_root, "confirmation",
+                    "clarification_sidecars_empty")
+    answers = sorted(sidecar_answers(report))
+    return _msg(
+        state.workspace_root, "confirmation", "clarification_sidecars_attached",
+        files=str(len(files)), count=str(len(answers)),
+        ids=", ".join(answers) or _msg(
+            state.workspace_root, "confirmation",
+            "clarification_sidecars_none_parsed"),
+    )
+
+
 def _reverify_scope_line(state: WizardState) -> Optional[str]:
     """이번 clarification 재실행이 좁혀질지 — 확인 단계에서 보여주는 줄.
 
@@ -4923,6 +4950,9 @@ def confirmation_block(state: WizardState) -> str:
         lines.append(f"  stage         : {stage}")
     if state.clarification_response_path:
         lines.append(f"  clarification : {state.clarification_response_path}")
+        sidecar_line = _clarification_sidecar_line(state)
+        if sidecar_line is not None:
+            lines.append(sidecar_line)
         reverify_line = _reverify_scope_line(state)
         if reverify_line is not None:
             lines.append(reverify_line)

package/runtime/validators/validate-run.py

@@ -66,7 +66,10 @@ from okstra_ctl.report_translation import (  # noqa: E402
     hangul_share,
 )
 from okstra_ctl.stage_citations import cited_stage_numbers  # noqa: E402
-from okstra_ctl.incremental_scope import coverage_row_blocked_on  # noqa: E402
+from okstra_ctl.incremental_scope import (  # noqa: E402
+    coverage_row_blocked_on,
+    stages_for_clarification,
+)
 from okstra_ctl.workflow import DEFAULT_NEXT_PHASE, PHASE_SEQUENCE  # noqa: E402
 from okstra_ctl.md_table import (  # noqa: E402
     is_separator_row as _is_markdown_separator,
@@ -4155,6 +4158,13 @@ def _validate_approval_clarification_backtrace(
     `incremental-scope` resolves impacted stages from these links and treats an
     id that traces to no stage as grounds to re-verify everything, so one
     unlinked blocker turns a narrow re-run into a full one.
+
+    The link must also *resolve to a stage*, which is the thing the re-run
+    actually reads. Checking only that a link exists let a row satisfy this
+    gate and still force full: `P-Req-*` and `P-Val-*` ids are numbered by
+    position in their own array, so they carry no stage, and a blocked
+    coverage row whose `coveredBy` is prose cites none either. Both shapes
+    passed while the re-run they were meant to narrow re-verified everything.
     """
     if (data.get("header") or {}).get("taskType") != "implementation-planning":
         return
@@ -4170,15 +4180,28 @@ def _validate_approval_clarification_backtrace(
         if not isinstance(row, dict) or row.get("blocks") != "approval":
             continue
         row_id = str(row.get("id") or "<unknown>")
-        if _has_clarification_backtrace(row_id, plan_items, coverage):
+        if not _has_clarification_backtrace(row_id, plan_items, coverage):
+            failures.append(
+                f"final-report data.json: clarification `{row_id}` blocks approval "
+                "but has no back-trace into the plan — no plan item carries it as "
+                "`clarificationId`, and no requirement-coverage row is `blocked "
+                f"{row_id}` in its `status` or `approvalDisposition`. An item that "
+                "withholds approval without recording what it affects forces the "
+                "next re-run to re-verify everything."
+            )
+            continue
+        if stages_for_clarification(data, row_id):
             continue
         failures.append(
             f"final-report data.json: clarification `{row_id}` blocks approval "
-            "but has no back-trace into the plan — no plan item carries it as "
-            "`clarificationId`, and no requirement-coverage row is `blocked "
-            f"{row_id}` in its `status` or `approvalDisposition`. An item that "
-            "withholds approval without recording what it affects forces the "
-            "next re-run to re-verify everything."
+            "and is linked, but the link resolves to no stage. `incremental-"
+            "scope` reads the stage from a `P-Step-<stage>.<step>` / `P-Prep-"
+            "S<stage>-<kind>` plan-item id, or from a `Stage N` citation in the "
+            f"blocked coverage row's `coveredBy`. A `P-Req-*` / `P-Val-*` id "
+            "carries no stage number, so a row linked only that way must cite "
+            "the stage in `coveredBy`. A blocker whose blast radius resolves to "
+            "no stage costs exactly what an unlinked one does — the next re-run "
+            "re-verifies every stage."
         )