@loucompanion/forge-bridge 0.1.1-dev.2ac58b6f94ce → 0.1.1-dev.2d1a116ca78d

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

@@ -1,5 +1,6 @@
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 import { execFile, spawn } from "node:child_process";
 import readline from "node:readline";
@@ -8,11 +9,140 @@ import { GitClient } from "../../shared/git/git.js";
 import { resolveCursorAgentDirectLaunch } from "../../shared/cursor-agent/cursor-agent.launch.js";
 import { ensureNoSymbolicLinkPathSegments, isPathUnderRoot, sha256File } from "../qa-sidecar-validation.js";
 import { buildSpecBody, selectLaneCommand } from "../../worktree/artifact-injector.js";
-import { codexMcpConfigArgs, completionPhaseFromDispatch, completionPromptForDevelopCycle, completionPromptForPhase, completionPromptForQaCycle, completionRedactionEnv, expectedCompletionToolName, expectedQaCompletionToolName, prepareCompletionToolRuntime, readCompletionArtifact, usesDevelopCycleCompletion, writeCompletionArtifact, artifactRootFor, qaCompletionGateOrder } from "../phase-completion.js";
+import { codexMcpConfigArgs, completionPhaseFromDispatch, completionPromptForDebugCycle, completionPromptForDevelopCycle, completionPromptForPhase, completionPromptForQaCycle, completionRedactionEnv, expectedCompletionToolName, expectedDebugCompletionToolName, expectedQaCompletionToolName, prepareCompletionToolRuntime, readCompletionArtifact, usesDebugCycleCompletion, usesDevelopCycleCompletion, writeCompletionArtifact, artifactRootFor, artifactRootForOwner, debugCompletionPhaseOrder, qaCompletionGateOrder } from "../phase-completion.js";
 import { addUsage, buildProviderUsageEvent, emptyUsage, hasUsage, readUsageNumber } from "./provider-usage.js";
 const fakeWorkerModel = "server-local-fake-worker";
 const execFileAsync = promisify(execFile);
 const developCyclePhaseOrder = ["implementation", "self_review", "validation"];
