@entelligentsia/forgecli 1.0.25 → 1.0.36

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

@@ -0,0 +1,65 @@
+// bug-body.ts — compose the per-phase subagent prompt body for a bug, with the
+// entity-kind override block prepended before the workflow body. Extracted
+// VERBATIM from fix-bug.ts (FORGE-S31 file-size refactor); no logic changes.
+// ── 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");
+}
+//# sourceMappingURL=bug-body.js.map

package/dist/extensions/forgecli/orchestrators/bug/bug-body.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bug-body.js","sourceRoot":"","sources":["../../../../../src/extensions/forgecli/orchestrators/bug/bug-body.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,2EAA2E;AAC3E,6EAA6E;AAE7E,6EAA6E;AAE7E,MAAM,UAAU,cAAc,CAC7B,aAAqB,EACrB,KAAa,EACb,SAAiB,EACjB,oBAA6B,EAC7B,cAAuB;IAEvB,6DAA6D;IAC7D,mDAAmD;IACnD,uFAAuF;IACvF,sFAAsF;IACtF,iFAAiF;IACjF,kEAAkE;IAClE,oDAAoD;IACpD,6EAA6E;IAC7E,EAAE;IACF,+DAA+D;IAC/D,6EAA6E;IAC7E,yEAAyE;IACzE,+EAA+E;IAC/E,mDAAmD;IACnD,MAAM,eAAe,GAAa;QACjC,WAAW,KAAK,EAAE;QAClB,EAAE;QACF,oDAAoD;QACpD,sEAAsE;QACtE,mFAAmF;QACnF,4DAA4D,KAAK,iCAAiC;QAClG,0HAA0H;QAC1H,4GAA4G,KAAK,6BAA6B;QAC9I,qHAAqH;QACrH,yFAAyF;QACzF,qFAAqF;QACrF,iEAAiE,KAAK,yBAAyB;QAC/F,qIAAqI,KAAK,EAAE;QAC5I,yGAAyG;QACzG,8EAA8E;KAC9E,CAAC;IAEF,kFAAkF;IAClF,IAAI,SAAS,KAAK,SAAS,IAAI,oBAAoB,EAAE,CAAC;QACrD,eAAe,CAAC,IAAI,CACnB,yDAAyD,oBAAoB,gFAAgF,CAC7J,CAAC;IACH,CAAC;IACD,IAAI,SAAS,KAAK,QAAQ,IAAI,oBAAoB,EAAE,CAAC;QACpD,eAAe,CAAC,IAAI,CACnB,2EAA2E,oBAAoB,eAAe,CAC9G,CAAC;IACH,CAAC;IACD,uEAAuE;IACvE,sEAAsE;IACtE,yEAAyE;IACzE,yEAAyE;IACzE,6DAA6D;IAE7D,MAAM,KAAK,GAAG;QACb,kDAAkD,KAAK,GAAG;QAC1D,EAAE;QACF,KAAK;QACL,EAAE;QACF,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC;QAC1B,EAAE;QACF,KAAK;QACL,EAAE;KACF,CAAC;IACF,IAAI,cAAc,EAAE,CAAC;QACpB,KAAK,CAAC,IAAI,CAAC,cAAc,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;IAC3C,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,CAAC;IACjC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC"}

package/dist/extensions/forgecli/orchestrators/bug/bug-id.d.ts

@@ -0,0 +1,23 @@
+export interface BugRecord {
+    bugId?: string;
+    status?: string;
+    summaries?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export declare function readBugRecord(bugId: string, storeCli: string, cwd: string): BugRecord | null;
+export declare function computeNextBugId(bugIds: string[], prefix: string): string;
+export declare function assignNextBugId(storeCli: string, cwd: string, prefix?: string): string;
+export declare function extractBugIdFromReportText(text: string, prefix: string): string | null;
+export declare function preCreateBug(bugId: string, title: string, storeCli: string, cwd: string): boolean;
+/**
+ * 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 declare function extractBugIdFromEvents(events: Array<{
+    toolName?: string;
+    result?: unknown;
+}>, prefix?: string): string | null;

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

@@ -0,0 +1,140 @@
+// bug-id.ts — bug record read helper plus the bug-ID minting / capture
+// utilities (computeNextBugId, assignNextBugId, extractBugIdFromReportText,
+// preCreateBug, extractBugIdFromEvents). Extracted VERBATIM from fix-bug.ts
+// (FORGE-S31 file-size refactor); no logic changes.
+import { spawnSync } from "node:child_process";
+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;
+}
+// ── BugId capture via tool_execution_end ──────────────────────────────────
+/**
+ * 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;
+}
+//# sourceMappingURL=bug-id.js.map

package/dist/extensions/forgecli/orchestrators/bug/bug-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bug-id.js","sourceRoot":"","sources":["../../../../../src/extensions/forgecli/orchestrators/bug/bug-id.ts"],"names":[],"mappings":"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"}

package/dist/extensions/forgecli/orchestrators/bug/bug-phase-dispatch.d.ts

@@ -0,0 +1,54 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { MergedConfig } from "../../config/config-layer.js";
+import { type SubagentResult } from "../../forge-subagent.js";
+import { attachViewportObserver } from "../../viewport/events.js";
+import { type PhaseDescriptor } from "../run-task.js";
+import type { BugRecord } from "./bug-id.js";
+import type { RunBugPipelineOptions, RunBugPipelineResult } from "./run-bug-types.js";
+export interface BugPhaseDispatchParams {
+    opts: RunBugPipelineOptions;
+    phase: PhaseDescriptor;
+    bugId: string;
+    cwd: string;
+    ctx: ExtensionCommandContext;
+    storeCli: string;
+    currentPhaseIndex: number;
+    iterationCounts: Record<string, number>;
+    dispatchCounts: Record<string, number>;
+    modelRoutingConfig: MergedConfig;
+    registry: RunBugPipelineOptions["registry"];
+    /** Whether this is a new bug — only used to decide the triage-prefix body. */
+    isNewBug: boolean | undefined;
+    originalArg: string | undefined;
+    /** Raw sub-workflow markdown already loaded + marker/audience-checked by the caller. */
+    subWorkflowMd: string;
+    /** Bug record read before this phase (status used for compose + cache key). */
+    bugRecordBefore: BugRecord | null;
+    bugStatusBeforePhase: string | undefined;
+    /** True when bugId is still a PENDING- placeholder (triage of a new bug). */
+    pendingBugId: boolean;
+}
+export type BugPhaseDispatchOutcome = {
+    kind: "return";
+    result: RunBugPipelineResult;
+} | {
+    kind: "ok";
+    result: SubagentResult;
+    finishPhaseNode: (status: "completed" | "failed" | "escalated") => void;
+    observer: ReturnType<typeof attachViewportObserver>;
+    phaseStart: number;
+    writeDebug: (rec: Record<string, unknown>) => void;
+    toolExecutionEvents: Array<{
+        toolName?: string;
+        result?: unknown;
+    }>;
+    debugLogPath: string | null;
+    debugLogDisabled: boolean;
+};
+/**
+ * Run a single bug phase's subagent dispatch and classify the immediate outcome
+ * (persona-load failure, subagent throw, cancellation, or non-zero exit) into a
+ * discriminated result. On success returns `kind: "ok"` with the live locals the
+ * caller's loop needs for bugId capture / verdict / advance handling.
+ */
+export declare function dispatchBugPhase(p: BugPhaseDispatchParams): Promise<BugPhaseDispatchOutcome>;

