@bitkyc08/opencodex 2.84.0 → 2.86.0

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

@@ -7,6 +7,9 @@ import type { ResponsesEffects } from "./response-effects";
 import type { ResponsesSendBudget } from "./request-send-budget";
 import { formatErrorResponse } from "../../bridge";
 import { planWebSearch, buildWebSearchTool, runWithWebSearch } from "../../web-search";
+import { createRegisteredAdvisorPlan } from "./advisor-plan-slot";
+import { ADVISOR_TOOL_NAME } from "./advisor-slot";
+import { buildToolBridgeMaps } from "./collaboration";
 import {
   planImageBridge,
   planVideoBridge,
@@ -30,6 +33,8 @@ import {
 } from "../../oauth/generic-account-failover";
 import { classifyKiroRefusal } from "../../adapters/kiro-refusal";
 import { isNonReplayableResponse } from "../../lib/upstream-retry";
+import { unwrapUpstreamRetryEvidenceError } from "../../codex/auth-context";
+import { AdmissionModelDeniedError, admissionModelDeniedResponse } from "../admission-model-scope";
 import { noteKiroMonthlyRefusal, noteKiroServedSuccess } from "../../providers/kiro-usage";
 import { persistKiroAccountState } from "../../providers/kiro-account-state-disk";
 import { anthropicPoolCooldownResponse, readDisplaySafeErrorText } from "./core-errors";
@@ -60,6 +65,7 @@ export async function executeResponsesSidecars(
     | "inboundWire"
     | "selectedForwardHeaders"
     | "translatorBudget"
+    | "toolBridgeMaps"
     | "rememberKiroDeliveredFinalAnswer"
     | "responseStateOptions"
   >,
@@ -169,6 +175,25 @@ export async function executeResponsesSidecars(
     }
   }
 
+  // Advisor sidecar plan (optional subsystem; null when disabled, unconfigured, or when this
+  // request IS an advisor loopback consultation — the recursion fence). The plan carries
+  // request-scoped state only; preflight keeps fixed policy separate from user-role advice
+  // before the worker is dispatched. Registration seam: the core path sees only
+  // `parsed._advisorGuard`; only an activated factory can load the optional implementation.
+  const advisorPlan = options.advisorInternal === true
+    ? null
+    : await createRegisteredAdvisorPlan({
+      config,
+      workerIdentity: `${route.modelId} (provider ${route.providerName})`,
+      workerModelId: route.modelId,
+      abortSignal: options.abortSignal,
+    });
+  // Preflight only on real worker turns: a routed-compaction turn is a summarization request,
+  // and injecting advice into it would pollute the summary Codex replaces its history with.
+  if (advisorPlan && !routedCompaction) {
+    await advisorPlan.preflightInject(parsed);
+  }
+
   // Image / web-search sidecars: plan once, then dispatch with runTurn-aware priority.
   // Routed-compaction turns must NOT hit the image bridge: compaction clears tools/_webSearch but
   // leaves _imageGeneration, so planImageBridge would activate and return a normal Responses
@@ -198,6 +223,20 @@ 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;
+  // A replacement credential whose Copilot Auto negotiation leaves the key's scope ends the turn.
+  // The loops only see "no rotation" and fail with the original, replayable 429, so the refusal
+  // is held here and answers in place of that failure.
+  let sidecarScopeDenial: AdmissionModelDeniedError | undefined;
+  const noteSidecarScopeDenial = (error: unknown): void => {
+    const refusal = unwrapUpstreamRetryEvidenceError(error);
+    if (refusal instanceof AdmissionModelDeniedError) sidecarScopeDenial ??= refusal;
+  };
+  const sidecarScopeRefusal = (response: Response): Response | undefined => {
+    if (!sidecarScopeDenial || response.ok) return undefined;
+    void response.body?.cancel().catch(() => {});
+    releaseSearchProbeLease();
+    return admissionModelDeniedResponse(sidecarScopeDenial);
+  };
   /** Admit a replacement credential, or leave the loop's original refusal authoritative. */
   const rotateSidecarProviderOn429 = async (
     retryAfter: string | null,
@@ -264,7 +303,8 @@ export async function executeResponsesSidecars(
           return null;
         }
         transportState.genericFailovers += 1;
-      } catch {
+      } catch (error) {
+        noteSidecarScopeDenial(error);
         hop.permit?.release();
         return null;
       }
@@ -284,7 +324,10 @@ export async function executeResponsesSidecars(
     } else if (rotated) {
       route.provider = rotated;
       try { await resolveCopilotSelection(retryParsed ?? parsed); }
-      catch { return null; } // Keep the sidecar's original refusal when replacement negotiation fails.
+      catch (error) { // Keep the sidecar's original refusal when replacement negotiation fails.
+        noteSidecarScopeDenial(error);
+        return null;
+      }
     } 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
@@ -326,7 +369,8 @@ export async function executeResponsesSidecars(
           return null;
         }
         if (route.providerName === "kiro") transportState.genericFailovers += 1;
-      } catch {
+      } catch (error) {
+        noteSidecarScopeDenial(error);
         hop.permit?.release();
         return null;
       }
