@bitkyc08/opencodex 2.52.0-preview.20260911 → 2.52.0-preview.20260912

package/src/integrations/cline-io.ts

@@ -0,0 +1,149 @@
+import { dirname, join, resolve } from "node:path";
+import { type IntegrationIO, type IntegrationTransaction, type ReadResult, type StatKind } from "./config-io";
+import type { IntegrationStateStore } from "./store";
+import { fingerprint, type OwnershipRecord } from "./ownership";
+import type { JournalEntry } from "./journal";
+import { parseClineTransaction } from "./cline-transaction";
+import { decodeClinePair, encodeClinePair, type ClineRawPair } from "./cline-document";
+
+/** Per-file atomic replacement with durable pair recovery, not simultaneous two-file visibility. */
+export class ClineTransactionError extends Error {
+  readonly residual = true;
+  constructor(readonly snapshotPath: string) {
+    super(`Cline has an unfinished two-file operation. Stop Cline and retry the mutation. If either file was edited, recover from ${snapshotPath} before retrying.`);
+  }
+}
+
+function sameRecord(a: unknown, b: unknown): boolean {
+  return JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+}
+
+export function clinePendingPath(store: IntegrationStateStore, configPath: string): string {
+  return join(store.root, `cline-pending-${fingerprint(resolve(configPath))}.json`);
+}
+
+/** Snapshot/ownership remain in the existing store. Only the filesystem projection changes. */
+export function createClineIO(
+  base: IntegrationIO,
+  configPath: string,
+  store: IntegrationStateStore,
+  recover = false,
+): IntegrationIO {
+  const catalogPath = join(dirname(configPath), "models.json");
+  const markerPath = clinePendingPath(store, configPath);
+  const targets = { settings: configPath, catalog: catalogPath };
+  const keys = ["settings", "catalog"] as const;
+  const kind = (path: string) => (base.lstatKind ?? base.statKind)(path);
+  const readPair = (): ClineRawPair => {
+    const pair: ClineRawPair = { settings: null, catalog: null };
+    for (const key of keys) {
+      const path = targets[key];
+      const state = kind(path);
+      if (state === "missing") continue;
+      if (state !== "file") throw new ClineTransactionError(markerPath);
+      const read = base.readText(path);
+      if (read.kind !== "text") throw new ClineTransactionError(markerPath);
+      pair[key] = read.text;
+    }
+    return pair;
+  };
+  const writeMember = (key: typeof keys[number], text: string | null): void => {
+    if (text === null) base.removeFile(targets[key]);
+    else { base.mkdirp(dirname(targets[key])); base.writeText(targets[key], text); }
+  };
+  const writePair = (pair: ClineRawPair): void => {
+    for (const key of keys) writeMember(key, pair[key]);
+  };
+  const readPending = (): IntegrationTransaction | null => {
+    if (kind(markerPath) === "missing") return null;
+    if (kind(markerPath) !== "file") throw new ClineTransactionError(markerPath);
+    const read = base.readText(markerPath);
+    if (read.kind !== "text") throw new ClineTransactionError(markerPath);
+    try {
+      return parseClineTransaction(read.text, configPath);
+    } catch { throw new ClineTransactionError(markerPath); }
+  };
+  const committed = (pending: IntegrationTransaction, current: ClineRawPair): boolean => {
+    let operation: JournalEntry | null;
+    let record: OwnershipRecord | undefined;
+    try { operation = store.findCommittedOperation(pending.entry.opId); record = store.readRecordsStrict().cline; }
+    catch { throw new ClineTransactionError(markerPath); }
+    return operation !== null && operation.clientId === "cline" && operation.configPath === configPath
+      && operation.resultFingerprint === pending.entry.resultFingerprint
+      && encodeClinePair(current) === pending.nextText
+      && sameRecord(record, pending.record);
+  };
+  const cleanup = (): void => {
+    // The append is the commit boundary. Cleanup failure never rolls back a committed pair.
+    try { base.removeFile(markerPath); } catch { /* The next mutation recognizes the committed record. */ }
+  };
+  const pendingSafe = (): boolean => {
+    const pending = readPending();
+    return pending === null || committed(pending, readPair());
+  };
+
+  if (resolve(configPath).toLowerCase() === resolve(catalogPath).toLowerCase()) throw new ClineTransactionError(markerPath);
+  if (recover) {
+    const pending = readPending();
+    if (pending) {
+      const current = readPair();
+      if (committed(pending, current)) cleanup();
+      else {
+        // A journaled but mixed/inconsistent result is not an interrupted uncommitted write.
+        try {
+          if (store.findCommittedOperation(pending.entry.opId)) throw new ClineTransactionError(markerPath);
+        } catch { throw new ClineTransactionError(markerPath); }
+        const before = decodeClinePair(pending.before);
+        const after = decodeClinePair(pending.nextText);
+        if (!keys.every(key => current[key] === before[key] || current[key] === after[key])) throw new ClineTransactionError(markerPath);
+        let record: OwnershipRecord | null;
+        try { record = store.readRecordsStrict().cline ?? null; }
+        catch { throw new ClineTransactionError(markerPath); }
+        if (!sameRecord(record, pending.priorRecord) && !sameRecord(record, pending.record)) throw new ClineTransactionError(markerPath);
+        try {
+          writePair(before);
+          if (pending.priorRecord) base.putRecord(pending.priorRecord);
+          else base.dropRecord("cline");
+          base.removeFile(markerPath);
+        } catch { throw new ClineTransactionError(markerPath); }
+      }
+    }
+  }
+
+  return {
+    ...base,
+    statKind: (path): StatKind => {
+      if (path !== configPath) return base.statKind(path);
+      try {
+        if (!pendingSafe()) return "failed";
+        const pair = readPair();
+        return pair.settings === null && pair.catalog === null ? "missing" : "file";
+      } catch { return "failed"; }
+    },
+    readText: (path): ReadResult => {
+      if (path !== configPath) return base.readText(path);
+      try {
+        if (!pendingSafe()) return { kind: "failed", code: "CLINE_PENDING" };
+        const text = encodeClinePair(readPair());
+        return text === null ? { kind: "missing" } : { kind: "text", text };
+      } catch { return { kind: "failed", code: "CLINE_UNSAFE" }; }
+    },
+    beginTransaction: transaction => {
+      if (transaction.entry.clientId !== "cline" || transaction.entry.configPath !== configPath) throw new ClineTransactionError(markerPath);
+      if (readPending() !== null) throw new ClineTransactionError(markerPath);
+      if (encodeClinePair(readPair()) !== transaction.before) throw new ClineTransactionError(markerPath);
+      base.mkdirp(store.root);
+      const { entry, before, nextText, record, priorRecord } = transaction;
+      base.writeText(markerPath, JSON.stringify({ entry, before, nextText, record, priorRecord }));
+    },
+    writeText: (path, text) => {
+      if (path !== configPath) return base.writeText(path, text);
+      writePair(decodeClinePair(text));
+    },
+    removeFile: path => {
+      if (path !== configPath) return base.removeFile(path);
+      writePair({ settings: null, catalog: null });
+    },
+    finishTransaction: cleanup,
+  };
+}

