@kal-elsam/kairo-runtime 0.14.0 → 0.16.0

package/src/global/fleet-models.js

@@ -0,0 +1,188 @@
+/**
+ * Unified fleet model profile (~/.harness/fleet-models.json).
+ * Multi-agent platforms (Claude + OpenCode) share phase keys.
+ * Codex keeps a single default model. Cursor Auto stays IDE-managed.
+ */
+import { readFile, mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { resolveHomeDir } from "./paths.js";
+import { writeAtomicJson } from "./runtime/write-atomic-json.js";
+import {
+  SDD_PHASES,
+  loadGentleClaudeAssignments
+} from "./fleet-shared.js";
+import { parseFrontmatterModel, parseCodexDefaultModel } from "./observability/fleet-platforms.js";
+
+export const FLEET_MODELS_VERSION = 1;
+
+export function fleetModelsPath(homeDir = resolveHomeDir()) {
+  return join(homeDir, ".harness", "fleet-models.json");
+}
+
+export function emptyFleetProfile() {
+  const phases = {};
+  for (const id of SDD_PHASES) {
+    phases[id] = { claude: null, opencode: null };
+  }
+  return {
+    version: FLEET_MODELS_VERSION,
+    claudeDefault: null,
+    codexDefault: null,
+    cursorAgentModel: "inherit",
+    phases,
+    note: "Multi-agent phases for Claude + OpenCode. Codex uses codexDefault only. Cursor agents use inherit (Auto is IDE-managed)."
+  };
+}
+
+async function readJsonSafe(path, read) {
+  try {
+    return JSON.parse(await read(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Seed profile from Gentle + current on-disk OpenCode/Claude/Codex.
+ * Preserves tuned OpenCode models when present.
+ */
+export async function seedFleetProfile({
+  homeDir = resolveHomeDir(),
+  read = readFile
+} = {}) {
+  const profile = emptyFleetProfile();
+  const gentle = await loadGentleClaudeAssignments(homeDir, read);
+  if (gentle) {
+    profile.claudeDefault = gentle.default ?? "sonnet";
+    for (const id of SDD_PHASES) {
+      if (gentle[id]) profile.phases[id].claude = gentle[id];
+    }
+  }
+
+  const settings = await readJsonSafe(join(homeDir, ".claude", "settings.json"), read);
+  if (settings?.model && !profile.claudeDefault) profile.claudeDefault = settings.model;
+
+  for (const id of SDD_PHASES) {
+    try {
+      const raw = await read(join(homeDir, ".claude", "agents", `${id}.md`), "utf8");
+      const model = parseFrontmatterModel(raw).model;
+      if (model && model !== "inherit") profile.phases[id].claude = model;
+    } catch { /* missing */ }
+  }
+
+  const oc = await readJsonSafe(join(homeDir, ".config", "opencode", "opencode.json"), read);
+  const agents = oc?.agent ?? oc?.agents ?? {};
+  for (const id of SDD_PHASES) {
+    const model = agents[id]?.model;
+    // Only declare OpenCode models that exist on disk — never invent from Claude tiers.
+    if (typeof model === "string") profile.phases[id].opencode = model;
+  }
+
+  try {
+    const toml = await read(join(homeDir, ".codex", "config.toml"), "utf8");
+    profile.codexDefault = parseCodexDefaultModel(toml);
+  } catch { /* missing */ }
+
+  return profile;
+}
+
+export async function loadFleetProfile({
+  homeDir = resolveHomeDir(),
+  read = readFile,
+  seedIfMissing = true
+} = {}) {
+  const path = fleetModelsPath(homeDir);
+  const existing = await readJsonSafe(path, read);
+  if (existing?.phases) {
+    return { profile: existing, path, seeded: false };
+  }
+  if (!seedIfMissing) {
+    return { profile: emptyFleetProfile(), path, seeded: false };
+  }
+  const profile = await seedFleetProfile({ homeDir, read });
+  return { profile, path, seeded: true };
+}
+
+export async function saveFleetProfile(profile, {
+  homeDir = resolveHomeDir(),
+  writeAtomicJsonFn = writeAtomicJson,
+  mkdirFn = mkdir
+} = {}) {
+  const path = fleetModelsPath(homeDir);
+  await mkdirFn(dirname(path), { recursive: true });
+  const next = {
+    ...profile,
+    version: FLEET_MODELS_VERSION,
+    updatedAt: new Date().toISOString()
+  };
+  await writeAtomicJsonFn(path, next);
+  return { path, profile: next };
+}
+
+/** Expand profile → assignment maps used by apply. */
+export function profileToPlatformAssignments(profile) {
+  const claude = {};
+  const opencode = {};
+  if (profile.claudeDefault) claude.default = profile.claudeDefault;
+  for (const id of SDD_PHASES) {
+    const row = profile.phases?.[id] ?? {};
+    if (row.claude) claude[id] = row.claude;
+    if (row.opencode) opencode[id] = row.opencode;
+  }
+  return {
+    claude,
+    opencode,
+    codex: profile.codexDefault ? { codex_default: profile.codexDefault } : {},
+    cursorAgentModel: profile.cursorAgentModel ?? "inherit"
+  };
+}
+
+export function formatFleetProfileText(profile, { path = null } = {}) {
+  const lines = ["Fleet profile (multi-agent)", ""];
+  if (path) lines.push(`Path · ${path}`);
+  lines.push(`Claude default · ${profile.claudeDefault ?? "—"}`);
+  lines.push(`Codex default  · ${profile.codexDefault ?? "—"} (single-model tool)`);
+  lines.push(`Cursor agents  · ${profile.cursorAgentModel ?? "inherit"} (Auto IDE-managed)`);
+  lines.push("");
+  for (const id of SDD_PHASES) {
+    const row = profile.phases?.[id] ?? {};
+    lines.push(`${id} · claude ${row.claude ?? "—"} · opencode ${row.opencode ?? "—"}`);
+  }
+  if (profile.note) {
+    lines.push("");
+    lines.push(profile.note);
+  }
+  return lines.join("\n").trimEnd();
+}
+
+export async function runFleetModels({
+  json = false,
+  profile = false,
+  homeDir = resolveHomeDir()
+} = {}) {
+  const { printJson } = await import("./json-output.js");
+  const { commandHeader } = await import("./brand/index.js");
+  const { buildFleetModelsCatalog, formatFleetModelsText } = await import(
+    "./observability/fleet-models-catalog.js"
+  );
+  const catalog = await buildFleetModelsCatalog({ homeDir });
+  if (!profile) {
+    if (json) printJson(catalog);
+    else {
+      console.log(commandHeader("Fleet models"));
+      console.log(formatFleetModelsText(catalog));
+    }
+    return catalog;
+  }
+
+  const loaded = await loadFleetProfile({ homeDir, seedIfMissing: true });
+  const payload = { ok: true, profile: loaded.profile, path: loaded.path, catalog };
+  if (json) printJson(payload);
+  else {
+    console.log(commandHeader("Fleet models"));
+    console.log(formatFleetProfileText(loaded.profile, { path: loaded.path }));
+    console.log("");
+    console.log(formatFleetModelsText(catalog));
+  }
+  return payload;
+}

package/src/global/fleet-set.js

@@ -0,0 +1,219 @@
+/**
+ * Consent-gated fleet model writes (OpenCode / Claude / Codex).
+ * Plan by default; --yes applies with backup. Never touches Cursor Auto / state.vscdb.
+ */
+import { copyFile, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { resolveHomeDir } from "./paths.js";
+import { writeAtomicJson } from "./runtime/write-atomic-json.js";
+import { printJson } from "./json-output.js";
+import { commandHeader } from "./brand/index.js";
+import { formatCliCommand } from "./brand/cli.js";
+import {
+  parseFrontmatterModel,
+  replaceFrontmatterModel,
+  replaceCodexDefaultModel
+} from "./observability/fleet-platforms.js";
+
+const PLATFORMS = new Set(["opencode", "claude", "codex"]);
+
+function backupPath(path, stamp = Date.now()) {
+  return `${path}.kairo-backup.${stamp}`;
+}
+
+function requirePlatform(platform) {
+  const p = String(platform ?? "").toLowerCase();
+  if (!PLATFORMS.has(p)) {
+    throw new Error(`Unsupported platform "${platform}". Use opencode, claude, or codex.`);
+  }
+  return p;
+}
+
+function requireAgent(agent) {
+  const id = String(agent ?? "").trim();
+  if (!id) throw new Error("Missing --agent <id>.");
+  return id;
+}
+
+function requireModel(model) {
+  const m = String(model ?? "").trim();
+  if (!m) throw new Error("Missing --model <id>.");
+  return m;
+}
+
+export function buildOpenCodeFleetSetPlan({ config, agent, model, configPath }) {
+  const agents = config?.agent ?? config?.agents;
+  if (!agents || typeof agents !== "object" || !(agent in agents)) {
+    throw new Error(`OpenCode agent "${agent}" not found in ${configPath}.`);
+  }
+  const prev = agents[agent];
+  const previousModel = typeof prev?.model === "string" ? prev.model : (config?.model ?? null);
+  const nextAgents = {
+    ...agents,
+    [agent]: { ...prev, model }
+  };
+  const next = { ...config, agent: nextAgents };
+  if (config.agents && !config.agent) {
+    delete next.agent;
+    next.agents = nextAgents;
+  }
+  return {
+    platform: "opencode",
+    agent,
+    model,
+    previousModel,
+    path: configPath,
+    wouldWrite: previousModel !== model,
+    next,
+    note: `Set OpenCode agent.${agent}.model → ${model}`
+  };
+}
+
+export async function runFleetSet({
+  platform,
+  agent,
+  model,
+  yes = false,
+  json = false,
+  dryRun = false,
+  homeDir = resolveHomeDir(),
+  read = readFile,
+  writeText = writeFile,
+  copyFileFn = copyFile,
+  writeAtomicJsonFn = writeAtomicJson,
+  now = () => Date.now()
+} = {}) {
+  const p = requirePlatform(platform);
+  const nextModel = requireModel(model);
+  const agentId = p === "codex"
+    ? (String(agent ?? "default").trim() || "default")
+    : requireAgent(agent);
+  const apply = yes === true && dryRun !== true;
+
+  let plan;
+  let path;
+  let applyFn;
+
+  if (p === "opencode") {
+    path = join(homeDir, ".config", "opencode", "opencode.json");
+    const raw = await read(path, "utf8");
+    const config = JSON.parse(raw);
+    plan = buildOpenCodeFleetSetPlan({
+      config, agent: agentId, model: nextModel, configPath: path
+    });
+    applyFn = async () => {
+      await writeAtomicJsonFn(path, plan.next);
+    };
+  } else if (p === "claude") {
+    if (agentId === "default") {
+      path = join(homeDir, ".claude", "settings.json");
+      const existing = JSON.parse(await read(path, "utf8"));
+      const previousModel = typeof existing.model === "string" ? existing.model : null;
+      plan = {
+        platform: "claude",
+        agent: agentId,
+        model: nextModel,
+        previousModel,
+        path,
+        wouldWrite: previousModel !== nextModel,
+        next: { ...existing, model: nextModel },
+        note: `Set Claude settings.model → ${nextModel}`
+      };
+      applyFn = async () => {
+        await writeAtomicJsonFn(path, plan.next);
+      };
+    } else {
+      path = join(homeDir, ".claude", "agents", `${agentId}.md`);
+      const raw = await read(path, "utf8");
+      const previousModel = parseFrontmatterModel(raw).model;
+      const nextText = replaceFrontmatterModel(raw, nextModel);
+      plan = {
+        platform: "claude",
+        agent: agentId,
+        model: nextModel,
+        previousModel,
+        path,
+        wouldWrite: previousModel !== nextModel,
+        nextText,
+        note: `Set Claude agent ${agentId} frontmatter model → ${nextModel}`
+      };
+      applyFn = async () => {
+        await writeText(path, plan.nextText, "utf8");
+      };
+    }
+  } else {
+    path = join(homeDir, ".codex", "config.toml");
+    const raw = await read(path, "utf8");
+    const previousMatch = raw.match(/^\s*model\s*=\s*"([^"]+)"/m);
+    const previousModel = previousMatch ? previousMatch[1] : null;
+    const nextText = replaceCodexDefaultModel(raw, nextModel);
+    plan = {
+      platform: "codex",
+      agent: "default",
+      model: nextModel,
+      previousModel,
+      path,
+      wouldWrite: previousModel !== nextModel,
+      nextText,
+      note: `Set Codex config.toml model → ${nextModel}`
+    };
+    applyFn = async () => {
+      await writeText(path, plan.nextText, "utf8");
+    };
+  }
+
+  plan.backupPath = backupPath(path, now());
+  plan.applyWith = formatCliCommand(
+    `fleet set --platform ${p} --agent ${plan.agent} --model ${nextModel} --yes`
+  );
+
+  if (!apply) {
+    const payload = {
+      ok: true,
+      applied: false,
+      plan: {
+        platform: plan.platform,
+        agent: plan.agent,
+        model: plan.model,
+        previousModel: plan.previousModel,
+        path: plan.path,
+        wouldWrite: plan.wouldWrite,
+        note: plan.note,
+        applyWith: plan.applyWith
+      }
+    };
+    if (json) printJson(payload);
+    else {
+      console.log(commandHeader("Fleet set"));
+      console.log(plan.note);
+      console.log(`Path · ${plan.path}`);
+      console.log(`Was · ${plan.previousModel ?? "—"}`);
+      console.log(`Now · ${plan.model}`);
+      console.log(`Apply · ${plan.applyWith}`);
+    }
+    return payload;
+  }
+
+  await copyFileFn(path, plan.backupPath);
+  await applyFn();
+
+  const receipt = {
+    ok: true,
+    applied: true,
+    platform: plan.platform,
+    agent: plan.agent,
+    model: plan.model,
+    previousModel: plan.previousModel,
+    path: plan.path,
+    backupPath: plan.backupPath,
+    note: "Model assignment updated. Refresh Kairo Fleet to see declared changes."
+  };
+  if (json) printJson(receipt);
+  else {
+    console.log(commandHeader("Fleet set"));
+    console.log(`Wrote · ${receipt.path}`);
+    console.log(`Backup · ${receipt.backupPath}`);
+    console.log(receipt.note);
+  }
+  return receipt;
+}

package/src/global/fleet-shared.js

@@ -0,0 +1,38 @@
+/**
+ * Shared fleet constants + Gentle assignment loader (no circular imports).
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+export const SDD_PHASES = Object.freeze([
+  "sdd-apply", "sdd-archive", "sdd-design", "sdd-explore", "sdd-init",
+  "sdd-onboard", "sdd-propose", "sdd-spec", "sdd-tasks", "sdd-verify"
+]);
+
+/** Map Gentle/Claude tier names → OpenCode provider/model ids. */
+export const CLAUDE_TO_OPENCODE = Object.freeze({
+  opus: "opencode-go/deepseek-v4-pro",
+  sonnet: "opencode-go/qwen3.5-plus",
+  haiku: "opencode-go/deepseek-v4-flash"
+});
+
+export async function loadGentleClaudeAssignments(homeDir, read = readFile) {
+  try {
+    const state = JSON.parse(await read(join(homeDir, ".gentle-ai", "state.json"), "utf8"));
+    const map = state?.claude_model_assignments;
+    if (!map || typeof map !== "object") return null;
+    return { ...map };
+  } catch {
+    return null;
+  }
+}
+
+export function mapClaudeAssignmentsToOpenCode(assignments = {}) {
+  const out = {};
+  for (const [agent, tier] of Object.entries(assignments)) {
+    if (agent === "default" || agent === "codex_default") continue;
+    const key = String(tier ?? "").toLowerCase();
+    out[agent] = CLAUDE_TO_OPENCODE[key] ?? CLAUDE_TO_OPENCODE.sonnet;
+  }
+  return out;
+}

package/src/global/ink/cockpit-controller.js

@@ -29,7 +29,7 @@ export {
 export function createCockpitUiState({
   layoutMode = LAYOUT_MODES.COMPACT,
   view = ORCHESTRATOR_VIEWS.HOME,
-  region = COCKPIT_REGIONS.NAV,
+  region = null,
   navIndex = 0,
   listIndex = 0,
   helpOpen = false,

package/src/global/ink/cockpit-models.js

@@ -328,8 +328,11 @@ export function buildFooterModel({
 
   // HOME footer must stay on one line at 80 cols (frame already near 24 rows).
   if (view === ORCHESTRATOR_VIEWS.HOME) {
+    const homeParts = region === COCKPIT_REGIONS.NAV
+      ? ["↑↓ Section", "Enter Open", "? Help", "Esc Exit"]
+      : ["1·2 Select", "Enter Run", "? Help", "Esc Exit"];
     return {
-      text: ["↑↓", "Enter", "Tab", "Space", "R", "?", "/", "Esc"].join(` ${glyphs.bullet} `),
+      text: homeParts.join(` ${glyphs.bullet} `),
       columns: footerColumns
     };
   }

package/src/global/ink/orchestrator-app.js

@@ -63,8 +63,7 @@ export function OrchestratorApp({
   const [ui, dispatch] = useReducer(
     reduceCockpitUi,
     createCockpitUiState({
-      layoutMode: layoutMode ?? LAYOUT_MODES.COMPACT,
-      region: COCKPIT_REGIONS.NAV
+      layoutMode: layoutMode ?? LAYOUT_MODES.COMPACT
     })
   );
   const data = useOrchestratorData({
@@ -166,6 +165,26 @@ export function OrchestratorApp({
       return;
     }
 
+    if (ui.view === ORCHESTRATOR_VIEWS.HOME && !ui.paletteOpen) {
+      const digit = inputKey === "1" ? 0 : inputKey === "2" ? 1 : -1;
+      if (digit >= 0) {
+        const buttons = buildOverviewButtons({
+          hasGlobalState,
+          snapshot: data.snapshot,
+          diagnostics: data.diagnostics,
+          dashboard: data.dashboard
+        });
+        const selected = buttons[digit];
+        const intent = selected?.intent ?? null;
+        if (intent === "setup") {
+          finish({ cancelled: false, action: "setup" });
+          return;
+        }
+        if (intent && openDestination(intent)) return;
+        return;
+      }
+    }
+
     if (inputKey === " " && ui.view === ORCHESTRATOR_VIEWS.HOME && !ui.paletteOpen) {
       dispatch({ type: "toggle-overview-details" });
       return;

package/src/global/ink/ux/live-overview.js

@@ -94,12 +94,6 @@ export function adaptControlCenterToOverview(model = {}, options = {}) {
       label: `Alerts · ${model.alerts.headline ?? `${model.alerts.count} open`}`
     });
   }
-  if (rest.length > 0) {
-    metrics.push({
-      id: "more",
-      label: `${rest.length} more in Details · Space`
-    });
-  }
   if (metrics.length === 0) {
     metrics.push({ id: "quiet", label: "Nothing else needs you right now" });
   }
@@ -201,13 +195,13 @@ export function SemanticOverviewPanel({
           marginBottom: index === view.buttons.length - 1 ? 0 : 1
         },
           React.createElement(Text, {
-            bold: true,
-            color: focused && colorEnabled ? COCKPIT_COLORS.interactive : undefined
-          }, `${focused ? glyphs.focus : " "} ${button.label}`),
+            bold: selected,
+            color: colorEnabled && selected ? COCKPIT_COLORS.interactive : undefined
+          }, `${selected ? glyphs.focus : " "} [${index + 1}] ${button.label}${focused ? "  ← Press Enter" : ""}`),
           button.detail
             ? React.createElement(Text, {
               color: colorEnabled ? COCKPIT_COLORS.muted : undefined
-            }, `  ${button.detail}`)
+            }, `      ${button.detail}`)
             : null
         );
       })
@@ -223,7 +217,7 @@ export function SemanticOverviewPanel({
     ),
     React.createElement(Details, {
       open: detailsOpen,
-      summary: "More info",
+      summary: `More info (${view.details.length})`,
       lines: view.details,
       colorEnabled,
       focused: false,

package/src/global/ink/ux/overview-needs.js

@@ -4,7 +4,7 @@
 import { CONTROL_PLANE_HEALTH } from "../../control-plane-snapshot.js";
 import { formatCliCommand } from "../../brand/cli.js";
 
-export const OVERVIEW_NEED_LIMIT = 3;
+export const OVERVIEW_NEED_LIMIT = 2;
 
 /** Prefixes that never belong on the first screen (machine / internals). */
 export const DETAILS_ONLY_PREFIXES = [

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

@@ -215,12 +215,17 @@ function jsonKeyEvidence(path, keyPath, kind) {
   try {
     let cursor = JSON.parse(readFileSync(path, "utf8"));
     for (const key of keyPath) {
-      if (cursor == null || typeof cursor !== "object") {
+      if (cursor == null || typeof cursor !== "object" || Array.isArray(cursor)) {
         return { path, kind, present: false, conflict: true, keyPath, detail: "invalid structure" };
       }
+      // Missing key = unconfigured evidence, not a conflict (file may use another MCP path).
+      if (!Object.prototype.hasOwnProperty.call(cursor, key)) {
+        return { path, kind, present: false, conflict: false, keyPath };
+      }
       cursor = cursor[key];
     }
-    return { path, kind, present: cursor != null && typeof cursor === "object", conflict: false, keyPath };
+    const present = cursor != null && typeof cursor === "object" && !Array.isArray(cursor);
+    return { path, kind, present, conflict: false, keyPath };
   } catch {
     return { path, kind, present: false, conflict: true, keyPath, detail: "unreadable json" };
   }

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

@@ -17,7 +17,8 @@ const APPLYING_ACTIONS = new Set([SDD_PLAN_ACTIONS.CREATE, SDD_PLAN_ACTIONS.UPDA
 
 export async function applySddConfigure({
   requestedAgentIds = null, detectedAgentIds = [], homeDir, packageRoot, persona = "off",
-  personaAgentIds = [], trackedFiles = {}, preservePersona = false, dryRun = false, yes = false,
+  personaAgentIds = [], trackedFiles = {}, adoptedFiles = {}, overwriteConflicts = false,
+  preservePersona = false, dryRun = false, yes = false,
   json = false, interactive = null, receiptId = null, plan = planSddConfigure,
   confirm = promptApplyConfirmation, saveReceipt = saveSddReceipt,
   now = () => new Date().toISOString()
@@ -28,14 +29,16 @@ export async function applySddConfigure({
 
   const planned = await plan({
     requestedAgentIds, detectedAgentIds, homeDir, packageRoot, persona, personaAgentIds,
-    trackedFiles, preservePersona, dryRun: true
+    trackedFiles, adoptedFiles, overwriteConflicts, preservePersona, dryRun: true
   });
   if (dryRun) return { ...planned, applied: false, cancelled: false, receipt: null };
 
   if (shouldPromptApplyConfirmation({ applying: true, dryRun, json, confirm: yes, interactive })) {
     const accepted = await confirm({
       command: "components configure sdd-core",
-      question: "Materialize SDD skills for the planned agents? [Y/n]: "
+      question: overwriteConflicts
+        ? "Overwrite conflicting SDD skills with canonical Kairo copies (backups first)? [Y/n]: "
+        : "Materialize SDD skills for the planned agents? [Y/n]: "
     });
     if (!accepted) return { ...planned, applied: false, cancelled: true, receipt: null };
   }
@@ -66,7 +69,8 @@ export async function applySddConfigure({
     try {
       const managedRoot = resolveSddSkillRoot(action.agentIds[0], homeDir);
       const outcome = await materializeOne(action, {
-        homeDir, packageRoot, managedRoot, receiptId: resolvedReceiptId
+        homeDir, packageRoot, managedRoot, receiptId: resolvedReceiptId,
+        overwriteConflicts: Boolean(action.overwrote || overwriteConflicts)
       });
       if (outcome.conflict) {
         files.push({
@@ -78,7 +82,8 @@ export async function applySddConfigure({
       if (outcome.backup) backups.push(outcome.backup);
       files.push({
         ...record, applied: true, skipped: false, outcome: SDD_FILE_OUTCOMES.APPLIED,
-        afterHash: outcome.afterHash, parentRealpath: outcome.parentRealpath
+        afterHash: outcome.afterHash, parentRealpath: outcome.parentRealpath,
+        overwrote: Boolean(action.overwrote)
       });
     } catch (error) {
       failed = { skillId: action.skillId, destinationPath: action.destinationPath, error: error.message };
@@ -141,7 +146,9 @@ async function readCanonicalBytes(action, packageRoot) {
   ));
 }
 
-async function materializeOne(action, { homeDir, packageRoot, managedRoot, receiptId }) {
+async function materializeOne(action, {
+  homeDir, packageRoot, managedRoot, receiptId, overwriteConflicts = false
+}) {
   const chain = await assertSafePathChain(action.destinationPath, managedRoot, homeDir);
   if (!chain.ok) return { conflict: chain.reason };
 
@@ -169,7 +176,10 @@ async function materializeOne(action, { homeDir, packageRoot, managedRoot, recei
     return { conflict: "Managed destination disappeared after planning; preserving byte-for-byte." };
   }
   const snap = await snapshotRegularFile(action.destinationPath);
-  if (snap.hash !== action.trackedHash) {
+  const expectedHash = overwriteConflicts || action.overwrote
+    ? snap.hash
+    : action.trackedHash;
+  if (snap.hash !== expectedHash) {
     return { conflict: "Managed file changed after planning; preserving byte-for-byte." };
   }
   const parent = await parentRealpath(action.destinationPath);