@bitkyc08/opencodex 2.63.0 → 2.64.0

package/src/cli/index.ts

@@ -96,7 +96,18 @@ import {
 import { createReadinessGate } from "../server/readiness";
 import { isApiAuthRequired } from "../server/auth-cors";
 import { runReady, type ReadyArgs } from "./ready";
-import { runResolve, type ResolveArgs } from "./resolve";
+import { runResolve, type ResolveArgs, type ResolveJson } from "./resolve";
+import {
+  approvalChanged,
+  guardFinalStopSummary,
+  managerStillActive,
+  runApprovedStop,
+  runGuardedManagerStep,
+  settleApprovedTarget,
+  type GuardedStopSnapshot,
+  type StopApproval,
+} from "./stop-approval";
+import { inspectGuardedManagerTarget, observeGuardedManagerStopped } from "../service/guarded-manager-target";
 import { summarizeStopRun, type StopOutcome, type StopRunRecord } from "./stop-report";
 import { runCli } from "./root";
 import { isProcessAlive, ProxyOwnershipRefusedError, refusalNextStep, stopProxy } from "../lib/process-control";
@@ -181,6 +192,16 @@ async function refreshOwnedRaycastCatalog(
 
 initializeNodeLauncherContext();
 
+// The compiled executable is also the capture-only MCP server's launcher.
+// Handle this private entrypoint before CLI preflight or command dispatch.
+if (process.argv[2] === "__codebuddy-mcp") {
+  const { runCodeBuddyMcpServer } = await import("../adapters/codebuddy/mcp-server");
+  await runCodeBuddyMcpServer(process.argv[3] ?? "");
+  // The MCP stdio loop owns this process until stdin closes; do not fall through
+  // to ordinary CLI dispatch or exit after the handshake completes.
+  await new Promise<never>(() => {});
+}
+
 // Head: version/help early exits, `ready` pre-parse (exit 64 before any
 // preflight), and the bounded Codex-shim auto-restore preflight live in
 // src/cli/root.ts (Phase 1 of the CLI deepening). runCli exits for
@@ -556,7 +577,7 @@ async function handleStart(options: { block?: boolean } = {}) {
   }
 
   const { server, serverModule, port, readinessGate, config } = boundStart;
-  const { drainAndShutdown, isRecyclingForExit } = serverModule;
+  const { drainAndShutdown, isRecyclingForExit, noteExplicitShutdownRequested } = serverModule;
   // Records are visible now; background work may observe this runtime without a gap.
   scheduleCatalogPrewarm();
   installCrashGuards();
@@ -627,6 +648,7 @@ async function handleStart(options: { block?: boolean } = {}) {
     }
     shuttingDown = true;
     shutdownStartedAt = now;
+    noteExplicitShutdownRequested(); // an automatic package restart must not hand off after this
     console.log("\n🛑 Shutting down opencodex proxy...");
     void (async () => {
       let shutdownSucceeded = false;
@@ -882,6 +904,8 @@ function reportRestartFailure(result: Extract<ProxyRestartResult, { ok: false }>
     } else if (code === "restart_version_skew") {
       console.error("❌ The running proxy reports a different OpenCodex version than this CLI; restarting in place would respawn the old installation.");
       console.error("   Run `ocx stop` and then `ocx start` from this installation instead.");
+    } else if (code === "restart_package_tree_unsettled") {
+      console.error("❌ The proxy's package files are still being replaced; wait for the install to finish, then run `ocx restart` again.");
     } else {
       console.error("❌ Proxy restart request could not be confirmed; no fallback stop/start was attempted.");
     }
@@ -898,7 +922,7 @@ async function handleProxyRestart(
   const deadlineAt = Date.now() + PROXY_RESTART_OBSERVE_MS;
   const result = await runProxyRestart({
     findLive: () => discoverStableProxyForRestart({
-      findLive: () => findLiveProxy({ deadlineAt, attempts: 2 }),
+      findLive: () => findLiveProxy({ deadlineAt, attempts: 2, acceptPackageTreeFenced: true }),
       expired: () => Date.now() >= deadlineAt,
     }),
     startWhenStopped,
@@ -990,13 +1014,37 @@ async function restoreSharedClientStateAfterStop(): Promise<{ historyOnly: boole
   return { historyOnly, historyDeferred, other };
 }
 
-async function handleStop() {
+async function handleStop(approval?: StopApproval) {
   const lease = acquireOwnershipMutationLease(serviceStatePaths());
-  try { return await handleStopUnlocked(); }
+  try {
+    if (!approval) return await handleStopUnlocked();
+    return await runApprovedStop(
+      approval,
+      async () => {
+        const lines: string[] = [];
+        const code = await runResolve({ json: true }, {
+          stdout: { log: line => { lines.push(line); } },
+          stderr: { error: () => {} },
+        });
+        if (code !== 0 || lines.length !== 1) return null;
+        try { return JSON.parse(lines[0]!) as ResolveJson; }
+        catch { return null; }
+      },
+      () => {
+        const pid = readPid();
+        const runtime = pid === null ? null : readRuntimePort(pid);
+        return pid && runtime?.port ? {
+          pid, port: runtime.port, hostname: runtime.hostname ?? "",
+        } : null;
+      },
+      () => inspectGuardedManagerTarget(approval.pid, approval.port),
+      snapshot => handleStopUnlocked(snapshot),
+    );
+  }
   finally { lease.release(); }
 }
 
-async function handleStopUnlocked() {
+async function handleStopUnlocked(snapshot?: GuardedStopSnapshot) {
   // The receipt must name the endpoint the owner was stopping — an obligation nobody can
   // locate cannot be proven discharged. Only the runtime record knows it; a proxy started
   // with an explicit --port is not on the configured one.
@@ -1137,8 +1185,23 @@ async function handleStopUnlocked() {
     // to this process.
     return graceful && !teardownNonce;
   };
+  const approvedEndpoint = snapshot
+    ? { hostname: probeHostname(snapshot.approval.hostname || undefined), port: snapshot.approval.port }
+    : null;
+  let guardedStep: Awaited<ReturnType<typeof runGuardedManagerStep>> | null = null;
   try {
-    const serviceStop = stopServiceIfInstalledDetailed();
+    const serviceStop = snapshot
+      ? (guardedStep = await runGuardedManagerStep(snapshot, {
+          revalidateManager: () => inspectGuardedManagerTarget(snapshot.approval.pid, snapshot.approval.port),
+          stopManager: () => {
+            if (approvedEndpoint) claimTeardown(approvedEndpoint, "exact");
+            return stopServiceIfInstalledDetailed();
+          },
+          signalApproved: () => stopWithDeferral(snapshot.approval.pid, approvedEndpoint),
+          settle: () => settleApprovedTarget(snapshot.approval),
+          managerState: () => observeGuardedManagerStopped(snapshot.manager),
+        })).service
+      : stopServiceIfInstalledDetailed();
     record.service = serviceStop;
     stoppedService = serviceStop === "stopped" || serviceStop === "stopped-respawnable";
     schedulerCanRespawn = serviceStop === "stopped-respawnable";
@@ -1171,6 +1234,25 @@ async function handleStopUnlocked() {
     }
   }
 
+  if (snapshot) {
+    if (guardedStep?.effect === "approval-changed") {
+      return approvalChanged();
+    }
+    if (guardedStep?.effect === "manager-still-active") {
+      return managerStillActive(record.service, record);
+    }
+    if (guardedStep?.effect === "stopped") {
+      record.proxy = guardedStep.proxy;
+      nativeRestoreHandledByProxy = guardedStep.handledByProxy;
+      removePid(snapshot.approval.pid);
+      removeRuntimePort(snapshot.approval.pid);
+    } else {
+      stopFailed = true;
+      ownershipBlocked = true;
+      record.proxy = "unknown";
+      console.error("The approved runtime could not be verified after the guarded stop step.");
+    }
+  } else {
   const pid = readPid();
   if (pid) {
     try {
@@ -1212,7 +1294,7 @@ async function handleStopUnlocked() {
     const staleRuntimePid = readRuntimePort()?.pid ?? null;
     // Orphan recovery: a live proxy can outlive its pid file (crash, manual delete,
     // corrupt file). Identity-checked liveness still finds it via the runtime record.
-    const live = await findLiveProxy();
+    const live = await findLiveProxy({ acceptPackageTreeFenced: true });
     if (live?.pid) {
       try {
         // The probe already found where it answers, and on this path the runtime record is
@@ -1260,6 +1342,7 @@ async function handleStopUnlocked() {
       removeRuntimePortIfPidIs(staleRuntimePid);
     }
   }
+  }
   // Environment ownership is independent from service ownership. Always roll back
   // current-home variables; the helper refuses foreign markers on its own.
   try { revertSystemEnv(); } catch { /* best-effort */ }
@@ -1429,12 +1512,17 @@ async function handleStopUnlocked() {
       ? STOP_HISTORY_DEFERRED_EXIT_CODE
       : 1;
   }
-  const summary = summarizeStopRun(record, {
+  const signals = {
     failed: stopFailed,
     historyOnly: historyOnlyFailure,
     historyDeferred: historyDeferredNonces !== null,
     exitCode: Number(process.exitCode ?? 0),
-  });
+  };
+  const summary = summarizeStopRun(record, signals);
+  if (snapshot && !stopFailed) {
+    return guardFinalStopSummary(record, () => observeGuardedManagerStopped(snapshot.manager),
+      () => ({ ok: !stopFailed, summary }));
+  }
   return { ok: !stopFailed, summary };
 }
 

package/src/cli/registry.ts

@@ -83,7 +83,7 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   },
   {
     name: "service",
-    usage: "ocx service [install|repair|restart|start|stop|status|uninstall|remove]",
+    usage: "ocx service [install|repair|restart|start|stop|status|uninstall|remove|claim]",
     summary: "Run as a background service.",
     details: [
       "With no subcommand, installs when absent or repairs an existing service.",

package/src/cli/resolve.ts

@@ -45,6 +45,20 @@ import {
   type LiveProxy,
 } from "../server/proxy-liveness";
 import { endpointsToProve, everyEndpointProvenDownAsync, type ProbeEndpoint } from "./uninstall-plan";
+import {
+  resolveServiceOwnership,
+  resolveServiceState,
+  type ServiceInstallState,
+  type ServiceOwnershipResolution,
+  type ServiceStateResolution,
+} from "../service/state";
+import {
+  assessServiceTakeoverCompatibility,
+  type ManagingCliObservation,
+  type ManagingCliRole,
+} from "../service/ownership-compatibility";
+import { observeManagingClis } from "../service/managing-cli";
+import { SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION } from "../service/install-state-contract.mjs";
 
 /** Wire version of the resolve document. Bump only on an incompatible shape change. */
 export const RESOLVE_SCHEMA = "ocx-resolve/1";
@@ -86,8 +100,26 @@ export interface ResolveJson {
     source: LiveProxy["source"];
   };
   liveness: ResolveLivenessJson;
+  /**
+   * The recorded runtime owner, in the CLI's own three answers. `unknown` is on the wire
+   * deliberately: it never changes the exit code — the liveness verdict is still
+   * trustworthy — and the embedding shell fails closed on it rather than asking consent
+   * against a record it could not read.
+   */
+  ownership: ServiceOwnershipResolution;
+  /**
+   * Whether a desktop takeover can be offered, and the token that binds that approval to
+   * the exact subject and managing-CLI observations a later `ocx service claim` must find
+   * unchanged. `ownership-unknown` is produced only here: it is a wire reason, not a new
+   * member of `ServiceTakeoverCompatibility`'s union.
+   */
+  takeover: ResolveTakeover;
 }
 
+export type ResolveTakeover =
+  | { kind: "supported"; protocolVersion: number; minimumCliVersion: string; token: string }
+  | { kind: "blocked"; reason: string; detail: string; minimumCliVersion: string };
+
 export interface ResolveArgs {
   json: boolean;
 }
@@ -111,6 +143,14 @@ export interface ResolveIo {
   /** Tri-state endpoint probe; production default runs in-process for compiled standalone binaries. */
   probeEndpoint?: (endpoint: ProbeEndpoint) => EndpointLiveness | Promise<EndpointLiveness>;
   cliVersion?: () => string;
+  /** Recorded-ownership resolver; production default is resolveServiceOwnership. */
+  resolveOwnership?: () => ServiceOwnershipResolution;
+  /** Full install-state resolver; production default is resolveServiceState. */
+  resolveState?: () => ServiceStateResolution;
+  /** Managing-CLI observer; production default is observeManagingClis. */
+  observeManagers?: (
+    state: ServiceInstallState | null,
+  ) => Readonly<Record<ManagingCliRole, ManagingCliObservation>>;
   stdout?: { log: (s: string) => void };
   stderr?: { error: (s: string) => void };
 }
@@ -136,6 +176,8 @@ export function buildResolveJson(
   live: LiveProxy | null,
   configHome: string,
   cliVersion: string,
+  ownership: ServiceOwnershipResolution,
+  takeover: ResolveTakeover,
 ): ResolveJson {
   const configured = config.port ?? RESOLVE_DEFAULT_PORT;
   return {
@@ -148,6 +190,8 @@ export function buildResolveJson(
       source: live ? live.source : "config",
     },
     liveness: livenessJson(live),
+    ownership,
+    takeover,
   };
 }
 
@@ -164,6 +208,19 @@ function reportHuman(json: ResolveJson, stdout: { log: (s: string) => void }): v
   } else {
     stdout.log(`No live proxy (absence proven); effective port ${json.port.effective} (configured).`);
   }
+  const ownership = json.ownership;
+  if (ownership.kind === "owned") {
+    stdout.log(`Owner: ${ownership.ownership.owner} (install ${ownership.ownership.installId}, generation ${ownership.ownership.consentGeneration})`);
+  } else if (ownership.kind === "unknown") {
+    stdout.log(`Owner: unknown (${ownership.reason})`);
+  } else {
+    stdout.log("Owner: none recorded");
+  }
+  stdout.log(
+    json.takeover.kind === "supported"
+      ? "Takeover: supported"
+      : `Takeover: blocked (${json.takeover.reason}: ${json.takeover.detail})`,
+  );
 }
 
 /**
@@ -181,6 +238,9 @@ export async function runResolve(args: ResolveArgs, io: ResolveIo = {}): Promise
   const readRuntime = io.readRuntime ?? readRuntimePort;
   const probeEndpoint = io.probeEndpoint ?? probeEndpointLiveness;
   const cliVersion = io.cliVersion ?? packageVersion;
+  const resolveOwnership = io.resolveOwnership ?? resolveServiceOwnership;
+  const resolveState = io.resolveState ?? resolveServiceState;
+  const observeManagers = io.observeManagers ?? observeManagingClis;
   const configHome = configDir();
   let diagnostics: ConfigDiagnostics;
   try {
@@ -223,7 +283,59 @@ export async function runResolve(args: ResolveArgs, io: ResolveIo = {}): Promise
       return 1;
     }
   }
-  const json = buildResolveJson(diagnostics.config, live, configHome, cliVersion());
+  let ownership: ServiceOwnershipResolution;
+  try {
+    ownership = resolveOwnership();
+  } catch (error) {
+    ownership = { kind: "unknown", reason: error instanceof Error ? error.message : String(error) };
+  }
+  let takeover: ResolveTakeover;
+  if (!live) {
+    // A proven absence may authorize start, but there is no runtime to take over.
+    // Avoid synchronous managing-CLI version probes on this launch path.
+    takeover = {
+      kind: "blocked",
+      reason: "runtime-absent",
+      detail: "no live runtime is available for takeover",
+      minimumCliVersion: SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+    };
+  } else if (ownership.kind === "unknown") {
+    // The claim cannot be read, so nothing can be approved against it. This reason is a
+    // wire answer, not a new member of the compatibility union.
+    takeover = {
+      kind: "blocked",
+      reason: "ownership-unknown",
+      detail: ownership.reason,
+      minimumCliVersion: SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+    };
+  } else {
+    try {
+      const resolved = resolveState();
+      if (resolved.kind === "unknown") {
+        takeover = {
+          kind: "blocked",
+          reason: "ownership-unknown",
+          detail: resolved.reason,
+          minimumCliVersion: SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+        };
+      } else {
+        const resolvedState = resolved.kind === "state" ? resolved.state : null;
+        takeover = assessServiceTakeoverCompatibility({
+          state: resolvedState,
+          subject: ownership,
+          managers: observeManagers(resolvedState),
+        });
+      }
+    } catch (error) {
+      takeover = {
+        kind: "blocked",
+        reason: "managing-cli-unknown",
+        detail: error instanceof Error ? error.message : String(error),
+        minimumCliVersion: SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+      };
+    }
+  }
+  const json = buildResolveJson(diagnostics.config, live, configHome, cliVersion(), ownership, takeover);
   if (args.json) stdout.log(JSON.stringify(json));
   else reportHuman(json, stdout);
   return 0;

package/src/cli/root.ts

@@ -11,6 +11,7 @@
 import { hasHelpFlag, printSubcommandUsage, printUsage, printVersion } from "./help";
 import { parseReadyArgs, type ReadyArgs } from "./ready";
 import { parseResolveArgs, type ResolveArgs } from "./resolve";
+import { parseStopApproval } from "./stop-approval";
 import { maybeAutoRestoreCodexShim } from "./codex-shim-autorestore";
 
 export interface CliHead {
@@ -103,6 +104,10 @@ export async function runCli(argv: string[]): Promise<CliHead> {
       return head;
     }
     case "command":
+      if (head.command === "stop" && !parseStopApproval(head.args.slice(1)).ok) {
+        console.error("Usage: ocx stop [--json [--expect-pid <pid> --expect-port <port> --expect-hostname <host> --expect-config-home <home> --expect-cli-version <version> --expect-compatibility-token <hex>]]");
+        process.exit(64);
+      }
       maybeAutoRestoreCodexShim(head.command, head.args);
       return head;
   }

package/src/cli/stop-approval.ts

@@ -0,0 +1,186 @@
+/** Opt-in consistency guard for a desktop-approved stop. Not a consent proof. */
+import { waitForExit } from "../lib/process-control";
+import { waitForPortAvailable } from "../server/ports";
+import { probeEndpointLiveness, probeHostname } from "../server/proxy-liveness";
+import type { GuardedManagerTarget } from "../service/guarded-manager-target";
+import type { ResolveJson } from "./resolve";
+import { STOP_SUMMARY_SCHEMA, type StopOutcome, type StopRunRecord, type StopServiceOutcome } from "./stop-report";
+
+export interface StopApproval {
+  pid: number;
+  port: number;
+  hostname: string;
+  configHome: string;
+  cliVersion: string;
+  compatibilityToken: string;
+}
+
+export interface GuardedStopSnapshot {
+  approval: StopApproval;
+  manager: Exclude<GuardedManagerTarget, { kind: "unknown" }>;
+}
+
+function sameGuardedManager(
+  expected: GuardedStopSnapshot["manager"],
+  current: GuardedManagerTarget,
+): boolean {
+  if (expected.kind === "absent") return current.kind === "absent";
+  return current.kind === "bound" && current.pid === expected.pid
+    && current.managerPid === expected.managerPid && current.backend === expected.backend;
+}
+
+export type StopApprovalParse = { ok: true; json: boolean; approval: StopApproval | null } | { ok: false };
+
+export function parseStopApproval(argv: string[]): StopApprovalParse {
+  if (argv.length === 0) return { ok: true, json: false, approval: null };
+  if (argv.every(arg => arg === "--json")) return { ok: true, json: true, approval: null };
+  const names = ["--expect-pid", "--expect-port", "--expect-hostname",
+    "--expect-config-home", "--expect-cli-version", "--expect-compatibility-token"];
+  if (argv.filter(arg => arg === "--json").length !== 1) return { ok: false };
+  const values = new Map<string, string>();
+  for (let index = 0; index < argv.length; index += 1) {
+    const flag = argv[index]!;
+    if (flag === "--json") continue;
+    if (!names.includes(flag) || values.has(flag) || index + 1 >= argv.length) return { ok: false };
+    values.set(flag, argv[++index]!);
+  }
+  if (values.size !== names.length) return { ok: false };
+  const integer = (value: string | undefined, max: number): number | null => {
+    if (!value || !/^\d+$/.test(value)) return null;
+    const parsed = Number(value);
+    return Number.isSafeInteger(parsed) && parsed > 0 && parsed <= max ? parsed : null;
+  };
+  const pid = integer(values.get("--expect-pid"), Number.MAX_SAFE_INTEGER);
+  const port = integer(values.get("--expect-port"), 65535);
+  const compatibilityToken = values.get("--expect-compatibility-token") ?? "";
+  const configHome = values.get("--expect-config-home") ?? "";
+  const cliVersion = values.get("--expect-cli-version") ?? "";
+  if (pid === null || port === null || !/^[a-f0-9]{64}$/.test(compatibilityToken)
+    || !configHome || !cliVersion) return { ok: false };
+  return { ok: true, json: true, approval: {
+    pid, port, hostname: values.get("--expect-hostname") ?? "",
+    configHome, cliVersion, compatibilityToken,
+  } };
+}
+
+export function matchesStopApproval(expected: StopApproval, now: ResolveJson): boolean {
+  return now.schema === "ocx-resolve/1" && now.liveness.status === "live"
+    && now.liveness.pid === expected.pid && now.liveness.port === expected.port
+    && now.port.effective === expected.port && (now.liveness.hostname ?? "") === expected.hostname
+    && now.liveness.role !== "client" && now.configHome === expected.configHome
+    && now.cliVersion === expected.cliVersion && now.ownership.kind !== "unknown"
+    && now.takeover.kind === "supported" && now.takeover.token === expected.compatibilityToken;
+}
+
+export function approvalChanged(): StopOutcome {
+  return { ok: false, summary: {
+    schema: STOP_SUMMARY_SCHEMA, ok: false, outcome: "approval-changed", exitCode: 1,
+    runtimeDown: false, service: "absent", proxy: "unknown", sharedTeardown: "skipped",
+    message: "The approved runtime or managing CLI changed; no stop was attempted.",
+  } };
+}
+
+export function managerStillActive(
+  service: StopServiceOutcome,
+  record?: Pick<StopRunRecord, "proxy" | "sharedTeardown">,
+): StopOutcome {
+  return { ok: false, summary: {
+    schema: STOP_SUMMARY_SCHEMA, ok: false, outcome: "manager-still-active", exitCode: 1,
+    runtimeDown: false, service,
+    proxy: record?.proxy ?? "unknown", sharedTeardown: record?.sharedTeardown ?? "skipped",
+    message: "The approved runtime and service manager could not both be confirmed stopped.",
+  } };
+}
+
+export async function runApprovedStop(
+  expected: StopApproval,
+  read: () => Promise<ResolveJson | null>,
+  tracked: () => { pid: number; port: number; hostname: string } | null,
+  managerTarget: () => GuardedManagerTarget,
+  stop: (snapshot: GuardedStopSnapshot) => Promise<StopOutcome>,
+): Promise<StopOutcome> {
+  let snapshot: GuardedStopSnapshot | null = null;
+  try {
+    const now = await read();
+    const target = tracked();
+    const manager = managerTarget();
+    if (!now || !matchesStopApproval(expected, now) || !target
+      || target.pid !== expected.pid || target.port !== expected.port
+      || target.hostname !== expected.hostname || manager.kind === "unknown"
+      || (manager.kind === "bound" && manager.pid !== expected.pid)) return approvalChanged();
+    snapshot = { approval: expected, manager };
+  } catch { return approvalChanged(); }
+  return snapshot ? stop(snapshot) : approvalChanged();
+}
+
+const GUARDED_SETTLE_MS = 5_000;
+
+/** Compose the existing bounded PID/port waiters, then prove health absence. */
+export async function settleApprovedTarget(
+  approved: StopApproval,
+  io: {
+    now?: () => number;
+    waitExit?: (pid: number, timeoutMs: number) => boolean;
+    waitPort?: typeof waitForPortAvailable;
+    probe?: typeof probeEndpointLiveness;
+  } = {},
+): Promise<boolean> {
+  const now = io.now ?? Date.now;
+  const deadline = now() + GUARDED_SETTLE_MS;
+  const remaining = () => Math.max(0, deadline - now());
+  if (!(io.waitExit ?? waitForExit)(approved.pid, remaining()) || remaining() <= 0) return false;
+  const hostname = probeHostname(approved.hostname || undefined);
+  if (!await (io.waitPort ?? waitForPortAvailable)(approved.port, hostname,
+    { timeoutMs: remaining(), intervalMs: 50 }) || remaining() <= 0) return false;
+  const verdict = await (io.probe ?? probeEndpointLiveness)(
+    { port: approved.port, hostname: approved.hostname || undefined },
+    { timeoutMs: Math.min(250, remaining()) },
+  );
+  return verdict === "dead" && now() <= deadline;
+}
+
+export async function runGuardedManagerStep(
+  snapshot: GuardedStopSnapshot,
+  io: {
+    revalidateManager: () => GuardedManagerTarget;
+    stopManager: () => StopServiceOutcome;
+    signalApproved: () => Promise<boolean>;
+    settle: () => Promise<boolean>;
+    managerState: () => Promise<"inactive" | "active" | "unknown">;
+  },
+): Promise<{ service: StopServiceOutcome; effect: "stopped" | "approval-changed" | "manager-still-active" | "failed";
+  proxy: "stopped" | "unknown"; handledByProxy: boolean }> {
+  try {
+    if (!sameGuardedManager(snapshot.manager, io.revalidateManager())) {
+      return { service: "absent", effect: "approval-changed", proxy: "unknown", handledByProxy: false };
+    }
+  } catch {
+    return { service: "absent", effect: "approval-changed", proxy: "unknown", handledByProxy: false };
+  }
+  const service = snapshot.manager.kind === "absent" ? "absent" : io.stopManager();
+  let handledByProxy = false;
+  if (snapshot.manager.kind === "absent") {
+    try { handledByProxy = await io.signalApproved(); }
+    catch { return { service, effect: "failed", proxy: "unknown", handledByProxy }; }
+  }
+  if (!await io.settle()) {
+    return { service, effect: "manager-still-active", proxy: "unknown", handledByProxy };
+  }
+  try {
+    if (await io.managerState() !== "inactive") {
+      return { service, effect: "manager-still-active", proxy: "unknown", handledByProxy };
+    }
+  } catch { return { service, effect: "manager-still-active", proxy: "unknown", handledByProxy }; }
+  return { service, effect: "stopped", proxy: "stopped", handledByProxy };
+}
+
+export async function guardFinalStopSummary(
+  record: StopRunRecord,
+  managerState: () => Promise<"inactive" | "active" | "unknown">,
+  finish: () => StopOutcome,
+): Promise<StopOutcome> {
+  try {
+    if (await managerState() !== "inactive") return managerStillActive(record.service, record);
+  } catch { return managerStillActive(record.service, record); }
+  return finish();
+}

package/src/cli/stop-report.ts

@@ -67,7 +67,7 @@ export interface StopSummaryJson {
   schema: typeof STOP_SUMMARY_SCHEMA;
   /** Strict exit-code view: true only for exit 0. */
   ok: boolean;
-  outcome: "stopped" | "not-running" | "history-incomplete" | "history-deferred" | "failed";
+  outcome: "stopped" | "not-running" | "history-incomplete" | "history-deferred" | "failed" | "approval-changed" | "manager-still-active";
   exitCode: number;
   /** True when this stop left no proxy of this home running by its own paths. */
   runtimeDown: boolean;

package/src/cli/system-restart-client.ts

@@ -16,7 +16,9 @@ import {
 } from "../lib/system-restart-contract";
 import {
   findLiveProxy,
+  isHealthzVersion,
   isOpencodexHealthz,
+  isPackageTreeFencedHealthz,
   probeHostname,
   type HealthzIdentity,
   type LiveProxy,
@@ -105,9 +107,12 @@ export async function requestBoundSystemRestart(
   }
   const body = await proofResponse.json().catch(() => null) as HealthzIdentity | null;
   const proof = proofResponse.headers.get(LOCAL_ATTESTATION_PROOF_HEADER);
+  // A package-tree fence answers /healthz with 503 but still proves its identity (#5496).
+  // Only that exact body is admitted as a non-OK proof response; the proof check is unchanged.
+  const fenced = proofResponse.status === 503 && isPackageTreeFencedHealthz(body);
   if (
-    !proofResponse.ok
-    || !isOpencodexHealthz(body)
+    !(proofResponse.ok || fenced)
+    || !(isOpencodexHealthz(body) || fenced)
     || body?.pid !== target.pid
     || !verifyLocalAttestationProof(runtime.attestationSecret, challenge, target.pid, target.port, proof)
   ) {
@@ -127,14 +132,24 @@ export async function requestBoundSystemRestart(
   // diagnosis compares (packageVersion vs the /healthz version), so reuse that
   // comparison and refuse before POST. Placeholder versions (unknown/0.0.0) are
   // "cannot compare", not mismatch, and keep the existing behavior.
-  const proxyVersion = typeof body.version === "string" ? body.version : undefined;
+  //
+  // A fenced proxy booted from files that have since been replaced at the same path, so its
+  // boot version differs from this CLI by construction. What the respawn will run is the
+  // manifest now on disk, which the fence reports as installedVersion. Without a readable
+  // one the replacement is still in flight and restarting now could load a partial tree.
+  if (fenced && !isHealthzVersion(body.installedVersion)) {
+    return rejected("restart_package_tree_unsettled");
+  }
+  const proxyVersion = fenced
+    ? body.installedVersion as string
+    : typeof body.version === "string" ? body.version : undefined;
   if (computeVersionSkew(deps.cliVersion ?? ownCliVersion(), proxyVersion).skewed) {
     return rejected("restart_version_skew");
   }
 
   let observed: LiveProxy | null;
   try {
-    observed = await (deps.findLive ?? findLiveProxy)({ deadlineAt, nowFn: now });
+    observed = await (deps.findLive ?? findLiveProxy)({ deadlineAt, nowFn: now, acceptPackageTreeFenced: true });
   } catch {
     return rejected("restart_target_recheck_failed");
   }