@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
609 lines (570 loc) • 32 kB
text/typescript
import { isRouteClientId, type RouteClientId } from "./route-intent";
/**
* Argument vectors for the system OpenSSH client used by machine links.
*
* Every command is built here so the security-relevant options live in one place:
* - BatchMode=yes: no password or passphrase prompt, keys and agents only.
* - HostKeyAlias=<alias> with UserKnownHostsFile=<link known_hosts> and
* GlobalKnownHostsFile=none: only a host key the user confirmed for this link is trusted,
* and the stored entry has the same form for every port and ProxyJump route.
* - HashKnownHosts=no: private probe records keep their alias-prefixed form even
* when the user's normal SSH configuration hashes its own known_hosts file.
* - KnownHostsCommand=none, VerifyHostKeyDNS=no and CheckHostIP=no: no other source of host-key
* trust (a helper command, DNS SSHFP records, IP entries) can stand in for the link file.
* Command-line options win over ~/.ssh/config, so a user config cannot re-enable them.
* - Tunnel and exec commands use StrictHostKeyChecking=yes. Only the probe uses accept-new,
* against an empty temporary file, so the key it records can be shown to the user first.
* - Forwards always bind 127.0.0.1 on both ends.
* - Remote ocx runs through `remoteOcxArgv`: a non-interactive ssh session reads no interactive
* profile, so ~/.bun/bin and Homebrew are usually missing from the remote PATH.
*/
import { isAbsolute } from "node:path";
import { ExplicitRouteError, explicitRouteSshOptions, type ExplicitRoute } from "./explicit-route";
import { REMOTE_SERVED_PATH_TRUST } from "./remote-runtime-trust";
import { POWERSHELL_ENCODED_MAX, PowerShellCommandTooLongError, ROUTE_OVERWRITE_MIN_CHILD_VERSION, windowsGatedOcxArgv, windowsOcxArgv, windowsOverwriteSyncArgv } from "./remote-windows";
export type TunnelDirection = "R" | "L";
const ALIAS_PATTERN = /^[A-Za-z0-9_][A-Za-z0-9._@%+:\[\]-]{0,252}$/;
export class LinkSshArgumentError extends Error {
constructor(message: string) {
super(message);
this.name = "LinkSshArgumentError";
}
}
/** A host alias as ssh reads it. A leading "-" would be parsed as an option, so it is refused. */
export function isSshAlias(alias: string): boolean {
return ALIAS_PATTERN.test(alias);
}
export function assertSshAlias(alias: string): string {
if (!ALIAS_PATTERN.test(alias)) throw new LinkSshArgumentError(`invalid ssh host alias: ${JSON.stringify(alias)}`);
return alias;
}
function assertPort(port: number, label: string): number {
if (!Number.isInteger(port) || port < 1 || port > 65535) {
throw new LinkSshArgumentError(`${label} must be an integer port between 1 and 65535`);
}
return port;
}
/**
* ssh splits `-o` values on whitespace, expands `%` tokens, `${ENV}` and a leading `~` in
* UserKnownHostsFile, treats the value `none` as "no file" and resolves a relative path against
* its working directory. Any of those could name a different file than the one written, so only
* an absolute path without expansion syntax is accepted; whitespace is quoted.
*/
function assertKnownHostsPath(path: string): string {
if (!path || !isAbsolute(path) || /["%$\x00-\x1f]/.test(path) || path.startsWith("~")) {
throw new LinkSshArgumentError("known_hosts path is not usable in an ssh option");
}
return path;
}
function optionPath(path: string): string {
assertKnownHostsPath(path);
return /\s/.test(path) ? `"${path}"` : path;
}
/** ERROR everywhere; DEBUG1 only for a tunnel spawned while opt-in SSH capture is on (src/link/ssh-capture.ts). */
export type SshLogLevel = "ERROR" | "DEBUG1";
/**
* The link's explicit route (src/link/explicit-route.ts) as command-line options, which ssh takes before
* anything in ssh_config. It names how to reach the link's own alias, so it is refused with any other
* destination; null adds nothing, which is the argv of a link without one.
*/
function routeOptions(route: ExplicitRoute | null | undefined, alias: string, destination: string): RouteArgs {
if (!route) return NO_ROUTE;
if (destination !== alias) throw new LinkSshArgumentError("an explicit route reaches the link alias only");
try {
// Decided by the route itself, never by what its options happen to be: a link with a route reads no ssh_config.
return { configFile: ["-F", "none"], options: explicitRouteSshOptions(route) };
} catch (error) {
if (error instanceof ExplicitRouteError) throw new LinkSshArgumentError(error.message);
throw error;
}
}
/**
* What a route adds to the argv. configFile is ["-F", "none"] for every explicit route and comes first: an explicit route
* names the transport, user and port and the host key is pinned, so such a link reads no ssh_config at all (list-valued
* settings such as forwards, SendEnv and IdentityFile would add to ours, a RemoteCommand would break every exec, and no
* option can remove a configured forward from the tunnel). A route's identity file (link.route/2) narrows what remains:
* with -F none the defaults still offer the agent's keys and ~/.ssh/id_*, so IdentitiesOnly=yes and IdentityAgent=none
* leave that one IdentityFile. Links without a route keep reading the owner's ssh_config, which is how they reach their host.
*/
interface RouteArgs { configFile: readonly string[]; options: readonly string[] }
const NO_ROUTE: RouteArgs = { configFile: [], options: [] };
function commonOptions(alias: string, knownHostsFile: string, strict: "yes" | "accept-new", logLevel: SshLogLevel, route: RouteArgs): string[] {
return [
...route.configFile,
"-o", "BatchMode=yes",
"-o", "ConnectTimeout=10",
"-o", "ServerAliveInterval=15",
"-o", "ServerAliveCountMax=3",
"-o", `StrictHostKeyChecking=${strict}`,
"-o", `HostKeyAlias=${alias}`,
"-o", `UserKnownHostsFile=${optionPath(knownHostsFile)}`,
"-o", "HashKnownHosts=no",
"-o", "GlobalKnownHostsFile=none",
"-o", "KnownHostsCommand=none",
"-o", "VerifyHostKeyDNS=no",
"-o", "CheckHostIP=no",
"-o", "UpdateHostKeys=no",
"-o", "ControlMaster=no",
"-o", "ControlPath=none",
"-o", "ForwardAgent=no",
"-o", "ForwardX11=no",
"-o", "PermitLocalCommand=no",
"-o", `LogLevel=${logLevel}`,
...route.options,
];
}
export interface TunnelArgvOptions {
alias: string;
/**
* Where ssh connects, when it is another route to the same machine. HostKeyAlias stays alias, so
* the route is checked against the key pinned for the link. Omitted: alias (today's argv).
*/
destination?: string;
/** "R": listen on the remote host and reach this host. "L": listen here and reach the remote host. */
direction: TunnelDirection;
/** Port the forward listens on (remote for "R", local for "L"). */
bindPort: number;
/** Port the forward connects to on the other side's 127.0.0.1. */
targetPort: number;
knownHostsFile: string;
/** Defaults to ERROR. DEBUG1 is requested only by opt-in SSH capture; the argv is otherwise unchanged. */
logLevel?: SshLogLevel;
/**
* The link's explicit route, or null. Required so every caller decides: a Home-initiated link passes
* its record's explicitRoute (absent: null); Child-initiated and messaging commands pass null.
*/
route: ExplicitRoute | null;
}
export function buildTunnelArgv(options: TunnelArgvOptions): string[] {
const alias = assertSshAlias(options.alias);
const destination = assertSshAlias(options.destination ?? alias);
const bind = assertPort(options.bindPort, "bindPort");
const target = assertPort(options.targetPort, "targetPort");
if (options.direction !== "R" && options.direction !== "L") throw new LinkSshArgumentError("direction must be R or L");
const logLevel = options.logLevel ?? "ERROR";
if (logLevel !== "ERROR" && logLevel !== "DEBUG1") throw new LinkSshArgumentError("logLevel must be ERROR or DEBUG1");
return [
"ssh", "-N", "-T",
...commonOptions(alias, options.knownHostsFile, "yes", logLevel, routeOptions(options.route, alias, destination)),
"-o", "ExitOnForwardFailure=yes",
`-${options.direction}`, `127.0.0.1:${bind}:127.0.0.1:${target}`,
"--", destination,
];
}
export interface ExecArgvOptions {
alias: string;
/** Another route to the same machine; HostKeyAlias stays alias. Omitted: alias. */
destination?: string;
/** Remote argv. The command must be sh; its arguments are quoted for the remote shell. */
argv: readonly string[];
knownHostsFile: string;
/**
* The link's explicit route, or null. Required so every caller decides: a Home-initiated link passes
* its record's explicitRoute (absent: null); Child-initiated and messaging commands pass null.
*/
route: ExplicitRoute | null;
}
export function buildExecArgv(options: ExecArgvOptions): string[] {
const alias = assertSshAlias(options.alias);
const destination = assertSshAlias(options.destination ?? alias);
if (options.argv.length === 0) throw new LinkSshArgumentError("remote argv must not be empty");
return [
"ssh", "-T",
...commonOptions(alias, options.knownHostsFile, "yes", "ERROR", routeOptions(options.route, alias, destination)),
"-o", "ClearAllForwardings=yes",
"--", destination,
quoteRemote(options.argv),
];
}
/** 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;
/**
* Reads the first record's \`command\` of \`serving-runtimes.json\` (#8359): one or two absolute paths
* without quotes or backslashes, printed one per line, from a file of at most 64 KiB. The file must
* be the complete document in the layout its only writer produces (\`JSON.stringify(_, null, 2)\` in
* src/config/serving-runtimes.ts): a first record without \`command\` never borrows a later record's,
* and a file cut off anywhere before its closing brace prints nothing. Any other shape fails, and an
* unreadable file or a missing awk fails without writing to stderr.
* Shared by the ocx discovery, pinned sync and runtime inspection scripts.
*/
export const REMOTE_SERVED_RUNTIME = `${REMOTE_SERVED_PATH_TRUST}served_runtime() {
# The count below reports wc's status, never dd's: a missing dd or an unreadable file ends here,
# and a dd that fails anyway counts zero bytes, which is refused like an oversized census.
[ -f "$1" ] && [ -r "$1" ] && command -v dd >/dev/null 2>&1 || return 1
served_size=$( { dd if="$1" bs=65537 count=1 2>/dev/null | wc -c; } 2>/dev/null ) || return 1
[ "$served_size" -gt 0 ] 2>/dev/null && [ "$served_size" -le 65536 ] 2>/dev/null || return 1
awk '
{ prev = last; last = $0 }
bad || done { next }
NR == 1 { if ($0 != "{") bad = 1; next }
NR == 2 { if ($0 != " \\"runtimes\\": [") bad = 1; next }
NR == 3 { if ($0 != " {") bad = 1; next }
inside {
if ($0 == " ]" || $0 == " ],") { inside = 0; closed = 1; next }
line = $0; sub(/,$/, "", line)
if (line !~ /^ "\\/[^"\\\\]*"$/ || ++count > 2) { bad = 1; next }
path[count] = substr(line, 10, length(line) - 10); next
}
$0 == " \\"command\\": [" { if (closed) bad = 1; else inside = 1; next }
$0 == " }" || $0 == " }," { done = 1 }
END {
if (bad || !done || !closed || !count || prev != " ]" || last != "}") exit 1
for (i = 1; i <= count; i++) print path[i]
}
' "$1" 2>/dev/null
}
`;
/**
* Tries the served install with \`attempt\`, which must read \`$served_bin\` and honour \`$ocx_entry\`:
* a compiled binary runs alone, and both package paths must pass the same trust gate.
* The unquoted \`OCX_SERVED\` heredoc is safe only because \`served_runtime\` prints paths without
* quotes, backslashes or newlines; relaxing that character class would let a path expand or split.
*/
export function remoteServedRuntimeAttempt(attempt: string): string {
return `served_bin= served_entry=
if served=$(served_runtime "\${OPENCODEX_HOME:-$HOME/.opencodex}/serving-runtimes.json"); then
{ IFS= read -r served_bin; IFS= read -r served_entry; } <<OCX_SERVED
$served
OCX_SERVED
served_bin=$(trusted_served_path "$served_bin") || served_bin=
if [ -z "$served_bin" ]; then
:
elif [ -z "$served_entry" ]; then
${attempt}
elif served_entry=$(trusted_served_path "$served_entry"); then
ocx_entry=$served_entry
${attempt}
ocx_entry=
fi
fi`;
}
/**
* 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. After an ephemeral ocx-child, the install that
* last started serving this home comes first, whatever its version (#8359): every `ocx start` that binds records its own
* relaunch argv at the front of `serving-runtimes.json` (src/config/serving-runtimes.ts), `[ocx]`
* for a compiled binary or `[bun, cli/index.ts]` for a package install. Only the first entry's
* `command`, one or two absolute paths without quotes or backslashes, is read; any other shape
* falls through. Desktop binaries then precede PATH candidates; each candidate must run --version
* successfully. A missing runnable ocx exits 127.
*/
const REMOTE_OCX_CANDIDATES = `ocx_entry=
${REMOTE_SERVED_RUNTIME}run_ocx_child() {
for candidate in "$HOME/.local/bin/ocx-child" "$HOME/.cache/opencodex/bin/ocx-child"; do
try_ocx "$candidate" "$@"
done
remaining=$PATH
while :; do
directory=\${remaining%%:*}
try_ocx "\${directory:-.}/ocx-child" "$@"
case "$remaining" in *:*) remaining=\${remaining#*:};; *) break;; esac
done
}
if [ -f "\${OPENCODEX_HOME:-$HOME/.opencodex}/child/state.json" ]; then
run_ocx_child "$@"
fi
${remoteServedRuntimeAttempt('try_ocx "$served_bin" "$@"')}
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
run_ocx_child "$@"`;
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" \${ocx_entry:+"$ocx_entry"} --version >/dev/null 2>&1; then
executable=$1
shift
exec "$executable" \${ocx_entry:+"$ocx_entry"} "$@"
fi
}
${REMOTE_OCX_CANDIDATES}
exit ${REMOTE_COMMAND_NOT_FOUND}`;
export function remoteOcxArgv(args: readonly string[], platform: "posix" | "windows" = "posix"): string[] {
return platform === "windows" ? windowsOcxArgv(args) : ["sh", "-c", REMOTE_OCX_SCRIPT, "ocx", ...args];
}
export interface ProbeArgvOptions {
alias: string;
/** An empty, private, temporary file. The probe records the offered host key here. */
tempKnownHostsFile: string;
/**
* The link's explicit route, or null. Required so every caller decides: a Home-initiated link passes
* its record's explicitRoute (absent: null); Child-initiated and messaging commands pass null.
*/
route: ExplicitRoute | null;
}
/**
* First contact with a host that has no confirmed key. accept-new writes the offered key to the
* temporary file; the caller reads it with `ssh-keygen -lf` and shows the fingerprint before
* anything is trusted. The remote command is a fixed cross-shell echo; it conveys no authorization.
*/
export function buildProbeArgv(options: ProbeArgvOptions): string[] {
const alias = assertSshAlias(options.alias);
return [
"ssh", "-T",
...commonOptions(alias, options.tempKnownHostsFile, "accept-new", "ERROR", routeOptions(options.route, alias, alias)),
"-o", "ClearAllForwardings=yes",
"--", alias,
"echo ocx-link-probe",
];
}
export interface RouteProbeArgvOptions {
/** The link's alias: the name its host key is pinned under. */
alias: string;
/** The route being tried. */
destination: string;
/** The link known_hosts file. It is only read: the route must offer the key already pinned. */
knownHostsFile: string;
/**
* The link's explicit route, or null. Required so every caller decides: a Home-initiated link passes
* its record's explicitRoute (absent: null); Child-initiated and messaging commands pass null.
*/
route: ExplicitRoute | null;
}
/**
* Does this route reach the pinned machine and accept our key? Strict host-key checking against
* the link file under HostKeyAlias=alias: a route that answers with any other key fails with "Host
* key verification failed" and nothing is learned or written. Success prints exactly ocx-link-probe.
*/
export function buildRouteProbeArgv(options: RouteProbeArgvOptions): string[] {
const alias = assertSshAlias(options.alias);
const destination = assertSshAlias(options.destination);
return [
"ssh", "-T",
...commonOptions(alias, options.knownHostsFile, "yes", "ERROR", routeOptions(options.route, alias, destination)),
"-o", "ClearAllForwardings=yes",
"--", destination,
"echo ocx-link-probe",
];
}
/**
* Locale-independent Windows check for a host whose SSH shell is cmd.exe or PowerShell. Both run
* `cmd.exe /c echo %OS%`, and cmd expands it to `Windows_NT` regardless of display language. The
* command is a fixed literal; a POSIX shell answers "command not found" and nothing else.
*
* It names `cmd.exe`, never bare `cmd` (#8972). Win32-OpenSSH with the default cmd.exe shell runs an
* exec request as `cmd.exe /c "<command>"`, and cmd keeps those quotes when the quoted text starts
* with the name of something runnable: `cmd /c echo %OS%` then prints `Windows_NT"`. With
* `cmd.exe` the outer cmd strips the quotes. The parser still accepts the stray quote
* (`isWindowsNtAnswer`), so a shell that adds it anyway is understood.
*/
export const WINDOWS_OS_PROBE = "cmd.exe /c echo %OS%";
/** Run WINDOWS_OS_PROBE against an already trusted (pinned or just-probed) host key only. */
export function buildWindowsProbeArgv(options: { alias: string; knownHostsFile: string; destination?: string; route: ExplicitRoute | null }): string[] {
const alias = assertSshAlias(options.alias);
const destination = assertSshAlias(options.destination ?? alias);
return [
"ssh", "-T",
...commonOptions(alias, options.knownHostsFile, "yes", "ERROR", routeOptions(options.route, alias, destination)),
"-o", "ClearAllForwardings=yes",
"--", destination,
WINDOWS_OS_PROBE,
];
}
/** Read the fingerprint of the host key recorded by a probe. */
export function buildFingerprintArgv(tempKnownHostsFile: string): string[] {
return ["ssh-keygen", "-l", "-f", assertKnownHostsPath(tempKnownHostsFile)];
}
/** `ssh -G <alias>`: resolve an alias the same way ssh itself does, without connecting. */
export function buildResolveArgv(alias: string): string[] {
return ["ssh", "-G", "--", assertSshAlias(alias)];
}
/** Emit only sh in command position; single-quote every argument for the remote shell. */
export function quoteRemote(argv: readonly string[]): string {
if (argv[0] === "powershell.exe") {
if (argv.length !== 6 || argv.slice(1, 5).join(" ") !== "-NoLogo -NoProfile -NonInteractive -EncodedCommand"
|| !/^[A-Za-z0-9+/]+={0,2}$/.test(argv[5] ?? "") || (argv[5]?.length ?? 0) > POWERSHELL_ENCODED_MAX) {
throw new LinkSshArgumentError("invalid encoded PowerShell command");
}
return argv.join(" ");
}
if (argv[0] !== "sh") throw new LinkSshArgumentError("remote command must be sh or encoded PowerShell");
return argv.map((arg, index) => {
if (arg.includes("\0")) throw new LinkSshArgumentError("remote argument contains NUL");
// PowerShell treats a leading quoted word as an expression, not a command invocation.
if (index === 0) return "sh";
return `'${arg.replaceAll("'", `'"'"'`)}'`;
}).join(" ");
}
/** Minimum served ocx for a gated command. Closed set: the literals are spliced into awk and PowerShell. */
export { ROUTE_OVERWRITE_MIN_CHILD_VERSION };
export type GatedMinVersion = "2.93.0" | "2.97.0" | "2.100.0";
export type GatedLacksMarker = "child-ocx-lacks-expect-link" | "child-ocx-lacks-orchestrated-update" | "child-ocx-lacks-overwrite";
export interface GatedOcxCommand {
minVersion: GatedMinVersion;
lacksMarker: GatedLacksMarker;
/** false: a selected ocx-child exits 121 with ocx-fanout:child-ocx-ephemeral before args run. */
acceptEphemeral: boolean;
/** true: print ocx-fanout:entry:pair|binary on stderr right after the selection marker. */
reportEntry: boolean;
/** true: print ocx-fanout:child-now:<epoch-ms> (the Child's own clock) after the entry marker. Plan probe only. */
reportClock: boolean;
/** With acceptEphemeral, print ocx-fanout:selected-kind:ocx-child when the selected candidate is ocx-child.
* Set only by remotePinnedSyncArgv when a restart is requested (ocx-child ignores the restart flags). */
reportSelectedKind?: boolean;
/**
* A4: what the script does with the Node launcher of a package install whose census pair sits under node_modules.
* "none": nothing. "report": print ocx-fanout:launcher:available|unavailable (the plan probe; never exits for it).
* "apply": exec <node> <root>/bin/ocx.mjs with the arguments, or exit 121 child-node-unavailable when no Node answers.
* A closed union spliced as a literal; only the Home's parsed plan (installer npm or pnpm) chooses "apply".
*/
launcher: "none" | "report" | "apply";
args: readonly string[];
}
export const GATED_VERSION_PARTS: Readonly<Record<GatedMinVersion, readonly [string, string, string]>> = {
"2.93.0": ["2", "93", "0"], "2.97.0": ["2", "97", "0"], "2.100.0": ["2", "100", "0"],
};
const LACKS_MARKERS: ReadonlySet<string> = new Set(["child-ocx-lacks-expect-link", "child-ocx-lacks-orchestrated-update", "child-ocx-lacks-overwrite"]);
export const LINK_ID_PATTERN = /^lnk_[0-9a-f]{16}$/;
function assertGated(cmd: GatedOcxCommand): readonly [string, string, string] {
const parts = Object.hasOwn(GATED_VERSION_PARTS, cmd.minVersion) ? GATED_VERSION_PARTS[cmd.minVersion] : undefined;
if (!parts || !LACKS_MARKERS.has(cmd.lacksMarker)) throw new LinkSshArgumentError("invalid gated ocx command");
if (cmd.args.length === 0 || cmd.args.some(arg => arg.includes("\0"))) throw new LinkSshArgumentError("invalid gated ocx arguments");
if (cmd.launcher !== "none" && cmd.launcher !== "report" && cmd.launcher !== "apply") throw new LinkSshArgumentError("invalid gated ocx launcher");
return parts;
}
/**
* The pinned script for one gate: select a candidate, read its version inside the remote script, refuse below the
* minimum, then exec it with "$@". OCX_NO_DESKTOP_HANDOFF=1 makes a package launcher answer --version for itself and
* run the command itself, so a Desktop handoff can never pass the gate on behalf of an older launcher.
* With launcher "report" or "apply" and a census pair under node_modules that ships bin/ocx.mjs, the script looks for a
* Node that answers --version within 10 s (the npm prefix's bin/node first, then PATH) before the temp dir is removed.
*/
function remoteGatedScript(cmd: GatedOcxCommand): string {
const [major, minor, patch] = assertGated(cmd);
const overwriteEphemeral = cmd.lacksMarker === "child-ocx-lacks-overwrite" ? `
case "\${c##*/}" in ocx-child*) printf '%s\\n' 'ocx-fanout:child-ephemeral-no-overwrite' >&2; exit 121;; esac` : "";
const ephemeral = cmd.acceptEphemeral || overwriteEphemeral ? "" : `
case "\${c##*/}" in ocx-child*) printf '%s\\n' 'ocx-fanout:child-ocx-ephemeral' >&2; exit 121;; esac`;
// Only a pinned sync that carries a restart asks for this, so the plain sync's stderr stays exact.
const kind = cmd.acceptEphemeral && cmd.reportSelectedKind ? `
case "\${c##*/}" in ocx-child*) printf '%s\\n' 'ocx-fanout:selected-kind:ocx-child' >&2;; esac` : "";
const entry = cmd.reportEntry ? `
if [ -n "$ocx_entry" ]; then printf '%s\\n' 'ocx-fanout:entry:pair' >&2; else printf '%s\\n' 'ocx-fanout:entry:binary' >&2; fi` : "";
// Seconds resolution is enough for a 120 s window; a date(1) that prints nothing numeric prints no marker.
const clock = cmd.reportClock ? `
now=$(date +%s 2>/dev/null); case "$now" in ''|*[!0-9]*) ;; *) printf 'ocx-fanout:child-now:%s000\\n' "$now" >&2;; esac` : "";
return `export PATH="$PATH:$HOME/.bun/bin:$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin"
export OCX_NO_DESKTOP_HANDOFF=1
case "$(uname -s 2>/dev/null)" in Windows*|MSYS*|MINGW*|CYGWIN*) exit ${REMOTE_PLATFORM_UNSUPPORTED};; esac
umask 077
dir=$(mktemp -d "\${TMPDIR:-/tmp}/ocx-fanout.XXXXXXXX") || exit 127
tmp=$dir/version; ready=$dir/ready
trap 'rm -rf "$dir"' EXIT HUP INT TERM
launcher=${cmd.launcher}
node_ok() {
( ulimit -c 0; exec "$1" --version ) >/dev/null 2>&1 & np=$!
( sleep 10 & ntimer=$!; trap 'kill "$ntimer" 2>/dev/null; wait "$ntimer" 2>/dev/null; exit' TERM HUP INT; : > "$ready"; wait "$ntimer" 2>/dev/null; kill -9 "$np" 2>/dev/null ) >/dev/null 2>&1 & nwd=$!
while [ ! -f "$ready" ]; do kill -0 "$nwd" 2>/dev/null || break; sleep 0.01 >/dev/null 2>&1; done
{ wait "$np"; nstatus=$?; } 2>/dev/null
kill "$nwd" 2>/dev/null; wait "$nwd" 2>/dev/null; rm -f "$ready"
[ "$nstatus" -eq 0 ]
}
find_launcher_node() {
node_bin=
case "$1" in */lib/node_modules/@bitkyc08/opencodex)
n=\${1%/lib/node_modules/@bitkyc08/opencodex}/bin/node
if [ -x "$n" ] && node_ok "$n"; then node_bin=$n; return 0; fi;; esac
n=$(command -v node 2>/dev/null) && [ -x "$n" ] && node_ok "$n" && node_bin=$n
return 0
}
try_ocx() {
c=$1; shift
[ -x "$c" ] || return${overwriteEphemeral}
( ulimit -c 0; ulimit -f 1; exec "$c" \${ocx_entry:+"$ocx_entry"} --version ) >"$tmp" 2>/dev/null & vp=$!
( sleep 10 & timer=$!; trap 'kill "$timer" 2>/dev/null; wait "$timer" 2>/dev/null; exit' TERM HUP INT; : > "$ready"; wait "$timer" 2>/dev/null; kill -9 "$vp" 2>/dev/null ) >/dev/null 2>&1 & watchdog=$!
while [ ! -f "$ready" ]; do kill -0 "$watchdog" 2>/dev/null || break; sleep 0.01 >/dev/null 2>&1; done
{ wait "$vp"; status=$?; } 2>/dev/null
kill "$watchdog" 2>/dev/null; wait "$watchdog" 2>/dev/null; rm -f "$ready"
[ "$status" -eq 0 ] || return
bytes=$(wc -c < "$tmp" 2>/dev/null) || return
[ "$bytes" -le 256 ] 2>/dev/null || return
version=$(cat "$tmp"); version=\${version#opencodex }
printf '%s\\n' "$version" | awk '
function idlist(s,pre, n,a,i) {
n=split(s,a,/\\./); if (!n) return 0;
for(i=1;i<=n;i++) if(a[i]=="" || a[i] !~ /^[0-9A-Za-z-]+$/ || (pre && a[i] ~ /^[0-9]+$/ && length(a[i])>1 && substr(a[i],1,1)=="0")) return 0;
return 1
}
function cmp(a,b) { if(length(a)!=length(b)) return length(a)>length(b)?1:-1; return ("x" a)==("x" b)?0:(("x" a)>("x" b)?1:-1) }
NR==1 {
v=$0; if(length(v)>128) { result=2; next }
plus=index(v,"+"); if(plus) { build=substr(v,plus+1); v=substr(v,1,plus-1); if(!idlist(build,0)) {result=2; next} }
dash=index(v,"-"); if(dash) { pre=substr(v,dash+1); v=substr(v,1,dash-1); if(!idlist(pre,1)) {result=2; next} }
if(split(v,a,/\\./)!=3) { result=2; next }
for(i=1;i<=3;i++) if(a[i] !~ /^(0|[1-9][0-9]*)$/) { result=2; next }
c=cmp(a[1],"${major}"); if(!c)c=cmp(a[2],"${minor}"); if(!c)c=cmp(a[3],"${patch}"); if(c<0 || (!c && dash))result=1
}
NR>1 {result=2}
END {exit result}
' 2>/dev/null
status=$?
if [ "$status" -eq 1 ]; then printf '%s\\n' 'ocx-fanout:${cmd.lacksMarker}' >&2; exit 121; fi
if [ "$status" -ne 0 ]; then printf '%s\\n' 'ocx-fanout:child-ocx-version-unknown' >&2; exit 121; fi${ephemeral}
root=; [ -n "$ocx_entry" ] && root=\${ocx_entry%/src/cli/index.ts}
case "$root" in */node_modules/*) [ -f "$root/bin/ocx.mjs" ] || root=;; *) root=;; esac
node_bin=; if [ -n "$root" ] && [ "$launcher" != none ]; then find_launcher_node "$root"; fi
rm -rf "$dir"; trap - EXIT HUP INT TERM
printf 'ocx-fanout:selected:%s\\n' "$version" >&2${kind}${entry}${clock}
if [ -n "$root" ] && [ "$launcher" = report ]; then
if [ -n "$node_bin" ]; then printf '%s\\n' 'ocx-fanout:launcher:available' >&2
else printf '%s\\n' 'ocx-fanout:launcher:unavailable' >&2; fi
fi
if [ -n "$root" ] && [ "$launcher" = apply ]; then
[ -n "$node_bin" ] || { printf '%s\\n' 'ocx-fanout:child-node-unavailable' >&2; exit 121; }
printf '%s\\n' 'ocx-fanout:launcher:exec' >&2
printf '%s\\n' 'ocx-fanout:stdout-begin'
unset OCX_UPDATE_ORCHESTRATED_CHILD
exec "$node_bin" "$root/bin/ocx.mjs" "$@"
fi
printf '%s\\n' 'ocx-fanout:stdout-begin'
exec "$c" \${ocx_entry:+"$ocx_entry"} "$@"
}
${REMOTE_OCX_CANDIDATES}
exit ${REMOTE_COMMAND_NOT_FOUND}`;
}
export function remoteGatedOcxArgv(cmd: GatedOcxCommand, platform: "posix" | "windows" = "posix"): string[] {
const versionParts = assertGated(cmd);
if (platform === "windows") {
// A dropped channel kills the orchestrating parent with the Job, so no Windows apply is ever built (D20).
// Only a plan is ever built for Windows: an update spelled without --plan (or a future mutating flag) is refused.
if (cmd.args[0] === "update" && (!cmd.args.includes("--plan") || cmd.args.includes("--yes"))) throw new LinkSshArgumentError("unsupported:windows-apply");
try {
return windowsGatedOcxArgv({ ...cmd, versionParts });
} catch (error) {
if (error instanceof PowerShellCommandTooLongError) throw new LinkSshArgumentError("windows-command-too-long");
throw error;
}
}
return ["sh", "-c", remoteGatedScript(cmd), "ocx", ...cmd.args];
}
export type ChildRestartRequest = "app-server" | "codex";
export interface PinnedSyncOptions { restart?: ChildRestartRequest; overwrite?: boolean; overwriteClient?: RouteClientId }
const RESTART_FLAG: Readonly<Record<ChildRestartRequest, string>> = { "app-server": "--restart-app-server-only", codex: "--restart-codex" };
export function remotePinnedSyncArgv(linkId: string, platform: "posix" | "windows" = "posix", opts: PinnedSyncOptions | boolean = {}, overwriteClient?: RouteClientId): string[] {
if (typeof opts === "boolean") opts = { overwrite: opts, ...(overwriteClient !== undefined ? { overwriteClient } : {}) };
else if (overwriteClient !== undefined) throw new LinkSshArgumentError("invalid overwrite client");
const overwrite = opts.overwrite === true;
overwriteClient = opts.overwriteClient;
if (overwriteClient !== undefined && (!overwrite || !isRouteClientId(overwriteClient))) throw new LinkSshArgumentError("invalid overwrite client");
if (!LINK_ID_PATTERN.test(linkId)) throw new LinkSshArgumentError("invalid link id");
if (opts.restart !== undefined && !Object.hasOwn(RESTART_FLAG, opts.restart)) throw new LinkSshArgumentError("invalid restart request");
// D20: the Home never sends a restart to a Windows Child.
if (opts.restart !== undefined && platform === "windows") throw new LinkSshArgumentError("unsupported:windows-restart");
const restart = opts.restart === undefined ? [] : [RESTART_FLAG[opts.restart]];
if (overwrite && platform === "windows") {
try { return windowsOverwriteSyncArgv(linkId, true, overwriteClient); }
catch (error) { if (error instanceof PowerShellCommandTooLongError) throw new LinkSshArgumentError("windows-command-too-long"); throw error; }
}
return remoteGatedOcxArgv({ minVersion: overwrite ? "2.100.0" : "2.93.0", lacksMarker: overwrite ? "child-ocx-lacks-overwrite" : "child-ocx-lacks-expect-link", acceptEphemeral: !overwrite,
reportEntry: false, reportClock: false, reportSelectedKind: restart.length > 0, launcher: "none",
args: ["sync", "--expect-link", linkId, "--json", ...restart, ...(overwrite ? ["--overwrite-conflict"] : []), ...(overwriteClient ? ["--overwrite-client", overwriteClient] : [])] }, platform);
}