@entelligentsia/forgecli 1.0.2 → 1.0.3

package/dist/extensions/forgecli/fix-bug.js

@@ -56,6 +56,7 @@ import { resolveModelForPhase } from "./model-resolver.js";
 import { loadWorkflow } from "./parsers/workflow-loader.js";
 import { buildPhaseEvent, buildSummariesBlock, drainFrictionFile, emitEvent, findPredecessorIndex, formatLocalTime, isNonInteractive, judgementFromSummary, runPreflightGate, validateId, } from "./run-task.js";
 import { getSessionRegistry } from "./session-registry.js";
+import { OrchestratorTranscriptWriter } from "./subagent/orchestrator-transcript.js";
 import { resolveToCanonicalId, resolveToolDir } from "./store-resolver.js";
 import { attachViewportObserver } from "./viewport-events.js";
 import { fmtPhaseSummary } from "./viewport-renderer.js";
@@ -67,26 +68,27 @@ import { fmtPhaseSummary } from "./viewport-renderer.js";
 // FORGE-S25-T16: readPersonaDirBug / readPipelineNamesBug extracted to
 // lib/catalog-helpers.ts and imported above with aliases (H-4, N-H-G).
 export const BUG_PHASES = [
-    { role: "triage", workflowFile: "fix_bug", personaNoun: "bug-fixer", isReview: false, maxIterations: 1 },
-    { role: "plan-fix", workflowFile: "fix_bug", personaNoun: "bug-fixer", isReview: false, maxIterations: 1 },
+    // FORGE-BUG-040: each phase points at its own phase-scoped subagent workflow.
+    // Previously triage/plan-fix/implement all pointed at fix_bug.md (the
+    // orchestrator-only body), which caused the triage subagent to execute
+    // the full lifecycle in a single invocation. plan-fix and implement reuse
+    // plan_task.md / implement_plan.md (bug-mode) per meta-fix-bug.md
+    // § Pipeline Phases — the bug-mode entity-kind detection is built into
+    // those workflows already.
+    { role: "triage", workflowFile: "triage", personaNoun: "bug-fixer", isReview: false, maxIterations: 1 },
+    { role: "plan-fix", workflowFile: "plan_task", personaNoun: "engineer", isReview: false, maxIterations: 1 },
     { role: "review-plan", workflowFile: "review_plan", personaNoun: "supervisor", isReview: true, maxIterations: 3 },
-    { role: "implement", workflowFile: "fix_bug", personaNoun: "bug-fixer", isReview: false, maxIterations: 1 },
+    { role: "implement", workflowFile: "implement_plan", personaNoun: "engineer", isReview: false, maxIterations: 1 },
     { role: "review-code", workflowFile: "review_code", personaNoun: "supervisor", isReview: true, maxIterations: 3 },
     { role: "approve", workflowFile: "architect_approve", personaNoun: "architect", isReview: true, maxIterations: 3 },
     { role: "commit", workflowFile: "commit_task", personaNoun: "engineer", isReview: false, maxIterations: 1 },
 ];
-// Map phase.role → canonical summary key written by base-pack workflows.
-// Phases mapped to null use update-status bug instead of set-bug-summary
-// for verdict tracking (Option B).
-export const BUG_SUMMARY_KEY_BY_ROLE = {
-    triage: "triage",
-    "plan-fix": "plan",
-    "review-plan": "review_plan",
-    implement: "implementation",
-    "review-code": "code_review",
-    approve: "approve", // read from bug.summaries.approve (set-bug-summary)
-    commit: null, // commit transitions bug.status → fixed (terminal), no summaries entry
-};
+// FORGE-BUG-040: BUG_SUMMARY_KEY_BY_ROLE lives in
+// subagent/phase-summary-map.ts so the new phase-guard.ts can import
+// it without dragging fix-bug.ts into a forge-tools import cycle.
+// Re-exported here for backwards-compatibility with existing call sites.
+export { BUG_SUMMARY_KEY_BY_ROLE } from "./subagent/phase-summary-map.js";
+import { BUG_SUMMARY_KEY_BY_ROLE } from "./subagent/phase-summary-map.js";
 // Bug-event type tokens — explicit mapping per review finding #3.
 // Non-review phases always emit the pass token. Review phases select
 // pass or fail based on ec.judgement.verdict.
@@ -339,9 +341,11 @@ export function composeBugBody(subWorkflowMd, bugId, phaseRole, bugStatusBeforeP
     if (phaseRole === "commit" && bugStatusBeforePhase) {
         entityKindLines.push(`- Commit phase: after the git commit lands, transition bug.status from '${bugStatusBeforePhase}' to 'fixed'.`);
     }
-    if (phaseRole === "triage") {
-        entityKindLines.push('- Triage phase: in addition to writing TRIAGE.md and TRIAGE-SUMMARY.json, the summary MUST include a `route` field set to `"A"` or `"B"`.', "  Path A (short-circuit): severity == minor AND single-file fix ≤ ~20 lines AND no schema/API/migration AND regression test obvious from repro.", "  Path B (default): everything else. When in doubt, choose B.", "  The orchestrator reads bug.summaries.triage.route to select the downstream phase list.");
-    }
+    // FORGE-BUG-040: the triage-phase hint block previously prepended here
+    // compensated for the orchestrator-only fix_bug.md being delivered to
+    // the triage subagent. With the new phase-scoped triage.md sub-workflow,
+    // the route-field contract and Path A/B criteria are documented natively
+    // in the workflow body — no compose-time injection required.
     const parts = [
         `Read the workflow below and follow it. Bug ID: ${bugId}.`,
         "",
@@ -474,476 +478,301 @@ export async function runBugPipeline(opts) {
             };
         }
     }
