@loucompanion/forge-bridge 0.1.3-dev.fbe15023cdfe → 0.1.4-dev.1ff37038366e

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

@@ -2,55 +2,89 @@ import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { isAlias, parseDocument, visit } from "yaml";
+import { readCanonicalSourceFile } from "./canonical-source-file.js";
+import { isGeneratedOutputDirectoryName } from "./generated-output-reset.js";
 export const hostRuntimeContractPath = ".forge/forge.runtime.yml";
+export const hostRuntimeTestPostgresAdminEnvironment = "FORGE_TEST_POSTGRES_ADMIN_CONNECTION_STRING";
+export const hostRuntimeLegacyTestPostgresEnvironment = "FORGE_TEST_POSTGRES_CONNECTION_STRING";
 const maximumContractBytes = 64 * 1024;
 const maximumDepth = 12;
+// Every discovery scan stops after this many directory entries. A monorepo needs a few
+// thousand; the bound only keeps a pathological tree from stalling attempt preparation.
+const maximumDiscoveryEntries = 20_000;
+/**
+ * A discovery scan reached its entry budget before seeing the whole tree, so what it did not
+ * find may still exist. Discovery must not treat that as absence: a partial runtime (for
+ * example a web app without its API) would send the attempt's traffic to the wrong server.
+ */
+class IncompleteRuntimeDiscoveryError extends Error {
+}
+// Dependency, build and editor folders never hold an application entrypoint, and counting
+// them would exhaust the budget and serialize a repository for no reason.
 const ignoredDiscoveryDirectories = new Set([
     ".forge",
     ".forge-designer",
     ".git",
+    ".gradle",
+    ".idea",
     ".local",
+    ".next",
+    ".pnpm",
+    ".turbo",
+    ".venv",
+    ".vs",
+    ".vscode",
+    ".yarn",
     "bin",
+    "build",
     "coverage",
     "dist",
     "node_modules",
     "obj",
+    "target",
+    "vendor",
+    "venv",
 ]);
 const topLevelKeys = new Set(["schemaVersion", "runtime"]);
 const runtimeKeys = new Set(["hostConcurrency", "ports", "playwright", "browserProfile", "singletonResources"]);
 const portKeys = new Set(["adapter", "launch", "env", "baseUrlEnv", "format"]);
 const launchKeys = new Set(["command", "args", "workingDirectory", "environment"]);
 const playwrightKeys = new Set(["config", "baseUrlPort", "workers"]);
-export async function loadHostRuntimeContract(worktreePath) {
+export async function loadHostRuntimeContract(worktreePath, snapshot, directorySnapshot) {
+    worktreePath = await fs.realpath(worktreePath);
     const target = path.join(path.resolve(worktreePath), hostRuntimeContractPath);
-    let targetStat;
+    let source;
     try {
-        targetStat = await fs.stat(target);
+        const captured = snapshot ? await snapshot(target) : await readCanonicalSourceFile(target, maximumContractBytes);
+        if (captured === null)
+            return await discoverHostRuntimeContract(worktreePath, snapshot, directorySnapshot);
+        source = captured;
     }
     catch (error) {
         if (isFileNotFound(error))
-            return await discoverHostRuntimeContract(worktreePath);
+            return await discoverHostRuntimeContract(worktreePath, snapshot, directorySnapshot);
         throw error;
     }
-    if (!targetStat.isFile() || targetStat.size < 1 || targetStat.size > maximumContractBytes) {
-        throw new Error(`runtime_contract_invalid: forge.runtime.yml must be a regular 1-${maximumContractBytes} byte file.`);
-    }
-    const [realWorktree, realTarget] = await Promise.all([fs.realpath(worktreePath), fs.realpath(target)]);
-    const relative = path.relative(realWorktree, realTarget);
-    if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
-        throw new Error("runtime_contract_invalid: forge.runtime.yml must remain inside the prepared worktree.");
-    }
     return {
-        contract: validateHostRuntimeContract(await fs.readFile(realTarget, "utf8")),
+        contract: validateHostRuntimeContract(source.toString("utf8")),
         source: "project",
     };
 }
