@kal-elsam/kairo-runtime 0.4.3 → 0.5.0

package/src/global/ink/use-orchestrator-data.js

@@ -1,5 +1,6 @@
-import { useEffect, useState } from "react";
+import { useEffect, useMemo, useState } from "react";
 import { buildReadOnlyDiagnostics } from "../action-planner.js";
+import { buildControlPlaneSnapshot } from "../control-plane-snapshot.js";
 import { buildRuntimeDashboardData } from "../runtime/run-cli.js";
 import { readRunEvents } from "../runtime/run-store.js";
 import { startRun, stopRun } from "../runtime/run-manager.js";
@@ -10,6 +11,28 @@ import {
   resolveLaunchableAgents
 } from "./orchestrator-state.js";
 import { LAUNCH_WIZARD_STEPS, ORCHESTRATOR_VIEWS } from "./orchestrator-state.js";
+import {
+  CONTROL_PLANE_AUTO_SCAN,
+  createSerializedReloader,
+  loadCockpitScanBundle
+} from "./cockpit-scan.js";
+import {
+  CHANGES_PHASE,
+  createChangesActionState,
+  reduceChangesAction
+} from "./cockpit-changes.js";
+import {
+  applyGovernanceSync,
+  previewGovernanceSync,
+  applyGovernanceRollback,
+  previewGovernanceRollback
+} from "../governance-actions.js";
+import {
+  RECOVERY_PHASE,
+  createRecoveryActionState,
+  listRecoverySnapshots,
+  reduceRecoveryAction
+} from "./cockpit-recovery.js";
 
 export function useOrchestratorData({
   homeDir,
@@ -20,9 +43,11 @@ export function useOrchestratorData({
 }) {
   const [loading, setLoading] = useState(true);
   const [busy, setBusy] = useState(false);
+  const [retrying, setRetrying] = useState(false);
   const [error, setError] = useState(null);
   const [dashboard, setDashboard] = useState(null);
   const [diagnostics, setDiagnostics] = useState(null);
+  const [snapshot, setSnapshot] = useState(null);
   const [selectedRun, setSelectedRun] = useState(null);
   const [selectedEvents, setSelectedEvents] = useState([]);
   const [statusMessage, setStatusMessage] = useState(null);
@@ -30,27 +55,50 @@ export function useOrchestratorData({
   const [launchStep, setLaunchStep] = useState(LAUNCH_WIZARD_STEPS.AGENT);
   const [launchDraft, setLaunchDraft] = useState(createLaunchDraft);
   const [launchPermissionIndex, setLaunchPermissionIndex] = useState(0);
+  const [changesAction, setChangesAction] = useState(createChangesActionState);
+  const [recoveryAction, setRecoveryAction] = useState(createRecoveryActionState);
+
+  const serializedReload = useMemo(() => createSerializedReloader(() => loadCockpitScanBundle({
+    homeDir,
+    workspaceRoot,
+    packageName,
+    packageRoot,
+    cliVersion,
+    buildDashboard: buildRuntimeDashboardData,
+    buildDiagnostics: buildReadOnlyDiagnostics,
+    buildSnapshot: buildControlPlaneSnapshot
+  })), [homeDir, workspaceRoot, packageName, packageRoot, cliVersion]);
+
+  const reload = async ({ showLoading = false, asRetry = false } = {}) => {
+    if (showLoading) setLoading(true);
+    if (asRetry) setRetrying(true);
+    const outcome = await serializedReload();
+    // Keep retrying=true across stale completions so overlapping retries don't clear too early.
+    if (outcome.stale) return outcome;
+
+    if (outcome.error) {
+      setError(outcome.error instanceof Error ? outcome.error.message : String(outcome.error));
+      setLoading(false);
+      setRetrying(false);
+      throw outcome.error;
+    }
 
-  const reload = async () => {
-    const [dash, diag] = await Promise.all([
-      buildRuntimeDashboardData({ homeDir, workspaceRoot, cliVersion }),
-      buildReadOnlyDiagnostics({ homeDir, workspaceRoot, packageName, packageRoot, cliVersion })
-    ]);
-    setDashboard(dash);
-    setDiagnostics(diag);
+    setDashboard(outcome.result.dashboard);
+    setDiagnostics(outcome.result.diagnostics);
+    setSnapshot(outcome.result.snapshot);
+    setError(null);
+    setLoading(false);
+    setRetrying(false);
+    return outcome;
   };
 
   useEffect(() => {
     let cancelled = false;
     async function load() {
       try {
-        await reload();
+        await reload({ showLoading: true });
+      } catch {
         if (!cancelled) setLoading(false);
-      } catch (loadError) {
-        if (!cancelled) {
-          setError(loadError instanceof Error ? loadError.message : String(loadError));
-          setLoading(false);
-        }
       }
     }
     load();
@@ -105,8 +153,8 @@ export function useOrchestratorData({
         .runs.find((entry) => entry.runId === runId);
       setStatusMessage(`Run started: ${runId}`);
       resetLaunchWizard();
-      dispatch({ type: "set-view", view: ORCHESTRATOR_VIEWS.HOME });
-      if (run) await openRunDetail(run, dispatch);
+      dispatch({ type: "set-view", view: ORCHESTRATOR_VIEWS.RUNS });
+      if (run) await openRunDetail(run, dispatch, ORCHESTRATOR_VIEWS.ACTIVE_RUNS);
     } catch (launchError) {
       setError(launchError instanceof Error ? launchError.message : String(launchError));
     } finally {
@@ -133,13 +181,175 @@ export function useOrchestratorData({
     }
   };
 
+  const previewChanges = async () => {
+    setChangesAction((prev) => reduceChangesAction(prev, { type: "preview-start" }));
+    setBusy(true);
+    try {
+      const preview = await previewGovernanceSync({
+        homeDir, workspaceRoot, packageName, packageRoot, cliVersion
+      });
+      setChangesAction((prev) => reduceChangesAction(prev, { type: "preview-ready", preview }));
+      return preview;
+    } catch (previewError) {
+      const message = previewError instanceof Error ? previewError.message : String(previewError);
+      setChangesAction((prev) => reduceChangesAction(prev, {
+        type: "preview-failed", error: "preview-failed", message
+      }));
+      return null;
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const cancelChanges = () => {
+    setChangesAction((prev) => reduceChangesAction(prev, { type: "cancel" }));
+    setStatusMessage("Cancelled — no files written.");
+  };
+
+  const confirmApplyChanges = async () => {
+    let preview = null;
+    setChangesAction((prev) => {
+      if (prev.phase !== CHANGES_PHASE.CONFIRMING || !prev.preview) return prev;
+      preview = prev.preview;
+      return reduceChangesAction(prev, { type: "apply-start" });
+    });
+    if (!preview) return null;
+    setBusy(true);
+    try {
+      const result = await applyGovernanceSync({
+        preview,
+        homeDir, workspaceRoot, packageName, packageRoot, cliVersion
+      });
+      if (result.reason === "stale-preview") {
+        setChangesAction((prev) => reduceChangesAction(prev, {
+          type: "apply-done",
+          ok: false,
+          reason: "stale-preview",
+          preview: result.preview,
+          message: "Preview stale — press A for a fresh preview."
+        }));
+        return result;
+      }
+      if (result.reason === "setup-required") {
+        setChangesAction((prev) => reduceChangesAction(prev, {
+          type: "preview-ready",
+          preview: { setupRequired: true }
+        }));
+        return result;
+      }
+      await reload();
+      setChangesAction((prev) => reduceChangesAction(prev, {
+        type: "apply-done",
+        ok: result.ok,
+        reason: result.reason,
+        receipt: result.receipt,
+        message: result.ok
+          ? (result.partial ? "Applied with partial evidence — re-scan complete." : "Applied — re-scan complete.")
+          : `Apply ${result.reason}.`
+      }));
+      setStatusMessage(result.ok ? "Governance apply recorded." : null);
+      return result;
+    } catch (applyError) {
+      const message = applyError instanceof Error ? applyError.message : String(applyError);
+      setChangesAction((prev) => reduceChangesAction(prev, {
+        type: "apply-done", ok: false, reason: "apply-failed", message
+      }));
+      return null;
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const rescanChanges = async () => {
+    setChangesAction(() => createChangesActionState());
+    await reload();
+  };
+
+  const previewRecovery = async (snapshotName) => {
+    if (!snapshotName) return null;
+    setRecoveryAction((prev) => reduceRecoveryAction(prev, {
+      type: "preview-start", snapshot: snapshotName
+    }));
+    setBusy(true);
+    try {
+      const preview = await previewGovernanceRollback({ homeDir, snapshot: snapshotName });
+      setRecoveryAction((prev) => reduceRecoveryAction(prev, { type: "preview-ready", preview }));
+      return preview;
+    } catch (previewError) {
+      const message = previewError instanceof Error ? previewError.message : String(previewError);
+      setRecoveryAction((prev) => reduceRecoveryAction(prev, {
+        type: "preview-failed", error: "preview-failed", message
+      }));
+      return null;
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const cancelRecovery = () => {
+    setRecoveryAction((prev) => reduceRecoveryAction(prev, { type: "cancel" }));
+    setStatusMessage("Cancelled — previous snapshot kept.");
+  };
+
+  const confirmApplyRecovery = async () => {
+    let preview = null;
+    setRecoveryAction((prev) => {
+      if (prev.phase !== RECOVERY_PHASE.CONFIRMING || !prev.preview) return prev;
+      preview = prev.preview;
+      return reduceRecoveryAction(prev, { type: "apply-start" });
+    });
+    if (!preview) return null;
+    setBusy(true);
+    try {
+      const result = await applyGovernanceRollback({
+        preview, homeDir, cliVersion
+      });
+      if (result.reason === "stale-preview") {
+        setRecoveryAction((prev) => reduceRecoveryAction(prev, {
+          type: "apply-done",
+          ok: false,
+          reason: "stale-preview",
+          preview: result.preview,
+          message: "Preview stale — press Enter for a fresh preview."
+        }));
+        return result;
+      }
+      await reload();
+      setRecoveryAction((prev) => reduceRecoveryAction(prev, {
+        type: "apply-done",
+        ok: result.ok,
+        reason: result.reason,
+        receipt: result.receipt,
+        message: result.ok ? "Rollback applied — re-scan complete." : `Rollback ${result.reason}.`
+      }));
+      setStatusMessage(result.ok ? "Rollback recorded." : null);
+      return result;
+    } catch (applyError) {
+      const message = applyError instanceof Error ? applyError.message : String(applyError);
+      // Keep prior preview so the selected snapshot remains visible after failure.
+      setRecoveryAction((prev) => reduceRecoveryAction(prev, {
+        type: "apply-done", ok: false, reason: "apply-failed", message, preview: prev.preview
+      }));
+      return null;
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const rescanRecovery = async () => {
+    setRecoveryAction(() => createRecoveryActionState());
+    await reload();
+  };
+
   return {
     loading,
     busy,
+    retrying,
     error,
     setError,
     dashboard,
     diagnostics,
+    snapshot,
     selectedRun,
     setSelectedRun,
     selectedEvents,
@@ -153,10 +363,22 @@ export function useOrchestratorData({
     launchPermissionIndex,
     setLaunchPermissionIndex,
     launchableAgents: resolveLaunchableAgents(dashboard?.providers ?? []),
+    scanOptions: CONTROL_PLANE_AUTO_SCAN,
+    changesAction,
+    recoveryAction,
     reload,
     resetLaunchWizard,
     openRunDetail,
     handleLaunch,
-    handleCancelRun
+    handleCancelRun,
+    previewChanges,
+    cancelChanges,
+    confirmApplyChanges,
+    rescanChanges,
+    previewRecovery,
+    cancelRecovery,
+    confirmApplyRecovery,
+    rescanRecovery,
+    recoverySnapshots: listRecoverySnapshots(snapshot)
   };
 }

package/src/global/integrations/engram-apply.js

@@ -0,0 +1,105 @@
+import {
+  assertExplicitApplyConsent,
+  promptApplyConfirmation,
+  shouldPromptApplyConfirmation
+} from "../apply-confirmation.js";
+import { ENGRAM_INTEGRATION_STATUS } from "./engram-evidence.js";
+import { planEngramConfigure } from "./engram-plan.js";
+import { runEngramSetup } from "./engram-exec.js";
+
+/** Apply Engram configure with consent; stop on first failure with partial receipt. */
+export async function applyEngramConfigure({
+  requestedAgentIds = null,
+  detectedAgentIds = [],
+  env = process.env,
+  homeDir,
+  dryRun = false,
+  yes = false,
+  json = false,
+  interactive = null,
+  receiptId = null,
+  plan = planEngramConfigure,
+  runSetup = runEngramSetup,
+  confirm = promptApplyConfirmation,
+  now = () => new Date().toISOString()
+} = {}) {
+  assertExplicitApplyConsent({
+    applying: !dryRun, dryRun, json, yes, interactive, command: "components configure"
+  });
+
+  const planned = plan({ requestedAgentIds, detectedAgentIds, env, homeDir, dryRun: true });
+  if (dryRun) return { ...planned, applied: false, cancelled: false, receipt: null };
+  if (planned.blocked) {
+    throw new Error(planned.guidance ?? "Engram configure is blocked until the binary is supported.");
+  }
+
+  if (shouldPromptApplyConfirmation({ applying: true, dryRun, json, confirm: yes, interactive })) {
+    const accepted = await confirm({
+      command: "components configure engram-memory",
+      question: "Apply Engram setup for the planned agents? [Y/n]: "
+    });
+    if (!accepted) return { ...planned, applied: false, cancelled: true, receipt: null };
+  }
+
+  const startedAt = now();
+  const agentResults = [];
+  let failed = null;
+
+  for (const action of planned.actions) {
+    if (action.action === "blocked" || !action.command) {
+      failed = { agentId: action.agentId, slug: action.slug, error: action.reason ?? "Missing setup command." };
+      break;
+    }
+    const [binaryPath, , slug] = action.command;
+    const result = await runSetup({ binaryPath, slug, env });
+    agentResults.push({
+      agentId: action.agentId, slug, ok: result.ok, status: result.status,
+      timedOut: result.timedOut, terminationFailed: result.terminationFailed,
+      command: result.command, stdout: result.stdout, stderr: result.stderr
+    });
+    if (!result.ok) {
+      failed = {
+        agentId: action.agentId,
+        slug,
+        error: result.timedOut
+          ? `Engram setup timed out for ${slug}.`
+          : `Engram setup failed for ${slug} (exit ${result.status}).`
+      };
+      break;
+    }
+  }
+
+  const completed = planned.actions
+    .filter((action) => agentResults.some((entry) => entry.agentId === action.agentId && entry.ok))
+    .map((action) => action.agentId);
+  const remaining = planned.actions.map((a) => a.agentId).filter((id) => !completed.includes(id));
+
+  const receipt = {
+    id: receiptId ?? `engram-${startedAt.replace(/[:.]/g, "-")}`,
+    provider: "engram",
+    componentId: "engram-memory",
+    startedAt,
+    finishedAt: now(),
+    binary: planned.binary,
+    agentsRequested: planned.actions.map((a) => a.agentId),
+    agentsCompleted: completed,
+    agentsRemaining: remaining,
+    agentResults,
+    ok: failed == null,
+    partial: failed != null && completed.length > 0,
+    failed,
+    status: failed == null ? ENGRAM_INTEGRATION_STATUS.RESTART_REQUIRED : ENGRAM_INTEGRATION_STATUS.CONFLICT,
+    persisted: false,
+    touchedMemoryDb: false
+  };
+
+  return {
+    ...planned,
+    dryRun: false,
+    executes: true,
+    writes: true,
+    applied: failed == null,
+    cancelled: false,
+    receipt
+  };
+}

package/src/global/integrations/engram-evidence.js

@@ -0,0 +1,218 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { probeCommand } from "../cli-probe.js";
+
+export const KAIRO_ENGRAM_AGENT_IDS = Object.freeze(["cursor", "codex", "opencode", "claude"]);
+export const ENGRAM_SETUP_SLUG_BY_AGENT = Object.freeze({
+  cursor: "cursor",
+  codex: "codex",
+  opencode: "opencode",
+  claude: "claude-code"
+});
+export const ENGRAM_MIN_VERSION = "1.19.0";
+export const ENGRAM_MAX_MAJOR = 2;
+export const ENGRAM_INTEGRATION_STATUS = Object.freeze({
+  MISSING: "missing",
+  UNSUPPORTED: "unsupported",
+  AVAILABLE: "available",
+  UNCONFIGURED: "unconfigured",
+  CONFIGURED: "configured",
+  CONFLICT: "conflict",
+  RESTART_REQUIRED: "restart_required"
+});
+
+export function engramSetupSlugForAgent(agentId) {
+  const slug = ENGRAM_SETUP_SLUG_BY_AGENT[agentId];
+  if (!slug) {
+    throw new Error(`Agent "${agentId}" is not managed for Engram setup. Use: ${KAIRO_ENGRAM_AGENT_IDS.join(", ")}.`);
+  }
+  return slug;
+}
+
+export function resolveEngramAgentSelection({
+  requestedIds = null,
+  detectedIds = [],
+  managedIds = KAIRO_ENGRAM_AGENT_IDS
+} = {}) {
+  const managed = [...managedIds];
+  if (requestedIds == null) {
+    const detected = new Set(detectedIds);
+    return managed.filter((id) => detected.has(id));
+  }
+  if (requestedIds.length === 1 && requestedIds[0] === "all") return [...managed];
+  return requestedIds.map((id) => {
+    if (!managed.includes(id)) {
+      throw new Error(`Agent "${id}" is not managed for Engram setup. Use: ${managed.join(", ")}.`);
+    }
+    return id;
+  });
+}
+
+export function parseEngramVersion(output) {
+  const text = String(output ?? "");
+  const labeled = text.match(/\bengram\s+v?(\d+\.\d+\.\d+)\b/i);
+  if (labeled) return labeled[1];
+  for (const line of text.split(/\r?\n/).map((l) => l.trim()).filter(Boolean)) {
+    if (/update available/i.test(line)) continue;
+    const match = line.match(/^v?(\d+\.\d+\.\d+)\b/);
+    if (match) return match[1];
+  }
+  return null;
+}
+
+export function classifyEngramVersion(version) {
+  const parsed = parseSemver(version);
+  const range = `>=${ENGRAM_MIN_VERSION} <${ENGRAM_MAX_MAJOR}.0.0`;
+  if (!parsed) {
+    return unsupported(`Unable to parse Engram version "${version}". Supported range: ${range}.`);
+  }
+  if (parsed.major >= ENGRAM_MAX_MAJOR || parsed.major < 1) {
+    return unsupported(`Engram ${version} is outside the supported major range (${range}).`);
+  }
+  if (compareSemver(parsed, parseSemver(ENGRAM_MIN_VERSION)) < 0) {
+    return unsupported(
+      `Engram ${version} is below the supported baseline ${ENGRAM_MIN_VERSION}. Upgrade Engram manually (Kairo will not update it).`
+    );
+  }
+  return { status: ENGRAM_INTEGRATION_STATUS.AVAILABLE, supported: true, guidance: null };
+}
+
+export function inspectEngramBinary({ env = process.env, probe = probeCommand, whichCommand = defaultWhich } = {}) {
+  const path = whichCommand("engram", env) || null;
+  if (!path) {
+    return {
+      path: null,
+      version: null,
+      status: ENGRAM_INTEGRATION_STATUS.MISSING,
+      supported: false,
+      guidance: "Engram binary not found in PATH. Install Engram separately, then re-run configure."
+    };
+  }
+  const result = probe(path, ["version"], { env, timeoutMs: 5000 });
+  const version = parseEngramVersion(`${result.stdout}\n${result.stderr}`);
+  if (!version) {
+    return {
+      path,
+      version: null,
+      status: ENGRAM_INTEGRATION_STATUS.UNSUPPORTED,
+      supported: false,
+      guidance: "Engram binary found but `engram version` did not return a parseable version."
+    };
+  }
+  const classified = classifyEngramVersion(version);
+  return { path, version, status: classified.status, supported: classified.supported, guidance: classified.guidance };
+}
+
+export function inspectEngramAgentConfig(agentId, { homeDir = homedir() } = {}) {
+  const slug = engramSetupSlugForAgent(agentId);
+  const evidence = collectAgentEvidence(agentId, homeDir);
+  const conflicts = evidence.filter((item) => item.conflict);
+  let status = ENGRAM_INTEGRATION_STATUS.UNCONFIGURED;
+  if (conflicts.length > 0) status = ENGRAM_INTEGRATION_STATUS.CONFLICT;
+  else if (evidence.some((item) => item.present && item.kind === "mcp")) {
+    status = ENGRAM_INTEGRATION_STATUS.CONFIGURED;
+  }
+  return { id: agentId, slug, status, evidence };
+}
+
+export function inspectEngramIntegration({
+  env = process.env,
+  homeDir = homedir(),
+  agentIds = KAIRO_ENGRAM_AGENT_IDS,
+  probe = probeCommand,
+  whichCommand = defaultWhich
+} = {}) {
+  const binary = inspectEngramBinary({ env, probe, whichCommand });
+  const agents = agentIds.map((id) => inspectEngramAgentConfig(id, { homeDir }));
+  let status = binary.status;
+  if (binary.supported) {
+    if (agents.some((a) => a.status === ENGRAM_INTEGRATION_STATUS.CONFLICT)) {
+      status = ENGRAM_INTEGRATION_STATUS.CONFLICT;
+    } else if (agents.every((a) => a.status === ENGRAM_INTEGRATION_STATUS.CONFIGURED)) {
+      status = ENGRAM_INTEGRATION_STATUS.CONFIGURED;
+    } else if (agents.some((a) => a.status === ENGRAM_INTEGRATION_STATUS.CONFIGURED)) {
+      status = ENGRAM_INTEGRATION_STATUS.AVAILABLE;
+    } else {
+      status = ENGRAM_INTEGRATION_STATUS.UNCONFIGURED;
+    }
+  }
+  return { provider: "engram", status, binary, agents, doctorInvoked: false };
+}
+
+function collectAgentEvidence(agentId, homeDir) {
+  if (agentId === "claude") {
+    return [
+      fileEvidence(join(homeDir, ".claude", "mcp", "engram.json"), "mcp"),
+      jsonKeyEvidence(join(homeDir, ".claude", "settings.json"), ["mcpServers", "engram"], "mcp")
+    ];
+  }
+  if (agentId === "codex") {
+    return [
+      tomlSectionEvidence(join(homeDir, ".codex", "config.toml"), "mcp_servers.engram", "mcp"),
+      fileEvidence(join(homeDir, ".codex", "engram-instructions.md"), "protocol")
+    ];
+  }
+  if (agentId === "opencode") {
+    return [
+      jsonKeyEvidence(join(homeDir, ".config", "opencode", "opencode.json"), ["mcp", "engram"], "mcp"),
+      fileEvidence(join(homeDir, ".config", "opencode", "plugins", "engram.ts"), "plugin")
+    ];
+  }
+  if (agentId === "cursor") {
+    return [
+      jsonKeyEvidence(join(homeDir, ".cursor", "mcp.json"), ["mcpServers", "engram"], "mcp"),
+      fileEvidence(join(homeDir, ".cursor", "rules", "engram.mdc"), "protocol")
+    ];
+  }
+  throw new Error(`Unsupported Engram agent "${agentId}".`);
+}
+
+function fileEvidence(path, kind) {
+  return { path, kind, present: existsSync(path), conflict: false };
+}
+
+function jsonKeyEvidence(path, keyPath, kind) {
+  if (!existsSync(path)) return { path, kind, present: false, conflict: false, keyPath };
+  try {
+    let cursor = JSON.parse(readFileSync(path, "utf8"));
+    for (const key of keyPath) {
+      if (cursor == null || typeof cursor !== "object") {
+        return { path, kind, present: false, conflict: true, keyPath, detail: "invalid structure" };
+      }
+      cursor = cursor[key];
+    }
+    return { path, kind, present: cursor != null && typeof cursor === "object", conflict: false, keyPath };
+  } catch {
+    return { path, kind, present: false, conflict: true, keyPath, detail: "unreadable json" };
+  }
+}
+
+function tomlSectionEvidence(path, section, kind) {
+  if (!existsSync(path)) return { path, kind, present: false, conflict: false, section };
+  try {
+    const text = readFileSync(path, "utf8");
+    const present = new RegExp(`\\[\\s*${section.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*\\]`).test(text);
+    return { path, kind, present, conflict: false, section };
+  } catch {
+    return { path, kind, present: false, conflict: true, section, detail: "unreadable toml" };
+  }
+}
+
+function unsupported(guidance) {
+  return { status: ENGRAM_INTEGRATION_STATUS.UNSUPPORTED, supported: false, guidance };
+}
+
+function parseSemver(version) {
+  const match = String(version ?? "").match(/^(\d+)\.(\d+)\.(\d+)/);
+  return match ? { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) } : null;
+}
+
+function compareSemver(a, b) {
+  return a.major - b.major || a.minor - b.minor || a.patch - b.patch;
+}
+
+function defaultWhich(command, env) {
+  const result = probeCommand("which", [command], { env, timeoutMs: 3000 });
+  return result.ok ? result.stdout.trim() : null;
+}