@bitkyc08/opencodex 2.67.0 → 2.68.0

package/src/claude/inbound-model-options.ts

@@ -1,5 +1,5 @@
 import type { OcxClaudeCodeConfig } from "../types";
-import { isAnthropicOutputSchema } from "../adapters/anthropic-output-schema";
+import { isAnthropicOutputSchema, satisfiesOpenAiStrictSchema } from "../adapters/anthropic-output-schema";
 import { resolveAlias } from "./alias";
 import { stripOneMillionMarker } from "./context-windows";
 import { isUnresolvedDesktop3pAlias, resolveDesktop3pAlias } from "./desktop-3p";
@@ -104,7 +104,19 @@ export function formatFromOutputConfig(outputConfig: unknown): Rec | undefined {
     || !isRec(format.schema)
     || !isAnthropicOutputSchema(format.schema)
   ) return undefined;
-  return { type: "json_schema", name: "response", schema: format.schema };
+  // `strict` is stated rather than left to the destination's default. A schema with an optional
+  // property is legal to Anthropic and a hard 400 under OpenAI strict mode ("'required' ... an
+  // array including every key in properties"), which takes down every structured-output turn on
+  // a route whose canonical target is unavailable. Satisfying strict by adding the missing keys
+  // to `required` would change the caller's contract, so the optionality is preserved and the
+  // strict claim is dropped instead.
+  return {
+    type: "json_schema",
+    name: "response",
+    schema: format.schema,
+    // Strict Structured Outputs also needs an object at the root; a root anyOf/oneOf is refused.
+    strict: format.schema.type === "object" && satisfiesOpenAiStrictSchema(format.schema),
+  };
 }
 
 /**

package/src/claude/inbound.ts

@@ -513,7 +513,7 @@ function translateAnthropicRequest(
     // value, so do not attach the similarly named internal catalog sentinel.
     body.reasoning = { effort: "none" };
   } else if (isRec(thinking) || outputConfigEffort !== undefined) {
-    const reasoning: Rec = { summary: "auto" };
+    const reasoning: Rec = { summary: isRec(thinking) && thinking.display === "omitted" ? "none" : "auto" };
     if (outputConfigEffort !== undefined) {
       // Adaptive wire: /effort arrives as output_config.effort (devlog 080).
       reasoning.effort = outputConfigEffort;

package/src/claude/intercept/connect-proxy.ts

@@ -32,6 +32,8 @@ export interface ConnectProxyOptions {
   authToken?: string | (() => string | null);
   /** Hostnames (lowercase) whose 443 tunnels are spliced onto `interceptPort`. */
   interceptHosts?: readonly string[];
+  /** Optional exact CONNECT authorities (host:port); empty denies all, absent keeps blind relay. */
+  allowedTargets?: readonly string[];
   /** Per-connection override, consulted before interceptHosts; null keeps the default. */
   selectTunnel?: (host: string, port: number, request: ConnectRequestInfo) => TunnelDecision | null | Promise<TunnelDecision | null>;
   /** Test seam: dial the real destination for a blind tunnel. */
@@ -67,7 +69,8 @@ function connectRequestInfo(head: string): ConnectRequestInfo {
 }
 
 type ResolvedConnectProxyOptions = Required<Pick<ConnectProxyOptions, "interceptPort" | "interceptHosts" | "dialUpstream">>
-  & Pick<ConnectProxyOptions, "selectTunnel" | "authToken">;
+  & Pick<ConnectProxyOptions, "selectTunnel" | "authToken">
+  & { allowedTargets?: ReadonlySet<string> };
 
 export interface ConnectProxyHandle {
   port: number;
@@ -186,6 +189,10 @@ function handleConnection(socket: Socket, options: ResolvedConnectProxyOptions):
       respond(socket, 403, "Forbidden");
       return;
     }