-async function discoverHostRuntimeContract(worktreePath) {
+async function discoverHostRuntimeContract(worktreePath, snapshot, directorySnapshot) {
     const root = path.resolve(worktreePath);
-    const [nodeDiscovery, aspNetDiscovery] = await Promise.all([
-        discoverNodeRuntimes(root),
-        discoverAspNetRuntimes(root),
-    ]);
+    let nodeDiscovery;
+    let aspNetDiscovery;
+    try {
+        [nodeDiscovery, aspNetDiscovery] = await Promise.all([
+            discoverNodeRuntimes(root, snapshot, directorySnapshot),
+            discoverAspNetRuntimes(root, snapshot, directorySnapshot),
+        ]);
+    }
+    catch (error) {
+        if (error instanceof IncompleteRuntimeDiscoveryError)
+            return incompleteRuntimeDiscovery();
+        throw error;
+    }
     if (nodeDiscovery.ambiguous || aspNetDiscovery.ambiguous) {
         return ambiguousRuntimeDiscovery();
     }
@@ -99,16 +133,16 @@ async function discoverHostRuntimeContract(worktreePath) {
         },
     };
 }
-async function discoverNodeRuntimes(root) {
+async function discoverNodeRuntimes(root, snapshot, directorySnapshot) {
     const manifests = [...new Set([
             path.join(root, "package.json"),
-            ...await findFiles(root, file => path.basename(file).toLowerCase() === "package.json", 4, 500),
+            ...await findFiles(root, file => path.basename(file).toLowerCase() === "package.json", 4, maximumDiscoveryEntries, directorySnapshot),
         ])];
-    const candidates = (await Promise.all(manifests.map(async (manifestPath) => await discoverNodeRuntime(root, manifestPath)))).filter((candidate) => candidate !== null);
+    const candidates = (await Promise.all(manifests.map(async (manifestPath) => await discoverNodeRuntime(root, manifestPath, snapshot, directorySnapshot)))).filter((candidate) => candidate !== null);
     return { candidates: candidates.length === 1 ? candidates : [], ambiguous: candidates.length > 1 };
 }
-async function discoverNodeRuntime(root, manifestPath) {
-    const source = await readBoundedOptionalFile(manifestPath, 256 * 1024);
+async function discoverNodeRuntime(root, manifestPath, snapshot, directorySnapshot) {
+    const source = await readBoundedOptionalFile(manifestPath, 256 * 1024, snapshot);
     if (source === null)
         return null;
     let manifest;
@@ -130,15 +164,15 @@ async function discoverNodeRuntime(root, manifestPath) {
     const next = Object.hasOwn(dependencies, "next") || /(^|\s)next(?:\s|$)/u.test(script);
     if (vite === next)
         return null;
-    const packageManager = await nearestPackageManager(root, path.dirname(manifestPath));
+    const packageManager = await nearestPackageManager(root, path.dirname(manifestPath), snapshot);
     if (!packageManager)
         return null;
     const adapter = vite ? "vite" : "next";
     const playwrightConfigs = [...new Set((await Promise.all([
             ...["playwright.config.ts", "playwright.config.js", "playwright.config.mjs", "playwright.config.cjs"]
                 .flatMap(file => [file, `e2e/${file}`, `tests/e2e/${file}`])
-                .map(async (candidate) => await optionalFileExists(path.join(root, candidate)) ? path.join(root, candidate) : null),
-            findFiles(root, file => /^playwright\.config\.(?:ts|js|mjs|cjs)$/iu.test(path.basename(file)), 4, 2_000),
+                .map(async (candidate) => await optionalFileExists(path.join(root, candidate), snapshot) ? path.join(root, candidate) : null),
+            findFiles(root, file => /^playwright\.config\.(?:ts|js|mjs|cjs)$/iu.test(path.basename(file)), 4, maximumDiscoveryEntries, directorySnapshot),
         ])).flat().filter((value) => value !== null))]
         .map(config => portableRelativePath(root, config));
     const playwright = playwrightConfigs.length === 1
@@ -182,11 +216,13 @@ async function discoverNodeRuntime(root, manifestPath) {
         }),
     };
 }
-async function discoverAspNetRuntimes(root) {
-    const projects = await findFiles(root, file => file.toLowerCase().endsWith(".csproj"), 3, 200);
+async function discoverAspNetRuntimes(root, snapshot, directorySnapshot) {
+    // Deep enough for nested solutions (src/<area>/<Project>/<Project>.csproj); the entry budget,
+    // not the depth, bounds the scan, and a scan that exceeds it is reported as incomplete.
+    const projects = await findFiles(root, file => file.toLowerCase().endsWith(".csproj"), 6, maximumDiscoveryEntries, directorySnapshot);
     const webProjects = [];
     for (const projectPath of projects) {
-        const source = await readBoundedOptionalFile(projectPath, 512 * 1024);
+        const source = await readBoundedOptionalFile(projectPath, 512 * 1024, snapshot);
         if (source && /<Project\s+Sdk=["']Microsoft\.NET\.Sdk\.Web["']/iu.test(source)) {
             webProjects.push({ relativePath: path.relative(root, projectPath).replaceAll("\\", "/"), source });
         }
@@ -194,7 +230,7 @@ async function discoverAspNetRuntimes(root) {
     if (webProjects.length !== 1)
         return { candidates: [], ambiguous: webProjects.length > 1 };
     const project = webProjects[0];
-    const launchProfile = await discoverAspNetLaunchProfile(root, project.relativePath);
+    const launchProfile = await discoverAspNetLaunchProfile(root, project.relativePath, snapshot);
     const contract = {
         schemaVersion: 1,
         runtime: {
@@ -277,6 +313,17 @@ function combineBrowserAndApiRuntime(browser, api) {
         }),
     };
 }
+function incompleteRuntimeDiscovery() {
+    return {
+        contract: defaultHostRuntimeContract(),
+        source: "default",
+        discovery: {
+            status: "ambiguous",
+            reasonCode: "runtime_discovery_incomplete",
+            summary: "Forge could not scan the whole repository within its discovery budget, so host application runs remain serialized.",
+        },
+    };
+}
 function ambiguousRuntimeDiscovery() {
     return {
         contract: defaultHostRuntimeContract(),
@@ -288,15 +335,15 @@ function ambiguousRuntimeDiscovery() {
         },
     };
 }
-async function nearestPackageManager(root, start) {
+async function nearestPackageManager(root, start, snapshot) {
     let directory = path.resolve(start);
     const resolvedRoot = path.resolve(root);
     while (directory === resolvedRoot || directory.startsWith(`${resolvedRoot}${path.sep}`)) {
         const lockfiles = (await Promise.all([
-            optionalFileExists(path.join(directory, "pnpm-lock.yaml")).then(exists => exists ? "pnpm" : null),
-            optionalFileExists(path.join(directory, "yarn.lock")).then(exists => exists ? "yarn" : null),
-            optionalFileExists(path.join(directory, "package-lock.json")).then(exists => exists ? "npm" : null),
-            optionalFileExists(path.join(directory, "npm-shrinkwrap.json")).then(exists => exists ? "npm" : null),
+            optionalFileExists(path.join(directory, "pnpm-lock.yaml"), snapshot).then(exists => exists ? "pnpm" : null),
+            optionalFileExists(path.join(directory, "yarn.lock"), snapshot).then(exists => exists ? "yarn" : null),
+            optionalFileExists(path.join(directory, "package-lock.json"), snapshot).then(exists => exists ? "npm" : null),
+            optionalFileExists(path.join(directory, "npm-shrinkwrap.json"), snapshot).then(exists => exists ? "npm" : null),
         ])).filter((value) => value !== null);
         const packageManagers = [...new Set(lockfiles)];
         if (packageManagers.length > 1)
@@ -312,9 +359,9 @@ async function nearestPackageManager(root, start) {
 function portableRelativePath(root, target) {
     return path.relative(root, target).replaceAll("\\", "/");
 }
-async function discoverAspNetLaunchProfile(root, projectRelativePath) {
+async function discoverAspNetLaunchProfile(root, projectRelativePath, snapshot) {
     const target = path.join(root, path.dirname(projectRelativePath), "Properties", "launchSettings.json");
-    const source = await readBoundedOptionalFile(target, 512 * 1024);
+    const source = await readBoundedOptionalFile(target, 512 * 1024, snapshot);
     if (!source)
         return { name: null, source: null, environment: {} };
     try {
@@ -339,7 +386,13 @@ async function discoverAspNetLaunchProfile(root, projectRelativePath) {
         return { name: null, source, environment: {} };
     }
 }
+// A project's "forge-attempt" profile configures its API for managed attempts. The
+// attempt's pre-publication checks then run against the same settings the project's own
+// e2e suite uses, instead of the developer's "http" profile.
+const attemptLaunchProfileName = "forge-attempt";
 function aspNetProfilePriority(name) {
+    if (name.toLowerCase() === attemptLaunchProfileName)
+        return -1;
     if (name.toLowerCase() === "http")
         return 0;
     if (name.toLowerCase() === "https")
@@ -354,6 +407,7 @@ function safeAspNetLaunchEnvironment(name, value) {
         return false;
     const normalized = name.toUpperCase();
     return !normalized.startsWith("FORGE_")
+        && !isUnsafeDotnetEnvironmentName(name)
         && !new Set([
             "ASPNETCORE_URLS",
             "ASPNETCORE_HTTP_PORTS",
@@ -368,34 +422,53 @@ function safeAspNetLaunchEnvironment(name, value) {
             "TMPDIR",
         ]).has(normalized);
 }
-async function findFiles(root, accepts, maximumDepth, maximumEntries) {
+async function findFiles(root, accepts, maximumDepth, maximumEntries, snapshot) {
     const results = [];
     let examined = 0;
-    const visitDirectory = async (directory, depth) => {
-        if (depth > maximumDepth || examined >= maximumEntries)
-            return;
-        const entries = await fs.readdir(directory, { withFileTypes: true }).catch(() => []);
-        for (const entry of entries) {
-            if (examined++ >= maximumEntries)
-                return;
-            if (entry.isDirectory() && ignoredDiscoveryDirectories.has(entry.name.toLowerCase()))
+    const directories = [{ directory: root, depth: 0 }];
+    while (directories.length > 0) {
+        const current = directories.shift();
+        if (current.depth > maximumDepth)
+            continue;
+        const entries = snapshot
+            ? await snapshot(current.directory)
+            : await fs.readdir(current.directory, { withFileTypes: true }).then(found => found.map(entry => ({
+                name: entry.name,
+                isDirectory: entry.isDirectory(),
+                isFile: entry.isFile(),
+            }))).catch((error) => {
+                // A directory removed since it was listed holds nothing; one that cannot be read
+                // (permissions, open-file limits) may hold the entrypoint discovery is looking for.
+                if (isFileNotFound(error))
+                    return [];
+                throw new IncompleteRuntimeDiscoveryError();
+            });
+        const orderedEntries = [...entries].sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+        for (const entry of orderedEntries) {
+            if (entry.isDirectory
+                && (ignoredDiscoveryDirectories.has(entry.name.toLowerCase()) || isGeneratedOutputDirectoryName(entry.name)))
                 continue;
-            const target = path.join(directory, entry.name);
-            if (entry.isDirectory())
-                await visitDirectory(target, depth + 1);
-            else if (entry.isFile() && accepts(target))
+            if (examined++ >= maximumEntries)
+                throw new IncompleteRuntimeDiscoveryError();
+            const target = path.join(current.directory, entry.name);
+            if (entry.isDirectory)
+                directories.push({ directory: target, depth: current.depth + 1 });
+            else if (entry.isFile && accepts(target))
                 results.push(target);
         }
-    };
-    await visitDirectory(root, 0);
+    }
     return results.sort((left, right) => left.localeCompare(right));
 }
-async function readBoundedOptionalFile(target, maximumBytes) {
+async function readBoundedOptionalFile(target, maximumBytes, snapshot) {
+    if (snapshot) {
+        const source = await snapshot(target);
+        return source && source.length > 0 && source.length <= maximumBytes ? source.toString("utf8") : null;
+    }
     try {
         const stat = await fs.stat(target);
         if (!stat.isFile() || stat.size < 1 || stat.size > maximumBytes)
             return null;
-        return await fs.readFile(target, "utf8");
+        return (await readCanonicalSourceFile(target, maximumBytes)).toString("utf8");
     }
     catch (error) {
         if (isFileNotFound(error))
@@ -403,7 +476,9 @@ async function readBoundedOptionalFile(target, maximumBytes) {
         throw error;
     }
 }
-async function optionalFileExists(target) {
+async function optionalFileExists(target, snapshot) {
+    if (snapshot)
+        return await snapshot(target) !== null;
     try {
         return (await fs.stat(target)).isFile();
     }
@@ -574,6 +649,7 @@ function parseLaunch(value, adapter, name) {
         throw new Error(`runtime_contract_invalid: runtime.ports.${name}.launch.args must contain at most 128 strings.`);
     }
     const parsedArgs = args.map((argument, index) => boundedString(argument, 4096, `runtime.ports.${name}.launch.args[${index}]`));
+    rejectProjectAuthoredForgeArguments(parsedArgs, adapter, name);
     const portableDirectory = launch.workingDirectory === undefined || launch.workingDirectory === null
         ? "."
         : containedPortablePath(launch.workingDirectory, `runtime.ports.${name}.launch.workingDirectory`);
@@ -596,9 +672,46 @@ function parseLaunchEnvironment(value, portName) {
         if (!/^[A-Za-z_][A-Za-z0-9_]{0,127}$/u.test(name)) {
             throw new Error(`runtime_contract_invalid: launch environment name '${name}' is invalid.`);
         }
+        if (name.toLowerCase().startsWith("forge_") || isUnsafeDotnetEnvironmentName(name)) {
+            throw new Error(`runtime_contract_invalid: launch environment name '${name}' is host-owned or enables pre-startup code injection and cannot be project-authored.`);
+        }
         return [name, boundedString(raw, 8192, `runtime.ports.${portName}.launch.environment.${name}`)];
     }));
 }
+function isUnsafeDotnetEnvironmentName(name) {
+    const normalized = name.toUpperCase();
+    return normalized === "DOTNET_STARTUP_HOOKS"
+        || normalized === "DOTNET_ADDITIONAL_DEPS"
+        || normalized === "DOTNET_SHARED_STORE"
+        || normalized === "DOTNET_HOST_PATH"
+        || normalized === "MSBUILD_EXE_PATH"
+        || normalized === "MSBUILDSDKSPATH"
+        || normalized === "NUGET_PLUGIN_PATHS"
+        || normalized === "ASPNETCORE_HOSTINGSTARTUPASSEMBLIES"
+        || normalized === "ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES"
+        || normalized.startsWith("CUSTOMBEFOREMICROSOFTCOMMON")
+        || normalized.startsWith("CUSTOMAFTERMICROSOFTCOMMON")
+        || normalized.startsWith("DOTNET_ROOT")
+        || normalized.startsWith("CORECLR_")
+        || normalized.startsWith("COR_")
+        || normalized.startsWith("COMPLUS_")
+        || normalized.startsWith("LD_")
+        || normalized.startsWith("DYLD_");
+}
+function rejectProjectAuthoredForgeArguments(args, adapter, portName) {
+    if (adapter !== "aspnetcore")
+        return;
+    const applicationArgumentIndex = args.indexOf("--");
+    if (applicationArgumentIndex < 0)
+        return;
+    const forbidden = args.slice(applicationArgumentIndex + 1).find(argument => {
+        const key = argument.split("=", 1)[0].replace(/^(?:--?|\/)/u, "");
+        return /^forge(?:[_:.-]|$)/iu.test(key);
+    });
+    if (forbidden) {
+        throw new Error(`runtime_contract_invalid: runtime.ports.${portName}.launch.args cannot override the host-owned FORGE_* namespace.`);
+    }
+}
 function containedPortablePath(value, label) {
     const original = boundedString(value, 1024, label);
     const portable = original.replaceAll("\\", "/");

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

@@ -4,8 +4,11 @@ import { type RuntimeIsolationLease } from "./runtime-isolation-lease.js";
 import { type LoadedHostRuntimeContract } from "./host-runtime-contract.js";
 import { HostPortBroker } from "./host-port-broker.js";
 import { NodeHostRuntimeAdapter, type NodeRuntimeAdapterLaunch, type NodeRuntimeCommand, type NodeRuntimeCommandLauncher } from "./node-host-runtime-adapter.js";
+import type { AttemptProcessTreeMemoryTelemetry } from "./attempt-process-supervisor.js";
 import { AttemptProcessSupervisorRegistry } from "./attempt-process-supervisor-registry.js";
+import { type AttemptDatabaseBroker } from "./attempt-database-broker.js";
 import { HostListenerInspector } from "./host-listener-inspector.js";
+import { type MemoryAdmissionDiagnostics } from "./memory-capacity.js";
 import { PlaywrightHostRuntimeAdapter } from "./playwright-host-runtime-adapter.js";
 import { HostParallelPromotionStore } from "./host-runtime-promotion.js";
 import { type HostProcessRecovery } from "../shared/process/host-process-recovery.js";
@@ -15,6 +18,18 @@ export interface HostRuntimeLeaseStart {
     readonly runtimeContract: LoadedHostRuntimeContract;
     readonly executionClass: HostRuntimeExecutionClass;
 }
+export interface HostRuntimeAdmissionCheckpoint {
+    readonly code: "host_runtime_serial_admission_waiting" | "host_runtime_prepared_probe_started" | "host_runtime_prepared_probe_progress" | "host_runtime_prepared_probe_completed" | "host_runtime_prepared_admission_waiting" | "host_runtime_prepared_admission_acquired";
+    readonly message: string;
+    readonly expiresAt: string;
+}
+export type HostRuntimeAdmissionCheckpointHandler = (checkpoint: HostRuntimeAdmissionCheckpoint) => void | Promise<void>;
+export interface HostRuntimeProjectCheckpoint {
+    readonly code: "host_runtime_build_started" | "host_runtime_build_cached" | "host_runtime_build_completed" | "host_runtime_database_provisioned";
+    readonly message: string;
+    readonly data?: Readonly<Record<string, unknown>>;
+}
+export type HostRuntimeProjectCheckpointHandler = (checkpoint: HostRuntimeProjectCheckpoint) => void | Promise<void>;
 export type HostRuntimeExecutionClass = "analysis_only" | "managed_runtime";
 export type HostRuntimeSafetyClass = "host_serial_only" | "host_parallel_candidate" | "host_parallel_safe";
 export interface HostRuntimeProjectCapacitySnapshot {
@@ -29,12 +44,25 @@ export interface HostRuntimeProjectCapacitySnapshot {
     readonly promotedAt?: string | null;
 }
 export interface HostRuntimeCapacitySnapshot {
+    readonly preparedWorktreeReadiness?: boolean;
     readonly activeAttempts: number;
     readonly reservedAttempts: number;
     readonly waitingAttempts: number;
     readonly degradedAttempts: number;
     readonly exclusiveReservations: number;
     readonly sharedReservations: number;
+    readonly hardMaxAttempts: number;
+    readonly effectiveMaxAttempts: number;
+    readonly availableAttempts: number;
+    readonly totalMemoryBytes: number;
+    readonly availableMemoryBytes: number;
+    readonly hostReserveBytes: number;
+    readonly availableCpuMillis: number;
+    readonly availableWorkspaceBytes: number;
+    readonly activeReservationMemoryBytes: number;
+    readonly memoryAdmission: MemoryAdmissionDiagnostics;
+    readonly unavailableCode?: string | null;
+    readonly unavailableReason?: string | null;
     readonly projects: readonly HostRuntimeProjectCapacitySnapshot[];
 }
 export interface HostRuntimeReapOptions {
@@ -48,21 +76,41 @@ export interface HostRuntimeReapReport {
     readonly processesTerminated: number;
     readonly reusedPidsProtected: number;
     readonly degraded: number;
+    /**
+     * Active attempts of a previous runner instance whose every supervised
+     * process tree was proved absent, terminated or PID-reused. Forge may settle
+     * these exact attempts instead of leaving their launch outcome unknown.
+     */
+    readonly recoveredAttempts?: readonly HostRuntimeRecoveredAttempt[];
+}
+export interface HostRuntimeRecoveredAttempt {
+    readonly dispatchAttemptId: string;
+    readonly fencingToken: string;
+    readonly runnerInstanceId: string;
 }
 export interface HostNodeRuntimeLaunch<T> extends NodeRuntimeAdapterLaunch<T> {
     readonly runtimeLease: RuntimeIsolationLease;
 }
 export interface HostRuntimeLeaseRuntime {
+    acquirePreparation?(dispatch: RunOnceDispatchPacket, signal?: AbortSignal): Promise<readonly string[]>;
     acquire(dispatch: RunOnceDispatchPacket, signal?: AbortSignal): Promise<readonly string[]>;
-    start(dispatch: RunOnceDispatchPacket, worktreePath: string, signal?: AbortSignal): Promise<HostRuntimeLeaseStart>;
-    startConfiguredProject(dispatchAttemptId: string, fencingToken: string, signal?: AbortSignal): Promise<HostRuntimeLeaseStart>;
+    start(dispatch: RunOnceDispatchPacket, worktreePath: string, signal?: AbortSignal, onAdmissionCheckpoint?: HostRuntimeAdmissionCheckpointHandler): Promise<HostRuntimeLeaseStart>;
+    startConfiguredProject(dispatchAttemptId: string, fencingToken: string, signal?: AbortSignal, onProjectCheckpoint?: HostRuntimeProjectCheckpointHandler): Promise<HostRuntimeLeaseStart>;
     updateLease(dispatchAttemptId: string, fencingToken: string, expiresAt: string): Promise<void>;
     providerProcessRunner?(dispatchAttemptId: string, fencingToken: string): ProviderProcessRunner | null;
+    providerMemoryTelemetry?(dispatchAttemptId: string, fencingToken: string): AttemptProcessTreeMemoryTelemetry | null;
     release(dispatchAttemptId: string, fencingToken: string): Promise<RuntimeIsolationLease | null>;
-    invalidatePromotion?(repoId: string): Promise<void>;
+    invalidatePromotion?(repoId: string, scope?: "all" | "discovery"): Promise<void>;
+    hasForegroundDemand?(): boolean;
     reap?(options: HostRuntimeReapOptions): Promise<HostRuntimeReapReport>;
     snapshot?(): HostRuntimeCapacitySnapshot;
 }
+export interface HostCapacityResourceSample {
+    readonly totalMemoryBytes: number;
+    readonly availableMemoryBytes: number;
+    readonly totalCpuMillis: number;
+    readonly availableWorkspaceBytes: number;
+}
 export declare class HostRuntimeLeaseManager implements HostRuntimeLeaseRuntime {
     private readonly stateRoot;
     private readonly processSupervisors;
@@ -71,30 +119,58 @@ export declare class HostRuntimeLeaseManager implements HostRuntimeLeaseRuntime
     private readonly promotionStore;
     private readonly playwrightAdapter;
     private readonly processRecovery;
+    private readonly capacityResourceSample?;
+    private readonly databaseBroker;
+    private readonly preparedReadiness;
     private readonly active;
     private readonly pendingRenewals;
+    private readonly acquiringAdmissions;
     private readonly admissions;
     private readonly singletonOwners;
     private readonly singletonWaiters;
     private readonly parallelProjectOwners;
     private readonly parallelProjectWaiters;
+    private readonly capacityReservations;
+    private readonly capacityWaiters;
+    private capacityWaiterScanCursor;
+    private readonly backgroundAdmissionWaiters;
     private readonly degraded;
     private readonly knownPromotions;
+    private ledgerWriteTail;
+    private workspaceAvailableBytes;
     private readonly portBroker;
     private readonly nodeAdapter;
-    constructor(stateRoot: string, portBroker?: HostPortBroker, nodeAdapter?: NodeHostRuntimeAdapter, processSupervisors?: AttemptProcessSupervisorRegistry, processRunner?: ProviderProcessRunner, listenerInspector?: HostListenerInspector, promotionStore?: HostParallelPromotionStore, playwrightAdapter?: PlaywrightHostRuntimeAdapter, processRecovery?: HostProcessRecovery);
+    private readonly capacityConfiguration;
+    private readonly memoryAvailability;
+    private readonly executionRoot;
+    constructor(stateRoot: string, portBroker?: HostPortBroker, nodeAdapter?: NodeHostRuntimeAdapter, processSupervisors?: AttemptProcessSupervisorRegistry, processRunner?: ProviderProcessRunner, listenerInspector?: HostListenerInspector, promotionStore?: HostParallelPromotionStore, playwrightAdapter?: PlaywrightHostRuntimeAdapter, processRecovery?: HostProcessRecovery, capacityResourceSample?: HostCapacityResourceSample | undefined, executionRoot?: string, databaseBroker?: AttemptDatabaseBroker | null);
     reap(options: HostRuntimeReapOptions): Promise<HostRuntimeReapReport>;
     snapshot(): HostRuntimeCapacitySnapshot;
+    hasForegroundDemand(): boolean;
+    acquirePreparation(dispatch: RunOnceDispatchPacket, signal?: AbortSignal): Promise<readonly string[]>;
     acquire(dispatch: RunOnceDispatchPacket, signal?: AbortSignal): Promise<readonly string[]>;
+    private reserveHostCapacity;
+    private reserveBackgroundAdmission;
+    private hostCapacityAvailable;
+    private hostCapacityImpossibleReason;
+    private hostResourceSnapshot;
+    private refreshWorkspaceCapacity;
+    private releaseHostCapacity;
+    private drainCapacityWaiters;
+    private capacityWaitersForScan;
+    private detachCapacityWaiter;
     private reserveSingletonKeys;
     private reserveParallelProject;
-    start(dispatch: RunOnceDispatchPacket, worktreePath: string, signal?: AbortSignal): Promise<HostRuntimeLeaseStart>;
+    private upgradeParallelProjectToSingleton;
+    start(dispatch: RunOnceDispatchPacket, worktreePath: string, signal?: AbortSignal, onAdmissionCheckpoint?: HostRuntimeAdmissionCheckpointHandler): Promise<HostRuntimeLeaseStart>;
     updateLease(dispatchAttemptId: string, fencingToken: string, expiresAt: string): Promise<void>;
-    startConfiguredProject(dispatchAttemptId: string, fencingToken: string, signal?: AbortSignal): Promise<HostRuntimeLeaseStart>;
+    startConfiguredProject(dispatchAttemptId: string, fencingToken: string, signal?: AbortSignal, onProjectCheckpoint?: HostRuntimeProjectCheckpointHandler): Promise<HostRuntimeLeaseStart>;
     providerProcessRunner(dispatchAttemptId: string, fencingToken: string): ProviderProcessRunner | null;
+    private markCapacityReservationRunning;
+    providerMemoryTelemetry(dispatchAttemptId: string, fencingToken: string): AttemptProcessTreeMemoryTelemetry | null;
     private promoteVerifiedRuntime;
     launchNodeRuntime<T>(dispatchAttemptId: string, fencingToken: string, portName: string, command: NodeRuntimeCommand, launcher: NodeRuntimeCommandLauncher<T>, signal?: AbortSignal): Promise<HostNodeRuntimeLaunch<T>>;
-    release(dispatchAttemptId: string, fencingToken: string): Promise<RuntimeIsolationLease | null>;
+    release(dispatchAttemptId: string, fencingToken: string, preservePreparation?: boolean): Promise<RuntimeIsolationLease | null>;
     private readLedgers;
     private recoverPersistedProcesses;
     private markLedgerDegraded;
@@ -102,6 +178,7 @@ export declare class HostRuntimeLeaseManager implements HostRuntimeLeaseRuntime
     private forgetDegraded;
     private attemptRoot;
     private writeLedger;
+    private writeLedgerAtomic;
     private ledgerPath;
     private singletonKeysAvailable;
     private assignSingletonKeys;
@@ -118,9 +195,13 @@ export declare class HostRuntimeLeaseManager implements HostRuntimeLeaseRuntime
     private cancelAdmissionWaiters;
     private drainSingletonWaiters;
     private drainParallelProjectWaiters;
+    private drainBackgroundAdmissionWaiters;
     private refreshKnownPromotions;
-    invalidatePromotion(repoId: string): Promise<void>;
+    invalidatePromotion(repoId: string, scope?: "all" | "discovery"): Promise<void>;
     private drainAdmissionWaiters;
+    private reconcileReservationOwners;
+    private reservationOwnerIsLive;
+    private hasAttemptRepresentation;
 }
 export declare class HostRuntimeLeaseCleanupError extends Error {
     readonly lease: RuntimeIsolationLease;
@@ -129,5 +210,8 @@ export declare class HostRuntimeLeaseCleanupError extends Error {
 export declare class HostRuntimeAdmissionExpiredError extends Error {
     constructor();
 }
+export declare class HostRuntimeCapacityRequestImpossibleError extends Error {
+    constructor(reason: string);
+}
 export declare function hostRuntimeEventResources(lease: RuntimeIsolationLease, runtimeContract?: LoadedHostRuntimeContract, executionClass?: HostRuntimeExecutionClass): Record<string, unknown>;
 export declare function hostRuntimeSingletonKeys(dispatch: RunOnceDispatchPacket): readonly string[];