okstra 0.163.2 → 0.164.0

package/runtime/python/okstra_ctl/adapters/hosts/claude-code/adapter.py

@@ -0,0 +1,120 @@
+"""Bundled Claude Code host strategy."""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+from collections.abc import Callable
+from pathlib import Path
+
+from okstra_ctl.adapters.accounting import ClaudeJsonlUsageAccountingPort
+from okstra_ctl.adapters.hosts.capability_adapter import (
+    INTERACTION_FUNCTIONS,
+    PENDING_HOST_PORT,
+    CapabilityHostAdapter,
+    numbered_interaction_port,
+)
+from okstra_ctl.domain.host import HostClaim, HostDescriptor, HostResolutionContext
+from okstra_ctl.registry.provider_registry import ProviderRegistry
+
+
+DESCRIPTOR = HostDescriptor(
+    id="claude-code",
+    aliases=("claude",),
+    native_provider_id="claude",
+    required_executables=("claude",),
+    launch_mode="lead",
+    install_targets=frozenset({"agents", "claude"}),
+    agent_id="claude",
+    agent_label="Claude Code",
+    role="Claude lead",
+    dispatch_mode="team",
+    session_accounting="claude-jsonl",
+    has_claude_session=True,
+    relay_contract=str(Path(__file__).with_name("relay.md").resolve()),
+)
+
+
+def _detect_claude_skill_handoff(
+    context: HostResolutionContext,
+) -> HostClaim | None:
+    if "claude-skill-handoff" not in context.signals:
+        return None
+    return HostClaim(
+        DESCRIPTOR.id,
+        100,
+        "Claude Code skill handoff selected runtime 'claude-code'.",
+    )
+
+
+def _workspace_trust_checks(context) -> tuple[dict[str, object], ...]:
+    project_root = Path(
+        os.path.abspath(
+            os.environ.get("OKSTRA_PROBE_PROJECT_ROOT", str(Path.cwd()))
+        )
+    )
+    home_dir = Path(os.environ.get("OKSTRA_PROBE_HOME_DIR", str(Path.home())))
+    if not (project_root / ".claude" / "settings.local.json").exists():
+        return ({"id": "workspace-trust", "status": "not-applicable"},)
+    try:
+        state = json.loads((home_dir / ".claude.json").read_text(encoding="utf-8"))
+        projects = state.get("projects") if isinstance(state, dict) else None
+        if not isinstance(projects, dict):
+            return _workspace_trust_unavailable()
+        project_key = str(project_root)
+        if project_key not in projects:
+            return _workspace_trust_required()
+        project_state = projects[project_key]
+        if not isinstance(project_state, dict):
+            return _workspace_trust_unavailable()
+        accepted = project_state.get("hasTrustDialogAccepted")
+        if accepted is True:
+            return ({"id": "workspace-trust", "status": "accepted"},)
+        if accepted is False or accepted is None:
+            return _workspace_trust_required()
+        return _workspace_trust_unavailable()
+    except (OSError, json.JSONDecodeError):
+        return _workspace_trust_unavailable()
+
+
+def _workspace_trust_required() -> tuple[dict[str, object], ...]:
+    return ({
+        "id": "workspace-trust",
+        "status": "required",
+        "action": "restart-and-trust",
+    },)
+
+
+def _workspace_trust_unavailable() -> tuple[dict[str, object], ...]:
+    return ({
+        "id": "workspace-trust",
+        "status": "unavailable",
+        "action": "open-project-and-trust",
+    },)
+
+
+def create_adapter(
+    *,
+    executable_finder: Callable[[str], str | None] = shutil.which,
+    interaction_port=None,
+    lead_session_port=PENDING_HOST_PORT,
+    worker_dispatch_port=PENDING_HOST_PORT,
+    usage_accounting_port=ClaudeJsonlUsageAccountingPort(),
+    provider_registry: ProviderRegistry | None = None,
+) -> CapabilityHostAdapter:
+    return CapabilityHostAdapter(
+        DESCRIPTOR,
+        executable_finder=executable_finder,
+        interaction_port=(
+            interaction_port
+            if interaction_port is not None
+            else numbered_interaction_port()
+        ),
+        lead_session_port=lead_session_port,
+        worker_dispatch_port=worker_dispatch_port,
+        usage_accounting_port=usage_accounting_port,
+        supported_functions=INTERACTION_FUNCTIONS,
+        detector=_detect_claude_skill_handoff,
+        provider_registry=provider_registry,
+        readiness_probe=_workspace_trust_checks,
+    )

