okstra 0.164.0 → 0.165.0

package/runtime/bin/okstra-provider-exec.py

@@ -1,121 +1,184 @@
 #!/usr/bin/env python3
-"""Run an external LLM CLI with the shared okstra wrapper contract."""
+"""Run an external LLM CLI with the shared okstra wrapper contract.
+
+Argument parsing and provider lookup only — the run itself belongs to
+``okstra_ctl.worker_runner``, which every provider shares. What stays here is
+the request the provider strategies then take on trust: resolved paths, the
+write scope in the order the CLIs are told it, and the role's idle budget.
+"""
 from __future__ import annotations
 
-import json
 import os
-import selectors
 import shutil
-import signal
-import subprocess
 import sys
-import time
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Callable
+from typing import Any, Mapping
+
+_HERE = Path(__file__).resolve().parent
+# ``okstra_ctl`` sits beside this file in the repo (``scripts/``) but under
+# ``~/.okstra/lib/python/`` once installed, and the four-line shell entrypoints
+# that exec this script set no PYTHONPATH. Offer both, repo first.
+_HOME_LIB = (
+    Path(os.environ.get("OKSTRA_HOME", str(Path.home() / ".okstra"))) / "lib" / "python"
+)
+sys.path.insert(0, str(_HERE))
+if _HOME_LIB.is_dir() and str(_HOME_LIB) not in sys.path:
+    sys.path.append(str(_HOME_LIB))
+
+from okstra_ctl.domain.provider import ProviderSpec, UnknownProviderError  # noqa: E402
+from okstra_ctl.domain.worker_exec import (  # noqa: E402
+    ExecutionStrategy,
+    WorkerExecRequest,
+)
+from okstra_ctl.registry.provider_registry import (  # noqa: E402
+    default_provider_registry,
+)
+from okstra_ctl.worker_request import build_request, idle_timeout  # noqa: E402
+from okstra_ctl.worker_runner import LIVE, QUIET, run_worker  # noqa: E402
+
+_USAGE = (
+    "usage: okstra-provider-exec.py <provider> <project-root> "
+    "<model-execution-value> <prompt-path> [worktree-path] [role] "
+    "[idle-timeout-seconds] [--presentation live|quiet]"
+)
+
+_PRESENTATION_FLAG = "--presentation"
+_PRESENTATIONS = (LIVE, QUIET)
+
+
+class PreflightError(Exception):
+    def __init__(self, exit_code: int, message: str) -> None:
+        super().__init__(message)
+        self.exit_code = exit_code
 
 
 @dataclass(frozen=True)
-class ProviderCommand:
-    binary: str
-    wrapper: str
-    build_args: Callable[[str, str, str], list[str]]
+class Invocation:
+    strategy: ExecutionStrategy
+    request: WorkerExecRequest
+    presentation: str
+    log_path: Path
+    status_path: Path
+    status_extra: Mapping[str, Any]
+
+
+def parse_invocation(argv: list[str]) -> Invocation:
+    """Resolve the wrapper's positional contract into one runnable dispatch."""
+    positional, presentation = _take_presentation(argv)
+    if not 4 <= len(positional) <= 7:
+        raise PreflightError(64, _USAGE)
+    provider_id, project_root_raw, model, prompt_raw = positional[:4]
+    worktree_raw = positional[4] if len(positional) >= 5 else ""
+    role = positional[5] if len(positional) >= 6 and positional[5] else "worker"
+    timeout_raw = positional[6] if len(positional) >= 7 and positional[6] else ""
+
+    spec = _provider_spec(provider_id)
+    project_root = _existing_dir(project_root_raw, 65, "project-root")
+    if not model:
+        raise PreflightError(66, "model-execution-value is empty")
+    prompt_path = _existing_file(prompt_raw, 67, "prompt-path")
+    idle_timeout_seconds = _idle_timeout(timeout_raw, role)
+    worktree = (
+        _existing_dir(worktree_raw, 68, "worktree-path") if worktree_raw else None
+    )
 
+    request = build_request(
+        prompt_text=prompt_path.read_text(encoding="utf-8"),
+        model=model,
+        project_root=project_root,
+        worktree_path=worktree,
+        role=role,
+        idle_timeout_seconds=idle_timeout_seconds,
+    )
+    strategy = spec.exec_strategy
+    _check_command(strategy, request)
+    return Invocation(
+        strategy=strategy,
+        request=request,
+        presentation=presentation,
+        log_path=_log_path(prompt_path),
+        status_path=Path(f"{prompt_path}.status.json"),
+        status_extra={"wrapper": spec.wrapper, "role": role},
+    )
 
-def _grok_args(prompt: str, model: str, cwd: str) -> list[str]:
-    return [
-        "grok",
-        "-p",
-        prompt,
-        "-m",
-        model,
-        "--output-format",
-        "streaming-json",
-        "--cwd",
-        cwd,
-    ]
 