package/src/integrations/cline-transaction.ts

@@ -0,0 +1,42 @@
+import type { IntegrationTransaction } from "./config-io";
+import { decodeClinePair, encodeClinePair, isClineObject } from "./cline-document";
+import { isJournalEntry } from "./journal";
+import { fingerprint, isOwnershipRecord, type OwnershipRecord } from "./ownership";
+import { validRefreshablePaths } from "./ownership-policy";
+
+const FRAGMENTS = [["catalog", "providers", "opencodex"], ["settings", "providers", "opencodex"]];
+const CONTAINERS = new Set(["catalog", "settings", "catalog\0providers", "settings\0providers"]);
+
+function clineRecord(value: unknown, configPath: string): value is OwnershipRecord | null {
+  if (value === null) return true;
+  if (!isOwnershipRecord(value) || value.clientId !== "cline" || value.configPath !== configPath) return false;
+  if (value.fragmentPaths.length !== FRAGMENTS.length
+    || !FRAGMENTS.every(expected => value.fragmentPaths.some(path =>
+      path.length === expected.length && path.every((segment, index) => segment === expected[index])))) return false;
+  if (value.createdContainers?.some(path => !CONTAINERS.has(path))) return false;
+  if (value.refreshablePaths !== undefined
+    && !validRefreshablePaths({ clientId: "cline", fragments: [] }, value.refreshablePaths)) return false;
+  return value.protectedBlockFingerprint === undefined || value.refreshablePaths !== undefined;
+}
+
+/** Validate all recovery authority before a file or ownership record can be replaced. */
+export function parseClineTransaction(text: string, configPath: string): IntegrationTransaction {
+  const value: unknown = JSON.parse(text);
+  if (!isClineObject(value) || !isJournalEntry(value.entry)
+    || value.entry.clientId !== "cline" || value.entry.configPath !== configPath
+    || !(typeof value.before === "string" || value.before === null)
+    || !(typeof value.nextText === "string" || value.nextText === null)
+    || !clineRecord(value.record, configPath) || !clineRecord(value.priorRecord, configPath)
+    || !clineRecord(value.entry.priorRecord, configPath)
+    || JSON.stringify(value.entry.priorRecord) !== JSON.stringify(value.priorRecord)
+    || (value.record !== null && (value.record.opId !== value.entry.opId || value.record.appliedAt !== value.entry.at))) {
+    throw new Error("invalid Cline transaction metadata");
+  }
+  if (encodeClinePair(decodeClinePair(value.before)) !== value.before
+    || encodeClinePair(decodeClinePair(value.nextText)) !== value.nextText
+    || value.entry.resultAbsent !== (value.nextText === null)
+    || value.entry.resultFingerprint !== (value.nextText === null ? "" : fingerprint(value.nextText))) {
+    throw new Error("inconsistent Cline transaction result");
+  }
+  return { entry: value.entry, before: value.before, nextText: value.nextText, record: value.record, priorRecord: value.priorRecord };
+}

