@loucompanion/forge-bridge 0.1.3-dev.ba7d36726eda → 0.1.3-dev.bca7d0ccee53

package/dist/bridge/bridge.base.d.ts

@@ -1,4 +1,4 @@
-import type { BridgeCancelHandler, BridgeDispatchHandler, BridgeLeaseUpdateHandler, BridgeOfferHandler, BridgeReapHandler, BridgeServiceConfig, BridgeStartHandler } from "./bridge.types.js";
+import type { BridgeCancelHandler, BridgeDispatchHandler, BridgeLeaseUpdateHandler, BridgeOfferHandler, BridgeReadinessProbeHandler, BridgeReapHandler, BridgeServiceConfig, BridgeStartHandler } from "./bridge.types.js";
 export interface BridgeService {
     connectOnce(): Promise<void>;
     run(signal?: AbortSignal): Promise<void>;
@@ -14,6 +14,7 @@ export interface BridgeConnection {
     onLeaseUpdate?(handler: BridgeLeaseUpdateHandler): void;
     onCancel(handler: BridgeCancelHandler): void;
     onReap?(handler: BridgeReapHandler): void;
+    onReadinessProbe?(handler: BridgeReadinessProbeHandler): void;
     invoke<TResponse>(methodName: string, payload: unknown): Promise<TResponse>;
 }
 export interface BridgeConnectionFactory {

package/dist/bridge/bridge.service.d.ts

@@ -15,6 +15,9 @@ export declare class ForgeBridgeService implements BridgeService {
     private readonly connections;
     private connection;
     private heartbeatTimer;
+    private heartbeatInFlight;
+    private consecutiveHeartbeatFailures;
+    private reconnectingFromHeartbeatFailure;
     private leaseWatchdogTimer;
     private sandboxMaintenanceTimer;
     private sandboxMaintenanceRunning;
@@ -22,6 +25,7 @@ export declare class ForgeBridgeService implements BridgeService {
     private stopped;
     private readonly activeSessions;
     private readonly reservations;
+    private readonly activeReadinessProbes;
     private readonly preflight;
     private readonly sandboxRuntime;
     private readonly sandboxResourceResolver;
@@ -40,12 +44,15 @@ export declare class ForgeBridgeService implements BridgeService {
     private parseDispatchOrReport;
     private handleCancel;
     private handleReap;
+    private handleReadinessProbe;
     private abortActiveSessions;
+    private abortActiveReadinessProbes;
     private normalizeDispatch;
     private sendResult;
     private sendLegacyResult;
     private sendResultPayload;
     private startHeartbeat;
+    private heartbeatTick;
     private startLeaseWatchdog;
     private stopLeaseWatchdog;
     private expireLeases;
@@ -80,6 +87,7 @@ export declare class SignalRBridgeConnection implements BridgeConnection {
     onLeaseUpdate(handler: (request: BridgeLeaseUpdateRequest) => Promise<void>): void;
     onCancel(handler: BridgeCancelHandler): void;
     onReap(handler: (request: BridgeReapRequest) => Promise<void>): void;
+    onReadinessProbe(handler: (request: unknown) => Promise<void>): void;
     invoke<TResponse>(methodName: string, payload: unknown): Promise<TResponse>;
 }
 export declare function defaultBridgeServiceConfig(overrides?: Partial<BridgeServiceConfig>): BridgeServiceConfig;

package/dist/bridge/bridge.service.js

@@ -25,6 +25,9 @@ export class ForgeBridgeService {
     connections;
     connection = null;
     heartbeatTimer = null;
+    heartbeatInFlight = false;
+    consecutiveHeartbeatFailures = 0;
+    reconnectingFromHeartbeatFailure = false;
     leaseWatchdogTimer = null;
     sandboxMaintenanceTimer = null;
     sandboxMaintenanceRunning = false;
@@ -32,6 +35,7 @@ export class ForgeBridgeService {
     stopped = false;
     activeSessions = new Map();
     reservations = new Map();
+    activeReadinessProbes = new Map();
     preflight;
     sandboxRuntime;
     sandboxResourceResolver;
@@ -82,6 +86,7 @@ export class ForgeBridgeService {
             connection.onClose(() => {
                 this.stopHeartbeat();
                 this.abortActiveSessions("bridge connection closed");
+                this.abortActiveReadinessProbes("bridge connection closed");
                 resolve();
             });
         });
@@ -91,6 +96,7 @@ export class ForgeBridgeService {
         connection.onLeaseUpdate?.((request) => this.handleLeaseUpdate(request));
         connection.onCancel((request) => this.handleCancel(request));
         connection.onReap?.((request) => this.handleReap(request));
+        connection.onReadinessProbe?.((request) => this.handleReadinessProbe(request));
         await connection.start();
         await this.invokeAck("Hello", {
             version: this.config.version,
@@ -133,6 +139,7 @@ export class ForgeBridgeService {
         finally {
             if (signal?.aborted) {
                 this.abortActiveSessions(String(signal.reason ?? "bridge stopping"));
+                this.abortActiveReadinessProbes(String(signal.reason ?? "bridge stopping"));
             }
             await this.stopConnection();
         }
@@ -140,6 +147,7 @@ export class ForgeBridgeService {
     async stop() {
         this.stopped = true;
         this.abortActiveSessions("bridge stopping");
+        this.abortActiveReadinessProbes("bridge stopping");
         await this.stopConnection();
         await this.preflight.release();
     }
@@ -221,7 +229,14 @@ export class ForgeBridgeService {
             const summary = controller.signal.aborted
                 ? `Dispatch cancelled: ${String(controller.signal.reason ?? "cancelled")}`
                 : redactText(error instanceof Error ? error.message : String(error), redactionSecrets);
-            await this.sendResult(dispatch, failureResult(summary)).catch(() => undefined);
+            const failureEventType = infrastructureFailureEventType(summary);
+            const failureEvents = failureEventType ? [{
+                    role: "runner",
+                    kind: "error",
+                    content: summary,
+                    eventType: failureEventType,
+                }] : [];
+            await this.sendResult(dispatch, failureResult(summary, failureEvents)).catch(() => undefined);
         }
         finally {
             this.activeSessions.delete(leaseId);
@@ -270,6 +285,11 @@ export class ForgeBridgeService {
                 await this.sendOfferDecision(dispatch, false, "policy_mismatch", networkFailure);
                 return;
             }
+            const providerNetworkFailure = sandboxProviderNetworkFailure(dispatch, this.config);
+            if (providerNetworkFailure) {
+                await this.sendOfferDecision(dispatch, false, "provider_network_unavailable", providerNetworkFailure);
+                return;
+            }
             const authFailure = sandboxAuthFailure(dispatch, this.config);
             if (authFailure) {
                 await this.sendOfferDecision(dispatch, false, "sandbox_auth_unavailable", authFailure);
@@ -452,19 +472,73 @@ export class ForgeBridgeService {
         active.controller.abort(request.reason ?? "cancelled by server");
     }
     async handleReap(request) {
-        if (!this.config.dockerEnabled
-            || request.runnerId !== this.config.runnerId
+        if (request.runnerId !== this.config.runnerId
             || request.runnerInstanceId !== this.config.runnerInstanceId)
             return;
         await this.runSandboxMaintenance();
         await this.sendHeartbeat();
     }
+    async handleReadinessProbe(rawRequest) {
+        const request = parseReadinessProbe(rawRequest);
+        if (!request || request.runnerInstanceId !== this.config.runnerInstanceId)
+            return;
+        const existing = this.activeReadinessProbes.get(request.requestId);
+        if (existing)
+            return;
+        const controller = new AbortController();
+        this.activeReadinessProbes.set(request.requestId, controller);
+        const deadlineMs = Date.parse(request.expiresAt) - Date.now();
+        const timer = setTimeout(() => controller.abort("readiness probe expired"), Math.max(0, deadlineMs));
+        timer.unref?.();
+        let result;
+        try {
+            if (!this.sessions.probeHostRuntime) {
+                throw new Error("host_runtime_probe_unavailable: this bridge does not implement runtime readiness probes.");
+            }
+            const probe = await this.sessions.probeHostRuntime({
+                ...request,
+                runnerId: this.config.runnerId,
+                repoRoot: this.config.defaultRepoRoot,
+                cleanupWorktrees: this.config.cleanupWorktrees,
+            }, controller.signal);
+            result = {
+                schemaVersion: 1,
+                requestId: request.requestId,
+                fencingToken: request.fencingToken,
+                runnerInstanceId: this.config.runnerInstanceId,
+                ...probe,
+            };
+        }
+        catch (error) {
+            result = {
+                schemaVersion: 1,
+                requestId: request.requestId,
+                fencingToken: request.fencingToken,
+                runnerInstanceId: this.config.runnerInstanceId,
+                status: "failed",
+                reasonCode: "host_runtime_probe_failed",
+                reasonMessage: errorMessage(error).slice(0, 1000),
+                checkedAt: new Date().toISOString(),
+            };
+        }
+        finally {
+            clearTimeout(timer);
+            this.activeReadinessProbes.delete(request.requestId);
+        }
+        await this.invokeAck("ReadinessResult", result).catch(() => undefined);
+        await this.sendHeartbeat().catch(() => undefined);
+    }
     abortActiveSessions(reason) {
         for (const active of this.activeSessions.values()) {
             active.controller.abort(reason);
         }
         this.activeSessions.clear();
     }
+    abortActiveReadinessProbes(reason) {
+        for (const controller of this.activeReadinessProbes.values())
+            controller.abort(reason);
+        this.activeReadinessProbes.clear();
+    }
     normalizeDispatch(dispatch) {
         const mapping = findRepoMapping(dispatch, repoMappingsFor(this.config));
         const localPath = mapping?.localPath?.trim();
@@ -515,12 +589,41 @@ export class ForgeBridgeService {
     }
     startHeartbeat() {
         this.stopHeartbeat();
+        this.consecutiveHeartbeatFailures = 0;
+        this.reconnectingFromHeartbeatFailure = false;
         const intervalMs = positiveFiniteNumber(this.config.heartbeatIntervalMs, 30_000);
         this.heartbeatTimer = setInterval(() => {
-            this.sendHeartbeat().catch(() => undefined);
+            void this.heartbeatTick();
         }, intervalMs);
         this.heartbeatTimer.unref?.();
     }
+    async heartbeatTick() {
+        if (this.heartbeatInFlight || this.reconnectingFromHeartbeatFailure)
+            return;
+        const connection = this.connection;
+        if (!connection)
+            return;
+        this.heartbeatInFlight = true;
+        try {
+            await this.sendHeartbeat();
+            this.consecutiveHeartbeatFailures = 0;
+        }
+        catch (error) {
+            if (connection !== this.connection || this.stopped)
+                return;
+            this.consecutiveHeartbeatFailures += 1;
+            logBridgeStatus(`Heartbeat ${this.consecutiveHeartbeatFailures} failed: ${errorMessage(error)}.`);
+            if (this.consecutiveHeartbeatFailures < 2)
+                return;
+            this.reconnectingFromHeartbeatFailure = true;
+            this.stopHeartbeat();
+            logBridgeStatus("Heartbeat failed twice. Closing the stale connection so the Bridge can reconnect...");
+            await connection.stop().catch(() => undefined);
+        }
+        finally {
+            this.heartbeatInFlight = false;
+        }
+    }
     startLeaseWatchdog() {
         this.stopLeaseWatchdog();
         this.leaseWatchdogTimer = setInterval(() => this.expireLeases(), 1000);
@@ -553,8 +656,6 @@ export class ForgeBridgeService {
     }
     startSandboxMaintenance() {
         this.stopSandboxMaintenance();
-        if (!this.config.dockerEnabled)
-            return;
         this.sandboxMaintenanceTimer = setInterval(() => {
             this.runSandboxMaintenance().catch(() => undefined);
         }, 60_000);
@@ -571,11 +672,20 @@ export class ForgeBridgeService {
             return;
         this.sandboxMaintenanceRunning = true;
         try {
-            const preflight = await this.preflight.refresh();
-            if (canReapManagedSandboxes(preflight)) {
-                const attemptSnapshot = await this.readAttemptSnapshot();
-                await this.sandboxRuntime.reap({ diskLow: preflight.diskLow, attemptSnapshot });
-                await this.flushCleanupReports();
+            const hostReap = await this.sessions.reapHostRuntime?.({
+                runnerId: this.config.runnerId,
+                runnerInstanceId: this.config.runnerInstanceId,
+            });
+            if (hostReap && (hostReap.reaped > 0 || hostReap.degraded > 0)) {
+                logBridgeStatus(`Managed-host maintenance reaped ${hostReap.reaped} stale attempt(s) and left ${hostReap.degraded} degraded attempt(s) for reconciliation.`);
+            }
+            if (this.config.dockerEnabled) {
+                const preflight = await this.preflight.refresh();
+                if (canReapManagedSandboxes(preflight)) {
+                    const attemptSnapshot = await this.readAttemptSnapshot();
+                    await this.sandboxRuntime.reap({ diskLow: preflight.diskLow, attemptSnapshot });
+                    await this.flushCleanupReports();
+                }
             }
         }
         finally {
@@ -639,6 +749,7 @@ export class ForgeBridgeService {
             sandboxRuntimes: preflight?.healthy ? ["docker"] : [],
             sandboxRuntimeVersion: preflight?.runtimeVersion ?? null,
             sandboxFeatures: preflight?.features ?? null,
+            allowsOpenPublicSandbox: this.config.allowOpenPublicSandbox,
             sandboxPublicationModes: [this.config.sandboxPublicationMode ?? "shared_filesystem"],
             sandboxAuthModes: sandboxAuthModesFor(this.config),
             availableMemoryBytes: preflight ? Math.max(0, capacity.memoryBytes - used.memoryBytes) : null,
@@ -824,6 +935,11 @@ export class SignalRBridgeConnection {
             void handler(request).catch(() => undefined);
         });
     }
+    onReadinessProbe(handler) {
+        this.connection.on("ReadinessProbe", (request) => {
+            void handler(request).catch(() => undefined);
+        });
+    }
     invoke(methodName, payload) {
         return this.connection.invoke(methodName, payload);
     }
@@ -1030,10 +1146,11 @@ function normalizeQaAppLaunchTarget(target) {
         command: cleanString(target.command),
         working_directory: cleanString(target.working_directory),
         ready_url: cleanString(target.ready_url),
+        managed_runtime_port: cleanString(target.managed_runtime_port),
         routes,
         notes: cleanString(target.notes)
     };
-    return normalized.url || normalized.command || normalized.ready_url || routes.length > 0
+    return normalized.url || normalized.command || normalized.ready_url || normalized.managed_runtime_port
         ? normalized
         : null;
 }
@@ -1117,6 +1234,61 @@ function sandboxNetworkPolicyFailure(dispatch, config) {
     }
     return null;
 }
+function infrastructureFailureEventType(summary) {
+    if (summary.startsWith("worktree_prepare_failed:"))
+        return "worktree_prepare_failed";
+    if (summary.startsWith("provider_start_unavailable:"))
+        return "provider_start_unavailable";
+    if (summary.startsWith("host_port_collision:"))
+        return "host_port_collision";
+    if (summary.startsWith("host_runtime_process_exited:"))
+        return "host_runtime_process_exited";
+    if (summary.startsWith("host_runtime_listener_timeout:"))
+        return "host_runtime_listener_timeout";
+    if (summary.startsWith("host_runtime_http_readiness_timeout:"))
+        return "host_runtime_http_readiness_timeout";
+    if (summary.startsWith("attempt_process_supervisor_start_failed:"))
+        return "attempt_process_supervisor_start_failed";
+    if (summary.startsWith("attempt_process_supervisor_start_timeout:"))
+        return "attempt_process_supervisor_start_timeout";
+    return null;
+}
+function parseReadinessProbe(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const request = value;
+    const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+    const bounded = (candidate, maximum) => typeof candidate === "string" && candidate.trim().length > 0 && candidate.length <= maximum;
+    if (request.schemaVersion !== 1
+        || !uuid.test(request.requestId ?? "")
+        || !uuid.test(request.fencingToken ?? "")
+        || !uuid.test(request.userId ?? "")
+        || !uuid.test(request.projectId ?? "")
+        || !uuid.test(request.repoId ?? "")
+        || !uuid.test(request.runnerInstanceId ?? "")
+        || !Number.isInteger(request.attempt) || (request.attempt ?? 0) < 1
+        || !bounded(request.repoName, 160)
+        || typeof request.remoteUrl !== "string" || request.remoteUrl.length > 2048
+        || !bounded(request.defaultBranch, 512)
+        || typeof request.cloneOnDemand !== "boolean"
+        || !bounded(request.runnerRepoLocalPath, 4096)
+        || !bounded(request.revision, 512)
+        || !Number.isFinite(Date.parse(request.expiresAt ?? ""))
+        || Date.parse(request.expiresAt ?? "") <= Date.now()) {
+        return null;
+    }
+    return request;
+}
+function sandboxProviderNetworkFailure(dispatch, config) {
+    const sandbox = dispatch.sandbox;
+    if (!sandbox || sandbox.networkPolicy.mode !== "offline")
+        return null;
+    const provider = dispatch.execution.provider.trim().toLowerCase();
+    const isNetworkProvider = config.cliProviders.some(candidate => candidate.trim().toLowerCase() === provider);
+    if (!isNetworkProvider)
+        return null;
+    return `Provider ${dispatch.execution.provider} requires outbound network access, but this Docker attempt uses the offline network policy.`;
+}
 function sandboxAuthFailure(dispatch, config) {
     const unsupported = sandboxProviderAuthUnavailableMessage(dispatch.execution.provider, dispatch.execution.authKind);
     if (unsupported) {

package/dist/bridge/bridge.types.d.ts

@@ -63,6 +63,7 @@ export interface QaAppLaunchTarget {
     readonly command?: string | null;
     readonly working_directory?: string | null;
     readonly ready_url?: string | null;
+    readonly managed_runtime_port?: string | null;
     readonly routes?: readonly string[] | null;
     readonly notes?: string | null;
 }
@@ -85,6 +86,7 @@ export interface BridgeCapabilities {
     readonly sandboxRuntimes?: readonly string[] | null;
     readonly sandboxRuntimeVersion?: string | null;
     readonly sandboxFeatures?: SandboxFeatureMatrix | null;
+    readonly allowsOpenPublicSandbox?: boolean | null;
     readonly sandboxPublicationModes?: readonly string[] | null;
     readonly sandboxAuthModes?: Readonly<Record<string, readonly string[]>> | null;
     readonly maxConcurrentSandboxes?: number | null;
@@ -226,3 +228,38 @@ export type BridgeStartHandler = (dispatch: unknown) => Promise<void>;
 export type BridgeLeaseUpdateHandler = (request: BridgeLeaseUpdateRequest) => Promise<void>;
 export type BridgeCancelHandler = (request: BridgeCancelRequest) => Promise<void>;
 export type BridgeReapHandler = (request: BridgeReapRequest) => Promise<void>;
+export type BridgeReadinessProbeHandler = (request: unknown) => Promise<void>;
+export interface BridgeRuntimeReadinessRequest {
+    readonly schemaVersion: 1;
+    readonly requestId: string;
+    readonly fencingToken: string;
+    readonly userId: string;
+    readonly projectId: string;
+    readonly repoId: string;
+    readonly runnerInstanceId: string;
+    readonly attempt: number;
+    readonly repoName: string;
+    readonly remoteUrl: string;
+    readonly defaultBranch: string;
+    readonly cloneOnDemand: boolean;
+    readonly runnerRepoLocalPath: string;
+    readonly revision: string;
+    readonly expiresAt: string;
+}
+export interface BridgeRuntimeReadinessResult {
+    readonly schemaVersion: 1;
+    readonly requestId: string;
+    readonly fencingToken: string;
+    readonly runnerInstanceId: string;
+    readonly status: "parallel_ready" | "serialized" | "failed";
+    readonly runtimeContractFingerprint?: string | null;
+    readonly runtimeContractSource?: string | null;
+    readonly reasonCode?: string | null;
+    readonly reasonMessage?: string | null;
+    readonly qaAppLaunchTarget?: BridgeRuntimeReadinessQaLaunchTarget | null;
+    readonly checkedAt: string;
+}
+export interface BridgeRuntimeReadinessQaLaunchTarget {
+    readonly managedRuntimePort: string;
+    readonly routes: readonly string[];
+}

package/dist/cli/cli.help.js

@@ -194,7 +194,7 @@ export function commandHelpText(command) {
                 "Internal MCP server used by provider CLIs to report Forge phase artifacts.",
                 "",
                 "Usage:",
-                "  forge-bridge mcp --worktree <path> --work-item-id <id> --phase <phase>",
+                "  forge-bridge mcp --worktree <path> --work-item-id <id> --phase <phase>  # includes ci-repair",
                 "",
             ].join("\n");
         case "version":

package/dist/cli/cli.service.js

@@ -714,7 +714,7 @@ function parsePairArgs(argv) {
         name: name?.trim() || defaultName,
         fingerprint: fingerprint?.trim() || `local-bridge:${os.hostname()}:${user}`,
         repoRoot: repoRoot?.trim() ? path.resolve(repoRoot) : undefined,
-        cleanupWorktrees: cleanupWorktrees ?? localConfig.cleanupWorktrees ?? false,
+        cleanupWorktrees: cleanupWorktrees ?? defaultConfig.cleanupWorktrees,
         cliProviders: cliProviders.length > 0 ? cliProviders : localConfig.cliProviders && localConfig.cliProviders.length > 0 ? [...localConfig.cliProviders] : ["codex"],
         projectLabels: projectLabels.length > 0 ? projectLabels : localConfig.projectLabels ? [...localConfig.projectLabels] : []
     };

package/dist/cli/local-config.js

@@ -221,10 +221,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;
 }

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

@@ -1,15 +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 } from "./node-host-runtime-adapter.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

@@ -2,12 +2,14 @@ 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;
@@ -18,17 +20,39 @@ export class AttemptNodeRuntimeLauncher {
         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 child = await this.supervisor.startChild(childName, {
-            command: request.command,
-            args: request.args,
-            cwd: request.cwd,
-            env: request.environment,
-            captureOutput: false,
-        }, {
-            onStdoutLine: async (line) => await appendLine(stdoutPath, line),
-            onStderrLine: async (line) => await appendLine(stderrPath, line),
-        }, signal);
-        await child.ready;
+        const diagnostics = { exited: false, stdoutTail: "", stderrTail: "" };
+        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);
+                    await appendLine(stdoutPath, line);
+                },
+                onStderrLine: async (line) => {
+                    diagnostics.stderrTail = appendTail(diagnostics.stderrTail, line);
+                    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);
+        }, error => {
+            diagnostics.exited = true;
+            diagnostics.stderrTail = appendTail(diagnostics.stderrTail, error instanceof Error ? error.message : String(error));
+        });
         return child;
     }
     async inspectListener(child, request) {
@@ -37,6 +61,12 @@ export class AttemptNodeRuntimeLauncher {
     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}`;
@@ -48,3 +78,24 @@ function projectChildName(portName) {
 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.js

@@ -52,7 +52,7 @@ export class AttemptCoordinatedProviderProcessRunner {
         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.startChild("provider", request, handlers, signal);
+        const child = await supervisor.startChildReady("provider", request, handlers, signal, { maxStartAttempts: request.stdin === undefined ? 1 : 3, retryDelayMs: 100 });
         return await child.result;
     }
 }

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

@@ -43,6 +43,10 @@ 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
@@ -63,6 +67,14 @@ export declare class AttemptProcessSupervisor {
     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;