@loucompanion/forge-bridge 0.1.3-dev.d1ca67076aa9 → 0.1.3-dev.eeefdb0d19c1

package/dist/sandbox/worker.js

@@ -0,0 +1,225 @@
+import { createHash } from "node:crypto";
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { MonotonicLeaseDeadline } from "./lease-watchdog.js";
+import { terminationMessage, WorkerDeadlineSupervisor } from "./worker-supervisor.js";
+const controlRoot = "/control";
+const runtimeRoot = "/run/forge";
+const workspace = process.env.FORGE_WORKSPACE ?? "/workspace";
+async function main() {
+    const dispatchText = await readBoundedStdin(16 * 1024 * 1024);
+    const bootstrap = JSON.parse(dispatchText);
+    if (bootstrap.schemaVersion !== 1 || !bootstrap.dispatch || typeof bootstrap.leaseControlKey !== "string") {
+        throw new Error("Invalid sandbox bootstrap packet.");
+    }
+    const dispatch = bootstrap.dispatch;
+    const sandbox = dispatch.sandbox;
+    const attemptId = requiredId(sandbox?.dispatchAttemptId, "dispatchAttemptId");
+    const lease = dispatch.lease;
+    const fencingToken = requiredId(lease?.fencingToken, "fencingToken");
+    const leaseDeadline = new MonotonicLeaseDeadline(attemptId, fencingToken, requiredString(lease?.expiresAt, "expiresAt"), bootstrap.leaseControlKey);
+    const limits = requiredLimits(bootstrap.limits);
+    await installServiceEnvironment(attemptId);
+    await fs.mkdir(runtimeRoot, { recursive: true, mode: 0o700 });
+    await fs.mkdir(path.join(controlRoot, "output"), { recursive: true, mode: 0o700 });
+    const dispatchPath = path.join(runtimeRoot, "dispatch.json");
+    const resultPath = path.join(controlRoot, "output", "result.json");
+    await fs.writeFile(dispatchPath, JSON.stringify(dispatch), { mode: 0o600 });
+    const entrypoint = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../cli/bin.js");
+    const runOutcome = await run(process.execPath, [entrypoint, "run-once", "--dispatch", dispatchPath, "--result", resultPath], {
+        deadline: leaseDeadline,
+        updatePath: path.join(runtimeRoot, "lease-update.json"),
+        supervisor: new WorkerDeadlineSupervisor(leaseDeadline, limits.hardWallMs, limits.idleMs)
+    });
+    await fs.rm(dispatchPath, { force: true });
+    if (runOutcome.terminationCode) {
+        await writeTerminationResult(resultPath, runOutcome.terminationCode);
+    }
+    let resultCommitSha = null;
+    let bundleSha256 = null;
+    let bundleBytes = 0;
+    const bundlePath = path.join(controlRoot, "output", "result.bundle");
+    if (!runOutcome.terminationCode && runOutcome.exitCode === 0 && await exists(path.join(workspace, ".git"))) {
+        resultCommitSha = (await capture("git", ["-C", workspace, "rev-parse", "HEAD"])).trim();
+        const resultRef = `refs/forge/results/${attemptId.replace(/-/g, "")}`;
+        await runRequired("git", ["-C", workspace, "update-ref", resultRef, resultCommitSha]);
+        try {
+            await runRequired("git", ["-C", workspace, "bundle", "create", bundlePath, resultRef]);
+        }
+        finally {
+            await run("git", ["-C", workspace, "update-ref", "-d", resultRef]);
+        }
+        const bundle = await fs.readFile(bundlePath);
+        bundleBytes = bundle.length;
+        bundleSha256 = createHash("sha256").update(bundle).digest("hex");
+    }
+    const resultBytes = await fs.readFile(resultPath);
+    const manifest = {
+        schemaVersion: 1,
+        dispatchAttemptId: attemptId,
+        executionLeaseId: sandbox?.executionLeaseId,
+        fencingToken: dispatch.lease?.fencingToken,
+        runnerInstanceId: sandbox?.runnerInstanceId,
+        inputCommitSha: sandbox?.inputCommitSha,
+        resultCommitSha,
+        branch: dispatch.lease?.worktreeKey,
+        contractDigest: sandbox?.contractDigest,
+        imageDigest: sandbox?.imageDigest,
+        result: { path: "result.json", bytes: resultBytes.length, sha256: createHash("sha256").update(resultBytes).digest("hex") },
+        bundle: bundleSha256 ? { path: "result.bundle", bytes: bundleBytes, sha256: bundleSha256 } : null,
+        workerExitCode: runOutcome.exitCode,
+        workerExitClassification: runOutcome.terminationCode ?? "agent_exit"
+    };
+    const temporary = path.join(controlRoot, "output", "manifest.json.tmp");
+    await fs.writeFile(temporary, `${JSON.stringify(manifest)}\n`, { mode: 0o600 });
+    await fs.rename(temporary, path.join(controlRoot, "output", "manifest.json"));
+    return runOutcome.exitCode;
+}
+async function readBoundedStdin(limit) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of process.stdin) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        total += buffer.length;
+        if (total > limit)
+            throw new Error("Dispatch bootstrap exceeds 16 MiB.");
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+async function run(command, args, watchdog) {
+    return await new Promise((resolve, reject) => {
+        const child = spawn(command, args, { stdio: ["ignore", "pipe", "pipe"], shell: false });
+        let readingUpdate = false;
+        let killTimer = null;
+        let terminationCode = null;
+        const terminate = (code) => {
+            if (child.exitCode !== null || child.signalCode !== null)
+                return;
+            terminationCode ??= code;
+            emitTerminationEvent(terminationCode);
+            child.kill("SIGTERM");
+            killTimer = setTimeout(() => child.kill("SIGKILL"), 10_000);
+            killTimer.unref?.();
+        };
+        child.stdout.on("data", chunk => {
+            watchdog?.supervisor.touch();
+            process.stdout.write(chunk);
+        });
+        child.stderr.on("data", chunk => {
+            watchdog?.supervisor.touch();
+            process.stderr.write(chunk);
+        });
+        const monitor = watchdog ? setInterval(() => {
+            const reason = watchdog.supervisor.termination();
+            if (reason) {
+                terminate(reason);
+                return;
+            }
+            if (readingUpdate)
+                return;
+            readingUpdate = true;
+            fs.readFile(watchdog.updatePath, "utf8")
+                .then(value => {
+                return watchdog.deadline.apply(JSON.parse(value));
+            })
+                .catch(() => false)
+                .finally(() => { readingUpdate = false; });
+        }, 250) : null;
+        monitor?.unref?.();
+        child.on("error", error => {
+            if (monitor)
+                clearInterval(monitor);
+            if (killTimer)
+                clearTimeout(killTimer);
+            reject(error);
+        });
+        child.on("close", code => {
+            if (monitor)
+                clearInterval(monitor);
+            if (killTimer)
+                clearTimeout(killTimer);
+            resolve({ exitCode: terminationCode ? 124 : code ?? 1, terminationCode });
+        });
+    });
+}
+async function runRequired(command, args) {
+    const outcome = await run(command, args);
+    if (outcome.exitCode !== 0)
+        throw new Error(`${command} failed with exit ${outcome.exitCode}.`);
+}
+async function capture(command, args) {
+    return await new Promise((resolve, reject) => {
+        const child = spawn(command, args, { stdio: ["ignore", "pipe", "inherit"], shell: false });
+        const chunks = [];
+        child.stdout.on("data", chunk => chunks.push(Buffer.from(chunk)));
+        child.on("error", reject);
+        child.on("close", code => code === 0 ? resolve(Buffer.concat(chunks).toString("utf8")) : reject(new Error(`${command} failed with exit ${code}.`)));
+    });
+}
+async function exists(target) { return fs.stat(target).then(() => true).catch(() => false); }
+async function installServiceEnvironment(attemptId) {
+    const attemptHex = attemptId.replace(/-/gu, "").toLowerCase();
+    const postgresPassword = await readServiceCredential("postgres-password");
+    if (postgresPassword)
+        process.env.FORGE_TEST_DATABASE = `postgresql://forge:${encodeURIComponent(postgresPassword)}@forge-${attemptHex}-postgres:5432/forge_test`;
+    const redisPassword = await readServiceCredential("redis-password");
+    if (redisPassword)
+        process.env.FORGE_TEST_REDIS = `redis://:${encodeURIComponent(redisPassword)}@forge-${attemptHex}-redis:6379/0`;
+    const browserToken = await readServiceCredential("browser-token");
+    if (browserToken)
+        process.env.FORGE_BROWSER_TOKEN = browserToken;
+}
+async function readServiceCredential(name) {
+    const target = `/run/forge-secrets/${name}`;
+    const stat = await fs.lstat(target).catch(() => null);
+    if (!stat)
+        return null;
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size < 32 || stat.size > 256) {
+        throw new Error(`Invalid ${name} service credential file.`);
+    }
+    return (await fs.readFile(target, "utf8")).trim();
+}
+function requiredId(value, label) {
+    if (typeof value !== "string" || !/^[0-9a-f-]{32,36}$/i.test(value))
+        throw new Error(`Invalid ${label}.`);
+    return value;
+}
+function requiredString(value, label) {
+    if (typeof value !== "string" || value.length === 0)
+        throw new Error(`Invalid ${label}.`);
+    return value;
+}
+function requiredLimits(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Invalid sandbox watchdog limits.");
+    const limits = value;
+    if (typeof limits.hardWallMs !== "number" || !Number.isSafeInteger(limits.hardWallMs) || limits.hardWallMs < 60_000 || limits.hardWallMs > 28_800_000
+        || typeof limits.idleMs !== "number" || !Number.isSafeInteger(limits.idleMs) || limits.idleMs < 60_000 || limits.idleMs > limits.hardWallMs) {
+        throw new Error("Invalid sandbox watchdog limits.");
+    }
+    return { hardWallMs: limits.hardWallMs, idleMs: limits.idleMs };
+}
+async function writeTerminationResult(resultPath, code) {
+    const message = terminationMessage(code);
+    const result = {
+        schemaVersion: 1,
+        exitCode: 124,
+        summary: message,
+        events: [{ role: "runner", kind: "error", content: message, eventType: code }]
+    };
+    const temporary = `${resultPath}.timeout.tmp`;
+    await fs.writeFile(temporary, `${JSON.stringify(result)}\n`, { mode: 0o600 });
+    await fs.rename(temporary, resultPath);
+}
+function emitTerminationEvent(code) {
+    const message = terminationMessage(code);
+    process.stdout.write(`${JSON.stringify({ type: "runner_event", event: { role: "runner", kind: "error", content: message, eventType: code } })}\n`);
+    process.stderr.write(`${code}: ${message}\n`);
+}
+main().then(code => { process.exitCode = code; }).catch(error => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});

