@bitkyc08/opencodex 2.68.0 → 2.69.0

package/src/integrations/catalog-refresh.ts

@@ -11,7 +11,7 @@ import {
 /** Refresh only previously connected clients; a refused file never blocks its peers. */
 export async function refreshOwnedCatalogIntegrations(
   input: Omit<OwnedIntegrationRefreshInput, "clientId">,
-  clientIds: readonly IntegrationClientId[] = ["pi", "aside", "raycast", "omo"],
+  clientIds: readonly IntegrationClientId[] = ["pi", "aside", "raycast", "omo", "droid"],
 ): Promise<OwnedIntegrationRefreshOutcome[]> {
   // Client files are shared with the live proxy a sibling instance runs beside; their entries
   // point at the owner's port, and refreshing them here would re-point them at this one.

package/src/integrations/config-io.ts

@@ -9,6 +9,7 @@
  */
 import { lstatSync, mkdirSync, readFileSync, rmSync, statSync } from "node:fs";
 import type { ConfigFormat } from "../clients/config-export";
+import { canonicalizeJsonc } from "../lib/jsonc";
 import { MAX_JSON_NESTING } from "./serialize";
 import { atomicWriteFileNoFollow, isMissingPathError } from "../config/atomic-write";
 import type { JournalEntry } from "./journal";
@@ -132,7 +133,11 @@ function jsonTextSafeToRewrite(text: string): boolean {
 }
 
 /** Parse a client config, tolerating absence. PARSE_FAILED on garbage. */
-export function parseConfig(text: string | null, format: ConfigFormat): unknown | typeof PARSE_FAILED {
+export function parseConfig(
+  text: string | null,
+  format: ConfigFormat,
+  options?: { jsonc?: boolean },
+): unknown | typeof PARSE_FAILED {
   if (text === null || text.trim().length === 0) return {};
   try {
     switch (format) {
@@ -143,9 +148,13 @@ export function parseConfig(text: string | null, format: ConfigFormat): unknown
          * would otherwise cap the rewrite only after JSON.parse had already
          * built the 50k-deep object graph. The outcome is unchanged: invalid
          * JSON still returns PARSE_FAILED, from the catch below.
+         *
+         * Kilo's global file is JSONC. Comments and trailing commas are
+         * stripped first so the rewrite-safety scan sees JSON, not comment text.
          */
-        if (!jsonTextSafeToRewrite(text)) return PARSE_FAILED;
-        return JSON.parse(text);
+        const source = options?.jsonc ? canonicalizeJsonc(text) : text;
+        if (!jsonTextSafeToRewrite(source)) return PARSE_FAILED;
+        return JSON.parse(source);
       }
       case "json5": return Bun.JSON5.parse(text);
       case "yaml": return Bun.YAML.parse(text);

package/src/integrations/droid-settings.ts

@@ -0,0 +1,65 @@
+/** Read-only guard for competing Factory settings before a managed write. */
+import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync } from "node:fs";
+import { join, win32 } from "node:path";
+
+const isWindowsRoot = (path: string) => /^[A-Za-z]:[\\/]|^\\\\/.test(path);
+
+function endpointKey(value: string): string | null {
+  try {
+    const url = new URL(value);
+    if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+    const host = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname.toLowerCase())
+      ? "127.0.0.1" : url.hostname.toLowerCase();
+    return `${url.protocol}//${host}:${url.port}${url.pathname.replace(/\/+$/, "") || "/"}`;
+  } catch { return null; }
+}
+
+/** Other Factory settings can take priority over the managed personal rows. */
+export function assertDroidSettingsUnambiguous(root: string, baseUrl?: string, modelIds: readonly string[] = []): void {
+  const managedEndpoint = baseUrl === undefined ? null : endpointKey(baseUrl);
+  const managedModels = new Set(modelIds);
+  try {
+    const directory = lstatSync(root);
+    if (!directory.isDirectory()) throw new Error("Unsafe Factory settings directory");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+  for (const name of ["config.json", "settings.local.json"]) {
+    const path = isWindowsRoot(root) ? win32.join(root, name) : join(root, name);
+    let stat: ReturnType<typeof lstatSync>;
+    try { stat = lstatSync(path); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
+      throw new Error(`Cannot inspect Factory ${name}`);
+    }
+    if (!stat.isFile() || stat.size > 1024 * 1024) throw new Error(`Unsafe Factory ${name}`);
+    let value: unknown;
+    let fd: number | undefined;
+    try {
+      fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+      const opened = fstatSync(fd);
+      if (!opened.isFile() || opened.size > 1024 * 1024 || opened.ino !== stat.ino || opened.dev !== stat.dev) {
+        throw new Error("file changed during inspection");
+      }
+      value = JSON.parse(readFileSync(fd, "utf8"));
+    } catch { throw new Error(`Cannot safely parse Factory ${name}`); }
+    finally { if (fd !== undefined) closeSync(fd); }
+    if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`Unsafe Factory ${name}`);
+    const rows = name === "config.json"
+      ? (value as Record<string, unknown>).custom_models
+      : (value as Record<string, unknown>).customModels;
+    if (name === "settings.local.json" && rows !== undefined) {
+      throw new Error("Factory settings.local.json overrides customModels; resolve its precedence before enabling Droid");
+    }
+    if (name === "config.json" && Array.isArray(rows) && rows.some(row => {
+      if (!row || typeof row !== "object" || Array.isArray(row)) return false;
+      const legacy = row as Record<string, unknown>;
+      return (typeof legacy.display_name === "string" && legacy.display_name.startsWith("OpenCodex:"))
+        || (typeof legacy.model === "string" && managedModels.has(legacy.model))
+        || (managedEndpoint !== null && typeof legacy.base_url === "string"
+          && endpointKey(legacy.base_url) === managedEndpoint);
+    })) {
+      throw new Error("Factory config.json already defines OpenCodex models; resolve its precedence before enabling Droid");
+    }
+  }
+}

package/src/integrations/kilo-candidates.ts

@@ -0,0 +1,30 @@
+import { homedir } from "node:os";
+import { KILO_CONFIG_CANDIDATES, kiloCandidatePath, kiloHomeDir } from "../clients/config-export";
+import { loadTarget, parseConfig, PARSE_FAILED, type IntegrationIO } from "./config-io";
+
+/** Kilo deep-merges every global candidate, so an off-target provider can override ours. */
+export function inspectKiloCandidates(input: {
+  io: IntegrationIO;
+  selectedPath: string;
+  env?: NodeJS.ProcessEnv;
+  home?: string;
+}): { kind: "ok" } | { kind: "unsafe"; path: string; why: "unparseable" | "not-regular-file" }
+  | { kind: "conflict"; paths: string[] } {
+  const dir = kiloHomeDir(input.env ?? process.env, input.home ?? homedir());
+  const conflictPaths: string[] = [];
+  for (const name of KILO_CONFIG_CANDIDATES) {
+    const path = kiloCandidatePath(dir, name);
+    const loaded = loadTarget(input.io, path);
+    if (!loaded.ok) return { kind: "unsafe", path, why: loaded.why === "read-failed" ? "unparseable" : "not-regular-file" };
+    if (loaded.before === null) continue;
+    const parsed = parseConfig(loaded.before, "json", { jsonc: true });
+    if (parsed === PARSE_FAILED) return { kind: "unsafe", path, why: "unparseable" };
+    if (path !== input.selectedPath && typeof parsed === "object" && parsed !== null
+      && !Array.isArray(parsed) && Object.hasOwn(parsed, "provider")) {
+      const provider = (parsed as Record<string, unknown>).provider;
+      if (typeof provider === "object" && provider !== null && !Array.isArray(provider)
+        && Object.hasOwn(provider, "opencodex")) conflictPaths.push(path);
+    }
+  }
+  return conflictPaths.length > 0 ? { kind: "conflict", paths: conflictPaths } : { kind: "ok" };
+}

package/src/integrations/mutation-plan.ts

@@ -26,13 +26,18 @@ import { parseClineDocument } from "./cline-document";
 import { PARSE_FAILED, defaultIntegrationIO, loadTarget, parseConfig, type IntegrationIO } from "./config-io";
 import {
   INTEGRATION_CLIENTS,
+  boundIntegrationConfigPath,
+  assertDroidPathsUnambiguous,
+  assertDroidRecordedSettingsUnambiguous,
   isLoopbackOnly,
   resolveIntegrationPaths,
+  restoreOwnershipCollision,
   type IntegrationClientId,
 } from "./registry";
 import { declaredIntegrationTarget, resolveIntegrationTarget, type IntegrationTarget } from "./target";
 import { shouldInjectApiAuthHeader } from "../codex/inject";
 import { classifyIntegration, exportContextOf, readPath, type IntegrationState, type StateReason } from "./state";
+import { inspectKiloCandidates } from "./kilo-candidates";
 import { InvalidSelectorError } from "./merge";
 import { createIntegrationStateStore, type IntegrationStateStore } from "./store";
 import type { OcxConfig } from "../types";
@@ -144,6 +149,8 @@ const CLIENT_MANAGED_PATHS = {
     ["settings", "providers", OPENCODE_PROVIDER_ID],
     ["catalog", "providers", OPENCODE_PROVIDER_ID],
   ],
+  kilo: [["provider", OPENCODE_PROVIDER_ID]],
+  droid: [["customModels", DYNAMIC_SEGMENT]],
 } satisfies Record<IntegrationClientId, readonly (readonly string[])[]>;
 
 /** Not a configuration surface. Exported so a parity case can compare it against the shipped clients. */
@@ -339,6 +346,7 @@ function foreignEditOf(input: PlanInput): IntegrationPlanForeignEdit {
 function applyOutcome(input: PlanInput): PlanOutcome {
   if (input.installKind !== "dir") return deny("not_installed");
   if (input.admissionBlocked) return deny("non_loopback");
+  if (input.clientId === "droid" && input.contribution?.fragments.length === 0) return deny("unsafe");
   /*
    * Before any file state. The document may be perfectly writable and our block
    * may already be current in it; neither says anything about whether the
@@ -551,7 +559,9 @@ export function observeRestore(
   const clientId = input.clientId;
   let resolved: { configPath: string; detectDir: string };
   try {
-    resolved = input.resolvedPaths ?? resolveIntegrationPaths(clientId, input.env, input.home);
+    const context = exportContextOf(input);
+    resolved = input.resolvedPaths ?? resolveIntegrationPaths(clientId, input.env, input.home, context);
+    if (clientId === "droid" && input.resolvedPaths) assertDroidPathsUnambiguous(resolved.detectDir, context);
   } catch (error) {
     if (!(error instanceof ClientPathError)) throw error;
     return { failed: observationFailure("unsafe", "unsafe", error.message) } as const;
@@ -582,6 +592,22 @@ export function observeRestore(
       failed: observationFailure("conflict", "conflict", "that operation was recorded for a different location"),
     } as const;
   }
+  /*
+   * A legal historical path is not enough. Another candidate can already own
+   * the single record, and committing this row's prior record would orphan the
+   * block that candidate still holds. Direct restore asks the same question.
+   */
+  const currentOwner = store.readRecords()[clientId] ?? null;
+  const collision = restoreOwnershipCollision({
+    clientId,
+    journaledPath: configPath,
+    currentPath: currentOwner && currentOwner.clientId === clientId ? currentOwner.configPath : null,
+    env: input.env,
+    home: input.home,
+  });
+  if (collision !== null) {
+    return { failed: observationFailure("conflict", "conflict", collision) } as const;
+  }
   if (clientId === "cline") {
     try { io = createClineIO(io, configPath, store, effects.recover); }
     catch (error) {
@@ -640,7 +666,7 @@ export function previewIntegration(input: IntegrationWriteInput, request: Previe
   // Restore never reaches the general observation, because the writer's undo path never parses
   // or classifies and a preview that did would answer a different question.
   if (request.operation === "restore") return previewRestore(input, request);
-  const observed = observeIntegration(input, { maintenance: false, recover: false });
+  const observed = observeIntegration(input, { maintenance: false, recover: false }, request.operation);
   if (observed.failed) return unboundPlan(input.clientId, request.operation, observed.failed, request.profileId);
 
   const shared = {
@@ -743,7 +769,7 @@ function previewRestore(input: IntegrationWriteInput, request: PreviewRequest):
       ? {}
       : observed.clientId === "cline"
         ? parseClineDocument(observed.before)
-        : parseConfig(observed.before, observed.format),
+        : parseConfig(observed.before, observed.format, EXPORT_CLIENTS[observed.clientId].jsonc ? { jsonc: true } : undefined),
     restore: {
       opId: observed.entry.opId,
       entry: observed.entry,
@@ -812,7 +838,11 @@ export interface ObservationEffects {
  * classification rather than two independent reads that can disagree. The ordering of refusals is
  * load-bearing and is preserved exactly as the writer had it.
  */
-export function observeIntegration(input: IntegrationWriteInput, effects: ObservationEffects) {
+export function observeIntegration(
+  input: IntegrationWriteInput,
+  effects: ObservationEffects,
+  operation: Exclude<IntegrationPlanOperation, "restore">,
+) {
   const store = input.store ?? createIntegrationStateStore();
   let io = input.io ?? defaultIntegrationIO(store);
   const clientId = input.clientId;
@@ -839,7 +869,9 @@ export function observeIntegration(input: IntegrationWriteInput, effects: Observ
      * an Aside account switch land between the two, so a direct apply could
      * verify account 1 was installed and then write account 0's catalog.
      */
-    const resolved = input.resolvedPaths ?? resolveIntegrationPaths(clientId, input.env, input.home);
+    const context = exportContextOf(input);
+    const resolved = input.resolvedPaths ?? resolveIntegrationPaths(clientId, input.env, input.home, context);
+    if (clientId === "droid" && input.resolvedPaths) assertDroidPathsUnambiguous(resolved.detectDir, context);
     detectDir = resolved.detectDir;
     if (clientId === "cline") io = createClineIO(io, resolved.configPath, store, effects.recover);
     /*
@@ -850,6 +882,10 @@ export function observeIntegration(input: IntegrationWriteInput, effects: Observ
      * target is known, because that is the path it has to match.
      */
     stored = store.readRecords()[clientId] ?? null;
+    const recordedPath = boundIntegrationConfigPath({
+      clientId, record: stored, resolvedPath: resolved.configPath,
+      statKind: io.statKind, env: input.env, home: input.home,
+    });
     /*
      * Inside the same guard as resolution, because this resolver can refuse the
      * same way: the store is named by a client env var, and a relative one is a
@@ -857,7 +893,7 @@ export function observeIntegration(input: IntegrationWriteInput, effects: Observ
      * collection route.
      */
     effective = resolveIntegrationTarget({
-      clientId, configPath: resolved.configPath, io, record: stored, env: input.env, home: input.home,
+      clientId, configPath: recordedPath, io, record: stored, env: input.env, home: input.home,
     });
     configPath = effective.configPath;
   } catch (error) {
@@ -868,6 +904,13 @@ export function observeIntegration(input: IntegrationWriteInput, effects: Observ
     return { failed: observationFailure("unsafe", "unsafe", error.message) } as const;
   }
   // Pruning writes, so only a mutation may perform it. Preview reports the state it finds.
+  if (clientId === "kilo" && operation !== "disable") {
+    const candidates = inspectKiloCandidates({ io, selectedPath: configPath, env: input.env, home: input.home });
+    if (candidates.kind !== "ok") return { failed: candidates.kind === "conflict"
+      ? observationFailure("conflict", "conflict", `${configPath} cannot be managed while ${candidates.paths.join(", ")} also defines provider.opencodex`)
+      : observationFailure("unsafe", "unsafe", `${candidates.path} cannot be inspected safely (${candidates.why})`),
+    } as const;
+  }
   if (effects.maintenance) store.retryPendingPrunes();
 
   const loaded = loadTarget(io, configPath);
@@ -880,7 +923,9 @@ export function observeIntegration(input: IntegrationWriteInput, effects: Observ
     } as const;
   }
   const before = loaded.before;
-  const parsed = clientId === "cline" ? parseClineDocument(before) : parseConfig(before, effective.format);
+  const parsed = clientId === "cline"
+    ? parseClineDocument(before)
+    : parseConfig(before, effective.format, exportSpec.jsonc ? { jsonc: true } : undefined);
   if (parsed === PARSE_FAILED) {
     return { failed: observationFailure("unsafe", "unsafe",
       `${configPath} could not be parsed, or holds something opencodex cannot rewrite without changing it (a non-finite number, a large integer or a tiny one a rewrite would round, -0, a duplicate member, or nesting deeper than 1000 levels)`) } as const;
@@ -898,6 +943,9 @@ export function observeIntegration(input: IntegrationWriteInput, effects: Observ
   const record = stored && stored.clientId === clientId && stored.configPath === configPath
     ? stored
     : null;
+  if (clientId === "droid" && input.models.length > 0 && contribution.fragments.length === 0 && !record) {
+    return { failed: observationFailure("unsafe", "unsafe", "Factory Droid has no addressable models in the selected catalog") } as const;
+  }
   // `configPath`/`clientId` are load-bearing, not decoration: a record proves
   // ownership of ONE file, and the writer mutates whatever path resolves NOW.
   // Without them a record written for another home directory would grant
@@ -906,6 +954,13 @@ export function observeIntegration(input: IntegrationWriteInput, effects: Observ
     fileText: before, fileIsRegular: true, parsed, record, contribution, configPath, clientId,
     format: effective.format,
   });
+  if (clientId === "droid" && record && (classified.state === "current" || classified.state === "stale")) {
+    try { assertDroidRecordedSettingsUnambiguous(detectDir, parsed, record); }
+    catch (error) {
+      if (!(error instanceof ClientPathError)) throw error;
+      return { failed: observationFailure("unsafe", "unsafe", error.message) } as const;
+    }
+  }
   return {
     failed: undefined, store, io, clientId, spec, exportSpec, target: effective, configPath, detectDir,
     /*

package/src/integrations/native/ownership-preflight.ts

@@ -18,9 +18,11 @@ import {
 import {
   currentServiceHomes,
   inspectServiceStateEvidence,
-  serviceHomeMatches,
+  compareServicePathToInstall,
   type ServiceStateEvidence,
+  type ServicePathComparison,
 } from "../../service";
+import type { CodexHomeDeps } from "../../codex/home";
 import {
   createWindowsTaskListingCache,
   inspectServiceManagerInstallation,
@@ -70,15 +72,25 @@ export interface OwnershipInspection {
   readonly reason: string;
 }
 
-function claimNamesDifferentHome(
+function claimComparesToCurrentHomes(
   claim: ServiceManagerClaim,
   current: { codexHome: string; opencodexHome: string },
-): boolean {
+  deps: CodexHomeDeps,
+): ServicePathComparison {
   // A definition that OMITS a home is not a definition that disagrees about it:
   // an install run without CODEX_HOME set writes no such key at all.
-  if (claim.homes.codexHome !== null && !serviceHomeMatches(claim.homes.codexHome, current.codexHome)) return true;
-  if (claim.homes.opencodexHome !== null && !serviceHomeMatches(claim.homes.opencodexHome, current.opencodexHome)) return true;
-  return false;
+  let indeterminate = false;
+  if (claim.homes.codexHome !== null) {
+    const verdict = compareServicePathToInstall(claim.homes.codexHome, current.codexHome, deps);
+    if (verdict === "different") return "different";
+    indeterminate ||= verdict === "unknown";
+  }
+  if (claim.homes.opencodexHome !== null) {
+    const verdict = compareServicePathToInstall(claim.homes.opencodexHome, current.opencodexHome, deps);
+    if (verdict === "different") return "different";
+    indeterminate ||= verdict === "unknown";
+  }
+  return indeterminate ? "unknown" : "same";
 }
 
 /**
@@ -109,6 +121,8 @@ export interface OwnershipDeps extends ProbeDeps {
    */
   readonly statePaths?: readonly string[];
   readonly currentHomes?: { codexHome: string; opencodexHome: string };
+  /** Test seam for resolving recorded home aliases to their physical directory. */
+  readonly realpathSync?: (path: string) => string;
 }
 
 export function inspectNativeCodexOwnership(deps: OwnershipDeps = {}): OwnershipInspection {
@@ -130,22 +144,35 @@ export function inspectNativeCodexOwnership(deps: OwnershipDeps = {}): Ownership
   // Mirrors that disagree with each other are not a majority vote.
   for (const one of valid) {
     for (const other of valid) {
-      if (!serviceHomeMatches(one.state.codexHome, other.state.codexHome)
-        || !serviceHomeMatches(one.state.opencodexHome, other.state.opencodexHome)) {
+      if (compareServicePathToInstall(one.state.codexHome, other.state.codexHome, deps) !== "same"
+        || compareServicePathToInstall(one.state.opencodexHome, other.state.opencodexHome, deps) !== "same") {
         return { ownership: "unknown", reason: "two service state files disagree about which homes are installed" };
       }
     }
   }
 
-  const foreign = valid.find(e =>
-    !serviceHomeMatches(e.state.codexHome, current.codexHome)
-    || !serviceHomeMatches(e.state.opencodexHome, current.opencodexHome));
+  const evidenceComparesDifferent = (e: Extract<ServiceStateEvidence, { kind: "valid" }>): boolean =>
+    compareServicePathToInstall(e.state.codexHome, current.codexHome, deps) === "different"
+    || compareServicePathToInstall(e.state.opencodexHome, current.opencodexHome, deps) === "different";
+  const evidenceComparesIndeterminate = (e: Extract<ServiceStateEvidence, { kind: "valid" }>): boolean =>
+    compareServicePathToInstall(e.state.codexHome, current.codexHome, deps) === "unknown"
+    || compareServicePathToInstall(e.state.opencodexHome, current.opencodexHome, deps) === "unknown";
+  const foreign = valid.find(evidenceComparesDifferent);
   if (foreign) {
     return {
       ownership: "foreign",
       reason: `a service is installed for CODEX_HOME=${foreign.state.codexHome} / OPENCODEX_HOME=${foreign.state.opencodexHome}`,
     };
   }
+  // A resolution that could not run (EACCES, EPERM, a vanished directory, transient I/O)
+  // proves neither same nor different — report it as unknown, never as foreign.
+  const indeterminateEvidence = valid.find(evidenceComparesIndeterminate);
+  if (indeterminateEvidence) {
+    return {
+      ownership: "unknown",
+      reason: `a recorded home in ${indeterminateEvidence.path} could not be resolved for comparison`,
+    };
+  }
 
   // The manager assets live under the effective OPENCODEX_HOME. Production
   // callers do not inject ProbeDeps.configDir, so derive it from the same
@@ -162,7 +189,7 @@ export function inspectNativeCodexOwnership(deps: OwnershipDeps = {}): Ownership
     return { ownership: "unknown", reason: "more than one service manager holds a registration for this proxy" };
   }
   if (manager.kind === "present") {
-    const disagreeing = manager.claims.find(claim => claimNamesDifferentHome(claim, current));
+    const disagreeing = manager.claims.find(claim => claimComparesToCurrentHomes(claim, current, deps) === "different");
     if (disagreeing) {
       /*
        * The state file says this home and the definition says another. An
@@ -175,6 +202,13 @@ export function inspectNativeCodexOwnership(deps: OwnershipDeps = {}): Ownership
         reason: `${disagreeing.backend} is installed from ${disagreeing.definitionPath}, which names different homes than the recorded service state`,
       };
     }
+    const indeterminateClaim = manager.claims.find(claim => claimComparesToCurrentHomes(claim, current, deps) === "unknown");
+    if (indeterminateClaim) {
+      return {
+        ownership: "unknown",
+        reason: `the homes recorded in ${indeterminateClaim.definitionPath} could not be resolved for comparison`,
+      };
+    }
     // A manager backend that disagrees with the recorded state (e.g. state says
     // native/WinSW but a scheduler task is found) is an interrupted backend
     // switch: it does not prove which manager owns the installation. v1 state

package/src/integrations/registry.ts

@@ -9,11 +9,17 @@
  * Design of record: devlog/_fin/260802_client_toggle_api/021 §1.
  */
 import { homedir } from "node:os";
+import { assertDroidSettingsUnambiguous } from "./droid-settings";
+import { readPath } from "./merge";
+import type { OwnershipRecord } from "./ownership";
 import { join } from "node:path";
 import {
   ClientPathError,
+  buildDroidContribution,
   clineConfigPath,
   clineSettingsDir,
+  droidConfigPath,
+  droidHomeDir,
   EXPORT_CLIENTS,
   asideAccountDir,
   asideConfigPath,
@@ -48,7 +54,13 @@ import {
   zcodeStoreSchemaEstablished,
   type BuildContribution,
   type ConfigFormat,
+  kiloConfigPath,
+  kiloHomeDir,
+  kiloCandidatePath,
+  KILO_CONFIG_CANDIDATES,
   type ExportClientId,
+  type DroidModelEntry,
+  type ExportContext,
 } from "../clients/config-export";
 
 /**
@@ -93,13 +105,12 @@ export interface IntegrationClientSpec {
    * Derive the config path AND the detect directory from one resolution, for a
    * client whose paths depend on mutable state rather than only env and home.
    *
-   * Only Aside needs this. Its two paths both come from the account id in
-   * `accounts.json`, so calling `configPath` and `detectDir` in sequence can
-   * straddle an account switch and check one account's install while writing
-   * another's catalog. Reading the id once and deriving both paths from it
-   * removes the window instead of narrowing it.
+   * Aside needs this because both paths come from the account id in
+   * `accounts.json`: one read prevents an account switch between resolutions.
+   * Droid uses the same seam to check competing settings against the export
+   * context before status, preview, or mutation proceeds.
    */
-  resolvePaths?: (env?: NodeJS.ProcessEnv, home?: string) => { configPath: string; detectDir: string };
+  resolvePaths?: (env?: NodeJS.ProcessEnv, home?: string, exportContext?: ExportContext) => { configPath: string; detectDir: string };
   /**
    * Where the client's config WOULD live, for a client whose real path cannot
    * be resolved yet.
@@ -115,6 +126,19 @@ export interface IntegrationClientSpec {
    * catalog. `resolveIntegrationPaths` still throws for callers that mutate.
    */
   unresolvedPathHint?: (env?: NodeJS.ProcessEnv, home?: string) => string;
+  /**
+   * Recognize a resolution drift that is still THIS client's own file, for a
+   * client whose config path depends on mutable world state rather than only
+   * env and home.
+   *
+   * Kilo resolves to the first EXISTING candidate, so a candidate created
+   * after apply moves resolution while the owned file still holds our block.
+   * While this predicate accepts the recorded path, reads and mutations stay
+   * bound to it instead of silently re-homing onto the newcomer. A client
+   * without this hook never binds: a record from another home stays a refusal
+   * ("a record for one home cannot authorize a write to another").
+   */
+  bindsDriftedRecord?: (recordPath: string, env?: NodeJS.ProcessEnv, home?: string) => boolean;
 }
 
 /**
@@ -129,12 +153,38 @@ export function resolveIntegrationPaths(
   clientId: IntegrationClientId,
   env: NodeJS.ProcessEnv = process.env,
   home: string = homedir(),
+  exportContext?: ExportContext,
 ): { configPath: string; detectDir: string } {
   const spec = INTEGRATION_CLIENTS[clientId];
-  if (spec.resolvePaths) return spec.resolvePaths(env, home);
+  if (spec.resolvePaths) return spec.resolvePaths(env, home, exportContext);
   return { configPath: spec.configPath(env, home), detectDir: spec.detectDir(env, home) };
 }
 
+export function assertDroidPathsUnambiguous(root: string, exportContext?: ExportContext): void {
+  try {
+    const generated = exportContext ? buildDroidContribution(exportContext).fragments : [];
+    assertDroidSettingsUnambiguous(root, exportContext?.baseUrl, generated.map(fragment => (fragment.value as DroidModelEntry).model));
+  }
+  catch (error) { throw new ClientPathError((error as Error).message); }
+}
+
+/** Check the identities still owned on disk even after they leave the catalog. */
+export function assertDroidRecordedSettingsUnambiguous(root: string, parsed: unknown, record: OwnershipRecord): void {
+  try {
+    const byEndpoint = new Map<string, Set<string>>();
+    for (const path of record.fragmentPaths) {
+      const row = readPath(parsed, path) as Partial<DroidModelEntry> | undefined;
+      if (typeof row?.baseUrl !== "string" || typeof row.model !== "string") {
+        throw new Error("Cannot verify recorded Factory Droid rows");
+      }
+      const models = byEndpoint.get(row.baseUrl) ?? new Set<string>();
+      models.add(row.model);
+      byEndpoint.set(row.baseUrl, models);
+    }
+    for (const [baseUrl, models] of byEndpoint) assertDroidSettingsUnambiguous(root, baseUrl, [...models]);
+  } catch (error) { throw new ClientPathError((error as Error).message); }
+}
+
 /**
  * The location to name when resolution refused, or `""` when there is none.
  *
@@ -345,11 +395,90 @@ export const INTEGRATION_CLIENTS: Record<IntegrationClientId, IntegrationClientS
     detectDir: (env = process.env, home = homedir()) => clineSettingsDir(env, home),
     writerLock: { suffix: ".lock" },
   },
+  kilo: {
+    id: "kilo",
+    configPath: (env = process.env, home = homedir()) => kiloConfigPath(env, home),
+    detectDir: (env = process.env, home = homedir()) => kiloHomeDir(env, home),
+    bindsDriftedRecord: (recordPath, env = process.env, home = homedir()) =>
+      KILO_CONFIG_CANDIDATES.some(name => recordPath === kiloCandidatePath(kiloHomeDir(env, home), name)),
+  },
+  droid: {
+    id: "droid",
+    configPath: (env = process.env, home = homedir()) => droidConfigPath(env, home),
+    detectDir: (env = process.env, home = homedir()) => droidHomeDir(env, home),
+    resolvePaths: (env = process.env, home = homedir(), exportContext) => {
+      const detectDir = droidHomeDir(env, home);
+      assertDroidPathsUnambiguous(detectDir, exportContext);
+      return { configPath: droidConfigPath(env, home), detectDir };
+    },
+  },
 };
 
 export const INTEGRATION_CLIENT_IDS: readonly IntegrationClientId[] =
   Object.keys(INTEGRATION_CLIENTS) as IntegrationClientId[];
 
+/**
+ * The effective config path for a read or mutation, given the ownership record.
+ *
+ * One implementation for status AND the mutation planner: when only one side
+ * carried the binding, the two could disagree again and status would report a
+ * file the writer never touches. Binds only while the client's own
+ * `bindsDriftedRecord` accepts the recorded path (still one of that client's
+ * candidates under the CURRENT env and home) and the file still exists; a
+ * record from another home never binds and keeps its refusal contract.
+ */
+export function boundIntegrationConfigPath(input: {
+  clientId: IntegrationClientId;
+  record: { clientId: IntegrationClientId; configPath: string } | null;
+  resolvedPath: string;
+  statKind: (path: string) => string;
+  env?: NodeJS.ProcessEnv;
+  home?: string;
+}): string {
+  const record = input.record;
+  if (
+    record && record.clientId === input.clientId &&
+    record.configPath !== input.resolvedPath &&
+    input.statKind(record.configPath) === "file" &&
+    INTEGRATION_CLIENTS[input.clientId].bindsDriftedRecord?.(record.configPath, input.env, input.home) === true
+  ) {
+    return record.configPath;
+  }
+  return input.resolvedPath;
+}
+
+/**
+ * Why a historical restore must not run, or null when it may.
+ *
+ * Kilo keeps one ownership record and may legally have written more than one
+ * candidate. Treating every same-home journaled path as a restore target lets
+ * an undo of an older file commit that file's prior record over the candidate
+ * that owns the integration now. The managed block in the current file stays
+ * on disk, the record points at the old file, and a later disable drops the
+ * record and orphans the newcomer.
+ *
+ * A missing current record is not a collision: undoing the disable that
+ * dropped it still restores the journaled file. A client without
+ * bindsDriftedRecord is unchanged, because that seam is what made the second
+ * candidate a legal target. Direct restore and its preview both ask here, so
+ * they cannot admit different answers.
+ */
+export function restoreOwnershipCollision(input: {
+  clientId: IntegrationClientId;
+  journaledPath: string;
+  currentPath: string | null;
+  env?: NodeJS.ProcessEnv;
+  home?: string;
+}): string | null {
+  const currentPath = input.currentPath;
+  if (currentPath === null || currentPath === input.journaledPath) return null;
+  const binds = INTEGRATION_CLIENTS[input.clientId].bindsDriftedRecord;
+  if (!binds) return null;
+  if (binds(input.journaledPath, input.env, input.home) !== true) return null;
+  if (binds(currentPath, input.env, input.home) !== true) return null;
+  return `that operation was recorded for ${input.journaledPath}, but ${currentPath} currently owns this integration`;
+}
+
 export function isIntegrationClientId(value: string): value is IntegrationClientId {
   return Object.prototype.hasOwnProperty.call(INTEGRATION_CLIENTS, value);
 }