@bitkyc08/opencodex 2.86.0 → 2.87.0

package/src/server/responses/sidecar-execution.ts

@@ -21,7 +21,7 @@ import {
   clampImageMaxRounds,
 } from "../../images";
 import type { ProviderAdapter } from "../../adapters/base";
-import type { OcxParsedRequest } from "../../types";
+import type { OcxParsedRequest, OcxUsage } from "../../types";
 import { rotateProviderTransportOn429, rateLimitRetryPolicyFor } from "../../providers/key-failover";
 import {
   isGenericOAuthFailoverEnabled,
@@ -50,6 +50,7 @@ import { providerFetch } from "./fetch-helpers";
 import type { AttemptRecoveryKind } from "../../usage/log";
 import { recordAdapterReasoning, recordAdapterTier } from "../request-log";
 import { normalizeLogConversationId } from "../request-log-conversation";
+import { attemptAccountChanged } from "../request-log-account-rotation";
 import { rememberResponseState } from "../../responses/state";
 import { trackStreamLifetime } from "../lifecycle";
 import { isAntigravityRawValidationRefusal } from "./antigravity-validation-refusal";
@@ -65,6 +66,7 @@ export async function executeResponsesSidecars(
     | "inboundWire"
     | "selectedForwardHeaders"
     | "translatorBudget"
+    | "clientToolCatalogRestriction"
     | "toolBridgeMaps"
     | "rememberKiroDeliveredFinalAnswer"
     | "responseStateOptions"
@@ -417,7 +419,8 @@ export async function executeResponsesSidecars(
         hop.permit?.release();
         return null;
       }
-      recoveryKind = originalResponse?.status === 401 ? "oauth-401" : "anthropic-oauth-429";
+      recoveryKind = originalResponse?.status === 401 ? "oauth-401"
+        : originalResponse?.status === 403 ? "oauth-account-403" : "anthropic-oauth-429";
       sidecarBudget.ownCredentialHop(hop.permit);
     } else {
       // No key pool, no generic OAuth roster, no Anthropic pool could produce a replacement
@@ -451,6 +454,15 @@ export async function executeResponsesSidecars(
     });
     return { adapter: rotatedAdapter, recoveryKind };
   };
