@loucompanion/forge-bridge 0.1.3-dev.09aeeb7ccadf → 0.1.3-dev.1fe428dd78ab

package/dist/sandbox/sandbox.types.d.ts

@@ -0,0 +1,83 @@
+import type { RunOnceDispatchPacket } from "../session/session.types.js";
+export interface SandboxContract {
+    readonly schemaVersion: 1;
+    readonly workingDirectory: "/workspace";
+    readonly commands: Readonly<Record<string, string>>;
+    readonly caches: readonly SandboxCache[];
+    readonly services: readonly SandboxService[];
+    readonly environment: readonly string[];
+    readonly artifacts: readonly string[];
+    readonly logs: readonly string[];
+    readonly browser: boolean;
+}
+export interface SandboxCache {
+    readonly name: string;
+    readonly mode: "readonly" | "per_attempt";
+}
+export interface SandboxService {
+    readonly type: "postgres" | "redis" | "browser";
+    readonly port: number;
+}
+export interface ValidatedSandboxContract {
+    readonly contract: SandboxContract;
+    readonly normalizedJson: string;
+    readonly digest: string;
+}
+export interface SandboxPreflightResult {
+    readonly available: boolean;
+    readonly healthy: boolean;
+    readonly generation: number;
+    readonly runtimeVersion: string | null;
+    readonly maxConcurrentSandboxes: number;
+    readonly availableMemoryBytes: number;
+    readonly availableCpuMillis: number;
+    readonly availableWorkspaceBytes: number;
+    readonly diskLow: boolean;
+    readonly unavailableCode: string | null;
+    readonly unavailableReason: string | null;
+    readonly features: SandboxFeatureMatrix;
+}
+export interface SandboxFeatureMatrix {
+    readonly rootless: boolean;
+    readonly userNamespaces: boolean;
+    readonly cgroupV2: boolean;
+    readonly seccomp: boolean;
+    readonly lsm: boolean;
+    readonly storageQuota: boolean;
+    readonly storagePolicy: boolean;
+    readonly compose: boolean;
+    readonly internalNetwork: boolean;
+    readonly buildkit: boolean;
+    readonly imagePolicy: boolean;
+    readonly securityProfile: boolean;
+    readonly egressProxy: boolean;
+}
+export interface SandboxReservation {
+    readonly dispatchAttemptId: string;
+    readonly leaseId: string;
+    readonly fencingToken: string;
+    readonly runnerInstanceId: string;
+    readonly expiresAt: string;
+    readonly reservedUntil: string;
+    readonly dispatch: RunOnceDispatchPacket;
+    readonly contract?: ValidatedSandboxContract;
+    readonly inputCommitSha?: string;
+    readonly sandboxConfigCommitSha?: string;
+    readonly imageDigest?: string;
+}
+export interface CommandResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface CommandRunner {
+    run(command: string, args: readonly string[], options?: CommandOptions): Promise<CommandResult>;
+}
+export interface CommandOptions {
+    readonly cwd?: string;
+    readonly env?: Readonly<Record<string, string>>;
+    readonly stdin?: string | Uint8Array;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+    readonly maxOutputBytes?: number;
+}

package/dist/sandbox/sandbox.types.js

@@ -0,0 +1 @@
+export {};

package/dist/sandbox/worker-supervisor.d.ts

@@ -0,0 +1,13 @@
+import type { MonotonicLeaseDeadline } from "./lease-watchdog.js";
+export type SandboxTerminationCode = "sandbox_lease_expired" | "sandbox_wall_timeout" | "sandbox_idle_timeout";
+export declare class WorkerDeadlineSupervisor {
+    readonly lease: MonotonicLeaseDeadline;
+    readonly hardWallMs: number;
+    readonly idleMs: number;
+    private readonly startedAtMs;
+    private lastActivityMs;
+    constructor(lease: MonotonicLeaseDeadline, hardWallMs: number, idleMs: number, startedAtMs?: number);
+    touch(nowMs?: number): void;
+    termination(nowMs?: number): SandboxTerminationCode | null;
+}
+export declare function terminationMessage(code: SandboxTerminationCode): string;

package/dist/sandbox/worker-supervisor.js

