@bitkyc08/opencodex 2.67.0 → 2.68.0-preview.20260927

package/src/images/loop.ts

@@ -23,6 +23,7 @@ import { clearableDeadline, idleDeadline } from "../lib/abort";
 import { readBoundedResponseBody } from "../lib/bounded-body";
 import { applyUpstreamRecoveryInit, fetchWithResetRetry, prepareSameTarget429Wait } from "../lib/upstream-retry";
 import { rateLimitRetryDelayMs } from "../providers/key-failover";
+import { releaseProviderRequestSlot, sendTrackingRequestSlot, type ProviderRequestSlot } from "../providers/request-pacing";
 import {
   createTranslatorBudget,
   isTranslatorBudgetExceededError,
@@ -309,7 +310,7 @@ export interface ImageBridgeDeps {
   /** Bind physical dispatch to this iteration's built request; pacing remains owned by the loop. */
   fetchForRequest?: (request: AdapterRequest, parsed: OcxParsedRequest) => typeof globalThis.fetch;
   /** Reserve the routed provider's next request-start slot before each adapter dispatch. */
-  waitForRequestSlot?: (signal?: AbortSignal) => Promise<void>;
+  waitForRequestSlot?: (signal?: AbortSignal) => Promise<ProviderRequestSlot | void>;
   /** Raw adapter usage at the terminal event, pre wire-normalization (see bridgeToResponsesSSE onUsage). */
   onUsage?: (usage: OcxUsage | undefined) => void;
   /**
@@ -334,6 +335,7 @@ export interface ImageBridgeDeps {
     retryAfterHeader: string | null,
     responseHeaders?: Headers,
     retryParsed?: OcxParsedRequest,
+    originalResponse?: Response,
   ) =>
     | { adapter: ProviderAdapter; recoveryKind: AttemptRecoveryKind }
     | null
@@ -466,7 +468,7 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
     // expose buildRequest/fetchResponse/parseStream to the bridge, so collect their events through
     // an AdapterEventQueue and pass the bounded collection directly to the common scanner.
     if (adapter.runTurn) {
-      await deps.waitForRequestSlot?.(signal);
+      const pacingSlot = (await deps.waitForRequestSlot?.(signal)) || undefined;
       const queue = createAdapterEventQueue({
         onBacklogExceeded: () => internalAbort.abort("runTurn backlog exceeded"),
       });
@@ -514,6 +516,7 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
           headers: deps.forwardHeaders ? new Headers(deps.forwardHeaders) : new Headers(),
           abortSignal: signal,
           translatorBudget,
+          pacingSlot,
         }, emit).then(closeOnAbort).catch(err => {
           if (accepting) {
             collectionError = err;
@@ -528,6 +531,7 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
           if (event.type !== "heartbeat") events.push(event);
         }
       } finally {
+        releaseProviderRequestSlot(pacingSlot);
         accepting = false;
         idle.cancel();
         signal.removeEventListener("abort", closeOnAbort);
@@ -561,10 +565,11 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
     }
 
     let headerDeadline = clearableDeadline(connectTimeoutMs, signal);
-    const paceThenResetHeaderDeadline = async (): Promise<void> => {
+    const paceThenResetHeaderDeadline = async (): Promise<ProviderRequestSlot | undefined> => {
       headerDeadline.clear();
-      await deps.waitForRequestSlot?.(signal);
+      const slot = (await deps.waitForRequestSlot?.(signal)) || undefined;
       headerDeadline = clearableDeadline(connectTimeoutMs, signal);
+      return slot;
     };
     try {
       /**
@@ -597,35 +602,43 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
         let response: Response;
         try {
           if (requestAdapter.fetchResponse) {
-            await paceThenResetHeaderDeadline();
-            deps.onAttemptSend?.(recovery);
-            response = await requestAdapter.fetchResponse(request, {
-              abortSignal: headerDeadline.signal,
-              timeoutMs: connectTimeoutMs,
-              returnRawErrors: true,
-              stream: true,
-              executor: requestFetch,
-            });
+            const slot = await paceThenResetHeaderDeadline();
+            try {
+              deps.onAttemptSend?.(recovery);
+              response = await sendTrackingRequestSlot(slot, () => requestAdapter.fetchResponse!(request, {
+                abortSignal: headerDeadline.signal,
+                timeoutMs: connectTimeoutMs,
+                returnRawErrors: true,
+                stream: true,
+                executor: requestFetch,
+              }));
+            } finally {
+              releaseProviderRequestSlot(slot);
+            }
           } else {
             response = await fetchWithResetRetry(
               async (retryRecovery) => {
-                await paceThenResetHeaderDeadline();
-                // Record every helper-driven send (the callback runs for the first attempt and
-                // each connection-reset replay); preserve the caller's recovery kind
-                // (rate-limit-429 / key-429) when the retry layer supplies none.
-                deps.onAttemptSend?.(retryRecovery ?? recovery);
-                const h = new Headers(request.headers);
-                if (!h.has("accept-encoding")) h.set("accept-encoding", "identity");
-                // Same reset-recovery parity as the web-search loop: the replay needs
-                // `keepalive: false` to abandon the pooled socket, because Bun has ignored the
-                // hop-by-hop header alone (oven-sh/bun#20492).
-                return requestFetch(request.url, applyUpstreamRecoveryInit({
-                  method: request.method,
-                  redirect: "manual",
-                  headers: h,
-                  body: request.body,
-                  signal: headerDeadline.signal,
-                }, retryRecovery));
+                const slot = await paceThenResetHeaderDeadline();
+                try {
+                  // Record every helper-driven send (the callback runs for the first attempt and
+                  // each connection-reset replay); preserve the caller's recovery kind
+                  // (rate-limit-429 / key-429) when the retry layer supplies none.
+                  deps.onAttemptSend?.(retryRecovery ?? recovery);
+                  const h = new Headers(request.headers);
+                  if (!h.has("accept-encoding")) h.set("accept-encoding", "identity");
+                  // Same reset-recovery parity as the web-search loop: the replay needs
+                  // `keepalive: false` to abandon the pooled socket, because Bun has ignored the
+                  // hop-by-hop header alone (oven-sh/bun#20492).
+                  return await sendTrackingRequestSlot(slot, () => requestFetch(request.url, applyUpstreamRecoveryInit({
+                    method: request.method,
+                    redirect: "manual",
+                    headers: h,
+                    body: request.body,
+                    signal: headerDeadline.signal,
+                  }, retryRecovery)));
+                } finally {
+                  releaseProviderRequestSlot(slot);
+                }
               },
               { replaySafe: true, abortSignal: headerDeadline.signal, label: "image-bridge-loop" },
             );
@@ -671,8 +684,10 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
         prepared = await fetchOnce(adapter, "rate-limit-429");
       }
       // 429 key-failover parity with web-search / normal routed path.
-      while (prepared.response.status === 429 && deps.on429) {
-        const rotated = await deps.on429(prepared.response.headers.get("retry-after"), prepared.response.headers, iterParsed);
+      while ((prepared.response.status === 429
+        || (iterParsed._kiroAuthContext && (prepared.response.status === 400 || prepared.response.status === 403))) && deps.on429) {
+        const rotated = await deps.on429(prepared.response.headers.get("retry-after"), prepared.response.headers,
+          iterParsed, prepared.response);
         if (!rotated) break;
         try { void prepared.response.body?.cancel().catch(() => {}); } catch { /* already closed */ }
         adapter = rotated.adapter;

package/src/integrations/catalog-refresh.ts

@@ -1,3 +1,4 @@
+import { siblingOfLivePort } from "../codex/sibling-start";
 import { redactSecretString } from "../lib/redact";
 import type { ExportModel } from "../clients/config-export";
 import type { IntegrationClientId } from "./registry";
@@ -12,6 +13,9 @@ export async function refreshOwnedCatalogIntegrations(
   input: Omit<OwnedIntegrationRefreshInput, "clientId">,
   clientIds: readonly IntegrationClientId[] = ["pi", "aside", "raycast", "omo"],
 ): Promise<OwnedIntegrationRefreshOutcome[]> {
+  // Client files are shared with the live proxy a sibling instance runs beside; their entries
+  // point at the owner's port, and refreshing them here would re-point them at this one.
+  if (siblingOfLivePort() !== null) return [];
   let models: Promise<readonly ExportModel[]> | undefined;
   const loadModels = () => models ??= Promise.resolve().then(() =>
     typeof input.models === "function" ? input.models() : input.models);

package/src/integrations/omp-yaml-source.ts

@@ -274,6 +274,7 @@ function childEnd(
       const nextSpaces = leadingSpaces(lines[ahead]!.body);
       if (nextSpaces === null) return null;
       if (nextSpaces <= indent) return index;
+      index = ahead - 1;
       continue;
     }
     if (quote === null && isComment(body)) return spaces <= indent ? index : null;

package/src/lib/claude-request-projection.ts

@@ -0,0 +1,101 @@
+/**
+ * Project a Messages request body onto the content a settled route actually serializes.
+ *
+ * `estimateClaudeRequestTokens` measures the caller's body as JSON. That is exactly right for the
+ * Anthropic-native wire, where a replayed `thinking` block — signature included — is forwarded
+ * verbatim. A routed wire may serialize far less, and on the Chat wire it does: replayed thinking
+ * becomes an optional `reasoning_content` string, the signature is never sent at all
+ * (`src/adapters/openai-chat/messages.ts` has no `signature` reference), and the text is dropped
+ * outright unless the model is on the provider's `preserveReasoningContentModels` list.
+ *
+ * The gap that opens is not a rounding error. On a captured 260-message Claude Code turn, replayed
+ * thinking blocks were 78.8% of the body's JSON characters and 56.7% of those characters were
+ * base64 signatures — bytes that are not prompt text under any tokenizer. Counting them made the
+ * published `message_start.usage.input_tokens` 3.28x the count the upstream actually reported
+ * (#4857 + the Paseo context meter it feeds), well past the >2x drift bound this estimator is held
+ * to (devlog 260711_claude_inbound 040 §3).
+ *
+ * The projection is therefore applied to the ESTIMATE only. The body the caller sent is never
+ * rewritten; this is a measurement that describes the route, not a transformation of the request.
+ */
+
+/** Which replayed reasoning blocks and fields a wire serializes. */
+export interface ClaudeThinkingProjection {
+  /** Serialize `thinking.thinking`, the model's own replayed text. */
+  text: boolean;
+  /**
+   * Serialize `thinking.signature`, the provider's base64 replay token. Real prompt size for
+   * wires that carry it; pure overhead for wires that do not.
+   */
+  signature: boolean;
+  /**
+   * Serialize a `redacted_thinking` block, whose `data` is an opaque provider blob. It rides
+   * alongside `thinking` rather than inside it: a wire can reconstruct the model's reasoning
+   * without carrying the encrypted form, and the Chat wire does exactly that.
+   */
+  redacted: boolean;
+}
+
+/**
+ * The Anthropic-native wire forwards a replayed thinking block verbatim, signature included, so
+ * nothing is projected away. This is the default: an unknown route keeps the measured body.
+ */
+export const CLAUDE_NATIVE_THINKING: ClaudeThinkingProjection = { text: true, signature: true, redacted: true };
+
+interface ProjectableBody {
+  system?: unknown;
+  messages?: unknown;
+  tools?: unknown;
+}
+
+/**
+ * One content block as the given wire would carry it.
+ *
+ * `undefined` means the wire sends nothing for it, and the caller drops the entry. A `thinking`
+ * block that keeps its text but not its signature is returned as a copy rather than edited: the
+ * block object is shared with the outbound request builder, which must stay untouched.
+ */
+function projectBlock(block: unknown, thinking: ClaudeThinkingProjection): unknown {
+  if (!block || typeof block !== "object") return block;
+  if (!("type" in block)) return block;
+  if (block.type === "redacted_thinking") return thinking.redacted ? block : undefined;
+  if (block.type !== "thinking") return block;
+  if (!thinking.text) return undefined;
+  if (thinking.signature || !("signature" in block)) return block;
+  // Copy without the signature: the caller's block object is shared with the outbound request
+  // builder, so it must never be edited in place.
+  const { signature: _dropped, ...rest } = block;
+  return rest;
+}
+
+/**
+ * A copy of `raw` whose message content carries only the replayed thinking this route serializes.
+ *
+ * Pure and idempotent; the input is never mutated. Blocks are dropped only inside array-valued
+ * message `content`, which is the sole protocol position a replayed thinking block occupies.
+ * A message whose content array empties out is left as an empty array rather than deleted: the
+ * adapter's own "nothing left to send" rule is keyed on text, tool calls and reasoning together,
+ * and re-deriving it here would be a second copy of that rule to keep in sync.
+ */
+export function projectClaudeRequest(
+  raw: ProjectableBody,
+  thinking: ClaudeThinkingProjection,
+): ProjectableBody {
+  if (thinking.text && thinking.signature && thinking.redacted) return raw;
+  if (!Array.isArray(raw.messages)) return raw;
+  const messages = raw.messages as unknown[];
+  return {
+    ...raw,
+    messages: messages.map(message => {
+      if (!message || typeof message !== "object") return message;
+      if (!("content" in message) || !Array.isArray(message.content)) return message;
+      const content = message.content as unknown[];
+      return {
+        ...message,
+        content: content
+          .map(block => projectBlock(block, thinking))
+          .filter(block => block !== undefined),
+      };
+    }),
+  };
+}

package/src/lib/local-account-switch-capability.ts

@@ -0,0 +1,48 @@
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+import { isLocalAttestationSecret } from "./local-management-attestation";
+import { LOCAL_MANAGEMENT_CAPABILITY_TTL_MS } from "./local-management-capability";
+
+export const LOCAL_ACCOUNT_SWITCH_PATHS = [
+  "/api/codex-auth/active",
+  "/api/oauth/accounts/active",
+  "/api/providers/keys/active",
+] as const;
+export const LOCAL_ACCOUNT_SWITCH_BODY_HEADER = "x-opencodex-account-switch-sha256";
+const BASE64URL_256 = /^[A-Za-z0-9_-]{43}$/;
+
+export function isLocalAccountSwitchPath(path: string): boolean {
+  return LOCAL_ACCOUNT_SWITCH_PATHS.some(candidate => candidate === path);
+}
+
+/** Digest the exact bytes on the wire, before parsing or reserialization. */
+export function accountSwitchBodyDigest(body: Uint8Array): string {
+  return createHash("sha256").update(body).digest("base64url");
+}
+
+export function createLocalAccountSwitchCapability(
+  secret: string, nonce: string, method: string, path: string,
+  pid: number, port: number, expiresAt: number, bodyDigest: string,
+): string | null {
+  if (!isLocalAttestationSecret(secret) || !BASE64URL_256.test(nonce)) return null;
+  if (method !== "PUT" || !isLocalAccountSwitchPath(path)) return null;
+  if (!Number.isSafeInteger(pid) || pid <= 0) return null;
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) return null;
+  if (!Number.isSafeInteger(expiresAt) || expiresAt <= 0) return null;
+  if (!BASE64URL_256.test(bodyDigest)) return null;
+  const payload = `opencodex-local-account-switch-v1\n${nonce}\n${method}\n${path}\n${pid}\n${port}\n${expiresAt}\n${bodyDigest}`;
+  return createHmac("sha256", secret).update(payload).digest("base64url");
+}
+
+export function verifyLocalAccountSwitchCapability(
+  secret: string, nonce: string | null, method: string, path: string,
+  pid: number, port: number, expiresAt: number, bodyDigest: string | null,
+  capability: string | null, now = Date.now(),
+): boolean {
+  if (!nonce || !bodyDigest || !capability || !BASE64URL_256.test(capability)) return false;
+  if (!Number.isSafeInteger(now) || expiresAt <= now
+    || expiresAt > now + LOCAL_MANAGEMENT_CAPABILITY_TTL_MS) return false;
+  const expected = createLocalAccountSwitchCapability(
+    secret, nonce, method, path, pid, port, expiresAt, bodyDigest,
+  );
+  return expected !== null && timingSafeEqual(Buffer.from(expected), Buffer.from(capability));
+}

package/src/lib/local-upstream.ts

@@ -0,0 +1,146 @@
+/**
+ * Classify an upstream provider destination as local or public.
+ *
+ * A *local* upstream is operator-trusted infrastructure on the same machine or LAN — LM Studio,
+ * Ollama, a self-hosted vLLM, a local gateway. Those models are frequently CPU-bound and their
+ * time-to-first-token or thinking phases can go silent for minutes, so a stall budget applied
+ * there would kill healthy turns. The stall resolver (`src/stall-timeout.ts`) therefore treats an
+ * unset budget on a local upstream as *disabled* while public upstreams keep the 300 s default.
+ *
+ * The destination is the provider's `baseUrl` (or the built request URL) — where the proxy
+ * actually dials upstream. This is a different question from
+ * `src/lib/local-destinations.ts`, which answers where local clients dial *this hub*; do not
+ * conflate them.
+ *
+ * Conservative on purpose: only clear local evidence (loopback, private, link-local, or a
+ * `.local`/`.lan` name) earns the disabled budget. Anything else — a public DNS name, an
+ * unreachable host, a bare domain — stays public and keeps its stall budget, because being local
+ * is what switches OFF a safety clock.
+ */
+import { isIP } from "node:net";
+
+/** True when the provider destination is local infrastructure and its stall budget should default to disabled. */
+export function isLocalUpstream(destination: string | null | undefined): boolean {
+  if (!destination) return false;
+  // A bare IP literal must be classified before URL parsing: `new URL("fe80::1")` reads the first
+  // hextet as a scheme and yields an empty host, and `new URL("::1")` throws — either way the host
+  // would be lost. Zone ids (`fe80::1%eth0`) are stripped for the family check.
+  const trimmed = destination.trim();
+  const literalFamily = isIP(trimmed.split("%")[0]);
+  if (literalFamily === 4) return isLocalIpv4(trimmed);
+  if (literalFamily === 6) return isLocalIpv6(trimmed.split("%")[0]);
+
+  const host = hostnameOf(destination);
+  if (!host) return false;
+  const bare = host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+  const normalized = bare.toLowerCase().split("%")[0].replace(/\.$/, "");
+  if (normalized === "") return false;
+  if (normalized === "localhost") return true;
+  if (normalized.endsWith(".local") || normalized.endsWith(".lan")) return true;
+  const family = isIP(normalized);
+  if (family === 4) return isLocalIpv4(normalized);
+  if (family === 6) return isLocalIpv6(normalized);
+  return false;
+}
+
+/**
+ * Extract a hostname from a full URL or a schemeless `host:port` / bare host.
+ *
+ * `new URL` handles the scheme-bearing forms (it keeps IPv6 brackets in `hostname`); the fallback
+ * recovers the host from a schemeless string by dropping a port or bracketed IPv6 suffix.
+ */
+function hostnameOf(destination: string): string | null {
+  const trimmed = destination.trim();
+  if (!trimmed) return null;
+  // Only trust `new URL` when it produces a non-empty host. `new URL("localhost:1234")` succeeds
+  // but reads `localhost` as a scheme and leaves the host empty, so fall through to the schemeless
+  // parse in that case rather than returning null.
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed)) {
+    try {
+      const parsed = new URL(trimmed).hostname;
+      if (parsed) return parsed;
+    } catch {
+      // Not an absolute URL after all: fall through to the schemeless forms.
+    }
+  }
+  let host = trimmed;
+  if (host.startsWith("[")) {
+    const end = host.indexOf("]");
+    host = end > 0 ? host.slice(1, end) : host.slice(1);
+  } else {
+    const colon = host.indexOf(":");
+    if (colon >= 0) host = host.slice(0, colon);
+  }
+  return host || null;
+}
+
+/** 0.0.0.0/8, 10/8, 127/8 (loopback), 169.254/16 (link-local), 172.16/12, 192.168/16. */
+function isLocalIpv4(host: string): boolean {
+  const parts = host.split(".");
+  if (parts.length !== 4) return false;
+  const octets: number[] = [];
+  for (const part of parts) {
+    if (!/^\d{1,3}$/.test(part)) return false;
+    const value = Number(part);
+    if (value > 255) return false;
+    octets.push(value);
+  }
+  const [a, b] = octets;
+  if (a === 0) return true;
+  if (a === 10) return true;
+  if (a === 127) return true;
+  if (a === 169 && b === 254) return true;
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 192 && b === 168) return true;
+  return false;
+}
+
+/** ::1 (loopback), `::ffff:a.b.c.d` (mapped), fe80::/10 (link-local), fc00::/7 (unique-local). */
+function isLocalIpv6(host: string): boolean {
+  const lower = host.toLowerCase();
+  const groups = ipv6Groups(lower);
+  if (!groups) return false;
+  // Loopback in any spelling: every group zero except a trailing one.
+  if (groups.every((group, index) => (index < 7 ? group === 0 : group === 1))) return true;
+  const mapped = lower.match(/^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/);
+  if (mapped) return isLocalIpv4(mapped[1]);
+  const first = groups[0];
+  if ((first & 0xffc0) === 0xfe80) return true;
+  if ((first & 0xfe00) === 0xfc00) return true;
+  return false;
+}
+
+/** Expand a (possibly `::`-compressed) IPv6 literal into eight 16-bit groups, or null if malformed. */
+function ipv6Groups(host: string): number[] | null {
+  const marker = host.indexOf("::");
+  const compressed = marker >= 0;
+  const head = compressed ? host.slice(0, marker) : host;
+  const tail = compressed ? host.slice(marker + 2) : "";
+  const headGroups = head === "" ? [] : head.split(":");
+  let tailGroups = tail === "" ? [] : tail.split(":");
+  // A trailing embedded IPv4 (e.g. `64:ff9b::1.2.3.4`) counts as two groups.
+  const last = tailGroups[tailGroups.length - 1];
+  if (last !== undefined && last.includes(".")) {
+    const v4 = last.split(".");
+    if (v4.length === 4 && v4.every((part) => /^\d{1,3}$/.test(part) && Number(part) <= 255)) {
+      const [o0, o1, o2, o3] = v4.map(Number);
+      tailGroups = [...tailGroups.slice(0, -1), ((o0 << 8) | o1).toString(16), ((o2 << 8) | o3).toString(16)];
+    } else return null;
+  }
+  let groups: string[];
+  if (compressed) {
+    // `::` fills the gap *between* head and tail with zero groups, not at either end.
+    const fill = 8 - headGroups.length - tailGroups.length;
+    if (fill < 1) return null;
+    groups = [...headGroups, ...Array<string>(fill).fill("0"), ...tailGroups];
+  } else {
+    groups = [...headGroups, ...tailGroups];
+    if (groups.length !== 8) return null;
+  }
+  const numbers = groups.map((group) => (isHextet(group) ? parseInt(group, 16) : Number.NaN));
+  return numbers.some((group) => Number.isNaN(group)) ? null : numbers;
+}
+
+function isHextet(token: string): boolean {
+  return /^[0-9a-f]{1,4}$/i.test(token);
+}

