@bitkyc08/opencodex 2.15.1 → 2.17.0

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

@@ -1,14 +1,11 @@
 /**
- * Source-preserving mutation for the one YAML fragment managed by OMP.
+ * Source-preserving mutation for one plain block-map YAML fragment.
  *
- * The general integration writer operates on parsed documents. Re-rendering a
- * shared YAML file would preserve values but destroy comments and formatting
- * outside `providers.opencodex`. OMP is the only client whose ownership model
- * deliberately permits those unrelated source edits, so its writer replaces
- * or removes only the exact block-style mapping entry it owns.
- *
- * Unsupported or ambiguous YAML returns `null`. The caller treats that as an
- * unsafe refusal instead of falling back to whole-document serialization.
+ * Shared client settings are not ours to re-render. This scanner accepts only
+ * the small, unambiguous source shape we can patch byte-for-byte around the
+ * owned leaf. Every candidate is parsed again and compared with the complete
+ * expected document; unsupported YAML fails closed and never falls back to a
+ * whole-document serializer.
  */
 import { renderYaml } from "./serialize";
 
@@ -18,6 +15,26 @@ interface SourceLine {
   body: string;
 }
 
+interface LocatedEntry {
+  lines: readonly SourceLine[];
+  index: number;
+  indent: number;
+  endIndex: number;
+}
+
+interface MissingEntry {
+  lines: readonly SourceLine[];
+  missingDepth: number;
+  indent: number;
+  insertAt: number;
+}
+
+type LocatedPath = { kind: "existing"; entry: LocatedEntry } | { kind: "missing"; entry: MissingEntry };
+
+export type YamlFragmentMutation =
+  | { kind: "upsert"; value: unknown }
+  | { kind: "remove"; createdContainers: readonly string[] };
+
 export type OmpYamlMutation =
   | { kind: "upsert"; value: unknown }
   | { kind: "remove"; removeEmptyProviders: boolean };
@@ -54,11 +71,15 @@ function hasInlineComment(line: string): boolean {
   return line.includes("#");
 }
 
