@bitkyc08/opencodex 2.83.0 → 2.86.0

package/src/lib/socks5-handshake.ts

@@ -0,0 +1,112 @@
+/**
+ * The SOCKS5 handshake both raw outbound transports share: method negotiation
+ * (RFC 1928), the optional RFC 1929 username/password subnegotiation, and the
+ * CONNECT exchange.
+ *
+ * `src/lib/socks5-fetch.ts` (the HTTP tunnel) and
+ * `src/lib/desktop-upstream-tunnel.ts` (the native desktop relay's raw
+ * dial) each own their socket, their timeouts, and what happens after CONNECT;
+ * this module only frames bytes through the reader each hands it, so a
+ * credentialed `socks5://` proxy URL authenticates identically whether the caller
+ * is a fetch or a raw WebSocket upgrade. When the URL carries credentials the
+ * greeting offers NO-AUTH alongside USER-PASS, which keeps an unauthenticated
+ * proxy working for a caller that configured more than it needed.
+ */
+
+export class Socks5HandshakeError extends Error {
+  override readonly name = "Socks5HandshakeError";
+}
+
+const SOCKS5_VERSION = 0x05;
+const SOCKS5_NO_AUTH = 0x00;
+const SOCKS5_USER_PASS = 0x02;
+const SOCKS5_CONNECT = 0x01;
+const SOCKS5_DOMAIN = 0x03;
+const SOCKS5_SUCCESS = 0x00;
+
+/** RFC 1929 credentials decoded from the proxy URL, each bounded to one length byte. */
+export interface Socks5Credentials {
+  username?: Uint8Array;
+  password?: Uint8Array;
+}
+
+export function socks5Credentials(proxy: URL): Socks5Credentials {
+  if (!proxy.username && !proxy.password) return {};
+  let username: string;
+  let password: string;
+  try {
+    username = decodeURIComponent(proxy.username);
+    password = decodeURIComponent(proxy.password);
+  } catch {
+    throw new Socks5HandshakeError("SOCKS5 proxy credentials contain invalid percent encoding");
+  }
+  const usernameBytes = new TextEncoder().encode(username);
+  const passwordBytes = new TextEncoder().encode(password);
+  if (usernameBytes.byteLength > 255 || passwordBytes.byteLength > 255) {
+    throw new Socks5HandshakeError("SOCKS5 proxy credentials must each fit in 255 UTF-8 bytes");
+  }
+  return { username: usernameBytes, password: passwordBytes };
+}
+
+/**
+ * The slice of a transport's socket reader the handshake needs: exact-length reads
+ * that reject on close, on error, or on the transport's own timeout, plus writes.
+ * Bytes read past a step stay queued in the transport's reader; the handshake never
+ * touches the socket itself.
+ */
+export interface Socks5HandshakeReader {
+  write(bytes: Uint8Array): void;
+  readExact(bytes: number, signal?: AbortSignal): Promise<Uint8Array>;
+}
+
+export interface Socks5Target {
+  host: string;
+  port: number;
+}
+
+/** Negotiate methods, authenticate when the proxy picks USER-PASS, and CONNECT to `target`. */
+export async function socks5Handshake(
+  reader: Socks5HandshakeReader,
+  target: Socks5Target,
+  credentials: Socks5Credentials,
+  signal?: AbortSignal,
+): Promise<void> {
+  const hostBytes = Buffer.from(target.host, "utf8");
+  if (hostBytes.byteLength > 255) throw new Socks5HandshakeError("SOCKS5 target hostname is too long");
+  const methods = credentials.username ? [SOCKS5_NO_AUTH, SOCKS5_USER_PASS] : [SOCKS5_NO_AUTH];
+  reader.write(Buffer.from([SOCKS5_VERSION, methods.length, ...methods]));
+  const greeting = await reader.readExact(2, signal);
+  if (greeting[0] !== SOCKS5_VERSION) throw new Socks5HandshakeError("SOCKS5 proxy returned an invalid greeting");
+  if (greeting[1] === SOCKS5_USER_PASS && credentials.username && credentials.password) {
+    reader.write(Buffer.from([
+      0x01,
+      credentials.username.byteLength,
+      ...credentials.username,
+      credentials.password.byteLength,
+      ...credentials.password,
+    ]));
+    const auth = await reader.readExact(2, signal);
+    if (auth[0] !== 0x01 || auth[1] !== 0x00) throw new Socks5HandshakeError("SOCKS5 proxy authentication failed");
+  } else if (greeting[1] !== SOCKS5_NO_AUTH) {
+    throw new Socks5HandshakeError("SOCKS5 proxy does not accept an offered authentication method");
+  }
+
+  reader.write(Buffer.from([
+    SOCKS5_VERSION,
+    SOCKS5_CONNECT,
+    0x00,
+    SOCKS5_DOMAIN,
+    hostBytes.byteLength,
+    ...hostBytes,
+    target.port >> 8,
+    target.port & 0xff,
+  ]));
+  const reply = await reader.readExact(4, signal);
+  if (reply[0] !== SOCKS5_VERSION) throw new Socks5HandshakeError("SOCKS5 proxy returned an invalid connect response");
+  if (reply[1] !== SOCKS5_SUCCESS) throw new Socks5HandshakeError(`SOCKS5 proxy refused the connection (code ${reply[1]})`);
+  if (reply[2] !== 0x00 || ![0x01, SOCKS5_DOMAIN, 0x04].includes(reply[3]!)) {
+    throw new Socks5HandshakeError("SOCKS5 proxy returned an invalid address type or reserved byte");
+  }
+  const addressLength = reply[3] === 0x01 ? 4 : reply[3] === SOCKS5_DOMAIN ? (await reader.readExact(1, signal))[0]! : 16;
+  await reader.readExact(addressLength + 2, signal);
+}