+    if (options.allowedTargets && !options.allowedTargets.has(`${target.host}:${target.port}`)) {
+      respond(socket, 403, "Forbidden");
+      return;
+    }
     const dialFor = (selected: TunnelDecision | null): void => {
       if (socket.destroyed) return;
       const choice = selected ?? (target.port === 443 && options.interceptHosts.includes(target.host)
@@ -258,10 +265,19 @@ function handleConnection(socket: Socket, options: ResolvedConnectProxyOptions):
 
 /** Bind the CONNECT proxy on 127.0.0.1. Rejects when the port is unavailable. */
 export function startConnectProxy(port: number, options: ConnectProxyOptions): Promise<ConnectProxyHandle> {
+  // Snapshot caller-owned policy before listening. Reuse the request parser's
+  // host normalization; malformed policy must not silently disable restrictions.
+  const allowedTargets = options.allowedTargets === undefined ? undefined : new Set(options.allowedTargets.map(authority => {
+    const target = typeof authority === "string" && !/[\s\r\n]/.test(authority)
+      ? parseConnectRequestLine(`CONNECT ${authority} HTTP/1.1`) : null;
+    if (!target || /[*/\\?#@%]/.test(target.host)) throw new Error("Invalid CONNECT allowed target");
+    return `${target.host}:${target.port}`;
+  }));
   const resolved: ResolvedConnectProxyOptions = {
     interceptPort: options.interceptPort,
     authToken: options.authToken,
     interceptHosts: options.interceptHosts ?? CLAUDE_INTERCEPT_HOSTS,
+    allowedTargets,
     selectTunnel: options.selectTunnel,
     dialUpstream: options.dialUpstream ?? ((host: string, targetPort: number) => connect({ host, port: targetPort })),
   };

package/src/claude/intercept/local-ca.ts

@@ -193,12 +193,18 @@ export interface LocalInterceptCa extends PemKeyPair {
 
 export interface AuthorityOptions {
   commonName: string;
+  /** Optional whole-day lifetime for short-lived authorities; defaults to the existing 3650 days. */
+  validityDays?: number;
   permittedDnsNames?: readonly string[];
   /** With permittedDnsNames: also exclude every IP address (default true). */
   excludeAllIpAddresses?: boolean;
 }
 
 export function createCertificateAuthority(options: AuthorityOptions): LocalInterceptCa {
+  const validityDays = options.validityDays ?? CA_VALIDITY_DAYS;
+  if (!Number.isInteger(validityDays) || validityDays < 1 || validityDays > CA_VALIDITY_DAYS) {
+    throw new Error("CA validityDays must be an integer between 1 and 3650");
+  }
   const { publicKey, privateKey } = generateKeyPairSync("ec", { namedCurve: "prime256v1" });
   const name = distinguishedName(options.commonName);
   const der = issueCertificate({
@@ -206,7 +212,7 @@ export function createCertificateAuthority(options: AuthorityOptions): LocalInte
     issuer: name,
     subjectKey: publicKey,
     signingKey: privateKey,
-    validityDays: CA_VALIDITY_DAYS,
+    validityDays,
     extensions: [
       extension(OID.basicConstraints, true, sequence(boolean(true), tlv(0x02, Uint8Array.of(0)))),
       // keyCertSign | cRLSign

package/src/claude/message-threads.ts

@@ -0,0 +1,28 @@
+/**
+ * Claude Code's message-threads beta, which it only enables against first-party Anthropic, sends
+ * a `thread` object on subagent turns. A `continue` carries just the messages after
+ * `previous_message_id` and may omit `system` and `tools`, because Anthropic replays them from the
+ * stored thread. A translated route has no such store, so translating that delta silently drops the
+ * task, the instructions and the earlier turns.
+ *
+ * Claude Code reads this error code as "threads are unsupported for this model": it resends the
+ * same turn with the full conversation and keeps that model stateless for the rest of the session.
+ */
+export const MESSAGE_THREAD_UNSUPPORTED_ERROR_CODE = "thread_unsupported_request";
+
+export function carriesMessageThread(body: unknown): boolean {
+  if (body === null || typeof body !== "object" || Array.isArray(body)) return false;
+  const thread = (body as Record<string, unknown>).thread;
+  return thread !== null && typeof thread === "object" && !Array.isArray(thread);
+}
+
+export function messageThreadUnsupportedResponse(): Response {
+  return new Response(JSON.stringify({
+    type: "error",
+    error: {
+      type: "invalid_request_error",
+      message: "message threads are not supported on translated routes",
+      details: { error_code: MESSAGE_THREAD_UNSUPPORTED_ERROR_CODE },
+    },
+  }), { status: 400, headers: { "Content-Type": "application/json" } });
+}

package/src/cli/account-api.ts

@@ -27,6 +27,8 @@ export interface AccountRow {
   masked?: string;
   active: boolean;
   needsReauth?: boolean;
+  autoSelectable?: boolean;
+  skipReason?: "needs_reauth" | "suspended" | "cooldown" | "quota_exhausted";
   selectionExcludedReason?: "plan_excluded";
   selectionExcludedPlan?: string;
   /** Registered credential that is still excluded from routing until validation completes. */
@@ -343,6 +345,8 @@ interface OAuthAccountDto {
   email?: string;
   active?: boolean;
   needsReauth?: boolean;
+  autoSelectable?: boolean;
+  skipReason?: unknown;
   /** Always sent by the management route; explicitly `null` when the tier is unknown. */
   plan?: string | null;
   quota?: CodexQuotaDto | null;
@@ -350,6 +354,11 @@ interface OAuthAccountDto {
   quotaFailure?: unknown;
 }
 
+function isKiroSkipReason(value: unknown): value is NonNullable<AccountRow["skipReason"]> {
+  return value === "needs_reauth" || value === "suspended"
+    || value === "cooldown" || value === "quota_exhausted";
+}
+
 async function fetchOAuthRows(
   deps: AccountDeps,
   baseUrl: string,
@@ -376,6 +385,10 @@ async function fetchOAuthRows(
     email: a.email,
     active: a.active ?? a.id === activeId,
     needsReauth: a.needsReauth,
+    ...(name === "kiro" && typeof a.autoSelectable === "boolean"
+      ? { autoSelectable: a.autoSelectable } : {}),
+    ...(name === "kiro" && a.autoSelectable === false && isKiroSkipReason(a.skipReason)
+      ? { skipReason: a.skipReason } : {}),
     // Forward the server's answer verbatim. An absent key means the proxy predates tier
     // reporting while `null` means it checked and found no tier — collapsing either
     // direction would destroy the one distinction this field exists to make.

package/src/cli/account-auth.ts

@@ -34,7 +34,7 @@ function writeStdoutFully(text: string): void {
 }
 
 const USAGE = `Usage:
-  ocx account login <provider> [--id <account-id>] [--reauth] [--device] [--code -] [--no-wait] [--json]
+  ocx account login <provider> [--id <account-id>] [--reauth] [--device] [--method builder-id|google|github] [--code -] [--no-wait] [--json]
   ocx account code <provider> [--flow <flow-id>] [--json]   (reads the code from stdin)
   ocx account cancel <provider> [--flow <flow-id>] [--json] (--flow required for codex)
   ocx account reset-credits <account-id|main> [--consume --yes [--operation-id <uuid>]] [--json]
@@ -72,6 +72,13 @@ interface LoginStart {
   deviceCode?: string;
   /** Whether the host actually opened a browser. Absent from older proxies. */
   browserLaunch?: "started" | "failed" | "skipped";
+  method?: "builder-id" | "google" | "github";
+  userCode?: string;
+  verificationUri?: string;
+  verificationUriComplete?: string;
+  expiresAt?: number;
+  state?: string;
+  warning?: string;
 }
 
 /**
@@ -94,6 +101,14 @@ const STDIN_SENTINEL = "-";
 
 /** Providers whose ONLY login is already a device flow; --device is redundant, not wrong. */
 const DEVICE_NATIVE_PROVIDERS = new Set(["kimi", "nous", "github-copilot"]);
+const stripTerminalControls = (value: string): string => value.replace(/[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u202a-\u202e\u2060-\u2069\ufeff]/g, "");
+export function formatKiroDeviceInstructions(start: { verificationUriComplete?: string; verificationUri?: string; userCode?: string; flowId?: string }): string {
+  return [
+    stripTerminalControls(start.verificationUriComplete ?? start.verificationUri ?? ""),
+    start.userCode ? `User code: ${stripTerminalControls(start.userCode)}` : "",
+    start.flowId ? `Flow: ${stripTerminalControls(start.flowId)}` : "",
+  ].filter(Boolean).join("\n");
+}
 
 const ARGV_WARNING =
   "warning: the authorization code was passed as a command-line argument, so it is now in your shell history and was visible in the process list while this ran. Pipe it on stdin instead, or pass `-` to read from stdin.";
@@ -128,9 +143,17 @@ async function login(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const noWait = takeFlag(args, "--no-wait");
   const reauth = takeFlag(args, "--reauth");
   const device = takeFlag(args, "--device");
+  const method = takeOption(args, "--method");
   const id = takeOption(args, "--id");
   const suppliedCode = takeOptionWithSyntax(args, "--code");
   if (!provider) throw new CliUsageError("provider is required", USAGE);
+  if (method !== undefined) {
+    if (provider !== "kiro" || !["builder-id", "google", "github"].includes(method)) {
+      throw new CliUsageError("--method requires kiro and builder-id, google, or github", USAGE);
+    }
+    if (reauth || id) throw new CliUsageError("native Kiro device login only adds accounts; remove and re-add to reauthenticate", USAGE);
+    if (device || suppliedCode) throw new CliUsageError("--method cannot be combined with --device or --code", USAGE);
+  }
   // A bare leftover here is plausibly the authorization code itself: this flow takes one
   // through --code, and a user who pastes it as a positional would otherwise see it echoed
   // back in the usage error. `ocx login codex` reaches this parser too, so the paste lands
@@ -147,6 +170,30 @@ async function login(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   // opens the browser flow and polls, and must not block on stdin.
   const code = await resolveCode(suppliedCode, deps, false);
 
+  if (method) {
+    const start = await runtimeRequest<LoginStart>("/api/oauth/login", {
+      method: "POST", body: JSON.stringify({ provider: "kiro", method }),
+    }, deps);
+    if (!wantsJson) {
+      const block = formatKiroDeviceInstructions(start);
+      if (block) writeStdoutFully(`${block}\n`);
+    }
+    if (noWait) { printData(start, wantsJson, []); return; }
+    if (!start.flowId) throw new CliUsageError("Kiro device login did not return a flow id");
+    for (let attempt = 0; attempt < 450; attempt++) {
+      await Bun.sleep(2_000);
+      const state = await runtimeRequest<LoginStart>(`/api/oauth/status?provider=kiro&flowId=${encodeURIComponent(start.flowId)}`, {}, deps);
+      if (state.state === "done") {
+        printData(state, wantsJson, ["Logged in to kiro.", ...(state.warning ? [`Warning: ${state.warning}`] : [])]);
+        return;
+      }
+      if (state.state === "failed" || state.state === "expired" || state.state === "cancelled") {
+        throw new CliUsageError(`Kiro device login ${state.state}`);
+      }
+    }
+    throw new CliUsageError("Kiro device login timed out");
+  }
+
   if (CODEX_NAMES.has(provider)) {
     const start = await runtimeRequest<LoginStart>("/api/codex-auth/login", {
       method: "POST",
@@ -290,7 +337,7 @@ async function cancel(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   }
   const result = await runtimeRequest(codex ? "/api/codex-auth/login/cancel" : "/api/oauth/login/cancel", {
     method: "POST",
-    body: JSON.stringify(codex ? { flowId } : { provider }),
+    body: JSON.stringify(codex ? { flowId } : { provider, ...(provider === "kiro" && flowId ? { flowId } : {}) }),
   }, deps);
   printData(result, wantsJson, [`Cancelled ${provider} login.`]);
 }

package/src/cli/account-extended.ts

@@ -45,7 +45,7 @@ const EXTENDED_USAGE = `Usage:
   ocx account pause <provider> <id|alias|main> [--json]
   ocx account resume <provider> <id|alias|main> [--json]
   ocx account pause-exhausted <provider> [--json]
-  ocx account strategy <provider> [<quota|round-robin|fill-first|reset-first>] [--json]
+  ocx account strategy <provider> [<quota|round-robin|fill-first|least-loaded|reset-first>] [--json]
   ocx account sticky <provider> [<1-100>] [--json]
   ocx account remove <provider> <id|alias|main> --yes [--json]
   ocx account clear-cooldown <provider> <id|alias|main> [--json]
@@ -961,7 +961,9 @@ async function poolSetting(
       console.log(JSON.stringify(payload, null, 2));
     } else {
       if (field === "strategy" && autoSwitchThreshold !== undefined) {
-        const thresholdSummary = strategy === "round-robin"
+        const thresholdSummary = strategy === "least-loaded"
+          ? "fewest active requests"
+          : strategy === "round-robin"
           ? "threshold not used"
           : autoSwitchThreshold > 0
           ? (strategy === "fill-first"

package/src/cli/account.ts

@@ -52,7 +52,7 @@ const ACCOUNT_USAGE = `Usage:
   ocx account pause <provider> <account-id|alias|main> [--json]
   ocx account resume <provider> <account-id|alias|main> [--json]
   ocx account pause-exhausted <provider> [--json]
-  ocx account strategy <provider> [<quota|round-robin|fill-first|reset-first>] [--json]
+  ocx account strategy <provider> [<quota|round-robin|fill-first|least-loaded|reset-first>] [--json]
   ocx account sticky <provider> [<1-100>] [--json]
   ocx account remove <provider> <account-or-key-id|alias|main> --yes [--json]
   ocx account clear-cooldown <provider> <account-id|alias|main> [--json]
@@ -104,7 +104,9 @@ function statusText(row: AccountRow): string {
   // held out -- so printing only one of the two would hide exactly the confusing case (#2703).
   if (row.paused) parts.push("paused");
   if (row.active) parts.push(row.type === "codex" ? "selected" : "active");
-  if (row.needsReauth) parts.push("needs-reauth");
+  if (row.needsReauth && !(row.provider === "kiro" && row.skipReason === "needs_reauth")) parts.push("needs-reauth");
+  if (row.provider === "kiro" && row.autoSelectable === false)
+    parts.push(row.skipReason ? `not-auto-selected(${row.skipReason})` : "not-auto-selected");
   if (row.validationPending) parts.push("validation-pending");
   if (row.selectionExcludedReason === "plan_excluded") {
     parts.push(`not-auto-selected(plan=${row.selectionExcludedPlan ?? row.plan ?? "unknown"})`);

package/src/cli/capabilities.ts

@@ -386,6 +386,23 @@ export const CAPABILITIES: readonly Capability[] = [
       "Values accepted by `set` are parsed as JSON when valid, so booleans, numbers, arrays, objects, and null can be passed directly.",
     ],
   },
+  {
+    command: ["account", "login"],
+    summary: "Log in to an OAuth provider; Kiro can add a native device account.",
+    routes: [
+      { method: "POST", path: "/api/oauth/login" },
+      { method: "GET", path: "/api/oauth/status" },
+    ],
+    flags: [
+      { name: "--method", value: "string", summary: "For Kiro: builder-id, google, or github device login (add only)." },
+      { name: "--reauth", value: "boolean", summary: "Reauthenticate a selected existing account." },
+      { name: "--id", value: "string", summary: "Account id for reauthentication." },
+      { name: "--no-wait", value: "boolean", summary: "Return after the login flow starts." },
+      { name: "--json", value: "boolean", summary: "Emit flow state as JSON." },
+    ],
+    mutates: true,
+    json: "payload",
+  },
   {
     command: ["account", "history"],
     summary: "Cached quota observations for one stored Codex pool account.",

package/src/cli/claude.ts

@@ -34,6 +34,7 @@ import { aliasForNative, aliasForRoute, legacyAliasForNative, legacyAliasForRout
 import { desktop3pAlias } from "../claude/desktop-3p";
 import { inspectDesktopFirstParty } from "../claude/desktop-first-party";
 import { isClaudeInterceptProxyUrl, type ClaudeInterceptSettingsState } from "../claude/intercept/settings";
+import { withoutSiblingMarker } from "../codex/sibling-start";
 
 export interface ClaudeLaunchEnv {
   [key: string]: string | undefined;
@@ -506,7 +507,8 @@ export async function ensureProxyForClaude(deps: ClaudeProxyEnsureDeps = {}): Pr
     detached: true,
     stdio: "ignore",
     windowsHide: true,
-    env: withProcessRuntimeProvenance({ ...process.env, OCX_SERVICE: "1" }),
+    // An ordinary owner: a stray sibling marker would otherwise mark it before any probe.
+    env: withProcessRuntimeProvenance(withoutSiblingMarker({ ...process.env, OCX_SERVICE: "1" })),
   });
   child.unref();
   const deadline = Date.now() + 8_000;

package/src/cli/dispatch.ts

@@ -21,7 +21,9 @@ import {
   localClientSkipMessage,
   setIntegrationEnabled,
   shouldSyncCodexOnStart,
+  type LocalClientSkipReason,
 } from "../codex/desired-state";
+import { siblingSkipMessage } from "../codex/sibling-start";
 import { syncModelsToCodex } from "../codex/sync";
 import { collectOrcaCodexHomeDiagnostic } from "../codex/home";
 import { restoreNativeCodexAsync, type CodexNativeRestoreResult } from "../codex/inject";
@@ -692,13 +694,15 @@ const commandRunners: Record<string, CommandRunner> = {
     switch (deps.args[1]) {
       case "install": {
         const r = installCodexShim();
+        const { healthy, summary } = diagnoseCodexShim();
         const { collectCodexShimReadinessWarnings } = await import("./codex-shim-readiness");
-        const warnings = diagnoseCodexShim().healthy
+        const warnings = healthy
           ? collectCodexShimReadinessWarnings()
           : [];
         console.log(`${r.installed && warnings.length === 0 ? "✅ " : "⚠️  "}${r.message}`);
         for (const warning of warnings) console.warn(`   ${warning}`);
-        break;
+        if (!healthy) console.error(`Codex shim installation is unhealthy: ${summary}`);
+        return healthy ? 0 : 1;
       }
       case "status":
         console.log(codexShimStatus());
@@ -999,7 +1003,7 @@ export const DISPATCH_ALIASES: ReadonlyMap<string, string> = aliasTargets;
 /** Resolve the runner key for a command, following registry aliases to the
  * canonical runner. Returns undefined when the command is unknown. */
 /** What `handleStart` does about a live proxy it found before binding. */
-export type StartOwnerDecision = "refuse" | "service-stay-out" | "sibling";
+export type StartOwnerDecision = "refuse" | "service-stay-out" | "sibling" | "await-parent";
 
 /**
  * Pure decision for `handleStart` when the pre-bind probe found a live proxy.
@@ -1011,21 +1015,74 @@ export type StartOwnerDecision = "refuse" | "service-stay-out" | "sibling";
  * decision allows isolated homes on one machine to remain independent.
  * The service wrapper always passes the configured port and keeps its exact
  * stay-out-of-the-way semantics: it never takes the sibling path.
+ *
+ * `"await-parent"` comes first and only for an exact pid match: the live proxy is the draining
+ * process that spawned this start as its restart replacement (`OCX_RESTART_PARENT_PID`, already
+ * checked against the real parent pid). Refusing it would leave no proxy once that parent exits,
+ * so the caller waits for it instead (`src/cli/restart-handoff.ts`). Every other owner, and a
+ * live proxy whose pid could not be verified, keeps the table above.
  */
 export function decideStartWithLiveOwner(input: {
   livePort: number;
   requestedPort: number | undefined;
   ocxService: string | undefined;
+  livePid?: number | null;
+  restartParentPid?: number | null;
 }): StartOwnerDecision {
+  if (input.restartParentPid != null && input.livePid === input.restartParentPid) return "await-parent";
   const sibling = input.requestedPort !== undefined
     && input.requestedPort !== input.livePort
-    // Only the exact "1" sentinel is service context — the same check syncCleanup
+    // Only the exact "1" sentinel is service context — the same check the exit teardown
     // uses — so an env value like "0" or "false" cannot reach the stay-out path.
     && input.ocxService !== "1";
   if (sibling) return "sibling";
   return input.ocxService === "1" ? "service-stay-out" : "refuse";
 }
 
+/** Which shared client state `handleStart`'s exit cleanup tears down. */
+export interface StartExitTeardown {
+  revertSystemEnv: boolean;
+  restoreNativeCodex: boolean;
+  stripGrokConfig: boolean;
+}
+
+/**
+ * Pure exit-teardown decision for `handleStart`'s `syncCleanup`.
+ *
+ * A sibling instance tears down nothing: the Codex routing, the Grok fence and the system env
+ * belong to the live proxy it runs beside, and restoring them would take Codex off a proxy that
+ * is still serving it (`src/codex/sibling-start.ts`). A dashboard drain-and-restart (#563) keeps
+ * everything for the replacement process. Under a service manager — only the exact `"1"`
+ * sentinel — a crash/respawn keeps routing and the fence, and only the environment comes down.
+ * The caller still applies its own external-provider and service-ownership checks.
+ */
+export function decideStartExitTeardown(input: {
+  sibling: boolean;
+  recycling: boolean;
+  ocxService: string | undefined;
+}): StartExitTeardown {
+  if (input.sibling || input.recycling) {
+    return { revertSystemEnv: false, restoreNativeCodex: false, stripGrokConfig: false };
+  }
+  const preserveRouting = input.ocxService === "1";
+  return { revertSystemEnv: true, restoreNativeCodex: !preserveRouting, stripGrokConfig: !preserveRouting };
+}
+
+/**
+ * The one startup line for "nothing was written to Codex".
+ *
+ * Three very different facts reach it: the user's own OFF switch, a hub declining to rewrite its
+ * own local clients, and a sibling instance leaving the live proxy's routing alone. Printing the
+ * toggle's wording for the gate is what made operators hunt for a switch they never set (#4236).
+ * `port` is the sibling's own bound port, named in its line.
+ */
+export function startupLeftCodexNativeLine(reason: LocalClientSkipReason, port?: number): string {
+  if (reason === "sibling") return `   ${siblingSkipMessage(port)}`;
+  return reason === "hub-gated"
+    ? `   ${HUB_GATED_SKIP_MESSAGE} Startup left Codex native.`
+    : "   Codex integration OFF; startup left Codex native.";
+}
+
 /** What `chooseListenPort` does when the preferred port stayed busy through prefer-retry. */
 export type BusyPreferredPortDecision =
   | "hop"
@@ -1057,7 +1114,7 @@ export type BusyPreferredPortDecision =
  *
  * Service-wrapper context keeps the semantics `decideStartWithLiveOwner` gives it: a
  * healthy proxy on the port means the port is served, and the wrapper's
- * `if %ERRORLEVEL% NEQ 0` loop must see a zero exit rather than respawn every 5 seconds.
+ * retry loop must receive the intentional stay-out signal rather than respawn every 5 seconds.
  */
 export function decideBusyPreferredPort(input: {
   preferredPort: number;