@bitkyc08/opencodex 2.81.0 → 2.83.0

package/src/server/responses/sidecar-execution.ts

@@ -48,6 +48,7 @@ import { normalizeLogConversationId } from "../request-log-conversation";
 import { rememberResponseState } from "../../responses/state";
 import { trackStreamLifetime } from "../lifecycle";
 import { isAntigravityRawValidationRefusal } from "./antigravity-validation-refusal";
+import { createSidecarSendBudget } from "./sidecar-send-budget";
 
 /** One responsibility of the Responses request pipeline; state owners are explicit. */
 export async function executeResponsesSidecars(
@@ -78,6 +79,7 @@ export async function executeResponsesSidecars(
     | "anthropicSessionKey"
     | "commitResolvedOAuthSelection"
     | "resolveSelectionAdapter"
+    | "resolveCopilotSelection"
     | "oauthDispatch"
     | "noteRoutedAttemptSend"
     | "bindKeyUsageFromBridge"
@@ -90,7 +92,7 @@ export async function executeResponsesSidecars(
     | "notifyResponseComplete"
     | "cancelResponseCompletion"
   >,
-  sendBudgetState: Pick<ResponsesSendBudget, "reserveCredentialHop" | "refundableAdapterDispatchBudget" | "pendingHopPermit" | "noteAdapterPhysicalSend">,
+  sendBudgetState: Pick<ResponsesSendBudget, "reserveCredentialHop" | "refundableAdapterDispatchBudget" | "adapterDispatchBudget" | "noteInitialDispatch" | "noteAdapterPhysicalSend" | "noteAdapterRecoveryWithheld" | "pendingHopPermit">,
 ) {
   const { config, options, logCtx } = requestContext;
   const antigravityPoolActivated = requestState.route.providerName === "google-antigravity"
@@ -102,6 +104,7 @@ export async function executeResponsesSidecars(
     anthropicSessionKey,
     commitResolvedOAuthSelection,
     resolveSelectionAdapter,
+    resolveCopilotSelection,
     oauthDispatch,
   } = transportState;
   const {
@@ -114,6 +117,7 @@ export async function executeResponsesSidecars(
   } = requestState;
   const { routedCompaction, openAiSidecar } = sidecarState;
   const { reserveCredentialHop } = sendBudgetState;
+  const sidecarBudget = createSidecarSendBudget(options, sendBudgetState, () => logCtx.usageLogInputTokens);
   const {
     commitReasoningReplayServingRoute,
     continuationStateForResponse,
@@ -194,6 +198,7 @@ export async function executeResponsesSidecars(
   // A single request may rotate once for a verification refusal. Keep this separate from the
   // broader OAuth failover count: a sidecar turn can also spend that count on rate-limit recovery.
   let antigravityValidationRotationAttempted = false;
+  /** Admit a replacement credential, or leave the loop's original refusal authoritative. */
   const rotateSidecarProviderOn429 = async (
     retryAfter: string | null,
     responseHeaders?: Headers,
@@ -202,7 +207,7 @@ export async function executeResponsesSidecars(
   ): Promise<{ adapter: ProviderAdapter; recoveryKind: AttemptRecoveryKind } | null> => {
     const antigravityValidationResponse = canRunWebSearch && route.providerName === "google-antigravity"
       && route.provider.authMode === "oauth" && originalResponse?.status === 403;
-    if (route.providerName !== "kiro" && !(anthropicInstance && originalResponse?.status === 403)
+    if (route.providerName !== "kiro" && !(anthropicInstance && (originalResponse?.status === 403 || originalResponse?.status === 401))
       && !antigravityValidationResponse && originalResponse && originalResponse.status !== 429) return null;
     let antigravityVerification = false;
     if (antigravityValidationResponse) {
@@ -264,7 +269,8 @@ export async function executeResponsesSidecars(
         return null;
       }
       recoveryKind = "oauth-account-403";
-      sendBudgetState.pendingHopPermit = hop.permit;
+      if (!options.comboInitialSend) sendBudgetState.pendingHopPermit = hop.permit;
+      else sidecarBudget.ownCredentialHop(hop.permit);
     }
     const rotated = !originalResponse || originalResponse.status === 429
       ? rotateProviderTransportOn429(config, route.providerName, route.provider, {
@@ -277,6 +283,8 @@ export async function executeResponsesSidecars(
       // `applyFailoverSnapshot` has already rebound the route to the sibling identity/project.
     } else if (rotated) {
       route.provider = rotated;
+      try { await resolveCopilotSelection(retryParsed ?? parsed); }
+      catch { return null; } // Keep the sidecar's original refusal when replacement negotiation fails.
     } else if (
       // A POSITIVE gate, not an early return. An early `return null` here made every later arm
       // unreachable: Anthropic never has a genericFailoverAccountId (isGenericFailoverProvider
@@ -323,8 +331,9 @@ export async function executeResponsesSidecars(
         return null;
       }
       recoveryKind = "oauth-account-429";
-      if (canRunWebSearch && route.providerName === "google-antigravity") sendBudgetState.pendingHopPermit = hop.permit;
-      else hop.permit?.use();
+      if (!options.comboInitialSend && canRunWebSearch && route.providerName === "google-antigravity")
+        sendBudgetState.pendingHopPermit = hop.permit;
+      else sidecarBudget.ownCredentialHop(hop.permit);
     } else if (
       // Anthropic's pool is excluded from generic failover, so without this arm a 429 inside a
       // web-search or image-bridge turn was terminal even with the pool fully enabled -- while
@@ -364,8 +373,8 @@ export async function executeResponsesSidecars(
         hop.permit?.release();
         return null;
       }
-      recoveryKind = "anthropic-oauth-429";
-      hop.permit?.use();
+      recoveryKind = originalResponse?.status === 401 ? "oauth-401" : "anthropic-oauth-429";
+      sidecarBudget.ownCredentialHop(hop.permit);
     } else {
       // No key pool, no generic OAuth roster, no Anthropic pool could produce a replacement
       // credential. The 429 is terminal for this sidecar turn.
@@ -451,11 +460,14 @@ export async function executeResponsesSidecars(
     const imageProviderFetch = providerFetch(
       route.provider,
       options.codexWsRuntimeIdentity,
-      { providerName: route.providerName, modelId: route.modelId },
+      { providerName: route.providerName, modelId: route.modelId, ...sidecarBudget.fetchOptions(transportState.adapter) },
     );
     const imgResponse = await runWithImageBridge({
       parsed, adapter: transportState.adapter,
-      incomingMeta: { headers: requestState.selectedForwardHeaders, providerName: route.providerName, abortSignal: options.abortSignal, translatorBudget },
+      incomingMeta: { headers: requestState.selectedForwardHeaders, providerName: route.providerName, abortSignal: options.abortSignal, translatorBudget, ...(options.comboInitialSend ? { providerFetch: imageProviderFetch } : {}), ...sidecarBudget.incomingMeta },
+      onProducerStart: sidecarBudget.takeProducerOwnership,
+      onProducerEnd: sidecarBudget.release,
+      onIterationEnd: sidecarBudget.releaseUnsentHop,
       ...(imgPlan ? { plan: imgPlan } : {}),
       ...(vidPlan ? { videoPlan: vidPlan } : {}),
       forwardHeaders: requestState.selectedForwardHeaders,
@@ -471,10 +483,10 @@ export async function executeResponsesSidecars(
       stallTimeoutSec: config.stallTimeoutSec,
       waitForRequestSlot: imageProviderFetch.waitForPacing,
       fetchImpl: imageProviderFetch.unpacedFetch ?? imageProviderFetch,
-      fetchForRequest: (request, iterParsed) => {
+      fetchForRequest: (request, iterParsed, adapter) => {
         const fetch = providerFetch(route.provider, options.codexWsRuntimeIdentity, {
           dispatchOverride: oauthDispatch(request, iterParsed),
-          providerName: route.providerName, modelId: route.modelId,
+          providerName: route.providerName, modelId: route.modelId, ...sidecarBudget.fetchOptions(adapter),
         });
         return fetch.unpacedFetch ?? fetch;
       },
@@ -541,12 +553,14 @@ export async function executeResponsesSidecars(
       providerFetch(route.provider, options.codexWsRuntimeIdentity, {
         providerName: route.providerName,
         modelId: route.modelId,
+        ...sidecarBudget.fetchOptions(transportState.adapter),
       })(input, init)) as typeof globalThis.fetch;
     const wsResponse = await runWithWebSearch({
       parsed, adapter: transportState.adapter,
-      fetchForRequest: (request, iterParsed) => providerFetch(route.provider, options.codexWsRuntimeIdentity, {
+      onIterationEnd: sidecarBudget.releaseUnsentHop,
+      fetchForRequest: (request, iterParsed, adapter) => providerFetch(route.provider, options.codexWsRuntimeIdentity, {
         dispatchOverride: oauthDispatch(request, iterParsed),
-        providerName: route.providerName, modelId: route.modelId,
+        providerName: route.providerName, modelId: route.modelId, ...sidecarBudget.fetchOptions(adapter),
       }),
       incomingMeta: {
         headers: requestState.selectedForwardHeaders,
@@ -554,11 +568,11 @@ export async function executeResponsesSidecars(
         abortSignal: options.abortSignal,
         translatorBudget,
         providerFetch: routedProviderFetch,
-        ...(route.providerName === "google-antigravity" ? {
+        ...(!options.comboInitialSend && route.providerName === "google-antigravity" ? {
           sendBudget: sendBudgetState.refundableAdapterDispatchBudget,
           onPhysicalSend: (send: { ordinal: number; recovery?: AttemptRecoveryKind }) =>
             sendBudgetState.noteAdapterPhysicalSend(logCtx.usageLogInputTokens, send),
-        } : {}),
+        } : sidecarBudget.incomingMeta),
       },
       backend: wsPlan.backend,
       forwardProvider: wsPlan.forwardSidecar?.provider,
@@ -591,7 +605,7 @@ export async function executeResponsesSidecars(
       stallTimeoutSec: wsPlan.stallTimeoutSec,
       streamRoutedModelOutput: wsPlan.streamRoutedModelOutput,
       on429: rotateSidecarProviderOn429,
-      ...(route.providerName === "google-antigravity" ? { onIterationEnd: () => {
+      ...(!options.comboInitialSend && route.providerName === "google-antigravity" ? { onIterationEnd: () => {
         // The next Antigravity adapter dispatch claims this permit. If request construction,
         // admission or cancellation stopped it first, return the unused send allowance.
         const permit = sendBudgetState.pendingHopPermit;

package/src/server/responses/sidecar-send-budget.ts

@@ -0,0 +1,58 @@
+import type { IncomingMeta, ProviderAdapter } from "../../adapters/base";
+import type { HandleResponsesOptions } from "./core-options";
+import type { ResponsesSendBudget } from "./request-send-budget";
+import type { ProviderFetchOptions } from "./fetch-helpers";
+import type { SingleUseDispatchPermit } from "../../lib/request-execution-budget";
+
+/** Hosted inference consumes the same child-owned booking as ordinary dispatch. */
+export function createSidecarSendBudget(
+  options: HandleResponsesOptions,
+  budget: Pick<ResponsesSendBudget, "adapterDispatchBudget" | "noteInitialDispatch" | "noteAdapterPhysicalSend" | "noteAdapterRecoveryWithheld" | "pendingHopPermit">,
+  inputTokens: () => number | undefined,
+) {
+  const initial = options.comboInitialSend;
+  let hopPermit: SingleUseDispatchPermit | undefined;
+  let producerActive = false;
+  /** Detach this owner’s hop before refunding its still-unused reservation. */
+  const releaseHop = (): void => {
+    const permit = hopPermit;
+    hopPermit = undefined;
+    if (budget.pendingHopPermit === permit) budget.pendingHopPermit = undefined;
+    permit?.release();
+  };
+  return {
+    /** Retain a Combo hop until dispatch; direct requests keep eager settlement. */
+    ownCredentialHop(permit?: SingleUseDispatchPermit): void {
+      if (!initial) { permit?.use(); return; } // Preserve direct callers' reporting contract.
+      releaseHop();
+      hopPermit = permit;
+      budget.pendingHopPermit = permit;
+    },
+    // Adapter-owned transports settle through the live dispatch view, not an HTTP receipt too.
+    incomingMeta: initial ? {
+      comboAttempt: options.comboAttempt === true,
+      sendBudget: budget.adapterDispatchBudget,
+      onPhysicalSend: send => budget.noteAdapterPhysicalSend(inputTokens(), send),
+      onRecoveryWithheld: budget.noteAdapterRecoveryWithheld,
+    } satisfies Partial<IncomingMeta> : {},
+    /** Attach HTTP receipts only when the adapter does not own physical dispatch. */
+    fetchOptions(adapter: ProviderAdapter): Pick<ProviderFetchOptions, "onPhysicalDispatch"> {
+      return initial && !adapter.fetchResponse && !adapter.runTurn
+        ? { onPhysicalDispatch: () => {
+          const prepaid = budget.pendingHopPermit;
+          budget.pendingHopPermit = undefined;
+          budget.noteInitialDispatch(prepaid);
+        } } : {};
+    },
+    /** Transfer cleanup to the asynchronous producer before it can outlive the response. */
+    takeProducerOwnership(): void {
+      if (initial) { initial.producerOwned = true; producerActive = true; }
+    },
+    /** Release unused bookings only after the owning producer has settled. */
+    release(): void {
+      initial?.permit.release(); producerActive = false; releaseHop();
+    },
+    /** An iteration may finish before runTurn; defer its refund while that producer is active. */
+    releaseUnsentHop(): void { if (!producerActive) releaseHop(); },
+  };
+}

package/src/server/responses/spend-storage-error.ts

@@ -0,0 +1,33 @@
+import { formatErrorResponse } from "../../bridge";
+import { SPEND_LEDGER_STORAGE_UNAVAILABLE_CODE } from "../../lib/errors";
+import { markLocalRequestLogRefusal, type RequestLogContext } from "../request-log";
+import { SpendLedgerFileRefusedError } from "../../lib/spend-reservation-ledger";
+
+type StorageRefusalLog = Pick<RequestLogContext, "localTerminalReason" | "terminalSource" | "errorCode">;
+
+/** Local storage refusal, including retry wrappers: never provider-health evidence. */
+export function mapSpendLedgerStorageError(error: unknown, logCtx?: StorageRefusalLog) {
+  const seen = new Set<unknown>();
+  while (error instanceof Error && !seen.has(error)) {
+    if (error instanceof SpendLedgerFileRefusedError) {
+      if (logCtx) {
+        markLocalRequestLogRefusal(logCtx, SPEND_LEDGER_STORAGE_UNAVAILABLE_CODE);
+        logCtx.errorCode = SPEND_LEDGER_STORAGE_UNAVAILABLE_CODE;
+      }
+      return {
+        status: 503,
+        errorType: "server_error",
+        code: SPEND_LEDGER_STORAGE_UNAVAILABLE_CODE,
+        message: error.message,
+      } as const;
+    }
+    seen.add(error);
+    error = error.cause;
+  }
+  return undefined;
+}
+
+export function spendLedgerStorageErrorResponse(error: unknown, logCtx?: StorageRefusalLog): Response | undefined {
+  const refusal = mapSpendLedgerStorageError(error, logCtx);
+  return refusal && formatErrorResponse(refusal.status, refusal.code, refusal.message);
+}

package/src/server/responses/ws-upstream.ts

@@ -15,6 +15,7 @@ import type { NativeResponseControl } from "./native-response-control";
 // returned event frames as an SSE byte stream, so every downstream consumer
 // (passthrough relay, adapter parsers, usage sniffing) is unchanged.
 
+import { codexWsReuseAcrossTurnsEnabled } from "../../config/codex-ws-reuse-setting";
 import { compareBunVersions } from "../../lib/bun-stream-caps";
 import { resolveProxyRoute, socks5ProxyFromEnv } from "../../lib/proxy-env";
 import type { CodexWsQuotaObserver } from "./codex-ws-metadata";
@@ -26,7 +27,7 @@ import { codexWsCreateFrameExceedsLimit } from "./codex-ws-wire";
 import { isLoopbackUrl, rewriteWebSocketDial } from "../../plugins/upstream-hooks";
 export { CODEX_WS_LIVENESS_PING_INTERVAL_MS, CODEX_WS_RESPONSE_PRELUDE_TIMEOUT_MS, MAX_CODEX_WS_FRAME_BYTES, MAX_CODEX_WS_QUEUE_BYTES,
   MAX_CODEX_WS_CREATE_FRAME_BYTES, CODEX_WS_CREATE_FRAME_LIMIT_BYTES, codexWsCreateFrameExceedsLimit,
-  isCodexWsQuotaObservedResponse, isCodexWsUpstreamResponse } from "./codex-ws-wire";
+  isCodexWsQuotaObservedResponse, isCodexWsUpstreamResponse, isCodexWsPreludeProjection } from "./codex-ws-wire";
 export const MIN_BOUNDED_CODEX_WS_BUN_VERSION = "1.4.0";
 
 /**
@@ -99,8 +100,10 @@ export function planCodexWsDial(
   // and is authoritative; a pooled socket's upgrade copy is intentionally ignored. A rewriter
   // therefore cannot change them here, and the upgrade keeps the values the frame carries.
   const dialHeaders = { ...rewritten.headers };
+  const reuseAcrossTurns = codexWsReuseAcrossTurnsEnabled();
   for (const name of CODEX_WS_FRAME_HEADERS) {
-    if (Object.hasOwn(headers, name)) dialHeaders[name] = headers[name]!;
+    if (reuseAcrossTurns) delete dialHeaders[name];
+    else if (Object.hasOwn(headers, name)) dialHeaders[name] = headers[name]!;
     else delete dialHeaders[name];
   }
   const dial = { ...rewritten, headers: dialHeaders };
@@ -148,7 +151,8 @@ export function shouldUseCodexWsUpstream(
   }
 }
 
-export function codexWsUpstreamFetch(
+/** Select the bounded WS lane or HTTP fallback, forwarding receipts at physical dispatch. */
+export async function codexWsUpstreamFetch(
   url: string,
   init: RequestInit,
   sseFallback: typeof globalThis.fetch,
@@ -157,6 +161,7 @@ export function codexWsUpstreamFetch(
   beforeDispatch?: (headers: Headers) => void,
   nativeControl?: NativeResponseControl,
   beforeContinuation?: () => Promise<void>,
+  onPhysicalDispatch?: () => void,
 ): Promise<Response> {
   const prepared = prepareCodexWsRequest(url, init);
   if (!prepared) return sseFallback(url, prepareCodexHttpInit(url, init));
@@ -217,8 +222,16 @@ export function codexWsUpstreamFetch(
     const dial = planCodexWsDial(wsUrl, headers, proxy);
     if (!dial) return sseFallback(url, init);
     const identity = control ? null : codexWsReuseIdentity(url, dial.headers, frameText, dial.proxy, dial.url);
-    session = (identity ? codexWsPool.acquire(identity, dial.url, dial.headers, dial.proxy) : null)
-      ?? new CodexWsSession(dial.url, dial.headers, false, undefined, dial.proxy);
+    const reuseAcrossTurns = identity !== null && codexWsReuseAcrossTurnsEnabled();
+    const pooled = identity
+      ? reuseAcrossTurns
+        ? await codexWsPool.acquireWaiting(identity, dial.url, dial.headers, dial.proxy, signal)
+        : codexWsPool.acquire(identity, dial.url, dial.headers, dial.proxy)
+      : null;
+    if (reuseAcrossTurns && signal?.aborted) {
+      return Promise.reject(signal.reason ?? new DOMException("The operation was aborted.", "AbortError"));
+    }
+    session = pooled ?? new CodexWsSession(dial.url, dial.headers, false, undefined, dial.proxy);
     if (!session.busy && !session.reserve()) {
       session.dispose();
       return sseFallback(url, init);
@@ -229,7 +242,7 @@ export function codexWsUpstreamFetch(
   return codexWsExchange({
     session, url, init, prepared, sseFallback, onQuota, beforeDispatch,
     nativeControl: control,
-    beforeContinuation,
+    beforeContinuation, onPhysicalDispatch,
     bunVersion: typeof runtime === "string" ? runtime : runtime.version,
   });
 }

package/src/server/startup-health-cache.ts

@@ -88,7 +88,8 @@ export function markStartupHealthDiagnosticStale(value: StartupHealth): StartupH
     // Mirror deriveStartupHealth's choice: an already-registered service is refreshed in
     // place. Hardcoding installService here silently undid that for every stale-cache
     // read, which is the path the dashboard hits while a probe is revalidating.
-    recommendedCommand: value.routingKind === "opencodex-local" && value.desktop?.owned
+    recommendedAction: value.desktop ? "Reopen OpenCodex and check Start at Login." : value.recommendedAction,
+    recommendedCommand: value.routingKind === "opencodex-local" && value.desktop !== undefined
       ? null
       : value.routingKind === "custom-local" || value.routingKind === "unknown"
       ? value.commands.restoreNative

package/src/server/workflow-refusal.ts

@@ -41,6 +41,8 @@ export interface WorkflowRefusalLog {
   readonly requestId: string;
   readonly start: number;
   readonly logCtx: RequestLogContext;
+  /** Receiving HTTP route's notification after this refusal's final-log call. */
+  readonly onLogged?: () => void;
 }
 
 /**
@@ -84,6 +86,7 @@ export function workflowRefusalResponse(
     addFinalRequestLog(refusalLog.requestId, refusalLog.start, refusalLog.logCtx, 429, {
       closeReason: "terminal",
     });
+    refusalLog.onLogged?.();
   }
   const refusal = formatErrorResponse(
     429,

package/src/service/cli.ts

@@ -26,6 +26,7 @@ import type { WindowsSchedulerTaskProbe } from "./windows-scheduler";
 import { win32 } from "node:path";
 import { serviceDiagnosticsSummary } from "./diagnostics";
 import { runServiceClaim } from "./claim";
+import { createSupervisionLatch, desktopServiceCommandRefusal } from "./desktop-command-guard";
 
 /**
  * `restart` is NO LONGER folded into `repair`.
@@ -214,6 +215,7 @@ export function removeServiceTokenAfterUninstall(
 /** Execute a service verb while preserving client-owned credentials during uninstall. */
 export async function serviceCommand(...args: (string | undefined)[]): Promise<void> {
   const filteredArgs = args.filter((a): a is string => Boolean(a));
+  const supervisionLatch = createSupervisionLatch();
   const execute = async (): Promise<void> => {
     // `claim` is not an install verb: it is deliberately outside planServiceCommand (whose
     // backend/installation checks do not apply to an ownership write) and outside
@@ -231,6 +233,12 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
       process.exit(1);
     }
     const { parsed, command } = plan;
+    const refusal = desktopServiceCommandRefusal(command, undefined, supervisionLatch);
+    if (refusal) {
+      console.error(refusal);
+      process.exitCode = 1;
+      return;
+    }
   if (command === "repair" || command === "restart") {
     const verb: ServiceRepairVerb = command === "restart" ? "restart" : "repair";
     assertServiceEnvironmentMatchesInstall();
@@ -249,7 +257,7 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
     // existing registration had been restarted, not repaired (#4914).
     let repairError: unknown;
     try {
-      await repairService({ verb });
+      await repairService({ verb, supervisionLatch });
     } catch (error) {
       repairError = error;
       process.exitCode = 1;
@@ -295,12 +303,12 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
             throw new Error(`Task Scheduler state could not be verified before install: ${scheduler.detail}`);
           }
           if (scheduler.status === "absent") {
-            await installFreshWindowsSchedulerSafely();
+            await installFreshWindowsSchedulerSafely({ supervisionLatch });
           } else {
-            await installServiceSafely(backend, ops.install);
+            await installServiceSafely(backend, ops.install, { supervisionLatch });
           }
         } else {
-          await installServiceSafely(backend, ops.install);
+          await installServiceSafely(backend, ops.install, { supervisionLatch });
         }
       } catch (error) {
         console.error(`❌ Service install cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
@@ -474,6 +482,14 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
   };
 
   const preliminary = parseServiceArgs(filteredArgs);
+  if (preliminary.invalid.length === 0) {
+    const refusal = desktopServiceCommandRefusal(preliminary.sub, undefined, supervisionLatch);
+    if (refusal) {
+      console.error(refusal);
+      process.exitCode = 1;
+      return;
+    }
+  }
   const windowsMutation = process.platform === "win32"
     && preliminary.invalid.length === 0
     && preliminary.sub !== "status";

package/src/service/desktop-command-guard.ts

@@ -0,0 +1,32 @@
+import { createSupervisionLatch, inspectDesktopSupervision } from "./desktop-supervision.mjs";
+
+export { createSupervisionLatch };
+export type DesktopSupervision = ReturnType<typeof inspectDesktopSupervision>;
+export type SupervisionInspector = (deps?: Parameters<typeof inspectDesktopSupervision>[0]) => DesktopSupervision;
+export type SupervisionLatch = ReturnType<typeof createSupervisionLatch>;
+
+export function desktopServiceRefusal(evidence: DesktopSupervision, blocked: boolean): string | null {
+  if (!blocked) return null;
+  const runtime = evidence.kind === "desktop" ? ` (pid ${evidence.runtimePid}, ${evidence.app})` : "";
+  return `OpenCodex Desktop supervises the running proxy${runtime}. `
+    + "Quit OpenCodex, then rerun 'ocx service install' to move startup management to this CLI.";
+}
+
+export function assertNoDesktopSupervision(
+  inspect: SupervisionInspector = inspectDesktopSupervision,
+  latch: SupervisionLatch = createSupervisionLatch(),
+): void {
+  const evidence = inspect();
+  const refusal = desktopServiceRefusal(evidence, latch.observe(evidence));
+  if (refusal) throw new Error(refusal);
+}
+
+export function desktopServiceCommandRefusal(
+  command: string,
+  inspect: SupervisionInspector = inspectDesktopSupervision,
+  latch: SupervisionLatch = createSupervisionLatch(),
+): string | null {
+  if (!["install", "repair", "start", "restart"].includes(command)) return null;
+  const evidence = inspect();
+  return desktopServiceRefusal(evidence, latch.observe(evidence));
+}

package/src/service/desktop-startup.ts

@@ -1,9 +1,10 @@
 import { execFileSync } from "node:child_process";
-import { accessSync, constants, readFileSync, readlinkSync, realpathSync } from "node:fs";
+import { accessSync, constants, readFileSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { readPid } from "../config/process-state";
 import { resolveServiceOwnership, sameServiceOwnershipSubject, type ServiceOwnershipResolution } from "./state";
+import { inspectDesktopSupervision, processIdentity, procfs, type ProcReader } from "./desktop-supervision.mjs";
 
 export interface DesktopStartupDiagnostic {
   /** Durable desktop claim; failed supervision does not release ownership. */
@@ -11,11 +12,13 @@ export interface DesktopStartupDiagnostic {
   loginEnabled: boolean;
   running: boolean;
   viable: boolean;
+  /** Live parentage when no durable claim exists; never converts supervision into ownership. */
+  supervisor?: { supervisorPid: number; runtimePid: number; app: string };
 }
 
-/** A login item alone is insufficient: the same app must own and supervise this proxy. */
+/** A login item alone is insufficient: the same app must supervise this proxy. */
 export function deriveDesktopStartup(facts: Omit<DesktopStartupDiagnostic, "viable">): DesktopStartupDiagnostic {
-  return { ...facts, viable: facts.owned && facts.loginEnabled && facts.running };
+  return { ...facts, viable: (facts.owned || facts.supervisor !== undefined) && facts.loginEnabled && facts.running };
 }
 
 function run(command: string, args: string[]): string {
@@ -28,25 +31,12 @@ interface DesktopStartupDeps {
   uid?: number;
   ownership?: () => ServiceOwnershipResolution;
   readPid?: () => number | null;
+  readRuntimePortPid?: () => number | null;
   run?: typeof run;
   env?: NodeJS.ProcessEnv;
   proc?: ProcReader;
 }
 
-/** Linux process identity from procfs: executable target and parent pid. */
-interface ProcReader {
-  exe(pid: number): string;
-  parent(pid: number): number;
-}
-const procfs: ProcReader = {
-  exe: pid => readlinkSync(`/proc/${pid}/exe`),
-  // comm may contain spaces or parentheses, so fields are counted after the last ')'.
-  parent: pid => {
-    const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
-    return Number(stat.slice(stat.lastIndexOf(")") + 2).split(" ")[1]);
-  },
-};
-
 /** Cheap ownership-only snapshot: no launchd/process probes on the server request path. */
 export function desktopStartupOwnership(deps: DesktopStartupDeps = {}): DesktopStartupDiagnostic | undefined {
   const platform = deps.platform ?? process.platform;
@@ -56,9 +46,47 @@ export function desktopStartupOwnership(deps: DesktopStartupDeps = {}): DesktopS
     ? deriveDesktopStartup({ owned: true, loginEnabled: false, running: false }) : undefined;
 }
 
-function processIdentity(pid: number, execute: typeof run): { parent: number; executable: string } | null {
-  const row = /^(\d+)\s+(.+)$/.exec(execute("/bin/ps", ["-p", String(pid), "-o", "ppid=,comm="]));
-  return row ? { parent: Number(row[1]), executable: realpathSync(row[2]!) } : null;
+function macLoginRegistration(deps: DesktopStartupDeps) {
+  const execute = deps.run ?? run;
+  const path = join(deps.home ?? homedir(), "Library", "LaunchAgents", "OpenCodex.plist");
+  const plist = JSON.parse(execute("/usr/bin/plutil", ["-convert", "json", "-o", "-", path]));
+  const args = plist.ProgramArguments;
+  if (plist.Label !== "OpenCodex" || plist.RunAtLoad !== true || !Array.isArray(args)
+    || args.length !== 2 || args[1] !== "--autostart" || typeof args[0] !== "string"
+    || !args[0].endsWith("/Contents/MacOS/opencodex-desktop")
+    || (plist.Program !== undefined && plist.Program !== args[0])) return null;
+  const app = realpathSync(args[0]);
+  const proxy = realpathSync(join(dirname(app), "ocx"));
+  accessSync(app, constants.X_OK);
+  accessSync(proxy, constants.X_OK);
+  const domain = `gui/${deps.uid ?? process.getuid!()}`;
+  const disabled = execute("/bin/launchctl", ["print-disabled", domain]);
+  const loaded = execute("/bin/launchctl", ["print", `${domain}/OpenCodex`]);
+  const program = /^\s*program = (.+)$/m.exec(loaded)?.[1];
+  const loadedPath = /^\s*path = (.+)$/m.exec(loaded)?.[1];
+  const loginEnabled = /^\s*disabled services = \{[\s\S]*\}\s*$/.test(disabled)
+    && !/"OpenCodex"\s*=>\s*(?:disabled|true)/.test(disabled)
+    && program !== undefined && realpathSync(program) === app
+    && loadedPath !== undefined && realpathSync(loadedPath) === realpathSync(path);
+  return { app, proxy, loginEnabled };
+}
+
+function diagnoseSupervisedStartup(deps: DesktopStartupDeps, ownerRevision: number, loginFor: (app: string) => boolean): DesktopStartupDiagnostic | undefined {
+  const evidence = inspectDesktopSupervision(deps);
+  if (evidence.kind !== "desktop") return undefined;
+  let loginEnabled = false;
+  try { loginEnabled = loginFor(evidence.app); }
+  catch { /* Login failure revokes restart viability, not the observed live supervisor. */ }
+  if ((deps.ownership ?? resolveServiceOwnership)().kind !== "none") return undefined;
+  // Login probes can outlive the runtime or its parent; only the same live chain gets credit.
+  const final = inspectDesktopSupervision({ ...deps, targetPid: evidence.runtimePid });
+  if (final.kind !== "desktop" || final.runtimePid !== evidence.runtimePid
+    || final.supervisorPid !== evidence.supervisorPid || final.app !== evidence.app) return undefined;
+  // A new claim or revision during the last process probe invalidates the unowned projection.
+  const finalOwner = (deps.ownership ?? resolveServiceOwnership)();
+  if (finalOwner.kind !== "none" || finalOwner.revision !== ownerRevision) return undefined;
+  const { supervisorPid, runtimePid, app } = evidence;
+  return deriveDesktopStartup({ owned: false, loginEnabled, running: true, supervisor: { supervisorPid, runtimePid, app } });
 }
 
 /** Read-only macOS desktop ownership, login registration and live parent/child checks. */
@@ -66,6 +94,10 @@ export function diagnoseMacDesktopStartup(deps: DesktopStartupDeps = {}): Deskto
   if ((deps.platform ?? process.platform) !== "darwin") return undefined;
   const ownership = deps.ownership ?? resolveServiceOwnership;
   const owner = ownership();
+  if (owner.kind === "none") return diagnoseSupervisedStartup(deps, owner.revision, app => {
+    const login = macLoginRegistration(deps);
+    return login !== null && login.app === app && login.loginEnabled;
+  });
   if (owner.kind !== "owned" || owner.ownership.owner !== "desktop") return undefined;
   const facts = { owned: true, loginEnabled: false, running: false };
   const execute = deps.run ?? run;
@@ -74,26 +106,10 @@ export function diagnoseMacDesktopStartup(deps: DesktopStartupDeps = {}): Deskto
     const home = deps.home ?? homedir();
     const id = readFileSync(join(home, "Library", "Application Support", "com.opencodex.desktop", "install-id"), "utf8").trim();
     if (id !== owner.ownership.installId) return deriveDesktopStartup(facts);
-    const path = join(home, "Library", "LaunchAgents", "OpenCodex.plist");
-    const plist = JSON.parse(execute("/usr/bin/plutil", ["-convert", "json", "-o", "-", path]));
-    const args = plist.ProgramArguments;
-    if (plist.Label !== "OpenCodex" || plist.RunAtLoad !== true || !Array.isArray(args)
-      || args.length !== 2 || args[1] !== "--autostart" || typeof args[0] !== "string"
-      || !args[0].endsWith("/Contents/MacOS/opencodex-desktop")
-      || (plist.Program !== undefined && plist.Program !== args[0])) return deriveDesktopStartup(facts);
-    const app = realpathSync(args[0]);
-    const proxy = realpathSync(join(dirname(app), "ocx"));
-    accessSync(app, constants.X_OK);
-    accessSync(proxy, constants.X_OK);
-    const domain = `gui/${deps.uid ?? process.getuid!()}`;
-    const disabled = execute("/bin/launchctl", ["print-disabled", domain]);
-    const loaded = execute("/bin/launchctl", ["print", `${domain}/OpenCodex`]);
-    const program = /^\s*program = (.+)$/m.exec(loaded)?.[1];
-    const loadedPath = /^\s*path = (.+)$/m.exec(loaded)?.[1];
-    facts.loginEnabled = /^\s*disabled services = \{[\s\S]*\}\s*$/.test(disabled)
-      && !/"OpenCodex"\s*=>\s*(?:disabled|true)/.test(disabled)
-      && program !== undefined && realpathSync(program) === app
-      && loadedPath !== undefined && realpathSync(loadedPath) === realpathSync(path);
+    const login = macLoginRegistration(deps);
+    if (!login) return deriveDesktopStartup(facts);
+    const { app, proxy } = login;
+    facts.loginEnabled = login.loginEnabled;
     const pid = pidReader();
     if (pid !== null) {
       const child = processIdentity(pid, execute);
@@ -135,6 +151,16 @@ export function diagnoseLinuxDesktopStartup(deps: DesktopStartupDeps = {}): Desk
   if ((deps.platform ?? process.platform) !== "linux") return undefined;
   const ownership = deps.ownership ?? resolveServiceOwnership;
   const owner = ownership();
+  if (owner.kind === "none") return diagnoseSupervisedStartup(deps, owner.revision, app => {
+    const home = deps.home ?? homedir();
+    const configured = (deps.env ?? process.env).XDG_CONFIG_HOME;
+    const config = configured && isAbsolute(configured) ? configured : join(home, ".config");
+    // auto-launch's HOME entry must remain inside the session's XDG autostart search path.
+    if (resolve(config) !== resolve(home, ".config")) return false;
+    const entry = readFileSync(join(home, ".config", "autostart", "OpenCodex.desktop"), "utf8");
+    const login = linuxLoginApp(entry);
+    return login !== null && realpathSync(login) === app;
+  });
   if (owner.kind !== "owned" || owner.ownership.owner !== "desktop") return undefined;
   const facts = { owned: true, loginEnabled: false, running: false };
   const proc = deps.proc ?? procfs;

package/src/service/desktop-supervision.d.mts

@@ -0,0 +1,26 @@
+export type SupervisionEvidence =
+  | { kind: "desktop"; runtimePid: number; supervisorPid: number; app: string; proxy: string }
+  | { kind: "none" }
+  | { kind: "unknown"; reason: string; desktopSeen: boolean }
+  | { kind: "unsupported" };
+
+export interface ProcReader {
+  exe(pid: number): string;
+  parent(pid: number): number;
+}
+
+export interface DesktopSupervisionDeps {
+  targetPid?: number;
+  platform?: NodeJS.Platform;
+  run?: (command: string, args: string[]) => string;
+  proc?: ProcReader;
+  readPid?: () => number | null;
+  readRuntimePortPid?: () => number | null;
+}
+
+export function desktopSupervisionPaths(): { pid: string; runtimePort: string };
+export const procfs: ProcReader;
+export function processIdentity(pid: number, execute?: DesktopSupervisionDeps["run"], onExecutable?: (path: string) => void):
+  { parent: number; executable: string } | null;
+export function inspectDesktopSupervision(deps?: DesktopSupervisionDeps): SupervisionEvidence;
+export function createSupervisionLatch(): { observe(evidence: SupervisionEvidence): boolean };