package/runtime/python/okstra_ctl/adapters/hosts/claude-code/manifest.json

@@ -0,0 +1 @@
+{"schemaVersion": 1, "id": "claude-code", "factory": "adapter.py:create_adapter", "nativeProviderId": "claude", "requiredExecutables": ["claude"], "relayContract": "relay.md"}

package/runtime/{prompts/lead/adapters/claude-code.md → python/okstra_ctl/adapters/hosts/claude-code/relay.md}

@@ -18,6 +18,117 @@ This adapter maps the neutral Okstra lead operations to Claude Code host primiti
 | `teardownMode` | `teammate-shutdown` |
 | `leadEventSource` | `claude-jsonl+artifact` |
 
+## Wizard interaction relay
+
+Read this contract when `okstra preflight` returns this file as `runtimeReadiness.relayContract`. The JSON is the complete interaction mapping for this host. `semanticFunctions` is an allowlist: the skill may declare a function only when both this list and the live harness expose it.
+
+```json
+{
+  "schemaVersion": 1,
+  "runtime": "claude-code",
+  "semanticFunctions": [
+    "plain_text_input",
+    "native_single_select",
+    "native_multi_select",
+    "native_question_group"
+  ],
+  "interactions": {
+    "native-single": {
+      "function": "AskUserQuestion",
+      "input": {
+        "callCount": 1,
+        "questions": "one",
+        "question": "label-with-progress",
+        "header": "Q1",
+        "options": "all-in-original-order-as-label-description",
+        "multiSelect": false
+      },
+      "response": {
+        "envelope": "answers",
+        "key": "rendered-question-text",
+        "selection": "selected-label",
+        "submit": "matching-option-value"
+      }
+    },
+    "native-multi": {
+      "function": "AskUserQuestion",
+      "input": {
+        "callCount": 1,
+        "questions": "one",
+        "question": "label-with-progress",
+        "header": "Q1",
+        "options": "all-in-original-order-as-label-description",
+        "multiSelect": true
+      },
+      "response": {
+        "envelope": "answers",
+        "key": "rendered-question-text",
+        "selection": "selected-labels-joined-comma-space",
+        "submit": "csv-matching-option-values-in-option-order"
+      }
+    },
+    "native-group": {
+      "function": "AskUserQuestion",
+      "input": {
+        "callCount": 1,
+        "questions": "all-in-original-order",
+        "question": "label-with-progress",
+        "header": "Q<one-based-question-position>",
+        "options": "all-in-original-order-as-label-description",
+        "multiSelect": "questions[].multi"
+      },
+      "response": {
+        "envelope": "answers",
+        "key": "rendered-question-text",
+        "selection": "selected-label-or-labels-joined-comma-space",
+        "multiValue": "csv-matching-option-values-in-option-order",
+        "submit": "compact-step-json-values"
+      }
+    },
+    "numbered-single": {
+      "function": "host-text",
+      "input": {
+        "questions": "one",
+        "question": "label-with-progress",
+        "options": "all-in-original-order-as-numbered-markdown-label-and-description"
+      },
+      "response": { "source": "next-message", "submit": "raw" }
+    },
+    "numbered-multi": {
+      "function": "host-text",
+      "input": {
+        "questions": "one",
+        "question": "label-with-progress",
+        "options": "all-in-original-order-as-numbered-markdown-label-and-description"
+      },
+      "response": { "source": "next-message", "submit": "raw" }
+    },
+    "sequential-group": {
+      "function": "host-text",
+      "input": {
+        "questions": "all-one-at-a-time-in-original-order",
+        "question": "label-with-progress",
+        "options": "all-in-original-order-as-numbered-markdown-label-and-description"
+      },
+      "response": {
+        "source": "next-message-by-question-position",
+        "submit": "compact-step-json-raw"
+      }
+    },
+    "plain-text": {
+      "function": "host-text",
+      "input": { "questions": "one", "question": "label-with-progress" },
+      "response": { "source": "next-message", "submit": "raw" }
+    }
+  }
+}
+```
+
+For `AskUserQuestion`, map each wizard option to the tool's `{label, description}` input without removing, shortening, or reordering entries. Look up each answer by the exact rendered `question` string sent to the tool, including the progress suffix; the `answers` keys are question text, not positions or headers. A single-select answer is the selected label. A multi-select answer is one string whose selected labels are joined with `, `. Match those labels back to the complete original option list, emit their `value` fields in original option order, and join the values with `,` for the wizard. Native plans are emitted only for one to four questions whose option labels are unique and whose complete option lists each contain two to four entries; other prompts use the text mapping so no option is dropped. For a group, key the compact JSON object by the corresponding `questions[].step`; a multi-select question stores its ordered value CSV as one string, not a JSON array. Never use the display header as an answer key. The `Q1`…`Q4` headers only satisfy the host tool's short-header input and carry no domain meaning.
+
+For a `host-text` mapping, render each numbered item as its option label followed by its description verbatim; preserve every item and its order. The next user message is the raw answer. Do not translate numbers, CSV members, labels, or values before `okstra wizard step`. A sequential group wraps each raw reply in one compact JSON object keyed by `questions[].step`; the wizard owns normalization.
+
+
 ## Semantic operation mapping
 
 | Operation | Mapping |

