@bitkyc08/opencodex 2.83.0 → 2.86.0

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

@@ -0,0 +1,241 @@
+/**
+ * Health-unresponsiveness recovery policy for the opt-in service health sentinel (#6671).
+ *
+ * Every supervisor this repository installs restarts the proxy only when it exits: the Windows
+ * Task Scheduler batch loop, launchd `KeepAlive`/`SuccessfulExit=false`, systemd
+ * `Restart=on-failure` and the desktop app's `on_exit`. A proxy that stays alive with its port
+ * listening while its event loop answers nothing is invisible to all of them. The sentinel turns
+ * that state into an exit, and this module is the whole of its judgement: pure, clock-injected,
+ * and free of I/O so every false-positive guard is testable on any platform.
+ *
+ * The guards, in the order they apply:
+ * - nothing counts until the target has answered once as itself and the startup grace is over;
+ *   the grace is elapsed time, so setting the clock back neither restarts nor extends it;
+ * - only a probe that got no complete answer by its deadline counts. Any answer proves the event
+ *   loop ran, and a refused or failed connection means the listener is closing, not hung;
+ * - an answer from another pid means the port is no longer the target's: stand down for good;
+ * - a probe that started far later than the cadence allows, that outlived its own deadline by
+ *   far more than jitter, or during which the sentinel's own event loop ran late (sleep, or the
+ *   sentinel itself paused or starved), discards the streak, because the timeout may belong to
+ *   that pause rather than to the target;
+ * - once a probe times out the next ones follow back to back, so a run of timeouts is one
+ *   continuous unresponsive stretch rather than separate stalls that line up with the cadence;
+ * - recovery needs both a run of consecutive timeouts and a minimum unhealthy span, which doubles
+ *   for each recovery in the last hour, and a cap on recoveries per hour stands the sentinel down:
+ *   a proxy that hangs again right after every restart is not fixed by killing it, and each kill
+ *   loses the work it held. Nothing is ever replayed.
+ */
+
+export type HealthProbeOutcome =
+  /** A complete status line and headers arrived before the deadline. */
+  | { kind: "answered"; pid: number | null; startedAt: number; endedAt: number }
+  /**
+   * No complete answer by the deadline, whether or not the connection was accepted.
+   * `sentinelLagMs` is how late the sentinel's own event loop ran during the probe: a sentinel
+   * that was itself paused or starved cannot tell a silent target from its own silence.
+   */
+  | { kind: "timeout"; startedAt: number; endedAt: number; sentinelLagMs?: number }
+  /** The connection was refused: nothing is listening. */
+  | { kind: "refused"; startedAt: number; endedAt: number }
+  /** Any other failure. */
+  | { kind: "error"; startedAt: number; endedAt: number };
+
+export type HealthSentinelTiming = {
+  /** Time between the end of one answered probe and the start of the next. */
+  intervalMs: number;
+  /**
+   * Time between a timed-out probe and the next. Short on purpose: back-to-back probes make a run
+   * of timeouts mean one continuous unresponsive stretch, so recurring shorter stalls that happen
+   * to line up with the cadence cannot add up to a recovery.
+   */
+  failureIntervalMs: number;
+  /** A probe without a complete answer by this deadline is a timeout. */
+  probeTimeoutMs: number;
+  /** Counted from the sentinel's start; nothing counts before it ends. */
+  startupGraceMs: number;
+  /** Consecutive timeouts needed before a recovery. */
+  failureThreshold: number;
+  /** Minimum span from the first failing probe's start to the last one's end, before backoff. */
+  minUnhealthyMs: number;
+  /** Slack over the cadence (and over a probe's deadline) before a pause voids the streak. */
+  suspendSlackMs: number;
+  /** A timeout during which the sentinel's own loop ran later than this is not evidence. */
+  lagToleranceMs: number;
+  /** Window over which earlier recoveries raise the backoff and count toward the cap. */
+  recoveryWindowMs: number;
+  /** Recoveries within the window after which the sentinel stands down. */
+  maxRecoveriesPerWindow: number;
+  /** Ceiling on the backoff multiplier. */
+  maxBackoffMultiplier: number;
+  /**
+   * Oldest the final failing observation may be when the kill is issued. Lease, history and log
+   * work runs between the decision and the kill; evidence older than this is discarded.
+   */
+  maxEvidenceAgeMs: number;
+};
+
+export const DEFAULT_HEALTH_SENTINEL_TIMING: Readonly<HealthSentinelTiming> = Object.freeze({
+  intervalMs: 30_000,
+  failureIntervalMs: 1_000,
+  probeTimeoutMs: 20_000,
+  startupGraceMs: 120_000,
+  failureThreshold: 3,
+  minUnhealthyMs: 60_000,
+  suspendSlackMs: 5_000,
+  lagToleranceMs: 2_000,
+  recoveryWindowMs: 60 * 60_000,
+  maxRecoveriesPerWindow: 3,
+  maxBackoffMultiplier: 8,
+  maxEvidenceAgeMs: 5_000,
+});
+
+export type HealthSentinelDecision =
+  | { action: "continue"; note?: string }
+  | { action: "recover"; reason: string; consecutiveTimeouts: number; unhealthyMs: number }
+  /** Stop acting for this target; the reason is logged once. */
+  | { action: "stand_down"; reason: string };
+
+export type HealthSentinelPolicyState = {
+  readonly armed: boolean;
+  readonly consecutiveTimeouts: number;
+  readonly firstFailureStartedAt: number | null;
+  readonly lastObservedAt: number | null;
+  readonly stoodDown: string | null;
+};
+
+export type HealthSentinelPolicy = {
+  observe(outcome: HealthProbeOutcome): HealthSentinelDecision;
+  state(): HealthSentinelPolicyState;
+  /** Minimum unhealthy span currently required, after backoff. */
+  requiredUnhealthyMs(): number;
+  /** How long to wait before the next probe: short while a failure streak is open. */
+  nextDelayMs(): number;
+};
+
+/**
+ * Recoveries recorded inside the window ending at `now`. An entry dated after `now` counts as
+ * recent: it means the wall clock was set back after it was written, and dropping it would let a
+ * clock rollback (or a restart after one) lift the hourly cap. It keeps counting until the clock
+ * passes it by a full window, which errs toward not killing.
+ */
+export function recentRecoveryCount(history: readonly number[], now: number, windowMs: number): number {
+  return history.filter(at => Number.isFinite(at) && now - at < windowMs).length;
+}
+
+/** The unhealthy span required after `recent` recoveries: doubled per recovery, capped. */
+export function requiredUnhealthySpan(timing: HealthSentinelTiming, recent: number): number {
+  const multiplier = Math.min(timing.maxBackoffMultiplier, 2 ** Math.max(0, recent));
+  return timing.minUnhealthyMs * multiplier;
+}
+
+export function createHealthSentinelPolicy(input: {
+  targetPid: number;
+  startedAt: number;
+  /** Epoch-ms of earlier recoveries for this installation, newest last. */
+  recoveryHistory: readonly number[];
+  timing?: Partial<HealthSentinelTiming>;
+}): HealthSentinelPolicy {
+  const timing: HealthSentinelTiming = { ...DEFAULT_HEALTH_SENTINEL_TIMING, ...input.timing };
+  let armed = false;
+  let streak = 0;
+  let firstFailureStartedAt: number | null = null;
+  let lastObservedAt: number | null = null;
+  let stoodDown: string | null = null;
+  let required = timing.minUnhealthyMs;
+  // Startup grace is measured as elapsed time, accumulated from forward clock movement only, so a
+  // wall clock set back after (or during) the grace cannot reopen it and hold off recovery for as
+  // long as the clock was moved.
+  let graceElapsedMs = 0;
+  let graceClock = input.startedAt;
+  const noteGraceProgress = (at: number) => {
+    if (at > graceClock) graceElapsedMs += at - graceClock;
+    graceClock = at;
+  };
+
+  const resetStreak = () => {
+    streak = 0;
+    firstFailureStartedAt = null;
+  };
+
+  const standDown = (reason: string): HealthSentinelDecision => {
+    stoodDown = reason;
+    resetStreak();
+    return { action: "stand_down", reason };
+  };
+
+  const observe = (outcome: HealthProbeOutcome): HealthSentinelDecision => {
+    if (stoodDown !== null) return { action: "stand_down", reason: stoodDown };
+    noteGraceProgress(outcome.startedAt);
+    const previous = lastObservedAt;
+    lastObservedAt = outcome.endedAt;
+    let note: string | undefined;
+    if (previous !== null && streak > 0 && outcome.startedAt - previous > timing.failureIntervalMs + timing.suspendSlackMs) {
+      // The sentinel overslept its cadence (a suspended machine, or the sentinel itself starved),
+      // so the timeouts counted so far may belong to that pause rather than to the target.
+      resetStreak();
+      note = "observation gap; failure streak discarded";
+    }
+    switch (outcome.kind) {
+      case "answered": {
+        if (outcome.pid !== null && outcome.pid !== input.targetPid) {
+          return standDown("another process answers the health endpoint");
+        }
+        if (outcome.pid === input.targetPid) armed = true;
+        resetStreak();
+        return { action: "continue", note };
+      }
+      case "refused":
+      case "error":
+        resetStreak();
+        return { action: "continue", note };
+      case "timeout": {
+        if (!armed) return { action: "continue", note: note ?? "not armed: the target has not answered yet" };
+        if (graceElapsedMs < timing.startupGraceMs) {
+          return { action: "continue", note: note ?? "startup grace" };
+        }
+        if (
+          outcome.endedAt - outcome.startedAt > timing.probeTimeoutMs + timing.suspendSlackMs
+          || outcome.endedAt < outcome.startedAt
+          || (previous !== null && outcome.startedAt < previous)
+        ) {
+          // The probe outlived its own deadline by far more than scheduling jitter, or the wall
+          // clock ran backwards: its timing spanned a pause or a clock step, so this timeout says
+          // nothing about the target.
+          resetStreak();
+          return { action: "continue", note: "probe spanned a pause; failure streak discarded" };
+        }
+        if ((outcome.sentinelLagMs ?? 0) > timing.lagToleranceMs) {
+          // The sentinel itself stalled during the probe (paused, starved, or the machine slept),
+          // so the deadline may have expired while nobody was listening for the answer.
+          resetStreak();
+          return { action: "continue", note: "probe spanned a pause; failure streak discarded" };
+        }
+        streak += 1;
+        if (firstFailureStartedAt === null) firstFailureStartedAt = outcome.startedAt;
+        const unhealthyMs = outcome.endedAt - firstFailureStartedAt;
+        const recent = recentRecoveryCount(input.recoveryHistory, outcome.endedAt, timing.recoveryWindowMs);
+        required = requiredUnhealthySpan(timing, recent);
+        if (streak < timing.failureThreshold || unhealthyMs < required) return { action: "continue", note };
+        if (recent >= timing.maxRecoveriesPerWindow) {
+          return standDown(`${recent} recoveries in the last ${Math.round(timing.recoveryWindowMs / 60_000)} minutes; not recovering again`);
+        }
+        const decision: HealthSentinelDecision = {
+          action: "recover",
+          reason: `no health answer for ${streak} consecutive probes over ${Math.round(unhealthyMs / 1000)}s`,
+          consecutiveTimeouts: streak,
+          unhealthyMs,
+        };
+        resetStreak();
+        return decision;
+      }
+    }
+  };
+
+  return {
+    observe,
+    state: () => ({ armed, consecutiveTimeouts: streak, firstFailureStartedAt, lastObservedAt, stoodDown }),
+    requiredUnhealthyMs: () => required,
+    nextDelayMs: () => (streak > 0 ? timing.failureIntervalMs : timing.intervalMs),
+  };
+}
+

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