+const allowedProviderParentEnvNames = [
+    "PATH",
+    "HOME",
+    "USERPROFILE",
+    "TMPDIR",
+    "TEMP",
+    "TMP",
+    "LANG"
+];
+const windowsAllowedProviderParentEnvNames = [
+    "SystemRoot",
+    "SystemDrive",
+    "ComSpec",
+    "PATHEXT",
+    "APPDATA",
+    "LOCALAPPDATA",
+    "USERNAME",
+    "USERDOMAIN",
+    "HOMEDRIVE",
+    "HOMEPATH",
+    "ProgramData",
+    "ProgramFiles",
+    "ProgramFiles(x86)",
+    "ProgramW6432",
+    "DOTNET_ROOT",
+    "DOTNET_ROOT(x86)",
+    "DOTNET_CLI_HOME",
+    "NUGET_PACKAGES",
+    "NUGET_HTTP_CACHE_PATH"
+];
+export function buildProviderChildEnvironment(requestEnv, options = {}) {
+    const parentEnv = options.parentEnv ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const env = {};
+    for (const [key, value] of Object.entries(parentEnv)) {
+        if (typeof value === "string" && isAllowedProviderParentEnv(key, platform)) {
+            env[key] = value;
+        }
+    }
+    if (requestEnv) {
+        for (const [key, value] of Object.entries(requestEnv)) {
+            const trimmedKey = key.trim();
+            if (trimmedKey.length > 0) {
+                env[trimmedKey] = value;
+            }
+        }
+    }
+    if (platform === "win32") {
+        normalizeWindowsDotNetEnvironment(env, parentEnv, options.homeDir ?? os.homedir());
+    }
+    return env;
+}
+function isAllowedProviderParentEnv(key, platform = process.platform) {
+    return isAllowedProviderParentEnvName(key, allowedProviderParentEnvNames)
+        || key.toUpperCase().startsWith("LC_")
+        || (platform === "win32" && isAllowedProviderParentEnvName(key, windowsAllowedProviderParentEnvNames));
+}
+function isAllowedProviderParentEnvName(key, allowedNames) {
+    return allowedNames.some((allowed) => allowed.toLowerCase() === key.toLowerCase());
+}
+function normalizeWindowsDotNetEnvironment(env, parentEnv, homeDir) {
+    const systemRoot = readEnvironmentValue(env, "SystemRoot") ?? readEnvironmentValue(parentEnv, "SystemRoot") ?? "C:\\Windows";
+    const systemDrive = path.win32.parse(systemRoot).root.replace(/\\$/, "") || "C:";
+    setEnvironmentValueIfMissing(env, "SystemRoot", systemRoot);
+    setEnvironmentValueIfMissing(env, "SystemDrive", readEnvironmentValue(parentEnv, "SystemDrive") ?? systemDrive);
+    setEnvironmentValueIfMissing(env, "ComSpec", readEnvironmentValue(parentEnv, "ComSpec") ?? path.win32.join(systemRoot, "System32", "cmd.exe"));
+    setEnvironmentValueIfMissing(env, "PATHEXT", readEnvironmentValue(parentEnv, "PATHEXT") ?? ".COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.MSC;.CPL");
+    const userProfile = resolveWindowsUserProfile(env, parentEnv, homeDir);
+    if (userProfile) {
+        setEnvironmentValueIfMissing(env, "USERPROFILE", userProfile);
+        setEnvironmentValueIfMissing(env, "HOME", userProfile);
+        setEnvironmentValueIfMissing(env, "DOTNET_CLI_HOME", userProfile);
+        setEnvironmentValueIfMissing(env, "NUGET_PACKAGES", path.win32.join(userProfile, ".nuget", "packages"));
+        const parsed = path.win32.parse(userProfile);
+        if (parsed.root) {
+            setEnvironmentValueIfMissing(env, "HOMEDRIVE", parsed.root.replace(/\\$/, ""));
+            setEnvironmentValueIfMissing(env, "HOMEPATH", userProfile.slice(parsed.root.length - (parsed.root.endsWith("\\") ? 1 : 0)) || "\\");
+        }
+    }
+    const appData = readEnvironmentValue(env, "APPDATA")
+        ?? readEnvironmentValue(parentEnv, "APPDATA")
+        ?? (userProfile ? path.win32.join(userProfile, "AppData", "Roaming") : undefined);
+    const localAppData = readEnvironmentValue(env, "LOCALAPPDATA")
+        ?? readEnvironmentValue(parentEnv, "LOCALAPPDATA")
+        ?? (userProfile ? path.win32.join(userProfile, "AppData", "Local") : undefined);
+    if (appData) {
+        setEnvironmentValueIfMissing(env, "APPDATA", appData);
+    }
+    if (localAppData) {
+        setEnvironmentValueIfMissing(env, "LOCALAPPDATA", localAppData);
+        setEnvironmentValueIfMissing(env, "NUGET_HTTP_CACHE_PATH", path.win32.join(localAppData, "NuGet", "v3-cache"));
+    }
+    setEnvironmentValueIfMissing(env, "DOTNET_NOLOGO", "1");
+    setEnvironmentValueIfMissing(env, "DOTNET_CLI_TELEMETRY_OPTOUT", "1");
+    setEnvironmentValueIfMissing(env, "DOTNET_SKIP_FIRST_TIME_EXPERIENCE", "1");
+    setEnvironmentValueIfMissing(env, "NUGET_XMLDOC_MODE", "skip");
+}
+function resolveWindowsUserProfile(env, parentEnv, homeDir) {
+    const existing = readEnvironmentValue(env, "USERPROFILE") ?? readEnvironmentValue(parentEnv, "USERPROFILE");
+    if (existing) {
+        return existing;
+    }
+    const home = readEnvironmentValue(env, "HOME") ?? readEnvironmentValue(parentEnv, "HOME");
+    if (home && path.win32.isAbsolute(home)) {
+        return home;
+    }
+    const homeDrive = readEnvironmentValue(env, "HOMEDRIVE") ?? readEnvironmentValue(parentEnv, "HOMEDRIVE");
+    const homePath = readEnvironmentValue(env, "HOMEPATH") ?? readEnvironmentValue(parentEnv, "HOMEPATH");
+    if (homeDrive && homePath) {
+        return `${homeDrive}${homePath}`;
+    }
+    if (homeDir && path.win32.isAbsolute(homeDir)) {
+        return homeDir;
+    }
+    const systemDrive = readEnvironmentValue(env, "SystemDrive") ?? readEnvironmentValue(parentEnv, "SystemDrive") ?? "C:";
+    const username = readEnvironmentValue(env, "USERNAME") ?? readEnvironmentValue(parentEnv, "USERNAME");
+    return username ? path.win32.join(systemDrive, "Users", username) : undefined;
+}
+function readEnvironmentValue(env, name) {
+    const entry = Object.entries(env).find(([key]) => key.toLowerCase() === name.toLowerCase());
+    const value = entry?.[1];
+    return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+function setEnvironmentValueIfMissing(env, name, value) {
+    if (readEnvironmentValue(env, name)) {
+        return;
+    }
+    env[name] = value;
+}
 export class RoutingProviderCliService {
     realProvider;
     deterministicProvider;
@@ -25,6 +155,11 @@ export class RoutingProviderCliService {
             ? await this.deterministicProvider.runImplementation(context)
             : await this.realProvider.runImplementation(context);
     }
+    async runArchitect(context) {
+        return isFakeWorkerModel(context.dispatch.execution.model)
+            ? await this.deterministicProvider.runArchitect(context)
+            : await this.realProvider.runArchitect(context);
+    }
     async runConflictResolve(context) {
         return isFakeWorkerModel(context.dispatch.execution.model)
             ? await this.deterministicProvider.runConflictResolve(context)
@@ -35,6 +170,11 @@ export class RoutingProviderCliService {
             ? await this.deterministicProvider.runQa(context)
             : await this.realProvider.runQa(context);
     }
+    async runDraft(context) {
+        return isFakeWorkerModel(context.dispatch.execution.model)
+            ? await this.deterministicProvider.runDraft(context)
+            : await this.realProvider.runDraft(context);
+    }
 }
 export class ProcessBackedProviderCliService {
     processRunner;
@@ -43,10 +183,74 @@ export class ProcessBackedProviderCliService {
         this.processRunner = processRunner;
         this.git = git;
     }
+    async runDraft(context) {
+        const { dispatch } = context;
+        if (!dispatch.draft) {
+            throw new Error("Draft dispatch context is missing.");
+        }
+        const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "forge-bridge-draft-"));
+        const command = buildProviderCliCommand(dispatch, {
+            worktreePath: tempDir,
+            prompt: buildDraftPrompt(dispatch),
+            skipGitRepoCheck: true
+        });
+        const draftArtifactSlugs = dispatch.artifacts
+            .filter((artifact) => artifact.scope === "operational" && ["command", "skill", "hook"].includes(artifact.kind))
+            .map((artifact) => `${artifact.kind}:${artifact.slug}`);
+        await context.emit({
+            role: "runner",
+            kind: "checkpoint",
+            content: `Draft artifacts injected: ${draftArtifactSlugs.length}${draftArtifactSlugs.length ? ` (${draftArtifactSlugs.join(", ")})` : ""}. Project: ${dispatch.draft.projectName ?? dispatch.repo.name}. Repo: ${dispatch.draft.repoName ?? dispatch.repo.name}.`,
+            eventType: "draft_artifacts_injected"
+        });
+        await context.emit({
+            role: "runner",
+            kind: "checkpoint",
+            content: `Starting provider CLI Draft: ${formatProviderCliCommand(command)}`,
+            eventType: "provider_cli_started"
+        });
+        const outputState = createProviderOutputState(dispatch.execution.provider);
+        try {
+            const result = await this.processRunner.run({
+                command: command.command,
+                args: command.args,
+                cwd: tempDir,
+                env: providerProcessEnv(dispatch)
+            }, {
+                onStdoutLine: async (line) => {
+                    for (const event of outputState.consume(line)) {
+                        await context.emit(event);
+                    }
+                }
+            }, context.signal);
+            if (result.exitCode !== 0) {
+                throw new Error(`Provider CLI exited with code ${result.exitCode}${summarizeStderr(result.stderr)}.`);
+            }
+            const content = outputState.finalMessage ?? result.stdout.trim();
+            if (!content) {
+                throw new Error("Provider CLI completed without returning a draft.");
+            }
+            const json = extractJsonObject(content);
+            await context.emit({
+                role: "assistant",
+                kind: "message",
+                content: json,
+                eventType: "draft_complete"
+            });
+            await emitProviderUsageEvent(context.emit, dispatch, outputState);
+            return {
+                summary: "Draft generated through Forge Runner."
+            };
+        }
+        finally {
+            await fs.rm(tempDir, { recursive: true, force: true });
+        }
+    }
     async runImplementation(context) {
         const { dispatch, worktree } = context;
         const phase = completionPhaseFromDispatch(dispatch);
         const developCycle = usesDevelopCycleCompletion(dispatch);
+        const debugCycle = usesDebugCycleCompletion(dispatch);
         const metadataRoot = path.join(worktree.worktreePath, ".forge", "work-items", dispatch.workItem.id);
         await fs.mkdir(metadataRoot, { recursive: true });
         const laneCommand = selectLaneCommand(dispatch.artifacts, dispatch.execution.lane, dispatch.cycleRun.phase);
@@ -60,7 +264,11 @@ export class ProcessBackedProviderCliService {
         const completionTools = await prepareCompletionToolRuntime({ dispatch, worktree, phase });
         const command = buildProviderCliCommand(dispatch, {
             worktreePath: worktree.worktreePath,
-            prompt: developCycle ? buildDevelopCyclePrompt(dispatch, phase) : buildImplementationPrompt(dispatch, phase),
+            prompt: debugCycle
+                ? buildDebugCyclePrompt(dispatch, phase)
+                : developCycle
+                    ? buildDevelopCyclePrompt(dispatch, phase)
+                    : buildImplementationPrompt(dispatch, phase),
             completionTools
         });
         await context.emit({
@@ -72,13 +280,15 @@ export class ProcessBackedProviderCliService {
         await context.emit({
             role: "runner",
             kind: "checkpoint",
-            content: developCycle
-                ? "Forge completion tools configured for implementation -> self_review -> validation; provider must call each MCP completion tool before exit."
-                : `Forge completion tools configured for ${phase}; provider must call the MCP completion tool before exit.`,
+            content: debugCycle
+                ? "Forge Debug completion tools configured for debug_repro -> debug_root_cause -> debug_fix -> debug_regression; provider must call each MCP completion tool before exit."
+                : developCycle
+                    ? "Forge completion tools configured for implementation -> self_review -> validation; provider must call each MCP completion tool before exit."
+                    : `Forge completion tools configured for ${phase}; provider must call the MCP completion tool before exit.`,
             eventType: "completion_tools_configured"
         });
         const outputState = createProviderOutputState(dispatch.execution.provider);
-        const liveCompletionEvents = new LiveCompletionArtifactEmitter(worktree.worktreePath, dispatch.workItem.id, phase, developCycle, context.emit);
+        const liveCompletionEvents = new LiveCompletionArtifactEmitter(worktree.worktreePath, dispatch.workItem.id, phase, developCycle, debugCycle, context.emit);
         let result;
         try {
             liveCompletionEvents.start();
@@ -86,11 +296,10 @@ export class ProcessBackedProviderCliService {
                 command: command.command,
                 args: command.args,
                 cwd: worktree.worktreePath,
-                env: providerRedactionEnv(dispatch)
+                env: providerProcessEnv(dispatch)
             }, {
                 onStdoutLine: async (line) => {
-                    const event = outputState.consume(line);
-                    if (event) {
+                    for (const event of outputState.consume(line)) {
                         await context.emit(event);
                     }
                 }
@@ -112,7 +321,7 @@ export class ProcessBackedProviderCliService {
         });
         await emitProviderUsageEvent(context.emit, dispatch, outputState);
         const committed = await commitWorktreeChanges(this.git, worktree.worktreePath, dispatch.workItem.id);
-        const completionArtifacts = await readCompletionArtifactsForRun(worktree.worktreePath, dispatch.workItem.id, phase, developCycle);
+        const completionArtifacts = await readCompletionArtifactsForRun(worktree.worktreePath, dispatch.workItem.id, phase, developCycle, debugCycle);
         for (const artifact of completionArtifacts) {
             if (!liveCompletionEvents.hasEmitted(completionPhaseFromArtifact(artifact))) {
                 await emitCompletionArtifactRecorded(context.emit, worktree.worktreePath, artifact);
@@ -138,7 +347,7 @@ export class ProcessBackedProviderCliService {
             });
         }
         return {
-            summary: `${dispatch.execution.provider} CLI completed ${worktree.branchName} (${developCycle ? "develop cycle" : phase}, ${committed.commitSha.slice(0, 12)}).`,
+            summary: `${dispatch.execution.provider} CLI completed ${worktree.branchName} (${debugCycle ? "debug cycle" : developCycle ? "develop cycle" : phase}, ${committed.commitSha.slice(0, 12)}).`,
             spec: {
                 repoPath: worktree.worktreePath,
                 path: specPath,
@@ -150,6 +359,89 @@ export class ProcessBackedProviderCliService {
             artifacts: completionArtifacts
         };
     }
+    async runArchitect(context) {
+        const { dispatch, worktree } = context;
+        const completionTools = await prepareCompletionToolRuntime({ dispatch, worktree, phase: "architect" });
+        const command = buildProviderCliCommand(dispatch, {
+            worktreePath: worktree.worktreePath,
+            prompt: buildArchitectPrompt(dispatch),
+            completionTools
+        });
+        const commandText = formatProviderCliCommand(command);
+        await context.emit({
+            role: "runner",
+            kind: "checkpoint",
+            content: `Starting provider CLI Architect: ${commandText} in ${worktree.worktreePath}`,
+            eventType: "provider_cli_started"
+        });
+        await context.emit({
+            role: "runner",
+            kind: "checkpoint",
+            content: "Forge Architect completion tools configured; provider must call forge.complete_architect_plan before exit.",
+            eventType: "completion_tools_configured"
+        });
+        const outputState = createProviderOutputState(dispatch.execution.provider);
+        const liveArchitectEvents = new LiveArchitectArtifactEmitter(worktree.worktreePath, dispatch.workItem.id, context.emit);
+        let result;
+        try {
+            liveArchitectEvents.start();
+            result = await this.processRunner.run({
+                command: command.command,
+                args: command.args,
+                cwd: worktree.worktreePath,
+                env: providerProcessEnv(dispatch)
+            }, {
+                onStdoutLine: async (line) => {
+                    for (const event of outputState.consume(line)) {
+                        await context.emit(event);
+                    }
+                }
+            }, context.signal);
+        }
+        finally {
+            await liveArchitectEvents.stop();
+            await cleanupCompletionTools(completionTools, context.emit);
+        }
+        if (result.exitCode !== 0) {
+            const stderr = clip(result.stderr.trim() || result.stdout.trim(), 1200);
+            throw new Error(`${command.command} exited ${result.exitCode}${stderr ? `: ${stderr}` : ""}`);
+        }
+        await context.emit({
+            role: "runner",
+            kind: "checkpoint",
+            content: `Provider CLI Architect completed: ${command.command} exit ${result.exitCode}${outputState.sessionLabel ? ` ${outputState.sessionLabel}` : ""}.`,
+            eventType: "provider_cli_completed"
+        });
+        await emitProviderUsageEvent(context.emit, dispatch, outputState);
+        const architectArtifact = await readCompletionArtifact(worktree.worktreePath, dispatch.workItem.id, "architect");
+        if (!architectArtifact) {
+            throw new Error("Provider CLI Architect completed but did not call the Forge Architect completion tool.");
+        }
+        if (!liveArchitectEvents.hasEmitted()) {
+            await emitCompletionArtifactRecorded(context.emit, worktree.worktreePath, architectArtifact);
+            await emitArchitectStructuredEvents(context.emit, worktree.worktreePath, dispatch.workItem.id, architectArtifact);
+        }
+        await context.emit({
+            role: "assistant",
+            kind: "message",
+            content: outputState.finalMessage || `${dispatch.execution.provider} CLI produced an Architect plan for ${worktree.branchName}.`,
+            eventType: "architect_complete"
+        });
+        const specPath = path.join(worktree.worktreePath, ".forge", "work-items", dispatch.workItem.id, "spec.md");
+        const specBody = await fs.readFile(specPath, "utf8").catch(() => `# ${dispatch.workItem.title}\n\nArchitect plan pending approval.\n`);
+        return {
+            summary: `${dispatch.execution.provider} CLI Architect plan produced.`,
+            spec: {
+                repoPath: worktree.worktreePath,
+                path: specPath,
+                body: specBody,
+                producedBy: `${dispatch.execution.provider}-cli`,
+                status: "pending_approval"
+            },
+            artifact: architectArtifact,
+            artifacts: [architectArtifact]
+        };
+    }
     async runQa(context) {
         const { dispatch, worktree } = context;
         const metadataRoot = path.join(worktree.worktreePath, ".forge", "work-items", dispatch.workItem.id);
@@ -190,11 +482,10 @@ export class ProcessBackedProviderCliService {
                 command: command.command,
                 args: command.args,
                 cwd: worktree.worktreePath,
-                env: providerRedactionEnv(dispatch)
+                env: providerProcessEnv(dispatch)
             }, {
                 onStdoutLine: async (line) => {
-                    const event = outputState.consume(line);
-                    if (event) {
+                    for (const event of outputState.consume(line)) {
                         await context.emit(event);
                     }
                 }
@@ -215,7 +506,7 @@ export class ProcessBackedProviderCliService {
             eventType: "provider_cli_completed"
         });
         await emitProviderUsageEvent(context.emit, dispatch, outputState);
-        const qaArtifact = await readQaCompletionArtifactBundle(worktree.worktreePath, dispatch.workItem.id);
+        const qaArtifact = await readQaCompletionArtifactBundle(worktree.worktreePath, dispatch.workItem.id, dispatch.cycleRun.ownerType, dispatch.cycleRun.ownerId);
         if (!qaArtifact) {
             const verdictOnly = await readCompletionArtifact(worktree.worktreePath, dispatch.workItem.id, "qa");
             throw new Error(verdictOnly
@@ -225,7 +516,7 @@ export class ProcessBackedProviderCliService {
         enforceQaBrowserLaunchTargetGate(dispatch, qaArtifact);
         if (!liveQaEvents.hasEmitted()) {
             await emitQaArtifactRecorded(context.emit, worktree.worktreePath, qaArtifact);
-            await emitQaStructuredEvents(context.emit, worktree.worktreePath, dispatch.workItem.id, qaArtifact);
+            await emitQaStructuredEvents(context.emit, qaArtifact);
         }
         const status = (qaArtifact.status ?? "unknown").trim().toLowerCase();
         const statusSummary = status === "pass"
@@ -265,11 +556,11 @@ export class ProcessBackedProviderCliService {
         const result = await this.processRunner.run({
             command: command.command,
             args: command.args,
-            cwd: worktree.worktreePath
+            cwd: worktree.worktreePath,
+            env: providerProcessEnv(dispatch)
         }, {
             onStdoutLine: async (line) => {
-                const event = outputState.consume(line);
-                if (event) {
+                for (const event of outputState.consume(line)) {
                     await context.emit(event);
                 }
             }
@@ -301,10 +592,22 @@ export class DeterministicProviderCliService {
     constructor(git = new GitClient()) {
         this.git = git;
     }
+    async runDraft(context) {
+        const content = JSON.stringify(deterministicDraftPayload(context.dispatch));
+        await context.emit({
+            role: "assistant",
+            kind: "message",
+            content,
+            eventType: "draft_complete"
+        });
+        await context.emit(buildProviderUsageEvent(context.dispatch, estimatedDeterministicUsage()));
+        return { summary: "forge-bridge generated deterministic draft." };
+    }
     async runImplementation(context) {
         const { dispatch, worktree } = context;
         const phase = completionPhaseFromDispatch(dispatch);
         const developCycle = usesDevelopCycleCompletion(dispatch);
+        const debugCycle = usesDebugCycleCompletion(dispatch);
         const providerCommand = buildProviderCliCommand(dispatch);
         const providerCommandText = formatProviderCliCommand(providerCommand);
         const metadataRoot = path.join(worktree.worktreePath, ".forge", "work-items", dispatch.workItem.id);
@@ -335,9 +638,11 @@ export class DeterministicProviderCliService {
             content: `Created bridge changeset at ${changesetPath}`,
             eventType: "changeset"
         });
-        const phases = developCycle
-            ? ["implementation", "self_review", "validation"]
-            : [phase];
+        const phases = debugCycle
+            ? debugCompletionPhaseOrder
+            : developCycle
+                ? ["implementation", "self_review", "validation"]
+                : [phase];
         const completionArtifacts = [];
         for (const completionPhase of phases) {
             await writeCompletionArtifact({
@@ -346,7 +651,9 @@ export class DeterministicProviderCliService {
                 phase: completionPhase,
                 producedBy: "forge-bridge",
                 redactionSecrets: exactRedactionSecrets(dispatch)
-            }, expectedCompletionToolName(completionPhase), deterministicCompletionPayload(completionPhase, dispatch, changesetBody));
+            }, isDebugCompletionPhaseForProvider(completionPhase)
+                ? expectedDebugCompletionToolName(completionPhase)
+                : expectedCompletionToolName(completionPhase), deterministicCompletionPayload(completionPhase, dispatch, changesetBody));
             const completionArtifact = await readCompletionArtifact(worktree.worktreePath, dispatch.workItem.id, completionPhase);
             if (!completionArtifact) {
                 throw new Error(`Deterministic provider did not produce the Forge ${completionPhase} completion artifact.`);
@@ -362,7 +669,7 @@ export class DeterministicProviderCliService {
         }
         await context.emit(buildProviderUsageEvent(dispatch, estimatedDeterministicUsage()));
         return {
-            summary: `forge-bridge completed ${worktree.branchName} (${developCycle ? "develop cycle" : phase}).`,
+            summary: `forge-bridge completed ${worktree.branchName} (${debugCycle ? "debug cycle" : developCycle ? "develop cycle" : phase}).`,
             spec: {
                 repoPath: worktree.worktreePath,
                 path: specPath,
@@ -374,6 +681,47 @@ export class DeterministicProviderCliService {
             artifacts: completionArtifacts
         };
     }
+    async runArchitect(context) {
+        const { dispatch, worktree } = context;
+        const metadataRoot = path.join(worktree.worktreePath, ".forge", "work-items", dispatch.workItem.id);
+        await fs.mkdir(metadataRoot, { recursive: true });
+        const specBody = `---\ntitle: "${dispatch.workItem.title}"\nstatus: pending_approval\nproduced_by: forge-bridge\n---\n\n# ${dispatch.workItem.title}\n\nArchitect plan pending approval.\n`;
+        const specPath = path.join(metadataRoot, "spec.md");
+        await fs.writeFile(specPath, specBody, "utf8");
+        await fs.writeFile(path.join(metadataRoot, "spec.meta.json"), JSON.stringify({ schema_version: 1, status: "pending_approval", produced_by: "forge-bridge" }) + "\n", "utf8");
+        await writeCompletionArtifact({
+            worktreePath: worktree.worktreePath,
+            workItemId: dispatch.workItem.id,
+            phase: "architect",
+            producedBy: "forge-bridge",
+            redactionSecrets: exactRedactionSecrets(dispatch),
+            architectCycle: true
+        }, expectedCompletionToolName("architect"), deterministicArchitectPayload(dispatch));
+        const artifact = await readCompletionArtifact(worktree.worktreePath, dispatch.workItem.id, "architect");
+        if (!artifact) {
+            throw new Error("Deterministic provider did not produce the Forge Architect completion artifact.");
+        }
+        await emitCompletionArtifactRecorded(context.emit, worktree.worktreePath, artifact);
+        await emitArchitectStructuredEvents(context.emit, worktree.worktreePath, dispatch.workItem.id, artifact);
+        await context.emit({
+            role: "assistant",
+            kind: "message",
+            content: "Architect plan complete. forge-bridge produced deterministic planning artifacts.",
+            eventType: "architect_complete"
+        });
+        return {
+            summary: "forge-bridge completed Architect plan (deterministic).",
+            spec: {
+                repoPath: worktree.worktreePath,
+                path: specPath,
+                body: specBody,
+                producedBy: "forge-bridge",
+                status: "pending_approval"
+            },
+            artifact,
+            artifacts: [artifact]
+        };
+    }
     async runQa(context) {
         const { dispatch, worktree } = context;
         await context.emit({
@@ -386,7 +734,7 @@ export class DeterministicProviderCliService {
         const launchTarget = qaBrowser?.launchTarget ?? null;
         const missingLaunchTarget = qaBrowser?.required === true && !hasLaunchTarget(launchTarget);
         const browserSidecar = !missingLaunchTarget && qaBrowser?.required === true && launchTarget
-            ? deterministicBrowserSidecar(dispatch.workItem.id, launchTarget)
+            ? deterministicBrowserSidecar(dispatch.workItem.id, launchTarget, dispatch.cycleRun.ownerType, dispatch.cycleRun.ownerId)
             : null;
         const browserChecks = browserSidecar && launchTarget
             ? [deterministicBrowserCheck(launchTarget, browserSidecar.relativePath)]
@@ -403,7 +751,9 @@ export class DeterministicProviderCliService {
                 phase: "qa",
                 producedBy: "forge-bridge",
                 redactionSecrets: exactRedactionSecrets(dispatch),
-                qaCycle: true
+                qaCycle: true,
+                ownerType: dispatch.cycleRun.ownerType ?? undefined,
+                ownerId: dispatch.cycleRun.ownerId ?? undefined
             }, expectedQaCompletionToolName(gate), deterministicQaGatePayload({
                 gate,
                 criterion,
@@ -412,19 +762,17 @@ export class DeterministicProviderCliService {
                 browserChecks,
                 sidecars
             }));
-            await context.emit({
-                role: "hook",
-                kind: "checkpoint",
-                content: `qa_gate: ${gate} artifact accepted.`,
-                eventType: "qa_gate"
-            });
+            const gateArtifact = await readQaGateArtifact(qaArtifactRootForDispatch(worktree.worktreePath, dispatch.workItem.id, dispatch), gate);
+            if (gateArtifact) {
+                await emitQaGateAccepted(context.emit, worktree.worktreePath, gateArtifact, nextQaGate(gate));
+            }
         }
-        const qaArtifact = await readQaCompletionArtifactBundle(worktree.worktreePath, dispatch.workItem.id);
+        const qaArtifact = await readQaCompletionArtifactBundle(worktree.worktreePath, dispatch.workItem.id, dispatch.cycleRun.ownerType, dispatch.cycleRun.ownerId);
         if (!qaArtifact) {
             throw new Error("Deterministic QA did not produce the complete durable QA artifact bundle.");
         }
         await emitQaArtifactRecorded(context.emit, worktree.worktreePath, qaArtifact);
-        await emitQaStructuredEvents(context.emit, worktree.worktreePath, dispatch.workItem.id, qaArtifact);
+        await emitQaStructuredEvents(context.emit, qaArtifact);
         await context.emit(buildProviderUsageEvent(dispatch, estimatedDeterministicUsage()));
         return {
             summary: missingLaunchTarget ? "forge-bridge QA blocked." : "forge-bridge QA passed.",
@@ -455,6 +803,9 @@ export class DeterministicProviderCliService {
 function phaseCompleteEventType(phase) {
     return phase === "implementation" ? "implementation_complete" : `${phase}_complete`;
 }
+function isDebugCompletionPhaseForProvider(phase) {
+    return debugCompletionPhaseOrder.includes(phase);
+}
 function deterministicCompletionPayload(phase, dispatch, changesetBody) {
     const changesetHash = sha256(changesetBody);
     const criterion = dispatch.workItem.acceptanceCriteria || "Deterministic bridge changeset exists";
@@ -477,6 +828,56 @@ function deterministicCompletionPayload(phase, dispatch, changesetBody) {
             next_phase_context: "Review FORGE_PHASE5_CHANGESET.md and the bridge commit before validation."
         };
     }
+    if (phase === "debug_repro") {
+        return {
+            status: "pass",
+            summary: "forge-bridge reproduced the bug deterministically.",
+            repro_steps: ["Run the deterministic fake-worker debug reproduction."],
+            observed: "The configured bug scenario is reproducible in deterministic bridge mode.",
+            expected: "The bug scenario should be fixed before QA handoff.",
+            evidence: [{ kind: "changeset", path: "FORGE_PHASE5_CHANGESET.md", content_hash: changesetHash }]
+        };
+    }
+    if (phase === "debug_root_cause") {
+        return {
+            status: "pass",
+            summary: "forge-bridge isolated a deterministic root cause.",
+            root_cause: "The deterministic fake-worker bug is represented by the generated changeset evidence.",
+            evidence: [{ kind: "changeset", path: "FORGE_PHASE5_CHANGESET.md", content_hash: changesetHash }],
+            eliminated_alternatives: [{ summary: "No alternate deterministic fake-worker path was implicated." }],
+            risk_area: "forge-bridge deterministic debug lane"
+        };
+    }
+    if (phase === "debug_fix") {
+        return {
+            status: "pass",
+            summary: "forge-bridge applied a deterministic debug fix.",
+            changed_files: [{ path: "FORGE_PHASE5_CHANGESET.md", summary: "Recorded deterministic debug fix evidence." }],
+            tests_added_or_updated: [{ path: "FORGE_PHASE5_CHANGESET.md", summary: "Deterministic debug evidence doubles as fake-worker regression coverage." }],
+            remaining_risks: [],
+            resolved_findings: (dispatch.qaRework?.findingIds ?? []).map((qaId) => ({
+                qa_id: qaId,
+                status: "resolved",
+                summary: `Resolved deterministic QA finding ${qaId}.`,
+                evidence: { path: "FORGE_PHASE5_CHANGESET.md", content_hash: changesetHash },
+                changed_files: [{ path: "FORGE_PHASE5_CHANGESET.md", summary: "Recorded deterministic debug fix evidence." }],
+                tests_added_or_updated: [{ path: "FORGE_PHASE5_CHANGESET.md", summary: "Deterministic fake-worker regression evidence." }],
+                regression_evidence: [{ command: "forge-bridge deterministic debug regression", status: "pass" }]
+            }))
+        };
+    }
+    if (phase === "debug_regression") {
+        return {
+            status: "pass",
+            summary: "forge-bridge proved the deterministic debug regression is QA-ready.",
+            commands: [{ command: "forge-bridge deterministic debug regression", exit_code: 0, status: "pass", summary: "Deterministic debug regression completed." }],
+            required_regressions: ["Original deterministic repro no longer fails."],
+            build_status: "not_applicable",
+            test_status: "pass",
+            repro_negative: true,
+            qa_ready: true
+        };
+    }
     if (phase === "self_review") {
         return {
             status: "pass",
@@ -537,6 +938,45 @@ function deterministicCompletionPayload(phase, dispatch, changesetBody) {
         ready_for_dev_test: true
     };
 }
+function deterministicArchitectPayload(dispatch) {
+    const planId = `architect-${dispatch.workItem.id.replace(/-/g, "")}`;
+    return {
+        status: "pass",
+        summary: "forge-bridge produced a deterministic Architect plan.",
+        implementation_plan: {
+            schema_version: 1,
+            plan_id: planId,
+            story_id: dispatch.workItem.id,
+            phases: [
+                { id: "phase-1", name: "Foundation", tasks: ["task-1"], gate: "phase-1-gate" }
+            ],
+            tasks: [
+                {
+                    id: "task-1",
+                    title: `Implement ${dispatch.workItem.title}`,
+                    phase: "phase-1",
+                    summary: "Deterministic bridge Architect task proving MCP artifact contract persistence.",
+                    acceptance_criteria: [dispatch.workItem.acceptanceCriteria || `Preserve story intent for ${dispatch.workItem.title}`],
+                    tests: [
+                        { command: "dotnet test /home/dillon/repos/Forge/Forge.sln --filter Architect", purpose: "Architect bridge contract regression" }
+                    ]
+                }
+            ],
+            dependencies: [],
+            phase_gates: [
+                { id: "phase-1-gate", phase: "phase-1", checks: ["Task tests pass", "Artifacts validate"] }
+            ]
+        },
+        qa_plan: {
+            schema_version: 1,
+            plan_id: planId,
+            final_qa: [
+                { id: "qa-1", coverage: `Verify Architect plan artifacts and pending approval status for ${dispatch.workItem.title}` }
+            ]
+        },
+        report_markdown: `# Architect Report\n\nWork item: ${dispatch.workItem.id}\nTitle: ${dispatch.workItem.title}\n\nVerdict: pass\n\nDeterministic bridge Architect plan produced for pending approval.\n`
+    };
+}
 function deterministicQaGatePayload(options) {
     const blocked = options.missingLaunchTarget;
     const skippedBecauseBlocked = blocked
@@ -648,16 +1088,25 @@ const qaArtifactFileNames = {
     verdict: "qa.verdict.json",
     report: "qa.report.md"
 };
+const qaGateArtifactFileNames = {
+    qa_plan: "qa.plan.json",
+    qa_regression: "qa.regression.json",
+    qa_api: "qa.api.json",
+    qa_manual_web: "qa.manual-web.json",
+    qa_bug_repro: "qa.bug-repro.json",
+    qa_findings: "qa.findings.json",
+    qa_verdict: "qa.verdict.json"
+};
 function hasLaunchTarget(target) {
     return Boolean(target?.url?.trim()
         || target?.ready_url?.trim()
         || target?.command?.trim()
         || (target?.routes ?? []).some((route) => route.trim().length > 0));
 }
-function deterministicBrowserSidecar(workItemId, target) {
+function deterministicBrowserSidecar(workItemId, target, ownerType, ownerId) {
     const route = primaryLaunchRoute(target);
     return {
-        relativePath: qaArtifactRelativePath(workItemId, "qa/screenshots/deterministic-browser-check.txt"),
+        relativePath: qaArtifactRelativePath(workItemId, "qa/screenshots/deterministic-browser-check.txt", ownerType, ownerId),
         content: `Deterministic Forge QA browser evidence\nRoute: ${route}\nConsole errors: []\nNetwork errors: []\nResponsive checks: desktop, mobile\n`
     };
 }
@@ -699,78 +1148,6 @@ async function writeQaSidecarFiles(worktreePath, files) {
     }
     return sidecars;
 }
-async function writeQaArtifacts(request) {
-    const artifactRoot = artifactRootFor(request.worktreePath, request.workItemId);
-    await fs.mkdir(artifactRoot, { recursive: true });
-    const sidecars = await writeQaSidecarFiles(request.worktreePath, request.sidecarFiles ?? []);
-    const status = request.status ?? "pass";
-    const criterion = request.acceptanceCriteria.trim() || "Forge QA evidence exists";
-    const relativeEvidencePath = qaArtifactRelativePath(request.workItemId, qaArtifactFileNames.evidence);
-    const relativeFindingsPath = qaArtifactRelativePath(request.workItemId, qaArtifactFileNames.findings);
-    const relativeReportPath = qaArtifactRelativePath(request.workItemId, qaArtifactFileNames.report);
-    const planJson = jsonText({
-        schema_version: 1,
-        phase: "qa",
-        checklist: [
-            "Review the validated work item against acceptance criteria.",
-            "Run relevant provider QA verification.",
-            "Confirm no in-scope QA findings remain."
-        ],
-        acceptance_criteria: [criterion]
-    });
-    const evidenceJson = jsonText({
-        schema_version: 1,
-        phase: "qa",
-        commands: status === "blocked"
-            ? []
-            : [
-                {
-                    command: request.command,
-                    exit_code: 0,
-                    status: "pass",
-                    summary: `${request.provider} QA completed successfully.`
-                }
-            ],
-        browser_checks: request.browserChecks ?? [],
-        sidecars,
-        notes: request.summary
-    });
-    const findingsJson = jsonText({
-        schema_version: 1,
-        phase: "qa",
-        findings: [],
-        candidate_bugs: []
-    });
-    const verdictJson = jsonText({
-        schema_version: 1,
-        phase: "qa",
-        status,
-        summary: request.summary,
-        tested_acceptance_criteria: status === "blocked" ? [] : [criterion],
-        finding_ids: [],
-        candidate_bug_ids: [],
-        blocker_reason: status === "blocked" ? request.blockerReason ?? "inconclusive" : null,
-        evidence_path: relativeEvidencePath,
-        findings_path: relativeFindingsPath,
-        report_path: relativeReportPath
-    });
-    const report = `# QA report\n\n${request.summary}\n\n- Provider: ${singleLine(request.provider)}\n- Model: ${singleLine(request.model)}\n- Command: ${singleLine(request.command)}\n`;
-    await fs.writeFile(path.join(artifactRoot, qaArtifactFileNames.plan), planJson, "utf8");
-    await fs.writeFile(path.join(artifactRoot, qaArtifactFileNames.evidence), evidenceJson, "utf8");
-    await fs.writeFile(path.join(artifactRoot, qaArtifactFileNames.findings), findingsJson, "utf8");
-    const verdictPath = path.join(artifactRoot, qaArtifactFileNames.verdict);
-    await fs.writeFile(verdictPath, verdictJson, "utf8");
-    await fs.writeFile(path.join(artifactRoot, qaArtifactFileNames.report), report, "utf8");
-    return {
-        repoPath: request.worktreePath,
-        path: verdictPath,
-        verdictJson,
-        report,
-        producedBy: request.producedBy,
-        status,
-        phase: "qa"
-    };
-}
 async function emitQaArtifactRecorded(emit, worktreePath, artifact) {
     const relativePath = path.relative(worktreePath, artifact.path) || path.basename(artifact.path);
     await emit({
@@ -786,16 +1163,29 @@ async function emitQaArtifactRecorded(emit, worktreePath, artifact) {
         eventType: "phase_gate"
     });
 }
-async function readQaCompletionArtifactBundle(worktreePath, workItemId) {
-    const artifact = await readCompletionArtifact(worktreePath, workItemId, "qa");
-    if (!artifact || !await hasCompleteQaArtifactBundle(worktreePath, workItemId)) {
+async function readQaCompletionArtifactBundle(worktreePath, workItemId, ownerType, ownerId) {
+    const artifact = await readCompletionArtifact(worktreePath, workItemId, "qa", ownerType, ownerId);
+    if (!artifact || !await hasCompleteQaArtifactBundle(worktreePath, workItemId, ownerType, ownerId)) {
         return null;
     }
-    await validateQaBundleSidecarReferences(worktreePath, workItemId);
-    return artifact;
+    const artifactRoot = ownerType && ownerId
+        ? artifactRootForOwner(worktreePath, ownerType, ownerId)
+        : artifactRootFor(worktreePath, workItemId);
+    const planJson = await fs.readFile(path.join(artifactRoot, qaArtifactFileNames.plan), "utf8");
+    const evidenceJson = await fs.readFile(path.join(artifactRoot, qaArtifactFileNames.evidence), "utf8");
+    const findingsJson = await fs.readFile(path.join(artifactRoot, qaArtifactFileNames.findings), "utf8");
+    await validateQaBundleSidecarReferences(worktreePath, workItemId, ownerType, ownerId);
+    return {
+        ...artifact,
+        planJson,
+        evidenceJson,
+        findingsJson
+    };
 }
-async function hasCompleteQaArtifactBundle(worktreePath, workItemId) {
-    const artifactRoot = artifactRootFor(worktreePath, workItemId);
+async function hasCompleteQaArtifactBundle(worktreePath, workItemId, ownerType, ownerId) {
+    const artifactRoot = ownerType && ownerId
+        ? artifactRootForOwner(worktreePath, ownerType, ownerId)
+        : artifactRootFor(worktreePath, workItemId);
     for (const fileName of Object.values(qaArtifactFileNames)) {
         try {
             const stat = await fs.stat(path.join(artifactRoot, fileName));
@@ -824,8 +1214,10 @@ function enforceQaBrowserLaunchTargetGate(dispatch, artifact) {
         throw new Error("QA browser testing is required but no app launch target was provided; provider must return blocked with blocker_reason missing_app_launch_target.");
     }
 }
-async function validateQaBundleSidecarReferences(worktreePath, workItemId) {
-    const artifactRoot = artifactRootFor(worktreePath, workItemId);
+async function validateQaBundleSidecarReferences(worktreePath, workItemId, ownerType, ownerId) {
+    const artifactRoot = ownerType && ownerId
+        ? artifactRootForOwner(worktreePath, ownerType, ownerId)
+        : artifactRootFor(worktreePath, workItemId);
     const evidence = await readJsonObjectFile(path.join(artifactRoot, qaArtifactFileNames.evidence));
     const sidecars = arrayField(evidence, "sidecars");
     if (sidecars.length === 0) {
@@ -844,7 +1236,9 @@ async function validateQaBundleSidecarReferences(worktreePath, workItemId) {
         }
         const fullPath = path.resolve(worktreePath, sidecarPath);
         if (!isPathUnderRoot(qaSidecarRoot, fullPath)) {
-            throw new Error(`QA sidecar ${index} path must be under .forge/work-items/${workItemId}/artifacts/qa/.`);
+            const ownerDirectory = ownerType && ownerId && ownerType.trim().toLowerCase() === "story" ? "stories" : "work-items";
+            const ownerSegment = ownerType && ownerId ? ownerId : workItemId;
+            throw new Error(`QA sidecar ${index} path must be under .forge/${ownerDirectory}/${ownerSegment}/artifacts/qa/.`);
         }
         const stat = await fs.lstat(fullPath).catch((error) => {
             if (isNodeError(error) && error.code === "ENOENT") {
@@ -865,8 +1259,8 @@ async function validateQaBundleSidecarReferences(worktreePath, workItemId) {
         }
     }
 }
-async function emitQaStructuredEvents(emit, worktreePath, workItemId, artifact) {
-    const artifactRoot = artifactRootFor(worktreePath, workItemId);
+async function emitQaStructuredEvents(emit, artifact) {
+    const artifactRoot = path.dirname(artifact.path);
     const plan = await readJsonObjectFile(path.join(artifactRoot, qaArtifactFileNames.plan));
     const evidence = await readJsonObjectFile(path.join(artifactRoot, qaArtifactFileNames.evidence));
     const findings = await readJsonObjectFile(path.join(artifactRoot, qaArtifactFileNames.findings));
@@ -906,12 +1300,76 @@ async function emitQaStructuredEvents(emit, worktreePath, workItemId, artifact)
         eventType: status === "blocked" ? "qa_blocked" : "qa_complete"
     });
 }
+function qaArtifactRootForDispatch(worktreePath, workItemId, dispatch) {
+    return dispatch.cycleRun.ownerType && dispatch.cycleRun.ownerId
+        ? artifactRootForOwner(worktreePath, dispatch.cycleRun.ownerType, dispatch.cycleRun.ownerId)
+        : artifactRootFor(worktreePath, workItemId);
+}
+async function readQaGateArtifact(artifactRoot, gate) {
+    const artifactPath = path.join(artifactRoot, qaGateArtifactFileNames[gate]);
+    try {
+        const stat = await fs.stat(artifactPath);
+        if (!stat.isFile()) {
+            return null;
+        }
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+    const payload = await readJsonObjectFile(artifactPath);
+    return {
+        gate,
+        path: artifactPath,
+        status: stringField(payload, "status") ?? "unknown",
+        producedBy: stringField(payload, "produced_by") ?? stringField(payload, "producedBy") ?? undefined,
+        contentHash: stringField(payload, "content_hash") ?? undefined
+    };
+}
+function nextQaGate(gate) {
+    const index = qaCompletionGateOrder.indexOf(gate);
+    return index >= 0 ? qaCompletionGateOrder[index + 1] ?? null : null;
+}
+async function emitQaGateAccepted(emit, worktreePath, artifact, nextGate) {
+    const relativePath = path.relative(worktreePath, artifact.path).split(path.sep).join("/");
+    await emit({
+        role: "hook",
+        kind: artifact.status === "blocked" ? "error" : "checkpoint",
+        content: `phase_gate: ${artifact.gate} artifact accepted with status ${artifact.status}.`,
+        eventType: "phase_gate",
+        data: JSON.stringify({
+            phase: "qa",
+            qa_gate: artifact.gate,
+            status: artifact.status,
+            artifact_relative_paths: [relativePath],
+            content_hash: artifact.contentHash ?? null,
+            produced_by: artifact.producedBy ?? null
+        })
+    });
+    if (!nextGate) {
+        return;
+    }
+    await emit({
+        role: "hook",
+        kind: "checkpoint",
+        content: `phase_progression: ${artifact.gate} -> ${nextGate}`,
+        eventType: "phase_gate",
+        data: JSON.stringify({
+            phase: "qa",
+            from_gate: artifact.gate,
+            to_gate: nextGate
+        })
+    });
+}
 class LiveQaArtifactEmitter {
     worktreePath;
     workItemId;
     dispatch;
     emit;
-    emitted = false;
+    emittedBundle = false;
+    emittedGates = new Set();
     timer = null;
     pending = Promise.resolve();
     constructor(worktreePath, workItemId, dispatch, emit) {
@@ -934,7 +1392,7 @@ class LiveQaArtifactEmitter {
         await this.pollQueued();
     }
     hasEmitted() {
-        return this.emitted;
+        return this.emittedBundle;
     }
     pollQueued() {
         this.pending = this.pending
@@ -943,19 +1401,125 @@ class LiveQaArtifactEmitter {
         return this.pending;
     }
     async poll() {
-        if (this.emitted) {
+        await this.emitAvailableGateEvents();
+        if (this.emittedBundle) {
             return;
         }
-        const artifact = await readQaCompletionArtifactBundle(this.worktreePath, this.workItemId);
+        const artifact = await readQaCompletionArtifactBundle(this.worktreePath, this.workItemId, this.dispatch.cycleRun.ownerType, this.dispatch.cycleRun.ownerId);
         if (!artifact) {
             return;
         }
         enforceQaBrowserLaunchTargetGate(this.dispatch, artifact);
-        this.emitted = true;
+        this.emittedBundle = true;
         await emitQaArtifactRecorded(this.emit, this.worktreePath, artifact);
-        await emitQaStructuredEvents(this.emit, this.worktreePath, this.workItemId, artifact);
+        await emitQaStructuredEvents(this.emit, artifact);
+    }
+    async emitAvailableGateEvents() {
+        const artifactRoot = qaArtifactRootForDispatch(this.worktreePath, this.workItemId, this.dispatch);
+        for (const gate of qaCompletionGateOrder) {
+            if (this.emittedGates.has(gate)) {
+                continue;
+            }
+            const artifact = await readQaGateArtifact(artifactRoot, gate);
+            if (!artifact) {
+                return;
+            }
+            this.emittedGates.add(gate);
+            await emitQaGateAccepted(this.emit, this.worktreePath, artifact, nextQaGate(gate));
+        }
+    }
+}
+class LiveArchitectArtifactEmitter {
+    worktreePath;
+    workItemId;
+    emit;
+    emitted = false;
+    timer = null;
+    pending = Promise.resolve();
+    constructor(worktreePath, workItemId, emit) {
+        this.worktreePath = worktreePath;
+        this.workItemId = workItemId;
+        this.emit = emit;
+    }
+    start() {
+        void this.pollQueued();
+        this.timer = setInterval(() => {
+            void this.pollQueued();
+        }, 250);
+    }
+    async stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        await this.pollQueued();
+    }
+    hasEmitted() {
+        return this.emitted;
+    }
+    pollQueued() {
+        this.pending = this.pending
+            .then(() => this.poll())
+            .catch(() => undefined);
+        return this.pending;
+    }
+    async poll() {
+        if (this.emitted || !await hasCompleteArchitectArtifactBundle(this.worktreePath, this.workItemId)) {
+            return;
+        }
+        const artifact = await readCompletionArtifact(this.worktreePath, this.workItemId, "architect");
+        if (!artifact) {
+            return;
+        }
+        this.emitted = true;
+        await emitCompletionArtifactRecorded(this.emit, this.worktreePath, artifact);
+        await emitArchitectStructuredEvents(this.emit, this.worktreePath, this.workItemId, artifact);
     }
 }
+async function hasCompleteArchitectArtifactBundle(worktreePath, workItemId) {
+    const artifactRoot = artifactRootFor(worktreePath, workItemId);
+    for (const fileName of ["implementation.plan.json", "qa.plan.json", "architect.verdict.json", "architect.report.md"]) {
+        try {
+            const stat = await fs.stat(path.join(artifactRoot, fileName));
+            if (!stat.isFile()) {
+                return false;
+            }
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === "ENOENT") {
+                return false;
+            }
+            throw error;
+        }
+    }
+    return true;
+}
+async function emitArchitectStructuredEvents(emit, worktreePath, workItemId, artifact) {
+    const artifactRoot = artifactRootFor(worktreePath, workItemId);
+    const implementationPlan = await readJsonObjectFile(path.join(artifactRoot, "implementation.plan.json"));
+    const qaPlan = await readJsonObjectFile(path.join(artifactRoot, "qa.plan.json"));
+    const verdict = parseJsonLine(artifact.verdictJson) ?? {};
+    const status = stringField(verdict, "status") ?? artifact.status ?? "unknown";
+    const planId = stringField(implementationPlan, "plan_id") ?? "unknown";
+    await emit({
+        role: "worker",
+        kind: "checkpoint",
+        content: `Architect plan recorded: ${planId} with ${arrayField(implementationPlan, "phases").length} phases and ${arrayField(implementationPlan, "tasks").length} tasks.`,
+        eventType: "architect_plan"
+    });
+    await emit({
+        role: "worker",
+        kind: "checkpoint",
+        content: `Architect QA seed recorded with ${arrayField(qaPlan, "final_qa").length} final QA items.`,
+        eventType: "architect_qa_seed"
+    });
+    await emit({
+        role: "hook",
+        kind: status === "pass" ? "checkpoint" : "error",
+        content: `architect_mcp_complete: ${status === "pass" ? "accepted" : "recorded"} - ${stringField(verdict, "summary") ?? "Architect completion payload recorded."}`,
+        eventType: "architect_mcp_complete"
+    });
+}
 async function readJsonObjectFile(filePath) {
     const content = await fs.readFile(filePath, "utf8").catch(() => "");
     return parseJsonLine(content) ?? {};
@@ -980,19 +1544,36 @@ function summarizeQaObject(source) {
         ?? stringField(source, "id")
         ?? JSON.stringify(source), 500);
 }
-function qaArtifactRelativePath(workItemId, fileName) {
+function qaArtifactRelativePath(workItemId, fileName, ownerType, ownerId) {
+    if (ownerType && ownerId) {
+        const ownerDirectory = ownerType.trim().toLowerCase() === "story" ? "stories" : "work-items";
+        return [".forge", ownerDirectory, ownerId, "artifacts", fileName].join("/");
+    }
     return [".forge", "work-items", workItemId, "artifacts", fileName].join("/");
 }
-function jsonText(value) {
-    return `${JSON.stringify(value, null, 2)}\n`;
-}
 async function emitCompletionArtifactRecorded(emit, worktreePath, artifact) {
     const relativePath = path.relative(worktreePath, artifact.path) || path.basename(artifact.path);
+    await emit({
+        role: "tool",
+        kind: "checkpoint",
+        content: `Forge completion tool validation passed for ${artifact.phase ?? "unknown"} (${artifact.status}).`,
+        eventType: "completion_tool_validation_passed",
+        data: JSON.stringify({
+            phase: artifact.phase ?? "unknown",
+            status: artifact.status,
+            artifact_relative_paths: [relativePath.split(path.sep).join("/")]
+        })
+    });
     await emit({
         role: "tool",
         kind: "tool_result",
         content: `Forge completion tool recorded ${artifact.phase ?? "unknown"} artifact ${relativePath} (${artifact.status}).`,
-        eventType: "completion_tool_artifact_recorded"
+        eventType: "completion_tool_artifact_recorded",
+        data: JSON.stringify({
+            phase: artifact.phase ?? "unknown",
+            status: artifact.status,
+            artifact_relative_paths: [relativePath.split(path.sep).join("/")]
+        })
     });
 }
 async function emitPhaseCompletionEvent(emit, artifact) {
@@ -1020,7 +1601,15 @@ async function emitPhaseGateEvents(emit, artifact) {
         ? "phase_progression: implementation -> self_review"
         : phase === "self_review"
             ? "phase_progression: self_review -> validation"
-            : "phase_progression: validation -> QA ready";
+            : phase === "debug_repro"
+                ? "phase_progression: debug_repro -> debug_root_cause"
+                : phase === "debug_root_cause"
+                    ? "phase_progression: debug_root_cause -> debug_fix"
+                    : phase === "debug_fix"
+                        ? "phase_progression: debug_fix -> debug_regression"
+                        : phase === "debug_regression"
+                            ? "phase_progression: debug_regression -> QA ready"
+                            : "phase_progression: validation -> QA ready";
     await emit({
         role: "hook",
         kind: "checkpoint",
@@ -1031,6 +1620,7 @@ async function emitPhaseGateEvents(emit, artifact) {
 function completionPhaseFromArtifact(artifact) {
     const phase = artifact.phase?.trim();
     return phase === "self_review" || phase === "validation" || phase === "implementation" || phase === "qa"
+        || phase === "architect" || phase === "debug_repro" || phase === "debug_root_cause" || phase === "debug_fix" || phase === "debug_regression"
         ? phase
         : "implementation";
 }
@@ -1042,13 +1632,18 @@ class LiveCompletionArtifactEmitter {
     emitted = new Set();
     timer = null;
     pending = Promise.resolve();
-    constructor(worktreePath, workItemId, phase, developCycle, emit) {
+    constructor(worktreePath, workItemId, phase, developCycle, debugCycle, emit) {
         this.worktreePath = worktreePath;
         this.workItemId = workItemId;
         this.emit = emit;
-        this.phases = developCycle
-            ? developCyclePhaseOrder.slice(developCyclePhaseOrder.indexOf(phase))
-            : [phase];
+        if (debugCycle && isDebugCompletionPhaseForProvider(phase)) {
+            this.phases = debugCompletionPhaseOrder.slice(debugCompletionPhaseOrder.indexOf(phase));
+        }
+        else {
+            this.phases = developCycle
+                ? developCyclePhaseOrder.slice(developCyclePhaseOrder.indexOf(phase))
+                : [phase];
+        }
     }
     start() {
         void this.pollQueued();
@@ -1091,20 +1686,23 @@ class LiveCompletionArtifactEmitter {
         }
     }
 }
-async function readCompletionArtifactsForRun(worktreePath, workItemId, phase, developCycle) {
-    if (!developCycle) {
+async function readCompletionArtifactsForRun(worktreePath, workItemId, phase, developCycle, debugCycle) {
+    if (!developCycle && !debugCycle) {
         const artifact = await readCompletionArtifact(worktreePath, workItemId, phase);
         if (!artifact) {
             throw new Error(`Provider CLI completed but did not call the Forge ${phase} completion tool.`);
         }
         return [artifact];
     }
+    const expectedPhases = debugCycle && isDebugCompletionPhaseForProvider(phase)
+        ? debugCompletionPhaseOrder.slice(debugCompletionPhaseOrder.indexOf(phase))
+        : ["implementation", "self_review", "validation"];
     const artifacts = [];
-    for (const expectedPhase of ["implementation", "self_review", "validation"]) {
+    for (const expectedPhase of expectedPhases) {
         const artifact = await readCompletionArtifact(worktreePath, workItemId, expectedPhase);
         if (!artifact) {
             if (artifacts.length === 0) {
-                throw new Error("Provider CLI completed but did not call the Forge implementation completion tool.");
+                throw new Error(`Provider CLI completed but did not call the Forge ${expectedPhase} completion tool.`);
             }
             const previous = artifacts[artifacts.length - 1];
             if ((previous.status ?? "").trim().toLowerCase() === "pass") {
@@ -1119,10 +1717,24 @@ async function readCompletionArtifactsForRun(worktreePath, workItemId, phase, de
     }
     return artifacts;
 }
-function providerRedactionEnv(dispatch) {
-    const env = completionRedactionEnv(exactRedactionSecrets(dispatch));
+function providerProcessEnv(dispatch) {
+    const env = {
+        ...completionRedactionEnv(exactRedactionSecrets(dispatch)),
+        ...providerCredentialEnv(dispatch)
+    };
     return Object.keys(env).length > 0 ? env : undefined;
 }
+function providerCredentialEnv(dispatch) {
+    const secret = dispatch.apiKeySecretGrant?.secret;
+    if (!secret || !dispatch.execution.requiresApiKeySecretGrant) {
+        return {};
+    }
+    const provider = dispatch.execution.provider.trim().toLowerCase();
+    if (provider === "codex" || provider === "openai") {
+        return { OPENAI_API_KEY: secret };
+    }
+    return {};
+}
 function exactRedactionSecrets(dispatch) {
     return dispatch.apiKeySecretGrant?.secret ? [dispatch.apiKeySecretGrant.secret] : [];
 }
@@ -1145,7 +1757,7 @@ export class StreamingProviderProcessRunner {
         return await new Promise((resolve, reject) => {
             const child = spawn(launch.command, launch.args, {
                 cwd: request.cwd,
-                env: request.env ? { ...process.env, ...request.env } : undefined,
+                env: buildProviderChildEnvironment(request.env),
                 stdio: ["ignore", "pipe", "pipe"],
                 windowsHide: true
             });
@@ -1280,9 +1892,6 @@ function quoteWindowsCommandLineArg(value) {
     }
     return `"${value.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/g, "$1$1")}"`;
 }
-async function fileExists(inputPath) {
-    return fs.stat(inputPath).then((stat) => stat.isFile()).catch(() => false);
-}
 async function readProcessLines(stream, onLine) {
     const reader = readline.createInterface({ input: stream });
     try {
@@ -1300,12 +1909,83 @@ function isFakeWorkerModel(model) {
 function sha256(content) {
     return crypto.createHash("sha256").update(content).digest("hex");
 }
+function buildDraftPrompt(dispatch) {
+    const draft = dispatch.draft;
+    if (!draft) {
+        throw new Error("Draft prompt is missing.");
+    }
+    const draftArtifacts = dispatch.artifacts
+        .filter((artifact) => artifact.scope === "operational" && ["command", "skill", "hook"].includes(artifact.kind))
+        .map((artifact) => `## ${artifact.kind}: ${artifact.slug}\n${artifact.body.trim()}`)
+        .join("\n\n");
+    const artifactSection = draftArtifacts
+        ? `\n\n# Injected Draft command/skills/hooks\n\n${draftArtifacts}`
+        : "";
+    const projectSection = [
+        draft.projectName ? `Project: ${draft.projectName}` : null,
+        draft.repoName ? `Repository: ${draft.repoName}` : null
+    ].filter(Boolean).join("\n");
+    const scopedProjectSection = projectSection ? `\n\n# Selected project context\n\n${projectSection}` : "";
+    return `${draft.systemPrompt}${scopedProjectSection}${artifactSection}
+
+Draft kind: ${draft.kind}
+
+${draft.userPrompt}
+
+This Draft path is a single draft-generation pass. Use the injected command/skills/hooks as planning instructions and cite their influence in the JSON content when relevant, but do not claim you used tool calls.
+
+Return ONLY the requested JSON object. Do not wrap it in markdown and do not modify files.`;
+}
+function extractJsonObject(content) {
+    let trimmed = content.trim();
+    if (trimmed.startsWith("```")) {
+        const firstNewline = trimmed.indexOf("\n");
+        const lastFence = trimmed.lastIndexOf("```");
+        if (firstNewline >= 0 && lastFence > firstNewline) {
+            trimmed = trimmed.slice(firstNewline + 1, lastFence).trim();
+        }
+    }
+    const start = trimmed.indexOf("{");
+    const end = trimmed.lastIndexOf("}");
+    return start >= 0 && end >= start ? trimmed.slice(start, end + 1) : trimmed;
+}
+function summarizeStderr(stderr) {
+    const trimmed = stderr.trim();
+    return trimmed ? `: ${clip(trimmed, 1000)}` : "";
+}
+function deterministicDraftPayload(dispatch) {
+    const kind = dispatch.draft?.kind ?? "work_item";
+    if (kind === "work_order") {
+        return {
+            title: "Deterministic runner Work Order draft",
+            summary: "Forge Runner generated this deterministic Work Order draft.",
+            objective: "Validate runner-backed Draft generation.",
+            planningPacket: "Runner-backed draft generation returned a Work Order JSON payload.",
+            decompositionContext: "Use this deterministic fixture only in bridge tests.",
+            assumptions: ["Forge Runner dispatch is available."],
+            warnings: []
+        };
+    }
+    if (kind === "story") {
+        return {
+            title: "Deterministic runner Story draft",
+            description: "Forge Runner generated this deterministic Story draft.",
+            acceptanceCriteria: "Given runner-backed Draft generation, when Forge requests a Story draft, then JSON is returned.",
+            points: 3
+        };
+    }
+    return {
+        title: "Deterministic runner Work Item draft",
+        description: "Forge Runner generated this deterministic Work Item draft.",
+        acceptanceCriteria: "Given runner-backed Draft generation, when Forge requests a draft, then JSON is returned.",
+        reproSteps: "Run Draft with a Forge Runner provider selected.",
+        systemInfo: "forge-bridge deterministic provider",
+        points: 1
+    };
+}
 export function formatProviderCliCommand(command) {
     return [command.command, ...command.args].map(singleLine).join(" ");
 }
-function yamlQuotedScalar(value) {
-    return JSON.stringify(singleLine(value));
-}
 function singleLine(value) {
     return value.replace(/\s+/g, " ").trim();
 }
@@ -1314,16 +1994,19 @@ export function buildProviderCliCommand(dispatch, run) {
     const normalizedProvider = provider.toLowerCase();
     const model = dispatch.execution.model.trim();
     if (normalizedProvider === "codex") {
-        const args = ["exec"];
+        const args = run ? ["-s", codexSandboxModeForPlatform(), "-a", "never", "exec"] : ["exec"];
         if (run?.completionTools) {
             args.push(...codexMcpConfigArgs(run.completionTools));
         }
         args.push("--model", model);
         if (run) {
-            args.push("--json", "--dangerously-bypass-approvals-and-sandbox");
+            args.push("--json");
             if (run.worktreePath) {
                 args.push("--cd", run.worktreePath);
             }
+            if (run.skipGitRepoCheck) {
+                args.push("--skip-git-repo-check");
+            }
             args.push(run.prompt ?? "");
         }
         return { command: "codex", args };
@@ -1344,6 +2027,35 @@ export function buildProviderCliCommand(dispatch, run) {
     }
     return { command: provider, args };
 }
+export function codexSandboxModeForPlatform(platform = process.platform) {
+    return platform === "win32" ? "danger-full-access" : "workspace-write";
+}
+function buildArchitectPrompt(dispatch) {
+    return `You are Forge's Architect lane running locally in a prepared git worktree.
+
+Work item: ${dispatch.workItem.id} — ${dispatch.workItem.title}
+
+Plan only. Do not implement source changes, do not create Develop phase artifacts, and do not mark the spec approved.
+Read injected Forge context under .forge plus the repository shape, then produce a repo-grounded implementation DAG with task tests, phase gates, final QA coverage, and a pending-approval spec.
+Implementation DAG tasks are Develop child tasks only: include focused repo/product implementation changes. Do not create child Develop tasks for parent-story QA, sign-off, materialized child inventory, child-count evidence, parent plan artifact checks, or final integrated acceptance proof; put those checks in qa_plan.final_qa.
+${architectRevisionInstruction(dispatch)}
+Forge owns protocol files: write Architect artifacts only through the completion MCP tool.
+
+${completionPromptForPhase("architect")}
+
+Finish only after calling forge.complete_architect_plan with implementation_plan, qa_plan, status, summary, and report/report_markdown.`;
+}
+function architectRevisionInstruction(dispatch) {
+    if (!dispatch.architectRevision) {
+        return "";
+    }
+    return `
+Architect revision context:
+- Previous plan id: ${dispatch.architectRevision.priorPlanId}
+- Previous content hash: ${dispatch.architectRevision.priorContentHash}
+- Reviewer feedback: ${dispatch.architectRevision.feedback}
+Revise the prior plan in response to the feedback. Preserve accepted scope and only change what the feedback requires.`;
+}
 function buildImplementationPrompt(dispatch, phase = completionPhaseFromDispatch(dispatch)) {
     return `You are Forge's ${phase.replace(/_/g, " ")} phase runner running locally in a prepared git worktree.
 
@@ -1372,6 +2084,20 @@ ${completionPromptForDevelopCycle(phase)}
 
 Finish with a concise summary of changed files and verification after the validation completion tool has accepted the work, or after the current phase tool records a non-pass blocker.`;
 }
+function buildDebugCyclePrompt(dispatch, phase = completionPhaseFromDispatch(dispatch)) {
+    return `You are Forge's Debug lane running locally in a prepared git worktree for a bug work item.
+
+Read .forge/work-items/${dispatch.workItem.id}/spec.md, reproduce or characterize the bug, isolate root cause, apply the smallest safe fix, then prove the regression in this same provider session.
+Start in the ${phase.replace(/_/g, " ")} gate. Do not stop after a passing Debug gate; continue through the next Debug MCP instruction returned by the tool server until debug_regression is accepted or the current gate records a non-pass blocker.
+${debugQaReworkInstruction(dispatch)}
+Use the repository's existing conventions. Run focused tests when practical, especially the original repro and required regressions.
+Forge owns protocol files: worktree prep, injected .forge commands/hooks/skills, Debug verdict artifacts, reports, and commits.
+Read Forge-provided context under .forge when needed, but do not edit .forge files or create Forge Debug artifacts by hand.
+
+${completionPromptForDebugCycle(isDebugCompletionPhaseForProvider(phase) ? phase : "debug_repro")}
+
+Finish with a concise summary of changed files and verification after the debug_regression completion tool has accepted the work, or after the current Debug gate tool records a non-pass blocker.`;
+}
 function qaReworkImplementationInstruction(dispatch) {
     if (!dispatch.qaRework) {
         return "";
@@ -1381,7 +2107,20 @@ QA rework context:
 - Attempt ${dispatch.qaRework.attempt}/${dispatch.qaRework.maxAttempts}
 - Rework packet: ${dispatch.qaRework.packetPath}
 - Required QA finding IDs: ${dispatch.qaRework.findingIds.join(", ")}
-Read the packet JSON and fix or explicitly dispute each listed finding. The implementation completion artifact must include resolved_findings entries for every required QA ID with qa_id, status, summary, evidence, changed_files, tests_added_or_updated, and regression_evidence.`;
+Read the packet JSON and fix or explicitly dispute each listed finding. The implementation completion artifact must include resolved_findings entries for every required QA ID with qa_id, status, summary, evidence, changed_files, tests_added_or_updated, and regression_evidence.
+Use only these resolved_findings status values: resolved, disputed, or not_reproduced. Use resolved when the finding was fixed; do not use fixed.`;
+}
+function debugQaReworkInstruction(dispatch) {
+    if (!dispatch.qaRework) {
+        return "";
+    }
+    return `
+QA rework context for Debug:
+- Attempt ${dispatch.qaRework.attempt}/${dispatch.qaRework.maxAttempts}
+- Rework packet: ${dispatch.qaRework.packetPath}
+- Required QA finding IDs: ${dispatch.qaRework.findingIds.join(", ")}
+Read the packet JSON, reproduce or characterize each listed finding, fix or explicitly dispute it, and include resolved_findings entries for every required QA ID in forge.complete_debug_fix with qa_id, status, summary, evidence, changed_files, tests_added_or_updated, and regression_evidence.
+Use only these resolved_findings status values: resolved, disputed, or not_reproduced. Use resolved when the finding was fixed; do not use fixed.`;
 }
 function qaReworkRetestInstruction(dispatch) {
     if (!dispatch.qaRework) {
@@ -1418,6 +2157,39 @@ function qaBrowserInstruction(dispatch) {
     const routes = launchTarget.routes.length > 0 ? launchTarget.routes.join(", ") : "not specified";
     return `Browser/app launch context:\n- Browser QA required: ${qaBrowser.required ? "yes" : "no, unless the diff/AC requires it"}\n- URL: ${launchTarget.url || "not specified"}\n- Ready URL: ${launchTarget.ready_url || "not specified"}\n- Launch command: ${launchTarget.command || "not specified"}\n- Working directory: ${launchTarget.working_directory || "repo root"}\n- Routes to cover: ${routes}\n- Notes: ${launchTarget.notes || "none"}\n- Browser sidecars path: ${qaBrowser.artifactsPath || `.forge/work-items/${dispatch.workItem.id}/artifacts/qa`}`;
 }
+function storyQaInstruction(dispatch) {
+    const storyQa = dispatch.storyQa;
+    if (!storyQa) {
+        return "";
+    }
+    const childLines = storyQa.childTasks.map((child) => {
+        const dependencies = child.dependencyWorkItemIds.length > 0
+            ? child.dependencyWorkItemIds.join(", ")
+            : "none";
+        const validation = child.validationArtifact
+            ? `${child.validationArtifact.status} (${child.validationArtifact.path || "artifact path unavailable"})`
+            : "missing";
+        const childQa = child.qaArtifact
+            ? `${child.qaArtifact.status} (${child.qaArtifact.path || "artifact path unavailable"})`
+            : "not present";
+        return `- ${child.title} (${child.workItemId}, architect ${child.architectTaskId}, phase ${child.phaseId}/${child.phaseOrder}); deps: ${dependencies}; validation: ${validation}; child QA: ${childQa}`;
+    }).join("\n");
+    const finalQa = storyQa.finalQaChecks.length > 0
+        ? storyQa.finalQaChecks.map((check) => `- ${check}`).join("\n")
+        : "- No final QA checks were provided in qa.plan.final_qa.";
+    return `Story QA integration context:
+- Story work item: ${storyQa.storyWorkItemId}
+- Plan: ${storyQa.planId} / ${storyQa.planContentHash}
+- Story worktree: ${storyQa.worktreeKey}
+- Branch: ${storyQa.branch}
+- Architect implementation.plan.json provided: ${storyQa.implementationPlanJson ? "yes" : "no"}
+- Architect qa.plan.json provided: ${storyQa.qaPlanJson ? "yes" : "no"}
+Materialized child tasks and evidence:
+${childLines || "- No child tasks were provided."}
+Architect final QA checks:
+${finalQa}
+This is parent Story QA: inspect the integrated Story result, all current-plan child specs/evidence, and the final worktree state. Do not treat the final child task as separately signed off.`;
+}
 function buildQaPrompt(dispatch, laneSpec) {
     return `You are Forge's QA lane running locally in a prepared git worktree.
 
@@ -1442,6 +2214,7 @@ ${dispatch.workItem.reproSteps || "Not provided."}
 System info / environment notes:
 ${dispatch.workItem.systemInfo || "Not provided."}
 
+${storyQaInstruction(dispatch)}
 Inspect the validated implementation and Forge artifacts under .forge/work-items/${dispatch.workItem.id}/artifacts/ when present, especially implementation, self-review, and validation evidence.
 ${qaBrowserInstruction(dispatch)}
 ${qaReworkRetestInstruction(dispatch)}
@@ -1483,6 +2256,7 @@ PR context:
 - Unresolved comments: ${pr?.unresolvedThreads ?? "unknown"}
 
 Use the PR URL, local git metadata, and available GitHub tooling/auth to inspect unresolved review threads. Make focused code or test changes that answer the feedback, commit the changes, and push ${branchName} to origin.
+After the push succeeds, Forge will resolve the addressed review threads through the pull request API.
 If the review thread contents are unavailable, stop with a clear summary of what could not be accessed instead of guessing.
 Keep the original work item intent intact:
 - Work item: ${dispatch.workItem.id}
@@ -1551,31 +2325,31 @@ class CursorStreamJsonState {
     consume(line) {
         const event = parseJsonLine(line);
         if (!event) {
-            return null;
+            return [];
         }
         const type = stringField(event, "type");
         if (type === "system" && stringField(event, "subtype") === "init") {
             this.sessionId = stringField(event, "session_id");
             if (this.sessionId && !this.emittedSession) {
                 this.emittedSession = true;
-                return {
-                    role: "runner",
-                    kind: "checkpoint",
-                    content: `Cursor session started: ${this.sessionId}.`,
-                    eventType: "provider_thread_started"
-                };
+                return [{
+                        role: "runner",
+                        kind: "checkpoint",
+                        content: `Cursor session started: ${this.sessionId}.`,
+                        eventType: "provider_thread_started"
+                    }];
             }
         }
         if (type === "assistant") {
             const text = assistantMessageText(event);
             if (text) {
                 this.finalMessage = clip(text, 4000);
-                return {
-                    role: "assistant",
-                    kind: "message",
-                    content: this.finalMessage,
-                    eventType: "provider_message"
-                };
+                return [{
+                        role: "assistant",
+                        kind: "message",
+                        content: this.finalMessage,
+                        eventType: "provider_message"
+                    }];
             }
         }
         if (type === "tool_call") {
@@ -1584,23 +2358,23 @@ class CursorStreamJsonState {
             if (subtype === "started") {
                 const summary = formatCursorToolCallStarted(toolCall);
                 if (summary) {
-                    return {
-                        role: "worker",
-                        kind: "checkpoint",
-                        content: summary,
-                        eventType: "provider_tool_call"
-                    };
+                    return [{
+                            role: "worker",
+                            kind: "checkpoint",
+                            content: summary,
+                            eventType: "provider_tool_call"
+                        }];
                 }
             }
             if (subtype === "completed") {
                 const completed = formatCursorToolCallCompleted(toolCall);
                 if (completed) {
-                    return {
-                        role: "worker",
-                        kind: completed.kind,
-                        content: completed.content,
-                        eventType: completed.kind === "file_edit" ? "provider_file_edit" : "provider_tool_call"
-                    };
+                    return [{
+                            role: "worker",
+                            kind: completed.kind,
+                            content: completed.content,
+                            eventType: completed.kind === "file_edit" ? "provider_file_edit" : "provider_tool_call"
+                        }];
                 }
             }
         }
@@ -1612,14 +2386,14 @@ class CursorStreamJsonState {
             this.accumulateUsage(event);
         }
         if (type === "error" || (type === "result" && event.is_error === true)) {
-            return {
-                role: "runner",
-                kind: "error",
-                content: clip(line.trim(), 1000),
-                eventType: "provider_cli_error"
-            };
+            return [{
+                    role: "runner",
+                    kind: "error",
+                    content: clip(line.trim(), 1000),
+                    eventType: "provider_cli_error"
+                }];
         }
-        return null;
+        return [];
     }
     accumulateUsage(event) {
         const usage = objectField(event, "usage");
@@ -1750,37 +2524,37 @@ class CodexJsonState {
     consume(line) {
         const event = parseJsonLine(line);
         if (!event) {
-            return null;
+            return [];
         }
         const type = stringField(event, "type") ?? "";
         if (type === "thread.started") {
             this.threadId = stringField(event, "thread_id");
             if (this.threadId && !this.emittedThread) {
                 this.emittedThread = true;
-                return {
-                    role: "runner",
-                    kind: "checkpoint",
-                    content: `Codex thread started: ${this.threadId}.`,
-                    eventType: "provider_thread_started"
-                };
+                return [{
+                        role: "runner",
+                        kind: "checkpoint",
+                        content: `Codex thread started: ${this.threadId}.`,
+                        eventType: "provider_thread_started"
+                    }];
             }
         }
         if (type === "turn.completed") {
             this.accumulateUsage(event);
-            return {
-                role: "runner",
-                kind: "checkpoint",
-                content: "Codex turn completed.",
-                eventType: "provider_turn_completed"
-            };
+            return [{
+                    role: "runner",
+                    kind: "checkpoint",
+                    content: "Codex turn completed.",
+                    eventType: "provider_turn_completed"
+                }];
         }
         if (type === "turn.failed" || type === "error") {
-            return {
-                role: "runner",
-                kind: "error",
-                content: clip(line.trim(), 1000),
-                eventType: "provider_cli_error"
-            };
+            return [{
+                    role: "runner",
+                    kind: "error",
+                    content: clip(line.trim(), 1000),
+                    eventType: "provider_cli_error"
+                }];
         }
         if (type === "item.completed" || type === "item.updated") {
             const item = objectField(event, "item");
@@ -1789,28 +2563,32 @@ class CodexJsonState {
                 const text = stringField(item, "text");
                 if (text) {
                     this.finalMessage = clip(text, 4000);
-                    return {
-                        role: "assistant",
-                        kind: "message",
-                        content: this.finalMessage,
-                        eventType: "provider_message"
-                    };
+                    return [{
+                            role: "assistant",
+                            kind: "message",
+                            content: this.finalMessage,
+                            eventType: "provider_message"
+                        }];
                 }
             }
             if (itemType === "command_execution") {
                 const command = stringField(item, "command");
                 const status = stringField(item, "status");
                 if (command) {
-                    return {
-                        role: "worker",
-                        kind: "checkpoint",
-                        content: `Codex command ${status || "completed"}: ${clip(command, 500)}`,
-                        eventType: "provider_command"
-                    };
+                    return [{
+                            role: "worker",
+                            kind: "checkpoint",
+                            content: `Codex command ${status || "completed"}: ${clip(command, 500)}`,
+                            eventType: "provider_command"
+                        }];
                 }
             }
         }
-        return null;
+        const mcpEvents = formatCodexMcpToolCallEvents(type, event);
+        if (mcpEvents.length > 0) {
+            return mcpEvents;
+        }
+        return [];
     }
     accumulateUsage(event) {
         const usage = objectField(event, "usage");
@@ -1826,6 +2604,113 @@ class CodexJsonState {
         });
     }
 }
+function formatCodexMcpToolCallEvents(type, event) {
+    if (type !== "item.started" && type !== "item.updated" && type !== "item.completed") {
+        return [];
+    }
+    const item = objectField(event, "item");
+    const itemType = stringField(item, "type") ?? "";
+    const serverName = mcpServerName(item);
+    const toolName = mcpToolName(item);
+    const isMcpItem = itemType.toLowerCase().includes("mcp")
+        || Boolean(serverName)
+        || (toolName ? isForgeCompletionTool(toolName) || toolName.toLowerCase().includes("mcp") : false);
+    if (!isMcpItem || !toolName) {
+        return [];
+    }
+    const status = normalizedString(stringField(item, "status")
+        ?? stringField(event, "status")
+        ?? (type === "item.started" ? "started" : type === "item.completed" ? "completed" : "updated"));
+    const failed = status === "failed" || status === "error" || status === "cancelled" || Boolean(item.error);
+    const completed = failed || type === "item.completed" || status === "completed" || status === "succeeded" || status === "success";
+    const started = type === "item.started" || status === "started" || status === "running" || status === "in_progress";
+    const data = safeProviderMcpData(item, serverName ?? "unknown", toolName, status);
+    const label = `${serverName ?? "unknown"}.${toolName}`;
+    if (failed) {
+        const summary = mcpErrorSummary(item) ?? "MCP tool call failed.";
+        const events = [{
+                role: "tool",
+                kind: "error",
+                content: `MCP tool call failed: ${label} - ${summary}`,
+                eventType: "provider_mcp_call_failed",
+                data
+            }];
+        if (isForgeCompletionTool(toolName)) {
+            events.push({
+                role: "tool",
+                kind: "error",
+                content: `Forge completion tool validation failed: ${label} - ${summary}`,
+                eventType: "completion_tool_validation_failed",
+                data
+            });
+        }
+        return events;
+    }
+    if (completed) {
+        return [{
+                role: "tool",
+                kind: "checkpoint",
+                content: `MCP tool call completed: ${label}.`,
+                eventType: "provider_mcp_call_completed",
+                data
+            }];
+    }
+    if (started) {
+        return [{
+                role: "tool",
+                kind: "checkpoint",
+                content: `MCP tool call started: ${label}.`,
+                eventType: "provider_mcp_call_started",
+                data
+            }];
+    }
+    return [];
+}
+function mcpServerName(item) {
+    return stringField(item, "server")
+        ?? stringField(item, "server_name")
+        ?? stringField(item, "mcp_server")
+        ?? stringField(objectField(item, "mcp"), "server")
+        ?? stringField(objectField(item, "mcp"), "server_name");
+}
+function mcpToolName(item) {
+    return stringField(item, "tool")
+        ?? stringField(item, "tool_name")
+        ?? stringField(item, "name")
+        ?? stringField(objectField(item, "function"), "name")
+        ?? stringField(objectField(item, "mcp"), "tool")
+        ?? stringField(objectField(item, "mcp"), "tool_name");
+}
+function mcpErrorSummary(item) {
+    const direct = stringField(item, "error")
+        ?? stringField(item, "error_message")
+        ?? stringField(item, "message");
+    if (direct) {
+        return clip(direct, 600);
+    }
+    const error = objectField(item, "error");
+    return stringField(error, "message")
+        ?? stringField(error, "summary")
+        ?? stringField(objectField(item, "result"), "error")
+        ?? null;
+}
+function safeProviderMcpData(item, serverName, toolName, status) {
+    const elapsedMs = numericField(item, "elapsed_ms") ?? numericField(item, "duration_ms");
+    return JSON.stringify(stripUndefined({
+        server_name: serverName,
+        tool_name: toolName,
+        status,
+        elapsed_ms: elapsedMs,
+        error_summary: mcpErrorSummary(item)
+    }));
+}
+function isForgeCompletionTool(toolName) {
+    const normalized = toolName.trim().toLowerCase();
+    return normalized.startsWith("forge.complete_")
+        || normalized.startsWith("complete_")
+        || normalized.includes("forge.complete_")
+        || normalized.includes("complete_architect_plan");
+}
 function objectField(source, key) {
     const value = source[key];
     return value && typeof value === "object" && !Array.isArray(value)
@@ -1836,6 +2721,13 @@ function stringField(source, key) {
     const value = source[key];
     return typeof value === "string" && value.trim().length > 0 ? value : null;
 }
+function numericField(source, key) {
+    const value = source[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function stripUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
 function normalizedString(value) {
     return value.trim().toLowerCase().replace(/-/g, "_");
 }