package/src/lib/translator-budget.ts

@@ -1,3 +1,5 @@
+import { isNonReplayableResponse, markResponseNonReplayable } from "./upstream-retry";
+
 export const TRANSLATOR_MAX_CALL_ARGUMENT_BYTES = 2 * 1024 * 1024;
 export const TRANSLATOR_MAX_TURN_BYTES = 32 * 1024 * 1024;
 export const TRANSLATOR_MAX_SSE_EVENT_BYTES = 32 * 1024 * 1024;
@@ -410,5 +412,9 @@ export function finalizeTranslatorBudgetResponse(response: Response, budget: Tra
   });
   if (signal?.aborted) finalize();
   else signal?.addEventListener("abort", finalize, { once: true });
-  return new Response(body, { status: response.status, statusText: response.statusText, headers: response.headers });
+  const finalizedResponse = new Response(body, { status: response.status, statusText: response.statusText, headers: response.headers });
+  // The rebuild above drops identity markers. A refusal that must not be replayed
+  // stays non-replayable through accounting finalization.
+  if (isNonReplayableResponse(response)) markResponseNonReplayable(finalizedResponse);
+  return finalizedResponse;
 }

package/src/link/codex-settings.ts

@@ -0,0 +1,155 @@
+/**
+ * The Codex settings a Remote Link Home decides for its Children (#6957).
+ *
+ * A link Child relays every model request to its Home, so everything the Home's proxy applies
+ * per request already follows the Home: effort caps, the sub-agent roster and fallback, the
+ * injection prompt, sidecar and compaction routing, and the catalog itself (served by
+ * `/v1/catalog`). What does NOT follow is the part of the Home's OpenCodex config that the
+ * injector writes into the Child's own Codex `config.toml`. This module carries exactly that
+ * part, which is every OpenCodex config field the Codex injection plan reads that is a policy
+ * decision rather than a fact about the Child's own listener:
+ *
+ * - `fastMode` -> `[features] fast_mode`
+ * - `multiAgentMode` -> the native `features.multi_agent_v2` reconcile (v1 mode)
+ * - `webSearchSidecar.enabled` -> the root `web_search` switch
+ * - `syncCodexSubagentDefaults` + `injectionModel` + `injectionEffort` -> the managed
+ *   `[agents]` defaults
+ *
+ * Root `model_reasoning_effort` and the `desktop.*` picker keys are Codex app settings that
+ * OpenCodex never writes on any machine, so they are deliberately not part of this document.
+ * Listener facts (port, hostname, Desktop authless and client compaction routing forms, resume
+ * history) stay the Child's own because they describe how the Child's Codex reaches the Child.
+ *
+ * It rides on its own authenticated link read rather than inside the catalog because the
+ * catalog bytes are written verbatim to `model_catalog_json`, which Codex parses itself.
+ */
+import { hostname } from "node:os";
+import type { OcxConfig } from "../types";
+
+export const HOME_CODEX_SETTINGS_VERSION = 1;
+const MULTI_AGENT_MODES = ["v1", "default", "v2"] as const;
+type MultiAgentMode = (typeof MULTI_AGENT_MODES)[number];
+
+export interface HomeCodexSettings {
+  /** null: the Home leaves `fast_mode` alone. */
+  fastMode: boolean | null;
+  /** null: the Home has no explicit mode. */
+  multiAgentMode: MultiAgentMode | null;
+  webSearchSidecarEnabled: boolean;
+  subagentDefaults: { model: string; reasoningEffort: string | null } | null;
+}
+
+export interface HomeCodexSettingsDocument {
+  version: typeof HOME_CODEX_SETTINGS_VERSION;
+  home: { name: string; version: string };
+  settings: HomeCodexSettings;
+}
+
+const NAME_MAX = 255;
+const VALUE_MAX = 256;
+
+function safeLabel(value: string, max: number): string | null {
+  const trimmed = value.trim();
+  if (!trimmed || trimmed.length > max) return null;
+  for (const character of trimmed) {
+    const code = character.codePointAt(0) ?? 0;
+    if (code < 0x20 || code === 0x7f || (code >= 0x202a && code <= 0x202e) || (code >= 0x2066 && code <= 0x2069)) return null;
+  }
+  return trimmed;
+}
+
+export function projectHomeCodexSettings(config: OcxConfig, version: string): HomeCodexSettingsDocument {
+  const mode = config.multiAgentMode;
+  // Same predicate as `subagentDefaultSyncEffective` (src/config/diagnostics.ts), inlined so
+  // this module stays inside the src/link import boundary.
+  const sync = config.syncCodexSubagentDefaults === true && Boolean(config.injectionModel?.trim());
+  const effort = config.injectionEffort?.trim();
+  return {
+    version: HOME_CODEX_SETTINGS_VERSION,
+    home: { name: safeLabel(hostname(), NAME_MAX) ?? "Home", version },
+    settings: {
+      fastMode: typeof config.fastMode === "boolean" ? config.fastMode : null,
+      multiAgentMode: mode && (MULTI_AGENT_MODES as readonly string[]).includes(mode) ? mode : null,
+      webSearchSidecarEnabled: config.webSearchSidecar?.enabled !== false,
+      subagentDefaults: sync
+        ? { model: config.injectionModel!.trim(), reasoningEffort: effort ? effort : null }
+        : null,
+    },
+  };
+}
+
+function exactKeys(value: unknown, keys: readonly string[]): value is Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const actual = Object.keys(value);
+  return actual.length === keys.length && actual.every(key => keys.includes(key));
+}
+
+/** Strict parse: an unknown field, a wrong type or an unsafe label rejects the whole document. */
+export function parseHomeCodexSettingsDocument(value: unknown): HomeCodexSettingsDocument | null {
+  if (!exactKeys(value, ["version", "home", "settings"]) || value.version !== HOME_CODEX_SETTINGS_VERSION) return null;
+  const home = value.home;
+  if (!exactKeys(home, ["name", "version"]) || typeof home.name !== "string" || typeof home.version !== "string") return null;
+  const name = safeLabel(home.name, NAME_MAX);
+  const homeVersion = safeLabel(home.version, 64);
+  if (!name || !homeVersion) return null;
+  const s = value.settings;
+  if (!exactKeys(s, ["fastMode", "multiAgentMode", "webSearchSidecarEnabled", "subagentDefaults"])) return null;
+  if (s.fastMode !== null && typeof s.fastMode !== "boolean") return null;
+  if (s.multiAgentMode !== null && !(MULTI_AGENT_MODES as readonly unknown[]).includes(s.multiAgentMode)) return null;
+  if (typeof s.webSearchSidecarEnabled !== "boolean") return null;
+  let subagentDefaults: HomeCodexSettings["subagentDefaults"] = null;
+  if (s.subagentDefaults !== null) {
+    const d = s.subagentDefaults;
+    if (!exactKeys(d, ["model", "reasoningEffort"]) || typeof d.model !== "string") return null;
+    const model = safeLabel(d.model, VALUE_MAX);
+    if (!model) return null;
+    let reasoningEffort: string | null = null;
+    if (d.reasoningEffort !== null) {
+      if (typeof d.reasoningEffort !== "string" || !/^[a-z][a-z0-9_-]{0,31}$/.test(d.reasoningEffort)) return null;
+      reasoningEffort = d.reasoningEffort;
+    }
+    subagentDefaults = { model, reasoningEffort };
+  }
+  return {
+    version: HOME_CODEX_SETTINGS_VERSION,
+    home: { name, version: homeVersion },
+    settings: {
+      fastMode: s.fastMode as boolean | null,
+      multiAgentMode: s.multiAgentMode as MultiAgentMode | null,
+      webSearchSidecarEnabled: s.webSearchSidecarEnabled,
+      subagentDefaults,
+    },
+  };
+}
+
+/** The Child's config as the Codex injector should see it: local listener facts, Home policy. */
+export function overlayHomeCodexSettings(config: OcxConfig, settings: HomeCodexSettings): OcxConfig {
+  const next: OcxConfig = {
+    ...config,
+    webSearchSidecar: { ...(config.webSearchSidecar ?? {}), enabled: settings.webSearchSidecarEnabled },
+  };
+  if (settings.fastMode === null) delete next.fastMode;
+  else next.fastMode = settings.fastMode;
+  if (settings.multiAgentMode === null) delete next.multiAgentMode;
+  else next.multiAgentMode = settings.multiAgentMode;
+  if (settings.subagentDefaults) {
+    next.injectionModel = settings.subagentDefaults.model;
+    next.syncCodexSubagentDefaults = true;
+    if (settings.subagentDefaults.reasoningEffort) next.injectionEffort = settings.subagentDefaults.reasoningEffort;
+    else delete next.injectionEffort;
+  } else {
+    next.syncCodexSubagentDefaults = false;
+  }
+  return next;
+}
+
+/** One line per applied value, for `ocx sync`, `ocx status` and the dashboard. */
+export function describeHomeCodexSettings(settings: HomeCodexSettings): string[] {
+  const d = settings.subagentDefaults;
+  return [
+    `fast mode: ${settings.fastMode === null ? "unset" : settings.fastMode ? "on" : "off"}`,
+    `multi-agent mode: ${settings.multiAgentMode ?? "default"}`,
+    `web search sidecar: ${settings.webSearchSidecarEnabled ? "on" : "off"}`,
+    `native sub-agent defaults: ${d ? `${d.model}${d.reasoningEffort ? ` (${d.reasoningEffort})` : ""}` : "not synced"}`,
+  ];
+}

