okstra 0.167.0 → 0.169.0

package/runtime/validators/validate-run.py

@@ -108,6 +108,11 @@ from okstra_ctl.worker_prompt_contract import (  # noqa: E402
     PromptRecord,
     validate_initial_prompt_records,
 )
+from okstra_ctl.agent_invocation import (  # noqa: E402
+    AgentInvocationError,
+    agent_model_assignment_from_payload,
+    verify_agent_invocation,
+)
 from okstra_ctl.worker_audit_ledger import (  # noqa: E402
     READING_CONFIRMATION_HEADING_RE,
     check_worker_results_audit,
@@ -124,6 +129,176 @@ from okstra_ctl.convergence_provenance import (  # noqa: E402
 TERMINAL_STATUSES = {"completed", "timeout", "error", "not-run"}
 ATTEMPTED_STATUSES = {"completed", "timeout", "error"}
 WORKER_DISPATCH_MODES = {"cli-wrapper", "mixed", "tmux-pane"}
+_AGENT_DISPATCH_DIGEST_KEYS = (
+    "catalogDigest",
+    "assignmentDigest",
+    "dutyDigest",
+    "instructionDigest",
+    "promptDigest",
+)
+
+
+def _validate_agent_dispatch_contract(
+    *,
+    project_root: Path,
+    run_manifest_path: Path,
+    run_manifest: Mapping[str, Any],
+    team_state: Mapping[str, Any],
+    failures: list[str],
+) -> None:
+    """Validate invocation-to-dispatch and result associations for new runs."""
+    contract = run_manifest.get("agentContract")
+    if not isinstance(contract, Mapping) or contract.get("schemaVersion") != 1:
+        return
+    assignments = run_manifest.get("invocationAssignments")
+    if not isinstance(assignments, Mapping):
+        failures.append("agent invocation metadata is missing: invocationAssignments")
+        return
+    worker_dispatches = [
+        row for row in (team_state.get("workerDispatches") or [])
+        if isinstance(row, Mapping) and row.get("invocationId")
+    ]
+    agent_dispatches = [
+        row for row in (team_state.get("agentDispatches") or [])
+        if isinstance(row, Mapping)
+    ]
+    dispatches = [*worker_dispatches, *agent_dispatches]
+    ids: dict[str, Mapping[str, Any]] = {}
+    for row in dispatches:
+        dispatch_id = str(row.get("dispatchId") or "").strip()
+        missing = [
+            key for key in (
+                "dispatchId", "workerId", "audience", "invocationId",
+                "assignmentRef", "promptMetadataPath", "modelExecutionValue",
+                "enforcementMode", *_AGENT_DISPATCH_DIGEST_KEYS,
+            )
+            if not str(row.get(key) or "").strip()
+        ]
+        if missing:
+            failures.append(
+                "agent invocation metadata is missing from dispatch record: "
+                + ", ".join(missing)
+            )
+            continue
+        if dispatch_id in ids:
+            failures.append(f"agent dispatch ID is duplicated: {dispatch_id}")
+            continue
+        ids[dispatch_id] = row
+        assignment_ref = str(row["assignmentRef"])
+        try:
+            assignment = agent_model_assignment_from_payload(
+                assignments.get(assignment_ref)
+            )
+        except AgentInvocationError as exc:
+            failures.append(f"agent dispatch {dispatch_id}: {exc}")
+            continue
+        metadata_path = _resolve_prompt_record_path(
+            project_root, str(row["promptMetadataPath"])
+        )
+        errors = verify_agent_invocation(
+            metadata_path,
+            project_root=project_root,
+            expected_run_manifest_path=run_manifest_path,
+            expected_assignment=assignment,
+            expected_invocation_id=str(row["invocationId"]),
+            expected_worker_id=str(row["workerId"]),
+            expected_assignment_ref=assignment_ref,
+            expected_audience=str(row["audience"]),
+        )
+        failures.extend(
+            f"agent dispatch {dispatch_id}: {error}" for error in errors
+        )
+        try:
+            metadata = json.loads(metadata_path.read_text(encoding="utf-8"))
+            digests = metadata["digests"]
+        except (OSError, json.JSONDecodeError, KeyError, TypeError):
+            digests = {}
+        for key in _AGENT_DISPATCH_DIGEST_KEYS:
+            if row.get(key) != digests.get(key):
+                failures.append(
+                    f"agent dispatch {dispatch_id}: {key} does not match metadata"
+                )
+        if row.get("modelExecutionValue") != assignment.model_execution_value:
+            failures.append(
+                f"agent dispatch {dispatch_id}: modelExecutionValue does not match assignment"
+            )
+        if row.get("hostModelValue") != assignment.host_model_value:
+            failures.append(
+                f"agent dispatch {dispatch_id}: hostModelValue does not match assignment"
+            )
+        enforcement = row.get("enforcementMode")
+        if enforcement not in {
+            "core-pre-dispatch", "host-native-spec-link-gate",
+        }:
+            failures.append(
+                f"agent dispatch {dispatch_id}: enforcementMode is invalid"
+            )
+        if (
+            enforcement == "host-native-spec-link-gate"
+            and row.get("promptDeliveryVerified") is not False
+        ):
+            failures.append(
+                "host-native lead delivery cannot be marked verified"
+                if row.get("audience") == "lead"
+                else "host-native prompt delivery cannot be marked verified"
+            )
+
+    lead_ids = {
+        dispatch_id for dispatch_id, row in ids.items()
+        if row.get("audience") == "lead" and row.get("workerId") == "lead"
+    }
+    if not lead_ids:
+        failures.append("accepted lead result has no lead dispatch record")
+
+    links = [
+        row for row in (team_state.get("agentResultLinks") or [])
+        if isinstance(row, Mapping)
+    ]
+    paths: dict[str, str] = {}
+    dispatch_link_counts: dict[str, int] = {}
+    for link in links:
+        dispatch_id = str(link.get("dispatchId") or "").strip()
+        result_path = str(link.get("resultPath") or "").strip()
+        if dispatch_id not in ids or not result_path:
+            failures.append("agent result link has no matching dispatch record")
+            continue
+        dispatch_link_counts[dispatch_id] = dispatch_link_counts.get(dispatch_id, 0) + 1
+        previous = paths.setdefault(result_path, dispatch_id)
+        if previous != dispatch_id:
+            failures.append(
+                f"agent result is linked to multiple dispatches: {result_path}"
+            )
+    for dispatch_id, count in dispatch_link_counts.items():
+        if count > 1:
+            failures.append(
+                f"agent dispatch is linked to multiple accepted results: {dispatch_id}"
+            )
+
+    for worker in team_state.get("workers") or []:
+        if not isinstance(worker, Mapping) or worker.get("status") != "completed":
+            continue
+        worker_id = str(worker.get("workerId") or "").strip()
+        worker_result = str(worker.get("resultPath") or "").strip()
+        worker_dispatch_ids = {
+            dispatch_id for dispatch_id, row in ids.items()
+            if row.get("workerId") == worker_id
+        }
+        if worker_id and not worker_dispatch_ids:
+            failures.append(
+                f"accepted LLM result has no agent invocation record: {worker_id}"
+            )
+            continue
+        matching = [
+            link for link in links
+            if link.get("dispatchId") in worker_dispatch_ids
+            and link.get("resultPath") == worker_result
+        ]
+        if worker_id and len(matching) != 1:
+            failures.append(
+                f"accepted LLM result is not linked to its own dispatch: {worker_id}"
+            )
+    if lead_ids and not any(link.get("dispatchId") in lead_ids for link in links):
+        failures.append("accepted lead result has no dispatch result link")
 
 
 def utc_now() -> str:
@@ -7805,6 +7980,13 @@ def main() -> int:
         failures,
         concurrent_run_authorized=concurrent_run_authorized,
     )
+    _validate_agent_dispatch_contract(
+        project_root=project_root,
+        run_manifest_path=run_manifest_path,
+        run_manifest=run_manifest,
+        team_state=team_state,
+        failures=failures,
+    )
     # Schema validation runs BEFORE markdown substring checks: if the
     # data.json is well-formed, the rendered markdown is guaranteed to
     # contain every required section. Substring checks below are a

package/src/cli-registry.mjs

@@ -80,6 +80,20 @@ export const COMMAND_REGISTRY = [
     category: "admin",
     summary: ["Extract and validate deterministic plan-body items"],
   },
+  {
+    name: "agent-prompt",
+    module: "./commands/execute/agent-prompt.mjs",
+    export: "run",
+    category: "admin",
+    summary: ["Materialize and verify auditable agent invocations"],
+  },
+  {
+    name: "worker-dispatch",
+    module: "./commands/execute/worker-dispatch.mjs",
+    export: "run",
+    category: "admin",
+    summary: ["Dispatch verified CLI-backed worker assignments"],
+  },
   {
     name: "plan-verify",
     module: "./commands/execute/plan-verify.mjs",

package/src/commands/execute/agent-prompt.mjs

@@ -0,0 +1,25 @@
+import { runPythonModule } from "../../lib/python-helper.mjs";
+
+const USAGE = `okstra agent-prompt — materialize and verify auditable agent invocations
+
+Usage:
+  okstra agent-prompt materialize [options]
+  okstra agent-prompt verify [options]
+  okstra agent-prompt materialize-result [options]
+  okstra agent-prompt complete [options]
+  okstra agent-prompt verify-completion [options]
+  okstra agent-prompt record-dispatch [options]
+  okstra agent-prompt link-result [options]
+`;
+
+export async function run(args) {
+  if (args.length === 1 && (args[0] === "--help" || args[0] === "-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  const { code } = await runPythonModule({
+    module: "okstra_ctl.agent_prompt_cli",
+    args,
+  });
+  return code ?? 1;
+}

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

@@ -1,67 +1,10 @@
-import { runPythonModule } from "../../lib/python-helper.mjs";
-import { resolvePaths } from "../../lib/paths.mjs";
+import {
+  buildWorkerDispatchArgs,
+  runWorkerDispatch,
+} from "./worker-dispatch.mjs";
 
-const USAGE = `okstra codex-dispatch — dispatch CLI-backed workers for a prepared Codex run
-
-Usage:
-  okstra codex-dispatch --project-root <dir> --run-manifest <path> \\
-    [--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 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.
-When the Codex report-writer path completes, this command also runs the
-idempotent post-report steps: token-usage substitution, render-views,
-spawn-followups, and validate-run.
-
-  --workspace-root and --okstra-bin are owned by this command.
-`;
-
-const OWNED_FLAGS = new Set(["--workspace-root", "--okstra-bin"]);
-
-function isOwnedFlag(arg) {
-  if (OWNED_FLAGS.has(arg)) return true;
-  return [...OWNED_FLAGS].some((flag) => arg.startsWith(`${flag}=`));
-}
-
-export function buildCodexDispatchArgs(args, paths) {
-  return [
-    "--workspace-root", paths.workspace,
-    "--okstra-bin", paths.bin,
-    ...args,
-  ];
-}
+export const buildCodexDispatchArgs = buildWorkerDispatchArgs;
 
 export async function run(args) {
-  if (args.includes("--help") || args.includes("-h")) {
-    process.stdout.write(USAGE);
-    return 0;
-  }
-  if (args.length === 0) {
-    process.stdout.write(USAGE);
-    return 2;
-  }
-
-  const forbidden = args.find(isOwnedFlag);
-  if (forbidden) {
-    process.stderr.write(
-      `error: ${forbidden} is set by 'okstra codex-dispatch' itself — remove it from your args\n`,
-    );
-    return 2;
-  }
-
-  const paths = await resolvePaths();
-  const result = await runPythonModule({
-    module: "okstra_ctl.codex_dispatch",
-    args: buildCodexDispatchArgs(args, paths),
-    stdio: "inherit-stdout",
-  });
-  return result.code;
+  return runWorkerDispatch(args, { commandName: "codex-dispatch" });
 }

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

@@ -0,0 +1,76 @@
+import { runPythonModule } from "../../lib/python-helper.mjs";
+import { resolvePaths } from "../../lib/paths.mjs";
+
+export const USAGE = `okstra worker-dispatch — dispatch verified CLI-backed workers
+
+Usage:
+  okstra worker-dispatch --project-root <dir> --run-manifest <path> \\
+    [--workers <cli-assigned-worker-ids>] [--dry-run] \\
+    [--idle-timeout-seconds <n>]
+
+This command reads a prepared run manifest and dispatches only assignments
+whose persisted runner is 'cli-wrapper'. It verifies each invocation contract
+before execution and uses the persisted provider, model, and registered CLI.
+Native-session assignments remain owned by the active host session.
+
+Missing worker prompt files are generated automatically from the immutable run snapshot.
+Existing prompt and metadata files are never overwritten.
+When report-writer completes, this command also runs the idempotent post-report
+steps: token-usage substitution, render-views, spawn-followups, and validate-run.
+
+  --workspace-root and --okstra-bin are owned by this command.
+`;
+
+const OWNED_FLAGS = new Set(["--workspace-root", "--okstra-bin"]);
+
+function isOwnedFlag(arg) {
+  if (OWNED_FLAGS.has(arg)) return true;
+  return [...OWNED_FLAGS].some((flag) => arg.startsWith(`${flag}=`));
+}
+
+export function buildWorkerDispatchArgs(args, paths) {
+  return [
+    "--workspace-root", paths.workspace,
+    "--okstra-bin", paths.bin,
+    ...args,
+  ];
+}
+
+export async function runWorkerDispatch(args, { commandName = "worker-dispatch" } = {}) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(
+      commandName === "worker-dispatch"
+        ? USAGE
+        : USAGE.replaceAll("worker-dispatch", commandName),
+    );
+    return 0;
+  }
+  if (args.length === 0) {
+    process.stdout.write(
+      commandName === "worker-dispatch"
+        ? USAGE
+        : USAGE.replaceAll("worker-dispatch", commandName),
+    );
+    return 2;
+  }
+
+  const forbidden = args.find(isOwnedFlag);
+  if (forbidden) {
+    process.stderr.write(
+      `error: ${forbidden} is set by 'okstra ${commandName}' itself — remove it from your args\n`,
+    );
+    return 2;
+  }
+
+  const paths = await resolvePaths();
+  const result = await runPythonModule({
+    module: "okstra_ctl.worker_dispatch",
+    args: buildWorkerDispatchArgs(args, paths),
+    stdio: "inherit-stdout",
+  });
+  return result.code;
+}
+
+export async function run(args) {
+  return runWorkerDispatch(args);
+}