package/runtime/python/okstra_ctl/adapters/hosts/codex/adapter.py

@@ -0,0 +1,60 @@
+"""Bundled Codex host strategy."""
+from __future__ import annotations
+
+import shutil
+from collections.abc import Callable
+from pathlib import Path
+
+from okstra_ctl.adapters.accounting import CliArtifactUsageAccountingPort
+from okstra_ctl.adapters.hosts.capability_adapter import (
+    INTERACTION_FUNCTIONS,
+    PENDING_HOST_PORT,
+    CapabilityHostAdapter,
+    no_automatic_claim,
+    numbered_interaction_port,
+)
+from okstra_ctl.domain.host import HostDescriptor
+from okstra_ctl.registry.provider_registry import ProviderRegistry
+
+
+DESCRIPTOR = HostDescriptor(
+    id="codex",
+    aliases=("codex",),
+    native_provider_id="codex",
+    required_executables=("codex",),
+    launch_mode="lead",
+    install_targets=frozenset({"agents"}),
+    agent_id="codex",
+    agent_label="Codex CLI",
+    role="Codex lead",
+    dispatch_mode="render-only",
+    session_accounting="artifact-only",
+    has_claude_session=False,
+    relay_contract=str(Path(__file__).with_name("relay.md").resolve()),
+)
+
+
+def create_adapter(
+    *,
+    executable_finder: Callable[[str], str | None] = shutil.which,
+    interaction_port=None,
+    lead_session_port=PENDING_HOST_PORT,
+    worker_dispatch_port=PENDING_HOST_PORT,
+    usage_accounting_port=CliArtifactUsageAccountingPort(),
+    provider_registry: ProviderRegistry | None = None,
+) -> CapabilityHostAdapter:
+    return CapabilityHostAdapter(
+        DESCRIPTOR,
+        executable_finder=executable_finder,
+        interaction_port=(
+            interaction_port
+            if interaction_port is not None
+            else numbered_interaction_port()
+        ),
+        lead_session_port=lead_session_port,
+        worker_dispatch_port=worker_dispatch_port,
+        usage_accounting_port=usage_accounting_port,
+        supported_functions=INTERACTION_FUNCTIONS,
+        detector=no_automatic_claim,
+        provider_registry=provider_registry,
+    )

package/runtime/python/okstra_ctl/adapters/hosts/codex/manifest.json

@@ -0,0 +1 @@
+{"schemaVersion": 1, "id": "codex", "factory": "adapter.py:create_adapter", "nativeProviderId": "codex", "requiredExecutables": ["codex"], "relayContract": "relay.md"}

package/runtime/{prompts/lead/adapters/codex.md → python/okstra_ctl/adapters/hosts/codex/relay.md}

@@ -18,6 +18,58 @@ This adapter maps the neutral Okstra lead operations to the Codex artifact-first
 | `teardownMode` | `process-cleanup` |
 | `leadEventSource` | `lead-events-jsonl` |
 
