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

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);
+}

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

@@ -237,12 +237,19 @@ export async function writeQaGateCompletionArtifact(config, gate, input) {
     const status = normalizeQaGateStatus(requiredString(payload, "status"));
     validateQaGatePayloadShape(gate, payload, status);
     validateOptionalWorkItemId(payload, config.workItemId);
-    const redactedPayload = redactSecrets({ ...payload, status }, config.redactionSecrets ?? []);
+    const ownerFields = artifactOwnerFields(config);
+    const validatedSidecars = gate === "qa_manual_web"
+        ? await validateQaSidecarReferences(config.worktreePath, config.workItemId, qaArray(payload, "sidecars", qaEvidenceSource(payload)), ownerFields.owner_type, ownerFields.owner_id)
+        : null;
+    const redactedPayload = redactSecrets({
+        ...payload,
+        status,
+        ...(validatedSidecars ? { sidecars: validatedSidecars } : {})
+    }, config.redactionSecrets ?? []);
     const producedBy = optionalString(redactedPayload, "produced_by")
         ?? optionalString(redactedPayload, "producedBy")
         ?? config.producedBy
         ?? "forge-completion-tool";
-    const ownerFields = artifactOwnerFields(config);
     const artifactRoot = ownerFields.owner_type && ownerFields.owner_id
         ? artifactRootForOwner(config.worktreePath, ownerFields.owner_type, ownerFields.owner_id)
         : artifactRootFor(config.worktreePath, config.workItemId);

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

@@ -9,7 +9,8 @@ export type DebugCompletionPhase = "debug_repro" | "debug_root_cause" | "debug_f
 export type ArchitectCompletionPhase = "architect";
 export type DraftCompletionPhase = "draft";
 export type DecomposeCompletionPhase = "decompose";
-export type CompletionPhase = DevelopCompletionPhase | "qa" | DebugCompletionPhase | ArchitectCompletionPhase | DraftCompletionPhase | DecomposeCompletionPhase;
+export type CiRepairCompletionPhase = "ci_repair";
+export type CompletionPhase = DevelopCompletionPhase | "qa" | DebugCompletionPhase | ArchitectCompletionPhase | DraftCompletionPhase | DecomposeCompletionPhase | CiRepairCompletionPhase;
 export type QaCompletionGate = "qa_plan" | "qa_regression" | "qa_api" | "qa_manual_web" | "qa_bug_repro" | "qa_findings" | "qa_verdict";
 export type DraftCompletionGate = "draft_intent" | "draft_repo_context" | "draft_graph_context" | "draft_product_scope" | "draft_work_order_plan" | "draft_critic" | "draft_proposal";
 export type DecomposeCompletionGate = "decompose_subject_intake" | "decompose_context_review" | "decompose_breakdown_strategy" | "decompose_child_items" | "decompose_dependency_graph" | "decompose_critic" | "decompose_proposal";
@@ -25,6 +26,7 @@ export interface CompletionToolRuntimeOptions {
     readonly dispatch: RunOnceDispatchPacket;
     readonly worktree: WorktreeHandle;
     readonly phase?: CompletionPhase;
+    readonly runtimeEnvironment?: Readonly<Record<string, string>>;
 }
 export interface CompletionToolServerConfig {
     readonly worktreePath: string;
@@ -56,7 +58,7 @@ export interface CompletionToolCallResult {
             readonly allowed: boolean;
             readonly reason: string;
         };
-        readonly nextPhase: CompletionPhase | "dev_test_ready" | "qa_ready" | "sign_off_ready";
+        readonly nextPhase: CompletionPhase | "dev_test_ready" | "qa_ready" | "sign_off_ready" | "provider_checks_ready";
         readonly nextInstruction: string;
     };
 }

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

