@kal-elsam/kairo-runtime 0.7.0 → 0.9.0

package/src/global/runtime/monitor/monitor-platform.js

@@ -0,0 +1,95 @@
+import { existsSync } from "node:fs";
+import { mkdir, unlink, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { execFile as execFileCb } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFile = promisify(execFileCb);
+export const MONITOR_LABEL = "local.kairo.monitor";
+
+export function resolveMonitorPlatform(platform = process.platform) {
+  if (platform === "darwin") {
+    const agentsDir = join(homedir(), "Library", "LaunchAgents");
+    return {
+      id: "darwin", supportsAutostart: true, supportsNotify: true,
+      agentsDir, plistPath: join(agentsDir, `${MONITOR_LABEL}.plist`)
+    };
+  }
+  return { id: platform, supportsAutostart: false, supportsNotify: platform === "linux" };
+}
+
+function gui() { return `gui/${process.getuid?.() ?? 501}`; }
+
+function plist({ nodePath, cliEntry, homeDir, intervalSec }) {
+  const e = (v) => String(v).replaceAll("&", "&amp;").replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;").replaceAll("\"", "&quot;");
+  const log = join(homeDir, ".harness", "monitor");
+  const n = Math.max(60, Number(intervalSec) || 300);
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+<key>Label</key><string>${MONITOR_LABEL}</string>
+<key>ProgramArguments</key><array><string>${e(nodePath)}</string><string>${e(cliEntry)}</string><string>monitor</string><string>tick</string></array>
+<key>StartInterval</key><integer>${n}</integer><key>RunAtLoad</key><true/>
+<key>EnvironmentVariables</key><dict><key>HARNESS_HOME</key><string>${e(homeDir)}</string></dict>
+<key>StandardOutPath</key><string>${e(join(log, "out.log"))}</string>
+<key>StandardErrorPath</key><string>${e(join(log, "err.log"))}</string>
+</dict></plist>`;
+}
+
+export async function notifyNewAlert({
+  title, body, platform = resolveMonitorPlatform(), execFileImpl = execFile
+} = {}) {
+  const t = String(title ?? "Kairo").slice(0, 80);
+  const b = String(body ?? "").slice(0, 180).replace(/[\r\n]+/g, " ");
+  try {
+    if (platform.id === "darwin") {
+      await execFileImpl("osascript", [
+        "-e", `display notification ${JSON.stringify(b)} with title ${JSON.stringify(t)}`
+      ], { shell: false, timeout: 5000 });
+      return { sent: true };
+    }
+    if (platform.id === "linux") {
+      await execFileImpl("notify-send", [t, b], { shell: false, timeout: 5000 });
+      return { sent: true };
+    }
+  } catch { /* degrade */ }
+  return { sent: false };
+}
+
+export async function installAutostart({
+  homeDir, platform = resolveMonitorPlatform(), nodePath, cliEntry,
+  intervalSec = 300, execFileImpl = execFile
+} = {}) {
+  if (!platform.supportsAutostart) {
+    return {
+      supported: false, configured: false, loaded: false, installed: false,
+      detail: `unsupported on ${platform.id}`
+    };
+  }
+  await mkdir(platform.agentsDir, { recursive: true });
+  await mkdir(join(homeDir, ".harness", "monitor"), { recursive: true });
+  await writeFile(platform.plistPath, plist({ nodePath, cliEntry, homeDir, intervalSec }));
+  try {
+    await execFileImpl("launchctl", ["bootout", `${gui()}/${MONITOR_LABEL}`], { shell: false }).catch(() => {});
+    await execFileImpl("launchctl", ["bootstrap", gui(), platform.plistPath], { shell: false });
+    return { supported: true, configured: true, loaded: true, installed: true, detail: "LaunchAgent loaded" };
+  } catch (error) {
+    return {
+      supported: true, configured: true, loaded: false, installed: false,
+      detail: `plist configured; not loaded (${error?.message ?? error})`
+    };
+  }
+}
+
+export async function removeAutostart({
+  platform = resolveMonitorPlatform(), execFileImpl = execFile
+} = {}) {
+  if (!platform.supportsAutostart) {
+    return { supported: false, configured: false, loaded: false, installed: false };
+  }
+  await execFileImpl("launchctl", ["bootout", `${gui()}/${MONITOR_LABEL}`], { shell: false }).catch(() => {});
+  if (platform.plistPath && existsSync(platform.plistPath)) await unlink(platform.plistPath).catch(() => {});
+  return { supported: true, configured: false, loaded: false, installed: false };
+}

package/src/global/runtime/monitor/monitor.js

@@ -0,0 +1,249 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile } from "node:fs/promises";
+import { harnessHomePaths } from "../../paths.js";
+import { detectGlobalDrift, hasRepairableDrift } from "../../drift.js";
+import { writeAtomicJson } from "../write-atomic-json.js";
+import { listAlerts, saveAlert } from "../alerts/alert-store.js";
+import { ALERT_SEVERITIES, ALERT_STATES } from "../alerts/alert-types.js";
+import { listRunRecords } from "../run-store.js";
+import { isRunAlive } from "../run-liveness.js";
+import { RUN_STATES, isActiveRunState } from "../run-types.js";
+import {
+  installAutostart, notifyNewAlert, removeAutostart, resolveMonitorPlatform
+} from "./monitor-platform.js";
+
+export {
+  installAutostart, notifyNewAlert, removeAutostart, resolveMonitorPlatform
+} from "./monitor-platform.js";
+
+const SOURCE = "monitor";
+const INTERVAL = 300;
+
+export class MonitorStateError extends Error {
+  constructor(message, { code = "corrupt_monitor_state" } = {}) {
+    super(message);
+    this.name = "MonitorStateError";
+    this.code = code;
+  }
+}
+
+export function defaultMonitorState() {
+  return {
+    version: 1, enabled: false, intervalSec: INTERVAL,
+    lastTickAt: null, lastTick: null,
+    autostart: {
+      platform: null, installed: false, supported: false, configured: false, loaded: false
+    },
+    updatedAt: null
+  };
+}
+
+function assertMonitorState(raw) {
+  if (!raw || typeof raw !== "object" || raw.version !== 1 || typeof raw.enabled !== "boolean") {
+    throw new MonitorStateError("Monitor state schema invalid.");
+  }
+  if (!Number.isFinite(raw.intervalSec) || raw.intervalSec < 1) {
+    throw new MonitorStateError("Monitor state.intervalSec invalid.");
+  }
+  const a = raw.autostart;
+  if (!a || typeof a !== "object"
+    || typeof a.supported !== "boolean"
+    || typeof a.configured !== "boolean"
+    || typeof a.loaded !== "boolean"
+    || typeof a.installed !== "boolean") {
+    throw new MonitorStateError("Monitor state.autostart invalid.");
+  }
+  if (a.loaded && !a.configured) {
+    throw new MonitorStateError("Monitor state.autostart loaded requires configured.");
+  }
+  if (a.installed !== a.loaded) {
+    throw new MonitorStateError("Monitor state.autostart installed must equal loaded.");
+  }
+  if (!a.supported && (a.configured || a.loaded || a.installed)) {
+    throw new MonitorStateError("Monitor state.autostart unsupported with lifecycle flags.");
+  }
+  if (!raw.enabled && (a.configured || a.loaded || a.installed)) {
+    throw new MonitorStateError("Monitor disabled with active autostart lifecycle.");
+  }
+  return {
+    ...defaultMonitorState(),
+    ...raw,
+    version: 1,
+    enabled: raw.enabled,
+    intervalSec: raw.intervalSec,
+    autostart: { ...defaultMonitorState().autostart, ...a }
+  };
+}
+
+export async function readMonitorState(homeDir, { repair = false } = {}) {
+  const path = harnessHomePaths(homeDir).monitorStatePath;
+  if (!existsSync(path)) return defaultMonitorState();
+  try {
+    return assertMonitorState(JSON.parse(await readFile(path, "utf8")));
+  } catch (error) {
+    if (repair) return defaultMonitorState();
+    if (error instanceof MonitorStateError) throw error;
+    throw new MonitorStateError("Monitor state unreadable.");
+  }
+}
+
+export async function writeMonitorState(homeDir, patch, { repair = false } = {}) {
+  const { monitorDir, monitorStatePath } = harnessHomePaths(homeDir);
+  await mkdir(monitorDir, { recursive: true });
+  const next = {
+    ...await readMonitorState(homeDir, { repair }), ...patch,
+    updatedAt: new Date().toISOString()
+  };
+  await writeAtomicJson(monitorStatePath, next);
+  return next;
+}
+
+async function raise(homeDir, input, notifyImpl) {
+  const result = await saveAlert({ ...input, source: SOURCE }, { homeDir });
+  if (!result.deduped) {
+    await notifyImpl({ title: "Kairo", body: `${result.alert.severity} · ${result.alert.title}` });
+  }
+  return result;
+}
+
+function autostartRecord(platform, a) {
+  return {
+    platform: platform.id, supported: a.supported,
+    configured: Boolean(a.configured), loaded: Boolean(a.loaded),
+    installed: Boolean(a.loaded), detail: a.detail ?? null
+  };
+}
+
+export async function runMonitorTick(homeDir, deps = {}) {
+  const {
+    notifyImpl = notifyNewAlert, detectDriftImpl = detectGlobalDrift,
+    listRunsImpl = listRunRecords, isRunAliveImpl = isRunAlive,
+    packageRoot = null, workspaceRoot = null
+  } = deps;
+  const raised = [];
+  await mkdir(harnessHomePaths(homeDir).monitorDir, { recursive: true });
+  try {
+    const paths = harnessHomePaths(homeDir);
+    const state = existsSync(paths.statePath)
+      ? JSON.parse(await readFile(paths.statePath, "utf8")) : null;
+    if (hasRepairableDrift(await detectDriftImpl({
+      homeDir, paths, state, packageRoot, workspaceRoot, context: { homeDir }
+    }))) {
+      raised.push(await raise(homeDir, {
+        kind: "monitor.drift", title: "Managed configuration drift",
+        summary: "Managed configs drifted. Run kairo sync.", severity: ALERT_SEVERITIES.HIGH
+      }, notifyImpl));
+    }
+  } catch {
+    raised.push(await raise(homeDir, {
+      kind: "monitor.drift", title: "Governance scan unavailable",
+      summary: "Monitor could not complete the drift scan.", severity: ALERT_SEVERITIES.MEDIUM
+    }, notifyImpl));
+  }
+
+  let runsOk = true; let dead = 0; let failed = 0;
+  try {
+    for (const run of await listRunsImpl(homeDir, { limit: 40 })) {
+      if (isActiveRunState(run.state) && !(await isRunAliveImpl(homeDir, run))) dead += 1;
+      if (run.state === RUN_STATES.FAILED) failed += 1;
+    }
+  } catch {
+    runsOk = false;
+    raised.push(await raise(homeDir, {
+      kind: "monitor.runs-unavailable", title: "Run monitoring unavailable",
+      summary: "Monitor could not inspect agent run health this tick.",
+      severity: ALERT_SEVERITIES.MEDIUM
+    }, notifyImpl));
+  }
+  if (runsOk && dead > 0) {
+    raised.push(await raise(homeDir, {
+      kind: "run.orphaned", title: "Orphaned agent run",
+      summary: `${dead} active run(s) have no live process.`, severity: ALERT_SEVERITIES.HIGH
+    }, notifyImpl));
+  }
+  if (runsOk && failed > 0) {
+    raised.push(await raise(homeDir, {
+      kind: "run.failed", title: "Agent run failed",
+      summary: `${failed} failed run(s) need attention.`, severity: ALERT_SEVERITIES.MEDIUM
+    }, notifyImpl));
+  }
+
+  const lastTick = {
+    raised: raised.length,
+    created: raised.filter((r) => !r.deduped).length,
+    deduped: raised.filter((r) => r.deduped).length,
+    complete: runsOk, runs: runsOk ? "ok" : "unavailable"
+  };
+  return {
+    state: await writeMonitorState(homeDir, {
+      lastTickAt: new Date().toISOString(), lastTick
+    }),
+    raised
+  };
+}
+
+export async function enableMonitor(homeDir, {
+  cliEntry, nodePath = process.execPath, platform = resolveMonitorPlatform(), intervalSec = INTERVAL
+} = {}) {
+  const autostart = await installAutostart({ homeDir, platform, nodePath, cliEntry, intervalSec });
+  try {
+    return await writeMonitorState(homeDir, {
+      enabled: true, intervalSec, autostart: autostartRecord(platform, autostart)
+    }, { repair: true });
+  } catch (error) {
+    if (autostart.loaded) await removeAutostart({ platform });
+    throw error;
+  }
+}
+
+export async function disableMonitor(homeDir, { platform = resolveMonitorPlatform() } = {}) {
+  return writeMonitorState(homeDir, {
+    enabled: false, autostart: autostartRecord(platform, await removeAutostart({ platform }))
+  }, { repair: true });
+}
+
+export async function getMonitorStatus(homeDir, { platform = resolveMonitorPlatform() } = {}) {
+  try {
+    const state = await readMonitorState(homeDir);
+    let openAlerts = 0;
+    try {
+      openAlerts = (await listAlerts({ homeDir, state: ALERT_STATES.OPEN })).length;
+    } catch { openAlerts = null; }
+    return {
+      available: true, corrupt: false, enabled: state.enabled, intervalSec: state.intervalSec,
+      lastTickAt: state.lastTickAt, lastTick: state.lastTick, autostart: state.autostart,
+      platform: platform.id,
+      notify: { supported: platform.supportsNotify, backend: platform.id }, openAlerts
+    };
+  } catch (error) {
+    if (error?.code !== "corrupt_monitor_state") throw error;
+    return {
+      available: false, corrupt: true, enabled: null, intervalSec: null,
+      lastTickAt: null, lastTick: null, autostart: null, platform: platform.id,
+      notify: { supported: platform.supportsNotify, backend: platform.id },
+      openAlerts: null, error: error.message
+    };
+  }
+}
+
+export async function monitorDoctorCheck(homeDir) {
+  const s = await getMonitorStatus(homeDir);
+  if (s.corrupt || s.available === false) {
+    return {
+      name: "monitor", status: "stale", category: "monitor",
+      detail: "corrupt state — run kairo monitor disable to repair"
+    };
+  }
+  if (s.enabled && s.autostart?.supported && !s.autostart?.loaded) {
+    return {
+      name: "monitor", status: "stale", category: "monitor",
+      detail: "enabled but autostart not loaded"
+    };
+  }
+  return {
+    name: "monitor", status: "ok", category: "monitor",
+    detail: s.enabled
+      ? `enabled · last ${s.lastTickAt ?? "none"} · autostart ${s.autostart?.loaded ? "loaded" : "off"}`
+      : "disabled (opt-in · kairo monitor enable)"
+  };
+}

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 });
+}