@@ -0,0 +1,36 @@
+export class WorkerDeadlineSupervisor {
+    lease;
+    hardWallMs;
+    idleMs;
+    startedAtMs;
+    lastActivityMs;
+    constructor(lease, hardWallMs, idleMs, startedAtMs = performance.now()) {
+        this.lease = lease;
+        this.hardWallMs = hardWallMs;
+        this.idleMs = idleMs;
+        this.startedAtMs = startedAtMs;
+        if (!Number.isFinite(hardWallMs) || hardWallMs <= 0 || !Number.isFinite(idleMs) || idleMs <= 0) {
+            throw new Error("Sandbox watchdog limits must be positive.");
+        }
+        this.lastActivityMs = startedAtMs;
+    }
+    touch(nowMs = performance.now()) {
+        this.lastActivityMs = Math.max(this.lastActivityMs, nowMs);
+    }
+    termination(nowMs = performance.now()) {
+        if (this.lease.expired(nowMs))
+            return "sandbox_lease_expired";
+        if (nowMs - this.startedAtMs >= this.hardWallMs)
+            return "sandbox_wall_timeout";
+        if (nowMs - this.lastActivityMs >= this.idleMs)
+            return "sandbox_idle_timeout";
+        return null;
+    }
+}
+export function terminationMessage(code) {
+    switch (code) {
+        case "sandbox_lease_expired": return "The durable execution lease expired inside the sandbox.";
+        case "sandbox_wall_timeout": return "The sandbox reached its hard wall-clock limit.";
+        case "sandbox_idle_timeout": return "The sandbox produced no control or process activity before its idle limit.";
+    }
+}

package/dist/sandbox/worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sandbox/worker.js

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

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

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

package/dist/sandbox/workspace.service.js

@@ -0,0 +1,49 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { GitClient } from "../shared/git/git.js";
+import { injectWorktreeArtifacts, filterArtifactsForLane } from "../worktree/artifact-injector.js";
+import { normalizeBranchName } from "../worktree/worktree.service.js";
+export class SandboxWorkspaceService {
+    workspace;
+    bundlePath;
+    inputCommitSha;
+    git;
+    constructor(workspace = process.env.FORGE_WORKSPACE ?? "/workspace", bundlePath = process.env.FORGE_INPUT_BUNDLE ?? "/control/input/repo.bundle", inputCommitSha = process.env.FORGE_INPUT_COMMIT_SHA ?? "", git = new GitClient()) {
+        this.workspace = workspace;
+        this.bundlePath = bundlePath;
+        this.inputCommitSha = inputCommitSha;
+        this.git = git;
+    }
+    async prepare(request) {
+        if (!/^[0-9a-f]{40,64}$/i.test(this.inputCommitSha))
+            throw new Error("Sandbox input commit SHA is missing or invalid.");
+        const stat = await fs.stat(this.workspace).catch(() => null);
+        if (!stat?.isDirectory())
+            throw new Error("Sandbox workspace volume is unavailable.");
+        const entries = await fs.readdir(this.workspace);
+        if (entries.length > 0)
+            throw new Error("Sandbox workspace must be empty before bundle import.");
+        await this.git.run(path.dirname(this.workspace), ["clone", "--no-checkout", "--no-local", this.bundlePath, this.workspace]);
+        const actualSha = (await this.git.run(this.workspace, ["rev-parse", "--verify", `${this.inputCommitSha}^{commit}`])).trim();
+        if (actualSha.toLowerCase() !== this.inputCommitSha.toLowerCase())
+            throw new Error("Imported bundle does not contain the exact recorded input commit.");
+        const branchName = normalizeBranchName(request.worktreeKey, `forge/${request.workItem.id.replace(/-/g, "")}`);
+        await this.git.run(this.workspace, ["checkout", "-B", branchName, this.inputCommitSha]);
+        await this.git.run(this.workspace, ["config", "user.email", "forge-agent@forge.local"]);
+        await this.git.run(this.workspace, ["config", "user.name", "Forge Agent"]);
+        await this.git.run(this.workspace, ["config", "core.hooksPath", "/dev/null"]);
+        const artifacts = filterArtifactsForLane(request.artifacts, request.lane, request.phase);
+        if (artifacts.length > 0)
+            await injectWorktreeArtifacts(this.workspace, artifacts);
+        return {
+            repoPath: this.workspace,
+            worktreePath: this.workspace,
+            branchName,
+            baseBranch: request.baseBranch,
+            cleanupWorktrees: false
+        };
+    }
+    async release(_handle) {
+        // The host supervisor owns the workspace volume lifecycle.
+    }
+}

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