+def _take_presentation(argv: list[str]) -> tuple[list[str], str]:
+    """Split the one flag out of an otherwise positional argv.
+
+    Defaults to ``quiet``. ``live`` is only ever right where a screen was
+    declared, and the only callers that can declare one are the pane backends —
+    which pass the flag explicitly. Defaulting the other way assumed a screen
+    that a subagent dispatch does not have, and sent every worker's progress
+    into its caller's context window instead.
+    """
+    positional: list[str] = []
+    presentation = QUIET
+    index = 0
+    while index < len(argv):
+        if argv[index] != _PRESENTATION_FLAG:
+            positional.append(argv[index])
+            index += 1
+            continue
+        if index + 1 >= len(argv):
+            raise PreflightError(64, f"{_PRESENTATION_FLAG} needs a value: {_USAGE}")
+        presentation = argv[index + 1]
+        index += 2
+    if presentation not in _PRESENTATIONS:
+        allowed = " | ".join(_PRESENTATIONS)
+        raise PreflightError(
+            64, f"unsupported presentation {presentation!r}. Allowed values: {allowed}"
+        )
+    return positional, presentation
 
-def _kimi_args(prompt: str, model: str, _cwd: str) -> list[str]:
-    return ["kimi", "-p", prompt, "-m", model, "--output-format", "stream-json"]
 
+def _provider_spec(provider_id: str) -> ProviderSpec:
+    try:
+        spec = default_provider_registry().resolve(provider_id)
+    except UnknownProviderError as exc:
+        raise PreflightError(64, str(exc)) from exc
+    if spec.exec_strategy is None:
+        raise PreflightError(
+            64, f"provider {provider_id!r} has no execution strategy to run"
+        )
+    return spec
 
-PROVIDERS = {
-    "grok": ProviderCommand("grok", "okstra-grok-exec.sh", _grok_args),
-    "kimi": ProviderCommand("kimi", "okstra-kimi-exec.sh", _kimi_args),
-}
 
+def _existing_dir(raw: str, exit_code: int, label: str) -> Path:
+    """Existence only — `build_request` owns the resolving."""
+    path = Path(raw) if raw else None
+    if path is None or not path.is_dir():
+        raise PreflightError(
+            exit_code, f"{label} is missing or not a directory: {raw!r}"
+        )
+    return path
 
-@dataclass(frozen=True)
-class Invocation:
-    provider: ProviderCommand
-    project_root: Path
-    model: str
-    prompt_path: Path
-    execution_root: Path
-    role: str
-    idle_timeout_seconds: int
 
+def _existing_file(raw: str, exit_code: int, label: str) -> Path:
+    path = Path(raw) if raw else None
+    if path is None or not path.is_file():
+        raise PreflightError(exit_code, f"{label} is missing or not a file: {raw!r}")
+    return path.resolve()
 
-class PreflightError(Exception):
-    def __init__(self, exit_code: int, message: str) -> None:
-        super().__init__(message)
-        self.exit_code = exit_code
 
+def _idle_timeout(raw: str, role: str) -> int:
+    try:
+        return idle_timeout(raw, role)
+    except ValueError as exc:
+        raise PreflightError(69, str(exc)) from exc
 
-def _parse_invocation(argv: list[str]) -> Invocation:
-    if len(argv) < 4 or len(argv) > 7:
-        raise PreflightError(
-            64,
-            "usage: okstra-provider-exec.py <provider> <project-root> <model-execution-value> "
-            "<prompt-path> [worktree-path] [role] [idle-timeout-seconds]",
-        )
-    provider_id, project_root_raw, model, prompt_raw = argv[:4]
-    provider = PROVIDERS.get(provider_id)
-    if provider is None:
-        raise PreflightError(64, f"unsupported provider: {provider_id}")
-    worktree_raw = argv[4] if len(argv) >= 5 else ""
-    role = argv[5] if len(argv) >= 6 and argv[5] else "worker"
-    default_timeout = 1500 if role in {"executor", "verifier"} else 600
-    timeout_raw = argv[6] if len(argv) >= 7 else str(default_timeout)
-    return _validate_invocation(
-        provider, project_root_raw, model, prompt_raw, worktree_raw, role, timeout_raw
-    )
 
