@kal-elsam/kairo-runtime 0.7.0 → 0.8.0

package/src/global/adapters/pi.js

@@ -7,7 +7,7 @@ export const PI_CODING_AGENT_DIR_ENV = "PI_CODING_AGENT_DIR";
 
 const CUSTOM_DIR_MESSAGE =
   `Pi config writes are unsupported when ${PI_CODING_AGENT_DIR_ENV} points away from `
-  + `~/${PI_DEFAULT_ROOT_DIR} (out of scope for Kairo 0.6.0). `
+  + `~/${PI_DEFAULT_ROOT_DIR} (out of scope for Kairo managed config). `
   + `Unset ${PI_CODING_AGENT_DIR_ENV} to manage the default directory; runtime launches remain available.`;
 
 /** True when PI_CODING_AGENT_DIR is set to a non-default absolute/relative path. */

package/src/global/runtime/execution-adapters/pi.js

@@ -30,12 +30,15 @@ export function buildPiPermissionsArgs(permissions = []) {
   }
 
   throw new Error(
-    `Pi permissions only support "read-only" in Kairo 0.6.0 (got: ${permissions.join(", ")}). `
+    `Pi permissions only support "read-only" (got: ${permissions.join(", ")}). `
     + "Other aliases are rejected and are never translated to --approve."
   );
 }
 