package/dist/sandbox/workspace.service.d.ts

@@ -0,0 +1,13 @@
+import { GitClient } from "../shared/git/git.js";
+import type { WorktreeService } from "../worktree/worktree.base.js";
+import type { WorktreeHandle, WorktreePrepareRequest } from "../worktree/worktree.types.js";
+export declare class SandboxWorkspaceService implements WorktreeService {
+    private readonly workspace;
+    private readonly bundlePath;
+    private readonly inputCommitSha;
+    private readonly git;
+    constructor(workspace?: string, bundlePath?: string, inputCommitSha?: string, git?: GitClient);
+    prepare(request: WorktreePrepareRequest): Promise<WorktreeHandle>;
+    release(_handle: WorktreeHandle): Promise<void>;
+}
+export declare function sandboxInputRefFromBundle(bundleHeads: string, inputCommitSha: string): string;

package/dist/sandbox/workspace.service.js

@@ -0,0 +1,72 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { GitClient } from "../shared/git/git.js";
+import { injectWorktreeArtifacts, filterArtifactsForLane } from "../worktree/artifact-injector.js";
+import { hydratePriorPhaseArtifacts } from "../worktree/prior-phase-artifact-hydrator.js";
+import { clearRunArtifactRoots, normalizeBranchName } from "../worktree/worktree.service.js";
+export class SandboxWorkspaceService {
+    workspace;
+    bundlePath;
+    inputCommitSha;
+    git;
+    constructor(workspace = process.env.FORGE_WORKSPACE ?? "/workspace", bundlePath = process.env.FORGE_INPUT_BUNDLE ?? "/control/input/repo.bundle", inputCommitSha = process.env.FORGE_INPUT_COMMIT_SHA ?? "", git = new GitClient()) {
+        this.workspace = workspace;
+        this.bundlePath = bundlePath;
+        this.inputCommitSha = inputCommitSha;
+        this.git = git;
+    }
+    async prepare(request) {
+        if (!/^[0-9a-f]{40,64}$/i.test(this.inputCommitSha))
+            throw new Error("Sandbox input commit SHA is missing or invalid.");
+        const stat = await fs.stat(this.workspace).catch(() => null);
+        if (!stat?.isDirectory())
+            throw new Error("Sandbox workspace volume is unavailable.");
+        const entries = await fs.readdir(this.workspace);
+        if (entries.length > 0)
+            throw new Error("Sandbox workspace must be empty before bundle import.");
+        const bundleHeads = await this.git.run(path.dirname(this.workspace), ["bundle", "list-heads", this.bundlePath]);
+        const inputRef = sandboxInputRefFromBundle(bundleHeads, this.inputCommitSha);
+        await this.git.run(path.dirname(this.workspace), ["init", this.workspace]);
+        await this.git.run(this.workspace, ["fetch", "--no-tags", "--no-write-fetch-head", this.bundlePath, `${inputRef}:refs/forge/input`]);
+        const actualSha = (await this.git.run(this.workspace, ["rev-parse", "--verify", `${this.inputCommitSha}^{commit}`])).trim();
+        if (actualSha.toLowerCase() !== this.inputCommitSha.toLowerCase())
+            throw new Error("Imported bundle does not contain the exact recorded input commit.");
+        const branchName = normalizeBranchName(request.worktreeKey, `forge/${request.workItem.id.replace(/-/g, "")}`);
+        await this.git.run(this.workspace, ["checkout", "-B", branchName, this.inputCommitSha]);
+        await this.git.run(this.workspace, ["config", "user.email", "forge-agent@forge.local"]);
+        await this.git.run(this.workspace, ["config", "user.name", "Forge Agent"]);
+        await this.git.run(this.workspace, ["config", "core.hooksPath", "/dev/null"]);
+        await clearRunArtifactRoots(this.workspace, request);
+        const artifacts = filterArtifactsForLane(request.artifacts, request.lane, request.phase);
+        if (artifacts.length > 0) {
+            const trackedForgePaths = new Set((await this.git.run(this.workspace, ["ls-files", "-z", "--", ".forge"]))
+                .split("\0")
+                .filter(Boolean)
+                .map(value => value.replaceAll("\\", "/")));
+            await injectWorktreeArtifacts(this.workspace, artifacts, trackedForgePaths);
+        }
+        const hydratedPriorPhaseArtifactCount = await hydratePriorPhaseArtifacts(this.workspace, request.priorPhaseArtifacts);
+        return {
+            repoPath: this.workspace,
+            worktreePath: this.workspace,
+            branchName,
+            baseBranch: request.baseBranch,
+            cleanupWorktrees: false,
+            hydratedPriorPhaseArtifactCount
+        };
+    }
+    async release(_handle) {
+        // The host supervisor owns the workspace volume lifecycle.
+    }
+}
+export function sandboxInputRefFromBundle(bundleHeads, inputCommitSha) {
+    const expectedSha = inputCommitSha.toLowerCase();
+    const matches = bundleHeads
+        .split(/\r?\n/u)
+        .map(line => /^([0-9a-f]{40}|[0-9a-f]{64}) (refs\/forge\/inputs\/[0-9a-f]{32})$/iu.exec(line.trim()))
+        .filter((match) => Boolean(match) && match[1].toLowerCase() === expectedSha);
+    if (matches.length !== 1) {
+        throw new Error("Sandbox input bundle does not expose the exact recorded input ref.");
+    }
+    return matches[0][2];
+}

