@loucompanion/forge-bridge 0.1.3-dev.8777774c67bc → 0.1.3-dev.88e93f53db5b

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,23 +251,69 @@ export function validateQaGatePayloadShape(gate, payload, status) {
         }
     }
 }
-export function validateQaGatePassingCommands(commands) {
+export function validateQaGatePassingCommands(commands, options = {}) {
+    const issues = [];
     for (const [index, command] of commands.entries()) {
-        requireEvidenceRecord(command, `commands[${index}]`);
+        if (!command || typeof command !== "object" || Array.isArray(command)) {
+            issues.push(`commands[${index}] must be an object.`);
+            continue;
+        }
         const record = command;
-        requireNonEmptyStringRecord(record, "command", `commands[${index}].`);
-        requireNonEmptyStringRecord(record, "status", `commands[${index}].`);
-        requireNonEmptyStringRecord(record, "summary", `commands[${index}].`);
+        if (!optionalString(record, "command"))
+            issues.push(`commands[${index}].command is required.`);
+        if (!optionalString(record, "status"))
+            issues.push(`commands[${index}].status is required.`);
+        if (!optionalString(record, "summary"))
+            issues.push(`commands[${index}].summary is required.`);
         if (typeof record.exit_code !== "number" || !Number.isFinite(record.exit_code)) {
-            throw new Error(`commands[${index}].exit_code is required.`);
+            issues.push(`commands[${index}].exit_code is required.`);
+            continue;
+        }
+        const passed = record.exit_code === 0 && normalizedString(record.status) === "pass";
+        if (!passed
+            && options.allowClassifiedNonBlockingFailures
+            && optionalString(record, "classification")) {
+            try {
+                validateClassifiedNonBlockingQaFailure(record, index);
+            }
+            catch (error) {
+                issues.push(error instanceof Error ? error.message : String(error));
+            }
+            continue;
         }
         if (record.exit_code !== 0) {
-            throw new Error(`commands[${index}].exit_code must be 0 when QA gate status is pass.`);
+            issues.push(`commands[${index}].exit_code must be 0 when QA gate status is pass.`);
         }
         if (normalizedString(record.status) !== "pass") {
-            throw new Error(`commands[${index}].status must be pass when QA gate status is pass.`);
+            issues.push(`commands[${index}].status must be pass when QA gate status is pass.`);
         }
     }
+    throwCompletionPayloadIssues(issues);
+}
+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") {
@@ -214,18 +332,22 @@ export function validateArchitectPayloadShape(payload, status) {
         throw new Error("implementation_plan.tasks: expected non-empty array; correction: include at least one task with id and tests.");
     }
     const taskIds = new Set();
-    for (const task of implementationPlan.tasks) {
+    const taskIndexById = new Map();
+    for (const [taskIndex, task] of implementationPlan.tasks.entries()) {
         if (!task || typeof task !== "object" || Array.isArray(task)) {
             throw new Error("implementation_plan.tasks[]: expected object entries; correction: each task must be an object with id and tests.");
         }
         const taskRecord = task;
         requireNonEmptyStringRecord(taskRecord, "id", "implementation_plan.tasks[].");
         const taskId = optionalString(taskRecord, "id") ?? "";
-        if (taskIds.has(taskId)) {
-            throw new Error(`implementation_plan.tasks: duplicate task id '${taskId}'.`);
+        const firstTaskIndex = taskIndexById.get(taskId);
+        if (firstTaskIndex !== undefined) {
+            throw new Error(`implementation_plan.tasks[${taskIndex}].id duplicates implementation_plan.tasks[${firstTaskIndex}].id '${taskId}'; correction: assign the duplicate a unique stable task id, update every phase/dependency reference to that task, and resubmit forge.complete_architect_plan.`);
         }
         taskIds.add(taskId);
+        taskIndexById.set(taskId, taskIndex);
         validateArchitectTaskDevelopScope(taskRecord, taskId);
+        requireNonEmptyStringArrayRecord(taskRecord, "acceptance_criteria", `implementation_plan.tasks[${taskId}].`);
         validateArchitectVerificationScope(taskRecord, taskId);
         requireArchitectArray(taskRecord, "tests", payload, { path: `implementation_plan.tasks[${optionalString(taskRecord, "id") ?? "?"}].tests` });
         if (arrayLength(taskRecord, "tests") === 0) {
@@ -611,22 +733,30 @@ export function validateQaPayloadShape(payload, status) {
             throw new Error("QA pass/needs_rework requires at least one command, browser check, or evidence note.");
         }
     }
+    const commandIssues = [];
     for (const [index, command] of commands.entries()) {
-        requireEvidenceRecord(command, `commands[${index}]`);
+        if (!command || typeof command !== "object" || Array.isArray(command)) {
+            commandIssues.push(`commands[${index}] must be an object.`);
+            continue;
+        }
         const record = command;
-        requireNonEmptyStringRecord(record, "command", `commands[${index}].`);
-        requireNonEmptyStringRecord(record, "status", `commands[${index}].`);
-        requireNonEmptyStringRecord(record, "summary", `commands[${index}].`);
+        if (!optionalString(record, "command"))
+            commandIssues.push(`commands[${index}].command is required.`);
+        if (!optionalString(record, "status"))
+            commandIssues.push(`commands[${index}].status is required.`);
+        if (!optionalString(record, "summary"))
+            commandIssues.push(`commands[${index}].summary is required.`);
         if (typeof record.exit_code !== "number" || !Number.isFinite(record.exit_code)) {
-            throw new Error(`commands[${index}].exit_code is required.`);
+            commandIssues.push(`commands[${index}].exit_code is required.`);
         }
-        if (status === "pass" && record.exit_code !== 0) {
-            throw new Error(`commands[${index}].exit_code must be 0 when QA status is pass.`);
+        else if (status === "pass" && record.exit_code !== 0) {
+            commandIssues.push(`commands[${index}].exit_code must be 0 when QA status is pass.`);
         }
         if (status === "pass" && normalizedString(record.status) !== "pass") {
-            throw new Error(`commands[${index}].status must be pass when QA status is pass.`);
+            commandIssues.push(`commands[${index}].status must be pass when QA status is pass.`);
         }
     }
+    throwCompletionPayloadIssues(commandIssues);
     for (const [index, browserCheck] of browserChecks.entries()) {
         requireEvidenceRecord(browserCheck, `browser_checks[${index}]`);
         const record = browserCheck;
@@ -720,5 +850,5 @@ export function validateOptionalWorkItemId(payload, expectedWorkItemId) {
         throw new Error(`completion payload work item ${actual} does not match dispatch work item ${expectedWorkItemId}.`);
     }
 }
-import { requireField, requireNonPassEvidence, requireImplementationEvidence, requirePassingCommands, requireArray, requireNonEmptyArray, arrayLength, requireAllowedStatus, requireObject, requiredRecord, requireBoolean, requireNumericOne, requireSatisfiedAcceptanceCriteria, validateResolvedFindings, isDebugCompletionPhase, qaEvidenceSource, qaArray, qaObjectArray, qaPolicyWarnings, qaStringArray, requireEvidenceRecord, requireNonEmptyStringRecord, requireKnownStringRecord, requireNonEmptyStringArrayRecord, requireSubstantiveEvidenceRecord, normalizedString, requiredString, optionalString, stripUndefined, } from "./phase-completion.helpers.js";
+import { requireField, requireNonPassEvidence, requireImplementationEvidence, requirePassingCommands, requireArray, requireNonEmptyArray, arrayLength, requireAllowedStatus, requireObject, requiredRecord, requireBoolean, requireNumericOne, requireSatisfiedAcceptanceCriteria, validateResolvedFindings, isDebugCompletionPhase, qaEvidenceSource, qaArray, qaObjectArray, qaPolicyWarnings, qaStringArray, requireEvidenceRecord, requireNonEmptyStringRecord, requireKnownStringRecord, requireNonEmptyStringArrayRecord, requireSubstantiveEvidenceRecord, normalizedString, requiredString, optionalString, stripUndefined, throwCompletionPayloadIssues, } from "./phase-completion.helpers.js";
 export * from "./phase-completion.helpers.js";

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

@@ -0,0 +1,14 @@
+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 declare const ciRepairLocalPreflightCommands: readonly [{
+    readonly id: "bridge-dispatch-without-nested-control-plane";
+    readonly cwd: "tests/e2e";
+    readonly command: readonly ["pnpm", "exec", "playwright", "test", "specs/bridge-dispatch.spec.ts", "--grep-invert", "online bridge completes a newly created task"];
+    readonly coverage: "Runs Bridge API/setup, offline recovery, CSRF, and repo-root approval coverage while excluding only the nested live Bridge process.";
+}];
+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,105 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createHash } from "node:crypto";
+export const ciRepairProviderOnlySpecs = [
+    "**/bridge-dispatch.spec.ts",
+    "**/develop-agent-run.spec.ts",
+    "**/runner-availability.spec.ts",
+];
+export const ciRepairLocalPreflightCommands = [{
+        id: "bridge-dispatch-without-nested-control-plane",
+        cwd: "tests/e2e",
+        command: [
+            "pnpm", "exec", "playwright", "test", "specs/bridge-dispatch.spec.ts",
+            "--grep-invert", "online bridge completes a newly created task",
+        ],
+        coverage: "Runs Bridge API/setup, offline recovery, CSRF, and repo-root approval coverage while excluding only the nested live Bridge process.",
+    }];
+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 providerOnlySpecsJson = JSON.stringify(ciRepairProviderOnlySpecs);
+    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: providerOnlySpecsJson,
+    };
+    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",
+            attempt_database_schema: runtimeEnvironment?.FORGE_ATTEMPT_DATABASE_SCHEMA ?? null,
+            attempt_database_readiness_path: runtimeEnvironment?.FORGE_ATTEMPT_DATABASE_READINESS_PATH ?? null,
+        },
+        local_equivalence: {
+            default: "supported",
+            nested_bridge: "provider_only",
+            provider_only_specs: ciRepairProviderOnlySpecs,
+            provider_only_specs_fingerprint: `sha256:${createHash("sha256").update(providerOnlySpecsJson).digest("hex")}`,
+            local_preflight_commands: ciRepairLocalPreflightCommands,
+            reason: "A managed Forge attempt cannot safely create a second Bridge/runner control plane inside itself. Only cases that launch a nested live Bridge remain provider-only; the surrounding API/setup coverage has a runnable local preflight.",
+            policy: "Run every applicable local_preflight_command. Do not delete, skip, or weaken provider CI coverage; record only the exact nested-control-plane case as provider_only in workflow_validation.",
+        },
+    };
+    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

@@ -1,6 +1,6 @@
 import { GitClient } from "../../shared/git/git.js";
 import { type CompletionPhase, type CompletionToolRuntime, type DebugCompletionPhase, type QaCompletionGate } from "../phase-completion.js";
-import type { RunOnceDispatchPacket, RunnerDispatchArtifact } from "../session.types.js";
+import type { RunOnceDispatchPacket, RunnerDispatchArtifact, RunnerDispatchSidecar } from "../session.types.js";
 import type { ProviderCliRunContext } from "./provider-cli.types.js";
 export declare function emitDraftGateArtifacts(emit: ProviderCliRunContext["emit"], worktreePath: string, workItemId: string): Promise<void>;
 export declare function emitDecomposeGateArtifacts(emit: ProviderCliRunContext["emit"], worktreePath: string, workItemId: string): Promise<void>;
@@ -18,8 +18,9 @@ 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 readQaBundleSidecars(worktreePath: string, workItemId: string, ownerType?: string | null, ownerId?: string | null): Promise<RunnerDispatchSidecar[]>;
 export declare function emitQaStructuredEvents(emit: ProviderCliRunContext["emit"], artifact: RunnerDispatchArtifact): Promise<void>;
 interface QaGateArtifactSnapshot {
     readonly gate: QaCompletionGate;

package/dist/session/provider-cli/provider-cli.artifacts.js

@@ -4,7 +4,10 @@ import { artifactRootFor, artifactRootForOwner, debugCompletionPhaseOrder, draft
 import { ensureNoSymbolicLinkPathSegments, isPathUnderRoot, sha256File } from "../qa-sidecar-validation.js";
 import { hasLaunchTarget } from "./provider-cli.qa-sidecars.js";
 import { clip, isNodeError, messageFromError, normalizedString, parseJsonLine, stringField } from "./provider-output-state.js";
+const maxTransportedQaSidecarBytes = 8 * 1024 * 1024;
+const maxTransportedQaSidecarsTotalBytes = 16 * 1024 * 1024;
 const developCyclePhaseOrder = ["implementation", "self_review", "validation"];
+const nonPublishableWorktreePaths = [".forge", ".local"];
 export async function emitDraftGateArtifacts(emit, worktreePath, workItemId) {
     const draftArtifactFiles = {
         draft_intent: "draft.intent.json",
@@ -147,7 +150,9 @@ export async function cleanupCompletionTools(completionTools, emit) {
 }
 export async function commitWorktreeChanges(git, worktreePath, workItemId) {
     await git.run(worktreePath, ["add", "-A"]);
-    await git.run(worktreePath, ["reset", "--", ".forge"]).catch(() => "");
+    for (const reservedPath of nonPublishableWorktreePaths) {
+        await git.run(worktreePath, ["reset", "--", reservedPath]).catch(() => "");
+    }
     const changedFiles = (await git.run(worktreePath, ["diff", "--cached", "--name-only"]))
         .split(/\r?\n/)
         .map((line) => line.trim())
@@ -209,12 +214,13 @@ export async function readQaCompletionArtifactBundle(worktreePath, workItemId, o
     const planJson = await fs.readFile(path.join(artifactRoot, qaArtifactFileNames.plan), "utf8");
     const evidenceJson = await fs.readFile(path.join(artifactRoot, qaArtifactFileNames.evidence), "utf8");
     const findingsJson = await fs.readFile(path.join(artifactRoot, qaArtifactFileNames.findings), "utf8");
-    await validateQaBundleSidecarReferences(worktreePath, workItemId, ownerType, ownerId);
+    const sidecars = await readQaBundleSidecars(worktreePath, workItemId, ownerType, ownerId);
     return {
         ...artifact,
         planJson,
         evidenceJson,
-        findingsJson
+        findingsJson,
+        sidecars
     };
 }
 export async function hasCompleteQaArtifactBundle(worktreePath, workItemId, ownerType, ownerId) {
@@ -237,28 +243,55 @@ export async function hasCompleteQaArtifactBundle(worktreePath, workItemId, owne
     }
     return true;
 }
-export function enforceQaBrowserLaunchTargetGate(dispatch, artifact) {
+export async function enforceQaBrowserLaunchTargetGate(dispatch, artifact) {
     const qaBrowser = dispatch.qaBrowser;
     if (!qaBrowser?.required || hasLaunchTarget(qaBrowser.launchTarget ?? null)) {
         return;
     }
+    const evidence = await readJsonObjectFile(path.join(path.dirname(artifact.path), qaArtifactFileNames.evidence));
+    if (hasPassingRepositoryPlaywrightEvidence(evidence)) {
+        return;
+    }
     const verdict = parseJsonLine(artifact.verdictJson) ?? {};
     const status = normalizedString(stringField(verdict, "status") ?? artifact.status ?? "");
     const blockerReason = normalizedString(stringField(verdict, "blocker_reason") ?? "");
     if (status !== "blocked" || blockerReason !== "missing_app_launch_target") {
-        throw new Error("QA browser testing is required but no app launch target was provided; provider must return blocked with blocker_reason missing_app_launch_target.");
+        throw new Error("QA browser testing is required but neither an app launch target nor passing repository Playwright evidence was provided; provider must return blocked with blocker_reason missing_app_launch_target.");
+    }
+}
+function hasPassingRepositoryPlaywrightEvidence(evidence) {
+    const passingBrowserCheck = arrayField(evidence, "browser_checks").some(check => normalizedString(stringField(check, "status") ?? "") === "pass"
+        && Boolean(stringField(check, "url") ?? stringField(check, "route")));
+    if (!passingBrowserCheck) {
+        return false;
     }
+    return arrayField(evidence, "commands").some(command => {
+        const status = normalizedString(stringField(command, "status") ?? "");
+        const exitCode = command.exit_code;
+        const description = [stringField(command, "command"), stringField(command, "summary")]
+            .filter((value) => Boolean(value))
+            .join(" ");
+        return status === "pass"
+            && exitCode === 0
+            && /(?:playwright|test:e2e|e2e(?:\s|:|$)|browser(?:\s|-)?test)/iu.test(description);
+    });
 }
 export async function validateQaBundleSidecarReferences(worktreePath, workItemId, ownerType, ownerId) {
+    await readQaBundleSidecars(worktreePath, workItemId, ownerType, ownerId);
+}
+export async function readQaBundleSidecars(worktreePath, workItemId, ownerType, ownerId) {
     const artifactRoot = ownerType && ownerId
         ? artifactRootForOwner(worktreePath, ownerType, ownerId)
         : artifactRootFor(worktreePath, workItemId);
     const evidence = await readJsonObjectFile(path.join(artifactRoot, qaArtifactFileNames.evidence));
     const sidecars = arrayField(evidence, "sidecars");
     if (sidecars.length === 0) {
-        return;
+        return [];
     }
     const qaSidecarRoot = path.resolve(artifactRoot, "qa");
+    const transported = [];
+    const transportedByPath = new Map();
+    let totalBytes = 0;
     for (const [index, sidecar] of sidecars.entries()) {
         const sidecarPath = stringField(sidecar, "path");
         const expectedHash = stringField(sidecar, "content_hash");
@@ -288,11 +321,36 @@ export async function validateQaBundleSidecarReferences(worktreePath, workItemId
         if (stat.size !== expectedBytes) {
             throw new Error(`QA sidecar ${index} bytes do not match the referenced file.`);
         }
+        if (stat.size > maxTransportedQaSidecarBytes) {
+            throw new Error(`QA sidecar ${index} exceeds the ${maxTransportedQaSidecarBytes}-byte transport limit.`);
+        }
         const actualHash = await sha256File(fullPath);
         if (actualHash !== expectedHash.trim().toLowerCase()) {
             throw new Error(`QA sidecar ${index} content_hash does not match the referenced file.`);
         }
+        const canonicalPath = path.relative(worktreePath, fullPath).split(path.sep).join("/");
+        const duplicateKey = canonicalPath.toLowerCase();
+        const existing = transportedByPath.get(duplicateKey);
+        if (existing) {
+            if (existing.contentHash !== actualHash || existing.bytes !== stat.size) {
+                throw new Error(`QA sidecar ${index} conflicts with another payload for ${canonicalPath}.`);
+            }
+            continue;
+        }
+        totalBytes += stat.size;
+        if (totalBytes > maxTransportedQaSidecarsTotalBytes) {
+            throw new Error(`QA sidecars exceed the ${maxTransportedQaSidecarsTotalBytes}-byte total transport limit.`);
+        }
+        const content = await fs.readFile(fullPath);
+        transportedByPath.set(duplicateKey, { contentHash: actualHash, bytes: stat.size });
+        transported.push({
+            path: canonicalPath,
+            contentBase64: content.toString("base64"),
+            contentHash: actualHash,
+            bytes: stat.size
+        });
     }
+    return transported;
 }
 export async function emitQaStructuredEvents(emit, artifact) {
     const artifactRoot = path.dirname(artifact.path);
@@ -444,7 +502,7 @@ export class LiveQaArtifactEmitter {
         if (!artifact) {
             return;
         }
-        enforceQaBrowserLaunchTargetGate(this.dispatch, artifact);
+        await enforceQaBrowserLaunchTargetGate(this.dispatch, artifact);
         this.emittedBundle = true;
         await emitQaArtifactRecorded(this.emit, this.worktreePath, artifact);
         await emitQaStructuredEvents(this.emit, artifact);

package/dist/session/provider-cli/provider-cli.deterministic.js

@@ -8,6 +8,7 @@ import { deterministicBrowserCheck, deterministicBrowserSidecar, hasLaunchTarget
 import { buildProviderCliCommand, formatProviderCliCommand, isPullRequestCheckRepairDispatch, isPullRequestCommentsDispatch, singleLine } from "./provider-cli.prompts.js";
 import { estimatedDeterministicUsage, exactRedactionSecrets } from "./provider-cli.runtime.js";
 import { buildProviderUsageEvent } from "./provider-usage.js";
+import { writeCiRepairReadinessManifest } from "./ci-repair-readiness.js";
 import { deterministicArchitectPayload, deterministicCompletionPayload, deterministicQaGatePayload } from "./provider-cli.deterministic-payloads.js";
 export class DeterministicProviderCliService {
     git;
@@ -212,6 +213,31 @@ export class DeterministicProviderCliService {
         const { dispatch, worktree } = context;
         const repairChecks = route === "ci_repair" || isPullRequestCheckRepairDispatch(dispatch);
         const addressComments = isPullRequestCommentsDispatch(dispatch);
+        let repairArtifact = null;
+        let repairSpec = null;
+        if (repairChecks) {
+            const metadataRoot = path.join(worktree.worktreePath, ".forge", "work-items", dispatch.workItem.id);
+            await fs.mkdir(metadataRoot, { recursive: true });
+            const laneCommand = selectLaneCommand(dispatch.artifacts, dispatch.execution.lane, dispatch.cycleRun.phase);
+            if (!laneCommand)
+                throw new Error("Deterministic CI repair could not materialize the approved lane spec.");
+            const specBody = buildSpecBody(laneCommand, dispatch.workItem, "ci_repair");
+            const specPath = path.join(metadataRoot, "spec.md");
+            await fs.writeFile(specPath, specBody, "utf8");
+            await fs.writeFile(path.join(metadataRoot, "spec.meta.json"), `${JSON.stringify({ schema_version: 1, status: "approved", produced_by: "forge-lane-command" })}\n`, "utf8");
+            repairSpec = { repoPath: worktree.worktreePath, path: specPath, body: specBody, producedBy: "forge-lane-command", status: "approved" };
+            await writeCiRepairReadinessManifest(dispatch, worktree.worktreePath, specPath, context.runtimeEnvironment);
+            const reference = await writeCompletionArtifact({
+                worktreePath: worktree.worktreePath,
+                workItemId: dispatch.workItem.id,
+                phase: "ci_repair",
+                producedBy: "forge-deterministic-provider",
+            }, expectedCompletionToolName("ci_repair"), deterministicCiRepairPayload());
+            repairArtifact = await readCompletionArtifact(worktree.worktreePath, dispatch.workItem.id, "ci_repair");
+            if (!repairArtifact)
+                throw new Error(`Deterministic CI repair did not produce ${reference.path}.`);
+            await emitCompletionArtifactRecorded(context.emit, worktree.worktreePath, repairArtifact);
+        }
         await this.git.run(worktree.worktreePath, ["commit", "--allow-empty", "-m", `forge bridge ${repairChecks ? "ci repair" : addressComments ? "pr comments" : "conflict resolve"} for ${dispatch.workItem.id.slice(0, 8)}`]);
         await context.emit(buildProviderUsageEvent(dispatch, estimatedDeterministicUsage()));
         await context.emit({
@@ -229,10 +255,30 @@ export class DeterministicProviderCliService {
                 ? `forge-bridge repaired PR checks for ${worktree.branchName}.`
                 : addressComments
                     ? `forge-bridge addressed PR comments for ${worktree.branchName}.`
-                    : `forge-bridge resolved conflicts for ${worktree.branchName}.`
+                    : `forge-bridge resolved conflicts for ${worktree.branchName}.`,
+            spec: repairSpec,
+            artifact: repairArtifact,
+            artifacts: repairArtifact ? [repairArtifact] : [],
         };
     }
 }
+function deterministicCiRepairPayload() {
+    const command = { command: "forge deterministic ci-repair validation", exit_code: 0, status: "pass", summary: "Deterministic CI repair fixture passed." };
+    return {
+        status: "pass",
+        summary: "Deterministic CI repair handoff is ready for provider checks.",
+        failed_checks: [{ name: "CI / deterministic", provider_state: "failure", workflow: ".github/workflows/ci.yml", job: "deterministic", step: "fixture" }],
+        root_cause: { classification: "test expectation mismatch", summary: "Deterministic fixture failure repaired.", evidence: ["Fixture provider reported the expected failed check."] },
+        changed_files: [],
+        no_code_action: { action: "deterministic_fixture", reason: "The deterministic provider models the repair without a product diff." },
+        narrow_validation: [command],
+        workflow_validation: [{ step: "deterministic fixture", equivalence: "supported", command: command.command, exit_code: 0, status: "pass", summary: command.summary }],
+        broader_validation: [command],
+        remaining_risks: [],
+        provider_state: "ready_for_rerun",
+        ready_for_push: true,
+    };
+}
 function deterministicDraftPayload(dispatch) {
     const kind = dispatch.draft?.kind ?? "work_item";
     if (kind === "work_order_decomposition") {