@loucompanion/forge-bridge 0.1.3-dev.b3bce6ba65a6 → 0.1.3-dev.ba293ccf876b

package/dist/cli/local-config.js

@@ -45,6 +45,15 @@ export function applyLocalConfigDefaults(config, local) {
         deviceName: process.env.FORGE_DEVICE_NAME ?? local.deviceName ?? config.deviceName,
         defaultRepoRoot: process.env.FORGE_REPO_ROOT ?? local.defaultRepoRoot ?? config.defaultRepoRoot,
         cleanupWorktrees: local.cleanupWorktrees ?? config.cleanupWorktrees,
+        dockerEnabled: process.env.FORGE_DOCKER_SANDBOX === undefined
+            ? local.dockerEnabled ?? config.dockerEnabled
+            : config.dockerEnabled,
+        dockerDesktopRecoveryEnabled: process.env.FORGE_DOCKER_DESKTOP_AUTO_RECOVERY === undefined
+            ? local.dockerDesktopRecoveryEnabled ?? config.dockerDesktopRecoveryEnabled
+            : config.dockerDesktopRecoveryEnabled,
+        allowOpenPublicSandbox: process.env.FORGE_ALLOW_OPEN_PUBLIC_SANDBOX === undefined
+            ? local.allowOpenPublicSandbox ?? config.allowOpenPublicSandbox
+            : config.allowOpenPublicSandbox,
         cliProviders,
         providerStatuses: normalizeProviderStatuses(local.providerStatuses) ?? providerStatusesFor(cliProviders),
         projectLabels: local.projectLabels ?? config.projectLabels,
@@ -88,6 +97,19 @@ export async function removeRepoMapping(label) {
     await writeLocalConfig(next);
     return { config: next, removed: after.length !== before.length };
 }
+export async function setServerUrl(serverUrl) {
+    const normalized = normalizeServerUrl(serverUrl);
+    const current = await readLocalConfig();
+    const next = normalizeLocalConfig({ ...current, serverUrl: normalized });
+    await writeLocalConfig(next);
+    return next;
+}
+export async function setSandboxPolicy(dockerEnabled, allowOpenPublicSandbox) {
+    const current = await readLocalConfig();
+    const next = normalizeLocalConfig({ ...current, dockerEnabled, allowOpenPublicSandbox });
+    await writeLocalConfig(next);
+    return next;
+}
 export function providerStatusesFor(providers) {
     return Object.fromEntries(providers.map((provider) => [provider, { signedIn: true, version: "", models: configuredModelsFor(provider) }]));
 }
@@ -106,6 +128,9 @@ function normalizeLocalConfig(config) {
         deviceName: cleanString(config.deviceName),
         defaultRepoRoot: cleanString(config.defaultRepoRoot),
         cleanupWorktrees: config.cleanupWorktrees,
+        dockerEnabled: config.dockerEnabled,
+        dockerDesktopRecoveryEnabled: config.dockerDesktopRecoveryEnabled,
+        allowOpenPublicSandbox: config.allowOpenPublicSandbox,
         cliProviders: cleanList(config.cliProviders),
         providerStatuses: normalizeProviderStatuses(config.providerStatuses),
         projectLabels: cleanList(config.projectLabels),
@@ -200,10 +225,11 @@ function normalizeQaAppLaunchTarget(value) {
         command: cleanString(value.command),
         working_directory: cleanString(value.working_directory),
         ready_url: cleanString(value.ready_url),
+        managed_runtime_port: cleanString(value.managed_runtime_port),
         routes,
         notes: cleanString(value.notes)
     };
-    return normalized.url || normalized.command || normalized.ready_url || routes?.length
+    return normalized.url || normalized.command || normalized.ready_url || normalized.managed_runtime_port
         ? normalized
         : undefined;
 }
@@ -211,6 +237,24 @@ function cleanString(value) {
     const clean = value?.trim();
     return clean ? clean : undefined;
 }
+function normalizeServerUrl(value) {
+    const clean = value.trim();
+    let parsed;
+    try {
+        parsed = new URL(clean);
+    }
+    catch {
+        throw new Error(`Invalid Forge server URL: ${value}`);
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new Error("Forge server URL must use http or https.");
+    }
+    if (parsed.username || parsed.password || parsed.search || parsed.hash) {
+        throw new Error("Forge server URL cannot include credentials, a query string, or a fragment.");
+    }
+    parsed.pathname = parsed.pathname.replace(/\/+$/u, "") || "/";
+    return parsed.toString().replace(/\/$/u, "");
+}
 function cleanList(values) {
     const clean = [...new Set((values ?? []).map((value) => value.trim()).filter(Boolean))];
     return clean.length > 0 ? clean : undefined;

package/dist/runtime/aspnet-runtime-prebuild.d.ts

@@ -0,0 +1,36 @@
+export interface AspNetRuntimePrebuildPlan {
+    readonly fingerprint: string;
+    readonly receiptPath: string;
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly cwd: string;
+    readonly environment: Readonly<Record<string, string>>;
+    readonly projectPath: string;
+    readonly worktreePath: string;
+    readonly inputCommitSha: string;
+}
+export interface AspNetRuntimePrebuildResult {
+    readonly cacheHit: boolean;
+    readonly receiptPath: string;
+    readonly fingerprint: string;
+}
+export interface AspNetRuntimeBuildExecutionResult {
+    readonly exitCode: number;
+    readonly stdoutTail: string;
+    readonly stderrTail: string;
+    readonly stdoutLogPath: string;
+    readonly stderrLogPath: string;
+}
+export type AspNetRuntimeBuildExecutor = (plan: AspNetRuntimePrebuildPlan, signal?: AbortSignal) => Promise<AspNetRuntimeBuildExecutionResult>;
+export declare function createAspNetRuntimePrebuildPlan(options: {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly cwd: string;
+    readonly worktreePath: string;
+    readonly environment?: Readonly<Record<string, string>>;
+    readonly inputCommitSha: string;
+    readonly runtimeContractFingerprint: string;
+}): AspNetRuntimePrebuildPlan | null;
+export declare function ensureAspNetRuntimePrebuilt(plan: AspNetRuntimePrebuildPlan, execute: AspNetRuntimeBuildExecutor, signal?: AbortSignal): Promise<AspNetRuntimePrebuildResult>;
+export declare function withAspNetPrebuiltRunArguments(command: string, args: readonly string[]): readonly string[];
+export declare function resolveWorktreeCommitSha(worktreePath: string, supplied?: string | null): Promise<string>;

package/dist/runtime/aspnet-runtime-prebuild.js

@@ -0,0 +1,340 @@
+import { createHash, randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+const inFlightPrebuilds = new Map();
+export function createAspNetRuntimePrebuildPlan(options) {
+    if (!isDotnetRun(options.command, options.args))
+        return null;
+    const projectArgument = readOptionValue(options.args, "--project");
+    const projectPath = path.resolve(options.cwd, projectArgument ?? ".");
+    const normalizedWorktree = path.resolve(options.worktreePath);
+    const relativeProject = path.relative(normalizedWorktree, projectPath);
+    if (relativeProject.startsWith("..") || path.isAbsolute(relativeProject)) {
+        throw new Error("host_runtime_build_invalid: the ASP.NET project must remain inside the managed worktree.");
+    }
+    const projectDirectory = projectArgument && path.extname(projectPath).toLowerCase() === ".csproj"
+        ? path.dirname(projectPath)
+        : projectPath;
+    const buildArgs = [
+        "build",
+        ...(projectArgument ? [projectArgument] : []),
+        "--nologo",
+        "--no-restore",
+        "--disable-build-servers",
+        "-p:UseSharedCompilation=false",
+        "-p:DefaultItemExcludesInProjectFolder=TestResults/**",
+        ...forwardBuildOptions(options.args),
+    ];
+    const fingerprint = `sha256:${createHash("sha256").update(JSON.stringify({
+        inputCommitSha: options.inputCommitSha,
+        runtimeContractFingerprint: options.runtimeContractFingerprint,
+        project: relativeProject.replaceAll("\\", "/"),
+        args: buildArgs,
+        environment: buildEnvironmentContract(options.environment ?? {}),
+    })).digest("hex")}`;
+    return {
+        fingerprint,
+        receiptPath: path.join(projectDirectory, "obj", ".forge-runtime-build.json"),
+        command: options.command,
+        args: buildArgs,
+        cwd: options.cwd,
+        environment: options.environment ?? {},
+        projectPath,
+        worktreePath: normalizedWorktree,
+        inputCommitSha: options.inputCommitSha,
+    };
+}
+export async function ensureAspNetRuntimePrebuilt(plan, execute, signal) {
+    const pending = inFlightPrebuilds.get(plan.receiptPath);
+    if (pending)
+        return await pending;
+    const started = ensureAspNetRuntimePrebuiltCore(plan, execute, signal);
+    inFlightPrebuilds.set(plan.receiptPath, started);
+    try {
+        return await started;
+    }
+    finally {
+        if (inFlightPrebuilds.get(plan.receiptPath) === started)
+            inFlightPrebuilds.delete(plan.receiptPath);
+    }
+}
+async function ensureAspNetRuntimePrebuiltCore(plan, execute, signal) {
+    const inputs = await aspNetBuildInputs(plan);
+    const fingerprint = `sha256:${createHash("sha256").update(JSON.stringify({
+        planFingerprint: plan.fingerprint,
+        ...inputs,
+    })).digest("hex")}`;
+    const receipt = await readReceipt(plan.receiptPath);
+    if (receipt?.fingerprint === fingerprint
+        && receipt.planFingerprint === plan.fingerprint
+        && receipt.inputCommitSha === plan.inputCommitSha
+        && await aspNetOutputsMatch(plan, receipt.outputs)) {
+        return { cacheHit: true, receiptPath: plan.receiptPath, fingerprint };
+    }
+    const result = await execute(plan, signal);
+    if (result.exitCode !== 0) {
+        const evidence = [
+            diagnostic("stderr", result.stderrTail),
+            diagnostic("stdout", result.stdoutTail),
+            `stdout log: ${result.stdoutLogPath}`,
+            `stderr log: ${result.stderrLogPath}`,
+        ].filter(Boolean).join("; ");
+        throw new Error(`host_runtime_build_failed: dotnet build exited with code ${result.exitCode}.${evidence ? ` ${evidence}` : ""}`);
+    }
+    await fs.mkdir(path.dirname(plan.receiptPath), { recursive: true });
+    const outputs = await collectAspNetBuildOutputs(plan);
+    if (outputs.length === 0) {
+        throw new Error("host_runtime_build_output_missing: dotnet build succeeded without producing a verifiable project output.");
+    }
+    const temporaryReceipt = `${plan.receiptPath}.${randomUUID()}.tmp`;
+    const nextReceipt = {
+        schemaVersion: 2,
+        fingerprint,
+        planFingerprint: plan.fingerprint,
+        inputCommitSha: plan.inputCommitSha,
+        projectPath: plan.projectPath,
+        ...inputs,
+        outputs,
+        completedAt: new Date().toISOString(),
+    };
+    await fs.writeFile(temporaryReceipt, `${JSON.stringify(nextReceipt)}\n`, { encoding: "utf8", mode: 0o600 });
+    try {
+        await fs.rename(temporaryReceipt, plan.receiptPath);
+    }
+    finally {
+        await fs.rm(temporaryReceipt, { force: true }).catch(() => undefined);
+    }
+    return { cacheHit: false, receiptPath: plan.receiptPath, fingerprint };
+}
+export function withAspNetPrebuiltRunArguments(command, args) {
+    if (!isDotnetRun(command, args)) {
+        throw new Error("node_runtime_adapter_invalid: aspnetcore adapter requires a dotnet run command.");
+    }
+    const applicationArguments = args.indexOf("--");
+    const insertionIndex = applicationArguments < 0 ? args.length : applicationArguments;
+    const beforeApplication = args.slice(0, insertionIndex);
+    return [
+        ...beforeApplication,
+        ...(!beforeApplication.includes("--no-build") ? ["--no-build"] : []),
+        ...(!beforeApplication.includes("--no-restore") ? ["--no-restore"] : []),
+        ...args.slice(insertionIndex),
+    ];
+}
+export async function resolveWorktreeCommitSha(worktreePath, supplied) {
+    if (supplied && /^[0-9a-f]{40,64}$/iu.test(supplied))
+        return supplied.toLowerCase();
+    return await new Promise((resolve, reject) => {
+        const child = spawn("git", ["rev-parse", "--verify", "HEAD^{commit}"], {
+            cwd: worktreePath,
+            windowsHide: true,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", chunk => { stdout = `${stdout}${String(chunk)}`.slice(-256); });
+        child.stderr.on("data", chunk => { stderr = `${stderr}${String(chunk)}`.slice(-1_000); });
+        child.once("error", reject);
+        child.once("close", code => {
+            const commit = stdout.trim();
+            if (code === 0 && /^[0-9a-f]{40,64}$/iu.test(commit))
+                resolve(commit.toLowerCase());
+            else
+                reject(new Error(`host_runtime_build_commit_unavailable: git rev-parse failed (${code ?? "unknown"}): ${stderr.trim()}`));
+        });
+    });
+}
+function isDotnetRun(command, args) {
+    const executable = path.basename(command).toLowerCase();
+    return (executable === "dotnet" || executable === "dotnet.exe") && args[0]?.toLowerCase() === "run";
+}
+function readOptionValue(args, option) {
+    const index = args.findIndex(argument => argument === option || argument.startsWith(`${option}=`));
+    if (index < 0)
+        return null;
+    const argument = args[index];
+    return argument.startsWith(`${option}=`) ? argument.slice(option.length + 1) : args[index + 1] ?? null;
+}
+function forwardBuildOptions(args) {
+    const forwarded = [];
+    const optionsWithValues = new Set(["-c", "--configuration", "-f", "--framework", "-r", "--runtime", "--arch", "--os"]);
+    for (let index = 1; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === "--")
+            break;
+        if (argument === "--project") {
+            index += 1;
+            continue;
+        }
+        if (argument.startsWith("--project="))
+            continue;
+        if (optionsWithValues.has(argument)) {
+            const value = args[index + 1];
+            if (value !== undefined) {
+                forwarded.push(argument, value);
+                index += 1;
+            }
+            continue;
+        }
+        if ([...optionsWithValues].some(option => argument.startsWith(`${option}=`))
+            || argument.startsWith("-p:")
+            || argument.startsWith("/p:")) {
+            forwarded.push(argument);
+        }
+    }
+    return forwarded;
+}
+async function readReceipt(receiptPath) {
+    try {
+        const parsed = JSON.parse(await fs.readFile(receiptPath, "utf8"));
+        return parsed.schemaVersion === 2
+            && typeof parsed.fingerprint === "string"
+            && typeof parsed.planFingerprint === "string"
+            && typeof parsed.inputCommitSha === "string"
+            && typeof parsed.sourceDigest === "string"
+            && typeof parsed.dependencyDigest === "string"
+            && typeof parsed.sdkVersion === "string"
+            && Array.isArray(parsed.outputs)
+            ? parsed
+            : null;
+    }
+    catch (error) {
+        if (error.code === "ENOENT" || error instanceof SyntaxError)
+            return null;
+        throw error;
+    }
+}
+async function aspNetBuildInputs(plan) {
+    const projectDirectory = path.extname(plan.projectPath).toLowerCase() === ".csproj"
+        ? path.dirname(plan.projectPath)
+        : plan.projectPath;
+    const sourceDigest = await directoryContentDigest(projectDirectory);
+    const dependencyReceipt = path.join(projectDirectory, "obj", ".forge-dependency-preparation.json");
+    const dependencyContent = await fs.readFile(dependencyReceipt).catch(() => null);
+    const globalJson = await findAncestorFile(projectDirectory, plan.worktreePath, "global.json");
+    const globalJsonContent = globalJson ? await fs.readFile(globalJson) : null;
+    return {
+        sourceDigest,
+        dependencyDigest: `sha256:${createHash("sha256")
+            .update(dependencyContent ?? Buffer.alloc(0))
+            .update(globalJsonContent ?? Buffer.alloc(0))
+            .digest("hex")}`,
+        sdkVersion: await dotnetSdkVersion(plan.cwd),
+    };
+}
+async function directoryContentDigest(directory) {
+    const files = [];
+    await collectInputFiles(directory, directory, files);
+    const hash = createHash("sha256");
+    for (const file of files.sort((left, right) => left.localeCompare(right))) {
+        hash.update(path.relative(directory, file).replaceAll("\\", "/"));
+        hash.update("\0");
+        hash.update(await fs.readFile(file));
+        hash.update("\0");
+    }
+    return `sha256:${hash.digest("hex")}`;
+}
+async function collectInputFiles(root, directory, files) {
+    const entries = await fs.readdir(directory, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+        const absolute = path.join(directory, entry.name);
+        if (entry.isDirectory()) {
+            if (!["bin", "obj", "node_modules", ".git", "TestResults"].includes(entry.name)) {
+                await collectInputFiles(root, absolute, files);
+            }
+        }
+        else if (entry.isFile()) {
+            files.push(absolute);
+        }
+    }
+}
+async function collectAspNetBuildOutputs(plan) {
+    const projectDirectory = path.extname(plan.projectPath).toLowerCase() === ".csproj"
+        ? path.dirname(plan.projectPath)
+        : plan.projectPath;
+    const outputRoot = path.join(projectDirectory, "bin");
+    const outputs = [];
+    await collectOutputFiles(outputRoot, projectDirectory, outputs);
+    return outputs.sort((left, right) => left.path.localeCompare(right.path));
+}
+async function collectOutputFiles(directory, projectDirectory, outputs) {
+    const entries = await fs.readdir(directory, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+        const absolute = path.join(directory, entry.name);
+        if (entry.isDirectory())
+            await collectOutputFiles(absolute, projectDirectory, outputs);
+        else if (entry.isFile()) {
+            const stat = await fs.stat(absolute);
+            outputs.push({
+                path: path.relative(projectDirectory, absolute).replaceAll("\\", "/"),
+                size: stat.size,
+                digest: createHash("sha256").update(await fs.readFile(absolute)).digest("hex"),
+            });
+        }
+    }
+}
+async function aspNetOutputsMatch(plan, outputs) {
+    if (outputs.length === 0)
+        return false;
+    const projectDirectory = path.extname(plan.projectPath).toLowerCase() === ".csproj"
+        ? path.dirname(plan.projectPath)
+        : plan.projectPath;
+    for (const output of outputs) {
+        const absolute = path.resolve(projectDirectory, output.path);
+        const relative = path.relative(projectDirectory, absolute);
+        if (relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
+            return false;
+        const stat = await fs.stat(absolute).catch(() => null);
+        if (!stat?.isFile() || stat.size !== output.size)
+            return false;
+        const digest = createHash("sha256").update(await fs.readFile(absolute)).digest("hex");
+        if (digest !== output.digest)
+            return false;
+    }
+    return true;
+}
+async function findAncestorFile(directory, root, name) {
+    let current = path.resolve(directory);
+    const resolvedRoot = path.resolve(root);
+    while (true) {
+        const candidate = path.join(current, name);
+        if (await fs.stat(candidate).then(stat => stat.isFile()).catch(() => false))
+            return candidate;
+        if (current === resolvedRoot)
+            return null;
+        const parent = path.dirname(current);
+        if (parent === current || path.relative(resolvedRoot, parent).startsWith(".."))
+            return null;
+        current = parent;
+    }
+}
+async function dotnetSdkVersion(cwd) {
+    return await new Promise(resolve => {
+        const child = spawn("dotnet", ["--version"], { cwd, windowsHide: true, stdio: ["ignore", "pipe", "pipe"] });
+        let output = "";
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", chunk => { output += String(chunk); });
+        child.stderr.on("data", chunk => { output += String(chunk); });
+        child.once("error", () => resolve("unavailable"));
+        child.once("close", code => resolve(code === 0 ? output.trim().slice(0, 256) : `unavailable:${code ?? "unknown"}`));
+    });
+}
+function buildEnvironmentContract(environment) {
+    return {
+        DOTNET_ROOT: environment.DOTNET_ROOT ?? process.env.DOTNET_ROOT ?? null,
+        DOTNET_ROLL_FORWARD: environment.DOTNET_ROLL_FORWARD ?? process.env.DOTNET_ROLL_FORWARD ?? null,
+        DOTNET_MULTILEVEL_LOOKUP: environment.DOTNET_MULTILEVEL_LOOKUP ?? process.env.DOTNET_MULTILEVEL_LOOKUP ?? null,
+        MSBuildSDKsPath: environment.MSBuildSDKsPath ?? process.env.MSBuildSDKsPath ?? null,
+        NUGET_PACKAGES: environment.NUGET_PACKAGES ?? process.env.NUGET_PACKAGES ?? null,
+        FORGE_BUILD_CACHE_EPOCH: createHash("sha256")
+            .update(environment.FORGE_BUILD_CACHE_EPOCH ?? process.env.FORGE_BUILD_CACHE_EPOCH ?? "default")
+            .digest("hex"),
+    };
+}
+function diagnostic(label, value) {
+    const normalized = value.replaceAll(/[\r\n\t]+/gu, " ").trim();
+    return normalized ? `${label} tail: ${normalized.slice(-2_000)}` : "";
+}

package/dist/runtime/attempt-node-runtime-launcher.d.ts

@@ -0,0 +1,17 @@
+import type { AttemptProcessChildHandle, AttemptProcessSupervisor } from "./attempt-process-supervisor.js";
+import type { HostPortLeaseOwner } from "./host-port-broker.js";
+import { HostListenerInspector } from "./host-listener-inspector.js";
+import type { HostListenerOwnership, NodeRuntimeCommandLauncher, NodeRuntimeLaunchRequest, NodeRuntimeReadinessDiagnostics } from "./node-host-runtime-adapter.js";
+/** Launches one explicitly configured HTTP project beneath the attempt coordinator. */
+export declare class AttemptNodeRuntimeLauncher implements NodeRuntimeCommandLauncher<AttemptProcessChildHandle> {
+    private readonly supervisor;
+    private readonly owner;
+    private readonly logDirectory;
+    private readonly listenerInspector;
+    private readonly diagnosticsByChild;
+    constructor(supervisor: AttemptProcessSupervisor, owner: HostPortLeaseOwner, logDirectory: string, listenerInspector?: HostListenerInspector);
+    launch(request: NodeRuntimeLaunchRequest, signal?: AbortSignal): Promise<AttemptProcessChildHandle>;
+    inspectListener(child: AttemptProcessChildHandle, request: NodeRuntimeLaunchRequest): Promise<HostListenerOwnership>;
+    stop(child: AttemptProcessChildHandle): Promise<void>;
+    readinessDiagnostics(child: AttemptProcessChildHandle): Promise<NodeRuntimeReadinessDiagnostics>;
+}

package/dist/runtime/attempt-node-runtime-launcher.js

@@ -0,0 +1,105 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { HostListenerInspector } from "./host-listener-inspector.js";
+const diagnosticTailLength = 4_000;
+/** Launches one explicitly configured HTTP project beneath the attempt coordinator. */
+export class AttemptNodeRuntimeLauncher {
+    supervisor;
+    owner;
+    logDirectory;
+    listenerInspector;
+    diagnosticsByChild = new WeakMap();
+    constructor(supervisor, owner, logDirectory, listenerInspector = new HostListenerInspector()) {
+        this.supervisor = supervisor;
+        this.owner = owner;
+        this.logDirectory = logDirectory;
+        this.listenerInspector = listenerInspector;
+    }
+    async launch(request, signal) {
+        const childName = projectChildName(request.port.name);
+        const stdoutPath = path.join(this.logDirectory, `${childName}.stdout.log`);
+        const stderrPath = path.join(this.logDirectory, `${childName}.stderr.log`);
+        const diagnostics = { exited: false, stdoutTail: "", stderrTail: "", outputRevision: 0 };
+        let child;
+        try {
+            child = await this.supervisor.startChildReady(childName, {
+                command: request.command,
+                args: request.args,
+                cwd: request.cwd,
+                env: request.environment,
+                captureOutput: false,
+            }, {
+                onStdoutLine: async (line) => {
+                    diagnostics.stdoutTail = appendTail(diagnostics.stdoutTail, line);
+                    diagnostics.outputRevision += 1;
+                    await appendLine(stdoutPath, line);
+                },
+                onStderrLine: async (line) => {
+                    diagnostics.stderrTail = appendTail(diagnostics.stderrTail, line);
+                    diagnostics.outputRevision += 1;
+                    await appendLine(stderrPath, line);
+                },
+            }, signal, { maxStartAttempts: 3, retryDelayMs: 250 });
+        }
+        catch (error) {
+            throw enrichLaunchFailure(error, diagnostics);
+        }
+        this.diagnosticsByChild.set(child, diagnostics);
+        void child.result.then(result => {
+            diagnostics.exited = true;
+            diagnostics.exitCode = result.exitCode;
+            diagnostics.stdoutTail = appendTail(diagnostics.stdoutTail, result.stdout);
+            diagnostics.stderrTail = appendTail(diagnostics.stderrTail, result.stderr);
+            diagnostics.outputRevision += 1;
+        }, error => {
+            diagnostics.exited = true;
+            diagnostics.stderrTail = appendTail(diagnostics.stderrTail, error instanceof Error ? error.message : String(error));
+            diagnostics.outputRevision += 1;
+        });
+        return child;
+    }
+    async inspectListener(child, request) {
+        return await this.listenerInspector.inspect(child, request.port, this.owner);
+    }
+    async stop(child) {
+        await child.stop(this.owner.fencingToken);
+    }
+    async readinessDiagnostics(child) {
+        // Yield once so an already-settled result can update the diagnostic record.
+        await Promise.resolve();
+        const diagnostics = this.diagnosticsByChild.get(child);
+        return diagnostics ?? { exited: false };
+    }
+}
+function projectChildName(portName) {
+    const candidate = `project-${portName}`;
+    if (/^[a-z][a-z0-9_-]{0,31}$/u.test(candidate))
+        return candidate;
+    const digest = createHash("sha256").update(portName).digest("hex").slice(0, 16);
+    return `project-${digest}`;
+}
+async function appendLine(target, line) {
+    await fs.appendFile(target, `${line}\n`, { encoding: "utf8", mode: 0o600 });
+}
+function appendTail(current, value) {
+    if (!value)
+        return current;
+    const combined = current ? `${current}\n${value}` : value;
+    return combined.slice(-diagnosticTailLength);
+}
+function enrichLaunchFailure(error, diagnostics) {
+    const message = error instanceof Error ? error.message : String(error);
+    const evidence = [
+        diagnostics.stderrTail ? `stderr tail: ${boundedDiagnostic(diagnostics.stderrTail)}` : "",
+        diagnostics.stdoutTail ? `stdout tail: ${boundedDiagnostic(diagnostics.stdoutTail)}` : "",
+    ].filter(Boolean);
+    return evidence.length > 0
+        ? new Error(`${message} ${evidence.join("; ")}`, { cause: error })
+        : error instanceof Error
+            ? error
+            : new Error(message);
+}
+function boundedDiagnostic(value) {
+    return value.replaceAll(/[\r\n\t]+/gu, " ").trim().slice(-1_000);
+}

package/dist/runtime/attempt-path-operation.d.ts

@@ -0,0 +1,21 @@
+import type { BigIntStats } from "node:fs";
+/** A separate process pins cwd without changing the multithreaded Bridge's cwd.
+ * All writes use single relative components, never a re-resolved ancestor path.
+ */
+export declare function runAttemptPathOperation(parent: string, identity: BigIntStats, operation: {
+    kind: "mkdir";
+    segments: string[];
+} | {
+    kind: "private-directory-mode";
+    segments: string[];
+} | {
+    kind: "overlay";
+    name: string;
+    content: string;
+}): Promise<void>;
+/** Archive copies may be large or numerous: never block Bridge heartbeats while a pinned worker writes. */
+export declare function runAttemptArchiveOperation(parent: string, identity: BigIntStats, operation: {
+    name: string;
+    bytes: Buffer;
+    sha256: string;
+}): Promise<void>;