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

package/dist/session/provider-cli/bridge-cli.conformance-fixtures.d.ts

@@ -0,0 +1,72 @@
+import { type BridgeChatCapability, type BridgeChatRequestedCapability, type ChatTurnCallbackEnvelope, type ChatTurnCallbackKind, type ChatTurnDispatchPacket, type ChatTurnMessage } from "../../bridge/bridge-chat.types.js";
+export declare const requiredBridgeCliScenarioKeys: readonly ["happy-path", "cancellation", "failure", "malformed-tool-call", "redaction"];
+export type BridgeCliConformanceScenarioKey = typeof requiredBridgeCliScenarioKeys[number];
+export type BridgeCliConformanceProviderKind = "codex" | "cursor";
+export type BridgeCliConformanceRuntimeKind = "managed-host";
+export interface BridgeCliConformanceCapabilityFixture {
+    readonly fixtureKey: string;
+    readonly runtimeState: string;
+    readonly supportedCapabilities: readonly BridgeChatRequestedCapability[];
+    readonly metadata: Readonly<Record<string, string>>;
+    readonly capability: BridgeChatCapability;
+}
+export interface BridgeCliConformanceInputTurn {
+    readonly turnKey: string;
+    readonly messages: readonly ChatTurnMessage[];
+    readonly toolCalls: readonly BridgeCliConformanceInputToolCall[];
+    readonly requestedCapabilities: readonly BridgeChatRequestedCapability[];
+    readonly providerThreadId: string | null;
+    readonly dispatchPacket: ChatTurnDispatchPacket;
+}
+export interface BridgeCliConformanceInputToolCall {
+    readonly toolName: string;
+    readonly argumentsJson: string;
+    readonly isMalformed?: boolean;
+}
+export interface BridgeCliConformanceExpectedEvent {
+    readonly sequence: number;
+    readonly adapterEventId: string | null;
+    readonly eventType: ChatTurnCallbackKind;
+    readonly payloadKey?: string | null;
+}
+export interface BridgeCliConformanceExpectedTerminalState {
+    readonly state: "completed" | "cancelled" | "failed" | "rejected";
+    readonly failureCode?: string | null;
+    readonly failureKind?: string | null;
+}
+export interface BridgeCliConformanceExpectedSnapshotState {
+    readonly runtimeState: string;
+    readonly providerThreadId: string | null;
+    readonly metadata: Readonly<Record<string, string>>;
+}
+export interface BridgeCliConformanceProviderStreamFixture {
+    readonly stdoutLines: readonly string[];
+    readonly expectedEventTypes: readonly string[];
+    readonly expectedFinalMessage: string | null;
+}
+export interface BridgeCliChatAdapterConformanceCase {
+    readonly adapterKind: "bridge-cli";
+    readonly runtimeKind: BridgeCliConformanceRuntimeKind;
+    readonly providerKind: BridgeCliConformanceProviderKind;
+    readonly capabilityFixture: BridgeCliConformanceCapabilityFixture;
+    readonly scenarioKey: BridgeCliConformanceScenarioKey;
+    readonly inputTurn: BridgeCliConformanceInputTurn;
+    readonly expectedEvents: readonly BridgeCliConformanceExpectedEvent[];
+    readonly expectedTerminalState: BridgeCliConformanceExpectedTerminalState;
+    readonly expectedSnapshotState: BridgeCliConformanceExpectedSnapshotState;
+    readonly prohibitedLogPatterns: readonly string[];
+    readonly skipReason: string | null;
+    readonly callbackEnvelope: ChatTurnCallbackEnvelope;
+    readonly providerStream: BridgeCliConformanceProviderStreamFixture;
+    readonly redactionSecrets: readonly string[];
+}
+export interface BridgeCliEnvelopeRejectionCase {
+    readonly caseKey: string;
+    readonly sourceScenarioKey: BridgeCliConformanceScenarioKey;
+    readonly dispatchPacket: Readonly<Record<string, unknown>>;
+    readonly capability: BridgeChatCapability;
+    readonly expectedMessage: string;
+}
+export declare const bridgeCliConformanceCases: readonly BridgeCliChatAdapterConformanceCase[];
+export declare const bridgeCliEnvelopeRejectionCases: readonly BridgeCliEnvelopeRejectionCase[];
+export declare const malformedProviderStreamFixtures: Readonly<Record<BridgeCliConformanceProviderKind, readonly string[]>>;

