root: string;

env: Record<string, string | undefined>;

cleanup(): void;

baseEnv: Record<string, string | undefined> = process.env,

): IsolatedTestEnvironment {

const hostTemp = tmpdir();

const recovery = recoverStaleTestTempArtifactsOnce({ tempRoot: hostTemp });

if (recovery && (recovery.removed > 0 || recovery.errors > 0 || recovery.truncated)) {

console.warn(

`[test] stale TEMP recovery removed ${recovery.removed} OpenCodex test root(s)`

+ (recovery.errors > 0 ? `; ${recovery.errors} could not be reclaimed` : "")

+ (recovery.truncated ? "; the bounded scan will continue on a later run" : "")

+ ".",

);

}

const root = mkdtempSync(join(hostTemp, "opencodex-test-"));

const opencodexHome = join(root, ".opencodex");

const codexHome = join(root, ".codex");

const containedTemp = createContainedTestTemp(root);

mkdirSync(opencodexHome, { recursive: true });

mkdirSync(codexHome, { recursive: true });

if (process.platform === "win32") {

// A Windows sandbox has to look like a real profile, because the known-folder APIs

// resolve relative to USERPROFILE and .NET returns an EMPTY STRING — not an error —

// when the folder it computes does not exist. `resolveWindowsRuntimeRoot` asks

// PowerShell for `GetFolderPath(LocalApplicationData)`, so without these directories

// every Codex coordinator lookup refuses with "Windows effective-account lookup

// returned an empty value" and each refusal surfaces as an unrelated assertion in

// whichever suite happened to touch a Codex home.

mkdirSync(join(root, "AppData", "Local"), { recursive: true });

mkdirSync(join(root, "AppData", "Roaming"), { recursive: true });

}

writeTestTempOwner(root, baseEnv[TEST_RUN_ID_ENV]);

const inherited = { ...baseEnv };

for (const name of LIVE_INSTALL_CREDENTIAL_ENV) delete inherited[name];

return {

root,

env: {

...inherited,

// Captured BEFORE HOME is overwritten: once the child starts with a rewritten

// HOME, `homedir()` returns the sandbox, so this hand-off is the only way the

// real-home write guard can still know which path to protect.

// (devlog 260730_codex_rs_upstream_v2_live_handoff/070.)

OCX_REAL_HOME: baseEnv.OCX_REAL_HOME ?? homedir(),

// Pin git's global config to the developer's real one before HOME moves.

//

// git resolves ~/.gitconfig from HOME, so a sandboxed HOME makes it invisible.

// That silently drops `safe.directory`, and on a checkout whose directory owner

// differs from the running account -- ordinary on Windows when a tool or

// installer created the tree -- every `git` call a test makes then fails with

// "detected dubious ownership". The test reads that as "this is not a git

// repository" and asserts against a fallback, which looks like a product bug in

// whichever adapter collected the metadata. Naming the file keeps the sandbox

// (git still writes nothing here) while leaving git's own trust decisions intact.

GIT_CONFIG_GLOBAL: baseEnv.GIT_CONFIG_GLOBAL ?? join(homedir(), ".gitconfig"),

// Pin Bun's runtime transpiler cache for the same reason. Bun keeps it under the home

// directory (macOS: ~/Library/Caches/bun/@t@), so a sandboxed HOME/USERPROFILE handed every

// batch, and every fixture that gives its child its own HOME, an empty cache: the first child

// re-transpiled each large module (73 src files are over the 50 KB cache threshold). On a busy

// Windows shard that first child took 10-45 s where later ones took 2-5 s, failing whichever

// timed case happened to spawn it. The cache holds transpiled source only, so sharing it keeps

// the sandbox. An explicit value, including "" or "0" to disable it, is kept as given.

BUN_RUNTIME_TRANSPILER_CACHE_PATH: baseEnv.BUN_RUNTIME_TRANSPILER_CACHE_PATH

?? join(hostTemp, "ocx-test-bun-transpiler-cache"),

HOME: root,

USERPROFILE: root,

OPENCODEX_HOME: opencodexHome,

CODEX_HOME: codexHome,

TEMP: containedTemp,

TMP: containedTemp,

TMPDIR: containedTemp,

},

cleanup() {

removeTestTempTree(root);

},

};

const delimiterIndex = requested.indexOf("--");

const wrapperArgs = delimiterIndex === -1 ? requested : requested.slice(0, delimiterIndex);

return wrapperArgs.some(arg => arg === name || arg.startsWith(`${name}=`));

comparisonRef: string;

comparisonCommit: string;

changedFiles: string[];

const delimiterIndex = requested.indexOf("--");

const wrapperArgs = delimiterIndex === -1 ? requested : requested.slice(0, delimiterIndex);

const changedArg = wrapperArgs.find(arg => arg === "--changed" || arg.startsWith("--changed="));

if (!changedArg) return null;

if (changedArg === "--changed" || changedArg === "--changed=") {

throw new Error(

"[test] changed mode requires an explicit comparison ref; use --changed=<ref> so the selection can be validated.",

);

}

return changedArg.slice("--changed=".length);

ref: string,

cwd: string,

env: Record<string, string | undefined>,

): boolean {

const result = Bun.spawnSync(["git", "rev-parse", "--verify", "--quiet", `${ref}^{commit}`], {

cwd,

env,

stdout: "ignore",

stderr: "ignore",

});

return result.exitCode === 0;

args: string[],

cwd: string,

env: Record<string, string | undefined>,

): string {

const result = Bun.spawnSync(["git", ...args], {

cwd,

env,

stdout: "pipe",

stderr: "pipe",

});

if (result.exitCode !== 0) {

const detail = decodeOutput(result.stderr).trim() || `exit ${result.exitCode ?? "unknown"}`;

throw new Error(`[test] git ${args[0]} failed while validating changed mode: ${detail}`);

}

return decodeOutput(result.stdout);

requested: string[],

cwd: string = process.cwd(),

env: Record<string, string | undefined> = process.env,

): ChangedRunPreflight | null {

const requestedComparisonRef = changedComparisonRef(requested);

if (!requestedComparisonRef) return null;

if (requestedComparisonRef.startsWith("-")) {

throw new Error(

`[test] --changed comparison ref ${JSON.stringify(requestedComparisonRef)} is invalid.`,

);

}

const comparisonRef = requestedComparisonRef === "dev"

? selectChangedComparisonRef(ref => gitRefExists(ref, cwd, env))

: requestedComparisonRef;

if (!comparisonRef) {

throw new Error(

`[test] --changed=dev could not resolve a comparison ref; none of ${changedComparisonRefs.join(", ")} exists.`,

);

}

if (!gitRefExists(comparisonRef, cwd, env)) {

throw new Error(

`[test] --changed comparison ref ${JSON.stringify(comparisonRef)} does not resolve to a commit.`,

);

}

const comparisonCommit = gitOutput(["merge-base", "HEAD", comparisonRef], cwd, env).trim();

if (!comparisonCommit) {

throw new Error(

`[test] --changed comparison ref ${JSON.stringify(comparisonRef)} has no merge base with HEAD.`,

);

}

const diff = gitOutput(["diff", "--name-only", comparisonCommit, "--"], cwd, env);

const changedFiles = [...new Set(diff.split("\n").filter(Boolean))];

return { comparisonRef, comparisonCommit, changedFiles };

preflight: ChangedRunPreflight,

output: string,

): string | null {

if (preflight.changedFiles.length === 0) return null;

const summary = output

.replace(/\u001B\[[0-?]*[ -/]*[@-~]/g, "")

.match(/Ran\s+(\d+)\s+tests?\s+across\s+(\d+)\s+files?\b/i);

if (!summary) {

return `[test] could not validate --changed=${preflight.comparisonCommit} (${preflight.comparisonRef} merge base): Bun did not emit a recognizable selection summary for a diff containing ${preflight.changedFiles.length} changed file(s).`;

}

if (Number(summary[1]) !== 0 || Number(summary[2]) !== 0) return null;

return `[test] --changed=${preflight.comparisonCommit} (${preflight.comparisonRef} merge base) selected 0 tests across 0 files, but the diff contains ${preflight.changedFiles.length} changed file(s). Bun follows only the parsed module graph; run the relevant focused tests for subprocess, read-as-data, or golden-file dependencies, or run the full suite.`;

const delimiterIndex = requested.indexOf("--");

const wrapperArgs = delimiterIndex === -1 ? requested : requested.slice(0, delimiterIndex);

const passedThrough = delimiterIndex === -1 ? [] : requested.slice(delimiterIndex + 1);

if (passedThrough.length > 0) return false;

if (hasCliFlag(requested, "--changed")) return false;

for (let index = 0; index < wrapperArgs.length; index++) {

const arg = wrapperArgs[index];

if (arg === "-" || !arg.startsWith("-")) return false;

if (!arg.includes("=") && BUN_TEST_OPTIONS_REQUIRING_VALUES.has(arg)) index++;

}

return true;

requested: string[],

comparisonCommit?: string,

): string[] {

const delimiterIndex = requested.indexOf("--");

const effectiveRequested = comparisonCommit

? requested.map((arg, index) => (

(delimiterIndex === -1 || index < delimiterIndex)

&& (arg === "--changed" || arg.startsWith("--changed="))

? "--changed=" + comparisonCommit

: arg

))

: requested;

const args = ["--isolate"];

if (!hasCliFlag(effectiveRequested, "--parallel")) {

args.push(`--parallel=${DEFAULT_TEST_PARALLELISM}`);

}

args.push(...effectiveRequested);

if (isFullSuiteRun(effectiveRequested)) args.push("./tests/");

return args;

label: string;

args: string[];

timeoutMs: number;

requested: string[], comparisonCommit?: string,

env: Record<string, string | undefined> = process.env,

): BunTestLane[] {

const rawTimeout = env.OCX_TEST_MAIN_TIMEOUT_MS;

const mainTimeout = rawTimeout === undefined ? 900_000 : Number(rawTimeout);

if (rawTimeout !== undefined && (!/^\d+$/.test(rawTimeout)

|| !Number.isSafeInteger(mainTimeout) || mainTimeout < 60_000 || mainTimeout > 3_600_000)) {

throw new Error("OCX_TEST_MAIN_TIMEOUT_MS must be an integer between 60000 and 3600000");

}

if (!canUseSerialLanes(requested)) {

return [{ label: "suite", args: resolveBunTestArgs(requested, comparisonCommit), timeoutMs: mainTimeout }];

}

const mainArgs = resolveBunTestArgs(requested, comparisonCommit);

const rootIndex = mainArgs.lastIndexOf("./tests/");

const ignores = SERIAL_FULL_SUITE_FILES.flatMap(file => ["--path-ignore-patterns", `**/${basename(file)}`]);

mainArgs.splice(rootIndex === -1 ? mainArgs.length : rootIndex, 0, ...ignores);

const serialRequested = withoutParallelOverride(requested);

return [

{ label: "parallel suite", args: mainArgs, timeoutMs: mainTimeout },

...SERIAL_FULL_SUITE_FILES.map(file => ({

label: basename(file),

args: resolveBunTestArgs(["--parallel=1", ...serialRequested, `./tests/${file}`]),

timeoutMs: SERIAL_LANE_TIMEOUT_MS[basename(file) as SerialLaneBasename] ?? 3 * 60 * 1000,

})),

];

return new Promise((resolve, reject) => {

const timer = setTimeout(() => resolve(null), timeoutMs);

promise.then(

value => {

clearTimeout(timer);

resolve(value);

},

error => {

clearTimeout(timer);

reject(error);

},

);

});

stdout: ReadableStream<Uint8Array>,

stderr: ReadableStream<Uint8Array>,

) {

const collect = (stream: ReadableStream<Uint8Array>) => {

const reader = stream.getReader();

const decoder = new TextDecoder();

let text = "";

let reading = true;

let complete = false;

const done = (async () => {

try {

while (reading) {

const chunk = await reader.read();

if (!reading) break;

if (chunk.done) {

complete = true;

break;

}

text += decoder.decode(chunk.value, { stream: true });

}

} catch {

// Retain the prefix without turning a pipe error into an unhandled rejection.

} finally {

if (reading) text += decoder.decode();

reading = false;

reader.releaseLock();

}

})();

return {

done,

snapshot: () => ({ text, complete }),

cancel() {

if (!reading) return;

reading = false;

text += decoder.decode();

// A descendant may own a pipe, or a stream's cancellation may never settle.

// Cancellation is best effort; neither it nor EOF may extend the drain bound.

void reader.cancel().catch(() => {});

},

};

};

const out = collect(stdout);

const err = collect(stderr);

return {

async finish(timeoutMs: number) {

const drained = await waitWithTimeout(Promise.all([out.done, err.done]), timeoutMs);

if (drained === null) {

out.cancel();

err.cancel();

}

const stdout = out.snapshot();

const stderr = err.snapshot();

return {

stdout: stdout.text,

stderr: stderr.text,

complete: drained !== null && stdout.complete && stderr.complete,

};

},

};

lane: BunTestLane,

runId: string,

inheritedLock: { lockPath: string; ownerToken: string } | undefined,

capture = false,

writers = {

stdout: (value: string) => { process.stdout.write(value); },

stderr: (value: string) => { process.stderr.write(value); },

},

): Promise<{ exitCode: number; output: string }> {

const isolated = createIsolatedTestEnvironment({

...process.env,

[TEST_RUN_ID_ENV]: runId,

[TEST_RUN_LOCK_PATH_ENV]: inheritedLock?.lockPath,

[TEST_RUN_LOCK_TOKEN_ENV]: inheritedLock?.ownerToken,

// Lanes run many files in parallel, so a test that shortened a PRODUCT timing budget

// (not its own test timeout) needs headroom for process startup on a busy machine.

// See tests/helpers/ci-watchdog.ts `isolationBudgetMs`.

OCX_TEST_FULL_SUITE: "1",

});

const startedAt = Date.now();

let interrupted: NodeJS.Signals | null = null;

const child = Bun.spawn([process.execPath, "test", ...lane.args], {

env: isolated.env,

stdin: "inherit",

stdout: capture ? "pipe" : "inherit",

stderr: capture ? "pipe" : "inherit",

});

const captured = capture ? captureTestOutput(child.stdout!, child.stderr!) : undefined;

const forward = (signal: NodeJS.Signals) => {

interrupted = signal;

try { child.kill(signal); } catch { /* child already exited */ }

};

const onInterrupt = () => forward("SIGINT");

const onTerminate = () => forward("SIGTERM");

process.once("SIGINT", onInterrupt);

process.once("SIGTERM", onTerminate);

const exited = child.exited;

try {

let exitCode = await waitWithTimeout(exited, lane.timeoutMs);

if (exitCode === null) {

console.error(`[test] ${lane.label} exceeded ${Math.round(lane.timeoutMs / 1000)}s; terminating pid ${child.pid}.`);

try { child.kill("SIGTERM"); } catch { /* child already exited */ }

const graceful = await waitWithTimeout(exited, 5_000);

if (graceful === null) {

try { child.kill("SIGKILL"); } catch { /* child already exited */ }

await waitWithTimeout(exited, 2_000);

}

}

// Process exit does not guarantee EOF when a descendant inherited the pipe.

const result = await captured?.finish(1_000);

const stdout = result?.stdout ?? "";

const stderr = result?.stderr ?? "";

if (stdout) writers.stdout(stdout);

if (stderr) writers.stderr(stderr);

const output = stdout + "\n" + stderr;

if (result && !result.complete) {

console.error("[test] captured output is incomplete; collected output is shown above.");

if (exitCode === 0) exitCode = 1;

}

if (exitCode === null) return { exitCode: 124, output };

if (interrupted === "SIGINT") return { exitCode: 130, output };

if (interrupted === "SIGTERM") return { exitCode: 143, output };

const seconds = ((Date.now() - startedAt) / 1000).toFixed(1);

console.warn(`[test] ${lane.label} finished in ${seconds}s (exit ${exitCode}).`);

return { exitCode, output };

} finally {

process.off("SIGINT", onInterrupt);

process.off("SIGTERM", onTerminate);

try {

isolated.cleanup();

} catch {

console.error("[test] deferred cleanup of one test root after Windows kept a handle open; a later run will retry it.");

}

}

cwd?: string;

exists?: (path: string) => boolean;

install?: (guiDir: string) => { ok: boolean; detail: string };

log?: (message: string) => void;

} = {}): { kind: "present" | "installed" | "absent" | "failed"; detail?: string } {

const cwd = io.cwd ?? process.cwd();

const exists = io.exists ?? existsSync;

const log = io.log ?? (message => console.warn(message));

const guiDir = join(cwd, "gui");

if (!exists(join(guiDir, "package.json"))) return { kind: "absent" };

if (exists(join(guiDir, "node_modules", "react", "package.json"))) return { kind: "present" };

log("[test] gui dependencies are missing or incomplete; installing them so tests importing gui/src can resolve React.");

const install = io.install ?? ((dir: string) => {

const result = Bun.spawnSync(["bun", "install", "--frozen-lockfile"], {

cwd: dir,

stdout: "pipe",

stderr: "pipe",

});

return {

ok: result.exitCode === 0,

detail: decodeOutput(result.stderr) || decodeOutput(result.stdout),

};

});

const outcome = install(guiDir);

if (outcome.ok) return { kind: "installed" };

return { kind: "failed", detail: outcome.detail };