@bitkyc08/opencodex 2.63.0 → 2.64.0-preview.20260923

package/src/server/responses/passthrough-dispatch.ts

@@ -41,6 +41,7 @@ import {
   NamespaceToolCollisionError,
   restoreRoutedNamespaceCalls,
 } from "../../responses/namespace-tool-compat";
+import { restoreRoutedCustomCalls, RoutedCustomToolCompatError } from "../../responses/custom-tool-compat";
 import { XaiToolSchemaCompatibilityError } from "../../adapters/xai-tool-schema";
 import { formatErrorResponse } from "../../bridge";
 import { redactSecretString } from "../../lib/redact";
@@ -61,7 +62,6 @@ import {
   parseMuseSubscriptionUsage,
 } from "../../providers/muse-subscription-usage";
 import { restoreMuseToolNames } from "../../responses/muse-tool-name-alias";
-import { restoreRoutedCustomCalls } from "../../responses/custom-tool-compat";
 import { restorePlaintextV2AgentMessageCalls } from "../../responses/plaintext-v2-agent-messages";
 import {
   recordAdapterReasoning,
@@ -122,7 +122,6 @@ import { recordCodexUpstreamOutcome } from "../../codex/routing";
 import { describeUpstreamConnectFailure } from "./upstream-error";
 import type { OpaqueBlobRecoveryGuard } from "./core-opaque-recovery";
 import {
-  isOpenCodeGoDestination,
   rateLimitRetryPolicyFor,
   rateLimitRetryDelayMs,
   transientRetryPolicyFor,
@@ -136,6 +135,7 @@ import { publicOAuthAuthenticationErrorMessage } from "../../oauth";
 import { resolveCopilotApiBaseUrl } from "../../oauth/github-copilot";
 import {
   GENERIC_OAUTH_MAX_FAILOVERS_PER_REQUEST,
+  hasEligibleGenericOAuthFailoverTarget,
   isGenericOAuthFailoverEnabled,
   rotateGenericOAuthAccountOn429,
   failoverAccountSnapshot,
@@ -328,7 +328,11 @@ export async function preparePassthroughExchange(
       // unstructured 500 — and no request log — depending only on whether a rotation ran first.
       // Same shape for a tool_choice this proxy cannot honor: the destination rejects a schema the
       // catalog had to drop, so the selector naming it is a client input error, not a 500.
-      if (error instanceof NamespaceToolCollisionError || error instanceof XaiToolSchemaCompatibilityError) {
+      if (
+        error instanceof NamespaceToolCollisionError
+        || error instanceof XaiToolSchemaCompatibilityError
+        || error instanceof RoutedCustomToolCompatError
+      ) {
         return formatErrorResponse(400, "invalid_request_error", redactSecretString(error.message));
       }
       throw error;
@@ -889,12 +893,6 @@ export async function preparePassthroughExchange(
         { abortSignal: upstream.signal, label: safeHostLabel(request.url),
           attempts: remainingTransientSendBudget(transientSendAttempts()), onSendsConsumed: noteTransientSends,
           claimAmbiguousResend: claimPreHeaderResend,
-          // The OpenCode Go destination stalls-then-drops inference sends (ambiguous
-          // pre-header resets surfacing as refused 429s); its subscription traffic is
-          // inference-only, so a bounded reset replay here absorbs the blip instead of
-          // failing the turn. Recovery legs keep the fail-closed refusal; only this
-          // initial send is replay-eligible. Attempts stay budget-bounded via attempts.
-          replaySafe: isOpenCodeGoDestination(route.provider),
         },
       );
     } catch (err) {
@@ -1310,10 +1308,11 @@ export async function preparePassthroughExchange(
         // No credential moved, so the reservation costs nothing.
         hop.permit?.release();
       } else {
-        // Rotation was available -- the roster cap above admitted it -- and the shared request
-        // budget refused. Recorded so a one-send log is not read as "nothing was eligible",
-        // which is the ambiguity this attribution exists to remove (#5044).
-        noteAttemptRecoveryWithheld(logCtx.activeAttempt, "rotation-send-budget");
+        // The activation quorum ignores cooldowns; prove that the selector has a live alternate
+        // before describing this as a recovery that only the shared request budget withheld.
+        if (hasEligibleGenericOAuthFailoverTarget(
+          route.providerName, transportState.genericFailoverAccountId, Date.now(), route.modelId,
+        )) noteAttemptRecoveryWithheld(logCtx.activeAttempt, "rotation-send-budget");
       }
     }
 

package/src/server/responses/policy-fallback.ts

@@ -8,6 +8,8 @@ import { handleResponses as handleResponsesCore } from "./core";
 import { requestPacingOverloadResponse } from "./pacing-overload";
 import { captureExplicitOpenAiCallerAuth } from "../../providers/openai-sidecar";
 import { captureCallerDirectAuth } from "../../providers/caller-authorization";
+import { resolvePolicyProfileId } from "../../routing/profile";
+import { parseSyntheticRowId } from "../fast-row";
 
 type CoreHandler = typeof handleResponsesCore;
 type CoreOptions = Parameters<CoreHandler>[3];
@@ -146,7 +148,16 @@ export async function handleResponsesWithPolicyFallback(
     } : {}),
     onRequestBodyParsed: body => {
       options.onRequestBodyParsed?.(body);
-      if (body && typeof body === "object" && !Array.isArray(body)) rawBody = body as Record<string, unknown>;
+      if (rawBody === null && body && typeof body === "object" && !Array.isArray(body)
+        && typeof (body as { model?: unknown }).model === "string") {
+        const model = (body as { model: string }).model;
+        const { fastRow, effortRow } = parseSyntheticRowId(model, config);
+        if (resolvePolicyProfileId(config, fastRow?.baseId ?? effortRow?.baseId ?? model) === null) return;
+        // Recovery and other core preparation may mutate the parsed body in place. Keep an
+        // immutable snapshot of the original wire body so a retry cannot serialize those
+        // mutations. Object-identity metadata is re-established by each attempt, not serialized.
+        rawBody = structuredClone(body as Record<string, unknown>);
+      }
     },
     onStoredPool401ReplayDispatched: () => {
       storedPool401ReplayDispatched = true;

package/src/server/responses/request-prepare.ts

@@ -13,6 +13,7 @@ import {
 } from "./core-errors";
 import { parseSyntheticRowId } from "../fast-row";
 import { resolveComboId, comboIdFromRawBody, NoAvailableComboTargetsError } from "../../combos";
+import { INTERCEPT_TARGET_UNAVAILABLE_CODE, interceptTargetUnavailableResponse, resolveShadowCallTarget } from "./shadow-target-availability";
 import { recallComboForLane } from "./combo-session-recall";
 import {
   sessionLaneIdFromRequest,
@@ -38,6 +39,7 @@ import {
   applyCodexAuthContextToProvider,
   hasCallerCodexBearer,
   requestOwnedMainPinState,
+  requestOwnedMainCredentialIsLive,
 } from "../../codex/auth-context";
 import {
   copyPreviousResponseReplayProvenance,
@@ -226,6 +228,7 @@ export async function prepareResponsesRequest(
   // hops — which only exist inside that loop — are unreachable (#4129). Rewrite the selector
   // here instead, before comboIdFromRawBody reads `model`, and identify the combo by CONFIG
   // LOOKUP so the check can never observe a one-candidate collapse.
+  let shadowCallIntercepted = false;
   if (!options.comboAttempt && !options.compactionRoutingOverride && body && typeof body === "object" && !Array.isArray(body)) {
     const shadowIntercept = config.shadowCallIntercept;
     const rawShadowModel = (body as { model?: unknown }).model;
@@ -233,6 +236,7 @@ export async function prepareResponsesRequest(
       && isShadowSourceModel(rawShadowModel, shadowIntercept.sourceModels)) {
       const shadowComboId = resolveComboId(config, shadowIntercept.model);
       if (shadowComboId && Object.hasOwn(config.combos ?? {}, shadowComboId)) {
+        shadowCallIntercepted = true;
         (body as Record<string, unknown>).model = shadowIntercept.model;
         // Same rule as the late intercept site: record the operator-configured prefix that
         // matched, never the caller's raw model string. Matching is by prefix, so the raw
@@ -248,6 +252,9 @@ export async function prepareResponsesRequest(
     options.onRequestBodyRead?.();
     return requestDispatchers.handleComboResponses(req, body, comboId, config, logCtx, {
       ...options,
+      // Concrete combo child selectors no longer match the shadow source model. Carry the
+      // interception decision explicitly so provider-specific helper isolation still applies.
+      shadowCallIntercepted,
       // The original request body was accepted above. Combo children are synthetic
       // replays and must not repeat the caller-owned timeout transition.
       onRequestBodyRead: undefined,
@@ -370,6 +377,7 @@ export async function prepareResponsesRequest(
       }
     }
     if (cursorClientThreadId) parsed._cursorClientThreadId = cursorClientThreadId;
+    if (options.shadowCallIntercepted === true) parsed._cursorIsolateConversation = true;
   } catch (err) {
     if (isTranslatorBudgetExceededError(err)) {
       return formatErrorResponse(413, "request_too_large", "request translation buffer exceeded the safe limit", {
@@ -482,7 +490,15 @@ export async function prepareResponsesRequest(
         const resolvedSource = routeConcreteModel(config, parsed.modelId);
         sourceIdentity = { providerName: resolvedSource.providerName, modelId: sourcePrefix };
       } catch { /* Native Codex helper calls remain OpenAI-owned without an enabled OpenAI route. */ }
-      const targetRoute = resolveRoute(_sci.model);
+      // A dead target fails this helper call once, before any send; it never falls through to
+      // the native source model or to the default provider (#5618).
+      const target = resolveShadowCallTarget(_sci.model, resolveRoute);
+      if ("unavailable" in target) {
+        logCtx.shadowCallRewrittenFrom = sanitizeLogMetadataString(sourcePrefix);
+        logCtx.errorCode = INTERCEPT_TARGET_UNAVAILABLE_CODE;
+        return interceptTargetUnavailableResponse(_sci.model, target.unavailable);
+      }
+      const targetRoute = target.route;
       if (shouldInterceptShadowCall(parsed.modelId, _sci.sourceModels, sourceIdentity, targetRoute)) {
         credentialDomainWasRewritten = true;
         const _sciOriginal = parsed.modelId;
@@ -580,7 +596,19 @@ export async function prepareResponsesRequest(
     options.codexAuthPolicy ?? config,
     previewRequestScopedMainCredential,
     route.codexAccountId,
+    codexQuotaScopeForModel(route.modelId),
   ).preserve;
+  // Final auth's own liveness answer for a request-owned bearer, from its own shared expression
+  // (#5019). Predicting the pin alone dropped main here and handed subagent fallback a different
+  // account than the one that serves.
+  const previewRequestOwnedMainCredentialLive = requestOwnedMainCredentialIsLive({
+    preserveRequestOwnedMainPin: previewRequestOwnedMainPin,
+    requestScopedMainCredential: previewRequestScopedMainCredential,
+    nativeMainTrafficBlocked: nativeMainRecoveryBlocked,
+    mainProfileDraining: previewSelectionAdmission?.mainProfileDraining === true,
+    // Final-auth-only, and stated rather than defaulted: see the field's own note.
+    callerOwnsCooledPoolSubscription: false,
+  });
   // Deliberately NOT fenced on ownership: final auth derives `nativeMainSelectionOnly` from the
   // drain alone, and adding a term here would diverge from it in the other direction.
   const previewSelectionOptions = {
@@ -592,12 +620,13 @@ export async function prepareResponsesRequest(
     // spawn, because subagent fallback re-enters the preview through the callback below.
     //
     // Scoped to ownership, and carrying final auth's value rather than a constant, because
-    // preview exists to predict final auth. Under an effective main pin the request really is
-    // served by its own main credential, so main must stay eligible; without the pin final auth
-    // scores main `main_credential_unavailable` and drops it, so preview has to drop it too. A
-    // hardcoded `true` would be wrong in the second case and `false` in the first.
+    // preview exists to predict final auth. The request really is served by its own main
+    // credential whenever that bearer is forwardable, so main stays eligible; while retained
+    // recovery or a profile drain fences the physical identity, final auth drops main and preview
+    // has to drop it too. A hardcoded `true` would be wrong in the second case and `false` in
+    // the first.
     isMainAccountTokenLive: previewRequestScopedMainCredential
-      ? () => previewRequestOwnedMainPin
+      ? () => previewRequestOwnedMainCredentialLive
       : undefined,
     // Preview must reach the same answer as the final resolution, including the uploaded-file
     // retention (#4778): a preview that reported a quota move the request will not make would
@@ -836,12 +865,22 @@ export async function prepareResponsesRequest(
                 options.codexAuthPolicy ?? config,
                 recoveryRequestScopedMainCredential,
                 route.codexAccountId,
+                codexQuotaScopeForModel(route.modelId),
               ).preserve;
+              // Same shared expression as the first preview and as final auth (#5019), recomputed
+              // against the route recovery may have moved to.
+              const recoveryRequestOwnedMainCredentialLive = requestOwnedMainCredentialIsLive({
+                preserveRequestOwnedMainPin: recoveryRequestOwnedMainPin,
+                requestScopedMainCredential: recoveryRequestScopedMainCredential,
+                nativeMainTrafficBlocked: recoveryNativeMainBlocked,
+                mainProfileDraining: recoverySelectionAdmission?.mainProfileDraining === true,
+                callerOwnsCooledPoolSubscription: false,
+              });
               const recoverySelectionOptions = {
                 nativeMainSelectionOnly: !recoveryNativeMainBlocked
                   && recoverySelectionAdmission?.mainProfileDraining === true,
                 isMainAccountTokenLive: recoveryRequestScopedMainCredential
-                  ? () => recoveryRequestOwnedMainPin
+                  ? () => recoveryRequestOwnedMainCredentialLive
                   : undefined,
                 // #4778, same reason as `previewSelectionOptions` above: this preview decides
                 // which account subagent fallback scores against, and final auth passes the

package/src/server/responses/request-spend.ts

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import type { RequestSendObserver } from "../../lib/request-execution-budget";
 import { sharedSpendLedger, type SpendReservationLedger } from "../../lib/spend-reservation-ledger";
+import { SpendLedgerOwnerError } from "../../lib/spend-ledger-owner";
 import { markLocalRequestLogRefusal, type RequestLogContext } from "../request-log";
 import { recordWorkflowRefusalEvent, workflowDenialSummary } from "../../lib/workflow-budget";
 
@@ -42,7 +43,7 @@ export interface RequestSpendTracker extends RequestSendObserver, RequestSpendSe
 export function createRequestSpendTracker(
   logCtx: Pick<
     RequestLogContext,
-    "provider" | "accountLogLabel" | "usageLogInputTokens" | "spendOutputCeilingTokens"
+    "provider" | "accountLogLabel" | "usageLogInputTokens" | "spendOutputCeilingTokens" | "spendInputEstimateTokens"
   > & Partial<Pick<RequestLogContext, "localTerminalReason" | "terminalSource" | "errorCode">>,
   rootId: string | undefined,
   injected?: SpendReservationLedger,
@@ -57,6 +58,7 @@ export function createRequestSpendTracker(
   const live: string[] = [];
   let refusals = 0;
   let resolved = false;
+  let terminalProcessed = false;
   /**
    * Confirm the sends this request has already moved past.
    *
@@ -88,7 +90,7 @@ export function createRequestSpendTracker(
           ...(logCtx.accountLogLabel !== undefined ? { identityId: logCtx.accountLogLabel } : {}),
           ...(logCtx.provider !== undefined ? { poolId: logCtx.provider } : {}),
         },
-        inputTokens: logCtx.usageLogInputTokens ?? 0,
+        inputTokens: logCtx.spendInputEstimateTokens ?? logCtx.usageLogInputTokens ?? 0,
         outputCeilingTokens: logCtx.spendOutputCeilingTokens ?? 0,
         ...(alreadySent ? { alreadySent: true } : {}),
       });
@@ -135,21 +137,35 @@ export function createRequestSpendTracker(
     },
     settle(usage: TerminalSpendUsage | undefined): void {
       if (resolved) return;
-      resolved = true;
-      const terminal = live.pop();
-      if (terminal !== undefined) {
-        const reported = typeof usage?.inputTokens === "number" || typeof usage?.outputTokens === "number";
-        if (reported) {
-          ledger().settle(terminal, {
-            inputTokens: usage?.inputTokens ?? 0,
-            outputTokens: usage?.outputTokens ?? 0,
-          });
-        } else {
-          // The response never reported usage. It may still have been billed.
-          ledger().markLost(terminal);
+      try {
+        if (!terminalProcessed && live.length > 0) {
+          const terminal = live[live.length - 1] as string;
+          const reported = typeof usage?.inputTokens === "number" || typeof usage?.outputTokens === "number";
+          if (reported) {
+            ledger().settle(terminal, {
+              inputTokens: usage?.inputTokens ?? 0,
+              outputTokens: usage?.outputTokens ?? 0,
+            });
+          } else {
+            // The response never reported usage. It may still have been billed.
+            ledger().markLost(terminal);
+          }
+          live.pop();
+          terminalProcessed = true;
         }
+        while (live.length > 0) {
+          ledger().markLost(live[live.length - 1] as string);
+          live.pop();
+        }
+        resolved = true;
+      } catch (error) {
+        // A deferred final log may arrive after server.stop released this ledger's lease.
+        // Only that ended ownership can discard sends already reserved by this tracker.
+        if (live.length === 0 || !(error instanceof SpendLedgerOwnerError)
+          || error.code !== "SPEND_LEDGER_OWNER_NOT_HELD") throw error;
+        live.length = 0;
+        resolved = true;
       }
-      for (const sendId of live.splice(0)) ledger().markLost(sendId);
     },
     get refusals(): number { return refusals; },
   };

package/src/server/responses/run-turn-execution.ts

@@ -23,6 +23,7 @@ import { adapterFailureFromMessage, SEND_BUDGET_EXHAUSTED_CODE } from "../../lib
 import { SendBudgetExhaustedError } from "../../lib/upstream-retry";
 import {
   GENERIC_OAUTH_MAX_FAILOVERS_PER_REQUEST,
+  hasEligibleGenericOAuthFailoverTarget,
   isGenericOAuthFailoverEnabled,
   rotateGenericOAuthAccountOn429,
   failoverAccountSnapshot,
@@ -253,11 +254,11 @@ export async function executeResponsesRunTurn(
         `${route.providerName}|${route.modelId}|runturn-oauth-429`,
       );
       if (!hop.allowed) {
-        // The roster bound above already said this credential set may rotate again; the shared
-        // request budget is what refused. Returning false lets the preflight 429 reach the
-        // client unchanged, which is right, but it used to leave a log indistinguishable from
-        // a request where no rotation was ever available (#5044).
-        noteAttemptRecoveryWithheld(logCtx.activeAttempt, "rotation-send-budget");
+        // The activation quorum deliberately ignores cooldowns. Attribute a withheld recovery
+        // only when the non-mutating selector proves a usable alternate exists right now.
+        if (hasEligibleGenericOAuthFailoverTarget(
+          route.providerName, transportState.genericFailoverAccountId, Date.now(), route.modelId,
+        )) noteAttemptRecoveryWithheld(logCtx.activeAttempt, "rotation-send-budget");
         return false;
       }
       const nextAccountId = rotateGenericOAuthAccountOn429(

package/src/server/responses/shadow-target-availability.ts

@@ -0,0 +1,61 @@
+import { NoAvailableComboTargetsError } from "../../combos";
+import { NoEligiblePolicyCandidateError, type RouteResult } from "../../router";
+import { AdmissionModelDeniedError } from "../admission-model-scope";
+
+/**
+ * Shadow-call interception names one operator-chosen target (#5618). When that target stops
+ * resolving (its provider disabled or deleted, its combo removed), the helper call must fail once,
+ * clearly, before anything is sent. It must not pass through to the native model it was meant to
+ * replace, and it must not reach the default provider through the router's last-resort fallback:
+ * either would change the destination, the credentials and the cost without the operator choosing
+ * it. A combo or routing-profile target keeps its own declared failover, which is the fallback the
+ * operator approved.
+ */
+export const INTERCEPT_TARGET_UNAVAILABLE_CODE = "intercept_target_unavailable";
+
+/** Non-retryable: the target stays unavailable until the operator changes the configuration. */
+export const INTERCEPT_TARGET_UNAVAILABLE_STATUS = 409;
+
+export type ShadowTargetResolution = { route: RouteResult } | { unavailable: string };
+
+/**
+ * Resolve the configured target. Admission-scope refusals, exhausted combos and policy
+ * evaluations keep their existing responses, so they are rethrown to the caller's handler.
+ */
+export function resolveShadowCallTarget(
+  model: string,
+  resolve: (model: string) => RouteResult,
+): ShadowTargetResolution {
+  let route: RouteResult;
+  try {
+    route = resolve(model);
+  } catch (error) {
+    if (error instanceof AdmissionModelDeniedError
+      || error instanceof NoAvailableComboTargetsError
+      || error instanceof NoEligiblePolicyCandidateError) throw error;
+    return { unavailable: error instanceof Error ? error.message : String(error) };
+  }
+  // A qualified target whose provider segment matched nothing reaches the default provider only
+  // through the router's terminal fallback. A bare target resolved that way is the operator's
+  // documented choice and stays valid.
+  if (route.routeKind === "default-provider" && model.includes("/")) {
+    return { unavailable: "it names no configured provider and would only reach the default provider" };
+  }
+  return { route };
+}
+
+const warnedTargets = new Set<string>();
+
+export function interceptTargetUnavailableResponse(model: string, detail: string): Response {
+  const message = `Shadow call intercept target "${model}" is unavailable: ${detail}. `
+    + "Choose another target in the shadow call settings or re-enable its provider.";
+  const key = `${model}\u0000${detail}`;
+  if (!warnedTargets.has(key)) {
+    warnedTargets.add(key);
+    console.warn(`shadow-call: ${message}`);
+  }
+  return new Response(
+    JSON.stringify({ error: { message, type: "invalid_request_error", code: INTERCEPT_TARGET_UNAVAILABLE_CODE } }),
+    { status: INTERCEPT_TARGET_UNAVAILABLE_STATUS, headers: { "Content-Type": "application/json" } },
+  );
+}

package/src/server/responses-custom-tool-repair.ts

@@ -1,6 +1,7 @@
 import type { TranslatorBudget } from "../lib/translator-budget";
 import { mayBecomePatchEnvelope, normalizeApplyPatchDelimiters } from "../responses/apply-patch-envelope";
 import { compileCodeModeHelperInput, resolveCodeModeHelperName } from "../responses/code-mode-helper-compat";
+import { mayBecomeCodeModeShellInput } from "../responses/code-mode-shell-input";
 import { progressiveFreeformInput } from "../responses/progressive-freeform-input";
 import { declaresCodeModeExec } from "../types/tools";
 import {
@@ -320,6 +321,7 @@ export function createRoutedCustomToolRestoreBlockRewrite(
         && itemName?.name === "exec";
       const mayNormalize = ownsFreeformGrammar && itemName?.name === "apply_patch";
       if ((mayCompile || mayNormalize) && mayBecomePatchEnvelope(fullInput)) return [];
+      if (mayCompile && mayBecomeCodeModeShellInput(open.argumentsText, fullInput)) return [];
       if (!fullInput.startsWith(open.emittedInput) || fullInput.length === open.emittedInput.length) return [];
       const inputDelta = fullInput.slice(open.emittedInput.length);
       open.emittedInput = fullInput;

package/src/service/claim.ts

@@ -0,0 +1,185 @@
+/**
+ * `ocx service claim` — record an ownership claim the embedding shell already got consent for.
+ *
+ * The desktop cannot write the record itself: the claim has to be committed under the
+ * ownership mutation lease, against the subject and managing-CLI compatibility the caller
+ * observed, by the module that owns all three. `recordServiceOwner` is that module; this
+ * verb is the wire that hands it the approval `ocx resolve --json` produced.
+ *
+ * Every expectation is mandatory because the claim is only valid against the exact answer
+ * the consent prompt was approved from. A subject or compatibility that moved in between
+ * is a fresh situation, and fresh approval is the only thing that covers it.
+ */
+import {
+  recordServiceOwner,
+  resolveServiceState,
+  type RecordServiceOwnerDeps,
+  type ServiceOwner,
+  type ServiceOwnershipSubject,
+} from "./state";
+import {
+  SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+  SERVICE_OWNERSHIP_PROTOCOL_VERSION,
+} from "./install-state-contract.mjs";
+import { observeManagingClis } from "./managing-cli";
+import type { ManagingCliObservation, ManagingCliRole } from "./ownership-compatibility";
+
+export const CLAIM_SCHEMA = "ocx-service-claim/1";
+
+const CLAIM_USAGE = [
+  "Usage: ocx service claim --owner <cli|desktop> --install-id <id>",
+  "    (--expect-none | --expect-owner <cli|desktop> --expect-install-id <id> --expect-generation <n>)",
+  "    --expect-revision <n> --expect-compatibility-token <hex> [--json]",
+].join("\n");
+
+export interface ClaimArgs {
+  owner: ServiceOwner;
+  installId: string;
+  expectedSubject: ServiceOwnershipSubject;
+  compatibilityToken: string;
+  json: boolean;
+}
+
+export type ClaimParseResult = { ok: true; args: ClaimArgs } | { ok: false };
+
+function readFlag(args: string[], index: number): string {
+  return args[index + 1] ?? "";
+}
+
+function readOwner(value: string): ServiceOwner | null {
+  return value === "cli" || value === "desktop" ? value : null;
+}
+
+function readRevision(value: string): number | null {
+  if (!/^\d+$/.test(value)) return null;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) ? parsed : null;
+}
+
+/** Strict parse: the whole approval arrives on argv or the invocation is a usage error. */
+export function parseClaimArgs(args: string[]): ClaimParseResult {
+  let owner: ServiceOwner | null = null;
+  let installId: string | null = null;
+  let expectNone = false;
+  let expectOwner: ServiceOwner | null = null;
+  let expectInstallId: string | null = null;
+  let expectGeneration: number | null = null;
+  let expectRevision: number | null = null;
+  let token: string | null = null;
+  let json = false;
+  const withValue = new Set([
+    "--owner", "--install-id", "--expect-owner", "--expect-install-id",
+    "--expect-generation", "--expect-revision", "--expect-compatibility-token",
+  ]);
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index]!;
+    if (arg === "--json") { json = true; continue; }
+    if (arg === "--expect-none") { expectNone = true; continue; }
+    if (!withValue.has(arg)) return { ok: false };
+    const value = readFlag(args, index);
+    if (!value) return { ok: false };
+    index += 1;
+    switch (arg) {
+      case "--owner": owner = readOwner(value); if (owner === null) return { ok: false }; break;
+      case "--install-id": installId = value; break;
+      case "--expect-owner": expectOwner = readOwner(value); if (expectOwner === null) return { ok: false }; break;
+      case "--expect-install-id": expectInstallId = value; break;
+      case "--expect-generation": expectGeneration = readRevision(value); if (expectGeneration === null) return { ok: false }; break;
+      case "--expect-revision": expectRevision = readRevision(value); if (expectRevision === null) return { ok: false }; break;
+      case "--expect-compatibility-token": token = value; break;
+    }
+  }
+  if (!owner || !installId || expectRevision === null || !token) return { ok: false };
+  let expectedSubject: ServiceOwnershipSubject;
+  if (expectNone) {
+    if (expectOwner !== null || expectInstallId !== null || expectGeneration !== null) return { ok: false };
+    expectedSubject = { kind: "none", revision: expectRevision };
+  } else {
+    if (expectOwner === null || expectInstallId === null || expectGeneration === null) return { ok: false };
+    expectedSubject = {
+      kind: "owned",
+      ownership: { owner: expectOwner, installId: expectInstallId, consentGeneration: expectGeneration },
+      revision: expectRevision,
+    };
+  }
+  return { ok: true, args: { owner, installId, expectedSubject, compatibilityToken: token, json } };
+}
+
+export interface ServiceClaimDeps {
+  /** recordServiceOwner seam. */
+  recordOwner?: typeof recordServiceOwner;
+  /** The managing-CLI revalidation the record runs inside its lock. */
+  observeManagers?: () => Readonly<Record<ManagingCliRole, ManagingCliObservation>>;
+  /** Re-resolves the state under the lock for the observation. */
+  resolveState?: typeof resolveServiceState;
+  stdout?: { log: (s: string) => void };
+  stderr?: { error: (s: string) => void };
+}
+
+interface ClaimError extends Error {
+  code?: string;
+}
+
+/**
+ * Run `ocx service claim`. Returns the exit code; the caller assigns it, so the verb
+ * reports before the process decides.
+ */
+export async function runServiceClaim(argv: string[], deps: ServiceClaimDeps = {}): Promise<number> {
+  const stdout = deps.stdout ?? console;
+  const stderr = deps.stderr ?? console;
+  const parsed = parseClaimArgs(argv);
+  if (!parsed.ok) {
+    stderr.error(CLAIM_USAGE);
+    return 64;
+  }
+  const { args } = parsed;
+  const resolveState = deps.resolveState ?? resolveServiceState;
+  const observeManagers = deps.observeManagers ?? (() => {
+    const resolved = resolveState();
+    if (resolved.kind === "unknown") {
+      // recordServiceOwner converts a thrown observation into a compatibility-changed
+      // refusal; an unreadable state under the lock is exactly that.
+      throw new Error(resolved.reason);
+    }
+    return observeManagingClis(resolved.kind === "state" ? resolved.state : null);
+  });
+  const recordOwner = deps.recordOwner ?? recordServiceOwner;
+  const request = {
+    owner: args.owner,
+    installId: args.installId,
+    expectedSubject: args.expectedSubject,
+    expectedCompatibility: {
+      kind: "supported" as const,
+      protocolVersion: SERVICE_OWNERSHIP_PROTOCOL_VERSION,
+      minimumCliVersion: SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+      token: args.compatibilityToken,
+    },
+  };
+  try {
+    const recordDeps: RecordServiceOwnerDeps = { observeManagers };
+    const committed = recordOwner(request, recordDeps);
+    if (args.json) {
+      stdout.log(JSON.stringify({
+        schema: CLAIM_SCHEMA,
+        ok: true,
+        ownership: committed.ownership,
+        revision: committed.revision,
+      }));
+    } else {
+      stdout.log(
+        `✅ Recorded ${args.owner} as the runtime owner (install ${args.installId}, generation ${committed.ownership.consentGeneration}).`,
+      );
+    }
+    return 0;
+  } catch (error) {
+    const claimError = error as ClaimError;
+    const code = typeof claimError?.code === "string" ? claimError.code : "claim-failed";
+    const message = claimError instanceof Error ? claimError.message : String(error);
+    if (args.json) {
+      stdout.log(JSON.stringify({ schema: CLAIM_SCHEMA, ok: false, code, message }));
+    } else {
+      stderr.error(`❌ ${message}`);
+    }
+    return 1;
+  }
+}

package/src/service/cli.ts

@@ -21,6 +21,7 @@ import { inspectWindowsSchedulerServiceStatus, schtasksErrorDetail, probeWindows
 import type { WindowsSchedulerTaskProbe } from "./windows-scheduler";
 import { win32 } from "node:path";
 import { serviceDiagnosticsSummary } from "./diagnostics";
+import { runServiceClaim } from "./claim";
 
 /**
  * `restart` is NO LONGER folded into `repair`.
@@ -184,6 +185,14 @@ export function parseServiceArgs(args: string[]): ParsedServiceArgs {
 export async function serviceCommand(...args: (string | undefined)[]): Promise<void> {
   const filteredArgs = args.filter((a): a is string => Boolean(a));
   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
+    // assertServiceEnvironmentMatchesInstall — a takeover is not an install.
+    if (filteredArgs[0] === "claim") {
+      const code = await runServiceClaim(filteredArgs.slice(1));
+      if (code !== 0) process.exitCode = code;
+      return;
+    }
     // Planning reads manager state. Repeat it only after the writer lock is held, otherwise a
     // bare command can choose install from a snapshot another service command already changed.
     const plan = planServiceCommand(filteredArgs);
@@ -419,7 +428,7 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
       console.log("✅ service uninstalled.");
       break;
     default:
-      console.error("Usage: ocx service [install|repair|restart|start|stop|status|uninstall|remove] [--native|--scheduler]");
+      console.error("Usage: ocx service [install|repair|restart|start|stop|status|uninstall|remove|claim] [--native|--scheduler]");
       console.error("       With no subcommand, installs when absent or repairs/restarts an existing service.");
       console.error("       repair: refresh the installed backend, reloading it only when the definition changed; stale Windows tasks may request admin approval.");
       console.error("       restart: the same refresh, but always restarts the service — on macOS a healthy job is kickstarted in place.");