-export function buildPiLaunch({ task, cwd, model, permissions = [], env = process.env } = {}) {
+export function buildPiLaunch({
+  task, cwd, model, permissions = [], env = process.env,
+  strategy = "direct", extensionPath = null
+} = {}) {
   const args = [
     "--mode",
     "json",
@@ -47,6 +50,13 @@ export function buildPiLaunch({ task, cwd, model, permissions = [], env = proces
     args.push("--model", model);
   }
 
+  if (strategy === "orchestrated") {
+    if (typeof extensionPath !== "string" || !extensionPath) {
+      throw new Error("Orchestrated Pi requires a managed extension path.");
+    }
+    args.push("--no-extensions", "--extension", extensionPath);
+  }
+
   args.push(task);
 
   return {

package/src/global/runtime/orchestration/index.js

@@ -0,0 +1,23 @@
+import { join } from "node:path";
+import { harnessHomePaths } from "../../paths.js";
+
+export {
+  RUN_STRATEGIES, DAG_NODE_STATES, DAG_TERMINAL_STATES, ORCH_LIMITS, ORCH_ERROR_CODES,
+  OrchContractError, createTaskId, isTerminalDagState, normalizeRunStrategy,
+  createOrchLineage, createBudgetUsage, createDagNode, createMinionBrief,
+  createMinionResult, digestAllowlisted
+} from "./orch-types.js";
+export { assertOrchReceiptSecretFree, FORBIDDEN_KEYS, walkForbiddenKeys } from "./orch-validate.js";
+export {
+  orchPaths, buildOrchReceipt, saveOrchReceipt, loadOrchReceipt,
+  createOrchState, saveOrchState, loadOrchState, terminalizeOrchNodes,
+  updateOrchState, applyMinionDagUpdate, finalizeOrchState, reconcileOrchState
+} from "./orch-receipts.js";
+
+export const KAIRO_MINION_RELATIVE_ASSET =
+  "components/orchestrator/extensions/pi/kairo-minion.js";
+
+/** Materialized extension path under ~/.harness (never Pi global auto-discover). */
+export function resolveKairoMinionExtensionPath(homeDir) {
+  return join(harnessHomePaths(homeDir).root, KAIRO_MINION_RELATIVE_ASSET);
+}

package/src/global/runtime/orchestration/orch-receipts.js

@@ -0,0 +1,234 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { runPaths } from "../../paths.js";
+import { writeAtomicJson } from "../write-atomic-json.js";
+import {
+  DAG_NODE_STATES, ORCH_ERROR_CODES, OrchContractError, RUN_STRATEGIES,
+  createBudgetUsage, createDagNode, createMinionResult, createOrchLineage,
+  digestAllowlisted, isTerminalDagState, normalizeRunStrategy
+} from "./orch-types.js";
+import { assertOrchReceiptSecretFree, walkForbiddenKeys } from "./orch-validate.js";
+
+export function orchPaths(homeDir, rootRunId) {
+  if (typeof rootRunId !== "string" || !rootRunId) {
+    throw new OrchContractError("rootRunId is required for orchestration paths.", {
+      code: ORCH_ERROR_CODES.INVALID_LINEAGE
+    });
+  }
+  const { runDir } = runPaths(homeDir, rootRunId);
+  const orchDir = join(runDir, "orchestration");
+  return {
+    runDir, orchDir,
+    receiptPath: join(orchDir, "receipt.json"),
+    statePath: join(orchDir, "state.json")
+  };
+}
+
+function normalizeNodes(nodes = []) {
+  return nodes.map((node) => {
+    const { objective, ...rest } = node;
+    return createDagNode({
+      ...rest,
+      budget: createBudgetUsage(rest.budget ?? {}),
+      objectiveDigest: rest.objectiveDigest
+        ?? (objective ? digestAllowlisted({ objective }) : null)
+    });
+  });
+}
+
+export function buildOrchReceipt({
+  rootRunId, strategy = RUN_STRATEGIES.ORCHESTRATED, lineage = null,
+  nodes = [], results = [], cliVersion = null, createdAt = null, recovered = false
+} = {}) {
+  const normalizedStrategy = normalizeRunStrategy(strategy);
+  const normalizedLineage = createOrchLineage(lineage ?? { rootRunId, parentRunId: null, depth: 0 });
+  if (normalizedLineage.rootRunId !== rootRunId) {
+    throw new OrchContractError("lineage.rootRunId must match receipt rootRunId.", {
+      code: ORCH_ERROR_CODES.INVALID_LINEAGE
+    });
+  }
+  return assertOrchReceiptSecretFree({
+    version: 1, strategy: normalizedStrategy, rootRunId, lineage: normalizedLineage,
+    nodes: normalizeNodes(nodes),
+    results: results.map((entry) => createMinionResult(entry)),
+    createdAt: createdAt ?? new Date().toISOString(),
+    cliVersion,
+    recovered: Boolean(recovered)
+  });
+}
+
+export async function saveOrchReceipt(receipt, { homeDir } = {}) {
+  const sanitized = assertOrchReceiptSecretFree(receipt);
+  const { orchDir, receiptPath } = orchPaths(homeDir, sanitized.rootRunId);
+  await mkdir(orchDir, { recursive: true });
+  try {
+    await writeAtomicJson(receiptPath, sanitized, { createExclusive: true });
+  } catch (error) {
+    if (error?.code === "EEXIST") {
+      throw new OrchContractError(`Orchestration receipt already exists: ${sanitized.rootRunId}`, {
+        code: ORCH_ERROR_CODES.RECEIPT_EXISTS,
+        details: { rootRunId: sanitized.rootRunId, path: receiptPath }
+      });
+    }
+    throw error;
+  }
+  return { path: receiptPath, receipt: sanitized };
+}
+
+export async function loadOrchReceipt(rootRunId, { homeDir } = {}) {
+  const { receiptPath } = orchPaths(homeDir, rootRunId);
+  if (!existsSync(receiptPath)) {
+    throw new OrchContractError(`Orchestration receipt not found: ${rootRunId}`, {
+      code: ORCH_ERROR_CODES.INVALID_LINEAGE, details: { rootRunId }
+    });
+  }
+  return assertOrchReceiptSecretFree(JSON.parse(await readFile(receiptPath, "utf8")));
+}
+
+export function createOrchState({
+  rootRunId, strategy = RUN_STRATEGIES.ORCHESTRATED, lineage = null,
+  nodes = [], results = [], cliVersion = null, updatedAt = null
+} = {}) {
+  const normalizedStrategy = normalizeRunStrategy(strategy);
+  if (normalizedStrategy !== RUN_STRATEGIES.ORCHESTRATED) {
+    throw new OrchContractError("Orchestration state requires strategy orchestrated.", {
+      code: ORCH_ERROR_CODES.INVALID_STRATEGY
+    });
+  }
+  const normalizedLineage = createOrchLineage(lineage ?? { rootRunId, parentRunId: null, depth: 0 });
+  if (normalizedLineage.rootRunId !== rootRunId) {
+    throw new OrchContractError("lineage.rootRunId must match state rootRunId.", {
+      code: ORCH_ERROR_CODES.INVALID_LINEAGE
+    });
+  }
+  const state = {
+    version: 1, strategy: normalizedStrategy, rootRunId, lineage: normalizedLineage,
+    nodes: normalizeNodes(nodes),
+    results: (results ?? []).map((entry) => createMinionResult(entry)),
+    cliVersion: cliVersion ?? null,
+    updatedAt: updatedAt ?? new Date().toISOString()
+  };
+  walkForbiddenKeys(state);
+  return state;
+}
+
+export async function saveOrchState(state, { homeDir } = {}) {
+  const sanitized = createOrchState(state);
+  const { orchDir, statePath } = orchPaths(homeDir, sanitized.rootRunId);
+  await mkdir(orchDir, { recursive: true });
+  await writeAtomicJson(statePath, sanitized);
+  return { path: statePath, state: sanitized };
+}
+
+export async function loadOrchState(rootRunId, { homeDir } = {}) {
+  const { statePath } = orchPaths(homeDir, rootRunId);
+  if (!existsSync(statePath)) {
+    throw new OrchContractError(`Orchestration state not found: ${rootRunId}`, {
+      code: ORCH_ERROR_CODES.INVALID_NODE, details: { rootRunId }
+    });
+  }
+  try {
+    return createOrchState(JSON.parse(await readFile(statePath, "utf8")));
+  } catch {
+    throw new OrchContractError(`Corrupt orchestration state: ${rootRunId}`, {
+      code: ORCH_ERROR_CODES.INVALID_NODE, details: { rootRunId }
+    });
+  }
+}
+
+export function terminalizeOrchNodes(nodes, { recovered = false } = {}) {
+  return (nodes ?? []).map((node) => {
+    if (isTerminalDagState(node.state)) return createDagNode(node);
+    return createDagNode({
+      ...node,
+      state: recovered ? DAG_NODE_STATES.CANCELLED : DAG_NODE_STATES.COMPLETED,
+      error: recovered ? (node.error ?? { code: "interrupted" }) : node.error
+    });
+  });
+}
+
+const orchWriteLocks = new Map();
+
+function withOrchWriteLock(rootRunId, work) {
+  const previous = orchWriteLocks.get(rootRunId) ?? Promise.resolve();
+  const next = previous.then(work);
+  orchWriteLocks.set(rootRunId, next.catch(() => {}));
+  return next;
+}
+
+/** Serialized load → mutate → save for concurrent minion DAG updates. */
+export async function updateOrchState(rootRunId, mutator, { homeDir } = {}) {
+  return withOrchWriteLock(rootRunId, async () => {
+    const current = await loadOrchState(rootRunId, { homeDir });
+    return saveOrchState(await mutator(current), { homeDir });
+  });
+}
+
+/** Upsert one depth-1 node by taskId; append/replace MinionResult on completed. */
+export async function applyMinionDagUpdate(rootRunId, {
+  homeDir, taskId, parentTaskId, attempt = 0, state,
+  objectiveDigest = null, result = null, error = null
+} = {}) {
+  return updateOrchState(rootRunId, (current) => {
+    const rootTaskId = current.lineage?.taskId;
+    if (!rootTaskId || taskId === rootTaskId || parentTaskId !== rootTaskId) {
+      throw new OrchContractError("Minion taskId/parentTaskId must honor supervisor rootTaskId.", {
+        code: ORCH_ERROR_CODES.INVALID_NODE, details: { taskId, parentTaskId, rootTaskId }
+      });
+    }
+    const node = createDagNode({
+      taskId, parentTaskId, depth: 1, state, attempt,
+      objectiveDigest: objectiveDigest ?? null, error: error ?? null
+    });
+    const nodes = [...current.nodes];
+    const idx = nodes.findIndex((entry) => entry.taskId === taskId);
+    if (idx >= 0) {
+      nodes[idx] = createDagNode({
+        ...nodes[idx], ...node,
+        objectiveDigest: node.objectiveDigest ?? nodes[idx].objectiveDigest
+      });
+    } else {
+      nodes.push(node);
+    }
+    let results = current.results;
+    if (state === DAG_NODE_STATES.COMPLETED && result) {
+      const sealed = createMinionResult(result);
+      results = [...results.filter((entry) => entry.taskId !== taskId), sealed];
+    }
+    return { ...current, nodes, results, updatedAt: new Date().toISOString() };
+  }, { homeDir });
+}
+
+export async function finalizeOrchState(rootRunId, { homeDir, recovered = false } = {}) {
+  return withOrchWriteLock(rootRunId, async () => {
+    const { receiptPath } = orchPaths(homeDir, rootRunId);
+    if (existsSync(receiptPath)) {
+      return { path: receiptPath, receipt: await loadOrchReceipt(rootRunId, { homeDir }), idempotent: true };
+    }
+    const state = await loadOrchState(rootRunId, { homeDir });
+    const nodes = terminalizeOrchNodes(state.nodes, { recovered });
+    await saveOrchState({ ...state, nodes, updatedAt: new Date().toISOString() }, { homeDir });
+    try {
+      const saved = await saveOrchReceipt(buildOrchReceipt({
+        rootRunId: state.rootRunId, strategy: state.strategy, lineage: state.lineage,
+        nodes, results: state.results, cliVersion: state.cliVersion, recovered
+      }), { homeDir });
+      return { ...saved, idempotent: false };
+    } catch (error) {
+      if (error?.code === ORCH_ERROR_CODES.RECEIPT_EXISTS) {
+        return { path: receiptPath, receipt: await loadOrchReceipt(rootRunId, { homeDir }), idempotent: true };
+      }
+      throw error;
+    }
+  });
+}
+
+export async function reconcileOrchState(rootRunId, { homeDir } = {}) {
+  const { statePath, receiptPath } = orchPaths(homeDir, rootRunId);
+  if (existsSync(receiptPath)) {
+    return { rootRunId, path: receiptPath, receipt: await loadOrchReceipt(rootRunId, { homeDir }), idempotent: true };
+  }
+  if (!existsSync(statePath)) return null;
+  return finalizeOrchState(rootRunId, { homeDir, recovered: true });
+}

package/src/global/runtime/orchestration/orch-types.js

@@ -0,0 +1,173 @@
+import { createHash, randomBytes } from "node:crypto";
+export const RUN_STRATEGIES = Object.freeze({ DIRECT: "direct", ORCHESTRATED: "orchestrated" });
+export const DAG_NODE_STATES = Object.freeze({
+  PENDING: "pending", READY: "ready", RUNNING: "running", COMPACTING: "compacting",
+  COMPLETED: "completed", FAILED: "failed", CANCELLED: "cancelled", BLOCKED: "blocked"
+});
+export const DAG_TERMINAL_STATES = new Set([
+  DAG_NODE_STATES.COMPLETED, DAG_NODE_STATES.FAILED, DAG_NODE_STATES.CANCELLED
+]);
+export const ORCH_LIMITS = Object.freeze({
+  MAX_DEPTH: 1, DEFAULT_CONCURRENCY: 2, MAX_ATTEMPTS: 2, COMPACT_RATIO: 0.7, STOP_RATIO: 0.9
+});
+export const ORCH_ERROR_CODES = Object.freeze({
+  INVALID_STRATEGY: "invalid_strategy", INVALID_DEPTH: "invalid_depth",
+  INVALID_LINEAGE: "invalid_lineage", INVALID_HANDOFF: "invalid_handoff",
+  INVALID_NODE: "invalid_node", LIMIT_EXCEEDED: "limit_exceeded",
+  FORBIDDEN_FIELD: "forbidden_field", RECEIPT_EXISTS: "receipt_exists"
+});
+export class OrchContractError extends Error {
+  constructor(message, { code, details = null } = {}) {
+    super(message);
+    this.name = "OrchContractError";
+    this.code = code;
+    this.details = details;
+  }
+}
+export function createTaskId() {
+  return `task_${randomBytes(8).toString("hex")}`;
+}
+export function isTerminalDagState(state) {
+  return DAG_TERMINAL_STATES.has(state);
+}
+
+function assertDepth(depth) {
+  const d = Number(depth);
+  if (!Number.isInteger(d) || d < 0) {
+    throw new OrchContractError(`Invalid depth "${depth}".`, {
+      code: ORCH_ERROR_CODES.INVALID_DEPTH, details: { depth }
+    });
+  }
+  if (d > ORCH_LIMITS.MAX_DEPTH) {
+    throw new OrchContractError(`Orchestration depth ${d} exceeds max ${ORCH_LIMITS.MAX_DEPTH}.`, {
+      code: ORCH_ERROR_CODES.INVALID_DEPTH, details: { depth: d }
+    });
+  }
+  return d;
+}
+
+function assertParentForDepth(depth, parentId, { rootMsg, minionMsg, code }) {
+  if (depth === 0 && parentId != null) {
+    throw new OrchContractError(rootMsg, { code });
+  }
+  if (depth > 0 && !parentId) {
+    throw new OrchContractError(minionMsg, { code });
+  }
+}
+
+export function normalizeRunStrategy(value = RUN_STRATEGIES.DIRECT) {
+  const strategy = String(value ?? RUN_STRATEGIES.DIRECT).trim().toLowerCase();
+  if (!Object.values(RUN_STRATEGIES).includes(strategy)) {
+    throw new OrchContractError(`Invalid run strategy "${value}". Use direct or orchestrated.`, {
+      code: ORCH_ERROR_CODES.INVALID_STRATEGY, details: { value }
+    });
+  }
+  return strategy;
+}
+
+/** Lineage: max depth 1 (root=0, minion=1). */
+export function createOrchLineage({ rootRunId, parentRunId = null, taskId = null, depth = 0 } = {}) {
+  if (typeof rootRunId !== "string" || !rootRunId) {
+    throw new OrchContractError("rootRunId is required.", { code: ORCH_ERROR_CODES.INVALID_LINEAGE });
+  }
+  const d = assertDepth(depth);
+  assertParentForDepth(d, parentRunId, {
+    rootMsg: "Root nodes must not set parentRunId.",
+    minionMsg: "Minion nodes require parentRunId.",
+    code: ORCH_ERROR_CODES.INVALID_LINEAGE
+  });
+  return { rootRunId, parentRunId: parentRunId ?? null, taskId: taskId ?? createTaskId(), depth: d };
+}
+
+export function createBudgetUsage({
+  contextTokens = 0, contextLimit = 0,
+  compactRatio = ORCH_LIMITS.COMPACT_RATIO, stopRatio = ORCH_LIMITS.STOP_RATIO
+} = {}) {
+  const tokens = Math.max(0, Number(contextTokens) || 0);
+  const limit = Math.max(0, Number(contextLimit) || 0);
+  const ratio = limit > 0 ? tokens / limit : 0;
+  return {
+    contextTokens: tokens, contextLimit: limit, ratio,
+    shouldCompact: limit > 0 && ratio >= compactRatio && ratio < stopRatio,
+    shouldStop: limit > 0 && ratio >= stopRatio
+  };
+}
+
+export function createDagNode({
+  taskId = null, runId = null, parentTaskId = null, depth = 0,
+  state = DAG_NODE_STATES.PENDING, dependsOn = [], attempt = 0,
+  objectiveDigest = null, budget = null, resultDigest = null, error = null
+} = {}) {
+  if (!Object.values(DAG_NODE_STATES).includes(state)) {
+    throw new OrchContractError(`Invalid DAG node state "${state}".`, {
+      code: ORCH_ERROR_CODES.INVALID_NODE, details: { state }
+    });
+  }
+  const d = assertDepth(depth);
+  assertParentForDepth(d, parentTaskId, {
+    rootMsg: "Root nodes must not set parentTaskId.",
+    minionMsg: "Minion nodes require parentTaskId.",
+    code: ORCH_ERROR_CODES.INVALID_NODE
+  });
+  const attempts = Number(attempt) || 0;
+  if (attempts < 0 || attempts > ORCH_LIMITS.MAX_ATTEMPTS) {
+    throw new OrchContractError(`Attempt ${attempts} outside 0..${ORCH_LIMITS.MAX_ATTEMPTS}.`, {
+      code: ORCH_ERROR_CODES.LIMIT_EXCEEDED, details: { attempt: attempts }
+    });
+  }
+  const deps = [...new Set((dependsOn ?? []).map((id) => {
+    if (typeof id !== "string" || !id) {
+      throw new OrchContractError("Dependency taskId is required.", { code: ORCH_ERROR_CODES.INVALID_NODE });
+    }
+    return id;
+  }))];
+  return {
+    taskId: taskId ?? createTaskId(), runId: runId ?? null, parentTaskId: parentTaskId ?? null,
+    depth: d, state, dependsOn: deps, attempt: attempts,
+    objectiveDigest, budget: budget ?? null, resultDigest, error: error ?? null
+  };
+}
+
+export function createMinionBrief({
+  objective, constraints = [], admittedPaths = [], exitCriteria = [],
+  parentTaskId = null, taskId = null
+} = {}) {
+  if (typeof objective !== "string" || !objective.trim()) {
+    throw new OrchContractError("Minion brief requires a non-empty objective.", {
+      code: ORCH_ERROR_CODES.INVALID_HANDOFF
+    });
+  }
+  return {
+    taskId: taskId ?? createTaskId(), parentTaskId: parentTaskId ?? null,
+    objective: objective.trim(), constraints: (constraints ?? []).map(String),
+    admittedPaths: (admittedPaths ?? []).map(String), exitCriteria: (exitCriteria ?? []).map(String)
+  };
+}
+
+export function createMinionResult({
+  taskId = null, summary, decisions = [], files = [], risks = [],
+  evidence = [], usage = null, compact = false
+} = {}) {
+  if (typeof taskId !== "string" || !taskId) {
+    throw new OrchContractError("Minion result requires taskId.", { code: ORCH_ERROR_CODES.INVALID_HANDOFF });
+  }
+  if (typeof summary !== "string" || !summary.trim()) {
+    throw new OrchContractError("Minion result requires a non-empty summary.", {
+      code: ORCH_ERROR_CODES.INVALID_HANDOFF
+    });
+  }
+  return {
+    taskId, summary: summary.trim(),
+    decisions: (decisions ?? []).map(String), files: (files ?? []).map(String),
+    risks: (risks ?? []).map(String), evidence: (evidence ?? []).map(String),
+    usage: {
+      inputTokens: usage?.inputTokens ?? null, outputTokens: usage?.outputTokens ?? null,
+      totalTokens: usage?.totalTokens ?? null, cost: usage?.cost ?? null
+    },
+    compact: Boolean(compact)
+  };
+}
+
+export function digestAllowlisted(value) {
+  return createHash("sha256").update(JSON.stringify(value)).digest("hex").slice(0, 16);
+}

package/src/global/runtime/orchestration/orch-validate.js

@@ -0,0 +1,63 @@
+import {
+  ORCH_ERROR_CODES, OrchContractError, createBudgetUsage, createDagNode,
+  createMinionResult, createOrchLineage, normalizeRunStrategy
+} from "./orch-types.js";
+export const FORBIDDEN_KEYS = new Set([
+  "prompt", "diff", "transcript", "raw", "rawOutput", "stdout", "stderr", "output",
+  "message", "messages", "content", "secret", "secrets", "token", "apiKey",
+  "conversation", "history", "toolArgs", "arguments", "objective"
+]);
+export function walkForbiddenKeys(value, path = "") {
+  if (!value || typeof value !== "object") return;
+  if (Array.isArray(value)) {
+    value.forEach((item, i) => walkForbiddenKeys(item, `${path}[${i}]`));
+    return;
+  }
+  for (const [key, child] of Object.entries(value)) {
+    if (FORBIDDEN_KEYS.has(key)) {
+      throw new OrchContractError(`Forbidden field "${path}${key}" in orchestration receipt.`, {
+        code: ORCH_ERROR_CODES.FORBIDDEN_FIELD, details: { key, path }
+      });
+    }
+    walkForbiddenKeys(child, `${path}${key}.`);
+  }
+}
+export function assertOrchReceiptSecretFree(receipt) {
+  if (!receipt || typeof receipt !== "object" || Array.isArray(receipt)) {
+    throw new OrchContractError("Invalid orchestration receipt: expected object.", {
+      code: ORCH_ERROR_CODES.FORBIDDEN_FIELD
+    });
+  }
+  walkForbiddenKeys(receipt);
+  if (receipt.version !== 1) {
+    throw new OrchContractError("Orchestration receipt version must be 1.", {
+      code: ORCH_ERROR_CODES.FORBIDDEN_FIELD
+    });
+  }
+  normalizeRunStrategy(receipt.strategy);
+  if (typeof receipt.rootRunId !== "string" || !receipt.rootRunId) {
+    throw new OrchContractError("rootRunId is required on receipt.", {
+      code: ORCH_ERROR_CODES.INVALID_LINEAGE
+    });
+  }
+  createOrchLineage(receipt.lineage);
+  if (receipt.lineage.rootRunId !== receipt.rootRunId) {
+    throw new OrchContractError("lineage.rootRunId must match receipt.rootRunId.", {
+      code: ORCH_ERROR_CODES.INVALID_LINEAGE
+    });
+  }
+  if (!Array.isArray(receipt.nodes) || !Array.isArray(receipt.results)) {
+    throw new OrchContractError("Receipt requires nodes[] and results[].", {
+      code: ORCH_ERROR_CODES.INVALID_NODE
+    });
+  }
+  for (const node of receipt.nodes) {
+    createDagNode(node);
+    if (node.budget) createBudgetUsage(node.budget);
+  }
+  for (const result of receipt.results) createMinionResult(result);
+  if (typeof receipt.createdAt !== "string" || !receipt.createdAt) {
+    throw new OrchContractError("createdAt is required.", { code: ORCH_ERROR_CODES.FORBIDDEN_FIELD });
+  }
+  return receipt;
+}

package/src/global/runtime/run-cli.js

@@ -45,6 +45,7 @@ export async function runGlobalRun(options, packageManifest, { startRunImpl = st
     captureTranscript,
     cliVersion: packageManifest.version,
     profile: profileResolved,
+    strategy: options.strategy ?? "direct",
     follow: options.follow,
     timeoutMs: options.timeoutMs,
     wait: options.wait !== false

package/src/global/runtime/run-manager.js

@@ -5,6 +5,7 @@ import {
   appendRunEvent,
   appendRunStartedEvent,
   createRunRecord,
+  listRunRecords,
   readRunState,
   reconcileActiveRuns,
   writeRunState
@@ -22,6 +23,20 @@ import {
   readSupervisorLockForRun,
   supervisePreparedRun
 } from "./run-supervisor.js";
+import {
+  assertManagedMinionExtension,
+  assertOrchestratedAgent,
+  createRootRunLineage,
+  normalizeRunStrategy,
+  RUN_STRATEGIES
+} from "./run-strategy.js";
+import {
+  DAG_NODE_STATES,
+  createDagNode,
+  createOrchState,
+  reconcileOrchState,
+  saveOrchState
+} from "./orchestration/index.js";
 
 const activeProcesses = new Map();
 const cancelledRuns = new Set();
@@ -55,6 +70,19 @@ export async function recoverRuns(homeDir) {
     exceptRunIds: listActiveRunIds(),
     isRunAliveImpl: isRunSupervisedAlive
   });
+  for (const run of await listRunRecords(homeDir)) {
+    if (normalizeRunStrategy(run.strategy ?? RUN_STRATEGIES.DIRECT) !== RUN_STRATEGIES.ORCHESTRATED) {
+      continue;
+    }
+    if (await isRunSupervisedAlive(homeDir, run)) {
+      continue;
+    }
+    try {
+      await reconcileOrchState(run.runId, { homeDir });
+    } catch {
+      // Fail closed per root: never invent receipt evidence from corrupt state.
+    }
+  }
   return interrupted;
 }
 
@@ -67,8 +95,10 @@ async function prepareRun({
   permissions = [],
   captureTranscript = false,
   cliVersion,
-  profile = null
+  profile = null,
+  strategy = "direct"
 }) {
+  const normalizedStrategy = assertOrchestratedAgent(agentId, strategy);
   const adapter = resolveExecutionAdapter(agentId);
   const availability = adapter.availability({ cwd });
 
@@ -83,7 +113,12 @@ async function prepareRun({
     );
   }
 
+  if (normalizedStrategy === RUN_STRATEGIES.ORCHESTRATED) {
+    await assertManagedMinionExtension(homeDir);
+  }
+
   const runId = createRunId();
+  const lineage = createRootRunLineage(runId);
   const metadata = createRunMetadata({
     runId,
     agentId,
@@ -94,7 +129,9 @@ async function prepareRun({
     permissions,
     captureTranscript,
     cliVersion,
-    profileSources: profile?.sources ?? null
+    profileSources: profile?.sources ?? null,
+    strategy: normalizedStrategy,
+    lineage
   });
 
   await createRunRecord(homeDir, metadata);
@@ -107,9 +144,25 @@ async function prepareRun({
     permissions,
     captureTranscript,
     cliVersion,
-    profile: profile?.profile ?? null
+    profile: profile?.profile ?? null,
+    strategy: normalizedStrategy
   });
 
+  if (normalizedStrategy === RUN_STRATEGIES.ORCHESTRATED) {
+    await saveOrchState(createOrchState({
+      rootRunId: runId,
+      strategy: normalizedStrategy,
+      lineage,
+      nodes: [createDagNode({
+        taskId: lineage.taskId,
+        runId,
+        depth: 0,
+        state: DAG_NODE_STATES.RUNNING
+      })],
+      cliVersion
+    }), { homeDir });
+  }
+
   return { runId, metadata };
 }
 
@@ -123,6 +176,7 @@ export async function startRun({
   captureTranscript = false,
   cliVersion,
   profile = null,
+  strategy = "direct",
   follow = false,
   timeoutMs = null,
   wait = true,
@@ -138,7 +192,8 @@ export async function startRun({
     permissions,
     captureTranscript,
     cliVersion,
-    profile
+    profile,
+    strategy: normalizeRunStrategy(strategy)
   });
 
   if (!wait) {