deepseek-web-retrieval 0.4.0 → 0.5.1

package/src/installer/formats/value.ts

@@ -1,45 +1,45 @@
-export function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value)
-}
+import { isPlainObject } from "../../core/object";
+
+export { isPlainObject };
 
 export function deepEqual(a: unknown, b: unknown): boolean {
-  if (a === b) return true
-  if (a === null || b === null || typeof a !== "object" || typeof b !== "object") return false
-  const aArray = Array.isArray(a)
-  const bArray = Array.isArray(b)
-  if (aArray !== bArray) return false
+  if (a === b) return true;
+  if (a === null || b === null || typeof a !== "object" || typeof b !== "object") return false;
+  const aArray = Array.isArray(a);
+  const bArray = Array.isArray(b);
+  if (aArray !== bArray) return false;
   if (aArray && bArray) {
-    const x = a as unknown[]
-    const y = b as unknown[]
-    return x.length === y.length && x.every((item, index) => deepEqual(item, y[index]))
+    const x = a as unknown[];
+    const y = b as unknown[];
+    return x.length === y.length && x.every((item, index) => deepEqual(item, y[index]));
   }
-  const x = a as Record<string, unknown>
-  const y = b as Record<string, unknown>
-  const xKeys = Object.keys(x)
-  const yKeys = Object.keys(y)
-  return xKeys.length === yKeys.length && xKeys.every((key) => deepEqual(x[key], y[key]))
+  const x = a as Record<string, unknown>;
+  const y = b as Record<string, unknown>;
+  const xKeys = Object.keys(x);
+  const yKeys = Object.keys(y);
+  return xKeys.length === yKeys.length && xKeys.every((key) => deepEqual(x[key], y[key]));
 }
 
 /** Reads the value at a dotted path from a parsed object, or undefined when absent. */
 export function valueAt(value: Record<string, unknown>, path: readonly string[]): unknown {
-  let node: unknown = value
+  let node: unknown = value;
   for (const key of path) {
     if (Array.isArray(node)) {
-      const index = Number(key)
-      node = Number.isInteger(index) ? node[index] : undefined
+      const index = Number(key);
+      node = Number.isInteger(index) ? node[index] : undefined;
     } else if (isPlainObject(node)) {
-      node = node[key]
+      node = node[key];
     } else {
-      return undefined
+      return undefined;
     }
-    if (node === undefined) return undefined
+    if (node === undefined) return undefined;
   }
-  return node
+  return node;
 }
 
 export function removeAt(value: Record<string, unknown>, path: readonly string[]): void {
-  const parent = valueAt(value, path.slice(0, -1))
-  if (isPlainObject(parent)) delete parent[path[path.length - 1] as string]
+  const parent = valueAt(value, path.slice(0, -1));
+  if (isPlainObject(parent)) delete parent[path[path.length - 1] as string];
 }
 
 /**
@@ -47,11 +47,15 @@ export function removeAt(value: Record<string, unknown>, path: readonly string[]
  * path and dedupes entries already present, so applied records list only what
  * was actually appended.
  */
