@bitkyc08/opencodex 2.77.0 → 2.78.0

package/src/integrations/merge.ts

@@ -184,9 +184,11 @@ export function setPath(doc: unknown, path: readonly string[], value: unknown):
   /*
    * `parent[slot]` is the position the segment just consumed addresses. The
    * root sits in a one-key holder so the first segment needs no special case:
-   * a non-record document is replaced by `{}` exactly as before.
+   * a document that is neither a record nor a sequence is replaced by `{}`
+   * exactly as before. A sequence root survives so a leading selector can
+   * address one of its entries (a DSH profile patch is a top-level list).
    */
-  const holder: Record<string, unknown> = { root: isPlainRecord(doc) ? clone(doc) : {} };
+  const holder: Record<string, unknown> = { root: isPlainRecord(doc) || Array.isArray(doc) ? clone(doc) : {} };
   let parent: Record<string, unknown> | unknown[] = holder;
   let slot: string | number = "root";
   const read = (): unknown => (Array.isArray(parent) ? parent[slot as number] : parent[slot as string]);
@@ -244,8 +246,8 @@ export function deletePath(
   path: readonly string[],
   createdContainers: ReadonlySet<string> = new Set(),
 ): { doc: unknown; removed: boolean } {
-  if (!isPlainRecord(doc) || path.length === 0) return { doc, removed: false };
-  const root = clone(doc) as Record<string, unknown>;
+  if ((!isPlainRecord(doc) && !Array.isArray(doc)) || path.length === 0) return { doc, removed: false };
+  const root = clone(doc) as Record<string, unknown> | unknown[];
   // `chain[i]` is the container segment `i` is resolved against; `slots[i]` is
   // the key or index it resolved to, so the prune walk can delete by position.
   const chain: (Record<string, unknown> | unknown[])[] = [root];
@@ -288,7 +290,13 @@ export function deletePath(
    */
   for (let index = path.length - 1; index >= 1; index -= 1) {
     const container = chain[index]!;
-    const empty = Array.isArray(container) ? container.length === 0 : Object.keys(container).length === 0;
+    // An element we pushed for a selector is empty once only the fields that seeded it remain.
+    const segment = parseSegment(path[index - 1]!);
+    const empty = Array.isArray(container)
+      ? container.length === 0
+      : segment.kind === "select"
+        ? Object.keys(container).length === segment.criteria.length && selectIndex([container], segment.criteria) === 0
+        : Object.keys(container).length === 0;
     if (!empty) break;
     const containerPath = path.slice(0, index).join("\u0000");
     if (!createdContainers.has(containerPath)) break;

package/src/integrations/mutation-plan.ts

@@ -14,6 +14,7 @@
  * preview route.
  */
 import { createHash } from "node:crypto";
+import { dirname } from "node:path";
 import { canonicalContribution, fingerprint, type OwnershipRecord } from "./ownership";
 import { ClientPathError, EXPORT_CLIENTS, type ExportModel, type ManagedContribution } from "../clients/config-export";
 import { OPENCODE_PROVIDER_ID } from "../clients/config-export/constants";
@@ -34,7 +35,7 @@ import {
   restoreOwnershipCollision,
   type IntegrationClientId,
 } from "./registry";
-import { declaredIntegrationTarget, resolveIntegrationTarget, type IntegrationTarget } from "./target";
+import { declaredIntegrationTarget, resolveIntegrationTarget, type IneffectiveWrite, type IneffectiveWriteReason, type IntegrationTarget } from "./target";
 import { shouldInjectApiAuthHeader } from "../codex/inject";
 import { buildIntegrationContribution, classifyIntegration, exportContextOf, readPath, type IntegrationState, type StateReason } from "./state";
 import { inspectKiloCandidates } from "./kilo-candidates";
@@ -99,6 +100,13 @@ export interface IntegrationMutationPlan {
    */
   readonly willChange: boolean;
   readonly refusalReason?: RefusalReason;
+  /**
+   * `superseded_store` only: why the store the client reads is not written. The store's location
+   * stays on the status row (`supersededBy`); the plan names no file.
+   */
+  readonly supersededReason?: IneffectiveWriteReason;
+  /** `missing-store` only: the document that recreates the store, so the remedy can name it. */
+  readonly missingStoreDocument?: string;
   readonly profileId?: number;
 }
 
@@ -129,7 +137,7 @@ const CLIENT_MANAGED_PATHS = {
   openclaw: [["models", "providers", OPENCODE_PROVIDER_ID]],
   kimi: [["providers", OPENCODE_PROVIDER_ID], ["models", DYNAMIC_SEGMENT]],
   gajae: [["providers", OPENCODE_PROVIDER_ID]],
-  dsh: [["llm-pi-ai", "providers", OPENCODE_PROVIDER_ID]],
+  dsh: [["llm-pi-ai", "providers", OPENCODE_PROVIDER_ID], ["[id=llm-pi-ai]", "config", "providers", OPENCODE_PROVIDER_ID]],
   mcode: [["custom_provider", OPENCODE_PROVIDER_ID]],
   zcode: [
     ["provider", OPENCODE_PROVIDER_ID],
@@ -245,6 +253,11 @@ export interface PlanFingerprintInput {
    * flip as a store appearing.
    */
   readonly ineffectiveWrite: string | null;
+  /**
+   * The same finding as `ineffectiveWrite`, unflattened, for the refusal's description. It is
+   * descriptive only: the bound token above is what decides and what the fingerprint covers.
+   */
+  readonly ineffective?: IneffectiveWrite | null;
   /** Exact current bytes, or null when the target is missing. Missing and empty are not equal. */
   readonly before: string | null;
   readonly contribution: ManagedContribution | null;
@@ -497,6 +510,12 @@ export function buildMutationPlan(input: PlanInput): IntegrationMutationPlan {
     canApply: outcome.kind !== "refuse",
     willChange: outcome.kind === "change",
     ...(outcome.kind === "refuse" ? { refusalReason: outcome.reason } : {}),
+    ...(outcome.kind === "refuse" && outcome.reason === "superseded_store" && input.ineffective
+      ? {
+          supersededReason: input.ineffective.why,
+          ...(input.ineffective.emptyDocument === undefined ? {} : { missingStoreDocument: input.ineffective.emptyDocument }),
+        }
+      : {}),
     ...(input.profileId === undefined ? {} : { profileId: input.profileId }),
   });
 }
@@ -531,6 +550,25 @@ function unboundPlan(
   });
 }
 
+/** A restore must not recreate a declared store without its client's lock. */
+export function restoreStoreDirectoryRefusal(
+  input: IntegrationWriteInput,
+  configPath: string,
+  io: IntegrationIO,
+): string | null {
+  const declared = INTEGRATION_CLIENTS[input.clientId].currentStore;
+  if (!declared?.lockFile) return null;
+  let storePath: string;
+  try {
+    storePath = declared.path(input.env, input.home);
+  } catch (error) {
+    if (error instanceof ClientPathError) return null;
+    throw error;
+  }
+  return configPath === storePath && io.statKind(dirname(storePath)) !== "dir"
+    ? "the client store directory is missing; restore will not create it" : null;
+}
+
 /**
  * Restore reads a different specification, so it gets its own observation.
  *
@@ -592,6 +630,10 @@ export function observeRestore(
       failed: observationFailure("conflict", "conflict", "that operation was recorded for a different location"),
     } as const;
   }
+  const directoryRefusal = restoreStoreDirectoryRefusal(input, configPath, io);
+  if (directoryRefusal !== null) {
+    return { failed: observationFailure("unsafe", "unsafe", directoryRefusal) } 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
@@ -678,6 +720,7 @@ export function previewIntegration(input: IntegrationWriteInput, request: Previe
     // Loopback-only clients cannot carry the admission header a non-loopback bind requires.
     admissionBlocked: isLoopbackOnly(observed.clientId) && shouldInjectApiAuthHeader(input.config),
     ineffectiveWrite: observed.ineffectiveWrite,
+    ineffective: observed.target.ineffective,
     before: observed.before,
     contribution: observed.contribution,
     record: observed.record,
@@ -954,7 +997,7 @@ export function observeIntegration(
   // ownership here and disable would delete fragments it never wrote.
   const classified = classifyIntegration({
     fileText: before, fileIsRegular: true, parsed, record, contribution, configPath, clientId,
-    format: effective.format,
+    format: effective.format, sourcePreservingYaml: effective.sourcePreservingYaml !== null,
   });
   if (clientId === "droid" && record && (classified.state === "current" || classified.state === "stale")) {
     try { assertDroidRecordedSettingsUnambiguous(detectDir, parsed, record); }

package/src/integrations/omp-yaml-source.ts

@@ -7,6 +7,7 @@
  * expected document; unsupported YAML fails closed and never falls back to a
  * whole-document serializer.
  */
+import { parseSegment, selectIndex, type SelectorCriterion } from "./merge";
 import { renderYaml } from "./serialize";
 
 interface SourceLine {
@@ -442,6 +443,7 @@ function upsertSource(
   path: readonly string[],
   value: unknown,
 ): string | null {
+  if (leadingSelector(path) !== null) return upsertSequenceEntry(text, parsed, path, value);
   const located = locatePath(text, parsed, path);
   if (located === null || located.kind === "unsupported-style") return null;
   const eol = lineEnding(text);
@@ -467,6 +469,178 @@ function upsertSource(
   return preserveFinalNewline(candidate, text, eol);
 }
 
+/**
+ * The criteria of a path whose first segment selects one entry of a top-level
+ * sequence, or null for an ordinary block-map path.
+ *
+ * DSH 0.1.7+ keeps settings in a profile patch: a YAML list of loader rows,
+ * `- id: llm-pi-ai` among them. The entry is patched as the block map it is
+ * once its `- ` indicator and two-space continuation indent are set aside, and
+ * both are put back byte for byte. Every other list shape fails closed.
+ */
+function leadingSelector(path: readonly string[]): readonly SelectorCriterion[] | null {
+  if (path.length === 0) return null;
+  const segment = parseSegment(path[0]!);
+  return segment.kind === "select" ? segment.criteria : null;
+}
+
+/** Line ranges of a block sequence's top-level entries, or null for any other document shape. */
+function topLevelEntries(lines: readonly SourceLine[]): Array<{ start: number; end: number }> | null {
+  const entries: Array<{ start: number; end: number }> = [];
+  let open = false;
+  for (let index = 0; index < lines.length; index += 1) {
+    const body = lines[index]!.body;
+    if (isBlank(body)) continue;
+    const spaces = leadingSpaces(body);
+    if (spaces === null) return null;
+    if (spaces > 0) {
+      // Continuation of the open entry; deeper text anywhere else is not a list we can place.
+      if (!open) return null;
+      continue;
+    }
+    if (open) entries[entries.length - 1]!.end = index;
+    open = false;
+    if (isComment(body)) continue;
+    if (!/^- \S/u.test(body)) return null;
+    entries.push({ start: index, end: lines.length });
+    open = true;
+  }
+  return entries;
+}
+
+/** The entry's text as the block map it holds, or null when it is not in the two-space form. */
+function entrySource(text: string, lines: readonly SourceLine[], start: number, end: number): string | null {
+  let source = "";
+  for (let index = start; index < end; index += 1) {
+    const line = lines[index]!;
+    const raw = text.slice(line.start, line.end);
+    if (index === start) source += raw.slice(2);
+    else if (isBlank(line.body)) source += raw;
+    else if ((leadingSpaces(line.body) ?? 0) >= 2) source += raw.slice(2);
+    else return null;
+  }
+  return source;
+}
+
+/** Put an entry back: `- ` on its first line, two spaces on every other non-blank line. */
+function reindentEntry(source: string): string {
+  return sourceLines(source).map((line, index) => {
+    const raw = source.slice(line.start, line.end);
+    if (index === 0) return `- ${raw}`;
+    return isBlank(line.body) ? raw : `  ${raw}`;
+  }).join("");
+}
+
+function firstLine(text: string): string {
+  return text.split(/\r?\n/u, 1)[0] ?? "";
+}
+
+type SequenceEntry =
+  | {
+      kind: "found";
+      criteria: readonly SelectorCriterion[];
+      rest: readonly string[];
+      /** Byte range of the entry, trailing blank lines included. */
+      startOffset: number;
+      endOffset: number;
+      source: string;
+      parsed: Record<string, unknown>;
+      /** Entries the list keeps if this one is removed. */
+      siblings: number;
+    }
+  | {
+      kind: "missing";
+      criteria: readonly SelectorCriterion[];
+      rest: readonly string[];
+      /** Where a new entry goes, and the end of the `[]` line it replaces, if any. */
+      insertAt: number;
+      replaceEnd: number | null;
+    };
+
+function sequenceEntry(text: string, parsed: unknown, path: readonly string[]): SequenceEntry | null {
+  const criteria = leadingSelector(path);
+  if (criteria === null || !Array.isArray(parsed)) return null;
+  const lines = sourceLines(text);
+  const rest = path.slice(1);
+  const found = selectIndex(parsed, criteria);
+  const entries = topLevelEntries(lines);
+  if (entries === null) {
+    // `[]` is how DSH writes a profile patch with no rows yet: the one flow form adopted.
+    const content = lines.filter(line => !isBlank(line.body) && !isComment(line.body));
+    if (found >= 0 || parsed.length !== 0 || content.length !== 1 || content[0]!.body.trimEnd() !== "[]") return null;
+    return { kind: "missing", criteria, rest, insertAt: content[0]!.start, replaceEnd: content[0]!.end };
+  }
+  if (entries.length !== parsed.length) return null;
+  if (found < 0) return { kind: "missing", criteria, rest, insertAt: text.length, replaceEnd: null };
+  const element = parsed[found];
+  const { start, end } = entries[found]!;
+  const source = entrySource(text, lines, start, end);
+  if (!isPlainRecord(element) || source === null) return null;
+  return {
+    kind: "found",
+    criteria,
+    rest,
+    startOffset: lines[start]!.start,
+    endOffset: end < lines.length ? lines[end]!.start : text.length,
+    source,
+    parsed: element,
+    siblings: entries.length - 1,
+  };
+}
+
+function spliceEntry(text: string, entry: Extract<SequenceEntry, { kind: "found" }>, replacement: string): string {
+  return `${text.slice(0, entry.startOffset)}${replacement}${text.slice(entry.endOffset)}`;
+}
+
+function upsertSequenceEntry(text: string, parsed: unknown, path: readonly string[], value: unknown): string | null {
+  const entry = sequenceEntry(text, parsed, path);
+  if (entry === null) return null;
+  const eol = lineEnding(text);
+  if (entry.kind === "found") {
+    if (entry.rest.length === 0) return null;
+    const patched = upsertSource(entry.source, entry.parsed, entry.rest, value);
+    // The `- ` belongs to the entry's first line; a patch that rewrote that line cannot take it back.
+    if (patched === null || firstLine(patched) !== firstLine(entry.source)) return null;
+    return preserveFinalNewline(spliceEntry(text, entry, reindentEntry(patched)), text, eol);
+  }
+  // The same element `setPath` seeds: the selector's own fields, then the fragment beneath them.
+  const seeded = Object.fromEntries(entry.criteria.map(criterion => [criterion.field, criterion.value]));
+  const element = entry.rest.length === 0 ? value : { ...seeded, ...nestedValue(entry.rest, value) };
+  if (!isPlainRecord(element)) return null;
+  const item = reindentEntry(rendered(element, 0, eol));
+  if (entry.replaceEnd !== null) {
+    return preserveFinalNewline(`${text.slice(0, entry.insertAt)}${item}${text.slice(entry.replaceEnd)}`, text, eol);
+  }
+  const prefix = text.length > 0 && !text.endsWith("\n") ? eol : "";
+  return preserveFinalNewline(`${text}${prefix}${item}`, text, eol);
+}
+
+function removeSequenceEntryPath(
+  text: string,
+  parsed: unknown,
+  path: readonly string[],
+  requireEmpty: boolean,
+): string | null {
+  const entry = sequenceEntry(text, parsed, path);
+  if (entry === null || entry.kind !== "found") return null;
+  if (entry.rest.length > 0) {
+    const patched = removeExactPath(entry.source, entry.rest, requireEmpty);
+    if (patched === null || firstLine(patched) !== firstLine(entry.source)) return null;
+    return spliceEntry(text, entry, reindentEntry(patched));
+  }
+  if (requireEmpty) {
+    // A pruned entry may still hold what its selector seeded, and nothing else.
+    const seededOnly = Object.keys(entry.parsed).length === entry.criteria.length
+      && selectIndex([entry.parsed], entry.criteria) === 0;
+    if (!seededOnly || sourceLines(entry.source).some(line => hasInlineComment(line.body) || isComment(line.body))) {
+      return null;
+    }
+  }
+  // A list left with no entries goes back to the `[]` DSH writes for an empty one.
+  const eol = lineEnding(text);
+  return preserveFinalNewline(spliceEntry(text, entry, entry.siblings === 0 ? `[]${eol}` : ""), text, eol);
+}
+
 function removeExactPath(text: string, path: readonly string[], requireEmpty: boolean): string | null {
   let parsed: unknown;
   try {
@@ -474,6 +648,7 @@ function removeExactPath(text: string, path: readonly string[], requireEmpty: bo
   } catch {
     return null;
   }
+  if (leadingSelector(path) !== null) return removeSequenceEntryPath(text, parsed, path, requireEmpty);
   const located = locatePath(text, parsed, path);
   if (located === null || located.kind !== "existing") return null;
   const { lines, index, endIndex } = located.entry;
@@ -506,7 +681,7 @@ function planSourceRemoval(
     next = pruned;
     prunedContainers.push(encoded);
   }
-  return { text: next, prunedContainers };
+  return { text: preserveFinalNewline(next, text, lineEnding(text)), prunedContainers };
 }
 
 /** Containers whose source ranges are still empty and safe to prune. */
@@ -560,6 +735,11 @@ export function yamlFragmentUnsupportedStyle(text: string, path: readonly string
   } catch {
     return false;
   }
+  if (leadingSelector(path) !== null) {
+    const entry = sequenceEntry(text, parsed, path);
+    return entry?.kind === "found" && entry.rest.length > 0
+      && locatePath(entry.source, entry.parsed, entry.rest)?.kind === "unsupported-style";
+  }
   return locatePath(text, parsed, path)?.kind === "unsupported-style";
 }
 

package/src/integrations/ownership-policy.ts

@@ -14,6 +14,7 @@ import {
 } from "../clients/config-export";
 import { canonicalContribution, fingerprint, semanticContribution, type OwnershipRecord } from "./ownership";
 import { readPath } from "./merge";
+import { serializeDocument } from "./serialize";
 
 type JsonObject = Record<string, unknown>;
 
@@ -51,6 +52,71 @@ export function isHermesAffinityUpgrade(
       && fingerprint(semanticContribution(predecessor)) === record.semanticBlockFingerprint);
 }
 
+function removeDroidNormalizationFields(row: Record<string, unknown>): boolean {
+  let projected = false;
+  if (Object.hasOwn(row, "id")) {
+    delete row.id;
+    projected = true;
+  }
+  if (Object.hasOwn(row, "index")) {
+    delete row.index;
+    projected = true;
+  }
+  return projected;
+}
+
+function projectObservedDroidContribution(
+  contribution: ManagedContribution,
+): ManagedContribution {
+  if (contribution.clientId !== "droid") return contribution;
+  let projected = false;
+  const fragments = contribution.fragments.map(fragment => {
+    if (
+      fragment.path.length !== 2
+      || fragment.path[0] !== "customModels"
+      || !isObject(fragment.value)
+    ) return fragment;
+    const value = { ...fragment.value };
+    if (!removeDroidNormalizationFields(value)) return fragment;
+    projected = true;
+    return { ...fragment, value };
+  });
+  return projected ? { ...contribution, fragments } : contribution;
+}
+
+export function droidNormalizedContributionMatchesRecord(
+  observed: ManagedContribution,
+  record: OwnershipRecord,
+): boolean {
+  const projectedObserved = projectObservedDroidContribution(observed);
+  return projectedObserved !== observed
+    && (
+      fingerprint(canonicalContribution(projectedObserved)) === record.blockFingerprint
+      || (typeof record.semanticBlockFingerprint === "string"
+        && fingerprint(semanticContribution(projectedObserved)) === record.semanticBlockFingerprint)
+    );
+}
+
+export function droidNormalizedFileMatchesRecord(
+  document: unknown,
+  record: OwnershipRecord,
+): boolean {
+  if (record.clientId !== "droid") return false;
+  try {
+    const normalized = structuredClone(document);
+    let projected = false;
+    for (const path of record.fragmentPaths) {
+      if (path.length !== 2 || path[0] !== "customModels") return false;
+      const row = readPath(normalized, path);
+      if (!isObject(row)) return false;
+      if (removeDroidNormalizationFields(row)) projected = true;
+    }
+    return projected && fingerprint(serializeDocument(normalized, "json")) === record.fileFingerprint;
+  } catch {
+    return false;
+  }
+}
+
 function pathStartsWith(path: readonly string[], prefix: readonly string[]): boolean {
   return prefix.length <= path.length && prefix.every((part, index) => path[index] === part);
 }

package/src/integrations/registry.ts

@@ -12,7 +12,7 @@ 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 { dirname, join } from "node:path";
 import {
   ClientPathError,
   buildDroidContribution,
@@ -52,6 +52,10 @@ import {
   zcodeProviderStorePath,
   buildZcodeStoreContribution,
   zcodeStoreSchemaEstablished,
+  dshProfilePatchPath,
+  dshProfilePatchEstablished,
+  buildDshProfilePatchContribution,
+  DSH_PROFILE_PROVIDER_PATH,
   type BuildContribution,
   type ConfigFormat,
   kiloConfigPath,
@@ -96,6 +100,29 @@ export interface IntegrationClientSpec {
     format: ConfigFormat;
     establishes: (parsed: unknown) => boolean;
     buildContribution: BuildContribution;
+    /** Patch only this leaf of the store, as `sourcePreservingYaml` does for the config file. */
+    sourcePreservingYaml?: { path: readonly string[] };
+    /**
+     * The file whose `<file>.lock` sibling the client's own writer holds while
+     * it rewrites the store. Taken after the config file's lock, whenever the
+     * store's directory exists.
+     */
+    lockFile?: (storePath: string) => string;
+    /**
+     * A missing store the client already manages. Writing the config file instead would not stay
+     * where opencodex records it, so the target is reported as an ineffective write with this
+     * remedy rather than silently writing the config file.
+     */
+    missingStore?: {
+      readsStore: (storePath: string, statKind: (path: string) => string) => boolean;
+      /**
+       * The document the client writes into a new store. Creating the store with exactly this is
+       * the remedy, and it is published on its own so a surface that localizes the remedy text
+       * can still name what to write.
+       */
+      emptyDocument: string;
+      remedy: string;
+    };
   };
   /** Patch only this block-map YAML leaf; never re-render the shared file. */
   sourcePreservingYaml?: { path: readonly string[] };
@@ -297,6 +324,28 @@ export const INTEGRATION_CLIENTS: Record<IntegrationClientId, IntegrationClientS
     detectDir: (env = process.env, home = homedir()) => dshHomeDir(env, home),
     sourcePreservingYaml: { path: ["llm-pi-ai", "providers", "opencodex"] },
     writerLock: { suffix: ".lock" },
+    /*
+     * DSH 0.1.7+ imports `settings.yaml` once into the first profile that boots
+     * and renames it; what it reads afterwards is the Desktop profile's patch.
+     */
+    currentStore: {
+      path: (env = process.env, home = homedir()) => dshProfilePatchPath(env, home),
+      format: "yaml",
+      establishes: dshProfilePatchEstablished,
+      buildContribution: buildDshProfilePatchContribution,
+      sourcePreservingYaml: { path: DSH_PROFILE_PROVIDER_PATH },
+      // DSH's config editor serializes profile edits on the profile manifest's lock.
+      lockFile: store => join(dirname(store), "package.json"),
+      // A Desktop profile manifest without its patch is a profile DSH manages. On each startup
+      // DSH's importLegacyDocument renames `settings.yaml` to `settings.yaml.imported` and imports
+      // it into the active profile, so a block written there would leave opencodex's ownership
+      // record pointing at a file that no longer exists. Refuse it and name the remedy instead.
+      missingStore: {
+        readsStore: (store, statKind) => statKind(join(dirname(store), "package.json")) === "file",
+        emptyDocument: "[]",
+        remedy: "Create it containing `[]` (the empty patch DSH writes for a new profile), then enable the integration again.",
+      },
+    },
   },
   mcode: {
     id: "mcode",

package/src/integrations/state.ts

@@ -25,6 +25,8 @@ import {
 } from "./merge";
 import { canonicalContribution, fingerprint, semanticContribution, type OwnershipRecord } from "./ownership";
 import {
+  droidNormalizedContributionMatchesRecord,
+  droidNormalizedFileMatchesRecord,
   isHermesAffinityUpgrade,
   protectedContributionFingerprint,
   refreshablePathsOf,
@@ -40,7 +42,7 @@ import {
   unresolvedPathHintFor,
   type IntegrationClientId,
 } from "./registry";
-import { resolveIntegrationTarget, type IntegrationTarget } from "./target";
+import { resolveIntegrationTarget, type IneffectiveWriteReason, type IntegrationTarget } from "./target";
 import { inspectKiloCandidates } from "./kilo-candidates";
 import { createIntegrationStateStore, type IntegrationStateStore } from "./store";
 
@@ -84,6 +86,13 @@ export interface IntegrationStatus {
    * `current` has to be able to report this beside it.
    */
   supersededBy?: string;
+  /** Why `supersededBy` is not written; present exactly when it is. */
+  supersededReason?: IneffectiveWriteReason;
+  /**
+   * `missing-store` only: the document that recreates the store. A surface that localizes the
+   * remedy needs the content to name, not the writer's English sentence.
+   */
+  missingStoreDocument?: string;
   /** Snapshot files retained for this client; -1 when they cannot be inspected. */
   snapshotCount: number;
   /** Pruning is behind, so older (possibly credential-bearing) snapshots remain. */
@@ -208,6 +217,18 @@ function recordedContribution(
   };
 }
 
+function observedContributionMatchesRecord(
+  observed: ManagedContribution,
+  record: OwnershipRecord,
+): boolean {
+  if (fingerprint(canonicalContribution(observed)) === record.blockFingerprint) return true;
+  if (
+    typeof record.semanticBlockFingerprint === "string"
+    && fingerprint(semanticContribution(observed)) === record.semanticBlockFingerprint
+  ) return true;
+  return droidNormalizedContributionMatchesRecord(observed, record);
+}
+
 /**
  * Prove that every protected field still matches what OpenCodex wrote.
  *
@@ -223,13 +244,8 @@ function recordedBlockIsOwned(
 ): boolean {
   const observed = recordedContribution(doc, record);
   if (!observed) return false;
-  if (fingerprint(canonicalContribution(observed)) === record.blockFingerprint) return true;
-
+  if (observedContributionMatchesRecord(observed, record)) return true;
   const observedSemanticFingerprint = fingerprint(semanticContribution(observed));
-  if (
-    typeof record.semanticBlockFingerprint === "string"
-    && observedSemanticFingerprint === record.semanticBlockFingerprint
-  ) return true;
 
   const desiredFingerprint = fingerprint(canonicalContribution(desired));
   if (
@@ -304,6 +320,12 @@ export function classifyIntegration(input: {
    * the wrong way.
    */
   format?: ConfigFormat;
+  /**
+   * Whether the file being classified is patched in place, which makes a
+   * sibling edit harmless. Like `format`, it belongs to the target; omitted, the
+   * client's config-file declaration answers.
+   */
+  sourcePreservingYaml?: boolean;
 }): { state: IntegrationState; reason?: StateReason } {
   if (input.fileText !== null && !input.fileIsRegular) {
     return { state: "unsafe", reason: "not-regular-file" };
@@ -405,12 +427,16 @@ export function classifyIntegration(input: {
     && !isHermesAffinityUpgrade(input.parsed, input.record, input.contribution)) {
     return { state: "conflict", reason: "foreign-edit" };
   }
-  if (!INTEGRATION_CLIENTS[clientId].sourcePreservingYaml
-    && fingerprint(input.fileText ?? "") !== input.record.fileFingerprint) {
+  if (!(input.sourcePreservingYaml ?? INTEGRATION_CLIENTS[clientId].sourcePreservingYaml !== undefined)
+    && fingerprint(input.fileText ?? "") !== input.record.fileFingerprint
+    && !droidNormalizedFileMatchesRecord(input.parsed, input.record)) {
     /*
-     * The file changed since we wrote it, but every fragment we own is still
-     * byte-for-byte what we put there — a sibling edit, not tampering. Apply
-     * rewrites the WHOLE document, so for comment-capable formats (yaml,
+     * The file changed since we wrote it. Every fragment we own is still
+     * byte-for-byte what we put there, so this is a sibling edit rather than
+     * tampering. Known Droid row normalization is accepted before this branch
+     * only when removing its two client fields reproduces the recorded file.
+     * Other drift reaches this branch. Apply rewrites the WHOLE document, so
+     * for comment-capable formats (yaml,
      * json5, toml) it would drop comments the user wrote next to us: fail
      * closed there. Strict JSON cannot carry comments — a commented file
      * never reaches this branch because parsing already failed — so the only
@@ -500,14 +526,8 @@ export function buildIntegrationContribution(
 
 function recordedDroidContributionMatches(document: unknown, record: OwnershipRecord): boolean {
   try {
-    const fragments = record.fragmentPaths.flatMap(path => {
-      const value = readPath(document, path);
-      return value === undefined ? [] : [{ path, value }];
-    });
-    if (fragments.length !== record.fragmentPaths.length) return false;
-    const observed: ManagedContribution = { clientId: "droid", fragments };
-    return record.semanticBlockFingerprint === fingerprint(semanticContribution(observed))
-      || record.blockFingerprint === fingerprint(canonicalContribution(observed));
+    const observed = recordedContribution(document, record);
+    return observed !== null && observedContributionMatchesRecord(observed, record);
   } catch {
     return false;
   }
@@ -655,6 +675,7 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
     configPath,
     clientId: input.clientId,
     format: effective.format,
+    sourcePreservingYaml: effective.sourcePreservingYaml !== null,
   });
   if (input.clientId === "droid" && record && (state === "current" || state === "stale")) {
     try { assertDroidRecordedSettingsUnambiguous(spec.detectDir(input.env, input.home), parsed, record); }
@@ -676,7 +697,11 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
      * about. A store we are writing needs no notice; the path already names it.
      */
     ...(effective.ineffective && effective.ineffective.store !== configPath
-      ? { supersededBy: effective.ineffective.store }
+      ? {
+          supersededBy: effective.ineffective.store,
+          supersededReason: effective.ineffective.why,
+          ...(effective.ineffective.emptyDocument === undefined ? {} : { missingStoreDocument: effective.ineffective.emptyDocument }),
+        }
       : {}),
     ...(record ? { appliedAt: record.appliedAt, lastOpId: record.opId } : {}),
     ...retention,