package/src/lib/package-tree-integrity.ts

@@ -1,4 +1,6 @@
 import { readFileSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { isStandaloneBinary } from "./standalone";
 
 export interface PackageTreeObservation {
@@ -63,9 +65,19 @@ const packageManifestUrl = new URL("../../package.json", import.meta.url);
 
 const INSTALLED_VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
 
+/** Directory of the package this process was loaded from, as the module loader spells it. */
+export function runningPackageRoot(): string {
+  return dirname(fileURLToPath(packageManifestUrl));
+}
+
 function readInstalledManifestVersion(): string | undefined {
+  return readPackageManifestVersionAt(fileURLToPath(packageManifestUrl));
+}
+
+/** The `version` of the manifest at `manifestPath`, or undefined when unreadable or malformed. */
+export function readPackageManifestVersionAt(manifestPath: string): string | undefined {
   try {
-    const version = (JSON.parse(readFileSync(packageManifestUrl, "utf8")) as { version?: unknown }).version;
+    const version = (JSON.parse(readFileSync(manifestPath, "utf8")) as { version?: unknown }).version;
     return typeof version === "string" && version.length <= 64 && INSTALLED_VERSION_PATTERN.test(version)
       ? version
       : undefined;
@@ -75,8 +87,13 @@ function readInstalledManifestVersion(): string | undefined {
 }
 
 function observePackageManifest(): PackageTreeObservation | null {
+  return observePackageManifestAt(fileURLToPath(packageManifestUrl));
+}
+
+/** Identity of the manifest at `manifestPath`, or null when it cannot be stat'd. */
+export function observePackageManifestAt(manifestPath: string): PackageTreeObservation | null {
   try {
-    const stat = statSync(packageManifestUrl, { bigint: true });
+    const stat = statSync(manifestPath, { bigint: true });
     return {
       device: stat.dev,
       inode: stat.ino,
@@ -99,7 +116,12 @@ function observePackageManifest(): PackageTreeObservation | null {
   }
 }
 
-function sameObservation(left: PackageTreeObservation, right: PackageTreeObservation): boolean {
+/** The manifest path inside a package root. */
+export function packageManifestPathIn(root: string): string {
+  return join(root, "package.json");
+}
+
+export function sameObservation(left: PackageTreeObservation, right: PackageTreeObservation): boolean {
   return left.device === right.device
     && left.inode === right.inode
     && left.contentTimeNs === right.contentTimeNs

package/src/lib/package-tree-retarget.ts

@@ -0,0 +1,130 @@
+import {
+  packageManifestPathIn,
+  readPackageManifestVersionAt,
+  sameObservation,
+  type PackageTreeObservation,
+} from "./package-tree-integrity";
+
+/**
+ * The package a service launcher would start right now: its canonical root and the identity of
+ * the manifest inside it. Null when the launcher, its target or the manifest cannot be resolved.
+ */
+export interface LauncherTarget {
+  readonly root: string;
+  readonly manifest: PackageTreeObservation;
+}
+
+export type ResolveLauncherTarget = () => LauncherTarget | null;
+
+export interface PackageTreeRetargetOptions {
+  /** How often the launcher is re-resolved. Detection must not depend on inbound requests. */
+  pollIntervalMs?: number;
+  /** How long one complete target identity must hold before the restart is requested. */
+  settleMs?: number;
+  now?: () => number;
+  /** Test seam; production uses an unref'd timer and returns its cancellation. */
+  schedule?: (callback: () => void, delayMs: number) => () => void;
+  /** Test seam for the settled target's version; production reads its package manifest. */
+  readVersion?: (root: string) => string | undefined;
+}
+
+export interface PackageTreeRetargetWatch {
+  /**
+   * Version of the package the launcher now starts, once that target has held for the full
+   * settle interval and still resolves to the same identity. A fenced `/healthz` reports it
+   * when the running tree itself has gone, so `ocx restart` compares against what the
+   * supervisor will actually start.
+   */
+  settledVersion(): string | undefined;
+  /** Stops polling and invalidates any pending restart request. */
+  dispose(): void;
+}
+
+const DEFAULT_POLL_INTERVAL_MS = 5_000;
+const DEFAULT_SETTLE_MS = 5_000;
+
+function sameTarget(left: LauncherTarget, right: LauncherTarget): boolean {
+  return left.root === right.root && sameObservation(left.manifest, right.manifest);
+}
+
+/**
+ * Watches a version-manager launcher whose target can move to a different package tree while the
+ * running tree stays intact.
+ *
+ * The package-tree integrity fence only sees its own manifest. A manager that installs every
+ * version into its own directory and then repoints a floating link (mise's `latest`) never
+ * touches that manifest, so the fence neither restarts onto the new version nor recovers when
+ * the old version is later pruned from under it. This watch compares what the launcher resolves
+ * to with the running root instead.
+ *
+ * `onRetargeted` runs once, after one complete target identity (canonical root plus manifest
+ * identity) has held for `settleMs`. Any change of either part, an unresolvable launcher, or a
+ * return to the running root restarts the wait. A throwing handler is retried after another full
+ * interval. After the supervisor restarts through the launcher, the new process's running root
+ * is the target, so it never requests a second restart.
+ */
+export function createPackageTreeRetargetWatch(
+  runningRoot: string,
+  resolveTarget: ResolveLauncherTarget,
+  onRetargeted: () => void,
+  options: PackageTreeRetargetOptions = {},
+): PackageTreeRetargetWatch {
+  const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+  const settleMs = options.settleMs ?? DEFAULT_SETTLE_MS;
+  const now = options.now ?? Date.now;
+  const readVersion = options.readVersion ?? (root => readPackageManifestVersionAt(packageManifestPathIn(root)));
+  const schedule = options.schedule ?? ((callback, delayMs) => {
+    const timer = setTimeout(callback, delayMs);
+    timer.unref?.();
+    return () => clearTimeout(timer);
+  });
+
+  let stopped = false;
+  let cancelPoll: (() => void) | null = null;
+  let candidate: LauncherTarget | null = null;
+  let candidateSince = 0;
+  let settled: LauncherTarget | null = null;
+
+  const poll = (): void => {
+    cancelPoll = null;
+    if (stopped) return;
+    const target = resolveTarget();
+    if (target === null || target.root === runningRoot) {
+      candidate = null;
+      settled = null;
+    } else if (candidate === null || !sameTarget(candidate, target)) {
+      candidate = target;
+      candidateSince = now();
+      settled = null;
+    } else if (now() - candidateSince >= settleMs) {
+      settled = target;
+      try {
+        onRetargeted();
+        stopped = true;
+        return;
+      } catch {
+        // Restart admission refused (for example, the service home changed owner). Keep the
+        // settled identity and ask again only after another full interval.
+        candidateSince = now();
+      }
+    }
+    cancelPoll = schedule(poll, pollIntervalMs);
+  };
+
+  cancelPoll = schedule(poll, pollIntervalMs);
+
+  return {
+    settledVersion: () => {
+      if (settled === null) return undefined;
+      const current = resolveTarget();
+      if (current === null || !sameTarget(settled, current)) return undefined;
+      return readVersion(settled.root);
+    },
+    dispose: () => {
+      stopped = true;
+      const cancel = cancelPoll;
+      cancelPoll = null;
+      cancel?.();
+    },
+  };
+}