@entelligentsia/forgecli 1.0.21 → 1.0.36

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

@@ -1,1705 +1,33 @@
 // fix-bug.ts — /forge:fix-bug Orchestrator native handler (FORGE-S21-T07).
 //
-// Promotes /forge:fix-bug from stub to a full TS-driven Orchestrator-archetype
-// native handler. Reads `.forge/workflows/fix_bug.md`, chains the bug-specific
-// phase sequence (triage → plan-fix → review-plan → implement → review-code →
-// approve → commit) by spawning a fresh runForgeSubagent per phase (IL10).
+// BARREL (FORGE-S31 file-size refactor). The implementation was decomposed into
+// themed modules under ./bug/ to satisfy the per-file architectural line cap.
+// This file re-exports the full public surface so existing importers
+// (index.ts, bin/config.ts, the test suite) keep resolving unchanged.
 //
-// Iron Laws enforced here:
+// Iron Laws (enforced in the extracted modules):
 //   IL1  — code only under forge-cli/src/extensions/forgecli/
 //   IL6  — no shell-string interpolation; all external calls via spawnSync argv arrays
 //   IL7  — every failure path emits ctx.ui.notify and returns; no silent continuation
 //   IL10 — ALL LLM dispatch goes through runForgeSubagent (NO sendKickoff calls here)
 //
-// sendKickoff is NEVER called from this file.
-// Audit-grep: grep -n "sendKickoff(" fix-bug.ts must return empty.
-//
-// N-H-C — bugId dual-assignment lifecycle:
-//   Phase 1 (handler entry, ~line 1372): bugId = `PENDING-${Date.now()}`, isNewBug = true.
-//     A temporary placeholder; the timestamp is later used to find the real bug record.
-//   Phase 2 (pre-init, ~line 1495–1500): preCreateBug() writes a minimal bug record with a
-//     real FORGE-BUG-NNN ID so the triage subagent has a stable ID to reference.
-//     If preCreateBug fails, the PENDING- placeholder is kept for fallback capture.
-//   Phase 3 (post-triage, ~line 962–989): capture real ID from BugCreated events emitted by
-//     the triage subagent; fall back to listing the most-recent bug after pipelineStart if
-//     event capture fails. The PENDING- prefix is used throughout as a guard for
-//     state-write paths (see ~line 176 and CallerContextStore guards).
-//   Reference: PENDING- prefix semantics defined in CallerContextStore guards.
-//
-// N-H-H — Preflight gate design (closed by FORGE-S25-T17):
-//   Entry-level: runOrchestratorPreflight is called at runBugPipeline entry (~line 523).
-//     Validates persona/model config before any LLM dispatch (mirrors run-task.ts design).
-//   Per-phase: runPreflightGate (store-cli gate) is called per phase (~line 667).
-//     Evaluates declarative gate conditions from the workflow's gate block.
-//   This two-level design ensures both structural validity (model/persona config) and
-//   store-state validity (predecessor verdicts, status guards) are checked.
-//   Reference: orchestrator-preflight.ts (N-H-H, FORGE-S25-T17).
-//
-// N-H-E tag: see inline comment at the materialization skip (~line 707 / checkMaterialization).
-import { spawnSync } from "node:child_process";
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { fileURLToPath } from "node:url";
-import { assertAudience, CallerContextStore } from "../audience-gate.js";
-// ModelRegistry/AuthStorage no longer instantiated here — use ctx.modelRegistry
-// so extension-registered providers (registered against the live session) are
-// visible to validateModelConfig. Creating a fresh registry here would miss
-// them and produce spurious MODEL_UNAVAILABLE warnings (FORGE-BUG-001).
-import { loadLayeredConfig } from "../config/config-layer.js";
-import { resolveModelForPhase } from "../config/model-resolver.js";
-import { loadForgePersona, runForgeSubagent } from "../forge-subagent.js";
-import { getSubagentTools } from "../forge-tools.js";
-import { loadGovernorProjectConfig } from "../governor-config.js";
-import { readPersonaDir as readPersonaDirBug, readPipelineNames as readPipelineNamesBug, } from "../lib/catalog-helpers.js";
-import { discoverForgeConfigCached } from "../lib/forge-config.js";
-import { checkMaterialization } from "../lib/manifest-checker.js";
-import { getOrchestratorTree } from "../orchestrator-tree.js";
-import { loadWorkflow } from "../parsers/workflow-loader.js";
-import { getSessionRegistry } from "../session-registry.js";
-import { resolveToCanonicalId, resolveToolDir } from "../store/store-resolver.js";
-import { OrchestratorTranscriptWriter } from "../subagent/orchestrator-transcript.js";
-import { archiveRun, sweepProjectTranscripts } from "../transcript-archive.js";
-import { attachViewportObserver } from "../viewport/events.js";
-import { fmtPhaseSummary } from "../viewport/renderer.js";
-import { resolveAdvisorModel, runHaltAdvisor } from "./halt-advisor.js";
-import { runOrchestratorPreflight } from "./orchestrator-preflight.js";
-import { buildPhaseEvent, buildSummariesBlock, drainFrictionFile, emitEvent, emitIncompletePhaseEvent, findPredecessorIndex, formatLocalTime, isNonInteractive, judgementFromSummary, runPreflightGateWithData, transcriptOutcomeFor, validateId, } from "./run-task.js";
-// ── Bug phase descriptor table ──────────────────────────────────────────────
-//
-// Decoded from .forge/workflows/fix_bug.md and the task prompt's BUG_PHASES.
-// triage / plan-fix / implement all read the same fix_bug.md body — the
-// workflow handles all three phases through prose.
-// 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 = [
-    // 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: "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 },
-];
-// 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.
+// sendKickoff is NEVER called from this file or its extracted modules.
+// ── Bug phase descriptor table + FSM transitions + event tokens ────────────
+export { BUG_PHASES, BUG_TYPE_TOKENS, postTriageTransitions } from "./bug/bug-phases.js";
+// ── Post-triage routing (status transitions + Path A/B branch) ─────────────
+export { routeAfterTriage, } from "./bug/bug-triage-routing.js";
+// BUG_SUMMARY_KEY_BY_ROLE lives in subagent/phase-summary-map.ts; re-exported
+// here for backwards-compatibility with existing call sites and tests.
 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.
