@loucompanion/forge-bridge 0.1.1-dev.03b8ba168599 → 0.1.1-dev.0b87deed581c

package/dist/cli/cli.service.js

@@ -4,10 +4,13 @@ import os from "node:os";
 import path from "node:path";
 import { createInterface } from "node:readline/promises";
 import { promisify } from "node:util";
+import { resolveCursorAgentDirectLaunch } from "../shared/cursor-agent/cursor-agent.launch.js";
 import { redactSecrets, redactText } from "../shared/redaction/redaction.js";
 import { defaultBridgeServiceConfig, ForgeBridgeService } from "../bridge/bridge.service.js";
+import { forgeBridgeVersion } from "../version.js";
 import { addRepoMapping, applyLocalConfigDefaults, providerStatusesFor, readLocalConfigSync, removeRepoMapping, resolveLocalConfigPath, writeLocalConfig } from "./local-config.js";
 import { BridgeSessionService } from "../session/session.service.js";
+import { parseCompletionMcpArgs, runCompletionMcpServer } from "../session/phase-completion.js";
 import { failureResult, parseRunOnceDispatchPacket } from "../session/session.types.js";
 const apiKeySecretGrantEnv = "FORGE_API_KEY_SECRET_GRANT";
 const execFileAsync = promisify(execFile);
@@ -21,6 +24,22 @@ export class ForgeBridgeCliService {
         this.pairRunner = pairRunner;
     }
     async run(argv, io = { stdout: process.stdout, stderr: process.stderr }) {
+        if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
+            io.stdout.write(helpText());
+            return 0;
+        }
+        if (argv[0] === "help") {
+            io.stdout.write(argv[1] ? commandHelpText(argv[1]) : helpText());
+            return 0;
+        }
+        if (argv[1] === "--help" || argv[1] === "-h") {
+            io.stdout.write(commandHelpText(argv[0]));
+            return 0;
+        }
+        if (argv[0] === "version" || argv[0] === "--version" || argv[0] === "-v") {
+            io.stdout.write(`forge-bridge ${defaultBridgeServiceConfig().version ?? forgeBridgeVersion}\n`);
+            return 0;
+        }
         const args = parseArgs(argv);
         if (!args.ok) {
             io.stderr.write(`${args.error}\n`);
@@ -42,6 +61,7 @@ export class ForgeBridgeCliService {
             process.once("SIGINT", stop);
             process.once("SIGTERM", stop);
             try {
+                io.stdout.write(connectStartupText(config));
                 await this.bridgeFactory(config).run(controller.signal);
                 return 0;
             }
@@ -102,6 +122,15 @@ export class ForgeBridgeCliService {
         if (args.command === "cleanup") {
             return await cleanupRepos(args.config, args.mode, args.force, io);
         }
+        if (args.command === "mcp") {
+            const parsed = parseCompletionMcpArgs(args.argv);
+            if (!parsed.ok) {
+                io.stderr.write(`${parsed.error}\n`);
+                return 2;
+            }
+            await runCompletionMcpServer(parsed.config);
+            return 0;
+        }
         let redactionSecrets = readEnvSecretValuesForRedaction();
         try {
             const dispatchJson = await fs.readFile(args.dispatchPath, "utf8");
@@ -165,19 +194,23 @@ function parseEnvSecretGrant(raw) {
     };
 }
 function exactSecrets(dispatch) {
-    return dispatch.apiKeySecretGrant?.secret ? [dispatch.apiKeySecretGrant.secret] : [];
+    return exactSecretValues(dispatch.apiKeySecretGrant?.secret, process.env.FORGE_DEVICE_TOKEN);
 }
 function readEnvSecretValuesForRedaction() {
+    const secrets = [];
     const raw = process.env[apiKeySecretGrantEnv];
-    if (!raw) {
-        return [];
-    }
-    try {
-        return [parseEnvSecretGrant(raw).secret];
-    }
-    catch {
-        return [];
+    if (raw) {
+        try {
+            secrets.push(parseEnvSecretGrant(raw).secret);
+        }
+        catch {
+            // Ignore malformed grant env here; command handling will report the parse error.
+        }
     }
+    return exactSecretValues(...secrets, process.env.FORGE_DEVICE_TOKEN);
+}
+function exactSecretValues(...values) {
+    return values.filter((value) => typeof value === "string" && value.length > 0);
 }
 export function parseArgs(argv) {
     if (argv[0] === "connect") {
@@ -214,6 +247,9 @@ export function parseArgs(argv) {
     if (argv[0] === "cleanup") {
         return parseCleanupArgs(argv);
     }
+    if (argv[0] === "mcp") {
+        return { ok: true, command: "mcp", argv };
+    }
     if (argv[0] !== "run-once") {
         return {
             ok: false,
@@ -460,6 +496,7 @@ function pairedConfig(current, args, claim) {
         supportsManagedWorktrees: current.supportsManagedWorktrees ?? true,
         supportsManagedForgeArtifacts: current.supportsManagedForgeArtifacts ?? true,
         supportsRunnerAuthoredPhaseArtifacts: current.supportsRunnerAuthoredPhaseArtifacts ?? true,
+        supportsDraftRunOnce: current.supportsDraftRunOnce ?? true,
         repoMappings: current.repoMappings ?? []
     };
 }
@@ -508,7 +545,199 @@ function normalizeServerUrl(serverUrl) {
     return serverUrl.endsWith("/") ? serverUrl : `${serverUrl}/`;
 }
 function usage() {
-    return "Usage: forge-bridge run-once --dispatch <dispatch-json-path> --result <result-json-path> | forge-bridge pair [code] [--server <url>] | forge-bridge connect --server <url> --runner-id <id> --device-token <token> | forge-bridge add-repo <label> <path> | forge-bridge remove-repo <label> | forge-bridge status [--check-updates] | forge-bridge cleanup [--stale|--merged|--all|--force]";
+    return helpText();
+}
+function helpText() {
+    const version = defaultBridgeServiceConfig().version ?? forgeBridgeVersion;
+    return [
+        `🛠 Forge Bridge ${version} — Local provider runners for Forge.`,
+        "",
+        "Usage: forge-bridge [options] [command]",
+        "",
+        "Options:",
+        "  -h, --help       Display help for command",
+        "  -v, --version    Output the version number",
+        "",
+        "Commands:",
+        "  Hint: commands suffixed with * have detailed help. Run <command> --help for details.",
+        "  connect *        Start the runner bridge and wait for Forge dispatches",
+        "  pair *           Pair this machine with Forge and save runner credentials",
+        "  status *         Show config, runner identity, repos, provider CLIs, and updates",
+        "  add-repo *       Map a Forge repo label/name to a local checkout path",
+        "  remove-repo *    Remove a saved repo mapping",
+        "  cleanup *        Prune managed bridge worktrees",
+        "  version *        Print the installed bridge package version",
+        "  help *           Display help for command",
+        "  run-once *       Internal: run one dispatch packet from JSON",
+        "  mcp *            Internal: run the phase-completion MCP server",
+        "",
+        "Examples:",
+        "  npm install -g @loucompanion/forge-bridge@next",
+        "  forge-bridge pair 1234-5678 --server https://srv1493013.tail66073d.ts.net:8443 --repo-root \"%USERPROFILE%\\ForgeRepos\"",
+        "  forge-bridge connect",
+        "  forge-bridge status --check-updates",
+        "  forge-bridge add-repo Forge D:\\Programming\\repos\\Forge",
+        "  forge-bridge cleanup --stale",
+        "",
+        "Troubleshooting:",
+        "  If Forge says the bridge is old: npm install -g @loucompanion/forge-bridge@next",
+        "  If connect shows 502/500: leave it open; it reconnects with backoff while dev restarts.",
+        "  If a provider is missing: run forge-bridge status --check-updates and verify CLI login.",
+        "",
+        "Docs:",
+        "  https://github.com/coleman399/Forge/tree/develop/tools/forge-bridge#readme",
+        "",
+    ].join("\n");
+}
+function commandHelpText(command) {
+    switch (command) {
+        case "pair":
+            return [
+                "Forge Bridge — pair",
+                "Pair this machine with Forge and save runner credentials.",
+                "",
+                "Usage:",
+                "  forge-bridge pair [code] [options]",
+                "",
+                "Options:",
+                "  --server <url>              Forge server URL.",
+                "  --repo-root <path>          Folder where bridge-managed repos/worktrees live.",
+                "  --name <name>               Display name for this runner.",
+                "  --fingerprint <value>       Stable device fingerprint override.",
+                "  --cli-provider <list>       Comma-separated providers, e.g. codex,cursor.",
+                "  --cleanup-worktrees         Enable managed worktree cleanup.",
+                "  --no-cleanup-worktrees      Disable managed worktree cleanup.",
+                "",
+                "Example:",
+                "  forge-bridge pair 1234-5678 --server https://forge.example.com --repo-root \"%USERPROFILE%\\ForgeRepos\"",
+                "",
+            ].join("\n");
+        case "connect":
+            return [
+                "Forge Bridge — connect",
+                "Start the runner bridge and keep it connected for Forge dispatches.",
+                "",
+                "Usage:",
+                "  forge-bridge connect [options]",
+                "",
+                "Options:",
+                "  --server <url>              Forge server URL; saved config is used when omitted.",
+                "  --runner-id <id>            Runner id; saved config is used when omitted.",
+                "  --device-token <token>      Device token; saved config is used when omitted.",
+                "  --repo-root <path>          Override repo/worktree folder for this run.",
+                "  --cli-provider <list>       Comma-separated providers, e.g. codex,cursor.",
+                "  --heartbeat-interval-ms <n> Heartbeat interval in milliseconds.",
+                "  --cleanup-worktrees         Enable managed worktree cleanup for this run.",
+                "  --no-cleanup-worktrees      Disable managed worktree cleanup for this run.",
+                "",
+                "Example:",
+                "  forge-bridge connect",
+                "",
+            ].join("\n");
+        case "status":
+            return [
+                "Forge Bridge — status",
+                "Show saved configuration, paired runner identity, repo mappings, detected provider CLIs, and optional update info.",
+                "",
+                "Usage:",
+                "  forge-bridge status [--check-updates]",
+                "",
+                "Example:",
+                "  forge-bridge status --check-updates",
+                "",
+            ].join("\n");
+        case "add-repo":
+            return [
+                "Forge Bridge — add-repo",
+                "Map a Forge repo label/name to an existing local checkout.",
+                "",
+                "Usage:",
+                "  forge-bridge add-repo <label> <path>",
+                "",
+                "Example:",
+                "  forge-bridge add-repo Forge D:\\Programming\\repos\\Forge",
+                "",
+            ].join("\n");
+        case "remove-repo":
+            return [
+                "Forge Bridge — remove-repo",
+                "Remove a saved local repo mapping.",
+                "",
+                "Usage:",
+                "  forge-bridge remove-repo <label>",
+                "",
+            ].join("\n");
+        case "cleanup":
+            return [
+                "Forge Bridge — cleanup",
+                "Prune managed bridge worktrees under the configured repo folder.",
+                "",
+                "Usage:",
+                "  forge-bridge cleanup [--stale|--merged|--all] [--force]",
+                "",
+                "Examples:",
+                "  forge-bridge cleanup --stale",
+                "  forge-bridge cleanup --all --force",
+                "",
+            ].join("\n");
+        case "run-once":
+            return [
+                "Forge Bridge — run-once",
+                "Internal command used by Forge to run a single dispatch packet.",
+                "",
+                "Usage:",
+                "  forge-bridge run-once --dispatch <dispatch-json-path> --result <result-json-path>",
+                "",
+            ].join("\n");
+        case "mcp":
+            return [
+                "Forge Bridge — mcp",
+                "Internal MCP server used by provider CLIs to report Forge phase artifacts.",
+                "",
+                "Usage:",
+                "  forge-bridge mcp --worktree <path> --work-item-id <id> --phase <phase>",
+                "",
+            ].join("\n");
+        case "version":
+            return [
+                "Forge Bridge — version",
+                "Print the installed bridge package version.",
+                "",
+                "Usage:",
+                "  forge-bridge version",
+                "",
+            ].join("\n");
+        default:
+            return [
+                `Unknown forge-bridge command: ${command}`,
+                "",
+                "Run `forge-bridge help` to see available commands.",
+                "",
+            ].join("\n");
+    }
+}
+function connectStartupText(config) {
+    const runner = config.runnerId
+        ? `${config.runnerId}${config.deviceName ? ` (${config.deviceName})` : ""}`
+        : "not configured";
+    return [
+        `Forge Bridge ${config.version}`,
+        "Starting runner bridge...",
+        "",
+        "Startup:",
+        `  server: ${config.serverUrl || "not configured"}`,
+        `  runner: ${runner}`,
+        `  config: ${resolveLocalConfigPath()}`,
+        `  repo folder: ${config.defaultRepoRoot || "not configured"}`,
+        `  providers: ${formatList(config.cliProviders)}`,
+        `  cleanup worktrees: ${config.cleanupWorktrees ? "enabled" : "disabled"}`,
+        "",
+        "Press Ctrl+C to stop.",
+        "",
+    ].join("\n");
+}
+function formatList(values) {
+    return values.length > 0 ? values.join(", ") : "none";
 }
 async function writeJsonAtomic(outputPath, value) {
     await fs.mkdir(path.dirname(outputPath), { recursive: true });
@@ -620,6 +849,12 @@ function cliProbeCommandsFor(provider) {
     ];
 }
 async function execVersionCommand(probe, timeout = 2000) {
+    const directLaunch = process.platform === "win32"
+        ? await resolveCursorAgentDirectLaunch(probe.command, probe.args)
+        : null;
+    if (directLaunch) {
+        return await execFileAsync(directLaunch.command, [...directLaunch.args], { timeout });
+    }
     try {
         return await execFileAsync(probe.command, probe.args, { timeout });
     }

package/dist/cli/local-config.d.ts

@@ -16,6 +16,7 @@ export interface BridgeLocalConfig {
     readonly supportsManagedWorktrees?: boolean;
     readonly supportsManagedForgeArtifacts?: boolean;
     readonly supportsRunnerAuthoredPhaseArtifacts?: boolean;
+    readonly supportsDraftRunOnce?: boolean;
 }
 export interface LocalRepoMapping extends BridgeRepoMapping {
     readonly label: string;

package/dist/cli/local-config.js

@@ -49,11 +49,12 @@ export function applyLocalConfigDefaults(config, local) {
         providerStatuses: normalizeProviderStatuses(local.providerStatuses) ?? providerStatusesFor(cliProviders),
         projectLabels: local.projectLabels ?? config.projectLabels,
         repoMappings: local.repoMappings ?? config.repoMappings,
-        sandboxProfiles: local.sandboxProfiles ?? config.sandboxProfiles,
+        sandboxProfiles: normalizeSandboxProfiles(local.sandboxProfiles ?? config.sandboxProfiles, cliProviders) ?? config.sandboxProfiles,
         supportsApiSecretGrant: local.supportsApiSecretGrant ?? config.supportsApiSecretGrant,
         supportsManagedWorktrees: local.supportsManagedWorktrees ?? config.supportsManagedWorktrees,
         supportsManagedForgeArtifacts: local.supportsManagedForgeArtifacts ?? config.supportsManagedForgeArtifacts,
-        supportsRunnerAuthoredPhaseArtifacts: local.supportsRunnerAuthoredPhaseArtifacts ?? config.supportsRunnerAuthoredPhaseArtifacts
+        supportsRunnerAuthoredPhaseArtifacts: local.supportsRunnerAuthoredPhaseArtifacts ?? config.supportsRunnerAuthoredPhaseArtifacts,
+        supportsDraftRunOnce: local.supportsDraftRunOnce ?? config.supportsDraftRunOnce
     };
 }
 export async function addRepoMapping(label, repoPath) {
@@ -111,7 +112,8 @@ function normalizeLocalConfig(config) {
         supportsApiSecretGrant: config.supportsApiSecretGrant,
         supportsManagedWorktrees: config.supportsManagedWorktrees,
         supportsManagedForgeArtifacts: config.supportsManagedForgeArtifacts,
-        supportsRunnerAuthoredPhaseArtifacts: config.supportsRunnerAuthoredPhaseArtifacts
+        supportsRunnerAuthoredPhaseArtifacts: config.supportsRunnerAuthoredPhaseArtifacts,
+        supportsDraftRunOnce: config.supportsDraftRunOnce
     };
 }
 function emptyConfig() {
@@ -149,6 +151,19 @@ function splitCsv(value) {
         .map((entry) => entry.trim())
         .filter((entry) => entry.length > 0);
 }
+function normalizeSandboxProfiles(profiles, cliProviders) {
+    const normalized = cleanList(profiles);
+    if (process.platform === "win32"
+        && cliProviders.some((provider) => provider.toLowerCase() === "codex")
+        && normalized?.some((profile) => profile.toLowerCase() === "provider-workspace-write")
+        && !normalized.some((profile) => profile.toLowerCase() === "danger-full-access")) {
+        return [
+            ...normalized.filter((profile) => profile.toLowerCase() !== "provider-workspace-write"),
+            "danger-full-access"
+        ];
+    }
+    return normalized;
+}
 function normalizeRepoMappings(values) {
     return (values ?? [])
         .filter((mapping) => !!mapping.label?.trim() && !!mapping.localPath?.trim())
@@ -159,7 +174,8 @@ function normalizeRepoMappings(values) {
             repoId: cleanString(mapping.repoId),
             name: cleanString(mapping.name) ?? label,
             remoteUrl: cleanString(mapping.remoteUrl),
-            localPath: path.resolve(mapping.localPath)
+            localPath: path.resolve(mapping.localPath),
+            qaAppLaunchTarget: normalizeQaAppLaunchTarget(mapping.qaAppLaunchTarget)
         };
     })
         .sort((left, right) => left.label.localeCompare(right.label));
@@ -171,6 +187,22 @@ function normalizeLabel(value) {
     }
     return label;
 }
+function normalizeQaAppLaunchTarget(value) {
+    if (!value)
+        return undefined;
+    const routes = cleanList(value.routes);
+    const normalized = {
+        url: cleanString(value.url),
+        command: cleanString(value.command),
+        working_directory: cleanString(value.working_directory),
+        ready_url: cleanString(value.ready_url),
+        routes,
+        notes: cleanString(value.notes)
+    };
+    return normalized.url || normalized.command || normalized.ready_url || routes?.length
+        ? normalized
+        : undefined;
+}
 function cleanString(value) {
     const clean = value?.trim();
     return clean ? clean : undefined;

package/dist/config.js

@@ -2,7 +2,7 @@ import os from "node:os";
 import path from "node:path";
 export function defaultForgeBridgeConfig() {
     return {
-        defaultRepoRoot: path.join(os.tmpdir(), "forge-phase5-repos"),
+        defaultRepoRoot: path.join(os.tmpdir(), "forge-repos"),
         cleanupWorktrees: true
     };
 }

package/dist/session/index.d.ts

@@ -1,2 +1,4 @@
 export { BridgeSessionService } from "./session.service.js";
+export { buildCompletionToolServerArgs, codexMcpConfigArgs, completionPhaseFromDispatch, expectedCompletionToolName, prepareCompletionToolRuntime, readCompletionArtifact, writeCompletionArtifact } from "./phase-completion.js";
+export type { CompletionArtifactReference, CompletionPhase, CompletionToolRuntime } from "./phase-completion.js";
 export type { SessionService } from "./session.base.js";

package/dist/session/index.js

@@ -1 +1,2 @@
 export { BridgeSessionService } from "./session.service.js";
+export { buildCompletionToolServerArgs, codexMcpConfigArgs, completionPhaseFromDispatch, expectedCompletionToolName, prepareCompletionToolRuntime, readCompletionArtifact, writeCompletionArtifact } from "./phase-completion.js";

package/dist/session/internals.d.ts

@@ -1,6 +1,8 @@
 export { parseRunOnceDispatchPacket, failureResult } from "./session.types.js";
+export { buildCompletionToolServerArgs, codexMcpConfigArgs, completionPhaseFromDispatch, expectedCompletionToolName, prepareCompletionToolRuntime, readCompletionArtifact, writeCompletionArtifact } from "./phase-completion.js";
+export type { CompletionArtifactReference, CompletionPhase, CompletionToolRuntime } from "./phase-completion.js";
 export type { SessionEventSink, SessionService } from "./session.base.js";
-export type { ApiKeySecretGrant, DispatchCycleRun, DispatchExecution, DispatchLease, DispatchSession, DispatchRepo, DispatchServerLocalConfig, DispatchWorkItem, RunOnceDispatchPacket, RunOnceResultPacket, RunnerDispatchArtifact, RunnerDispatchEvent, RunnerDispatchSpec, RunnerEventLine } from "./session.types.js";
+export type { ApiKeySecretGrant, DispatchCycleRun, DispatchExecution, DispatchLease, DispatchPullRequestContext, DispatchSession, DispatchRepo, DispatchServerLocalConfig, DispatchWorkItem, RunOnceDispatchPacket, RunOnceResultPacket, RunnerDispatchArtifact, RunnerDispatchEvent, RunnerDispatchSpec, RunnerEventLine } from "./session.types.js";
 export { DeterministicProviderCliService, ProcessBackedProviderCliService, RoutingProviderCliService, buildProviderCliCommand } from "./provider-cli/provider-cli.service.js";
 export type { ProviderCliService } from "./provider-cli/provider-cli.base.js";
 export type { ProviderCliCommand, ProviderProcessRunner, ProviderProcessRunRequest, ProviderProcessRunResult } from "./provider-cli/provider-cli.service.js";

package/dist/session/internals.js

@@ -1,2 +1,3 @@
 export { parseRunOnceDispatchPacket, failureResult } from "./session.types.js";
+export { buildCompletionToolServerArgs, codexMcpConfigArgs, completionPhaseFromDispatch, expectedCompletionToolName, prepareCompletionToolRuntime, readCompletionArtifact, writeCompletionArtifact } from "./phase-completion.js";
 export { DeterministicProviderCliService, ProcessBackedProviderCliService, RoutingProviderCliService, buildProviderCliCommand } from "./provider-cli/provider-cli.service.js";

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

@@ -0,0 +1,126 @@
+import type { RunOnceDispatchPacket, RunnerDispatchArtifact } from "./session.types.js";
+import type { WorktreeHandle } from "../worktree/worktree.types.js";
+export type DevelopCompletionPhase = "implementation" | "self_review" | "validation";
+export type DebugCompletionPhase = "debug_repro" | "debug_root_cause" | "debug_fix" | "debug_regression";
+export type ArchitectCompletionPhase = "architect";
+export type DraftCompletionPhase = "draft";
+export type CompletionPhase = DevelopCompletionPhase | "qa" | DebugCompletionPhase | ArchitectCompletionPhase | DraftCompletionPhase;
+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 interface CompletionToolRuntime {
+    readonly serverName: string;
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly env: Readonly<Record<string, string>>;
+    readonly cursorMcpConfigPath?: string | null;
+    cleanup(): Promise<void>;
+}
+export interface CompletionToolRuntimeOptions {
+    readonly dispatch: RunOnceDispatchPacket;
+    readonly worktree: WorktreeHandle;
+    readonly phase?: CompletionPhase;
+}
+export interface CompletionToolServerConfig {
+    readonly worktreePath: string;
+    readonly workItemId: string;
+    readonly ownerType?: string;
+    readonly ownerId?: string;
+    readonly phase: CompletionPhase;
+    readonly producedBy?: string;
+    readonly redactionSecrets?: readonly string[];
+    readonly developCycle?: boolean;
+    readonly qaCycle?: boolean;
+    readonly debugCycle?: boolean;
+    readonly architectCycle?: boolean;
+    readonly draftCycle?: boolean;
+}
+export interface CompletionToolCallResult {
+    readonly content: readonly {
+        readonly type: "text";
+        readonly text: string;
+    }[];
+    readonly structuredContent: CompletionArtifactReference & {
+        readonly gate: {
+            readonly phase: CompletionPhase;
+            readonly qaGate?: QaCompletionGate;
+            readonly draftGate?: DraftCompletionGate;
+            readonly status: string;
+            readonly allowed: boolean;
+            readonly reason: string;
+        };
+        readonly nextPhase: CompletionPhase | "dev_test_ready" | "qa_ready" | "sign_off_ready";
+        readonly nextInstruction: string;
+    };
+}
+export interface CompletionArtifactReference {
+    readonly phase: CompletionPhase;
+    readonly workItemId: string;
+    readonly ownerType?: string;
+    readonly ownerId?: string;
+    readonly repoPath: string;
+    readonly path: string;
+    readonly reportPath: string;
+    readonly contentHash: string;
+    readonly status: string;
+    readonly producedBy: string;
+}
+export declare const debugCompletionPhaseOrder: readonly DebugCompletionPhase[];
+export declare const qaCompletionGateOrder: readonly QaCompletionGate[];
+export declare const draftCompletionGateOrder: readonly DraftCompletionGate[];
+export declare function completionPhaseFromDispatch(dispatch: RunOnceDispatchPacket): CompletionPhase;
+export declare function normalizeCompletionPhase(value: string | null | undefined): CompletionPhase;
+export declare function usesDevelopCycleCompletion(dispatch: RunOnceDispatchPacket): boolean;
+export declare function usesQaCycleCompletion(dispatch: RunOnceDispatchPacket): boolean;
+export declare function usesDebugCycleCompletion(dispatch: RunOnceDispatchPacket): boolean;
+export declare function usesArchitectCycleCompletion(dispatch: RunOnceDispatchPacket): boolean;
+export declare function completionToolNamesForPhase(phase: CompletionPhase): readonly string[];
+export declare function completionToolNamesForQaGate(gate: QaCompletionGate): readonly string[];
+export declare function completionToolNamesForDebugGate(gate: DebugCompletionPhase): readonly string[];
+export declare function completionToolNamesForDraftGate(gate: DraftCompletionGate): readonly string[];
+export declare function expectedCompletionToolName(phase: CompletionPhase): string;
+export declare function expectedQaCompletionToolName(gate: QaCompletionGate): string;
+export declare function expectedDebugCompletionToolName(gate: DebugCompletionPhase): string;
+export declare function expectedDraftCompletionToolName(gate: DraftCompletionGate): string;
+export declare function artifactRootFor(worktreePath: string, workItemId: string): string;
+export declare function artifactRootForOwner(worktreePath: string, ownerType: string, ownerId: string): string;
+export declare function completionArtifactJsonPath(worktreePath: string, workItemId: string, phase: CompletionPhase, ownerType?: string | null, ownerId?: string | null): string;
+export declare function completionArtifactReportPath(worktreePath: string, workItemId: string, phase: CompletionPhase, ownerType?: string | null, ownerId?: string | null): string;
+export declare function prepareCompletionToolRuntime(options: CompletionToolRuntimeOptions): Promise<CompletionToolRuntime>;
+export declare function buildCompletionToolServerArgs(config: CompletionToolServerConfig): readonly string[];
+export declare function codexMcpConfigArgs(runtime: CompletionToolRuntime): readonly string[];
+export declare function cursorMcpServerConfig(runtime: CompletionToolRuntime): unknown;
+export declare function completionPromptForPhase(phase: CompletionPhase): string;
+export declare function completionPromptForDevelopCycle(phase: CompletionPhase): string;
+export declare function completionPromptForQaCycle(currentGate?: QaCompletionGate): string;
+export declare function completionPromptForDraftCycle(currentGate?: DraftCompletionGate): string;
+export declare function completionPromptForDebugCycle(currentGate?: DebugCompletionPhase): string;
+export declare function completionToolNamesForServer(config: CompletionToolServerConfig): readonly string[];
+export declare class CompletionToolServerSession {
+    private readonly config;
+    private currentPhase;
+    private currentQaGate;
+    private currentDraftGate;
+    private completed;
+    constructor(config: CompletionToolServerConfig);
+    get instructions(): string;
+    toolDefinitions(): readonly unknown[];
+    callTool(toolName: string, input: unknown): Promise<CompletionToolCallResult>;
+    private callDraftGateTool;
+    private callDebugGateTool;
+    private callQaGateTool;
+    private advanceAfterPass;
+    private advanceAfterDraftGate;
+    private advanceAfterQaGate;
+    private advanceAfterDebugGate;
+}
+export declare function writeCompletionArtifact(config: CompletionToolServerConfig, toolName: string, input: unknown): Promise<CompletionArtifactReference>;
+export declare function readCompletionArtifact(worktreePath: string, workItemId: string, phase: CompletionPhase, ownerType?: string | null, ownerId?: string | null): Promise<RunnerDispatchArtifact | null>;
+export declare function runCompletionMcpServer(config: CompletionToolServerConfig): Promise<void>;
+export declare function parseCompletionMcpArgs(argv: readonly string[]): {
+    readonly ok: true;
+    readonly config: CompletionToolServerConfig;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+export declare function completionRedactionEnv(secrets: readonly string[]): Readonly<Record<string, string>>;