package/src/link/management-routes.ts

@@ -0,0 +1,89 @@
+/**
+ * The read-only management surface a Remote Link Child may reach on its Home (#6957).
+ *
+ * Default deny: a path is readable only when it is listed here, the method is GET or HEAD, and
+ * the query does not ask the Home to refresh upstream state. Everything else is refused on both
+ * ends: the Child's listener and CLI refuse before sending, and the Home's link listener answers
+ * 404 for any other path under the prefix. No route here returns a credential value; provider
+ * and account projections report presence and masked identities only.
+ *
+ * A link read must not change the Home. The Home runs these reads passively
+ * (`src/lib/passive-read.ts`): model discovery, which reaches provider upstreams and persists the
+ * initial model selection of a pending provider, config writes and diagnostics do not run (#6959).
+ * `tests/server/link-management-relay.test.ts` reads every path here and asserts that the Home
+ * config and its upstreams are untouched.
+ */
+export const LINK_MANAGEMENT_PREFIX = "/v1/link-management";
+/** The Home's OpenCodex-owned Codex settings a Child applies when it syncs. */
+export const LINK_CODEX_SETTINGS_PATH = `${LINK_MANAGEMENT_PREFIX}/codex-settings`;
+
+export const LINK_MANAGEMENT_READ_PATHS: readonly string[] = [
+  "/api/system/health",
+  "/api/startup-health",
+  "/api/providers",
+  "/api/settings",
+  "/api/usage",
+  "/api/effort-caps",
+  "/api/injection-model",
+  "/api/shadow-call-settings",
+  "/api/sidecar-settings",
+  "/api/v2",
+  "/api/provider-quotas",
+  "/api/codex-auth/active",
+  "/api/codex-auth/accounts",
+  "/api/oauth/accounts",
+  "/api/providers/keys",
+  "/api/oauth/providers",
+  "/api/catalog",
+  "/api/system/memory",
+  "/api/provider-presets",
+  "/api/provider-context-caps",
+];
+const READ_PATHS = new Set(LINK_MANAGEMENT_READ_PATHS);
+/**
+ * Query keys that make a read trigger upstream work on the Home: forced refreshes and the
+ * per-account quota probes `?quota=1` starts on the OAuth-account and key-pool reads.
+ * `/api/models`, `/api/model-presets`, `/api/subagent-models` and `/api/subagent-model-fallback`
+ * are absent for the same reason: they run live provider discovery and may persist initial model
+ * selection. The preset preview exists only to decide a write a Child cannot make.
+ */
+const REFRESH_KEYS = ["refresh", "reload", "force", "quota"];
+
+/** Is `method path?query` (a Home management path, without the link prefix) readable over the link? */
+export function linkManagementReadAllowed(method: string, pathname: string, search: URLSearchParams | string = ""): boolean {
+  const upper = method.toUpperCase();
+  if (upper !== "GET" && upper !== "HEAD") return false;
+  if (!READ_PATHS.has(pathname)) return false;
+  const query = typeof search === "string" ? new URLSearchParams(search) : search;
+  return !REFRESH_KEYS.some(key => query.has(key));
+}
+
+/** The Home management URL a prefixed link request names, or null when it names none. */
+export function linkManagementTarget(url: URL): URL | null {
+  if (!url.pathname.startsWith(`${LINK_MANAGEMENT_PREFIX}/api/`)) return null;
+  const target = new URL(url.href);
+  target.pathname = url.pathname.slice(LINK_MANAGEMENT_PREFIX.length);
+  return target;
+}
+
+/** Home side: may the hub-link listener dispatch this request to the link management handler? */
+export function linkManagementRouteAllowed(url: URL, req: Request): boolean {
+  if (req.headers.has("upgrade")) return false;
+  if (url.pathname === LINK_CODEX_SETTINGS_PATH) return req.method === "GET" && url.search === "";
+  const target = linkManagementTarget(url);
+  return target !== null && linkManagementReadAllowed(req.method, target.pathname, target.searchParams);
+}
+
+export function isLinkManagementPath(pathname: string): boolean {
+  return pathname === LINK_MANAGEMENT_PREFIX || pathname.startsWith(`${LINK_MANAGEMENT_PREFIX}/`);
+}
+
+/**
+ * The one refusal every management surface on a link Child uses: the dashboard relay, the CLI,
+ * and the Child's listener. It names the Home and the link and never suggests a relay transport.
+ * `homePhrase` is "Home <name>" or "its Home" when the Child does not know the Home's name.
+ */
+export function linkChildManagementRefusal(homePhrase: string, linkId: string, operation = "This management command"): string {
+  return `This machine is a Remote Link Child managed by ${homePhrase} (link ${linkId}). `
+    + `${operation} runs on the Home, not on this Child: use the Home's dashboard or run the command there. No request was sent.`;
+}