+function regexpEscape(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+
 function isPlainBlockKey(line: string, indent: number, key: string): boolean {
   const spaces = leadingSpaces(line);
   if (spaces !== indent) return false;
   const rest = line.slice(indent);
-  return new RegExp(`^${key}:[ ]*(?:#.*)?$`, "u").test(rest);
+  return new RegExp(`^${regexpEscape(key)}:[ ]*(?:#.*)?$`, "u").test(rest);
 }
 
 function containerEnd(lines: readonly SourceLine[], start: number, indent: number): number | null {
@@ -86,9 +107,8 @@ function childEnd(
     const body = lines[index]!.body;
     const spaces = leadingSpaces(body);
     if (spaces === null) return null;
-    // Blank lines and same-level comments are conservatively outside the
-    // managed entry. Deeper comments would be destroyed by replacement, so
-    // refuse rather than guessing whether the user meant to keep them.
+    // Blank lines and same-level comments remain outside our replacement.
+    // Deeper comments belong to the leaf and would be destroyed, so refuse.
     if (isBlank(body)) return index;
     if (isComment(body)) return spaces <= indent ? index : null;
     if (spaces <= indent) return index;
@@ -112,8 +132,7 @@ function canonicalValue(value: unknown): unknown {
 function semanticallyMatches(text: string, expected: unknown): boolean {
   try {
     const parsed = text.trim().length === 0 ? {} : Bun.YAML.parse(text);
-    return JSON.stringify(canonicalValue(parsed))
-      === JSON.stringify(canonicalValue(expected));
+    return JSON.stringify(canonicalValue(parsed)) === JSON.stringify(canonicalValue(expected));
   } catch {
     return false;
   }
@@ -123,103 +142,217 @@ function lineEnding(text: string): "\n" | "\r\n" {
   return text.includes("\r\n") ? "\r\n" : "\n";
 }
 
-function renderedEntry(value: unknown, indent: number, eol: "\n" | "\r\n"): string {
-  return renderYaml({ opencodex: value }, indent).replaceAll("\n", eol);
-}
-
-/**
- * Patch `providers.opencodex` while preserving every byte outside that entry.
- * The returned text is parsed and compared with `expected` before it is
- * accepted, so a scanner mistake fails closed rather than writing bad YAML.
- */
-export function patchOmpYamlSource(
-  text: string,
-  mutation: OmpYamlMutation,
-  expected: unknown,
-): string | null {
-  const lines = sourceLines(text);
-  const eol = lineEnding(text);
-  const providerIndexes = lines
-    .map((line, index) => isPlainBlockKey(line.body, 0, "providers") ? index : -1)
-    .filter(index => index >= 0);
-
-  if (providerIndexes.length === 0) {
-    if (mutation.kind === "remove") return null;
-    const separator = text.length === 0 || text.endsWith("\n") ? "" : eol;
-    const patched = `${text}${separator}providers:${eol}${renderedEntry(mutation.value, 2, eol)}`;
-    return semanticallyMatches(patched, expected) ? patched : null;
+function readPath(doc: unknown, path: readonly string[]): unknown {
+  let cursor = doc;
+  for (const key of path) {
+    if (cursor === null || typeof cursor !== "object" || Array.isArray(cursor)) return undefined;
+    cursor = (cursor as Record<string, unknown>)[key];
+    if (cursor === undefined) return undefined;
   }
-  if (providerIndexes.length !== 1) return null;
+  return cursor;
+}
 
-  const providersIndex = providerIndexes[0]!;
-  const providersEnd = containerEnd(lines, providersIndex, 0);
-  if (providersEnd === null) return null;
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
 
-  let inferredIndent: number | null = null;
-  for (let index = providersIndex + 1; index < providersEnd; index += 1) {
+function immediateIndent(
+  lines: readonly SourceLine[],
+  start: number,
+  end: number,
+  parentIndent: number,
+): number | null {
+  let indent: number | null = null;
+  for (let index = start; index < end; index += 1) {
     const body = lines[index]!.body;
     const spaces = leadingSpaces(body);
     if (spaces === null) return null;
-    if (!isBlank(body) && !isComment(body) && spaces > 0) {
-      inferredIndent = inferredIndent === null ? spaces : Math.min(inferredIndent, spaces);
+    if (isBlank(body) || isComment(body) || spaces <= parentIndent) continue;
+    indent = indent === null ? spaces : Math.min(indent, spaces);
+  }
+  return indent ?? parentIndent + 2;
+}
+
+/** Locate a path only when every present segment is a plain block-map key. */
+function locatePath(text: string, parsed: unknown, path: readonly string[]): LocatedPath | null {
+  if (path.length === 0 || !isPlainRecord(parsed)) return null;
+  const lines = sourceLines(text);
+  if (lines.some(line => leadingSpaces(line.body) === null)) return null;
+
+  let rangeStart = 0;
+  let rangeEnd = lines.length;
+  let parentIndent = -2;
+  const prefix: string[] = [];
+  for (let depth = 0; depth < path.length; depth += 1) {
+    const indent = depth === 0 ? 0 : immediateIndent(lines, rangeStart, rangeEnd, parentIndent);
+    if (indent === null) return null;
+    const matches: number[] = [];
+    for (let index = rangeStart; index < rangeEnd; index += 1) {
+      if (isPlainBlockKey(lines[index]!.body, indent, path[depth]!)) matches.push(index);
+    }
+    if (matches.length > 1) return null;
+    prefix.push(path[depth]!);
+    if (matches.length === 0) {
+      // The parser saw this key through syntax we do not patch (quoted/flow,
+      // merge aliases, or an ambiguous indentation shape).
+      if (readPath(parsed, prefix) !== undefined) return null;
+      const insertAt = rangeEnd < lines.length ? lines[rangeEnd]!.start : text.length;
+      return { kind: "missing", entry: { lines, missingDepth: depth, indent, insertAt } };
     }
+
+    const index = matches[0]!;
+    const end = containerEnd(lines, index, indent);
+    if (end === null) return null;
+    if (depth === path.length - 1) {
+      if (hasInlineComment(lines[index]!.body)) return null;
+      const leafEnd = childEnd(lines, index, end, indent);
+      if (leafEnd === null) return null;
+      return { kind: "existing", entry: { lines, index, indent, endIndex: leafEnd } };
+    }
+    if (!isPlainRecord(readPath(parsed, prefix))) return null;
+    rangeStart = index + 1;
+    rangeEnd = end;
+    parentIndent = indent;
   }
-  const childIndexes = inferredIndent === null
-    ? []
-    : lines.slice(providersIndex + 1, providersEnd)
-      .map((line, offset) => (
-        isPlainBlockKey(line.body, inferredIndent!, "opencodex")
-          ? providersIndex + 1 + offset
-          : -1
-      ))
-      .filter(index => index >= 0);
-  if (childIndexes.length > 1) return null;
-
-  const childIndex = childIndexes[0];
-  if (childIndex === undefined) {
-    if (mutation.kind === "remove") return null;
-    const indent = inferredIndent ?? 2;
-    const insertAt = providersEnd < lines.length ? lines[providersEnd]!.start : text.length;
-    const prefix = insertAt > 0 && !text.slice(0, insertAt).endsWith("\n") ? eol : "";
-    const patched = `${text.slice(0, insertAt)}${prefix}${renderedEntry(mutation.value, indent, eol)}${text.slice(insertAt)}`;
-    return semanticallyMatches(patched, expected) ? patched : null;
+  return null;
+}
+
+function nestedValue(path: readonly string[], value: unknown): Record<string, unknown> {
+  let nested: unknown = value;
+  for (let index = path.length - 1; index >= 0; index -= 1) nested = { [path[index]!]: nested };
+  return nested as Record<string, unknown>;
+}
+
+function rendered(value: unknown, indent: number, eol: "\n" | "\r\n"): string {
+  return renderYaml(value as Record<string, unknown>, indent).replaceAll("\n", eol);
+}
+
+function preserveFinalNewline(candidate: string, original: string, eol: "\n" | "\r\n"): string {
+  if (original.length > 0 && !original.endsWith("\n") && candidate.endsWith(eol)) {
+    return candidate.slice(0, -eol.length);
+  }
+  return candidate;
+}
+
+function upsertSource(
+  text: string,
+  parsed: unknown,
+  path: readonly string[],
+  value: unknown,
+): string | null {
+  const located = locatePath(text, parsed, path);
+  if (located === null) return null;
+  const eol = lineEnding(text);
+  if (located.kind === "existing") {
+    const { lines, index, indent, endIndex } = located.entry;
+    const startOffset = lines[index]!.start;
+    const endOffset = endIndex < lines.length ? lines[endIndex]!.start : text.length;
+    const candidate = `${text.slice(0, startOffset)}${rendered({ [path[path.length - 1]!]: value }, indent, eol)}${text.slice(endOffset)}`;
+    return preserveFinalNewline(candidate, text, eol);
   }
 
-  const childIndent = leadingSpaces(lines[childIndex]!.body);
-  if (childIndent === null || childIndent <= 0) return null;
-  if (hasInlineComment(lines[childIndex]!.body)) return null;
-  const endIndex = childEnd(lines, childIndex, providersEnd, childIndent);
-  if (endIndex === null) return null;
-  const startOffset = lines[childIndex]!.start;
+  const { missingDepth, indent, insertAt } = located.entry;
+  const prefix = insertAt > 0 && !text.slice(0, insertAt).endsWith("\n") ? eol : "";
+  const insertion = rendered(nestedValue(path.slice(missingDepth), value), indent, eol);
+  const candidate = `${text.slice(0, insertAt)}${prefix}${insertion}${text.slice(insertAt)}`;
+  return preserveFinalNewline(candidate, text, eol);
+}
+
+function removeExactPath(text: string, path: readonly string[], requireEmpty: boolean): string | null {
+  let parsed: unknown;
+  try {
+    parsed = text.trim().length === 0 ? {} : Bun.YAML.parse(text);
+  } catch {
+    return null;
+  }
+  const located = locatePath(text, parsed, path);
+  if (located === null || located.kind !== "existing") return null;
+  const { lines, index, endIndex } = located.entry;
+  const startOffset = lines[index]!.start;
   const endOffset = endIndex < lines.length ? lines[endIndex]!.start : text.length;
+  if (requireEmpty) {
+    const sourceBody = text.slice(lines[index]!.end, endOffset);
+    if (sourceBody.trim().length > 0) return null;
+  }
+  return `${text.slice(0, startOffset)}${text.slice(endOffset)}`;
+}
 
-  if (mutation.kind === "upsert") {
-    const patched = `${text.slice(0, startOffset)}${renderedEntry(mutation.value, childIndent, eol)}${text.slice(endOffset)}`;
-    return semanticallyMatches(patched, expected) ? patched : null;
+function planSourceRemoval(
+  text: string,
+  path: readonly string[],
+  createdContainers: readonly string[],
+): { text: string; prunedContainers: string[] } | null {
+  let next = removeExactPath(text, path, false);
+  if (next === null) return null;
+  const created = new Set(createdContainers);
+  const prunedContainers: string[] = [];
+  for (let depth = path.length - 1; depth >= 1; depth -= 1) {
+    const containerPath = path.slice(0, depth);
+    const encoded = containerPath.join("\u0000");
+    if (!created.has(encoded)) continue;
+    const pruned = removeExactPath(next, containerPath, true);
+    // A user-added sibling/comment makes this ancestor source-owned now. Keep
+    // it (and every parent) while still removing our leaf.
+    if (pruned === null) break;
+    next = pruned;
+    prunedContainers.push(encoded);
   }
+  return { text: next, prunedContainers };
+}
 
-  let patched = `${text.slice(0, startOffset)}${text.slice(endOffset)}`;
-  if (mutation.removeEmptyProviders) {
-    const remaining = Bun.YAML.parse(patched) as { providers?: unknown } | null;
-    if (remaining && Object.hasOwn(remaining, "providers")) {
-      const provider = remaining.providers;
-      const empty = provider === null || (
-        provider && typeof provider === "object" && !Array.isArray(provider)
-        && Object.keys(provider as Record<string, unknown>).length === 0
-      );
-      if (!empty) return semanticallyMatches(patched, expected) ? patched : null;
-      if (hasInlineComment(lines[providersIndex]!.body)) return null;
-
-      const providerStart = lines[providersIndex]!.start;
-      // Removing a container we created is safe only when nothing but our
-      // entry occupied its source range. Comments or blank formatting make
-      // that range user-owned and therefore ambiguous.
-      for (let index = providersIndex + 1; index < providersEnd; index += 1) {
-        if (index >= childIndex && index < endIndex) continue;
-        if (lines[index]!.body.length > 0) return null;
-      }
-      patched = `${text.slice(0, providerStart)}${text.slice(endOffset)}`;
-    }
+/** Containers whose source ranges are still empty and safe to prune. */
+export function sourcePrunableYamlContainers(
+  text: string,
+  path: readonly string[],
+  createdContainers: readonly string[],
+): readonly string[] | null {
+  return planSourceRemoval(text, path, createdContainers)?.prunedContainers ?? null;
+}
+
+function removeSource(
+  text: string,
+  path: readonly string[],
+  createdContainers: readonly string[],
+): string | null {
+  return planSourceRemoval(text, path, createdContainers)?.text ?? null;
+}
+
+/**
+ * Patch one arbitrary plain block-map path, preserving every other byte.
+ */
+export function patchYamlFragmentSource(
+  text: string,
+  path: readonly string[],
+  mutation: YamlFragmentMutation,
+  expected: unknown,
+): string | null {
+  let parsed: unknown;
+  try {
+    parsed = text.trim().length === 0 ? {} : Bun.YAML.parse(text);
+  } catch {
+    return null;
   }
-  return semanticallyMatches(patched, expected) ? patched : null;
+  const patched = mutation.kind === "upsert"
+    ? upsertSource(text, parsed, path, mutation.value)
+    : removeSource(text, path, mutation.createdContainers);
+  return patched !== null && semanticallyMatches(patched, expected) ? patched : null;
+}
+
+/** Backward-compatible OMP wrapper around the generic path patcher. */
+export function patchOmpYamlSource(
+  text: string,
+  mutation: OmpYamlMutation,
+  expected: unknown,
+): string | null {
+  return patchYamlFragmentSource(
+    text,
+    ["providers", "opencodex"],
+    mutation.kind === "upsert"
+      ? mutation
+      : {
+          kind: "remove",
+          createdContainers: mutation.removeEmptyProviders ? ["providers"] : [],
+        },
+    expected,
+  );
 }

package/src/integrations/registry.ts

@@ -12,6 +12,8 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import {
   EXPORT_CLIENTS,
+  dshConfigPath,
+  dshHomeDir,
   gajaeConfigPath,
   gajaeHomeDir,
   hermesConfigPath,
@@ -38,6 +40,10 @@ export interface IntegrationClientSpec {
   configPath: (env?: NodeJS.ProcessEnv, home?: string) => string;
   /** Directory whose existence is the cheap "is it installed?" signal. */
   detectDir: (env?: NodeJS.ProcessEnv, home?: string) => string;
+  /** Patch only this block-map YAML leaf; never re-render the shared file. */
+  sourcePreservingYaml?: { path: readonly string[] };
+  /** Coordinate the complete mutation through a sibling config lock. */
+  writerLock?: { suffix: ".lock" };
 }
 
 /**
@@ -74,6 +80,7 @@ export const INTEGRATION_CLIENTS: Record<IntegrationClientId, IntegrationClientS
     id: "omp",
     configPath: (env = process.env, home = homedir()) => ompModelsConfigPath(env, home),
     detectDir: (env = process.env, home = homedir()) => ompAgentDir(env, home),
+    sourcePreservingYaml: { path: ["providers", "opencodex"] },
   },
   hermes: {
     id: "hermes",
@@ -98,6 +105,13 @@ export const INTEGRATION_CLIENTS: Record<IntegrationClientId, IntegrationClientS
     configPath: (env = process.env, home = homedir()) => gajaeConfigPath(env, home),
     detectDir: (env = process.env, home = homedir()) => gajaeHomeDir(env, home),
   },
+  dsh: {
+    id: "dsh",
+    configPath: (env = process.env, home = homedir()) => dshConfigPath(env, home),
+    detectDir: (env = process.env, home = homedir()) => dshHomeDir(env, home),
+    sourcePreservingYaml: { path: ["llm-pi-ai", "providers", "opencodex"] },
+    writerLock: { suffix: ".lock" },
+  },
 };
 
 export const INTEGRATION_CLIENT_IDS: readonly IntegrationClientId[] =

package/src/integrations/serialize.ts

@@ -221,10 +221,89 @@ export function renderToml(document: Record<string, unknown>, prefix = ""): stri
   return `${[scalars.join("\n"), tables.join("\n\n")].filter(Boolean).join("\n\n")}\n`;
 }
 
+/**
+ * Ceiling on container nesting for json documents, shared by the parse-time
+ * scanner (config-io.ts) and the serializer walk below. One constant on
+ * purpose: the walk must accept every document the scanner admits, or a file
+ * the classifier reported as recoverable would refuse at rewrite time. Real
+ * configs nest a handful of levels.
+ */
+export const MAX_JSON_NESTING = 1000;
+
+/** Error messages carry the path to the offending value; keep them readable. */
+function clampPath(path: string): string {
+  return path.length > 200 ? `${path.slice(0, 100)}…${path.slice(-100)}` : path;
+}
+
+/**
+ * JSON.stringify writes a non-finite number as `null` and -0 as `0`; any
+ * other finite double round-trips value-exactly (literal-level rounding is
+ * the parse-time scanner's concern), so those two are exactly what this walk
+ * refuses — refusing more turned a state the classifier had promised as
+ * recoverable into a permanent refusal. Documents read from disk are already
+ * guarded at parse time, and the writer's merge layer JSON-clones documents —
+ * normalizing these values — before serializing, so on the apply/disable path
+ * this walk is unreachable for them: it guards the direct serializers
+ * (preview/export builders), same posture as the YAML and TOML renderers
+ * above, and enforces the nesting ceiling for every json caller before the
+ * recursive JSON.stringify can turn depth into a RangeError.
+ *
+ * Iterative frames instead of recursion or a node stack: depth AND size of
+ * the document are inputs under the writer of the config file. Recursion made
+ * a deep file a RangeError-500; materializing every node with its path made a
+ * wide file allocate a large multiple of its size. Frames keep memory
+ * proportional to nesting depth, and path strings exist only for the
+ * containers on the current path plus the failing value itself.
+ */
+function assertJsonNumbersRoundTrip(document: unknown, rootPath: string): void {
+  const refuse = (value: number, path: string): never => {
+    throw new UnserializableValueError(Object.is(value, -0)
+      ? `JSON cannot rewrite -0 at ${clampPath(path)} without changing it to 0`
+      : `JSON cannot rewrite the number at ${clampPath(path)} without changing it to null`);
+  };
+  if (typeof document === "number" && (!Number.isFinite(document) || Object.is(document, -0))) {
+    refuse(document, rootPath);
+  }
+  type Frame = { container: unknown; keys: string[] | null; index: number; prefix: string };
+  const frames: Frame[] = [];
+  const pushContainer = (value: unknown, prefix: string) => {
+    if (Array.isArray(value)) frames.push({ container: value, keys: null, index: 0, prefix });
+    else if (isPlainRecord(value)) frames.push({ container: value, keys: Object.keys(value), index: 0, prefix });
+  };
+  pushContainer(document, rootPath);
+  while (frames.length > 0) {
+    const frame = frames[frames.length - 1]!;
+    const length = frame.keys ? frame.keys.length : (frame.container as unknown[]).length;
+    if (frame.index >= length) { frames.pop(); continue; }
+    const i = frame.index;
+    frame.index += 1;
+    const child = frame.keys
+      ? (frame.container as Record<string, unknown>)[frame.keys[i]!]
+      : (frame.container as unknown[])[i];
+    const childPath = () => frame.keys
+      ? (frame.prefix === "$" ? frame.keys[i]! : `${frame.prefix}.${frame.keys[i]!}`)
+      : `${frame.prefix}[${i}]`;
+    if (typeof child === "number") {
+      if (!Number.isFinite(child) || Object.is(child, -0)) refuse(child, childPath());
+      continue;
+    }
+    if (typeof child === "object" && child !== null) {
+      if (frames.length >= MAX_JSON_NESTING) {
+        throw new UnserializableValueError(
+          `the document nests deeper than ${MAX_JSON_NESTING} levels at ${clampPath(childPath())}, which JSON serialization cannot rewrite safely`);
+      }
+      pushContainer(child, childPath());
+    }
+  }
+}
+
 /** Every serializer returns text ending in exactly one newline. */
 export function serializeDocument(document: unknown, format: ConfigFormat): string {
   switch (format) {
-    case "json": return `${JSON.stringify(document, null, 2)}\n`;
+    case "json": {
+      assertJsonNumbersRoundTrip(document, "$");
+      return `${JSON.stringify(document, null, 2)}\n`;
+    }
     case "json5": return `${Bun.JSON5.stringify(document, null, 2)}\n`;
     case "yaml": return renderYaml(document);
     case "toml": {

package/src/integrations/state.ts

@@ -134,9 +134,15 @@ function recordedFragmentFingerprint(
 /**
  * The two-axis rule: the recorded bytes or fragments prove nobody changed
  * what we may rewrite, and the contribution hash proves our catalog has not
- * moved on. OMP is the sole fragment-scoped client because its writer patches
- * only `providers.opencodex`; every whole-document serializer retains the
- * whole-file fingerprint guard.
+ * moved on. Three classes of client (revising the unconditional whole-file
+ * rule of devlog 260802_client_toggle_api/021 §3 for json — #1631):
+ * registry-declared source-preserving YAML clients are fragment-scoped because
+ * their writers patch only the owned leaf, so the whole-file check is skipped;
+ * strict-json clients keep the whole-file check but downgrade a drift with
+ * intact owned fragments to `stale`, because a rewrite there can lose only
+ * formatting (comments cannot parse, non-round-tripping numbers are refused
+ * by the serializer); every comment-capable whole-document serializer (yaml,
+ * json5, toml) retains the whole-file fingerprint guard as a hard conflict.
  */
 export function classifyIntegration(input: {
   fileText: string | null;
@@ -180,12 +186,38 @@ export function classifyIntegration(input: {
     return { state: "conflict", reason: "unowned-key" };
   }
   const clientId = input.clientId ?? input.record.clientId;
-  if (clientId !== "omp" && fingerprint(input.fileText ?? "") !== input.record.fileFingerprint) {
-    return { state: "conflict", reason: "foreign-edit" };
-  }
+  /*
+   * Checked BEFORE file-level drift: an edit INSIDE an owned fragment is a
+   * conflict no matter what the rest of the file looks like, so the sibling-
+   * edit exemption below can never mask it.
+   */
   if (recordedFragmentFingerprint(input.parsed, input.record) !== input.record.blockFingerprint) {
     return { state: "conflict", reason: "foreign-edit" };
   }
+  if (!INTEGRATION_CLIENTS[clientId].sourcePreservingYaml
+    && fingerprint(input.fileText ?? "") !== input.record.fileFingerprint) {
+    /*
+     * 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,
+     * 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
+     * possible loss is formatting normalization: everything a rewrite would
+     * actually change (numbers that would not round-trip, duplicate members
+     * a rewrite would delete) is PARSE_FAILED in parseConfig and classifies
+     * as unsafe long before this branch, exactly like comments. Refusing
+     * forever over formatting
+     * dead-ends the integration on the user's first own config edit (#1631).
+     * Report drift instead; a re-apply merges into the parsed document as it
+     * stands and re-owns the file. This also lets disable proceed on a
+     * drifted file — removal still touches only the recorded fragment paths.
+     */
+    if (EXPORT_CLIENTS[clientId].format !== "json") {
+      return { state: "conflict", reason: "foreign-edit" };
+    }
+    return { state: "stale" };
+  }
   return input.record.blockFingerprint === fingerprint(canonicalContribution(input.contribution))
     ? { state: "current" }
     : { state: "stale" };