okstra 0.146.1 → 0.148.0

package/runtime/validators/validate-run.py

@@ -30,12 +30,12 @@ for _ssot_dir in (_VALIDATORS_DIR.parent / "scripts", _VALIDATORS_DIR.parent / "
 try:
     from okstra_ctl.final_report_schema import (
         SchemaError,
-        load_schema,
+        load_schema_for_data,
         validate as schema_validate,
     )
 except ImportError:  # pragma: no cover — runtime guarantees this import
     SchemaError = None  # type: ignore[assignment]
-    load_schema = None  # type: ignore[assignment]
+    load_schema_for_data = None  # type: ignore[assignment]
     schema_validate = None  # type: ignore[assignment]
 
 from okstra_project import project_json_path  # noqa: E402
@@ -51,6 +51,7 @@ from okstra_ctl.conformance import (  # noqa: E402
     validate_conformance_manifest,
 )
 from okstra_ctl.paths import RunRef  # noqa: E402
+from okstra_ctl.lead_runtime import ARTIFACT_ONLY_LEAD_RUNTIMES  # noqa: E402
 from okstra_ctl.build_tools import (  # noqa: E402
     command_invokes_build_tool,
     resolve_build_tool_tokens,
@@ -156,7 +157,7 @@ def _session_accounting(team_state: dict) -> str:
         return value
     return (
         "artifact-only"
-        if team_state.get("leadRuntime") in {"codex", "external"}
+        if team_state.get("leadRuntime") in ARTIFACT_ONLY_LEAD_RUNTIMES
         else "claude-jsonl"
     )
 
@@ -415,20 +416,24 @@ def extract_contract(
         required_worker_roles = []
         failures.append("requiredWorkerRoles is missing from run/task manifest")
 
+    lead_role = (
+        run_contract.get("leadRole")
+        or task_contract.get("leadRole")
+        or "Okstra lead"
+    )
+
     required_agent_status_entries = run_contract.get("requiredAgentStatusEntries")
     if not isinstance(required_agent_status_entries, list):
         required_agent_status_entries = task_contract.get("requiredAgentStatusEntries")
     if not isinstance(required_agent_status_entries, list):
-        required_agent_status_entries = ["Claude lead"] + [
+        required_agent_status_entries = [lead_role] + [
             item.get("role", "")
             for item in required_worker_roles
             if isinstance(item, dict) and item.get("role")
         ]
 
     return {
-        "lead_role": run_contract.get("leadRole")
-        or task_contract.get("leadRole")
-        or "Claude lead",
+        "lead_role": lead_role,
         "lead_agent": run_contract.get("leadAgent")
         or task_contract.get("leadAgent")
         or "claude",
@@ -722,7 +727,7 @@ def validate_team_state(
         dispatch_mode = str(team_state.get("dispatchMode", "")).strip()
         if (
             dispatch_mode in WORKER_DISPATCH_MODES
-            or team_state.get("leadRuntime") in {"codex", "external"}
+            or team_state.get("leadRuntime") in ARTIFACT_ONLY_LEAD_RUNTIMES
         ):
             if dispatch_mode not in WORKER_DISPATCH_MODES:
                 expected = ", ".join(sorted(WORKER_DISPATCH_MODES))
@@ -1021,6 +1026,48 @@ def _scan_token_usage_summary(
 # a section heading line (not as inline text inside a paragraph or table).
 _VERDICT_CARD_HEADING_RE = re.compile(r"^##[ \t]+Verdict Card\b", re.MULTILINE)
 
+_V2_AI_HANDOFF_HEADINGS = (
+    "## AI Handoff Summary",
+    "## Clarification and User Decisions",
+    "## Evidence Ledger",
+    "## Task Deliverable:",
+    "## Cross Verification Audit",
+    "## Execution Audit",
+    "## Token and Cost Audit",
+)
+
+
+def _validate_v2_ai_handoff(content: str, failures: list[str]) -> None:
+    positions: list[int] = []
+    for heading in _V2_AI_HANDOFF_HEADINGS:
+        count = content.count(heading)
+        if count != 1:
+            failures.append(
+                "schema-v2 AI handoff markdown requires exactly one "
+                f"`{heading}` heading; found {count}."
+            )
+            continue
+        positions.append(content.index(heading))
+    if len(positions) == len(_V2_AI_HANDOFF_HEADINGS) and positions != sorted(
+        positions
+    ):
+        failures.append(
+            "schema-v2 AI handoff markdown heading order does not match "
+            "templates/reports/final-report-v2.template.md."
+        )
+    for human_only_field in ('"humanSummary"', '"userNarrative"'):
+        if human_only_field in content:
+            failures.append(
+                "schema-v2 AI handoff markdown contains human-only field "
+                f"{human_only_field}; render it only in the task-specific HTML."
+            )
+    if _READING_CONFIRMATION_HEADING_RE.search(content) is not None:
+        failures.append(
+            "final report contains a `## 0. Reading Confirmation` heading — "
+            "Reading Confirmation lives in the worker audit sidecar, never "
+            "in the AI handoff markdown."
+        )
+
 # Top-of-report Index block. The renderer
 # (scripts/okstra_ctl/render_final_report.py) injects `<a id="report-index">`
 # into the index heading; a missing anchor means the markdown was produced
@@ -2229,6 +2276,10 @@ def validate_report(
                 "run `okstra-token-usage.py ... --substitute-data <report-path>` during Phase 7"
             )
 
+    if (report_data or {}).get("schemaVersion") == "2.0":
+        _validate_v2_ai_handoff(content, failures)
+        return
+
     # Catch the "workers typed `0` / `pending` instead of the placeholder"
     # failure mode that bypasses the placeholder check above.
     _scan_token_usage_summary(
@@ -2995,7 +3046,7 @@ def validate_final_report_data(
     project_root: Path | None = None,
     clarification_text: str = "",
 ) -> Mapping[str, Any] | None:
-    """Validate the final-report data.json against the v1.0 schema.
+    """Validate final-report data.json against its declared versioned schema.
 
     The data.json is the source-of-truth that the renderer reads to
     produce the markdown. If schema validation passes here, the rendered
@@ -3010,7 +3061,7 @@ def validate_final_report_data(
     The returned mapping is the exact loaded snapshot consumed by later
     finalization checks and workflow persistence.
     """
-    if schema_validate is None or load_schema is None:
+    if schema_validate is None or load_schema_for_data is None:
         # Module-load fallback path; should never fire in a real install.
         failures.append(
             "validate-run: okstra_ctl.final_report_schema is not importable — "
@@ -3028,13 +3079,11 @@ def validate_final_report_data(
         return
 
     try:
-        schema = load_schema()
+        data = json.loads(data_path.read_text(encoding="utf-8"))
+        schema = load_schema_for_data(data)
     except SchemaError as exc:
         failures.append(f"final-report schema could not be loaded: {exc}")
         return
-
-    try:
-        data = json.loads(data_path.read_text(encoding="utf-8"))
     except json.JSONDecodeError as exc:
         failures.append(f"final-report data.json is not valid JSON: {exc}")
         return
@@ -6035,6 +6084,8 @@ def validate_phase_boundary(
     task_type: str,
     report_path: Path,
     failures: list[str],
+    *,
+    report_data: Mapping[str, Any] | None = None,
 ) -> None:
     """Phase-specific contract checks.
 
@@ -6050,6 +6101,8 @@ def validate_phase_boundary(
       MUST be absent (lead converted findings into Clarification rows
       instead of opening the gate).
     """
+    if (report_data or {}).get("schemaVersion") == "2.0":
+        return
     if not report_path.exists():
         return
     content = report_path.read_text()
@@ -7167,7 +7220,12 @@ def main() -> int:
     )
     validate_team_state_usage(team_state, failures)
 
-    validate_phase_boundary(task_type, report_path, failures)
+    validate_phase_boundary(
+        task_type,
+        report_path,
+        failures,
+        report_data=validation_data,
+    )
     _validate_phase_boundary_error_log(
         report_path.parent.parent,
         task_type,

package/runtime/validators/validate_improvement_report.py

@@ -7,6 +7,7 @@ Called by validators/validate-run.py when task_type == "improvement-discovery".
 """
 from __future__ import annotations
 
+import json
 import re
 import sys
 from dataclasses import dataclass, field
@@ -25,6 +26,10 @@ from okstra_ctl.improvement_lenses import (
     ABSOLUTE_CANDIDATE_CAP,
     SOURCE_WORKERS,
 )
+from okstra_ctl.final_report_schema import (
+    load_schema_version,
+    validate as validate_final_report_data,
+)
 from okstra_ctl.md_table import split_pipe_row
 
 
@@ -290,6 +295,47 @@ def _check_verdict_card(
         errors.append("Verdict Card row must byte-match `## 7. Final Verdict` row")
 
 
+def _v2_candidate_rows(data: dict) -> list[list[str]]:
+    candidates = data["improvementDiscovery"]["candidates"]
+    return [
+        [
+            row["id"],
+            ",".join(row["lens"]),
+            row["title"],
+            ",".join(row["scope"]),
+            row["severity"],
+            row["effort"],
+            row["consensus"],
+            ",".join(row["sourceWorkers"]),
+            row["recommendedNextPhase"],
+            row["expectedBehaviorAfter"],
+            ",".join(row["evidence"]),
+        ]
+        for row in candidates
+    ]
+
+
+def _validate_v2_report(
+    data: dict,
+    run_dir: Path,
+    brief_frontmatter: dict,
+) -> ValidationResult:
+    errors = validate_final_report_data(data, load_schema_version("2.0"))
+    _check_grilling_log(run_dir, errors)
+    if errors:
+        return ValidationResult(ok=False, errors=errors)
+
+    rows = _v2_candidate_rows(data)
+    _check_candidates_cap(len(rows), brief_frontmatter, errors)
+    _check_candidate_rows(
+        rows,
+        brief_frontmatter.get("scan-scope") or [],
+        brief_frontmatter.get("out-of-scope") or [],
+        errors,
+    )
+    return ValidationResult(ok=not errors, errors=errors)
+
+
 def validate_improvement_report(
     report_path: Path, run_dir: Path, brief_frontmatter: dict
 ) -> ValidationResult:
@@ -299,6 +345,15 @@ def validate_improvement_report(
         errors.append(f"report file not found: {report_path}")
         return ValidationResult(ok=False, errors=errors)
 
+    data_path = report_path.with_suffix(".data.json")
+    if data_path.exists():
+        try:
+            data = json.loads(data_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            return ValidationResult(ok=False, errors=[f"invalid report data: {exc}"])
+        if data.get("schemaVersion") == "2.0":
+            return _validate_v2_report(data, run_dir, brief_frontmatter)
+
     body = report_path.read_text(encoding="utf-8")
 
     _check_grilling_log(run_dir, errors)

package/runtime/validators/validate_session_conformance.py

@@ -38,6 +38,7 @@ from okstra_ctl.worker_heartbeat import (  # noqa: E402
     HEARTBEAT_LINE_RE,
     max_gap_seconds_after,
 )
+from okstra_ctl.lead_runtime import ARTIFACT_ONLY_LEAD_RUNTIMES  # noqa: E402
 from okstra_ctl.wrapper_status import read_wrapper_status  # noqa: E402
 
 _DISPATCHED_STATUSES = {"completed", "timeout", "error", "in-progress"}
@@ -366,7 +367,7 @@ def _conformance_evidence_source(
             return None, f"unsupported sessionAccounting: `{accounting}`"
 
     legacy_runtime = str(team_state.get("leadRuntime", "") or "claude-code")
-    if legacy_runtime in {"codex", "external"}:
+    if legacy_runtime in ARTIFACT_ONLY_LEAD_RUNTIMES:
         return "artifact-only", None
     return "claude-jsonl", None
 

package/src/cli-registry.mjs

@@ -415,18 +415,18 @@ export const COMMANDS = new Map(
   ]),
 );
 
-const PREAMBLE = `okstra — multi-agent cross-verification orchestrator for Claude Code
+const PREAMBLE = `okstra — host-aware multi-provider cross-verification orchestrator
 
 This CLI is the installer/admin tool. Day-to-day usage happens inside a
-Claude Code session via slash commands (/okstra-setup, /okstra-run, ...).
+supported agent host through installed skills (okstra-setup, okstra-run, ...).
 
 Quick start (CLI):
   1. npx -y okstra@latest install                       # one-time, this machine
   2. cd <your project>
   3. npx -y okstra@latest setup --project-id <id>       # one-time, this project
-  4. open a Claude Code session and run /okstra-run     # start a task
+  4. open Claude Code, Codex, or Antigravity and run okstra-run  # start a task
 
-Inside a Claude Code session you can replace step 3 with /okstra-setup —
+Inside a supported agent host you can replace step 3 with okstra-setup —
 both write the same <PROJECT_ROOT>/.okstra/project.json.
 
 Usage:

package/src/commands/execute/codex-dispatch.mjs

@@ -5,18 +5,15 @@ const USAGE = `okstra codex-dispatch — dispatch CLI-backed workers for a prepa
 
 Usage:
   okstra codex-dispatch --project-root <dir> --run-manifest <path> \\
-    [--workers codex[,antigravity[,report-writer]]] [--dry-run] \\
-    [--idle-timeout-seconds <n>] \\
-    [--enable-codex-report-writer --report-writer-codex-model <model>]
+    [--workers <cli-assigned-worker-ids>] [--dry-run] \\
+    [--idle-timeout-seconds <n>]
 
 This command reads an existing run manifest produced by 'okstra codex-run' and
-dispatches only Codex-side supported workers. When --workers is omitted, the
-command selects the supported subset of the run roster (codex/antigravity, plus
-report-writer only when explicitly opted in). Codex and antigravity use their
-existing wrappers. The report-writer role is available only through explicit
-Codex opt-in because the prepared manifest still records the Claude-side report
-writer model by default. Explicitly requesting unsupported workers such as
-claude fails.
+dispatches only assignments whose persisted runner is 'cli-wrapper'. When
+--workers is omitted, it selects that subset from the run roster. Each worker,
+including report-writer, uses its persisted provider, model, and registered
+wrapper. Native-session assignments remain owned by the current Codex host;
+explicitly requesting one here fails.
 
 Missing worker prompt files are generated automatically from the run manifest
 and active-run-context. Existing prompt files are never overwritten.

package/src/commands/execute/render-bundle.mjs

@@ -2,7 +2,7 @@ import { runPythonModule } from "../../lib/python-helper.mjs";
 import { resolvePaths } from "../../lib/paths.mjs";
 import { resolveRuntime } from "../../lib/runtime-resolver.mjs";
 
-const USAGE = `okstra render-bundle — preview the task bundle without launching claude
+const USAGE = `okstra render-bundle — preview the task bundle without launching a lead
 
 This is a thin shim over \`python3 -m okstra_ctl.run\` that forces
 \`--render-only\`. Use it to preview where prepare_task_bundle() would
@@ -18,7 +18,7 @@ Usage:
     [--analysis-target <text>] [--evidence-inputs <csv>] \\
     [--lead-model <m>] [--claude-model <m>] [--codex-model <m>] \\
     [--antigravity-model <m>] [--report-writer-model <m>] \\
-    [--lead-runtime claude-code|codex] \\
+    [--lead-runtime claude-code|codex|antigravity|external] \\
     [--related-tasks <list>] [--base-ref <ref>] \\
     [--clarification-response <path>] [--work-category <cat>] \\
     [--stage <auto|N>] [--stages <csv>] [--pr-template-path <path>] \\
@@ -26,7 +26,7 @@ Usage:
 
   --stage             implementation / final-verification only
   --stages            release-handoff only: PR stage bundle csv (empty = whole-task)
-  --lead-runtime      lead adapter marker; codex is render-only in this version
+  --lead-runtime      host-native lead adapter marker
   --pr-template-path  release-handoff only
   --fix-cycle         entry phase only: record this re-entry of a done task as a
                       bug-fix cycle (yes opens/continues the cycle)

package/src/commands/execute/run.mjs

@@ -7,10 +7,10 @@ const USAGE = `okstra run — host-aware okstra execution front door
 
 Usage:
   okstra run --project-root <dir> --project-id <id> --task-group <tg> \\
-    --task-id <tid> --task-type <type> [--lead-runtime auto|claude-code|codex|external]
+    --task-id <tid> --task-type <type> [--lead-runtime auto|claude-code|codex|antigravity|external]
 
-Claude Code native execution remains the /okstra-run skill front door. Bare
-'okstra run' orchestrates Codex and external/tmux CLI execution.
+Host-native Claude Code, Codex, and Antigravity execution use the okstra-run
+skill front door. Bare 'okstra run' orchestrates only external/tmux all-CLI execution.
 `;
 
 function flagValue(args, flag) {
@@ -48,55 +48,22 @@ function projectRootFromArgs(args) {
   return flagValue(args, "--project-root");
 }
 
-function withoutDispatchOnlyFlags(args) {
-  const out = [];
-  for (let i = 0; i < args.length; i += 1) {
-    const arg = args[i];
-    if (arg === "--enable-codex-report-writer") continue;
-    if (arg === "--report-writer-codex-model") {
-      i += 1;
-      continue;
-    }
-    if (arg.startsWith("--report-writer-codex-model=")) continue;
-    out.push(arg);
-  }
-  return out;
-}
-
 function renderArgs(args, resolution) {
   return [
     "--lead-runtime", resolution.resolvedRuntime,
     "--lead-runtime-request", resolution.requestedRuntime,
     "--runtime-resolution-json", JSON.stringify(resolution),
-    ...withoutDispatchOnlyFlags(withoutLeadRuntimeFlags(args)),
+    ...withoutLeadRuntimeFlags(args),
   ];
 }
 
-function codexDispatchArgs(args, projectRoot, runManifestPath) {
-  const out = ["--project-root", projectRoot, "--run-manifest", runManifestPath];
-  for (let i = 0; i < args.length; i += 1) {
-    const arg = args[i];
-    if (arg === "--enable-codex-report-writer") {
-      out.push(arg);
-      continue;
-    }
-    if (arg === "--report-writer-codex-model") {
-      out.push(arg, args[i + 1] ?? "");
-      i += 1;
-      continue;
-    }
-    if (arg.startsWith("--report-writer-codex-model=")) out.push(arg);
-  }
-  return out;
-}
-
 export function buildRunPlan({ args, paths, resolution, runManifestPath = "" }) {
   void paths;
   const projectRoot = projectRootFromArgs(args);
   if (resolution.resolvedRuntime === "claude-code") {
     return {
       ok: false,
-      reason: "Bare okstra run cannot invoke Claude Code TeamCreate / Agent(...). Use /okstra-run in Claude Code or pass --lead-runtime external|codex.",
+      reason: "Bare okstra run cannot invoke host-native Claude workers. Use the okstra-run skill in Claude Code or pass --lead-runtime external.",
       commands: [],
     };
   }
@@ -115,12 +82,17 @@ export function buildRunPlan({ args, paths, resolution, runManifestPath = "" })
 
   if (resolution.resolvedRuntime === "codex") {
     return {
-      ok: true,
-      reason: resolution.reason,
-      commands: [
-        { name: "codex-run", args: renderArgs(args, resolution), capture: true },
-        { name: "codex-dispatch", args: codexDispatchArgs(args, projectRoot, runManifestPath), capture: false },
-      ],
+      ok: false,
+      reason: "Bare okstra run cannot invoke host-native Codex workers. Use the okstra-run skill in Codex or pass --lead-runtime external for an all-CLI run.",
+      commands: [],
+    };
+  }
+
+  if (resolution.resolvedRuntime === "antigravity") {
+    return {
+      ok: false,
+      reason: "Bare okstra run cannot invoke host-native Antigravity workers. Use the okstra-run skill in Antigravity or pass --lead-runtime external for an all-CLI run.",
+      commands: [],
     };
   }
 
@@ -147,11 +119,6 @@ async function runTeam(args) {
   return await runTeamCommand(args);
 }
 
-async function runCodexDispatch(args) {
-  const { run: runCodexDispatchCommand } = await import("./codex-dispatch.mjs");
-  return await runCodexDispatchCommand(args);
-}
-
 export async function run(args) {
   if (args.includes("--help") || args.includes("-h")) {
     process.stdout.write(USAGE);
@@ -192,9 +159,7 @@ export async function run(args) {
 
   const plan = buildRunPlan({ args, paths, resolution, runManifestPath });
   for (const command of plan.commands.slice(1)) {
-    const code = command.name.startsWith("team ")
-      ? await runTeam(command.args)
-      : await runCodexDispatch(command.args);
+    const code = await runTeam(command.args);
     if (code !== 0) return code;
   }
   return 0;

package/src/commands/execute/wizard.mjs

@@ -20,7 +20,7 @@ Subcommands:
 
 Usage:
   okstra wizard new-state-file
-  okstra wizard init --state-file <path> --project-root <p> --project-id <id>
+  okstra wizard init --state-file <path> --project-root <p> --project-id <id> --host-runtime <runtime>
   okstra wizard step --state-file <path> [--answer <value>]
   okstra wizard render-args --state-file <path>
   okstra wizard confirmation --state-file <path>
@@ -106,6 +106,9 @@ export async function run(args) {
     pyArgs.push("--workspace-root", paths.workspace);
     pyArgs.push("--project-root", flags["project-root"]);
     pyArgs.push("--project-id", flags["project-id"]);
+    if (flags["host-runtime"]) {
+      pyArgs.push("--host-runtime", flags["host-runtime"]);
+    }
   } else if (sub === "step" && flags.answer !== undefined) {
     pyArgs.push("--answer", flags.answer);
   }

package/src/commands/lifecycle/doctor.mjs

@@ -14,7 +14,7 @@ const USAGE = `okstra doctor — diagnose the installed runtime
 
 Usage:
   okstra doctor               Run all checks and print a summary
-  okstra doctor --runtime <claude-code|codex|external|all>
+  okstra doctor --runtime <claude-code|codex|antigravity|external|all>
   okstra doctor --phase <phase>
   okstra doctor --json        Machine-readable result
 Checks:
@@ -48,7 +48,7 @@ export function parseDoctorArgs(args) {
     } else if (arg === "--runtime" || arg.startsWith("--runtime=")) {
       const value = arg.startsWith("--runtime=") ? arg.slice("--runtime=".length) : args[i + 1];
       if (!value || value.startsWith("--")) {
-        throw new Error("--runtime requires one of: claude-code, codex, external, all");
+        throw new Error("--runtime requires one of: claude-code, codex, antigravity, external, all");
       }
       result.runtime = validateInstallRuntime(value);
       if (arg === "--runtime") i++;
@@ -226,6 +226,9 @@ export async function run(args) {
     await check("bin: okstra.sh", () => checkBashEntry(paths.bin, "okstra.sh")),
     await check("bin: okstra-codex-exec.sh", () => checkBashEntry(paths.bin, "okstra-codex-exec.sh")),
     await check("bin: okstra-antigravity-exec.sh", () => checkBashEntry(paths.bin, "okstra-antigravity-exec.sh")),
+    await check("bin: okstra-grok-exec.sh", () => checkBashEntry(paths.bin, "okstra-grok-exec.sh")),
+    await check("bin: okstra-kimi-exec.sh", () => checkBashEntry(paths.bin, "okstra-kimi-exec.sh")),
+    await check("bin: okstra-provider-exec.py", () => checkBashEntry(paths.bin, "okstra-provider-exec.py")),
     await check("bin: okstra-central.sh", () => checkBashEntry(paths.bin, "okstra-central.sh")),
     ...(await Promise.all(
       requiredSkillNamesForRuntime(resolvedRuntime).map((name) =>
@@ -275,7 +278,7 @@ export async function run(args) {
 
   if (!runtimeResolution.ok) {
     process.stdout.write(
-      `  [WARN] runtime host: ${runtimeResolution.reason} skill checks skipped — pass --runtime <claude-code|codex|external> to include them.\n`,
+      `  [WARN] runtime host: ${runtimeResolution.reason} skill checks skipped — pass --runtime <claude-code|codex|antigravity|external> to include them.\n`,
     );
   }
   if (dockerWarning) {