package/src/commands/lifecycle/doctor.mjs

@@ -88,6 +88,16 @@ export function phaseDiagnosticsToChecks(phase, phaseDiagnostics) {
   }));
 }
 
+export function buildPhaseDiagnosticsArgs(phase, paths, resolvedRuntime) {
+  return [
+    phase,
+    process.cwd(),
+    paths.workspace,
+    homedir(),
+    resolvedRuntime || "",
+  ];
+}
+
 async function checkPython3() {
   const r = await runProcess("python3", ["--version"]);
   if (r.code !== 0) return { ok: false, detail: `python3 not found: ${r.stderr.trim() || "missing binary"}` };
@@ -140,7 +150,7 @@ async function check(name, fn) {
   }
 }
 
-async function loadPhaseDiagnostics(phase, paths) {
+async function loadPhaseDiagnostics(phase, paths, resolvedRuntime) {
   const script = [
     "import json, sys",
     "from okstra_ctl.doctor import phase_diagnostics",
@@ -149,6 +159,7 @@ async function loadPhaseDiagnostics(phase, paths) {
     "    cwd=sys.argv[2],",
     "    workspace_root=sys.argv[3],",
     "    home=sys.argv[4],",
+    "    host_runtime=sys.argv[5],",
     ")",
     "print(json.dumps(payload, ensure_ascii=False))",
   ].join("\n");
@@ -159,7 +170,7 @@ async function loadPhaseDiagnostics(phase, paths) {
   // never exists and report a false "missing agent".
   const result = await runPythonSnippet({
     script,
-    args: [phase, process.cwd(), paths.workspace, homedir()],
+    args: buildPhaseDiagnosticsArgs(phase, paths, resolvedRuntime),
   });
   if (result.code !== 0 && !result.stdout.trim()) {
     return {
@@ -249,7 +260,11 @@ export async function run(args) {
 
   let phaseDiagnostics = null;
   if (opts.phase) {
-    phaseDiagnostics = await loadPhaseDiagnostics(opts.phase, paths);
+    phaseDiagnostics = await loadPhaseDiagnostics(
+      opts.phase,
+      paths,
+      resolvedRuntime,
+    );
     if (phaseDiagnostics.usageError) {
       process.stderr.write(`error: ${phaseDiagnostics.reason}\n`);
       return 2;

package/src/commands/lifecycle/install.mjs

@@ -10,9 +10,9 @@ import { normalizeHostRequest, resolveRuntime } from "../../lib/host-registry-cl
 import { OBSOLETE_SKILL_NAMES, USER_SKILL_NAMES } from "../../lib/skill-catalog.mjs";
 import {
   AGENTS_MANIFEST_REL,
+  LEGACY_TRANSPORT_AGENT_NAMES,
   SKILLS_MANIFEST_REL,
 } from "../../lib/install-assets.mjs";
-import { renderWorkerAgentDefinitions } from "../../lib/worker-agent-render.mjs";
 
 
 const USER_HOME = homedir();
@@ -389,6 +389,7 @@ async function installLinkMode(repoPath, paths, opts) {
 
   let agentResult = { installed: [] };
   if (skillTargets.some((target) => target.provider === "claude")) {
+    await pruneOwnedLegacyTransportAgents(paths.home, { dryRun, quiet });
     agentResult = await installAgentsLink(repoAbs, { dryRun, quiet });
   }
   await writeAgentsManifest(paths.home, agentResult.installed, { dryRun });
@@ -493,6 +494,35 @@ async function writeAgentsManifest(home, names, opts) {
   );
 }
 
+async function pruneOwnedLegacyTransportAgents(home, opts) {
+  const { dryRun = false, quiet = false } = opts ?? {};
+  let previous = [];
+  try {
+    const data = JSON.parse(
+      await fs.readFile(join(home, AGENTS_MANIFEST_REL), "utf8"),
+    );
+    if (Array.isArray(data?.agents)) previous = data.agents;
+  } catch (err) {
+    if (err.code !== "ENOENT" && !(err instanceof SyntaxError)) throw err;
+  }
+  const ownedLegacy = LEGACY_TRANSPORT_AGENT_NAMES.filter((name) => (
+    previous.includes(name)
+  ));
+  for (const name of ownedLegacy) {
+    const target = join(CLAUDE_AGENTS_DIR, name);
+    if (dryRun) {
+      process.stdout.write(`[dry-run] remove retired agent ${target}\n`);
+      continue;
+    }
+    try {
+      await fs.unlink(target);
+      if (!quiet) process.stdout.write(`  agents/${name}: removed retired wrapper\n`);
+    } catch (err) {
+      if (err.code !== "ENOENT") throw err;
+    }
+  }
+}
+
 async function writeRuntimeManifest(home, runtime, opts) {
   const { dryRun = false, resolution = null, installedAssets = null } = opts ?? {};
   const data = buildRuntimeManifest(
@@ -574,11 +604,7 @@ async function installAgentsLink(repoAbs, opts) {
   const { dryRun, quiet } = opts;
   const srcRoot = join(repoAbs, "agents", "workers");
   const sourceNames = await listWorkerFiles(srcRoot);
-  const renderedDefinitions = await renderWorkerAgentDefinitions(srcRoot);
-  const names = [
-    ...sourceNames,
-    ...renderedDefinitions.map(({ name }) => name),
-  ].sort();
+  const names = [...sourceNames].sort();
   if (names.length === 0) {
     if (!quiet) process.stdout.write("  agents: <repo>/agents/workers missing — skipped\n");
     return { installed: [] };
@@ -590,15 +616,6 @@ async function installAgentsLink(repoAbs, opts) {
     const action = await ensureSymlink(src, dst, { dryRun });
     if (!quiet) process.stdout.write(`  agents/${name}: ${action}\n`);
   }
-  for (const { name, content } of renderedDefinitions) {
-    const dst = join(CLAUDE_AGENTS_DIR, name);
-    if (dryRun) {
-      process.stdout.write(`[dry-run] render ${name} -> ${dst}\n`);
-    } else {
-      await writeFileAtomic(dst, content, 0o644);
-    }
-    if (!quiet) process.stdout.write(`  agents/${name}: rendered\n`);
-  }
   return { installed: names };
 }
 
@@ -900,6 +917,7 @@ export async function runInstall(args) {
 
   let agentResult = { installed: [] };
   if (skillTargets.some((target) => target.provider === "claude")) {
+    await pruneOwnedLegacyTransportAgents(paths.home, opts);
     agentResult = await installAgentsCopy(runtimeRoot, opts);
   }
   await writeAgentsManifest(paths.home, agentResult.installed, { dryRun: opts.dryRun });

package/src/commands/lifecycle/uninstall.mjs

@@ -11,6 +11,7 @@ import {
   AGENTS_MANIFEST_REL,
   INSTALLED_FILES,
   INSTALLED_TREES,
+  LEGACY_TRANSPORT_AGENT_NAMES,
   SKILLS_MANIFEST_REL,
 } from "../../lib/install-assets.mjs";
 
@@ -23,11 +24,11 @@ export const FALLBACK_SKILL_NAMES = [
   ...new Set([...USER_SKILL_NAMES, ...OBSOLETE_SKILL_NAMES]),
 ];
 
-const FALLBACK_AGENT_NAMES = [
+export const FALLBACK_AGENT_NAMES = [
   "claude-worker.md",
-  "codex-worker.md",
-  "antigravity-worker.md",
   "report-writer-worker.md",
+  "translator-worker.md",
+  ...LEGACY_TRANSPORT_AGENT_NAMES,
 ];
 
 const USER_HOME = homedir();

package/src/lib/install-assets.mjs

@@ -35,3 +35,12 @@ export const INSTALLED_FILES = [
 
 export const SKILLS_MANIFEST_REL = "installed-skills.json";
 export const AGENTS_MANIFEST_REL = "installed-agents.json";
+
+// Exact names of the retired LLM transport wrappers. Install removes an entry
+// only when the previous agent manifest proves that Okstra installed it.
+export const LEGACY_TRANSPORT_AGENT_NAMES = Object.freeze([
+  "codex-worker.md",
+  "antigravity-worker.md",
+  "grok-worker.md",
+  "kimi-worker.md",
+]);