package/src/integrations/config-io.ts

@@ -7,7 +7,7 @@
  *
  * Design of record: devlog/_fin/260802_client_toggle_api/021 §5-6.
  */
-import { mkdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { lstatSync, mkdirSync, readFileSync, rmSync, statSync } from "node:fs";
 import type { ConfigFormat } from "../clients/config-export";
 import { MAX_JSON_NESTING } from "./serialize";
 import { atomicWriteFile } from "../config";
@@ -200,6 +200,8 @@ export interface IntegrationIO {
   readText: (path: string) => ReadResult;
   /** `failed` is distinct from `missing` for the same reason. */
   statKind: (path: string) => StatKind;
+  /** Optional no-follow probe for paired-file clients. */
+  lstatKind?: (path: string) => StatKind;
   writeText: (path: string, text: string) => void;
   removeFile: (path: string) => void;
   mkdirp: (path: string) => void;
@@ -208,6 +210,16 @@ export interface IntegrationIO {
   appendJournal: (entry: JournalEntry) => void;
   putRecord: (record: OwnershipRecord) => void;
   dropRecord: (clientId: IntegrationClientId) => void;
+  beginTransaction?: (transaction: IntegrationTransaction) => void;
+  finishTransaction?: () => void;
+}
+
+export interface IntegrationTransaction {
+  entry: JournalEntry;
+  before: string | null;
+  nextText: string | null;
+  record: OwnershipRecord | null;
+  priorRecord: OwnershipRecord | null;
 }
 
 export type TargetState =
@@ -240,6 +252,14 @@ export function loadTarget(io: IntegrationIO, configPath: string): TargetState {
  */
 export function fileIO(): Omit<IntegrationIO, "appendJournal" | "putRecord" | "dropRecord"> {
   return {
+    lstatKind: path => {
+      try {
+        const stats = lstatSync(path);
+        return stats.isFile() ? "file" : stats.isDirectory() ? "dir" : "other";
+      } catch (error) {
+        return (error as NodeJS.ErrnoException).code === "ENOENT" ? "missing" : "failed";
+      }
+    },
     readText: path => {
       try {
         return { kind: "text", text: readFileSync(path, "utf8") };
@@ -334,4 +354,3 @@ export function assertIntegrationWriteOwnership(
     + "of sharing the mount.",
   );
 }
-

package/src/integrations/journal.ts

@@ -16,7 +16,7 @@ import { randomUUID } from "node:crypto";
 import { appendFileSync, existsSync, readFileSync, readdirSync, rmSync } from "node:fs";
 import { join, resolve, sep } from "node:path";
 import { atomicWriteFile } from "../config";
-import { ensureDir, fingerprint, integrationsDir, type OwnershipRecord } from "./ownership";
+import { ensureDir, fingerprint, integrationsDir, isOwnershipRecord, type OwnershipRecord } from "./ownership";
 import { isIntegrationClientId, type IntegrationClientId } from "./registry";
 
 /**
@@ -231,6 +231,48 @@ export function findOperation(opId: string, dir: string = integrationsDir()): Jo
   return listOperations(undefined, Number.MAX_SAFE_INTEGER, dir).find(row => row.opId === opId) ?? null;
 }
 
+export function isJournalEntry(value: unknown): value is JournalEntry {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const entry = value as Record<string, unknown>;
+  const snapshot = entry.snapshot;
+  return typeof entry.opId === "string" && /^[a-zA-Z0-9-]+$/.test(entry.opId)
+    && typeof entry.clientId === "string" && isIntegrationClientId(entry.clientId)
+    && typeof entry.configPath === "string" && entry.configPath.length > 0
+    && typeof entry.at === "string" && Number.isFinite(Date.parse(entry.at))
+    && typeof entry.kind === "string" && ["apply", "refresh", "disable", "restore", "overwrite"].includes(entry.kind)
+    && typeof entry.resultAbsent === "boolean"
+    && (entry.resultAbsent ? entry.resultFingerprint === "" : typeof entry.resultFingerprint === "string" && /^[a-f0-9]{16}$/.test(entry.resultFingerprint))
+    && (entry.priorRecord === null || isOwnershipRecord(entry.priorRecord))
+    && snapshot !== null && typeof snapshot === "object" && !Array.isArray(snapshot)
+    && ("kind" in snapshot && (snapshot.kind === "none" || snapshot.kind === "expired"
+      || (snapshot.kind === "stored" && "relPath" in snapshot && typeof snapshot.relPath === "string" && snapshot.relPath.length > 0)));
+}
+
+/** Commit evidence includes retired rows. Read/parse failures must never become "not committed". */
+export function findCommittedOperation(opId: string, dir: string = integrationsDir()): JournalEntry | null {
+  let raw: string;
+  try { raw = readFileSync(journalPath(dir), "utf8"); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw new Error("integration journal cannot be read for recovery");
+  }
+  let found: JournalEntry | null = null;
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    let row: unknown;
+    try { row = JSON.parse(line); }
+    catch { throw new Error("integration journal is incomplete for recovery"); }
+    if (isTombstone(row)) {
+      if (!row.tombstone || typeof row.at !== "string" || !Number.isFinite(Date.parse(row.at))
+        || typeof row.by !== "string" || !row.by) throw new Error("integration journal contains invalid recovery metadata");
+      continue;
+    }
+    if (!isJournalEntry(row)) throw new Error("integration journal contains invalid recovery metadata");
+    if (row.opId === opId) found = row;
+  }
+  return found;
+}
+
 /** Resolves the tag against what is actually on disk now. */
 export function readSnapshot(
   entry: JournalEntry,

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

@@ -29,7 +29,20 @@ interface MissingEntry {
   insertAt: number;
 }
 
-type LocatedPath = { kind: "existing"; entry: LocatedEntry } | { kind: "missing"; entry: MissingEntry };
+interface ReplaceLineEntry {
+  lines: readonly SourceLine[];
+  index: number;
+  indent: number;
+  missingDepth: number;
+}
+
+type LocatedPath =
+  | { kind: "existing"; entry: LocatedEntry }
+  | { kind: "missing"; entry: MissingEntry }
+  // `key: {}` — an empty inline map the block-key scanner cannot see (#4260).
+  | { kind: "replace-line"; entry: ReplaceLineEntry }
+  // A populated flow container. Still refused, but nameable as its own cause.
+  | { kind: "unsupported-style" };
 
 export type YamlFragmentMutation =
   | { kind: "upsert"; value: unknown }
@@ -82,6 +95,61 @@ function isPlainBlockKey(line: string, indent: number, key: string): boolean {
   return new RegExp(`^${regexpEscape(key)}:[ ]*(?:#.*)?$`, "u").test(rest);
 }
 
+/** The inline value written after `key:` on this line, or null if the key is not here. */
+function inlineValueAfterKey(line: string, indent: number, key: string): string | null {
+  const spaces = leadingSpaces(line);
+  if (spaces !== indent) return null;
+  const rest = line.slice(indent);
+  const head = `${key}:`;
+  // Compared as text, not as a pattern: a path segment is arbitrary user data,
+  // and brace escaping inside a `u`-flag regex is its own hazard.
+  if (!rest.startsWith(head)) return null;
+  return rest.slice(head.length).trim();
+}
+
+/** Exactly `key: {}` (any inner spacing) — an empty inline map, no inline comment. */
+function isEmptyInlineMapKey(line: string, indent: number, key: string): boolean {
+  const value = inlineValueAfterKey(line, indent, key);
+  if (value === null) return false;
+  return value.startsWith("{") && value.endsWith("}") && value.slice(1, -1).trim().length === 0;
+}
+
+/** `key: { ... }` or `key: [ ... ]` on one line: content we would have to re-render. */
+function isPopulatedInlineFlowKey(line: string, indent: number, key: string): boolean {
+  const value = inlineValueAfterKey(line, indent, key);
+  if (value === null) return false;
+  if (!value.startsWith("{") && !value.startsWith("[")) return false;
+  return !isEmptyInlineMapKey(line, indent, key);
+}
+
+/**
+ * A plain block key whose first child opens a flow collection:
+ *
+ *     providers:
+ *       { native: { ... } }
+ *
+ * DSH writes this shape itself. The walk passes straight through it — the key
+ * line is a plain block key and `containerEnd` does not stop at `}` — so the
+ * refusal used to surface only as a failed re-parse at the very end and got
+ * reported as a comment or formatting problem that was not there (#4260).
+ */
+function firstChildOpensFlow(
+  lines: readonly SourceLine[],
+  start: number,
+  end: number,
+  parentIndent: number,
+): boolean {
+  for (let index = start + 1; index < end; index += 1) {
+    const body = lines[index]!.body;
+    if (isBlank(body) || isComment(body)) continue;
+    const spaces = leadingSpaces(body);
+    if (spaces === null || spaces <= parentIndent) continue;
+    const trimmed = body.trimStart();
+    return trimmed.startsWith("{") || trimmed.startsWith("[");
+  }
+  return false;
+}
+
 function containerEnd(lines: readonly SourceLine[], start: number, indent: number): number | null {
   for (let index = start + 1; index < lines.length; index += 1) {
     const body = lines[index]!.body;
@@ -193,9 +261,24 @@ function locatePath(text: string, parsed: unknown, path: readonly string[]): Loc
     if (matches.length > 1) return null;
     prefix.push(path[depth]!);
     if (matches.length === 0) {
+      const seen = readPath(parsed, prefix);
+      // An empty inline map is the one flow shape we can adopt: rewriting that
+      // single line into block form adds our subtree and re-renders nothing the
+      // user wrote, because there is nothing in it (#4260).
+      const inline: number[] = [];
+      const populatedFlow: number[] = [];
+      for (let index = rangeStart; index < rangeEnd; index += 1) {
+        const body = lines[index]!.body;
+        if (isEmptyInlineMapKey(body, indent, path[depth]!)) inline.push(index);
+        else if (isPopulatedInlineFlowKey(body, indent, path[depth]!)) populatedFlow.push(index);
+      }
+      if (inline.length === 1 && isPlainRecord(seen) && Object.keys(seen).length === 0) {
+        return { kind: "replace-line", entry: { lines, index: inline[0]!, indent, missingDepth: depth } };
+      }
+      if (populatedFlow.length === 1 && seen !== undefined) return { kind: "unsupported-style" };
       // 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;
+      if (seen !== undefined) return null;
       const insertAt = rangeEnd < lines.length ? lines[rangeEnd]!.start : text.length;
       return { kind: "missing", entry: { lines, missingDepth: depth, indent, insertAt } };
     }
@@ -209,7 +292,20 @@ function locatePath(text: string, parsed: unknown, path: readonly string[]): Loc
       if (leafEnd === null) return null;
       return { kind: "existing", entry: { lines, index, indent, endIndex: leafEnd } };
     }
-    if (!isPlainRecord(readPath(parsed, prefix))) return null;
+    const container = readPath(parsed, prefix);
+    // `key:` with no children parses as null. The key line matched, so the
+    // missing-key branch above never runs, and `isPlainRecord(null)` is false —
+    // so an empty container used to refuse the whole document (#4260). Insert
+    // our subtree as its first child instead.
+    if (container === null) {
+      const insertAt = end < lines.length ? lines[end]!.start : text.length;
+      return {
+        kind: "missing",
+        entry: { lines, missingDepth: depth + 1, indent: indent + 2, insertAt },
+      };
+    }
+    if (!isPlainRecord(container)) return null;
+    if (firstChildOpensFlow(lines, index, end, indent)) return { kind: "unsupported-style" };
     rangeStart = index + 1;
     rangeEnd = end;
     parentIndent = indent;
@@ -241,7 +337,7 @@ function upsertSource(
   value: unknown,
 ): string | null {
   const located = locatePath(text, parsed, path);
-  if (located === null) return null;
+  if (located === null || located.kind === "unsupported-style") return null;
   const eol = lineEnding(text);
   if (located.kind === "existing") {
     const { lines, index, indent, endIndex } = located.entry;
@@ -250,6 +346,13 @@ function upsertSource(
     const candidate = `${text.slice(0, startOffset)}${rendered({ [path[path.length - 1]!]: value }, indent, eol)}${text.slice(endOffset)}`;
     return preserveFinalNewline(candidate, text, eol);
   }
+  if (located.kind === "replace-line") {
+    const { lines, index, indent, missingDepth } = located.entry;
+    const startOffset = lines[index]!.start;
+    const endOffset = index + 1 < lines.length ? lines[index + 1]!.start : text.length;
+    const insertion = rendered(nestedValue(path.slice(missingDepth), value), indent, eol);
+    return preserveFinalNewline(`${text.slice(0, startOffset)}${insertion}${text.slice(endOffset)}`, text, eol);
+  }
 
   const { missingDepth, indent, insertAt } = located.entry;
   const prefix = insertAt > 0 && !text.slice(0, insertAt).endsWith("\n") ? eol : "";
@@ -338,6 +441,22 @@ export function patchYamlFragmentSource(
   return patched !== null && semanticallyMatches(patched, expected) ? patched : null;
 }
 
+/**
+ * True when a refusal on this path is caused by a flow-style container rather
+ * than by comments or formatting we would have to re-render. DSH writes that
+ * shape itself, so naming it is the difference between an actionable message
+ * and one that sends the user hunting for a comment that is not there (#4260).
+ */
+export function yamlFragmentUnsupportedStyle(text: string, path: readonly string[]): boolean {
+  let parsed: unknown;
+  try {
+    parsed = text.trim().length === 0 ? {} : Bun.YAML.parse(text);
+  } catch {
+    return false;
+  }
+  return locatePath(text, parsed, path)?.kind === "unsupported-style";
+}
+
 /** Backward-compatible OMP wrapper around the generic path patcher. */
 export function patchOmpYamlSource(
   text: string,

package/src/integrations/ownership-policy.ts

@@ -63,6 +63,10 @@ function cloneFragment(fragment: ManagedFragment): ManagedFragment {
 export function refreshablePathsOf(
   contribution: ManagedContribution,
 ): readonly (readonly string[])[] {
+  if (contribution.clientId === "cline") return [
+    ["settings", "providers", OPENCODE_PROVIDER_ID, "updatedAt"],
+    ["settings", "providers", OPENCODE_PROVIDER_ID, "settings", "model"],
+  ];
   if (contribution.clientId !== "zcode") return [];
   const fragment = contribution.fragments.find(candidate => (
     candidate.path.length === 2
@@ -90,6 +94,9 @@ export function validRefreshablePaths(
   contribution: ManagedContribution,
   value: unknown,
 ): value is readonly (readonly string[])[] {
+  if (contribution.clientId === "cline") {
+    return JSON.stringify(value) === JSON.stringify(refreshablePathsOf(contribution));
+  }
   if (contribution.clientId !== "zcode" || !Array.isArray(value) || value.length === 0) {
     return false;
   }

package/src/integrations/ownership.ts

@@ -101,6 +101,42 @@ export interface OwnershipRecord {
   opId: string;
 }
 
+/** Recovery needs proven metadata, unlike the tolerant status-reader fallback. */
+export function isOwnershipRecord(value: unknown): value is OwnershipRecord {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const record = value as Record<string, unknown>;
+  const hash = (item: unknown) => typeof item === "string" && /^[a-f0-9]{16}$/.test(item);
+  const paths = (item: unknown) => Array.isArray(item) && item.every(path =>
+    Array.isArray(path) && path.length > 0 && path.every(key => typeof key === "string" && key.length > 0));
+  return typeof record.clientId === "string" && record.clientId.length > 0
+    && typeof record.configPath === "string" && record.configPath.length > 0
+    && typeof record.opId === "string" && record.opId.length > 0
+    && typeof record.appliedAt === "string" && Number.isFinite(Date.parse(record.appliedAt))
+    && hash(record.fileFingerprint) && hash(record.blockFingerprint)
+    && paths(record.fragmentPaths) && (record.fragmentPaths as unknown[]).length > 0
+    && ["semanticBlockFingerprint", "protectedBlockFingerprint", "semanticProtectedBlockFingerprint"]
+      .every(key => record[key] === undefined || hash(record[key]))
+    && (record.refreshablePaths === undefined || paths(record.refreshablePaths))
+    && (record.createdContainers === undefined || (Array.isArray(record.createdContainers)
+      && record.createdContainers.every(path => typeof path === "string")));
+}
+
+/** Missing is empty; corrupt/unreadable ownership is uncertainty and must abort recovery. */
+export function readRecordsStrict(dir: string = integrationsDir()): Partial<Record<IntegrationClientId, OwnershipRecord>> {
+  let text: string;
+  try { text = readFileSync(recordsPath(dir), "utf8"); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return {};
+    throw new Error("integration ownership cannot be read for recovery");
+  }
+  try {
+    const parsed: unknown = JSON.parse(text);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)
+      || !Object.entries(parsed).every(([key, value]) => isOwnershipRecord(value) && value.clientId === key)) throw new Error();
+    return parsed as Partial<Record<IntegrationClientId, OwnershipRecord>>;
+  } catch { throw new Error("integration ownership is invalid for recovery"); }
+}
+
 /**
  * The integrations directory itself. Every primitive takes THIS path, never a
  * config root, so a caller cannot accidentally produce

package/src/integrations/registry.ts

@@ -12,6 +12,8 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import {
   ClientPathError,
+  clineConfigPath,
+  clineSettingsDir,
   EXPORT_CLIENTS,
   asideAccountDir,
   asideConfigPath,
@@ -26,6 +28,8 @@ import {
   kimiHomeDir,
   mcodeConfigPath,
   mcodeHomeDir,
+  omoAgentDir,
+  omoConfigPath,
   ompAgentDir,
   ompModelsConfigPath,
   opencodeGlobalConfigPath,
@@ -280,6 +284,29 @@ export const INTEGRATION_CLIENTS: Record<IntegrationClientId, IntegrationClientS
      */
     detectDir: (env = process.env, home = homedir()) => raycastAiDir(env, home),
   },
+  omo: {
+    id: "omo",
+    configPath: (env = process.env, home = homedir()) => omoConfigPath(env, home),
+    /*
+     * The AGENT directory, not `~/.omo`. The v4 launcher wrapper creates
+     * `~/.omo` to hold `binary-runtime` without ever creating `agent/`, so
+     * detecting on the parent reports an omo v5 install that is not there --
+     * and `installed` is what stops apply from writing a catalog for an engine
+     * that will never read it. Prime's agent directory and Aside's account
+     * directory are the same shape; Pi's parent-directory check is the odd one.
+     *
+     * No `sourcePreservingYaml` (JSON), no `writerLock` (single writer), and no
+     * `resolvePaths` -- unlike Aside, both omo paths are a pure function of env
+     * and home, so reading them in sequence cannot straddle a state change.
+     */
+    detectDir: (env = process.env, home = homedir()) => omoAgentDir(env, home),
+  },
+  cline: {
+    id: "cline",
+    configPath: (env = process.env, home = homedir()) => clineConfigPath(env, home),
+    detectDir: (env = process.env, home = homedir()) => clineSettingsDir(env, home),
+    writerLock: { suffix: ".lock" },
+  },
 };
 
 export const INTEGRATION_CLIENT_IDS: readonly IntegrationClientId[] =

package/src/integrations/state.ts

@@ -8,6 +8,8 @@
  *
  * Design of record: devlog/_fin/260802_client_toggle_api/021 §3.
  */
+import { createClineIO } from "./cline-io";
+import { parseClineDocument } from "./cline-document";
 import { ClientPathError, EXPORT_CLIENTS, opencodeProxyBaseUrl, type ExportModel, type ManagedContribution } from "../clients/config-export";
 import type { OcxConfig } from "../types";
 import { PARSE_FAILED, loadTarget, parseConfig, type IntegrationIO } from "./config-io";
@@ -487,7 +489,7 @@ function retentionOf(
 export function readIntegrationState(input: IntegrationStateInput): IntegrationStatus {
   const store = input.store ?? createIntegrationStateStore();
   retryPendingPrunesOnce(store);
-  const io = input.io ?? store.io();
+  let io = input.io ?? store.io();
   const spec = INTEGRATION_CLIENTS[input.clientId];
   const exportSpec = EXPORT_CLIENTS[input.clientId];
   const retention = retentionOf(input.clientId, store);
@@ -529,6 +531,7 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
     };
   }
 
+  if (input.clientId === "cline") io = createClineIO(io, configPath, store);
   const target = loadTarget(io, configPath);
   if (!target.ok) {
     return {
@@ -541,7 +544,7 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
     };
   }
 
-  const parsed = parseConfig(target.before, exportSpec.format);
+  const parsed = input.clientId === "cline" ? parseClineDocument(target.before) : parseConfig(target.before, exportSpec.format);
   const contribution = exportSpec.buildContribution(exportContextOf(input));
   const record = store.readRecords()[input.clientId] ?? null;
   const { state, reason } = classifyIntegration({