package/dist/session/provider-cli/bridge-cli.conformance-fixtures.js

@@ -0,0 +1,462 @@
+import { bridgeChatProtocolVersion, unavailableBridgeChatCapability, } from "../../bridge/bridge-chat.types.js";
+export const requiredBridgeCliScenarioKeys = [
+    "happy-path",
+    "cancellation",
+    "failure",
+    "malformed-tool-call",
+    "redaction",
+];
+const ids = {
+    callbackId: "77777777-7777-4777-8777-777777777777",
+    chatRunId: "11111111-1111-4111-8111-111111111111",
+    conversationId: "22222222-2222-4222-8222-222222222222",
+    turnId: "33333333-3333-4333-8333-333333333333",
+    leaseId: "44444444-4444-4444-8444-444444444444",
+    fencingToken: "55555555-5555-4555-8555-555555555555",
+    runnerInstanceId: "66666666-6666-4666-8666-666666666666",
+    runnerId: "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
+    attachmentId: "88888888-8888-4888-8888-888888888888",
+    grantId: "99999999-9999-4999-8999-999999999999",
+};
+const deterministicExpiresAt = "2099-01-01T00:00:00.000Z";
+const redactionSecrets = [
+    "raw-provider-secret",
+    "raw-tool-token",
+    "opaque-temp-file-token",
+    "opaque-grant-nonce",
+];
+const prohibitedLogPatterns = [
+    "raw-provider-secret",
+    "raw-tool-token",
+    "opaque-temp-file-token",
+    "opaque-grant-nonce",
+    "sk-[A-Za-z0-9_-]+",
+    "Authorization:\\s*Bearer\\s+(?!\\[REDACTED\\])\\S+",
+];
+const providerDefinitions = [
+    {
+        providerKind: "codex",
+        model: "gpt-5-codex",
+        runtimeState: "codex-cli-authenticated",
+        providerThreadPrefix: "codex-thread",
+    },
+    {
+        providerKind: "cursor",
+        model: "cursor-fast",
+        runtimeState: "cursor-agent-authenticated",
+        providerThreadPrefix: "cursor-session",
+    },
+];
+const scenarioDefinitions = [
+    {
+        scenarioKey: "happy-path",
+        requestedCapabilities: [
+            "text",
+            "cancel",
+            "resume",
+            "thread_continuity",
+            "attachment_handoffs",
+            "action_broker_grants",
+        ],
+        terminalEventType: "output_completed",
+        terminalState: { state: "completed" },
+        finalMessage: "Deterministic Bridge CLI turn completed.",
+        includeBoundedEnvelopes: true,
+    },
+    {
+        scenarioKey: "cancellation",
+        requestedCapabilities: ["text", "cancel", "thread_continuity"],
+        terminalEventType: "cancelled",
+        terminalState: {
+            state: "cancelled",
+            failureCode: "chat_turn_cancelled",
+            failureKind: "cancelled",
+        },
+        finalMessage: null,
+    },
+    {
+        scenarioKey: "failure",
+        requestedCapabilities: ["text", "thread_continuity"],
+        terminalEventType: "failed",
+        terminalState: {
+            state: "failed",
+            failureCode: "provider_failed",
+            failureKind: "provider",
+        },
+        finalMessage: null,
+    },
+    {
+        scenarioKey: "malformed-tool-call",
+        requestedCapabilities: ["text", "thread_continuity"],
+        terminalEventType: "failed",
+        terminalState: {
+            state: "rejected",
+            failureCode: "bridge_cli.malformed_tool_call",
+            failureKind: "malformed_tool_call",
+        },
+        finalMessage: null,
+        toolCalls: [{
+                toolName: "write_file",
+                argumentsJson: "{\"path\":",
+                isMalformed: true,
+            }],
+    },
+    {
+        scenarioKey: "redaction",
+        requestedCapabilities: [
+            "text",
+            "thread_continuity",
+            "attachment_handoffs",
+            "action_broker_grants",
+        ],
+        terminalEventType: "output_completed",
+        terminalState: { state: "completed" },
+        finalMessage: "Redacted Bridge CLI turn completed.",
+        includeBoundedEnvelopes: true,
+    },
+];
+export const bridgeCliConformanceCases = providerDefinitions.flatMap((provider) => scenarioDefinitions.map((scenario) => buildCase(provider, scenario)));
+const sourceCase = bridgeCliConformanceCases.find((testCase) => testCase.providerKind === "codex" && testCase.scenarioKey === "happy-path");
+if (!sourceCase) {
+    throw new Error("Bridge CLI conformance happy-path fixture was not initialized.");
+}
+const sourcePacket = sourceCase.inputTurn.dispatchPacket;
+const sourceCapability = sourceCase.capabilityFixture.capability;
+export const bridgeCliEnvelopeRejectionCases = [
+    {
+        caseKey: "attachment_handoff_unsupported_runner",
+        sourceScenarioKey: "happy-path",
+        capability: capabilityFor("codex", "gpt-5-codex", { supportsAttachments: false }),
+        dispatchPacket: {
+            ...packetRecord(sourcePacket),
+            requestedCapabilities: ["text", "attachment_handoffs"],
+            attachmentHandoffs: [attachmentHandoff()],
+            actionBrokerGrants: [],
+        },
+        expectedMessage: "requestedCapabilities attachment_handoffs for this runner",
+    },
+    {
+        caseKey: "attachment_handoff_unfenced_turn",
+        sourceScenarioKey: "happy-path",
+        capability: sourceCapability,
+        dispatchPacket: {
+            ...packetRecord(sourcePacket),
+            requestedCapabilities: ["text", "attachment_handoffs"],
+            attachmentHandoffs: [{
+                    ...attachmentHandoff(),
+                    turnId: "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb",
+                }],
+            actionBrokerGrants: [],
+        },
+        expectedMessage: "attachmentHandoffs[0].turnId must match turnId",
+    },
+    {
+        caseKey: "attachment_handoff_malformed_direct_path",
+        sourceScenarioKey: "happy-path",
+        capability: sourceCapability,
+        dispatchPacket: {
+            ...packetRecord(sourcePacket),
+            requestedCapabilities: ["text", "attachment_handoffs"],
+            attachmentHandoffs: [{
+                    ...attachmentHandoff(),
+                    rawPath: "C:\\Users\\developer\\secret.txt",
+                }],
+            actionBrokerGrants: [],
+        },
+        expectedMessage: "attachmentHandoffs[0].rawPath is not supported",
+    },
+    {
+        caseKey: "action_grant_widened_without_request",
+        sourceScenarioKey: "happy-path",
+        capability: sourceCapability,
+        dispatchPacket: {
+            ...packetRecord(sourcePacket),
+            requestedCapabilities: ["text"],
+            attachmentHandoffs: [],
+            actionBrokerGrants: [actionBrokerGrant()],
+        },
+        expectedMessage: "actionBrokerGrants require requestedCapabilities to include action_broker_grants",
+    },
+    {
+        caseKey: "action_grant_direct_execution_input",
+        sourceScenarioKey: "happy-path",
+        capability: sourceCapability,
+        dispatchPacket: {
+            ...packetRecord(sourcePacket),
+            requestedCapabilities: ["text", "action_broker_grants"],
+            attachmentHandoffs: [],
+            actionBrokerGrants: [{
+                    ...actionBrokerGrant(),
+                    executeCommand: "Remove-Item -Recurse C:\\repo",
+                }],
+        },
+        expectedMessage: "actionBrokerGrants[0].executeCommand is not supported",
+    },
+    {
+        caseKey: "action_grant_unfenced_lease",
+        sourceScenarioKey: "happy-path",
+        capability: sourceCapability,
+        dispatchPacket: {
+            ...packetRecord(sourcePacket),
+            requestedCapabilities: ["text", "action_broker_grants"],
+            attachmentHandoffs: [],
+            actionBrokerGrants: [{
+                    ...actionBrokerGrant(),
+                    leaseId: "cccccccc-cccc-4ccc-8ccc-cccccccccccc",
+                }],
+        },
+        expectedMessage: "actionBrokerGrants[0] must match the active dispatch fence",
+    },
+];
+export const malformedProviderStreamFixtures = {
+    codex: [
+        "not-json",
+        JSON.stringify({ type: "item.started", item: { type: "mcp_tool_call", server: "forge", status: "in_progress" } }),
+        JSON.stringify({ type: "item.completed", item: { type: "mcp_tool_call", server: "forge", status: "completed" } }),
+    ],
+    cursor: [
+        "not-json",
+        JSON.stringify({ type: "tool_call", subtype: "started", tool_call: { writeToolCall: { args: { path: "" } } } }),
+        JSON.stringify({ type: "tool_call", subtype: "completed", tool_call: { writeToolCall: { result: { success: {} } } } }),
+    ],
+};
+function buildCase(provider, scenario) {
+    const providerThreadId = `${provider.providerThreadPrefix}-${scenario.scenarioKey}`;
+    const capability = capabilityFor(provider.providerKind, provider.model);
+    const attachmentHandoffs = scenario.includeBoundedEnvelopes ? [attachmentHandoff()] : [];
+    const actionBrokerGrants = scenario.includeBoundedEnvelopes ? [actionBrokerGrant()] : [];
+    const messages = messagesFor(scenario.scenarioKey);
+    const dispatchPacket = {
+        chatRunId: ids.chatRunId,
+        conversationId: ids.conversationId,
+        turnId: ids.turnId,
+        leaseId: ids.leaseId,
+        fencingToken: ids.fencingToken,
+        runnerInstanceId: ids.runnerInstanceId,
+        providerKind: provider.providerKind,
+        model: provider.model,
+        messages,
+        contextRefs: [{
+                kind: "work_item",
+                refId: `bridge-cli-${scenario.scenarioKey}`,
+                title: "Bridge CLI deterministic conformance",
+                summary: "Fixture mapped to ChatAdapterConformanceCase fields.",
+                metadata: {
+                    adapterKind: "bridge-cli",
+                    runtimeKind: "managed-host",
+                    providerKind: provider.providerKind,
+                    scenarioKey: scenario.scenarioKey,
+                },
+            }],
+        idempotencyKey: `bridge-cli-${provider.providerKind}-${scenario.scenarioKey}`,
+        providerThreadId,
+        protocolVersion: bridgeChatProtocolVersion,
+        requestedCapabilities: scenario.requestedCapabilities,
+        attachmentHandoffs,
+        actionBrokerGrants,
+    };
+    return {
+        adapterKind: "bridge-cli",
+        runtimeKind: "managed-host",
+        providerKind: provider.providerKind,
+        capabilityFixture: {
+            fixtureKey: `${provider.providerKind}-managed-host-${scenario.scenarioKey}`,
+            runtimeState: provider.runtimeState,
+            supportedCapabilities: [
+                "text",
+                "cancel",
+                "resume",
+                "thread_continuity",
+                "attachment_handoffs",
+                "action_broker_grants",
+            ],
+            metadata: {
+                model: provider.model,
+                protocolVersion: bridgeChatProtocolVersion,
+            },
+            capability,
+        },
+        scenarioKey: scenario.scenarioKey,
+        inputTurn: {
+            turnKey: `${provider.providerKind}-${scenario.scenarioKey}`,
+            messages,
+            toolCalls: scenario.toolCalls ?? [],
+            requestedCapabilities: scenario.requestedCapabilities,
+            providerThreadId,
+            dispatchPacket,
+        },
+        expectedEvents: expectedEventsFor(scenario.terminalEventType),
+        expectedTerminalState: scenario.terminalState,
+        expectedSnapshotState: {
+            runtimeState: scenario.terminalState.state,
+            providerThreadId,
+            metadata: {
+                providerKind: provider.providerKind,
+                scenarioKey: scenario.scenarioKey,
+            },
+        },
+        prohibitedLogPatterns,
+        skipReason: null,
+        callbackEnvelope: callbackEnvelopeFor(dispatchPacket, scenario.terminalEventType, scenario.finalMessage),
+        providerStream: providerStreamFor(provider.providerKind, providerThreadId, scenario),
+        redactionSecrets,
+    };
+}
+function capabilityFor(providerKind, model, overrides = {}) {
+    return {
+        ...unavailableBridgeChatCapability(),
+        availability: "available",
+        supportedProviders: [providerKind],
+        supportedModels: [model],
+        supportsTextStreaming: true,
+        supportsCancel: true,
+        supportsResume: true,
+        supportsProviderThreadContinuity: true,
+        supportsAttachments: true,
+        supportsActionBrokerGrants: true,
+        maxMessageBytes: 128 * 1024,
+        maxContextRefs: 8,
+        ...overrides,
+    };
+}
+function messagesFor(scenarioKey) {
+    if (scenarioKey === "redaction") {
+        return [{
+                role: "user",
+                content: "Check redaction boundaries without exposing raw-provider-secret.",
+                metadata: { scenarioKey },
+            }];
+    }
+    return [{
+            role: "user",
+            content: `Run deterministic ${scenarioKey} conformance.`,
+            metadata: { scenarioKey },
+        }];
+}
+function expectedEventsFor(terminalEventType) {
+    const events = [{
+            sequence: 1,
+            adapterEventId: "bridge-cli-turn-started",
+            eventType: "turn_started",
+            payloadKey: "turn_started",
+        }];
+    if (terminalEventType === "output_completed") {
+        events.push({
+            sequence: 2,
+            adapterEventId: "bridge-cli-output-delta",
+            eventType: "output_delta",
+            payloadKey: "provider_message",
+        });
+    }
+    events.push({
+        sequence: events.length + 1,
+        adapterEventId: `bridge-cli-${terminalEventType}`,
+        eventType: terminalEventType,
+        payloadKey: terminalEventType,
+    });
+    return events;
+}
+function callbackEnvelopeFor(packet, eventType, finalMessage) {
+    return {
+        callbackId: ids.callbackId,
+        chatRunId: packet.chatRunId,
+        conversationId: packet.conversationId,
+        turnId: packet.turnId,
+        leaseId: packet.leaseId,
+        fencingToken: packet.fencingToken,
+        runnerId: ids.runnerId,
+        runnerInstanceId: packet.runnerInstanceId,
+        sequence: eventType === "output_completed" ? 3 : 2,
+        eventType,
+        redactionStatus: "redacted",
+        providerThreadId: packet.providerThreadId,
+        payload: {
+            code: eventType,
+            text: finalMessage ?? "",
+            provider: packet.providerKind,
+            model: packet.model,
+        },
+        occurredAt: "2026-09-26T12:00:00.000Z",
+        protocolVersion: bridgeChatProtocolVersion,
+    };
+}
+function providerStreamFor(providerKind, providerThreadId, scenario) {
+    if (providerKind === "cursor") {
+        const stdoutLines = [
+            JSON.stringify({ type: "system", subtype: "init", session_id: providerThreadId }),
+            ...(scenario.finalMessage
+                ? [JSON.stringify({
+                        type: "assistant",
+                        message: { role: "assistant", content: [{ type: "text", text: scenario.finalMessage }] },
+                    })]
+                : []),
+            JSON.stringify({ type: "result", subtype: "success", is_error: false, result: scenario.finalMessage ?? "" }),
+        ];
+        return {
+            stdoutLines,
+            expectedEventTypes: scenario.finalMessage
+                ? ["provider_thread_started", "provider_message"]
+                : ["provider_thread_started"],
+            expectedFinalMessage: scenario.finalMessage,
+        };
+    }
+    const stdoutLines = [
+        JSON.stringify({ type: "thread.started", thread_id: providerThreadId }),
+        ...(scenario.finalMessage
+            ? [JSON.stringify({ type: "item.completed", item: { type: "agent_message", text: scenario.finalMessage } })]
+            : []),
+        JSON.stringify({ type: "turn.completed" }),
+    ];
+    return {
+        stdoutLines,
+        expectedEventTypes: scenario.finalMessage
+            ? ["provider_thread_started", "provider_message", "provider_turn_completed"]
+            : ["provider_thread_started", "provider_turn_completed"],
+        expectedFinalMessage: scenario.finalMessage,
+    };
+}
+function attachmentHandoff() {
+    return {
+        turnId: ids.turnId,
+        attachmentId: ids.attachmentId,
+        tempFileToken: "opaque-temp-file-token",
+        mimeType: "text/plain",
+        sizeBytes: 123,
+        sha256: "a".repeat(64),
+        fileNameDisplay: "notes.txt",
+        expiresAt: deterministicExpiresAt,
+        status: "available",
+    };
+}
+function actionBrokerGrant() {
+    return {
+        grantId: ids.grantId,
+        turnId: ids.turnId,
+        leaseId: ids.leaseId,
+        fencingToken: ids.fencingToken,
+        allowedScopes: ["action_broker_grants", "text"],
+        nonce: "opaque-grant-nonce",
+        expiresAt: deterministicExpiresAt,
+        redactionStatus: "not_applicable",
+    };
+}
+function packetRecord(packet) {
+    return {
+        chatRunId: packet.chatRunId,
+        conversationId: packet.conversationId,
+        turnId: packet.turnId,
+        leaseId: packet.leaseId,
+        fencingToken: packet.fencingToken,
+        runnerInstanceId: packet.runnerInstanceId,
+        providerKind: packet.providerKind,
+        model: packet.model,
+        messages: packet.messages,
+        contextRefs: packet.contextRefs,
+        idempotencyKey: packet.idempotencyKey,
+        providerThreadId: packet.providerThreadId,
+        protocolVersion: packet.protocolVersion,
+        requestedCapabilities: packet.requestedCapabilities,
+        attachmentHandoffs: packet.attachmentHandoffs,
+        actionBrokerGrants: packet.actionBrokerGrants,
+    };
+}

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

