@entelligentsia/forgecli 1.0.20 → 1.0.25

package/dist/extensions/forgecli/{fix-bug.js → orchestrators/fix-bug.js}

@@ -33,35 +33,37 @@
 //     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: lib/orchestrator-preflight.ts (N-H-H, FORGE-S25-T17).
+//   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";
+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-layer.js";
-import { loadForgePersona, runForgeSubagent } from "./forge-subagent.js";
-import { getSubagentTools } from "./forge-tools.js";
-import { readPersonaDir as readPersonaDirBug, readPipelineNames as readPipelineNamesBug, } from "./lib/catalog-helpers.js";
-import { discoverForgeConfigCached } from "./lib/forge-config.js";
-import { resolveAdvisorModel, runHaltAdvisor } from "./lib/halt-advisor.js";
-import { checkMaterialization } from "./lib/manifest-checker.js";
-import { runOrchestratorPreflight } from "./lib/orchestrator-preflight.js";
-import { resolveModelForPhase } from "./model-resolver.js";
-import { loadWorkflow } from "./parsers/workflow-loader.js";
-import { buildPhaseEvent, buildSummariesBlock, drainFrictionFile, emitEvent, emitIncompletePhaseEvent, findPredecessorIndex, formatLocalTime, isNonInteractive, judgementFromSummary, runPreflightGateWithData, validateId, } from "./run-task.js";
-import { getSessionRegistry } from "./session-registry.js";
-import { getOrchestratorTree } from "./orchestrator-tree.js";
-import { OrchestratorTranscriptWriter } from "./subagent/orchestrator-transcript.js";
-import { resolveToCanonicalId, resolveToolDir } from "./store-resolver.js";
-import { attachViewportObserver } from "./viewport-events.js";
-import { fmtPhaseSummary } from "./viewport-renderer.js";
+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.
@@ -89,8 +91,8 @@ export const BUG_PHASES = [
 // subagent/phase-summary-map.ts so the new phase-guard.ts can import
 // it without dragging fix-bug.ts into a forge-tools import cycle.
 // Re-exported here for backwards-compatibility with existing call sites.
-export { BUG_SUMMARY_KEY_BY_ROLE } from "./subagent/phase-summary-map.js";
-import { BUG_SUMMARY_KEY_BY_ROLE } from "./subagent/phase-summary-map.js";
+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.
@@ -108,6 +110,21 @@ export const BUG_TYPE_TOKENS = {
 // `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"]);
+// Post-triage status transitions the ORCHESTRATOR owns (meta-fix-bug.md
+// step 2: "On return, orchestrator transitions status: triaged then
+// in-progress" — a required two-step state-machine contract; the FSM
+// forbids the one-step reported → in-progress jump). First live firing of
+// commit-task.cjs exposed this as unimplemented: bugs reached the commit
+// phase still 'reported' and the terminal-status guard fired every run.
+// Returns the ordered list of statuses to write from the given status —
+// idempotent on resume (already in-progress / terminal → no-op).
+export function postTriageTransitions(status) {
+    if (status === "reported")
+        return ["triaged", "in-progress"];
+    if (status === "triaged")
+        return ["in-progress"];
+    return [];
+}
 function bugStateFilePath(cwd, bugId, sessionId) {
     if (!validateId(bugId)) {
         throw new Error(`Invalid bugId for state file path: ${bugId}`);
@@ -213,31 +230,51 @@ export function readBugRecord(bugId, storeCli, cwd) {
         return null;
     }
 }
-// Pre-assigns a real FORGE-BUG-NNN ID by listing existing bugs and incrementing.
-// Returns the next ID in sequence, e.g. "FORGE-BUG-003" if bugs 001 and 002 exist.
-export function assignNextBugId(storeCli, cwd) {
-    const result = spawnSync("node", [storeCli, "list", "bug", "--json"], { cwd, encoding: "utf8" });
+// 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)) {
-                for (const b of bugs) {
-                    const m = String(b.bugId ?? "").match(/FORGE-BUG-(\d+)/);
-                    if (m) {
-                        const n = parseInt(m[1], 10);
-                        if (n > maxNum)
-                            maxNum = n;
-                    }
-                }
+                bugIds = bugs.map((b) => String(b.bugId ?? ""));
             }
         }
         catch {
             /* empty store — start from 1 */
         }
     }
-    const next = maxNum + 1;
-    return `FORGE-BUG-${String(next).padStart(3, "0")}`;
+    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) {
@@ -374,7 +411,12 @@ const BUG_WRITE_TOOL_NAMES = new Set(["write", "store-cli", "bash", "forge_store
  * "store-cli"). In Claude Code runtime, subagents may shell out via Bash.
  * This function covers all three paths.
  */
-export function extractBugIdFromEvents(events) {
+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)
@@ -383,13 +425,13 @@ export function extractBugIdFromEvents(events) {
         if (event.toolName === "store-cli") {
             const result = event.result;
             if (typeof result === "string") {
-                const match = result.match(/FORGE-BUG-\d+/);
+                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("FORGE-BUG-")) {
+                if (typeof obj.bugId === "string" && obj.bugId.startsWith(idPrefix)) {
                     lastBugId = obj.bugId;
                 }
             }
@@ -398,13 +440,13 @@ export function extractBugIdFromEvents(events) {
         // 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(/FORGE-BUG-\d+/);
+            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(/(FORGE-BUG-\d+)/);
+            const match = event.result.match(idPattern);
             if (match)
                 lastBugId = match[0];
         }
@@ -415,7 +457,7 @@ export function extractBugIdFromEvents(events) {
         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(/FORGE-BUG-\d+/);
+                const match = output.match(idPattern);
                 if (match)
                     lastBugId = match[0];
             }
@@ -426,6 +468,22 @@ export function extractBugIdFromEvents(events) {
 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
@@ -435,6 +493,14 @@ export async function runBugPipeline(opts) {
     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) ─────────────────────────────────
@@ -457,9 +523,9 @@ export async function runBugPipeline(opts) {
         };
     }
     // Pre-flight validation — same shape as run-task / run-sprint.
-    // FORGE-S25-T17: delegated to lib/orchestrator-preflight.ts (H-13).
+    // 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 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);
@@ -491,6 +557,7 @@ export async function runBugPipeline(opts) {
         entityKind: "bug",
         entityId: bugId,
     });
+    onOrchestratorTranscript(orchTranscript);
     const __origNotify = ctx.ui.notify.bind(ctx.ui);
     ctx.ui.notify = ((msg, level) => {
         __origNotify(msg, level);
@@ -762,9 +829,7 @@ export async function runBugPipeline(opts) {
             // ── 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;
+            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.
@@ -811,14 +876,18 @@ export async function runBugPipeline(opts) {
             }
             writeDebug({ kind: "phase_start", phaseIndex: currentPhaseIndex });
             registry.startPhase(bugId, phase.role, currentPhaseIndex);
-            // Bridge: register phase in OrchestratorTree
-            const iteration = (iterationCounts[phase.role] ?? 0) + 1;
+            // 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",
-                promptPreview: bugBody.slice(0, 200),
+                // 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")
@@ -831,6 +900,7 @@ export async function runBugPipeline(opts) {
                 registry,
                 sessionId: bugId,
                 phaseRole: phase.role,
+                nodeId: phaseNodeId,
                 beginHeader: `─── phase ${phase.role} begin ───`,
                 writeDebug,
                 notify: (msg, level) => ctx.ui.notify(msg, level),
@@ -881,6 +951,7 @@ export async function runBugPipeline(opts) {
                     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
@@ -898,6 +969,7 @@ export async function runBugPipeline(opts) {
             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,
@@ -913,6 +985,21 @@ export async function runBugPipeline(opts) {
                     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");
@@ -964,6 +1051,7 @@ export async function runBugPipeline(opts) {
                 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: {
@@ -1014,7 +1102,7 @@ export async function runBugPipeline(opts) {
             // 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);
+                const capturedBugId = extractBugIdFromEvents(toolExecutionEvents, loadGovernorProjectConfig(cwd).prefix);
                 if (capturedBugId) {
                     ctx.ui.notify(`forge:fix-bug — captured bug ID: ${capturedBugId}`, "info");
                     bugId = capturedBugId;
@@ -1098,6 +1186,7 @@ export async function runBugPipeline(opts) {
                     turns: turn,
                     toolCount,
                     errCount,
+                    subagentTranscriptPath: result.subagentTranscriptPath,
                 });
                 registry.appendTail(bugId, phase.role, fmtPhaseSummary({
                     role: phase.role,
@@ -1191,6 +1280,7 @@ export async function runBugPipeline(opts) {
                 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,
@@ -1234,6 +1324,7 @@ export async function runBugPipeline(opts) {
                     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,
@@ -1261,6 +1352,11 @@ export async function runBugPipeline(opts) {
                             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");
@@ -1287,10 +1383,7 @@ export async function runBugPipeline(opts) {
             }
             // ── Advance to next phase ─────────────────────────────────────
             registry.completePhase(bugId, phase.role, "completed");
-            tree.completeNode(phaseNodeId, "completed");
-            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 ?? "");
+            finishPhaseNode("completed");
             writeBugState(cwd, {
                 bugId,
                 phaseIndex: currentPhaseIndex,
@@ -1313,6 +1406,17 @@ export async function runBugPipeline(opts) {
             // bug status proves the work happened.
             if (phase.role === "triage") {
                 const bugAfterTriage = readBugRecord(bugId, storeCli, cwd);
+                // Orchestrator-owned post-triage transitions (meta-fix-bug.md
+                // step 2). Two sequential writes through store-cli (the FSM
+                // authority); failure warns but does not halt — the commit
+                // phase's status guard is the backstop.
+                for (const target of postTriageTransitions(bugAfterTriage?.status)) {
+                    const upd = spawnSync("node", [storeCli, "update-status", "bug", bugId, "status", target], { cwd, encoding: "utf8" });
+                    if (upd.status !== 0) {
+                        ctx.ui.notify(`⚠ forge:fix-bug — post-triage transition to '${target}' failed: ${(upd.stderr ?? "").toString().trim()}`, "warning");
+                        break;
+                    }
+                }
                 const triageSummary = bugAfterTriage?.summaries?.triage;
                 const route = triageSummary?.route;
                 if (route === "A") {
@@ -1369,6 +1473,11 @@ export function registerFixBug(pi, options = {}) {
                 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");
@@ -1378,8 +1487,10 @@ export function registerFixBug(pi, options = {}) {
             // 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 (/^FORGE-BUG-\d+$/.test(rawArg)) {
-                // Canonical bug ID — verify it exists
+            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) {
@@ -1423,10 +1534,42 @@ export function registerFixBug(pi, options = {}) {
                 }
             }
             else {
-                // Free-form text — defer bug creation to triage-phase subagent
-                // Use a temporary bugId placeholder; will be captured from subagent events
-                bugId = `PENDING-${Date.now()}`;
-                isNewBug = true;
+                // @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()) {
@@ -1526,7 +1669,7 @@ export function registerFixBug(pi, options = {}) {
             // 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);
+                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");
@@ -1572,6 +1715,14 @@ export function registerFixBug(pi, options = {}) {
                 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);
         },