@@ -0,0 +1,71 @@
+/**
+ * The service health sentinel's one question to the proxy it watches: does `GET /healthz`
+ * produce a complete answer before the deadline (#6671)?
+ *
+ * The request goes through {@link directLocalHttpFetch}: raw `node:net`, so neither proxy
+ * environment variables nor the bundled runtime's fetch stack (#6684) are involved, with capped
+ * 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";
+
+export type HealthProbeTarget = { hostname: string; port: number };
+
+export type HealthProbeIo = {
+  now?: () => number;
+  fetch?: (url: string, timeoutMs: number) => Promise<Response>;
+};
+
+/**
+ * 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. */
+export function healthzPid(body: string): number | null {
+  try {
+    const parsed = JSON.parse(body) as { pid?: unknown };
+    return typeof parsed.pid === "number" && Number.isSafeInteger(parsed.pid) && parsed.pid > 0 ? parsed.pid : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function probeHealth(target: HealthProbeTarget, timeoutMs: number, io: HealthProbeIo = {}): Promise<HealthProbeOutcome> {
+  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://${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() };
+  } catch (error) {
+    const endedAt = now();
+    const failure = error as { name?: unknown; code?: unknown };
+    if (failure?.name === "TimeoutError") return { kind: "timeout", startedAt, endedAt };
+    if (failure?.code === "ECONNREFUSED") return { kind: "refused", startedAt, endedAt };
+    return { kind: "error", startedAt, endedAt };
+  }
+}

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

@@ -0,0 +1,87 @@
+/**
+ * A Windows process handle on the health sentinel's parent, held for the sentinel's lifetime
+ * (#6671).
+ *
+ * Windows reuses process ids quickly, so "is pid N still my parent" checked just before a kill
+ * cannot bind the kill to the proxy: the proxy may exit and its id be handed to another process in
+ * between. An open handle can: while any handle to a process object is open, its id is not
+ * reused, and `TerminateProcess` acts on exactly that object. The handle is opened once at
+ * startup and accepted only if the process it names was created before this sentinel, which a
+ * replacement holding a recycled id cannot satisfy. libuv's kill-on-close Job would otherwise be
+ * the only tie between the two processes, and libuv ignores a failed Job assignment.
+ *
+ * Bun exposes no API for a handle on a process it did not spawn, so this calls kernel32 through
+ * `bun:ffi`. Nothing here runs on other platforms.
+ */
+import { dlopen, FFIType } from "bun:ffi";
+
+const PROCESS_TERMINATE = 0x0001;
+const PROCESS_QUERY_LIMITED_INFORMATION = 0x1000;
+const SYNCHRONIZE = 0x0010_0000;
+const WAIT_OBJECT_0 = 0;
+const WAIT_TIMEOUT = 0x102;
+
+export type ParentProcessHandle = {
+  /** TerminateProcess on the held handle; true when Windows accepted the request. */
+  terminate(exitCode: number): boolean;
+  /** True once the process has exited (non-blocking). */
+  exited(): boolean;
+  close(): void;
+};
+
+export type ParentHandleResult =
+  | { ok: true; handle: ParentProcessHandle }
+  | { ok: false; reason: string };
+
+// HANDLEs travel as u64 (bigint), never as `ptr`: a JS number cannot carry every pointer-width
+// value, and a truncated handle would name a different object.
+function kernel32() {
+  return dlopen("kernel32.dll", {
+    OpenProcess: { args: [FFIType.u32, FFIType.i32, FFIType.u32], returns: FFIType.u64 },
+    GetProcessTimes: { args: [FFIType.u64, FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr], returns: FFIType.i32 },
+    TerminateProcess: { args: [FFIType.u64, FFIType.u32], returns: FFIType.i32 },
+    WaitForSingleObject: { args: [FFIType.u64, FFIType.u32], returns: FFIType.u32 },
+    CloseHandle: { args: [FFIType.u64], returns: FFIType.i32 },
+  }).symbols;
+}
+
+/** Open the parent and prove it is the process that created this one. */
+export function openParentProcessHandle(parentPid: number): ParentHandleResult {
+  if (process.platform !== "win32") return { ok: false, reason: "not Windows" };
+  let k32: ReturnType<typeof kernel32>;
+  try {
+    k32 = kernel32();
+  } catch {
+    return { ok: false, reason: "kernel32 is unavailable" };
+  }
+  const handle = BigInt(k32.OpenProcess(PROCESS_TERMINATE | PROCESS_QUERY_LIMITED_INFORMATION | SYNCHRONIZE, 0, parentPid));
+  if (handle === 0n) return { ok: false, reason: "the parent process cannot be opened" };
+  const close = () => { try { k32.CloseHandle(handle); } catch { /* already closed */ } };
+  const created = (target: bigint): bigint | null => {
+    const times = new BigUint64Array(4);
+    const ok = k32.GetProcessTimes(target, times.subarray(0, 1), times.subarray(1, 2), times.subarray(2, 3), times.subarray(3, 4));
+    return ok ? times[0]! : null;
+  };
+  // This process cannot be reused while it runs, so opening it by id is exact; the pseudo-handle
+  // from GetCurrentProcess is avoided because it is -1.
+  const self = BigInt(k32.OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, 0, process.pid));
+  const parentCreated = created(handle);
+  const selfCreated = self === 0n ? null : created(self);
+  if (self !== 0n) { try { k32.CloseHandle(self); } catch { /* already closed */ } }
+  if (parentCreated === null || selfCreated === null || parentCreated === 0n || parentCreated >= selfCreated) {
+    close();
+    return { ok: false, reason: "the process holding the parent id was not created before this sentinel" };
+  }
+  if (k32.WaitForSingleObject(handle, 0) !== WAIT_TIMEOUT) {
+    close();
+    return { ok: false, reason: "the parent process has already exited" };
+  }
+  return {
+    ok: true,
+    handle: {
+      terminate: exitCode => k32.TerminateProcess(handle, exitCode) !== 0,
+      exited: () => k32.WaitForSingleObject(handle, 0) === WAIT_OBJECT_0,
+      close,
+    },
+  };
+}

package/src/service/linux-linger.ts

@@ -0,0 +1,20 @@
+import { execFileSync } from "node:child_process";
+import { userInfo } from "node:os";
+
+interface LinuxLingerDeps {
+  user?: () => string;
+  run?: typeof execFileSync;
+}
+
+/** Advisory only: never enables linger or changes the user's login settings. */
+export function linuxServiceBootHint(deps: LinuxLingerDeps = {}): string {
+  try {
+    const user = (deps.user ?? (() => userInfo().username))();
+    const output = (deps.run ?? execFileSync)("loginctl", ["show-user", user, "-p", "Linger"], {
+      encoding: "utf8", timeout: 750, maxBuffer: 16 * 1024, stdio: ["ignore", "pipe", "pipe"],
+    }).trim();
+    if (output === "Linger=yes") return "   Auto-start on boot: user lingering is already enabled.";
+    if (output === "Linger=no") return "   For auto-start on boot: loginctl enable-linger $USER";
+  } catch { /* Missing loginctl or failed diagnosis is advisory, not an install failure. */ }
+  return "   User lingering could not be verified. For auto-start on boot, check it and, if disabled, run: loginctl enable-linger $USER";
+}

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()