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

package/dist/session/managed-attempt-tools.js

@@ -0,0 +1,912 @@
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { resetGeneratedOutputs } from "../runtime/generated-output-reset.js";
+import { ManagedBuildCoordinator } from "./managed-build-coordinator.js";
+import { managedBuildConfiguration, publishManagedBuildReceipt, verifyManagedBuildReceipt, } from "./managed-build-receipt.js";
+import { resolveWindowsCommandFromPath, StreamingProviderProcessRunner } from "./provider-cli/provider-cli.process.js";
+const managedCommandNames = new Set(["forge.run_managed_command", "run_managed_command"]);
+const startManagedCommandNames = new Set(["forge.start_managed_command", "start_managed_command"]);
+const getManagedCommandNames = new Set(["forge.get_managed_command", "get_managed_command"]);
+const waitManagedCommandNames = new Set(["forge.wait_managed_command", "wait_managed_command"]);
+const startManagedVerificationNames = new Set(["forge.start_managed_verification", "start_managed_verification"]);
+const resetGeneratedOutputNames = new Set(["forge.reset_generated_outputs", "reset_generated_outputs"]);
+const maximumCapturedCharacters = 200_000;
+const maximumReturnedOutputCharacters = 4_000;
+const maximumReportedFailedTests = 50;
+// Keep a wait slice comfortably below the MCP transport deadline. The managed
+// process remains supervised and its durable receipt continues to update after
+// this call returns, so a shorter slice avoids converting healthy long-running
+// commands into ambiguous MCP failures.
+const maximumSynchronousWaitMs = 45_000;
+const managedCommandRetryAfterMs = 60_000;
+const managedCommandLaunchTimeoutMs = 60_000;
+const managedCommandProgressPersistIntervalMs = 5_000;
+const managedCommandReceiptPollIntervalMs = 1_000;
+const managedCommandReceiptReplaceAttempts = 40;
+const managedCommandReceiptReplaceRetryMs = 25;
+const terminalManagedCommandStatuses = new Set([
+    "pass",
+    "fail",
+    "timed_out",
+    "timeout_termination_failed",
+    "runner_error",
+]);
+const managedVerificationBuildCoverage = "forge_dotnet_test_graph_v1";
+const managedCommandTasks = new Map();
+export const managedAttemptToolNames = [
+    "forge.run_managed_command",
+    "run_managed_command",
+    "forge.start_managed_command",
+    "start_managed_command",
+    "forge.get_managed_command",
+    "get_managed_command",
+    "forge.wait_managed_command",
+    "wait_managed_command",
+    "forge.start_managed_verification",
+    "start_managed_verification",
+    "forge.reset_generated_outputs",
+    "reset_generated_outputs",
+];
+export function isManagedAttemptTool(name) {
+    return managedCommandNames.has(name)
+        || startManagedCommandNames.has(name)
+        || getManagedCommandNames.has(name)
+        || waitManagedCommandNames.has(name)
+        || startManagedVerificationNames.has(name)
+        || resetGeneratedOutputNames.has(name);
+}
+export function managedAttemptToolDefinition(name) {
+    if (startManagedVerificationNames.has(name)) {
+        return {
+            name,
+            description: "Start a canonical Forge verification profile with runner-owned cwd, arguments, attempt output, timeout, and process supervision. Prefer this over reconstructing broad .NET commands. Continue independent work, then use forge.wait_managed_command for a transport-safe terminal receipt.",
+            inputSchema: {
+                type: "object",
+                additionalProperties: false,
+                required: ["profile"],
+                properties: {
+                    profile: {
+                        type: "string",
+                        enum: ["dotnet_unit", "dotnet_contract", "dotnet_api_component", "dotnet_orchestration", "dotnet_infrastructure", "dotnet_solution"],
+                    },
+                    shard_count: { type: "integer", minimum: 1, maximum: 32, default: 1 },
+                    shard_index: { type: "integer", minimum: 0, maximum: 31, default: 0 },
+                    run_all_shards: { type: "boolean", default: false },
+                    max_parallelism: { type: "integer", minimum: 1, maximum: 4, default: 2 },
+                    no_build: { type: "boolean", default: false },
+                    timeout_ms: { type: "integer", minimum: 1000, maximum: 7200000 },
+                },
+            },
+        };
+    }
+    if (managedCommandNames.has(name) || startManagedCommandNames.has(name)) {
+        return {
+            name,
+            description: startManagedCommandNames.has(name)
+                ? "Start a long command in an attempt-owned process tree and return a durable command ID immediately. Continue independent work, then use forge.wait_managed_command for a transport-safe terminal receipt."
+                : "Run a short command in an attempt-owned process tree. Commands with a timeout above four minutes automatically start asynchronously; continue independent work, then use forge.wait_managed_command for the durable result.",
+            inputSchema: {
+                type: "object",
+                additionalProperties: false,
+                required: ["command", "args"],
+                properties: {
+                    command: { type: "string", minLength: 1 },
+                    args: { type: "array", items: { type: "string" } },
+                    cwd: { type: "string", description: "Worktree-relative directory; defaults to the worktree root." },
+                    timeout_ms: { type: "integer", minimum: 1000, maximum: 7200000, default: 2700000 },
+                },
+            },
+        };
+    }
+    if (getManagedCommandNames.has(name)) {
+        return {
+            name,
+            description: "Read the durable status and final receipt for a command started by Forge's managed command runner.",
+            inputSchema: {
+                type: "object",
+                additionalProperties: false,
+                required: ["command_id"],
+                properties: {
+                    command_id: { type: "string", minLength: 1 },
+                },
+            },
+        };
+    }
+    if (waitManagedCommandNames.has(name)) {
+        return {
+            name,
+            description: "Wait up to 45 seconds for a managed command terminal receipt. If it remains active, the call succeeds with command_continues=true and retry_after_ms; continue independent work or wait again later. Live progress remains in the durable receipt/UI; do not poll get_managed_command.",
+            inputSchema: {
+                type: "object",
+                additionalProperties: false,
+                required: ["command_id"],
+                properties: {
+                    command_id: { type: "string", minLength: 1 },
+                    wait_timeout_ms: { type: "integer", minimum: 1000, maximum: 45000, default: 45000 },
+                },
+            },
+        };
+    }
+    return {
+        name,
+        description: "Quarantine known untracked generated test-output directories into this attempt's private output directory.",
+        inputSchema: { type: "object", additionalProperties: false, properties: {} },
+    };
+}
+export async function callManagedAttemptTool(name, input, worktreePath) {
+    if (resetGeneratedOutputNames.has(name)) {
+        const outputDirectory = requiredAttemptEnvironment("FORGE_TEST_OUTPUT_DIR");
+        const result = await resetGeneratedOutputs(worktreePath, outputDirectory);
+        return {
+            content: [{
+                    type: "text",
+                    text: result.quarantinedPaths.length === 0
+                        ? "Forge found no stale generated output in the source worktree."
+                        : `Forge quarantined ${result.quarantinedPaths.length} generated-output director${result.quarantinedPaths.length === 1 ? "y" : "ies"}: ${result.quarantinedPaths.join(", ")}.`,
+                }],
+            structuredContent: {
+                status: "pass",
+                quarantined_paths: result.quarantinedPaths,
+                quarantine_directory: result.quarantineDirectory,
+            },
+        };
+    }
+    if (getManagedCommandNames.has(name)) {
+        return await readManagedCommand(input);
+    }
+    if (waitManagedCommandNames.has(name)) {
+        return await waitManagedCommand(input);
+    }
+    if (startManagedVerificationNames.has(name)) {
+        return await startManagedVerification(input, worktreePath);
+    }
+    if (!managedCommandNames.has(name) && !startManagedCommandNames.has(name)) {
+        throw new Error(`Unknown managed attempt tool: ${name}`);
+    }
+    return await launchManagedCommand(asRecord(input), worktreePath, startManagedCommandNames.has(name));
+}
+async function launchManagedCommand(record, worktreePath, forceAsync, verificationProfile, buildProducingOverride, buildReceiptReuse) {
+    const command = requiredInputString(record, "command");
+    const args = requiredStringArray(record, "args");
+    const timeoutMs = optionalTimeout(record.timeout_ms);
+    const cwd = await containedWorkingDirectory(worktreePath, record.cwd);
+    await validatePlaywrightCommandProject(command, args, cwd);
+    const logDirectory = requiredAttemptEnvironment("FORGE_LOG_DIR");
+    await fs.mkdir(path.join(logDirectory, "managed-commands"), { recursive: true, mode: 0o700 });
+    const commandId = randomUUID();
+    const metadataPath = path.join(logDirectory, "managed-commands", `${commandId}.json`);
+    const receiptPath = managedCommandReceiptPath(logDirectory, commandId);
+    const invocation = {
+        commandId,
+        command,
+        args,
+        cwd,
+        timeoutMs,
+        logDirectory,
+        metadataPath,
+        receiptPath,
+        startedAt: Date.now(),
+        verificationProfile,
+        worktreePath,
+        buildProducing: buildProducingOverride ?? isBuildProducingManagedCommand(command, args),
+        buildReceiptReuse,
+    };
+    if (forceAsync || timeoutMs > maximumSynchronousWaitMs) {
+        const started = managedCommandResult({
+            ...invocation,
+            timedOut: false,
+            status: "starting",
+            exitCode: null,
+            stdout: "",
+            stderr: "",
+        });
+        await persistManagedCommandReceipt(receiptPath, started.structuredContent);
+        const task = executeManagedCommand(invocation);
+        managedCommandTasks.set(commandId, task);
+        void task.finally(() => managedCommandTasks.delete(commandId)).catch(() => undefined);
+        return {
+            ...managedCommandPublicResult(started),
+            content: [{
+                    type: "text",
+                    text: `Forge managed command ${commandId} started asynchronously. Continue independent work, then use forge.wait_managed_command with this command_id for a transport-safe terminal receipt.`,
+                }],
+        };
+    }
+    return await executeManagedCommand(invocation);
+}
+async function startManagedVerification(input, worktreePath) {
+    const record = asRecord(input);
+    const profile = requiredInputString(record, "profile");
+    const shardCount = optionalBoundedInteger(record.shard_count, "shard_count", 1, 32, 1);
+    const shardIndex = optionalBoundedInteger(record.shard_index, "shard_index", 0, 31, 0);
+    if (shardIndex >= shardCount) {
+        throw new Error("managed_verification_invalid: shard_index must be less than shard_count.");
+    }
+    const noBuild = optionalBoolean(record.no_build, "no_build", false);
+    const runAllShards = optionalBoolean(record.run_all_shards, "run_all_shards", false);
+    const maxParallelism = optionalBoundedInteger(record.max_parallelism, "max_parallelism", 1, 4, 2);
+    if (runAllShards && shardCount < 2) {
+        throw new Error("managed_verification_invalid: run_all_shards requires shard_count of at least 2.");
+    }
+    if (runAllShards && shardIndex !== 0) {
+        throw new Error("managed_verification_invalid: shard_index must be 0 when run_all_shards is enabled.");
+    }
+    if (runAllShards && noBuild) {
+        throw new Error("managed_verification_invalid: run_all_shards owns the single prerequisite build and cannot be combined with no_build.");
+    }
+    const outputDirectory = requiredAttemptEnvironment("FORGE_TEST_OUTPUT_DIR");
+    const profileCommand = buildManagedVerificationCommand(profile, outputDirectory, shardCount, shardIndex, noBuild, runAllShards, maxParallelism);
+    const buildReceiptReuse = noBuild
+        ? await verifyManagedBuildReceipt({
+            worktreePath,
+            configuration: managedBuildConfiguration(profileCommand.command, profileCommand.args),
+            requiredCoverage: managedVerificationBuildCoverage,
+        })
+        : undefined;
+    return await launchManagedCommand({
+        command: profileCommand.command,
+        args: profileCommand.args,
+        timeout_ms: record.timeout_ms ?? profileCommand.timeoutMs,
+    }, worktreePath, true, profile, !noBuild, buildReceiptReuse);
+}
+export function buildManagedVerificationCommand(profile, outputDirectory, shardCount, shardIndex, noBuild, runAllShards = false, maxParallelism = 2) {
+    if (profile === "dotnet_solution") {
+        if (runAllShards) {
+            throw new Error("managed_verification_invalid: dotnet_solution does not support run_all_shards; select a test tier instead.");
+        }
+        if (shardCount !== 1 || shardIndex !== 0) {
+            throw new Error("managed_verification_invalid: dotnet_solution does not accept sharding; select a test tier instead.");
+        }
+        const command = preferredPowerShellExecutable();
+        const args = [
+            "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "scripts/run-dotnet-test-suite.ps1",
+            "-ResultsDirectory", outputDirectory,
+            "-MaxParallelism", String(maxParallelism),
+        ];
+        if (noBuild)
+            args.push("-NoBuild");
+        return { command, args, timeoutMs: 2_700_000 };
+    }
+    const tiers = {
+        dotnet_unit: "Unit",
+        dotnet_contract: "Contract",
+        dotnet_api_component: "ApiComponent",
+        dotnet_orchestration: "Orchestration",
+        dotnet_infrastructure: "Infrastructure",
+    };
+    const tier = tiers[profile];
+    if (!tier)
+        throw new Error(`managed_verification_invalid: unsupported profile ${profile}.`);
+    const command = preferredPowerShellExecutable();
+    if (runAllShards) {
+        return {
+            command,
+            args: [
+                "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "scripts/run-dotnet-test-tier-set.ps1",
+                "-Tier", tier,
+                "-ResultsDirectory", outputDirectory,
+                "-ShardCount", String(shardCount),
+                "-MaxParallelism", String(maxParallelism),
+            ],
+            timeoutMs: tier === "Unit" || tier === "Contract" ? 900_000 : 2_700_000,
+        };
+    }
+    const args = [
+        "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "scripts/run-dotnet-test-tier.ps1",
+        "-Tier", tier,
+        "-ResultsDirectory", outputDirectory,
+        "-ShardCount", String(shardCount),
+        "-ShardIndex", String(shardIndex),
+    ];
+    if (noBuild)
+        args.push("-NoBuild");
+    return { command, args, timeoutMs: tier === "Unit" || tier === "Contract" ? 900_000 : 2_700_000 };
+}
+export function preferredPowerShellExecutable(platform = process.platform, pathValue = process.env.PATH ?? "") {
+    if (platform !== "win32")
+        return "pwsh";
+    return resolveWindowsCommandFromPath("pwsh.exe", pathValue) ?? "powershell.exe";
+}
+export function validatePlaywrightProjectName(project, availableProjects) {
+    if (!availableProjects.includes(project)) {
+        throw new Error(`managed_command_capability_unavailable: Playwright project '${project}' is not advertised by the selected config. Available projects: ${availableProjects.join(", ") || "none"}.`);
+    }
+}
+async function validatePlaywrightCommandProject(command, args, cwd) {
+    const invocation = [path.basename(command).toLowerCase(), ...args.map(argument => argument.toLowerCase())];
+    if (!invocation.some(argument => argument.includes("playwright")))
+        return;
+    const project = optionValue(args, "--project");
+    if (!project)
+        return;
+    const configuredPath = optionValue(args, "--config") ?? process.env.FORGE_PLAYWRIGHT_CONFIG;
+    const candidates = configuredPath
+        ? [path.resolve(cwd, configuredPath)]
+        : ["playwright.config.ts", "playwright.config.js", "playwright.config.mjs"].map(file => path.join(cwd, file));
+    for (const candidate of candidates) {
+        try {
+            const source = await fs.readFile(candidate, "utf8");
+            const projects = playwrightProjectNamesFromConfigSource(source);
+            validatePlaywrightProjectName(project, projects);
+            return;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+    throw new Error("managed_command_capability_unavailable: Playwright config was not found; project selection cannot be validated.");
+}
+export function playwrightProjectNamesFromConfigSource(source) {
+    const marker = source.match(/^\/\/ forge-playwright-projects: (\[[^\r\n]*\])$/mu)?.[1];
+    if (!marker) {
+        return [...source.matchAll(/\bname\s*:\s*["']([^"']+)["']/gu)].map(match => match[1]);
+    }
+    try {
+        const parsed = JSON.parse(marker);
+        return Array.isArray(parsed)
+            ? parsed.filter((value) => typeof value === "string" && value.trim().length > 0)
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+function optionValue(args, name) {
+    const direct = args.find(argument => argument.startsWith(`${name}=`));
+    if (direct)
+        return direct.slice(name.length + 1).trim() || null;
+    const index = args.indexOf(name);
+    return index >= 0 ? args[index + 1]?.trim() || null : null;
+}
+async function executeManagedCommand(invocation) {
+    if (!invocation.buildProducing)
+        return await executeManagedCommandProcess(invocation);
+    return await new ManagedBuildCoordinator().withBuildSlot(invocation.worktreePath, async (buildQueueWaitMs) => await executeManagedCommandProcess({ ...invocation, buildQueueWaitMs }), async () => {
+        const waiting = managedCommandResult({
+            ...invocation,
+            timedOut: false,
+            status: "waiting_for_build_slot",
+            exitCode: null,
+            stdout: "",
+            stderr: "",
+        });
+        await persistManagedCommandReceipt(invocation.receiptPath, waiting.structuredContent);
+    });
+}
+async function executeManagedCommandProcess(invocation) {
+    const environment = inheritedEnvironment({
+        FORGE_RUNTIME_MODE: "host",
+        FORGE_RESOURCE_LEASE_ID: requiredAttemptEnvironment("FORGE_RESOURCE_LEASE_ID"),
+        FORGE_DISPATCH_ATTEMPT_ID: requiredAttemptEnvironment("FORGE_DISPATCH_ATTEMPT_ID"),
+        // This nested command owns a distinct supervisor identity. A command-local
+        // fence avoids exposing the parent attempt's fencing capability to Codex's
+        // MCP subprocess configuration while preserving exact-tree cleanup proof.
+        FORGE_FENCING_TOKEN: randomUUID(),
+        FORGE_LOG_DIR: invocation.logDirectory,
+        FORGE_TEST_OUTPUT_DIR: requiredAttemptEnvironment("FORGE_TEST_OUTPUT_DIR"),
+        FORGE_PROCESS_SUPERVISOR_ID: `managed-${invocation.commandId.replaceAll("-", "")}`,
+        FORGE_PROCESS_SUPERVISOR_METADATA_PATH: invocation.metadataPath,
+    });
+    let stdout = "";
+    let stderr = "";
+    const controller = new AbortController();
+    let timedOut = false;
+    let timer = null;
+    let outputRevision = 0;
+    let lastOutputAt = null;
+    let lastOutputStream = null;
+    let lastProgressPersistedAt = 0;
+    let progressPersistence = Promise.resolve();
+    const launchTimer = setTimeout(() => {
+        timedOut = true;
+        controller.abort(new Error(`managed_command_launch_timeout: process supervisor was not ready within ${managedCommandLaunchTimeoutMs}ms.`));
+    }, managedCommandLaunchTimeoutMs);
+    try {
+        const result = await new StreamingProviderProcessRunner().run({
+            command: invocation.command,
+            args: invocation.args,
+            cwd: invocation.cwd,
+            env: environment,
+            captureOutput: false,
+        }, {
+            onStarted: async () => {
+                clearTimeout(launchTimer);
+                const running = managedCommandResult({
+                    ...invocation,
+                    timedOut: false,
+                    status: "running",
+                    exitCode: null,
+                    stdout,
+                    stderr,
+                    outputRevision,
+                    lastOutputAt,
+                    lastOutputStream,
+                });
+                await persistManagedCommandReceipt(invocation.receiptPath, running.structuredContent);
+                timer = setTimeout(() => {
+                    timedOut = true;
+                    controller.abort(new Error(`managed_command_timeout: exceeded ${invocation.timeoutMs}ms.`));
+                }, invocation.timeoutMs);
+            },
+            onStdoutLine: (line) => {
+                stdout = appendBounded(stdout, line);
+                outputRevision += 1;
+                lastOutputAt = Date.now();
+                lastOutputStream = "stdout";
+                progressPersistence = persistManagedCommandProgressIfDue(invocation, () => ({ stdout, stderr, outputRevision, lastOutputAt, lastOutputStream }), progressPersistence, () => lastProgressPersistedAt, value => { lastProgressPersistedAt = value; });
+                return progressPersistence;
+            },
+            onStderrLine: (line) => {
+                stderr = appendBounded(stderr, line);
+                outputRevision += 1;
+                lastOutputAt = Date.now();
+                lastOutputStream = "stderr";
+                progressPersistence = persistManagedCommandProgressIfDue(invocation, () => ({ stdout, stderr, outputRevision, lastOutputAt, lastOutputStream }), progressPersistence, () => lastProgressPersistedAt, value => { lastProgressPersistedAt = value; });
+                return progressPersistence;
+            },
+        }, controller.signal);
+        await progressPersistence;
+        const status = timedOut ? "timed_out" : result.exitCode === 0 ? "pass" : "fail";
+        const receiptCoverage = managedBuildReceiptCoverage(invocation);
+        const buildReceipt = status === "pass" && receiptCoverage
+            ? await publishManagedBuildReceipt({
+                worktreePath: invocation.worktreePath,
+                command: invocation.command,
+                args: invocation.args,
+                configuration: managedBuildConfiguration(invocation.command, invocation.args),
+                coverage: receiptCoverage,
+            })
+            : invocation.buildReceiptReuse;
+        const receipt = managedCommandResult({
+            ...invocation,
+            timedOut,
+            status,
+            exitCode: result.exitCode,
+            stdout,
+            stderr,
+            outputRevision,
+            lastOutputAt,
+            lastOutputStream,
+            buildReceipt,
+            buildReceiptReused: invocation.buildReceiptReuse !== undefined,
+        });
+        await persistManagedCommandReceipt(invocation.receiptPath, receipt.structuredContent);
+        return managedCommandPublicResult(receipt);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        stderr = appendBounded(stderr, message);
+        outputRevision += 1;
+        lastOutputAt = Date.now();
+        lastOutputStream = "stderr";
+        const receipt = managedCommandResult({
+            ...invocation,
+            timedOut,
+            status: timedOut ? "timeout_termination_failed" : "runner_error",
+            exitCode: null,
+            stdout,
+            stderr,
+            outputRevision,
+            lastOutputAt,
+            lastOutputStream,
+        });
+        await persistManagedCommandReceipt(invocation.receiptPath, receipt.structuredContent);
+        return managedCommandPublicResult(receipt);
+    }
+    finally {
+        clearTimeout(launchTimer);
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+async function readManagedCommand(input) {
+    const commandId = validatedCommandId(asRecord(input));
+    const receiptPath = managedCommandReceiptPath(requiredAttemptEnvironment("FORGE_LOG_DIR"), commandId);
+    let receipt;
+    try {
+        receipt = JSON.parse(await fs.readFile(receiptPath, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new Error(`managed_command_not_found: no durable receipt exists for ${commandId}.`, { cause: error });
+        }
+        throw error;
+    }
+    const status = typeof receipt.status === "string" ? receipt.status : "unknown";
+    const stdout = typeof receipt.stdout === "string" ? receipt.stdout : "";
+    const stderr = typeof receipt.stderr === "string" ? receipt.stderr : "";
+    return managedCommandPublicResult({
+        content: [{
+                type: "text",
+                text: terminalManagedCommandStatuses.has(status)
+                    ? terminalManagedCommandText({
+                        commandId,
+                        status,
+                        exitCode: typeof receipt.exit_code === "number" ? receipt.exit_code : null,
+                        elapsedMs: typeof receipt.elapsed_ms === "number" ? receipt.elapsed_ms : null,
+                        stdout,
+                        stderr,
+                    })
+                    : `Forge managed command ${commandId} is ${status}. Continue independent work and use forge.wait_managed_command when ready for its terminal receipt.`,
+            }],
+        structuredContent: receipt,
+        isError: terminalManagedCommandStatuses.has(status) && status !== "pass",
+    });
+}
+async function waitManagedCommand(input) {
+    const record = asRecord(input);
+    const commandId = validatedCommandId(record);
+    const requestedWaitTimeoutMs = optionalWaitTimeout(record.wait_timeout_ms);
+    const waitTimeoutMs = Math.min(requestedWaitTimeoutMs, maximumSynchronousWaitMs);
+    const deadline = Date.now() + waitTimeoutMs;
+    const receiptPath = managedCommandReceiptPath(requiredAttemptEnvironment("FORGE_LOG_DIR"), commandId);
+    const task = managedCommandTasks.get(commandId);
+    if (task) {
+        const result = await Promise.race([
+            task,
+            delay(waitTimeoutMs).then(() => null),
+        ]);
+        if (result)
+            return result;
+    }
+    while (Date.now() < deadline) {
+        const result = await readManagedCommand({ command_id: commandId });
+        if (terminalManagedCommandStatuses.has(String(result.structuredContent.status))) {
+            return result;
+        }
+        await delay(Math.min(managedCommandReceiptPollIntervalMs, Math.max(1, deadline - Date.now())));
+    }
+    const receipt = await readManagedCommand({ command_id: commandId });
+    return {
+        ...receipt,
+        content: [{
+                type: "text",
+                text: `Forge is still supervising managed command ${commandId} after this ${waitTimeoutMs}ms transport-safe wait. Continue independent work or call forge.wait_managed_command again after ${managedCommandRetryAfterMs}ms. Its durable receipt remains at ${receiptPath}.`,
+            }],
+        structuredContent: {
+            ...receipt.structuredContent,
+            command_continues: true,
+            terminal: false,
+            wait_timeout_ms: waitTimeoutMs,
+            requested_wait_timeout_ms: requestedWaitTimeoutMs,
+            retry_after_ms: managedCommandRetryAfterMs,
+        },
+        isError: false,
+    };
+}
+function managedCommandReceiptPath(logDirectory, commandId) {
+    return path.join(logDirectory, "managed-commands", `${commandId}.receipt.json`);
+}
+async function persistManagedCommandReceipt(receiptPath, receipt) {
+    const temporaryPath = `${receiptPath}.${randomUUID()}.tmp`;
+    await fs.writeFile(temporaryPath, `${JSON.stringify(receipt, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    try {
+        for (let attempt = 1;; attempt += 1) {
+            try {
+                await fs.rename(temporaryPath, receiptPath);
+                break;
+            }
+            catch (error) {
+                const code = error.code;
+                if (attempt >= managedCommandReceiptReplaceAttempts
+                    || (code !== "EPERM" && code !== "EBUSY" && code !== "EACCES")) {
+                    throw error;
+                }
+                await delay(managedCommandReceiptReplaceRetryMs);
+            }
+        }
+    }
+    finally {
+        await fs.rm(temporaryPath, { force: true }).catch(() => undefined);
+    }
+}
+function managedCommandResult(values) {
+    const elapsedMs = Date.now() - values.startedAt;
+    const isTerminal = terminalManagedCommandStatuses.has(values.status);
+    const diagnostics = isTerminal
+        ? managedCommandDiagnostics(values.stdout, values.stderr)
+        : undefined;
+    return {
+        content: [{
+                type: "text",
+                text: isTerminal
+                    ? terminalManagedCommandText({
+                        commandId: values.commandId,
+                        status: values.status,
+                        exitCode: values.exitCode,
+                        elapsedMs,
+                        stdout: values.stdout,
+                        stderr: values.stderr,
+                    }, diagnostics)
+                    : `Forge managed command ${values.commandId} is ${values.status} after ${elapsedMs}ms.`,
+            }],
+        structuredContent: {
+            command_id: values.commandId,
+            status: values.status,
+            command: [values.command, ...values.args],
+            cwd: values.cwd,
+            timeout_ms: values.timeoutMs,
+            elapsed_ms: elapsedMs,
+            started_at: new Date(values.startedAt).toISOString(),
+            timed_out: values.timedOut,
+            exit_code: values.exitCode,
+            stdout: values.stdout,
+            stderr: values.stderr,
+            ...(diagnostics ? { diagnostics } : {}),
+            output_truncated: values.stdout.length >= maximumCapturedCharacters
+                || values.stderr.length >= maximumCapturedCharacters,
+            output_revision: values.outputRevision ?? 0,
+            last_output_at: values.lastOutputAt ? new Date(values.lastOutputAt).toISOString() : null,
+            last_output_stream: values.lastOutputStream ?? null,
+            supervisor_metadata_path: values.metadataPath,
+            receipt_path: values.receiptPath,
+            verification_profile: values.verificationProfile ?? null,
+            verification_profile_runner_authored: values.verificationProfile !== undefined,
+            build_producing: values.buildProducing,
+            build_coordination: values.buildProducing ? "per_worktree_exclusive" : null,
+            build_queue_wait_ms: values.buildQueueWaitMs ?? 0,
+            build_receipt_reused: values.buildReceiptReused ?? false,
+            build_receipt: values.buildReceipt ? {
+                fingerprint: values.buildReceipt.fingerprint,
+                receipt_path: values.buildReceipt.receiptPath,
+                producer_command: values.buildReceipt.producerCommand,
+                configuration: values.buildReceipt.configuration,
+                coverage: values.buildReceipt.coverage,
+                output_count: values.buildReceipt.outputCount,
+            } : null,
+            runtime_configuration: managedRuntimeConfiguration(),
+            process_tree_terminated: values.status === "timed_out" ? true : values.timedOut ? false : undefined,
+        },
+        isError: isTerminal && values.status !== "pass",
+    };
+}
+function managedRuntimeConfiguration() {
+    const providerOnlySpecs = process.env.FORGE_CI_REPAIR_PROVIDER_ONLY_SPECS?.trim();
+    let providerOnlySpecCount = 0;
+    if (providerOnlySpecs) {
+        try {
+            const parsed = JSON.parse(providerOnlySpecs);
+            providerOnlySpecCount = Array.isArray(parsed)
+                ? parsed.filter(value => typeof value === "string" && value.length > 0).length
+                : 0;
+        }
+        catch {
+            providerOnlySpecCount = 0;
+        }
+    }
+    return {
+        attempt_database_schema: process.env.FORGE_ATTEMPT_DATABASE_SCHEMA ?? null,
+        attempt_database_readiness_path: process.env.FORGE_ATTEMPT_DATABASE_READINESS_PATH ?? null,
+        playwright_config: process.env.FORGE_PLAYWRIGHT_CONFIG ?? null,
+        provider_only_spec_count: providerOnlySpecCount,
+        provider_only_spec_fingerprint: providerOnlySpecs
+            ? `sha256:${createHash("sha256").update(providerOnlySpecs).digest("hex")}`
+            : null,
+    };
+}
+function managedCommandPublicResult(result) {
+    const stdout = typeof result.structuredContent.stdout === "string" ? result.structuredContent.stdout : "";
+    const stderr = typeof result.structuredContent.stderr === "string" ? result.structuredContent.stderr : "";
+    const { stdout: _stdout, stderr: _stderr, ...receipt } = result.structuredContent;
+    return {
+        ...result,
+        structuredContent: {
+            ...receipt,
+            stdout_tail: tail(stdout, maximumReturnedOutputCharacters),
+            stderr_tail: tail(stderr, maximumReturnedOutputCharacters),
+            full_output_in_receipt: true,
+        },
+    };
+}
+function persistManagedCommandProgressIfDue(invocation, snapshot, previousPersistence, lastPersistedAt, setLastPersistedAt) {
+    const now = Date.now();
+    if (now - lastPersistedAt() < managedCommandProgressPersistIntervalMs)
+        return previousPersistence;
+    setLastPersistedAt(now);
+    const current = snapshot();
+    return previousPersistence.then(async () => {
+        const receipt = managedCommandResult({
+            ...invocation,
+            timedOut: false,
+            status: "running",
+            exitCode: null,
+            ...current,
+        });
+        await persistManagedCommandReceipt(invocation.receiptPath, receipt.structuredContent);
+    });
+}
+async function containedWorkingDirectory(worktreePath, input) {
+    const root = await fs.realpath(path.resolve(worktreePath));
+    const relative = input === undefined ? "." : requiredStandaloneString(input, "cwd");
+    if (path.isAbsolute(relative))
+        throw new Error("managed_command_invalid: cwd must be worktree-relative.");
+    const target = await fs.realpath(path.resolve(root, relative));
+    const containment = path.relative(root, target);
+    if (containment.startsWith(`..${path.sep}`) || path.isAbsolute(containment)) {
+        throw new Error("managed_command_invalid: cwd resolves outside the source worktree.");
+    }
+    return target;
+}
+function inheritedEnvironment(overrides) {
+    const env = {};
+    for (const [key, value] of Object.entries(process.env)) {
+        if (typeof value === "string" && !looksSensitiveEnvironmentName(key))
+            env[key] = value;
+    }
+    return { ...env, ...overrides };
+}
+export function isBuildProducingManagedCommand(command, args) {
+    const executable = path.basename(command).toLowerCase();
+    if (executable === "dotnet" || executable === "dotnet.exe") {
+        const verb = args.find(argument => !argument.startsWith("-"))?.toLowerCase();
+        if (!verb || !new Set(["build", "test", "restore", "publish", "pack", "msbuild"]).has(verb))
+            return false;
+        return verb === "restore" || !args.some(argument => argument.toLowerCase() === "--no-build");
+    }
+    if (["powershell", "powershell.exe", "pwsh", "pwsh.exe"].includes(executable)) {
+        const fileIndex = args.findIndex(argument => argument.toLowerCase() === "-file");
+        const script = fileIndex >= 0 ? path.basename(args[fileIndex + 1] ?? "").toLowerCase() : "";
+        if (script === "run-dotnet-test-tier-set.ps1" || script === "run-dotnet-test-suite.ps1") {
+            return !args.some(argument => argument.toLowerCase() === "-nobuild");
+        }
+        if (script === "run-dotnet-test-tier.ps1") {
+            return !args.some(argument => argument.toLowerCase() === "-nobuild");
+        }
+    }
+    return false;
+}
+function managedBuildReceiptCoverage(invocation) {
+    if (!invocation.buildProducing)
+        return null;
+    if (invocation.verificationProfile)
+        return managedVerificationBuildCoverage;
+    const executable = path.basename(invocation.command).toLowerCase();
+    if (executable === "dotnet" || executable === "dotnet.exe") {
+        const verb = invocation.args.find(argument => !argument.startsWith("-"))?.toLowerCase();
+        if (!verb || !new Set(["build", "test"]).has(verb))
+            return null;
+        const target = invocation.args.find(argument => /\.(?:sln|slnx|csproj)$/iu.test(argument));
+        if (target && (/\.(?:sln|slnx)$/iu.test(target) || /(?:^|[\\/])Forge\.Api\.Tests\.csproj$/iu.test(target))) {
+            return managedVerificationBuildCoverage;
+        }
+        return null;
+    }
+    if (["powershell", "powershell.exe", "pwsh", "pwsh.exe"].includes(executable)) {
+        const fileIndex = invocation.args.findIndex(argument => argument.toLowerCase() === "-file");
+        const script = fileIndex >= 0 ? path.basename(invocation.args[fileIndex + 1] ?? "").toLowerCase() : "";
+        if (["run-dotnet-test-tier.ps1", "run-dotnet-test-tier-set.ps1", "run-dotnet-test-suite.ps1"].includes(script)
+            && !invocation.args.some(argument => argument.toLowerCase() === "-nobuild")) {
+            return managedVerificationBuildCoverage;
+        }
+    }
+    return null;
+}
+function looksSensitiveEnvironmentName(name) {
+    const normalized = name.trim().toUpperCase();
+    return normalized.includes("SECRET")
+        || normalized.includes("TOKEN")
+        || normalized.includes("PASSWORD")
+        || normalized.includes("CREDENTIAL")
+        || normalized.endsWith("_API_KEY")
+        || normalized === "OPENAI_API_KEY";
+}
+function requiredAttemptEnvironment(name) {
+    const value = process.env[name]?.trim();
+    if (!value)
+        throw new Error(`managed_attempt_tool_unavailable: ${name} is not configured.`);
+    return value;
+}
+function asRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("managed_command_invalid: input must be an object.");
+    return value;
+}
+function requiredInputString(record, name) {
+    return requiredStandaloneString(record[name], name);
+}
+function validatedCommandId(record) {
+    const commandId = requiredInputString(record, "command_id");
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu.test(commandId)) {
+        throw new Error("managed_command_invalid: command_id must be a UUID returned by Forge.");
+    }
+    return commandId;
+}
+function requiredStandaloneString(value, name) {
+    if (typeof value !== "string" || !value.trim())
+        throw new Error(`managed_command_invalid: ${name} is required.`);
+    return value.trim();
+}
+function requiredStringArray(record, name) {
+    const value = record[name];
+    if (!Array.isArray(value) || value.some(entry => typeof entry !== "string")) {
+        throw new Error(`managed_command_invalid: ${name} must be a string array.`);
+    }
+    return value;
+}
+function optionalTimeout(value) {
+    if (value === undefined)
+        return 2_700_000;
+    if (!Number.isSafeInteger(value) || value < 1_000 || value > 7_200_000) {
+        throw new Error("managed_command_invalid: timeout_ms must be an integer from 1000 through 7200000.");
+    }
+    return value;
+}
+function optionalWaitTimeout(value) {
+    if (value === undefined)
+        return maximumSynchronousWaitMs;
+    if (!Number.isSafeInteger(value) || value < 1_000 || value > maximumSynchronousWaitMs) {
+        throw new Error(`managed_command_invalid: wait_timeout_ms must be an integer from 1000 through ${maximumSynchronousWaitMs}.`);
+    }
+    return value;
+}
+function optionalBoundedInteger(value, name, minimum, maximum, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+        throw new Error(`managed_verification_invalid: ${name} must be an integer from ${minimum} through ${maximum}.`);
+    }
+    return value;
+}
+function optionalBoolean(value, name, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== "boolean")
+        throw new Error(`managed_verification_invalid: ${name} must be a boolean.`);
+    return value;
+}
+async function delay(ms) {
+    await new Promise(resolve => setTimeout(resolve, ms));
+}
+function appendBounded(current, line) {
+    const next = `${current}${line}\n`;
+    return next.length <= maximumCapturedCharacters
+        ? next
+        : next.slice(-maximumCapturedCharacters);
+}
+function managedCommandDiagnostics(stdout, stderr) {
+    const lines = `${stdout}\n${stderr}`
+        .split(/\r?\n/u)
+        .map(line => line.trim())
+        .filter(Boolean);
+    const failedTests = new Set();
+    for (const line of lines) {
+        const xunit = line.match(/^\[xUnit\.net[^\]]*\]\s+(.+?)\s+\[FAIL\]$/u);
+        if (xunit?.[1])
+            failedTests.add(xunit[1].trim());
+        const vstest = line.match(/^Failed\s+(.+?)(?:\s+\[(?:\d|<).*)?$/u);
+        if (vstest?.[1] && !vstest[1].startsWith("!"))
+            failedTests.add(vstest[1].trim());
+    }
+    const summaryLines = lines
+        .filter(line => /(?:Failed!|Passed!|Test Run|Tests?:\s|Test Files|\[FAIL\]|error\s+[A-Z]+\d+)/iu.test(line))
+        .slice(-20);
+    return {
+        failed_tests: [...failedTests].slice(0, maximumReportedFailedTests),
+        failed_test_count: failedTests.size,
+        summary_lines: summaryLines,
+    };
+}
+function terminalManagedCommandText(values, diagnostics = managedCommandDiagnostics(values.stdout, values.stderr)) {
+    const failedTests = diagnostics.failed_tests;
+    const summaryLines = diagnostics.summary_lines;
+    const duration = values.elapsedMs === null ? "an unknown duration" : `${values.elapsedMs}ms`;
+    const sections = [
+        `Forge managed command ${values.commandId} ${values.status} after ${duration} (exit ${values.exitCode ?? "unavailable"}).`,
+    ];
+    if (failedTests.length > 0) {
+        sections.push(`Failed tests (${diagnostics.failed_test_count}):\n${failedTests.map(test => `- ${test}`).join("\n")}`);
+    }
+    if (summaryLines.length > 0) {
+        sections.push(`Test summary:\n${summaryLines.join("\n")}`);
+    }
+    const stdoutTail = tail(values.stdout, maximumReturnedOutputCharacters);
+    const stderrTail = tail(values.stderr, maximumReturnedOutputCharacters);
+    sections.push(`stdout tail:\n${stdoutTail || "(empty)"}`);
+    sections.push(`stderr tail:\n${stderrTail || "(empty)"}`);
+    return sections.join("\n\n");
+}
+function tail(value, maximumCharacters) {
+    return value.length <= maximumCharacters ? value : value.slice(-maximumCharacters);
+}