fix(update): preserve service-home authority during recovery

docs-site/src/content/docs/troubleshooting/update-failed.md

@@ -20,7 +20,14 @@ and, afterwards, a folder next to the package that cannot be deleted because `bu
 The updater stops the proxy, installs the new version into a separate staging folder, checks it,
 and only then swaps it in. When the install step fails, the swap never happens: the previous version
 stays installed and runnable, and the updater restarts the previous background service (or the
-previous proxy) before it exits. You do not need to reinstall to get back to a working proxy.
+previous proxy) before it exits, when ownership and service-home checks authorize recovery.
+
+If the initial service-home check is inconclusive, for example because Bun is missing or a service
+query fails, the updater can replace an idle package without stopping or restarting the proxy.
+A successful package-only update prints a manual restart hint and explains that service ownership
+could not be verified. Check `ocx service status` and the registered installation before restarting.
+Changes in authority, unknown durable runtime ownership, Desktop supervision, a live package
+runtime or an unresolved teardown receipt still block package replacement; an inconclusive check is not permission to control them.
 
 Check that with:
 

scripts/test-layout/layout-update-home.json

@@ -0,0 +1,13 @@
+{
+  "update-windows-wrapper-authority.test.ts": "update",
+  "update-mutation-scanner.test.ts": "update",
+  "update-mutation-boundaries.test.ts": "update",
+  "update-mutation-guard.test.ts": "update",
+  "update-home-launcher.test.ts": "update",
+  "update-home-recovery.test.ts": "update",
+  "update-recovery-authority.test.ts": "update",
+  "update-recovery-boundaries.test.ts": "update",
+  "update-home-worker.test.ts": "update",
+  "update-service-home-policy.test.ts": "update",
+  "update-service-home.test.ts": "update"
+}

scripts/test-layout/layout.json

@@ -1,7 +1,7 @@
 {
   "version": 1,
   "root": "tests",
-  "explicitShards": ["layout-clients.json", "layout-codex-collision.json", "layout-agent-assertion.json", "layout-chat.json", "layout-replay.json", "layout-adapters.json", "layout-jev.json", "layout-workbuddy.json", "layout-combos.json", "layout-credit-renewal.json"],
+  "explicitShards": ["layout-clients.json", "layout-codex-collision.json", "layout-update-home.json", "layout-agent-assertion.json", "layout-chat.json", "layout-replay.json", "layout-adapters.json", "layout-jev.json", "layout-workbuddy.json", "layout-combos.json", "layout-credit-renewal.json"],
   "explicit": { "combo-description.test.ts": "routing", "combo-description-catalog.test.ts": "codex-integration", "codex-provider-routing.test.ts": "codex-integration", "config-native-reasoning-retention.test.ts": "config", "server-native-reasoning-retention-merge.test.ts": "server", "server-native-reasoning-retention.test.ts": "server", "responses-retained-reasoning-stream-recovery.test.ts": "responses", "openai-native-hosted-search-history.test.ts": "adapters/openai", "responses-native-compact-search-history.test.ts": "responses", "config-hosted-search-projection.test.ts": "config", "gcp-credential-boundary.test.ts": "adapters/google", "gcp-sa-marker.test.ts": "adapters/google", "gcp-sa-adapter.test.ts": "adapters/google", "management-gcp-credential-input.test.ts": "server", "codex-preserve-signed-in.test.ts": "codex-integration", "cli-account-preservation.test.ts": "cli", "cli-provider-list-active.test.ts": "cli", "service-state-isolation.test.ts": "service", "compaction-history-framing.test.ts": "responses", "catalog-native-max-context.test.ts": "codex-integration", "protocol-argon-thought-boundary.test.ts": "responses", "service-log.test.ts": "service", "messages-native-empty-inline.test.ts": "claude-integration", "catalog-auto-review-override.test.ts": "codex-integration", "management-auto-review-settings.test.ts": "server", "management-auto-review-auth.test.ts": "server", "prefer-model-alias-ids.test.ts": "server", "responses-mimo-envelope.test.ts": "responses", "responses-call-id-linkage.test.ts": "responses", "bridge-terminal-refusal.test.ts": "adapters", "loop-terminal-refusal.test.ts": "images", "web-search-terminal-refusal.test.ts": "web-search", "combo-terminal-refusal.test.ts": "routing", "server-terminal-refusal-wiring.test.ts": "server", "incomplete-reason-normalization.test.ts": "responses", "advisor-retention.test.ts": "advisor", "responses-native-key-cooldown.test.ts": "responses", "responses-run-turn-key-readmission.test.ts": "responses", "qoder-spawn-readmission.test.ts": "adapters", "api-key-selection-cooldown.test.ts": "providers", "api-key-auto-pause-distribution.test.ts": "providers", "explicit-key-pause-oauth-boundary.test.ts": "providers", "server-chat-native-key-selection.test.ts": "server", "compact-key-selection.test.ts": "responses", "messages-native-key-selection.test.ts": "claude-integration", "coding-agent-windows-dispatch.test.ts": "adapters", "coding-agent-native-empty-argv.test.ts": "windows",
     "service-proxy-env.test.ts": "service", "openai-chat-standalone-bare-block.test.ts": "adapters/openai",
     "owner-registry-isolation.test.ts": "config",

src/server/port-reclaim.ts

@@ -67,6 +67,13 @@ export type ReclaimListenPortOptions = WaitForPortOptions & {
   killFn?: (pid: number) => void;
   dropTcpFn?: (port: number) => number | { dropped: number; skippedIpv6: number };
   isAvailableFn?: (port: number, hostname?: string) => Promise<boolean>;
+  /**
+   * Synchronous authority gate re-checked after each availability await and
+   * immediately before every destructive action (killFn / dropTcpFn). Returning
+   * false denies the mutation and ends the reclaim: the port is reported
+   * not-freed without touching processes or TCP rows. A throwing gate denies too.
+   */
+  mayMutateFn?: () => boolean;
   sleepMs?: (ms: number) => Promise<void>;
 };
 
@@ -516,6 +523,8 @@ export async function ownsIpv4LoopbackListener(
  * revalidates immediately before each kill.
  * Never overrides a rejected ocx verifier result. Never drops TCP rows while a
  * rejected live or protected ocx listener owns the port, or when the scan failed.
+ * A denied `mayMutateFn` ends the wait: no kill or TCP-row drop may run under
+ * an authority that no longer holds.
  */
 export async function reclaimListenPort(
   port: number,
@@ -539,13 +548,18 @@ export async function reclaimListenPort(
   const dropTcpFn = opts.dropTcpFn ?? dropWindowsTcpRowsForLocalPort;
   const isAvailableFn = opts.isAvailableFn ?? isPortAvailable;
   const sleep = opts.sleepMs ?? ((ms: number) => new Promise<void>(resolve => setTimeout(resolve, ms)));
+  const mayMutate = (): boolean => {
+    try { return opts.mayMutateFn?.() !== false; } catch { return false; }
+  };
 
   const deadline = Date.now() + timeoutMs;
   let lastScan = 0;
   const killed = new Set<number>();
 
   for (;;) {
     if (await isAvailableFn(port, hostname)) return true;
+    // The authority may have changed while the availability probe was in flight.
+    if (!mayMutate()) return false;
     if (Date.now() >= deadline) return false;
 
     if (Date.now() - lastScan >= scanIntervalMs) {
@@ -585,6 +599,7 @@ export async function reclaimListenPort(
         }
         if (!killed.has(pid)) {
           // Revalidate immediately before termination.
+          if (!mayMutate()) return false;
           if (isAliveFn(pid) && verifyOcxFn(pid) === pid && mayKillThis) {
             try {
               killFn(pid);
@@ -619,6 +634,8 @@ export async function reclaimListenPort(
       // Reset those IPv4 TCBs (and ghost LISTEN rows) so the configured port can bind again —
       // without killing the browser process. Only safe when no live foreign/protected listener remains.
       if (dropTcpRows) {
+        // Same gate as the kill path: denied authority never runs SetTcpEntry.
+        if (!mayMutate()) return false;
         try {
           dropTcpFn(port);
         } catch {