@loucompanion/forge-bridge 0.1.3-dev.fbe15023cdfe → 0.1.4-dev.41da3780c451

package/dist/runtime/host-runtime-promotion.d.ts

@@ -3,19 +3,28 @@ export interface HostParallelPromotionRecord {
     readonly schemaVersion: 1;
     readonly repoId: string;
     readonly runtimeContractFingerprint: string;
+    readonly inputCommitSha?: string | null;
+    readonly sourceFingerprint?: string;
     readonly runtimeContractSource?: "project" | "derived";
     readonly observedAt: string;
     readonly observedDispatchAttemptId: string;
     readonly verifiedPortNames: readonly string[];
 }
+export interface HostParallelProofIdentity {
+    readonly runtimeContractFingerprint: string;
+    readonly inputCommitSha: string;
+    readonly sourceFingerprint?: string;
+}
 /** Persists only observed, contract-bound host parallel-safety evidence. */
 export declare class HostParallelPromotionStore {
     private readonly stateRoot;
     constructor(stateRoot: string);
-    load(repoId: string): Promise<HostParallelPromotionRecord | null>;
+    load(repoId: string, identity?: HostParallelProofIdentity): Promise<HostParallelPromotionRecord | null>;
     list(): Promise<readonly HostParallelPromotionRecord[]>;
-    observe(repoId: string, runtimeContract: LoadedHostRuntimeContract, dispatchAttemptId: string, verifiedPortNames: readonly string[]): Promise<HostParallelPromotionRecord>;
-    invalidate(repoId: string): Promise<void>;
+    observe(repoId: string, runtimeContract: LoadedHostRuntimeContract, dispatchAttemptId: string, verifiedPortNames: readonly string[], inputCommitSha?: string, sourceFingerprint?: string): Promise<HostParallelPromotionRecord>;
+    private writeRecord;
+    private pruneVersions;
+    invalidate(repoId: string, scope?: "all" | "discovery"): Promise<void>;
     private recordPath;
 }
 export declare function hostRuntimeContractFingerprint(runtimeContract: LoadedHostRuntimeContract): string;

package/dist/runtime/host-runtime-promotion.js