-export function appendEntries(existing: unknown, entries: readonly unknown[], path: readonly string[]): { readonly list: readonly unknown[]; readonly appended: readonly unknown[] } {
+export function appendEntries(
+  existing: unknown,
+  entries: readonly unknown[],
+  path: readonly string[],
+): { readonly list: readonly unknown[]; readonly appended: readonly unknown[] } {
   if (existing !== undefined && !Array.isArray(existing)) {
-    throw new Error(`cannot append to ${path.join(".")}: it is a ${typeof existing}, not an array`)
+    throw new Error(`cannot append to ${path.join(".")}: it is a ${typeof existing}, not an array`);
   }
-  const list = Array.isArray(existing) ? existing : []
-  const appended = entries.filter((entry) => !list.some((item) => deepEqual(item, entry)))
-  return { list, appended }
+  const list = Array.isArray(existing) ? existing : [];
+  const appended = entries.filter((entry) => !list.some((item) => deepEqual(item, entry)));
+  return { list, appended };
 }

package/src/installer/hosts/codex.ts

@@ -1,51 +1,81 @@
-import { codecFor } from "../formats"
-import { isPlainObject } from "../formats/value"
-import {
-  FORCED_COST_NOTE,
-  othersStayRegisteredNote,
-  replacingExistingEntryNote,
-  splitCompetitors,
-} from "../detect"
-import { join } from "../paths"
-import { API_KEY_ENV, ENABLE_FETCH_ENV, ENABLE_SEARCH_ENV } from "../../core/constants"
-import { buildRulesBlock } from "../formats/rules"
-import { MCP_TOOL_IDS, rulesLines } from "../rulesContent"
-import { planHeader } from "./shared"
-import type { ConfigOp, FileEdit, HostPaths, InstallRecord, InstallerInput, InstallPlan } from "../types"
+import { spawnSync } from "node:child_process";
+import { API_KEY_ENV } from "../../core/constants";
+import { FORCED_COST_NOTE, othersStayRegisteredNote, replacingExistingEntryNote, splitCompetitors } from "../detect";
+import { codecFor } from "../formats";
+import { buildRulesBlock } from "../formats/rules";
+import { isPlainObject } from "../formats/value";
+import { join } from "../paths";
+import { MCP_TOOL_IDS, RAW_MCP_TOOL_IDS, rulesLines } from "../rulesContent";
+import type { ConfigOp, FileEdit, HostPaths, InstallerInput, InstallPlan, InstallRecord } from "../types";
+import { planHeader } from "./shared";
+
+/**
+ * The Codex release this installer's facts are verified against — the lock in
+ * docs/hosts.jsonc; the drift note fires when the probed CLI differs.
+ */
+export const CODEX_TESTED_VERSION = "0.163.0";
+
+/**
+ * The one subprocess the installer runs: `codex --version`, probed for the
+ * version-drift note. A missing binary or unreadable output skips the check with
+ * a stderr note and never blocks the plan — honor or report.
+ */
+export function probeCodexVersion(err: (line: string) => void): string | undefined {
+  // env passed explicitly: runtime PATH edits (tests) must reach the lookup.
+  const result = spawnSync("codex", ["--version"], { timeout: 5000, encoding: "utf8", env: process.env });
+  const version = result.status === 0 ? parseCodexVersion(result.stdout ?? "") : undefined;
+  if (version === undefined) {
+    err("note: codex was not found on PATH or printed no version; the version-drift check was skipped");
+  }
+  return version;
+}
+
+/** Parses `codex --version` output (`codex-cli 0.163.0`) into the bare version. */
+export function parseCodexVersion(output: string): string | undefined {
+  return /\bcodex(?:-cli)?\s+(\d+\.\d+\.\d+)\b/.exec(output)?.[1];
+}
 
 /** Codex config is user-level only; project scope keeps the rules file project-local. */
 function codexPaths(input: InstallerInput): HostPaths {
   return {
     config: join(input.home, ".codex/config.toml"),
     rules: input.scope === "global" ? join(input.home, ".codex/AGENTS.md") : join(input.cwd, "AGENTS.md"),
-  }
+  };
 }
 
 export function planCodex(input: InstallerInput, _previous: InstallRecord | undefined): InstallPlan {
-  const paths = codexPaths(input)
-  const loaded = codecFor("toml", input.host).load(paths.config)
-  const tiers = { search: input.search, fetch: input.fetch }
-  const header = planHeader(input, paths, loaded, "TOML")
+  const paths = codexPaths(input);
+  const loaded = codecFor("toml", input.host).load(paths.config);
+  const tiers = { search: input.search, fetch: input.fetch };
+  const header = planHeader(input, paths, loaded, "TOML");
   if (header.abort) {
-    return { host: "codex", scope: input.scope, tiers, edits: [], notes: header.notes, errors: header.errors }
+    return { host: "codex", scope: input.scope, tiers, edits: [], notes: header.notes, errors: header.errors };
   }
-  const notes = [...header.notes]
-  const errors = [...header.errors]
-  const edits: FileEdit[] = []
+  const notes = [...header.notes];
+  const errors = [...header.errors];
+  const edits: FileEdit[] = [];
 
-  const tools = loaded.value.tools
+  if (input.hostVersion !== undefined && input.hostVersion !== CODEX_TESTED_VERSION) {
+    notes.push(
+      `Codex ${input.hostVersion} is installed, but this installer's Codex facts are verified against ` +
+        `${CODEX_TESTED_VERSION} (the docs/hosts.jsonc lock). Kill-switch and trap behavior may have drifted ` +
+        "between the two — re-verify the tiers if routing misbehaves.",
+    );
+  }
+
+  const tools = loaded.value.tools;
   if (isPlainObject(tools) && "web_search" in tools) {
     errors.push({
       message:
         `${paths.config} sets [tools] web_search, which is a silent no-op at Codex 0.163.0 (only the top-level ` +
         "web_search key controls the tool). Remove it first so the config cannot mislead.",
-    })
+    });
   }
 