@@ -527,6 +571,8 @@ export async function executeResponsesSidecars(
         notifyResponseComplete(response);
       },
     });
+    const imgScopeRefusal = sidecarScopeRefusal(imgResponse);
+    if (imgScopeRefusal) return imgScopeRefusal;
     if (imgResponse.body) {
       const imgTurnAc = new AbortController();
       imgTurnAc.signal.addEventListener("abort", cancelResponseCompletion, { once: true });
@@ -622,6 +668,8 @@ export async function executeResponsesSidecars(
         notifyResponseComplete(response);
       },
     });
+    const wsScopeRefusal = sidecarScopeRefusal(loopResponse);
+    if (wsScopeRefusal) return wsScopeRefusal;
     // A routed Anthropic model whose last pool account refused on spent quota fails the loop's
     // first iteration with a generic 429 before any search runs. Answer the usage limit instead,
     // as the main path does (#6991), so Codex stops rather than retrying the whole turn.
@@ -645,5 +693,32 @@ export async function executeResponsesSidecars(
     return wsResponse;
   }
 
+  // Advisor synthetic tool + stream guard: attach ONLY when this function is about to hand the
+  // request back to the normal translated exchange (no sidecar loop claimed the turn, not a
+  // run-turn adapter, not compaction). The web-search/image loops own their own event handling;
+  // run-turn adapters execute their own loop; both would leak the synthetic tool call they
+  // cannot intercept. Preflight (above) still applies to those paths — only the tool does not.
+  if (advisorPlan && !routedCompaction && !transportState.adapter.runTurn && !wsPlan && !imgPlan && !vidPlan) {
+    // A client-declared tool named "advisor" would collide with the synthetic injection (one
+    // wire name, two schemas); the synthetic runtime owns the name for this turn.
+    parsed.context.tools = [
+      ...(parsed.context.tools ?? []).filter(t => !t.advisor && t.name !== ADVISOR_TOOL_NAME),
+      advisorPlan.tool,
+    ];
+    // The advisor tool joined AFTER prepare computed the bridge maps; recompute so the tool is
+    // declared (undeclared-tool guard, tool_choice mapping, schema repair) on this turn.
+    //
+    // Rebuild WITHOUT the budget: prepare already charged every tool in the catalog, and
+    // buildToolBridgeMaps charges each name it registers, so re-passing the budget would bill the
+    // whole catalog a second time and can trip `translation_buffer_limit` for a large MCP catalog.
+    // Charge only the one entry that is genuinely new — the synthetic advisor tool is a bare
+    // function tool, so it retains its wire name and its bare name (collaboration.ts:187, :233).
+    requestState.toolBridgeMaps = buildToolBridgeMaps(parsed);
+    translatorBudget.chargeRetained(new TextEncoder().encode(ADVISOR_TOOL_NAME).byteLength * 2, {
+      kind: "retained_collectors",
+    });
+    advisorPlan.attachGuard(parsed);
+  }
+
   return undefined;
 }

package/src/server/responses/terminal-guard.ts

@@ -170,7 +170,8 @@ export function isTerminalGuardPassthroughOnly(event: AdapterEvent): boolean {
   return event.type === "heartbeat" || event.type === "tool_call_delta";
 }
 
