okstra 0.162.2 → 0.163.1

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.162.2",
+  "version": "0.163.1",
   "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.162.2",
-  "builtAt": "2026-08-08T18:44:32.842Z",
+  "package": "0.163.1",
+  "builtAt": "2026-08-09T08:20:00.790Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/bin/lib/okstra/cli.sh

@@ -94,6 +94,10 @@ while [[ $# -gt 0 ]]; do
       REPORT_WRITER_MODEL_OVERRIDE="$(require_option_value --report-writer-model "${2-}")"
       shift 2
       ;;
+    --launch-only)
+      LAUNCH_ONLY="true"
+      shift
+      ;;
     --lead-runtime)
       LEAD_RUNTIME="$(require_option_value --lead-runtime "${2-}")"
       shift 2

package/runtime/bin/lib/okstra/globals.sh

@@ -164,3 +164,6 @@ REPORT_WRITER_MODEL_EXECUTION_VALUE=""
 DEFAULT_WORKERS="claude,codex,report-writer"
 DISPLAY_COMMAND_NAME="${OKSTRA_COMMAND_NAME:-$(basename "$0")}"
 DISPLAY_TOOL_NAME="${OKSTRA_TOOL_NAME:-okstra}"
+
+# `okstra run <lead>` 전용: 번들을 준비하지 않고 리드 CLI 만 띄운다.
+LAUNCH_ONLY="false"

package/runtime/bin/okstra.sh

@@ -71,6 +71,58 @@ if [[ "$RESUME_CLARIFICATION_MODE" == "true" ]]; then
   exit 0
 fi
 autofill_from_project_json
+
+# `okstra run <lead>` — open the host, nothing else. The okstra-run skill inside
+# it collects task inputs, which is how the Claude Code path has always worked.
+# Preparing a bundle here would demand a task id before the user has a session
+# to choose one in.
+if [[ "$LAUNCH_ONLY" == "true" ]]; then
+  if [[ -z "$PROJECT_ROOT" ]]; then
+    PROJECT_ROOT="$(resolve_project_root_strict "$PROJECT_ROOT_OVERRIDE")" || exit 1
+  fi
+  read -r LEAD_EXECUTABLE SANDBOX_NOTE < <(
+    okstra_py - "$LEAD_RUNTIME" <<'PY'
+import sys
+from okstra_ctl.lead_runtime import lead_runtime_info
+from okstra_ctl.models import bare_lead_launch_argv, lead_launch_spec
+provider = lead_runtime_info(sys.argv[1]).agent
+print(bare_lead_launch_argv(provider)[0], lead_launch_spec(provider).sandbox_waiver_note)
+PY
+  )
+  if ! command -v "$LEAD_EXECUTABLE" >/dev/null 2>&1; then
+    printf '%s command not found\n' "$LEAD_EXECUTABLE" >&2
+    exit 1
+  fi
+  if [[ -n "$SANDBOX_NOTE" ]]; then
+    okstra_py - "$LEAD_RUNTIME" <<'PY' >&2
+import sys
+from okstra_ctl.lead_runtime import lead_runtime_info
+from okstra_ctl.models import lead_launch_spec
+print("\n" + lead_launch_spec(lead_runtime_info(sys.argv[1]).agent).sandbox_waiver_note)
+PY
+    if [[ "$ASSUME_YES" != "true" ]]; then
+      printf 'Start %s without its sandbox? [y/N] ' "$LEAD_EXECUTABLE" >&2
+      read -r _sandbox_answer < /dev/tty || _sandbox_answer=""
+      if [[ "$_sandbox_answer" != "y" && "$_sandbox_answer" != "Y" ]]; then
+        printf 'okstra: cancelled\n' >&2
+        exit 1
+      fi
+    fi
+  fi
+  LAUNCH_ARGV=()
+  while IFS= read -r -d '' _arg; do LAUNCH_ARGV+=("$_arg"); done < <(
+    okstra_py - "$LEAD_RUNTIME" <<'PY'
+import sys
+from okstra_ctl.lead_runtime import lead_runtime_info
+from okstra_ctl.models import bare_lead_launch_argv
+for a in bare_lead_launch_argv(lead_runtime_info(sys.argv[1]).agent):
+    sys.stdout.write(a + "\0")
+PY
+  )
+  cd "$PROJECT_ROOT"
+  exec "${LAUNCH_ARGV[@]}"
+fi
+
 autofill_from_manifest
 collect_required_arguments
 

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/models.py

@@ -247,6 +247,18 @@ def lead_launch_spec(provider: str) -> LeadLaunchSpec:
     return spec.lead_launch
 
 
+def bare_lead_launch_argv(provider: str) -> list[str]:
+    """Start this provider's CLI with nothing to do yet.
+
+    `okstra run <lead>` opens the host; the okstra-run skill inside it collects
+    task inputs, exactly as the Claude Code path already works. So there is no
+    prompt and no model to pin here — only the flags that make the session
+    usable to okstra at all.
+    """
+    launch = lead_launch_spec(provider)
+    return [launch.executable, *launch.sandbox_waiver]
+
+
 def lead_launch_argv(
     provider: str,
     *,

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."
         )
 
 

package/src/commands/execute/run.mjs

@@ -32,6 +32,8 @@ const RUNTIME_ALIASES = new Map([
   ["claude-code", "claude-code"],
   ["codex", "codex"],
   ["antigravity", "antigravity"],
+  ["avg", "antigravity"],
+  ["agy", "antigravity"],
   ["external", "external"],
 ]);
 
@@ -110,10 +112,18 @@ export function buildRunPlan({ args, paths, resolution, runManifestPath = "" })
       // Handed to okstra.sh, which owns input collection and the launch. Only
       // the runtime is decided here; everything else is passed through so the
       // launcher can prompt for whatever is still missing.
+      // --launch-only: open the host and stop. Task inputs are collected by the
+      // okstra-run skill inside the session, which is how the Claude Code path
+      // has always worked — demanding a task id out here asks for it before the
+      // user has a session to pick one in.
       commands: [
         {
           name: "launcher",
-          args: ["--lead-runtime", resolution.resolvedRuntime, ...withoutRuntimeSelection(args)],
+          args: [
+            "--launch-only",
+            "--lead-runtime", resolution.resolvedRuntime,
+            ...withoutRuntimeSelection(args),
+          ],
           capture: false,
         },
       ],