-  const servers = loaded.value.mcp_servers
+  const servers = loaded.value.mcp_servers;
   if (isPlainObject(servers)) {
-    if ("deepseek" in servers) notes.push(replacingExistingEntryNote("mcp_servers.deepseek"))
-    const { competitors, bystanders } = splitCompetitors(servers)
+    if ("deepseek" in servers) notes.push(replacingExistingEntryNote("mcp_servers.deepseek"));
+    const { competitors, bystanders } = splitCompetitors(servers);
     if ((input.search === "forced" || input.fetch === "forced") && competitors.length > 0) {
       // Codex has no per-server kill switch (only per-tool enabled_tools/disabled_tools
       // inside a server), so a web-capable competitor cannot be excluded from the plan —
@@ -55,60 +85,76 @@ export function planCodex(input: InstallerInput, _previous: InstallRecord | unde
           `Forced cannot deliver exclusive routing: [mcp_servers.${competitors.join("], [mcp_servers.")}] look(s) web-capable, ` +
           "and Codex offers no per-server kill switch. Remove the server(s), disable their tools by hand via their " +
           "disabled_tools key, or choose a lower tier.",
-      })
+      });
     }
-    const stayRegistered = input.search === "forced" || input.fetch === "forced" ? bystanders : [...competitors, ...bystanders]
-    if (stayRegistered.length > 0) notes.push(othersStayRegisteredNote(stayRegistered))
+    const stayRegistered =
+      input.search === "forced" || input.fetch === "forced" ? bystanders : [...competitors, ...bystanders];
+    if (stayRegistered.length > 0) notes.push(othersStayRegisteredNote(stayRegistered));
   }
 
-  const env: Record<string, string> = {}
-  if (input.search === "off") env[ENABLE_SEARCH_ENV] = "false"
-  if (input.fetch === "off") env[ENABLE_FETCH_ENV] = "false"
+  const existingEntry = isPlainObject(servers) ? servers.deepseek : undefined;
+  // The entry's disabled_tools key carries the user's own entries (ours filtered out)
+  // plus the off tier's tool names, so re-inits and uninstall stay whole-entry ops —
+  // an append inside a set op's subtree would break both verify and the drift check.
+  const rawToolIds: readonly string[] = Object.values(RAW_MCP_TOOL_IDS);
+  const keptDisabled =
+    isPlainObject(existingEntry) && Array.isArray(existingEntry.disabled_tools)
+      ? existingEntry.disabled_tools.filter(
+          (name): name is string => typeof name === "string" && !rawToolIds.includes(name),
+        )
+      : [];
+  const offDisabled = [
+    ...(input.search === "off" ? [RAW_MCP_TOOL_IDS.search] : []),
+    ...(input.fetch === "off" ? [RAW_MCP_TOOL_IDS.fetch] : []),
+  ];
   const entry = {
     command: "npx",
     args: ["-y", input.packageRef],
-    ...(Object.keys(env).length > 0 ? { env } : {}),
+    ...(keptDisabled.length > 0 || offDisabled.length > 0 ? { disabled_tools: [...keptDisabled, ...offDisabled] } : {}),
     env_vars: [API_KEY_ENV],
-  }
+  };
 
-  const existingEntry = isPlainObject(servers) ? servers.deepseek : undefined
-  const ops: ConfigOp[] = [
-    { op: "set", path: ["mcp_servers", "deepseek"], value: entry, previous: existingEntry },
-  ]
+  const ops: ConfigOp[] = [{ op: "set", path: ["mcp_servers", "deepseek"], value: entry, previous: existingEntry }];
+  if (offDisabled.length > 0) {
+    notes.push(
+      `Off capabilities use Codex's own disabled_tools key (${offDisabled.join(", ")}): the tools are removed from ` +
+        "the model's context while the server keeps running and stays re-enableable by deleting the entries.",
+    );
+  }
   if (input.search === "forced") {
-    const previous = typeof loaded.value.web_search === "string" ? loaded.value.web_search : undefined
-    ops.push({ op: "set", path: ["web_search"], value: "disabled", previous })
+    const previous = typeof loaded.value.web_search === "string" ? loaded.value.web_search : undefined;
+    ops.push({ op: "set", path: ["web_search"], value: "disabled", previous });
     notes.push(
       previous === undefined
-        ? "web_search is being set to \"disabled\" (no previous value existed; the default is \"cached\")."
+        ? 'web_search is being set to "disabled" (no previous value existed; the default is "cached").'
         : `web_search is being set to "disabled"; the previous value "${previous}" is snapshotted for uninstall.`,
-    )
+    );
   }
