@loucompanion/forge-bridge 0.1.3-dev.9d8f2e7e5241 → 0.1.3-dev.a58d7cd1092f

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-process-supervisor-registry.d.ts

@@ -0,0 +1,20 @@
+import type { ProviderProcessHandlers, ProviderProcessRunRequest, ProviderProcessRunner, ProviderProcessRunResult } from "../session/provider-cli/provider-cli.process.js";
+import { AttemptProcessSupervisor, type AttemptProcessSupervisorIdentity, type AttemptProcessSupervisorOptions } from "./attempt-process-supervisor.js";
+/** Runner-local authority for active host attempt process coordinators. */
+export declare class AttemptProcessSupervisorRegistry {
+    private readonly active;
+    register(identity: AttemptProcessSupervisorIdentity, runner: ProviderProcessRunner, options?: AttemptProcessSupervisorOptions): AttemptProcessSupervisor;
+    require(dispatchAttemptId: string, fencingToken: string): AttemptProcessSupervisor;
+    unregister(dispatchAttemptId: string, fencingToken: string): boolean;
+    has(dispatchAttemptId: string): boolean;
+}
+/**
+ * Routes managed-host provider commands through the attempt's named provider
+ * child while retaining the raw runner for Docker and unmanaged execution.
+ */
+export declare class AttemptCoordinatedProviderProcessRunner implements ProviderProcessRunner {
+    private readonly registry;
+    private readonly rawRunner;
+    constructor(registry: AttemptProcessSupervisorRegistry, rawRunner: ProviderProcessRunner);
+    run(request: ProviderProcessRunRequest, handlers?: ProviderProcessHandlers, signal?: AbortSignal): Promise<ProviderProcessRunResult>;
+}

package/dist/runtime/attempt-process-supervisor-registry.js

@@ -0,0 +1,64 @@
+import { AttemptProcessSupervisor, } from "./attempt-process-supervisor.js";
+/** Runner-local authority for active host attempt process coordinators. */
+export class AttemptProcessSupervisorRegistry {
+    active = new Map();
+    register(identity, runner, options = {}) {
+        const existing = this.active.get(identity.dispatchAttemptId);
+        if (existing) {
+            if (existing.fencingToken !== identity.fencingToken) {
+                throw new Error("attempt_process_registry_conflict: dispatch attempt is registered under a different fence.");
+            }
+            return existing.supervisor;
+        }
+        const supervisor = new AttemptProcessSupervisor(identity, runner, options);
+        this.active.set(identity.dispatchAttemptId, { fencingToken: identity.fencingToken, supervisor });
+        return supervisor;
+    }
+    require(dispatchAttemptId, fencingToken) {
+        const registered = this.active.get(dispatchAttemptId);
+        if (!registered) {
+            throw new Error("attempt_process_registry_missing: no process coordinator owns this dispatch attempt.");
+        }
+        if (registered.fencingToken !== fencingToken) {
+            throw new Error("attempt_process_registry_fenced: process coordinator fence does not match the dispatch.");
+        }
+        return registered.supervisor;
+    }
+    unregister(dispatchAttemptId, fencingToken) {
+        const registered = this.active.get(dispatchAttemptId);
+        if (!registered || registered.fencingToken !== fencingToken)
+            return false;
+        return this.active.delete(dispatchAttemptId);
+    }
+    has(dispatchAttemptId) {
+        return this.active.has(dispatchAttemptId);
+    }
+}
+/**
+ * Routes managed-host provider commands through the attempt's named provider
+ * child while retaining the raw runner for Docker and unmanaged execution.
+ */
+export class AttemptCoordinatedProviderProcessRunner {
+    registry;
+    rawRunner;
+    constructor(registry, rawRunner) {
+        this.registry = registry;
+        this.rawRunner = rawRunner;
+    }
+    async run(request, handlers, signal) {
+        if (request.env?.FORGE_RUNTIME_MODE !== "host") {
+            return await this.rawRunner.run(request, handlers, signal);
+        }
+        const dispatchAttemptId = requiredEnvironment(request, "FORGE_DISPATCH_ATTEMPT_ID");
+        const fencingToken = requiredEnvironment(request, "FORGE_FENCING_TOKEN");
+        const supervisor = this.registry.require(dispatchAttemptId, fencingToken);
+        const child = await supervisor.startChildReady("provider", request, handlers, signal, { maxStartAttempts: request.stdin === undefined ? 1 : 3, retryDelayMs: 100 });
+        return await child.result;
+    }
+}
+function requiredEnvironment(request, name) {
+    const value = request.env?.[name]?.trim();
+    if (!value)
+        throw new Error(`attempt_process_registry_invalid: ${name} is required for managed-host execution.`);
+    return value;
+}

