@loucompanion/forge-bridge 0.1.3-dev.b6be5e7f9668 → 0.1.3-dev.bca7d0ccee53

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

@@ -0,0 +1,712 @@
+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 { 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;
+const maximumSynchronousWaitMs = 240_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 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 call forge.wait_managed_command once.",
+            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 },
+                    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 call forge.wait_managed_command once for its 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 call forge.wait_managed_command once 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 once for a command started by Forge's managed command runner to reach a terminal state. Live progress remains in the durable receipt/UI without repeated provider messages; this call returns the single terminal result.",
+            inputSchema: {
+                type: "object",
+                additionalProperties: false,
+                required: ["command_id"],
+                properties: {
+                    command_id: { type: "string", minLength: 1 },
+                    wait_timeout_ms: { type: "integer", minimum: 1000, maximum: 7200000, default: 7200000 },
+                },
+            },
+        };
+    }
+    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) {
+    const command = requiredInputString(record, "command");
+    const args = requiredStringArray(record, "args");
+    const timeoutMs = optionalTimeout(record.timeout_ms);
+    const cwd = await containedWorkingDirectory(worktreePath, record.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,
+    };
+    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 call forge.wait_managed_command once with this command_id for the 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 outputDirectory = requiredAttemptEnvironment("FORGE_TEST_OUTPUT_DIR");
+    const profileCommand = buildManagedVerificationCommand(profile, outputDirectory, shardCount, shardIndex, noBuild);
+    return await launchManagedCommand({
+        command: profileCommand.command,
+        args: profileCommand.args,
+        timeout_ms: record.timeout_ms ?? profileCommand.timeoutMs,
+    }, worktreePath, true, profile);
+}
+export function buildManagedVerificationCommand(profile, outputDirectory, shardCount, shardIndex, noBuild) {
+    if (profile === "dotnet_solution") {
+        if (shardCount !== 1 || shardIndex !== 0) {
+            throw new Error("managed_verification_invalid: dotnet_solution does not accept sharding; select a test tier instead.");
+        }
+        const args = [
+            "test", "Forge.sln", "--nologo", "-c", "Release",
+            "--results-directory", outputDirectory,
+            "--logger", "trx;LogFileName=forge-solution.trx",
+            "--blame-hang", "--blame-hang-timeout", "15m",
+        ];
+        if (noBuild)
+            args.push("--no-build");
+        return { command: "dotnet", 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 = process.platform === "win32" ? "powershell.exe" : "pwsh";
+    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 };
+}
+async function executeManagedCommand(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 receipt = managedCommandResult({
+            ...invocation,
+            timedOut,
+            status,
+            exitCode: result.exitCode,
+            stdout,
+            stderr,
+            outputRevision,
+            lastOutputAt,
+            lastOutputStream,
+        });
+        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 waitTimeoutMs = optionalWaitTimeout(record.wait_timeout_ms);
+    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 waiting ${waitTimeoutMs}ms. Its durable receipt remains at ${receiptPath}.`,
+            }],
+    };
+}
+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,
+            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 };
+}
+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 7_200_000;
+    if (!Number.isSafeInteger(value) || value < 1_000 || value > 7_200_000) {
+        throw new Error("managed_command_invalid: wait_timeout_ms must be an integer from 1000 through 7200000.");
+    }
+    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);
+}