okstra 0.169.0 → 0.169.1

package/docs/cli.md

@@ -774,7 +774,7 @@ The `okstra` Node CLI (`bin/okstra`) provides both installer/admin commands and
 | `okstra codex-run <args…>` | Codex lead-adapter dry-run entry point. Accepts the same arguments as `render-bundle` but owns `--render-only --lead-runtime codex`. It prepares the task bundle and prints the prompt for the Codex lead without dispatching workers |
 | `okstra worker-dispatch --project-root <dir> --run-manifest <path> [--workers <csv>] [--dry-run]` | Provider-neutral deterministic dispatcher for `runner=cli-wrapper` assignments. It verifies each adjacent invocation specification against the immutable run manifest immediately before process creation and records `core-pre-dispatch`; native-session rows stay with the host. The default selects CLI analysis assignments only. Phase 6 uses explicit `--workers report-writer`, and a mixed analysis/report batch is rejected. `--dry-run` performs the same verification and resolution without starting a provider process. |
 | `okstra codex-dispatch --project-root <dir> --run-manifest <path> [--workers <csv>] [--dry-run]` | Compatibility alias for `okstra worker-dispatch`; it no longer selects a Codex-only transport-agent path. |
-| `okstra agent-prompt materialize\|verify\|record-dispatch\|link-result\|materialize-result\|complete\|verify-completion` | Internal invocation-contract CLI. `materialize` composes model assignment, functional duty, and task instructions; `verify` rejects identity, path, snapshot, assignment, source, or digest drift. Run-backed calls resolve `assignmentRef` from the manifest, enforce `authorizedPaths`, and reject real-path or symbolic-link escape. `record-dispatch` records a verified host-native specification before dispatch and `link-result` binds the accepted result. Standalone calls are identified by `(purpose, invocationId)` under `.okstra/agent-invocations/<purpose>/`; they publish a canonical result envelope and publish the completion marker last. Consumers use only the `returnedBody` from `verify-completion`. Metadata contains exactly `catalogDigest`, `assignmentDigest`, `dutyDigest`, `instructionDigest`, and `promptDigest`; JSON inputs use UTF-8, sorted keys, compact separators, and no non-finite values, while duty files use versioned sorted-name/byte framing. Instruction sources use `{kind: project\|runtime, path: <relative POSIX path>}` and never persist an installed absolute runtime path. |
+| `okstra agent-prompt materialize\|verify\|record-dispatch\|link-result\|materialize-result\|complete\|verify-completion` | Internal invocation-contract CLI. `materialize` composes model assignment, functional duty, and task instructions; `verify` rejects identity, path, snapshot, assignment, source, or digest drift. Run-backed calls resolve `assignmentRef` from the manifest, enforce `authorizedPaths`, and reject real-path or symbolic-link escape. `record-dispatch` records a verified host-native specification before dispatch and `link-result` binds the accepted result. Standalone calls are identified by `(purpose, invocationId)` under `.okstra/agent-invocations/<purpose>/`; they publish a canonical result envelope and publish the completion marker last. Consumers use only the `returnedBody` from `verify-completion`. Metadata contains exactly `catalogDigest`, `assignmentDigest`, `dutyDigest`, `instructionDigest`, and `promptDigest`; JSON inputs use UTF-8, sorted keys, compact separators, and no non-finite values, while duty files use versioned sorted-name/byte framing. Instruction sources use `{kind: project\|runtime, path: <relative POSIX path>}` and never persist an installed absolute runtime path. A published prompt is immutable, so re-running `materialize` with an edited instruction file fails as `existing_invocation_conflict`; `--replace-undispatched` is the one exit, for a prompt that failed a pre-dispatch gate and therefore ran nowhere. It republishes prompt and metadata together, and it is verified rather than trusted — a row in `agentDispatches` or `workerDispatches` naming this `invocationId` refuses the replacement and names the dispatch that used it. |
 | `okstra team dispatch --project-root <dir> --run-manifest <path> [--workers <csv>] [--jobs-file <path>] [--dry-run]` / `okstra team await --project-root <dir> --run-manifest <path> [--json]` / `okstra team teardown --project-root <dir> --run-manifest <path> [--dry-run] [--json]` | Read a `leadRuntime=external` run manifest and dispatch, await, or tear down tmux-pane workers. Default dispatch excludes report writer; Phase 6 selects it explicitly, and mixed analysis/report jobs are rejected. If a tmux pane cannot be created, gracefully degrade to the CLI wrapper and record the fallback in `workerDispatches[].degradedFrom` |
 | `okstra report-finalize --project-root <dir> --run-manifest <path> --report <final-report.md>` | Run the whole Phase 7 post-report sequence in its contractual order: `token-usage` → `render-views` → `spawn-followups` → `validate-run`. Stops at the first non-zero exit and names the failing step, then prints a per-step `[ok]` / `[FAIL]` / `[skip]` summary on stderr so the outcome is legible without parsing the JSON payload. Every step is idempotent, so re-running after a fix is safe — but `--only <step>` (repeatable) reruns just the named steps in contractual order, which matters because `validate-run` is the step that usually fails and retrying it otherwise repeats the three steps before it at full token and wall-clock cost. This is the same code path (`scripts/okstra_ctl/report_finalize.py`) the Codex lead adapter runs automatically after its report-writer completes, so a Claude-led and a Codex-led run finalize identically. `--workspace-root` is owned by the Node wrapper. Prefer this over invoking the four steps individually |
 | `okstra render-views <final-report.data.json\|final-report.md>` | The Phase 7 `render-views` step, runnable on its own. Schema v2 data is rendered directly (contract: `schemas/final-report-v2.0.schema.json`) into an always-generated, task-specific human HTML sibling while `templates/reports/final-report-v2.template.md` independently owns the AI handoff Markdown. Passing the Markdown sibling locates the same v2 data.json. Schema v1 and quick reports keep the legacy conditional renderer. The Node wrapper calls `scripts/okstra-render-report-views.py`; `validators/validate-report-views.py` verifies source/schema/template digests, required human fields, form controls, external assets, diagram/table ID parity, and Response ID parity |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.169.0",