+def _check_command(strategy: ExecutionStrategy, request: WorkerExecRequest) -> None:
+    """Refuse a missing CLI before the run leaves any artifact behind.
 
-def _validate_invocation(
-    provider: ProviderCommand,
-    project_root_raw: str,
-    model: str,
-    prompt_raw: str,
-    worktree_raw: str,
-    role: str,
-    timeout_raw: str,
-) -> Invocation:
-    project_root = Path(project_root_raw)
-    prompt_path = Path(prompt_raw)
-    if not project_root_raw or not project_root.is_dir():
-        raise PreflightError(65, f"project-root is missing or not a directory: {project_root_raw!r}")
-    if not model:
-        raise PreflightError(66, "model-execution-value is empty")
-    if not prompt_raw or not prompt_path.is_file():
-        raise PreflightError(67, f"prompt-path is missing or not a file: {prompt_raw!r}")
-    if not timeout_raw.isdigit():
-        raise PreflightError(69, f"idle-timeout-seconds must be a non-negative integer: {timeout_raw!r}")
-    execution_root = Path(worktree_raw) if worktree_raw else project_root
-    if worktree_raw and not execution_root.is_dir():
-        raise PreflightError(68, f"worktree-path was provided but is not a directory: {worktree_raw!r}")
-    if shutil.which(provider.binary) is None:
-        raise PreflightError(127, f"{provider.binary} CLI is not installed on PATH")
-    return Invocation(
-        provider=provider,
-        project_root=project_root.resolve(),
-        model=model,
-        prompt_path=prompt_path.resolve(),
-        execution_root=execution_root.resolve(),
-        role=role,
-        idle_timeout_seconds=int(timeout_raw),
-    )
+    Building the command is the only truthful way to learn which binary this
+    provider runs, and it is a pure call. The check stays out of the runner so a
+    refused dispatch leaves no `started` status sidecar for the liveness probe to
+    read as a worker that launched.
+    """
+    binary = strategy.build_command(request).argv[0]
+    if shutil.which(binary) is None:
+        raise PreflightError(127, f"{binary} CLI is not installed on PATH")
 
 
 def _log_path(prompt_path: Path) -> Path:
@@ -124,105 +187,17 @@ def _log_path(prompt_path: Path) -> Path:
     return Path(f"{prompt_path}.log")
 
 
