@iislee/opencodex 2.11.0 → 2.31.0

package/src/integrations/serialize.ts

@@ -0,0 +1,314 @@
+/**
+ * Text serializers for client config documents.
+ *
+ * Bun 1.3.14 gives us JSON and JSON5 stringify natively, but the two formats a
+ * client config actually needs beyond JSON are hand-rendered here:
+ *
+ * - **TOML** has no `Bun.TOML.stringify` at all.
+ * - **YAML** has `Bun.YAML.stringify`, but it emits flow style with no trailing
+ *   newline (`{a: 1,b: {c: d}}`). That is valid YAML and completely wrong for a
+ *   file a user opens, so we render block style ourselves.
+ *
+ * The renderers originally covered only the shallow shapes our builders emit.
+ * That was fine while they only ever saw generated documents — but the
+ * integration writer parses the USER's whole config and re-serializes it, so a
+ * legitimate `null` or a numeric array in a file we never wrote threw straight
+ * out of the writer and surfaced as a 500. They now cover the value domains
+ * their formats actually allow.
+ *
+ * What they still refuse is genuinely unrenderable: a function, a symbol, a
+ * non-finite number. Those must fail loudly rather than produce bytes a client
+ * might misread — and the writer turns the failure into a structured refusal
+ * rather than an exception.
+ *
+ * Design of record: devlog/_fin/260802_client_toggle_api/011_wp1_builders.md.
+ */
+
+export type ConfigFormat = "json" | "yaml" | "toml" | "json5";
+
+/** Thrown when a document holds a value its format cannot represent. */
+export class UnserializableValueError extends Error {}
+
+export const FORMAT_MEDIA_TYPE: Record<ConfigFormat, string> = {
+  json: "application/json",
+  yaml: "application/yaml",
+  toml: "application/toml",
+  json5: "application/json5",
+};
+
+/**
+ * Type guard, not a boolean check — the renderers walk `unknown`, so without
+ * the predicate every narrowed branch stays `unknown`.
+ */
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isYamlScalar(value: unknown): value is string | number | boolean | null {
+  return value === null
+    || typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+
+/**
+ * Keep only unambiguous, single-token strings plain. Everything else uses a
+ * JSON-compatible double-quoted scalar, which gives deterministic escaping —
+ * JSON string escaping is valid YAML 1.2 string escaping.
+ */
+function yamlString(value: string): string {
+  const plainSafe = value.length > 0
+    && value.trim() === value
+    && /^[A-Za-z_./][A-Za-z0-9_./-]*$/u.test(value)
+    && !/^(?:null|true|false|yes|no|on|off|~|\.nan|[-+]?\.inf)$/iu.test(value);
+  return plainSafe ? value : JSON.stringify(value);
+}
+
+function yamlScalar(value: string | number | boolean | null): string {
+  // `null` renders as the explicit `null` token rather than an empty value:
+  // a bare `key:` is also null in YAML, but round-tripping it through other
+  // parsers is less predictable than saying so.
+  if (value === null) return "null";
+  if (typeof value === "string") return yamlString(value);
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (Number.isFinite(value)) return String(value);
+  throw new UnserializableValueError(`YAML cannot represent the number ${String(value)}`);
+}
+
+function yamlEmptyCollection(value: unknown): "[]" | "{}" | undefined {
+  if (Array.isArray(value) && value.length === 0) return "[]";
+  if (isPlainRecord(value) && Object.keys(value).length === 0) return "{}";
+  return undefined;
+}
+
+function yamlMapEntryLines(key: string, value: unknown, indent: number): string[] {
+  const padding = " ".repeat(indent);
+  const renderedKey = yamlString(key);
+  if (isYamlScalar(value)) return [`${padding}${renderedKey}: ${yamlScalar(value)}`];
+  const empty = yamlEmptyCollection(value);
+  if (empty !== undefined) return [`${padding}${renderedKey}: ${empty}`];
+  if (Array.isArray(value) || isPlainRecord(value)) {
+    return [`${padding}${renderedKey}:`, ...yamlLines(value, indent + 2)];
+  }
+  throw new UnserializableValueError(`YAML cannot represent the value at key ${JSON.stringify(key)}: ${describeValue(value)}`);
+}
+
+/** A map inside a sequence: the first key rides the dash, the rest indent under it. */
+function yamlArrayMapLines(value: Record<string, unknown>, indent: number): string[] {
+  const entries = Object.entries(value);
+  const padding = " ".repeat(indent);
+  if (entries.length === 0) return [`${padding}- {}`];
+
+  const [first, ...rest] = entries;
+  const [firstKey, firstValue] = first!;
+  const renderedFirstKey = yamlString(firstKey);
+  const firstEmpty = yamlEmptyCollection(firstValue);
+  const lines: string[] = [];
+  if (isYamlScalar(firstValue)) {
+    lines.push(`${padding}- ${renderedFirstKey}: ${yamlScalar(firstValue)}`);
+  } else if (firstEmpty !== undefined) {
+    lines.push(`${padding}- ${renderedFirstKey}: ${firstEmpty}`);
+  } else if (Array.isArray(firstValue) || isPlainRecord(firstValue)) {
+    lines.push(`${padding}- ${renderedFirstKey}:`);
+    lines.push(...yamlLines(firstValue, indent + 4));
+  } else {
+    throw new UnserializableValueError(`YAML cannot represent the value at key ${JSON.stringify(firstKey)}: ${describeValue(firstValue)}`);
+  }
+  for (const [key, child] of rest) lines.push(...yamlMapEntryLines(key, child, indent + 2));
+  return lines;
+}
+
+function yamlLines(value: unknown, indent: number): string[] {
+  const padding = " ".repeat(indent);
+  if (isYamlScalar(value)) return [`${padding}${yamlScalar(value)}`];
+  if (Array.isArray(value)) {
+    if (value.length === 0) return [`${padding}[]`];
+    return value.flatMap(item => {
+      if (isYamlScalar(item)) return [`${padding}- ${yamlScalar(item)}`];
+      if (isPlainRecord(item)) return yamlArrayMapLines(item, indent);
+      /*
+       * A nested sequence is ordinary YAML (`matrix: [[1,2],[3,4]]`). This
+       * used to throw a plain Error carrying `String(item)` — untyped, so the
+       * writer could not turn it into a refusal and it surfaced as a 500, and
+       * carrying the value's CONTENTS into the message, which a config may
+       * not want repeated.
+       */
+      if (Array.isArray(item)) {
+        if (item.length === 0) return [`${padding}- []`];
+        return [`${padding}-`, ...yamlLines(item, indent + 2)];
+      }
+      throw new UnserializableValueError(
+        `YAML cannot represent this sequence item: ${describeValue(item)}`,
+      );
+    });
+  }
+  if (isPlainRecord(value)) {
+    const entries = Object.entries(value);
+    if (entries.length === 0) return [`${padding}{}`];
+    return entries.flatMap(([key, child]) => yamlMapEntryLines(key, child, indent));
+  }
+  throw new UnserializableValueError(`YAML cannot represent this value: ${describeValue(value)}`);
+}
+
+/** Block-style YAML for the shallow shapes we emit. Throws on anything else. */
+export function renderYaml(value: unknown, indent = 0): string {
+  if (!Number.isInteger(indent) || indent < 0) {
+    throw new Error(`YAML indent must be a non-negative integer: ${String(indent)}`);
+  }
+  return `${yamlLines(value, indent).join("\n")}\n`;
+}
+
+/** A short, safe description for an error message — never the value's contents. */
+function describeValue(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "an array";
+  if (typeof value === "object") return "an object";
+  return typeof value;
+}
+
+/** TOML basic-string escape. Mirrors `tomlString` in src/grok/inject.ts. */
+export function tomlString(value: string): string {
+  return JSON.stringify(value);
+}
+
+/** Bare key when safe, basic-string key otherwise (TOML 1.0 §Keys). */
+export function quoteTomlKey(key: string): string {
+  return /^[A-Za-z0-9_-]+$/.test(key) ? key : tomlString(key);
+}
+
+function tomlScalar(value: unknown): string {
+  if (typeof value === "string") return tomlString(value);
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  /*
+   * Arrays of ANY scalar, not just strings. The string-only check was written
+   * against our own builder output; a user's config legitimately holds
+   * `ports = [1, 2]`, and refusing it threw out of the writer as a 500.
+   * TOML permits mixed-type arrays since 1.0, so the elements are rendered
+   * individually rather than required to share a type.
+   */
+  if (Array.isArray(value)) {
+    return `[${value.map(item => tomlScalar(item)).join(", ")}]`;
+  }
+  /*
+   * An inline table is valid TOML (`items = [{ x = 1 }]`), and rendering one
+   * inline is straightforward — but only where the whole array can be
+   * rendered, so this stays a scalar-position renderer rather than silently
+   * flattening a table into a string.
+   */
+  if (isPlainRecord(value)) {
+    const entries = Object.entries(value);
+    return `{ ${entries.map(([k, v]) => `${quoteTomlKey(k)} = ${tomlScalar(v)}`).join(", ")} }`;
+  }
+  throw new UnserializableValueError(`TOML cannot represent this value: ${describeValue(value)}`);
+}
+
+/**
+ * Render `{ [table]: { key: scalar } }` as TOML. Scalars come first, then
+ * tables in insertion order, so two calls with the same document produce
+ * identical bytes — the stability guarantee `normalizeExportModels` exists to
+ * protect.
+ */
+export function renderToml(document: Record<string, unknown>, prefix = ""): string {
+  const scalars: string[] = [];
+  const tables: string[] = [];
+  for (const [key, value] of Object.entries(document)) {
+    const path = prefix ? `${prefix}.${quoteTomlKey(key)}` : quoteTomlKey(key);
+    if (isPlainRecord(value)) {
+      tables.push(`[${path}]\n${renderToml(value, path)}`.trimEnd());
+    } else {
+      scalars.push(`${quoteTomlKey(key)} = ${tomlScalar(value)}`);
+    }
+  }
+  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": {
+      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": {
+      if (!isPlainRecord(document)) throw new Error("TOML root must be a table");
+      return renderToml(document);
+    }
+  }
+}