-function mergeUsage(first: OcxUsage | undefined, second: OcxUsage | undefined): OcxUsage | undefined {
+/** Merge two reported usages (canonical Responses convention). Shared with the advisor guard. */
+export function mergeUsage(first: OcxUsage | undefined, second: OcxUsage | undefined): OcxUsage | undefined {
   if (!first) return second;
   if (!second) return first;
   const sumOptional = (key: keyof OcxUsage): number | undefined => {

package/src/server/responses-undeclared-tool-guard.ts

@@ -1,3 +1,4 @@
+import { UNDECLARED_TOOL_CALL_ERROR_CODE } from "../lib/errors";
 import {
   collectAmbiguousDottedAliases,
   dottedAliasIsUnambiguous,
@@ -78,7 +79,7 @@ const NAMELESS_TOOL_SPEC_TYPES = new Set([
 /** An upstream-supplied name reaches the error message; keep it bounded. */
 const MAX_REPORTED_NAME_CHARS = 100;
 
-export const UNDECLARED_TOOL_CALL_ERROR_CODE = "undeclared_tool_call";
+export { UNDECLARED_TOOL_CALL_ERROR_CODE };
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return !!value && typeof value === "object" && !Array.isArray(value);
@@ -370,6 +371,24 @@ export function hasExplicitWireToolCatalog(body: unknown): boolean {
   );
 }
 
+/**
+ * Whether the caller declared an explicitly EMPTY catalog — `tools: []` or an
+ * `additional_tools` item with `tools: []`. Unlike an absent or partial catalog this is an
+ * unambiguous deny-all: no deferred registry can exist under it, so even deferred wires
+ * enforce it. A hosted-only catalog is NOT empty — it still defers like an absent one.
+ */
+export function hasExplicitEmptyToolCatalog(body: unknown): boolean {
+  if (!isPlainObject(body)) return false;
+  if (Array.isArray(body.tools) && body.tools.length === 0) return true;
+  if (!Array.isArray(body.input)) return false;
+  return body.input.some(item =>
+    isPlainObject(item)
+    && item.type === "additional_tools"
+    && Array.isArray(item.tools)
+    && item.tools.length === 0
+  );
+}
+
 /**
  * Evaluates whether an individual output item represents an undeclared tool call.
  *
@@ -703,7 +722,6 @@ function failedBlocks(name: string, newline: string): readonly string[] {
  * @param providerExecutedCallTypes - Call types executed by the provider.
  * @param declaredBare - Explicitly declared bare tool names without namespace provenance.
  * @param declaredCustom - Current bare custom declarations eligible for code-mode recovery.
- * @param enforceDeclaredToolNames - Refuse undeclared calls; normalization remains active when false.
  * @returns An SSE block rewrite function.
  */
 export function createUndeclaredToolCallGuardBlockRewrite(
@@ -712,8 +730,11 @@ export function createUndeclaredToolCallGuardBlockRewrite(
   providerExecutedCallTypes: ProviderExecutedCallTypes = EMPTY_PROVIDER_EXECUTED_CALL_TYPES,
   declaredBare?: ReadonlySet<string>,
   declaredCustom?: ReadonlySet<string>,
-  enforceDeclaredToolNames = true,
+  options?: { refuseUndeclared?: boolean },
 ): SseBlockRewrite {
+  // Deferred-catalog wires (Chat/Anthropic) keep the default-namespace normalization — the
+  // client can only resolve the bare name it declared — while the refusal itself stays off.
+  const refuse = options?.refuseUndeclared !== false;
   let tripped = false;
   return (block: string) => {
     if (tripped) return [];
@@ -725,12 +746,12 @@ export function createUndeclaredToolCallGuardBlockRewrite(
     } catch {
       return [block];
     }
-    const name = enforceDeclaredToolNames
-      ? undeclaredToolCallName(parsed, declared, declaredNamelessClientCallTypes, providerExecutedCallTypes, declaredBare, declaredCustom)
-      : undefined;
-    if (name !== undefined) {
-      tripped = true;
-      return failedBlocks(name, block.includes("\r\n") ? "\r\n" : "\n");
+    if (refuse) {
+      const name = undeclaredToolCallName(parsed, declared, declaredNamelessClientCallTypes, providerExecutedCallTypes, declaredBare, declaredCustom);
+      if (name !== undefined) {
+        tripped = true;
+        return failedBlocks(name, block.includes("\r\n") ? "\r\n" : "\n");
+      }
     }
     const normalized = normalizeDefaultNamespaceInPayload(parsed, declared, declaredBare);
     if (normalized.changed) {

package/src/server/startup-action-control.ts

@@ -3,6 +3,8 @@ import { execFile } from "node:child_process";
 import { join } from "node:path";
 import { durableBunPath } from "../lib/bun-runtime";
 import { selfLaunchArgv } from "../lib/self-launch-argv";
+import { isDesktopSupervised } from "../lib/system-restart-contract";
+import { withLoginShellPath } from "./login-shell-path";
 import {
   WINDOWS_SCHTASKS_CREATE_ACCESS_DENIED_MARKER,
   isWindowsSchtasksCreateAccessDenied,
@@ -66,6 +68,8 @@ interface StartupInstallLaunch {
   execFile?: typeof execFile;
   /** Overrides Bun's own standalone detection, which a source-mode test cannot flip. */
   isStandaloneExecutable?: boolean;
+  isDesktopSupervised?: () => boolean;
+  withLoginShellPath?: (env: NodeJS.ProcessEnv) => Promise<NodeJS.ProcessEnv>;
 }
 let installLaunch: StartupInstallLaunch = {};
 
@@ -169,7 +173,16 @@ export function installFailureDetail(stdout: string, stderr: string, error: Erro
   return classifyCliInstallFailure(stdout, stderr, error).detail;
 }
 
-function runCliInstall(
+/**
+ * Under OpenCodex Desktop the proxy has the GUI launch PATH, where no user-installed Codex is
+ * visible. The shim installer gets the user's login-shell PATH instead (#6971).
+ */
+async function installChildEnv(action: StartupInstallAction): Promise<NodeJS.ProcessEnv> {
+  if (action !== "install-shim" || !(installLaunch.isDesktopSupervised ?? isDesktopSupervised)()) return process.env;
+  return (installLaunch.withLoginShellPath ?? withLoginShellPath)(process.env);
+}
+
+async function runCliInstall(
   action: StartupInstallAction,
   options?: { repair?: boolean },
 ): Promise<{ stdout: string; stderr: string }> {
@@ -183,13 +196,14 @@ function runCliInstall(
     isStandaloneExecutable: installLaunch.isStandaloneExecutable,
   });
   const run = installLaunch.execFile ?? execFile;
+  const env = await installChildEnv(action);
   return new Promise((resolve, reject) => {
     const timeout = process.platform === "win32" && action === "install-service"
       ? 0
       : 60_000;
     run(bun, argv, {
       encoding: "utf8",
-      env: process.env,
+      env,
       // A fresh Windows scheduler install now owns its UAC prompt inside this CLI
       // transaction. Killing only the CLI at 60s can orphan its elevated schtasks child,
       // which may register the task after the Dashboard has reported failure. Keep the

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

@@ -117,6 +117,7 @@ function conservativeFallback(config: Pick<OcxConfig, "codexAutoStart">): Startu
     serviceSupported: process.platform === "win32" || process.platform === "darwin" || process.platform === "linux",
     shimInstalled: shim.installed,
     shimHealthy: shim.healthy,
+    ...(shim.activationPending ? { shimActivationPending: true } : {}),
     platform: process.platform,
     diagnosticStale: true,
   });

package/src/service/desktop-startup.ts

@@ -122,11 +122,25 @@ function macLoginRegistration(deps: DesktopStartupDeps) {
   }
   const program = /^\s*program = (.+)$/m.exec(loaded)?.[1];
   const loadedPath = /^\s*path = (.+)$/m.exec(loaded)?.[1];
+  // macOS 13+ Background Task Management can take over the user LaunchAgent and resubmit it
+  // through smd; launchctl then names the submitter instead of the plist (#7019). The loaded
+  // job no longer points at the registration, so credit it like an unloaded job: same program,
+  // and the entire registration re-read unchanged.
+  if (program !== undefined && loadedPath !== undefined && SMD_SUBMITTED.test(loadedPath)
+    && /^\s*managed_by = (.+)$/m.exec(loaded)?.[1] === SERVICE_MANAGEMENT && realpathSync(program) === app) {
+    const final = capture();
+    if (!final || JSON.stringify(first) !== JSON.stringify(final)) return { app, proxy, loginEnabled: false };
+    return { app, proxy, loginEnabled: true, loginRegistration: "loaded" as const };
+  }
   const loginEnabled = program !== undefined && realpathSync(program) === app
     && loadedPath !== undefined && realpathSync(loadedPath) === first.registrationPath;
   return { app, proxy, loginEnabled, ...(loginEnabled ? { loginRegistration: "loaded" as const } : {}) };
 }
 
+/** launchctl's `path` for a job Background Task Management resubmitted through smd. */
+const SMD_SUBMITTED = /^\(submitted by smd\.\d+\)$/;
+const SERVICE_MANAGEMENT = "com.apple.xpc.ServiceManagement";
+
 type DesktopLoginFacts = Pick<DesktopStartupDiagnostic, "loginEnabled" | "loginRegistration">;
 
 /**

package/src/service/health-sentinel-main.ts

@@ -38,7 +38,7 @@ import {
   type HealthProbeOutcome,
   type HealthSentinelTiming,
 } from "./health-sentinel-policy";
-import { probeHealth, type HealthProbeTarget } from "./health-sentinel-probe";
+import { probeHealth, probeUrlHost, type HealthProbeTarget } from "./health-sentinel-probe";
 
 export const HEALTH_SENTINEL_ENV = {
   targetPid: "OCX_HEALTH_SENTINEL_TARGET_PID",
@@ -143,6 +143,11 @@ type Attempt =
   | { kind: "gone" }
   | { kind: "intent"; entry: RecoveryEntry };
 
+function matchesProbeTarget(runtime: SentinelRuntimeRecord | null, pid: number, target: HealthProbeTarget): boolean {
+  return runtime !== null && runtime.pid === pid && !runtime.sibling
+    && runtime.port === target.port && probeUrlHost(runtime.hostname) === target.hostname;
+}
+
 export async function runHealthSentinel(deps: HealthSentinelDeps): Promise<HealthSentinelResult> {
   const timing: HealthSentinelTiming = { ...DEFAULT_HEALTH_SENTINEL_TIMING, ...deps.timing };
   const standDown = (reason: string): HealthSentinelResult => {
@@ -162,12 +167,18 @@ export async function runHealthSentinel(deps: HealthSentinelDeps): Promise<Healt
     recoveryHistory: history,
     timing,
   });
+  let pinnedTarget: HealthProbeTarget | null = null;
   for (;;) {
     if (deps.isTargetGone()) return { outcome: "target_exited" };
     const runtime = deps.readRuntime();
     if (!runtime || runtime.pid !== deps.targetPid) return standDown("the runtime record no longer names the watched process");
     if (runtime.sibling) return standDown("the watched process is a sibling proxy");
-    const outcome = await raceGone(deps.probe({ hostname: runtime.hostname ?? "", port: runtime.port }, timing.probeTimeoutMs), exitSignal);
+    const hostname = probeUrlHost(runtime.hostname);
+    if (hostname === null) return standDown("the recorded bind address is not numeric; DNS names cannot authorize recovery");
+    const target: HealthProbeTarget = pinnedTarget ?? { hostname, port: runtime.port };
+    if (!matchesProbeTarget(runtime, deps.targetPid, target)) return standDown("the recorded probe endpoint changed");
+    pinnedTarget = target;
+    const outcome = await raceGone(deps.probe(target, timing.probeTimeoutMs), exitSignal);
     if (outcome === GONE) return { outcome: "target_exited" };
     const wasArmed = policy.state().armed;
     const decision = policy.observe(outcome);
@@ -178,7 +189,7 @@ export async function runHealthSentinel(deps: HealthSentinelDeps): Promise<Healt
         // Everything that could have changed during the probe is re-read under the lease.
         if (deps.isTargetGone()) return { kind: "gone" };
         const current = deps.readRuntime();
-        if (!current || current.pid !== deps.targetPid || current.port !== runtime.port || current.sibling) {
+        if (!matchesProbeTarget(current, deps.targetPid, target)) {
           return { kind: "stand_down", reason: "the runtime record changed while the target was unresponsive" };
         }
         // Persist first: an attempted recovery must count toward the cap, and on Windows this
@@ -202,7 +213,10 @@ export async function runHealthSentinel(deps: HealthSentinelDeps): Promise<Healt
         const { entry } = attempt;
         // The lease, history and log work above takes time. Re-check that the evidence is still
         // fresh right before the irreversible step: a proxy that recovered meanwhile must not be
-        // killed on old observations. A clock that ran backwards makes the evidence stale too.
+        // killed on old observations. A clock that ran backwards makes the evidence stale too. The
+        // final runtime-record read is included before the freshness check so time spent on it
+        // cannot authorize termination on stale observations.
+        const finalRuntime = deps.readRuntime();
         const evidenceAge = deps.now() - outcome.endedAt;
         if (evidenceAge < 0 || evidenceAge > timing.maxEvidenceAgeMs || deps.isTargetGone()) {
           settle({ ...entry, state: "skipped" });
@@ -211,6 +225,10 @@ export async function runHealthSentinel(deps: HealthSentinelDeps): Promise<Healt
           if (await raceGone(deps.sleep(policy.nextDelayMs()), exitSignal) === GONE) return { outcome: "target_exited" };
           continue;
         }
+        if (!matchesProbeTarget(finalRuntime, deps.targetPid, target)) {
+          settle({ ...entry, state: "skipped" });
+          return standDown("the recorded probe endpoint changed before termination");
+        }
         const result = deps.terminateTarget();
         if (result === "not_target") {
           settle({ ...entry, state: "skipped" });
@@ -329,6 +347,7 @@ export function readSentinelRuntime(path: string): SentinelRuntimeRecord | null
   try {
     const parsed = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
     const { pid, port, hostname } = parsed;
+    if (hostname !== undefined && typeof hostname !== "string") return null;
     if (typeof pid !== "number" || !Number.isSafeInteger(pid) || pid <= 0) return null;
     if (typeof port !== "number" || !Number.isSafeInteger(port) || port <= 0 || port > 65_535) return null;
     return { pid, port, ...(typeof hostname === "string" ? { hostname } : {}), sibling: parsed.siblingOfPort !== undefined };

package/src/service/health-sentinel-probe.ts

@@ -7,6 +7,9 @@
  * response framing and an absolute deadline. Only the timing decides liveness; the body's `pid`
  * lets the policy tell the target from another process that took the port.
  */
+import { isIP } from "node:net";
+
+import { isWildcardHostname } from "../codex/loopback-target";
 import { directLocalHttpFetch } from "../server/direct-local-http";
 import type { HealthProbeOutcome } from "./health-sentinel-policy";
 
@@ -17,12 +20,24 @@ export type HealthProbeIo = {
   fetch?: (url: string, timeoutMs: number) => Promise<Response>;
 };
 
-/** The URL host to dial for a recorded listen hostname: wildcard binds answer on loopback. */
-export function probeUrlHost(hostname: string | undefined): string {
-  const value = (hostname ?? "").trim().replace(/^\[|\]$/g, "");
-  if (!value || value === "0.0.0.0" || value === "localhost") return "127.0.0.1";
-  if (value === "::") return "[::1]";
-  return value.includes(":") ? `[${value}]` : value;
+/**
+ * Numeric probe endpoint only; unknown DNS destinations cannot authorize recovery. Wildcard
+ * spellings use the server's own predicate (`*`, `0`, `00.0.0.000`, `::0`, ...), so every bind
+ * the server accepts as a wildcard is probed on loopback instead of standing the sentinel down.
+ */
+export function probeUrlHost(hostname: string | undefined): string | null {
+  let value = (hostname ?? "").trim();
+  if (isWildcardHostname(value)) return value.includes(":") ? "[::1]" : "127.0.0.1";
+  if (value.startsWith("[") || value.endsWith("]")) {
+    if (!value.startsWith("[") || !value.endsWith("]")) return null;
+    value = value.slice(1, -1);
+    if (isIP(value) !== 6) return null;
+  }
+  if (!value || value === "0.0.0.0" || /^localhost\.?$/i.test(value)) return "127.0.0.1";
+  if (isIP(value) === 4) return value;
+  if (isIP(value) !== 6 || value.includes("%")) return null;
+  const host = new URL(`http://[${value}]/`).hostname;
+  return host === "[::]" ? "[::1]" : host;
 }
 
 /** `pid` from a `/healthz` JSON body, or null when the body does not carry one. */
@@ -39,8 +54,10 @@ export async function probeHealth(target: HealthProbeTarget, timeoutMs: number,
   const now = io.now ?? Date.now;
   const fetchFn = io.fetch ?? ((url: string, deadlineMs: number) => directLocalHttpFetch(url, { headers: { accept: "application/json" } }, { timeoutMs: deadlineMs }));
   const startedAt = now();
+  const hostname = probeUrlHost(target.hostname);
+  if (hostname === null) return { kind: "error", startedAt, endedAt: now() };
   try {
-    const response = await fetchFn(`http://${probeUrlHost(target.hostname)}:${target.port}/healthz`, timeoutMs);
+    const response = await fetchFn(`http://${hostname}:${target.port}/healthz`, timeoutMs);
     // The framed body is already in memory; reading it cannot wait on the target.
     const body = await response.text().catch(() => "");
     return { kind: "answered", pid: healthzPid(body), startedAt, endedAt: now() };

package/src/service/logging.ts

@@ -0,0 +1,72 @@
+import { closeSync, fstatSync, ftruncateSync, openSync, readSync, renameSync, writeSync } from "node:fs";
+import { formatWithOptions } from "node:util";
+import { dirname } from "node:path";
+import { recordOwnedConfigPath } from "../lib/config-ownership";
+
+export const SERVICE_LOG_MAX_BYTES = 20 * 1024 * 1024;
+export const SERVICE_LOG_CHECK_INTERVAL_MS = 60_000;
+
+/** Preserve the manager's open append descriptor; retain at most two bounded archives. */
+export function rotateServiceLog(path: string, maxBytes = SERVICE_LOG_MAX_BYTES): boolean {
+  let source: number | undefined;
+  let archive: number | undefined;
+  try {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) return false;
+    source = openSync(path, "r+");
+    const size = fstatSync(source).size;
+    if (size <= maxBytes) return false;
+    try { renameSync(`${path}.1`, `${path}.2`); } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") return false;
+    }
+    archive = openSync(`${path}.1`, "w", 0o600);
+    // A legacy unbounded file may be huge. Copy only its newest cap-sized tail,
+    // using fixed memory, before truncating the original inode.
+    const buffer = Buffer.alloc(Math.min(64 * 1024, maxBytes));
+    let position = size - maxBytes;
+    while (position < size) {
+      const read = readSync(source, buffer, 0, Math.min(buffer.length, size - position), position);
+      if (read === 0) return false;
+      let written = 0;
+      while (written < read) {
+        const count = writeSync(archive, buffer, written, read - written);
+        if (count === 0) return false;
+        written += count;
+      }
+      position += read;
+    }
+    ftruncateSync(source, 0);
+    return true;
+  } catch {
+    return false; // Missing files, permissions and disk failures must never stop the service.
+  } finally {
+    for (const fd of [archive, source]) {
+      if (fd !== undefined) try { closeSync(fd); } catch { /* best-effort */ }
+    }
+  }
+}
+
+/** One sink wrapper covers startup, provider diagnostics and multiline errors. */
+export function startServiceLogging(
+  path: string,
+  env: NodeJS.ProcessEnv = process.env,
+  intervalMs = SERVICE_LOG_CHECK_INTERVAL_MS,
+): () => void {
+  if (!env.OCX_SERVICE) return () => {};
+  const restore: (() => void)[] = [];
+  for (const method of ["log", "info", "debug", "warn", "error"] as const) {
+    const original = console[method];
+    console[method] = (...args: unknown[]) => {
+      const at = new Date().toISOString();
+      const line = formatWithOptions({ colors: false }, ...args);
+      original.call(console, line.split("\n").map(part => `${at} ${part}`).join("\n"));
+    };
+    restore.push(() => { console[method] = original; });
+  }
+  try {
+    for (const suffix of [".1", ".2"]) recordOwnedConfigPath(dirname(path), `${path}${suffix}`);
+  } catch { /* ownership bookkeeping must not break logging */ }
+  rotateServiceLog(path);
+  const timer = setInterval(() => { rotateServiceLog(path); }, intervalMs);
+  timer.unref();
+  return () => { clearInterval(timer); for (const reset of restore) reset(); };
+}

package/src/tray/windows-tray.ps1

@@ -201,14 +201,10 @@ function Start-StartupHealthProbe {
     if ($null -ne $script:startupProbeProcess) {
       # Process.Start succeeded but the async pipe setup failed: Dispose alone
       # would leave the Bun child running, so terminate it before cleanup.
-      try {
-        $script:startupProbeProcess.Kill()
-        [void]$script:startupProbeProcess.WaitForExit(3000)
-      } catch {
-        Write-ActionLog "startup-health probe launch cleanup failed: $($_.Exception.GetType().Name)"
-      }
+      Stop-StartupHealthProbe
+    } else {
+      Complete-StartupHealthProbe
     }
-    Complete-StartupHealthProbe
   }
 }
 
@@ -217,8 +213,11 @@ function Complete-StartupHealthProbe {
   $script:startupProbeProcess = $null
   $script:startupProbeOutputTask = $null
   $script:startupProbeErrorTask = $null
+  $script:startupProbeTerminating = $false
   if ($null -ne $process) {
     try {
+      $process.StandardOutput.Dispose()
+      $process.StandardError.Dispose()
       $process.Dispose()
     } catch {
       Write-ActionLog "startup-health probe dispose failed: $($_.Exception.GetType().Name)"
@@ -226,6 +225,31 @@ function Complete-StartupHealthProbe {
   }
 }
 
+function Stop-StartupHealthProbe([switch]$Shutdown) {
+  if ($null -eq $script:startupProbeProcess) { return }
+  $script:startupProbeTerminating = $true
+  try {
+    if (-not $script:startupProbeProcess.HasExited) { $script:startupProbeProcess.Kill() }
+  } catch { Write-ActionLog "startup-health probe kill failed: $($_.Exception.GetType().Name)" }
+  if ($Shutdown) {
+    # Shutdown alone may wait. Timeout ticks keep the child tracked until actual exit.
+    try { [void]$script:startupProbeProcess.WaitForExit(500) } catch { $null = $_ }
+    $exited = $false
+    try { $exited = $script:startupProbeProcess.HasExited } catch { $null = $_ }
+    if ($exited) {
+      # Exit does not mean both pipe readers finished; give them the same bounded wait.
+      $readers = @($script:startupProbeOutputTask, $script:startupProbeErrorTask) | Where-Object { $null -ne $_ }
+      if ($readers.Count -gt 0) {
+        try { [void][System.Threading.Tasks.Task]::WaitAll([System.Threading.Tasks.Task[]]$readers, 500) } catch { $null = $_ }
+      }
+      Complete-StartupHealthProbe
+    } else {
+      # Releasing the only reference would orphan a live child; keep it tracked.
+      Write-ActionLog "startup-health probe still running at shutdown; leaving it tracked"
+    }
+  }
+}
+
 function Initialize-UpdateBadgeReader {
   if (([System.Management.Automation.PSTypeName]"TrayUpdateBadgeReader").Type) { return }
   Add-Type -TypeDefinition @'
@@ -433,6 +457,7 @@ $script:startupRefreshMs = 20000L
 $script:startupProbeProcess = $null
 $script:startupProbeOutputTask = $null
 $script:startupProbeErrorTask = $null
+$script:startupProbeTerminating = $false
 $script:startupProbeStarted = 0L
 $script:startupProbeTimeoutMs = 30000L
 $script:updateAvailable = $false
@@ -520,10 +545,16 @@ function Update-TrayState {
     try {
       $probeExited = $script:startupProbeProcess.HasExited
     } catch {
-      $probeExited = $true
+      # Failed inspection is not proof of exit; keep ownership and request termination.
+      Stop-StartupHealthProbe
     }
     $probeTimedOut = ($now - $script:startupProbeStarted) -gt $script:startupProbeTimeoutMs
-    if ($probeExited -and $null -ne $script:startupProbeOutputTask -and $script:startupProbeOutputTask.IsCompleted) {
+    $probeDrained = ($null -eq $script:startupProbeOutputTask -or $script:startupProbeOutputTask.IsCompleted) -and
+      ($null -eq $script:startupProbeErrorTask -or $script:startupProbeErrorTask.IsCompleted)
+    if ($script:startupProbeTerminating) {
+      if ($probeExited -and $probeDrained) { Complete-StartupHealthProbe }
+      elseif (-not $probeExited) { Stop-StartupHealthProbe }
+    } elseif ($probeExited -and $probeDrained -and $null -ne $script:startupProbeOutputTask) {
       $probeStartup = $null
       try {
         $probeStartup = Parse-StartupHealthText $script:startupProbeOutputTask.Result
@@ -537,14 +568,8 @@ function Update-TrayState {
       # A hung diagnostic must not survive its refresh slot: terminate it so the
       # next refresh cannot stack another orphaned Bun process behind it.
       Write-ActionLog "startup-health probe timed out; terminating it"
-      try {
-        $script:startupProbeProcess.Kill()
-        [void]$script:startupProbeProcess.WaitForExit(3000)
-      } catch {
-        Write-ActionLog "startup-health probe kill failed: $($_.Exception.GetType().Name)"
-      }
+      Stop-StartupHealthProbe
       $script:startupHealth = $null
-      Complete-StartupHealthProbe
       $script:startupHealthCheckedAt = $now
     }
   }
@@ -710,14 +735,8 @@ try {
     # A probe still running when the tray shuts down would outlive it: Dispose()
     # releases the handle but does not terminate the child, so kill the active
     # probe, wait briefly for exit, then release the probe state.
-    try {
-      Write-ActionLog "terminating active startup-health probe on tray shutdown"
-      $script:startupProbeProcess.Kill()
-      [void]$script:startupProbeProcess.WaitForExit(3000)
-    } catch {
-      Write-ActionLog "startup-health probe shutdown kill failed: $($_.Exception.GetType().Name)"
-    }
-    Complete-StartupHealthProbe
+    Write-ActionLog "terminating active startup-health probe on tray shutdown"
+    Stop-StartupHealthProbe -Shutdown
   }
   Stop-UpdateBadgeProbe -Shutdown
   $notify.Dispose()