@loucompanion/forge-bridge 0.1.3-dev.f66395c3ac21 → 0.1.4-dev.04a1e5b9e484

package/dist/session/phase-completion.runtime.js

@@ -0,0 +1,840 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { attemptDatabaseCapabilityEnvironment, attemptDatabaseCapabilitySecrets, } from "../runtime/attempt-database-broker.js";
+import { completionPhaseFromDispatch, completionPhaseOrder, completionRedactionSecretsEnv, completionToolNamesForDebugGate, completionToolNamesForDecomposeGate, completionToolNamesForDraftGate, completionToolNamesForPhase, completionToolNamesForQaGate, debugCompletionPhaseOrder, decomposeCompletionGateOrder, draftCompletionGateOrder, qaCompletionGateOrder, toolServerName, usesArchitectCycleCompletion, usesDebugCycleCompletion, usesDevelopCycleCompletion, usesQaCycleCompletion } from "./phase-completion.js";
+import { CompletionPayloadValidationError, asDebugCompletionPhase, asJsonRpcMessage, asMutableRecord, asRecord, artifactOwnerRelativeRoot, decomposeGateFromToolName, draftGateFromToolName, errorMessage, forgeBridgeCliBinPath, isDebugCompletionPhase, isDecomposeDispatch, isDevelopCompletionPhase, normalizedOwnerType, parseCompletionRedactionSecrets, parseOptionalJsonObject, parseStrictCompletionPhase, phaseFromToolName, qaGateFromToolName, requiredString, rpcError, tomlString, tomlStringArray, writeFileAtomic, writeJsonRpc } from "./phase-completion.validation.js";
+import { completionPromptForDebugCycle, completionPromptForDecomposeCycle, completionPromptForDevelopCycle, completionPromptForDraftCycle, completionPromptForPhase, completionPromptForQaCycle, completionToolNextInstruction, completionToolNextInstructionForDebugGate, completionToolNextInstructionForDecomposeGate, completionToolNextInstructionForDraftGate, completionToolNextInstructionForQaGate, nextDebugPhaseAfter, nextPhaseAfter } from "./phase-completion.prompts.js";
+import { configuredNativeTestPostgresFallbackPath, nativeTestPostgresFallbackConfigEnvironment, } from "../runtime/native-test-postgres-fallback.js";
+import { toolDescription, toolInputSchema } from "./phase-completion.schemas.js";
+import { writeCompletionArtifact, writeDecomposeGateCompletionArtifact, writeDraftGateCompletionArtifact } from "./phase-completion.artifacts.js";
+import { callManagedAttemptTool, isManagedAttemptTool, managedAttemptToolDefinition, managedAttemptToolNames, } from "./managed-attempt-tools.js";
+export async function prepareCompletionToolRuntime(options) {
+    const phase = options.phase ?? completionPhaseFromDispatch(options.dispatch);
+    const worktreePath = path.resolve(options.worktree.worktreePath);
+    const workItemId = options.dispatch.workItem.id;
+    const ownerType = normalizedOwnerType(options.dispatch.cycleRun.ownerType) ?? "work_item";
+    const ownerId = options.dispatch.cycleRun.ownerId ?? workItemId;
+    const mcpArgs = buildCompletionToolServerArgs({
+        worktreePath,
+        workItemId,
+        ownerType,
+        ownerId,
+        phase,
+        producedBy: `${options.dispatch.execution.provider}-cli`,
+        developCycle: usesDevelopCycleCompletion(options.dispatch),
+        qaCycle: usesQaCycleCompletion(options.dispatch),
+        debugCycle: usesDebugCycleCompletion(options.dispatch),
+        architectCycle: usesArchitectCycleCompletion(options.dispatch),
+        draftCycle: (phase === "draft"
+            || options.dispatch.execution.lane.trim().toLowerCase() === "draft"
+            || options.dispatch.cycleRun.kind.trim().toLowerCase() === "draft")
+            && !isDecomposeDispatch(options.dispatch),
+        decomposeCycle: isDecomposeDispatch(options.dispatch)
+    });
+    const runtime = {
+        serverName: toolServerName,
+        command: process.execPath,
+        args: [forgeBridgeCliBinPath(), ...mcpArgs],
+        env: completionToolRuntimeEnvironment(options.runtimeEnvironment, configuredNativeTestPostgresFallbackPath()),
+        cleanup: async () => undefined
+    };
+    const provider = options.dispatch.execution.provider.trim().toLowerCase();
+    if (provider === "cursor") {
+        return await prepareCursorCompletionToolRuntime(worktreePath, runtime);
+    }
+    if (provider === "claude") {
+        return await prepareClaudeCompletionToolRuntime(runtime);
+    }
+    return runtime;
+}
+export function buildCompletionToolServerArgs(config) {
+    const args = [
+        "mcp",
+        "--worktree",
+        path.resolve(config.worktreePath),
+        "--work-item-id",
+        config.workItemId,
+        "--phase",
+        config.phase,
+        "--produced-by",
+        config.producedBy ?? "forge-completion-tool"
+    ];
+    if (config.ownerType || config.ownerId) {
+        args.push("--owner-type", normalizedOwnerType(config.ownerType) ?? "work_item");
+        args.push("--owner-id", config.ownerId ?? config.workItemId);
+    }
+    if (config.developCycle) {
+        args.push("--develop-cycle");
+    }
+    if (config.qaCycle) {
+        args.push("--qa-cycle");
+    }
+    if (config.debugCycle) {
+        args.push("--debug-cycle");
+    }
+    if (config.architectCycle) {
+        args.push("--architect-cycle");
+    }
+    if (config.draftCycle) {
+        args.push("--draft-cycle");
+    }
+    if (config.decomposeCycle) {
+        args.push("--decompose-cycle");
+    }
+    return args;
+}
+export function codexMcpConfigArgs(runtime) {
+    const prefix = `mcp_servers.${runtime.serverName}`;
+    const args = [
+        "-c",
+        `${prefix}.command=${tomlString(runtime.command)}`,
+        "-c",
+        `${prefix}.args=${tomlStringArray(runtime.args)}`,
+        "-c",
+        `${prefix}.default_tools_approval_mode=${tomlString("approve")}`,
+        "-c",
+        `${prefix}.tool_timeout_sec=7200`
+    ];
+    for (const [key, value] of Object.entries(runtime.env)) {
+        args.push("-c", `${prefix}.env.${key}=${tomlString(value)}`);
+    }
+    return args;
+}
+export function cursorMcpServerConfig(runtime) {
+    return {
+        command: runtime.command,
+        args: [...runtime.args],
+        env: runtime.env
+    };
+}
+export function claudeMcpServerConfig(runtime) {
+    return {
+        type: "stdio",
+        command: runtime.command,
+        args: [...runtime.args],
+        env: runtime.env
+    };
+}
+export function completionToolNamesForServer(config) {
+    return config.decomposeCycle
+        ? decomposeCompletionGateOrder.flatMap((gate) => completionToolNamesForDecomposeGate(gate))
+        : config.draftCycle
+            ? draftCompletionGateOrder.flatMap((gate) => completionToolNamesForDraftGate(gate))
+            : config.debugCycle
+                ? debugCompletionPhaseOrder.flatMap((gate) => completionToolNamesForDebugGate(gate))
+                : config.qaCycle
+                    ? qaCompletionGateOrder.flatMap((gate) => completionToolNamesForQaGate(gate))
+                    : config.developCycle
+                        ? completionPhaseOrder.flatMap((phase) => completionToolNamesForPhase(phase))
+                        : config.architectCycle
+                            ? completionToolNamesForPhase("architect")
+                            : completionToolNamesForPhase(config.phase);
+}
+export class CompletionToolServerSession {
+    config;
+    currentPhase;
+    currentQaGate = "qa_plan";
+    currentDraftGate = "draft_intent";
+    currentDecomposeGate = "decompose_subject_intake";
+    managedCommandReceipts = [];
+    completed = false;
+    constructor(config) {
+        this.config = config;
+        this.currentPhase = config.phase;
+    }
+    get instructions() {
+        return this.config.decomposeCycle
+            ? completionPromptForDecomposeCycle(this.currentDecomposeGate)
+            : this.config.draftCycle
+                ? completionPromptForDraftCycle(this.currentDraftGate)
+                : this.config.debugCycle
+                    ? completionPromptForDebugCycle(asDebugCompletionPhase(this.currentPhase))
+                    : this.config.qaCycle
+                        ? completionPromptForQaCycle(this.currentQaGate, artifactOwnerRelativeRoot(this.config.ownerType, this.config.ownerId, this.config.workItemId))
+                        : this.config.developCycle
+                            ? completionPromptForDevelopCycle(this.currentPhase)
+                            : completionPromptForPhase(this.currentPhase, artifactOwnerRelativeRoot(this.config.ownerType, this.config.ownerId, this.config.workItemId));
+    }
+    toolDefinitions() {
+        const completionTools = completionToolNamesForServer(this.config).map((name) => toolDefinition(name, phaseFromToolName(name), qaGateFromToolName(name), decomposeGateFromToolName(name)));
+        return managedAttemptToolsAvailable()
+            ? [...completionTools, ...managedAttemptToolNames.map(managedAttemptToolDefinition)]
+            : completionTools;
+    }
+    async callTool(toolName, input) {
+        if (isManagedAttemptTool(toolName)) {
+            if (!managedAttemptToolsAvailable()) {
+                throw new Error("Forge managed-attempt tools require an active managed host runtime.");
+            }
+            const result = await callManagedAttemptTool(toolName, input, this.config.worktreePath);
+            if (Array.isArray(result.structuredContent.command)) {
+                this.managedCommandReceipts.push(result.structuredContent);
+            }
+            return result;
+        }
+        const requestedPhase = phaseFromToolName(toolName);
+        if (this.completed) {
+            throw new Error("Forge completion cycle is already complete; no more completion calls are accepted.");
+        }
+        if (this.config.decomposeCycle) {
+            return await this.callDecomposeGateTool(toolName, requestedPhase, input);
+        }
+        if (this.config.draftCycle) {
+            return await this.callDraftGateTool(toolName, requestedPhase, input);
+        }
+        if (this.config.debugCycle) {
+            return await this.callDebugGateTool(toolName, requestedPhase, input);
+        }
+        if (this.config.qaCycle) {
+            return await this.callQaGateTool(toolName, requestedPhase, input);
+        }
+        if (requestedPhase !== this.currentPhase) {
+            throw new Error(`Tool ${toolName} is out of order. Current Forge phase is ${this.currentPhase}.`);
+        }
+        const completedPhase = this.currentPhase;
+        const reference = await writeCompletionArtifact({ ...this.config, phase: completedPhase }, toolName, input);
+        const status = reference.status.trim().toLowerCase();
+        const pass = status === "pass";
+        const nextPhase = pass
+            ? this.advanceAfterPass(completedPhase)
+            : completedPhase;
+        const nextInstruction = completionToolNextInstruction(completedPhase, status, nextPhase);
+        const reason = completedPhase === "qa"
+            ? `QA artifact recorded locally with status ${status}; API ingestion and acceptance are pending.`
+            : pass
+                ? `${completedPhase} completion artifact accepted.`
+                : `${completedPhase} completion artifact recorded with status ${status}; rework is required before phase progression.`;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Forge recorded ${reference.phase} completion artifact ${path.relative(reference.repoPath, reference.path)} (${reference.status}, ${reference.contentHash}). ${nextInstruction}`
+                }
+            ],
+            structuredContent: {
+                ...reference,
+                ...acceptedArtifactReceipt(reference),
+                gate: {
+                    phase: completedPhase,
+                    status,
+                    allowed: pass,
+                    reason
+                },
+                nextPhase,
+                nextInstruction
+            }
+        };
+    }
+    async callDecomposeGateTool(toolName, requestedPhase, input) {
+        const requestedGate = decomposeGateFromToolName(toolName);
+        if (requestedPhase !== "decompose" || !requestedGate) {
+            throw new Error(`Tool ${toolName} is not available in Decompose-cycle mode. Current Forge Decompose gate is ${this.currentDecomposeGate}.`);
+        }
+        if (requestedGate !== this.currentDecomposeGate) {
+            throw new Error(`Tool ${toolName} is out of order. Current Forge Decompose gate is ${this.currentDecomposeGate}.`);
+        }
+        const completedGate = this.currentDecomposeGate;
+        const reference = await writeDecomposeGateCompletionArtifact(this.config, completedGate, toolName, input);
+        const status = reference.status.trim().toLowerCase();
+        const pass = status === "pass";
+        const nextGate = pass ? this.advanceAfterDecomposeGate(completedGate) : completedGate;
+        const nextPhase = pass
+            ? (nextGate ? "decompose" : "sign_off_ready")
+            : "decompose";
+        const nextInstruction = completionToolNextInstructionForDecomposeGate(completedGate, status, nextGate);
+        const reason = pass
+            ? nextGate
+                ? `${completedGate} artifact accepted; continue to ${nextGate}.`
+                : `Decompose proposal artifact accepted with status ${status}.`
+            : `${completedGate} artifact recorded with status ${status}; rework is required before continuing.`;
+        return {
+            content: [{ type: "text", text: `Forge recorded ${completedGate} artifact ${path.relative(reference.repoPath, reference.path)} (${reference.status}, ${reference.contentHash}). ${nextInstruction}` }],
+            structuredContent: {
+                ...reference,
+                ...acceptedArtifactReceipt(reference),
+                gate: { phase: "decompose", decomposeGate: completedGate, status, allowed: pass, reason },
+                nextPhase,
+                nextInstruction
+            }
+        };
+    }
+    async callDraftGateTool(toolName, requestedPhase, input) {
+        const requestedGate = draftGateFromToolName(toolName);
+        if (requestedPhase !== "draft" || !requestedGate) {
+            throw new Error(`Tool ${toolName} is not available in Draft-cycle mode. Current Forge Draft gate is ${this.currentDraftGate}.`);
+        }
+        if (requestedGate !== this.currentDraftGate) {
+            throw new Error(`Tool ${toolName} is out of order. Current Forge Draft gate is ${this.currentDraftGate}.`);
+        }
+        const completedGate = this.currentDraftGate;
+        const reference = await writeDraftGateCompletionArtifact(this.config, completedGate, toolName, input);
+        const status = reference.status.trim().toLowerCase();
+        const nextGate = this.advanceAfterDraftGate(completedGate);
+        const nextPhase = nextGate ? "draft" : "sign_off_ready";
+        const nextInstruction = completionToolNextInstructionForDraftGate(completedGate, status, nextGate);
+        return {
+            content: [{ type: "text", text: `Forge recorded ${completedGate} artifact ${path.relative(reference.repoPath, reference.path)} (${reference.status}, ${reference.contentHash}). ${nextInstruction}` }],
+            structuredContent: {
+                ...reference,
+                ...acceptedArtifactReceipt(reference),
+                gate: { phase: "draft", draftGate: completedGate, status, allowed: status !== "blocked", reason: nextGate ? `${completedGate} artifact accepted; continue to ${nextGate}.` : `Draft proposal artifact accepted with status ${status}.` },
+                nextPhase,
+                nextInstruction
+            }
+        };
+    }
+    async callDebugGateTool(toolName, requestedPhase, input) {
+        const currentDebugGate = asDebugCompletionPhase(this.currentPhase);
+        if (!isDebugCompletionPhase(requestedPhase)) {
+            throw new Error(`Tool ${toolName} is not available in Debug-cycle mode. Current Forge Debug gate is ${currentDebugGate}.`);
+        }
+        if (requestedPhase !== currentDebugGate) {
+            throw new Error(`Tool ${toolName} is out of order. Current Forge Debug gate is ${currentDebugGate}.`);
+        }
+        const completedGate = currentDebugGate;
+        const reference = await writeCompletionArtifact({ ...this.config, phase: completedGate }, toolName, input);
+        const status = reference.status.trim().toLowerCase();
+        const pass = status === "pass";
+        const nextGate = pass ? this.advanceAfterDebugGate(completedGate) : completedGate;
+        const nextPhase = nextGate ?? "qa_ready";
+        const nextInstruction = completionToolNextInstructionForDebugGate(completedGate, status, nextGate);
+        const reason = pass
+            ? `${completedGate} artifact accepted${nextGate ? `; continue to ${nextGate}.` : "; Debug regression is QA-ready."}`
+            : `${completedGate} artifact recorded with status ${status}; rework is required before Debug progression.`;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Forge recorded ${completedGate} artifact ${path.relative(reference.repoPath, reference.path)} (${reference.status}, ${reference.contentHash}). ${nextInstruction}`
+                }
+            ],
+            structuredContent: {
+                ...reference,
+                ...acceptedArtifactReceipt(reference),
+                gate: {
+                    phase: completedGate,
+                    status,
+                    allowed: pass,
+                    reason
+                },
+                nextPhase,
+                nextInstruction
+            }
+        };
+    }
+    async callQaGateTool(toolName, requestedPhase, input) {
+        const requestedGate = qaGateFromToolName(toolName);
+        if (requestedPhase !== "qa" || !requestedGate) {
+            throw new Error(`Tool ${toolName} is not available in QA-cycle mode. Current Forge QA gate is ${this.currentQaGate}.`);
+        }
+        if (requestedGate !== this.currentQaGate) {
+            throw new Error(`Tool ${toolName} is out of order. Current Forge QA gate is ${this.currentQaGate}.`);
+        }
+        const completedGate = this.currentQaGate;
+        if (completedGate === "qa_regression" && managedAttemptToolsAvailable()) {
+            assertManagedQaRegressionEvidence(input, this.managedCommandReceipts);
+        }
+        const reference = await writeCompletionArtifact({ ...this.config, phase: "qa" }, toolName, input);
+        const status = reference.status.trim().toLowerCase();
+        const nextGate = this.advanceAfterQaGate(completedGate);
+        const nextPhase = nextGate ? "qa" : "sign_off_ready";
+        const nextInstruction = completionToolNextInstructionForQaGate(completedGate, status, nextGate);
+        const allowed = status !== "blocked";
+        const reason = nextGate
+            ? `${completedGate} artifact accepted locally; continue to ${nextGate}.`
+            : `QA verdict artifact recorded locally with status ${status}; API ingestion and acceptance are pending.`;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Forge recorded ${completedGate} artifact ${path.relative(reference.repoPath, reference.path)} (${reference.status}, ${reference.contentHash}). ${nextInstruction}`
+                }
+            ],
+            structuredContent: {
+                ...reference,
+                ...acceptedArtifactReceipt(reference),
+                gate: {
+                    phase: "qa",
+                    qaGate: completedGate,
+                    status,
+                    allowed,
+                    reason
+                },
+                nextPhase,
+                nextInstruction
+            }
+        };
+    }
+    advanceAfterPass(phase) {
+        if (phase === "qa") {
+            this.completed = true;
+            return "sign_off_ready";
+        }
+        if (phase === "ci_repair") {
+            this.completed = true;
+            return "provider_checks_ready";
+        }
+        if (isDebugCompletionPhase(phase)) {
+            return nextDebugPhaseAfter(phase) ?? "qa_ready";
+        }
+        const next = nextPhaseAfter(phase);
+        if (!this.config.developCycle) {
+            return next ?? "dev_test_ready";
+        }
+        if (next) {
+            this.currentPhase = next;
+            return next;
+        }
+        this.completed = true;
+        return "dev_test_ready";
+    }
+    advanceAfterDecomposeGate(gate) {
+        const index = decomposeCompletionGateOrder.indexOf(gate);
+        const next = index >= 0 ? decomposeCompletionGateOrder[index + 1] ?? null : null;
+        if (next) {
+            this.currentDecomposeGate = next;
+            return next;
+        }
+        this.completed = true;
+        return null;
+    }
+    advanceAfterDraftGate(gate) {
+        const index = draftCompletionGateOrder.indexOf(gate);
+        const next = index >= 0 ? draftCompletionGateOrder[index + 1] ?? null : null;
+        if (next) {
+            this.currentDraftGate = next;
+            return next;
+        }
+        this.completed = true;
+        return null;
+    }
+    advanceAfterQaGate(gate) {
+        const index = qaCompletionGateOrder.indexOf(gate);
+        const next = index >= 0 ? qaCompletionGateOrder[index + 1] ?? null : null;
+        if (next) {
+            this.currentQaGate = next;
+            return next;
+        }
+        this.completed = true;
+        return null;
+    }
+    advanceAfterDebugGate(gate) {
+        const index = debugCompletionPhaseOrder.indexOf(gate);
+        const next = index >= 0 ? debugCompletionPhaseOrder[index + 1] ?? null : null;
+        if (next) {
+            this.currentPhase = next;
+            return next;
+        }
+        this.completed = true;
+        return null;
+    }
+}
+const completionToolRuntimeEnvironmentNames = [
+    "FORGE_RUNTIME_MODE",
+    "FORGE_RESOURCE_LEASE_ID",
+    "FORGE_DISPATCH_ATTEMPT_ID",
+    "FORGE_E2E_OWNERSHIP_MODE",
+    "FORGE_E2E_OWNERSHIP_TOKEN",
+    "FORGE_WORKTREE_PATH",
+    "FORGE_LOG_DIR",
+    "FORGE_CACHE_DIR",
+    "FORGE_TEST_OUTPUT_DIR",
+    "FORGE_ATTEMPT_DATABASE_SCHEMA",
+    "FORGE_ATTEMPT_DATABASE_READINESS_PATH",
+    "FORGE_ATTEMPT_DATABASE_CAPABILITY",
+    "FORGE_CI_REPAIR_READINESS_PATH",
+    "FORGE_CI_REPAIR_HANDOFF_PATH",
+    "FORGE_CI_REPAIR_PROVIDER_ONLY_SPECS",
+    "FORGE_PLAYWRIGHT_CONFIG",
+    "FORGE_API_URL",
+    "FORGE_WEB_URL",
+    "FORGE_E2E_API_URL",
+    "FORGE_E2E_WEB_URL",
+    "PLAYWRIGHT_BROWSERS_PATH",
+    "FORGE_TMPDIR",
+    "NPM_CONFIG_CACHE",
+    "TMPDIR",
+    "TMP",
+    "TEMP",
+];
+export function completionToolRuntimeEnvironment(runtimeEnvironment, nativeTestPostgresFallbackPath) {
+    if (!runtimeEnvironment)
+        return {};
+    const env = {};
+    for (const name of completionToolRuntimeEnvironmentNames) {
+        const value = runtimeEnvironment[name]?.trim();
+        if (value)
+            env[name] = value;
+    }
+    // Managed verification reads the operator's native test cluster only through
+    // this explicit path, and only while Docker is unavailable.
+    if (nativeTestPostgresFallbackPath) {
+        env[nativeTestPostgresFallbackConfigEnvironment] = nativeTestPostgresFallbackPath;
+    }
+    return env;
+}
+const minimumManagedSolutionTestTimeoutMs = 45 * 60 * 1000;
+/**
+ * A solution-wide Forge test is long enough that a generic provider shell can
+ * expire while VSTest is still healthy. On managed host attempts, only the
+ * attempt-owned command runner can prove the exact process outcome and clean
+ * up its process tree. Keep this check at the completion gate so prompt drift
+ * cannot turn an arbitrary shell timeout into a QA blocker.
+ */
+export function assertManagedQaRegressionEvidence(input, receipts) {
+    const payload = asRecord(input, "QA regression completion payload");
+    const nestedEvidence = asMutableRecord(payload.evidence);
+    const commands = payload.commands ?? nestedEvidence.commands;
+    if (!Array.isArray(commands))
+        return;
+    for (const [index, entry] of commands.entries()) {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry))
+            continue;
+        const command = entry.command;
+        if (typeof command !== "string" || !isForgeSolutionTestCommand(command))
+            continue;
+        const managedCommandId = entry.managed_command_id;
+        if (typeof managedCommandId !== "string" || !managedCommandId.trim()) {
+            throw new Error(`qa_regression_managed_command_id_required: commands[${index}] runs the solution-wide Forge test. `
+                + "Run it with forge.start_managed_command, continue independent work, then call forge.wait_managed_command for a transport-safe receipt. "
+                + "If command_continues=true, continue useful work or wait again after retry_after_ms. Include the terminal managed_command_id in this command evidence.");
+        }
+        const matchingReceipts = receipts.filter((receipt) => {
+            const tokens = receipt.command;
+            return receipt.command_id === managedCommandId
+                && Array.isArray(tokens)
+                && tokens.every((token) => typeof token === "string")
+                && isForgeSolutionTestCommand(tokens.join(" "));
+        });
+        if (matchingReceipts.length === 0) {
+            throw new Error(`qa_regression_managed_command_required: commands[${index}] runs the solution-wide Forge test. `
+                + "Run it with forge.start_managed_command, continue independent work, then call forge.wait_managed_command for a transport-safe receipt. "
+                + "If command_continues=true, continue useful work or wait again after retry_after_ms. Include its matching terminal managed_command_id; generic-shell timeout evidence is not accepted on a managed host.");
+        }
+        const terminalReceipts = matchingReceipts.filter((receipt) => typeof receipt.status === "string" && [
+            "pass",
+            "fail",
+            "timed_out",
+            "timeout_termination_failed",
+            "runner_error",
+        ].includes(receipt.status));
+        if (terminalReceipts.length === 0) {
+            throw new Error(`qa_regression_managed_command_in_progress: commands[${index}] has not produced a terminal managed receipt. `
+                + "Call forge.wait_managed_command. If command_continues=true, continue useful work or wait again after retry_after_ms; resubmit this gate only after the receipt is terminal.");
+        }
+        const adequateReceipt = terminalReceipts.some((receipt) => {
+            if (receipt.timed_out !== true)
+                return true;
+            return typeof receipt.timeout_ms === "number"
+                && receipt.timeout_ms >= minimumManagedSolutionTestTimeoutMs
+                && receipt.process_tree_terminated === true;
+        });
+        if (!adequateReceipt) {
+            throw new Error(`qa_regression_managed_timeout_too_short: commands[${index}] timed out before the minimum `
+                + `${minimumManagedSolutionTestTimeoutMs}ms solution-test budget. Rerun it with forge.start_managed_command `
+                + "using at least a 45-minute timeout and resubmit this gate.");
+        }
+    }
+}
+function isForgeSolutionTestCommand(command) {
+    const normalized = command.trim().toLowerCase().replaceAll("\\", "/");
+    return normalized.includes("dotnet")
+        && /(?:^|\s)test(?:\s|$)/u.test(normalized)
+        && /(?:^|[\s/"'])forge\.sln(?:[\s"']|$)/u.test(normalized);
+}
+function managedAttemptToolsAvailable() {
+    return process.env.FORGE_RUNTIME_MODE === "host"
+        && Boolean(process.env.FORGE_RESOURCE_LEASE_ID?.trim())
+        && Boolean(process.env.FORGE_DISPATCH_ATTEMPT_ID?.trim())
+        && Boolean(process.env.FORGE_LOG_DIR?.trim())
+        && Boolean(process.env.FORGE_TEST_OUTPUT_DIR?.trim());
+}
+export async function runCompletionMcpServer(config) {
+    const session = new CompletionToolServerSession(config);
+    process.stdin.setEncoding("utf8");
+    let buffer = "";
+    for await (const chunk of process.stdin) {
+        buffer += chunk;
+        let newlineIndex = buffer.indexOf("\n");
+        while (newlineIndex >= 0) {
+            const rawLine = buffer.slice(0, newlineIndex).trim();
+            buffer = buffer.slice(newlineIndex + 1);
+            if (rawLine.length > 0) {
+                await handleJsonRpcLine(session, rawLine);
+            }
+            newlineIndex = buffer.indexOf("\n");
+        }
+    }
+    const trailing = buffer.trim();
+    if (trailing.length > 0) {
+        await handleJsonRpcLine(session, trailing);
+    }
+}
+export function parseCompletionMcpArgs(argv) {
+    let worktreePath = null;
+    let workItemId = null;
+    let phase = "implementation";
+    let ownerType;
+    let ownerId;
+    let producedBy;
+    let developCycle = false;
+    let qaCycle = false;
+    let debugCycle = false;
+    let architectCycle = false;
+    let draftCycle = false;
+    let decomposeCycle = false;
+    for (let index = 1; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--worktree") {
+            worktreePath = argv[++index] ?? null;
+        }
+        else if (arg === "--work-item-id") {
+            workItemId = argv[++index] ?? null;
+        }
+        else if (arg === "--owner-type") {
+            ownerType = normalizedOwnerType(argv[++index]);
+            if (!ownerType) {
+                return { ok: false, error: "mcp --owner-type must be work_item or story." };
+            }
+        }
+        else if (arg === "--owner-id") {
+            ownerId = argv[++index] ?? undefined;
+        }
+        else if (arg === "--phase") {
+            const rawPhase = argv[++index];
+            const parsedPhase = parseStrictCompletionPhase(rawPhase);
+            if (!parsedPhase) {
+                return { ok: false, error: "mcp --phase must be one of: implementation, self-review, validation, qa, architect, draft, decompose, ci-repair, comment-repair, debug-repro, debug-root-cause, debug-fix, debug-regression." };
+            }
+            phase = parsedPhase;
+        }
+        else if (arg === "--produced-by") {
+            producedBy = argv[++index] ?? undefined;
+        }
+        else if (arg === "--develop-cycle") {
+            developCycle = true;
+        }
+        else if (arg === "--qa-cycle") {
+            qaCycle = true;
+        }
+        else if (arg === "--debug-cycle") {
+            debugCycle = true;
+        }
+        else if (arg === "--architect-cycle") {
+            architectCycle = true;
+        }
+        else if (arg === "--draft-cycle") {
+            draftCycle = true;
+        }
+        else if (arg === "--decompose-cycle") {
+            decomposeCycle = true;
+        }
+        else {
+            return { ok: false, error: `Unknown mcp argument: ${arg}` };
+        }
+    }
+    if (!worktreePath?.trim() || !workItemId?.trim()) {
+        return { ok: false, error: "mcp requires --worktree and --work-item-id." };
+    }
+    if ([developCycle, qaCycle, debugCycle, architectCycle, draftCycle, decomposeCycle].filter(Boolean).length > 1) {
+        return { ok: false, error: "mcp accepts only one cycle mode." };
+    }
+    if (developCycle && !isDevelopCompletionPhase(phase)) {
+        return { ok: false, error: "mcp --develop-cycle requires --phase implementation, self-review, or validation." };
+    }
+    if (qaCycle && phase !== "qa") {
+        return { ok: false, error: "mcp --qa-cycle requires --phase qa." };
+    }
+    if (debugCycle && !isDebugCompletionPhase(phase)) {
+        return { ok: false, error: "mcp --debug-cycle requires --phase debug-repro, debug-root-cause, debug-fix, or debug-regression." };
+    }
+    if (architectCycle && phase !== "architect") {
+        return { ok: false, error: "mcp --architect-cycle requires --phase architect." };
+    }
+    if (draftCycle && phase !== "draft") {
+        return { ok: false, error: "mcp --draft-cycle requires --phase draft." };
+    }
+    if (decomposeCycle && phase !== "decompose") {
+        return { ok: false, error: "mcp --decompose-cycle requires --phase decompose." };
+    }
+    return {
+        ok: true,
+        config: {
+            worktreePath: path.resolve(worktreePath),
+            workItemId,
+            ownerType,
+            ownerId,
+            phase,
+            producedBy,
+            redactionSecrets: [
+                ...parseCompletionRedactionSecrets(process.env[completionRedactionSecretsEnv]),
+                ...attemptDatabaseCapabilitySecrets(process.env[attemptDatabaseCapabilityEnvironment]),
+            ],
+            developCycle,
+            qaCycle,
+            debugCycle,
+            architectCycle,
+            draftCycle,
+            decomposeCycle
+        }
+    };
+}
+export function completionRedactionEnv(secrets) {
+    const filtered = secrets.filter((secret) => secret.length > 0);
+    return filtered.length > 0
+        ? { [completionRedactionSecretsEnv]: JSON.stringify(filtered) }
+        : {};
+}
+async function prepareCursorCompletionToolRuntime(worktreePath, runtime) {
+    const cursorDir = path.join(worktreePath, ".cursor");
+    const configPath = path.join(cursorDir, "mcp.json");
+    const original = await fs.readFile(configPath, "utf8").then((content) => ({ existed: true, content }), () => ({ existed: false, content: "" }));
+    const existing = original.existed ? parseOptionalJsonObject(original.content, configPath) : {};
+    const servers = asMutableRecord(existing.mcpServers);
+    servers[runtime.serverName] = cursorMcpServerConfig(runtime);
+    const next = {
+        ...existing,
+        mcpServers: servers
+    };
+    await fs.mkdir(cursorDir, { recursive: true });
+    await writeFileAtomic(configPath, `${JSON.stringify(next, null, 2)}\n`);
+    return {
+        ...runtime,
+        cursorMcpConfigPath: configPath,
+        cleanup: async () => {
+            if (original.existed) {
+                await writeFileAtomic(configPath, original.content);
+            }
+            else {
+                await fs.rm(configPath, { force: true });
+                await fs.rmdir(cursorDir).catch(() => undefined);
+            }
+        }
+    };
+}
+/**
+ * Claude Code takes MCP servers from `--mcp-config <file>`. The file lives in an attempt-owned
+ * temp directory (never the worktree) because its env block can carry redaction secrets, and
+ * passing the JSON inline would not survive Windows shim quoting.
+ */
+async function prepareClaudeCompletionToolRuntime(runtime) {
+    const configDir = await fs.mkdtemp(path.join(os.tmpdir(), "forge-claude-mcp-"));
+    const configPath = path.join(configDir, "mcp.json");
+    const config = {
+        mcpServers: {
+            [runtime.serverName]: claudeMcpServerConfig(runtime)
+        }
+    };
+    await fs.writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    return {
+        ...runtime,
+        claudeMcpConfigPath: configPath,
+        cleanup: async () => {
+            await fs.rm(configDir, { recursive: true, force: true });
+        }
+    };
+}
+async function handleJsonRpcLine(session, rawLine) {
+    let message;
+    try {
+        message = JSON.parse(rawLine);
+    }
+    catch (error) {
+        writeJsonRpc({ jsonrpc: "2.0", id: null, error: rpcError(-32700, errorMessage(error)) });
+        return;
+    }
+    const request = asJsonRpcMessage(message);
+    if (!request) {
+        writeJsonRpc({ jsonrpc: "2.0", id: null, error: rpcError(-32600, "Invalid JSON-RPC message.") });
+        return;
+    }
+    if (request.id === undefined) {
+        return;
+    }
+    try {
+        const result = await handleJsonRpcRequest(session, request.method, request.params);
+        writeJsonRpc({ jsonrpc: "2.0", id: request.id, result });
+    }
+    catch (error) {
+        writeJsonRpc({ jsonrpc: "2.0", id: request.id, error: rpcError(-32000, errorMessage(error)) });
+    }
+}
+async function handleJsonRpcRequest(session, method, params) {
+    if (method === "initialize") {
+        const initializeParams = params && typeof params === "object" && !Array.isArray(params)
+            ? params
+            : {};
+        return {
+            protocolVersion: typeof initializeParams.protocolVersion === "string" ? initializeParams.protocolVersion : "2025-06-18",
+            capabilities: {
+                tools: {}
+            },
+            serverInfo: {
+                name: "forge-completion-tools",
+                version: "0.1.0"
+            },
+            instructions: session.instructions
+        };
+    }
+    if (method === "ping") {
+        return {};
+    }
+    if (method === "tools/list") {
+        return {
+            tools: session.toolDefinitions()
+        };
+    }
+    if (method === "tools/call") {
+        const call = asRecord(params, "tools/call params");
+        const name = requiredString(call, "name");
+        const args = call.arguments ?? {};
+        try {
+            return await session.callTool(name, args);
+        }
+        catch (error) {
+            if (isManagedAttemptTool(name))
+                throw error;
+            return completionToolRejectedResult(name, error);
+        }
+    }
+    throw new Error(`Unsupported MCP method: ${method}`);
+}
+export function completionToolRejectedResult(toolName, error) {
+    const issues = error instanceof CompletionPayloadValidationError
+        ? [...error.issues]
+        : [errorMessage(error)];
+    const repairInstruction = "Repair every listed issue and resubmit this same gate once. Do not inspect the artifact path: rejected calls never write or replace completion artifacts.";
+    return {
+        content: [{
+                type: "text",
+                text: `Forge rejected ${toolName}. No artifact was written.\n${issues.map(issue => `- ${issue}`).join("\n")}\n${repairInstruction}`,
+            }],
+        structuredContent: {
+            status: "rejected",
+            tool_name: toolName,
+            artifact_written: false,
+            issues,
+            repair_instruction: repairInstruction,
+        },
+        isError: true,
+    };
+}
+function acceptedArtifactReceipt(reference) {
+    return {
+        artifact_written: true,
+        artifact_receipt: {
+            schema_version: 1,
+            path: reference.path,
+            report_path: reference.reportPath,
+            content_hash: reference.contentHash,
+        },
+    };
+}
+function toolDefinition(name, phase, qaGate = null, decomposeGate = null) {
+    return {
+        name,
+        description: toolDescription(phase, qaGate, decomposeGate),
+        inputSchema: toolInputSchema(phase, qaGate, decomposeGate)
+    };
+}