-  edits.push({ file: paths.config, format: "toml", ops })
+  edits.push({ file: paths.config, format: "toml", shared: true, ops });
 
   notes.push(
     `Codex stdio children do not inherit the parent environment, so the entry forwards ${API_KEY_ENV} explicitly ` +
       "via env_vars; the key must be set in the shell that launches Codex.",
-  )
+  );
   if (input.scope === "project") {
     notes.push(
       "Codex config lives in ~/.codex/config.toml only (user level), so the server registration and kill switch are " +
         "written there even for a project-scope install; the rules file stays project-local.",
-    )
+    );
   }
   if (loaded.lossy) {
-    notes.push(`${paths.config} contains comments; the TOML rewrite will drop them.`)
+    notes.push(`${paths.config} contains comments; the TOML rewrite will drop them.`);
   }
   if (input.search === "forced" || input.fetch === "forced") {
     notes.push(
-      'Forced search is exclusion: the built-in web_search tool is disabled ("disabled" mode). ' + FORCED_COST_NOTE,
-    )
+      `Forced search is exclusion: the built-in web_search tool is disabled ("disabled" mode). ${FORCED_COST_NOTE}`,
+    );
   }
   if (input.search === "optional" || input.fetch === "optional") {
     notes.push(
       'Note: Codex ships a built-in web_search tool (default "cached" mode, an OpenAI index) that stays available ' +
         "alongside the DeepSeek tools under the optional tier.",
-    )
+    );
   }
 
   if (input.search === "preferred" || input.fetch === "preferred") {
@@ -116,13 +162,13 @@ export function planCodex(input: InstallerInput, _previous: InstallRecord | unde
       file: paths.rules,
       format: "rules",
       block: buildRulesBlock(input.host, rulesLines(MCP_TOOL_IDS, input.search, input.fetch)),
-    })
+    });
     notes.push(
       input.scope === "global"
         ? `Rules block upserted in ${paths.rules}; Codex reads ~/.codex/AGENTS.md plus every AGENTS.md from the project root to the cwd.`
         : `Rules block upserted in ${paths.rules}; Codex reads every AGENTS.md from the project root to the cwd.`,
-    )
+    );
   }
 
-  return { host: "codex", scope: input.scope, tiers, edits, notes, errors }
+  return { host: "codex", scope: input.scope, tiers, edits, notes, errors };
 }

package/src/installer/hosts/index.ts

@@ -1,15 +1,17 @@
-import { planCodex } from "./codex"
-import { planOpenCode } from "./opencode"
-import { planPi } from "./pi"
-import { API_KEY_ENV } from "../../core/constants"
-import { claimedByOtherScope, readRecord } from "../state"
-import type { HostName, InstallRecord, InstallerInput, InstallPlan, RecordedFile } from "../types"
+import { API_KEY_ENV } from "../../core/constants";
+import { deepEqual, isPlainObject } from "../formats/value";
+import { assertFileOwnership, fileOwnershipNotes } from "../ownership";
+import { claimedByOtherScope, InstallRecordError, readRecord } from "../state";
+import type { HostName, InstallerInput, InstallPlan, InstallRecord, RecordedFile } from "../types";
+import { planCodex, probeCodexVersion } from "./codex";
+import { planOpenCode } from "./opencode";
+import { planPi } from "./pi";
 
 /**
  * A host planner sees the previous install record for its scope, so it never reads
  * install state itself; planForHost is the one place a record read happens per plan.
  */
