@loucompanion/forge-bridge 0.1.3-dev.f2b8822ce953 → 0.1.3-dev.fbe15023cdfe

package/dist/session/managed-attempt-tools.js

@@ -0,0 +1,561 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { resetGeneratedOutputs } from "../runtime/generated-output-reset.js";
+import { StreamingProviderProcessRunner } from "./provider-cli/provider-cli.process.js";
+const managedCommandNames = new Set(["forge.run_managed_command", "run_managed_command"]);
+const startManagedCommandNames = new Set(["forge.start_managed_command", "start_managed_command"]);
+const getManagedCommandNames = new Set(["forge.get_managed_command", "get_managed_command"]);
+const waitManagedCommandNames = new Set(["forge.wait_managed_command", "wait_managed_command"]);
+const resetGeneratedOutputNames = new Set(["forge.reset_generated_outputs", "reset_generated_outputs"]);
+const maximumCapturedCharacters = 200_000;
+const maximumReturnedOutputCharacters = 12_000;
+const maximumReportedFailedTests = 50;
+const maximumSynchronousWaitMs = 240_000;
+const managedCommandLaunchTimeoutMs = 60_000;
+const managedCommandProgressPersistIntervalMs = 5_000;
+const managedCommandReceiptPollIntervalMs = 1_000;
+const managedCommandReceiptReplaceAttempts = 40;
+const managedCommandReceiptReplaceRetryMs = 25;
+const terminalManagedCommandStatuses = new Set([
+    "pass",
+    "fail",
+    "timed_out",
+    "timeout_termination_failed",
+    "runner_error",
+]);
+const managedCommandTasks = new Map();
+export const managedAttemptToolNames = [
+    "forge.run_managed_command",
+    "run_managed_command",
+    "forge.start_managed_command",
+    "start_managed_command",
+    "forge.get_managed_command",
+    "get_managed_command",
+    "forge.wait_managed_command",
+    "wait_managed_command",
+    "forge.reset_generated_outputs",
+    "reset_generated_outputs",
+];
+export function isManagedAttemptTool(name) {
+    return managedCommandNames.has(name)
+        || startManagedCommandNames.has(name)
+        || getManagedCommandNames.has(name)
+        || waitManagedCommandNames.has(name)
+        || resetGeneratedOutputNames.has(name);
+}
+export function managedAttemptToolDefinition(name) {
+    if (managedCommandNames.has(name) || startManagedCommandNames.has(name)) {
+        return {
+            name,
+            description: startManagedCommandNames.has(name)
+                ? "Start a long command in an attempt-owned process tree and return a durable command ID immediately. Continue independent work, then call forge.wait_managed_command once for its terminal receipt."
+                : "Run a short command in an attempt-owned process tree. Commands with a timeout above four minutes automatically start asynchronously; continue independent work, then call forge.wait_managed_command once for the durable result.",
+            inputSchema: {
+                type: "object",
+                additionalProperties: false,
+                required: ["command", "args"],
+                properties: {
+                    command: { type: "string", minLength: 1 },
+                    args: { type: "array", items: { type: "string" } },
+                    cwd: { type: "string", description: "Worktree-relative directory; defaults to the worktree root." },
+                    timeout_ms: { type: "integer", minimum: 1000, maximum: 7200000, default: 2700000 },
+                },
+            },
+        };
+    }
+    if (getManagedCommandNames.has(name)) {
+        return {
+            name,
+            description: "Read the durable status and final receipt for a command started by Forge's managed command runner.",
+            inputSchema: {
+                type: "object",
+                additionalProperties: false,
+                required: ["command_id"],
+                properties: {
+                    command_id: { type: "string", minLength: 1 },
+                },
+            },
+        };
+    }
+    if (waitManagedCommandNames.has(name)) {
+        return {
+            name,
+            description: "Wait for a command started by Forge's managed command runner to reach a terminal state. Use this once after completing work that is independent of the command; Forge streams durable progress while this call waits.",
+            inputSchema: {
+                type: "object",
+                additionalProperties: false,
+                required: ["command_id"],
+                properties: {
+                    command_id: { type: "string", minLength: 1 },
+                    wait_timeout_ms: { type: "integer", minimum: 1000, maximum: 7200000, default: 7200000 },
+                },
+            },
+        };
+    }
+    return {
+        name,
+        description: "Quarantine known untracked generated test-output directories into this attempt's private output directory.",
+        inputSchema: { type: "object", additionalProperties: false, properties: {} },
+    };
+}
+export async function callManagedAttemptTool(name, input, worktreePath) {
+    if (resetGeneratedOutputNames.has(name)) {
+        const outputDirectory = requiredAttemptEnvironment("FORGE_TEST_OUTPUT_DIR");
+        const result = await resetGeneratedOutputs(worktreePath, outputDirectory);
+        return {
+            content: [{
+                    type: "text",
+                    text: result.quarantinedPaths.length === 0
+                        ? "Forge found no stale generated output in the source worktree."
+                        : `Forge quarantined ${result.quarantinedPaths.length} generated-output director${result.quarantinedPaths.length === 1 ? "y" : "ies"}: ${result.quarantinedPaths.join(", ")}.`,
+                }],
+            structuredContent: {
+                status: "pass",
+                quarantined_paths: result.quarantinedPaths,
+                quarantine_directory: result.quarantineDirectory,
+            },
+        };
+    }
+    if (getManagedCommandNames.has(name)) {
+        return await readManagedCommand(input);
+    }
+    if (waitManagedCommandNames.has(name)) {
+        return await waitManagedCommand(input);
+    }
+    if (!managedCommandNames.has(name) && !startManagedCommandNames.has(name)) {
+        throw new Error(`Unknown managed attempt tool: ${name}`);
+    }
+    const record = asRecord(input);
+    const command = requiredInputString(record, "command");
+    const args = requiredStringArray(record, "args");
+    const timeoutMs = optionalTimeout(record.timeout_ms);
+    const cwd = await containedWorkingDirectory(worktreePath, record.cwd);
+    const logDirectory = requiredAttemptEnvironment("FORGE_LOG_DIR");
+    await fs.mkdir(path.join(logDirectory, "managed-commands"), { recursive: true, mode: 0o700 });
+    const commandId = randomUUID();
+    const metadataPath = path.join(logDirectory, "managed-commands", `${commandId}.json`);
+    const receiptPath = managedCommandReceiptPath(logDirectory, commandId);
+    const invocation = {
+        commandId,
+        command,
+        args,
+        cwd,
+        timeoutMs,
+        logDirectory,
+        metadataPath,
+        receiptPath,
+        startedAt: Date.now(),
+    };
+    if (startManagedCommandNames.has(name) || timeoutMs > maximumSynchronousWaitMs) {
+        const started = managedCommandResult({
+            ...invocation,
+            timedOut: false,
+            status: "starting",
+            exitCode: null,
+            stdout: "",
+            stderr: "",
+        });
+        await persistManagedCommandReceipt(receiptPath, started.structuredContent);
+        const task = executeManagedCommand(invocation);
+        managedCommandTasks.set(commandId, task);
+        void task.finally(() => managedCommandTasks.delete(commandId)).catch(() => undefined);
+        return {
+            ...started,
+            content: [{
+                    type: "text",
+                    text: `Forge managed command ${commandId} started asynchronously. Continue independent work, then call forge.wait_managed_command once with this command_id for the terminal receipt.`,
+                }],
+        };
+    }
+    return await executeManagedCommand(invocation);
+}
+async function executeManagedCommand(invocation) {
+    const environment = inheritedEnvironment({
+        FORGE_RUNTIME_MODE: "host",
+        FORGE_RESOURCE_LEASE_ID: requiredAttemptEnvironment("FORGE_RESOURCE_LEASE_ID"),
+        FORGE_DISPATCH_ATTEMPT_ID: requiredAttemptEnvironment("FORGE_DISPATCH_ATTEMPT_ID"),
+        // This nested command owns a distinct supervisor identity. A command-local
+        // fence avoids exposing the parent attempt's fencing capability to Codex's
+        // MCP subprocess configuration while preserving exact-tree cleanup proof.
+        FORGE_FENCING_TOKEN: randomUUID(),
+        FORGE_LOG_DIR: invocation.logDirectory,
+        FORGE_TEST_OUTPUT_DIR: requiredAttemptEnvironment("FORGE_TEST_OUTPUT_DIR"),
+        FORGE_PROCESS_SUPERVISOR_ID: `managed-${invocation.commandId.replaceAll("-", "")}`,
+        FORGE_PROCESS_SUPERVISOR_METADATA_PATH: invocation.metadataPath,
+    });
+    let stdout = "";
+    let stderr = "";
+    const controller = new AbortController();
+    let timedOut = false;
+    let timer = null;
+    let outputRevision = 0;
+    let lastOutputAt = null;
+    let lastProgressPersistedAt = 0;
+    let progressPersistence = Promise.resolve();
+    const launchTimer = setTimeout(() => {
+        timedOut = true;
+        controller.abort(new Error(`managed_command_launch_timeout: process supervisor was not ready within ${managedCommandLaunchTimeoutMs}ms.`));
+    }, managedCommandLaunchTimeoutMs);
+    try {
+        const result = await new StreamingProviderProcessRunner().run({
+            command: invocation.command,
+            args: invocation.args,
+            cwd: invocation.cwd,
+            env: environment,
+            captureOutput: false,
+        }, {
+            onStarted: async () => {
+                clearTimeout(launchTimer);
+                const running = managedCommandResult({
+                    ...invocation,
+                    timedOut: false,
+                    status: "running",
+                    exitCode: null,
+                    stdout,
+                    stderr,
+                    outputRevision,
+                    lastOutputAt,
+                });
+                await persistManagedCommandReceipt(invocation.receiptPath, running.structuredContent);
+                timer = setTimeout(() => {
+                    timedOut = true;
+                    controller.abort(new Error(`managed_command_timeout: exceeded ${invocation.timeoutMs}ms.`));
+                }, invocation.timeoutMs);
+            },
+            onStdoutLine: (line) => {
+                stdout = appendBounded(stdout, line);
+                outputRevision += 1;
+                lastOutputAt = Date.now();
+                progressPersistence = persistManagedCommandProgressIfDue(invocation, () => ({ stdout, stderr, outputRevision, lastOutputAt }), progressPersistence, () => lastProgressPersistedAt, value => { lastProgressPersistedAt = value; });
+                return progressPersistence;
+            },
+            onStderrLine: (line) => {
+                stderr = appendBounded(stderr, line);
+                outputRevision += 1;
+                lastOutputAt = Date.now();
+                progressPersistence = persistManagedCommandProgressIfDue(invocation, () => ({ stdout, stderr, outputRevision, lastOutputAt }), progressPersistence, () => lastProgressPersistedAt, value => { lastProgressPersistedAt = value; });
+                return progressPersistence;
+            },
+        }, controller.signal);
+        await progressPersistence;
+        const status = timedOut ? "timed_out" : result.exitCode === 0 ? "pass" : "fail";
+        const receipt = managedCommandResult({
+            ...invocation,
+            timedOut,
+            status,
+            exitCode: result.exitCode,
+            stdout,
+            stderr,
+            outputRevision,
+            lastOutputAt,
+        });
+        await persistManagedCommandReceipt(invocation.receiptPath, receipt.structuredContent);
+        return receipt;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        stderr = appendBounded(stderr, message);
+        const receipt = managedCommandResult({
+            ...invocation,
+            timedOut,
+            status: timedOut ? "timeout_termination_failed" : "runner_error",
+            exitCode: null,
+            stdout,
+            stderr,
+            outputRevision,
+            lastOutputAt,
+        });
+        await persistManagedCommandReceipt(invocation.receiptPath, receipt.structuredContent);
+        return receipt;
+    }
+    finally {
+        clearTimeout(launchTimer);
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+async function readManagedCommand(input) {
+    const commandId = validatedCommandId(asRecord(input));
+    const receiptPath = managedCommandReceiptPath(requiredAttemptEnvironment("FORGE_LOG_DIR"), commandId);
+    let receipt;
+    try {
+        receipt = JSON.parse(await fs.readFile(receiptPath, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new Error(`managed_command_not_found: no durable receipt exists for ${commandId}.`, { cause: error });
+        }
+        throw error;
+    }
+    const status = typeof receipt.status === "string" ? receipt.status : "unknown";
+    const stdout = typeof receipt.stdout === "string" ? receipt.stdout : "";
+    const stderr = typeof receipt.stderr === "string" ? receipt.stderr : "";
+    return {
+        content: [{
+                type: "text",
+                text: terminalManagedCommandStatuses.has(status)
+                    ? terminalManagedCommandText({
+                        commandId,
+                        status,
+                        exitCode: typeof receipt.exit_code === "number" ? receipt.exit_code : null,
+                        elapsedMs: typeof receipt.elapsed_ms === "number" ? receipt.elapsed_ms : null,
+                        stdout,
+                        stderr,
+                    })
+                    : `Forge managed command ${commandId} is ${status}. Continue independent work and use forge.wait_managed_command when ready for its terminal receipt.`,
+            }],
+        structuredContent: receipt,
+        isError: terminalManagedCommandStatuses.has(status) && status !== "pass",
+    };
+}
+async function waitManagedCommand(input) {
+    const record = asRecord(input);
+    const commandId = validatedCommandId(record);
+    const waitTimeoutMs = optionalWaitTimeout(record.wait_timeout_ms);
+    const deadline = Date.now() + waitTimeoutMs;
+    const receiptPath = managedCommandReceiptPath(requiredAttemptEnvironment("FORGE_LOG_DIR"), commandId);
+    const task = managedCommandTasks.get(commandId);
+    if (task) {
+        const result = await Promise.race([
+            task,
+            delay(waitTimeoutMs).then(() => null),
+        ]);
+        if (result)
+            return result;
+    }
+    while (Date.now() < deadline) {
+        const result = await readManagedCommand({ command_id: commandId });
+        if (terminalManagedCommandStatuses.has(String(result.structuredContent.status))) {
+            return result;
+        }
+        await delay(Math.min(managedCommandReceiptPollIntervalMs, Math.max(1, deadline - Date.now())));
+    }
+    const receipt = await readManagedCommand({ command_id: commandId });
+    return {
+        ...receipt,
+        content: [{
+                type: "text",
+                text: `Forge is still supervising managed command ${commandId} after waiting ${waitTimeoutMs}ms. Its durable receipt remains at ${receiptPath}.`,
+            }],
+    };
+}
+function managedCommandReceiptPath(logDirectory, commandId) {
+    return path.join(logDirectory, "managed-commands", `${commandId}.receipt.json`);
+}
+async function persistManagedCommandReceipt(receiptPath, receipt) {
+    const temporaryPath = `${receiptPath}.${randomUUID()}.tmp`;
+    await fs.writeFile(temporaryPath, `${JSON.stringify(receipt, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    try {
+        for (let attempt = 1;; attempt += 1) {
+            try {
+                await fs.rename(temporaryPath, receiptPath);
+                break;
+            }
+            catch (error) {
+                const code = error.code;
+                if (attempt >= managedCommandReceiptReplaceAttempts
+                    || (code !== "EPERM" && code !== "EBUSY" && code !== "EACCES")) {
+                    throw error;
+                }
+                await delay(managedCommandReceiptReplaceRetryMs);
+            }
+        }
+    }
+    finally {
+        await fs.rm(temporaryPath, { force: true }).catch(() => undefined);
+    }
+}
+function managedCommandResult(values) {
+    const elapsedMs = Date.now() - values.startedAt;
+    const isTerminal = terminalManagedCommandStatuses.has(values.status);
+    const diagnostics = isTerminal
+        ? managedCommandDiagnostics(values.stdout, values.stderr)
+        : undefined;
+    return {
+        content: [{
+                type: "text",
+                text: isTerminal
+                    ? terminalManagedCommandText({
+                        commandId: values.commandId,
+                        status: values.status,
+                        exitCode: values.exitCode,
+                        elapsedMs,
+                        stdout: values.stdout,
+                        stderr: values.stderr,
+                    }, diagnostics)
+                    : `Forge managed command ${values.commandId} is ${values.status} after ${elapsedMs}ms.`,
+            }],
+        structuredContent: {
+            command_id: values.commandId,
+            status: values.status,
+            command: [values.command, ...values.args],
+            cwd: values.cwd,
+            timeout_ms: values.timeoutMs,
+            elapsed_ms: elapsedMs,
+            started_at: new Date(values.startedAt).toISOString(),
+            timed_out: values.timedOut,
+            exit_code: values.exitCode,
+            stdout: values.stdout,
+            stderr: values.stderr,
+            ...(diagnostics ? { diagnostics } : {}),
+            output_truncated: values.stdout.length >= maximumCapturedCharacters
+                || values.stderr.length >= maximumCapturedCharacters,
+            output_revision: values.outputRevision ?? 0,
+            last_output_at: values.lastOutputAt ? new Date(values.lastOutputAt).toISOString() : null,
+            supervisor_metadata_path: values.metadataPath,
+            receipt_path: values.receiptPath,
+            process_tree_terminated: values.status === "timed_out" ? true : values.timedOut ? false : undefined,
+        },
+        isError: isTerminal && values.status !== "pass",
+    };
+}
+function persistManagedCommandProgressIfDue(invocation, snapshot, previousPersistence, lastPersistedAt, setLastPersistedAt) {
+    const now = Date.now();
+    if (now - lastPersistedAt() < managedCommandProgressPersistIntervalMs)
+        return previousPersistence;
+    setLastPersistedAt(now);
+    const current = snapshot();
+    return previousPersistence.then(async () => {
+        const receipt = managedCommandResult({
+            ...invocation,
+            timedOut: false,
+            status: "running",
+            exitCode: null,
+            ...current,
+        });
+        await persistManagedCommandReceipt(invocation.receiptPath, receipt.structuredContent);
+    });
+}
+async function containedWorkingDirectory(worktreePath, input) {
+    const root = await fs.realpath(path.resolve(worktreePath));
+    const relative = input === undefined ? "." : requiredStandaloneString(input, "cwd");
+    if (path.isAbsolute(relative))
+        throw new Error("managed_command_invalid: cwd must be worktree-relative.");
+    const target = await fs.realpath(path.resolve(root, relative));
+    const containment = path.relative(root, target);
+    if (containment.startsWith(`..${path.sep}`) || path.isAbsolute(containment)) {
+        throw new Error("managed_command_invalid: cwd resolves outside the source worktree.");
+    }
+    return target;
+}
+function inheritedEnvironment(overrides) {
+    const env = {};
+    for (const [key, value] of Object.entries(process.env)) {
+        if (typeof value === "string" && !looksSensitiveEnvironmentName(key))
+            env[key] = value;
+    }
+    return { ...env, ...overrides };
+}
+function looksSensitiveEnvironmentName(name) {
+    const normalized = name.trim().toUpperCase();
+    return normalized.includes("SECRET")
+        || normalized.includes("TOKEN")
+        || normalized.includes("PASSWORD")
+        || normalized.includes("CREDENTIAL")
+        || normalized.endsWith("_API_KEY")
+        || normalized === "OPENAI_API_KEY";
+}
+function requiredAttemptEnvironment(name) {
+    const value = process.env[name]?.trim();
+    if (!value)
+        throw new Error(`managed_attempt_tool_unavailable: ${name} is not configured.`);
+    return value;
+}
+function asRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("managed_command_invalid: input must be an object.");
+    return value;
+}
+function requiredInputString(record, name) {
+    return requiredStandaloneString(record[name], name);
+}
+function validatedCommandId(record) {
+    const commandId = requiredInputString(record, "command_id");
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu.test(commandId)) {
+        throw new Error("managed_command_invalid: command_id must be a UUID returned by Forge.");
+    }
+    return commandId;
+}
+function requiredStandaloneString(value, name) {
+    if (typeof value !== "string" || !value.trim())
+        throw new Error(`managed_command_invalid: ${name} is required.`);
+    return value.trim();
+}
+function requiredStringArray(record, name) {
+    const value = record[name];
+    if (!Array.isArray(value) || value.some(entry => typeof entry !== "string")) {
+        throw new Error(`managed_command_invalid: ${name} must be a string array.`);
+    }
+    return value;
+}
+function optionalTimeout(value) {
+    if (value === undefined)
+        return 2_700_000;
+    if (!Number.isSafeInteger(value) || value < 1_000 || value > 7_200_000) {
+        throw new Error("managed_command_invalid: timeout_ms must be an integer from 1000 through 7200000.");
+    }
+    return value;
+}
+function optionalWaitTimeout(value) {
+    if (value === undefined)
+        return 7_200_000;
+    if (!Number.isSafeInteger(value) || value < 1_000 || value > 7_200_000) {
+        throw new Error("managed_command_invalid: wait_timeout_ms must be an integer from 1000 through 7200000.");
+    }
+    return value;
+}
+async function delay(ms) {
+    await new Promise(resolve => setTimeout(resolve, ms));
+}
+function appendBounded(current, line) {
+    const next = `${current}${line}\n`;
+    return next.length <= maximumCapturedCharacters
+        ? next
+        : next.slice(-maximumCapturedCharacters);
+}
+function managedCommandDiagnostics(stdout, stderr) {
+    const lines = `${stdout}\n${stderr}`
+        .split(/\r?\n/u)
+        .map(line => line.trim())
+        .filter(Boolean);
+    const failedTests = new Set();
+    for (const line of lines) {
+        const xunit = line.match(/^\[xUnit\.net[^\]]*\]\s+(.+?)\s+\[FAIL\]$/u);
+        if (xunit?.[1])
+            failedTests.add(xunit[1].trim());
+        const vstest = line.match(/^Failed\s+(.+?)(?:\s+\[(?:\d|<).*)?$/u);
+        if (vstest?.[1] && !vstest[1].startsWith("!"))
+            failedTests.add(vstest[1].trim());
+    }
+    const summaryLines = lines
+        .filter(line => /(?:Failed!|Passed!|Test Run|Tests?:\s|Test Files|\[FAIL\]|error\s+[A-Z]+\d+)/iu.test(line))
+        .slice(-20);
+    return {
+        failed_tests: [...failedTests].slice(0, maximumReportedFailedTests),
+        failed_test_count: failedTests.size,
+        summary_lines: summaryLines,
+    };
+}
+function terminalManagedCommandText(values, diagnostics = managedCommandDiagnostics(values.stdout, values.stderr)) {
+    const failedTests = diagnostics.failed_tests;
+    const summaryLines = diagnostics.summary_lines;
+    const duration = values.elapsedMs === null ? "an unknown duration" : `${values.elapsedMs}ms`;
+    const sections = [
+        `Forge managed command ${values.commandId} ${values.status} after ${duration} (exit ${values.exitCode ?? "unavailable"}).`,
+    ];
+    if (failedTests.length > 0) {
+        sections.push(`Failed tests (${diagnostics.failed_test_count}):\n${failedTests.map(test => `- ${test}`).join("\n")}`);
+    }
+    if (summaryLines.length > 0) {
+        sections.push(`Test summary:\n${summaryLines.join("\n")}`);
+    }
+    const stdoutTail = tail(values.stdout, maximumReturnedOutputCharacters);
+    const stderrTail = tail(values.stderr, maximumReturnedOutputCharacters);
+    sections.push(`stdout tail:\n${stdoutTail || "(empty)"}`);
+    sections.push(`stderr tail:\n${stderrTail || "(empty)"}`);
+    return sections.join("\n\n");
+}
+function tail(value, maximumCharacters) {
+    return value.length <= maximumCharacters ? value : value.slice(-maximumCharacters);
+}

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

@@ -237,12 +237,19 @@ export async function writeQaGateCompletionArtifact(config, gate, input) {
     const status = normalizeQaGateStatus(requiredString(payload, "status"));
     validateQaGatePayloadShape(gate, payload, status);
     validateOptionalWorkItemId(payload, config.workItemId);
-    const redactedPayload = redactSecrets({ ...payload, status }, config.redactionSecrets ?? []);
+    const ownerFields = artifactOwnerFields(config);
+    const validatedSidecars = gate === "qa_manual_web"
+        ? await validateQaSidecarReferences(config.worktreePath, config.workItemId, qaArray(payload, "sidecars", qaEvidenceSource(payload)), ownerFields.owner_type, ownerFields.owner_id)
+        : null;
+    const redactedPayload = redactSecrets({
+        ...payload,
+        status,
+        ...(validatedSidecars ? { sidecars: validatedSidecars } : {})
+    }, config.redactionSecrets ?? []);
     const producedBy = optionalString(redactedPayload, "produced_by")
         ?? optionalString(redactedPayload, "producedBy")
         ?? config.producedBy
         ?? "forge-completion-tool";
-    const ownerFields = artifactOwnerFields(config);
     const artifactRoot = ownerFields.owner_type && ownerFields.owner_id
         ? artifactRootForOwner(config.worktreePath, ownerFields.owner_type, ownerFields.owner_id)
         : artifactRootFor(config.worktreePath, config.workItemId);
@@ -424,7 +431,7 @@ async function synthesizeQaCycleVerdictPayload(config, payload, status) {
     ]);
     merged.browser_checks = dedupeUnknownArray([
         ...qaArray(payload, "browser_checks", payloadEvidence),
-        ...evidenceGates.flatMap((gate) => qaArray(gate, "browser_checks"))
+        ...evidenceGates.flatMap((gate) => qaArray(gate, "browser_checks").map(normalizeInheritedQaBrowserCheck))
     ]);
     merged.sidecars = dedupeUnknownArray([
         ...qaArray(payload, "sidecars", payloadEvidence),
@@ -516,6 +523,27 @@ function dedupeStrings(values) {
     }
     return deduped;
 }
+function normalizeInheritedQaBrowserCheck(browserCheck) {
+    if (!browserCheck || typeof browserCheck !== "object" || Array.isArray(browserCheck)) {
+        return browserCheck;
+    }
+    const record = browserCheck;
+    if (optionalString(record, "summary")) {
+        return record;
+    }
+    const target = optionalString(record, "url") ?? optionalString(record, "route") ?? "the configured browser target";
+    const status = optionalString(record, "status") ?? "recorded";
+    return {
+        ...record,
+        summary: `Inherited browser check ${status} for ${target}.`
+    };
+}
+function normalizeSha256ContentHash(contentHash) {
+    const normalized = contentHash.trim().toLowerCase();
+    return normalized.startsWith("sha256:")
+        ? normalized.slice("sha256:".length)
+        : normalized;
+}
 async function validateQaSidecarReferences(worktreePath, workItemId, sidecars, ownerType, ownerId) {
     if (sidecars.length === 0) {
         return [];
@@ -557,7 +585,7 @@ async function validateQaSidecarReferences(worktreePath, workItemId, sidecars, o
             throw new Error(`sidecars[${index}].bytes does not match the referenced file.`);
         }
         const actualHash = await sha256File(fullPath);
-        if (actualHash !== contentHash.trim().toLowerCase()) {
+        if (actualHash !== normalizeSha256ContentHash(contentHash)) {
             throw new Error(`sidecars[${index}].content_hash does not match the referenced file.`);
         }
         validated.push({

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

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