package/src/link/remote-probe.ts

@@ -0,0 +1,38 @@
+import { MEMORY_DRAIN_RESTART_MS, REPLACEMENT_READY_TIMEOUT_MS } from "../lib/system-restart-contract";
+
+export const LINK_COMMAND_WORK_MS = 15_000;
+export const LINK_COMMAND_MAX_MS = 60_000;
+export const LINK_RELAY_VERIFY_MS = 15_000;
+export const LINK_CATALOG_MAX_BYTES = 4 * 1024 * 1024;
+
+/** Probe latency pays for SSH setup without making the remote work window unbounded. */
+export function linkCommandBudget(latencyMs = 0): number {
+  const latency = Number.isFinite(latencyMs) ? Math.max(0, latencyMs) : 0;
+  return Math.min(LINK_COMMAND_MAX_MS, LINK_COMMAND_WORK_MS + Math.ceil(latency * 4));
+}
+
+export function linkRestartBudget(latencyMs = 0): number {
+  return MEMORY_DRAIN_RESTART_MS + REPLACEMENT_READY_TIMEOUT_MS + linkCommandBudget(latencyMs);
+}
+
+/** Credential-free Child HTTP probe. Ignore curlrc/proxies; never follow a redirect. */
+export function remoteChildHttpArgv(port: number, path: "healthz" | "v1/catalog", timeoutMs = LINK_RELAY_VERIFY_MS): string[] {
+  if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error("invalid Child port");
+  const seconds = Math.max(1, Math.ceil(Math.min(LINK_RELAY_VERIFY_MS, timeoutMs) / 1000));
+  return ["sh", "-c", 'curl -q --noproxy "*" --silent --show-error --fail --connect-timeout 3 --max-time "$3" --write-out "\\n%{http_code}" "http://127.0.0.1:$1/$2"', "ocx-child-http", String(port), path, String(seconds)];
+}
+
+export const REMOTE_CURL_PREFLIGHT = ["sh", "-c", 'command -v curl >/dev/null 2>&1 && curl -q --version >/dev/null 2>&1', "ocx-curl-preflight"];
+
+export function parseChildHttp(stdout: string): unknown {
+  const match = /\n200$/.exec(stdout.trimEnd());
+  if (!match) throw new Error("Child HTTP probe did not return 200");
+  return JSON.parse(stdout.trimEnd().slice(0, match.index));
+}
+
+export function isChildHealth(value: unknown, role: "standalone" | "client", expectedPort: number): boolean {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const body = value as Record<string, unknown>;
+  return body.port === expectedPort && body.service === "opencodex" && Number.isInteger(body.pid) && (body.pid as number) > 0
+    && (role === "client" ? body.role === "client" : (body.role === undefined || body.role === "standalone") && body.restartCapability === "v1");
+}