+## Wizard interaction relay
+
+Read this contract when `okstra preflight` returns this file as `runtimeReadiness.relayContract`. The JSON is the complete interaction mapping for this host. This relay exposes only text input; do not invent a native picker function.
+
+```json
+{
+  "schemaVersion": 1,
+  "runtime": "codex",
+  "semanticFunctions": ["plain_text_input"],
+  "interactions": {
+    "numbered-single": {
+      "function": "host-text",
+      "input": {
+        "questions": "one",
+        "question": "label-with-progress",
+        "options": "all-in-original-order-as-numbered-markdown-label-and-description"
+      },
+      "response": { "source": "next-message", "submit": "raw" }
+    },
+    "numbered-multi": {
+      "function": "host-text",
+      "input": {
+        "questions": "one",
+        "question": "label-with-progress",
+        "options": "all-in-original-order-as-numbered-markdown-label-and-description"
+      },
+      "response": { "source": "next-message", "submit": "raw" }
+    },
+    "sequential-group": {
+      "function": "host-text",
+      "input": {
+        "questions": "all-one-at-a-time-in-original-order",
+        "question": "label-with-progress",
+        "options": "all-in-original-order-as-numbered-markdown-label-and-description"
+      },
+      "response": {
+        "source": "next-message-by-question-position",
+        "submit": "compact-step-json-raw"
+      }
+    },
+    "plain-text": {
+      "function": "host-text",
+      "input": { "questions": "one", "question": "label-with-progress" },
+      "response": { "source": "next-message", "submit": "raw" }
+    }
+  }
+}
+```
+
+Render every numbered item as its option label followed by its description verbatim, preserving every item and its original order. The next user message is the raw answer: do not translate a number such as `1`, a CSV reply such as `1, 3`, an option label, or an option value before `okstra wizard step`. For `sequential-group`, collect one raw reply per question in order and build one compact JSON object keyed by the corresponding `questions[].step`; the wizard owns all normalization.
+
+
 ## Semantic operation mapping
 
 | Operation | Mapping |

package/runtime/python/okstra_ctl/adapters/hosts/external/adapter.py

@@ -0,0 +1,72 @@
+"""Bundled external host strategy."""
+from __future__ import annotations
+
+import shutil
+from collections.abc import Callable
+from pathlib import Path
+
+from okstra_ctl.adapters.accounting import UnavailableUsageAccountingPort
+from okstra_ctl.adapters.hosts.capability_adapter import (
+    INTERACTION_FUNCTIONS,
+    PENDING_HOST_PORT,
+    CapabilityHostAdapter,
+    numbered_interaction_port,
+)
+from okstra_ctl.domain.host import HostClaim, HostDescriptor, HostResolutionContext
+from okstra_ctl.registry.provider_registry import ProviderRegistry
+
+
+DESCRIPTOR = HostDescriptor(
+    id="external",
+    aliases=("external",),
+    native_provider_id="",
+    required_executables=(),
+    launch_mode="team",
+    install_targets=frozenset({"agents"}),
+    agent_id="external",
+    agent_label="External harness",
+    role="Okstra lead",
+    dispatch_mode="render-only",
+    session_accounting="artifact-only",
+    has_claude_session=False,
+    relay_contract=str(Path(__file__).with_name("relay.md").resolve()),
+)
+
+
+def _detect_tmux(context: HostResolutionContext) -> HostClaim | None:
+    if "tmux" not in context.signals:
+        return None
+    return HostClaim(
+        DESCRIPTOR.id,
+        10,
+        "No Claude Code host signal; tmux is available.",
+    )
+
+
+def create_adapter(
+    *,
+    executable_finder: Callable[[str], str | None] = shutil.which,
+    interaction_port=None,
+    lead_session_port=PENDING_HOST_PORT,
+    worker_dispatch_port=PENDING_HOST_PORT,
+    usage_accounting_port=UnavailableUsageAccountingPort(
+        "External host usage accounting is unavailable because no session "
+        "transcript or CLI usage artifact contract is registered."
+    ),
+    provider_registry: ProviderRegistry | None = None,
+) -> CapabilityHostAdapter:
+    return CapabilityHostAdapter(
+        DESCRIPTOR,
+        executable_finder=executable_finder,
+        interaction_port=(
+            interaction_port
+            if interaction_port is not None
+            else numbered_interaction_port()
+        ),
+        lead_session_port=lead_session_port,
+        worker_dispatch_port=worker_dispatch_port,
+        usage_accounting_port=usage_accounting_port,
+        supported_functions=INTERACTION_FUNCTIONS,
+        detector=_detect_tmux,
+        provider_registry=provider_registry,
+    )

package/runtime/python/okstra_ctl/adapters/hosts/external/manifest.json

@@ -0,0 +1 @@
+{"schemaVersion": 1, "id": "external", "factory": "adapter.py:create_adapter", "nativeProviderId": "", "requiredExecutables": [], "relayContract": "relay.md"}

package/runtime/{prompts/lead/adapters/external.md → python/okstra_ctl/adapters/hosts/external/relay.md}