@@ -1,4 +1,4 @@
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 /** Persists only observed, contract-bound host parallel-safety evidence. */
@@ -7,11 +7,12 @@ export class HostParallelPromotionStore {
     constructor(stateRoot) {
         this.stateRoot = stateRoot;
     }
-    async load(repoId) {
+    async load(repoId, identity) {
         const normalizedRepoId = normalizeRepoId(repoId);
         try {
-            const parsed = JSON.parse(await fs.readFile(this.recordPath(normalizedRepoId), "utf8"));
-            return validRecord(parsed, normalizedRepoId) ? parsed : null;
+            const parsed = JSON.parse(await fs.readFile(this.recordPath(normalizedRepoId, identity), "utf8"));
+            return validRecord(parsed, normalizedRepoId)
+                && (!identity || matchesIdentity(parsed, identity)) ? parsed : null;
         }
         catch (error) {
             if (error.code === "ENOENT" || error instanceof SyntaxError)
@@ -45,7 +46,7 @@ export class HostParallelPromotionStore {
         }
         return records.sort((left, right) => left.repoId.localeCompare(right.repoId));
     }
-    async observe(repoId, runtimeContract, dispatchAttemptId, verifiedPortNames) {
+    async observe(repoId, runtimeContract, dispatchAttemptId, verifiedPortNames, inputCommitSha, sourceFingerprint) {
         if (!hostRuntimeParallelEligible(runtimeContract)) {
             throw new Error("host_parallel_promotion_ineligible: the runtime contract is not eligible for parallel host execution.");
         }
@@ -60,15 +61,26 @@ export class HostParallelPromotionStore {
             schemaVersion: 1,
             repoId: normalizedRepoId,
             runtimeContractFingerprint: hostRuntimeContractFingerprint(runtimeContract),
+            inputCommitSha: inputCommitSha ?? null,
+            ...(sourceFingerprint ? { sourceFingerprint } : {}),
             runtimeContractSource: runtimeContract.source === "project" ? "project" : "derived",
             observedAt: new Date().toISOString(),
             observedDispatchAttemptId: normalizedUuid(dispatchAttemptId, "dispatch attempt"),
             verifiedPortNames: observedPorts,
         };
-        const target = this.recordPath(normalizedRepoId);
+        if (inputCommitSha) {
+            await this.writeRecord(this.recordPath(normalizedRepoId, {
+                runtimeContractFingerprint: record.runtimeContractFingerprint, inputCommitSha, sourceFingerprint,
+            }), record);
+        }
+        await this.writeRecord(this.recordPath(normalizedRepoId), record);
+        await this.pruneVersions(normalizedRepoId);
+        return record;
+    }
+    async writeRecord(target, record) {
         const root = path.dirname(target);
         await ensurePrivateDirectory(root);
-        const temporary = `${target}.${process.pid}.${Date.now()}.tmp`;
+        const temporary = `${target}.${randomUUID()}.tmp`;
         try {
             const handle = await fs.open(temporary, "wx", 0o600);
             try {
@@ -79,21 +91,56 @@ export class HostParallelPromotionStore {
                 await handle.close();
             }
             await fs.rename(temporary, target);
-            return record;
         }
         catch (error) {
             await fs.rm(temporary, { force: true }).catch(() => undefined);
             throw error;
         }
     }
-    async invalidate(repoId) {
-        await fs.rm(this.recordPath(normalizeRepoId(repoId)), { force: true });
+    async pruneVersions(repoId) {
+        const target = this.recordPath(repoId);
+        const root = path.dirname(target);
+        const prefix = path.basename(target, ".json") + ".";
+        const versions = (await fs.readdir(root)).filter(name => name.startsWith(prefix)
+            && /^[0-9a-f]{64}\.[0-9a-f]{64}\.json$/u.test(name));
+        if (versions.length <= 128)
+            return;
+        const dated = await Promise.all(versions.map(async (name) => ({ name,
+            at: await fs.stat(path.join(root, name)).then(stat => stat.mtimeMs, () => Number.MAX_SAFE_INTEGER) })));
+        for (const entry of dated.sort((a, b) => b.at - a.at).slice(128)) {
+            await fs.rm(path.join(root, entry.name), { force: true });
+        }
+    }
+    async invalidate(repoId, scope = "all") {
+        const target = this.recordPath(normalizeRepoId(repoId));
+        await fs.rm(target, { force: true });
+        // Background/default-branch discovery must not erase proofs bound to other
+        // prepared sources. Actual containment/cleanup degradation invalidates all.
+        if (scope === "discovery")
+            return;
+        const prefix = path.basename(target, ".json") + ".";
+        const entries = await fs.readdir(path.dirname(target)).catch((error) => {
+            if (error.code === "ENOENT")
+                return [];
+            throw error;
+        });
+        for (const entry of entries.filter(name => name.startsWith(prefix) && /^[0-9a-f]{64}\.[0-9a-f]{64}\.json$/u.test(name))) {
+            await fs.rm(path.join(path.dirname(target), entry), { force: true });
+        }
     }
-    recordPath(normalizedRepoId) {
+    recordPath(normalizedRepoId, identity) {
         const key = createHash("sha256").update(normalizedRepoId).digest("hex");
-        return path.join(this.stateRoot, "runtime-promotion", "host", `${key}.json`);
+        const version = identity ? `.${createHash("sha256").update(JSON.stringify([
+            identity.runtimeContractFingerprint, identity.inputCommitSha, identity.sourceFingerprint ?? null,
+        ])).digest("hex")}` : "";
+        return path.join(this.stateRoot, "runtime-promotion", "host", `${key}${version}.json`);
     }
 }
+function matchesIdentity(record, identity) {
+    return record.runtimeContractFingerprint === identity.runtimeContractFingerprint
+        && record.inputCommitSha === identity.inputCommitSha
+        && record.sourceFingerprint === identity.sourceFingerprint;
+}
 export function hostRuntimeContractFingerprint(runtimeContract) {
     const canonical = JSON.stringify({
         schemaVersion: runtimeContract.contract.schemaVersion,

package/dist/runtime/memory-capacity.d.ts

@@ -0,0 +1,70 @@
+export declare const memoryAdmissionPolicyVersion = "memory-admission-v2";
+export declare const memoryAdmissionEquation = "max(0, min(stabilized_available - reserve - pending_commitment, total - reserve - committed))";
+export interface MemoryAdmissionDiagnostics {
+    readonly policyVersion: string;
+    readonly sampledAt: string;
+    readonly totalMemoryBytes: number;
+    readonly rawAvailableMemoryBytes: number;
+    readonly stabilizedAvailableMemoryBytes: number;
+    readonly reclaimableMemoryBytes: number | null;
+    readonly reclaimableMemorySource: "not_sampled_separately";
+    readonly controlPlaneMemoryBytes: number;
+    readonly reserveMemoryBytes: number;
+    readonly committedMemoryBytes: number;
+    readonly pendingCommitmentMemoryBytes: number;
+    readonly availableForAdmissionBytes: number;
+    readonly requestedMemoryBytes: number | null;
+    readonly shortfallMemoryBytes: number | null;
+    readonly decision: "snapshot" | "admitted" | "denied";
+    readonly equation: string;
+}
+export interface MemoryAdmissionInputs {
+    readonly sampledAt: string;
+    readonly totalMemoryBytes: number;
+    readonly rawAvailableMemoryBytes: number;
+    readonly stabilizedAvailableMemoryBytes: number;
+    readonly controlPlaneMemoryBytes: number;
+    readonly reserveMemoryBytes: number;
+    /** Every committed Forge request, including pending requests. */
+    readonly committedMemoryBytes: number;
+    /** Commitments not yet reflected in the OS available-memory sample. */
+    readonly pendingCommitmentMemoryBytes: number;
+    readonly requestedMemoryBytes?: number | null;
+}
+/**
+ * One memory admission equation for Docker and managed-host capacity. The raw
+ * OS/daemon sample already reflects resident active children, so only pending
+ * commitments are charged against sampled headroom. Ambient host use must not
+ * also be folded into committedMemoryBytes: it is already reflected in the OS
+ * sample, and doing both permanently double-charges long-lived host processes.
+ * The total-memory ceiling independently caps Forge's own reservations.
+ */
+export declare function buildMemoryAdmissionDiagnostics(inputs: MemoryAdmissionInputs): MemoryAdmissionDiagnostics;
+export interface AdaptiveMemoryReserveOptions {
+    readonly explicitBytes?: number | null;
+    readonly floorBytes?: number | null;
+    readonly ceilingBytes?: number | null;
+    readonly percent?: number | null;
+}
+/**
+ * Derives a host safety reserve from the capacity domain it protects. An
+ * explicit operator value remains authoritative; otherwise the reserve scales
+ * with the sampled total inside conservative floors and ceilings.
+ */
+export declare function resolveAdaptiveMemoryReserveBytes(totalMemoryBytes: number, options?: AdaptiveMemoryReserveOptions): number;
+/**
+ * Applies pressure immediately while requiring durable recovery samples before
+ * increasing advertised capacity. This prevents one GC/cache sample from
+ * waking queued work and then immediately withdrawing the same capacity.
+ */
+export declare class RecoveryStabilizedMemory {
+    private readonly requiredRecoverySamples;
+    private readonly minimumRecoverySampleIntervalMs;
+    private stableBytes;
+    private recoveryFloorBytes;
+    private recoverySamples;
+    private lastRecoverySampleAt;
+    constructor(requiredRecoverySamples?: number, minimumRecoverySampleIntervalMs?: number);
+    observe(rawAvailableBytes: number, sampledAt?: number): number;
+    private resetRecovery;
+}

package/dist/runtime/memory-capacity.js

@@ -0,0 +1,123 @@
+const GiB = 1024 ** 3;
+export const memoryAdmissionPolicyVersion = "memory-admission-v2";
+export const memoryAdmissionEquation = "max(0, min(stabilized_available - reserve - pending_commitment, total - reserve - committed))";
+/**
+ * One memory admission equation for Docker and managed-host capacity. The raw
+ * OS/daemon sample already reflects resident active children, so only pending
+ * commitments are charged against sampled headroom. Ambient host use must not
+ * also be folded into committedMemoryBytes: it is already reflected in the OS
+ * sample, and doing both permanently double-charges long-lived host processes.
+ * The total-memory ceiling independently caps Forge's own reservations.
+ */
+export function buildMemoryAdmissionDiagnostics(inputs) {
+    const totalMemoryBytes = nonNegativeInteger(inputs.totalMemoryBytes);
+    const rawAvailableMemoryBytes = nonNegativeInteger(inputs.rawAvailableMemoryBytes);
+    const stabilizedAvailableMemoryBytes = nonNegativeInteger(inputs.stabilizedAvailableMemoryBytes);
+    const reserveMemoryBytes = nonNegativeInteger(inputs.reserveMemoryBytes);
+    const committedMemoryBytes = nonNegativeInteger(inputs.committedMemoryBytes);
+    const pendingCommitmentMemoryBytes = Math.min(committedMemoryBytes, nonNegativeInteger(inputs.pendingCommitmentMemoryBytes));
+    const requestedMemoryBytes = inputs.requestedMemoryBytes == null
+        ? null
+        : nonNegativeInteger(inputs.requestedMemoryBytes);
+    const availableForAdmissionBytes = Math.max(0, Math.min(stabilizedAvailableMemoryBytes - reserveMemoryBytes - pendingCommitmentMemoryBytes, totalMemoryBytes - reserveMemoryBytes - committedMemoryBytes));
+    const shortfallMemoryBytes = requestedMemoryBytes === null
+        ? null
+        : Math.max(0, requestedMemoryBytes - availableForAdmissionBytes);
+    return {
+        policyVersion: memoryAdmissionPolicyVersion,
+        sampledAt: inputs.sampledAt,
+        totalMemoryBytes,
+        rawAvailableMemoryBytes,
+        stabilizedAvailableMemoryBytes,
+        reclaimableMemoryBytes: null,
+        reclaimableMemorySource: "not_sampled_separately",
+        controlPlaneMemoryBytes: nonNegativeInteger(inputs.controlPlaneMemoryBytes),
+        reserveMemoryBytes,
+        committedMemoryBytes,
+        pendingCommitmentMemoryBytes,
+        availableForAdmissionBytes,
+        requestedMemoryBytes,
+        shortfallMemoryBytes,
+        decision: requestedMemoryBytes === null
+            ? "snapshot"
+            : shortfallMemoryBytes === 0 ? "admitted" : "denied",
+        equation: memoryAdmissionEquation,
+    };
+}
+/**
+ * Derives a host safety reserve from the capacity domain it protects. An
+ * explicit operator value remains authoritative; otherwise the reserve scales
+ * with the sampled total inside conservative floors and ceilings.
+ */
+export function resolveAdaptiveMemoryReserveBytes(totalMemoryBytes, options = {}) {
+    const explicit = positiveInteger(options.explicitBytes);
+    if (explicit !== null)
+        return explicit;
+    const total = Math.max(0, finiteInteger(totalMemoryBytes));
+    const floor = positiveInteger(options.floorBytes) ?? GiB;
+    const ceiling = Math.max(floor, positiveInteger(options.ceilingBytes) ?? 4 * GiB);
+    const percent = positiveNumber(options.percent) ?? 12.5;
+    const proportional = Math.floor(total * Math.min(50, percent) / 100);
+    return Math.max(floor, Math.min(ceiling, proportional));
+}
+/**
+ * Applies pressure immediately while requiring durable recovery samples before
+ * increasing advertised capacity. This prevents one GC/cache sample from
+ * waking queued work and then immediately withdrawing the same capacity.
+ */
+export class RecoveryStabilizedMemory {
+    requiredRecoverySamples;
+    minimumRecoverySampleIntervalMs;
+    stableBytes = null;
+    recoveryFloorBytes = null;
+    recoverySamples = 0;
+    lastRecoverySampleAt = null;
+    constructor(requiredRecoverySamples = 2, minimumRecoverySampleIntervalMs = 1_000) {
+        this.requiredRecoverySamples = requiredRecoverySamples;
+        this.minimumRecoverySampleIntervalMs = minimumRecoverySampleIntervalMs;
+    }
+    observe(rawAvailableBytes, sampledAt = Date.now()) {
+        const observed = Math.max(0, finiteInteger(rawAvailableBytes));
+        if (this.stableBytes === null) {
+            this.stableBytes = observed;
+            return observed;
+        }
+        if (observed <= this.stableBytes) {
+            this.stableBytes = observed;
+            this.resetRecovery();
+            return observed;
+        }
+        this.recoveryFloorBytes = this.recoveryFloorBytes === null
+            ? observed
+            : Math.min(this.recoveryFloorBytes, observed);
+        if (this.lastRecoverySampleAt !== null
+            && sampledAt - this.lastRecoverySampleAt < Math.max(0, this.minimumRecoverySampleIntervalMs)) {
+            return this.stableBytes;
+        }
+        this.recoverySamples += 1;
+        this.lastRecoverySampleAt = sampledAt;
+        if (this.recoverySamples < Math.max(1, this.requiredRecoverySamples)) {
+            return this.stableBytes;
+        }
+        this.stableBytes = this.recoveryFloorBytes ?? this.stableBytes;
+        this.resetRecovery();
+        return this.stableBytes;
+    }
+    resetRecovery() {
+        this.recoveryFloorBytes = null;
+        this.recoverySamples = 0;
+        this.lastRecoverySampleAt = null;
+    }
+}
+function finiteInteger(value) {
+    return Number.isFinite(value) ? Math.floor(value) : 0;
+}
+function positiveInteger(value) {
+    return Number.isFinite(value) && value > 0 ? Math.floor(value) : null;
+}
+function positiveNumber(value) {
+    return Number.isFinite(value) && value > 0 ? value : null;
+}
+function nonNegativeInteger(value) {
+    return Number.isFinite(value) ? Math.max(0, Math.floor(value)) : 0;
+}

package/dist/runtime/native-test-postgres-fallback.d.ts

@@ -0,0 +1,25 @@
+export declare const nativeTestPostgresFallbackConfigEnvironment = "FORGE_NATIVE_TEST_POSTGRES_CONFIG";
+export declare const nativeTestPostgresFallbackFileName = "native-test-postgres.json";
+export declare const nativeTestPostgresFallbackDatabaseMode = "native_fallback";
+/**
+ * A dedicated, operator-provisioned PostgreSQL cluster that runner-authored .NET
+ * test tiers may use only while the Docker engine is unavailable. The cluster
+ * must hold nothing but disposable test databases, so its capability carries no
+ * more authority than the attempt-private container it replaces.
+ */
+export interface NativeTestPostgresFallback {
+    readonly connectionString: string;
+    readonly endpoint: string;
+}
+export declare class NativeTestPostgresFallbackError extends Error {
+    readonly code = "native_test_postgres_fallback_invalid";
+    constructor(detail: string);
+}
+export declare function resolveNativeTestPostgresFallbackPath(): string;
+/** The operator's fallback file when one has been provisioned on this host. */
+export declare function configuredNativeTestPostgresFallbackPath(): string | null;
+/** Returns null when no fallback is configured; throws when one is configured unsafely. */
+export declare function readNativeTestPostgresFallback(configPath?: string): NativeTestPostgresFallback | null;
+export declare function parseNativeTestPostgresFallback(connectionString: string): NativeTestPostgresFallback;
+/** Environment for one runner-authored .NET test process using the fallback. */
+export declare function nativeTestPostgresFallbackEnvironment(fallback: NativeTestPostgresFallback): Readonly<Record<string, string>>;

package/dist/runtime/native-test-postgres-fallback.js

@@ -0,0 +1,91 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveLocalConfigPath } from "../cli/local-config.js";
+import { hostRuntimeLegacyTestPostgresEnvironment, hostRuntimeTestPostgresAdminEnvironment, } from "./host-runtime-contract.js";
+export const nativeTestPostgresFallbackConfigEnvironment = "FORGE_NATIVE_TEST_POSTGRES_CONFIG";
+export const nativeTestPostgresFallbackFileName = "native-test-postgres.json";
+export const nativeTestPostgresFallbackDatabaseMode = "native_fallback";
+const defaultPostgresPort = 5432;
+const loopbackHosts = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+export class NativeTestPostgresFallbackError extends Error {
+    code = "native_test_postgres_fallback_invalid";
+    constructor(detail) {
+        super(`native_test_postgres_fallback_invalid: ${detail}`);
+        this.name = "NativeTestPostgresFallbackError";
+    }
+}
+export function resolveNativeTestPostgresFallbackPath() {
+    const configured = process.env[nativeTestPostgresFallbackConfigEnvironment]?.trim();
+    return configured
+        ? path.resolve(configured)
+        : path.join(path.dirname(resolveLocalConfigPath()), nativeTestPostgresFallbackFileName);
+}
+/** The operator's fallback file when one has been provisioned on this host. */
+export function configuredNativeTestPostgresFallbackPath() {
+    const configPath = resolveNativeTestPostgresFallbackPath();
+    return fs.existsSync(configPath) ? configPath : null;
+}
+/** Returns null when no fallback is configured; throws when one is configured unsafely. */
+export function readNativeTestPostgresFallback(configPath = resolveNativeTestPostgresFallbackPath()) {
+    let raw;
+    try {
+        raw = fs.readFileSync(configPath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    let document;
+    try {
+        document = JSON.parse(raw);
+    }
+    catch {
+        throw new NativeTestPostgresFallbackError(`${configPath} is not valid JSON.`);
+    }
+    if (document.schemaVersion !== 1 || typeof document.connectionString !== "string") {
+        throw new NativeTestPostgresFallbackError(`${configPath} must contain schemaVersion 1 and a connectionString.`);
+    }
+    return parseNativeTestPostgresFallback(document.connectionString);
+}
+export function parseNativeTestPostgresFallback(connectionString) {
+    const fields = new Map();
+    for (const segment of connectionString.split(";")) {
+        const separator = segment.indexOf("=");
+        if (separator <= 0)
+            continue;
+        fields.set(segment.slice(0, separator).trim().toLowerCase().replaceAll(" ", ""), segment.slice(separator + 1).trim());
+    }
+    const host = (fields.get("host") ?? fields.get("server") ?? "").toLowerCase();
+    if (!loopbackHosts.has(host)) {
+        throw new NativeTestPostgresFallbackError("the fallback must use a single loopback host.");
+    }
+    const database = (fields.get("database") ?? fields.get("db") ?? fields.get("initialcatalog") ?? "").toLowerCase();
+    if (database !== "postgres") {
+        throw new NativeTestPostgresFallbackError("the fallback must connect to the 'postgres' administrative database.");
+    }
+    if (fields.get("searchpath")) {
+        throw new NativeTestPostgresFallbackError("the fallback must not set a search path.");
+    }
+    const port = Number.parseInt(fields.get("port") ?? "", 10);
+    if (!Number.isInteger(port) || port <= 0 || port > 65_535) {
+        throw new NativeTestPostgresFallbackError("the fallback must name an explicit port.");
+    }
+    if (port === defaultPostgresPort) {
+        // The default port is where developer databases live; a dedicated test
+        // cluster must be provisioned on its own port.
+        throw new NativeTestPostgresFallbackError(`the fallback must not use the default PostgreSQL port ${defaultPostgresPort}; provision a dedicated test cluster.`);
+    }
+    if (!(fields.get("username") ?? fields.get("userid") ?? fields.get("user"))) {
+        throw new NativeTestPostgresFallbackError("the fallback must name a dedicated test role.");
+    }
+    return { connectionString: connectionString.trim(), endpoint: `${host}:${port}` };
+}
+/** Environment for one runner-authored .NET test process using the fallback. */
+export function nativeTestPostgresFallbackEnvironment(fallback) {
+    return {
+        [hostRuntimeTestPostgresAdminEnvironment]: fallback.connectionString,
+        [hostRuntimeLegacyTestPostgresEnvironment]: fallback.connectionString,
+        FORGE_MANAGED_VERIFICATION_DATABASE_MODE: nativeTestPostgresFallbackDatabaseMode,
+    };
+}

package/dist/runtime/node-host-runtime-adapter.d.ts

@@ -23,9 +23,11 @@ export interface NodeRuntimeReadinessDiagnostics {
     readonly exitCode?: number;
     readonly stdoutTail?: string;
     readonly stderrTail?: string;
+    readonly outputRevision?: number;
 }
 export interface NodeHostRuntimeAdapterOptions {
     readonly readinessTimeoutMs?: number;
+    readonly hardReadinessTimeoutMs?: number;
     readonly readinessPollIntervalMs?: number;
     readonly httpProbeTimeoutMs?: number;
     readonly probeHttp?: (url: string, timeoutMs: number, signal?: AbortSignal) => Promise<boolean>;
@@ -41,6 +43,7 @@ export interface NodeRuntimeAdapterLaunch<T> extends HostPortLaunch<T> {
 export declare class NodeHostRuntimeAdapter {
     private readonly broker;
     private readonly readinessTimeoutMs;
+    private readonly hardReadinessTimeoutMs;
     private readonly readinessPollIntervalMs;
     private readonly httpProbeTimeoutMs;
     private readonly probeHttp;

package/dist/runtime/node-host-runtime-adapter.js

@@ -1,5 +1,8 @@
 import path from "node:path";
+import { ForgeFailureError } from "../session/session.types.js";
+import { withAspNetPrebuiltRunArguments } from "./aspnet-runtime-prebuild.js";
 import { hostPortEnvironment, } from "./host-runtime-contract.js";
+import { monotonicNowMs } from "../shared/time/monotonic.js";
 /**
  * Launches an explicitly configured HTTP project command beneath the caller's
  * attempt supervisor. It never shells a command and never promotes a project
@@ -8,12 +11,14 @@ import { hostPortEnvironment, } from "./host-runtime-contract.js";
 export class NodeHostRuntimeAdapter {
     broker;
     readinessTimeoutMs;
+    hardReadinessTimeoutMs;
     readinessPollIntervalMs;
     httpProbeTimeoutMs;
     probeHttp;
     constructor(broker, options = {}) {
         this.broker = broker;
         this.readinessTimeoutMs = boundedInteger(options.readinessTimeoutMs ?? 120_000, 100, 120_000, "readinessTimeoutMs");
+        this.hardReadinessTimeoutMs = boundedInteger(options.hardReadinessTimeoutMs ?? 600_000, this.readinessTimeoutMs, 900_000, "hardReadinessTimeoutMs");
         this.readinessPollIntervalMs = boundedInteger(options.readinessPollIntervalMs ?? 100, 10, 5_000, "readinessPollIntervalMs");
         this.httpProbeTimeoutMs = boundedInteger(options.httpProbeTimeoutMs ?? 1_000, 50, 10_000, "httpProbeTimeoutMs");
         this.probeHttp = options.probeHttp ?? probeHttpReadiness;
@@ -49,14 +54,21 @@ export class NodeHostRuntimeAdapter {
         return { ...launched, request: activeRequest };
     }
     async waitUntilReady(value, request, launcher, signal) {
-        const deadline = Date.now() + this.readinessTimeoutMs;
+        const startedAt = monotonicNowMs();
+        const hardDeadline = startedAt + this.hardReadinessTimeoutMs;
+        let idleDeadline = startedAt + this.readinessTimeoutMs;
+        let outputRevision = -1;
         let observedOwnership = "unbound";
-        while (Date.now() <= deadline) {
+        while (monotonicNowMs() <= idleDeadline && monotonicNowMs() <= hardDeadline) {
             if (signal?.aborted)
                 throw cancellationError(signal);
             const diagnostics = await launcher.readinessDiagnostics?.(value);
             if (diagnostics?.exited) {
-                throw new Error(readinessFailure("host_runtime_process_exited", `the supervised process exited with code ${diagnostics.exitCode ?? "unknown"} before its assigned runtime became ready`, request, diagnostics));
+                throw new ForgeFailureError("host_runtime_process_exited", readinessFailure("host_runtime_process_exited", `the supervised process exited with code ${diagnostics.exitCode ?? "unknown"} before its assigned runtime became ready`, request, diagnostics), "bridge");
+            }
+            if (diagnostics?.outputRevision !== undefined && diagnostics.outputRevision > outputRevision) {
+                outputRevision = diagnostics.outputRevision;
+                idleDeadline = Math.min(hardDeadline, monotonicNowMs() + this.readinessTimeoutMs);
             }
             const ownership = await launcher.inspectListener(value, request, signal);
             observedOwnership = ownership;
@@ -69,15 +81,20 @@ export class NodeHostRuntimeAdapter {
         }
         const diagnostics = await launcher.readinessDiagnostics?.(value);
         if (diagnostics?.exited) {
-            throw new Error(readinessFailure("host_runtime_process_exited", `the supervised process exited with code ${diagnostics.exitCode ?? "unknown"} before its assigned runtime became ready`, request, diagnostics));
+            throw new ForgeFailureError("host_runtime_process_exited", readinessFailure("host_runtime_process_exited", `the supervised process exited with code ${diagnostics.exitCode ?? "unknown"} before its assigned runtime became ready`, request, diagnostics), "bridge");
         }
         const code = observedOwnership === "owned"
             ? "host_runtime_http_readiness_timeout"
             : "host_runtime_listener_timeout";
+        const reachedHardDeadline = monotonicNowMs() >= hardDeadline;
         const detail = observedOwnership === "owned"
-            ? `the supervised process owned its assigned loopback port but HTTP readiness did not succeed within ${this.readinessTimeoutMs}ms`
-            : `the supervised process did not bind its assigned loopback port within ${this.readinessTimeoutMs}ms`;
-        throw new Error(readinessFailure(code, detail, request, diagnostics));
+            ? reachedHardDeadline
+                ? `the supervised process owned its assigned loopback port but HTTP readiness did not succeed within the ${this.hardReadinessTimeoutMs}ms hard limit`
+                : `the supervised process owned its assigned loopback port but made no readiness progress for ${this.readinessTimeoutMs}ms`
+            : reachedHardDeadline
+                ? `the supervised process did not bind its assigned loopback port within the ${this.hardReadinessTimeoutMs}ms hard limit`
+                : `the supervised process did not bind its assigned loopback port and made no output progress for ${this.readinessTimeoutMs}ms`;
+        throw new ForgeFailureError(code, readinessFailure(code, detail, request, diagnostics), "bridge");
     }
 }
 function readinessFailure(code, detail, request, diagnostics) {
@@ -195,15 +212,16 @@ function aspNetCoreArguments(command, args) {
     if (args[0]?.toLowerCase() !== "run") {
         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 prebuiltArgs = withAspNetPrebuiltRunArguments(command, args);
+    const applicationArguments = prebuiltArgs.indexOf("--");
+    const insertionIndex = applicationArguments < 0 ? prebuiltArgs.length : applicationArguments;
     return [
-        ...args.slice(0, insertionIndex),
+        ...prebuiltArgs.slice(0, insertionIndex),
         "--disable-build-servers",
         "-p:UseSharedCompilation=false",
         "-p:DefaultItemExcludesInProjectFolder=TestResults/**",
         "--no-launch-profile",
-        ...args.slice(insertionIndex),
+        ...prebuiltArgs.slice(insertionIndex),
     ];
 }
 function validateCommand(command) {

package/dist/runtime/pinned-directory-process.d.ts

@@ -0,0 +1,9 @@
+import type { BigIntStats } from "node:fs";
+export type PinnedDirectoryIdentity = Pick<BigIntStats, "dev" | "ino">;
+export declare class PinnedDirectoryProcessError extends Error {
+    readonly failureKind: "failed" | "timeout";
+    readonly terminationConfirmed: boolean;
+    constructor(message: string, failureKind: "failed" | "timeout", options?: ErrorOptions, terminationConfirmed?: boolean);
+}
+/** Keep filesystem stalls off the Bridge event loop. The worker pins and checks cwd. */
+export declare function runPinnedDirectoryProcess(parent: string, identity: PinnedDirectoryIdentity, worker: string, operation: object, bytes?: Buffer, maxBuffer?: number, timeoutMs?: number, terminationConfirmationMs?: number): Promise<string>;

package/dist/runtime/pinned-directory-process.js

@@ -0,0 +1,61 @@
+import childProcess from "node:child_process";
+export class PinnedDirectoryProcessError extends Error {
+    failureKind;
+    terminationConfirmed;
+    constructor(message, failureKind, options, terminationConfirmed = true) {
+        super(`pinned_directory_operation_${failureKind}: ${message}`, options);
+        this.failureKind = failureKind;
+        this.terminationConfirmed = terminationConfirmed;
+        this.name = "PinnedDirectoryProcessError";
+    }
+}
+/** Keep filesystem stalls off the Bridge event loop. The worker pins and checks cwd. */
+export async function runPinnedDirectoryProcess(parent, identity, worker, operation, bytes, maxBuffer = 16 * 1024, timeoutMs = 30_000, terminationConfirmationMs = 2_000) {
+    const environment = { ...process.env };
+    delete environment.NODE_OPTIONS;
+    const header = `${JSON.stringify({ parent, dev: identity.dev.toString(), ino: identity.ino.toString(), ...operation })}\n`;
+    return await new Promise((resolve, reject) => {
+        let settled = false;
+        let timedOut = false;
+        const deadline = { timer: undefined };
+        const termination = { timer: undefined };
+        const child = childProcess.execFile(process.execPath, ["--input-type=commonjs", "-e", worker], {
+            cwd: parent, env: environment, windowsHide: true, maxBuffer,
+        }, (error, stdout, stderr) => {
+            if (settled)
+                return;
+            settled = true;
+            if (deadline.timer)
+                clearTimeout(deadline.timer);
+            if (termination.timer)
+                clearTimeout(termination.timer);
+            if (timedOut) {
+                reject(new PinnedDirectoryProcessError(`operation exceeded ${timeoutMs} ms`, "timeout", error ? { cause: error } : undefined));
+                return;
+            }
+            if (error) {
+                reject(new PinnedDirectoryProcessError(stderr.trim() || error.message, "failed", { cause: error }));
+            }
+            else
+                resolve(stdout);
+        });
+        deadline.timer = setTimeout(() => {
+            if (settled)
+                return;
+            timedOut = true;
+            child.kill("SIGKILL");
+            // Wait for execFile's callback so callers know the helper has released
+            // its pinned cwd before they remove attempt state. A mocked or wedged
+            // child still gets one bounded post-kill confirmation window.
+            termination.timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                reject(new PinnedDirectoryProcessError(`operation exceeded ${timeoutMs} ms and termination was not confirmed`, "timeout", undefined, false));
+            }, terminationConfirmationMs);
+        }, timeoutMs);
+        child.stdin.on("error", () => undefined);
+        child.stdin.write(header);
+        child.stdin.end(bytes);
+    });
+}