package/dist/runtime/attempt-process-supervisor.d.ts

@@ -0,0 +1,97 @@
+import type { ProviderProcessHandlers, ProviderProcessRunRequest, ProviderProcessRunner, ProviderProcessRunResult } from "../session/provider-cli/provider-cli.process.js";
+export type AttemptProcessChildStatus = "starting" | "running" | "stopping" | "exited" | "failed";
+export type AttemptProcessSupervisorStatus = "active" | "stopping" | "stopped" | "degraded";
+export interface AttemptProcessSupervisorIdentity {
+    readonly processSupervisorId: string;
+    readonly dispatchAttemptId: string;
+    readonly executionLeaseId: string;
+    readonly fencingToken: string;
+    readonly logDirectory: string;
+}
+export interface AttemptProcessChildLedgerEntry {
+    readonly name: string;
+    readonly generation: number;
+    readonly childId: string;
+    readonly processSupervisorId: string;
+    readonly metadataPath: string;
+    readonly status: AttemptProcessChildStatus;
+    readonly startedAt: string;
+    readonly settledAt?: string;
+    readonly exitCode?: number;
+    readonly failure?: string;
+    readonly peakMemoryBytes?: number;
+    readonly memorySampleCount?: number;
+    readonly memorySource?: string;
+    readonly memoryObservedAt?: string;
+}
+export interface AttemptProcessSupervisorLedger {
+    readonly schemaVersion: 1;
+    readonly attemptSupervisorId: string;
+    readonly dispatchAttemptId: string;
+    readonly executionLeaseId: string;
+    readonly status: AttemptProcessSupervisorStatus;
+    readonly updatedAt: string;
+    readonly children: readonly AttemptProcessChildLedgerEntry[];
+}
+export interface AttemptProcessChildHandle {
+    readonly name: string;
+    readonly generation: number;
+    readonly childId: string;
+    readonly processSupervisorId: string;
+    readonly metadataPath: string;
+    readonly ready: Promise<void>;
+    readonly result: Promise<ProviderProcessRunResult>;
+    stop(fencingToken: string): Promise<ProviderProcessRunResult>;
+}
+export interface AttemptProcessSupervisorOptions {
+    readonly metadataReadyTimeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+export interface AttemptProcessChildReadyOptions {
+    readonly maxStartAttempts?: number;
+    readonly retryDelayMs?: number;
+}
+/**
+ * Owns the independently supervised process trees that belong to one host
+ * dispatch attempt. Each named child gets a distinct Windows Job Object or
+ * Unix process group through the existing process runner, while this
+ * coordinator supplies shared fencing, cancellation, and a durable ledger.
+ */
+export declare class AttemptProcessSupervisor {
+    private readonly runner;
+    readonly ledgerPath: string;
+    private readonly identity;
+    private readonly metadataReadyTimeoutMs;
+    private readonly records;
+    private readonly currentByName;
+    private readonly attemptController;
+    private status;
+    private persistTail;
+    private persistenceFailure;
+    private stopOperation;
+    constructor(identity: AttemptProcessSupervisorIdentity, runner: ProviderProcessRunner, options?: AttemptProcessSupervisorOptions);
+    startChild(name: string, request: ProviderProcessRunRequest, handlers?: ProviderProcessHandlers, signal?: AbortSignal): Promise<AttemptProcessChildHandle>;
+    /**
+     * Starts a child and proves that the OS process tree is supervised before
+     * returning it to the caller. A launch that settles before producing its
+     * provider-ready supervision record is safe to retry: the raw runner only
+     * persists that record after the actual provider child has started, before
+     * Forge announces the provider as active.
+     */
+    startChildReady(name: string, request: ProviderProcessRunRequest, handlers?: ProviderProcessHandlers, signal?: AbortSignal, options?: AttemptProcessChildReadyOptions): Promise<AttemptProcessChildHandle>;
+    stopChild(name: string, generation: number, fencingToken: string, reason?: unknown): Promise<ProviderProcessRunResult>;
+    stopAll(fencingToken: string, reason?: unknown): Promise<void>;
+    private performStopAll;
+    snapshot(): AttemptProcessSupervisorLedger;
+    providerMemoryTelemetry(): AttemptProcessTreeMemoryTelemetry | null;
+    private observeChildReady;
+    private settleChild;
+    private assertFence;
+    private persist;
+}
+export interface AttemptProcessTreeMemoryTelemetry {
+    readonly peakMemoryBytes: number;
+    readonly sampleCount: number;
+    readonly source: string;
+    readonly observedAt: string;
+}