-    while (currentPhaseIndex < BUG_PHASES.length) {
-        // ── Between-phase cancellation gate ────────────────────────────
-        if (opts.signal?.aborted) {
-            ctx.ui.notify(`⊘ forge:fix-bug — ${bugId} cancelled by user.`, "info");
-            registry.completePhase(bugId, BUG_PHASES[currentPhaseIndex]?.role ?? "unknown", "cancelled");
-            registry.confirmCancelled(bugId);
-            // ADR-S21-01: preserve state file so cancelled runs are resumable
-            writeBugState(cwd, {
-                bugId,
-                phaseIndex: currentPhaseIndex,
-                iterationCounts,
-                halted: false,
-                status: "cancelled",
-                lastError: undefined,
-                savedAt: new Date().toISOString(),
-            });
-            return { status: "cancelled", lastPhaseIndex: currentPhaseIndex, iterationCounts };
-        }
-        const phase = BUG_PHASES[currentPhaseIndex];
-        if (!phase) {
-            ctx.ui.notify(`× forge:fix-bug — invalid phase index ${currentPhaseIndex}`, "error");
-            return {
-                status: "failed",
-                lastPhaseIndex: currentPhaseIndex,
-                iterationCounts,
-                lastError: `invalid phase index ${currentPhaseIndex}`,
-            };
-        }
-        ctx.ui.setStatus?.(STATUS_KEY, `fix-bug ${bugId}: phase ${currentPhaseIndex + 1}/${BUG_PHASES.length} (${phase.role})`);
-        ctx.ui.notify(`→ ${bugId}: ${phase.role} (phase ${currentPhaseIndex + 1}/${BUG_PHASES.length})`, "info");
-        const subWorkflowPath = path.join(cwd, ".forge", "workflows", `${phase.workflowFile}.md`);
-        // ── Read sub-workflow ─────────────────────────────────────────
-        let subWorkflowMd;
-        let subWorkflowAudience = "any";
-        try {
-            const loaded = loadWorkflow(subWorkflowPath);
-            subWorkflowMd = loaded.rawMarkdown;
-            subWorkflowAudience = loaded.audience;
-        }
-        catch (err) {
-            const e = err;
-            ctx.ui.notify(`× forge:fix-bug — failed to read sub-workflow for ${phase.role}: ${e.message ?? "unknown"}`, "error");
-            writeBugState(cwd, {
-                bugId,
-                phaseIndex: currentPhaseIndex,
-                iterationCounts,
-                halted: true,
-                lastError: `sub-workflow read failed: ${e.message ?? "unknown"}`,
-                savedAt: new Date().toISOString(),
-            });
-            return {
-                status: "failed",
-                lastPhaseIndex: currentPhaseIndex,
-                iterationCounts,
-                lastError: `sub-workflow read failed: ${e.message ?? "unknown"}`,
-            };
-        }
-        // ── 6a. Phase skip (state-aware, defense-in-depth) ─────────────
-        // Belt-and-suspenders alongside the explicit summaries.triage.route
-        // branch (handled in section 6c below). Some subagents in some
-        // runtimes still go end-to-end during triage instead of just triaging
-        // — rather than roll back the work they did, skip non-review phases
-        // whose output is already reflected in the bug status. Review phases
-        // are never skipped — they are quality gates that must always run.
-        //
-        // Post-v0.44.0: terminal status is `fixed` only. `approved` and
-        // `verified` are no longer valid bug status values; references
-        // removed.
-        const PHASE_SKIP_STATES = {
-            "plan-fix": new Set(["fixed"]),
-            implement: new Set(["fixed"]),
-            commit: new Set(["fixed"]), // commit writes the terminal status; skip if already there
-        };
-        const bugNow = readBugRecord(bugId, storeCli, cwd);
-        const skipStates = PHASE_SKIP_STATES[phase.role];
-        if (skipStates && bugNow?.status && skipStates.has(bugNow.status) && !phase.isReview) {
-            ctx.ui.notify(`⊘ forge:fix-bug — skipping ${phase.role}: bug ${bugId} is already '${bugNow.status}' (work already done).`, "info");
-            // Write a synthetic "approved" summary so downstream `after` predecessor
-            // verdict checks find a verdict and don't block review phases.
-            const summaryKey = BUG_SUMMARY_KEY_BY_ROLE[phase.role];
-            if (summaryKey) {
-                const synthSummary = {
-                    objective: `Phase ${phase.role} skipped — bug already ${bugNow.status}`,
-                    findings: ["Subagent completed fix during triage (Path A); phase output implicitly satisfied."],
-                    // Non-review phases should have verdict "n/a" — the phase
-                    // didn't produce a gate verdict. This matches the `after
-                    // <phase> = n/a` preflight gate contract. Review phases
-                    // use "approved" since they are gate phases.
-                    verdict: phase.isReview ? "approved" : "n/a",
-                    written_at: new Date().toISOString(),
-                };
-                const synthFile = path.join(cwd, ".forge", "cache", `synthetic-summary-${bugId}-${summaryKey}.json`);
-                fs.writeFileSync(synthFile, JSON.stringify(synthSummary, null, 2), "utf8");
-                const synthResult = spawnSync("node", [storeCli, "set-bug-summary", bugId, summaryKey, synthFile], {
-                    cwd,
-                    encoding: "utf8",
-                });
-                if (synthResult.status !== 0) {
-                    ctx.ui.notify(`⚠ forge:fix-bug — synthetic summary write failed for ${phase.role}: ${String(synthResult.stderr).trim()}`, "warning");
-                }
-                try {
-                    fs.unlinkSync(synthFile);
-                }
-                catch {
-                    /* non-fatal */
-                }
-            }
-            currentPhaseIndex++;
-            continue;
-        }
-        // ── 6b. Preflight gate ────────────────────────────────────────
-        // Skip preflight gate for triage phase of new bugs (PENDING- placeholder)
-        // because the bug record doesn't exist yet — gates referencing bug fields
-        // would always fail.
-        //
-        // Also skip for review phases when the bug is already in a terminal
-        // state ("fixed"). Path A bugs get fixed during triage, then the
-        // preflight gate's `forbid bug.status == fixed` and `after implement
-        // = n/a` checks block review-code/review-plan even though we
-        // deliberately want to run those reviews. The review subagent handles
-        // the already-fixed scenario internally.
-        const pendingBugId = bugId.startsWith("PENDING-");
-        const bugAlreadyFixed = bugNow?.status === "fixed" && phase.isReview;
-        if (!pendingBugId && !bugAlreadyFixed && fs.existsSync(preflightGate)) {
-            const preflightResult = runPreflightGate(preflightGate, phase.role, bugId, cwd, "bug");
-            if (preflightResult === "halt") {
-                ctx.ui.notify(`× forge:fix-bug — preflight gate failed for phase ${phase.role} (exit 1); halting.`, "error");
+    // ── Orchestrator transcript ──────────────────────────────────────────
+    // One JSONL file per pipeline run, ISO-prefixed in its filename so
+    // review-loop iterations (plan → review → plan → review) preserve
+    // their own logs instead of overwriting each other. Captures every
+    // ctx.ui.notify line plus structured phase-boundary events.
+    const orchTranscript = new OrchestratorTranscriptWriter({
+        cwd,
+        entityKind: "bug",
+        entityId: bugId,
+    });
+    const __origNotify = ctx.ui.notify.bind(ctx.ui);
+    ctx.ui.notify = ((msg, level) => {
+        __origNotify(msg, level);
+        orchTranscript.record({
+            kind: "notify",
+            ts: new Date().toISOString(),
+            level: (level ?? "info"),
+            message: typeof msg === "string" ? msg : String(msg),
+        });
+    });
+    const pipelineStartMs = Date.now();
+    try {
+        while (currentPhaseIndex < BUG_PHASES.length) {
+            // ── Between-phase cancellation gate ────────────────────────────
+            if (opts.signal?.aborted) {
+                ctx.ui.notify(`⊘ forge:fix-bug — ${bugId} cancelled by user.`, "info");
+                registry.completePhase(bugId, BUG_PHASES[currentPhaseIndex]?.role ?? "unknown", "cancelled");
+                registry.confirmCancelled(bugId);
+                // ADR-S21-01: preserve state file so cancelled runs are resumable
                 writeBugState(cwd, {
                     bugId,
                     phaseIndex: currentPhaseIndex,
                     iterationCounts,
-                    halted: true,
-                    lastError: `preflight gate exit 1 for ${phase.role}`,
+                    halted: false,
+                    status: "cancelled",
+                    lastError: undefined,
                     savedAt: new Date().toISOString(),
                 });
+                return { status: "cancelled", lastPhaseIndex: currentPhaseIndex, iterationCounts };
+            }
+            const phase = BUG_PHASES[currentPhaseIndex];
+            if (!phase) {
+                ctx.ui.notify(`× forge:fix-bug — invalid phase index ${currentPhaseIndex}`, "error");
                 return {
-                    status: "halted",
+                    status: "failed",
                     lastPhaseIndex: currentPhaseIndex,
                     iterationCounts,
-                    lastError: `preflight gate exit 1 for ${phase.role}`,
+                    lastError: `invalid phase index ${currentPhaseIndex}`,
                 };
             }
-            if (preflightResult === "escalate") {
-                ctx.ui.notify(`× forge:fix-bug — preflight gate escalated for phase ${phase.role} (exit 2); manual intervention required.`, "error");
+            ctx.ui.setStatus?.(STATUS_KEY, `fix-bug ${bugId}: phase ${currentPhaseIndex + 1}/${BUG_PHASES.length} (${phase.role})`);
+            ctx.ui.notify(`→ ${bugId}: ${phase.role} (phase ${currentPhaseIndex + 1}/${BUG_PHASES.length})`, "info");
+            orchTranscript.record({
+                kind: "phase-start",
+                ts: new Date().toISOString(),
+                phase: phase.role,
+                phaseIndex: currentPhaseIndex,
+                phaseCount: BUG_PHASES.length,
+                attempt: (iterationCounts[phase.role] ?? 0) + 1,
+                workflowFile: phase.workflowFile,
+                persona: phase.personaNoun,
+            });
+            const subWorkflowPath = path.join(cwd, ".forge", "workflows", `${phase.workflowFile}.md`);
+            // ── Read sub-workflow ─────────────────────────────────────────
+            let subWorkflowMd;
+            let subWorkflowAudience = "any";
+            try {
+                const loaded = loadWorkflow(subWorkflowPath);
+                subWorkflowMd = loaded.rawMarkdown;
+                subWorkflowAudience = loaded.audience;
+            }
+            catch (err) {
+                const e = err;
+                ctx.ui.notify(`× forge:fix-bug — failed to read sub-workflow for ${phase.role}: ${e.message ?? "unknown"}`, "error");
                 writeBugState(cwd, {
                     bugId,
                     phaseIndex: currentPhaseIndex,
                     iterationCounts,
                     halted: true,
-                    lastError: `preflight gate exit 2 (escalate) for ${phase.role}`,
+                    lastError: `sub-workflow read failed: ${e.message ?? "unknown"}`,
                     savedAt: new Date().toISOString(),
                 });
-                return {
-                    status: "escalated",
-                    lastPhaseIndex: currentPhaseIndex,
-                    iterationCounts,
-                    lastError: `preflight gate exit 2 (escalate) for ${phase.role}`,
-                };
-            }
-        }
-        // ── 6. Materialization-marker check ───────────────────────────
-        // N-H-E: Skip for the monolithic fix_bug.md — it is the orchestrator prose
-        // algorithm, not a sub-workflow that subagents run tool calls against.
-        // Triage/plan-fix/implement phases reference fix_bug.md for their
-        // prose body but the actual tool-use discipline (Store-Write Verification,
-        // forge_store) lives in the sub-workflows (review_plan.md, commit_task.md,
-        // etc.) which get checked when their own phases run.
-        if (phase.workflowFile !== "fix_bug") {
-            const markerCheck = checkMaterialization(subWorkflowPath, subWorkflowMd);
-            if (!markerCheck.ok) {
-                for (const marker of markerCheck.missing) {
-                    ctx.ui.notify(`× workflow regression: ${marker} not found in ${subWorkflowPath}`, "error");
-                }
                 return {
                     status: "failed",
                     lastPhaseIndex: currentPhaseIndex,
                     iterationCounts,
-                    lastError: `materialization markers missing: ${markerCheck.missing.join(", ")}`,
+                    lastError: `sub-workflow read failed: ${e.message ?? "unknown"}`,
                 };
             }
-        }
-        // ── 5. Audience check ─────────────────────────────────────────
-        // fix_bug.md is orchestrator-only but the subagent doesn't "run" it as a
-        // workflow — the orchestrator reads its prose and composes the body text.
-        // Skip the audience gate for the monolithic fix_bug.md; only check the
-        // true sub-workflows (review_plan, review_code, architect_approve, commit_task)
-        // which the subagent does run directly.
-        const audienceOk = phase.workflowFile === "fix_bug" ||
-            CallerContextStore.asSubagent(() => assertAudience({ workflowName: phase.workflowFile, audience: subWorkflowAudience }, ctx));
-        if (!audienceOk) {
-            writeBugState(cwd, {
-                bugId,
-                phaseIndex: currentPhaseIndex,
-                iterationCounts,
-                halted: true,
-                lastError: `audience check failed for ${phase.workflowFile}`,
-                savedAt: new Date().toISOString(),
-            });
-            return {
-                status: "failed",
-                lastPhaseIndex: currentPhaseIndex,
-                iterationCounts,
-                lastError: `audience check failed for ${phase.workflowFile}`,
+            // ── 6a. Phase skip (state-aware, defense-in-depth) ─────────────
+            // Belt-and-suspenders alongside the explicit summaries.triage.route
+            // branch (handled in section 6c below). Some subagents in some
+            // runtimes still go end-to-end during triage instead of just triaging
+            // — rather than roll back the work they did, skip non-review phases
+            // whose output is already reflected in the bug status. Review phases
+            // are never skipped — they are quality gates that must always run.
+            //
+            // Post-v0.44.0: terminal status is `fixed` only. `approved` and
+            // `verified` are no longer valid bug status values; references
+            // removed.
+            const PHASE_SKIP_STATES = {
+                "plan-fix": new Set(["fixed"]),
+                implement: new Set(["fixed"]),
+                commit: new Set(["fixed"]), // commit writes the terminal status; skip if already there
             };
-        }
-        // ── Persona load ──────────────────────────────────────────────
-        let persona;
-        try {
-            persona = loadForgePersona(phase.personaNoun, cwd);
-        }
-        catch (err) {
-            const e = err;
-            ctx.ui.notify(`× forge:fix-bug — persona '${phase.personaNoun}' not found for phase ${phase.role}: ${e.message ?? "unknown"}. ` +
-                "Run /forge:regenerate to materialize persona files.", "error");
-            writeBugState(cwd, {
-                bugId,
-                phaseIndex: currentPhaseIndex,
-                iterationCounts,
-                halted: true,
-                lastError: `persona load failed: ${e.message ?? "unknown"}`,
-                savedAt: new Date().toISOString(),
-            });
-            return {
-                status: "failed",
-                lastPhaseIndex: currentPhaseIndex,
-                iterationCounts,
-                lastError: `persona load failed: ${e.message ?? "unknown"}`,
-            };
-        }
-        // ── Read bug record for current status ────────────────────────
-        // Skip for PENDING bugIds (bug doesn't exist yet).
-        const bugRecordBefore = pendingBugId ? null : readBugRecord(bugId, storeCli, cwd);
-        const bugStatusBeforePhase = bugRecordBefore?.status;
-        // ── 4. Dispatch via runForgeSubagent (IL10) ───────────────────
-        // NEVER sendKickoff here — that would reproduce issue #30.
-        // Carry forward prior phase summaries (forge-cli#19).
-        const bugSummariesBlock = currentPhaseIndex > 0
-            ? buildSummariesBlock(bugRecordBefore?.summaries) || undefined
-            : undefined;
-        let bugBody = composeBugBody(subWorkflowMd, bugId, phase.role, bugStatusBeforePhase, bugSummariesBlock);
-        // For new bugs in triage, prepend the original free-form text so the
-        // subagent knows the user-provided bug description to triage.
-        // The bug record already exists (pre-created with status "reported"),
-        // so the subagent should update it, not create a new one.
-        if (phase.role === "triage" && isNewBug && originalArg) {
-            bugBody = `Bug description: ${originalArg}\n\n---\n\n${bugBody}`;
-        }
-        // Phase-scoped progress counters
-        const phaseStart = Date.now();
-        // Track tool_execution_end events for bugId capture (Findings #1, #2).
-        const toolExecutionEvents = [];
-        // Stabilization debug log
-        // Skip for PENDING bugIds — create after real bugId is captured.
-        // Disable entirely with FORGE_DEBUG_LOG=0.
-        const debugLogDisabled = process.env.FORGE_DEBUG_LOG === "0";
-        let debugLogPath = null;
-        let writeDebug = () => { };
-        if (!pendingBugId && !debugLogDisabled) {
-            debugLogPath = path.join(cwd, ".forge", "cache", `fix-bug-debug-${bugId}.jsonl`);
-            writeDebug = (rec) => {
-                try {
-                    fs.mkdirSync(path.dirname(debugLogPath), { recursive: true });
-                    // Cap at 10 MB: truncate head when size exceeds the cap.
+            const bugNow = readBugRecord(bugId, storeCli, cwd);
+            const skipStates = PHASE_SKIP_STATES[phase.role];
+            if (skipStates && bugNow?.status && skipStates.has(bugNow.status) && !phase.isReview) {
+                ctx.ui.notify(`⊘ forge:fix-bug — skipping ${phase.role}: bug ${bugId} is already '${bugNow.status}' (work already done).`, "info");
+                // Write a synthetic "approved" summary so downstream `after` predecessor
+                // verdict checks find a verdict and don't block review phases.
+                const summaryKey = BUG_SUMMARY_KEY_BY_ROLE[phase.role];
+                if (summaryKey) {
+                    const synthSummary = {
+                        objective: `Phase ${phase.role} skipped — bug already ${bugNow.status}`,
+                        findings: ["Subagent completed fix during triage (Path A); phase output implicitly satisfied."],
+                        // Non-review phases should have verdict "n/a" — the phase
+                        // didn't produce a gate verdict. This matches the `after
+                        // <phase> = n/a` preflight gate contract. Review phases
+                        // use "approved" since they are gate phases.
+                        verdict: phase.isReview ? "approved" : "n/a",
+                        written_at: new Date().toISOString(),
+                    };
+                    const synthFile = path.join(cwd, ".forge", "cache", `synthetic-summary-${bugId}-${summaryKey}.json`);
+                    fs.writeFileSync(synthFile, JSON.stringify(synthSummary, null, 2), "utf8");
+                    const synthResult = spawnSync("node", [storeCli, "set-bug-summary", bugId, summaryKey, synthFile], {
+                        cwd,
+                        encoding: "utf8",
+                    });
+                    if (synthResult.status !== 0) {
+                        ctx.ui.notify(`⚠ forge:fix-bug — synthetic summary write failed for ${phase.role}: ${String(synthResult.stderr).trim()}`, "warning");
+                    }
                     try {
-                        const st = fs.statSync(debugLogPath);
-                        if (st.size > 10 * 1024 * 1024) {
-                            const all = fs.readFileSync(debugLogPath, "utf8");
-                            const lines = all.split("\n");
-                            // Keep last 80% of lines
-                            const keep = Math.floor(lines.length * 0.8);
-                            fs.writeFileSync(debugLogPath, lines.slice(-keep).join("\n"), "utf8");
-                        }
+                        fs.unlinkSync(synthFile);
                     }
                     catch {
-                        /* file may not exist yet */
+                        /* non-fatal */
                     }
-                    fs.appendFileSync(debugLogPath, `${JSON.stringify({ ts: new Date().toISOString(), phase: phase.role, ...rec })}\n`, "utf8");
                 }
-                catch {
-                    // non-fatal; debug log is best-effort
-                }
-            };
-        }
-        writeDebug({ kind: "phase_start", phaseIndex: currentPhaseIndex });
-        registry.startPhase(bugId, phase.role, currentPhaseIndex);
-        const refreshStatus = () => {
-            if (process.env.FORGE_VERBOSE !== "1")
-                return;
-            const elapsed = Math.floor((Date.now() - phaseStart) / 1000);
-            const tail = observer.state.lastTool ? ` · ${observer.state.lastTool}` : "";
-            ctx.ui.setStatus?.(STATUS_KEY, `fix-bug ${bugId}: ${phase.role} · t${observer.state.turn} · tools ${observer.state.toolCount}${observer.state.errCount ? ` · err ${observer.state.errCount}` : ""} · ${elapsed}s${tail}`);
-        };
-        const observer = attachViewportObserver({
-            registry,
-            sessionId: bugId,
-            phaseRole: phase.role,
-            beginHeader: `─── phase ${phase.role} begin ───`,
-            writeDebug,
-            notify: (msg, level) => ctx.ui.notify(msg, level),
-            setStatusVerbose: process.env.FORGE_VERBOSE === "1" ? (k, v) => ctx.ui.setStatus?.(k, v) : undefined,
-            verboseKeys: { messageKey: `${STATUS_KEY}:message` },
-            afterEach: refreshStatus,
-        });
-        // Wrap the observer's onEvent to also capture tool_execution_end events
-        // for bugId capture downstream (findings #1, #2), plus the first turn_end
-        // per phase (IL10 visibility — stream-observed model id).
-        let modelObservedLogged = false;
-        const onSubagentEvent = (event) => {
-            if (event?.type === "tool_execution_end") {
-                toolExecutionEvents.push({ toolName: event.toolName, result: event.result });
-            }
-            if (!modelObservedLogged && event?.type === "turn_end" && event.message?.model) {
-                modelObservedLogged = true;
-                writeDebug({
-                    kind: "model_observed",
-                    provider: event.message.provider ?? null,
-                    model: event.message.model,
-                });
+                currentPhaseIndex++;
+                continue;
             }
-            observer.onEvent(event);
-        };
-        // Per-phase model resolution. When config is absent or cascade bottoms
-        // out, resolves to inherit (model: undefined) — setModel is skipped and
-        // pi's current model is used. IL10 still holds: result.model below is
-        // the stream-observed runtime model, not whatever we requested here.
-        const modelResolution = resolveModelForPhase("fix-bug", phase.role, phase.personaNoun, modelRoutingConfig);
-        writeDebug({
-            kind: "requested_model",
-            requested: modelResolution.model ?? null,
-            source: modelResolution.source,
-            persona: phase.personaNoun,
-        });
-        let result;
-        try {
-            result = await runForgeSubagent({
-                persona,
-                task: bugBody,
-                cwd,
-                exportTag: `${bugId}__${phase.role}`,
-                // Sprint-scoped if the bug is attached to one, else bug-scoped.
-                // Keeps every phase of this bug-fix pipeline in a single cache
-                // namespace so the system-prompt + persona prefix stays warm
-                // across the ~10-minute phases.
-                cacheSessionId: typeof bugRecordBefore?.sprintId === "string"
-                    ? `forge:${bugRecordBefore.sprintId}`
-                    : `forge:bug:${bugId}`,
-                onEvent: onSubagentEvent,
-                requestedModel: modelResolution.model,
-                modelRegistry: ctx.modelRegistry,
-                signal: opts.signal,
-                customTools: opts.forgeToolDefs ? getSubagentTools(opts.forgeToolDefs, persona.name) : undefined,
-            });
-        }
-        catch (err) {
-            const e = err;
-            ctx.ui.notify(`× forge:fix-bug — runForgeSubagent threw for phase ${phase.role}: ${e.message ?? "unknown"}`, "error");
-            writeBugState(cwd, {
-                bugId,
-                phaseIndex: currentPhaseIndex,
-                iterationCounts,
-                halted: true,
-                lastError: `runForgeSubagent threw: ${e.message ?? "unknown"}`,
-                savedAt: new Date().toISOString(),
-            });
-            return {
-                status: "failed",
-                lastPhaseIndex: currentPhaseIndex,
-                iterationCounts,
-                lastError: `runForgeSubagent threw: ${e.message ?? "unknown"}`,
-            };
-        }
-        // ── Post-subagent abort detection ─────────────────────────────────
-        if (result.stopReason === "aborted" || opts.signal?.aborted) {
-            ctx.ui.notify(`⊘ forge:fix-bug — ${bugId} phase ${phase.role} cancelled.`, "info");
-            registry.completePhase(bugId, phase.role, "cancelled");
-            registry.confirmCancelled(bugId);
-            // ADR-S21-01: preserve state file so cancelled runs are resumable
-            writeBugState(cwd, {
-                bugId,
-                phaseIndex: currentPhaseIndex,
-                iterationCounts,
-                halted: false,
-                status: "cancelled",
-                lastError: undefined,
-                savedAt: new Date().toISOString(),
-            });
-            return { status: "cancelled", lastPhaseIndex: currentPhaseIndex, iterationCounts };
-        }
-        // ── Halt-on-failure ───────────────────────────────────────────
-        if (result.exitCode !== 0) {
-            ctx.ui.notify(`× forge:fix-bug — phase ${phase.role} failed (exit ${result.exitCode})` +
-                (result.errorMessage ? `: ${result.errorMessage}` : "") +
-                (result.stopReason ? ` [${result.stopReason}]` : ""), "error");
-            writeBugState(cwd, {
-                bugId,
-                phaseIndex: currentPhaseIndex,
-                iterationCounts,
-                halted: true,
-                lastError: result.errorMessage ?? result.stopReason ?? "subagent exit non-zero",
-                savedAt: new Date().toISOString(),
-            });
-            return {
-                status: "failed",
-                lastPhaseIndex: currentPhaseIndex,
-                iterationCounts,
-                lastError: result.errorMessage ?? result.stopReason ?? "subagent exit non-zero",
-            };
-        }
-        // Capture model/provider from subagent result.
-        if (result.model)
-            lastModel = result.model;
-        if (result.provider)
-            lastProvider = result.provider;
-        // ── BugId capture after triage phase (Finding #1, #2) ──────────
-        // For new bugs, the triage subagent creates the bug record via store-cli.
-        // We capture the bugId by scanning tool_execution_end events.
-        if (phase.role === "triage" && isNewBug && bugId.startsWith("PENDING-")) {
-            const capturedBugId = extractBugIdFromEvents(toolExecutionEvents);
-            if (capturedBugId) {
-                ctx.ui.notify(`forge:fix-bug — captured bug ID: ${capturedBugId}`, "info");
-                bugId = capturedBugId;
+            // ── 6b. Preflight gate ────────────────────────────────────────
+            // Skip preflight gate for triage phase of new bugs (PENDING- placeholder)
+            // because the bug record doesn't exist yet — gates referencing bug fields
+            // would always fail.
+            //
+            // Also skip for review phases when the bug is already in a terminal
+            // state ("fixed"). Path A bugs get fixed during triage, then the
+            // preflight gate's `forbid bug.status == fixed` and `after implement
+            // = n/a` checks block review-code/review-plan even though we
+            // deliberately want to run those reviews. The review subagent handles
+            // the already-fixed scenario internally.
+            const pendingBugId = bugId.startsWith("PENDING-");
+            const bugAlreadyFixed = bugNow?.status === "fixed" && phase.isReview;
+            if (!pendingBugId && !bugAlreadyFixed && fs.existsSync(preflightGate)) {
+                const preflightResult = runPreflightGate(preflightGate, phase.role, bugId, cwd, "bug");
+                if (preflightResult === "halt") {
+                    ctx.ui.notify(`× forge:fix-bug — preflight gate failed for phase ${phase.role} (exit 1); halting.`, "error");
+                    writeBugState(cwd, {
+                        bugId,
+                        phaseIndex: currentPhaseIndex,
+                        iterationCounts,
+                        halted: true,
+                        lastError: `preflight gate exit 1 for ${phase.role}`,
+                        savedAt: new Date().toISOString(),
+                    });
+                    return {
+                        status: "halted",
+                        lastPhaseIndex: currentPhaseIndex,
+                        iterationCounts,
+                        lastError: `preflight gate exit 1 for ${phase.role}`,
+                    };
+                }
+                if (preflightResult === "escalate") {
+                    ctx.ui.notify(`× forge:fix-bug — preflight gate escalated for phase ${phase.role} (exit 2); manual intervention required.`, "error");
+                    writeBugState(cwd, {
+                        bugId,
+                        phaseIndex: currentPhaseIndex,
+                        iterationCounts,
+                        halted: true,
+                        lastError: `preflight gate exit 2 (escalate) for ${phase.role}`,
+                        savedAt: new Date().toISOString(),
+                    });
+                    return {
+                        status: "escalated",
+                        lastPhaseIndex: currentPhaseIndex,
+                        iterationCounts,
+                        lastError: `preflight gate exit 2 (escalate) for ${phase.role}`,
+                    };
+                }
             }
-            else {
-                // Fallback: list bugs and find the most recent one created after pipeline start.
-                const listResult = spawnSync("node", [storeCli, "list", "bug", "--json"], { cwd, encoding: "utf8" });
-                if (listResult.status === 0 && listResult.stdout) {
-                    try {
-                        const bugs = JSON.parse(listResult.stdout);
-                        if (Array.isArray(bugs)) {
-                            // Find most recent bug whose reportedAt is after the pipeline start
-                            const pipelineStartIso = new Date(parseInt(bugId.replace("PENDING-", ""))).toISOString();
-                            const recent = bugs
-                                .filter((b) => b.reportedAt && b.reportedAt >= pipelineStartIso)
-                                .sort((a, b) => String(b.reportedAt).localeCompare(String(a.reportedAt)))[0];
-                            if (recent &&
-                                recent.bugId &&
-                                typeof recent.bugId === "string" &&
-                                recent.bugId.startsWith("FORGE-BUG-")) {
-                                bugId = recent.bugId;
-                                ctx.ui.notify(`forge:fix-bug — captured bug ID via store fallback: ${bugId}`, "info");
-                            }
-                        }
-                    }
-                    catch {
-                        /* parse failure — fall through to assertion */
+            // ── 6. Materialization-marker check ───────────────────────────
+            // FORGE-BUG-040: every BUG phase is now a true `audience: subagent`
+            // sub-workflow — triage / plan-fix / implement no longer alias to
+            // fix_bug.md. The marker check is therefore unconditional; a missing
+            // marker is a hard failure on the first dispatch.
+            {
+                const markerCheck = checkMaterialization(subWorkflowPath, subWorkflowMd);
+                if (!markerCheck.ok) {
+                    for (const marker of markerCheck.missing) {
+                        ctx.ui.notify(`× workflow regression: ${marker} not found in ${subWorkflowPath}`, "error");
                     }
+                    return {
+                        status: "failed",
+                        lastPhaseIndex: currentPhaseIndex,
+                        iterationCounts,
+                        lastError: `materialization markers missing: ${markerCheck.missing.join(", ")}`,
+                    };
                 }
             }
-            // Defensive guard: if bugId is still PENDING after triage, pipeline cannot proceed.
-            if (bugId.startsWith("PENDING-")) {
-                ctx.ui.notify("× forge:fix-bug — failed to capture real bug ID after triage. Cannot proceed with PENDING placeholder.", "error");
+            // ── 5. Audience check ─────────────────────────────────────────
+            // FORGE-BUG-040: every BUG phase is a true `audience: subagent`
+            // workflow now; the previous `fix_bug.md` audience-bypass is gone.
+            const audienceOk = CallerContextStore.asSubagent(phase.role, () => assertAudience({ workflowName: phase.workflowFile, audience: subWorkflowAudience }, ctx));
+            if (!audienceOk) {
+                writeBugState(cwd, {
+                    bugId,
+                    phaseIndex: currentPhaseIndex,
+                    iterationCounts,
+                    halted: true,
+                    lastError: `audience check failed for ${phase.workflowFile}`,
+                    savedAt: new Date().toISOString(),
+                });
+                return {
+                    status: "failed",
+                    lastPhaseIndex: currentPhaseIndex,
+                    iterationCounts,
+                    lastError: `audience check failed for ${phase.workflowFile}`,
+                };
+            }
+            // ── Persona load ──────────────────────────────────────────────
+            let persona;
+            try {
+                persona = loadForgePersona(phase.personaNoun, cwd);
+            }
+            catch (err) {
+                const e = err;
+                ctx.ui.notify(`× forge:fix-bug — persona '${phase.personaNoun}' not found for phase ${phase.role}: ${e.message ?? "unknown"}. ` +
+                    "Run /forge:regenerate to materialize persona files.", "error");
+                writeBugState(cwd, {
+                    bugId,
+                    phaseIndex: currentPhaseIndex,
+                    iterationCounts,
+                    halted: true,
+                    lastError: `persona load failed: ${e.message ?? "unknown"}`,
+                    savedAt: new Date().toISOString(),
+                });
                 return {
                     status: "failed",
                     lastPhaseIndex: currentPhaseIndex,
                     iterationCounts,
-                    lastError: "bugId still PENDING after triage",
+                    lastError: `persona load failed: ${e.message ?? "unknown"}`,
                 };
             }
-            // Re-initialize debug log now that real bugId is available.
-            if (!debugLogDisabled) {
+            // ── Read bug record for current status ────────────────────────
+            // Skip for PENDING bugIds (bug doesn't exist yet).
+            const bugRecordBefore = pendingBugId ? null : readBugRecord(bugId, storeCli, cwd);
+            const bugStatusBeforePhase = bugRecordBefore?.status;
+            // ── 4. Dispatch via runForgeSubagent (IL10) ───────────────────
+            // NEVER sendKickoff here — that would reproduce issue #30.
+            // Carry forward prior phase summaries (forge-cli#19).
+            const bugSummariesBlock = currentPhaseIndex > 0
+                ? buildSummariesBlock(bugRecordBefore?.summaries) || undefined
+                : undefined;
+            let bugBody = composeBugBody(subWorkflowMd, bugId, phase.role, bugStatusBeforePhase, bugSummariesBlock);
+            // For new bugs in triage, prepend the original free-form text so the
+            // subagent knows the user-provided bug description to triage.
+            // The bug record already exists (pre-created with status "reported"),
+            // so the subagent should update it, not create a new one.
+            if (phase.role === "triage" && isNewBug && originalArg) {
+                bugBody = `Bug description: ${originalArg}\n\n---\n\n${bugBody}`;
+            }
+            // Phase-scoped progress counters
+            const phaseStart = Date.now();
+            // Track tool_execution_end events for bugId capture (Findings #1, #2).
+            const toolExecutionEvents = [];
+            // Stabilization debug log
+            // Skip for PENDING bugIds — create after real bugId is captured.
+            // Disable entirely with FORGE_DEBUG_LOG=0.
+            const debugLogDisabled = process.env.FORGE_DEBUG_LOG === "0";
+            let debugLogPath = null;
+            let writeDebug = () => { };
+            if (!pendingBugId && !debugLogDisabled) {
                 debugLogPath = path.join(cwd, ".forge", "cache", `fix-bug-debug-${bugId}.jsonl`);
-                const savedWriteDebug = writeDebug;
                 writeDebug = (rec) => {
                     try {
                         fs.mkdirSync(path.dirname(debugLogPath), { recursive: true });
+                        // Cap at 10 MB: truncate head when size exceeds the cap.
                         try {
                             const st = fs.statSync(debugLogPath);
                             if (st.size > 10 * 1024 * 1024) {
                                 const all = fs.readFileSync(debugLogPath, "utf8");
                                 const lines = all.split("\n");
+                                // Keep last 80% of lines
                                 const keep = Math.floor(lines.length * 0.8);
                                 fs.writeFileSync(debugLogPath, lines.slice(-keep).join("\n"), "utf8");
                             }
@@ -954,216 +783,456 @@ export async function runBugPipeline(opts) {
                         fs.appendFileSync(debugLogPath, `${JSON.stringify({ ts: new Date().toISOString(), phase: phase.role, ...rec })}\n`, "utf8");
                     }
                     catch {
-                        // non-fatal
+                        // non-fatal; debug log is best-effort
                     }
                 };
-                writeDebug({ kind: "bugid_captured", bugId });
             }
-        }
-        {
-            const elapsed = Math.floor((Date.now() - phaseStart) / 1000);
-            const { turn, toolCount, errCount, cumUsage } = observer.state;
-            ctx.ui.notify(`✓ ${phase.role}: ${turn} turn${turn === 1 ? "" : "s"} · ${toolCount} tool call${toolCount === 1 ? "" : "s"}${errCount ? ` · ${errCount} err` : ""} · ${elapsed}s`, "info");
-            registry.appendTail(bugId, phase.role, fmtPhaseSummary({
-                role: phase.role,
-                turns: turn,
-                tools: toolCount,
-                errors: errCount,
-                wallSeconds: elapsed,
-                usage: cumUsage,
-                model: result.model,
-                provider: result.provider,
-            }));
-        }
-        // ── Slice-2: orchestrator emits phase event ──────────────────
-        // sprintId for bug event emission is the literal "bugs" (routing key),
-        // matching the convention in .forge/workflows/fix_bug.md.
-        const phaseEndMs = Date.now();
-        const bugRecord = readBugRecord(bugId, storeCli, cwd);
-        const sprintId = "bugs"; // routing key for bug events — not a sprint reference
-        const phaseIteration = (iterationCounts[phase.role] ?? 0) + 1;
-        // Read summary judgement for review phases (using bug summary key map)
-        const judgement = phase.isReview
-            ? judgementFromSummary(bugRecord ?? null, phase.role, BUG_SUMMARY_KEY_BY_ROLE)
-            : undefined;
-        const emitCtx = {
-            entityType: "bug",
-            bugId,
-            sprintId, // routing key "bugs" — not a sprint reference
-            phase,
-            iteration: phaseIteration,
-            startMs: phaseStart,
-            endMs: phaseEndMs,
-            model: result.model ?? "unknown",
-            provider: result.provider ?? "unknown",
-            usage: {
-                input: result.usage.input,
-                output: result.usage.output,
-                cacheRead: result.usage.cacheRead,
-                cacheWrite: result.usage.cacheWrite,
-            },
-            judgement,
-            storeCli,
-            cwd,
-        };
-        const phaseEvent = buildPhaseEvent(emitCtx);
-        // Set bug event type based on BUG_TYPE_TOKENS mapping.
-        const typeTokenEntry = BUG_TYPE_TOKENS[phase.role];
-        if (typeTokenEntry) {
-            if (phase.isReview && judgement?.verdict === "revision") {
-                phaseEvent.type = typeTokenEntry.fail;
-            }
-            else {
-                phaseEvent.type = typeTokenEntry.pass;
+            writeDebug({ kind: "phase_start", phaseIndex: currentPhaseIndex });
+            registry.startPhase(bugId, phase.role, currentPhaseIndex);
+            const refreshStatus = () => {
+                if (process.env.FORGE_VERBOSE !== "1")
+                    return;
+                const elapsed = Math.floor((Date.now() - phaseStart) / 1000);
+                const tail = observer.state.lastTool ? ` · ${observer.state.lastTool}` : "";
+                ctx.ui.setStatus?.(STATUS_KEY, `fix-bug ${bugId}: ${phase.role} · t${observer.state.turn} · tools ${observer.state.toolCount}${observer.state.errCount ? ` · err ${observer.state.errCount}` : ""} · ${elapsed}s${tail}`);
+            };
+            const observer = attachViewportObserver({
+                registry,
+                sessionId: bugId,
+                phaseRole: phase.role,
+                beginHeader: `─── phase ${phase.role} begin ───`,
+                writeDebug,
+                notify: (msg, level) => ctx.ui.notify(msg, level),
+                setStatusVerbose: process.env.FORGE_VERBOSE === "1" ? (k, v) => ctx.ui.setStatus?.(k, v) : undefined,
+                verboseKeys: { messageKey: `${STATUS_KEY}:message` },
+                afterEach: refreshStatus,
+            });
+            // Wrap the observer's onEvent to also capture tool_execution_end events
+            // for bugId capture downstream (findings #1, #2), plus the first turn_end
+            // per phase (IL10 visibility — stream-observed model id).
+            let modelObservedLogged = false;
+            const onSubagentEvent = (event) => {
+                if (event?.type === "tool_execution_end") {
+                    toolExecutionEvents.push({ toolName: event.toolName, result: event.result });
+                }
+                if (!modelObservedLogged && event?.type === "turn_end" && event.message?.model) {
+                    modelObservedLogged = true;
+                    writeDebug({
+                        kind: "model_observed",
+                        provider: event.message.provider ?? null,
+                        model: event.message.model,
+                    });
+                }
+                observer.onEvent(event);
+            };
+            // Per-phase model resolution. When config is absent or cascade bottoms
+            // out, resolves to inherit (model: undefined) — setModel is skipped and
+            // pi's current model is used. IL10 still holds: result.model below is
+            // the stream-observed runtime model, not whatever we requested here.
+            const modelResolution = resolveModelForPhase("fix-bug", phase.role, phase.personaNoun, modelRoutingConfig);
+            writeDebug({
+                kind: "requested_model",
+                requested: modelResolution.model ?? null,
+                source: modelResolution.source,
+                persona: phase.personaNoun,
+            });
+            let result;
+            try {
+                // FORGE-BUG-040: wrap the runForgeSubagent dispatch in the phase
+                // caller context so downstream tool calls (forge_preflight,
+                // forge_store update-status / set-bug-summary / set-summary / emit)
+                // can verify the caller's phase matches the phase named in the
+                // tool's arguments. This is the single setter of phase context
+                // for the bug pipeline; the audience-test wrap above is a
+                // short-lived test, not the canonical dispatch context.
+                result = await CallerContextStore.asSubagent(phase.role, () => runForgeSubagent({
+                    persona,
+                    task: bugBody,
+                    cwd,
+                    exportTag: `${bugId}__${phase.role}`,
+                    // Sprint-scoped if the bug is attached to one, else bug-scoped.
+                    // Keeps every phase of this bug-fix pipeline in a single cache
+                    // namespace so the system-prompt + persona prefix stays warm
+                    // across the ~10-minute phases.
+                    cacheSessionId: typeof bugRecordBefore?.sprintId === "string"
+                        ? `forge:${bugRecordBefore.sprintId}`
+                        : `forge:bug:${bugId}`,
+                    onEvent: onSubagentEvent,
+                    requestedModel: modelResolution.model,
+                    modelRegistry: ctx.modelRegistry,
+                    signal: opts.signal,
+                    customTools: opts.forgeToolDefs ? getSubagentTools(opts.forgeToolDefs, persona.name) : undefined,
+                }));
             }
-        }
-        const emitResult = emitEvent(storeCli, cwd, sprintId, phaseEvent);
-        if (!emitResult.ok) {
-            ctx.ui.notify(`⚠ forge:fix-bug — phase event emit failed for ${phase.role}: ${emitResult.stderr.trim()}`, "warning");
-            writeDebug({ kind: "emit_failed", stderr: emitResult.stderr });
-        }
-        else {
-            writeDebug({ kind: "emit_ok", eventId: phaseEvent.eventId });
-        }
-        // Drain friction file for this phase.
-        const frictionPath = path.join(cwd, ".forge", "cache", `FRICTION-${phase.role}.jsonl`);
-        const drain = drainFrictionFile(frictionPath, emitCtx);
-        if (drain.emitted + drain.failed > 0) {
-            writeDebug({ kind: "friction_drain", ...drain });
-            if (drain.failed > 0) {
-                ctx.ui.notify(`⚠ forge:fix-bug — friction drain for ${phase.role}: ${drain.emitted} ok, ${drain.failed} failed`, "warning");
+            catch (err) {
+                const e = err;
+                ctx.ui.notify(`× forge:fix-bug — runForgeSubagent threw for phase ${phase.role}: ${e.message ?? "unknown"}`, "error");
+                writeBugState(cwd, {
+                    bugId,
+                    phaseIndex: currentPhaseIndex,
+                    iterationCounts,
+                    halted: true,
+                    lastError: `runForgeSubagent threw: ${e.message ?? "unknown"}`,
+                    savedAt: new Date().toISOString(),
+                });
+                return {
+                    status: "failed",
+                    lastPhaseIndex: currentPhaseIndex,
+                    iterationCounts,
+                    lastError: `runForgeSubagent threw: ${e.message ?? "unknown"}`,
+                };
             }
-        }
-        // ── AC §C.16: Bug FSM canonical-enum assertion ────────────────
-        // After each phase that could transition bug status, validate the new
-        // status via store-cli (single source of truth). Surface a warning (not halt) if invalid.
-        const currentBugRecordForAssert = readBugRecord(bugId, storeCli, cwd);
-        if (currentBugRecordForAssert && currentBugRecordForAssert.status) {
-            // Defer to store-cli's isLegalTransition as authoritative guard.
-            // Only warn on statuses store-cli itself would reject.
-            const validateResult = spawnSync("node", [storeCli, "validate", "bug", JSON.stringify(currentBugRecordForAssert)], { cwd, encoding: "utf8" });
-            if (validateResult.status !== 0) {
-                const detail = typeof validateResult.stderr === "string" ? validateResult.stderr.trim() : "unknown";
-                ctx.ui.notify(`⚠ forge:fix-bug — bug ${bugId} validation warning: ${detail}`, "warning");
-                writeDebug({ kind: "fsm_assertion_warning", bugId, status: currentBugRecordForAssert.status, detail });
+            // ── Post-subagent abort detection ─────────────────────────────────
+            if (result.stopReason === "aborted" || opts.signal?.aborted) {
+                ctx.ui.notify(`⊘ forge:fix-bug — ${bugId} phase ${phase.role} cancelled.`, "info");
+                registry.completePhase(bugId, phase.role, "cancelled");
+                registry.confirmCancelled(bugId);
+                // ADR-S21-01: preserve state file so cancelled runs are resumable
+                writeBugState(cwd, {
+                    bugId,
+                    phaseIndex: currentPhaseIndex,
+                    iterationCounts,
+                    halted: false,
+                    status: "cancelled",
+                    lastError: undefined,
+                    savedAt: new Date().toISOString(),
+                });
+                return { status: "cancelled", lastPhaseIndex: currentPhaseIndex, iterationCounts };
             }
-        }
-        // ── 6b. Verdict check (review phases only) ────────────────────
-        if (phase.isReview) {
-            // Re-read bug record for latest status after subagent ran
-            const updatedBugRecord = readBugRecord(bugId, storeCli, cwd);
-            const verdict = readBugVerdict(updatedBugRecord, phase.role, BUG_SUMMARY_KEY_BY_ROLE);
-            if (verdict === "missing") {
-                ctx.ui.notify(`× forge:fix-bug — verdict missing for phase ${phase.role} after subagent completed. Escalating.`, "error");
+            // ── Halt-on-failure ───────────────────────────────────────────
+            if (result.exitCode !== 0) {
+                ctx.ui.notify(`× forge:fix-bug — phase ${phase.role} failed (exit ${result.exitCode})` +
+                    (result.errorMessage ? `: ${result.errorMessage}` : "") +
+                    (result.stopReason ? ` [${result.stopReason}]` : ""), "error");
                 writeBugState(cwd, {
                     bugId,
                     phaseIndex: currentPhaseIndex,
                     iterationCounts,
                     halted: true,
-                    lastError: `verdict missing for ${phase.role}`,
+                    lastError: result.errorMessage ?? result.stopReason ?? "subagent exit non-zero",
                     savedAt: new Date().toISOString(),
                 });
                 return {
                     status: "failed",
                     lastPhaseIndex: currentPhaseIndex,
                     iterationCounts,
-                    lastError: `verdict missing for ${phase.role}`,
+                    lastError: result.errorMessage ?? result.stopReason ?? "subagent exit non-zero",
                 };
             }
-            if (verdict === "revision") {
-                iterationCounts[phase.role] = (iterationCounts[phase.role] ?? 0) + 1;
-                if (iterationCounts[phase.role] >= phase.maxIterations) {
-                    ctx.ui.notify(`× forge:fix-bug — revision cap reached for phase ${phase.role} ` +
-                        `(${iterationCounts[phase.role]}/${phase.maxIterations} iterations). Escalating.`, "error");
+            // Capture model/provider from subagent result.
+            if (result.model)
+                lastModel = result.model;
+            if (result.provider)
+                lastProvider = result.provider;
+            // ── BugId capture after triage phase (Finding #1, #2) ──────────
+            // For new bugs, the triage subagent creates the bug record via store-cli.
+            // We capture the bugId by scanning tool_execution_end events.
+            if (phase.role === "triage" && isNewBug && bugId.startsWith("PENDING-")) {
+                const capturedBugId = extractBugIdFromEvents(toolExecutionEvents);
+                if (capturedBugId) {
+                    ctx.ui.notify(`forge:fix-bug — captured bug ID: ${capturedBugId}`, "info");
+                    bugId = capturedBugId;
+                }
+                else {
+                    // Fallback: list bugs and find the most recent one created after pipeline start.
+                    const listResult = spawnSync("node", [storeCli, "list", "bug", "--json"], { cwd, encoding: "utf8" });
+                    if (listResult.status === 0 && listResult.stdout) {
+                        try {
+                            const bugs = JSON.parse(listResult.stdout);
+                            if (Array.isArray(bugs)) {
+                                // Find most recent bug whose reportedAt is after the pipeline start
+                                const pipelineStartIso = new Date(parseInt(bugId.replace("PENDING-", ""))).toISOString();
+                                const recent = bugs
+                                    .filter((b) => b.reportedAt && b.reportedAt >= pipelineStartIso)
+                                    .sort((a, b) => String(b.reportedAt).localeCompare(String(a.reportedAt)))[0];
+                                if (recent &&
+                                    recent.bugId &&
+                                    typeof recent.bugId === "string" &&
+                                    recent.bugId.startsWith("FORGE-BUG-")) {
+                                    bugId = recent.bugId;
+                                    ctx.ui.notify(`forge:fix-bug — captured bug ID via store fallback: ${bugId}`, "info");
+                                }
+                            }
+                        }
+                        catch {
+                            /* parse failure — fall through to assertion */
+                        }
+                    }
+                }
+                // Defensive guard: if bugId is still PENDING after triage, pipeline cannot proceed.
+                if (bugId.startsWith("PENDING-")) {
+                    ctx.ui.notify("× forge:fix-bug — failed to capture real bug ID after triage. Cannot proceed with PENDING placeholder.", "error");
+                    return {
+                        status: "failed",
+                        lastPhaseIndex: currentPhaseIndex,
+                        iterationCounts,
+                        lastError: "bugId still PENDING after triage",
+                    };
+                }
+                // Re-initialize debug log now that real bugId is available.
+                if (!debugLogDisabled) {
+                    debugLogPath = path.join(cwd, ".forge", "cache", `fix-bug-debug-${bugId}.jsonl`);
+                    const savedWriteDebug = writeDebug;
+                    writeDebug = (rec) => {
+                        try {
+                            fs.mkdirSync(path.dirname(debugLogPath), { recursive: true });
+                            try {
+                                const st = fs.statSync(debugLogPath);
+                                if (st.size > 10 * 1024 * 1024) {
+                                    const all = fs.readFileSync(debugLogPath, "utf8");
+                                    const lines = all.split("\n");
+                                    const keep = Math.floor(lines.length * 0.8);
+                                    fs.writeFileSync(debugLogPath, lines.slice(-keep).join("\n"), "utf8");
+                                }
+                            }
+                            catch {
+                                /* file may not exist yet */
+                            }
+                            fs.appendFileSync(debugLogPath, `${JSON.stringify({ ts: new Date().toISOString(), phase: phase.role, ...rec })}\n`, "utf8");
+                        }
+                        catch {
+                            // non-fatal
+                        }
+                    };
+                    writeDebug({ kind: "bugid_captured", bugId });
+                }
+            }
+            {
+                const elapsed = Math.floor((Date.now() - phaseStart) / 1000);
+                const { turn, toolCount, errCount, cumUsage, cumCompression } = observer.state;
+                ctx.ui.notify(`✓ ${phase.role}: ${turn} turn${turn === 1 ? "" : "s"} · ${toolCount} tool call${toolCount === 1 ? "" : "s"}${errCount ? ` · ${errCount} err` : ""} · ${elapsed}s`, "info");
+                orchTranscript.record({
+                    kind: "phase-end",
+                    ts: new Date().toISOString(),
+                    phase: phase.role,
+                    phaseIndex: currentPhaseIndex,
+                    attempt: (iterationCounts[phase.role] ?? 0) + 1,
+                    verdict: "n/a",
+                    elapsedMs: Date.now() - phaseStart,
+                    turns: turn,
+                    toolCount,
+                    errCount,
+                });
+                registry.appendTail(bugId, phase.role, fmtPhaseSummary({
+                    role: phase.role,
+                    turns: turn,
+                    tools: toolCount,
+                    errors: errCount,
+                    wallSeconds: elapsed,
+                    usage: cumUsage,
+                    model: result.model,
+                    provider: result.provider,
+                    compression: cumCompression.tokensSaved > 0 ? cumCompression : undefined,
+                }));
+            }
+            // ── Slice-2: orchestrator emits phase event ──────────────────
+            // sprintId for bug event emission is the literal "bugs" (routing key),
+            // matching the convention in .forge/workflows/fix_bug.md.
+            const phaseEndMs = Date.now();
+            const bugRecord = readBugRecord(bugId, storeCli, cwd);
+            const sprintId = "bugs"; // routing key for bug events — not a sprint reference
+            const phaseIteration = (iterationCounts[phase.role] ?? 0) + 1;
+            // Read summary judgement for review phases (using bug summary key map)
+            const judgement = phase.isReview
+                ? judgementFromSummary(bugRecord ?? null, phase.role, BUG_SUMMARY_KEY_BY_ROLE)
+                : undefined;
+            const emitCtx = {
+                entityType: "bug",
+                bugId,
+                sprintId, // routing key "bugs" — not a sprint reference
+                phase,
+                iteration: phaseIteration,
+                startMs: phaseStart,
+                endMs: phaseEndMs,
+                model: result.model ?? "unknown",
+                provider: result.provider ?? "unknown",
+                usage: {
+                    input: result.usage.input,
+                    output: result.usage.output,
+                    cacheRead: result.usage.cacheRead,
+                    cacheWrite: result.usage.cacheWrite,
+                },
+                judgement,
+                storeCli,
+                cwd,
+            };
+            const phaseEvent = buildPhaseEvent(emitCtx);
+            // Set bug event type based on BUG_TYPE_TOKENS mapping.
+            const typeTokenEntry = BUG_TYPE_TOKENS[phase.role];
+            if (typeTokenEntry) {
+                if (phase.isReview && judgement?.verdict === "revision") {
+                    phaseEvent.type = typeTokenEntry.fail;
+                }
+                else {
+                    phaseEvent.type = typeTokenEntry.pass;
+                }
+            }
+            const emitResult = emitEvent(storeCli, cwd, sprintId, phaseEvent);
+            if (!emitResult.ok) {
+                ctx.ui.notify(`⚠ forge:fix-bug — phase event emit failed for ${phase.role}: ${emitResult.stderr.trim()}`, "warning");
+                writeDebug({ kind: "emit_failed", stderr: emitResult.stderr });
+            }
+            else {
+                writeDebug({ kind: "emit_ok", eventId: phaseEvent.eventId });
+            }
+            // Drain friction file for this phase.
+            const frictionPath = path.join(cwd, ".forge", "cache", `FRICTION-${phase.role}.jsonl`);
+            const drain = drainFrictionFile(frictionPath, emitCtx);
+            if (drain.emitted + drain.failed > 0) {
+                writeDebug({ kind: "friction_drain", ...drain });
+                if (drain.failed > 0) {
+                    ctx.ui.notify(`⚠ forge:fix-bug — friction drain for ${phase.role}: ${drain.emitted} ok, ${drain.failed} failed`, "warning");
+                }
+            }
+            // ── AC §C.16: Bug FSM canonical-enum assertion ────────────────
+            // After each phase that could transition bug status, validate the new
+            // status via store-cli (single source of truth). Surface a warning (not halt) if invalid.
+            const currentBugRecordForAssert = readBugRecord(bugId, storeCli, cwd);
+            if (currentBugRecordForAssert && currentBugRecordForAssert.status) {
+                // Defer to store-cli's isLegalTransition as authoritative guard.
+                // Only warn on statuses store-cli itself would reject.
+                const validateResult = spawnSync("node", [storeCli, "validate", "bug", JSON.stringify(currentBugRecordForAssert)], { cwd, encoding: "utf8" });
+                if (validateResult.status !== 0) {
+                    const detail = typeof validateResult.stderr === "string" ? validateResult.stderr.trim() : "unknown";
+                    ctx.ui.notify(`⚠ forge:fix-bug — bug ${bugId} validation warning: ${detail}`, "warning");
+                    writeDebug({ kind: "fsm_assertion_warning", bugId, status: currentBugRecordForAssert.status, detail });
+                }
+            }
+            // ── 6b. Verdict check (review phases only) ────────────────────
+            if (phase.isReview) {
+                // Re-read bug record for latest status after subagent ran
+                const updatedBugRecord = readBugRecord(bugId, storeCli, cwd);
+                const verdict = readBugVerdict(updatedBugRecord, phase.role, BUG_SUMMARY_KEY_BY_ROLE);
+                if (verdict === "missing") {
+                    ctx.ui.notify(`× forge:fix-bug — verdict missing for phase ${phase.role} after subagent completed. Escalating.`, "error");
                     writeBugState(cwd, {
                         bugId,
                         phaseIndex: currentPhaseIndex,
                         iterationCounts,
                         halted: true,
-                        lastError: `revision cap reached for ${phase.role}`,
+                        lastError: `verdict missing for ${phase.role}`,
                         savedAt: new Date().toISOString(),
                     });
                     return {
-                        status: "escalated",
+                        status: "failed",
                         lastPhaseIndex: currentPhaseIndex,
                         iterationCounts,
-                        lastError: `revision cap reached for ${phase.role}`,
+                        lastError: `verdict missing for ${phase.role}`,
                     };
                 }
-                // Transition bug back to in-progress before re-dispatching implement.
-                // This is required for review-code → implement and approve → implement loops.
-                const currentBugStatus = updatedBugRecord?.status;
-                if (currentBugStatus === "fixed" || currentBugStatus === "approved") {
-                    const transitionResult = spawnSync("node", [storeCli, "update-status", "bug", bugId, "status", "in-progress"], { cwd, encoding: "utf8" });
-                    if (transitionResult.status !== 0) {
-                        ctx.ui.notify(`⚠ forge:fix-bug — failed to transition bug ${bugId} from ${currentBugStatus} to in-progress: ${transitionResult.stderr ?? "unknown"}`, "warning");
+                if (verdict === "revision") {
+                    iterationCounts[phase.role] = (iterationCounts[phase.role] ?? 0) + 1;
+                    if (iterationCounts[phase.role] >= phase.maxIterations) {
+                        ctx.ui.notify(`× forge:fix-bug — revision cap reached for phase ${phase.role} ` +
+                            `(${iterationCounts[phase.role]}/${phase.maxIterations} iterations). Escalating.`, "error");
+                        writeBugState(cwd, {
+                            bugId,
+                            phaseIndex: currentPhaseIndex,
+                            iterationCounts,
+                            halted: true,
+                            lastError: `revision cap reached for ${phase.role}`,
+                            savedAt: new Date().toISOString(),
+                        });
+                        return {
+                            status: "escalated",
+                            lastPhaseIndex: currentPhaseIndex,
+                            iterationCounts,
+                            lastError: `revision cap reached for ${phase.role}`,
+                        };
                     }
-                    else {
-                        ctx.ui.notify(`⟳ forge:fix-bug — transitioned bug ${bugId}: ${currentBugStatus} → in-progress`, "info");
+                    // Transition bug back to in-progress before re-dispatching implement.
+                    // This is required for review-code → implement and approve → implement loops.
+                    const currentBugStatus = updatedBugRecord?.status;
+                    if (currentBugStatus === "fixed" || currentBugStatus === "approved") {
+                        const transitionResult = spawnSync("node", [storeCli, "update-status", "bug", bugId, "status", "in-progress"], { cwd, encoding: "utf8" });
+                        if (transitionResult.status !== 0) {
+                            ctx.ui.notify(`⚠ forge:fix-bug — failed to transition bug ${bugId} from ${currentBugStatus} to in-progress: ${transitionResult.stderr ?? "unknown"}`, "warning");
+                        }
+                        else {
+                            ctx.ui.notify(`⟳ forge:fix-bug — transitioned bug ${bugId}: ${currentBugStatus} → in-progress`, "info");
+                        }
                     }
+                    const predIndex = findPredecessorIndex(BUG_PHASES, currentPhaseIndex);
+                    ctx.ui.notify(`⟳ forge:fix-bug — ${phase.role} returned revision; looping to ${BUG_PHASES[predIndex]?.role ?? predIndex} ` +
+                        `(attempt ${iterationCounts[phase.role]}/${phase.maxIterations})`, "info");
+                    orchTranscript.record({
+                        kind: "phase-loopback",
+                        ts: new Date().toISOString(),
+                        fromPhase: phase.role,
+                        toPhase: BUG_PHASES[predIndex]?.role ?? String(predIndex),
+                        fromPhaseIndex: currentPhaseIndex,
+                        toPhaseIndex: predIndex,
+                        reason: `${phase.role} returned revision (attempt ${iterationCounts[phase.role]}/${phase.maxIterations})`,
+                    });
+                    writeBugState(cwd, {
+                        bugId,
+                        phaseIndex: predIndex,
+                        iterationCounts,
+                        halted: false,
+                        savedAt: new Date().toISOString(),
+                    });
+                    currentPhaseIndex = predIndex;
+                    continue;
                 }
-                const predIndex = findPredecessorIndex(BUG_PHASES, currentPhaseIndex);
-                ctx.ui.notify(`⟳ forge:fix-bug — ${phase.role} returned revision; looping to ${BUG_PHASES[predIndex]?.role ?? predIndex} ` +
-                    `(attempt ${iterationCounts[phase.role]}/${phase.maxIterations})`, "info");
-                writeBugState(cwd, {
-                    bugId,
-                    phaseIndex: predIndex,
-                    iterationCounts,
-                    halted: false,
-                    savedAt: new Date().toISOString(),
-                });
-                currentPhaseIndex = predIndex;
-                continue;
+                // verdict === "approved": fall through to advance
             }
-            // verdict === "approved": fall through to advance
-        }
-        // ── Advance to next phase ─────────────────────────────────────
-        registry.completePhase(bugId, phase.role, "completed");
-        writeBugState(cwd, {
-            bugId,
-            phaseIndex: currentPhaseIndex,
-            iterationCounts,
-            halted: false,
-            savedAt: new Date().toISOString(),
-        });
-        // ── 6c. Path A / Path B branch (post-triage) ──────────────────
-        // Per meta-fix-bug.md § Triage Judgement (forge v0.44.0+), the
-        // triage subagent records the route decision in
-        // bug.summaries.triage.route. The orchestrator reads it after
-        // triage returns and selects the downstream phase list:
-        //   Path A (short-circuit): skip plan-fix + review-plan
-        //   Path B (default, full loop): run all phases
-        //
-        // If route is missing or malformed, default to Path B (the safe
-        // choice — running extra phases never produces an unsafe outcome).
-        // The PHASE_SKIP_STATES heuristic at section 6a remains as
-        // defense-in-depth for cases where the field is missing but the
-        // bug status proves the work happened.
-        if (phase.role === "triage") {
-            const bugAfterTriage = readBugRecord(bugId, storeCli, cwd);
-            const triageSummary = bugAfterTriage?.summaries?.triage;
-            const route = triageSummary?.route;
-            if (route === "A") {
-                const skipUntilIndex = BUG_PHASES.findIndex((p) => p.role === "implement");
-                if (skipUntilIndex > currentPhaseIndex + 1) {
-                    ctx.ui.notify(`⊘ forge:fix-bug — Path A selected by triage; skipping plan-fix and review-plan.`, "info");
-                    currentPhaseIndex = skipUntilIndex;
-                    continue;
+            // ── Advance to next phase ─────────────────────────────────────
+            registry.completePhase(bugId, phase.role, "completed");
+            writeBugState(cwd, {
+                bugId,
+                phaseIndex: currentPhaseIndex,
+                iterationCounts,
+                halted: false,
+                savedAt: new Date().toISOString(),
+            });
+            // ── 6c. Path A / Path B branch (post-triage) ──────────────────
+            // Per meta-fix-bug.md § Triage Judgement (forge v0.44.0+), the
+            // triage subagent records the route decision in
+            // bug.summaries.triage.route. The orchestrator reads it after
+            // triage returns and selects the downstream phase list:
+            //   Path A (short-circuit): skip plan-fix + review-plan
+            //   Path B (default, full loop): run all phases
+            //
+            // If route is missing or malformed, default to Path B (the safe
+            // choice — running extra phases never produces an unsafe outcome).
+            // The PHASE_SKIP_STATES heuristic at section 6a remains as
+            // defense-in-depth for cases where the field is missing but the
+            // bug status proves the work happened.
+            if (phase.role === "triage") {
+                const bugAfterTriage = readBugRecord(bugId, storeCli, cwd);
+                const triageSummary = bugAfterTriage?.summaries?.triage;
+                const route = triageSummary?.route;
+                if (route === "A") {
+                    const skipUntilIndex = BUG_PHASES.findIndex((p) => p.role === "implement");
+                    if (skipUntilIndex > currentPhaseIndex + 1) {
+                        ctx.ui.notify(`⊘ forge:fix-bug — Path A selected by triage; skipping plan-fix and review-plan.`, "info");
+                        currentPhaseIndex = skipUntilIndex;
+                        continue;
+                    }
                 }
+                // route === "B", missing, or any other value → fall through to standard advance
             }
-            // route === "B", missing, or any other value → fall through to standard advance
+            currentPhaseIndex++;
         }
-        currentPhaseIndex++;
+        // ── All phases complete ───────────────────────────────────────────
+        deleteBugState(cwd, bugId);
+        orchTranscript.record({
+            kind: "pipeline-end",
+            ts: new Date().toISOString(),
+            outcome: "complete",
+            elapsedMs: Date.now() - pipelineStartMs,
+        });
+        return {
+            status: "completed",
+            lastPhaseIndex: BUG_PHASES.length - 1,
+            iterationCounts,
+            model: lastModel,
+            provider: lastProvider,
+        };
+    }
+    finally {
+        ctx.ui.notify = __origNotify;
     }
-    // ── All phases complete ───────────────────────────────────────────
-    deleteBugState(cwd, bugId);
-    return {
-        status: "completed",
-        lastPhaseIndex: BUG_PHASES.length - 1,
-        iterationCounts,
-        model: lastModel,
-        provider: lastProvider,
-    };
 }
 export function registerFixBug(pi, options = {}) {
     pi.registerCommand("forge:fix-bug", {