-export const BUG_TYPE_TOKENS = {
-    triage: { pass: "bug-triaged", fail: "bug-triaged" },
-    "plan-fix": { pass: "fix-planned", fail: "fix-planned" },
-    "review-plan": { pass: "fix-review-passed", fail: "fix-review-failed" },
-    implement: { pass: "fix-implemented", fail: "fix-implemented" },
-    "review-code": { pass: "fix-code-review-passed", fail: "fix-code-review-failed" },
-    approve: { pass: "fix-approved", fail: "fix-revision-requested" },
-    commit: { pass: "bug-committed", fail: "bug-commit-failed" },
-};
-// ── Bug FSM transitions ────────────────────────────────────────────────────
-// Mirrors store-cli BUG_TRANSITIONS. Terminal: `fixed`.
-// `approved` and `verified` enum values were dropped in forge v0.44.0
-// (FORGE-BUG-002 trap). The canonical source is store-cli.cjs.
-const BUG_TERMINAL_STATES = new Set(["fixed"]);
-function bugStateFilePath(cwd, bugId, sessionId) {
-    if (!validateId(bugId)) {
-        throw new Error(`Invalid bugId for state file path: ${bugId}`);
-    }
-    const suffix = sessionId ?? process.env.FORGE_SESSION_ID ?? `${process.pid}`;
-    return path.join(cwd, ".forge", "cache", `fix-bug-state-${bugId}-${suffix}.json`);
-}
-export function readBugState(cwd, bugId, sessionId) {
-    // If a specific session ID is given, read that file directly.
-    if (sessionId || process.env.FORGE_SESSION_ID) {
-        const fp = bugStateFilePath(cwd, bugId, sessionId);
-        try {
-            if (!fs.existsSync(fp))
-                return null;
-            const raw = fs.readFileSync(fp, "utf8");
-            return JSON.parse(raw);
-        }
-        catch {
-            return null;
-        }
-    }
-    // No specific session — glob for the most recent matching state file.
-    // Single-writer assumption: normally only one session per bug.
-    const cacheDir = path.join(cwd, ".forge", "cache");
-    const prefix = `fix-bug-state-${bugId}-`;
-    let bestFile = null;
-    let bestMtime = 0;
-    try {
-        const entries = fs.readdirSync(cacheDir);
-        for (const entry of entries) {
-            if (!entry.startsWith(prefix) || !entry.endsWith(".json"))
-                continue;
-            const fp = path.join(cacheDir, entry);
-            try {
-                const st = fs.statSync(fp);
-                if (st.mtimeMs > bestMtime) {
-                    bestMtime = st.mtimeMs;
-                    bestFile = fp;
-                }
-            }
-            catch { }
-        }
-    }
-    catch {
-        return null;
-    }
-    if (!bestFile)
-        return null;
-    try {
-        const raw = fs.readFileSync(bestFile, "utf8");
-        return JSON.parse(raw);
-    }
-    catch {
-        return null;
-    }
-}
-export function writeBugState(cwd, state) {
-    // Guard: never write state for PENDING bugIds — wait for real bugId capture.
-    if (state.bugId.startsWith("PENDING-"))
-        return;
-    const fp = bugStateFilePath(cwd, state.bugId);
-    const dir = path.dirname(fp);
-    fs.mkdirSync(dir, { recursive: true });
-    fs.writeFileSync(fp, JSON.stringify(state, null, 2), "utf8");
-}
-export function deleteBugState(cwd, bugId) {
-    // Clean up all state files for this bug (all sessions)
-    const cacheDir = path.join(cwd, ".forge", "cache");
-    const statePrefix = `fix-bug-state-${bugId}-`;
-    const debugPrefix = `fix-bug-debug-${bugId}`;
-    try {
-        const entries = fs.readdirSync(cacheDir);
-        for (const entry of entries) {
-            if ((entry.startsWith(statePrefix) && entry.endsWith(".json")) || entry.startsWith(debugPrefix)) {
-                try {
-                    fs.unlinkSync(path.join(cacheDir, entry));
-                }
-                catch {
-                    /* non-fatal */
-                }
-            }
-        }
-    }
-    catch {
-        // non-fatal
-    }
-}
-export function isBugStateStale(state) {
-    const savedAt = new Date(state.savedAt).getTime();
-    const ageMs = Date.now() - savedAt;
-    const sevenDaysMs = 7 * 24 * 60 * 60 * 1000;
-    return ageMs > sevenDaysMs;
-}
-export function readBugRecord(bugId, storeCli, cwd) {
-    const result = spawnSync("node", [storeCli, "read", "bug", bugId], { cwd, encoding: "utf8" });
-    if (result.status !== 0)
-        return null;
-    try {
-        const raw = typeof result.stdout === "string" ? result.stdout : String(result.stdout);
-        return JSON.parse(raw);
-    }
-    catch {
-        return null;
-    }
-}
-// Pure helper: next <PREFIX>-BUG-NNN ID given the existing bug IDs.
-// Only same-prefix bugs participate in the increment — exported for tests.
-// The prefix is config-owned (project.prefix) and identifier-validated by
-// loadGovernorProjectConfig, so it is safe to splice into a RegExp.
-export function computeNextBugId(bugIds, prefix) {
-    const idPattern = new RegExp(`^${prefix}-BUG-(\\d+)$`);
-    let maxNum = 0;
-    for (const id of bugIds) {
-        const m = idPattern.exec(id);
-        if (m) {
-            const n = parseInt(m[1], 10);
-            if (n > maxNum)
-                maxNum = n;
-        }
-    }
-    return `${prefix}-BUG-${String(maxNum + 1).padStart(3, "0")}`;
-}
-// Pre-assigns a real <PREFIX>-BUG-NNN ID by listing existing bugs and
-// incrementing. Prefix comes from .forge/config.json project.prefix — the
-// hardcoded FORGE prefix minted phantom FORGE-BUG-* records in any project
-// with a different prefix (CART testbench incident, FORGE-BUG-043 class).
-export function assignNextBugId(storeCli, cwd, prefix = "FORGE") {
-    const result = spawnSync("node", [storeCli, "list", "bug", "--json"], { cwd, encoding: "utf8" });
-    let bugIds = [];
-    if (result.status === 0 && result.stdout) {
-        try {
-            const bugs = JSON.parse(result.stdout);
-            if (Array.isArray(bugs)) {
-                bugIds = bugs.map((b) => String(b.bugId ?? ""));
-            }
-        }
-        catch {
-            /* empty store — start from 1 */
-        }
-    }
-    return computeNextBugId(bugIds, prefix);
-}
-// Extracts the first canonical <PREFIX>-BUG-NNN referenced in a bug-report
-// text (e.g. the "**Bug ID**: CART-BUG-001" header line BUG_REPORT.md files
-// carry). Used by the @file intake path so /forge:fix-bug @BUG_REPORT.md
-// operates on the referenced store record instead of minting a duplicate.
-// Prefix is config-owned and identifier-validated (safe in a RegExp).
-export function extractBugIdFromReportText(text, prefix) {
-    const m = text.match(new RegExp(`\\b${prefix}-BUG-\\d+\\b`));
-    return m ? m[0] : null;
-}
-// Pre-creates a minimal bug record so the subagent has a real ID to work with.
-export function preCreateBug(bugId, title, storeCli, cwd) {
-    const data = {
-        bugId,
-        title,
-        severity: "minor",
-        status: "reported",
-        path: `engineering/bugs/${bugId}`,
-        reportedAt: new Date().toISOString(),
-    };
-    const result = spawnSync("node", [storeCli, "write", "bug", JSON.stringify(data)], { cwd, encoding: "utf8" });
-    return result.status === 0;
-}
-export function readBugVerdict(bugRecord, phaseRole, summaryKeyByRole) {
-    if (!bugRecord)
-        return "missing";
-    // Approve phase: read approve summary verdict (set via set-bug-summary).
-    // The forge v0.44.0 contract makes summaries.approve.verdict the canonical
-    // approve signal for bugs — `bug.status` does NOT carry an "approved"
-    // value (that enum was dropped). See read-verdict.cjs §
-    // BUG_PHASE_VERDICT_SOURCE for the matching plugin-side wiring.
-    if (phaseRole === "approve") {
-        const summaryKey = summaryKeyByRole["approve"];
-        if (summaryKey) {
-            const summaries = bugRecord.summaries ?? {};
-            const blob = summaries[summaryKey];
-            if (blob && typeof blob === "object") {
-                const verdict = blob?.verdict;
-                if (typeof verdict === "string") {
-                    if (verdict === "approved")
-                        return "approved";
-                    if (verdict === "revision")
-                        return "revision";
-                }
-            }
-        }
-        return "missing";
-    }
-    // Commit phase: read bug status directly. Terminal target is `fixed`.
-    if (phaseRole === "commit") {
-        if (bugRecord.status === "fixed")
-            return "approved";
-        // in-progress means commit did not advance status — treat as revision-needed.
-        if (bugRecord.status === "in-progress")
-            return "revision";
-        return "missing";
-    }
-    // Review phases: read from summaries via key map.
-    const summaryKey = summaryKeyByRole[phaseRole];
-    if (!summaryKey)
-        return "missing";
-    const summaries = bugRecord.summaries ?? {};
-    const blob = summaries[summaryKey];
-    if (!blob || typeof blob !== "object")
-        return "missing";
-    const verdict = blob?.verdict;
-    if (typeof verdict !== "string")
-        return "missing";
-    if (verdict === "approved")
-        return "approved";
-    if (verdict === "revision")
-        return "revision";
-    return "missing";
-}
-// ── Bug body composition ──────────────────────────────────────────────────
-export function composeBugBody(subWorkflowMd, bugId, phaseRole, bugStatusBeforePhase, summariesBlock) {
-    // Entity-kind override block prepended before workflow body.
-    // Conforms to forge v0.44.x meta-fix-bug contract:
-    //   - bug.status enum is {reported, triaged, in-progress, fixed}; `fixed` is terminal.
-    //   - `approved` and `verified` are NOT valid bug status values (dropped in v0.44.0).
-    //   - Approve phase: NO status write. Architect writes summaries.approve.verdict
-    //     via set-bug-summary; verdict signal IS the summary (read by
-    //     read-verdict.cjs § BUG_PHASE_VERDICT_SOURCE).
-    //   - Commit phase: status → fixed (the only status transition post-triage).
-    //
-    // Earlier revisions of this prompt told the architect to write
-    // `update-status bug ... approved` and the engineer to write `... verified`.
-    // Those instructions produced the FORGE-BUG-002 trap (LLM-translation of
-    // task-shaped approve workflow → illegal transition through a terminal state).
-    // The new contract removes the trap at its source.
-    const entityKindLines = [
-        `Bug ID: ${bugId}`,
-        "",
-        "⚠ ENTITY KIND OVERRIDE: This is a bug, not a task.",
-        "- All `update-status` calls must use entity kind `bug` (not `task`).",
-        "- Approve phase: NO status write. Write the approval verdict via set-bug-summary:",
-        `  node "$FORGE_ROOT/tools/store-cli.cjs" set-bug-summary ${bugId} approve <APPROVE-SUMMARY.json>`,
-        `  The summary's "verdict" field MUST be "approved" or "revision". The downstream commit gate reads this, not bug.status.`,
-        `- Commit phase: on successful git commit, run \`node "$FORGE_ROOT/tools/store-cli.cjs" update-status bug ${bugId} status fixed\` (terminal).`,
-        `- Do NOT write "approved" or "verified" to bug.status — those values were removed from the schema in forge v0.44.0.`,
-        `- Do NOT reference task-specific status values (e.g., "committed") or task entity kind.`,
-        "- CRITICAL: All `set-summary` calls must use `set-bug-summary` (not `set-summary`).",
-        `  e.g. node "$FORGE_ROOT/tools/store-cli.cjs" set-bug-summary ${bugId} review_plan <jsonFile>`,
-        `- Preflight gate: use \`--bug\` flag (not \`--task\`). e.g. node "$FORGE_ROOT/tools/preflight-gate.cjs" --phase review-plan --bug ${bugId}`,
-        "- Skip re-running preflight-gate — the orchestrator already checked it. Proceed directly to the review.",
-        'Any workflow text that says "task" should be read as "bug" for this context.',
-    ];
-    // Phase-specific reinforcement when the orchestrator can name the current status.
-    if (phaseRole === "approve" && bugStatusBeforePhase) {
-        entityKindLines.push(`- Approve phase (reinforce): bug.status is currently '${bugStatusBeforePhase}' and MUST NOT change in this phase. Record verdict in summaries.approve only.`);
-    }
-    if (phaseRole === "commit" && bugStatusBeforePhase) {
-        entityKindLines.push(`- Commit phase: after the git commit lands, transition bug.status from '${bugStatusBeforePhase}' to 'fixed'.`);
-    }
-    // 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}.`,
-        "",
-        "---",
-        "",
-        entityKindLines.join("\n"),
-        "",
-        "---",
-        "",
-    ];
-    if (summariesBlock) {
-        parts.push(summariesBlock, "", "---", "");
-    }
-    parts.push(subWorkflowMd.trim());
-    return parts.join("\n");
-}
-// ── BugId capture via tool_execution_end ──────────────────────────────────
-const BUG_WRITE_TOOL_NAMES = new Set(["write", "store-cli", "bash", "forge_store"]);
-/**
- * Scan tool_execution_end events to extract the bugId written by a triage
- * subagent. Returns the LAST matching tool call's bugId, or null if none found.
- *
- * In pi runtime, the forge_store tool is registered as "forge_store" (not
- * "store-cli"). In Claude Code runtime, subagents may shell out via Bash.
- * This function covers all three paths.
- */
-export function extractBugIdFromEvents(events, prefix = "FORGE") {
-    // Prefix is config-owned (project.prefix) and identifier-validated by
-    // loadGovernorProjectConfig — the previous hardcoded FORGE-BUG- pattern
-    // missed every capture in differently-prefixed projects (CART incident).
-    const idPattern = new RegExp(`${prefix}-BUG-\\d+`);
-    const idPrefix = `${prefix}-BUG-`;
-    let lastBugId = null;
-    for (const event of events) {
-        if (!event.toolName)
-            continue;
-        // Check for store-cli write bug calls (Claude Code runtime)
-        if (event.toolName === "store-cli") {
-            const result = event.result;
-            if (typeof result === "string") {
-                const match = result.match(idPattern);
-                if (match)
-                    lastBugId = match[0];
-            }
-            else if (result && typeof result === "object") {
-                const obj = result;
-                if (typeof obj.bugId === "string" && obj.bugId.startsWith(idPrefix)) {
-                    lastBugId = obj.bugId;
-                }
-            }
-        }
-        // Check for forge_store tool calls (pi runtime)
-        // The pi extension registers the tool as "forge_store", not "store-cli".
-        if (event.toolName === "forge_store" && event.result != null) {
-            const output = typeof event.result === "string" ? event.result : JSON.stringify(event.result);
-            const match = output.match(idPattern);
-            if (match)
-                lastBugId = match[0];
-        }
-        // Also check for write operations to .forge/store/bugs/
-        if (event.toolName === "write" && typeof event.result === "string") {
-            const match = event.result.match(idPattern);
-            if (match)
-                lastBugId = match[0];
-        }
-        // Bash events: subagents shelling out via Bash may run "store-cli write bug".
-        // Only match when output includes store-cli, write, and bug together
-        // to avoid false positives from unrelated Bash commands that happen to
-        // mention a bug ID in a different context.
-        if (event.toolName === "bash" && event.result != null) {
-            const output = typeof event.result === "string" ? event.result : JSON.stringify(event.result);
-            if (output.includes("store-cli") && output.includes("write") && output.includes("bug")) {
-                const match = output.match(idPattern);
-                if (match)
-                    lastBugId = match[0];
-            }
-        }
-    }
-    return lastBugId;
-}
-const STATUS_KEY = "forge:fix-bug";
-const MESSAGE_KEY = "forge:fix-bug:message";
-export async function runBugPipeline(opts) {
-    // Thin wrapper: capture the orchestrator transcript writer the inner
-    // pipeline creates, surface its path on the result (so callers can
-    // archive the run), and GUARANTEE a pipeline-end on every outcome —
-    // cancel/halt/failure paths that return without recording one left runs
-    // archived as "incomplete" instead of their true outcome.
-    let orchTranscript;
-    const result = await runBugPipelineInner(opts, (writer) => {
-        orchTranscript = writer;
-    });
-    if (orchTranscript) {
-        orchTranscript.close(transcriptOutcomeFor(result.status), result.lastError);
-        result.orchestratorTranscriptPath = orchTranscript.filePath;
-    }
-    return result;
-}
-async function runBugPipelineInner(opts, onOrchestratorTranscript) {
-    const { bugId: initialBugId, originalArg, isNewBug, cwd, ctx, forgeRoot, storeCli, preflightGate, registry, resumeFromState, } = opts;
-    const tree = getOrchestratorTree();
-    // Mutable bugId — for new bugs, pre-assign a real FORGE-BUG-NNN ID
-    // before triage so the subagent never needs to create or discover one.
-    // This replaces the fragile PENDING→capture pattern where the subagent was
-    // expected to create the bug record and we'd fish the ID from events.
-    let bugId = initialBugId;
-    let currentPhaseIndex = resumeFromState?.phaseIndex ?? 0;
-    const iterationCounts = resumeFromState?.iterationCounts ?? {};
-    // Per-role dispatch counter for OrchestratorTree node identity. Distinct
-    // from iterationCounts (which only tracks review-verdict revisions): every
-    // dispatch of a role — including a plan-fix re-run after a review
-    // loopback — gets its own `<bugId>:<role>:<attempt>` node, so the
-    // dashboard renders one leaf per run in dispatch order instead of merging
-    // attempts into one node (CART-BUG-003 dashboard regression). Seeded from
-    // resume state so resumed runs continue numbering past prior attempts.
-    const dispatchCounts = { ...(resumeFromState?.iterationCounts ?? {}) };
-    let lastModel;
-    let lastProvider;
-    // ── Per-persona model routing (Plan 16) ─────────────────────────────────
-    // Load layered routing config once at bug-pipeline entry. Empty / absent
-    // config produces inherit for every phase — no behaviour change. Pipeline
-    // name "fix-bug" lets users configure per-phase overrides distinctly from
-    // task pipelines under pipelines["fix-bug"] in their routing config.
-    // N-B-E: surface schema errors to caller (Decision 9 — orchestrators fail-fast).
-    // See doc/decisions/layered-config-error-policy.md.
-    const { merged: modelRoutingConfig, errors: layeredConfigErrors } = loadLayeredConfig(cwd);
-    if (layeredConfigErrors.length > 0) {
-        for (const e of layeredConfigErrors) {
-            ctx.ui.notify(`× forge:fix-bug — forge-cli config schema error: ${e}`, "error");
-        }
-        return {
-            status: "failed",
-            lastPhaseIndex: currentPhaseIndex,
-            iterationCounts,
-            lastError: `forge-cli config schema errors: ${layeredConfigErrors.join("; ")}`,
-        };
-    }
-    // Pre-flight validation — same shape as run-task / run-sprint.
-    // FORGE-S25-T17: delegated to orchestrator-preflight.ts (H-13).
-    {
-        const personasDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "forge-payload", ".base-pack", "personas");
-        const personaCatalogue = readPersonaDirBug(personasDir);
-        const forgeCfgPath = path.join(cwd, ".forge", "config.json");
-        const pipelineCatalogue = readPipelineNamesBug(forgeCfgPath);
-        const availableModels = ctx.modelRegistry?.getAvailable?.() ?? [];
-        const preflightResult = runOrchestratorPreflight({
-            mode: "task",
-            ctx,
-            notifyPrefix: "forge:fix-bug",
-            personaCatalogue,
-            pipelineCatalogue,
-            modelRoutingConfig,
-            availableModels: availableModels.map((m) => ({ provider: m.provider, id: m.id })),
-        });
-        if (!preflightResult.proceed) {
-            return {
-                ...preflightResult.result,
-                lastPhaseIndex: currentPhaseIndex,
-                iterationCounts,
-            };
-        }
-    }
-    // ── 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,
-    });
-    onOrchestratorTranscript(orchTranscript);
-    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: 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");
-            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: `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 preflightOutcome = runPreflightGateWithData(preflightGate, phase.role, bugId, cwd, "bug");
-                if (preflightOutcome.result === "halt") {
-                    // Render structured failure reason if available.
-                    if (preflightOutcome.gateFailure) {
-                        ctx.ui.notify(`× forge:fix-bug — preflight gate failed for phase ${phase.role} ` +
-                            `[${preflightOutcome.gateFailure.reasonCode}]: ${preflightOutcome.gateFailure.detail}`, "error");
-                    }
-                    else {
-                        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(),
-                    });
-                    // Spawn halt-recovery advisor (Tier 1, best-effort — non-fatal).
-                    if (preflightOutcome.gateFailure) {
-                        const advisorModel = resolveAdvisorModel(modelRoutingConfig, ctx.model);
-                        void runHaltAdvisor({
-                            gateFailure: preflightOutcome.gateFailure,
-                            advisorModel,
-                            taskId: bugId,
-                            cwd,
-                            ctx: { ui: ctx.ui },
-                            forgeRoot,
-                        });
-                    }
-                    return {
-                        status: "halted",
-                        lastPhaseIndex: currentPhaseIndex,
-                        iterationCounts,
-                        lastError: `preflight gate exit 1 for ${phase.role}`,
-                    };
-                }
-                if (preflightOutcome.result === "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}`,
-                    };
-                }
-            }
-            // ── 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(", ")}`,
-                    };
-                }
-            }
-            // ── 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: `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.
-                        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");
-                            }
-                        }
-                        catch {
-                            /* file may not exist yet */
-                        }
-                        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);
-            // Bridge: register phase in OrchestratorTree. Node identity is
-            // per-dispatch (see dispatchCounts above) — never reuse an ID for
-            // a re-dispatched role.
-            const iteration = (dispatchCounts[phase.role] = (dispatchCounts[phase.role] ?? 0) + 1);
-            const phaseNodeId = `${bugId}:${phase.role}:${iteration}`;
-            tree.startNode(phaseNodeId, {
-                parentId: bugId,
-                label: `${phase.role}:${iteration}`,
-                kind: "leaf",
-                // Full body — display clamping/expansion is the view's decision
-                // (the tree applies only a storage cap).
-                promptPreview: bugBody,
-            });
-            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,
-                nodeId: phaseNodeId,
-                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}`,
-                    tailLog: observer.state.tailLog,
-                    // 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");
-                tree.completeNode(phaseNodeId, "failed");
-                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"}`,
-                };
-            }
-            // Close this dispatch's tree node with final usage/model — MUST be
-            // called on every exit path below (failure, halt, escalation,
-            // loopback, advance). A node left `running` keeps a live spinner
-            // in the dashboard forever AND absorbs the next same-role
-            // dispatch's telemetry via the observer's legacy role-prefix scan.
-            const finishPhaseNode = (status) => {
-                tree.setNodeUsage(phaseNodeId, {
-                    input: result.usage.input,
-                    output: result.usage.output,
-                    cacheRead: result.usage.cacheRead,
-                });
-                if (result.model)
-                    tree.setNodeModel(phaseNodeId, result.model, result.provider ?? "");
-                tree.completeNode(phaseNodeId, status);
-            };
-            // ── 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");
-                tree.completeNode(phaseNodeId, "cancelled");
-                registry.confirmCancelled(bugId);
-                // Bug B parity with run-task: account billed tokens of the aborted attempt.
-                // sprintId "bugs" = routing key for bug events (matches success path).
-                // The optional `type` token is omitted — verdict carries the outcome.
-                emitIncompletePhaseEvent({
-                    emitCtx: {
-                        entityType: "bug",
-                        bugId,
-                        sprintId: "bugs",
-                        phase,
-                        iteration: (iterationCounts[phase.role] ?? 0) + 1,
-                        startMs: phaseStart,
-                        endMs: Date.now(),
-                        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: undefined,
-                        storeCli,
-                        cwd,
-                    },
-                    outcome: "aborted",
-                    notes: result.errorMessage ?? result.stopReason ?? undefined,
-                    onDebug: writeDebug,
-                });
-                // 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");
-                finishPhaseNode("failed");
-                // Bug B parity with run-task: account billed tokens of the failed attempt.
-                emitIncompletePhaseEvent({
-                    emitCtx: {
-                        entityType: "bug",
-                        bugId,
-                        sprintId: "bugs",
-                        phase,
-                        iteration: (iterationCounts[phase.role] ?? 0) + 1,
-                        startMs: phaseStart,
-                        endMs: Date.now(),
-                        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: undefined,
-                        storeCli,
-                        cwd,
-                    },
-                    outcome: "failed",
-                    notes: result.errorMessage ?? result.stopReason ?? undefined,
-                    onDebug: writeDebug,
-                });
-                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, loadGovernorProjectConfig(cwd).prefix);
-                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,
-                    subagentTranscriptPath: result.subagentTranscriptPath,
-                });
-                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. Halting for advisory.`, "error");
-                    finishPhaseNode("failed");
-                    writeBugState(cwd, {
-                        bugId,
-                        phaseIndex: currentPhaseIndex,
-                        iterationCounts,
-                        halted: true,
-                        lastError: `verdict missing for ${phase.role}`,
-                        savedAt: new Date().toISOString(),
-                    });
-                    // A missing verdict IS a postflight-outputs failure: the canonical
-                    // phase summary the subagent must write (e.g. summaries.code_review,
-                    // linked via set-bug-summary) was never recorded, so there is no
-                    // verdict to route on. Route it through the halt-recovery advisor
-                    // (FORGE-S26-T18) — the same hand-off the preflight/postflight gate
-                    // failures use — instead of a bare escalation. Best-effort, non-fatal.
-                    const advisorModel = resolveAdvisorModel(modelRoutingConfig, ctx.model);
-                    void runHaltAdvisor({
-                        gateFailure: {
-                            phase: phase.role,
-                            reasonCode: "verdict-missing",
-                            detail: `Phase '${phase.role}' completed but no verdict was found in the store. ` +
-                                "The canonical phase summary was not written, so the orchestrator has no verdict to route on.",
-                            remediation: "Re-run the phase and ensure the subagent's forge_store set-bug-summary call " +
-                                'uses args:["<bugId>", "<phaseKey>"] with the literal phase key as args[1] ' +
-                                "(e.g. code_review), and that the call exits zero before the subagent returns.",
-                        },
-                        advisorModel,
-                        taskId: bugId,
-                        cwd,
-                        ctx: { ui: ctx.ui },
-                        forgeRoot,
-                    });
-                    return {
-                        status: "halted",
-                        lastPhaseIndex: currentPhaseIndex,
-                        iterationCounts,
-                        lastError: `verdict missing for ${phase.role}`,
-                    };
-                }
-                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");
-                        finishPhaseNode("escalated");
-                        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}`,
-                        };
-                    }
-                    // 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");
-                        }
-                    }
-                    // The review subagent itself finished cleanly — `revision`
-                    // is its verdict, not a failure — so its node closes as
-                    // completed before the predecessor re-dispatches under a
-                    // fresh node ID.
-                    finishPhaseNode("completed");
-                    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;
-                }
-                // verdict === "approved": fall through to advance
-            }
-            // ── Advance to next phase ─────────────────────────────────────
-            registry.completePhase(bugId, phase.role, "completed");
-            finishPhaseNode("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
-            }
-            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;
-    }
-}
-export function registerFixBug(pi, options = {}) {
-    pi.registerCommand("forge:fix-bug", {
-        description: "Run the full bug-fix pipeline (triage → plan-fix → review-plan → implement → review-code → approve → commit). " +
-            "Usage: /forge:fix-bug <BUG_ID_OR_SUMMARY>. " +
-            "Orchestrator archetype: each phase is an isolated subagent session (IL10).",
-        async handler(args, ctx) {
-            const cwd = options.cwd ?? process.cwd();
-            const rawArg = args.trim();
-            if (!rawArg) {
-                ctx.ui.notify("× forge:fix-bug — bug ID or summary required. Usage: /forge:fix-bug <BUG_ID_OR_SUMMARY>", "error");
-                return;
-            }
-            ctx.ui.setStatus?.(STATUS_KEY, `fix-bug: initializing…`);
-            // ── Discover forge config ────────────────────────────────────────
-            const forgeConfig = discoverForgeConfigCached(cwd);
-            if (!forgeConfig) {
-                ctx.ui.notify("× forge:fix-bug — no Forge project found at cwd. Run /forge:init first.", "error");
-                ctx.ui.setStatus?.(STATUS_KEY, undefined);
-                ctx.ui.setStatus?.(MESSAGE_KEY, undefined);
-                return;
-            }
-            const forgeRoot = forgeConfig.forgeRoot;
-            // Best-effort transcript-archive sweep: adopt any project-local runs
-            // not yet in the central index (crash recovery + pre-existing
-            // history). Runs BEFORE this pipeline creates its own transcript
-            // writer, so the in-flight run is never swept half-written.
-            sweepProjectTranscripts(cwd);
-            // Tool paths
-            const storeCli = path.join(forgeRoot, "tools", "store-cli.cjs");
-            const preflightGate = path.join(forgeRoot, "tools", "preflight-gate.cjs");
-            // ── Determine bugId ────────────────────────────────────────────
-            let bugId;
-            let isNewBug = false;
-            // Check if arg looks like it could be a bug ID (prefixed or unprefixed).
-            // Covers: FORGE-BUG-042, BUG-042, B042.
-            const looksLikeBugId = /^(?:[A-Z0-9]+-)?(?:BUG-?\d+|B\d+)$/i.test(rawArg) || /^BUG-\d+$/i.test(rawArg);
-            if (/^[A-Z][A-Z0-9]*-BUG-\d+$/.test(rawArg)) {
-                // Canonical prefixed bug ID (any project prefix, e.g. FORGE-BUG-042,
-                // CART-BUG-001) — verify it exists. Previously hardcoded to FORGE-,
-                // which pushed other-prefix canonical IDs through the resolver.
-                bugId = rawArg;
-                const bugRecord = readBugRecord(bugId, storeCli, cwd);
-                if (!bugRecord) {
-                    ctx.ui.notify(`× forge:fix-bug — bug ${bugId} not found in store.`, "error");
-                    ctx.ui.setStatus?.(STATUS_KEY, undefined);
-                    return;
-                }
-                // Check if bug is already in a terminal state
-                if (BUG_TERMINAL_STATES.has(bugRecord.status ?? "")) {
-                    ctx.ui.notify(`× forge:fix-bug — bug ${bugId} is already in terminal state '${bugRecord.status}'. No further processing.`, "error");
-                    ctx.ui.setStatus?.(STATUS_KEY, undefined);
-                    return;
-                }
-            }
-            else if (looksLikeBugId) {
-                // Unprefixed bug ID — resolve through the store cascade.
-                // Issue #20: unprefixed entity IDs silently poisoned substitutions.
-                const toolDir = resolveToolDir(forgeRoot);
-                const resolvedBugId = await resolveToCanonicalId(rawArg, toolDir, cwd, "bug", {
-                    ctx,
-                    commandLabel: "forge:fix-bug",
-                });
-                if (!resolvedBugId) {
-                    // Error already emitted by resolver
-                    ctx.ui.setStatus?.(STATUS_KEY, undefined);
-                    ctx.ui.setStatus?.(MESSAGE_KEY, undefined);
-                    return;
-                }
-                bugId = resolvedBugId;
-                // Re-verify the resolved bug exists
-                const bugRecord = readBugRecord(bugId, storeCli, cwd);
-                if (!bugRecord) {
-                    ctx.ui.notify(`× forge:fix-bug — bug ${bugId} not found in store.`, "error");
-                    ctx.ui.setStatus?.(STATUS_KEY, undefined);
-                    return;
-                }
-                if (BUG_TERMINAL_STATES.has(bugRecord.status ?? "")) {
-                    ctx.ui.notify(`× forge:fix-bug — bug ${bugId} is already in terminal state '${bugRecord.status}'. No further processing.`, "error");
-                    ctx.ui.setStatus?.(STATUS_KEY, undefined);
-                    return;
-                }
-            }
-            else {
-                // @file or free-form text. If an @file report references a canonical
-                // <PREFIX>-BUG-NNN that already exists in the store, fix THAT record —
-                // minting a new bug here duplicated CART-BUG-001 as a phantom in the
-                // CART incident (the report header carried the real ID all along).
-                let reportBugId = null;
-                if (rawArg.startsWith("@")) {
-                    const rel = rawArg.slice(1).trim();
-                    const reportPath = path.isAbsolute(rel) ? rel : path.join(cwd, rel);
-                    try {
-                        // 256 KB cap — bug reports are small; never slurp arbitrary files.
-                        if (fs.existsSync(reportPath) && fs.statSync(reportPath).size <= 262144) {
-                            const projectPrefix = loadGovernorProjectConfig(cwd).prefix;
-                            reportBugId = extractBugIdFromReportText(fs.readFileSync(reportPath, "utf8"), projectPrefix);
-                        }
-                    }
-                    catch {
-                        /* unreadable report — fall through to new-bug intake */
-                    }
-                }
-                const reportRecord = reportBugId ? readBugRecord(reportBugId, storeCli, cwd) : null;
-                if (reportBugId && reportRecord) {
-                    if (BUG_TERMINAL_STATES.has(reportRecord.status ?? "")) {
-                        ctx.ui.notify(`× forge:fix-bug — ${rawArg} references ${reportBugId}, which is already in terminal state ` +
-                            `'${reportRecord.status}'. No further processing.`, "error");
-                        ctx.ui.setStatus?.(STATUS_KEY, undefined);
-                        return;
-                    }
-                    bugId = reportBugId;
-                    ctx.ui.notify(`forge:fix-bug — ${rawArg} references existing bug ${bugId}; fixing it (no new record minted).`, "info");
-                }
-                else {
-                    // Free-form text (or report with no resolvable ID) — defer bug
-                    // creation to the triage-phase subagent via a PENDING placeholder.
-                    bugId = `PENDING-${Date.now()}`;
-                    isNewBug = true;
-                }
-            }
-            // ── Pre-flight confirm ───────────────────────────────────────────
-            if (!isNonInteractive()) {
-                const confirmMsg = isNewBug
-                    ? `Fix bug: "${rawArg.slice(0, 80)}"? A bug record will be created during triage.`
-                    : `Fix bug ${bugId}?`;
-                const proceed = await ctx.ui.confirm(`Fix bug?`, confirmMsg);
-                if (!proceed) {
-                    ctx.ui.notify("forge:fix-bug — cancelled.", "info");
-                    ctx.ui.setStatus?.(STATUS_KEY, undefined);
-                    return;
-                }
-            }
-            // ── Resume detection ─────────────────────────────────────────────
-            const registry = getSessionRegistry();
-            const existing = isNewBug ? null : readBugState(cwd, bugId);
-            let resumeFromState;
-            if (existing) {
-                if (isBugStateStale(existing)) {
-                    ctx.ui.notify(`⚠ forge:fix-bug — cached state for ${bugId} is stale (>7 days old, saved at ${formatLocalTime(existing.savedAt)}). Offering purge.`, "warning");
-                    if (!isNonInteractive()) {
-                        const purge = await ctx.ui.confirm(`Purge stale state for ${bugId}?`, "The cached state is older than 7 days. Purge and restart from the beginning?");
-                        if (purge) {
-                            deleteBugState(cwd, bugId);
-                        }
-                        else {
-                            ctx.ui.notify("forge:fix-bug — stale state kept; aborting.", "info");
-                            ctx.ui.setStatus?.(STATUS_KEY, undefined);
-                            ctx.ui.setStatus?.(MESSAGE_KEY, undefined);
-                            return;
-                        }
-                    }
-                    else {
-                        ctx.ui.notify("forge:fix-bug — stale state; non-interactive mode auto-aborting.", "info");
-                        ctx.ui.setStatus?.(STATUS_KEY, undefined);
-                        ctx.ui.setStatus?.(MESSAGE_KEY, undefined);
-                        return;
-                    }
-                }
-                else {
-                    // ADR-S21-01: offer resume for ALL non-stale states — halted=true
-                    // (explicit failure), halted=false (cancelled/interrupted), and
-                    // any state with existing.status set.
-                    const stateStatus = existing.status ?? (existing.halted ? "halted" : "interrupted");
-                    const statusLabel = stateStatus === "cancelled" ? "cancelled" : stateStatus === "halted" ? "halted" : "interrupted";
-                    const phaseRole = BUG_PHASES[existing.phaseIndex]?.role ?? existing.phaseIndex;
-                    if (!isNonInteractive()) {
-                        const resume = await ctx.ui.confirm(`Resume ${bugId}?`, `Cached state — phase ${existing.phaseIndex} (${phaseRole}), ${statusLabel}, ` +
-                            `saved at ${formatLocalTime(existing.savedAt)}. Resume from here?`);
-                        if (resume) {
-                            resumeFromState = existing;
-                            ctx.ui.notify(`forge:fix-bug — resuming ${bugId} from phase ${phaseRole} (${statusLabel})`, "info");
-                        }
-                        else {
-                            deleteBugState(cwd, bugId);
-                        }
-                    }
-                    else {
-                        // Non-interactive: auto-resume from state (no confirmation).
-                        // Cancelled/interrupted states are valid resume points.
-                        resumeFromState = existing;
-                        ctx.ui.notify(`forge:fix-bug — resuming ${bugId} from phase ${phaseRole} (${statusLabel})`, "info");
-                    }
-                }
-            }
-            // For new bugs, triage phase will create the bug record.
-            // After triage, we need to capture the bugId from the subagent events.
-            // This is handled inside runBugPipeline via onEvent interception.
-            // For now, we pass the temporary bugId; runBugPipeline will update it.
-            // ── Materialization check (top-level workflow) ──────────────────
-            const workflowPath = path.join(cwd, ".forge", "workflows", "fix_bug.md");
-            if (fs.existsSync(workflowPath)) {
-                try {
-                    const loaded = loadWorkflow(workflowPath);
-                    // AC#12: Top-level audience check for the fix_bug.md workflow.
-                    // The orchestrator ITSELF runs fix_bug.md (not a subagent), so check
-                    // from orchestrator context. Using asSubagent would falsely reject
-                    // orchestrator-only workflows called by the orchestrator.
-                    const topAudienceOk = CallerContextStore.asOrchestrator(() => assertAudience({ workflowName: "fix_bug", audience: loaded.audience }, ctx));
-                    if (!topAudienceOk) {
-                        ctx.ui.notify("× forge:fix-bug — audience check failed for top-level fix_bug workflow.", "error");
-                        ctx.ui.setStatus?.(STATUS_KEY, undefined);
-                        ctx.ui.setStatus?.(MESSAGE_KEY, undefined);
-                        return;
-                    }
-                    // Note: no materialization-marker check here. fix_bug.md is the
-                    // orchestrator workflow (prose algorithm), not a sub-workflow that
-                    // subagents run directly. Per-phase sub-workflows (architect_approve,
-                    // review_code, etc.) each get their own materialization check inside
-                    // runBugPipeline at line ~481, which is the correct guard layer.
-                }
-                catch {
-                    // Workflow file exists but couldn't be read — non-fatal, continue
-                }
-            }
-            // ── Pre-assign real bug ID for new bugs ────────────────────────
-            // Previously this was done inside runBugPipeline, but the session registry
-            // needs the real ID before startSession is called.
-            if (isNewBug && bugId.startsWith("PENDING-")) {
-                const realBugId = assignNextBugId(storeCli, cwd, loadGovernorProjectConfig(cwd).prefix);
-                const title = rawArg && !rawArg.startsWith("@") ? rawArg.slice(0, 120) : "New bug (pending triage)";
-                if (preCreateBug(realBugId, title, storeCli, cwd)) {
-                    ctx.ui.notify(`forge:fix-bug — pre-assigned bug ID: ${realBugId}`, "info");
-                    bugId = realBugId;
-                }
-                else {
-                    ctx.ui.notify("× forge:fix-bug — failed to pre-create bug record. Falling back to PENDING capture.", "error");
-                }
-            }
-            // Register session
-            registry.startSession(bugId);
-            // Bridge: register bug in OrchestratorTree.
-            const tree = getOrchestratorTree();
-            tree.startNode(bugId, { label: `fix-bug ${bugId}`, kind: "orchestrator" });
-            // ── Delegate to pipeline ─────────────────────────────────────────
-            // ── Delegate to pipeline ─────────────────────────────────────────
-            const signal = registry.getAbortSignal(bugId);
-            const pipelineResult = await runBugPipeline({
-                bugId,
-                originalArg: isNewBug ? rawArg : undefined,
-                isNewBug,
-                cwd,
-                ctx,
-                forgeRoot,
-                storeCli,
-                preflightGate,
-                registry,
-                resumeFromState,
-                signal,
-                forgeToolDefs: options.forgeToolDefs,
-            });
-            // ── Handle result ────────────────────────────────────────────────
-            if (pipelineResult.status === "completed") {
-                registry.completeSession(bugId, "completed");
-                tree.completeNode(bugId, "completed");
-                ctx.ui.notify(`〇 forge:fix-bug — ${bugId} pipeline complete (${BUG_PHASES.length} phases).`, "info");
-            }
-            else if (pipelineResult.status === "cancelled") {
-                registry.completeSession(bugId, "cancelled");
-                tree.completeNode(bugId, "cancelled");
-            }
-            else {
-                registry.completeSession(bugId, "failed");
-                tree.completeNode(bugId, "failed");
-            }
-            // Mirror this run into the central transcript archive (best-effort —
-            // archiveRun never throws).
-            if (pipelineResult.orchestratorTranscriptPath) {
-                archiveRun({
-                    cwd,
-                    orchestratorJsonlPath: pipelineResult.orchestratorTranscriptPath,
-                });
-            }
-            ctx.ui.setStatus?.(STATUS_KEY, undefined);
-            ctx.ui.setStatus?.(MESSAGE_KEY, undefined);
-        },
-    });
-}
+// ── State persistence ─────────────────────────────────────────────────────
+export { deleteBugState, isBugStateStale, readBugState, writeBugState, } from "./bug/bug-state.js";
+// ── Bug record + ID minting / capture helpers ──────────────────────────────
+export { assignNextBugId, computeNextBugId, extractBugIdFromEvents, extractBugIdFromReportText, preCreateBug, readBugRecord, } from "./bug/bug-id.js";
+// ── Verdict read ───────────────────────────────────────────────────────────
+export { readBugVerdict } from "./bug/bug-verdict.js";
+// ── Bug body composition ───────────────────────────────────────────────────
+export { composeBugBody } from "./bug/bug-body.js";
+// ── Pipeline + command handler ─────────────────────────────────────────────
+export { runBugPipeline } from "./bug/run-bug-pipeline.js";
+export { registerFixBug } from "./bug/run-bug-command.js";
 //# sourceMappingURL=fix-bug.js.map