package/src/integrations/state.ts

@@ -0,0 +1,361 @@
+/**
+ * "What is on disk, and did we put it there?"
+ *
+ * The classifier is deliberately ordered, and the order is load-bearing: an
+ * unreadable file can never be reported as absent, and an edit to a fragment
+ * we own can never be reported as ordinary drift. Getting that wrong would let
+ * `disable` delete a user's own edits.
+ *
+ * Design of record: devlog/_fin/260802_client_toggle_api/021 §3.
+ */
+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";
+import { SNAPSHOT_RETENTION } from "./journal";
+import { canonicalContribution, fingerprint, type OwnershipRecord } from "./ownership";
+import { INTEGRATION_CLIENTS, type IntegrationClientId } from "./registry";
+import { createIntegrationStateStore, type IntegrationStateStore } from "./store";
+
+export type IntegrationState = "absent" | "current" | "stale" | "conflict" | "unsafe";
+export type StateReason =
+  | "unparseable"
+  | "not-regular-file"
+  | "foreign-edit"
+  | "unowned-key"
+  /** A container we would have to write through holds a non-object value. */
+  | "blocked-container"
+  /** A path selector we cannot resolve, e.g. a relative OPENCLAW_CONFIG_PATH. */
+  | "unresolvable-path";
+
+export interface IntegrationStatus {
+  clientId: IntegrationClientId;
+  state: IntegrationState;
+  installed: boolean;
+  configPath: string;
+  appliedAt?: string;
+  lastOpId?: string;
+  reason?: StateReason;
+  /** Snapshot files retained for this client; -1 when they cannot be inspected. */
+  snapshotCount: number;
+  /** Pruning is behind, so older (possibly credential-bearing) snapshots remain. */
+  retentionDegraded: boolean;
+}
+
+export function readPath(doc: unknown, path: readonly string[]): unknown {
+  let cursor: unknown = doc;
+  for (const key of path) {
+    if (typeof cursor !== "object" || cursor === null || Array.isArray(cursor)) return undefined;
+    cursor = (cursor as Record<string, unknown>)[key];
+    if (cursor === undefined) return undefined;
+  }
+  return cursor;
+}
+
+/** Does the document carry any fragment we would write? */
+export function hasOurFragments(doc: unknown, contribution: ManagedContribution): boolean {
+  return contribution.fragments.some(fragment => readPath(doc, fragment.path) !== undefined);
+}
+
+/**
+ * A container on one of our fragment paths that exists but is NOT an object.
+ *
+ * `setPath` replaces such a value with `{}` on the way to writing our leaf, so
+ * a user whose config held `providers: ["something"]` — legal in their schema,
+ * just not ours — lost it to an apply that reported success. The classifier
+ * called that document `absent` because our leaf was missing, which authorized
+ * the write. Detecting it here turns a silent overwrite into a refusal the
+ * user can act on; the snapshot exists, but "we backed up the thing we should
+ * not have destroyed" is not the promise this feature makes.
+ */
+export function blockedContainerPath(
+  doc: unknown,
+  contribution: ManagedContribution,
+): readonly string[] | null {
+  for (const fragment of contribution.fragments) {
+    let cursor: unknown = doc;
+    for (let depth = 0; depth < fragment.path.length - 1; depth += 1) {
+      const key = fragment.path[depth]!;
+      /*
+       * ONLY `undefined` means absent. A missing file parses as `{}`, so an
+       * absent prefix reads `undefined` — but a parsed `null` is a value the
+       * user's file actually contains, and treating it as absent let a
+       * document that is literally `null` be replaced wholesale by a
+       * "successful" apply.
+       */
+      if (cursor === undefined) break;
+      // `typeof null === "object"`, so null has to be named explicitly or it
+      // walks straight into the dereference below.
+      if (cursor === null || typeof cursor !== "object" || Array.isArray(cursor)) {
+        return fragment.path.slice(0, depth);
+      }
+      const next = (cursor as Record<string, unknown>)[key];
+      if (next === undefined) break;
+      if (typeof next !== "object" || next === null || Array.isArray(next)) {
+        return fragment.path.slice(0, depth + 1);
+      }
+      cursor = next;
+    }
+  }
+  return null;
+}
+
+/**
+ * Fingerprint the recorded fragments as they appear in the document now.
+ *
+ * The record intentionally names every path we own. Comparing just those
+ * values lets another integration or a user add a sibling without blocking a
+ * later refresh, while a change inside our block still fails closed.
+ */
+function recordedFragmentFingerprint(
+  doc: unknown,
+  record: OwnershipRecord,
+): string | null {
+  if (
+    !Array.isArray(record.fragmentPaths)
+    || record.fragmentPaths.length === 0
+    || !record.fragmentPaths.every(path => (
+      Array.isArray(path)
+      && path.length > 0
+      && path.every(key => typeof key === "string")
+    ))
+  ) return null;
+  const fragments = [];
+  for (const path of record.fragmentPaths) {
+    const value = readPath(doc, path);
+    if (value === undefined) return null;
+    fragments.push({ path, value });
+  }
+  return fingerprint(canonicalContribution({
+    clientId: record.clientId,
+    fragments,
+  }));
+}
+
+/**
+ * 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. 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;
+  fileIsRegular: boolean;
+  parsed: unknown | typeof PARSE_FAILED;
+  record: OwnershipRecord | null;
+  contribution: ManagedContribution;
+  /**
+   * The file being classified. A record only describes the file it was written
+   * for, so this is compared against `record.configPath` before any
+   * fingerprint is trusted.
+   */
+  configPath?: string;
+  clientId?: IntegrationClientId;
+}): { state: IntegrationState; reason?: StateReason } {
+  if (input.fileText !== null && !input.fileIsRegular) {
+    return { state: "unsafe", reason: "not-regular-file" };
+  }
+  if (input.parsed === PARSE_FAILED) return { state: "unsafe", reason: "unparseable" };
+  /*
+   * Checked BEFORE `absent`: our leaf is missing in exactly this case, so the
+   * absent branch would authorize an apply that replaces the user's value.
+   */
+  if (blockedContainerPath(input.parsed, input.contribution)) {
+    return { state: "unsafe", reason: "blocked-container" };
+  }
+  if (!hasOurFragments(input.parsed, input.contribution)) return { state: "absent" };
+  if (!input.record) return { state: "conflict", reason: "unowned-key" };
+  /*
+   * A record proves ownership of ONE file. Change HOME, XDG_CONFIG_HOME,
+   * HERMES_HOME or KIMI_CODE_HOME and the same client resolves to a different
+   * path — whose contents may hash identically because we generate the same
+   * bytes. Trusting the fingerprint alone would let a record for path A grant
+   * `current` on path B, and the writer resolves the CURRENT path, so disable
+   * would then delete fragments from a file this record never owned.
+   */
+  if (input.clientId !== undefined && input.record.clientId !== input.clientId) {
+    return { state: "conflict", reason: "unowned-key" };
+  }
+  if (input.configPath !== undefined && input.record.configPath !== input.configPath) {
+    return { state: "conflict", reason: "unowned-key" };
+  }
+  const clientId = input.clientId ?? input.record.clientId;
+  /*
+   * 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" };
+}
+
+export interface IntegrationStateInput {
+  clientId: IntegrationClientId;
+  models: readonly ExportModel[];
+  config: OcxConfig;
+  port: number;
+  env?: NodeJS.ProcessEnv;
+  home?: string;
+  /** The whole integration state store, bound to one root. */
+  store?: IntegrationStateStore;
+  io?: IntegrationIO;
+}
+
+export function exportContextOf(input: {
+  models: readonly ExportModel[];
+  config: OcxConfig;
+  port: number;
+}): { baseUrl: string; models: readonly ExportModel[]; config: OcxConfig } {
+  return {
+    /*
+     * Composed through the SAME helper `ocx export` uses. Interpolating the
+     * hostname by hand looked equivalent and was not: `::1` produced
+     * `http://::1:10100/v1` and `::` produced `http://:::10100/v1`, neither of
+     * which is a URL, and a `0.0.0.0` bind wrote a wildcard address no client
+     * can dial. `opencodeProxyBaseUrl` brackets IPv6 and maps wildcards to
+     * loopback, and every client we write into deserves the same answer the
+     * export command already gives.
+     */
+    baseUrl: opencodeProxyBaseUrl(input.port, input.config.hostname),
+    models: input.models,
+    config: input.config,
+  };
+}
+
+let retriedThisProcess = false;
+
+/**
+ * Retry pending prunes once per process for the default store, and always for
+ * an explicitly supplied one so tests stay order-independent. Never throws: a
+ * retry failure is a logged no-op, not a failed read.
+ */
+export function retryPendingPrunesOnce(store: IntegrationStateStore): void {
+  if (store.root === createIntegrationStateStore().root) {
+    if (retriedThisProcess) return;
+    retriedThisProcess = true;
+  }
+  try {
+    store.retryPendingPrunes();
+  } catch (error) {
+    console.error(`[integrations] prune retry failed: ${String(error)}`);
+  }
+}
+
+/**
+ * Retention is derived from what is ON DISK, not from the maintenance marker.
+ * The marker schedules retries and can itself fail to write; a promise about
+ * the user's credential-bearing backups must not depend on that.
+ */
+function retentionOf(
+  clientId: IntegrationClientId,
+  store: IntegrationStateStore,
+): { snapshotCount: number; retentionDegraded: boolean } {
+  const counted = store.countSnapshots(clientId);
+  if (counted === null) {
+    // Cannot inspect: report degraded with -1 rather than a reassuring zero.
+    return { snapshotCount: -1, retentionDegraded: true };
+  }
+  const marked = store.readMaintenance().pruneFailures[clientId] !== undefined;
+  return { snapshotCount: counted, retentionDegraded: marked || counted > SNAPSHOT_RETENTION };
+}
+
+/** The ONE reader every surface uses. */
+export function readIntegrationState(input: IntegrationStateInput): IntegrationStatus {
+  const store = input.store ?? createIntegrationStateStore();
+  retryPendingPrunesOnce(store);
+  const io = input.io ?? store.io();
+  const spec = INTEGRATION_CLIENTS[input.clientId];
+  const exportSpec = EXPORT_CLIENTS[input.clientId];
+  const retention = retentionOf(input.clientId, store);
+  /*
+   * Resolution can refuse — a relative OPENCLAW_* selector names a file whose
+   * meaning depends on a working directory we cannot know. The LIST route asks
+   * every client for its state, so letting that escape would answer 500 for
+   * the whole Integrations page because one client is misconfigured.
+   */
+  let configPath: string;
+  let installed: boolean;
+  try {
+    configPath = spec.configPath(input.env, input.home);
+    installed = io.statKind(spec.detectDir(input.env, input.home)) === "dir";
+  } catch (error) {
+    if (!(error instanceof ClientPathError)) throw error;
+    return {
+      clientId: input.clientId,
+      state: "unsafe",
+      installed: false,
+      configPath: "",
+      reason: "unresolvable-path",
+      ...retention,
+    };
+  }
+
+  const target = loadTarget(io, configPath);
+  if (!target.ok) {
+    return {
+      clientId: input.clientId,
+      state: "unsafe",
+      installed,
+      configPath,
+      reason: target.why === "read-failed" ? "unparseable" : "not-regular-file",
+      ...retention,
+    };
+  }
+
+  const parsed = parseConfig(target.before, exportSpec.format);
+  const contribution = exportSpec.buildContribution(exportContextOf(input));
+  const record = store.readRecords()[input.clientId] ?? null;
+  const { state, reason } = classifyIntegration({
+    fileText: target.before,
+    fileIsRegular: true,
+    parsed,
+    record,
+    contribution,
+    configPath,
+    clientId: input.clientId,
+  });
+
+  return {
+    clientId: input.clientId,
+    state,
+    installed,
+    configPath,
+    ...(reason ? { reason } : {}),
+    ...(record ? { appliedAt: record.appliedAt, lastOpId: record.opId } : {}),
+    ...retention,
+  };
+}