package/src/link/ssh-argv.ts

@@ -131,15 +131,36 @@ export function buildExecArgv(options: ExecArgvOptions): string[] {
   ];
 }
 
+/** The POSIX shell's exit status for a command it could not find. */
+export const REMOTE_COMMAND_NOT_FOUND = 127;
+/** Reserved prelude status: the remote OS cannot run the POSIX Remote Link workflow. */
+export const REMOTE_PLATFORM_UNSUPPORTED = 125;
+
 /**
  * The remote sh script for every ocx call. `quoteRemote` single-quotes it, so the login shell
  * passes it through untouched and `$HOME`/`$PATH` expand in the remote `sh`; the arguments reach
- * ocx as `"$@"` without another round of parsing. The fallback directories are appended, so an
- * ocx the remote PATH already resolves keeps winning. A missing ocx exits 127.
+ * ocx as `"$@"` without another round of parsing. Desktop binaries precede PATH candidates;
+ * each candidate must run --version successfully. A missing runnable ocx exits 127.
  */
-export const REMOTE_OCX_SCRIPT = 'PATH="$PATH:$HOME/.bun/bin:$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin"; exec ocx "$@"';
-/** The POSIX shell's exit status for a command it could not find. */
-export const REMOTE_COMMAND_NOT_FOUND = 127;
+export const REMOTE_OCX_SCRIPT = `export PATH="$PATH:$HOME/.bun/bin:$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin"
+case "$(uname -s 2>/dev/null)" in Windows*|MSYS*|MINGW*|CYGWIN*) exit ${REMOTE_PLATFORM_UNSUPPORTED};; esac
+try_ocx() {
+  if [ -x "$1" ] && "$1" --version >/dev/null 2>&1; then
+    executable=$1
+    shift
+    exec "$executable" "$@"
+  fi
+}
+for candidate in "$HOME/.opencodex-desktop/bin/ocx" "/Applications/OpenCodex.app/Contents/MacOS/ocx" "/usr/bin/ocx"; do
+  try_ocx "$candidate" "$@"
+done
+remaining=$PATH
+while :; do
+  directory=\${remaining%%:*}
+  try_ocx "\${directory:-.}/ocx" "$@"
+  case "$remaining" in *:*) remaining=\${remaining#*:};; *) break;; esac
+done
+exit ${REMOTE_COMMAND_NOT_FOUND}`;
 
 export function remoteOcxArgv(args: readonly string[]): string[] {
   return ["sh", "-c", REMOTE_OCX_SCRIPT, "ocx", ...args];

package/src/link/ssh-runner.ts

@@ -1,6 +1,8 @@
 import { homedir } from "node:os";
 
 const DEFAULT_OUTPUT_BYTES = 64 * 1024;
+const MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
+const TUNNEL_OUTPUT_EXIT_GRACE_MS = 250;
 const HINT_MAX_CHARS = 160;
 // Written as escapes on purpose: invisible and bidi controls must never sit literally in source.
 const ANSI_SEQUENCE = /\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)|\u001b\[[0-?]*[ -/]*[@-~]|\u001b[@-_]/g;
@@ -93,10 +95,21 @@ export class SshRunnerError extends Error {
   }
 }
 
