okstra 0.164.0 → 0.165.0

package/runtime/python/okstra_ctl/adapters/providers/grok/adapter.py

@@ -1,5 +1,12 @@
 """Bundled Grok provider catalog."""
 from okstra_ctl.domain.provider import LeadLaunchSpec, ModelSpec, ProviderSpec
+from okstra_ctl.domain.worker_exec import (
+    STREAM_JSON,
+    ExecCommand,
+    PolicySupport,
+    WorkerExecRequest,
+)
+from okstra_ctl.domain.worker_stream import content_block_events
 
 
 GROK = {
@@ -16,6 +23,42 @@ GROK_LEAD_LAUNCH = LeadLaunchSpec(
 )
 
 
+class GrokExecution:
+    """grok CLI invocation.
+
+    Runs inside the stage tree when there is one. That is where this provider's
+    production path already puts it, and it is why the working directory is part
+    of the returned command rather than something the runner picks.
+    """
+
+    def build_command(self, request: WorkerExecRequest) -> ExecCommand:
+        cwd = request.worktree_path or request.project_root
+        return ExecCommand(
+            argv=(
+                "grok",
+                "-p",
+                request.prompt_text,
+                "-m",
+                request.model,
+                "--output-format",
+                "streaming-json",
+                "--cwd",
+                str(cwd),
+            ),
+            stdin_text=None,
+            stream_format=STREAM_JSON,
+            normalise=content_block_events,
+            cwd=cwd,
+        )
+
+    def policy_support(self) -> PolicySupport:
+        return PolicySupport(
+            can_auto_approve=False,
+            can_bound_write_scope=False,
+            note="this CLI exposes no approval or sandbox flag",
+        )
+
+
 def create_provider() -> ProviderSpec:
     return ProviderSpec(
         provider="grok",
@@ -29,4 +72,5 @@ def create_provider() -> ProviderSpec:
         wrapper="okstra-grok-exec.sh",
         supported_roles=frozenset({"lead", "analyser", "critic"}),
         lead_launch=GROK_LEAD_LAUNCH,
+        exec_strategy=GrokExecution(),
     )

package/runtime/python/okstra_ctl/adapters/providers/kimi/adapter.py

@@ -1,5 +1,12 @@
 """Bundled Kimi provider catalog."""
 from okstra_ctl.domain.provider import LeadLaunchSpec, ModelSpec, ProviderSpec
+from okstra_ctl.domain.worker_exec import (
+    STREAM_JSON,
+    ExecCommand,
+    PolicySupport,
+    WorkerExecRequest,
+)
+from okstra_ctl.domain.worker_stream import content_block_events
 
 
 KIMI = {
@@ -22,6 +29,40 @@ KIMI_LEAD_LAUNCH = LeadLaunchSpec(
 )
 
 
+class KimiExecution:
+    """kimi CLI invocation.
+
+    No flag names the working directory, so the process's own is the only
+    control. Returning it in the command keeps that fact inside the contract
+    instead of leaving the runner to infer it.
+    """
+
+    def build_command(self, request: WorkerExecRequest) -> ExecCommand:
+        cwd = request.worktree_path or request.project_root
+        return ExecCommand(
+            argv=(
+                "kimi",
+                "-p",
+                request.prompt_text,
+                "-m",
+                request.model,
+                "--output-format",
+                "stream-json",
+            ),
+            stdin_text=None,
+            stream_format=STREAM_JSON,
+            normalise=content_block_events,
+            cwd=cwd,
+        )
+
+    def policy_support(self) -> PolicySupport:
+        return PolicySupport(
+            can_auto_approve=False,
+            can_bound_write_scope=False,
+            note="this CLI exposes no approval or sandbox flag",
+        )
+
+
 def create_provider() -> ProviderSpec:
     return ProviderSpec(
         provider="kimi",
@@ -35,4 +76,5 @@ def create_provider() -> ProviderSpec:
         wrapper="okstra-kimi-exec.sh",
         supported_roles=frozenset({"lead", "analyser", "critic"}),
         lead_launch=KIMI_LEAD_LAUNCH,
+        exec_strategy=KimiExecution(),
     )

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 import json
 import subprocess
 import time
-from dataclasses import dataclass, field
+from dataclasses import dataclass, field, replace
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Mapping, Sequence
@@ -620,6 +620,10 @@ def _refuse_when_cmux_is_walled_off() -> None:
 
 
 def _run_cli_wrapper(plan: DispatchPlan, job: WorkerJob, degraded_from: str) -> WorkerHandle:
+    # Whatever the job was planned as, this is a cli-wrapper dispatch: no pane
+    # took it, so the worker's stdout is read by whoever called the lead. The
+    # record already says so (`_dispatch_record`), and the command must agree.
+    job = replace(job, backend=BACKEND_CLI_WRAPPER)
     completed = subprocess.run(job.command, cwd=plan.project_root, text=True)
     return WorkerHandle(job, "", completed, status_path_for_prompt(job.prompt_path), degraded_from)
 

package/runtime/python/okstra_ctl/dispatch_state.py

@@ -30,6 +30,7 @@ from .worker_prompt_contract import (
     validate_initial_prompt_records,
     validate_reverify_prompt,
 )
+from .worker_runner import LIVE, QUIET
 
 BACKEND_CLI_WRAPPER = "cli-wrapper"
 BACKEND_TMUX_PANE = "tmux-pane"
@@ -91,6 +92,7 @@ class WorkerJob:
 
     @property
     def command(self) -> list[str]:
+        # The flag trails the positional contract the entrypoint reads by index.
         return [
             str(self.wrapper_path),
             str(self.project_root),
@@ -99,8 +101,16 @@ class WorkerJob:
             self.worktree_path,
             self.role,
             str(self.idle_timeout_seconds),
+            "--presentation",
+            self._presentation(),
         ]
 
+    def _presentation(self) -> str:
+        # A pane is a screen a person watches; a cli-wrapper dispatch's stdout is
+        # a subagent's context window. Progress belongs in the first and not the
+        # second.
+        return QUIET if self.backend == BACKEND_CLI_WRAPPER else LIVE
+
     def to_payload(self) -> dict[str, Any]:
         return {
             "workerId": self.worker_id,

package/runtime/python/okstra_ctl/domain/provider.py

@@ -2,7 +2,10 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Mapping, Optional
+from typing import TYPE_CHECKING, Mapping, Optional
+
+if TYPE_CHECKING:
+    from okstra_ctl.domain.worker_exec import ExecutionStrategy
 
 
 @dataclass(frozen=True)
@@ -35,6 +38,7 @@ class ProviderSpec:
     wrapper: str
     supported_roles: frozenset[str]
     lead_launch: Optional[LeadLaunchSpec] = None
+    exec_strategy: Optional["ExecutionStrategy"] = None
 
 
 @dataclass(frozen=True)

package/runtime/python/okstra_ctl/domain/worker_exec.py

@@ -0,0 +1,102 @@
+"""Provider-neutral execution contracts shared by the dispatcher and workers.
+
+A worker run is decided along three axes: which terminal surface it lands on,
+which provider CLI runs it, and which role it plays. This module owns the
+provider axis' vocabulary plus the one rule that is identical for every worker
+regardless of provider — see ``ExecutionPolicy``.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from .worker_stream import Normalise, no_events
+
+# What ``ExecCommand.stream_format`` may hold. The value decides whether the
+# runner pipes the CLI's output through the stream formatter or forwards it
+# unchanged, so it is part of the contract rather than a display hint.
+STREAM_JSON = "stream-json"
+TEXT = "text"
+
+
+@dataclass(frozen=True)
+class ExecutionPolicy:
+    """How a non-interactive worker is allowed to act.
+
+    Identical for every worker: nobody is at the keyboard to answer an approval
+    prompt, so the gate has to be open and the boundary has to come from a
+    sandbox instead. Declared once here rather than per provider, because a
+    policy that lives in one adapter file per provider drifts into one policy
+    per provider.
+    """
+
+    auto_approve: bool
+    write_scope: tuple[Path, ...]
+
+
+@dataclass(frozen=True)
+class WorkerExecRequest:
+    """One worker dispatch, before any provider has looked at it.
+
+    ``worktree_path`` is the stage tree this run was given, or None for a
+    dispatch that works in the project itself. It is kept apart from
+    ``policy.write_scope`` because the two answer different questions: the scope
+    is what may be written, while this is where the run belongs. Providers
+    disagree on that second answer, so the request carries both and each
+    strategy decides.
+    """
+
+    prompt_text: str
+    model: str
+    project_root: Path
+    worktree_path: Path | None
+    policy: ExecutionPolicy
+    idle_timeout_seconds: int
+
+
+@dataclass(frozen=True)
+class ExecCommand:
+    """One provider invocation, fully resolved.
+
+    ``stdin_text`` is None when the provider takes its prompt as an argument
+    rather than on stdin.
+
+    ``cwd`` is part of the contract because it is not derivable from the argv:
+    some CLIs name their working directory in a flag, others inherit the
+    process's, and the two groups do not choose the same directory. A runner
+    that had to re-derive it would be guessing at what the strategy already
+    decided.
+
+    ``normalise`` is the companion of ``stream_format``: declaring a JSON stream
+    without saying how to read it is what left one provider's pane blank for a
+    whole run. The two are named together so a provider whose events are shaped
+    differently cannot be silently handed a formatter that cannot see them.
+    """
+
+    argv: tuple[str, ...]
+    stdin_text: str | None
+    stream_format: str
+    cwd: Path
+    normalise: Normalise = field(default=no_events)
+
+
+@dataclass(frozen=True)
+class PolicySupport:
+    """Whether a provider CLI can express ``ExecutionPolicy`` at all.
+
+    A provider that cannot must say so rather than quietly accepting the policy
+    and running without it. ``note`` carries the reason and is what the contract
+    test asserts on.
+    """
+
+    can_auto_approve: bool
+    can_bound_write_scope: bool
+    note: str = ""
+
+
+@runtime_checkable
+class ExecutionStrategy(Protocol):
+    def build_command(self, request: WorkerExecRequest) -> ExecCommand: ...
+
+    def policy_support(self) -> PolicySupport: ...

package/runtime/python/okstra_ctl/domain/worker_role.py

@@ -0,0 +1,34 @@
+"""Per-role execution parameters.
+
+Roles differ by value, not by algorithm, so this is a value object rather than
+a strategy. Owning the values here takes the final say back from the shell: the
+dispatcher passed a global idle budget while each wrapper quietly overrode it
+with its own `case "$role"` block.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# Implementation executor / verifier dispatches run whole build + test suites
+# that legitimately emit nothing for minutes; the 600s cap reaped them mid-suite
+# (observed: a silent jest + tsc build TERM'd at ~929s). This stays below the
+# 1800s wall-clock polling cap so a genuine hang is still reaped first.
+_BUILD_RUNNING_IDLE_SECONDS = 1500
+_DEFAULT_IDLE_SECONDS = 600
+
+_BUILD_RUNNING_ROLES = frozenset({"executor", "verifier"})
+
+
+@dataclass(frozen=True)
+class WorkerRoleSpec:
+    role: str
+    idle_timeout_seconds: int
+
+
+def role_spec(role: str) -> WorkerRoleSpec:
+    seconds = (
+        _BUILD_RUNNING_IDLE_SECONDS
+        if role in _BUILD_RUNNING_ROLES
+        else _DEFAULT_IDLE_SECONDS
+    )
+    return WorkerRoleSpec(role=role, idle_timeout_seconds=seconds)

package/runtime/python/okstra_ctl/domain/worker_stream.py

@@ -0,0 +1,261 @@
+"""Turn a worker's progress into lines a person can read.
+
+Pure transformation: no files, no sockets, no clock. The runner decides where
+the lines go; this module decides what they say.
+
+Providers do not agree on a wire format, and this layer may not name one. So the
+formatter never reads a provider's JSON: it reads the normalised events below,
+and each provider adapter supplies the function that produces them from its own
+wire shape (``ExecCommand.normalise``). One wire shape is shared widely enough
+to be worth a default here — ``content_block_events``, whose events are keyed on
+``type`` and carry ``message.content`` blocks — but it is a schema, not a
+provider, and an adapter that speaks something else says so in its own file.
+
+Screen output folds what the log keeps in full — a tool call becomes one line, a
+tool result becomes an outcome and a size. Thinking is dropped at normalisation,
+which is safe only because worker liveness is measured from stream arrival
+rather than from log writes (see the spec's 7.2).
+
+Three projections of the same stream: ``format_live`` for the pane,
+``format_log`` for the archive, and ``final_text`` for the caller that must
+receive the closing message without the progress that produced it.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable, Mapping
+
+# Worker panes sit in a two-column grid whose narrowest allowed pane is the
+# floor named by the placement module (60 columns at the time of writing).
+# Holding a summary to two such lines keeps one tool call from pushing the
+# previous one off the top of a short pane.
+_MAX_SUMMARY = 120
+
+
+@dataclass(frozen=True)
+class Text:
+    """Prose the worker addressed to whoever is reading."""
+
+    body: str
+
+
+@dataclass(frozen=True)
+class ToolCall:
+    """A tool the worker invoked, and the argument worth naming on one row."""
+
+    name: str
+    detail: str = ""
+
+
+@dataclass(frozen=True)
+class ToolResult:
+    """What a tool returned.
+
+    ``size_bytes`` is carried rather than derived from ``body`` because the two
+    answer different questions: the size is how much the tool produced, while
+    the body is what the archive is willing to keep of it.
+
+    ``failed`` is None when the stream closed the tool step without reporting an
+    outcome at all. Reading that absence as success would put a confident "ok"
+    next to a command that failed.
+    """
+
+    body: str
+    size_bytes: int
+    failed: bool | None = None
+
+
+@dataclass(frozen=True)
+class Denial:
+    """A tool call the provider refused before the worker could make it."""
+
+    tool: str
+    reason: str
+
+
+@dataclass(frozen=True)
+class Result:
+    """The worker's closing message. At most one per run."""
+
+    text: str
+
+
+StreamEvent = Text | ToolCall | ToolResult | Denial | Result
+
+# What an adapter hands the runner alongside its stream format: one line of the
+# CLI's output, already parsed, turned into however many normalised events it
+# carries. Returning nothing is how an event is dropped.
+Normalise = Callable[[Mapping[str, Any]], tuple[StreamEvent, ...]]
+
+
+def no_events(event: Mapping[str, Any]) -> tuple[StreamEvent, ...]:
+    """The normaliser for a CLI that emits no events at all.
+
+    A text CLI's output is already what a person reads, so the runner forwards
+    it whole and never calls this. It exists so ``ExecCommand`` can default to
+    a truthful "there is nothing here to normalise" instead of to some
+    provider's schema.
+    """
+    return ()
+
+
+def content_block_events(event: Mapping[str, Any]) -> tuple[StreamEvent, ...]:
+    """Normalise the stream shape keyed on ``type`` with ``message.content``.
+
+    Assistant events carry the worker's prose and its tool calls in the same
+    content list, so one event becomes several normalised ones. Thinking blocks
+    and everything unrecognised are dropped here rather than in the formatter:
+    what is worth reading is a property of the stream, not of the projection.
+    """
+    kind = event.get("type")
+    if kind == "assistant":
+        return tuple(
+            item
+            for block in _content_blocks(event)
+            if (item := _assistant_event(block)) is not None
+        )
+    if kind == "user":
+        return tuple(
+            _tool_result(block)
+            for block in _content_blocks(event)
+            if block.get("type") == "tool_result"
+        )
+    if kind == "system" and event.get("subtype") == "permission_denied":
+        return (
+            Denial(
+                tool=str(event.get("tool_name", "?")),
+                reason=str(event.get("decision_reason", "")).strip(),
+            ),
+        )
+    if kind == "result" and isinstance(event.get("result"), str):
+        return (Result(text=str(event["result"])),)
+    return ()
+
+
+def format_live(event: StreamEvent) -> list[str]:
+    return _rows(event, limit=_MAX_SUMMARY, include_body=False)
+
+
+def format_log(event: StreamEvent) -> list[str]:
+    """What the archive keeps: everything the screen shows, plus the bodies.
+
+    The log is no longer a live window — the worker pane is. It is read after
+    the fact, by a person reconstructing why a worker failed and by
+    ``okstra log-report``.
+    """
+    return _rows(event, limit=None, include_body=True)
+
+
+def final_text(event: StreamEvent) -> str | None:
+    """The worker's closing message, or None for any other event."""
+    return event.text if isinstance(event, Result) else None
+
+
+def _rows(event: StreamEvent, *, limit: int | None, include_body: bool) -> list[str]:
+    if isinstance(event, Text):
+        return _body_rows(event.body)
+    if isinstance(event, ToolCall):
+        head = f"→ {event.name}: {event.detail}" if event.detail else f"→ {event.name}"
+        return [_truncate(head, limit)]
+    if isinstance(event, ToolResult):
+        rows = [f"  ← {_outcome(event.failed)} ({event.size_bytes} bytes)"]
+        if include_body:
+            rows.extend(_body_rows(event.body))
+        return rows
+    if isinstance(event, Denial):
+        return [_truncate(f"!! PERMISSION DENIED — {event.tool}: {event.reason}", limit)]
+    # A Result is printed by the runner at the point the run ends, not woven
+    # into the progress it interrupts.
+    return []
+
+
+def _outcome(failed: bool | None) -> str:
+    if failed is None:
+        return "done"
+    return "error" if failed else "ok"
+
+
+def _body_rows(text: str) -> list[str]:
+    """One screen row per line, with every blank row dropped.
+
+    Blank rows are dropped wherever they sit, not only at the end: a tool that
+    double-spaces its output would otherwise take twice the pane height it
+    earns, and a body that ends in newlines would pad the archive.
+    """
+    return [part for part in text.splitlines() if part.strip()]
+
+
+def _assistant_event(block: Mapping[str, Any]) -> StreamEvent | None:
+    if block.get("type") == "text":
+        return Text(body=str(block.get("text", "")))
+    if block.get("type") == "tool_use":
+        return ToolCall(
+            name=str(block.get("name", "tool")), detail=_tool_detail(block.get("input"))
+        )
+    return None
+
+
+def _tool_detail(payload: Any) -> str:
+    if not isinstance(payload, Mapping):
+        return ""
+    for key in ("command", "file_path", "path", "pattern", "query"):
+        value = payload.get(key)
+        if value:
+            return str(value)
+    return ""
+
+
+def _tool_result(block: Mapping[str, Any]) -> ToolResult:
+    body = block.get("content")
+    return ToolResult(
+        body=_body_text(body),
+        size_bytes=_body_size(body),
+        failed=bool(block.get("is_error")),
+    )
+
+
+def _body_text(body: Any) -> str:
+    """The tool's own output as one string, whatever shape it arrived in."""
+    if isinstance(body, str):
+        return body
+    if isinstance(body, list):
+        return "\n".join(
+            str(block.get("text", "")) for block in body if isinstance(block, Mapping)
+        )
+    return ""
+
+
+def _body_size(body: Any) -> int:
+    """How much a tool returned, in bytes.
+
+    The content arrives either as a plain string or as a list of content
+    blocks. Counting only the string form reports a five-figure result as
+    zero — a confident wrong number, which is worse on a screen than no
+    number. Bytes rather than characters because the figure exists to be
+    compared against the log this run leaves on disk.
+    """
+    if isinstance(body, str):
+        return len(body.encode("utf-8"))
+    if isinstance(body, list):
+        return sum(
+            len(str(block.get("text", "")).encode("utf-8"))
+            for block in body
+            if isinstance(block, Mapping)
+        )
+    return 0
+
+
+def _content_blocks(event: Mapping[str, Any]) -> list[Mapping[str, Any]]:
+    message = event.get("message")
+    if not isinstance(message, Mapping):
+        return []
+    content = message.get("content")
+    if not isinstance(content, list):
+        return []
+    return [block for block in content if isinstance(block, Mapping)]
+
+
+def _truncate(line: str, limit: int | None) -> str:
+    if limit is None or len(line) <= limit:
+        return line
+    return line[: limit - 1] + "…"

package/runtime/python/okstra_ctl/incremental_scope.py

@@ -293,20 +293,32 @@ def decide_scope(
     if not prev_base_sha or prev_base_sha != cur_base_sha:
         return IncrementalDecision(
             "full", [], [],
-            f"base-ref changed ({prev_base_sha!r} -> {cur_base_sha!r}); prior analysis invalid",
+            "the branch this plan was written against has moved on "
+            f"({prev_base_sha or 'unrecorded'} -> {cur_base_sha or 'unrecorded'}), "
+            "so none of the prior stages can be reused as they stand",
         )
     if not impacted_stages:
-        return IncrementalDecision("full", [], [], "no impacted stages resolved; falling back to full")
+        return IncrementalDecision(
+            "full", [], [],
+            "no stage of the prior plan could be tied to the answers, so there is "
+            "nothing to narrow the rework down to",
+        )
     all_stages = {num for num, _ in stages}
     closure = downstream_stage_closure(stages, set(impacted_stages))
     if len(closure) * 2 > len(all_stages):
         return IncrementalDecision(
             "full", [], [],
-            f"closure {len(closure)}/{len(all_stages)} exceeds {int(cutoff_ratio * 100)}% cutoff",
+            f"the answers reach {len(closure)} of the plan's {len(all_stages)} stages — "
+            f"past the {int(cutoff_ratio * 100)}% mark where replanning outright costs "
+            "less than tracking what carried over",
         )
     reverify = sorted(closure)
     carry = sorted(all_stages - closure)
-    return IncrementalDecision("incremental", reverify, carry, f"closure {reverify} within cutoff")
+    return IncrementalDecision(
+        "incremental", reverify, carry,
+        f"the answers reach {len(reverify)} of the plan's {len(all_stages)} stages; "
+        "the rest is reused as written",
+    )
 
 
 def _preview_result(args) -> dict: