@loucompanion/forge-bridge 0.1.3-dev.b6be5e7f9668 → 0.1.3-dev.ba293ccf876b

package/dist/session/pre-publication-validation.d.ts

@@ -0,0 +1,47 @@
+import type { ProviderProcessRunner } from "./provider-cli/provider-cli.process.js";
+import type { RunnerDispatchEvent } from "./session.types.js";
+export type PrePublicationProfile = "implementation" | "comment_repair" | "ci_repair" | "conflict_repair";
+interface ValidationStep {
+    readonly command: string;
+    readonly fallbackCommand?: string;
+    readonly args: readonly string[];
+    readonly fallbackArgs?: readonly string[];
+    readonly assertUnchangedPaths?: readonly string[];
+}
+interface ValidationCheck {
+    readonly id: string;
+    readonly profiles: readonly string[];
+    readonly changedPathPatterns: readonly string[];
+    readonly requiredCapability?: string;
+    readonly providerOnly?: boolean;
+    readonly steps: readonly ValidationStep[];
+}
+interface ValidationContract {
+    readonly schemaVersion: number;
+    readonly contractId: string;
+    readonly checks: readonly ValidationCheck[];
+}
+export interface PrePublicationCommandResult {
+    readonly exitCode: number;
+    readonly stdout?: string;
+    readonly stderr?: string;
+}
+export interface PrePublicationCommandRunner {
+    run(command: string, args: readonly string[], cwd: string, signal?: AbortSignal, environment?: Readonly<Record<string, string>>): Promise<PrePublicationCommandResult>;
+}
+export interface PrePublicationExecutionContext {
+    readonly baselineRevision?: string;
+    readonly environment?: Readonly<Record<string, string>>;
+    readonly processRunner?: ProviderProcessRunner;
+}
+export declare class PrePublicationValidator {
+    private readonly commands;
+    constructor(commands?: PrePublicationCommandRunner);
+    validate(worktreePath: string, profile: PrePublicationProfile, capabilities: ReadonlySet<string>, emit?: (event: RunnerDispatchEvent) => Promise<void>, signal?: AbortSignal, execution?: PrePublicationExecutionContext): Promise<readonly string[]>;
+    private changedPaths;
+    private runStep;
+    private runCommand;
+}
+export declare function applicableChecks(contract: ValidationContract, profile: PrePublicationProfile | "github_actions", changedPaths: readonly string[]): readonly ValidationCheck[];
+export declare function loadValidationContract(worktreePath: string): Promise<ValidationContract | null>;
+export {};

package/dist/session/pre-publication-validation.js

@@ -0,0 +1,249 @@
+import { execFile } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const contractRelativePath = ".forge/validation/ci-parity.v1.json";
+const requiredCheckIds = new Set([
+    "file-size-inventory",
+    "owned-suite-registration",
+    "dotnet-build-and-unit",
+    "openapi-and-generated-types",
+    "client",
+    "bridge",
+    "playwright-e2e",
+    "github-provider-policy",
+]);
+const approvedContractDigest = "014727b066b2b659b8772987650b85540f1bf70864c678187fde108a9b1d84d3";
+class ProcessPrePublicationCommandRunner {
+    async run(command, args, cwd, signal, environment) {
+        try {
+            const windowsBatch = process.platform === "win32" && (command === "npm" || command === "pnpm");
+            const executable = windowsBatch ? (process.env.ComSpec ?? "cmd.exe") : command;
+            const commandArgs = windowsBatch
+                ? ["/d", "/s", "/c", [`${command}.cmd`, ...args].map(quoteWindowsCommandArgument).join(" ")]
+                : [...args];
+            const result = await execFileAsync(executable, commandArgs, {
+                cwd,
+                encoding: "utf8",
+                maxBuffer: 4 * 1024 * 1024,
+                signal,
+                env: environment ? { ...process.env, ...environment } : process.env,
+            });
+            return { exitCode: 0, stdout: result.stdout, stderr: result.stderr };
+        }
+        catch (error) {
+            const failure = error;
+            if (failure.name === "AbortError")
+                throw error;
+            if (failure.code === "ENOENT") {
+                return { exitCode: 127, stderr: `executable_not_found: ${command}` };
+            }
+            return {
+                exitCode: typeof failure.code === "number" ? failure.code : 1,
+                stdout: failure.stdout,
+                stderr: failure.stderr ?? failure.message,
+            };
+        }
+    }
+}
+function quoteWindowsCommandArgument(value) {
+    return /^[A-Za-z0-9_./:@=-]+$/u.test(value) ? value : `"${value.replaceAll('"', '""')}"`;
+}
+export class PrePublicationValidator {
+    commands;
+    constructor(commands = new ProcessPrePublicationCommandRunner()) {
+        this.commands = commands;
+    }
+    async validate(worktreePath, profile, capabilities, emit, signal, execution) {
+        const contract = await loadValidationContract(worktreePath);
+        if (contract === null) {
+            await emit?.(validationEvent("prepublication_validation_legacy_contract", "legacy-provider-validation", `This checkout predates ${contractRelativePath}; Bridge preserved legacy provider validation without source mutation.`));
+            return [];
+        }
+        const scoped = await prepareValidationExecution(execution);
+        try {
+            const changedPaths = await this.changedPaths(worktreePath, signal, scoped.execution);
+            const selected = applicableChecks(contract, profile, changedPaths);
+            const completed = [];
+            for (const check of selected) {
+                if (check.providerOnly) {
+                    await emit?.(validationEvent("prepublication_validation_provider_only", check.id, `Preserved provider-only validation '${check.id}' for the provider check run.`));
+                    continue;
+                }
+                if (check.requiredCapability && !capabilities.has(check.requiredCapability)) {
+                    throw new Error(`prepublication_capability_unavailable: ${check.id} requires ${check.requiredCapability}; publication is holding until a capable runner is available.`);
+                }
+                await emit?.(validationEvent("prepublication_validation_started", check.id, `Running pre-publication CI parity check '${check.id}'.`));
+                for (const step of check.steps) {
+                    const result = await this.runStep(check.id, step, worktreePath, signal, scoped.execution);
+                    if (result.exitCode !== 0) {
+                        const detail = diagnosticDetail(result);
+                        await emit?.(validationEvent("prepublication_validation_failed", check.id, `Pre-publication CI parity check '${check.id}' exited ${result.exitCode}${detail ? `: ${detail}` : "."}`));
+                        throw new Error(`prepublication_validation_failed: ${check.id} exited ${result.exitCode}${detail ? `: ${detail}` : ""}`);
+                    }
+                }
+                completed.push(check.id);
+                await emit?.(validationEvent("prepublication_validation_passed", check.id, `Pre-publication CI parity check '${check.id}' passed.`));
+            }
+            return completed;
+        }
+        finally {
+            await scoped.cleanup();
+        }
+    }
+    async changedPaths(worktreePath, signal, execution) {
+        const baselineRevision = execution?.baselineRevision?.trim();
+        const requests = [
+            ["diff", "--name-only", "HEAD", "--"],
+            ...(baselineRevision ? [["diff", "--name-only", `${baselineRevision}..HEAD`, "--"]] : []),
+            ["status", "--porcelain=v1", "--untracked-files=all"],
+        ];
+        const paths = new Set();
+        for (const args of requests) {
+            const result = await this.runCommand("git", args, worktreePath, signal, execution);
+            if (result.exitCode !== 0) {
+                throw new Error(`prepublication_validation_failed: unable to inventory changed paths: ${result.stderr ?? result.stdout ?? "git failed"}`);
+            }
+            for (const line of `${result.stdout ?? ""}`.split(/\r?\n/u).filter(Boolean)) {
+                const raw = args[0] === "status" ? line.slice(3).split(" -> ").at(-1) ?? "" : line;
+                const normalized = raw.trim().replaceAll("\\", "/");
+                if (normalized)
+                    paths.add(normalized);
+            }
+        }
+        return [...paths];
+    }
+    async runStep(checkId, step, cwd, signal, execution) {
+        const invocation = managedAttemptInvocation(checkId, step, execution?.environment);
+        const before = await readValidationFiles(cwd, step.assertUnchangedPaths ?? []);
+        const result = await this.runCommand(invocation.command, invocation.args, cwd, signal, execution);
+        if (result.exitCode === 127 && step.fallbackCommand) {
+            const fallback = await this.runCommand(step.fallbackCommand, step.fallbackArgs ?? step.args, cwd, signal, execution);
+            return await assertValidationFilesUnchanged(cwd, before, fallback);
+        }
+        return await assertValidationFilesUnchanged(cwd, before, result);
+    }
+    async runCommand(command, args, cwd, signal, execution) {
+        if (execution?.processRunner) {
+            const result = await execution.processRunner.run({
+                command,
+                args,
+                cwd,
+                env: execution.environment,
+                captureOutput: true,
+            }, undefined, signal);
+            return { exitCode: result.exitCode, stdout: result.stdout, stderr: result.stderr };
+        }
+        return await this.commands.run(command, args, cwd, signal, execution?.environment);
+    }
+}
+function managedAttemptInvocation(checkId, step, environment) {
+    const playwrightConfig = environment?.FORGE_PLAYWRIGHT_CONFIG?.trim();
+    const attemptOwned = environment?.FORGE_E2E_OWNERSHIP_MODE === "attempt"
+        || Boolean(environment?.FORGE_DISPATCH_ATTEMPT_ID?.trim());
+    if (checkId !== "playwright-e2e" || !attemptOwned) {
+        return step;
+    }
+    if (!playwrightConfig) {
+        throw new Error("prepublication_capability_unavailable: playwright-e2e requires the Bridge-generated FORGE_PLAYWRIGHT_CONFIG for a managed attempt.");
+    }
+    return {
+        command: "pnpm",
+        args: ["--dir", "tests/e2e", "exec", "playwright", "test", "--config", playwrightConfig],
+    };
+}
+function diagnosticDetail(result) {
+    return [result.stderr, result.stdout]
+        .map(value => value?.trim() ?? "")
+        .filter(Boolean)
+        .join("\n")
+        .slice(-1600);
+}
+async function prepareValidationExecution(execution) {
+    if (process.platform !== "win32" || !execution) {
+        return { execution, cleanup: async () => undefined };
+    }
+    const systemDrive = process.env.SystemDrive?.trim() || "C:";
+    const configuredRoot = execution.environment?.FORGE_VALIDATION_TEMP_ROOT?.trim();
+    const root = configuredRoot || path.win32.join(systemDrive, "ForgeValidationTmp");
+    const temporaryRoot = path.win32.join(root, `${process.pid}-${randomUUID().slice(0, 8)}`);
+    await fs.mkdir(temporaryRoot, { recursive: true });
+    return {
+        execution: {
+            ...execution,
+            environment: {
+                ...execution.environment,
+                TEMP: temporaryRoot,
+                TMP: temporaryRoot,
+                TMPDIR: temporaryRoot,
+            },
+        },
+        cleanup: async () => {
+            await fs.rm(temporaryRoot, { recursive: true, force: true });
+        },
+    };
+}
+async function readValidationFiles(cwd, relativePaths) {
+    const values = new Map();
+    for (const relativePath of relativePaths) {
+        values.set(relativePath, await fs.readFile(path.join(cwd, relativePath), "utf8"));
+    }
+    return values;
+}
+async function assertValidationFilesUnchanged(cwd, before, result) {
+    if (result.exitCode !== 0)
+        return result;
+    for (const [relativePath, original] of before) {
+        const current = await fs.readFile(path.join(cwd, relativePath), "utf8");
+        if (current !== original) {
+            return {
+                exitCode: 1,
+                stderr: `generated_drift: ${relativePath} changed during validation; regenerate and review it before publication.`,
+            };
+        }
+    }
+    return result;
+}
+export function applicableChecks(contract, profile, changedPaths) {
+    return contract.checks.filter(check => check.profiles.includes(profile)
+        && changedPaths.some(changedPath => check.changedPathPatterns.some(pattern => new RegExp(pattern, "u").test(changedPath))));
+}
+export async function loadValidationContract(worktreePath) {
+    let source;
+    try {
+        source = await fs.readFile(path.join(worktreePath, contractRelativePath), "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    const contract = JSON.parse(source);
+    const ids = new Set(contract.checks?.map(check => check.id));
+    const contractDigest = createHash("sha256")
+        .update(JSON.stringify(canonicalizeJson(contract)))
+        .digest("hex");
+    if (contract.schemaVersion !== 1
+        || contract.contractId !== "forge-ci-parity-v1"
+        || contractDigest !== approvedContractDigest
+        || requiredCheckIds.size !== ids.size
+        || [...requiredCheckIds].some(id => !ids.has(id))
+        || contract.checks.some(check => !check.id || !Array.isArray(check.steps) || !Array.isArray(check.changedPathPatterns))) {
+        throw new Error(`prepublication_contract_invalid: the Forge CI parity contract does not match the approved definition (digest ${contractDigest}, expected ${approvedContractDigest}).`);
+    }
+    return contract;
+}
+function canonicalizeJson(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalizeJson);
+    if (value !== null && typeof value === "object") {
+        const record = value;
+        return Object.fromEntries(Object.keys(record).sort().map(key => [key, canonicalizeJson(record[key])]));
+    }
+    return value;
+}
+function validationEvent(eventType, checkId, content) {
+    return { role: "runner", kind: "checkpoint", content, eventType, data: JSON.stringify({ checkId, contractId: "forge-ci-parity-v1" }) };
+}

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("\\", "/"));
+}

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

@@ -0,0 +1,94 @@
+import { GitClient } from "../../shared/git/git.js";
+import { type CompletionPhase, type CompletionToolRuntime, type DebugCompletionPhase, type QaCompletionGate } from "../phase-completion.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>;
+export declare function fileExists(filePath: string): Promise<boolean>;
+export declare function summarizeStderr(stderr: string): string;
+export declare function waitForCompletionArtifact(worktreePath: string, workItemId: string, phase: "draft" | "decompose", signal?: AbortSignal): Promise<RunnerDispatchArtifact>;
+export declare function delay(ms: number, signal?: AbortSignal): Promise<void>;
+export declare function cleanupCompletionTools(completionTools: CompletionToolRuntime, emit: ProviderCliRunContext["emit"]): Promise<void>;
+export declare function commitWorktreeChanges(git: GitClient, worktreePath: string, workItemId: string): Promise<{
+    readonly commitSha: string;
+    readonly changedFiles: readonly string[];
+}>;
+export declare function phaseCompleteEventType(phase: CompletionPhase): string;
+export declare function isDebugCompletionPhaseForProvider(phase: CompletionPhase): phase is DebugCompletionPhase;
+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): 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;
+    readonly path: string;
+    readonly status: string;
+    readonly producedBy?: string;
+    readonly contentHash?: string;
+}
+export declare function qaArtifactRootForDispatch(worktreePath: string, workItemId: string, dispatch: RunOnceDispatchPacket): string;
+export declare function readQaGateArtifact(artifactRoot: string, gate: QaCompletionGate): Promise<QaGateArtifactSnapshot | null>;
+export declare function nextQaGate(gate: QaCompletionGate): QaCompletionGate | null;
+export declare function emitQaGateAccepted(emit: ProviderCliRunContext["emit"], worktreePath: string, artifact: QaGateArtifactSnapshot, nextGate: QaCompletionGate | null): Promise<void>;
+export declare class LiveQaArtifactEmitter {
+    private readonly worktreePath;
+    private readonly workItemId;
+    private readonly dispatch;
+    private readonly emit;
+    private emittedBundle;
+    private readonly emittedGates;
+    private timer;
+    private pending;
+    constructor(worktreePath: string, workItemId: string, dispatch: RunOnceDispatchPacket, emit: ProviderCliRunContext["emit"]);
+    start(): void;
+    stop(): Promise<void>;
+    hasEmitted(): boolean;
+    private pollQueued;
+    private poll;
+    private emitAvailableGateEvents;
+}
+export declare class LiveArchitectArtifactEmitter {
+    private readonly worktreePath;
+    private readonly workItemId;
+    private readonly emit;
+    private emitted;
+    private timer;
+    private pending;
+    constructor(worktreePath: string, workItemId: string, emit: ProviderCliRunContext["emit"]);
+    start(): void;
+    stop(): Promise<void>;
+    hasEmitted(): boolean;
+    private pollQueued;
+    private poll;
+}
+export declare function hasCompleteArchitectArtifactBundle(worktreePath: string, workItemId: string): Promise<boolean>;
+export declare function emitArchitectStructuredEvents(emit: ProviderCliRunContext["emit"], worktreePath: string, workItemId: string, artifact: RunnerDispatchArtifact): Promise<void>;
+export declare function readJsonObjectFile(filePath: string): Promise<Record<string, unknown>>;
+export declare function arrayField(source: Record<string, unknown>, key: string): Record<string, unknown>[];
+export declare function stringArrayField(source: Record<string, unknown>, key: string): string[];
+export declare function summarizeQaObject(source: Record<string, unknown>): string;
+export declare function qaArtifactRelativePath(workItemId: string, fileName: string, ownerType?: string | null, ownerId?: string | null): string;
+export declare function emitCompletionArtifactRecorded(emit: ProviderCliRunContext["emit"], worktreePath: string, artifact: RunnerDispatchArtifact): Promise<void>;
+export declare function emitPhaseCompletionEvent(emit: ProviderCliRunContext["emit"], artifact: RunnerDispatchArtifact): Promise<void>;
+export declare function emitPhaseGateEvents(emit: ProviderCliRunContext["emit"], artifact: RunnerDispatchArtifact): Promise<void>;
+export declare function completionPhaseFromArtifact(artifact: RunnerDispatchArtifact): CompletionPhase;
+export declare class LiveCompletionArtifactEmitter {
+    private readonly worktreePath;
+    private readonly workItemId;
+    private readonly emit;
+    private readonly phases;
+    private readonly emitted;
+    private timer;
+    private pending;
+    constructor(worktreePath: string, workItemId: string, phase: CompletionPhase, developCycle: boolean, debugCycle: boolean, emit: ProviderCliRunContext["emit"]);
+    start(): void;
+    stop(): Promise<void>;
+    hasEmitted(phase: CompletionPhase): boolean;
+    private pollQueued;
+    private poll;
+}
+export declare function readCompletionArtifactsForRun(worktreePath: string, workItemId: string, phase: CompletionPhase, developCycle: boolean, debugCycle: boolean): Promise<RunnerDispatchArtifact[]>;
+export {};