@@ -0,0 +1,16 @@
+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 CiRepairLocalPreflightCommand[];
+export interface CiRepairLocalPreflightCommand {
+    readonly id: string;
+    readonly cwd: string;
+    readonly command: readonly string[];
+    readonly coverage: string;
+}
+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>;
+export declare function assertCiRepairPreflightContract(providerOnlySpecs: readonly string[], localPreflightCommands: readonly CiRepairLocalPreflightCommand[]): void;

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

@@ -0,0 +1,110 @@
+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 = [];
+export async function writeCiRepairReadinessManifest(dispatch, worktreePath, specPath, runtimeEnvironment) {
+    assertCiRepairPreflightContract(ciRepairProviderOnlySpecs, ciRepairLocalPreflightCommands);
+    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 disables its hosted reconciler and cannot exercise specs that require the live Bridge/runner control plane. Those specs remain authoritative in provider CI; attempt-local unit, contract, API, and browser coverage remains supported.",
+            policy: "Run every listed local_preflight_command. Treat every provider_only_specs pattern as unavailable in the managed attempt, do not override its exclusion or weaken provider CI, and record the provider check that supplies that proof 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 };
+}
+export function assertCiRepairPreflightContract(providerOnlySpecs, localPreflightCommands) {
+    const providerOnlyFileNames = new Set(providerOnlySpecs.map(fileName));
+    for (const preflight of localPreflightCommands) {
+        const conflictingArgument = preflight.command.find(argument => providerOnlyFileNames.has(fileName(argument)));
+        if (conflictingArgument) {
+            throw new Error(`ci_repair_readiness_invalid: local preflight '${preflight.id}' references provider-only spec '${conflictingArgument}'.`);
+        }
+    }
+}
+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, "/");
+}
+function fileName(candidate) {
+    return path.posix.basename(candidate.replaceAll("\\", "/"));
+}