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

package/dist/session/managed-build-coordinator.d.ts

@@ -0,0 +1,5 @@
+export declare class ManagedBuildCoordinator {
+    private readonly stateRoot;
+    constructor(stateRoot?: string);
+    withBuildSlot<T>(worktreePath: string, action: (queueWaitMs: number) => Promise<T>, onWaiting?: () => Promise<void>): Promise<T>;
+}

package/dist/session/managed-build-coordinator.js

@@ -0,0 +1,105 @@
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { defaultWorktreeCoordinatorStateRoot } from "../worktree/worktree-paths.js";
+const heartbeatIntervalMs = 30_000;
+const staleAfterMs = 2 * 60_000;
+const acquisitionTimeoutMs = 2 * 60 * 60_000;
+const pollIntervalMs = 100;
+export class ManagedBuildCoordinator {
+    stateRoot;
+    constructor(stateRoot = defaultWorktreeCoordinatorStateRoot()) {
+        this.stateRoot = stateRoot;
+    }
+    async withBuildSlot(worktreePath, action, onWaiting) {
+        const resolved = path.resolve(worktreePath);
+        const key = createHash("sha256").update(resolved.toLowerCase()).digest("hex");
+        const root = path.join(this.stateRoot, "managed-build-locks");
+        const target = path.join(root, `${key}.lock`);
+        const token = randomUUID();
+        const startedAt = Date.now();
+        let waitingReported = false;
+        await fs.mkdir(root, { recursive: true, mode: 0o700 });
+        while (true) {
+            try {
+                const handle = await fs.open(target, "wx", 0o600);
+                try {
+                    await handle.writeFile(`${JSON.stringify({
+                        schemaVersion: 1,
+                        token,
+                        pid: process.pid,
+                        worktreePath: resolved,
+                        acquiredAt: new Date().toISOString(),
+                    })}\n`);
+                    await handle.sync();
+                }
+                finally {
+                    await handle.close();
+                }
+                break;
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+                if (await staleLock(target)) {
+                    await fs.rm(target, { force: true });
+                    continue;
+                }
+                if (!waitingReported) {
+                    waitingReported = true;
+                    await onWaiting?.();
+                }
+                if (Date.now() - startedAt >= acquisitionTimeoutMs) {
+                    throw new Error("managed_build_slot_timeout: another build held this worktree for more than two hours.", { cause: error });
+                }
+                await delay(pollIntervalMs);
+            }
+        }
+        const heartbeat = setInterval(() => void refreshHeartbeat(target, token), heartbeatIntervalMs);
+        heartbeat.unref?.();
+        try {
+            return await action(Date.now() - startedAt);
+        }
+        finally {
+            clearInterval(heartbeat);
+            const owner = await readOwner(target);
+            if (owner?.token === token)
+                await fs.rm(target, { force: true });
+        }
+    }
+}
+async function staleLock(target) {
+    const stat = await fs.lstat(target).catch(() => null);
+    if (!stat || stat.isSymbolicLink() || !stat.isFile() || stat.size > 16 * 1024)
+        return true;
+    if (Date.now() - stat.mtimeMs >= staleAfterMs)
+        return true;
+    const owner = await readOwner(target);
+    // A competing process can observe the exclusive lock file between open("wx")
+    // and the owner JSON being flushed. Keep a fresh unreadable lock rather than
+    // deleting a lock whose writer is still publishing its ownership record.
+    if (!owner || !Number.isInteger(owner.pid) || (owner.pid ?? 0) <= 0)
+        return false;
+    try {
+        process.kill(owner.pid, 0);
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
+async function refreshHeartbeat(target, token) {
+    const owner = await readOwner(target);
+    if (owner?.token !== token)
+        return;
+    const now = new Date();
+    await fs.utimes(target, now, now).catch(() => undefined);
+}
+async function readOwner(target) {
+    return await fs.readFile(target, "utf8")
+        .then(value => JSON.parse(value))
+        .catch(() => null);
+}
+async function delay(ms) {
+    await new Promise(resolve => setTimeout(resolve, ms));
+}

package/dist/session/managed-build-receipt.d.ts

@@ -0,0 +1,21 @@
+export interface ManagedBuildReceiptEvidence {
+    readonly fingerprint: string;
+    readonly receiptPath: string;
+    readonly producerCommand: readonly string[];
+    readonly configuration: string;
+    readonly coverage: string;
+    readonly outputCount: number;
+}
+export declare function publishManagedBuildReceipt(options: {
+    readonly worktreePath: string;
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly configuration: string;
+    readonly coverage: string;
+}): Promise<ManagedBuildReceiptEvidence | null>;
+export declare function verifyManagedBuildReceipt(options: {
+    readonly worktreePath: string;
+    readonly configuration: string;
+    readonly requiredCoverage: string;
+}): Promise<ManagedBuildReceiptEvidence>;
+export declare function managedBuildConfiguration(command: string, args: readonly string[]): string;

package/dist/session/managed-build-receipt.js

@@ -0,0 +1,337 @@
+import { createHash, randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { defaultWorktreeCoordinatorStateRoot } from "../worktree/worktree-paths.js";
+const schemaVersion = 1;
+const maximumRetainedReceipts = 8;
+const maximumOutputManifestEntries = 20_000;
+const skippedTraversalDirectories = new Set([
+    ".git",
+    ".forge-worktrees",
+    "node_modules",
+    ".venv",
+    "bin",
+    "obj",
+    "TestResults",
+    "artifacts",
+]);
+export async function publishManagedBuildReceipt(options) {
+    const worktreePath = path.resolve(options.worktreePath);
+    const inputs = await currentBuildInputs(worktreePath);
+    const outputs = await collectBuildOutputs(worktreePath);
+    if (outputs.length === 0)
+        return null;
+    const producerCommand = [options.command, ...options.args];
+    const producerCommandFingerprint = sha256Json(producerCommand);
+    const fingerprint = `sha256:${sha256Json({
+        ...inputs,
+        configuration: options.configuration,
+        coverage: options.coverage,
+        producerCommandFingerprint,
+        outputs,
+    })}`;
+    const directory = managedBuildReceiptDirectory(worktreePath);
+    const receiptPath = path.join(directory, `${fingerprint.slice("sha256:".length)}.json`);
+    const receipt = {
+        schemaVersion,
+        fingerprint,
+        ...inputs,
+        configuration: options.configuration,
+        coverage: options.coverage,
+        producerCommand,
+        producerCommandFingerprint,
+        outputs,
+        completedAt: new Date().toISOString(),
+    };
+    await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+    await persistImmutableReceipt(receiptPath, receipt);
+    await persistJsonAtomically(path.join(directory, "current.json"), {
+        schemaVersion,
+        fingerprint,
+        receiptPath,
+    });
+    await pruneReceipts(directory, receiptPath);
+    return evidence(receipt, receiptPath);
+}
+export async function verifyManagedBuildReceipt(options) {
+    const worktreePath = path.resolve(options.worktreePath);
+    const directory = managedBuildReceiptDirectory(worktreePath);
+    const pointer = await readJson(path.join(directory, "current.json"));
+    const receiptPath = typeof pointer?.receiptPath === "string" ? pointer.receiptPath : "";
+    if (!receiptPath || path.dirname(receiptPath) !== directory) {
+        throw new Error("managed_verification_build_receipt_required: no verified local build receipt is available.");
+    }
+    const receipt = await readBuildReceipt(receiptPath);
+    if (!receipt || receipt.fingerprint !== pointer?.fingerprint) {
+        throw new Error("managed_verification_build_receipt_invalid: the local build receipt is missing or corrupt.");
+    }
+    if (receipt.configuration.toLowerCase() !== options.configuration.toLowerCase()) {
+        throw new Error(`managed_verification_build_receipt_mismatch: expected ${options.configuration} outputs but receipt proves ${receipt.configuration}.`);
+    }
+    if (receipt.coverage !== options.requiredCoverage) {
+        throw new Error(`managed_verification_build_receipt_mismatch: expected ${options.requiredCoverage} coverage but receipt proves ${receipt.coverage}.`);
+    }
+    const current = await currentBuildInputs(worktreePath);
+    if (receipt.sourceDigest !== current.sourceDigest
+        || receipt.dependencyDigest !== current.dependencyDigest
+        || receipt.toolchain !== current.toolchain
+        || receipt.platform !== current.platform
+        || receipt.architecture !== current.architecture
+        || receipt.policyFingerprint !== current.policyFingerprint) {
+        throw new Error("managed_verification_build_receipt_mismatch: source, dependencies, toolchain, platform, or policy changed after the verified build.");
+    }
+    if (!(await outputsMatch(worktreePath, receipt.outputs))) {
+        throw new Error("managed_verification_build_receipt_output_missing: one or more verified build outputs are missing or changed.");
+    }
+    return evidence(receipt, receiptPath);
+}
+export function managedBuildConfiguration(command, args) {
+    const optionIndex = args.findIndex(argument => ["-c", "--configuration", "-Configuration"].includes(argument));
+    if (optionIndex >= 0 && args[optionIndex + 1])
+        return args[optionIndex + 1];
+    const inline = args.find(argument => /^--configuration=/iu.test(argument));
+    if (inline)
+        return inline.slice(inline.indexOf("=") + 1);
+    const executable = path.basename(command).toLowerCase();
+    const scriptIndex = args.findIndex(argument => argument.toLowerCase() === "-file");
+    const script = scriptIndex >= 0 ? path.basename(args[scriptIndex + 1] ?? "").toLowerCase() : "";
+    // The affected-tests runner builds Release before running the Release tier scripts.
+    const runsAffectedTests = args.some(argument => path.basename(argument).toLowerCase() === "run-affected-dotnet-tests.mjs");
+    return executable.includes("powershell") || executable === "pwsh" || executable === "pwsh.exe"
+        || script.startsWith("run-dotnet-test-") || runsAffectedTests
+        ? "Release"
+        : "Debug";
+}
+function managedBuildReceiptDirectory(worktreePath) {
+    const key = createHash("sha256").update(path.resolve(worktreePath).toLowerCase()).digest("hex");
+    return path.join(defaultWorktreeCoordinatorStateRoot(), "managed-build-receipts", key);
+}
+async function currentBuildInputs(worktreePath) {
+    const [sourceDigest, dependencyDigest, toolchain] = await Promise.all([
+        worktreeSourceDigest(worktreePath),
+        dependencyReceiptsDigest(worktreePath),
+        dotnetVersion(worktreePath),
+    ]);
+    return {
+        sourceDigest,
+        dependencyDigest,
+        toolchain,
+        platform: process.platform,
+        architecture: process.arch,
+        policyFingerprint: `sha256:${sha256Json({
+            contract: "managed-build-reuse-v1",
+            runtimeMode: process.env.FORGE_RUNTIME_MODE ?? "host",
+            trustDomain: sha256Text(process.env.FORGE_TRUST_DOMAIN_ID ?? "default"),
+            invalidationEpoch: sha256Text(process.env.FORGE_BUILD_CACHE_EPOCH ?? "default"),
+            dotnetRoot: process.env.DOTNET_ROOT ?? null,
+            msbuildSdksPath: process.env.MSBuildSDKsPath ?? null,
+            nugetPackages: process.env.NUGET_PACKAGES ?? null,
+        })}`,
+    };
+}
+async function worktreeSourceDigest(worktreePath) {
+    const names = await gitFileNames(worktreePath);
+    const hash = createHash("sha256");
+    for (const relative of names) {
+        const absolute = path.resolve(worktreePath, relative);
+        const containment = path.relative(worktreePath, absolute);
+        if (containment.startsWith(`..${path.sep}`) || path.isAbsolute(containment))
+            continue;
+        const stat = await fs.stat(absolute).catch(() => null);
+        if (!stat?.isFile())
+            continue;
+        hash.update(relative.replaceAll("\\", "/"));
+        hash.update("\0");
+        hash.update(await fs.readFile(absolute));
+        hash.update("\0");
+    }
+    return `sha256:${hash.digest("hex")}`;
+}
+async function gitFileNames(worktreePath) {
+    const output = await runProcess(worktreePath, "git", [
+        "ls-files",
+        "-z",
+        "--cached",
+        "--others",
+        "--exclude-standard",
+    ]);
+    if (output.exitCode !== 0) {
+        throw new Error(`managed_build_source_digest_failed: git ls-files exited ${output.exitCode}.`);
+    }
+    return output.stdout.split("\0").filter(Boolean).sort((left, right) => left.localeCompare(right));
+}
+async function dependencyReceiptsDigest(worktreePath) {
+    const receipts = [];
+    await walkDirectories(worktreePath, 0, async (directory, name) => {
+        if (!["node_modules", ".venv", "obj"].includes(name))
+            return;
+        const receiptPath = path.join(directory, name, ".forge-dependency-preparation.json");
+        const content = await fs.readFile(receiptPath).catch(() => null);
+        if (content)
+            receipts.push({
+                path: path.relative(worktreePath, receiptPath).replaceAll("\\", "/"),
+                digest: createHash("sha256").update(content).digest("hex"),
+            });
+    });
+    receipts.sort((left, right) => left.path.localeCompare(right.path));
+    return `sha256:${sha256Json(receipts)}`;
+}
+async function collectBuildOutputs(worktreePath) {
+    const outputs = [];
+    await walkDirectories(worktreePath, 0, async (directory, name) => {
+        if (name !== "bin")
+            return;
+        await collectFiles(path.join(directory, name), worktreePath, outputs);
+    });
+    outputs.sort((left, right) => left.path.localeCompare(right.path));
+    if (outputs.length > maximumOutputManifestEntries) {
+        throw new Error(`managed_build_receipt_too_large: build produced more than ${maximumOutputManifestEntries} output files.`);
+    }
+    return outputs;
+}
+async function collectFiles(directory, worktreePath, outputs) {
+    const entries = await fs.readdir(directory, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+        const absolute = path.join(directory, entry.name);
+        if (entry.isDirectory())
+            await collectFiles(absolute, worktreePath, outputs);
+        else if (entry.isFile()) {
+            const stat = await fs.stat(absolute);
+            outputs.push({
+                path: path.relative(worktreePath, absolute).replaceAll("\\", "/"),
+                size: stat.size,
+                digest: createHash("sha256").update(await fs.readFile(absolute)).digest("hex"),
+            });
+        }
+    }
+}
+async function walkDirectories(directory, depth, observe) {
+    if (depth > 8)
+        return;
+    const entries = await fs.readdir(directory, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        await observe(directory, entry.name);
+        if (!skippedTraversalDirectories.has(entry.name) && !entry.name.startsWith(".")) {
+            await walkDirectories(path.join(directory, entry.name), depth + 1, observe);
+        }
+    }
+}
+async function outputsMatch(worktreePath, outputs) {
+    if (outputs.length === 0)
+        return false;
+    for (const output of outputs) {
+        const absolute = path.resolve(worktreePath, output.path);
+        const containment = path.relative(worktreePath, absolute);
+        if (containment.startsWith(`..${path.sep}`) || path.isAbsolute(containment))
+            return false;
+        const stat = await fs.stat(absolute).catch(() => null);
+        if (!stat?.isFile() || stat.size !== output.size)
+            return false;
+        const digest = createHash("sha256").update(await fs.readFile(absolute)).digest("hex");
+        if (digest !== output.digest)
+            return false;
+    }
+    return true;
+}
+async function dotnetVersion(cwd) {
+    const result = await runProcess(cwd, "dotnet", ["--version"]);
+    return result.exitCode === 0
+        ? `dotnet@${result.stdout.trim() || result.stderr.trim() || "unknown"}`
+        : `dotnet@unavailable:${result.exitCode}`;
+}
+async function runProcess(cwd, command, args) {
+    return await new Promise((resolve, reject) => {
+        const child = spawn(command, args, { cwd, windowsHide: true, stdio: ["ignore", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", chunk => { stdout += String(chunk); });
+        child.stderr.on("data", chunk => { stderr += String(chunk); });
+        child.once("error", reject);
+        child.once("close", exitCode => resolve({ exitCode, stdout, stderr }));
+    });
+}
+async function persistImmutableReceipt(receiptPath, receipt) {
+    const existing = await readBuildReceipt(receiptPath);
+    if (existing)
+        return;
+    const temporaryPath = `${receiptPath}.${randomUUID()}.tmp`;
+    await fs.writeFile(temporaryPath, `${JSON.stringify(receipt, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    try {
+        await fs.rename(temporaryPath, receiptPath).catch(async (error) => {
+            if (error.code !== "EEXIST")
+                throw error;
+        });
+    }
+    finally {
+        await fs.rm(temporaryPath, { force: true }).catch(() => undefined);
+    }
+}
+async function persistJsonAtomically(receiptPath, value) {
+    const temporaryPath = `${receiptPath}.${randomUUID()}.tmp`;
+    await fs.writeFile(temporaryPath, `${JSON.stringify(value, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    try {
+        await fs.rename(temporaryPath, receiptPath);
+    }
+    finally {
+        await fs.rm(temporaryPath, { force: true }).catch(() => undefined);
+    }
+}
+async function readBuildReceipt(receiptPath) {
+    const value = await readJson(receiptPath);
+    return value?.schemaVersion === schemaVersion
+        && typeof value.fingerprint === "string"
+        && typeof value.sourceDigest === "string"
+        && typeof value.dependencyDigest === "string"
+        && typeof value.toolchain === "string"
+        && typeof value.policyFingerprint === "string"
+        && typeof value.configuration === "string"
+        && typeof value.coverage === "string"
+        && Array.isArray(value.producerCommand)
+        && Array.isArray(value.outputs)
+        ? value
+        : null;
+}
+async function readJson(receiptPath) {
+    try {
+        return JSON.parse(await fs.readFile(receiptPath, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT" || error instanceof SyntaxError)
+            return null;
+        throw error;
+    }
+}
+async function pruneReceipts(directory, preservedPath) {
+    const entries = await fs.readdir(directory, { withFileTypes: true });
+    const receipts = await Promise.all(entries
+        .filter(entry => entry.isFile() && /^[0-9a-f]{64}\.json$/u.test(entry.name))
+        .map(async (entry) => {
+        const receiptPath = path.join(directory, entry.name);
+        return { receiptPath, stat: await fs.stat(receiptPath) };
+    }));
+    receipts.sort((left, right) => right.stat.mtimeMs - left.stat.mtimeMs);
+    await Promise.all(receipts.slice(maximumRetainedReceipts)
+        .filter(entry => entry.receiptPath !== preservedPath)
+        .map(entry => fs.rm(entry.receiptPath, { force: true })));
+}
+function evidence(receipt, receiptPath) {
+    return {
+        fingerprint: receipt.fingerprint,
+        receiptPath,
+        producerCommand: receipt.producerCommand,
+        configuration: receipt.configuration,
+        coverage: receipt.coverage,
+        outputCount: receipt.outputs.length,
+    };
+}
+function sha256Json(value) {
+    return sha256Text(JSON.stringify(value));
+}
+function sha256Text(value) {
+    return createHash("sha256").update(value).digest("hex");
+}

package/dist/session/managed-verification-timeouts.d.ts

@@ -0,0 +1,8 @@
+export declare const managedQuickTierTimeoutMs = 900000;
+export declare const managedLongTierTimeoutMs = 2700000;
+export declare const managedShardWaveTimeoutMs = 900000;
+export declare const managedMaximumCommandTimeoutMs = 7200000;
+export declare function managedVerificationTierTimeoutMs(tier: string, allShards?: {
+    readonly shardCount: number;
+    readonly maxParallelism: number;
+}): number;

package/dist/session/managed-verification-timeouts.js

@@ -0,0 +1,17 @@
+// Runner-owned limits for managed .NET verification. The comment-repair prompt quotes
+// them, so an agent knows a tier that is still running has not failed: Forge terminates
+// a hung command at its limit and the receipt then reports timed_out.
+export const managedQuickTierTimeoutMs = 900_000;
+export const managedLongTierTimeoutMs = 2_700_000;
+export const managedShardWaveTimeoutMs = 900_000;
+export const managedMaximumCommandTimeoutMs = 7_200_000;
+export function managedVerificationTierTimeoutMs(tier, allShards) {
+    if (tier === "Unit" || tier === "Contract")
+        return managedQuickTierTimeoutMs;
+    if (!allShards)
+        return managedLongTierTimeoutMs;
+    // One window covers the build and every wave of shards, so a single-shard limit would
+    // end a healthy all-shard run of a large tier.
+    const waves = Math.ceil(allShards.shardCount / Math.max(1, allShards.maxParallelism));
+    return Math.min(managedMaximumCommandTimeoutMs, Math.max(managedLongTierTimeoutMs, managedShardWaveTimeoutMs * (waves + 1)));
+}

package/dist/session/phase-completion.artifacts.d.ts

@@ -0,0 +1,27 @@
+import { type CompletionArtifactReference, type CompletionPhase, type CompletionToolServerConfig, type DecomposeCompletionGate, type DraftCompletionGate, type QaCompletionGate } from "./phase-completion.js";
+import type { RunnerDispatchArtifact } from "./session.types.js";
+export declare function writeDecomposeGateCompletionArtifact(config: CompletionToolServerConfig, gate: DecomposeCompletionGate, toolName: string, input: unknown): Promise<CompletionArtifactReference>;
+export declare function writeDraftGateCompletionArtifact(config: CompletionToolServerConfig, gate: DraftCompletionGate, toolName: string, input: unknown): Promise<CompletionArtifactReference>;
+export declare function writeCompletionArtifact(config: CompletionToolServerConfig, toolName: string, input: unknown): Promise<CompletionArtifactReference>;
+export declare function writeArchitectCompletionArtifact(config: CompletionToolServerConfig, payload: Record<string, unknown>, status: string, producedBy: string): Promise<CompletionArtifactReference>;
+export declare function writeQaGateCompletionArtifact(config: CompletionToolServerConfig, gate: QaCompletionGate, input: unknown): Promise<CompletionArtifactReference>;
+export declare function writeQaCompletionArtifact(config: CompletionToolServerConfig, payload: Record<string, unknown>, status: string, producedBy: string): Promise<CompletionArtifactReference>;
+export declare function readQaGateArtifact(config: CompletionToolServerConfig, gate: QaCompletionGate): Promise<Record<string, unknown>>;
+export declare function readCompletionArtifact(worktreePath: string, workItemId: string, phase: CompletionPhase, ownerType?: string | null, ownerId?: string | null): Promise<RunnerDispatchArtifact | null>;
+export interface ArtifactBundleFile {
+    readonly fileName: string;
+    readonly content: string;
+}
+export interface ArtifactBundlePublicationOptions {
+    readonly signal?: AbortSignal;
+    /** Fault-injection hook used by publication tests. */
+    readonly beforePublishFile?: (fileName: string, index: number) => void | Promise<void>;
+}
+/**
+ * Stages a complete phase bundle outside the live artifact directory, then
+ * publishes its canonical verdict/marker last. Consumers treat the marker as
+ * the bundle's commit point, so they can observe either the old complete bundle
+ * or the new complete bundle, never a partially written set. A failed or
+ * cancelled publication rolls every touched file back before rejecting.
+ */
+export declare function publishArtifactBundleAtomic(artifactRoot: string, files: readonly ArtifactBundleFile[], commitFileName: string, options?: ArtifactBundlePublicationOptions): Promise<void>;