@@ -18,6 +18,58 @@ This adapter maps the neutral Okstra lead operations to a generic host using Oks
 | `teardownMode` | `pane-teardown` |
 | `leadEventSource` | `lead-events-jsonl` |
 
+## Wizard interaction relay
+
+Read this contract when `okstra preflight` returns this file as `runtimeReadiness.relayContract`. The JSON is the complete interaction mapping for this host. This relay exposes only text input; do not invent a native picker function.
+
+```json
+{
+  "schemaVersion": 1,
+  "runtime": "external",
+  "semanticFunctions": ["plain_text_input"],
+  "interactions": {
+    "numbered-single": {
+      "function": "host-text",
+      "input": {
+        "questions": "one",
+        "question": "label-with-progress",
+        "options": "all-in-original-order-as-numbered-markdown-label-and-description"
+      },
+      "response": { "source": "next-message", "submit": "raw" }
+    },
+    "numbered-multi": {
+      "function": "host-text",
+      "input": {
+        "questions": "one",
+        "question": "label-with-progress",
+        "options": "all-in-original-order-as-numbered-markdown-label-and-description"
+      },
+      "response": { "source": "next-message", "submit": "raw" }
+    },
+    "sequential-group": {
+      "function": "host-text",
+      "input": {
+        "questions": "all-one-at-a-time-in-original-order",
+        "question": "label-with-progress",
+        "options": "all-in-original-order-as-numbered-markdown-label-and-description"
+      },
+      "response": {
+        "source": "next-message-by-question-position",
+        "submit": "compact-step-json-raw"
+      }
+    },
+    "plain-text": {
+      "function": "host-text",
+      "input": { "questions": "one", "question": "label-with-progress" },
+      "response": { "source": "next-message", "submit": "raw" }
+    }
+  }
+}
+```
+
+Render every numbered item as its option label followed by its description verbatim, preserving every item and its original order. The next user message is the raw answer: do not translate a number such as `1`, a CSV reply such as `1, 3`, an option label, or an option value before `okstra wizard step`. For `sequential-group`, collect one raw reply per question in order and build one compact JSON object keyed by the corresponding `questions[].step`; the wizard owns all normalization.
+
+
 ## Semantic operation mapping
 
 | Operation | Mapping |

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

@@ -0,0 +1,63 @@
+"""Bundled Grok host strategy."""
+from __future__ import annotations
+
+import shutil
+from collections.abc import Callable
+from pathlib import Path
+
+from okstra_ctl.adapters.accounting import UnavailableUsageAccountingPort
+from okstra_ctl.adapters.hosts.capability_adapter import (
+    INTERACTION_FUNCTIONS,
+    PENDING_HOST_PORT,
+    CapabilityHostAdapter,
+    no_automatic_claim,
+    numbered_interaction_port,
+)
+from okstra_ctl.domain.host import HostDescriptor
+from okstra_ctl.registry.provider_registry import ProviderRegistry
+
+
+DESCRIPTOR = HostDescriptor(
+    id="grok",
+    aliases=("grok",),
+    native_provider_id="grok",
+    required_executables=("grok",),
+    launch_mode="lead",
+    install_targets=frozenset({"agents"}),
+    agent_id="grok",
+    agent_label="Grok CLI",
+    role="Grok lead",
+    dispatch_mode="render-only",
+    session_accounting="artifact-only",
+    has_claude_session=False,
+    relay_contract=str(Path(__file__).with_name("relay.md").resolve()),
+)
+
+
+def create_adapter(
+    *,
+    executable_finder: Callable[[str], str | None] = shutil.which,
+    interaction_port=None,
+    lead_session_port=PENDING_HOST_PORT,
+    worker_dispatch_port=PENDING_HOST_PORT,
+    usage_accounting_port=UnavailableUsageAccountingPort(
+        "Grok host usage accounting is unavailable because no session "
+        "transcript or CLI usage artifact contract is registered."
+    ),
+    provider_registry: ProviderRegistry | None = None,
+) -> CapabilityHostAdapter:
+    return CapabilityHostAdapter(
+        DESCRIPTOR,
+        executable_finder=executable_finder,
+        interaction_port=(
+            interaction_port
+            if interaction_port is not None
+            else numbered_interaction_port()
+        ),
+        lead_session_port=lead_session_port,
+        worker_dispatch_port=worker_dispatch_port,
+        usage_accounting_port=usage_accounting_port,
+        supported_functions=INTERACTION_FUNCTIONS,
+        detector=no_automatic_claim,
+        provider_registry=provider_registry,
+    )