-def _write_status(path: Path, status: dict[str, object]) -> None:
-    temporary = Path(f"{path}.tmp")
-    temporary.write_text(json.dumps(status, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
-    os.replace(temporary, path)
-
-
-def _terminate_process(process: subprocess.Popen[bytes]) -> None:
-    try:
-        os.killpg(process.pid, signal.SIGTERM)
-    except ProcessLookupError:
-        return
-    try:
-        process.wait(timeout=5)
-    except subprocess.TimeoutExpired:
-        try:
-            os.killpg(process.pid, signal.SIGKILL)
-        except ProcessLookupError:
-            pass
-        process.wait()
-
-
-def _stream_process(
-    process: subprocess.Popen[bytes], log_file, idle_timeout_seconds: int
-) -> tuple[int, bool, int]:
-    selector = selectors.DefaultSelector()
-    assert process.stdout is not None
-    selector.register(process.stdout, selectors.EVENT_READ)
-    last_output = time.monotonic()
-    timed_out = False
-    idle_seconds = 0
-    while selector.get_map():
-        for key, _ in selector.select(timeout=0.25):
-            chunk = os.read(key.fd, 8192)
-            if not chunk:
-                selector.unregister(key.fileobj)
-                continue
-            last_output = time.monotonic()
-            sys.stdout.buffer.write(chunk)
-            sys.stdout.buffer.flush()
-            log_file.write(chunk)
-            log_file.flush()
-        idle_seconds = int(time.monotonic() - last_output)
-        if idle_timeout_seconds and idle_seconds >= idle_timeout_seconds and process.poll() is None:
-            timed_out = True
-            _terminate_process(process)
-    exit_code = process.wait()
-    return (124 if timed_out else exit_code), timed_out, idle_seconds
-
-
-def _run(invocation: Invocation) -> int:
-    prompt = invocation.prompt_path.read_text(encoding="utf-8")
-    command = invocation.provider.build_args(prompt, invocation.model, str(invocation.execution_root))
-    status_path = Path(f"{invocation.prompt_path}.status.json")
-    log_path = _log_path(invocation.prompt_path)
-    started_ts = int(time.time())
-    started_monotonic = time.monotonic()
-    status: dict[str, object] = {
-        "schemaVersion": 1,
-        "wrapper": invocation.provider.wrapper,
-        "role": invocation.role,
-        "pid": os.getpid(),
-        "started_ts": started_ts,
-        "log_path": str(log_path),
-        "stage": "started",
-    }
-    _write_status(status_path, status)
-    with log_path.open("wb") as log_file:
-        process = subprocess.Popen(
-            command,
-            cwd=invocation.execution_root,
-            stdout=subprocess.PIPE,
-            stderr=subprocess.STDOUT,
-            start_new_session=True,
-        )
-        exit_code, timed_out, idle_seconds = _stream_process(
-            process, log_file, invocation.idle_timeout_seconds
-        )
-    ended_ts = int(time.time())
-    status.update(
-        stage="exited",
-        exit_code=exit_code,
-        ended_ts=ended_ts,
-        duration_ms=int((time.monotonic() - started_monotonic) * 1000),
-    )
-    if timed_out:
-        status.update(
-            timeout=True,
-            idle_at_ts=ended_ts,
-            idle_seconds=idle_seconds,
-            terminated_by="idle-watchdog",
-        )
-    _write_status(status_path, status)
-    return exit_code
-
-
 def main(argv: list[str]) -> int:
     try:
-        invocation = _parse_invocation(argv[1:])
-        return _run(invocation)
+        invocation = parse_invocation(argv[1:])
+        return run_worker(
+            invocation.strategy,
+            invocation.request,
+            presentation=invocation.presentation,
+            log_path=invocation.log_path,
+            status_path=invocation.status_path,
+            status_extra=invocation.status_extra,
+        )
     except PreflightError as exc:
         print(f"okstra-provider-exec: {exc}", file=sys.stderr)
         return exc.exit_code

package/runtime/bin/okstra-trace-cleanup.sh

@@ -2,13 +2,20 @@
 #
 # okstra-trace-cleanup.sh — close tmux panes created during okstra runs.
 #
-# Trace panes are `tail -F` siblings spawned by the codex/antigravity wrappers
-# (`okstra-codex-exec.sh`, `okstra-antigravity-exec.sh`). Worker-compute panes are
-# tmux-pane backend siblings. Each wrapper/dispatcher tags the pane it owns with
-# a pane-level user option (`@okstra_trace_run=<RUN_DIR>` or
-# `@okstra_worker_run=<RUN_DIR>`), so panes are found server-wide by tag — no
-# tmux env var or pane-id registry is needed, and the run-scoped tag keeps
-# concurrent okstra runs from closing each other's panes.
+# Worker-compute panes are tmux-pane backend siblings. Their dispatcher tags
+# each pane it owns with a pane-level user option (`@okstra_worker_run=<RUN_DIR>`),
+# so panes are found server-wide by tag — no tmux env var or pane-id registry is
+# needed, and the run-scoped tag keeps concurrent okstra runs from closing each
+# other's panes.
+#
+# Trace panes were `tail -F` siblings the provider wrappers split, tagged
+# `@okstra_trace_run` / `@okstra_status`. Those wrappers are now four-line
+# entrypoints and worker progress renders into the worker's own pane, so
+# NOTHING SPAWNS A TRACE PANE and neither tag has a writer left. The trace
+# paths below still run and simply match nothing; `--reclaim-completed`, which
+# keys on `@okstra_status`, is inert for the same reason. Kept rather than
+# deleted because the hooks that call this script are already seeded on user
+# machines — retiring the trace machinery is a deliberate follow-up.
 #
 # Two invocation shapes:
 #

package/runtime/bin/okstra-wrapper-status.py

@@ -1,27 +1,34 @@
 #!/usr/bin/env python3
-"""okstra-wrapper-status.py — heartbeat sidecar writer for codex/antigravity wrappers.
-
-The codex/antigravity wrappers (`okstra-codex-exec.sh`, `okstra-antigravity-exec.sh`)
-dispatch a long-running CLI under `Bash(run_in_background: true)` and rely on
-`BashOutput` polling for liveness. That polling stream only carries stdout
-plus a binary `running`/`completed` state. Several recovery decisions need
-more — specifically, "did this wrapper start at all, when, and how did it
-finish?" — so the wrappers write a small JSON sidecar at
-`<prompt-path>.status.json` that survives independent of the polling channel.
-
-Consumers:
-
-* `codex-worker` / `antigravity-worker` step 8c: read `log_path` to capture a
-  diagnostic tail when `exit_code == 0` but the canonical Result file is
-  absent.
-* Lead: cross-check `started_ts` / `ended_ts` to distinguish "wrapper hung
+"""okstra-wrapper-status.py — standalone CLI for the worker status sidecar.
+
+A CLI worker dispatch runs a long-running CLI in the background, and the
+polling channel that watches it carries only stdout plus a binary
+`running`/`completed` state. Several recovery decisions need more —
+specifically, "did this worker start at all, when, and how did it finish?" — so
+a small JSON sidecar is written at `<prompt-path>.status.json` that survives
+independent of the polling channel.
+
+**Nothing calls this script.** Every provider entrypoint now runs through
+`scripts/okstra_ctl/worker_runner.py`, which writes the same document
+in-process; the shell wrappers that shelled out to this file were its only
+callers and they are gone. It is kept for now rather than deleted because
+removing it also means touching the build sync list, the install payload, its
+own test module and the docs that name it — a deliberate follow-up, not a side
+effect of the wrapper migration. `scripts/okstra_ctl/wrapper_status.py` is the
+reader, and what it reads is what the runner writes.
+
+Consumers of the sidecar:
+
+* A CLI worker's diagnostic step: read `log_path` to capture a tail when
+  `exit_code == 0` but the canonical Result file is absent.
+* Lead: cross-check `started_ts` / `ended_ts` to distinguish "worker hung
   before CLI launched" from "CLI finished but never wrote artifact" when
   applying the redispatch policy (see team-contract "Lead Redispatch
   Policy on Result-Missing").
 
-Failures are deliberately non-fatal for the caller — the wrapper's main
-job is to run the underlying CLI; a missing sidecar must not break that.
-On any error the script prints a one-line diagnostic to stderr and exits 0.
+Failures are deliberately non-fatal for the caller — the caller's main job is
+to run the underlying CLI; a missing sidecar must not break that. On any error
+the script prints a one-line diagnostic to stderr and exits 0.
 
 Schema (schemaVersion 1):
 

package/runtime/prompts/lead/adapters/cmux.md

@@ -57,7 +57,7 @@ Use the screen to tell "still working" from "stuck", and to see at a glance whic
 - Worker completion is valid only from `workerDispatches[]`, terminal status sidecars, and required Result Paths. Pane creation alone is not completion.
 - Reverify uses a fresh jobs file at `runs/<task-type>/state/reverify-jobs-r<N>-<task-type>-<seq>.json`, sets `dispatchKind: "reverify-r<N>"`, and dispatches with `okstra team dispatch --project-root <root> --run-manifest <path> --dispatch-kind reverify-r<N> --jobs-file <jobs-file>`.
 - Report-writer uses a fresh one-job jobs file with `dispatchKind: "report-writer"` and the same schema, then dispatches through `okstra team dispatch --project-root <root> --run-manifest <path> --jobs-file <jobs-file>`.
-- Every reverify or report-writer jobs file carries `workerId`, `provider`, `role`, `modelExecutionValue`, `promptPath`, `resultPath`, `workerResultPath`, and `completionPaths`. For reverify, set `role` to `worker-reverify-r<N>` for the pane title. The report-writer completion paths include both data.json and the worker-results audit file.
+- Every reverify or report-writer jobs file carries `workerId`, `provider`, `role`, `modelExecutionValue`, `promptPath`, `resultPath`, `workerResultPath`, and `completionPaths`. For reverify, set `role` to `worker-reverify-r<N>` — the role selects the dispatch's idle budget and is recorded in the run's status sidecar, so it must name the actual assignment. The report-writer completion paths include both data.json and the worker-results audit file.
 - After either dispatch, run `okstra team await --project-root <root> --run-manifest <path>` before evaluating terminal status or completion paths.
 
 ## Completion, cleanup, and resume

package/runtime/prompts/lead/convergence.md

@@ -540,7 +540,7 @@ Schema rules:
 
 ## Coverage critic pass
 
-Runs only when `convergence.critic.enabled == true` (set by `--critic <provider>` or the okstra-run `critic_pick` step; default off). Applies to the three finding-producing phases (`requirements-discovery`, `error-analysis`, `implementation-planning`); for `final-verification` the critic runs in a different mode — see §"Acceptance critic pass (final-verification)". This pass targets **coverage** (missed findings), distinct from convergence which targets **agreement quality**.
+Runs only when `convergence.critic.enabled == true` (set by `--critic <provider>` or the okstra-run `critic_pick` step; default off). Applies to the three finding-producing phases (`requirements-discovery`, `error-analysis`, `implementation-planning`); for `final-verification` the critic runs in a different mode — see §"Acceptance critic pass (final-verification)". This pass targets **scope in both directions** — findings that are missing (coverage) and work the findings propose that no requirement asked for (over-scope) — distinct from convergence, which targets **agreement quality** among the findings already raised. The pass keeps its `coverage` mode id and `gaps` vocabulary for both halves; the two are told apart by each candidate's `category`, so no schema or reducer distinguishes them.
 
 ### When
 
@@ -554,10 +554,12 @@ Dispatch one fresh pass to `config.critic.provider` through `redispatch_worker`,
 
 The `-worker-` token is load-bearing, not decoration: the critic prompt carries the same generated anchor headers as every other worker ([team-contract](./team-contract.md) §"Worker prompts"), and its `**Audit sidecar path:**` comes from passing that result path through `okstra_ctl.worker_artifact_paths.audit_sidecar_rel()`, which inserts `-audit-` after the token and raises without it. A `<provider>-critic-...` name leaves the lead choosing between breaking the contract and hand-inventing the sidecar name. Note that `originWorker` stays `"<provider>-critic"` — that is a worker id in the convergence state, not a filename, and the two do not have to match.
 
-The critic prompt seeds the consolidated findings and asks ONLY for coverage gaps:
+The critic prompt carries the full analysis contract those anchor headers belong to — worker preamble, error-contract path, audit sidecar, packet boundary — but it is **exempt from the initial-analysis equality group**. Initial analysis workers must receive byte-identical normalized bodies (`worker_prompt_contract.validate_analysis_prompt_set`), and a critic body is deliberately unlike them, so `okstra_ctl.worker_prompt_policy.resolve_prompt_plan` resolves `dispatchKind = "critic"` to `equality_group = None` while keeping `audience = "analysis"`. Never reshape a critic prompt to match the initial one to satisfy that check — matching it would delete the pass. **Enforced:** `tests/contract/test_critic_prompt_equality_exemption.py` pins both directions — the critic is exempt, and two mismatched *initial* prompts still fail.
 
-Required reading before proposing a gap:
-- the current run's `analysis-packet.md` for requirements and phase scope;
+The critic prompt seeds the consolidated findings and asks for two things only — coverage gaps and unrequested work. The second half exists because every other scope check in the lifecycle runs *later*: the plan-body `P-Opt-*` verdict judges options this phase has not authored yet (report-writer writes the plan in Phase 6), and the `implementation` verifier judges a diff. Here the unit is a **finding**, which is the input those stages build on — catching unrequested work while it is still a finding is the cheapest place to catch it at all.
+
+Required reading before proposing a gap or an over-scope candidate:
+- the current run's `analysis-packet.md` for requirements and phase scope — for the over-scope half this is the authority you search against, so read it before judging any finding unrequested;
 - `convergence-groups-<task-type>-<seq>.json` for the complete Round 0 ledger;
 - every initial analysis-worker result named by team-state;
 - each matching audit sidecar, to distinguish an uninspected path from a claim that was inspected but summarized during grouping.
@@ -565,13 +567,30 @@ Required reading before proposing a gap:
 Operational guardrails are not task requirements. A gap must trace to a brief requirement, an analysis-packet scope item, a source path the packet authorizes, or an evidence claim in a worker result. Do NOT infer missing verification from a one-line summary; open the named result and audit sidecar first.
 
 ```
-You are the coverage critic for <task-key>. Below are the consolidated findings
-the workers produced. Your ONLY job is to name what is MISSING:
+You are the scope critic for <task-key>. Below are the consolidated findings the
+workers produced. Your job has exactly two halves. Answer both.
+
+(1) MISSING — name what nobody covered:
 - files / directories / execution paths nobody inspected,
 - requirements or acceptance points with zero findings,
 - claims raised but never verified.
-For each gap, emit a NEW finding with evidence (file:line or the requirement quote).
-Do NOT restate an existing finding. If nothing is missing, say so explicitly.
+For each, emit a NEW finding with evidence (file:line or the requirement quote).
+
+(2) UNREQUESTED — name work these findings propose that no requirement asked for:
+- a finding whose proposed change serves no requirement, scope item, or
+  acceptance point you can QUOTE from the analysis packet,
+- an abstraction, configuration knob, or generalization proposed for a caller or
+  a case nobody has stated,
+- a rewrite, migration, or cleanup of code the requirements never mention.
+For each, emit a candidate with `category: "unrequested-scope"`, quote the
+proposed work verbatim, and state which requirement you searched for and did not
+find.
+
+Do NOT restate an existing finding. Judge (2) against the analysis packet's
+requirements and scope, never against your own preference for how the code should
+look — "I would have done it differently" is not unrequested work, and neither is
+work the packet authorizes but you consider unnecessary. If a half has nothing,
+say so explicitly for that half; silence on one half is an incomplete result.
 ```
 
 ### Gap verification (1 adversarial reverify round)
@@ -579,8 +598,17 @@ Each critic gap enters the verification queue as a finding with `originWorker =
 
 **A gap that received no verdict is NOT a rejected gap (BLOCKING).** Dropping applies only to gaps the voters actually judged. A gap can also end the round *unjudged* — the verification dispatch returned a terminal non-result (`timeout`, `error`, no result file), the returned result covered only some of the gaps, or no non-critic analyser was available to vote at all. Nobody inspected those, so classifying them as hallucinations is a fabricated verdict. Each one MUST be recorded as a `## 5. Missing Information and Risks` row (`missingInformation`, `source: "critic-unverified"`) whose `risk` names the gap and the reason verification did not complete, and counted in `config.critic.gapsUnverified`. They are **not** promoted to findings (unverified) and **not** raised as `clarification` items — an unverified gap needs an analyser to verify it on the next run, not a decision from the user. Silently losing them is a contract violation: the batch that times out is exactly the batch of gaps too expensive to check, so the highest-risk items are the ones that vanish.
 
+**`category: "unrequested-scope"` candidates are classified the same way but disposed of differently.** A coverage gap the voters contest is a hallucination — nothing was actually missing, so dropping it costs one wasted verification. An over-scope candidate the voters contest is a *disagreement about whether the work was asked for*, and dropping that silently returns the run to the state this half exists to change. So:
+
+- `full-consensus` / `partial-consensus` → merge as a finding, exactly like a coverage gap. The merged finding names the unrequested work and the requirement search that came up empty; the phase's own deliverable rules decide whether it lands as a dropped item or a clarification row.
+- `contested` / `worker-unique` → counted in `config.critic.gapsRejected` (unchanged accounting) but ALSO recorded as a `## 5. Missing Information and Risks` row with `source: "critic-unconfirmed-scope"`, whose `risk` quotes the proposed work and the split verdict. It is **not** promoted to a finding: a contested over-scope claim must not block a plan on one worker's taste. The user reads the row and decides.
+- no verdict at all → the `critic-unverified` rule above applies unchanged.
+
+The asymmetry is deliberate and runs the opposite way from the coverage half: a false "you missed something" costs a verification, while a false "you built too much" costs a real requirement — so the first may be dropped outright and the second is recorded either way. This is the same reasoning that makes the `final-verification` acceptance critic never drop a candidate, applied to the one direction where dropping is otherwise the default.
+
 ### State
 - `convergence.critic` manifest block: `{ enabled, provider, modelExecutionValue }`.
+- Each candidate's `category` tells the two halves apart: literal `"unrequested-scope"` for the over-scope half, any other value for a coverage gap. `schemas/convergence-critic-results-v1.0.schema.json` leaves `category` a free string, so this needs no schema or reducer change — but it also means nothing machine-checks the spelling. A misspelled category is read as a coverage gap and silently takes the drop-on-contested path.
 - The lead passes one canonical coverage batch with `{ schemaVersion, taskKey, mode, provider, modelExecutionValue, dispatches, gaps }`; each gap carries its candidate fields plus `gapId` and `votes`. `dispatches[]` contains exactly one row for every Phase 4 analyser except the critic, even when execution did not produce a result: persist `status: timeout | error | not-run` and the elapsed `durationMs` instead of omitting that analyser. `apply-critic-gaps` rejects a non-terminal main queue, duplicate or missing analysers, unknown workers, critic dispatches/votes, votes without a completed dispatch, and a second batch.
 - Convergence state artifact: merged gaps appear in `findings[]` with `source: "critic"` and `rounds: []`. The separate `criticVerification.gaps[]` ledger retains each gap's `summary`, `category`, `ticketIds`, `originEvidence`, optional `evidenceArtifacts`, classification, merge link, and votes. Strict v1.3 validation deterministically replays each complete critic-origin finding from that ledger; a critic batch never increments `roundHistory` or `totalRounds` and never creates a fake main round.
 - `config.critic` is `{ provider, modelExecutionValue, gapsProposed, gapsMerged, gapsRejected, gapsUnverified }`, with `gapsProposed = gapsMerged + gapsRejected + gapsUnverified`. `full-consensus` / `partial-consensus` gaps merge, `contested` / `worker-unique` gaps count as rejected, and gaps with no usable analyser vote appear in both the ledger and final `unverifiedGaps[]`.

package/runtime/prompts/lead/okstra-lead-contract.md

@@ -104,9 +104,10 @@ Required checkpoints:
 - `PROGRESS: phase-5-collect worker=<role> status=<terminal-status>` — once per worker, immediately after the result file is verified.
 - `PROGRESS: phase-5.5-convergence round=<N> queue=<count>` — at the start of each convergence round (Phase 5.5).
 - `PROGRESS: phase-5.6-critic provider=<provider> gaps=<n>` — after the critic result is collected (Phase 5.6, opt-in; the critic dispatch itself fires concurrently with the first 5.5 reverify round). Omitted when `convergence.critic.enabled == false`.
-- `PROGRESS: phase-batch-cleanup panes=<n>` — immediately after cleaning up the previous batch's panes, at each batch boundary (① just before the first `phase-5.5-convergence` round ② just before the `phase-6-synthesis` report-writer dispatch). `<n>` is the number of panes reclaimed at that boundary — trace panes plus completed teammate panes, which are panes too — read from the cleanup's `--list` pass taken immediately before the reclaim, never estimated. Expose only the counts and NEVER expose `%NNN`/lead-pane.id/raw worker handles. Just before the first batch (analysis-worker dispatch) there is nothing to clean up, so it is a no-op and the marker is omitted.
+- `PROGRESS: phase-batch-cleanup panes=<n>` — immediately after cleaning up the previous batch's panes, at each batch boundary (① just before the first `phase-5.5-convergence` round ② just before the `phase-6-synthesis` report-writer dispatch). `<n>` is the number of panes reclaimed at that boundary — worker-compute panes plus completed teammate panes, which are panes too — read from the cleanup's `--list` pass taken immediately before the reclaim, never estimated. Expose only the counts and NEVER expose `%NNN`/lead-pane.id/raw worker handles. Just before the first batch (analysis-worker dispatch) there is nothing to clean up, so it is a no-op and the marker is omitted.
 - `PROGRESS: phase-6-synthesis dispatching report-writer-worker` — at the start of Phase 6.
 - `PROGRESS: phase-5.5.9-plan-verify round=<N> items=<count>` — immediately before dispatching each plan-body verification round (`implementation-planning` only; see [plan-body-verification](./plan-body-verification.md) §"Round protocol"). Each round is a worker batch like any other, so round 2 and later MUST be preceded by a `phase-batch-cleanup` line reclaiming the previous round's verifiers. The numbering keeps this line sorted where the work happens — after Phase 6, because the round verifies the drafted plan body.
+- `PROGRESS: user-confirm <C-NNN> <the question, one line>` — immediately before asking the user about anything that would otherwise become an open `Blocks=approval` row (see "User confirmation before an approval blocker" below). Not tied to a phase: it fires wherever the blocker surfaces. `<C-NNN>` is the id the row will carry, so the answer and the row can be matched afterwards.
 - `PROGRESS: phase-7-persist updating manifests` — at the start of Phase 7.
 - `PROGRESS: phase-7-teardown shutting-down-workers` — only after usage collection and user approval, immediately before `shutdown_workers`; omitted when no cleanup resource exists or the user keeps it.
 - `PROGRESS: complete final-report=<relative-path>` — final summary line, after all persistence.
@@ -117,6 +118,27 @@ Do NOT replace them with prose ("Now I'm starting Phase 2..."), do NOT skip a ch
 
 **Enforcement:** the Phase 7 validator (`validators/validate-run.py` → `validate_session_conformance.py`) reads the selected adapter's declared conformance evidence/event source within the run window and fails the run as `contract-violated` when a required checkpoint is missing — including the per-worker `phase-4-dispatch` / `phase-5-collect` lines (which must name each worker's role) and the `phase-batch-cleanup` lines that MUST precede the first `phase-5.5-convergence` round and the `phase-6-synthesis` report-writer dispatch. When the plan-body state file records two or more rounds, `_check_plan_verify_cleanup_checkpoints` additionally requires a `phase-5.5.9-plan-verify` line per round and a `phase-batch-cleanup` between consecutive rounds — that boundary sat outside both older checks, so a five-round self-fix loop left every round's verifiers holding their panes. `phase-7-teardown` and `complete` fire after validation and are not checked.
 
+## User confirmation before an approval blocker (BLOCKING)
+
+An open `Blocks=approval` row stops the whole task: the plan cannot be approved, `implementation` cannot start, and the answer arrives only through a separate user-response cycle and a re-run. It is the most expensive artifact this contract lets the lead produce. **Before writing one, ask the user.**
+
+This is not a phase. It fires wherever the blocker surfaces — during intake when the directive and the brief disagree, mid-convergence when workers split on something only the user can settle, in the §5.5.9 self-fix loop when an item no round can clear keeps the gate red.
+
+The sequence is fixed:
+
+1. Emit `PROGRESS: user-confirm <C-NNN> <the question, one line>` with the id the row would carry.
+2. Ask in plain user-facing text: what is undecided, the options with their consequences, and which one you recommend. One question at a time.
+3. On an answer — record it in the row's `userInput`, set `status: answered` and `userConfirmation: asked-and-answered`, apply it, and **keep going in this run**. An answered question is not a blocker, and a run that stops anyway wastes the answer it just received.
+4. Only when asking fails does the row stay open: `asked-awaiting` when the user has not answered, `deferred-no-interactive-session` when this run has no user to ask.
+
+**Predicting the blocker is not the same as raising it.** A lead that says "this will likely become an approval blocker; I will ask at that point" has already reached the moment — ask then, in that message. One run announced exactly that, never asked, wrote the row anyway, and then spent its entire self-fix budget on a gate no round could clear, because the user had already answered the question before the run started.
+
+**`lead-directed` blockers cannot be deferred.** When the item is the lead's own judgment rather than a worker's finding, and this run has nobody to ask, the row is not the outlet — record a Working Assumption in `## 5. Missing Information and Risks` naming the assumption the plan proceeds under, exactly as a surviving planner-fixable item does, and let the plan proceed. Blocking a plan on the lead's own judgment in a run where that judgment cannot be put to the user only moves the work to a re-run.
+
+**Never seed the answer into a worker prompt.** Instructing a worker to "raise this as a user decision rather than choosing" and then reporting the resulting agreement as an independent finding misrepresents where the blocker came from. If it is the lead's judgment, `origin` is `lead-directed` — see [_common-contract.md](../profiles/_common-contract.md) "Clarification request policy".
+
+**Enforcement:** `validators/validate-run.py` `_validate_open_approval_blocker_provenance` fails any open approval blocker missing `origin` / `userConfirmation`, and any `lead-directed` one deferred for want of an interactive session; `validators/validate_session_conformance.py` `_check_user_confirm_checkpoints` fails a row claiming the user was asked when no matching `user-confirm` line exists in this run's evidence.
+
 ## Model assignments
 
 **The lead never invents a model.** Every role's model is read from `task-manifest.json` → `resultContract.requiredWorkerRoles[*].modelExecutionValue` (and the lead model metadata). A missing assignment is a manifest defect, not a license to fall back — see [team-contract](./team-contract.md) "Model Assignment Rules". The manifest is always populated at run-prep time by the CLI, which seeds these values from `OKSTRA_DEFAULT_*_MODEL` (`scripts/okstra_ctl/run.py`).