-async function readOutput(stream: ReadableStream<Uint8Array>, maxBytes: number, kill?: () => void, fatalUtf8 = true): Promise<string> {
+async function readOutput(stream: ReadableStream<Uint8Array>, maxBytes: number, kill?: () => void, fatalUtf8 = true, exited?: Promise<number>, signal?: AbortSignal): Promise<string> {
   const reader = stream.getReader();
   const chunks: Uint8Array[] = [];
   let total = 0;
+  let finished = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const cancel = (): void => { void reader.cancel().catch(() => {}); };
+  const onExit = (): void => {
+    if (!finished) timer = setTimeout(cancel, TUNNEL_OUTPUT_EXIT_GRACE_MS);
+  };
+  signal?.addEventListener("abort", cancel, { once: true });
+  if (signal?.aborted) cancel();
+  // A descendant may inherit a pipe after ssh exits. Cancellation completes pending reads
+  // immediately; do not await the underlying source's possibly unbounded cancel promise.
+  void exited?.then(onExit, onExit);
   try {
     for (;;) {
       const next = await reader.read();
@@ -104,11 +117,15 @@ async function readOutput(stream: ReadableStream<Uint8Array>, maxBytes: number,
       total += next.value.byteLength;
       if (total > maxBytes) {
         kill?.();
+        cancel();
         throw new SshRunnerError("output_limit", `ssh output exceeded ${maxBytes} bytes`);
       }
       chunks.push(next.value);
     }
   } finally {
+    finished = true;
+    if (timer !== undefined) clearTimeout(timer);
+    signal?.removeEventListener("abort", cancel);
     reader.releaseLock();
   }
   const bytes = new Uint8Array(total);
@@ -149,8 +166,8 @@ export function createSshRunner(deps: { spawn?: typeof Bun.spawn; timeoutMs?: nu
     } catch (error) {
       throw new SshRunnerError("spawn", `could not spawn ${argv[0] ?? "ssh"}`, { cause: error });
     }
-    const stdout = readOutput(outputStream(child.stdout), DEFAULT_OUTPUT_BYTES, () => defaultKill(child, "SIGTERM"));
-    const stderr = readOutput(outputStream(child.stderr), DEFAULT_OUTPUT_BYTES, () => defaultKill(child, "SIGTERM"), false);
+    const stdout = readOutput(outputStream(child.stdout), DEFAULT_OUTPUT_BYTES, () => defaultKill(child, "SIGTERM"), true, child.exited);
+    const stderr = readOutput(outputStream(child.stderr), DEFAULT_OUTPUT_BYTES, () => defaultKill(child, "SIGTERM"), false, child.exited);
     void stdout.catch(() => {});
     void stderr.catch(() => {});
     return {
@@ -165,9 +182,13 @@ export function createSshRunner(deps: { spawn?: typeof Bun.spawn; timeoutMs?: nu
 
   return {
     async run(argv, options = {}) {
+      const timeoutMs = options.timeoutMs ?? defaultTimeoutMs;
+      if (!Number.isInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647) {
+        throw new SshRunnerError("timeout", "timeoutMs must be a positive integer at most 2147483647");
+      }
       const maxOutputBytes = options.maxOutputBytes ?? DEFAULT_OUTPUT_BYTES;
-      if (!Number.isInteger(maxOutputBytes) || maxOutputBytes < 0) {
-        throw new SshRunnerError("output_limit", "maxOutputBytes must be a non-negative integer");
+      if (!Number.isInteger(maxOutputBytes) || maxOutputBytes < 0 || maxOutputBytes > MAX_OUTPUT_BYTES) {
+        throw new SshRunnerError("output_limit", `maxOutputBytes must be an integer between 0 and ${MAX_OUTPUT_BYTES}`);
       }
       let child: Bun.Subprocess;
       try {
@@ -181,41 +202,50 @@ export function createSshRunner(deps: { spawn?: typeof Bun.spawn; timeoutMs?: nu
         throw new SshRunnerError("spawn", `could not spawn ${argv[0] ?? "ssh"}`, { cause: error });
       }
 
-      const stdout = readOutput(outputStream(child.stdout), Math.min(maxOutputBytes, DEFAULT_OUTPUT_BYTES), () => defaultKill(child, "SIGTERM"));
-      const stderr = readOutput(outputStream(child.stderr), Math.min(maxOutputBytes, DEFAULT_OUTPUT_BYTES), () => defaultKill(child, "SIGTERM"), false);
-      if (options.stdin !== undefined) {
-        try {
-          const input = child.stdin;
-          if (!input || typeof input === "number") throw new Error("ssh stdin was not piped");
-          await input.write(options.stdin);
-          await input.end();
-        } catch (error) {
-          child.kill("SIGTERM");
-          throw new SshRunnerError("spawn", "could not write ssh stdin", { cause: error });
-        }
-      }
-
-      const timeoutMs = options.timeoutMs ?? defaultTimeoutMs;
-      let timedOut = false;
+      const cancellation = new AbortController();
+      let stdout: Promise<string> | undefined;
+      let stderr: Promise<string> | undefined;
       let timer: ReturnType<typeof setTimeout> | undefined;
       const timeout = new Promise<never>((_, reject) => {
         timer = setTimeout(() => {
-          timedOut = true;
-          defaultKill(child, "SIGTERM");
           reject(new SshRunnerError("timeout", `ssh command exceeded ${timeoutMs}ms`));
         }, timeoutMs);
       });
       try {
-        const code = await Promise.race([child.exited, timeout]);
-        const [out, err] = await Promise.all([stdout, stderr]);
-        if (timedOut) throw new SshRunnerError("timeout", `ssh command exceeded ${timeoutMs}ms`);
+        const outStream = outputStream(child.stdout), errStream = outputStream(child.stderr);
+        stdout = readOutput(outStream, maxOutputBytes, undefined, true, undefined, cancellation.signal);
+        stderr = readOutput(errStream, Math.min(maxOutputBytes, DEFAULT_OUTPUT_BYTES), undefined, false, undefined, cancellation.signal);
+        const stdin = async (): Promise<void> => {
+          if (options.stdin === undefined) return;
+          try {
+            const input = child.stdin;
+            if (!input || typeof input === "number") throw new Error("ssh stdin was not piped");
+            await input.write(options.stdin);
+            // A timed-out write may settle later; do not start another operation after failure.
+            if (cancellation.signal.aborted) return;
+            await input.end();
+          } catch (error) {
+            throw new SshRunnerError("spawn", "could not write ssh stdin", { cause: error });
+          }
+        };
+        // Observe all rejections immediately, including errors arriving after timeout. One
+        // deadline covers stdin, exit and EOF: an inherited output pipe is still unfinished work.
+        const [, code, out, err] = await Promise.race([
+          Promise.all([stdin(), child.exited, stdout, stderr]), timeout,
+        ]);
         return { code, stdout: out, stderr: err };
       } catch (error) {
+        cancellation.abort();
+        // Only terminate this local SSH child. A kill failure must not hide the original error.
+        try { defaultKill(child, "SIGTERM"); } catch { /* Preserve the command failure when an already-gone child cannot be signalled. */ }
         if (error instanceof SshRunnerError) throw error;
         throw new SshRunnerError("spawn", "ssh command failed", { cause: error });
       } finally {
         if (timer !== undefined) clearTimeout(timer);
-        void Promise.allSettled([stdout, stderr, child.exited]);
+        void child.exited.catch(() => {});
+        // reader.cancel closes pending reads even if the source's cancel promise never settles.
+        // Do not await stdin or process exit: neither is guaranteed to settle after SIGTERM.
+        await Promise.allSettled([stdout, stderr]);
       }
     },
     spawnTunnel,
@@ -227,3 +257,4 @@ export function createSshRunner(deps: { spawn?: typeof Bun.spawn; timeoutMs?: nu
 }
 
 export const SSH_OUTPUT_CAP_BYTES = DEFAULT_OUTPUT_BYTES;
+export const SSH_MAX_OUTPUT_BYTES = MAX_OUTPUT_BYTES;