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

package/dist/session/session.types.d.ts

@@ -7,12 +7,14 @@ export interface RunOnceDispatchPacket {
     readonly session: DispatchSession;
     readonly lease: DispatchLease;
     readonly execution: DispatchExecution;
+    readonly runtimeIntent: DispatchRuntimeIntent;
     readonly serverLocal: DispatchServerLocalConfig;
     readonly sandbox?: DispatchSandboxContext | null;
     readonly pullRequest?: DispatchPullRequestContext | null;
     readonly apiKeySecretGrant?: ApiKeySecretGrant | null;
     readonly apiKeySecretGrantHandle?: ApiKeySecretGrantHandle | null;
     readonly artifacts: readonly DispatchResolvedArtifact[];
+    readonly priorPhaseArtifacts?: readonly DispatchPriorPhaseArtifact[];
     readonly warmPathOverrides?: readonly string[];
     readonly qaBrowser?: DispatchQaBrowserContext | null;
     readonly qaScope?: DispatchQaScope | null;
@@ -24,6 +26,10 @@ export interface RunOnceDispatchPacket {
     readonly designerRefs?: DispatchDesignerRefHandoffContext | null;
     readonly draft?: DispatchDraftPrompt | null;
 }
+export interface DispatchRuntimeIntent {
+    readonly executionClass: "analysis_only" | "managed_runtime";
+    readonly applicationRuntimeRequired: boolean;
+}
 export interface DispatchSandboxContext {
     readonly dispatchAttemptId: string;
     readonly executionLeaseId: string;
@@ -48,6 +54,9 @@ export interface DispatchPublishGrantHandle {
 export interface DispatchSandboxResourceRequest {
     readonly sandboxSlots: number;
     readonly cpuMillis: number;
+    readonly workerMemoryLimitBytes: number;
+    readonly serviceMemoryLimitBytes: number;
+    readonly runtimeOverheadBytes: number;
     readonly memoryBytes: number;
     readonly workspaceBytes: number;
     readonly pids: number;
@@ -85,6 +94,7 @@ export interface DispatchQaScope {
     readonly schema_version: number;
     readonly surface: readonly string[];
     readonly required_evidence: readonly string[];
+    readonly required_capabilities?: readonly string[];
     readonly not_applicable: readonly string[];
     readonly browser_required: boolean;
     readonly api_required: boolean;
@@ -101,6 +111,7 @@ export interface DispatchQaAppLaunchTarget {
     readonly command?: string | null;
     readonly working_directory?: string | null;
     readonly ready_url?: string | null;
+    readonly managed_runtime_port?: string | null;
     readonly routes: readonly string[];
     readonly notes?: string | null;
 }
@@ -189,6 +200,19 @@ export interface DispatchStoryQaDependencyContext {
     readonly fromWorkItemId: string;
     readonly toWorkItemId: string;
 }
+export interface DispatchPriorPhaseArtifact {
+    readonly workItemId: string;
+    readonly artifactId: string;
+    readonly cycleRunId: string;
+    readonly phase: "implementation" | "self_review" | "validation";
+    readonly status: string;
+    readonly producedAt: string;
+    readonly sourcePath: string;
+    readonly verdictJson: string;
+    readonly report: string;
+    readonly verdictContentHash: string;
+    readonly reportContentHash: string;
+}
 export interface DispatchDesignerRefHandoffContext {
     readonly schemaVersion: number;
     readonly kind: string;
@@ -278,6 +302,7 @@ export interface DispatchCycleRun {
     readonly requestedBase: string;
     readonly baseBranch: string;
     readonly expectedCurrentBranch?: string | null;
+    readonly repairHeadSha?: string | null;
     readonly attempt: number;
     readonly model: string;
 }
@@ -285,6 +310,8 @@ export interface DispatchSession {
     readonly id: string;
     readonly model: string;
     readonly lane: string;
+    readonly resumedFromSessionId?: string | null;
+    readonly resumeProviderThreadId?: string | null;
 }
 export interface DispatchLease {
     readonly id: string;
@@ -353,6 +380,19 @@ export interface RunnerDispatchArtifact {
     readonly producedBy: string;
     readonly status: string;
     readonly phase?: string | null;
+    /**
+     * QA sidecars are transported with the terminal result because managed
+     * worktrees may be released before the API mirrors the result. The API
+     * validates these bytes against the canonical evidence metadata and stores
+     * only that metadata.
+     */
+    readonly sidecars?: readonly RunnerDispatchSidecar[] | null;
+}
+export interface RunnerDispatchSidecar {
+    readonly path: string;
+    readonly contentBase64: string;
+    readonly contentHash: string;
+    readonly bytes: number;
 }
 export interface RunOnceResultPacket {
     readonly schemaVersion: 1;
@@ -368,4 +408,36 @@ export interface RunnerEventLine {
     readonly event: RunnerDispatchEvent;
 }
 export declare function parseRunOnceDispatchPacket(value: unknown): RunOnceDispatchPacket;
+export interface HostRuntimeReadinessProbeRequest {
+    readonly requestId: string;
+    readonly fencingToken: string;
+    readonly userId: string;
+    readonly projectId: string;
+    readonly repoId: string;
+    readonly runnerId: 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;
+    readonly repoRoot: string;
+    readonly cleanupWorktrees: boolean;
+}
+export interface HostRuntimeReadinessProbeResult {
+    readonly status: "parallel_ready" | "serialized" | "failed";
+    readonly runtimeContractFingerprint?: string | null;
+    readonly runtimeContractSource?: string | null;
+    readonly reasonCode?: string | null;
+    readonly reasonMessage?: string | null;
+    readonly qaAppLaunchTarget?: HostRuntimeReadinessQaLaunchTarget | null;
+    readonly checkedAt: string;
+}
+export interface HostRuntimeReadinessQaLaunchTarget {
+    readonly managedRuntimePort: string;
+    readonly routes: readonly string[];
+}
 export declare function failureResult(summary: string, events?: readonly RunnerDispatchEvent[]): RunOnceResultPacket;

package/dist/session/session.types.js

@@ -14,12 +14,14 @@ export function parseRunOnceDispatchPacket(value) {
         session: parseSession(packet.session),
         lease: parseLease(packet.lease),
         execution: parseExecution(packet.execution),
+        runtimeIntent: parseRuntimeIntent(packet.runtimeIntent),
         serverLocal: parseServerLocal(packet.serverLocal),
         sandbox: parseSandbox(packet.sandbox, schemaVersion),
         pullRequest: parsePullRequest(packet.pullRequest),
         apiKeySecretGrant: parseApiKeySecretGrant(packet.apiKeySecretGrant),
         apiKeySecretGrantHandle: parseApiKeySecretGrantHandle(packet.apiKeySecretGrantHandle),
         artifacts: parseArtifacts(packet.artifacts),
+        priorPhaseArtifacts: parsePriorPhaseArtifacts(packet.priorPhaseArtifacts),
         warmPathOverrides: parseWarmPathOverrides(packet.warmPathOverrides),
         qaBrowser: parseQaBrowser(packet.qaBrowser),
         qaScope: parseQaScope(packet.qaScope ?? packet.qa_scope),
@@ -32,6 +34,21 @@ export function parseRunOnceDispatchPacket(value) {
         draft: parseDraftPrompt(packet.draft)
     };
 }
+function parseRuntimeIntent(value) {
+    if (value === undefined || value === null) {
+        return { executionClass: "managed_runtime", applicationRuntimeRequired: true };
+    }
+    const intent = asObject(value, "runtimeIntent");
+    const executionClass = requiredString(intent, "executionClass").trim().toLowerCase();
+    if (executionClass !== "analysis_only" && executionClass !== "managed_runtime") {
+        throw new Error("runtimeIntent.executionClass must be analysis_only or managed_runtime.");
+    }
+    const applicationRuntimeRequired = requiredBoolean(intent, "applicationRuntimeRequired");
+    if ((executionClass === "analysis_only") === applicationRuntimeRequired) {
+        throw new Error("runtimeIntent execution class and application runtime requirement are inconsistent.");
+    }
+    return { executionClass, applicationRuntimeRequired };
+}
 function parseSandbox(value, schemaVersion) {
     if (value === undefined || value === null) {
         if (schemaVersion === 2) {
@@ -93,17 +110,38 @@ function parseSandboxResourceRequest(value) {
         return {
             sandboxSlots: 1,
             cpuMillis: 2000,
-            memoryBytes: 2 * 1024 ** 3,
+            workerMemoryLimitBytes: 2 * 1024 ** 3,
+            serviceMemoryLimitBytes: 0,
+            runtimeOverheadBytes: 128 * 1024 ** 2,
+            memoryBytes: 2 * 1024 ** 3 + 128 * 1024 ** 2,
             workspaceBytes: 10 * 1024 ** 3,
             pids: 512,
             buildSlots: 1
         };
     }
     const resources = asObject(value, "sandbox.requestedResources");
+    const memoryBytes = boundedInteger(resources, "memoryBytes", 128 * 1024 ** 2, 512 * 1024 ** 3);
+    const hasMemoryBreakdown = ["workerMemoryLimitBytes", "serviceMemoryLimitBytes", "runtimeOverheadBytes"]
+        .some(key => resources[key] !== undefined && resources[key] !== null);
+    const workerMemoryLimitBytes = hasMemoryBreakdown
+        ? boundedInteger(resources, "workerMemoryLimitBytes", 128 * 1024 ** 2, 512 * 1024 ** 3)
+        : memoryBytes;
+    const serviceMemoryLimitBytes = hasMemoryBreakdown
+        ? boundedInteger(resources, "serviceMemoryLimitBytes", 0, 512 * 1024 ** 3)
+        : 0;
+    const runtimeOverheadBytes = hasMemoryBreakdown
+        ? boundedInteger(resources, "runtimeOverheadBytes", 0, 64 * 1024 ** 3)
+        : 0;
+    if (workerMemoryLimitBytes + serviceMemoryLimitBytes + runtimeOverheadBytes !== memoryBytes) {
+        throw new Error("sandbox.requestedResources memory breakdown must equal memoryBytes.");
+    }
     return {
         sandboxSlots: boundedInteger(resources, "sandboxSlots", 1, 4),
         cpuMillis: boundedInteger(resources, "cpuMillis", 100, 64_000),
-        memoryBytes: boundedInteger(resources, "memoryBytes", 128 * 1024 ** 2, 512 * 1024 ** 3),
+        workerMemoryLimitBytes,
+        serviceMemoryLimitBytes,
+        runtimeOverheadBytes,
+        memoryBytes,
         workspaceBytes: boundedInteger(resources, "workspaceBytes", 1024 ** 3, 10 * 1024 ** 4),
         pids: boundedInteger(resources, "pids", 32, 65_536),
         buildSlots: boundedInteger(resources, "buildSlots", 0, 4)
@@ -176,6 +214,7 @@ function parseCycleRun(value) {
         requestedBase: optionalString(cycle, "requestedBase") ?? "develop",
         baseBranch: optionalString(cycle, "baseBranch") ?? "develop",
         expectedCurrentBranch: optionalString(cycle, "expectedCurrentBranch"),
+        repairHeadSha: optionalString(cycle, "repairHeadSha"),
         attempt: requiredNumber(cycle, "attempt"),
         model: requiredString(cycle, "model")
     };
@@ -185,7 +224,9 @@ function parseSession(value) {
     return {
         id: requiredString(session, "id"),
         model: requiredString(session, "model"),
-        lane: requiredString(session, "lane")
+        lane: requiredString(session, "lane"),
+        resumedFromSessionId: optionalString(session, "resumedFromSessionId"),
+        resumeProviderThreadId: optionalString(session, "resumeProviderThreadId")
     };
 }
 function parseLease(value) {
@@ -358,6 +399,7 @@ function parseQaScope(value) {
         schema_version: requiredNumber(qaScope, "schema_version"),
         surface: parseOptionalStringArray(qaScope.surface, "qaScope.surface"),
         required_evidence: parseOptionalStringArray(qaScope.required_evidence, "qaScope.required_evidence"),
+        required_capabilities: parseOptionalStringArray(qaScope.required_capabilities ?? qaScope.requiredCapabilities, "qaScope.required_capabilities"),
         not_applicable: parseOptionalStringArray(qaScope.not_applicable, "qaScope.not_applicable"),
         browser_required: optionalBoolean(qaScope, "browser_required") ?? optionalBoolean(qaScope, "browserRequired") ?? false,
         api_required: optionalBoolean(qaScope, "api_required") ?? optionalBoolean(qaScope, "apiRequired") ?? false,
@@ -384,6 +426,7 @@ function parseQaAppLaunchTarget(value) {
         command: optionalString(launchTarget, "command"),
         working_directory: optionalString(launchTarget, "working_directory"),
         ready_url: optionalString(launchTarget, "ready_url"),
+        managed_runtime_port: optionalString(launchTarget, "managed_runtime_port"),
         routes: Array.isArray(routes)
             ? routes.map((entry, index) => {
                 if (typeof entry !== "string") {
@@ -662,6 +705,34 @@ function parseArtifacts(value) {
         };
     });
 }
+function parsePriorPhaseArtifacts(value) {
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error("priorPhaseArtifacts must be an array when provided.");
+    }
+    return value.map((entry, index) => {
+        const artifact = asObject(entry, `priorPhaseArtifacts[${index}]`);
+        const phase = requiredString(artifact, "phase").trim().toLowerCase().replace(/-/g, "_");
+        if (phase !== "implementation" && phase !== "self_review" && phase !== "validation") {
+            throw new Error(`priorPhaseArtifacts[${index}].phase must be implementation, self_review, or validation.`);
+        }
+        return {
+            workItemId: requiredString(artifact, "workItemId"),
+            artifactId: requiredString(artifact, "artifactId"),
+            cycleRunId: requiredString(artifact, "cycleRunId"),
+            phase,
+            status: requiredString(artifact, "status"),
+            producedAt: requiredString(artifact, "producedAt"),
+            sourcePath: requiredString(artifact, "sourcePath"),
+            verdictJson: requiredString(artifact, "verdictJson"),
+            report: optionalString(artifact, "report") ?? "",
+            verdictContentHash: requiredString(artifact, "verdictContentHash").toLowerCase(),
+            reportContentHash: requiredString(artifact, "reportContentHash").toLowerCase()
+        };
+    });
+}
 function asObject(value, label) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         throw new Error(`${label} must be an object.`);

package/dist/shared/format/format-bytes.d.ts

@@ -0,0 +1 @@
+export declare function formatBytes(bytes: number): string;

package/dist/shared/format/format-bytes.js

@@ -0,0 +1,9 @@
+export function formatBytes(bytes) {
+    if (!Number.isFinite(bytes) || bytes <= 0)
+        return "0 B";
+    const units = ["B", "KiB", "MiB", "GiB", "TiB"];
+    const power = Math.max(0, Math.min(units.length - 1, Math.floor(Math.log(bytes) / Math.log(1024))));
+    const value = bytes / 1024 ** power;
+    const precision = power === 0 || value >= 100 ? 0 : 1;
+    return `${value.toFixed(precision)} ${units[power]}`;
+}

package/dist/shared/path/path.d.ts

@@ -1,4 +1,5 @@
 export declare function isSubPath(root: string, candidate: string): boolean;
 export declare function resolveExistingDirectoryPath(inputPath: string): Promise<string>;
+export declare function resolvePathIdentity(inputPath: string): Promise<string>;
 export declare function ensureDirectory(inputPath: string): Promise<string>;
 export declare function safeSegment(value: string, fallback: string): string;

package/dist/shared/path/path.js

@@ -4,7 +4,9 @@ export function isSubPath(root, candidate) {
     const normalizedRoot = path.resolve(root);
     const normalizedCandidate = path.resolve(candidate);
     const relative = path.relative(normalizedRoot, normalizedCandidate);
-    return relative === "" || (!!relative && !relative.startsWith("..") && !path.isAbsolute(relative));
+    return relative === "" || (relative !== ".."
+        && !relative.startsWith(`..${path.sep}`)
+        && !path.isAbsolute(relative));
 }
 export async function resolveExistingDirectoryPath(inputPath) {
     const stat = await fs.stat(inputPath);
@@ -13,6 +15,24 @@ export async function resolveExistingDirectoryPath(inputPath) {
     }
     return await fs.realpath(inputPath);
 }
+export async function resolvePathIdentity(inputPath) {
+    let existingAncestor = path.resolve(inputPath);
+    const missingSegments = [];
+    while (true) {
+        try {
+            return path.join(await fs.realpath(existingAncestor), ...missingSegments);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            const parent = path.dirname(existingAncestor);
+            if (parent === existingAncestor)
+                throw error;
+            missingSegments.unshift(path.basename(existingAncestor));
+            existingAncestor = parent;
+        }
+    }
+}
 export async function ensureDirectory(inputPath) {
     await fs.mkdir(inputPath, { recursive: true });
     return await resolveExistingDirectoryPath(inputPath);

package/dist/shared/process/dotnet-toolchain.d.ts

@@ -0,0 +1,14 @@
+export interface DotNetToolchainSelection {
+    readonly executablePath: string;
+    readonly rootPath: string;
+    readonly sdkVersion: string;
+    readonly requiredMajor: number;
+}
+export interface DotNetToolchainOptions {
+    readonly environment?: NodeJS.ProcessEnv;
+    readonly platform?: NodeJS.Platform;
+    readonly homeDirectory?: string;
+    readonly fileExists?: (candidate: string) => Promise<boolean>;
+    readonly listSdks?: (candidate: string) => Promise<string>;
+}
+export declare function configureDotNetToolchain(repoRoots: readonly string[], options?: DotNetToolchainOptions): Promise<DotNetToolchainSelection | null>;

package/dist/shared/process/dotnet-toolchain.js

@@ -0,0 +1,179 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const skippedDirectories = new Set([".git", "bin", "node_modules", "obj"]);
+export async function configureDotNetToolchain(repoRoots, options = {}) {
+    const environment = options.environment ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const requiredMajor = await requiredDotNetMajor(repoRoots);
+    if (requiredMajor === null)
+        return null;
+    const explicit = environmentValue(environment, "FORGE_DOTNET_PATH");
+    if (explicit && !path.isAbsolute(explicit)) {
+        throw new Error("dotnet_toolchain_invalid: FORGE_DOTNET_PATH must be an absolute executable path.");
+    }
+    const candidates = dotNetCandidates(environment, platform, options.homeDirectory ?? os.homedir(), requiredMajor);
+    const fileExists = options.fileExists ?? isFile;
+    const listSdks = options.listSdks ?? probeSdks;
+    const probed = [];
+    for (const candidate of candidates) {
+        if (!await fileExists(candidate))
+            continue;
+        try {
+            const output = await listSdks(candidate);
+            const sdkVersion = sdkVersions(output).find((version) => majorVersion(version) === requiredMajor);
+            probed.push(`${candidate} (${sdkVersions(output).join(", ") || "no SDKs"})`);
+            if (!sdkVersion)
+                continue;
+            const rootPath = path.dirname(candidate);
+            prependPath(environment, rootPath, platform);
+            setEnvironmentValue(environment, "DOTNET_ROOT", rootPath);
+            if (platform === "win32")
+                setEnvironmentValue(environment, "DOTNET_ROOT_X64", rootPath);
+            setEnvironmentValue(environment, "FORGE_DOTNET_PATH", candidate);
+            return { executablePath: candidate, rootPath, sdkVersion, requiredMajor };
+        }
+        catch (error) {
+            probed.push(`${candidate} (${error instanceof Error ? error.message : String(error)})`);
+        }
+    }
+    const detail = probed.length > 0 ? ` Probed: ${probed.join("; ")}.` : "";
+    throw new Error(`dotnet_toolchain_unavailable: repositories require .NET SDK ${requiredMajor}.x, but no compatible dotnet executable was found.`
+        + ` Set FORGE_DOTNET_PATH to the absolute executable path.${detail}`);
+}
+async function requiredDotNetMajor(repoRoots) {
+    const majors = [];
+    for (const root of [...new Set(repoRoots.map((candidate) => path.resolve(candidate)))]) {
+        const globalMajor = await readGlobalJsonMajor(root);
+        if (globalMajor !== null) {
+            majors.push(globalMajor);
+            continue;
+        }
+        majors.push(...await readProjectTargetMajors(root));
+    }
+    return majors.length > 0 ? Math.max(...majors) : null;
+}
+async function readGlobalJsonMajor(root) {
+    try {
+        const parsed = JSON.parse(await fs.readFile(path.join(root, "global.json"), "utf8"));
+        return typeof parsed.sdk?.version === "string" ? majorVersion(parsed.sdk.version) : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function readProjectTargetMajors(root) {
+    const projects = await findProjectFiles(root, 4, 256);
+    const majors = [];
+    for (const project of projects) {
+        let source;
+        try {
+            source = await fs.readFile(project, "utf8");
+        }
+        catch {
+            continue;
+        }
+        for (const match of source.matchAll(/<TargetFrameworks?>\s*([^<]+)\s*<\/TargetFrameworks?>/giu)) {
+            for (const framework of match[1]?.split(";") ?? []) {
+                const target = /^net(\d+)\./iu.exec(framework.trim());
+                if (target?.[1])
+                    majors.push(Number.parseInt(target[1], 10));
+            }
+        }
+    }
+    return majors;
+}
+async function findProjectFiles(root, maximumDepth, maximumFiles) {
+    const projects = [];
+    async function visit(directory, depth) {
+        if (depth > maximumDepth || projects.length >= maximumFiles)
+            return;
+        let entries;
+        try {
+            entries = await fs.readdir(directory, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (projects.length >= maximumFiles)
+                return;
+            if (entry.isDirectory() && !skippedDirectories.has(entry.name)) {
+                await visit(path.join(directory, entry.name), depth + 1);
+            }
+            else if (entry.isFile() && entry.name.toLowerCase().endsWith(".csproj")) {
+                projects.push(path.join(directory, entry.name));
+            }
+        }
+    }
+    await visit(root, 0);
+    return projects;
+}
+function dotNetCandidates(environment, platform, homeDirectory, requiredMajor) {
+    const executable = platform === "win32" ? "dotnet.exe" : "dotnet";
+    const explicit = environmentValue(environment, "FORGE_DOTNET_PATH");
+    if (explicit)
+        return [explicit];
+    const dotNetRoot = environmentValue(environment, "DOTNET_ROOT");
+    const pathValue = environmentValue(environment, "PATH") ?? "";
+    const programFiles = environmentValue(environment, "ProgramFiles");
+    const candidates = [
+        dotNetRoot ? path.join(dotNetRoot, executable) : null,
+        path.join(homeDirectory, ".dotnet", executable),
+        path.join(homeDirectory, `.dotnet${requiredMajor}`, executable),
+        ...(platform === "win32" && programFiles ? [path.join(programFiles, "dotnet", executable)] : []),
+        ...pathValue.split(path.delimiter).filter(Boolean).map((directory) => path.join(directory, executable)),
+    ].filter((candidate) => Boolean(candidate));
+    return [...new Map(candidates.map((candidate) => [canonicalPath(candidate, platform), path.resolve(candidate)])).values()];
+}
+async function probeSdks(candidate) {
+    const { stdout } = await execFileAsync(candidate, ["--list-sdks"], {
+        encoding: "utf8",
+        timeout: 10_000,
+        windowsHide: true,
+    });
+    return stdout;
+}
+function sdkVersions(output) {
+    return output.split(/\r?\n/gu)
+        .map((line) => /^(\d+\.\d+\.\d+(?:[-+][^\s]+)?)/u.exec(line.trim())?.[1] ?? null)
+        .filter((version) => version !== null);
+}
+function majorVersion(version) {
+    const match = /^(\d+)\./u.exec(version.trim());
+    return match?.[1] ? Number.parseInt(match[1], 10) : null;
+}
+async function isFile(candidate) {
+    try {
+        return (await fs.stat(candidate)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function prependPath(environment, directory, platform) {
+    const current = environmentValue(environment, "PATH") ?? "";
+    const normalizedDirectory = canonicalPath(directory, platform);
+    const remaining = current.split(path.delimiter)
+        .filter(Boolean)
+        .filter((entry) => canonicalPath(entry, platform) !== normalizedDirectory);
+    setEnvironmentValue(environment, "PATH", [directory, ...remaining].join(path.delimiter));
+}
+function environmentValue(environment, name) {
+    const key = Object.keys(environment).find((candidate) => candidate.toLowerCase() === name.toLowerCase());
+    return key ? environment[key] : undefined;
+}
+function setEnvironmentValue(environment, name, value) {
+    const keys = Object.keys(environment).filter((candidate) => candidate.toLowerCase() === name.toLowerCase());
+    const target = keys[0] ?? name;
+    for (const duplicate of keys.slice(1))
+        delete environment[duplicate];
+    environment[target] = value;
+}
+function canonicalPath(candidate, platform) {
+    const normalized = path.normalize(candidate);
+    return platform === "win32" ? normalized.toLowerCase() : normalized;
+}

package/dist/shared/process/host-process-recovery.d.ts

@@ -0,0 +1,12 @@
+import type { HostProcessSupervisorMetadata } from "./host-process-supervisor.js";
+export type HostProcessRecoveryOutcome = "absent" | "terminated" | "pid_reused" | "unverifiable";
+export interface HostProcessRecovery {
+    recover(metadata: HostProcessSupervisorMetadata): Promise<HostProcessRecoveryOutcome>;
+}
+/** Exact, birth-marker-fenced recovery for a process tree left by an old bridge. */
+export declare class ExactHostProcessRecovery implements HostProcessRecovery {
+    private readonly platform;
+    private readonly graceMs;
+    constructor(platform?: NodeJS.Platform, graceMs?: number);
+    recover(metadata: HostProcessSupervisorMetadata): Promise<HostProcessRecoveryOutcome>;
+}

package/dist/shared/process/host-process-recovery.js

@@ -0,0 +1,78 @@
+import { captureHostProcessIdentity } from "./host-process-supervisor.js";
+/** Exact, birth-marker-fenced recovery for a process tree left by an old bridge. */
+export class ExactHostProcessRecovery {
+    platform;
+    graceMs;
+    constructor(platform = process.platform, graceMs = 2_000) {
+        this.platform = platform;
+        this.graceMs = graceMs;
+    }
+    async recover(metadata) {
+        if (!processExists(metadata.rootPid))
+            return "absent";
+        if (!metadata.rootIdentity)
+            return "unverifiable";
+        const currentIdentity = captureHostProcessIdentity(metadata.rootPid, this.platform);
+        if (!currentIdentity)
+            return processExists(metadata.rootPid) ? "unverifiable" : "absent";
+        if (currentIdentity !== metadata.rootIdentity)
+            return "pid_reused";
+        if (this.platform === "win32") {
+            signalExactProcess(metadata.rootPid, "SIGTERM");
+        }
+        else {
+            signalExactProcessGroup(metadata.rootPid, "SIGTERM");
+        }
+        await waitForExit(metadata.rootPid, this.graceMs);
+        if (processExists(metadata.rootPid)) {
+            if (captureHostProcessIdentity(metadata.rootPid, this.platform) !== metadata.rootIdentity) {
+                return "pid_reused";
+            }
+            if (this.platform === "win32") {
+                signalExactProcess(metadata.rootPid, "SIGKILL");
+            }
+            else {
+                signalExactProcessGroup(metadata.rootPid, "SIGKILL");
+            }
+            await waitForExit(metadata.rootPid, this.graceMs);
+        }
+        if (processExists(metadata.rootPid)
+            && captureHostProcessIdentity(metadata.rootPid, this.platform) === metadata.rootIdentity) {
+            throw new Error("host_process_recovery_degraded: exact supervised process tree did not stop.");
+        }
+        return "terminated";
+    }
+}
+function processExists(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+function signalExactProcess(pid, signal) {
+    try {
+        process.kill(pid, signal);
+    }
+    catch (error) {
+        if (error.code !== "ESRCH")
+            throw error;
+    }
+}
+function signalExactProcessGroup(pid, signal) {
+    try {
+        process.kill(-pid, signal);
+    }
+    catch (error) {
+        if (error.code !== "ESRCH")
+            throw error;
+    }
+}
+async function waitForExit(pid, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline && processExists(pid)) {
+        await new Promise(resolve => setTimeout(resolve, 25));
+    }
+}