package/dist/session/managed-attempt-tools.d.ts

@@ -0,0 +1,12 @@
+export declare const managedAttemptToolNames: readonly ["forge.run_managed_command", "run_managed_command", "forge.start_managed_command", "start_managed_command", "forge.get_managed_command", "get_managed_command", "forge.reset_generated_outputs", "reset_generated_outputs"];
+export declare function isManagedAttemptTool(name: string): boolean;
+export declare function managedAttemptToolDefinition(name: string): unknown;
+export interface ManagedAttemptToolResult {
+    readonly content: readonly {
+        readonly type: "text";
+        readonly text: string;
+    }[];
+    readonly structuredContent: Readonly<Record<string, unknown>>;
+    readonly isError?: boolean;
+}
+export declare function callManagedAttemptTool(name: string, input: unknown, worktreePath: string): Promise<ManagedAttemptToolResult>;

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

@@ -0,0 +1,350 @@
+import { 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 resetGeneratedOutputNames = new Set(["forge.reset_generated_outputs", "reset_generated_outputs"]);
+const maximumCapturedCharacters = 1_000_000;
+const maximumSynchronousWaitMs = 240_000;
+const managedCommandLaunchTimeoutMs = 60_000;
+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.reset_generated_outputs",
+    "reset_generated_outputs",
+];
+export function isManagedAttemptTool(name) {
+    return managedCommandNames.has(name)
+        || startManagedCommandNames.has(name)
+        || getManagedCommandNames.has(name)
+        || resetGeneratedOutputNames.has(name);
+}
+export function managedAttemptToolDefinition(name) {
+    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. Poll forge.get_managed_command until it reaches a terminal status."
+                : "Run a short command in an attempt-owned process tree. Commands with a timeout above four minutes automatically start asynchronously; poll forge.get_managed_command for their 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 },
+                },
+            },
+        };
+    }
+    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 (!managedCommandNames.has(name) && !startManagedCommandNames.has(name)) {
+        throw new Error(`Unknown managed attempt tool: ${name}`);
+    }
+    const record = asRecord(input);
+    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(),
+    };
+    if (startManagedCommandNames.has(name) || 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 {
+            ...started,
+            content: [{
+                    type: "text",
+                    text: `Forge managed command ${commandId} started asynchronously. Poll forge.get_managed_command with this command_id until status is terminal.`,
+                }],
+        };
+    }
+    return await executeManagedCommand(invocation);
+}
+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;
+    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,
+                });
+                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); },
+            onStderrLine: (line) => { stderr = appendBounded(stderr, line); },
+        }, controller.signal);
+        const status = timedOut ? "timed_out" : result.exitCode === 0 ? "pass" : "fail";
+        const receipt = managedCommandResult({ ...invocation, timedOut, status, exitCode: result.exitCode, stdout, stderr });
+        await persistManagedCommandReceipt(invocation.receiptPath, receipt.structuredContent);
+        return receipt;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        stderr = appendBounded(stderr, message);
+        const receipt = managedCommandResult({
+            ...invocation,
+            timedOut,
+            status: timedOut ? "timeout_termination_failed" : "runner_error",
+            exitCode: null,
+            stdout,
+            stderr,
+        });
+        await persistManagedCommandReceipt(invocation.receiptPath, receipt.structuredContent);
+        return receipt;
+    }
+    finally {
+        clearTimeout(launchTimer);
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+async function readManagedCommand(input) {
+    const commandId = requiredInputString(asRecord(input), "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.");
+    }
+    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 {
+        content: [{
+                type: "text",
+                text: terminalManagedCommandStatuses.has(status)
+                    ? `Forge managed command ${commandId} is ${status} (exit ${receipt.exit_code ?? "unavailable"}).\nstdout:\n${stdout || "(empty)"}\nstderr:\n${stderr || "(empty)"}`
+                    : `Forge managed command ${commandId} is ${status}. Poll this tool again after the command advances.`,
+            }],
+        structuredContent: receipt,
+        isError: terminalManagedCommandStatuses.has(status) && status !== "pass",
+    };
+}
+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 });
+    await fs.rename(temporaryPath, receiptPath);
+}
+function managedCommandResult(values) {
+    const elapsedMs = Date.now() - values.startedAt;
+    return {
+        content: [{
+                type: "text",
+                text: `Forge managed command ${values.commandId} ${values.status} after ${elapsedMs}ms (exit ${values.exitCode ?? "unavailable"}).\nstdout:\n${values.stdout || "(empty)"}\nstderr:\n${values.stderr || "(empty)"}`,
+            }],
+        structuredContent: {
+            command_id: values.commandId,
+            status: values.status,
+            command: [values.command, ...values.args],
+            cwd: values.cwd,
+            timeout_ms: values.timeoutMs,
+            elapsed_ms: elapsedMs,
+            timed_out: values.timedOut,
+            exit_code: values.exitCode,
+            stdout: values.stdout,
+            stderr: values.stderr,
+            supervisor_metadata_path: values.metadataPath,
+            receipt_path: values.receiptPath,
+            process_tree_terminated: values.status === "timed_out" ? true : values.timedOut ? false : undefined,
+        },
+        isError: terminalManagedCommandStatuses.has(values.status) && values.status !== "pass",
+    };
+}
+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 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 appendBounded(current, line) {
+    if (current.length >= maximumCapturedCharacters)
+        return current;
+    return `${current}${line}\n`.slice(0, maximumCapturedCharacters);
+}