package/dist/extensions/forgecli/orchestrators/bug/bug-phase-dispatch.js

@@ -0,0 +1,349 @@
+// bug-phase-dispatch.ts — per-phase subagent dispatch for the fix-bug pipeline:
+// persona load → bug-body compose → debug-log setup → viewport observer attach
+// → model resolution → runForgeSubagent (IL10) → post-subagent abort /
+// halt-on-failure detection. Extracted VERBATIM from fix-bug.ts's phase loop
+// (FORGE-S31 file-size refactor) with no logic changes — the inline
+// `return {...}` paths now return `{ kind: "return"; result }`, and the success
+// path returns `{ kind: "ok"; ... }` carrying the live locals the loop needs
+// (subagent result, finishPhaseNode closure, observer, phaseStart, writeDebug,
+// the captured tool_execution_end events, and the debug-log handle/flags so the
+// post-triage bugId-capture block can re-initialize the log under the real ID).
+//
+// IL10 — ALL LLM dispatch goes through runForgeSubagent (NO sendKickoff here).
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { CallerContextStore } from "../../audience-gate.js";
+import { resolveModelForPhase } from "../../config/model-resolver.js";
+import { loadForgePersona, runForgeSubagent } from "../../forge-subagent.js";
+import { getSubagentTools } from "../../forge-tools.js";
+import { getOrchestratorTree } from "../../orchestrator-tree.js";
+import { attachViewportObserver } from "../../viewport/events.js";
+import { buildSummariesBlock, emitIncompletePhaseEvent } from "../run-task.js";
+import { composeBugBody } from "./bug-body.js";
+import { writeBugState } from "./bug-state.js";
+const STATUS_KEY = "forge:fix-bug";
+/**
+ * Run a single bug phase's subagent dispatch and classify the immediate outcome
+ * (persona-load failure, subagent throw, cancellation, or non-zero exit) into a
+ * discriminated result. On success returns `kind: "ok"` with the live locals the
+ * caller's loop needs for bugId capture / verdict / advance handling.
+ */
+export async function dispatchBugPhase(p) {
+    const { opts, phase, bugId, cwd, ctx, storeCli, currentPhaseIndex, iterationCounts, dispatchCounts, modelRoutingConfig, registry, isNewBug, originalArg, subWorkflowMd, bugRecordBefore, bugStatusBeforePhase, pendingBugId, } = p;
+    const tree = getOrchestratorTree();
+    // ── 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 {
+            kind: "return",
+            result: {
+                status: "failed",
+                lastPhaseIndex: currentPhaseIndex,
+                iterationCounts,
+                lastError: `persona load failed: ${e.message ?? "unknown"}`,
+            },
+        };
+    }
+    // ── 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 {
+            kind: "return",
+            result: {
+                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 {
+            kind: "return",
+            result: { 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 {
+            kind: "return",
+            result: {
+                status: "failed",
+                lastPhaseIndex: currentPhaseIndex,
+                iterationCounts,
+                lastError: result.errorMessage ?? result.stopReason ?? "subagent exit non-zero",
+            },
+        };
+    }
+    return {
+        kind: "ok",
+        result,
+        finishPhaseNode,
+        observer,
+        phaseStart,
+        writeDebug,
+        toolExecutionEvents,
+        debugLogPath,
+        debugLogDisabled,
+    };
+}
+//# sourceMappingURL=bug-phase-dispatch.js.map