@bitkyc08/opencodex 2.59.0 → 2.61.0-preview.20260922

package/src/integrations/writer.ts

@@ -11,12 +11,14 @@
  */
 import { homedir } from "node:os";
 import { createClineIO, ClineTransactionError } from "./cline-io";
-import { parseClineDocument, serializeClineDocument, preserveClineSelection } from "./cline-document";
+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";
 import type { OcxConfig } from "../types";
-import { PARSE_FAILED, defaultIntegrationIO, loadTarget, parseConfig, type IntegrationIO } from "./config-io";
+import { defaultIntegrationIO, loadTarget, type IntegrationIO } from "./config-io";
 import {
   fingerprint,
   canonicalContribution,
@@ -31,11 +33,13 @@ import {
 } from "./ownership-policy";
 import { AmbiguousSelectorError, createdContainerPaths, mergeContribution, removeFragments } from "./merge";
 import { INTEGRATION_CLIENTS, isLoopbackOnly, resolveIntegrationPaths, type IntegrationClientId } from "./registry";
-import { classifyIntegration, exportContextOf } from "./state";
+import { declaredIntegrationTarget } from "./target";
+import { exportContextOf } from "./state";
 import type { IntegrationState } from "./state";
 import { serializeDocument, UnserializableValueError } from "./serialize";
 import { ClientPathError } from "../clients/config-export";
 import { matchesOperationResult, newOpId, type JournalEntry } from "./journal";
+import { observeIntegration, type IntegrationWriteInput, type RefusalReason } from "./mutation-plan";
 import { createIntegrationStateStore, type IntegrationStateStore } from "./store";
 import {
   patchYamlFragmentSource,
@@ -62,14 +66,12 @@ function yamlRefusalReason(
 }
 import { withIntegrationWriterLock, type IntegrationWriterLockSeams } from "./writer-lock";
 
-export type RefusalReason =
-  | "not_installed"
-  | "conflict"
-  | "unsafe"
-  | "non_loopback"
-  | "drift_requires_confirm"
-  | "snapshot_expired"
-  | "write_failed";
+/**
+ * Owned by the planner so a plan can report a refusal without depending on the writer, and
+ * re-exported here because this module was its original home and every caller imports it from
+ * the writer.
+ */
+export type { IntegrationWriteInput, RefusalReason };
 
 export interface WriteOk {
   ok: true;
@@ -94,19 +96,6 @@ export interface WriteRefused {
 
 export type WriteOutcome = WriteOk | WriteRefused;
 
-export interface IntegrationWriteInput {
-  clientId: IntegrationClientId;
-  models: readonly ExportModel[];
-  config: OcxConfig;
-  port: number;
-  env?: NodeJS.ProcessEnv;
-  home?: string;
-  store?: IntegrationStateStore;
-  io?: IntegrationIO;
-  /** Frozen once by the async coordinator; synchronous callers may omit it. */
-  resolvedPaths?: { configPath: string; detectDir: string };
-}
-
 export interface IntegrationRestoreInput extends IntegrationWriteInput {
   opId: string;
   confirmDrift?: boolean;
@@ -227,76 +216,20 @@ function sourcePreservingFragmentValue(
   return fragment?.value;
 }
 
-/** Shared preflight: detect, gate, read, parse and classify. */
+/**
+ * Mutation's view of the shared observation.
+ *
+ * The read, parse and classify live in the planner so a preview and the mutation it authorizes
+ * cannot disagree. Mutation keeps the effects a preview must not have: pending-prune maintenance
+ * and Cline transaction recovery both write. Translating the planner's refusal into WriteRefused
+ * here keeps the planner free of any dependency on this module's result type.
+ */
 function preflight(input: IntegrationWriteInput) {
-  const store = input.store ?? createIntegrationStateStore();
-  let io = input.io ?? defaultIntegrationIO(store);
-  const clientId = input.clientId;
-  const spec = INTEGRATION_CLIENTS[clientId];
-  const exportSpec = EXPORT_CLIENTS[clientId];
-  /*
-   * Resolution itself can refuse: a relative OPENCLAW_* selector is rejected
-   * because we cannot know the gateway's working directory. That is a refusal
-   * about the user's configuration, not an internal fault, so it must not
-   * escape as an exception — the collection route would answer 500 for the
-   * whole Integrations page because one client is misconfigured.
-   */
-  let configPath: string;
-  let detectDir: string;
-  try {
-    /*
-     * Resolve the PAIR, never one half.
-     *
-     * The coordinated path hands us a frozen pair, but applyIntegration,
-     * refreshIntegration and disableIntegration are public and may be called
-     * without one. Resolving configPath here and detectDir separately later let
-     * an Aside account switch land between the two, so a direct apply could
-     * verify account 1 was installed and then write account 0's catalog.
-     */
-    const resolved = input.resolvedPaths ?? resolveIntegrationPaths(clientId, input.env, input.home);
-    configPath = resolved.configPath;
-    detectDir = resolved.detectDir;
-    if (clientId === "cline") io = createClineIO(io, configPath, store, true);
-  } catch (error) {
-    if (error instanceof ClineTransactionError) {
-      return { failed: { ...refuse(clientId, "unsafe", "unsafe", error.message, error.snapshotPath), residual: true } } as const;
-    }
-    if (!(error instanceof ClientPathError)) throw error;
-    return { failed: refuse(clientId, "unsafe", "unsafe", error.message) } as const;
-  }
-  store.retryPendingPrunes();
-
-  const target = loadTarget(io, configPath);
-  if (!target.ok) {
-    return {
-      failed: refuse(clientId, "unsafe", "unsafe",
-        target.why === "read-failed"
-          ? `${configPath} exists but could not be read`
-          : `${configPath} is not a regular file`),
-    } as const;
-  }
-  const before = target.before;
-  const parsed = clientId === "cline" ? parseClineDocument(before) : parseConfig(before, exportSpec.format);
-  if (parsed === PARSE_FAILED) {
-    return { failed: refuse(clientId, "unsafe", "unsafe",
-      `${configPath} could not be parsed, or holds something opencodex cannot rewrite without changing it (a non-finite number, a large integer or a tiny one a rewrite would round, -0, a duplicate member, or nesting deeper than 1000 levels)`) } as const;
-  }
-  const contribution = exportSpec.buildContribution(exportContextOf(input));
-  // A record proves ownership of the file it was written FOR. Matching only by
-  // client id let a record for one home authorize a write to another whose
-  // bytes happened to hash the same — which deleted a config we never touched.
-  const stored = store.readRecords()[clientId] ?? null;
-  const record = stored && stored.clientId === clientId && stored.configPath === configPath
-    ? stored
-    : null;
-  // `configPath`/`clientId` are load-bearing, not decoration: a record proves
-  // ownership of ONE file, and the writer mutates whatever path resolves NOW.
-  // Without them a record written for another home directory would grant
-  // ownership here and disable would delete fragments it never wrote.
-  const classified = classifyIntegration({
-    fileText: before, fileIsRegular: true, parsed, record, contribution, configPath, clientId,
-  });
-  return { failed: undefined, store, io, clientId, spec, exportSpec, configPath, detectDir, before, parsed, contribution, record, classified } as const;
+  const observed = observeIntegration(input, { maintenance: true, recover: true });
+  if (!observed.failed) return observed;
+  const { reason, state, message, snapshotPath, residual } = observed.failed;
+  const refused = refuse(input.clientId, reason, state, message, snapshotPath);
+  return { failed: residual ? { ...refused, residual: true } : refused } as const;
 }
 
 /**
@@ -319,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.
@@ -330,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",
@@ -440,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) {
@@ -528,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" };
@@ -600,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;
@@ -638,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); }
@@ -693,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?
    *
@@ -748,6 +718,15 @@ export function restoreIntegration(input: IntegrationRestoreInput): WriteOutcome
 
 export interface CoordinatedIntegrationOptions {
   lockSeams?: IntegrationWriterLockSeams;
+  /**
+   * Checked after the input is frozen and the writer lock is held, before any side effect.
+   *
+   * A confirmation is a statement about state the operator was shown. Checking it out here, where
+   * the lock already excludes cooperating writers, is what makes it a decision about the same
+   * state the mutation is about to change rather than about state from a moment earlier. A
+   * non-null result refuses without writing anything.
+   */
+  revalidate?: (frozen: IntegrationWriteInput) => Promise<WriteOutcome | null>;
 }
 
 /** Freeze all mutable resolution seams before the first lock await. */
@@ -759,6 +738,16 @@ type FrozenIntegrationInput = IntegrationWriteInput & {
   resolvedPaths: { configPath: string; detectDir: string };
 };
 
+/**
+ * An input this write cannot hold still.
+ *
+ * A coordinated write checks a plan and then writes a document from the same input, with an await
+ * in between. Anything it cannot copy would have to be read from the caller's object twice, and
+ * the second read is not the one that was checked. Refusing is bounded and says so; carrying the
+ * reference and calling it a frozen input would not be.
+ */
+class UncopyableIntegrationInputError extends Error {}
+
 function freezeIntegrationInput(input: IntegrationWriteInput): FrozenIntegrationInput {
   const env = { ...(input.env ?? process.env) };
   const home = input.home ?? homedir();
@@ -773,7 +762,23 @@ function freezeIntegrationInput(input: IntegrationWriteInput): FrozenIntegration
   const resolvedPaths = input.resolvedPaths
     ? { ...input.resolvedPaths }
     : resolveIntegrationPaths(input.clientId, env, home);
-  return { ...input, env, home, store, io, resolvedPaths };
+  /*
+   * The configuration and the roster are seams like the others, and they were the two still held
+   * by reference. A coordinated write plans from this input, awaits the writer lock and a
+   * revalidation, and only then serializes the document from it. A management route editing the
+   * live configuration, or a caller editing the model objects it passed in, would have been
+   * checked in one state and written from another, which is the substitution the fingerprint
+   * exists to prevent. Copying both here gives the plan and the document one input.
+   */
+  const config = detachedConfigSnapshot(input.config);
+  if (config === null) {
+    throw new UncopyableIntegrationInputError("the proxy configuration could not be captured for this write");
+  }
+  const models = copyPlainData(input.models);
+  if (!models.ok) {
+    throw new UncopyableIntegrationInputError("the model roster could not be captured for this write");
+  }
+  return { ...input, config, models: models.value, env, home, store, io, resolvedPaths };
 }
 
 function tryFreezeIntegrationInput(input: IntegrationWriteInput):
@@ -782,6 +787,9 @@ function tryFreezeIntegrationInput(input: IntegrationWriteInput):
   try {
     return { ok: true, value: freezeIntegrationInput(input) };
   } catch (error) {
+    if (error instanceof UncopyableIntegrationInputError) {
+      return { ok: false, refusal: refuse(input.clientId, "unsafe", "unsafe", error.message) };
+    }
     if (!(error instanceof ClientPathError)) throw error;
     return {
       ok: false,
@@ -799,15 +807,22 @@ async function coordinatedWrite(
   if (!prepared.ok) return prepared.refusal;
   const frozen = prepared.value;
   const spec = INTEGRATION_CLIENTS[frozen.clientId];
-  if (!spec.writerLock) return operation(frozen);
+  if (!spec.writerLock) {
+    const refused = await options?.revalidate?.(frozen);
+    return refused ?? operation(frozen);
+  }
 
   // An absent client home is not created merely to acquire a sibling lock.
   if (frozen.io.statKind(frozen.resolvedPaths.detectDir) !== "dir") {
-    return operation(frozen);
+    const refused = await options?.revalidate?.(frozen);
+    return refused ?? operation(frozen);
   }
   return withIntegrationWriterLock(
     frozen.resolvedPaths.configPath,
-    async () => operation(frozen),
+    async () => {
+      const refused = await options?.revalidate?.(frozen);
+      return refused ?? operation(frozen);
+    },
     options?.lockSeams,
     spec.writerLock.suffix,
   );
@@ -849,7 +864,11 @@ export async function restoreIntegrationCoordinated(
   if (!prepared.ok) return prepared.refusal;
   const frozen = prepared.value;
   const spec = INTEGRATION_CLIENTS[frozen.clientId];
-  if (!spec.writerLock) return restoreIntegration({ ...frozen, opId: input.opId, confirmDrift: input.confirmDrift });
+  const run = () => restoreIntegration({ ...frozen, opId: input.opId, confirmDrift: input.confirmDrift });
+  if (!spec.writerLock) {
+    const refused = await options?.revalidate?.(frozen);
+    return refused ?? run();
+  }
   if (frozen.io.statKind(frozen.resolvedPaths.detectDir) !== "dir") {
     return refuse(
       frozen.clientId,
@@ -860,7 +879,12 @@ export async function restoreIntegrationCoordinated(
   }
   return withIntegrationWriterLock(
     frozen.resolvedPaths.configPath,
-    async () => restoreIntegration({ ...frozen, opId: input.opId, confirmDrift: input.confirmDrift }),
+    async () => {
+      // An undo is bound like any other confirmation, and this is the only place where that check
+      // happens with the lock held and before the snapshot, the write and the journal row.
+      const refused = await options?.revalidate?.(frozen);
+      return refused ?? run();
+    },
     options?.lockSeams,
     spec.writerLock.suffix,
   );

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/lab/live/transport.ts

@@ -104,6 +104,10 @@ export function classifyTransportError(error: unknown): { classification: Failur
     case "network_blocked": return { classification: "network_failure", secondaryCode: code };
     case "region_blocked": return { classification: "region_blocked", secondaryCode: code };
     case "provider_transient": return { classification: "provider_transient", secondaryCode: code };
+    // A response this transport cannot read is an upstream protocol failure. It is deterministic
+    // rather than transient, and attributing it to the harness would blame the runner for what
+    // the peer sent.
+    case "unreadable_response": return { classification: "protocol_failure", secondaryCode: code };
     case "connect_timeout": case "first_byte_timeout": case "total_timeout":
       return { classification: "timeout", secondaryCode: code };
     case "inactivity_timeout":

package/src/lab/live/types.ts

@@ -89,6 +89,11 @@ export type TransportErrorCode =
   | "output_byte_limit"
   | "output_token_limit"
   | "tool_call_limit"
+  // The peer answered, and the answer cannot be read: a content coding this transport cannot
+  // undo, or coded bytes that did not decode. Neither is a timeout, a budget, or a fault of
+  // the harness, so none of those codes describes it and every one of them would send an
+  // operator looking in the wrong place.
+  | "unreadable_response"
   | "artifact_byte_limit"
   | "memory_limit"
   | "child_process_limit"

package/src/lab/subject/behavior-fingerprint.ts

@@ -9,7 +9,7 @@ const CLOSED_KEYS = new Set([
   "limits.contextWindow", "limits.maxInputTokens", "limits.maxOutputTokens",
   "modalities.input",
   "sampling.omitTemperature", "sampling.omitTopP", "sampling.omitPenalties",
-  "reasoning.supported", "reasoning.efforts", "reasoning.defaultEffort", "reasoning.effortMap", "reasoning.wireFormat",
+  "reasoning.supported", "reasoning.efforts", "reasoning.effortsAuthoritative", "reasoning.defaultEffort", "reasoning.effortMap", "reasoning.wireFormat",
   "reasoning.summaryMode", "reasoning.replayMode", "reasoning.splitMode", "reasoning.toggleMode", "reasoning.budgetMode",
   "tools.choiceRestrictions", "tools.parallel", "tools.hostedPreference", "tools.customFreeform", "tools.builtinNameEscaping",
   "cache.forwarding", "cache.retention", "anthropic.eofPolicy", "openai-chat.eofPolicy",

package/src/lib/admin-secrets.ts

@@ -1,4 +1,4 @@
-import { timingSafeEqual } from "node:crypto";
+import { createHmac, timingSafeEqual } from "node:crypto";
 import { lstatSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { getConfigDir } from "../config";
@@ -27,6 +27,14 @@ export function configuredAdminToken(configDir = getConfigDir(), env: NodeJS.Pro
 
 export const ADMIN_TOKEN_PREFIX = "ocx_admin_";
 
+/**
+ * Derive the bearer used by the OpenCode launcher for its one management read.
+ * A listener that captures this value cannot recover or replay the administrator token.
+ */
+export function opencodeCatalogToken(adminToken: string): string {
+  return `ocx_catalog_${createHmac("sha256", adminToken).update("opencode:/api/models:v1").digest("base64url")}`;
+}
+
 function secretTextEquals(left: string, right: string): boolean {
   const a = Buffer.from(left);
   const b = Buffer.from(right);

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

package/src/lib/debug-log-buffer.ts

@@ -9,7 +9,12 @@ export interface DebugLogEntry {
 
 const MAX_LINES = 2_000;
 const MAX_DEBUG_SUBSCRIBERS = 64;
-const MAX_DEBUG_LINE_BYTES = 16 * 1024;
+/**
+ * Per-line retention cap. Exported because a producer of a long structured line has to budget
+ * BELOW it: this buffer truncates at a byte boundary, so a JSON line cut here stops being
+ * parseable while its retained prefix still reads as complete.
+ */
+export const MAX_DEBUG_LINE_BYTES = 16 * 1024;
 const buffer: DebugLogEntry[] = [];
 interface DebugSubscriberRegistration { lease: AdmissionLease }
 const listeners = new Map<(entry: DebugLogEntry) => void, DebugSubscriberRegistration>();

package/src/lib/debug.ts

@@ -29,3 +29,66 @@ export function debugProviderDiagnostic(adapter: string, event: string, details:
     /* diagnostics must never affect request handling */
   }
 }
+
+/**
+ * The same diagnostic for details that are expensive to compute or read live request state.
+ *
+ * The eager form takes an already-built object, so the build runs in ARGUMENT position: outside
+ * this module's gate, and outside its try/catch. For a projection that walks a whole request
+ * that is wrong twice over — it pays the walk while debug is off, and a throw inside it reaches
+ * the caller, which for an adapter means a built request becomes a rejected one and a send that
+ * would have happened does not. Pass the builder instead: it runs only when debug is on, and a
+ * throw inside it is swallowed exactly like a throw in the emit.
+ */
+export function debugProviderDiagnosticLazy(
+  adapter: string,
+  event: string,
+  details: () => Record<string, unknown>,
+): void {
+  if (!isDebugEnabled()) return;
+  try {
+    emitDebugLine(`[ocx:${adapter}:${event}] ${JSON.stringify(redactSecrets(details()))}`);
+  } catch {
+    /* diagnostics must never affect request handling */
+  }
+}
+
+/**
+ * One line per finalized attempt, formatted from what the recorder already counted.
+ *
+ * #3983 wanted this visibility and emitted a line per stream event to get it. Two things made
+ * that the wrong shape. It is a second record: `emitDebugLine` writes the ring AND stderr, and
+ * a service manager redirects stderr to a file, so an installed service accumulates a per-event
+ * history beside the ledger with its own retention and sequencing. And per-event lines needed a
+ * per-payload fingerprint to correlate, which under a process-global key makes every repeated
+ * prompt fragment and tool name correlatable for the life of the process.
+ *
+ * So this writes the ring ONLY -- `appendDebugLogLine` directly, never `emitDebugLine` -- and
+ * says nothing the ledger does not already hold. The ring becomes a live view of the durable
+ * record rather than a parallel source for it.
+ */
+export function debugAttemptDeliverySummary(
+  requestId: string,
+  attempt: {
+    ordinal: number;
+    adapter: string;
+    deliverySummary?: {
+      adapterEvents: number;
+      relayedEvents: number;
+      semanticBytes: number;
+      sideEffectEvents: number;
+      terminalEvents: number;
+    };
+  },
+): void {
+  if (!isDebugEnabled() || !attempt.deliverySummary) return;
+  try {
+    appendDebugLogLine(`[ocx:${attempt.adapter}:delivery] ${JSON.stringify({
+      requestId,
+      ordinal: attempt.ordinal,
+      ...attempt.deliverySummary,
+    })}`);
+  } catch {
+    /* diagnostics must never affect request handling */
+  }
+}