@bitkyc08/opencodex 2.60.0 → 2.61.0-preview.20260922

package/src/integrations/state.ts

@@ -11,10 +11,18 @@
 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 { ConfigFormat } 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 { AmbiguousSelectorError, parseSegment, selectIndex, type PathSegment } from "./merge";
+import {
+  AmbiguousSelectorError,
+  InvalidSelectorError,
+  parseSegment,
+  readPath,
+  selectIndex,
+  type PathSegment,
+} from "./merge";
 import { canonicalContribution, fingerprint, semanticContribution, type OwnershipRecord } from "./ownership";
 import {
   protectedContributionFingerprint,
@@ -28,6 +36,7 @@ import {
   unresolvedPathHintFor,
   type IntegrationClientId,
 } from "./registry";
+import { resolveIntegrationTarget, type IntegrationTarget } from "./target";
 import { createIntegrationStateStore, type IntegrationStateStore } from "./store";
 
 export type IntegrationState = "absent" | "current" | "stale" | "conflict" | "unsafe";
@@ -50,6 +59,21 @@ export interface IntegrationStatus {
   appliedAt?: string;
   lastOpId?: string;
   reason?: StateReason;
+  /**
+   * The store this client reads instead of `configPath`.
+   *
+   * Present only when the integration is NOT writing that store: either our
+   * block is still in the config file, or the store is not a document whose
+   * shape has been observed. Where the store is written, `configPath` names it
+   * and there is nothing to report beside the state.
+   *
+   * Orthogonal to `state`, which answers "what is on disk, and did we put it
+   * there?" — and answers it correctly here: the block can be byte-for-byte
+   * current in a file the client stopped opening. That pair is not a
+   * contradiction, it is the whole of #5348, so the surface that reports
+   * `current` has to be able to report this beside it.
+   */
+  supersededBy?: 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. */
@@ -64,37 +88,14 @@ function assertNever(segment: never): never {
   throw new Error(`unknown path segment ${JSON.stringify(segment)}`);
 }
 
-/** The element a selector names, or `undefined` when none matches. */
-function selectElement(items: readonly unknown[], segment: PathSegment & { kind: "select" }): unknown {
-  return items[selectIndex(items, segment.field, segment.value)];
-}
-
 /**
- * Same segment grammar as `setPath`: a plain key reads through a record, a
- * `[field=value]` selector reads through an array. Because the classifier and
- * the writer share this one function, status and mutation cannot disagree
- * about which element is ours.
+ * The path reader lives with the path grammar, in `merge`, and is re-exported
+ * here because the classifier was its original home and every caller imports
+ * it from this module. One implementation is the point: a reader that resolved
+ * a selector differently from the writer would report one element as ours and
+ * then rewrite another.
  */
-export function readPath(doc: unknown, path: readonly string[]): unknown {
-  let cursor: unknown = doc;
-  for (const raw of path) {
-    const segment = parseSegment(raw);
-    switch (segment.kind) {
-      case "key":
-        if (!isPlainRecord(cursor)) return undefined;
-        cursor = cursor[segment.key];
-        break;
-      case "select":
-        if (!Array.isArray(cursor)) return undefined;
-        cursor = selectElement(cursor, segment);
-        break;
-      default:
-        return assertNever(segment);
-    }
-    if (cursor === undefined) return undefined;
-  }
-  return cursor;
-}
+export { readPath };
 
 /** Does the document carry any fragment we would write? */
 export function hasOurFragments(doc: unknown, contribution: ManagedContribution): boolean {
@@ -136,7 +137,7 @@ export function blockedContainerPath(
       case "key":
         return (value as Record<string, unknown>)[segment.key];
       case "select":
-        return selectElement(value as readonly unknown[], segment);
+        return (value as readonly unknown[])[selectIndex(value as readonly unknown[], segment.criteria)];
       default:
         return assertNever(segment);
     }
@@ -285,6 +286,14 @@ export function classifyIntegration(input: {
    */
   configPath?: string;
   clientId?: IntegrationClientId;
+  /**
+   * Text format of the file being classified, which is not always the client's
+   * config format: a client that moved its providers keeps a second document
+   * whose format is declared with the store. Only the comment-capability of the
+   * format is read here, and reading the wrong one would decide a sibling edit
+   * the wrong way.
+   */
+  format?: ConfigFormat;
 }): { state: IntegrationState; reason?: StateReason } {
   if (input.fileText !== null && !input.fileIsRegular) {
     return { state: "unsafe", reason: "not-regular-file" };
@@ -310,8 +319,13 @@ export function classifyIntegration(input: {
       }
     }
   } catch (error) {
-    if (!(error instanceof AmbiguousSelectorError)) throw error;
-    return { state: "unsafe", reason: "ambiguous-selector" };
+    if (error instanceof AmbiguousSelectorError) {
+      return { state: "unsafe", reason: "ambiguous-selector" };
+    }
+    if (error instanceof InvalidSelectorError) {
+      return { state: "unsafe", reason: "unparseable" };
+    }
+    throw error;
   }
   if (!hasOurFragments(input.parsed, input.contribution)) return { state: "absent" };
 
@@ -393,7 +407,7 @@ export function classifyIntegration(input: {
      * 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") {
+    if ((input.format ?? EXPORT_CLIENTS[clientId].format) !== "json") {
       return { state: "conflict", reason: "foreign-edit" };
     }
     return { state: "stale" };
@@ -491,7 +505,6 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
   retryPendingPrunesOnce(store);
   let 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
@@ -499,14 +512,25 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
    * 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;
+  let effective: IntegrationTarget;
+  let record: OwnershipRecord | null;
   try {
     // One resolution for both, so a client whose paths come from mutable state
     // cannot report one account's install beside another account's config path.
     const paths = input.resolvedPaths ?? resolveIntegrationPaths(input.clientId, input.env, input.home);
-    configPath = paths.configPath;
     installed = io.statKind(paths.detectDir) === "dir";
+    if (input.clientId === "cline") io = createClineIO(io, paths.configPath, store);
+    /*
+     * The record is one of the inputs the target is chosen from, so it is read
+     * here rather than after the file. The status this function reports is about
+     * whichever file the next mutation would act on; reading a different one
+     * would let the badge and the switch disagree.
+     */
+    record = store.readRecords()[input.clientId] ?? null;
+    effective = resolveIntegrationTarget({
+      clientId: input.clientId, configPath: paths.configPath, io, record, env: input.env, home: input.home,
+    });
   } catch (error) {
     if (!(error instanceof ClientPathError)) throw error;
     /*
@@ -531,30 +555,32 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
     };
   }
 
-  if (input.clientId === "cline") io = createClineIO(io, configPath, store);
-  const target = loadTarget(io, configPath);
-  if (!target.ok) {
+  const configPath = effective.configPath;
+  const loaded = loadTarget(io, configPath);
+  if (!loaded.ok) {
     return {
       clientId: input.clientId,
       state: "unsafe",
       installed,
       configPath,
-      reason: target.why === "read-failed" ? "unparseable" : "not-regular-file",
+      reason: loaded.why === "read-failed" ? "unparseable" : "not-regular-file",
       ...retention,
     };
   }
 
-  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 parsed = input.clientId === "cline"
+    ? parseClineDocument(loaded.before)
+    : parseConfig(loaded.before, effective.format);
+  const contribution = effective.buildContribution(exportContextOf(input));
   const { state, reason } = classifyIntegration({
-    fileText: target.before,
+    fileText: loaded.before,
     fileIsRegular: true,
     parsed,
     record,
     contribution,
     configPath,
     clientId: input.clientId,
+    format: effective.format,
   });
 
   return {
@@ -563,6 +589,13 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
     installed,
     configPath,
     ...(reason ? { reason } : {}),
+    /*
+     * Only when the client reads a DIFFERENT file than the one this status is
+     * about. A store we are writing needs no notice; the path already names it.
+     */
+    ...(effective.ineffective && effective.ineffective.store !== configPath
+      ? { supersededBy: effective.ineffective.store }
+      : {}),
     ...(record ? { appliedAt: record.appliedAt, lastOpId: record.opId } : {}),
     ...retention,
   };

package/src/integrations/target.ts

@@ -0,0 +1,208 @@
+/**
+ * Which file an integration operation reads, writes and records — and, when
+ * that is not the file the client reads, which file is.
+ *
+ * A client may move its provider list between releases and keep the old file
+ * reachable only through a one-shot import. Everything the integration checks
+ * still passes against the old file: it is writable, the block merges, the
+ * ownership record describes it correctly. The only thing that changed is
+ * whether anything reads it (#5348).
+ *
+ * So the target is chosen before anything is classified, and it is chosen by
+ * three facts in this order:
+ *
+ * 1. No declared store, or no store on disk — the config file, exactly as
+ *    before. A client that has never run still imports what we write there.
+ * 2. Our own block already sits in the config file this record names. Stay
+ *    there. Disable removes what we wrote from where we wrote it, and the
+ *    caller reports the write as ineffective rather than orphaning a block in
+ *    one file while writing another.
+ * 3. Otherwise the store, but only when its schema can be established. A store
+ *    we cannot parse or whose version we have not observed is reported as the
+ *    reason the write cannot reach the client, because merging an invented
+ *    nesting into a file holding the user's other providers would trade a
+ *    silent no-op for a silent loss.
+ */
+import { EXPORT_CLIENTS, ClientPathError, type BuildContribution, type ConfigFormat } from "../clients/config-export";
+import { PARSE_FAILED, loadTarget, parseConfig, type IntegrationIO } from "./config-io";
+import { AmbiguousSelectorError, InvalidSelectorError, readPath } from "./merge";
+import type { OwnershipRecord } from "./ownership";
+import { INTEGRATION_CLIENTS, type IntegrationClientId } from "./registry";
+
+export interface IntegrationTarget {
+  /** The file this operation reads, writes, journals and records ownership for. */
+  readonly configPath: string;
+  /** Text format of that file, which is not always the client's config format. */
+  readonly format: ConfigFormat;
+  /** The contribution shape that file's reader understands. */
+  readonly buildContribution: BuildContribution;
+  /**
+   * Set when a write to the file above would not reach the client.
+   *
+   * `why` is carried rather than re-derived because the cases have different
+   * remedies and only this function knows which one it took. Disable is not
+   * gated on it: removing bytes this project wrote from the file it wrote them
+   * to is as effective as it ever was.
+   */
+  readonly ineffective: IneffectiveWrite | null;
+}
+
+export interface IneffectiveWrite {
+  /** The provider store the client reads. */
+  readonly store: string;
+  /**
+   * `owned-config-file` — this project's block is still in the config file, so
+   * the operation stays there and the remedy is to remove it first, rather than
+   * leave a block in one file while writing another.
+   *
+   * `unestablished-schema` — the store is not a document whose shape has been
+   * observed, so there is nothing safe to merge into it. This one is reachable
+   * with the store itself as the target: a client that bumps its schema after
+   * we wrote the store leaves our block there, removable, and the file no
+   * longer one we may merge into.
+   */
+  readonly why: "owned-config-file" | "unestablished-schema";
+}
+
+function configFileTarget(
+  clientId: IntegrationClientId,
+  configPath: string,
+  ineffective: IneffectiveWrite | null,
+): IntegrationTarget {
+  const exportSpec = EXPORT_CLIENTS[clientId];
+  return {
+    configPath,
+    format: exportSpec.format,
+    buildContribution: exportSpec.buildContribution,
+    ineffective,
+  };
+}
+
+function storeTarget(
+  declared: NonNullable<(typeof INTEGRATION_CLIENTS)[IntegrationClientId]["currentStore"]>,
+  configPath: string,
+  ineffective: IneffectiveWrite | null = null,
+): IntegrationTarget {
+  return {
+    configPath,
+    format: declared.format,
+    buildContribution: declared.buildContribution,
+    ineffective,
+  };
+}
+
+/**
+ * Does the file this record names still hold any fragment it claims?
+ *
+ * Uncertainty answers yes. An unreadable or unparseable config file is a state
+ * the classifier is about to refuse on, and it must refuse on the file our
+ * record is about rather than silently move the operation to a different one.
+ * An ambiguous or invalid selector is the same kind of answer.
+ */
+function recordedBlockStillPresent(
+  io: IntegrationIO,
+  format: ConfigFormat,
+  configPath: string,
+  record: OwnershipRecord,
+): boolean {
+  const loaded = loadTarget(io, configPath);
+  if (!loaded.ok) return true;
+  const parsed = parseConfig(loaded.before, format);
+  if (parsed === PARSE_FAILED) return true;
+  try {
+    return record.fragmentPaths.some(path => readPath(parsed, path) !== undefined);
+  } catch (error) {
+    if (error instanceof AmbiguousSelectorError || error instanceof InvalidSelectorError) return true;
+    throw error;
+  }
+}
+
+/**
+ * Resolve the target for one operation.
+ *
+ * `configPath` is the client's config file as the registry resolves it now, and
+ * `record` is the stored ownership as read, before any path filtering — the
+ * filtering depends on the answer this function returns.
+ *
+ * The store is observed through the caller's own `IntegrationIO`, never the
+ * real filesystem directly, so status and mutation cannot disagree about
+ * whether a write can land.
+ */
+export function resolveIntegrationTarget(args: {
+  clientId: IntegrationClientId;
+  configPath: string;
+  io: IntegrationIO;
+  record: OwnershipRecord | null;
+  env?: NodeJS.ProcessEnv;
+  home?: string;
+}): IntegrationTarget {
+  const { clientId, configPath, io, record } = args;
+  const declared = INTEGRATION_CLIENTS[clientId].currentStore;
+  if (!declared) return configFileTarget(clientId, configPath, null);
+  const storePath = declared.path(args.env, args.home);
+  const kind = io.statKind(storePath);
+  if (kind === "missing") return configFileTarget(clientId, configPath, null);
+  // Only proven absence permits a legacy write. Unreadable or non-file stores
+  // cannot establish what the client reads; preserve the recorded removal target.
+  if (kind !== "file") {
+    const ineffective: IneffectiveWrite = { store: storePath, why: "unestablished-schema" };
+    return record?.clientId === clientId && record.configPath === storePath
+      ? storeTarget(declared, storePath, ineffective)
+      : configFileTarget(clientId, configPath, ineffective);
+  }
+  const loaded = loadTarget(io, storePath);
+  const parsed = loaded.ok ? parseConfig(loaded.before, declared.format) : PARSE_FAILED;
+  const established = parsed !== PARSE_FAILED && declared.establishes(parsed);
+  const unestablished: IneffectiveWrite = { store: storePath, why: "unestablished-schema" };
+  /*
+   * Our own block decides the target before the store's schema does, whichever
+   * file holds it. Disable has to remove what we wrote from where we wrote it,
+   * and an apply must never leave a block in one file while writing another.
+   */
+  const owned = record !== null && record.clientId === clientId ? record : null;
+  if (owned?.configPath === storePath && recordedBlockStillPresent(io, declared.format, storePath, owned)) {
+    return storeTarget(declared, storePath, established ? null : unestablished);
+  }
+  if (
+    owned?.configPath === configPath
+    && recordedBlockStillPresent(io, EXPORT_CLIENTS[clientId].format, configPath, owned)
+  ) {
+    return configFileTarget(clientId, configPath, { store: storePath, why: "owned-config-file" });
+  }
+  if (!established) {
+    return configFileTarget(clientId, configPath, unestablished);
+  }
+  return storeTarget(declared, storePath);
+}
+
+/**
+ * The target a path NAMES, or null when this client may not write there.
+ *
+ * Undo acts on the file its journal row recorded, so it needs the meaning of a
+ * historical path rather than the choice above: which contribution shape
+ * describes those bytes, and whether this client still resolves that location
+ * at all. Resolving a path the client no longer names is what would let a row
+ * recorded for one home delete a file in another, so an unrecognised path is
+ * null and the caller refuses.
+ */
+export function declaredIntegrationTarget(args: {
+  clientId: IntegrationClientId;
+  configPath: string;
+  resolvedConfigPath: string;
+  env?: NodeJS.ProcessEnv;
+  home?: string;
+}): IntegrationTarget | null {
+  const { clientId, configPath, resolvedConfigPath } = args;
+  if (configPath === resolvedConfigPath) return configFileTarget(clientId, configPath, null);
+  const declared = INTEGRATION_CLIENTS[clientId].currentStore;
+  if (!declared) return null;
+  try {
+    if (declared.path(args.env, args.home) !== configPath) return null;
+  } catch (error) {
+    // A store the operator relocated with a path we cannot resolve proves
+    // nothing about the row, so the row is not a legal target.
+    if (error instanceof ClientPathError) return null;
+    throw error;
+  }
+  return storeTarget(declared, configPath);
+}

package/src/integrations/writer.ts

@@ -13,7 +13,7 @@ import { homedir } from "node:os";
 import { createClineIO, ClineTransactionError } from "./cline-io";
 import { serializeClineDocument, preserveClineSelection } from "./cline-document";
 import { dirname } from "node:path";
-import { EXPORT_CLIENTS, type ExportModel, type ManagedContribution } from "../clients/config-export";
+import type { ExportModel, ManagedContribution } from "../clients/config-export";
 import { shouldInjectApiAuthHeader } from "../codex/inject";
 import { detachedConfigSnapshot } from "../config/admitted-identity";
 import { copyPlainData } from "../lib/plain-data";
@@ -33,6 +33,7 @@ import {
 } from "./ownership-policy";
 import { AmbiguousSelectorError, createdContainerPaths, mergeContribution, removeFragments } from "./merge";
 import { INTEGRATION_CLIENTS, isLoopbackOnly, resolveIntegrationPaths, type IntegrationClientId } from "./registry";
+import { declaredIntegrationTarget } from "./target";
 import { exportContextOf } from "./state";
 import type { IntegrationState } from "./state";
 import { serializeDocument, UnserializableValueError } from "./serialize";
@@ -251,7 +252,7 @@ function applyOrRefreshIntegration(
 ): WriteOutcome {
   const pre = preflight(input);
   if (pre.failed) return pre.failed;
-  const { store, io, clientId, spec, exportSpec, configPath, detectDir, before, parsed, contribution, record, classified } = pre;
+  const { store, io, clientId, spec, target, configPath, detectDir, before, parsed, contribution, record, classified } = pre;
 
   // The detect directory preflight already resolved, so it cannot name a
   // different account than the config path this operation is about to write.
@@ -262,6 +263,35 @@ function applyOrRefreshIntegration(
     return refuse(clientId, "non_loopback", classified.state,
       `The generated ${clientId} integration is loopback-only and does not emit the admission header a non-loopback bind requires. Give it loopback access instead, through a tunnel or a local forwarder.`);
   }
+  /*
+   * The write would land, and nothing would read it.
+   *
+   * This is deliberately a refusal rather than a warning attached to a success.
+   * The file is writable, our block merges cleanly, and the ownership record
+   * that follows would describe a real state of a real file — which is exactly
+   * how the original defect stayed invisible: every check the integration runs
+   * passed, the journal recorded a correct apply, and no model ever appeared in
+   * the client (#5348). Reporting the operation as done is the part that is
+   * wrong, so the operation does not report at all.
+   *
+   * Reached only when the store cannot be written: either this project's block
+   * is still in the config file, where removing it is the way forward, or the
+   * store is not a document whose shape has been observed. Where the store can
+   * be written the operation targets it and never arrives here.
+   *
+   * Apply, overwrite and refresh only. Disable removes bytes this project put
+   * in this file, and that removal is as effective as it ever was.
+   */
+  if (target.ineffective !== null) {
+    const readsFrom = target.ineffective.store;
+    const fallback = `Add the proxy as a provider in ${clientId}'s own settings instead; \`ocx export --client ${clientId}\` prints the model list to copy.`;
+    return refuse(clientId, "superseded_store", classified.state,
+      target.ineffective.why === "owned-config-file"
+        ? `${clientId} now reads its providers from ${readsFrom}, and opencodex still has a block in ${configPath}, which it no longer reads. Disable the ${clientId} integration to remove that block, then enable it again to write ${readsFrom}.`
+        : readsFrom === configPath
+          ? `opencodex does not recognise the schema of ${readsFrom}, the file ${clientId} reads its providers from, so it will not merge into it. ${fallback}`
+          : `${clientId} now reads its providers from ${readsFrom}, whose schema opencodex does not recognise, so writing ${configPath} would change nothing it loads. ${fallback}`);
+  }
   if (classified.state === "conflict") {
     if (conflictPolicy === "refuse") {
       return refuse(clientId, "conflict", "conflict",
@@ -372,7 +402,7 @@ function applyOrRefreshIntegration(
       }
       text = patched;
     } else {
-      text = clientId === "cline" ? serializeClineDocument(nextDocument) : serializeDocument(nextDocument, exportSpec.format);
+      text = clientId === "cline" ? serializeClineDocument(nextDocument) : serializeDocument(nextDocument, target.format);
     }
   } catch (error) {
     if (error instanceof AmbiguousSelectorError) {
@@ -460,7 +490,7 @@ export function refreshIntegration(input: IntegrationWriteInput): WriteOutcome {
 export function disableIntegration(input: IntegrationWriteInput): WriteOutcome {
   const pre = preflight(input);
   if (pre.failed) return pre.failed;
-  const { store, io, clientId, spec, exportSpec, configPath, before, parsed, record, classified } = pre;
+  const { store, io, clientId, spec, target, configPath, before, parsed, record, classified } = pre;
 
   if (classified.state === "absent") {
     return { ok: true, changed: false, state: "absent", clientId, message: "not applied" };
@@ -532,7 +562,7 @@ export function disableIntegration(input: IntegrationWriteInput): WriteOutcome {
       }
       text = patched;
     } else {
-      text = clientId === "cline" ? serializeClineDocument(doc) : serializeDocument(doc, exportSpec.format);
+      text = clientId === "cline" ? serializeClineDocument(doc) : serializeDocument(doc, target.format);
     }
   } catch (error) {
     if (!(error instanceof UnserializableValueError)) throw error;
@@ -570,13 +600,21 @@ export function restoreIntegration(input: IntegrationRestoreInput): WriteOutcome
   const clientId = entry.clientId;
   const resolvedPath = input.resolvedPaths?.configPath
     ?? INTEGRATION_CLIENTS[clientId].configPath(input.env, input.home);
-  // Restore acts on the path the operation was journaled against. Resolving a
-  // different path here would let an operation recorded for one home delete a
-  // file in another.
   const configPath = entry.configPath;
-  if (resolvedPath !== configPath) {
+  /*
+   * Restore acts on the path the operation was journaled against. Resolving a
+   * different path here would let an operation recorded for one home delete a
+   * file in another — but a client may legally have written more than one file,
+   * so the question is whether this client still names that location, not
+   * whether it is the config file. The answer also carries the contribution
+   * shape those bytes are in, which is what the state below is measured against.
+   */
+  const rowTarget = declaredIntegrationTarget({
+    clientId, configPath, resolvedConfigPath: resolvedPath, env: input.env, home: input.home,
+  });
+  if (rowTarget === null) {
     return refuse(clientId, "conflict", "conflict",
-      `that operation was recorded for ${configPath}, but this client now resolves to ${resolvedPath}`);
+      `that operation was recorded for ${configPath}, which this client no longer writes; it now resolves to ${resolvedPath}`);
   }
   if (clientId === "cline") {
     try { io = createClineIO(io, configPath, store, true); }
@@ -625,7 +663,7 @@ export function restoreIntegration(input: IntegrationRestoreInput): WriteOutcome
   // exact bytes when the snapshot was taken. Re-deriving it from the file would
   // mean guessing which entries are ours, and a wrong guess deletes a user's.
   const restoredRecord = entry.priorRecord;
-  const fresh = EXPORT_CLIENTS[clientId].buildContribution(exportContextOf(input));
+  const fresh = rowTarget.buildContribution(exportContextOf(input));
   /*
    * Does the restored record actually describe the restored bytes?
    *

package/src/lab/conformance/fixture-provider.ts

@@ -12,6 +12,11 @@ export function fixtureProviderConfig(adapter: string): OcxProviderConfig {
     models: ["fixture-model"],
     defaultModel: "fixture-model",
     liveModels: false,
+    // The wire role is no longer read from the hostname, and an undeclared destination folds
+    // `developer` to `system` because one that rejects the role answers 400 and the turn never
+    // starts. This fixture is the one place that asserts the forwarded role, so the destination
+    // it stands for records that it accepts it. Only the Chat adapter reaches that decision.
+    ...(adapter === "openai-chat" ? { foldDeveloperRoleToSystem: false } : {}),
   };
 }
 

package/src/lib/browser-launch-notice.ts

@@ -0,0 +1,59 @@
+import type { OpenUrlResult } from "./open-url";
+
+/**
+ * The one sentence a terminal login says when nothing opened.
+ *
+ * Stated once because it is now said from three places — the Codex account login, the generic
+ * OAuth login and the key login — and a sentence restated three times drifts three ways. Callers
+ * that have something more specific to add append to it rather than rewriting it, so the part a
+ * user learns to recognize stays identical everywhere.
+ */
+export const BROWSER_LAUNCH_FAILED_NOTICE =
+  "⚠️  No browser could be opened here — open the URL above yourself.";
+
+/**
+ * Report a browser launch whose answer arrives after the code that started it has moved on.
+ *
+ * The OAuth controller does not await `onAuth`, so a CLI login cannot simply await the launcher
+ * there: the flow continues, and on a callback-server provider the very next thing it does is
+ * draw a readline prompt. A warning written at that moment lands on the line the user is typing
+ * on, which is worse than not warning at all.
+ *
+ * So the launch reports itself as soon as it settles, and anything that would collide with it
+ * waits on {@link BrowserLaunchReport.settled} first. The launcher answers within its own settle
+ * window, so the wait costs a fraction of a second and buys a deterministic order.
+ */
+export interface BrowserLaunchReport {
+  /** Adopt a launch already in flight. Its failure is reported once, when it settles. */
+  track(launch: Promise<OpenUrlResult>): void;
+  /**
+   * Resolves once every launch tracked BEFORE this call has been reported, and immediately when
+   * none was. A login publishes one URL, so "before this call" and "at all" are the same set
+   * here; the narrower promise is the one this actually keeps.
+   */
+  settled(): Promise<void>;
+}
+
+export function createBrowserLaunchReport(
+  warn: (message: string) => void = message => { console.warn(message); },
+): BrowserLaunchReport {
+  let pending: Promise<void> = Promise.resolve();
+  return {
+    track(launch) {
+      pending = pending
+        .then(() => launch)
+        .then(
+          result => {
+            if (result.status !== "started") warn(`\n${BROWSER_LAUNCH_FAILED_NOTICE}`);
+          },
+          // openUrl is documented never to reject, and a launcher that did would mean the same
+          // thing as one that failed. Swallowing it here is not politeness: this chain is what
+          // `settled()` hands to a prompt, so a rejection would propagate out of a login that
+          // is still perfectly able to continue, and would go unhandled in the polling flows
+          // that do not reach that await until minutes later.
+          () => { warn(`\n${BROWSER_LAUNCH_FAILED_NOTICE}`); },
+        );
+    },
+    settled: () => pending,
+  };
+}

package/src/lib/bun-runtime.ts

@@ -14,6 +14,7 @@ import { createRequire } from "node:module";
 import { realpathSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { isRealBunBinary } from "./bun-binary-validator.mjs";
+import { isStandaloneBinary } from "./standalone";
 
 export { isRealBunBinary };
 
@@ -38,10 +39,10 @@ export const BUN_RUNTIME_SOURCE_ENV = "OCX_BUN_RUNTIME_SOURCE";
  */
 export const BUN_RUNTIME_PATH_ENV = "OCX_BUN_RUNTIME_PATH";
 
-export type BunRuntimeSource = "override" | "bundled" | "process";
+export type BunRuntimeSource = "override" | "bundled" | "process" | "standalone";
 
 /** The only provenance values any surface may accept off the wire or out of the env. */
-export const BUN_RUNTIME_SOURCES: readonly BunRuntimeSource[] = ["override", "bundled", "process"];
+export const BUN_RUNTIME_SOURCES: readonly BunRuntimeSource[] = ["override", "bundled", "process", "standalone"];
 
 export type DurableBunRuntime = {
   path: string;
@@ -165,6 +166,9 @@ function unmarkedDurableBunRuntime(): DurableBunRuntime {
 }
 
 export function durableBunRuntime(): DurableBunRuntime {
+  if (isStandaloneBinary()) {
+    return { path: process.execPath, source: "standalone", overrideEnv: BUN_OVERRIDE_ENV };
+  }
   // A durable artifact must use the runtime selected BEFORE Bun auto-loaded a
   // project dotenv. The Node launcher and owned service/shim launchers stamp the
   // selected source/path pair; it is accepted only when it names this exact