-export type HostPlanner = (input: InstallerInput, previous: InstallRecord | undefined) => InstallPlan
+export type HostPlanner = (input: InstallerInput, previous: InstallRecord | undefined) => InstallPlan;
 
 /**
  * The host registry. Key order feeds the CLI's usage string; a new host is one
@@ -21,12 +23,36 @@ export const HOST_PLANNERS: Readonly<Record<HostName, HostPlanner>> = {
   opencode: planOpenCode,
   pi: planPi,
   codex: planCodex,
-}
+};
+
+/**
+ * Per-host version probes the CLI edge runs before planning, so "which host
+ * needs a probe" is a host-module fact, not a CLI branch. A missing entry means
+ * the host's plan never reads hostVersion.
+ */
+export const HOST_VERSION_PROBES: Partial<Record<HostName, (err: (line: string) => void) => string | undefined>> = {
+  codex: probeCodexVersion,
+};
 
 export function planForHost(host: HostName, input: InstallerInput): InstallPlan {
-  const previous = readRecord(input)
-  const planned = withCrossScopeGuard(HOST_PLANNERS[host](input, previous), input)
-  return withSecretGuard(withOrphanReverts(planned, input, previous))
+  try {
+    const previous = readRecord(input);
+    const planned = withCrossScopeGuard(HOST_PLANNERS[host](input, previous), input);
+    return {
+      ...withSecretGuard(withOrphanReverts(withLegacySharedConfigGuard(planned, previous), previous)),
+      previousRecord: previous,
+    };
+  } catch (error) {
+    if (!(error instanceof InstallRecordError)) throw error;
+    return {
+      host,
+      scope: input.scope,
+      tiers: { search: input.search, fetch: input.fetch },
+      edits: [],
+      notes: [],
+      errors: [{ message: error.message }],
+    };
+  }
 }
 
 /**
@@ -36,10 +62,18 @@ export function planForHost(host: HostName, input: InstallerInput): InstallPlan
  * instead. Hosts whose scope pairs map to disjoint files (Pi, OpenCode) pass through.
  */
 function withCrossScopeGuard(plan: InstallPlan, input: InstallerInput): InstallPlan {
-  if (plan.errors.length > 0) return plan
-  const other = input.scope === "global" ? "project" : "global"
-  const overlap = claimedByOtherScope(input, plan.edits.map((edit) => edit.file))
-  if (overlap.length === 0) return plan
+  if (plan.errors.length > 0) return plan;
+  try {
+    assertFileOwnership(input, plan.edits);
+  } catch (error) {
+    return { ...plan, edits: [], reverts: undefined, errors: [{ message: String(error) }] };
+  }
+  const other = input.scope === "global" ? "project" : "global";
+  const overlap = claimedByOtherScope(
+    input,
+    plan.edits.map((edit) => edit.file),
+  );
+  if (overlap.length === 0) return { ...plan, notes: [...plan.notes, ...fileOwnershipNotes(input, plan.edits)] };
   return {
     ...plan,
     edits: [],
@@ -52,7 +86,46 @@ function withCrossScopeGuard(plan: InstallPlan, input: InstallerInput): InstallP
           `or re-run with --scope ${other} to update it in place — two scopes must not edit one file.`,
       },
     ],
+  };
+}
+
+/**
+ * Old installers had no shared ownership sidecar. A generated registration
+ * without this scope's record may belong to an unknown project; adopting it
+ * would snapshot installed values and recreate the cross-project undo bug.
+ */
+function withLegacySharedConfigGuard(plan: InstallPlan, previous: InstallRecord | undefined): InstallPlan {
+  if (plan.errors.length > 0 || previous !== undefined) return plan;
+  for (const edit of plan.edits) {
+    if (edit.format === "rules" || !edit.shared) continue;
+    for (const op of edit.ops) {
+      const old = op.previous;
+      if (
+        op.op !== "set" ||
+        !isPlainObject(old) ||
+        old.command !== "npx" ||
+        !Array.isArray(old.args) ||
+        old.args[0] !== "-y" ||
+        !Array.isArray(old.env_vars) ||
+        !old.env_vars.includes(API_KEY_ENV)
+      )
+        continue;
+      return {
+        ...plan,
+        edits: [],
+        reverts: undefined,
+        errors: [
+          {
+            message:
+              `${edit.file} contains an installer-style registration without an install record for this location. ` +
+              "It may belong to an older install in another project. Re-run init or uninstall from that original project and scope first; " +
+              "if the registration was created manually, remove it before retrying. No existing registration was adopted.",
+          },
+        ],
+      };
+    }
   }
+  return plan;
 }
 
 /**
@@ -64,10 +137,10 @@ function withCrossScopeGuard(plan: InstallPlan, input: InstallerInput): InstallP
  */
 function withSecretGuard(plan: InstallPlan): InstallPlan {
   for (const edit of plan.edits) {
-    if (edit.format === "rules") continue // rules edits carry no values to snapshot
+    if (edit.format === "rules") continue; // rules edits carry no values to snapshot
     for (const op of edit.ops) {
-      if (op.op !== "set" || op.previous === undefined) continue
-      const offender = findSecretLike(op.previous, op.path.join("."))
+      if (op.op !== "set" || op.previous === undefined) continue;
+      const offender = findSecretLike(op.previous, op.path.join("."));
       if (offender !== undefined) {
         return {
           ...plan,
@@ -81,29 +154,29 @@ function withSecretGuard(plan: InstallPlan): InstallPlan {
                 `environment indirection ("\${${API_KEY_ENV}}" expansion or env_vars) and re-run.`,
             },
           ],
-        }
+        };
       }
     }
   }
