@bitkyc08/opencodex 2.59.0 → 2.61.0-preview.20260922

package/src/lib/errors.ts

@@ -74,6 +74,75 @@ export function isCyberPolicyMessage(text: string): boolean {
   return false;
 }
 
+/**
+ * Refusal codes Codex ends a turn on.
+ *
+ * Its Responses parser classifies a `response.failed` terminal by `error.code`
+ * alone (codex-rs/codex-api/src/sse/responses.rs:423-462). These four become a
+ * fatal `ApiError` the client reports instead of reconnecting. A code outside
+ * this set is never read as a refusal: `server_is_overloaded` and `slow_down`
+ * take the overload arm, `rate_limit_exceeded` takes the rate-limit arm, and
+ * everything else falls through to `ApiError::Retryable` and is reconnected up
+ * to `stream_max_retries`.
+ *
+ * Deliberately scoped to content refusals. `insufficient_quota` and
+ * `context_length_exceeded` are terminal for Codex too, but they are separate
+ * failure families this proxy already classifies through its own quota and
+ * context paths, and pulling them in here would change their retry behavior
+ * with no evidence asking for it.
+ */
+const TERMINAL_REFUSAL_CODES = new Set<string>([
+  CYBER_POLICY_ERROR_CODE,
+  "misalignment_policy_violation",
+  "invalid_prompt",
+  "bio_policy",
+]);
+
+/** True when an upstream error code is a refusal the client must not retry. */
+export function isTerminalRefusalCode(code: string | null | undefined): boolean {
+  return typeof code === "string" && TERMINAL_REFUSAL_CODES.has(code);
+}
+
+/** Stand-in copy for a refusal the upstream sent without a message of its own. */
+export const TERMINAL_REFUSAL_FALLBACK_MESSAGE = "The upstream refused this request.";
+
+/** Readable copy for a refusal code, used when the upstream carried no message. */
+export function terminalRefusalFallbackMessage(code: string): string {
+  return code === CYBER_POLICY_ERROR_CODE
+    ? CYBER_POLICY_FALLBACK_MESSAGE
+    : TERMINAL_REFUSAL_FALLBACK_MESSAGE;
+}
+
+/**
+ * Name the refusal code behind upstream safety copy when the structured code
+ * was not carried on the wire.
+ *
+ * Same discipline as {@link isCyberPolicyMessage}: whole distinctive phrases
+ * only. A loose match here is the mirror-image defect — it would end a turn
+ * that a genuine transient failure would have retried successfully — so a
+ * message that merely mentions safety or blocking does not qualify. Callers
+ * must consult this only when the upstream carried no structured code at all,
+ * so that a transport failure quoting a refusal in its diagnostic text cannot
+ * be promoted past the verdict the upstream actually gave.
+ *
+ * Copy provenance: "limited access to this content for safety reasons" is the
+ * prefix Codex itself matches (tui/src/chatwidget/turn_runtime.rs:8-15) and
+ * pairs with `invalid_prompt` in its parser fixture (sse/responses.rs:1358-1366),
+ * which also pairs "flagged for possible biological risk" with `bio_policy`.
+ * "blocked by our safety systems" is the copy reported in #5176; pairing it
+ * with `invalid_prompt` is an inference from the two verified pairings above,
+ * not something the upstream source states.
+ */
+export function safetyRefusalCodeFromMessage(text: string): string | undefined {
+  const lower = String(text ?? "").toLowerCase();
+  if (lower.includes("flagged for possible biological risk")) return "bio_policy";
+  if (
+    lower.includes("blocked by our safety systems")
+    || lower.includes("limited access to this content for safety reasons")
+  ) return "invalid_prompt";
+  return undefined;
+}
+
 function isSubscriptionGateMessage(text: string): boolean {
   return (
     text.includes("requires a subscription") ||
@@ -187,6 +256,16 @@ export function isClientClosedMessage(text: string): boolean {
   );
 }
 
+/**
+ * Ambiguous-reset refusal wording owned by this proxy (src/lib/upstream-retry.ts):
+ * the upstream connection closed before any response arrived, so the request may
+ * already have been processed and automatic replay was stopped. Matched narrowly
+ * so a provider-sent message is never relabeled by it.
+ */
+export function isUpstreamResetReplayRefusedMessage(text: string): boolean {
+  return text.toLowerCase().includes("connection closed before a response was received");
+}
+
 export function classifyError(status: number, type: string, message: string): OcxErrorPayload {
   const text = message.toLowerCase();
   if (type === "previous_response_not_found") {

package/src/lib/http-response-semantics.ts

@@ -0,0 +1,57 @@
+/**
+ * Response rules both raw outbound transports have to apply themselves.
+ *
+ * `fetch` applies them below the Response constructor. `src/lib/pinned-http.ts` and
+ * `src/lib/socks5-fetch.ts` assemble a Response from a socket instead, so each one answers the
+ * same questions on its own — and a rule written twice is a rule that drifts. It already had:
+ * the SOCKS helper excluded 204 and the pinned helper excluded nothing, so the same no-content
+ * upstream answer behaved differently depending on which transport carried the request.
+ */
+
+/**
+ * Statuses the Fetch specification defines as null-body.
+ *
+ * `new Response(body, { status })` throws a TypeError for a non-null body on any of these, so a
+ * transport that attaches its stream unconditionally converts a valid no-content answer into a
+ * construction failure. There are no body bytes to wait for either, so a transport that streams
+ * one of these holds the caller until the peer closes a connection it is entitled to keep alive.
+ *
+ * 101 and 103 are null-body statuses too, but neither is a final Response status these helpers
+ * support. 103 and every other informational head is consumed while looking for the final one,
+ * and 101 hands the connection to a protocol neither helper speaks, which is outside what they
+ * construct a Response for at all. The three below are the statuses these transports actually
+ * have to answer for.
+ *
+ * https://fetch.spec.whatwg.org/#null-body-status
+ */
+export function isNullBodyStatus(status: number): boolean {
+  return status === 204 || status === 205 || status === 304;
+}
+
+/** What a transport must do with the coding a response declares. */
+export type ContentCoding =
+  | { kind: "identity" }
+  | { kind: "decodable"; format: "gzip" | "deflate" }
+  | { kind: "unsupported"; coding: string };
+
+/**
+ * Classify the `content-encoding` a raw transport received.
+ *
+ * `fetch` undoes a content-coding below the Response constructor. A transport that assembles a
+ * body from a socket hands the coded bytes to whatever reads them instead: `response.json()`
+ * throws a SyntaxError on the gzip magic number and an SSE reader sees noise rather than frames.
+ * Only `gzip` and `deflate` can be undone with `DecompressionStream`, so anything else is
+ * reported as unsupported and each transport refuses it under its own error type rather than
+ * surfacing bytes no caller can parse.
+ *
+ * This reads the coding the response actually carries and nothing else. A caller whose
+ * `accept-encoding` names a coding this code cannot undo is not the problem; what the peer
+ * chose to send is.
+ */
+export function classifyContentCoding(headers: Headers): ContentCoding {
+  const coding = (headers.get("content-encoding") ?? "").trim().toLowerCase();
+  if (coding === "" || coding === "identity") return { kind: "identity" };
+  if (coding === "gzip" || coding === "x-gzip") return { kind: "decodable", format: "gzip" };
+  if (coding === "deflate") return { kind: "decodable", format: "deflate" };
+  return { kind: "unsupported", coding };
+}

package/src/lib/lab-live-pinned-sender.ts

@@ -1,10 +1,32 @@
-import { PinnedHttpError, pinnedHttpGet, pinnedHttpPost } from "./pinned-http";
+import { PinnedHttpError, pinnedHttpGet, pinnedHttpPost, type PinnedHttpErrorCode } from "./pinned-http";
 import { TransportError } from "../lab/live/transport";
-import type { LabCredentialLeaseV1, LabPinnedSender } from "../lab/live/types";
+import type { LabCredentialLeaseV1, LabPinnedSender, TransportErrorCode } from "../lab/live/types";
 
 /** Only response metadata required by current live assertions crosses into Lab. */
 const LAB_RESPONSE_HEADER_ALLOWLIST = ["content-type"] as const;
 
+/**
+ * Every pinned-transport failure code, mapped to the Lab transport taxonomy or to nothing.
+ *
+ * A switch over the codes that existed when it was written silently let later ones fall through
+ * to a raw rethrow. That is not the same as leaving them unclassified: Lab's executor turns an
+ * unrecognized error into `harness_failure` / `execution_error`, so a response the peer coded
+ * in a format this transport cannot undo was reported as a fault of the runner. Both unreadable
+ * answers therefore carry `unreadable_response`, which Lab classifies as a protocol failure.
+ * A total map keeps a future code from acquiring that misattribution by default.
+ */
+const LAB_TRANSPORT_FAILURES = {
+  connect_timeout: { code: "connect_timeout", message: "pinned provider connection timed out" },
+  first_byte_timeout: { code: "first_byte_timeout", message: "pinned provider first byte timed out" },
+  inactivity_timeout: { code: "inactivity_timeout", message: "pinned provider response stalled" },
+  output_byte_limit: { code: "output_byte_limit", message: "pinned provider response exceeded byte budget" },
+  content_decode_failed: { code: "unreadable_response", message: "pinned provider response did not decode" },
+  unsupported_content_encoding: {
+    code: "unreadable_response",
+    message: "pinned provider used a content-encoding this transport cannot decode",
+  },
+} satisfies Record<PinnedHttpErrorCode, { code: TransportErrorCode; message: string }>;
+
 /**
  * Trusted credential/transport owner. Secret headers exist only in this non-Lab module and are
  * consumed directly by the pinned HTTP primitive; they are never returned to Lab code.
@@ -33,16 +55,8 @@ export function createLabAuthorizedPinnedSender(
       body = await response.text();
     } catch (error) {
       if (error instanceof PinnedHttpError) {
-        switch (error.code) {
-          case "connect_timeout":
-            throw new TransportError("connect_timeout", "pinned provider connection timed out");
-          case "first_byte_timeout":
-            throw new TransportError("first_byte_timeout", "pinned provider first byte timed out");
-          case "inactivity_timeout":
-            throw new TransportError("inactivity_timeout", "pinned provider response stalled");
-          case "output_byte_limit":
-            throw new TransportError("output_byte_limit", "pinned provider response exceeded byte budget");
-        }
+        const mapped = LAB_TRANSPORT_FAILURES[error.code];
+        throw new TransportError(mapped.code, mapped.message);
       }
       throw error;
     }

package/src/lib/open-url.ts

@@ -8,8 +8,33 @@ function windowsRundll32(): string {
   return existsSync(candidate) ? candidate : "rundll32";
 }
 
-export function openUrl(url: string): void {
-  if (!/^https?:\/\//i.test(url)) return;
+/**
+ * Whether the OS launcher actually started. `started` does not prove a browser rendered the
+ * page — nothing observable from here can — but it does separate "we handed the URL off" from
+ * "there was nothing to hand it to", which is the distinction a caller needs (#5261).
+ */
+export type OpenUrlResult =
+  | { status: "started" }
+  | { status: "failed"; reason: "invalid-url" | "spawn-error" | "launcher-exit" };
+
+/**
+ * How long to watch a launcher that did spawn before calling it started.
+ *
+ * `spawn` only proves a process began. `xdg-open` with no desktop handler, and rundll32 given a
+ * broken association, both spawn happily and exit nonzero a moment later without opening
+ * anything — so resolving on `spawn` alone would report a launch that did not happen. Those
+ * failures are immediate, and the only caller that awaits this is a login start, so a short
+ * window buys a true answer cheaply. A launcher still running when it elapses has started.
+ */
+const LAUNCHER_SETTLE_MS = 400;
+
+/**
+ * Never rejects. A browser that would not open is an inconvenience, not a login failure: the
+ * URL is still a valid thing to open by hand, so the caller decides what to say about it.
+ * Callers that genuinely do not care use `void openUrl(...)`.
+ */
+export function openUrl(url: string): Promise<OpenUrlResult> {
+  if (!/^https?:\/\//i.test(url)) return Promise.resolve({ status: "failed", reason: "invalid-url" });
   const cmd =
     process.platform === "darwin" ? "open"
     : process.platform === "win32" ? windowsRundll32()
@@ -17,9 +42,28 @@ export function openUrl(url: string): void {
   const args = process.platform === "win32"
     ? ["url.dll,FileProtocolHandler", url]
     : [url];
-  const child = spawn(cmd, args, { detached: true, stdio: "ignore", shell: false });
-  // Headless hosts (no xdg-open) emit ENOENT as an async 'error' event; without a
-  // listener that is an uncaught exception that kills the whole proxy/login flow.
-  child.on("error", () => {});
-  child.unref();
+  return new Promise<OpenUrlResult>(resolve => {
+    let settled = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const settle = (result: OpenUrlResult) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      resolve(result);
+    };
+    const child = spawn(cmd, args, { detached: true, stdio: "ignore", shell: false });
+    // Headless hosts (no xdg-open) emit ENOENT as an async 'error' event; without a
+    // listener that is an uncaught exception that kills the whole proxy/login flow.
+    // It is also the signal itself: on Windows this is how a missing rundll32 arrives.
+    child.on("error", () => settle({ status: "failed", reason: "spawn-error" }));
+    child.on("spawn", () => {
+      // Unref'd either way: this never keeps the process alive, it only decides what to report.
+      timer = setTimeout(() => settle({ status: "started" }), LAUNCHER_SETTLE_MS);
+      timer.unref?.();
+    });
+    child.on("exit", code => settle(code === 0 || code === null
+      ? { status: "started" }
+      : { status: "failed", reason: "launcher-exit" }));
+    child.unref();
+  });
 }

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

@@ -1,4 +1,5 @@
 import { statSync } from "node:fs";
+import { isStandaloneBinary } from "./standalone";
 
 export interface PackageTreeObservation {
   readonly device: bigint;
@@ -96,6 +97,6 @@ export function createRuntimePackageTreeIntegrityGuard(
   observe: ObservePackageTree = observePackageManifest,
   now: () => number = Date.now,
 ): PackageTreeIntegrityGuard {
-  if (installer === "source") return { status: () => ({ ok: true }) };
+  if (installer === "source" || isStandaloneBinary()) return { status: () => ({ ok: true }) };
   return createPackageTreeIntegrityGuard(observe, now);
 }

package/src/lib/package-version.ts

@@ -0,0 +1,8 @@
+import pkg from "../../package.json" with { type: "json" };
+
+type PackageManifest = { version?: unknown };
+
+export function packageVersion(fallback = "unknown"): string {
+  const version = (pkg as PackageManifest).version;
+  return typeof version === "string" ? version : fallback;
+}

package/src/lib/pinned-http.ts

@@ -1,5 +1,6 @@
 import http, { type ClientRequest, type IncomingMessage, type RequestOptions } from "node:http";
 import https from "node:https";
+import { classifyContentCoding, isNullBodyStatus } from "./http-response-semantics";
 
 export type PinnedAddress = { address: string; family: number };
 
@@ -7,7 +8,9 @@ export type PinnedHttpErrorCode =
   | "connect_timeout"
   | "first_byte_timeout"
   | "inactivity_timeout"
-  | "output_byte_limit";
+  | "output_byte_limit"
+  | "unsupported_content_encoding"
+  | "content_decode_failed";
 
 export class PinnedHttpError extends Error {
   override readonly name = "PinnedHttpError";
@@ -32,6 +35,99 @@ export interface PinnedHttpRequestOptions {
 /** @deprecated Use {@link PinnedHttpRequestOptions}. */
 export type PinnedHttpGetOptions = PinnedHttpRequestOptions;
 
+/**
+ * Undo the content-coding this transport has to undo itself, under the caller's byte ceiling.
+ *
+ * `maxBytes` keeps its existing meaning for the bytes that arrive on the socket, and gains the
+ * same meaning for the bytes the caller ends up reading. Bounding only the coded side would let
+ * a small compressed response expand past a ceiling the caller set precisely so it would not
+ * have to hold an unbounded body in memory.
+ *
+ * A completed body is not torn down here. The response already ended, so there is nothing to
+ * release, and destroying it would take a connection the agent is entitled to reuse. That
+ * matches the identity path, which also only closes. Teardown belongs to the paths that end a
+ * response early: a decode failure, an exceeded ceiling, and a caller that cancels.
+ *
+ * Only a decoder failure is renamed. A mid-body reset, a stalled response and an exceeded
+ * socket-byte ceiling all reach this pipeline as "the stream failed", and calling any of them a
+ * decode failure would tell the caller the peer sent unreadable bytes when the truth is that the
+ * connection died. The source failure is recorded as it passes so the original error survives;
+ * what is left after that is the decompressor's own, and that one is named because the caller's
+ * alternative is a bare TypeError from a stream it never constructed.
+ */
+function decodedBody(
+  source: ReadableStream<Uint8Array>,
+  format: "gzip" | "deflate",
+  maxBytes: number | undefined,
+  context: string,
+  release: () => void,
+): ReadableStream<Uint8Array> {
+  // Interposed purely to attribute failures. Once bytes enter the decompressor, a transport
+  // error and a corrupt trailer are indistinguishable from the far side of the pipe.
+  let sourceFailure: { error: unknown } | undefined;
+  const sourceReader = source.getReader();
+  const attributed = new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        const next = await sourceReader.read();
+        if (next.done) {
+          controller.close();
+          return;
+        }
+        controller.enqueue(next.value);
+      } catch (error) {
+        sourceFailure = { error };
+        controller.error(error);
+      }
+    },
+    cancel(reason) {
+      return sourceReader.cancel(reason);
+    },
+  });
+  // `DecompressionStream` declares its writable side as `WritableStream<BufferSource>`, and
+  // TypeScript measures `WritableStream` as invariant in its chunk type, so the pair is not
+  // assignable to `ReadableWritablePair<Uint8Array, Uint8Array>` even though every chunk this
+  // body produces is a valid `BufferSource`. The conversion states that relationship and
+  // nothing else; it does not widen what is actually written.
+  const decompressor = new DecompressionStream(format) as unknown as ReadableWritablePair<Uint8Array, Uint8Array>;
+  const reader = attributed.pipeThrough(decompressor).getReader();
+  let decoded = 0;
+  return new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        const next = await reader.read();
+        if (next.done) {
+          controller.close();
+          return;
+        }
+        decoded += next.value.byteLength;
+        if (maxBytes !== undefined && decoded > maxBytes) {
+          throw new PinnedHttpError("output_byte_limit", `${context} exceeds ${maxBytes} byte cap`);
+        }
+        controller.enqueue(next.value);
+      } catch (error) {
+        // A failure the socket stream raised is the caller's answer, whatever shape it has.
+        // Only what the decompressor itself rejected is renamed.
+        const named = sourceFailure !== undefined
+          ? sourceFailure.error
+          : error instanceof PinnedHttpError
+            ? error
+            : new PinnedHttpError("content_decode_failed", `${context} could not decode its ${format} body`);
+        // Cancelling the decoded reader propagates back through the decompressor to the socket
+        // stream's own `cancel`, which destroys the request; `release` covers the case where
+        // that propagation is already finished.
+        await reader.cancel(named).catch(() => { /* already torn down */ });
+        controller.error(named);
+        release();
+      }
+    },
+    async cancel(reason) {
+      await reader.cancel(reason).catch(() => { /* already torn down */ });
+      release();
+    },
+  });
+}
+
 function pinnedHttpRequest(
   url: string,
   pinned: PinnedAddress,
@@ -55,6 +151,10 @@ function pinnedHttpRequest(
   const maxBytes = options?.maxBytes;
   const headers = new Headers(options?.headers);
   headers.set("host", parsed.host);
+  // This transport assembles the response itself, so a coding it did not ask for becomes its own
+  // problem to undo. Ask for none by default and leave an explicit caller choice alone, which is
+  // the same rule `src/lib/socks5-fetch.ts` applies to the other raw route.
+  if (!headers.has("accept-encoding")) headers.set("accept-encoding", "identity");
   if (body !== undefined && !headers.has("content-length")) {
     headers.set("content-length", String(Buffer.byteLength(body)));
   }
@@ -150,6 +250,39 @@ function pinnedHttpRequest(
         return;
       }
 
+      // A success status can still be null-body. `new Response(stream, { status: 204 })` throws a
+      // TypeError, so attaching the body below would turn a correct no-content answer into a
+      // construction failure raised inside this event handler rather than a resolved response.
+      // Nothing is coming on the socket either, so streaming one of these would hold the caller
+      // until the peer closed a connection it is entitled to keep alive. The headers still
+      // describe the representation the peer would have sent and are preserved as they arrived.
+      if (isNullBodyStatus(status)) {
+        try { response.destroy(); } catch { /* ignore */ }
+        try { req?.destroy(); } catch { /* ignore */ }
+        if (settled) return;
+        settled = true;
+        resolve(new Response(null, { status, headers: responseHeaders }));
+        return;
+      }
+
+      // The peer may have coded the body whatever this request asked for. Classify before the
+      // stream takes the socket so a coding this transport cannot undo fails on the ordinary
+      // error path rather than reaching the caller as bytes its parser cannot read.
+      const coding = classifyContentCoding(responseHeaders);
+      if (coding.kind === "unsupported") {
+        try { response.destroy(); } catch { /* ignore */ }
+        fail(new PinnedHttpError(
+          "unsupported_content_encoding",
+          `${context} returned an unsupported content-encoding: ${coding.coding}`,
+        ));
+        return;
+      }
+      if (coding.kind === "decodable") {
+        responseHeaders.delete("content-encoding");
+        // The declared length counted the coded bytes, not what the caller now reads.
+        responseHeaders.delete("content-length");
+      }
+
       let received = 0;
       const stream = new ReadableStream<Uint8Array>({
         start(controller) {
@@ -191,7 +324,14 @@ function pinnedHttpRequest(
 
       if (settled) return;
       settled = true;
-      resolve(new Response(stream, { status, headers: responseHeaders }));
+      const release = () => {
+        try { response.destroy(); } catch { /* ignore */ }
+        try { req?.destroy(); } catch { /* ignore */ }
+      };
+      const payload = coding.kind === "decodable"
+        ? decodedBody(stream, coding.format, maxBytes, context, release)
+        : stream;
+      resolve(new Response(payload, { status, headers: responseHeaders }));
     };
 
     const requestFn = parsed.protocol === "https:" ? https.request : http.request;

package/src/lib/plain-data.ts

@@ -0,0 +1,103 @@
+/**
+ * Copying a value the way a consumer that must not observe later edits needs it copied.
+ *
+ * Serializing with JSON is not a copier and using it as one is a quiet hole: it drops functions
+ * without saying so, and it invokes getters and toJSON, so the object being copied gets to decide
+ * what the copy contains. Every read here goes through a property descriptor instead, including
+ * array elements, which an exotic array can define as accessors just as an object can.
+ *
+ * The contract is narrow on purpose. This copies what JSON could have produced and refuses
+ * everything else rather than approximating it: an accessor, a cycle, a function, a class instance,
+ * a Map, a Date, a symbol value, a bigint, a non-finite number. A caller that is refused has to
+ * decide what to do about it, which is the point; a copier that silently degraded would leave the
+ * caller believing it held a snapshot of something it never read.
+ *
+ * Symbol-keyed properties are skipped rather than refused. Process bookkeeping rides on symbols by
+ * convention here, and none of it is the data a consumer is being given a copy of.
+ */
+
+/** A copy, or a refusal. A union rather than a nullable value, because null is copyable data. */
+export type PlainDataCopy<T> = { readonly ok: true; readonly value: T } | { readonly ok: false };
+
+const REFUSED = Symbol("refused");
+
+export function copyPlainData<T>(value: T): PlainDataCopy<T> {
+  const copied = copyValue(value, new Set());
+  return copied === REFUSED ? { ok: false } : { ok: true, value: copied as T };
+}
+
+/**
+ * A stable string for comparing two plain-data values.
+ *
+ * Key-sorted entry pairs rather than objects, because property order is observable through
+ * serialization and two values that differ only in it are the same value.
+ */
+export function canonicalPlainData(value: unknown): string {
+  return JSON.stringify(sorted(value));
+}
+
+/** Own enumerable string keys, with null in the position of any key that is an accessor. */
+export function ownDataKeys(value: Record<string, unknown>): Array<string | null> {
+  return Object.keys(value).map(key => {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    return descriptor !== undefined && descriptor.get === undefined && descriptor.set === undefined ? key : null;
+  });
+}
+
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function copyValue(value: unknown, seen: Set<object>): unknown {
+  if (value === null) return null;
+  const type = typeof value;
+  if (type === "string" || type === "boolean") return value;
+  if (type === "number") return Number.isFinite(value as number) ? value : REFUSED;
+  if (type !== "object") return REFUSED;
+  const object = value as object;
+  if (seen.has(object)) return REFUSED;
+  seen.add(object);
+  try {
+    if (Array.isArray(object)) return copyArray(object, seen);
+    if (!isPlainObject(object)) return REFUSED;
+    const copied: Record<string, unknown> = {};
+    for (const key of ownDataKeys(object)) {
+      if (key === null) return REFUSED;
+      const entry = (object as Record<string, unknown>)[key];
+      if (entry === undefined) continue;
+      const item = copyValue(entry, seen);
+      if (item === REFUSED) return REFUSED;
+      copied[key] = item;
+    }
+    return copied;
+  } finally {
+    seen.delete(object);
+  }
+}
+
+function copyArray(source: unknown[], seen: Set<object>): unknown {
+  const copied: unknown[] = [];
+  for (let index = 0; index < source.length; index += 1) {
+    const descriptor = Object.getOwnPropertyDescriptor(source, index);
+    // A hole is written as null, which is what a reader of the serialized value would find there.
+    if (descriptor === undefined) { copied.push(null); continue; }
+    if (descriptor.get !== undefined || descriptor.set !== undefined) return REFUSED;
+    if (descriptor.value === undefined) { copied.push(null); continue; }
+    const item = copyValue(descriptor.value, seen);
+    if (item === REFUSED) return REFUSED;
+    copied.push(item);
+  }
+  return copied;
+}
+
+function sorted(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sorted);
+  if (value !== null && typeof value === "object") {
+    return Object.keys(value as Record<string, unknown>)
+      .sort()
+      .map(key => [key, sorted((value as Record<string, unknown>)[key])]);
+  }
+  return value;
+}

package/src/lib/process-control.ts

@@ -1,4 +1,5 @@
 import { execFileSync } from "node:child_process";
+import { isIP } from "node:net";
 import { loadConfig } from "../config";
 import { readRuntimePort } from "../config/process-state";
 import { configuredAdminToken } from "./admin-secrets";
@@ -50,9 +51,11 @@ export interface GracefulStopIo {
 }
 
 /**
- * Host to POST /api/stop against: follow the recorded bind hostname when it names a
- * concrete address (a proxy bound to ::1 or a LAN IP is unreachable on 127.0.0.1);
- * loopback aliases and wildcard binds all answer on IPv4 loopback.
+ * Host to POST /api/stop against: follow the recorded bind hostname only when it is
+ * an IP literal (a proxy bound to ::1 or a LAN IP is unreachable on 127.0.0.1).
+ * DNS names are not safe here because resolution may change between bind and stop,
+ * while this request carries the management token. Loopback aliases, DNS names, and
+ * wildcard binds therefore all fall back to IPv4 loopback.
  */
 export function gracefulStopHost(hostname: string | undefined): string {
   const trimmed = (hostname ?? "").trim();
@@ -61,8 +64,13 @@ export function gracefulStopHost(hostname: string | undefined): string {
     return "127.0.0.1";
   }
   if (lower === "::1" || lower === "[::1]") return "[::1]";
-  if (trimmed.startsWith("[") && trimmed.endsWith("]")) return trimmed;
-  return trimmed.includes(":") ? `[${trimmed}]` : trimmed;
+  const unbracketed = trimmed.startsWith("[") && trimmed.endsWith("]")
+    ? trimmed.slice(1, -1)
+    : trimmed;
+  const ipVersion = isIP(unbracketed);
+  if (ipVersion === 6) return `[${unbracketed}]`;
+  if (ipVersion === 4) return unbracketed;
+  return "127.0.0.1";
 }
 
 /**