@@ -85,6 +85,9 @@ export function parseStrictCompletionPhase(value) {
     if (normalized === "decompose" || normalized === "decomposition" || normalized === "work_order_decomposition" || normalized === "feature_decomposition") {
         return "decompose";
     }
+    if (normalized === "ci_repair" || normalized === "pr_checks" || normalized === "repair_pr_checks") {
+        return "ci_repair";
+    }
     return null;
 }
 export function normalizeDebugCompletionPhase(value) {
@@ -156,6 +159,9 @@ export function phaseFromToolName(toolName) {
     if (normalized === "forge.complete_architect_plan" || normalized === "complete_architect_plan") {
         return "architect";
     }
+    if (normalized === "forge.complete_ci_repair" || normalized === "complete_ci_repair") {
+        return "ci_repair";
+    }
     if (draftGateFromToolName(toolName)) {
         return "draft";
     }
@@ -600,9 +606,22 @@ export async function readOptionalFile(filePath) {
 }
 export async function writeFileAtomic(filePath, content) {
     await fs.mkdir(path.dirname(filePath), { recursive: true });
-    const tempPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${process.pid}.${Date.now()}.tmp`);
+    const tempPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${process.pid}.${crypto.randomUUID()}.tmp`);
     await fs.writeFile(tempPath, content, "utf8");
-    await fs.rename(tempPath, filePath);
+    try {
+        await fs.rename(tempPath, filePath);
+    }
+    catch (error) {
+        if (process.platform !== "win32" || !isNodeError(error) || (error.code !== "EPERM" && error.code !== "EEXIST")) {
+            await fs.rm(tempPath, { force: true });
+            throw error;
+        }
+        // Windows rename does not reliably replace an existing destination. QA-cycle gates
+        // intentionally refresh canonical bundle files, so remove only the exact destination
+        // after the replacement temp file is durable, then complete the rename.
+        await fs.rm(filePath, { force: true });
+        await fs.rename(tempPath, filePath);
+    }
 }
 export function stableStringify(value) {
     return JSON.stringify(sortJson(value));
@@ -626,7 +645,12 @@ export function forgeBridgeCliBinPath() {
     return fileURLToPath(new URL("../cli/bin.js", import.meta.url));
 }
 export function tomlString(value) {
-    return JSON.stringify(value);
+    if (value.includes("'''")) {
+        throw new Error("Codex MCP configuration values cannot contain three consecutive apostrophes.");
+    }
+    // Codex config overrides pass through npm's PowerShell shim on Windows.
+    // Literal TOML strings survive that boundary; basic-string double quotes do not.
+    return `'''${value}'''`;
 }
 export function tomlStringArray(values) {
     return `[${values.map(tomlString).join(", ")}]`;

package/dist/session/phase-completion.js

@@ -195,6 +195,10 @@ export const phaseFiles = {
     decompose: {
         jsonFileName: "decompose.proposal.json",
         reportFileName: "decompose.report.md"
+    },
+    ci_repair: {
+        jsonFileName: "ci-repair.handoff.json",
+        reportFileName: "ci-repair.report.md"
     }
 };
 export function completionPhaseFromDispatch(dispatch) {
@@ -224,6 +228,9 @@ export function normalizeCompletionPhase(value) {
     if (normalized === "decompose" || normalized === "decomposition" || normalized === "work_order_decomposition" || normalized === "feature_decomposition") {
         return "decompose";
     }
+    if (normalized === "ci_repair" || normalized === "pr_checks" || normalized === "repair_pr_checks") {
+        return "ci_repair";
+    }
     return "implementation";
 }
 export function usesDevelopCycleCompletion(dispatch) {
@@ -275,9 +282,11 @@ export function completionToolNamesForPhase(phase) {
             ? "complete_self_review"
             : phase === "validation"
                 ? "complete_validation"
-                : phase === "architect"
-                    ? "complete_architect_plan"
-                    : "complete_qa";
+                : phase === "ci_repair"
+                    ? "complete_ci_repair"
+                    : phase === "architect"
+                        ? "complete_architect_plan"
+                        : "complete_qa";
     return [`forge.${base}`, base];
 }
 export function completionToolNamesForQaGate(gate) {

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

@@ -1,13 +1,13 @@
 import { type CompletionPhase, type DebugCompletionPhase, type DecomposeCompletionGate, type DevelopCompletionPhase, type DraftCompletionGate, type QaCompletionGate } from "./phase-completion.js";
-export declare function completionPromptForPhase(phase: CompletionPhase): string;
+export declare function completionPromptForPhase(phase: CompletionPhase, artifactRoot?: string): string;
 export declare function completionPromptForDevelopCycle(phase: CompletionPhase): string;
-export declare function completionPromptForQaCycle(currentGate?: QaCompletionGate): string;
+export declare function completionPromptForQaCycle(currentGate?: QaCompletionGate, artifactRoot?: string): string;
 export declare function completionPromptForDraftCycle(currentGate?: DraftCompletionGate): string;
 export declare function completionPromptForDecomposeCycle(currentGate?: DecomposeCompletionGate): string;
 export declare function completionPromptForDebugCycle(currentGate?: DebugCompletionPhase): string;
 export declare function nextPhaseAfter(phase: CompletionPhase): DevelopCompletionPhase | null;
 export declare function nextDebugPhaseAfter(phase: DebugCompletionPhase): DebugCompletionPhase | null;
-export declare function completionToolNextInstruction(completedPhase: CompletionPhase, status: string, nextPhase: CompletionPhase | "dev_test_ready" | "qa_ready" | "sign_off_ready"): string;
+export declare function completionToolNextInstruction(completedPhase: CompletionPhase, status: string, nextPhase: CompletionPhase | "dev_test_ready" | "qa_ready" | "sign_off_ready" | "provider_checks_ready"): string;
 export declare function completionToolNextInstructionForDraftGate(completedGate: DraftCompletionGate, status: string, nextGate: DraftCompletionGate | null): string;
 export declare function completionToolNextInstructionForQaGate(completedGate: QaCompletionGate, status: string, nextGate: QaCompletionGate | null): string;
 export declare function completionToolNextInstructionForDecomposeGate(completedGate: DecomposeCompletionGate, status: string, nextGate: DecomposeCompletionGate | null): string;

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

@@ -1,13 +1,13 @@
 import { completionPhaseOrder, completionToolNamesForPhase, debugCompletionPhaseOrder, expectedCompletionToolName, expectedDebugCompletionToolName, expectedDecomposeCompletionToolName, phaseFiles, toolServerName } from "./phase-completion.js";
 import { isDebugCompletionPhase, isDevelopCompletionPhase } from "./phase-completion.validation.js";
-export function completionPromptForPhase(phase) {
+export function completionPromptForPhase(phase, artifactRoot = ".forge/work-items/{workItemId}/artifacts") {
     const toolName = expectedCompletionToolName(phase);
     const alias = completionToolNamesForPhase(phase).find((name) => name !== toolName);
     const artifactName = phaseFiles[phase].jsonFileName;
     if (phase === "qa") {
         return `Forge completion tools are available through the MCP server named \`${toolServerName}\`.
 Do not write QA artifacts by hand. When QA is complete, call \`${toolName}(...)\`${alias ? ` (or \`${alias}\` if your client shows unqualified MCP tool names)` : ""} with the required structured QA payload.
-That tool writes the durable QA bundle under \`.forge/work-items/{workItemId}/artifacts/\`: \`qa.plan.json\`, \`qa.evidence.json\`, \`qa.findings.json\`, \`${artifactName}\`, and \`qa.report.md\`.
+That tool writes the durable QA bundle under \`${artifactRoot}/\`: \`qa.plan.json\`, \`qa.evidence.json\`, \`qa.findings.json\`, \`${artifactName}\`, and \`qa.report.md\`.
 Use \`status: "pass"\` only when the validated changes satisfy acceptance criteria with concrete evidence. Use \`status: "needs_rework"\` with actionable in-scope findings, or \`status: "blocked"\` with a concrete blocker_reason.
 Include \`policy_warnings\` for non-blocking Forge policy or scope mismatches that should remain visible after QA.
 Forge will mirror only the tool-written QA artifacts; reporting QA completion in prose is not enough.`;
@@ -22,6 +22,14 @@ The payload must put \`phases\`, \`tasks\`, \`dependencies\`, and \`phase_gates\
 Dependency entries use canonical \`before\` and \`after\` task ids, for example \`{ "before": "task-1", "after": "task-2" }\`. Forge accepts \`from\`/\`to\` only as aliases and normalizes them before writing artifacts.
 Use \`status: "pass"\` for a valid pending-approval plan, \`needs_revision\` when story/design input must change, or \`blocked\` with a concrete blocker.
 Forge will mirror only the tool-written Architect artifacts; reporting the plan in prose is not enough.`;
+    }
+    if (phase === "ci_repair") {
+        return `Forge completion tools are available through the MCP server named \`${toolServerName}\`.
+Read the generated \`.forge/work-items/{workItemId}/ci-repair.readiness.json\` before running validation.
+Do not write the CI-repair handoff by hand. After the repair and locally equivalent validation are complete, call \`${toolName}(...)\`${alias ? ` (or \`${alias}\` if your client shows unqualified MCP tool names)` : ""}.
+That tool validates failed-check inspection, root cause, scoped changes, narrow proof, every failed-job guard/test/drift step, provider-only classifications, broader validation, remaining risk, provider state, and push readiness.
+It writes \`.forge/work-items/{workItemId}/artifacts/${artifactName}\`. Forge Bridge will not commit, push, or report CI repair success until this gate passes.
+For a step classified \`provider_only\`, include the exact reason and provider check that will supply the missing proof. Do not weaken or delete the provider check.`;
     }
     return `Forge completion tools are available through the MCP server named \`${toolServerName}\`.
 Do not write phase artifacts by hand. When the phase is complete, call \`${toolName}(...)\`${alias ? ` (or \`${alias}\` if your client shows unqualified MCP tool names)` : ""} with the required evidence payload.
@@ -38,7 +46,7 @@ Complete the dev cycle in order inside this same provider session:
 Each tool writes the canonical artifact under \`.forge/work-items/{workItemId}/artifacts/\` and returns the next-phase instruction Forge expects you to follow.
 If the current phase cannot pass, call the current phase tool with a non-pass status and explicit blockers instead of reporting completion in prose only.`;
 }
-export function completionPromptForQaCycle(currentGate = "qa_plan") {
+export function completionPromptForQaCycle(currentGate = "qa_plan", artifactRoot = ".forge/work-items/{workItemId}/artifacts") {
     return `Forge completion tools are available through the MCP server named \`${toolServerName}\`.
 Do not write QA artifacts by hand. The tool server enforces QA gate order and starts this run at \`${currentGate}\`.
 Complete the QA cycle in order inside this same provider session:
@@ -50,7 +58,8 @@ Complete the QA cycle in order inside this same provider session:
 6. Follow the returned findings instruction, then call \`forge.complete_qa_findings(...)\`.
 7. Follow the returned verdict instruction, then call \`forge.complete_qa_verdict(...)\`.
 Use \`status: "skipped"\` with a reason for gates that are not applicable. If a gate is blocked, keep moving through later gates as skipped due to the blocker and finish with a blocked verdict.
-The final verdict tool writes the canonical QA bundle under \`.forge/work-items/{workItemId}/artifacts/\`: \`qa.plan.json\`, \`qa.evidence.json\`, \`qa.findings.json\`, \`qa.verdict.json\`, and \`qa.report.md\`.
+On a managed host, start solution-wide \`dotnet test Forge.sln\` evidence through \`forge.start_managed_command\` with at least a 45-minute timeout, poll \`forge.get_managed_command\` until it returns a terminal receipt, and include the returned \`managed_command_id\` in its command evidence. The regression gate rejects generic-shell timeouts and non-terminal receipts for that command.
+The final verdict tool writes the canonical QA bundle under \`${artifactRoot}/\`: \`qa.plan.json\`, \`qa.evidence.json\`, \`qa.findings.json\`, \`qa.verdict.json\`, and \`qa.report.md\`.
 Include \`policy_warnings\` in the final verdict for non-blocking Forge policy or scope mismatches that should remain visible after QA.
 The legacy \`forge.complete_qa\` one-shot tool is not available in normal QA-cycle mode. Reporting QA completion in prose is not enough.`;
 }
@@ -115,6 +124,11 @@ export function completionToolNextInstruction(completedPhase, status, nextPhase)
         }
         return "QA accepted. Forge has the structured evidence needed to move this work item to Sign-Off.";
     }
+    if (completedPhase === "ci_repair") {
+        return status === "pass"
+            ? "CI repair handoff accepted. Forge Bridge may now commit, push, and return the PR to provider checks."
+            : "Stay in CI repair, address the exact missing evidence returned by this gate, then call forge.complete_ci_repair again.";
+    }
     if (status !== "pass") {
         return `Stay in ${completedPhase}, address the recorded blockers, then call ${expectedCompletionToolName(completedPhase)} again.`;
     }
@@ -203,7 +217,7 @@ export function completionToolNextInstructionForDebugGate(completedGate, status,
 function qaGateInstruction(gate) {
     switch (gate) {
         case "qa_regression":
-            return "Run or explicitly skip applicable regression/build/lint/typecheck/e2e checks, then call forge.complete_qa_regression.";
+            return "Run or explicitly skip applicable regression/build/lint/typecheck/e2e checks, then call forge.complete_qa_regression. On a managed host, start solution-wide dotnet test Forge.sln with forge.start_managed_command using at least a 45-minute timeout, poll forge.get_managed_command to a terminal receipt, and include its managed_command_id in the command evidence. A reproduced failure outside the current diff and acceptance criteria may remain non-blocking only when the current item has independent passing evidence: preserve it as an out_of_scope_failure with candidate_bug_id, scope_evidence, acceptance_criteria_independent: true, and a failing focused repro command/exit code. Never classify an unexplained, in-scope, or infrastructure failure this way.";
         case "qa_api":
             return "Run or explicitly skip applicable API/backend contract checks, then call forge.complete_qa_api.";
         case "qa_manual_web":

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

@@ -1,4 +1,5 @@
 import { type CompletionToolCallResult, type CompletionToolRuntime, type CompletionToolRuntimeOptions, type CompletionToolServerConfig } from "./phase-completion.js";
+import { type ManagedAttemptToolResult } from "./managed-attempt-tools.js";
 export declare function prepareCompletionToolRuntime(options: CompletionToolRuntimeOptions): Promise<CompletionToolRuntime>;
 export declare function buildCompletionToolServerArgs(config: CompletionToolServerConfig): readonly string[];
 export declare function codexMcpConfigArgs(runtime: CompletionToolRuntime): readonly string[];
@@ -10,11 +11,12 @@ export declare class CompletionToolServerSession {
     private currentQaGate;
     private currentDraftGate;
     private currentDecomposeGate;
+    private readonly managedCommandReceipts;
     private completed;
     constructor(config: CompletionToolServerConfig);
     get instructions(): string;
     toolDefinitions(): readonly unknown[];
-    callTool(toolName: string, input: unknown): Promise<CompletionToolCallResult>;
+    callTool(toolName: string, input: unknown): Promise<CompletionToolCallResult | ManagedAttemptToolResult>;
     private callDecomposeGateTool;
     private callDraftGateTool;
     private callDebugGateTool;
@@ -25,6 +27,15 @@ export declare class CompletionToolServerSession {
     private advanceAfterQaGate;
     private advanceAfterDebugGate;
 }
+export declare function completionToolRuntimeEnvironment(runtimeEnvironment?: Readonly<Record<string, string>>): Readonly<Record<string, string>>;
+/**
+ * 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 declare function assertManagedQaRegressionEvidence(input: unknown, receipts: readonly Readonly<Record<string, unknown>>[]): void;
 export declare function runCompletionMcpServer(config: CompletionToolServerConfig): Promise<void>;
 export declare function parseCompletionMcpArgs(argv: readonly string[]): {
     readonly ok: true;