@bitkyc08/opencodex 2.83.0 → 2.86.0

package/src/types/config.ts

@@ -30,6 +30,11 @@ export interface OcxProtocolsConfig {
     managedMessagesNativeOAuth?: boolean;
     /** Chat and Messages clients are encoded directly from adapter events. */
     directEncoders?: boolean;
+    /**
+     * Chat requests to a concrete Google Antigravity route decode straight into the IR and are
+     * answered through the direct encoders, with no internal Responses body in either direction.
+     */
+    antigravityDirect?: boolean;
     /** Compare the dispatch plan with the observed path; never sends a second request. */
     shadowPlan?: boolean;
   };
@@ -519,6 +524,11 @@ export interface OcxConfig {
   skills?: OcxSkillsConfig;
   /** Opt-in process-local aggregate request metrics on the authenticated management plane. */
   metricsExport?: { enabled?: boolean };
+  /**
+   * Opt-in recovery of a managed service proxy that stays alive but stops answering /healthz:
+   * a separate sentinel process terminates it so its supervisor restarts it (#6671).
+   */
+  serviceHealthRecovery?: { enabled?: boolean };
   /** Opt in to one identical-turn retry when a Responses completion has no text or tool call. */
   emptyCompletionRetry?: boolean;
   /** Suppress allowlisted client-facing Codex transport hints; provider enforcement is unchanged. */
@@ -576,12 +586,13 @@ export interface OcxConfig {
   /**
    * Opt-in Ultra Fast service tier, default off.
    *
-   * This does NOT synthesize an `ultrafast` row: `src/codex/data/upstream-models.json`
-   * advertises only `priority`, and PR #2994 was closed precisely because a catalog row
-   * the wire cannot honor is a picker entry that lies. What the flag turns on is honesty
-   * about a tier the operator supplies themselves — the catalog stops stripping an
-   * `ultrafast` the user configured, and the request path names it instead of recording
-   * "no fast tier was requested".
+   * On native GPT-6 Astra and GPT-6.1 Sol rows (bare and account-bound), the flag adds the
+   * Ultrafast speed choice OpenAI documents for those two models, so the Codex picker offers
+   * it even though `model_catalog_json` replaces ChatGPT's live, plan-aware model list
+   * (`src/codex/catalog/native-ultrafast.ts`). On routed rows it still never invents a tier:
+   * it keeps an `ultrafast` the operator configured from being stripped on regeneration
+   * (PR #2994 was closed for adding one the wire could not honor). Turning it off withdraws
+   * the generated native tier on the next catalog write.
    */
   ultraFastTier?: boolean;
   /**
@@ -594,6 +605,13 @@ export interface OcxConfig {
   codexMainAccountHardLock?: boolean;
   /** Per-window percentages: short defaults to 90, long to 98; integers 80..100, short <= long. */
   codexMainAccountHardLockThresholds?: { short?: number; long?: number };
+  /**
+   * Who refreshes the native main ChatGPT login in CODEX_HOME (#2999). "codex" asks the Codex
+   * binary through app-server `getAuthStatus` and never writes auth.json; "opencodex" keeps the
+   * guarded writer. Absent means "codex" when a Codex binary at or above the supported version
+   * is found, otherwise "opencodex". "codex" also falls back when no such binary exists.
+   */
+  nativeMainRefresh?: "codex" | "opencodex";
   /** Explicit top-level deletion intent used by stale whole-config rebases. */
   configRebaseProvenance?: OcxConfigRebaseProvenance | Record<string, unknown>;
   /** OpenAI provider-contract migration marker (v2 = single `openai` provider with account mode). */
@@ -765,6 +783,8 @@ export interface OcxConfig {
   };
   /** Opt-in failure-only recovery; never replaces the initial compaction model. */
   compactionRecovery?: { enabled: boolean; model: string; allowDevinInvalidArgument?: boolean };
+  /** Explicit opt-in; resumes Observe only using an existing trusted certificate and endpoints. */
+  desktopCompatibility?: { startOnProxyStart: boolean };
   /**
    * Destination model for Codex's own memory pipeline, per phase
    * (src/server/responses/memory-models.ts).
@@ -1023,6 +1043,16 @@ export interface OcxConfig {
   cacheRetention?: "none" | "short" | "long";
   /** Web-search sidecar: route web_search for non-OpenAI models through a gpt-mini via ChatGPT passthrough. */
   webSearchSidecar?: OcxWebSearchSidecarConfig;
+  /**
+   * Advisor sidecar: an OpenCodex-owned expert consultation runtime. The proxy injects a synthetic
+   * `advisor` tool into routed worker turns, executes the configured expert model itself (loopback
+   * through the normal routing authority, so the advisor may be ANY routable provider/model), and
+   * reinjects the advice so the original worker continues. `policy: "preflight"` additionally
+   * attempts one automatic consultation per task without worker cooperation, once the task has
+   * produced orientation evidence. Task context is sent only after
+   * `contextSharingConsent` is the current version; `enabled` does not grant that consent.
+   */
+  advisor?: OcxAdvisorConfig;
   /** Vision sidecar: describe images via a gpt vision model so text-only models can "see" them. */
   visionSidecar?: OcxVisionSidecarConfig;
   /** /v1/images relay for codex's built-in image_gen tool. */
@@ -1547,6 +1577,38 @@ export interface OcxVisionSidecarConfig {
   timeoutMs?: number;
 }
 
+/**
+ * Advisor sidecar configuration. Kept deliberately small for PR1: no adaptive trigger knobs
+ * (failedValidations / noProgressCycles / semanticClassifier) — those belong to a later PR.
+ */
+export interface OcxAdvisorConfig {
+  /** Master switch. Default: false — the advisor stays off the request path entirely. */
+  enabled?: boolean;
+  /**
+   * The expert model consulted by the sidecar. Any model string the routing authority accepts:
+   * a bare native model ("gpt-6-astra"), an explicit "provider/model" ("anthropic/claude-...",
+   * "xai/grok-..."), or an account-qualified native model ("<namespace>/gpt-6-astra").
+   */
+  model?: string;
+  /** Reasoning effort for the advisor call. Validated against the canonical effort ladder. */
+  effort?: "low" | "medium" | "high" | "xhigh" | "max" | "ultra";
+  /**
+   * When the advisor is consulted. "manual" (default): only when the worker explicitly calls the
+   * synthetic `advisor` tool. "preflight": OpenCodex additionally attempts one automatic
+   * consultation per task once the task has produced orientation evidence (an assistant tool call
+   * or a tool result after the latest user message).
+   */
+  policy?: "manual" | "preflight";
+  /** Advisor fetch timeout (ms). Default 120000. */
+  timeoutMs?: number;
+  /**
+   * Operator consent to send task conversation and tool results to the configured Advisor
+   * provider. Only `"v1"` is current. Absent or any other value means the runtime must not
+   * send task context. `enabled: true` does not grant this, and upgrades do not write it.
+   */
+  contextSharingConsent?: "v1";
+}
+
 export interface OcxWebSearchSidecarConfig {
   /** Explicit Anthropic account pool; unset inherits the request's instance. */
   anthropicInstance?: AnthropicInstanceId;

package/src/types/provider.ts

@@ -622,6 +622,11 @@ export interface OcxProviderConfig {
   contextWindow?: number;
   /** Per-model fallback when context metadata is absent; otherwise caps the reported window. */
   modelContextWindows?: Record<string, number>;
+  /**
+   * Custom providers only, default off: fill a missing context window from bundled model-ID
+   * metadata before the Context cap / 128k fallback. An estimate, not verified relay capacity.
+   */
+  inferContextWindow?: boolean;
   /** Per-model Copilot upstream tier; only the github-copilot route sends it. */
   modelContextTiers?: Record<string, "default" | "long_context">;
   /** Model-specific Codex catalog input modalities, e.g. ["text"] or ["text", "image"]. */
@@ -639,6 +644,8 @@ export interface OcxProviderConfig {
    * Responses `max_output_tokens`. Adapters still let an explicit request win.
    */
   defaultMaxOutputTokens?: number;
+  /** Opt-in Azure Responses floor for explicit positive output budgets; may raise the caller cap. */
+  minMaxOutputTokens?: number;
   /** Model-specific fallback output token budgets. Exact/model-pattern entries beat the provider default. */
   modelMaxOutputTokens?: Record<string, number>;
   /**

package/src/types/request.ts

@@ -164,6 +164,19 @@ export interface OcxParsedRequest {
    * provider-private continuation caches again on every later turn.
    */
   _contextCompactionBoundary?: boolean;
+  /**
+   * Core-owned registration slot for the optional advisor subsystem (src/advisor). Set per request
+   * by the sidecar planner, never at module load: the core Responses path only sees this
+   * structural shape, so an advisor-disabled install imports no advisor module. When present, the
+   * adapter delivery wraps the worker's event stream with it — the guard holds synthetic
+   * `advisor` tool calls, consults the configured expert model, and re-dispatches the worker.
+   */
+  _advisorGuard?: (options: {
+    parsed: OcxParsedRequest;
+    firstEvents: AsyncIterable<AdapterEvent>;
+    /** One bounded worker continuation re-dispatch (same machinery as the terminal guard). */
+    continuation: (parsed: OcxParsedRequest) => AsyncIterable<AdapterEvent> | Promise<AsyncIterable<AdapterEvent>>;
+  }) => AsyncGenerator<AdapterEvent>;
 }
 
 export interface OcxContext {
@@ -441,6 +454,8 @@ export type AdapterEvent =
       /** Responses error type and code when the adapter has a structured provider failure. */
       errorType?: string;
       code?: string;
+      /** Proxy-internal permission to consider API-key recovery; never serialized. */
+      apiKeyRecovery?: true;
       retryable?: boolean;
       /**
        * Proxy-internal, never serialized: the upstream failed the turn before producing text or a

package/src/types/tools.ts

@@ -25,6 +25,8 @@ export interface OcxTool {
   imageGeneration?: boolean;
   /** Synthetic video_gen tool: executed by the xAI video bridge sidecar. */
   videoGeneration?: boolean;
+  /** Synthetic advisor tool: the model's call is intercepted by the advisor sidecar (see src/advisor), never relayed to the client. */
+  advisor?: boolean;
 }
 
 /**

package/src/update/async-check.ts

@@ -51,7 +51,7 @@ export async function latestVersionAsync(
   installer: Installer,
   deps: AsyncLookupDeps = defaultDeps,
 ): Promise<string | null> {
-  if (installer === "source" || installer === "mise") return null;
+  if (installer === "source" || installer === "standalone" || installer === "mise") return null;
   let owner: PnpmGlobalOwner | null | undefined;
   try { owner = installer === "pnpm" ? await deps.ownerFn() : undefined; }
   catch { return null; }

package/src/update/badge.ts

@@ -44,11 +44,11 @@ export function readUpdateBadge(deps: UpdateBadgeDeps = defaultDeps): UpdateBadg
     latestVersion: null,
     channel,
     installer,
-    canUpdate: installer !== "source" && installer !== "mise",
+    canUpdate: installer !== "source" && installer !== "standalone" && installer !== "mise",
     unknown: true,
   };
   // A source checkout has nothing to compare against, so "unknown" is not useful there.
-  if (installer === "source" || current === "?" || isSourceBuildVersion(current)) {
+  if (installer === "source" || installer === "standalone" || current === "?" || isSourceBuildVersion(current)) {
     return { ...base, canUpdate: false, unknown: false };
   }
 

package/src/update/index.ts

@@ -17,13 +17,10 @@ import { unprivilegedOwnershipMutationEnvironment } from "../service/ownership-m
 import { withUpdateOwnershipLease, readUpdateRuntimeTarget } from "./ownership-transaction";
 import { npmInvocation } from "./npm-invocation.mjs";
 import { pnpmInvocation, pnpmInvocationForPath, resolvePnpmCommands } from "./pnpm-invocation.mjs";
-import {
-  detectInstallFromPath,
-  detectInstallOwnershipFromPath,
-} from "./install-detection.mjs";
+import { detectInstallOwnershipFromPath } from "./install-detection.mjs";
 import type {
   DetectedInstall,
-  InstallOwnership,
+  InstallOwnership as PackageInstallOwnership,
   MiseInstallOwner,
 } from "./install-detection.d.mts";
 import {
@@ -42,8 +39,13 @@ import { handoffWindowsTrayForUpdate, planWindowsTrayUpdate } from "./tray-updat
 import { withProcessRuntimeProvenance } from "../lib/bun-runtime";
 import { withoutSiblingMarker } from "../codex/sibling-start";
 import { packageVersion } from "../lib/package-version";
+import { isStandaloneModuleUrl } from "../lib/standalone";
 import { selfLaunchArgv } from "../lib/self-launch-argv";
 import { PNPM_READ_CWD, withPnpmCommandCwd, pnpmReadEnvironment } from "./pnpm-read-policy.mjs";
+import {
+  freshServingPid, hasRestartableServiceManager, readParentPid, readServiceManagerPid, restartServiceManagerJob,
+  supervisionVerdict, unsettledManagerWarning, unsupervisedRuntimeWarning,
+} from "./supervised-recovery.mjs";
 
 /**
  * A `codex-history-backup-*.json` surviving a stop means the native-history restore was
@@ -62,18 +64,21 @@ export function historyRestoreIncomplete(configDir = getConfigDir()): boolean {
 export const PKG = "@bitkyc08/opencodex";
 const HERE = dirname(fileURLToPath(import.meta.url)); // .../opencodex/src/update
 
-export type Installer = DetectedInstall;
+export type Installer = DetectedInstall | "standalone";
+export const STANDALONE_UPDATE_HINT = "Update via OpenCodex Desktop (Check for Updates…) or reinstall the standalone binary from GitHub Releases.";
 export type Channel = "latest" | "preview";
-export type { InstallOwnership, MiseInstallOwner };
+export type InstallOwnership = PackageInstallOwnership | { installer: "standalone" };
+export type { MiseInstallOwner };
 
 /** Infer how opencodex is installed from the running module's path. */
-export function detectInstall(): Installer {
-  return detectInstallFromPath(HERE, { exists: existsSync });
+export function detectInstall(moduleUrl = import.meta.url): Installer {
+  return detectInstallOwnership(moduleUrl).installer;
 }
 
 /** Resolve installer ownership and verified mise update guidance for this package. */
-export function detectInstallOwnership(): InstallOwnership {
-  return detectInstallOwnershipFromPath(HERE, { exists: existsSync });
+export function detectInstallOwnership(moduleUrl = import.meta.url): InstallOwnership {
+  if (isStandaloneModuleUrl(moduleUrl)) return { installer: "standalone" };
+  return detectInstallOwnershipFromPath(dirname(fileURLToPath(moduleUrl)), { exists: existsSync });
 }
 
 export function miseUpdateCommand(
@@ -234,6 +239,7 @@ export function registrySpawnTarget(
   args: readonly string[],
   owner?: PnpmGlobalOwner,
 ): SpawnTarget | null {
+  if (installer === "standalone") return null;
   // A pnpm command without an owner would silently fall back to the first PATH
   // candidate. That is unsafe when multiple PNPM_HOME installations expose the
   // same version, so registry queries use the same hard binding as mutation.
@@ -310,6 +316,7 @@ export function latestVersion(
 
 /** The global-install command opencodex would run to update on this channel. */
 export function updateCommand(installer: Installer, tag: Channel, resolvedVersion?: string | null): { bin: string; args: string[] } {
+  if (installer === "standalone") throw new Error(STANDALONE_UPDATE_HINT);
   if (installer === "mise") {
     throw new Error("mise-owned installations must be upgraded through mise");
   }
@@ -427,6 +434,12 @@ export async function runUpdate(): Promise<void> {
     return;
   }
 
+  if (installer === "standalone") {
+    console.error(STANDALONE_UPDATE_HINT);
+    process.exitCode = 1;
+    return;
+  }
+
   if (installer === "source") {
     console.log("Running from a source checkout — update with:  git pull && bun install");
     return;
@@ -551,7 +564,8 @@ export async function runUpdate(): Promise<void> {
     return before?.owner === after?.owner && before?.installId === after?.installId
       && before?.consentGeneration === after?.consentGeneration;
   };
-  const startProxyDirectly = async (): Promise<boolean> => {
+  /** `"vetoed"`: another owner holds the runtime, so not starting is the correct outcome. */
+  const startProxyDirectly = async (): Promise<boolean | "vetoed"> => {
     const ownership = await resolvedRuntimeOwnership();
     const supervision = observeSupervision();
     const plan = planUpdateRuntimeHandling({ ...ownership, serviceInstalled: false, supervision });
@@ -559,7 +573,7 @@ export async function runUpdate(): Promise<void> {
       console.warn(supervision
         ? "OpenCodex Desktop supervises the proxy; no CLI runtime was restored."
         : plan.notice);
-      return false;
+      return "vetoed";
     }
     if (!postUpdateLauncherUsable || !existsSync(postUpdateLauncher)) return false;
     // An ordinary owner: a stray sibling marker would otherwise mark it before any probe.
@@ -582,6 +596,51 @@ export async function runUpdate(): Promise<void> {
     console.warn("⚠️  Recovery did not report a healthy proxy before its deadline; run 'ocx service repair' or 'ocx start'.");
     return false;
   };
+  // #7043: before any detached start, ask launchd/systemd to restart the job it already holds,
+  // and count it only when the serving proxy is that job. Runs unleased: the manager's child
+  // cannot join this lease (#5760). `"unsettled"` means the manager may still finish the restart,
+  // so no competing proxy may be started.
+  const restartThroughServiceManager = async (): Promise<"supervised" | "failed" | "unsettled"> => {
+    if (!hasRestartableServiceManager()) return "failed";
+    console.log("🔁 Asking the service manager to restart the background service...");
+    const before = readUpdateRuntimeTarget(getRuntimePortPath(), capturedListen.hostname);
+    const staleRecordPid = before.kind === "target" ? before.target.pid : null;
+    const restarted = restartServiceManagerJob();
+    const unsettled = !restarted.ok && restarted.unsettled === true;
+    let verdict: ReturnType<typeof supervisionVerdict> | { kind: "failed"; reason: string };
+    if (!restarted.ok && !unsettled) {
+      verdict = { kind: "failed", reason: restarted.reason };
+    } else {
+      let servingPid: number | null = null;
+      const deadline = Date.now() + 30_000;
+      while (servingPid === null && Date.now() < deadline) {
+        const current = readUpdateRuntimeTarget(getRuntimePortPath(), capturedListen.hostname);
+        if (current.kind === "target" && current.target.port === capturedListen.port
+          && freshServingPid(current.target.pid, staleRecordPid) !== null
+          && await proxyIdentityAt(current.target.port, { hostname: current.target.hostname, expectedPid: current.target.pid },
+            { timeoutMs: 1500, deadlineAt: deadline, attempts: 1 })) servingPid = current.target.pid;
+        else await Bun.sleep(Math.min(100, Math.max(0, deadline - Date.now())));
+      }
+      verdict = supervisionVerdict({ servingPid, managerPid: readServiceManagerPid(), parentPid: pid => readParentPid(pid) });
+    }
+    if (verdict.kind === "supervised") {
+      console.log(`✅ Proxy is healthy on port ${capturedListen.port} under the service manager (pid ${verdict.managerPid}).`);
+      return "supervised";
+    }
+    if (unsettled) {
+      console.warn(unsettledManagerWarning(capturedListen.port));
+      return "unsettled";
+    }
+    console.warn(`⚠️  The service manager did not recover a supervised proxy: ${verdict.reason}.`);
+    return "failed";
+  };
+  /** Direct start as the last resort for a managed install: never reported as full recovery. */
+  const startUnsupervisedFallback = async (): Promise<"vetoed" | "started" | "failed"> => {
+    const started = await startProxyDirectly();
+    if (started === "vetoed") return "vetoed";
+    if (started) console.warn(unsupervisedRuntimeWarning(capturedListen.port));
+    return started ? "started" : "failed";
+  };
   const recoverStoppedRuntime = async (reason: string): Promise<void> => {
     try {
       const planRecovery = async () => {
@@ -617,6 +676,12 @@ export async function runUpdate(): Promise<void> {
           env: mutation.controlEnvironment({ ...process.env, OCX_BAKE_PORT: String(capturedListen.port) }),
         });
         if (service.status !== 0 || !isServiceViable()) {
+          // Ownership may have moved while the refresh ran unleased; only a recovery plan that
+          // still names the service may restart the manager's job.
+          if ((await planRecovery()).action === "service") {
+            const managed = await restartThroughServiceManager();
+            if (managed !== "failed") return;
+          }
           // The refresh ran unleased; a claim could have landed meanwhile, so take
           // the lease back before re-reading ownership and authorizing a direct start.
           mutation.reacquire();
@@ -626,7 +691,7 @@ export async function runUpdate(): Promise<void> {
             liveness: currentPackageRuntimeLiveness(), serviceInstalled: false,
             launcherUsable: postUpdateLauncherUsable && existsSync(postUpdateLauncher), hadRuntimeState,
           });
-          if (fallback.action === "direct") await startProxyDirectly();
+          if (fallback.action === "direct") await startUnsupervisedFallback();
           else console.warn("⚠️  Service recovery was not confirmed; no second proxy was started.");
         }
       } else if (recovery.action === "direct") {
@@ -902,6 +967,12 @@ export async function runUpdate(): Promise<void> {
           }
         }
         if (!serviceRefreshed || !serviceViable) {
+          // #7043: the manager first. Only a proxy it owns counts as recovered; everything
+          // below this line leaves an unsupervised runtime and exits non-zero.
+          if (!await mayRefresh()) return;
+          const managed = await restartThroughServiceManager();
+          if (managed === "supervised") return;
+          if (managed === "unsettled") return 1;
           // Repair normally avoids elevation for a healthy scheduler task, but a stale
           // definition may require guarded create/elevation. It can also fail — or exit 0
           // while leaving stale/missing assets that never start
@@ -956,7 +1027,9 @@ export async function runUpdate(): Promise<void> {
             console.warn(process.platform === "win32"
               ? "   Run 'ocx service repair' to refresh the background service."
               : "   Run 'ocx service repair' to refresh the background service and see why it failed.");
-            if (await startProxyDirectly()) console.log(`✅ Proxy is healthy on port ${capturedListen.port}.`);
+            // An ownership veto is the correct outcome, not a degraded one.
+            if (await startUnsupervisedFallback() === "vetoed") return;
+            return 1;
           }
         }
       } finally {

package/src/update/job-supervised-restart.ts

@@ -0,0 +1,107 @@
+import { readRuntimePort } from "../config/process-state";
+import { proxyIdentityAt } from "../server/proxy-liveness";
+import {
+  freshServingPid, hasRestartableServiceManager, readParentPid, readServiceManagerPid, restartServiceManagerJob,
+  supervisionVerdict, unsettledManagerWarning, unsupervisedRuntimeWarning,
+} from "./supervised-recovery.mjs";
+
+/**
+ * Manager-first recovery for the dashboard update worker (#7043), the `src/update/job.ts` side of
+ * what #7074 did for `ocx update`. When the post-update service refresh fails, is not viable, or
+ * never serves, the worker asks launchd/systemd to restart the job it already holds before any
+ * detached `ocx start`, and counts it only when the serving proxy is that job. It lives beside the
+ * worker because `src/update/job.ts` sits at the repository's size cap.
+ */
+export type ManagerRestartOutcome = "supervised" | "failed" | "unsettled";
+
+export interface ManagerRestartDeps {
+  hasManager?: () => boolean;
+  restartJob?: () => { ok: true } | { ok: false; reason: string; unsettled?: true };
+  managerPid?: () => number | null;
+  parentPid?: (pid: number) => number | null;
+  readRecord?: () => { pid: number; port: number; hostname?: string } | null;
+  probeServing?: (port: number, hostname: string, pid: number, deadlineAt: number) => Promise<boolean>;
+  now?: () => number;
+  sleepMs?: (ms: number) => Promise<void>;
+  deadlineMs?: number;
+}
+
+export type ManagerRestartFn = (
+  target: { port: number; hostname: string; release?: () => void },
+  log: (line: string) => void,
+) => Promise<ManagerRestartOutcome>;
+
+/**
+ * Ask the manager to restart its job and prove the serving proxy is that job. Never throws.
+ * `release` frees the update lease first: the manager's child cannot join it (#5760), and the
+ * worker reaches this point without a release when it skipped the service repair.
+ */
+export async function restartServiceManagerAfterUpdate(
+  target: { port: number; hostname: string; release?: () => void },
+  log: (line: string) => void,
+  deps: ManagerRestartDeps = {},
+): Promise<ManagerRestartOutcome> {
+  if (!(deps.hasManager ?? hasRestartableServiceManager)()) return "failed";
+  target.release?.();
+  log("Asking the service manager to restart the background service...");
+  const readRecord = deps.readRecord ?? (() => readRuntimePort());
+  const probe = deps.probeServing ?? (async (port: number, hostname: string, pid: number, deadlineAt: number) => (
+    !!(await proxyIdentityAt(port, { hostname, expectedPid: pid }, { timeoutMs: 1500, deadlineAt, attempts: 1 }))
+  ));
+  const now = deps.now ?? (() => Date.now());
+  const sleep = deps.sleepMs ?? ((ms: number) => new Promise<void>(r => setTimeout(r, ms)));
+  const staleRecordPid = readRecord()?.pid ?? null;
+  const restarted = (deps.restartJob ?? restartServiceManagerJob)();
+  const unsettled = !restarted.ok && restarted.unsettled === true;
+  let verdict: ReturnType<typeof supervisionVerdict>;
+  if (!restarted.ok && !unsettled) {
+    // The refusal reason is the manager's stderr: external text, so it never reaches the persisted job.
+    verdict = { kind: "failed", reason: "the service manager refused the restart" };
+  } else {
+    let servingPid: number | null = null;
+    const deadline = now() + (deps.deadlineMs ?? 30_000);
+    while (servingPid === null && now() < deadline) {
+      const current = readRecord();
+      if (current && current.port === target.port && freshServingPid(current.pid, staleRecordPid) !== null
+        && await probe(current.port, current.hostname ?? target.hostname, current.pid, deadline)) servingPid = current.pid;
+      else await sleep(Math.min(100, Math.max(0, deadline - now())));
+    }
+    verdict = supervisionVerdict({
+      servingPid,
+      managerPid: (deps.managerPid ?? readServiceManagerPid)(),
+      parentPid: deps.parentPid ?? (pid => readParentPid(pid)),
+    });
+  }
+  if (verdict.kind === "supervised") {
+    log(`Proxy is healthy on port ${target.port} under the service manager (pid ${verdict.managerPid}).`);
+    return "supervised";
+  }
+  if (unsettled) return "unsettled";
+  log(`The service manager did not recover a supervised proxy: ${verdict.reason}.`);
+  return "failed";
+}
+
+/** Job patch and log line when the manager may still finish its restart: no second proxy is started. */
+export function unsettledManagerRestartFailure(port: number) {
+  const patch = {
+    status: "failed" as const,
+    restarted: false,
+    error: "the service manager did not finish restarting the proxy; no second proxy was started",
+  };
+  return [patch, oneLine(unsettledManagerWarning(port))] as const;
+}
+
+/** Job patch and log line when only a detached fallback ran for a service-managed install. */
+export function unsupervisedRestartFailure(port: number) {
+  const patch = {
+    status: "failed" as const,
+    restarted: false,
+    error: `the proxy on port ${port} is running UNSUPERVISED after the update; run 'ocx service repair'`,
+  };
+  return [patch, oneLine(unsupervisedRuntimeWarning(port))] as const;
+}
+
+/** The job store withholds multi-line text as possible vendor output, so join the shared warning. */
+function oneLine(text: string): string {
+  return text.split("\n").map(line => line.trim()).join(" ");
+}