@@ -2,6 +2,7 @@ import type { ProviderCliDraftContext, ProviderCliRunContext, ProviderCliRunResu
 export interface ProviderCliService {
     runImplementation(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
     runArchitect(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
+    runCiRepair(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
     runConflictResolve(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
     runQa(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
     runDraft(context: ProviderCliDraftContext): Promise<ProviderCliRunResult>;

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

@@ -8,5 +8,7 @@ export declare class DeterministicProviderCliService implements ProviderCliServi
     runImplementation(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
     runArchitect(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
     runQa(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
+    runCiRepair(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
     runConflictResolve(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
+    private runPullRequestRepair;
 }

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

@@ -5,7 +5,7 @@ import { buildSpecBody, selectLaneCommand } from "../../worktree/artifact-inject
 import { completionPhaseFromDispatch, debugCompletionPhaseOrder, expectedCompletionToolName, expectedDebugCompletionToolName, expectedQaCompletionToolName, qaCompletionGateOrder, readCompletionArtifact, usesDebugCycleCompletion, usesDevelopCycleCompletion, writeCompletionArtifact } from "../phase-completion.js";
 import { emitArchitectStructuredEvents, emitCompletionArtifactRecorded, emitQaArtifactRecorded, emitQaGateAccepted, emitQaStructuredEvents, isDebugCompletionPhaseForProvider, nextQaGate, phaseCompleteEventType, qaArtifactRootForDispatch, readQaCompletionArtifactBundle, readQaGateArtifact } from "./provider-cli.artifacts.js";
 import { deterministicBrowserCheck, deterministicBrowserSidecar, hasLaunchTarget, writeQaSidecarFiles } from "./provider-cli.qa-sidecars.js";
-import { buildProviderCliCommand, formatProviderCliCommand, isPullRequestCommentsDispatch, singleLine } from "./provider-cli.prompts.js";
+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 { deterministicArchitectPayload, deterministicCompletionPayload, deterministicQaGatePayload } from "./provider-cli.deterministic-payloads.js";
@@ -202,23 +202,34 @@ export class DeterministicProviderCliService {
             artifacts: [qaArtifact]
         };
     }
+    async runCiRepair(context) {
+        return await this.runPullRequestRepair(context, "ci_repair");
+    }
     async runConflictResolve(context) {
+        return await this.runPullRequestRepair(context, "conflict_resolve");
+    }
+    async runPullRequestRepair(context, route) {
         const { dispatch, worktree } = context;
+        const repairChecks = route === "ci_repair" || isPullRequestCheckRepairDispatch(dispatch);
         const addressComments = isPullRequestCommentsDispatch(dispatch);
-        await this.git.run(worktree.worktreePath, ["commit", "--allow-empty", "-m", `forge bridge ${addressComments ? "pr comments" : "conflict resolve"} for ${dispatch.workItem.id.slice(0, 8)}`]);
+        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({
             role: "assistant",
             kind: "message",
-            content: addressComments
-                ? `Deterministic PR comment addressing completed for ${worktree.branchName}.`
-                : `Deterministic conflict resolve completed for ${worktree.branchName}.`,
-            eventType: addressComments ? "pr_comments_complete" : "conflict_resolve_complete"
+            content: repairChecks
+                ? `Deterministic CI repair completed for ${worktree.branchName}.`
+                : addressComments
+                    ? `Deterministic PR comment addressing completed for ${worktree.branchName}.`
+                    : `Deterministic conflict resolve completed for ${worktree.branchName}.`,
+            eventType: repairChecks ? "pr_checks_complete" : addressComments ? "pr_comments_complete" : "conflict_resolve_complete"
         });
         return {
-            summary: addressComments
-                ? `forge-bridge addressed PR comments for ${worktree.branchName}.`
-                : `forge-bridge resolved conflicts for ${worktree.branchName}.`
+            summary: repairChecks
+                ? `forge-bridge repaired PR checks for ${worktree.branchName}.`
+                : addressComments
+                    ? `forge-bridge addressed PR comments for ${worktree.branchName}.`
+                    : `forge-bridge resolved conflicts for ${worktree.branchName}.`
         };
     }
 }

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

@@ -38,5 +38,7 @@ export declare function qaBrowserInstruction(dispatch: RunOnceDispatchPacket): s
 export declare function storyQaInstruction(dispatch: RunOnceDispatchPacket): string;
 export declare function buildQaPrompt(dispatch: RunOnceDispatchPacket, laneSpec: string): string;
 export declare function buildConflictResolvePrompt(dispatch: RunOnceDispatchPacket, branchName: string): string;
+export declare function buildPullRequestCheckRepairPrompt(dispatch: RunOnceDispatchPacket, branchName: string): string;
 export declare function buildPullRequestCommentsPrompt(dispatch: RunOnceDispatchPacket, branchName: string): string;
+export declare function isPullRequestCheckRepairDispatch(dispatch: RunOnceDispatchPacket): boolean;
 export declare function isPullRequestCommentsDispatch(dispatch: RunOnceDispatchPacket): boolean;

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

@@ -467,6 +467,33 @@ Keep the original work item intent intact:
 
 Finish with a concise summary of the conflicts resolved and verification performed.`;
 }
+export function buildPullRequestCheckRepairPrompt(dispatch, branchName) {
+    const pr = dispatch.pullRequest;
+    const targetBranch = pr?.targetBranch || dispatch.cycleRun.requestedBase || dispatch.repo.defaultBranch || "main";
+    const prLocator = pr
+        ? `PR #${pr.number}${pr.url ? ` (${pr.url})` : ""}`
+        : "the open pull request for this work item";
+    return `You are Forge's CI Repair lane running locally in a prepared git worktree.
+
+The current branch is the pull request branch ${branchName}. Repair failed required checks on ${prLocator}.
+PR context:
+- Provider: ${pr?.provider || "not provided"}
+- Source branch: ${pr?.sourceBranch || branchName}
+- Target branch: ${targetBranch}
+- Check state: ${pr?.checkState || "unknown"}
+- Required checks: ${pr?.requiredChecksPassed ?? "?"}/${pr?.requiredChecksTotal ?? "?"}
+
+This is not a merge-conflict resolution task. Only fetch/merge/rebase ${targetBranch} if needed to inspect the branch, reproduce the failed check, or handle an explicit stale-branch/conflict blocker. The primary objective is to repair CI.
+
+Load and follow .forge/commands/operational/ci-repair-prompt.md, including its CI repair phase gate and validation skill. Inspect the failed provider check logs, identify the exact failed workflow job/step, make the smallest scoped repair, and before pushing run the failed job's local workflow-equivalent gate, including pre-test guard/drift steps when available.
+
+Keep the original work item intent intact:
+- Work item: ${dispatch.workItem.id}
+- Title: ${dispatch.workItem.title}
+- Acceptance criteria: ${dispatch.workItem.acceptanceCriteria || "Not specified"}
+
+Finish with a concise summary of failing checks, changed files, validation commands, pushed commit status, and any remaining provider checks still pending.`;
+}
 export function buildPullRequestCommentsPrompt(dispatch, branchName) {
     const pr = dispatch.pullRequest;
     const targetBranch = pr?.targetBranch || dispatch.cycleRun.requestedBase || dispatch.repo.defaultBranch || "main";
@@ -492,6 +519,10 @@ Keep the original work item intent intact:
 
 Finish with a concise summary of comments addressed and verification performed.`;
 }
+export function isPullRequestCheckRepairDispatch(dispatch) {
+    return dispatch.cycleRun.kind.trim().toLowerCase() === "pr_checks"
+        || dispatch.execution.role.trim().toLowerCase() === "ci_repair";
+}
 export function isPullRequestCommentsDispatch(dispatch) {
     return dispatch.cycleRun.kind.trim().toLowerCase() === "pr_comments";
 }

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

@@ -13,6 +13,7 @@ export declare class RoutingProviderCliService implements ProviderCliService {
     constructor(realProvider?: ProviderCliService, deterministicProvider?: ProviderCliService);
     runImplementation(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
     runArchitect(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
+    runCiRepair(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
     runConflictResolve(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
     runQa(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
     runDraft(context: ProviderCliDraftContext): Promise<ProviderCliRunResult>;
@@ -25,5 +26,7 @@ export declare class ProcessBackedProviderCliService implements ProviderCliServi
     runImplementation(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
     runArchitect(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
     runQa(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
+    runCiRepair(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
     runConflictResolve(context: ProviderCliRunContext): Promise<ProviderCliRunResult>;
+    private runPullRequestRepair;
 }