+  // A loop's hidden rounds before a rotation were spent by the account it left. Bill them to that
+  // account's attempt while it is still open; the next send seals it. Declined when that send
+  // keeps the account (no new attempt), so the loop's final total still carries them.
+  const billRotatedUsage = (usage: OcxUsage): boolean => {
+    const attempt = logCtx.activeAttempt;
+    if (!attempt || !attemptAccountChanged(attempt.accountLogLabel, logCtx.accountLogLabel, attempt.provider, logCtx.provider)) return false;
+    transportState.bindKeyUsageFromBridge(usage);
+    return true;
+  };
   if ((imgPlan || vidPlan) && wsPlan) {
     // Web search takes priority when both are active — the media bridge cannot run
     // alongside runWithWebSearch. Surface a runtime signal so the user knows their
@@ -508,6 +520,7 @@ export async function executeResponsesSidecars(
     );
     const imgResponse = await runWithImageBridge({
       parsed, adapter: transportState.adapter,
+      clientToolCatalogRestriction: route.provider.authMode === "forward" ? undefined : requestState.clientToolCatalogRestriction,
       incomingMeta: { headers: requestState.selectedForwardHeaders, providerName: route.providerName, abortSignal: options.abortSignal, translatorBudget, ...(options.comboInitialSend ? { providerFetch: imageProviderFetch } : {}), ...sidecarBudget.incomingMeta },
       onProducerStart: sidecarBudget.takeProducerOwnership,
       onProducerEnd: sidecarBudget.release,
@@ -549,10 +562,12 @@ export async function executeResponsesSidecars(
         transportState.bindKeyUsageFromBridge(usage);
       },
       on429: rotateSidecarProviderOn429,
+      onRotatedUsage: billRotatedUsage,
       retryOn429Policy: route.providerName === "kiro" && isGenericOAuthFailoverEnabled(config, "kiro")
         ? null : rateLimitRetryPolicyFor(route.provider),
       onFirstOutput: noteSidecarOutput,
       ...(options.forceEmptyResponseId ? { forceEmptyResponseId: true } : {}),
+      terminalRefusalAsFailed: inboundWire !== "chat" && inboundWire !== "anthropic",
       onCompletedResponse: (response, providerState) => {
         const served = transportState.replayOAuthCredentialSnapshot;
         if (route.providerName === "kiro" && response.status === "completed" && served
@@ -603,6 +618,7 @@ export async function executeResponsesSidecars(
       })(input, init)) as typeof globalThis.fetch;
     const loopResponse = await runWithWebSearch({
       parsed, adapter: transportState.adapter,
+      clientToolCatalogRestriction: route.provider.authMode === "forward" ? undefined : requestState.clientToolCatalogRestriction,
       onIterationEnd: sidecarBudget.releaseUnsentHop,
       fetchForRequest: (request, iterParsed, adapter) => providerFetch(route.provider, options.codexWsRuntimeIdentity, {
         dispatchOverride: oauthDispatch(request, iterParsed),
@@ -633,6 +649,7 @@ export async function executeResponsesSidecars(
       settings: wsPlan.settings,
       maxSearches: wsPlan.maxSearches,
       forceEmptyResponseId: true,
+      terminalRefusalAsFailed: inboundWire !== "chat" && inboundWire !== "anthropic",
       abortSignal: options.abortSignal,
       onFirstOutput: noteSidecarOutput,
       onRequestBuilt: request => {
@@ -651,6 +668,7 @@ export async function executeResponsesSidecars(
       stallTimeoutSec: wsPlan.stallTimeoutSec,
       streamRoutedModelOutput: wsPlan.streamRoutedModelOutput,
       on429: rotateSidecarProviderOn429,
+      onRotatedUsage: billRotatedUsage,
       ...(!options.comboInitialSend && route.providerName === "google-antigravity" ? { onIterationEnd: () => {
         // The next Antigravity adapter dispatch claims this permit. If request construction,
         // admission or cancellation stopped it first, return the unused send allowance.

package/src/server/responses/terminal-guard.ts

@@ -1,6 +1,6 @@
+import { assistantReplayContent } from "../../responses/assistant-replay";
 import type {
   AdapterEvent,
-  OcxAssistantContentPart,
   OcxAssistantMessage,
   OcxParsedRequest,
   OcxUsage,
@@ -121,21 +121,7 @@ export function analyzeTerminalTurn(parsed: OcxParsedRequest, events: readonly A
 }
 
 function assistantMessageFromEvents(events: readonly AdapterEvent[], timestamp: number): OcxAssistantMessage | undefined {
-  let text = "";
-  let thinking = "";
-  let signature: string | undefined;
-  const redacted: string[] = [];
-  for (const event of events) {
-    if (event.type === "text_delta") text += event.text;
-    else if (event.type === "thinking_delta") thinking += event.thinking;
-    else if (event.type === "thinking_signature") signature = event.signature;
-    else if (event.type === "redacted_thinking") redacted.push(event.data);
-  }
-  const content: OcxAssistantContentPart[] = [];
-  if (thinking || signature || redacted.length > 0) {
-    content.push({ type: "thinking", thinking, ...(signature ? { signature } : {}), ...(redacted.length > 0 ? { redacted } : {}) });
-  }
-  if (text) content.push({ type: "text", text });
+  const content = assistantReplayContent(events);
   if (content.length === 0) return undefined;
   return { role: "assistant", content, timestamp };
 }

package/src/service/auth-preflight.ts

@@ -0,0 +1,71 @@
+/**
+ * The install/repair preflight over the data-plane credential, plus the retry command it
+ * names. Split out of `guards.ts` so the guard module stops importing `diagnostics`.
+ *
+ * Direction of the remaining edge is deliberate: this module asks `guards` for
+ * `assertNotAdminToken` and `diagnostics` for the install verdict, and neither imports it back.
+ */
+import { loadConfig } from "../config";
+import { isLoopbackHostname } from "../codex/loopback-target";
+import { readServiceApiTokenState, serviceApiTokenFilePath } from "../lib/service-secrets";
+import { diagnoseService } from "./diagnostics";
+import type { ServiceDiagnostic } from "./diagnostics";
+import { assertNotAdminToken } from "./guards";
+
+/**
+ * The `ocx` command a user should rerun for the service state they actually have.
+ *
+ * `installed` alone is not enough: `repairService()` refuses a Task-Scheduler-plus-WinSW
+ * conflict outright, so recommending repair there names a command guaranteed to fail.
+ * Install IS the valid conflict recovery, because `installWindows` removes the native
+ * backend first. Exported so the guard tests the real selector rather than a copy of it.
+ */
+export function serviceRetryCommand(
+  diag: Pick<ServiceDiagnostic, "installed" | "conflict"> = diagnoseService(),
+): string {
+  return diag.installed && !diag.conflict ? "ocx service repair" : "ocx service install";
+}
+
+/**
+ * Preflight for `service install` / `service repair` on the data-plane credential.
+ *
+ * It used to DEMAND `OPENCODEX_API_AUTH_TOKEN` for a non-loopback hostname, and it threw
+ * even when `~/.opencodex/service-api-token` already held a perfectly good token. That is
+ * the defect behind the incident this unit exists to close (#4236): an operator exported the
+ * ADMIN token as OPENCODEX_API_AUTH_TOKEN because `install` asked for a token, the hub then
+ * crash-looped on `assertNotAdminToken`, and `service repair` asked for the same env var
+ * again — so the only remembered way to make the command proceed was the thing that broke it.
+ *
+ * Nobody should have to export a token by hand to run a hub. {@link writeServiceApiTokenFile}
+ * provisions one, so the only conditions left that install cannot fix are an admin-token
+ * collision in the environment and a token file that exists but cannot be used.
+ */
+export function assertServiceAuthEnvironment(): void {
+  const config = loadConfig();
+  // Both collision checks come BEFORE the loopback short-circuit, because the launch wrapper
+  // exports the token file unconditionally (`buildServiceShellCommand` cats it whenever it
+  // exists, whatever the hostname): a management token in either source fences the whole
+  // management plane closed at boot, even on a loopback install that needs no admission
+  // secret. Returning early is what let that broken state through.
+  const present = process.env.OPENCODEX_API_AUTH_TOKEN?.trim();
+  if (present) assertNotAdminToken(present);
+  const state = readServiceApiTokenState();
+  // An existing FILE holding the admin token is the incident shape itself, and the first round
+  // only checked the env var — so install/repair reused it and the hub crash-looped at boot.
+  // On a machine connected to a hub this same file holds that hub's issued client key, which
+  // is never a management token, so the check is a no-op there.
+  if (state.kind === "present") assertNotAdminToken(state.token, process.env, "file");
+  if (isLoopbackHostname(config.hostname)) return;
+  if (present) return;
+  // Absent is fine — install/repair generates one below. `unsafe` is not: the writer refuses
+  // to replace a path it cannot vouch for, so say so here, where the operator can still act,
+  // instead of failing mid-install. Reached from `service repair` as well as `install`, so
+  // name a command that can actually succeed (see serviceRetryCommand).
+  if (state.kind !== "unsafe") return;
+  const diag = diagnoseService();
+  throw new Error(
+    `The data-plane token file cannot be used (${state.reason}): ${serviceApiTokenFilePath()}. `
+      + `Move it aside, then rerun \`${serviceRetryCommand(diag)}\`; the service provisions a `
+      + "fresh owner-only token and needs nothing from the environment.",
+  );
+}

package/src/service/cli.ts

@@ -11,8 +11,10 @@ import { statusWinswRaw, type WinswStatus } from "../lib/winsw";
 import { withWindowsServiceMutationLock } from "../lib/windows-service-mutation-lock";
 import { maybeShowStarPrompt } from "../cli/star-prompt";
 import { serviceStatusReport } from "./diagnostics";
-import { assertServiceEnvironmentMatchesInstall, assertServiceAuthEnvironment } from "./guards";
-import { resolveServiceListenPort, reportServiceServing } from "./health";
+import { assertServiceAuthEnvironment } from "./auth-preflight";
+import { assertServiceEnvironmentMatchesInstall } from "./guards";
+import { resolveServiceListenPort } from "./definition";
+import { reportServiceServing } from "./health";
 import { platformOps, proxyStillLiveAfterStop, stopTrackedProxyForServiceCommand, installServiceSafely, installFreshWindowsSchedulerSafely, removeServiceInstallState, isServiceInstalled } from "./orchestration";
 import { repairService } from "./repair";
 import type { ServiceRepairVerb } from "./repair";

package/src/service/definition.ts

@@ -0,0 +1,97 @@
+/**
+ * The shape of a service definition: the shell command both Unix backends bake into
+ * their unit/plist, the port they pin into it, and the proxy environment it carries.
+ *
+ * Leaf module. It reads config and the token-file path, and asks nothing of the
+ * backends that consume it — importing it from `launchd.ts`/`systemd.ts` cannot
+ * route back through them (see `installedServiceListenPort` in `health.ts`, which
+ * intentionally stays behind because it asks every backend).
+ */
+import { loadConfig } from "../config";
+import { serviceApiTokenFilePath } from "../lib/service-secrets";
+import { PROXY_ENV_KEYS } from "../lib/proxy-env";
+
+export function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+
+/**
+ * Listen port baked into service wrappers / WinSW XML.
+ * Priority: explicit override → OCX_BAKE_PORT (update restart) → config.port → 10100.
+ * `config.port === 0` means ephemeral for interactive start; services need a stable pin,
+ * so treat 0 / invalid like unset (default 10100) instead of baking `--port 0`.
+ */
+export function resolveServiceListenPort(override?: number): number {
+  if (typeof override === "number" && Number.isFinite(override) && override > 0 && override <= 65535) {
+    return Math.trunc(override);
+  }
+  const baked = process.env.OCX_BAKE_PORT?.trim();
+  if (baked && /^\d+$/.test(baked)) {
+    const n = Number(baked);
+    if (n > 0 && n <= 65535) return n;
+  }
+  const configured = loadConfig().port;
+  if (typeof configured === "number" && configured > 0 && configured <= 65535) return configured;
+  return 10100;
+}
+
+export function buildServiceShellCommand(bun: string, cli: string | null, port = resolveServiceListenPort()): string {
+  const tokenFile = serviceApiTokenFilePath();
+  const args = cli ? `${shellQuote(cli)} start` : "start";
+  return `if [ -f ${shellQuote(tokenFile)} ]; then OPENCODEX_API_AUTH_TOKEN="$(cat ${shellQuote(tokenFile)})"; export OPENCODEX_API_AUTH_TOKEN; fi; exec ${shellQuote(bun)} ${args} --port ${port}`;
+}
+
+/**
+ * The same command shape, launched through a stable `ocx` executable instead of an
+ * explicit Bun + CLI pair. The token-file preamble is identical and deliberately shared
+ * in form: the service still reads the token from disk at start and never carries it in
+ * the unit.
+ */
+export function buildServiceLauncherShellCommand(launcher: string, port = resolveServiceListenPort()): string {
+  const tokenFile = serviceApiTokenFilePath();
+  return `if [ -f ${shellQuote(tokenFile)} ]; then OPENCODEX_API_AUTH_TOKEN="$(cat ${shellQuote(tokenFile)})"; export OPENCODEX_API_AUTH_TOKEN; fi; exec ${shellQuote(launcher)} start --port ${port}`;
+}
+
+/**
+ * Shared tail parser for the baked `--port <n>`.
+ *
+ * Terminators cover all three artifact shapes: whitespace (batch wrapper, systemd
+ * unit), `"` (systemd's quoted ExecStart), `<` (WinSW's `</arguments>`), and `&` (an
+ * XML-escaped quote). Matched LAST because every artifact carries the Bun and CLI
+ * paths ahead of the argument, and a path containing the literal must not shadow it.
+ */
+export function parseBakedListenPort(read: () => string): number | null {
+  try {
+    const last = [...read().matchAll(/start --port (\d{1,5})(?:\s|"|&|<|$)/gm)].at(-1);
+    if (!last) return null;
+    const n = Number(last[1]);
+    return n > 0 && n <= 65535 ? n : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Outbound proxy settings the installing shell had, resolved for baking into a service
+ * definition.
+ *
+ * A service manager does not inherit the environment of the shell that installed it, and
+ * `ExecStart=/bin/sh -lc` is dash on Ubuntu/WSL — login dash reads `.profile`, not
+ * `.bashrc`, which is where proxy exports usually live. So a user who needs a proxy to
+ * reach the upstream got a service that dialed direct: the socket was reset, the retry
+ * budget drained, and the request surfaced as `502 Provider unreachable` (#2107). The
+ * same install driven through `ocx codex-shim` worked, because that path spawns with
+ * `{ ...process.env }`.
+ *
+ * Lower-case variants are honored because curl-style tooling sets them and the runtime's
+ * own `applyProxyEnv` already treats both cases as equivalent. Only the canonical
+ * upper-case name is baked, so a definition never carries two spellings of one setting.
+ */
+export function resolvedProxyEnv(env: NodeJS.ProcessEnv = process.env): { name: string; value: string }[] {
+  const resolved: { name: string; value: string }[] = [];
+  for (const key of PROXY_ENV_KEYS) {
+    const value = env[key]?.trim() || env[key.toLowerCase()]?.trim();
+    if (value) resolved.push({ name: key, value });
+  }
+  return resolved;
+}

package/src/service/guards.ts

@@ -2,14 +2,12 @@ import { execSync } from "node:child_process";
 import { chmodSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { getConfigDir, loadConfig } from "../config";
 import { withConfigMutationLockSync } from "../config/mutation-lock";
-import { hardenReusedServiceApiToken, readServiceApiTokenState, serviceApiTokenFilePath } from "../lib/service-secrets";
+import { hardenReusedServiceApiToken, serviceApiTokenFilePath } from "../lib/service-secrets";
 import { tokenCollidesWithAdmin } from "../lib/admin-secrets";
 import { randomBytes } from "node:crypto";
 import { hardenSecretDir, hardenSecretPath } from "../lib/windows-secret-acl";
 import { recordOwnedConfigPath } from "../lib/config-ownership";
 import { isTestHomeGuardArmed } from "../lib/test-home-guard";
-import { diagnoseService } from "./diagnostics";
-import type { ServiceDiagnostic } from "./diagnostics";
 import { currentCodexHome, currentOpenCodexHome, resolveServiceState, serviceCodexHomeMatchesInstall, servicePathMatchesInstall } from "./state";
 import { resolveCodexSqliteHome } from "../codex/paths";
 import type { CodexHomeDeps } from "../codex/home";
@@ -76,20 +74,6 @@ export function assertServiceEnvironmentMatchesInstall(deps: CodexHomeDeps = {})
   }
 }
 
-/**
- * The `ocx` command a user should rerun for the service state they actually have.
- *
- * `installed` alone is not enough: `repairService()` refuses a Task-Scheduler-plus-WinSW
- * conflict outright, so recommending repair there names a command guaranteed to fail.
- * Install IS the valid conflict recovery, because `installWindows` removes the native
- * backend first. Exported so the guard tests the real selector rather than a copy of it.
- */
-export function serviceRetryCommand(
-  diag: Pick<ServiceDiagnostic, "installed" | "conflict"> = diagnoseService(),
-): string {
-  return diag.installed && !diag.conflict ? "ocx service repair" : "ocx service install";
-}
-
 /**
  * Refuse a management (admin) token as the data-plane secret.
  *
@@ -139,50 +123,6 @@ export function assertNotAdminToken(
   );
 }
 
-/**
- * Preflight for `service install` / `service repair` on the data-plane credential.
- *
- * It used to DEMAND `OPENCODEX_API_AUTH_TOKEN` for a non-loopback hostname, and it threw
- * even when `~/.opencodex/service-api-token` already held a perfectly good token. That is
- * the defect behind the incident this unit exists to close (#4236): an operator exported the
- * ADMIN token as OPENCODEX_API_AUTH_TOKEN because `install` asked for a token, the hub then
- * crash-looped on `assertNotAdminToken`, and `service repair` asked for the same env var
- * again — so the only remembered way to make the command proceed was the thing that broke it.
- *
- * Nobody should have to export a token by hand to run a hub. {@link writeServiceApiTokenFile}
- * provisions one, so the only conditions left that install cannot fix are an admin-token
- * collision in the environment and a token file that exists but cannot be used.
- */
-export function assertServiceAuthEnvironment(): void {
-  const config = loadConfig();
-  // Both collision checks come BEFORE the loopback short-circuit, because the launch wrapper
-  // exports the token file unconditionally (`buildServiceShellCommand` cats it whenever it
-  // exists, whatever the hostname): a management token in either source fences the whole
-  // management plane closed at boot, even on a loopback install that needs no admission
-  // secret. Returning early is what let that broken state through.
-  const present = process.env.OPENCODEX_API_AUTH_TOKEN?.trim();
-  if (present) assertNotAdminToken(present);
-  const state = readServiceApiTokenState();
-  // An existing FILE holding the admin token is the incident shape itself, and the first round
-  // only checked the env var — so install/repair reused it and the hub crash-looped at boot.
-  // On a machine connected to a hub this same file holds that hub's issued client key, which
-  // is never a management token, so the check is a no-op there.
-  if (state.kind === "present") assertNotAdminToken(state.token, process.env, "file");
-  if (isLoopbackHostname(config.hostname)) return;
-  if (present) return;
-  // Absent is fine — install/repair generates one below. `unsafe` is not: the writer refuses
-  // to replace a path it cannot vouch for, so say so here, where the operator can still act,
-  // instead of failing mid-install. Reached from `service repair` as well as `install`, so
-  // name a command that can actually succeed (see serviceRetryCommand).
-  if (state.kind !== "unsafe") return;
-  const diag = diagnoseService();
-  throw new Error(
-    `The data-plane token file cannot be used (${state.reason}): ${serviceApiTokenFilePath()}. `
-      + `Move it aside, then rerun \`${serviceRetryCommand(diag)}\`; the service provisions a `
-      + "fresh owner-only token and needs nothing from the environment.",
-  );
-}
-
 /** How the data-plane token the service will export was obtained. */
 export type ServiceApiTokenOrigin = "env" | "file" | "generated";
 

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

@@ -0,0 +1,112 @@
+/** Linux pidfd ownership for the opt-in sentinel. Loaded only on Linux. */
+import { dlopen, FFIType, read } from "bun:ffi";
+import type { TerminateResult } from "./health-sentinel-main";
+
+const ESRCH = 3;
+const ENOSYS = 38;
+// Syscalls from 424 onward share one number on every Linux architecture. Binding is limited to
+// x64/arm64 because the FFI signature below assumes their LP64 integer-register calling convention.
+const SYS_PIDFD_OPEN = 434;
+const SYS_PIDFD_SEND_SIGNAL = 424;
+
+type CallResult = { value: number; errno: number };
+export type PidfdSyscalls = {
+  open(pid: number): CallResult;
+  signal(fd: number, signal: number): CallResult;
+  close(fd: number): void;
+  dispose(): void;
+};
+export type ParentPidfd = { terminate(): TerminateResult; close(): void };
+export type ParentPidfdResult =
+  | { kind: "bound"; handle: ParentPidfd }
+  | { kind: "unsupported"; reason: string }
+  | { kind: "refused"; reason: string };
+
+function nativeSyscalls(): PidfdSyscalls {
+  const symbols = {
+    // syscall is variadic, but these syscalls use integer/pointer arguments only. All supplied
+    // slots are machine-word integers (including zero for siginfo and flags), on these LP64 ABIs.
+    syscall: { args: [FFIType.i64, FFIType.i64, FFIType.i64, FFIType.i64, FFIType.i64], returns: FFIType.i64 },
+    __errno_location: { args: [], returns: FFIType.ptr },
+    close: { args: [FFIType.i32], returns: FFIType.i32 },
+  } as const;
+  const load = (path: string) => dlopen(path, symbols);
+  let libc: ReturnType<typeof load>;
+  try {
+    libc = load("libc.so.6");
+  } catch {
+    // musl exports libc symbols through its loader; it has no glibc soname or pidfd wrappers.
+    libc = load(`/lib/ld-musl-${process.arch === "x64" ? "x86_64" : "aarch64"}.so.1`);
+  }
+  const call = (nr: number, a: number, b: number, c = 0, d = 0): CallResult => {
+    const value = Number(libc.symbols.syscall(nr, a, b, c, d));
+    return { value, errno: value === -1 ? read.i32(libc.symbols.__errno_location()!) : 0 };
+  };
+  return {
+    open: pid => call(SYS_PIDFD_OPEN, pid, 0),
+    signal: (fd, signal) => call(SYS_PIDFD_SEND_SIGNAL, fd, signal),
+    // Never retry close on Linux: even an EINTR has released the descriptor.
+    close: fd => { libc.symbols.close(fd); },
+    dispose: () => libc.close(),
+  };
+}
+
+/** Acquire before arming; reparenting during acquisition invalidates even a successfully opened fd. */
+export function openParentPidfd(
+  pid: number,
+  isParent: () => boolean,
+  options: { arch?: string; load?: () => PidfdSyscalls } = {},
+): ParentPidfdResult {
+  if (!isParent()) return { kind: "refused", reason: "the sentinel is not the watched process's child" };
+  const arch = options.arch ?? process.arch;
+  if (arch !== "x64" && arch !== "arm64") return { kind: "unsupported", reason: `pidfd syscall ABI is unsupported on ${arch}` };
+  let api: PidfdSyscalls;
+  try { api = (options.load ?? nativeSyscalls)(); }
+  catch { return { kind: "refused", reason: "Linux pidfd libc binding is unavailable" }; }
+  let fd: number | null = null;
+  let closed = false;
+  let signalled = false;
+  const close = () => {
+    if (closed) return;
+    closed = true;
+    try { if (fd !== null) api.close(fd); } finally { api.dispose(); }
+  };
+  const refuse = (reason: string): ParentPidfdResult => { close(); return { kind: "refused", reason }; };
+  try {
+    const opened = api.open(pid);
+    if (opened.value < 0) {
+      close();
+      return opened.errno === ENOSYS
+        ? { kind: "unsupported", reason: "pidfd_open is unsupported by this kernel" }
+        : { kind: "refused", reason: `pidfd_open failed (errno ${opened.errno})` };
+    }
+    fd = opened.value;
+    if (!isParent()) return refuse("the watched parent exited during pidfd acquisition");
+    // Check both syscall support and permission before arming, without sending a signal.
+    const probe = api.signal(fd, 0);
+    if (probe.value < 0) {
+      close();
+      return probe.errno === ENOSYS
+        ? { kind: "unsupported", reason: "pidfd_send_signal is unsupported by this kernel" }
+        : { kind: "refused", reason: `pidfd signal check failed (errno ${probe.errno})` };
+    }
+    if (!isParent()) return refuse("the watched parent exited during pidfd verification");
+    return {
+      kind: "bound",
+      handle: {
+        close,
+        terminate: () => {
+          if (closed || signalled) return "not_target";
+          // A throwing binding must settle the recorded intent as "failed", like process.kill does.
+          let sent: CallResult;
+          try { sent = api.signal(fd!, 9); } catch { return "failed"; }
+          if (sent.value < 0) return sent.errno === ESRCH ? "not_target" : "failed";
+          signalled = true;
+          return "terminated";
+        },
+      },
+    };
+  } catch {
+    return refuse("Linux pidfd binding failed");
+  }
+}