package/runtime/python/okstra_ctl/adapters/hosts/grok/manifest.json

@@ -0,0 +1 @@
+{"schemaVersion": 1, "id": "grok", "factory": "adapter.py:create_adapter", "nativeProviderId": "grok", "requiredExecutables": ["grok"], "relayContract": "relay.md"}

package/runtime/python/okstra_ctl/adapters/hosts/grok/relay.md

@@ -0,0 +1,90 @@
+# Grok Lead Runtime Adapter
+
+## Scope
+
+This adapter maps neutral Okstra lead operations to the Grok CLI. Read it only when the rendered launch prompt selects `leadRuntime=grok`.
+
+## Capability declaration
+
+| Field | Value |
+|---|---|
+| `runtime` | `grok` |
+| `leadRoleLabel` | `Grok lead` |
+| `userPromptMode` | `host-text` |
+| `workerDispatchBackend` | `mixed` |
+| `initialPromptDeliveryMode` | `eager-include` |
+| `sessionAccounting` | `artifact-only` |
+| `resumeMode` | `native-session-id` |
+| `teardownMode` | `process-cleanup` |
+| `leadEventSource` | `lead-events-jsonl` |
+
+## Wizard interaction relay
+
+Read this contract when `okstra preflight` returns this file as `runtimeReadiness.relayContract`. The JSON is the complete interaction mapping for this host. This relay exposes only text input; do not invent a native picker function.
+
+```json
+{
+  "schemaVersion": 1,
+  "runtime": "grok",
+  "semanticFunctions": ["plain_text_input"],
+  "interactions": {
+    "numbered-single": {
+      "function": "host-text",
+      "input": {
+        "questions": "one",
+        "question": "label-with-progress",
+        "options": "all-in-original-order-as-numbered-markdown-label-and-description"
+      },
+      "response": { "source": "next-message", "submit": "raw" }
+    },
+    "numbered-multi": {
+      "function": "host-text",
+      "input": {
+        "questions": "one",
+        "question": "label-with-progress",
+        "options": "all-in-original-order-as-numbered-markdown-label-and-description"
+      },
+      "response": { "source": "next-message", "submit": "raw" }
+    },
+    "sequential-group": {
+      "function": "host-text",
+      "input": {
+        "questions": "all-one-at-a-time-in-original-order",
+        "question": "label-with-progress",
+        "options": "all-in-original-order-as-numbered-markdown-label-and-description"
+      },
+      "response": {
+        "source": "next-message-by-question-position",
+        "submit": "compact-step-json-raw"
+      }
+    },
+    "plain-text": {
+      "function": "host-text",
+      "input": { "questions": "one", "question": "label-with-progress" },
+      "response": { "source": "next-message", "submit": "raw" }
+    }
+  }
+}
+```
+
+Render every numbered item as its option label followed by its description verbatim, preserving every item and its original order. Submit the next user message unchanged. For `sequential-group`, collect one raw reply per question in order and build one compact JSON object keyed by the corresponding `questions[].step`.
+
+## Semantic operation mapping
+
+| Operation | Mapping |
+|---|---|
+| `read_artifacts` | Read the manifest-provided paths through the current Grok host file interface. |
+| `write_artifact` | Write only core-authorized `.okstra/` artifacts and preserve their schemas. |
+| `prompt_user` | Ask through the current host text interface and wait for an explicit answer. |
+| `dispatch_worker` | Follow each persisted assignment's `runner` and use the common host dispatch boundary. |
+| `await_workers` | Await through the selected common dispatch backend, then verify terminal state and Result Paths. |
+| `redispatch_worker` | Start a fresh attempt from the persisted assignment and record the supplied dispatch kind. |
+| `shutdown_workers` | Clean up only host or process resources owned by this run. |
+| `record_lead_event` | Append the required structured event to `leadEventsPath` and emit the matching progress line. |
+| `collect_usage` | Return explicit unavailable lead usage until Grok registers a session transcript or CLI usage artifact contract. |
+
+## Completion, cleanup, and resume
+
+- Do not infer the current host from an installed `grok` executable. The runtime must come from an explicit request or current-session declaration.
+- Keep persisted provider, model, runner, and dispatch-kind assignments unchanged.
+- Resume with the persisted Grok session ID when one exists; otherwise resume from Okstra run artifacts.