-  return plan
+  return plan;
 }
 
 function findSecretLike(value: unknown, at: string): string | undefined {
-  if (typeof value !== "object" || value === null) return undefined
+  if (typeof value !== "object" || value === null) return undefined;
   for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
-    const path = `${at}.${key}`
+    const path = `${at}.${key}`;
     if (
       /(api[_-]?key|token|secret|password|credential)/i.test(key) &&
       typeof child === "string" &&
       child.length > 0 &&
       !/^\$\{[^}]+\}$/.test(child)
     ) {
-      return path
+      return path;
     }
-    const nested = findSecretLike(child, path)
-    if (nested !== undefined) return nested
+    const nested = findSecretLike(child, path);
+    if (nested !== undefined) return nested;
   }
-  return undefined
+  return undefined;
 }
 
 /**
@@ -111,24 +184,36 @@ function findSecretLike(value: unknown, at: string): string | undefined {
  * that the new plan no longer wants must be reverted explicitly — otherwise it is
  * silently orphaned (and uninstall could never restore it). Whole files missing
  * from the new plan revert entirely; files shared with the new plan revert only
- * the ops whose paths the new plan does not touch.
+ * the ops whose paths the new plan does not touch — and for a same-path
+ * append-array, only the entries the new plan no longer wants (a changed
+ * --package ref, retired tier options) revert, so a replaced entry never
+ * lingers beside its replacement.
  */
-function withOrphanReverts(plan: InstallPlan, input: InstallerInput, previous: InstallRecord | undefined): InstallPlan {
-  if (plan.errors.length > 0) return plan
-  if (previous === undefined) return plan
-  const reverts: RecordedFile[] = []
+function withOrphanReverts(plan: InstallPlan, previous: InstallRecord | undefined): InstallPlan {
+  if (plan.errors.length > 0) return plan;
+  if (previous === undefined) return plan;
+  const reverts: RecordedFile[] = [];
   for (const file of previous.files) {
-    const edit = plan.edits.find((candidate) => candidate.file === file.file)
+    const edit = plan.edits.find((candidate) => candidate.file === file.file);
     if (edit === undefined) {
-      reverts.push(file)
-      continue
+      reverts.push(file);
+      continue;
     }
-    if (edit.format === "rules" || file.format === "rules") continue // the new plan's block supersedes ours
-    const orphanOps = file.ops.filter(
-      (op) => !edit.ops.some((candidate) => candidate.op === op.op && candidate.path.join("\u0000") === op.path.join("\u0000")),
-    )
-    if (orphanOps.length > 0) reverts.push({ ...file, ops: orphanOps })
+    if (edit.format === "rules" || file.format === "rules") continue; // the new plan's block supersedes ours
+    const orphanOps = file.ops.flatMap((op) => {
+      const claimed = edit.ops.find(
+        (candidate) => candidate.op === op.op && candidate.path.join("\u0000") === op.path.join("\u0000"),
+      );
+      if (op.op !== "append-array" || claimed === undefined || claimed.op !== "append-array") {
+        return claimed === undefined ? [op] : [];
+      }
+      const dropped = (Array.isArray(op.applied) ? op.applied : []).filter(
+        (entry) => !(claimed.entries ?? []).some((wanted) => deepEqual(wanted, entry)),
+      );
+      return dropped.length > 0 ? [{ ...op, applied: dropped }] : [];
+    });
+    if (orphanOps.length > 0) reverts.push({ ...file, ops: orphanOps });
   }
-  if (reverts.length === 0) return plan
-  return { ...plan, reverts }
+  if (reverts.length === 0) return plan;
+  return { ...plan, reverts };
 }