@maiaos/node 0.1.0-canary.44938d4.manual.1

package/dist/session/testing/built-session-node.js

@@ -0,0 +1,715 @@
+import { spawn, spawnSync } from "node:child_process";
+import { access, copyFile, readdir, readFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { localNodeReadyRecordSchema, } from "@maiaos/protocol";
+import { connectLocalNode } from "@maiaos/sdk/node";
+import { Effect } from "effect";
+import * as Predicate from "effect/Predicate";
+import { build } from "esbuild";
+import { afterAll, afterEach, describe, it } from "vitest";
+import { embeddedNativeProcessHostDefines, validateNativeProcessHostReleaseIdentity, } from "../../runtime/process/resource/native-host-release-identity.js";
+import { appendBounded, createBoundedCapture, snapshotCapture, } from "./built-session-bounded-capture.js";
+import { runSupervisedCli, SupervisedCliFailure, } from "./built-session-cli-supervisor.js";
+import { BuiltSessionAuthorityFailure } from "./built-session-execution-failure.js";
+import { BUILT_SESSION_STRONG_PROVIDER_NAME, inspectBuiltSessionStrongProvider, } from "./built-session-execution-policy.js";
+import { assertOwnedBuiltSessionRoot, createOwnedBuiltSessionRoot, createOwnedTurnTestBinariesDirectory, disposeFinishedOwnedBuiltSessionRoots, disposeOwnedTurnTestBinaries, inspectOwnedBuiltSessionTemporary, removeOwnedBuiltSessionTemporary, trackOwnedBuiltSessionChild, } from "./built-session-temporary-lifecycle.js";
+const MAX_ARTIFACT_PATH_BYTES = 4096;
+const builtArtifactPath = (environmentKey, fallback) => {
+    const override = process.env[environmentKey];
+    if (override === undefined)
+        return fallback;
+    if (!isAbsolute(override) ||
+        Buffer.byteLength(override, "utf8") > MAX_ARTIFACT_PATH_BYTES) {
+        throw new TypeError(`The ${environmentKey} test artifact path is invalid.`);
+    }
+    return override;
+};
+export const BUILT_SESSION_NODE_BIN_PATH = builtArtifactPath("MAIA_BUILT_SESSION_NODE_BIN_PATH", fileURLToPath(new URL("../../../dist/bin/maia-node.mjs", import.meta.url)));
+export const BUILT_SESSION_CLI_BIN_PATH = builtArtifactPath("MAIA_BUILT_SESSION_CLI_BIN_PATH", fileURLToPath(new URL("../../../../../apps/cli/dist/bin/maia.mjs", import.meta.url)));
+export const BUILT_SESSION_OPERATION_DEADLINE_MS = 1500;
+export const BUILT_SESSION_FORCE_KILL_AFTER_MS = 200;
+export const BUILT_SESSION_STREAM_SETTLE_MS = 200;
+export const BUILT_SESSION_POST_KILL_WAIT_MS = 200;
+export const BUILT_SESSION_CLEANUP_DEADLINE_MS = 400;
+export const BUILT_SESSION_STARTUP_BOUND_MS = 2000;
+export const BUILT_SESSION_SHUTDOWN_SIGNAL_MS = 1600;
+export const BUILT_SESSION_SHUTDOWN_BOUND_MS = BUILT_SESSION_SHUTDOWN_SIGNAL_MS +
+    BUILT_SESSION_FORCE_KILL_AFTER_MS +
+    BUILT_SESSION_STREAM_SETTLE_MS;
+export const BUILT_SESSION_CLEANUP_BOUND_MS = 800;
+export const BUILT_SESSION_MAX_OUTPUT_BYTES = 64 * 1024;
+export const BUILT_SESSION_PROCESS_DEADLINE_MS = BUILT_SESSION_OPERATION_DEADLINE_MS;
+export const BUILT_SESSION_GIT_COMMAND_BOUND_MS = 8000;
+export const BUILT_SESSION_BARRIER_WAIT_BOUND_MS = 8000;
+export const BUILT_SESSION_SDK_CALL_BOUND_MS = BUILT_SESSION_OPERATION_DEADLINE_MS;
+export const BUILT_SESSION_GIT_REPOSITORY_COMMANDS = 5;
+export const BUILT_SESSION_IDLE_SESSION_CLI_CALLS = 2;
+const PROCESS_DEADLINE_MS = BUILT_SESSION_OPERATION_DEADLINE_MS;
+const PROCESS_MAX_OUTPUT_BYTES = BUILT_SESSION_MAX_OUTPUT_BYTES;
+export const BUILT_SESSION_CLI_BOUND_MS = BUILT_SESSION_OPERATION_DEADLINE_MS +
+    BUILT_SESSION_FORCE_KILL_AFTER_MS +
+    BUILT_SESSION_POST_KILL_WAIT_MS +
+    BUILT_SESSION_STREAM_SETTLE_MS;
+export const builtSessionTestBudgetMs = (counts) => {
+    const idleSessions = counts.idleSessions ?? 0;
+    return (counts.startups * BUILT_SESSION_STARTUP_BOUND_MS +
+        counts.shutdowns * BUILT_SESSION_SHUTDOWN_BOUND_MS +
+        (counts.cliCalls + idleSessions * BUILT_SESSION_IDLE_SESSION_CLI_CALLS) *
+            BUILT_SESSION_CLI_BOUND_MS +
+        ((counts.gitCommands ?? 0) +
+            idleSessions * BUILT_SESSION_GIT_REPOSITORY_COMMANDS) *
+            BUILT_SESSION_GIT_COMMAND_BOUND_MS +
+        (counts.barrierWaits ?? 0) * BUILT_SESSION_BARRIER_WAIT_BOUND_MS +
+        (counts.sdkCalls ?? 0) * BUILT_SESSION_SDK_CALL_BOUND_MS +
+        (counts.crashWaits ?? 0) * BUILT_SESSION_STREAM_SETTLE_MS +
+        (counts.extraMilliseconds ?? 0) +
+        BUILT_SESSION_CLEANUP_BOUND_MS);
+};
+export const withSessionTestDeadline = async (promise, milliseconds, label) => {
+    let timer;
+    const remaining = Math.max(0, milliseconds);
+    const deadline = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            reject(new Error(`${label} exceeded its deadline.`));
+        }, remaining);
+    });
+    try {
+        return await Promise.race([promise, deadline]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+};
+export const mapSequentially = async (items, mapper) => {
+    if (items.length === 0)
+        return [];
+    const [head, ...tail] = items;
+    if (head === undefined)
+        return [];
+    return [await mapper(head), ...(await mapSequentially(tail, mapper))];
+};
+const parseReadinessRecord = (line) => localNodeReadyRecordSchema.parse(JSON.parse(line));
+const normalizeReadinessError = (error) => error instanceof Error
+    ? error
+    : new Error("The node readiness record is invalid.");
+export const captureBuiltSessionPipe = (stream) => {
+    const capture = createBoundedCapture(PROCESS_MAX_OUTPUT_BYTES);
+    stream?.on("data", (chunk) => {
+        appendBounded(capture, chunk);
+    });
+    return () => snapshotCapture(capture);
+};
+export const attachBuiltSessionPipeDrain = (stream) => {
+    const capture = captureBuiltSessionPipe(stream);
+    return () => capture().text;
+};
+const SENSITIVE_DIAGNOSTIC_KEY = /^(authorization|bearer|credential|password|secret|token)$/iu;
+const DIAGNOSTIC_BEARER_PATTERN = /Bearer\s+\S+/giu;
+const DIAGNOSTIC_FIELD_PATTERN = /["']?(?:authorization|bearer|credential|password|secret|token)["']?\s*[:=][ \t]*["']?(?:\\.|[^\\"'}\s,])+["']?/giu;
+const DIAGNOSTIC_MULTILINE_PATTERN = /["']?(?:authorization|bearer|credential|password|secret|token)["']?\s*[:=][ \t]*\n[ \t]*\S+/giu;
+const DIAGNOSTIC_MARKER_PATTERN = /MAIA_TEST_SECRET_[A-Za-z0-9+/=_-]+/gu;
+const redactDiagnosticText = (text) => text
+    .replaceAll(DIAGNOSTIC_BEARER_PATTERN, "[redacted]")
+    .replaceAll(DIAGNOSTIC_FIELD_PATTERN, "[redacted]")
+    .replaceAll(DIAGNOSTIC_MULTILINE_PATTERN, "[redacted]")
+    .replaceAll(DIAGNOSTIC_MARKER_PATTERN, "[redacted]");
+const redactDiagnosticValue = (value, key) => {
+    if (key !== undefined && SENSITIVE_DIAGNOSTIC_KEY.test(key)) {
+        return "[redacted]";
+    }
+    if (typeof value === "string")
+        return redactDiagnosticText(value);
+    if (Array.isArray(value)) {
+        return value.map((entry) => redactDiagnosticValue(entry));
+    }
+    if (!Predicate.isObject(value))
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([entryKey, entryValue]) => [
+        entryKey,
+        redactDiagnosticValue(entryValue, entryKey),
+    ]));
+};
+export const redactBuiltSessionDiagnostic = (text) => {
+    const trimmed = text.trim();
+    if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+        try {
+            return JSON.stringify(redactDiagnosticValue(JSON.parse(trimmed)));
+        }
+        catch {
+            // Fall through to the text fallback for mixed diagnostic blobs.
+        }
+    }
+    return redactDiagnosticText(text);
+};
+const redactDiagnosticCause = (cause, seen = new Set()) => {
+    if (cause === undefined || cause === null || seen.has(cause))
+        return "";
+    seen.add(cause);
+    if (typeof cause === "string")
+        return redactBuiltSessionDiagnostic(cause);
+    if (cause instanceof Error) {
+        const nested = redactDiagnosticCause(cause.cause, seen);
+        return nested === ""
+            ? redactBuiltSessionDiagnostic(cause.message)
+            : `${redactBuiltSessionDiagnostic(cause.message)}\ncause:\n${nested}`;
+    }
+    if (Predicate.isObject(cause)) {
+        try {
+            return JSON.stringify(redactDiagnosticValue(cause));
+        }
+        catch {
+            return redactBuiltSessionDiagnostic(String(cause));
+        }
+    }
+    return redactBuiltSessionDiagnostic(String(cause));
+};
+export const describeBuiltSessionNode = (node) => {
+    const exit = node.child.exitCode;
+    const signal = node.child.signalCode;
+    const stderr = redactBuiltSessionDiagnostic(node.readStderr());
+    if (signal !== null) {
+        return `maia-node exited by ${signal}\n${stderr}`;
+    }
+    if (exit === null) {
+        return `maia-node still running\n${stderr}`;
+    }
+    return `maia-node exited ${String(exit)}\n${stderr}`;
+};
+const hasExited = (child) => child.exitCode !== null || child.signalCode !== null;
+const firstReadyLine = (readStdout) => {
+    const output = readStdout();
+    const newline = output.indexOf("\n");
+    return newline < 0 ? undefined : output.slice(0, newline);
+};
+const parseReadyLine = (readStdout) => {
+    const line = firstReadyLine(readStdout);
+    return line === undefined ? undefined : parseReadinessRecord(line);
+};
+const finishReadiness = (wait, error, record) => {
+    if (wait.settled)
+        return;
+    wait.settled = true;
+    wait.child.stdout?.off("data", wait.inspect);
+    wait.child.off("exit", wait.onExit);
+    wait.child.off("error", wait.onError);
+    if (error !== undefined) {
+        wait.reject(error);
+        return;
+    }
+    if (record === undefined) {
+        wait.reject(new Error("The node readiness record is missing."));
+        return;
+    }
+    wait.resolve(record);
+};
+const inspectReadiness = (source, wait) => {
+    try {
+        const record = parseReadyLine(source.readStdout);
+        if (record !== undefined)
+            finishReadiness(wait, undefined, record);
+    }
+    catch (error) {
+        finishReadiness(wait, normalizeReadinessError(error));
+    }
+};
+const assignReadinessHandlers = (source, wait) => {
+    wait.inspect = () => {
+        inspectReadiness(source, wait);
+    };
+    wait.onExit = (code) => {
+        finishReadiness(wait, new Error(`maia-node exited ${String(code)}: ${source.readStderr()}`));
+    };
+    wait.onError = (error) => {
+        finishReadiness(wait, new Error(`maia-node spawn failed: ${error.message}`));
+    };
+};
+const bindReadiness = (source, wait) => {
+    assignReadinessHandlers(source, wait);
+    if (hasExited(source.child)) {
+        wait.onExit(source.child.exitCode);
+        return;
+    }
+    source.child.stdout?.on("data", wait.inspect);
+    source.child.once("exit", wait.onExit);
+    source.child.once("error", wait.onError);
+    if (hasExited(source.child)) {
+        wait.onExit(source.child.exitCode);
+        return;
+    }
+    wait.inspect();
+};
+const createReadinessWait = (source, resolve, reject) => ({
+    child: source.child,
+    inspect() {
+        return;
+    },
+    onError() {
+        return;
+    },
+    onExit() {
+        return;
+    },
+    reject,
+    resolve,
+    settled: false,
+});
+const observeReadiness = (source) => {
+    let resolveRecord;
+    let rejectError;
+    const promise = new Promise((resolve, reject) => {
+        resolveRecord = resolve;
+        rejectError = reject;
+    });
+    const wait = createReadinessWait(source, resolveRecord, rejectError);
+    bindReadiness(source, wait);
+    return {
+        cancel: (reason) => {
+            finishReadiness(wait, reason);
+        },
+        promise,
+    };
+};
+export const waitForBuiltSessionReadiness = async (source) => {
+    const observed = observeReadiness(source);
+    try {
+        return await withSessionTestDeadline(observed.promise, source.deadlineMilliseconds ?? PROCESS_DEADLINE_MS, "session node readiness");
+    }
+    catch (error) {
+        observed.cancel(error instanceof Error
+            ? error
+            : new Error("session node readiness exceeded its deadline."));
+        throw error;
+    }
+};
+const TEST_CLI_ENTRY_PATH = fileURLToPath(new URL("../../../../../apps/cli/scripts/testing/turn-source-candidate-cli-entry.mjs", import.meta.url));
+const TEST_NODE_ENTRY_PATH = fileURLToPath(new URL("../../../scripts/testing/turn-source-candidate-node-entry.mjs", import.meta.url));
+const TURN_SOURCE_CANDIDATE_STARTED_SESSION_AUTHORITY_ID = "session_turn_source_candidate";
+let testExecutableBuild;
+const buildTestExecutable = async (entryPoint, outfile, define) => {
+    await build({
+        bundle: true,
+        ...(define === undefined ? {} : { define }),
+        entryPoints: [entryPoint],
+        format: "esm",
+        logLevel: "silent",
+        outfile,
+        platform: "node",
+        target: "node24",
+    });
+};
+export const buildTurnSourceCandidateTestCli = (outfile) => buildTestExecutable(TEST_CLI_ENTRY_PATH, outfile);
+const nativeProcessHostIdentity = async () => {
+    if (process.platform !== "darwin" || process.arch !== "arm64")
+        return;
+    const hostBasename = "maia-process-host-darwin-arm64";
+    const metadataPath = join(dirname(BUILT_SESSION_NODE_BIN_PATH), `${hostBasename}.build.json`);
+    const parsed = JSON.parse(await readFile(metadataPath, "utf8"));
+    if (!Predicate.isObject(parsed) ||
+        !Predicate.isObject(parsed.artifact) ||
+        typeof parsed.artifact.path !== "string" ||
+        typeof parsed.artifact.sha256 !== "string" ||
+        typeof parsed.protocolVersion !== "number" ||
+        typeof parsed.targetTriple !== "string") {
+        throw new TypeError("The built native process-host metadata is invalid.");
+    }
+    const identity = validateNativeProcessHostReleaseIdentity({
+        basename: basename(parsed.artifact.path),
+        protocolVersion: parsed.protocolVersion,
+        sha256: parsed.artifact.sha256,
+        targetTriple: parsed.targetTriple,
+    });
+    if (identity === undefined)
+        throw new TypeError("The built native process-host identity is missing.");
+    return identity;
+};
+const removeCreatedTemporaryQuietly = async (path) => {
+    try {
+        await removeOwnedBuiltSessionTemporary(path);
+    }
+    catch {
+        // Never mask the original start, readiness, or executable-build error.
+    }
+};
+const populateTurnSourceCandidateTestExecutables = async (root) => {
+    const cliBinPath = join(root, "maia-turn-test.mjs");
+    const nodeBinPath = join(root, "maia-node-turn-test.mjs");
+    const identity = await nativeProcessHostIdentity();
+    await Promise.all([
+        buildTurnSourceCandidateTestCli(cliBinPath),
+        buildTestExecutable(TEST_NODE_ENTRY_PATH, nodeBinPath, embeddedNativeProcessHostDefines(identity)),
+        ...(identity === undefined
+            ? []
+            : [
+                copyFile(join(dirname(BUILT_SESSION_NODE_BIN_PATH), identity.basename), join(root, identity.basename)),
+            ]),
+    ]);
+    return { cliBinPath, nodeBinPath, root };
+};
+const buildTurnSourceCandidateTestExecutables = async () => {
+    const root = await createOwnedTurnTestBinariesDirectory();
+    try {
+        return await populateTurnSourceCandidateTestExecutables(root);
+    }
+    catch (error) {
+        await removeCreatedTemporaryQuietly(root);
+        throw error;
+    }
+};
+const turnSourceCandidateTestExecutables = () => {
+    if (testExecutableBuild === undefined) {
+        testExecutableBuild = buildTurnSourceCandidateTestExecutables().then((value) => value, (error) => {
+            testExecutableBuild = undefined;
+            throw error;
+        });
+    }
+    return testExecutableBuild;
+};
+const rejectUnqualifiedBuiltSessionStart = () => {
+    const status = inspectBuiltSessionStrongProvider();
+    return Promise.reject(new BuiltSessionAuthorityFailure({
+        helpersCreated: 0,
+        message: status.message,
+        reason: "platform_unsupported",
+        targetsCreated: 0,
+    }));
+};
+const disabledMcpEnvironment = (names) => names === undefined
+    ? {}
+    : { ["MAIA_NODE_TEST_CODEX_DISABLED_MCP_SERVERS"]: names.join(",") };
+const codexExecutableEnvironment = (executable) => executable === undefined
+    ? {}
+    : {
+        ["MAIA_NODE_TEST_CODEX_EXECUTABLE"]: executable,
+        ["PATH"]: `${dirname(executable)}:/usr/bin:/bin:/usr/sbin:/sbin`,
+    };
+const makeCodexTestEnvironment = (options) => ({
+    ...(options.codexDriver === undefined
+        ? {}
+        : { ["MAIA_NODE_TEST_CODEX_DRIVER"]: options.codexDriver }),
+    ...codexExecutableEnvironment(options.codexExecutable),
+    ...(options.codexExecutableSha256 === undefined
+        ? {}
+        : {
+            ["MAIA_NODE_TEST_CODEX_EXECUTABLE_SHA256"]: options.codexExecutableSha256,
+        }),
+    ...(options.codexExecutableVersion === undefined
+        ? {}
+        : {
+            ["MAIA_NODE_TEST_CODEX_EXECUTABLE_VERSION"]: options.codexExecutableVersion,
+        }),
+    ...(options.codexCleanupBarrier
+        ? { ["MAIA_NODE_TEST_CODEX_CLEANUP_BARRIER"]: "1" }
+        : {}),
+    ...(options.codexWorkspaceWrite
+        ? { ["MAIA_NODE_TEST_CODEX_WORKSPACE_WRITE"]: "1" }
+        : {}),
+    ...disabledMcpEnvironment(options.codexDisabledMcpServers),
+});
+const makeSessionTestEnvironment = (options) => ({
+    ...(options.activationBarrier
+        ? { ["MAIA_NODE_TEST_SESSION_ACTIVATION_BARRIER"]: "1" }
+        : {}),
+    ...(options.dropMutationResponse
+        ? { ["MAIA_NODE_TEST_DROP_MUTATION_RESPONSE"]: "1" }
+        : {}),
+    ...(options.integrationAuthorization
+        ? { ["MAIA_NODE_TEST_INTEGRATION_AUTHORIZATION"]: "1" }
+        : {}),
+    ...(options.reconcileAdmissionBarrier
+        ? { ["MAIA_NODE_TEST_RECONCILE_BARRIER"]: "1" }
+        : {}),
+    ...(options.reconciliationBarrier
+        ? { ["MAIA_NODE_TEST_SESSION_RECONCILIATION_BARRIER"]: "1" }
+        : {}),
+    ...(options.turnBarrier
+        ? { ["MAIA_NODE_TEST_SESSION_TURN_BARRIER"]: "1" }
+        : {}),
+});
+const makeNodeEnvironment = (root, options) => ({
+    ...process.env,
+    ["MAIA_NODE_TEST_COOPERATIVE_PROCESS_FIXTURE"]: "1",
+    ["MAIA_NODE_TEST_MODE"]: "1",
+    ["MAIA_NODE_TEST_RUNTIME_ROOT"]: root,
+    ...makeCodexTestEnvironment(options),
+    ...makeSessionTestEnvironment(options),
+});
+const resolveRuntimeDirectory = async (root) => {
+    const entries = await readdir(root, { withFileTypes: true });
+    const candidates = entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => join(root, entry.name));
+    const inspected = await Promise.all(candidates.map(async (candidate) => {
+        try {
+            await access(join(candidate, "auth.token"));
+            return candidate;
+        }
+        catch {
+            return;
+        }
+    }));
+    const matches = inspected.filter((candidate) => candidate !== undefined);
+    if (matches.length !== 1 || matches[0] === undefined) {
+        throw new Error("Expected one isolated Maia runtime directory.");
+    }
+    return matches[0];
+};
+const spawnTurnSourceCandidateNode = (root, options, nodeBinPath) => {
+    assertOwnedBuiltSessionRoot(root);
+    const child = spawn(process.execPath, [nodeBinPath, "--desktop", "--json"], {
+        env: makeNodeEnvironment(root, options),
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    try {
+        trackOwnedBuiltSessionChild(root, child);
+    }
+    catch (error) {
+        killIfStillRunning(child);
+        throw error;
+    }
+    return {
+        child,
+        readStderr: attachBuiltSessionPipeDrain(child.stderr),
+    };
+};
+const waitForExit = (child) => {
+    if (child.exitCode !== null)
+        return Promise.resolve(child.exitCode);
+    return new Promise((resolve) => {
+        child.once("exit", resolve);
+    });
+};
+const rejectUnavailableBuiltSessionLifecycle = (action) => Promise.reject(new Error(`node ${action} cleanup remained unknown because strong built-session execution is unavailable.`));
+const isTurnSourceCandidateStarted = (node) => node.turnSourceCandidateStarted === true;
+const killIfStillRunning = (child) => {
+    if (child.exitCode === null && child.signalCode === null) {
+        child.kill("SIGKILL");
+    }
+};
+const awaitTurnSourceCandidateReadiness = async (child, readStderr) => {
+    try {
+        await waitForBuiltSessionReadiness({
+            child,
+            deadlineMilliseconds: BUILT_SESSION_STARTUP_BOUND_MS,
+            readStderr,
+            readStdout: attachBuiltSessionPipeDrain(child.stdout),
+        });
+    }
+    catch (error) {
+        killIfStillRunning(child);
+        try {
+            await withSessionTestDeadline(waitForExit(child), BUILT_SESSION_CLEANUP_BOUND_MS, "node start-failure exit");
+        }
+        catch {
+            // Fail closed later if the child still occupies the owned root.
+        }
+        throw error;
+    }
+};
+const startedTurnSourceCandidateNode = async (root, options, testExecutables) => {
+    const { child, readStderr } = spawnTurnSourceCandidateNode(root, options, testExecutables.nodeBinPath);
+    await awaitTurnSourceCandidateReadiness(child, readStderr);
+    return {
+        child,
+        cliBinPath: testExecutables.cliBinPath,
+        nodeBinPath: testExecutables.nodeBinPath,
+        readStderr,
+        root,
+        runtimeDirectory: await resolveRuntimeDirectory(root),
+        sessionAuthorityId: TURN_SOURCE_CANDIDATE_STARTED_SESSION_AUTHORITY_ID,
+        turnSourceCandidateStarted: true,
+    };
+};
+const startTurnSourceCandidateBuiltSession = async (options) => {
+    const createdRoot = options.root === undefined
+        ? await createOwnedBuiltSessionRoot()
+        : undefined;
+    const root = options.root ?? createdRoot;
+    if (root === undefined) {
+        throw new Error("Expected an isolated built-session root.");
+    }
+    try {
+        return await startedTurnSourceCandidateNode(root, options, await turnSourceCandidateTestExecutables());
+    }
+    catch (error) {
+        if (createdRoot !== undefined) {
+            await removeCreatedTemporaryQuietly(createdRoot);
+        }
+        throw error;
+    }
+};
+export const disposeTurnSourceCandidateTestExecutables = async () => {
+    const cached = testExecutableBuild;
+    if (cached === undefined)
+        return;
+    const resolved = await cached;
+    const owned = inspectOwnedBuiltSessionTemporary(resolved.root);
+    if (owned !== undefined && !owned.removed) {
+        await disposeOwnedTurnTestBinaries(resolved.root);
+    }
+    testExecutableBuild = undefined;
+};
+export const startBuiltSessionNode = (options = {}) => options.turnSourceCandidateTestEntries === true
+    ? startTurnSourceCandidateBuiltSession(options)
+    : rejectUnqualifiedBuiltSessionStart();
+const parkedTurnSourceCandidateNode = async (options) => {
+    const testExecutables = await turnSourceCandidateTestExecutables();
+    const { child, readStderr } = spawnTurnSourceCandidateNode(options.root, {
+        ...options,
+        reconcileAdmissionBarrier: true,
+    }, testExecutables.nodeBinPath);
+    return {
+        child,
+        cliBinPath: testExecutables.cliBinPath,
+        nodeBinPath: testExecutables.nodeBinPath,
+        readStderr,
+        root: options.root,
+        runtimeDirectory: options.runtimeDirectory,
+        sessionAuthorityId: TURN_SOURCE_CANDIDATE_STARTED_SESSION_AUTHORITY_ID,
+        turnSourceCandidateStarted: true,
+    };
+};
+export const startParkedBuiltSessionNode = (options) => parkedTurnSourceCandidateNode(options);
+export const crashBuiltSessionNode = (node) => {
+    if (!isTurnSourceCandidateStarted(node)) {
+        return rejectUnavailableBuiltSessionLifecycle("crash");
+    }
+    node.child.kill("SIGKILL");
+    return withSessionTestDeadline(waitForExit(node.child), BUILT_SESSION_CLEANUP_BOUND_MS, "node crash");
+};
+const sessionCliEnvironment = (node) => ({
+    ...process.env,
+    ["MAIA_CLI_TEST_MODE"]: "1",
+    ["MAIA_CLI_TEST_RUNTIME_ROOT"]: node.root,
+});
+const supervisedCliErrorMessage = (node, cause) => {
+    const cleanup = redactDiagnosticCause(cause.cleanupCause);
+    const nested = redactDiagnosticCause(cause.cause);
+    const suffix = [
+        cleanup === "" ? "" : `\ncleanup cause:\n${cleanup}`,
+        nested === "" ? "" : `\ncause:\n${nested}`,
+    ].join("");
+    return redactBuiltSessionDiagnostic(`${cause.reason}: ${cause.message}\ncli stdout:\n${cause.stdout}\ncli stderr:\n${cause.stderr}${suffix}\n${describeBuiltSessionNode(node)}`);
+};
+const toCliError = (node, cause) => {
+    if (cause instanceof SupervisedCliFailure) {
+        return new Error(supervisedCliErrorMessage(node, cause));
+    }
+    const message = cause instanceof Error ? cause.message : String(cause);
+    if (/interrupt/i.test(message)) {
+        return new Error(redactBuiltSessionDiagnostic(`cancelled: The built CLI was cancelled.\n${describeBuiltSessionNode(node)}`));
+    }
+    if (cause instanceof Error) {
+        const nested = redactDiagnosticCause(cause.cause);
+        return new Error(redactBuiltSessionDiagnostic(nested === "" ? cause.message : `${cause.message}\ncause:\n${nested}`));
+    }
+    return new Error("The built CLI failed.");
+};
+const sessionCliRequest = (node, cliArguments, options) => ({
+    abortSignal: options.signal,
+    cliArguments: options.programPath === undefined
+        ? [node.cliBinPath, ...cliArguments]
+        : cliArguments,
+    deadlineMilliseconds: options.deadlineMilliseconds ?? PROCESS_DEADLINE_MS,
+    environment: sessionCliEnvironment(node),
+    forceKillAfterMilliseconds: BUILT_SESSION_FORCE_KILL_AFTER_MS,
+    maxOutputBytes: PROCESS_MAX_OUTPUT_BYTES,
+    postKillWaitMilliseconds: BUILT_SESSION_POST_KILL_WAIT_MS,
+    program: options.programPath ?? process.execPath,
+    rootPath: node.root,
+    sessionAuthorityId: node.sessionAuthorityId,
+    stdin: options.input,
+    streamSettleMilliseconds: BUILT_SESSION_STREAM_SETTLE_MS,
+});
+const runDirectTurnSourceCandidateCli = (node, cliArguments, options = {}) => {
+    const program = options.programPath ?? process.execPath;
+    const argv = options.programPath === undefined
+        ? [node.cliBinPath, ...cliArguments]
+        : [...cliArguments];
+    const output = spawnSync(program, argv, {
+        encoding: "utf8",
+        env: sessionCliEnvironment(node),
+        maxBuffer: PROCESS_MAX_OUTPUT_BYTES,
+        ...(options.input === undefined ? {} : { input: options.input }),
+        timeout: options.deadlineMilliseconds ?? PROCESS_DEADLINE_MS,
+    });
+    if (output.error !== undefined || output.signal !== null) {
+        throw (output.error ??
+            new Error(`The built CLI exited by ${String(output.signal)}.`));
+    }
+    return {
+        code: output.status,
+        stderr: output.stderr,
+        stdout: output.stdout,
+    };
+};
+const runSessionCliPromise = (node, cliArguments, options = {}) => {
+    if (isTurnSourceCandidateStarted(node)) {
+        return Promise.resolve(runDirectTurnSourceCandidateCli(node, cliArguments, options));
+    }
+    return Effect.runPromise(runSupervisedCli(sessionCliRequest(node, cliArguments, options))).then((output) => output, (error) => {
+        throw toCliError(node, error);
+    });
+};
+export const runBuiltSessionCliWithDeadline = (node, arguments_, options) => runSessionCliPromise(node, arguments_, options);
+export const runBuiltSessionCliAsync = (node, arguments_, input) => runSessionCliPromise(node, arguments_, { input });
+export const runBuiltSessionCli = (node, arguments_, input) => runBuiltSessionCliAsync(node, arguments_, input);
+export const parseBuiltSessionResult = (output) => {
+    const envelope = JSON.parse(output.trim());
+    if (!Predicate.isObject(envelope) || !Predicate.isObject(envelope.result)) {
+        throw new TypeError("The built CLI result envelope is invalid.");
+    }
+    return envelope.result.result;
+};
+export const shutdownBuiltSessionNode = async (node) => {
+    if (!isTurnSourceCandidateStarted(node)) {
+        return rejectUnavailableBuiltSessionLifecycle("exit");
+    }
+    const connection = await connectLocalNode({
+        profile: "default",
+        runtimeRootOverride: node.root,
+    });
+    await connection.client.shutdown({ messageId: "session_test_shutdown" });
+    return withSessionTestDeadline(waitForExit(node.child), BUILT_SESSION_SHUTDOWN_BOUND_MS, "node exit");
+};
+export const assertUnqualifiedBuiltSessionStart = async () => {
+    try {
+        await startBuiltSessionNode();
+    }
+    catch (error) {
+        if (!(error instanceof BuiltSessionAuthorityFailure))
+            throw error;
+        if (error.reason !== "platform_unsupported")
+            throw error;
+        if (error.helpersCreated !== 0 || error.targetsCreated !== 0) {
+            throw new Error("An unqualified start created a helper or target.");
+        }
+        return;
+    }
+    throw new Error("Expected platform_unsupported before target creation.");
+};
+export const describeStrongBuiltSession = (name, suite) => {
+    const status = inspectBuiltSessionStrongProvider();
+    describe(`${name} [unqualified ${status.platform}]`, () => {
+        it(`returns platform_unsupported before helper or target (${BUILT_SESSION_STRONG_PROVIDER_NAME} unavailable)`, async () => {
+            await assertUnqualifiedBuiltSessionStart();
+        });
+    });
+    describe.skipIf(!status.available)(`${name} [requires ${BUILT_SESSION_STRONG_PROVIDER_NAME}]`, suite);
+};
+// Identity-validated test-entry suites. Does not consult
+// linux-delegated-cgroup-v2 or unskip ordinary-binary suites.
+export const describeTurnSourceCandidateBuiltSession = (name, suite) => {
+    describe(`${name} [identity-validated turn-source-candidate test entries]`, () => {
+        afterEach(disposeFinishedOwnedBuiltSessionRoots);
+        afterAll(async () => {
+            await disposeTurnSourceCandidateTestExecutables();
+            await disposeFinishedOwnedBuiltSessionRoots();
+        });
+        suite();
+    });
+};
+export { decodeBoundedUtf8, utf8ValidPrefixLength, } from "./built-session-bounded-capture.js";
+export { assertOwnedBuiltSessionRoot, BuiltSessionTemporaryLifecycleFailure, createOwnedBuiltSessionRoot, createOwnedBuiltSessionRuntime, createOwnedTurnTestBinariesDirectory, disposeFinishedOwnedBuiltSessionRoots, disposeFinishedOwnedBuiltSessionTemporaries, inspectOwnedBuiltSessionTemporary, isBuiltSessionTemporaryName, listBuiltSessionTemporaryOccupants, listOwnedBuiltSessionTemporaries, releaseOwnedBuiltSessionTemporary, removeOwnedBuiltSessionTemporary, retainOwnedBuiltSessionTemporary, trackOwnedBuiltSessionChild, } from "./built-session-temporary-lifecycle.js";
+//# sourceMappingURL=built-session-node.js.map