+  "version": "0.169.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.169.0",
-  "builtAt": "2026-08-13T13:31:24.833Z",
+  "package": "0.169.1",
+  "builtAt": "2026-08-13T15:45:32.359Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/bin/okstra-error-log.py

@@ -1,296 +1,52 @@
 #!/usr/bin/env python3
-"""OKSTRA error log helper.
+"""OKSTRA error log helper — CLI adapter.
 
-Single writer for runs/<task-type>/logs/errors-<task-type>-<seq>.jsonl.
+The writer itself lives in `okstra_ctl.error_log_write`, which the deterministic
+dispatcher also calls in-process. This file is the argparse surface over it and
+re-exports the writer's names so the contract tests keep reading one module.
 """
 from __future__ import annotations
 
 import argparse
-import datetime as dt
 import json
-import os
 from pathlib import Path
 
-STDERR_EXCERPT_MAX_BYTES = 2048
-TRUNCATION_SUFFIX = "...[truncated]"
-PIPE_BUF_BYTES = 4096
-
-ALLOWED_ERROR_TYPES = {"tool-failure", "cli-failure", "contract-violation"}
-ALLOWED_AGENTS = {
-    "claude-lead", "claude-worker", "codex-worker",
-    "antigravity-worker", "report-writer",
-}
-ALLOWED_AGENT_ROLES = {"lead", "worker", "report-writer"}
-SUPPORTED_SIDECAR_SCHEMA_VERSIONS = {1}
-
-ALLOWED_CAUSES = {
-    "sandbox-denied", "service-unavailable", "auth-failed", "unknown",
-}
-# A `sandbox-denied` claim is only admissible with both probes attached.
-CAUSE_EVIDENCE_FIELDS = ("targetProbe", "controlProbe")
-# Both probes share a record's PIPE_BUF_BYTES budget with stderrExcerpt, so
-# they cannot reuse the 2048 cap that assumes stderrExcerpt owns it alone.
-CAUSE_PROBE_MAX_BYTES = 256
-# Backstop vocabulary: scanned in `message` only — never in stderrExcerpt,
-# where a kernel's real "Operation not permitted" is legitimate content.
-# Deliberately excludes bare "blocked"/"blocks": everyday English that would
-# reject honest records like "test blocked on upstream dependency".
-_BLOCKING_CLAIM_TERMS = (
-    "sandbox", "not permitted", "permission denied", "eperm",
+from okstra_ctl.error_log_write import (
+    ALLOWED_AGENT_ROLES,
+    ALLOWED_AGENTS,
+    ALLOWED_CAUSES,
+    ALLOWED_ERROR_TYPES,
+    CAUSE_EVIDENCE_FIELDS,
+    CAUSE_PROBE_MAX_BYTES,
+    PIPE_BUF_BYTES,
+    STDERR_EXCERPT_MAX_BYTES,
+    SUPPORTED_SIDECAR_SCHEMA_VERSIONS,
+    TRUNCATION_SUFFIX,
+    append_jsonl_line,
+    append_observed,
+    dump_from_worker_sidecar,
+    normalize_cause_context,
+    truncate_stderr,
 )
-# The backstop targets *unclassified* blocking claims. A worker that declared
-# a specific cause has already done the honest work — `auth-failed` legitimately
-# reads "permission denied" (MySQL 1045).
-_UNCLASSIFIED_CAUSES = (None, "unknown")
-
-
-def _now_utc():
-    return dt.datetime.now(dt.timezone.utc)
-
-
-def _iso(t):
-    return t.isoformat()
-
-
-def _truncate_utf8(s, limit):
-    """Truncate to `limit` bytes without splitting a multibyte character."""
-    if s is None:
-        return None
-    encoded = s.encode("utf-8")
-    if len(encoded) <= limit:
-        return s
-    cut = encoded[:limit]
-    while cut:
-        try:
-            return cut.decode("utf-8") + TRUNCATION_SUFFIX
-        except UnicodeDecodeError:
-            cut = cut[:-1]
-    return TRUNCATION_SUFFIX
-
-
-def truncate_stderr(s):
-    """Truncate stderr text to STDERR_EXCERPT_MAX_BYTES, multibyte-safe."""
-    return _truncate_utf8(s, STDERR_EXCERPT_MAX_BYTES)
-
-
-def normalize_cause_context(context, *, message):
-    """Validate a record's cause claim and return the normalized context.
-
-    Raises ValueError on three conditions:
-    - `cause` is set to a value outside ALLOWED_CAUSES;
-    - `cause` is 'sandbox-denied' but the two probes are missing or blank —
-      those probes are what distinguish a real denial from an unreachable
-      or auth-gated target, the misdiagnosis this gate exists to stop;
-    - `message` asserts a block in prose while the record left its cause
-      unclassified, which would smuggle the same claim past the gate.
-    """
-    cause = context.get("cause") if isinstance(context, dict) else None
-
-    if cause is not None and cause not in ALLOWED_CAUSES:
-        raise ValueError(
-            f"invalid cause: {cause!r} (allowed: {sorted(ALLOWED_CAUSES)})"
-        )
-
-    if cause == "sandbox-denied":
-        evidence = context.get("causeEvidence")
-        if not isinstance(evidence, dict):
-            raise ValueError(
-                "cause 'sandbox-denied' requires context.causeEvidence with "
-                f"{list(CAUSE_EVIDENCE_FIELDS)}"
-            )
-        normalized_evidence = {}
-        for field in CAUSE_EVIDENCE_FIELDS:
-            value = evidence.get(field)
-            if not isinstance(value, str) or not value.strip():
-                raise ValueError(
-                    f"cause 'sandbox-denied' requires a non-empty "
-                    f"context.causeEvidence.{field}: record the command and "
-                    f"its raw output that proves the claim"
-                )
-            normalized_evidence[field] = _truncate_utf8(
-                value, CAUSE_PROBE_MAX_BYTES
-            )
-        return {**context, "causeEvidence": normalized_evidence}
 
-    if message and cause in _UNCLASSIFIED_CAUSES:
-        lowered = message.lower()
-        hit = next((t for t in _BLOCKING_CLAIM_TERMS if t in lowered), None)
-        if hit:
-            raise ValueError(
-                f"message asserts a blocking claim ({hit!r}) without "
-                "context.cause='sandbox-denied' + context.causeEvidence. "
-                "Either attach the two probes, or state the cause you "
-                "actually verified."
-            )
-
-    return context
-
-
-def append_jsonl_line(path, record):
-    """Append a single JSON record as one line to ``path``.
-
-    Atomicity guarantee (POSIX only):
-        With ``O_APPEND`` and a single ``write()`` syscall, the kernel
-        appends the entire payload as one indivisible operation as long as
-        the payload size is at most ``PIPE_BUF`` (4096 bytes on Linux and
-        macOS). Larger payloads may be split across syscalls and interleave
-        with concurrent writers, so this helper rejects them with
-        ``ValueError`` rather than silently losing atomicity.
-
-    The atomicity contract holds only on POSIX filesystems with O_APPEND
-    semantics. Concurrent writers using ``O_TRUNC``, ``unlink``, or
-    non-append modes against the same path break the contract and are
-    out of scope for this helper.
-
-    Caller responsibilities:
-    - Keep records small (this module's stderr excerpt cap of
-      ``STDERR_EXCERPT_MAX_BYTES`` exists to keep records well under
-      ``PIPE_BUF_BYTES``).
-    - Handle ``TypeError`` from ``json.dumps`` for non-serializable values.
-
-    Creates parent directories as needed.
-    """
-    p = Path(path)
-    p.parent.mkdir(parents=True, exist_ok=True)
-    # ensure_ascii=False keeps UTF-8 compact (no \uXXXX escapes).
-    # json.dumps escapes literal newlines inside string values, so the
-    # only unescaped newline is the record separator we append below.
-    line = json.dumps(record, ensure_ascii=False, separators=(",", ":")) + "\n"
-    data = line.encode("utf-8")
-    if len(data) > PIPE_BUF_BYTES:
-        raise ValueError(
-            f"record too large for atomic append: {len(data)} bytes > "
-            f"PIPE_BUF ({PIPE_BUF_BYTES})"
-        )
-    # mode 0o644: owner read/write, group/world read-only.
-    fd = os.open(str(p), os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o644)
-    try:
-        os.write(fd, data)
-    finally:
-        os.close(fd)
-
-
-def append_observed(
-    *,
-    out_path,
-    task_key,
-    phase,
-    agent,
-    agent_role,
-    model,
-    error_type,
-    command,
-    command_kind,
-    exit_code,
-    duration_ms,
-    message,
-    stderr_excerpt,
-    context,
-    now=None,
-):
-    """Append a lead-observed error event to errors.jsonl."""
-    if error_type not in ALLOWED_ERROR_TYPES:
-        raise ValueError(f"invalid errorType: {error_type!r}")
-    if agent not in ALLOWED_AGENTS:
-        raise ValueError(f"invalid agent: {agent!r}")
-    if agent_role not in ALLOWED_AGENT_ROLES:
-        raise ValueError(f"invalid agentRole: {agent_role!r}")
-    # Runs before append_jsonl_line so a rejected claim leaves no trace in the
-    # log: a written-then-flagged record is still a record someone can cite.
-    context = normalize_cause_context(context, message=message)
-    ts = _iso(now or _now_utc())
-    rec = {
-        "ts": ts,
-        "recordedAt": ts,
-        "taskKey": task_key,
-        "phase": str(phase),
-        "agent": agent,
-        "agentRole": agent_role,
-        "model": model,
-        "source": "lead-observed",
-        "errorType": error_type,
-        "command": command,
-        "commandKind": command_kind,
-        "exitCode": exit_code,
-        "durationMs": duration_ms,
-        "message": message,
-        "stderrExcerpt": truncate_stderr(stderr_excerpt),
-        "context": context,
-    }
-    append_jsonl_line(out_path, rec)
-    return rec
-
-
-def dump_from_worker_sidecar(
-    *,
-    sidecar_path,
-    out_path,
-    task_key,
-    agent,
-    agent_role,
-    model,
-    now=None,
-):
-    """Read worker sidecar errors[] and append each to errors.jsonl with
-    Lead-side metadata filled in. Returns number of records appended.
-
-    Raises ValueError if:
-      - ``agent`` or ``agent_role`` is not in the allow-lists
-      - sidecar ``schemaVersion`` is not in ``SUPPORTED_SIDECAR_SCHEMA_VERSIONS``
-      - any entry's ``errorType`` is not in ``ALLOWED_ERROR_TYPES``
-      - any entry asserts a blocking cause without its required evidence
-
-    Returns 0 (no-op) if the sidecar file does not exist or its
-    ``errors`` list is empty.
-
-    Partial-failure semantics: entries are validated and appended in
-    order. If entry N fails validation, entries 0..N-1 have already
-    been written to ``out_path`` and are NOT rolled back. Callers that
-    require atomicity must validate the sidecar payload before invoking
-    this function.
-    """
-    if agent not in ALLOWED_AGENTS:
-        raise ValueError(f"invalid agent: {agent!r}")
-    if agent_role not in ALLOWED_AGENT_ROLES:
-        raise ValueError(f"invalid agentRole: {agent_role!r}")
-    p = Path(sidecar_path)
-    if not p.exists():
-        return 0
-    payload = json.loads(p.read_text())
-    schema = payload.get("schemaVersion")
-    if schema not in SUPPORTED_SIDECAR_SCHEMA_VERSIONS:
-        raise ValueError(f"unsupported sidecar schemaVersion: {schema!r}")
-    entries = payload.get("errors") or []
-    recorded_at = _iso(now or _now_utc())
-    count = 0
-    for e in entries:
-        et = e.get("errorType")
-        if et not in ALLOWED_ERROR_TYPES:
-            raise ValueError(f"invalid errorType in sidecar: {et!r}")
-        entry_context = normalize_cause_context(
-            e.get("context"), message=e.get("message")
-        )
-        rec = {
-            "ts": e.get("ts"),
-            "recordedAt": recorded_at,
-            "taskKey": task_key,
-            "phase": str(e.get("phase")) if e.get("phase") is not None else None,
-            "agent": agent,
-            "agentRole": agent_role,
-            "model": model,
-            "source": "worker-reported",
-            "errorType": et,
-            "command": e.get("command"),
-            "commandKind": e.get("commandKind"),
-            "exitCode": e.get("exitCode"),
-            "durationMs": e.get("durationMs"),
-            "message": e.get("message"),
-            "stderrExcerpt": truncate_stderr(e.get("stderrExcerpt")),
-            "context": entry_context,
-        }
-        append_jsonl_line(out_path, rec)
-        count += 1
-    return count
+__all__ = [
+    "ALLOWED_AGENT_ROLES",
+    "ALLOWED_AGENTS",
+    "ALLOWED_CAUSES",
+    "ALLOWED_ERROR_TYPES",
+    "CAUSE_EVIDENCE_FIELDS",
+    "CAUSE_PROBE_MAX_BYTES",
+    "PIPE_BUF_BYTES",
+    "STDERR_EXCERPT_MAX_BYTES",
+    "SUPPORTED_SIDECAR_SCHEMA_VERSIONS",
+    "TRUNCATION_SUFFIX",
+    "append_jsonl_line",
+    "append_observed",
+    "dump_from_worker_sidecar",
+    "main",
+    "normalize_cause_context",
+    "truncate_stderr",
+]
 
 
 def _build_parser():

package/runtime/prompts/lead/convergence.md

@@ -235,6 +235,15 @@ prompt/result/audit paths. The returned `promptPath` is the only body that may
 be dispatched; do not append role prose or reconstruct model headers after
 materialization.
 
+If the dispatch gate then rejects that prompt, fix the task-instructions file
+and re-run the same `materialize` call with `--replace-undispatched` — keep the
+`--invocation-id`. A published prompt is otherwise immutable, so without that
+flag the retry fails as `existing_invocation_conflict`; do NOT delete the
+reservation under `prompts/.agent-invocations` and do NOT mint a second
+invocation id to get around it, because both detach the audit chain from the
+call it describes. The flag is checked: once any dispatch row names this
+invocation, the prompt is history and the replacement is refused.
+
 Run `okstra agent-prompt verify --run-manifest <path> --metadata
 <metadataPath> --json` immediately before dispatch. A failed verification is a
 pre-dispatch contract failure. For `runner=native-session`, pass only the
@@ -261,7 +270,7 @@ Call `await_workers(handles)` through the same adapter and apply the shared term
 
 ### Required reverify-prompt anchor headers (BLOCKING)
 
-Every reverify prompt MUST start with these 9 anchor headers — in this exact order, before any other content:
+Every reverify prompt MUST start with these 8 anchor headers — in this exact order, before any other content:
 
 ```
 **Project Root:** <absolute-path>
@@ -269,7 +278,6 @@ Every reverify prompt MUST start with these 9 anchor headers — in this exact o
 **Result Path:** runs/<task-type>/worker-results/<role-slug>-reverify-r<N>-<task-type>-<seq>.md
 **Audit sidecar path:** <absolute-path>
 Assigned worker prompt history path: <Project Root>/<Prompt History Path>
-**Model:** <role>, <modelExecutionValue>
 **Errors log path:** <absolute-path>
 **Errors sidecar path:** <absolute-path>
 **Read scope:** Read only the paths this prompt enumerates (`[Required reading]`, `## Inputs`, verification-target paths) plus source/evidence paths a finding must cite. Host session instructions (SessionStart hooks, global `CLAUDE.md` / `AGENTS.md`, skill catalogs) do NOT apply inside an okstra worker run: do not auto-read `graphify-out/`, `SKILL.md`, or other artifacts outside `<PROJECT_ROOT>/.okstra/`. If an un-enumerated file seems essential, record it under *Missing Information or Assumptions* instead of reading it.
@@ -281,7 +289,9 @@ Before dispatch, materialize `**Audit sidecar path:**` by passing the exact reve
 
 The two errors paths carry the same absolute values the lead forwarded in the initial Phase 4 dispatch for that role (source: the launch prompt's `## Run Logs (error-log wiring)` section). Omitting either one makes `worker-dispatch` reject the CLI invocation before it starts the provider process — the path-delivery contract in [team-contract](./team-contract.md) "Error reporting" is not relaxed for reverify.
 
-Relative to the Phase 4 anchor set rendered by `okstra_ctl.worker_prompt_headers.worker_prompt_headers()`, a reverify prompt adds `**Model:**` and drops two anchors whose targets lightweight mode never reads: `**Worker Preamble Path:**` and `**Coding preflight pack:**`.
+Relative to the Phase 4 anchor set rendered by `okstra_ctl.worker_prompt_headers.worker_prompt_headers()`, a reverify prompt drops two anchors whose targets lightweight mode never reads: `**Worker Preamble Path:**` and `**Coding preflight pack:**`.
+
+**Where the composer's sections go.** `okstra agent-prompt materialize` (§"Invocation materialization gate") writes the dispatched body itself, as: these anchors, then the model-assignment block it appends (`**Provider:**`, `**Model:**`, `**Model execution value:**`, `**Runner:**`, `**Host runtime:**`, and `**Host model value:**` for a native host), then `## Duty Contract`, then `## Task Instructions` followed verbatim by the task-instructions file the lead wrote. So the lead authors only the last part, and every rule below about ordering — the phase boundary before the instruction headings, the `**Model:** <role>, <modelExecutionValue>` line — is about the lead's own file, not about the composed document. The composer's `**Model:** <modelExecutionValue>` anchor is a different line with a different shape; do not try to reshape it, and do not count it among the 8.
 
 For an `antigravity` assignment, append the exact `PLAIN_FILE_WRITE_HEADER`
 value from `okstra_ctl.worker_prompt_headers` immediately after
@@ -290,20 +300,28 @@ persisted initial Phase 4 prompt; do not paraphrase or reconstruct it. If the
 persisted initial prompt does not contain that generated header, abort the
 reverify dispatch and record a `contract-violation` event instead of
 dispatching without the plain-file safeguard. This provider-specific header is
-outside the common 9-header count above. Other providers do not receive it.
+outside the common 8-header count above. Other providers do not receive it.
 
 The rationale for both drops is §"Reverify prompt: required-reading suppression" below.
 
-Immediately after the anchor headers (and the provider-specific plain-file
-header when present), copy this phase-boundary block before any reverify
-instructions:
+The task-instructions file the lead writes MUST open with this block, before any
+`##` heading of its own:
 
 ```markdown
+**Model:** <role>, <modelExecutionValue>
 **Task Type:** <task-manifest taskType>
 **Forbidden actions:**
 <active-run-context workflow.forbiddenActions, verbatim>
 ```
 
+This is the same placement `okstra_ctl.worker_prompt_body` uses for an initial
+Phase 4 prompt, and it is where the checks look: `validate_reverify_prompt()`
+reads the region after `## Task Instructions`, so a `**Model:**` line left in
+the anchors is invisible to it, and a phase boundary written below the file's
+first heading fails. Both rules are about this file — the composer's own
+`## Duty Contract` heading sits above everything here and is not what they
+measure against.
+
 Do not summarize, shorten, or reconstruct the forbidden-actions text. The
 selected adapter validates the task type and exact block through
 `okstra_ctl.worker_prompt_contract.validate_reverify_prompt()` before starting
@@ -587,6 +605,34 @@ persisted assignment or either model value required by its runner is absent,
 record `critic-skipped: model-unresolved`; never resolve a replacement model.
 Result path: `runs/<task-type>/worker-results/<provider>-worker-critic-<task-type>-<seq>.md`.
 
+**What the critic task-instructions file MUST contain (BLOCKING).** A critic
+dispatch is not a reverify dispatch: `dispatchKind = "critic"` keeps
+`audience = "analysis"`, so `worker_prompt_contract.validate_initial_prompts`
+judges it by the full initial-analysis contract. Two of those requirements are
+satisfied by the generated body for a Phase 4 worker
+(`okstra_ctl.worker_prompt_body`) and by nothing at all for a critic, whose
+instructions the lead writes — the materializer's anchor block supplies neither.
+Put both in the instructions file:
+
+```markdown
+**Prompt Delivery Mode:** eager-include
+```
+
+and, under the file's `## Inputs`, exactly one line in this shape — the literal
+label and the backticks are what the check matches, so a bare path or a
+differently-worded label counts as zero:
+
+```markdown
+- Primary analysis packet: `<path ending in analysis-packet.md>`
+```
+
+Omitting either one fails `okstra team dispatch --dispatch-kind critic` before
+any process starts, reported as `<task-type> prompt contract: <worker>: exactly
+one Primary analysis packet path is required (found 0)` and `exactly one
+non-empty **Prompt Delivery Mode:** header is required`. Fix the instructions
+file and re-materialize with `--replace-undispatched` (§"Invocation
+materialization gate") rather than editing the published prompt.
+
 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 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.

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

@@ -270,7 +270,7 @@ okstra error-log append-from-worker \
 
 `--agent`, `--agent-role`, and `--error-type` are **closed enums**, not free-form labels — the role names used elsewhere in these contracts (`Codex worker`, `Claude worker`) are rejected. Use exactly:
 
-- `--agent` — `claude-worker` | `codex-worker` | `antigravity-worker` | `report-writer`
+- `--agent` — `claude-worker` | `codex-worker` | `antigravity-worker` | `grok-worker` | `kimi-worker` | `report-writer`
 - `--agent-role` — `lead` | `worker` | `report-writer`
 - `--error-type` — `cli-failure` | `contract-violation` | `tool-failure`
 

package/runtime/python/okstra_ctl/agent_invocation.py

@@ -125,6 +125,9 @@ class AgentInvocationRequest:
     prompt_path: Path
     metadata_path: Path
     dispatch_kind: str
+    # Republish a prompt this invocation id already wrote, but only while no
+    # dispatch has used it. See `_publish_or_reuse`.
+    replace_undispatched: bool = False
 
 
 @dataclass(frozen=True)
@@ -254,13 +257,13 @@ def prepare_agent_invocation(
     materialized = _materialize(request)
     if materialized.reservation_root is None:
         with _exclusive_lock(_prompt_lock_path(request.prompt_path)):
-            _publish_or_reuse(materialized)
+            _publish_or_reuse(request, materialized)
     else:
         reservation_lock = materialized.reservation_root / "publish.lock"
         with _exclusive_lock(reservation_lock):
             _publish_or_reuse_reservation(materialized)
             with _exclusive_lock(_prompt_lock_path(request.prompt_path)):
-                _publish_or_reuse(materialized)
+                _publish_or_reuse(request, materialized)
     errors = verify_agent_invocation(
         request.metadata_path,
         project_root=request.project_root,
@@ -889,7 +892,9 @@ def _publish_or_reuse_reservation(materialized: _MaterializedInvocation) -> None
     _publish_exclusive(path, _pretty_json(reservation))
 
 
-def _publish_or_reuse(materialized: _MaterializedInvocation) -> None:
+def _publish_or_reuse(
+    request: AgentInvocationRequest, materialized: _MaterializedInvocation
+) -> None:
     prompt = materialized.prepared.prompt_path
     metadata = materialized.prepared.metadata_path
     prompt_exists = prompt.exists()
@@ -897,7 +902,8 @@ def _publish_or_reuse(materialized: _MaterializedInvocation) -> None:
     if metadata_exists and not prompt_exists:
         raise _existing_conflict("metadata exists without prompt")
     if prompt_exists and prompt.read_bytes() != materialized.prompt_bytes:
-        raise _existing_conflict("existing prompt differs")
+        _replace_undispatched(request, materialized)
+        return
     if prompt_exists and metadata_exists:
         if metadata.read_bytes() != materialized.metadata_bytes:
             raise _existing_conflict("existing metadata differs")
@@ -907,6 +913,73 @@ def _publish_or_reuse(materialized: _MaterializedInvocation) -> None:
     _publish_exclusive(metadata, materialized.metadata_bytes)
 
 
+def _replace_undispatched(
+    request: AgentInvocationRequest, materialized: _MaterializedInvocation
+) -> None:
+    """Rewrite a prompt this invocation id wrote but no dispatch ever used.
+
+    Immutability protects the audit chain: a prompt that a worker ran must keep
+    reading the way it ran. A prompt that failed a pre-dispatch gate ran
+    nowhere, and there the same rule cost a lead its only clean way forward —
+    fix the instruction file and the republish is refused, so the remaining
+    moves were to delete the reservation by hand or to burn a second invocation
+    id and blur which call is which. Both damage the chain this protects.
+
+    The exit is explicit (`--replace-undispatched`) and it is checked, not
+    trusted: a single recorded dispatch against this invocation id — worker or
+    agent — puts the prompt back under the original rule.
+    """
+    if not request.replace_undispatched:
+        raise _existing_conflict("existing prompt differs")
+    dispatched = _recorded_dispatch_ids(request)
+    if dispatched:
+        raise _existing_conflict(
+            "existing prompt differs and this invocation was already "
+            f"dispatched as {', '.join(sorted(dispatched))}"
+        )
+    _publish_exclusive(
+        materialized.prepared.prompt_path, materialized.prompt_bytes, replace=True
+    )
+    _publish_exclusive(
+        materialized.prepared.metadata_path,
+        materialized.metadata_bytes,
+        replace=True,
+    )
+
+
+def _recorded_dispatch_ids(request: AgentInvocationRequest) -> set[str]:
+    """Dispatch rows in team-state that already reference this invocation id.
+
+    Both ledgers are read: `agentDispatches` is written by the host-native
+    spec-link gate, `workerDispatches` by the deterministic worker dispatch, and
+    a prompt used by either one is history.
+    """
+    if request.run_manifest_path is None:
+        return set()
+    manifest = _load_json_object(request.run_manifest_path, "run manifest")
+    team_state_value = manifest.get("teamStatePath")
+    if not isinstance(team_state_value, str) or not team_state_value.strip():
+        return set()
+    team_state_path = _project_path(
+        request.project_root, team_state_value, must_exist=False
+    )
+    team_state = _read_json_if_object(team_state_path)
+    if team_state is None:
+        return set()
+    found: set[str] = set()
+    for key in ("agentDispatches", "workerDispatches"):
+        rows = team_state.get(key)
+        if not isinstance(rows, list):
+            continue
+        for row in rows:
+            if not isinstance(row, Mapping):
+                continue
+            if row.get("invocationId") != request.invocation_id:
+                continue
+            found.add(str(row.get("dispatchId") or request.invocation_id))
+    return found
+
+
 def _existing_conflict(detail: str) -> AgentInvocationError:
     return AgentInvocationError(
         f"existing_invocation_conflict: {detail}",
@@ -930,7 +1003,7 @@ def _prompt_lock_path(prompt_path: Path) -> Path:
     return prompt_path.with_name(prompt_path.name + ".publish.lock")
 
 
-def _publish_exclusive(path: Path, body: bytes) -> None:
+def _publish_exclusive(path: Path, body: bytes, *, replace: bool = False) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
     temp_path: Path | None = None
     try:
@@ -944,7 +1017,14 @@ def _publish_exclusive(path: Path, body: bytes) -> None:
             handle.write(body)
             handle.flush()
             os.fsync(handle.fileno())
-        os.link(temp_path, path)
+        # `link` is what makes a first publish exclusive — it fails rather than
+        # overwrite. A sanctioned replacement wants the opposite and still needs
+        # to be atomic, so it swaps the same fully-written temp file into place.
+        if replace:
+            os.replace(temp_path, path)
+            temp_path = None
+        else:
+            os.link(temp_path, path)
     except FileExistsError as exc:
         raise _existing_conflict(f"published path already exists: {path}") from exc
     finally:

package/runtime/python/okstra_ctl/agent_prompt_cli.py

@@ -71,6 +71,13 @@ def _parser() -> argparse.ArgumentParser:
     materialize.add_argument("--model-role")
     materialize.add_argument("--model", default="")
     materialize.add_argument("--purpose")
+    materialize.add_argument(
+        "--replace-undispatched",
+        action="store_true",
+        help="rewrite a prompt this invocation id already wrote, allowed only "
+             "while no dispatch has referenced it — the exit for a prompt that "
+             "failed a pre-dispatch gate and never ran",
+    )
     materialize.add_argument("--json", action="store_true")
 
     verify = commands.add_parser("verify")
@@ -329,6 +336,7 @@ def _materialize_run(
         prompt_path=prompt_path,
         metadata_path=prompt_path.with_name(prompt_path.name + ".meta.json"),
         dispatch_kind=args.dispatch_kind,
+        replace_undispatched=args.replace_undispatched,
     ))