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

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

@@ -1,10 +1,11 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { completionPhaseFromDispatch, completionPhaseOrder, completionRedactionSecretsEnv, completionToolNamesForDebugGate, completionToolNamesForDecomposeGate, completionToolNamesForDraftGate, completionToolNamesForPhase, completionToolNamesForQaGate, debugCompletionPhaseOrder, decomposeCompletionGateOrder, draftCompletionGateOrder, qaCompletionGateOrder, toolServerName, usesArchitectCycleCompletion, usesDebugCycleCompletion, usesDevelopCycleCompletion, usesQaCycleCompletion } from "./phase-completion.js";
-import { asDebugCompletionPhase, asJsonRpcMessage, asMutableRecord, asRecord, 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 { 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 { 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);
@@ -32,7 +33,7 @@ export async function prepareCompletionToolRuntime(options) {
         serverName: toolServerName,
         command: process.execPath,
         args: [forgeBridgeCliBinPath(), ...mcpArgs],
-        env: {},
+        env: completionToolRuntimeEnvironment(options.runtimeEnvironment),
         cleanup: async () => undefined
     };
     if (options.dispatch.execution.provider.trim().toLowerCase() !== "cursor") {
@@ -82,7 +83,9 @@ export function codexMcpConfigArgs(runtime) {
         "-c",
         `${prefix}.command=${tomlString(runtime.command)}`,
         "-c",
-        `${prefix}.args=${tomlStringArray(runtime.args)}`
+        `${prefix}.args=${tomlStringArray(runtime.args)}`,
+        "-c",
+        `${prefix}.default_tools_approval_mode=${tomlString("approve")}`
     ];
     for (const [key, value] of Object.entries(runtime.env)) {
         args.push("-c", `${prefix}.env.${key}=${tomlString(value)}`);
@@ -117,6 +120,7 @@ export class CompletionToolServerSession {
     currentQaGate = "qa_plan";
     currentDraftGate = "draft_intent";
     currentDecomposeGate = "decompose_subject_intake";
+    managedCommandReceipts = [];
     completed = false;
     constructor(config) {
         this.config = config;
@@ -130,15 +134,28 @@ export class CompletionToolServerSession {
                 : this.config.debugCycle
                     ? completionPromptForDebugCycle(asDebugCompletionPhase(this.currentPhase))
                     : this.config.qaCycle
-                        ? completionPromptForQaCycle(this.currentQaGate)
+                        ? completionPromptForQaCycle(this.currentQaGate, artifactOwnerRelativeRoot(this.config.ownerType, this.config.ownerId, this.config.workItemId))
                         : this.config.developCycle
                             ? completionPromptForDevelopCycle(this.currentPhase)
-                            : completionPromptForPhase(this.currentPhase);
+                            : completionPromptForPhase(this.currentPhase, artifactOwnerRelativeRoot(this.config.ownerType, this.config.ownerId, this.config.workItemId));
     }
     toolDefinitions() {
-        return completionToolNamesForServer(this.config).map((name) => toolDefinition(name, phaseFromToolName(name), qaGateFromToolName(name), decomposeGateFromToolName(name)));
+        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.");
@@ -292,6 +309,9 @@ export class CompletionToolServerSession {
             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);
@@ -327,6 +347,10 @@ export class CompletionToolServerSession {
             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";
         }
@@ -382,6 +406,102 @@ export class CompletionToolServerSession {
         return null;
     }
 }
+const completionToolRuntimeEnvironmentNames = [
+    "FORGE_RUNTIME_MODE",
+    "FORGE_RESOURCE_LEASE_ID",
+    "FORGE_DISPATCH_ATTEMPT_ID",
+    "FORGE_LOG_DIR",
+    "FORGE_TEST_OUTPUT_DIR",
+    "FORGE_TMPDIR",
+    "TMPDIR",
+    "TMP",
+    "TEMP",
+];
+export function completionToolRuntimeEnvironment(runtimeEnvironment) {
+    if (!runtimeEnvironment)
+        return {};
+    const env = {};
+    for (const name of completionToolRuntimeEnvironmentNames) {
+        const value = runtimeEnvironment[name]?.trim();
+        if (value)
+            env[name] = value;
+    }
+    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, poll forge.get_managed_command to a terminal receipt, and include the returned 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, poll forge.get_managed_command to a terminal receipt, and include its matching 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. `
+                + "Poll forge.get_managed_command until the status is terminal, then resubmit this gate.");
+        }
+        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");
@@ -437,7 +557,7 @@ export function parseCompletionMcpArgs(argv) {
             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, debug-repro, debug-root-cause, debug-fix, debug-regression." };
+                return { ok: false, error: "mcp --phase must be one of: implementation, self-review, validation, qa, architect, draft, decompose, ci-repair, debug-repro, debug-root-cause, debug-fix, debug-regression." };
             }
             phase = parsedPhase;
         }

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

@@ -16,6 +16,9 @@ export function toolDescription(phase, qaGate = null, decomposeGate = null) {
     if (phase === "implementation") {
         return "Complete Forge implementation by writing implementation.completeness.json with scoped changed-file, verification, acceptance-criteria, gap, and next-phase evidence.";
     }
+    if (phase === "ci_repair") {
+        return "Complete Forge CI repair by writing ci-repair.handoff.json with failed-check, root-cause, scoped-change, workflow-equivalence, validation, provider-state, and push-readiness evidence.";
+    }
     if (phase === "self_review") {
         return "Complete Forge self-review by writing self-review.report.json with diff review, findings, security, edge-case, design, deterministic-comparison, fixes, and remaining-risk evidence.";
     }
@@ -55,6 +58,94 @@ export function toolInputSchema(phase, qaGate = null, decomposeGate = null) {
     if (isDebugCompletionPhase(phase)) {
         return debugToolInputSchema(phase, baseProperties);
     }
+    if (phase === "ci_repair") {
+        return objectToolSchema({
+            ...baseProperties,
+            failed_checks: {
+                type: "array",
+                description: "Required and non-empty for pass. Provider check/job/step evidence inspected before repair.",
+                items: evidenceObjectSchema(["name", "provider_state"], {
+                    name: { type: "string" },
+                    provider_state: { type: "string" },
+                    workflow: { type: "string" },
+                    job: { type: "string" },
+                    step: { type: "string" },
+                    details_url: { type: "string" },
+                    evidence: { type: "string" }
+                })
+            },
+            root_cause: {
+                type: "object",
+                description: "Required for pass. Include classification, summary, and concrete evidence.",
+                additionalProperties: true,
+                properties: {
+                    classification: { type: "string" },
+                    summary: { type: "string" },
+                    evidence: { type: "array", items: { type: "string" } }
+                }
+            },
+            changed_files: {
+                type: "array",
+                description: "Files changed by the repair. May be empty only when no_code_action explains the provider-only action or blocker.",
+                items: evidenceObjectSchema(["path", "summary"], {
+                    path: { type: "string" },
+                    summary: { type: "string" }
+                })
+            },
+            no_code_action: {
+                type: "object",
+                description: "Required when changed_files is empty. Describe the evidence-backed provider action or blocker.",
+                additionalProperties: true,
+                properties: {
+                    action: { type: "string" },
+                    reason: { type: "string" },
+                    evidence: { type: "string" }
+                }
+            },
+            narrow_validation: {
+                type: "array",
+                description: "Required and non-empty for pass. The focused failing command or evidence-backed substitute.",
+                items: commandEvidenceSchema()
+            },
+            workflow_validation: {
+                type: "array",
+                description: "Required and non-empty for pass. Each failed-job guard/test/drift step with local equivalence supported, substitute, or provider_only.",
+                items: evidenceObjectSchema(["step", "equivalence", "status"], {
+                    step: { type: "string" },
+                    equivalence: { type: "string", enum: ["supported", "substitute", "provider_only"] },
+                    command: { type: "string" },
+                    exit_code: { type: "number" },
+                    status: { type: "string" },
+                    summary: { type: "string" },
+                    reason: { type: "string" },
+                    substitute: { type: "string" }
+                })
+            },
+            broader_validation: {
+                type: "array",
+                description: "Required and non-empty for pass. Normal validation covering every touched compiled/tested surface.",
+                items: commandEvidenceSchema()
+            },
+            remaining_risks: {
+                type: "array",
+                description: "Required for pass, even when empty.",
+                items: evidenceObjectSchema(["summary"], {
+                    summary: { type: "string" },
+                    mitigation: { type: "string" },
+                    owner: { type: "string" }
+                })
+            },
+            provider_state: {
+                type: "string",
+                enum: ["ready_for_rerun", "rerun_requested", "checks_pending", "still_failing", "blocked_by_provider"],
+                description: "Provider state after local validation and before Forge-owned publication."
+            },
+            ready_for_push: {
+                type: "boolean",
+                description: "Required for pass and must be true. Forge Bridge performs the commit/push only after this gate passes."
+            }
+        }, ["status", "summary"], "For status pass, include failed_checks, root_cause, changed_files or no_code_action, narrow_validation, workflow_validation, broader_validation, remaining_risks, provider_state, and ready_for_push: true.");
+    }
     if (phase === "implementation") {
         return objectToolSchema({
             ...baseProperties,
@@ -198,7 +289,7 @@ export function toolInputSchema(phase, qaGate = null, decomposeGate = null) {
             },
             sidecars: {
                 type: "array",
-                description: "Optional QA sidecar files already written under .forge/work-items/<id>/artifacts/qa/ with path/content_hash/bytes metadata.",
+                description: "Optional QA sidecar files already written under the dispatch-provided QA artifacts path with path/content_hash/bytes metadata.",
                 items: evidenceObjectSchema(["path", "content_hash", "bytes"], {
                     path: { type: "string" },
                     content_hash: { type: "string" },
@@ -652,9 +743,23 @@ function qaScopeSchema(description) {
 function commandEvidenceSchema() {
     return evidenceObjectSchema(["command", "exit_code", "status", "summary"], {
         command: { type: "string" },
-        exit_code: { type: "number" },
+        managed_command_id: { type: "string", description: "Receipt ID returned by forge.start_managed_command and completed through forge.get_managed_command for managed-host evidence." },
+        exit_code: { type: ["number", "null"], description: "Process exit code, or null when the managed runner timed out or could not launch the process." },
         status: { type: "string" },
-        summary: { type: "string" }
+        summary: { type: "string" },
+        classification: {
+            type: "string",
+            enum: ["out_of_scope_failure", "baseline_failure"],
+            description: "Only for a verified non-blocking failure in a passing QA regression gate. Never use for an in-scope or unexplained failure."
+        },
+        candidate_bug_id: { type: "string", description: "Required for a classified non-blocking failure; links the preserved failure to candidate_bugs." },
+        scope_evidence: { type: "string", description: "Required proof that the failing surface is outside the current acceptance criteria and changed-file scope." },
+        acceptance_criteria_independent: { type: "boolean", description: "Required and true only when the current item can be judged independently of this failure." },
+        repro_command: { type: "string", description: "Required for out_of_scope_failure; focused command that reproduced the unrelated failure." },
+        repro_exit_code: { type: "number", description: "Required non-zero focused repro exit code for out_of_scope_failure." },
+        baseline_ref: { type: "string", description: "Required for baseline_failure; immutable ref where the same failure was observed." },
+        baseline_exit_code: { type: "number", description: "Required non-zero baseline command exit code for baseline_failure." },
+        failure_signature_match: { type: "boolean", description: "Required and true for baseline_failure after matching failing test/error signatures." }
     });
 }
 function resolvedFindingSchema() {

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

@@ -2,9 +2,12 @@ import { type CompletionPhase, type DebugCompletionPhase, type QaCompletionGate
 export declare function normalizeCompletionStatus(value: string, phase?: CompletionPhase): string;
 export declare function normalizeQaGateStatus(value: string): string;
 export declare function validatePayloadShape(phase: CompletionPhase, payload: Record<string, unknown>): void;
+export declare function validateCiRepairPayloadShape(payload: Record<string, unknown>): void;
 export declare function validateDebugPayloadShape(phase: DebugCompletionPhase, payload: Record<string, unknown>): void;
 export declare function validateQaGatePayloadShape(gate: QaCompletionGate, payload: Record<string, unknown>, status: string): void;
-export declare function validateQaGatePassingCommands(commands: readonly unknown[]): void;
+export declare function validateQaGatePassingCommands(commands: readonly unknown[], options?: {
+    readonly allowClassifiedNonBlockingFailures?: boolean;
+}): void;
 export declare function validateArchitectPayloadShape(payload: Record<string, unknown>, status: string): void;
 export declare function validateArchitectTaskDevelopScope(task: Record<string, unknown>, taskId: string): void;
 export declare function validateArchitectVerificationScope(task: Record<string, unknown>, taskId: string): void;

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

@@ -51,6 +51,10 @@ export function validatePayloadShape(phase, payload) {
         requireNonPassEvidence(payload);
         return;
     }
+    if (phase === "ci_repair") {
+        validateCiRepairPayloadShape(payload);
+        return;
+    }
     if (isDebugCompletionPhase(phase)) {
         validateDebugPayloadShape(phase, payload);
         return;
@@ -97,6 +101,72 @@ export function validatePayloadShape(phase, payload) {
     requirePassingCommands(payload);
     requireSatisfiedAcceptanceCriteria(payload);
 }
+export function validateCiRepairPayloadShape(payload) {
+    requireArray(payload, "failed_checks");
+    requireNonEmptyArray(payload, "failed_checks");
+    for (const [index, failedCheck] of payload.failed_checks.entries()) {
+        requireEvidenceRecord(failedCheck, `failed_checks[${index}]`);
+        const record = failedCheck;
+        requireNonEmptyStringRecord(record, "name", `failed_checks[${index}].`);
+        requireNonEmptyStringRecord(record, "provider_state", `failed_checks[${index}].`);
+    }
+    requireObject(payload, "root_cause");
+    const rootCause = requiredRecord(payload, "root_cause");
+    requireNonEmptyStringRecord(rootCause, "classification", "root_cause.");
+    requireNonEmptyStringRecord(rootCause, "summary", "root_cause.");
+    requireNonEmptyStringArrayRecord(rootCause, "evidence", "root_cause.");
+    requireArray(payload, "changed_files");
+    if (arrayLength(payload, "changed_files") === 0) {
+        requireObject(payload, "no_code_action");
+        const noCodeAction = requiredRecord(payload, "no_code_action");
+        requireNonEmptyStringRecord(noCodeAction, "action", "no_code_action.");
+        requireNonEmptyStringRecord(noCodeAction, "reason", "no_code_action.");
+    }
+    else {
+        for (const [index, changedFile] of payload.changed_files.entries()) {
+            requireEvidenceRecord(changedFile, `changed_files[${index}]`);
+            const record = changedFile;
+            requireNonEmptyStringRecord(record, "path", `changed_files[${index}].`);
+            requireNonEmptyStringRecord(record, "summary", `changed_files[${index}].`);
+        }
+    }
+    for (const key of ["narrow_validation", "broader_validation"]) {
+        requireArray(payload, key);
+        requireNonEmptyArray(payload, key);
+        validateQaGatePassingCommands(payload[key]);
+    }
+    requireArray(payload, "workflow_validation");
+    requireNonEmptyArray(payload, "workflow_validation");
+    for (const [index, entry] of payload.workflow_validation.entries()) {
+        requireEvidenceRecord(entry, `workflow_validation[${index}]`);
+        const record = entry;
+        requireNonEmptyStringRecord(record, "step", `workflow_validation[${index}].`);
+        requireKnownStringRecord(record, "equivalence", new Set(["supported", "substitute", "provider_only"]), `workflow_validation[${index}].`);
+        requireNonEmptyStringRecord(record, "status", `workflow_validation[${index}].`);
+        const equivalence = normalizedString(optionalString(record, "equivalence"));
+        if (equivalence === "provider_only") {
+            requireNonEmptyStringRecord(record, "reason", `workflow_validation[${index}].`);
+            continue;
+        }
+        requireNonEmptyStringRecord(record, "command", `workflow_validation[${index}].`);
+        requireNonEmptyStringRecord(record, "summary", `workflow_validation[${index}].`);
+        if (typeof record.exit_code !== "number" || !Number.isFinite(record.exit_code)) {
+            throw new Error(`workflow_validation[${index}].exit_code is required for ${equivalence} evidence.`);
+        }
+        if (record.exit_code !== 0 || normalizedString(optionalString(record, "status")) !== "pass") {
+            throw new Error(`workflow_validation[${index}] must pass locally when equivalence is ${equivalence}.`);
+        }
+        if (equivalence === "substitute") {
+            requireNonEmptyStringRecord(record, "substitute", `workflow_validation[${index}].`);
+        }
+    }
+    requireArray(payload, "remaining_risks");
+    requireAllowedStatus(payload, "provider_state", ["ready_for_rerun", "rerun_requested", "checks_pending"]);
+    requireBoolean(payload, "ready_for_push");
+    if (payload.ready_for_push !== true) {
+        throw new Error("ci_repair pass requires ready_for_push: true.");
+    }
+}
 export function validateDebugPayloadShape(phase, payload) {
     if (phase === "debug_repro") {
         requireArray(payload, "repro_steps");
@@ -169,7 +239,9 @@ export function validateQaGatePayloadShape(gate, payload, status) {
         if (commands.length === 0) {
             throw new Error(`${qaGateToolNames[gate]} pass requires commands with at least one entry.`);
         }
-        validateQaGatePassingCommands(commands);
+        validateQaGatePassingCommands(commands, {
+            allowClassifiedNonBlockingFailures: gate === "qa_regression"
+        });
     }
     if (gate === "qa_manual_web" && status === "pass") {
         const browserChecks = qaArray(payload, "browser_checks");
@@ -179,7 +251,7 @@ export function validateQaGatePayloadShape(gate, payload, status) {
         }
     }
 }
-export function validateQaGatePassingCommands(commands) {
+export function validateQaGatePassingCommands(commands, options = {}) {
     for (const [index, command] of commands.entries()) {
         requireEvidenceRecord(command, `commands[${index}]`);
         const record = command;
@@ -189,6 +261,13 @@ export function validateQaGatePassingCommands(commands) {
         if (typeof record.exit_code !== "number" || !Number.isFinite(record.exit_code)) {
             throw new Error(`commands[${index}].exit_code is required.`);
         }
+        const passed = record.exit_code === 0 && normalizedString(record.status) === "pass";
+        if (!passed
+            && options.allowClassifiedNonBlockingFailures
+            && optionalString(record, "classification")) {
+            validateClassifiedNonBlockingQaFailure(record, index);
+            continue;
+        }
         if (record.exit_code !== 0) {
             throw new Error(`commands[${index}].exit_code must be 0 when QA gate status is pass.`);
         }
@@ -197,6 +276,31 @@ export function validateQaGatePassingCommands(commands) {
         }
     }
 }
+function validateClassifiedNonBlockingQaFailure(record, index) {
+    const classification = normalizedString(optionalString(record, "classification"));
+    if (classification !== "out_of_scope_failure" && classification !== "baseline_failure") {
+        throw new Error(`commands[${index}] is non-passing; QA regression pass requires classification out_of_scope_failure or baseline_failure with corroborating evidence.`);
+    }
+    requireNonEmptyStringRecord(record, "candidate_bug_id", `commands[${index}].`);
+    requireNonEmptyStringRecord(record, "scope_evidence", `commands[${index}].`);
+    if (record.acceptance_criteria_independent !== true) {
+        throw new Error(`commands[${index}].acceptance_criteria_independent must be true for a non-blocking QA regression failure.`);
+    }
+    if (classification === "out_of_scope_failure") {
+        requireNonEmptyStringRecord(record, "repro_command", `commands[${index}].`);
+        if (typeof record.repro_exit_code !== "number" || !Number.isFinite(record.repro_exit_code) || record.repro_exit_code === 0) {
+            throw new Error(`commands[${index}].repro_exit_code must be a non-zero number for an out-of-scope failure.`);
+        }
+        return;
+    }
+    requireNonEmptyStringRecord(record, "baseline_ref", `commands[${index}].`);
+    if (typeof record.baseline_exit_code !== "number" || !Number.isFinite(record.baseline_exit_code) || record.baseline_exit_code === 0) {
+        throw new Error(`commands[${index}].baseline_exit_code must be a non-zero number for a baseline failure.`);
+    }
+    if (record.failure_signature_match !== true) {
+        throw new Error(`commands[${index}].failure_signature_match must be true for a baseline failure.`);
+    }
+}
 export function validateArchitectPayloadShape(payload, status) {
     if (status !== "pass") {
         requireArchitectNonPassEvidence(payload);

package/dist/session/provider-cli/ci-repair-readiness.d.ts

@@ -0,0 +1,8 @@
+import type { RunOnceDispatchPacket } from "../session.types.js";
+export declare const ciRepairProviderOnlySpecs: readonly ["**/bridge-dispatch.spec.ts", "**/develop-agent-run.spec.ts", "**/runner-availability.spec.ts"];
+export interface CiRepairReadinessResult {
+    readonly path: string;
+    readonly environment: Readonly<Record<string, string>>;
+    readonly manifest: Readonly<Record<string, unknown>>;
+}
+export declare function writeCiRepairReadinessManifest(dispatch: RunOnceDispatchPacket, worktreePath: string, specPath: string, runtimeEnvironment: Readonly<Record<string, string>> | undefined): Promise<CiRepairReadinessResult>;

package/dist/session/provider-cli/ci-repair-readiness.js

@@ -0,0 +1,90 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+export const ciRepairProviderOnlySpecs = [
+    "**/bridge-dispatch.spec.ts",
+    "**/develop-agent-run.spec.ts",
+    "**/runner-availability.spec.ts",
+];
+export async function writeCiRepairReadinessManifest(dispatch, worktreePath, specPath, runtimeEnvironment) {
+    const metadataRoot = path.dirname(specPath);
+    const manifestPath = path.join(metadataRoot, "ci-repair.readiness.json");
+    const workflowPath = path.join(worktreePath, ".github", "workflows", "ci.yml");
+    const browserReady = runtimeEnvironment?.FORGE_PLAYWRIGHT_BROWSER_READY === "true";
+    const apiUrl = runtimeEnvironment?.FORGE_E2E_API_URL ?? runtimeEnvironment?.FORGE_API_URL ?? null;
+    const webUrl = runtimeEnvironment?.FORGE_E2E_WEB_URL
+        ?? runtimeEnvironment?.FORGE_WEB_URL
+        ?? runtimeEnvironment?.FORGE_PLAYWRIGHT_BASE_URL
+        ?? null;
+    const environment = {
+        ...(runtimeEnvironment ?? {}),
+        ...(apiUrl ? { FORGE_E2E_API_URL: apiUrl } : {}),
+        ...(webUrl ? { FORGE_E2E_WEB_URL: webUrl } : {}),
+        FORGE_CI_REPAIR_READINESS_PATH: manifestPath,
+        FORGE_CI_REPAIR_HANDOFF_PATH: path.join(metadataRoot, "artifacts", "ci-repair.handoff.json"),
+        FORGE_CI_REPAIR_PROVIDER_ONLY_SPECS: JSON.stringify(ciRepairProviderOnlySpecs),
+    };
+    const manifest = {
+        schema_version: 1,
+        generated_by: "forge-bridge",
+        work_item_id: dispatch.workItem.id,
+        session_id: dispatch.session.id,
+        spec: {
+            path: relativePath(worktreePath, specPath),
+            ready: await isFile(specPath),
+        },
+        handoff: {
+            path: relativePath(worktreePath, environment.FORGE_CI_REPAIR_HANDOFF_PATH),
+            completion_tool: "forge.complete_ci_repair",
+            required_before_commit_or_push: true,
+        },
+        pull_request: {
+            provider: dispatch.pullRequest?.provider ?? "unknown",
+            number: dispatch.pullRequest?.number ?? null,
+            url: dispatch.pullRequest?.url ?? null,
+            source_branch: dispatch.pullRequest?.sourceBranch ?? dispatch.cycleRun.baseBranch,
+            target_branch: dispatch.pullRequest?.targetBranch ?? dispatch.cycleRun.requestedBase,
+            check_state: dispatch.pullRequest?.checkState ?? "unknown",
+            required_checks_passed: dispatch.pullRequest?.requiredChecksPassed ?? 0,
+            required_checks_total: dispatch.pullRequest?.requiredChecksTotal ?? 0,
+            failed_job_discovery: "Inspect provider check runs and record exact job/step in the completion payload.",
+        },
+        workflow: {
+            path: relativePath(worktreePath, workflowPath),
+            ready: await isFile(workflowPath),
+            requirement: "Record the failed step and every earlier guard/drift step in workflow_validation.",
+        },
+        runtime: {
+            mode: runtimeEnvironment?.FORGE_RUNTIME_MODE ?? "unknown",
+            application_runtime_ready: Boolean(apiUrl || webUrl),
+            api_url: apiUrl,
+            web_url: webUrl,
+            playwright_config: runtimeEnvironment?.FORGE_PLAYWRIGHT_CONFIG ?? null,
+            playwright_browser_cache: runtimeEnvironment?.PLAYWRIGHT_BROWSERS_PATH ?? null,
+            playwright_browser_ready: browserReady,
+            playwright_browser_install_command: browserReady
+                ? null
+                : runtimeEnvironment?.FORGE_PLAYWRIGHT_BROWSER_INSTALL_COMMAND ?? "npx playwright install chromium",
+        },
+        local_equivalence: {
+            default: "supported",
+            nested_bridge: "provider_only",
+            provider_only_specs: ciRepairProviderOnlySpecs,
+            reason: "A managed Forge attempt cannot safely create a second Bridge/runner control plane inside itself. Provider CI remains authoritative for these specs.",
+            policy: "Do not delete, skip, or weaken provider CI coverage. Record provider_only steps in workflow_validation with this reason.",
+        },
+    };
+    await fs.mkdir(metadataRoot, { recursive: true });
+    await fs.writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    return { path: manifestPath, environment, manifest };
+}
+async function isFile(candidate) {
+    try {
+        return (await fs.stat(candidate)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function relativePath(worktreePath, candidate) {
+    return path.relative(worktreePath, candidate).replaceAll(path.sep, "/");
+}

package/dist/session/provider-cli/provider-cli.artifacts.d.ts

@@ -18,7 +18,7 @@ export declare function isDebugCompletionPhaseForProvider(phase: CompletionPhase
 export declare function emitQaArtifactRecorded(emit: ProviderCliRunContext["emit"], worktreePath: string, artifact: RunnerDispatchArtifact): Promise<void>;
 export declare function readQaCompletionArtifactBundle(worktreePath: string, workItemId: string, ownerType?: string | null, ownerId?: string | null): Promise<RunnerDispatchArtifact | null>;
 export declare function hasCompleteQaArtifactBundle(worktreePath: string, workItemId: string, ownerType?: string | null, ownerId?: string | null): Promise<boolean>;
-export declare function enforceQaBrowserLaunchTargetGate(dispatch: RunOnceDispatchPacket, artifact: RunnerDispatchArtifact): void;
+export declare function enforceQaBrowserLaunchTargetGate(dispatch: RunOnceDispatchPacket, artifact: RunnerDispatchArtifact): Promise<void>;
 export declare function validateQaBundleSidecarReferences(worktreePath: string, workItemId: string, ownerType?: string | null, ownerId?: string | null): Promise<void>;
 export declare function emitQaStructuredEvents(emit: ProviderCliRunContext["emit"], artifact: RunnerDispatchArtifact): Promise<void>;
 interface QaGateArtifactSnapshot {