@entelligentsia/forgecli 1.0.14 → 1.0.21

package/dist/extensions/forgecli/orchestrators/run-sprint.js

@@ -0,0 +1,734 @@
+// run-sprint.ts — /forge:run-sprint native Orchestrator handler (FORGE-S21-T03, Plan 12).
+//
+// Sprint-level orchestrator that iterates over a sprint's task list,
+// delegating per-task execution to runTaskPipeline (extracted from run-task.ts).
+//
+// The sprint handler does NOT contain its own phase loop; per-phase concerns
+// are ALL delegated to runTaskPipeline. The sprint handler owns sprint
+// coordination only: resolve sprint, confirm gates, iterate tasks, persist
+// sprint state, dispatch architect ceremony, and emit sprint-scoped events.
+//
+// Plan 12 truth table (§3):
+//   Clean-complete   → architect ceremony (mode=complete) → sprint-complete event
+//   User-paused      → architect ceremony (mode=partial) if ≥1 task done → sprint-complete event (verdict=partial)
+//   Halted-on-failure → NO ceremony → sprint-halted event
+//
+// Iron Laws enforced here:
+//   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)
+//
+// sendKickoff is NEVER called from this file.
+// Audit-grep: grep -n "sendKickoff(" run-sprint.ts must return empty.
+//
+// N-H-D — Ceremony vs per-task model routing:
+//   The sprint ceremony phase (architect summary / sprint-complete event) uses
+//   loadLayeredConfig + lookupPersonaModel directly (~lines 216, 227) without
+//   calling validateModelConfig. This is intentional: the ceremony is a single
+//   LLM call with a known model and the overhead of full preflight validation
+//   is not warranted here.
+//   Per-task dispatch is entirely delegated to runTaskPipeline, which calls
+//   runOrchestratorPreflight (persona/model config validation) at entry before
+//   any LLM dispatch. The two paths are deliberately separate.
+//   Reference: orchestrator-preflight.ts (N-H-D, FORGE-S25-T17).
+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 } from "../audience-gate.js";
+import { loadLayeredConfig } from "../config/config-layer.js";
+import { loadForgePersona, runForgeSubagent } from "../forge-subagent.js";
+import { getSubagentTools } from "../forge-tools.js";
+import { emitSyntheticEvent } from "../hook-dispatcher.js";
+import { readPersonaDir as readPersonaDirSprint, readPipelineNames as readPipelineNamesSprint, } from "../lib/catalog-helpers.js";
+import { discoverForgeConfigCached } from "../lib/forge-config.js";
+import { archiveRun, sweepProjectTranscripts } from "../transcript-archive.js";
+import { checkMaterialization } from "../lib/manifest-checker.js";
+import { readJsonState, sprintStateFilePath, writeJsonState } from "../lib/state-helpers.js";
+import { lookupPersonaModel } from "../config/model-resolver.js";
+import { validateModelConfig } from "../config/model-validator.js";
+import { loadWorkflow } from "../parsers/workflow-loader.js";
+import { getSessionRegistry } from "../session-registry.js";
+import { getOrchestratorTree } from "../orchestrator-tree.js";
+import { resolveToCanonicalId, resolveToolDir } from "../store/store-resolver.js";
+import { attachViewportObserver } from "../viewport/events.js";
+import { emitEvent, formatLocalTime, isNonInteractive, isoCompact, isStateStale, readState as readTaskState, runTaskPipeline, validateId, } from "./run-task.js";
+// FORGE-S25-T16 (N-H-B): sprint state helpers delegate to lib/state-helpers.ts.
+function getSprintStatePath(cwd, sprintId) {
+    if (!validateId(sprintId)) {
+        throw new Error(`Invalid sprintId for state file path: ${sprintId}`);
+    }
+    return sprintStateFilePath(cwd, sprintId);
+}
+function readSprintState(cwd, sprintId) {
+    return readJsonState(getSprintStatePath(cwd, sprintId));
+}
+function writeSprintState(cwd, state) {
+    writeJsonState(getSprintStatePath(cwd, state.sprintId), state);
+}
+function deleteSprintState(cwd, sprintId) {
+    const fp = getSprintStatePath(cwd, sprintId);
+    try {
+        if (fs.existsSync(fp))
+            fs.unlinkSync(fp);
+    }
+    catch {
+        // non-fatal
+    }
+}
+function isSprintStateStale(state) {
+    const savedAt = new Date(state.savedAt).getTime();
+    const ageMs = Date.now() - savedAt;
+    const sevenDaysMs = 7 * 24 * 60 * 60 * 1000;
+    return ageMs > sevenDaysMs;
+}
+function readSprintRecord(sprintId, storeCli, cwd) {
+    const result = spawnSync("node", [storeCli, "read", "sprint", sprintId], { cwd, encoding: "utf8" });
+    if (result.status !== 0)
+        return null;
+    try {
+        const raw = typeof result.stdout === "string" ? result.stdout : String(result.stdout);
+        const record = JSON.parse(raw);
+        // Validate taskIds is a non-empty array of strings
+        if (!Array.isArray(record.taskIds) || record.taskIds.length === 0)
+            return null;
+        if (!record.taskIds.every((id) => typeof id === "string"))
+            return null;
+        return record;
+    }
+    catch {
+        return null;
+    }
+}
+async function dispatchSprintCeremony(params) {
+    const { sprintId, mode, completedTaskIds, pausedAfterIndex, cwd, forgeRoot, ctx, registry, streamFnFactory, forgeToolDefs, } = params;
+    const startMs = Date.now();
+    // Materialized workflow path — already shipped from base pack.
+    const workflowName = "architect_review_sprint_completion";
+    const personaName = "architect";
+    let persona;
+    try {
+        persona = loadForgePersona(personaName, cwd);
+    }
+    catch {
+        return {
+            verdict: "revision-required",
+            durationMs: Date.now() - startMs,
+            errorMessage: `architect persona not found`,
+        };
+    }
+    const taskLines = [
+        `# Sprint Completion Review — ${sprintId}`,
+        ``,
+        `Mode: ${mode}`,
+        `Completed tasks: ${completedTaskIds.join(", ") || "(none)"}`,
+    ];
+    if (pausedAfterIndex !== undefined) {
+        taskLines.push(`Paused after task index: ${pausedAfterIndex}`);
+    }
+    taskLines.push(``, `Execute the materialized workflow at \`.forge/workflows/${workflowName}.md\`.`, `Do not emit any phase event yourself; the orchestrator owns event emission.`);
+    const task = taskLines.join("\n");
+    // Use a dedicated session id (NOT a taskId) so the thread-switcher renders it
+    // as a sprint-scoped chip distinct from per-task sessions.
+    const sessionId = `${sprintId}:ceremony`;
+    registry.startSession(sessionId);
+    registry.startPhase(sessionId, "ceremony", 0);
+    // Bridge: register ceremony phase in OrchestratorTree so the dashboard
+    // shows the ceremony as a leaf under the sprint root.
+    const tree = getOrchestratorTree();
+    tree.startNode(sessionId, { parentId: sprintId, label: "ceremony", kind: "leaf" });
+    let model;
+    let provider;
+    let errorMessage;
+    const observer = attachViewportObserver({
+        registry,
+        sessionId,
+        phaseRole: "ceremony",
+        displayRole: "ceremony",
+        beginHeader: `─── sprint ${sprintId} ceremony begin · ${personaName} ───`,
+    });
+    // Resolve model routing for the ceremony's architect persona (Plan 16 Slice 2).
+    // N-B-E: surface schema errors to caller (Decision 9 — orchestrators fail-fast).
+    // See doc/decisions/layered-config-error-policy.md.
+    const { merged: ceremonyModelConfig, errors: ceremonyCfgErrors } = loadLayeredConfig(cwd);
+    if (ceremonyCfgErrors.length > 0) {
+        for (const e of ceremonyCfgErrors) {
+            ctx.ui.notify(`× forge:run-sprint ceremony — forge-cli config schema error: ${e}`, "error");
+        }
+        return {
+            verdict: "revision-required",
+            durationMs: Date.now() - startMs,
+            errorMessage: `forge-cli config schema errors: ${ceremonyCfgErrors.join("; ")}`,
+        };
+    }
+    const ceremonyModelLookup = lookupPersonaModel(personaName, "default", ceremonyModelConfig);
+    try {
+        const result = await runForgeSubagent({
+            persona,
+            task,
+            cwd,
+            exportTag: `${sprintId}__ceremony`,
+            tailLog: observer.state.tailLog,
+            forgeRoot,
+            streamFn: streamFnFactory?.({ kind: "ceremony", persona: personaName }),
+            // Sprint-scoped prompt-cache key — every subagent spawned across
+            // the sprint (ceremonies + per-task phases) shares this namespace
+            // so the system-prompt + persona prefix stays warm.
+            cacheSessionId: `forge:${sprintId}`,
+            onEvent: observer.onEvent,
+            requestedModel: ceremonyModelLookup.model,
+            modelRegistry: ctx.modelRegistry,
+            customTools: forgeToolDefs ? getSubagentTools(forgeToolDefs, persona.name) : undefined,
+        });
+        model = result.model;
+        provider = result.provider;
+        if (result.exitCode !== 0) {
+            errorMessage = result.errorMessage ?? "architect subagent exited non-zero";
+        }
+    }
+    catch (e) {
+        const err = e;
+        errorMessage = err?.message ?? "runForgeSubagent threw";
+    }
+    finally {
+        registry.completeSession(sessionId, errorMessage ? "failed" : "completed");
+        tree.completeNode(sessionId, errorMessage ? "failed" : "completed");
+    }
+    // Parse verdict from store: did the architect actually transition the sprint?
+    // The store is the source of truth — verdict text in SPRINT_COMPLETION_REVIEW.md
+    // is human-readable but the store status is authoritative.
+    let verdict = "revision-required";
+    const readResult = spawnSync("node", [`${forgeRoot}/tools/store-cli.cjs`, "read", "sprint", sprintId], {
+        cwd,
+        encoding: "utf8",
+    });
+    if (readResult.status === 0) {
+        try {
+            const sprint = JSON.parse(readResult.stdout);
+            if (sprint.status === "completed")
+                verdict = "complete";
+            else if (sprint.status === "partially-completed")
+                verdict = "partial";
+            // else: status unchanged → revision-required
+        }
+        catch {
+            // fall through with revision-required
+        }
+    }
+    return {
+        verdict,
+        model,
+        provider,
+        durationMs: Date.now() - startMs,
+        errorMessage,
+    };
+}
+const SPRINT_STATUS_KEY = "forge:run-sprint";
+export function registerRunSprint(pi, options = {}) {
+    pi.registerCommand("forge:run-sprint", {
+        description: "Run all tasks in a sprint sequentially. " +
+            "Usage: /forge:run-sprint <SPRINT_ID>. " +
+            "Orchestrator archetype: delegates per-task execution to runTaskPipeline.",
+        async handler(args, ctx) {
+            const cwd = options.cwd ?? process.cwd();
+            let sprintId = args.trim();
+            if (!sprintId) {
+                ctx.ui.notify("× forge:run-sprint — sprint ID required. Usage: /forge:run-sprint <SPRINT_ID>", "error");
+                return;
+            }
+            // Path traversal validation (advisory #3)
+            if (!validateId(sprintId)) {
+                ctx.ui.notify(`× forge:run-sprint — invalid sprint ID format: ${sprintId}`, "error");
+                return;
+            }
+            ctx.ui.setStatus?.(SPRINT_STATUS_KEY, `run-sprint ${sprintId}: initializing…`);
+            // ── Discover forge config ────────────────────────────────────────
+            const forgeConfig = discoverForgeConfigCached(cwd);
+            if (!forgeConfig) {
+                ctx.ui.notify("× forge:run-sprint — no Forge project found at cwd. Run /forge:init first.", "error");
+                ctx.ui.setStatus?.(SPRINT_STATUS_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 any task pipeline creates its transcript
+            // writer, so in-flight runs are never swept half-written.
+            sweepProjectTranscripts(cwd);
+            // ── Resolve sprint ID (prefix-normalize, suffix-match, NLP fallback) ──
+            // Handles unprefixed IDs like "S22" → "FORGE-S22".
+            // Issue #20: unprefixed entity IDs silently poisoned substitutions.
+            const toolDir = resolveToolDir(forgeRoot);
+            const resolvedSprintId = await resolveToCanonicalId(sprintId, toolDir, cwd, "sprint", {
+                ctx,
+                commandLabel: "forge:run-sprint",
+            });
+            if (!resolvedSprintId) {
+                // Error already emitted by resolver
+                ctx.ui.setStatus?.(SPRINT_STATUS_KEY, undefined);
+                return;
+            }
+            // Replace raw arg with canonical ID for all subsequent operations.
+            sprintId = resolvedSprintId;
+            // Update status with canonical ID so the user sees the resolved form.
+            ctx.ui.setStatus?.(SPRINT_STATUS_KEY, `run-sprint ${sprintId}: ready`);
+            const storeCli = path.join(forgeRoot, "tools", "store-cli.cjs");
+            const preflightGate = path.join(forgeRoot, "tools", "preflight-gate.cjs");
+            // ── Sprint resolution ────────────────────────────────────────────
+            const sprintRecord = readSprintRecord(sprintId, storeCli, cwd);
+            if (!sprintRecord) {
+                ctx.ui.notify(`× forge:run-sprint — could not read sprint ${sprintId} or sprint has no task IDs.`, "error");
+                ctx.ui.setStatus?.(SPRINT_STATUS_KEY, undefined);
+                return;
+            }
+            const taskIds = sprintRecord.taskIds;
+            ctx.ui.notify(`▶ forge:run-sprint — sprint ${sprintId}: ${taskIds.length} tasks`, "info");
+            // ── Audience check (AC B-12) ──────────────────────────────────────
+            // Read the run_sprint workflow for audience check.
+            const workflowPath = path.join(cwd, ".forge", "workflows", "run_sprint.md");
+            let workflowMd;
+            let workflowAudience = "any";
+            try {
+                const loaded = loadWorkflow(workflowPath);
+                workflowMd = loaded.rawMarkdown;
+                workflowAudience = loaded.audience;
+            }
+            catch {
+                // Workflow file may not exist — default to orchestrator-only since
+                // /forge:run-sprint is an orchestrator archetype command.
+                workflowMd = "";
+                workflowAudience = "orchestrator-only";
+            }
+            if (!assertAudience({ workflowName: "run_sprint", audience: workflowAudience }, ctx)) {
+                ctx.ui.setStatus?.(SPRINT_STATUS_KEY, undefined);
+                return;
+            }
+            // ── Materialization-marker check (AC B-5) ────────────────────────
+            if (workflowMd) {
+                const markerCheck = checkMaterialization(workflowPath, workflowMd);
+                if (!markerCheck.ok) {
+                    for (const marker of markerCheck.missing) {
+                        ctx.ui.notify(`× workflow regression: ${marker} not found in ${workflowPath}`, "error");
+                    }
+                    ctx.ui.setStatus?.(SPRINT_STATUS_KEY, undefined);
+                    return;
+                }
+            }
+            // ── Pre-flight confirm (AC B-7) ───────────────────────────────────
+            if (!isNonInteractive()) {
+                const proceed = await ctx.ui.confirm(`Begin sprint ${sprintId}?`, `Tasks: ${taskIds.join(", ")}`);
+                if (!proceed) {
+                    ctx.ui.notify("forge:run-sprint — sprint aborted.", "info");
+                    ctx.ui.setStatus?.(SPRINT_STATUS_KEY, undefined);
+                    return;
+                }
+            }
+            // ── Sprint-level resume detection (AC B-11) ──────────────────────
+            const existingSprintState = readSprintState(cwd, sprintId);
+            let startTaskIndex = 0;
+            let completedTaskIds = [];
+            const resumeTaskStates = new Map();
+            if (existingSprintState) {
+                if (isSprintStateStale(existingSprintState)) {
+                    ctx.ui.notify(`⚠ forge:run-sprint — cached sprint state for ${sprintId} is stale (>7 days old, saved at ${formatLocalTime(existingSprintState.savedAt)}). Offering purge.`, "warning");
+                    if (!isNonInteractive()) {
+                        const purge = await ctx.ui.confirm(`Purge stale sprint state for ${sprintId}?`, "The cached state is older than 7 days. Purge and restart from the beginning?");
+                        if (purge) {
+                            deleteSprintState(cwd, sprintId);
+                        }
+                        else {
+                            ctx.ui.notify("forge:run-sprint — stale state kept; aborting.", "info");
+                            ctx.ui.setStatus?.(SPRINT_STATUS_KEY, undefined);
+                            return;
+                        }
+                    }
+                    else {
+                        // Non-interactive: auto-abort on stale state (advisory #9)
+                        ctx.ui.notify("forge:run-sprint — stale sprint state; non-interactive mode auto-aborting.", "info");
+                        ctx.ui.setStatus?.(SPRINT_STATUS_KEY, undefined);
+                        return;
+                    }
+                }
+                else {
+                    // Fresh state: offer resume
+                    if (!isNonInteractive()) {
+                        const resume = await ctx.ui.confirm(`Resume sprint ${sprintId}?`, `Cached state found at task ${existingSprintState.taskIndex} (${existingSprintState.completedTaskIds.length} completed). Resume from here?`);
+                        if (resume) {
+                            startTaskIndex = existingSprintState.taskIndex;
+                            completedTaskIds = existingSprintState.completedTaskIds;
+                            ctx.ui.notify(`forge:run-sprint — resuming ${sprintId} from task ${taskIds[startTaskIndex] ?? startTaskIndex}`, "info");
+                            // Collect halted and cancelled task states for mid-task resume
+                            // (REVIEW FIX #2, option b; ADR-S21-01: cancelled states are
+                            // resumable from the beginning of the cancelled phase).
+                            for (const taskId of taskIds.slice(startTaskIndex)) {
+                                const taskState = readTaskState(cwd, taskId);
+                                if (taskState && (taskState.halted || taskState.status === "cancelled")) {
+                                    resumeTaskStates.set(taskId, taskState);
+                                }
+                            }
+                        }
+                        else {
+                            deleteSprintState(cwd, sprintId);
+                        }
+                    }
+                    else {
+                        // Non-interactive + existing state: auto-abort (advisory #9)
+                        ctx.ui.notify(`forge:run-sprint — cached sprint state for ${sprintId} found but non-interactive mode; aborting.`, "info");
+                        ctx.ui.setStatus?.(SPRINT_STATUS_KEY, undefined);
+                        return;
+                    }
+                }
+            }
+            // ── Model routing pre-flight (Plan 16 Slice 3) ──────────────────────
+            // Validate routing config once at sprint start (before any LLM calls).
+            // N-B-E: surface schema errors first (Decision 9 — orchestrators fail-fast).
+            // See doc/decisions/layered-config-error-policy.md.
+            {
+                const { merged: modelRoutingConfig, errors: schemaErrors } = loadLayeredConfig(cwd);
+                if (schemaErrors.length > 0) {
+                    for (const e of schemaErrors) {
+                        ctx.ui.notify(`× forge:run-sprint — forge-cli config schema error: ${e}`, "error");
+                    }
+                    ctx.ui.setStatus?.(SPRINT_STATUS_KEY, undefined);
+                    return;
+                }
+                const personasDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "forge-payload", ".base-pack", "personas");
+                const personaCatalogue = readPersonaDirSprint(personasDir);
+                const forgeCfgPath = path.join(cwd, ".forge", "config.json");
+                const pipelineCatalogue = readPipelineNamesSprint(forgeCfgPath);
+                const availableModels = ctx.modelRegistry?.getAvailable?.() ?? [];
+                const strict = process.env.FORGE_STRICT_MODELS === "1";
+                const { errors, warnings } = validateModelConfig(personaCatalogue, pipelineCatalogue, modelRoutingConfig, availableModels.map((m) => ({ provider: m.provider, id: m.id })), strict);
+                for (const w of warnings) {
+                    ctx.ui.notify(`⚠ forge:run-sprint — model routing: ${w.message}`, "warning");
+                }
+                if (errors.length > 0) {
+                    for (const e of errors) {
+                        ctx.ui.notify(`× forge:run-sprint — model routing: ${e.message}`, "error");
+                    }
+                    ctx.ui.setStatus?.(SPRINT_STATUS_KEY, undefined);
+                    return;
+                }
+            }
+            // ── Per-task loop (AC B-8) ────────────────────────────────────────
+            const registry = getSessionRegistry();
+            const tree = getOrchestratorTree();
+            let lastModel;
+            let lastProvider;
+            const sprintStartMs = Date.now();
+            // Bridge: register sprint root in OrchestratorTree.
+            tree.startNode(sprintId, { label: `wfl:run-sprint`, kind: "orchestrator" });
+            for (let i = startTaskIndex; i < taskIds.length; i++) {
+                const taskId = taskIds[i];
+                if (!taskId)
+                    continue;
+                // ── Skip already-completed tasks ──────────────────────────────
+                // If the task is already committed/approved in the store, skip the
+                // phase pipeline and accumulate it as completed. This handles
+                // re-runs where tasks finished in a prior attempt.
+                {
+                    const taskReadResult = spawnSync("node", [`${forgeRoot}/tools/store-cli.cjs`, "read", "task", taskId], {
+                        cwd,
+                        encoding: "utf8",
+                    });
+                    if (taskReadResult.status === 0) {
+                        try {
+                            const taskRecord = JSON.parse(taskReadResult.stdout);
+                            if (taskRecord.status === "committed" || taskRecord.status === "completed") {
+                                ctx.ui.notify(`▶ ${sprintId}: task ${i + 1}/${taskIds.length} — ${taskId} already ${taskRecord.status}, skipping.`, "info");
+                                completedTaskIds.push(taskId);
+                                lastModel = taskRecord.model ?? lastModel;
+                                lastProvider = taskRecord.provider ?? lastProvider;
+                                writeSprintState(cwd, {
+                                    sprintId,
+                                    taskIndex: i + 1,
+                                    completedTaskIds,
+                                    halted: false,
+                                    savedAt: new Date().toISOString(),
+                                });
+                                continue;
+                            }
+                        }
+                        catch {
+                            // Malformed task record — fall through to runTaskPipeline
+                        }
+                    }
+                }
+                ctx.ui.setStatus?.(SPRINT_STATUS_KEY, `run-sprint ${sprintId}: task ${i + 1}/${taskIds.length} (${taskId})`);
+                ctx.ui.notify(`▶ ${sprintId}: task ${i + 1}/${taskIds.length} — ${taskId}`, "info");
+                // Determine resumeFromState for mid-task resume (REVIEW FIX #2).
+                // If a halted or cancelled task state exists for this task,
+                // pass it to runTaskPipeline so it resumes from the saved phase.
+                let resumeFromState = resumeTaskStates.get(taskId);
+                if (resumeFromState) {
+                    // Validate the state is not corrupt
+                    if (typeof resumeFromState.phaseIndex !== "number" ||
+                        typeof resumeFromState.iterationCounts !== "object") {
+                        ctx.ui.notify(`⚠ forge:run-sprint — corrupt task state for ${taskId}; starting fresh.`, "warning");
+                        resumeFromState = undefined;
+                    }
+                }
+                if (resumeFromState) {
+                    const resumephaseRole = resumeFromState.phaseIndex;
+                    const resumeStatus = resumeFromState.status ?? (resumeFromState.halted ? "halted" : "interrupted");
+                    ctx.ui.notify(`▶ forge:run-sprint — resuming ${taskId} from phase ${resumephaseRole} (${resumeStatus})`, "info");
+                }
+                // Stale task state fallback: if task state >7d, delete and start fresh
+                if (resumeFromState && isStateStale(resumeFromState)) {
+                    ctx.ui.notify(`⚠ forge:run-sprint — stale task state for ${taskId} (>7d); starting fresh.`, "warning");
+                    resumeFromState = undefined;
+                }
+                // ── Session lifecycle for thread-switcher (REVIEW FIX #2) ──────
+                registry.startSession(taskId);
+                // Bridge: register task in OrchestratorTree under sprint root.
+                tree.startNode(taskId, { parentId: sprintId, label: `▸ wfl:run-task`, kind: "orchestrator" });
+                const taskSignal = registry.getAbortSignal(taskId);
+                const taskResult = await runTaskPipeline({
+                    taskId,
+                    cwd,
+                    ctx,
+                    forgeRoot,
+                    storeCli,
+                    preflightGate,
+                    registry,
+                    resumeFromState,
+                    signal: taskSignal,
+                    forgeToolDefs: options.forgeToolDefs,
+                    extensionFactories: options.extensionFactories,
+                    streamFnFactory: options.streamFnFactory
+                        ? (c) => options.streamFnFactory?.({
+                            kind: "task-phase",
+                            persona: c.persona,
+                            phase: c.phase,
+                            taskId: c.taskId,
+                        })
+                        : undefined,
+                });
+                // Capture model/provider from last task result (REVIEW FIX #1)
+                if (taskResult.model)
+                    lastModel = taskResult.model;
+                if (taskResult.provider)
+                    lastProvider = taskResult.provider;
+                // Mirror the task run into the central transcript archive
+                // (best-effort — archiveRun never throws). The sprintId rides
+                // on the task manifest as a back-reference; a sprint surfaces
+                // as N task runs, no synthetic sprint container.
+                if (taskResult.orchestratorTranscriptPath) {
+                    archiveRun({
+                        cwd,
+                        orchestratorJsonlPath: taskResult.orchestratorTranscriptPath,
+                        sprintId,
+                    });
+                }
+                // ── Handle task result ──────────────────────────────────────
+                if (taskResult.status === "completed") {
+                    completedTaskIds.push(taskId);
+                    registry.completeSession(taskId, "completed");
+                    tree.completeNode(taskId, "completed");
+                }
+                else if (taskResult.status === "cancelled") {
+                    // Task was cancelled by user — mark session, persist sprint
+                    // state, emit sprint-halted with cancellation detail, exit.
+                    registry.completeSession(taskId, "cancelled");
+                    tree.completeNode(taskId, "cancelled");
+                    tree.completeNode(sprintId, "cancelled");
+                    const cancelledEvent = {
+                        eventId: `${isoCompact(sprintStartMs)}_${sprintId}_sprint_halted`,
+                        sprintId,
+                        role: "orchestrator",
+                        action: "sprint-halted",
+                        startTimestamp: new Date(sprintStartMs).toISOString(),
+                        endTimestamp: new Date(Date.now()).toISOString(),
+                        durationMinutes: Math.round(((Date.now() - sprintStartMs) / 60000) * 100) / 100,
+                        model: lastModel ?? "orchestrator",
+                        provider: lastProvider ?? "orchestrator",
+                        type: "sprint-halted",
+                        haltedAtTaskIndex: i,
+                        haltedAtTaskId: taskId,
+                        lastError: "cancelled",
+                    };
+                    emitEvent(storeCli, cwd, sprintId, cancelledEvent);
+                    writeSprintState(cwd, {
+                        sprintId,
+                        taskIndex: i,
+                        completedTaskIds,
+                        halted: true,
+                        lastError: "cancelled",
+                        savedAt: new Date().toISOString(),
+                    });
+                    ctx.ui.notify(`⊘ forge:run-sprint — ${sprintId} halted: task ${taskId} cancelled.`, "info");
+                    ctx.ui.setStatus?.(SPRINT_STATUS_KEY, undefined);
+                    return;
+                }
+                else {
+                    // Task halted/escalated/failed: mark session failed, persist sprint state, emit sprint-halted, exit.
+                    registry.completeSession(taskId, "failed");
+                    tree.completeNode(taskId, "failed");
+                    tree.completeNode(sprintId, "failed");
+                    const haltedEvent = {
+                        eventId: `${isoCompact(sprintStartMs)}_${sprintId}_sprint_halted`,
+                        sprintId,
+                        role: "orchestrator",
+                        action: "sprint-halted",
+                        startTimestamp: new Date(sprintStartMs).toISOString(),
+                        endTimestamp: new Date(Date.now()).toISOString(),
+                        durationMinutes: Math.round(((Date.now() - sprintStartMs) / 60000) * 100) / 100,
+                        model: lastModel ?? "orchestrator",
+                        provider: lastProvider ?? "orchestrator",
+                        type: "sprint-halted",
+                        haltedAtTaskIndex: i,
+                        haltedAtTaskId: taskId,
+                        lastError: taskResult.lastError ?? "unknown",
+                    };
+                    emitEvent(storeCli, cwd, sprintId, haltedEvent);
+                    writeSprintState(cwd, {
+                        sprintId,
+                        taskIndex: i,
+                        completedTaskIds,
+                        halted: true,
+                        lastError: taskResult.lastError,
+                        savedAt: new Date().toISOString(),
+                    });
+                    ctx.ui.setStatus?.(SPRINT_STATUS_KEY, undefined);
+                    return;
+                }
+                // ── Post-task confirm (AC B-9) ────────────────────────────
+                // Skip after final task
+                if (i < taskIds.length - 1 && !isNonInteractive()) {
+                    const proceed = await ctx.ui.confirm(`Continue to next task?`, `${taskIds[i + 1]} is next. ${taskIds.length - i - 1} task(s) remaining.`);
+                    if (!proceed) {
+                        // Persist sprint state for resume.
+                        writeSprintState(cwd, {
+                            sprintId,
+                            taskIndex: i + 1,
+                            completedTaskIds,
+                            halted: false,
+                            savedAt: new Date().toISOString(),
+                        });
+                        // User-paused branch: dispatch ceremony if ≥1 task completed, emit partial event.
+                        const pauseEndMs = Date.now();
+                        let ceremonyResult;
+                        if (completedTaskIds.length > 0) {
+                            // Only dispatch ceremony if at least one task completed.
+                            // A zero-progress pause has nothing to review.
+                            ceremonyResult = await dispatchSprintCeremony({
+                                sprintId,
+                                mode: "partial",
+                                completedTaskIds,
+                                pausedAfterIndex: i,
+                                cwd,
+                                forgeRoot,
+                                ctx,
+                                registry,
+                                streamFnFactory: options.streamFnFactory,
+                                forgeToolDefs: options.forgeToolDefs,
+                            });
+                        }
+                        const pausedEvent = {
+                            eventId: `${isoCompact(sprintStartMs)}_${sprintId}_sprint_complete`,
+                            sprintId,
+                            role: "architect",
+                            action: "sprint-complete",
+                            startTimestamp: new Date(sprintStartMs).toISOString(),
+                            endTimestamp: new Date(pauseEndMs).toISOString(),
+                            durationMinutes: Math.round(((pauseEndMs - sprintStartMs) / 60000) * 100) / 100,
+                            model: ceremonyResult?.model ?? lastModel ?? "orchestrator",
+                            provider: ceremonyResult?.provider ?? lastProvider ?? "orchestrator",
+                            type: "sprint-complete",
+                            taskCount: taskIds.length,
+                            completedTaskIds,
+                            verdict: "partial",
+                            pausedAfterTaskIndex: i,
+                            waveCount: 1,
+                            maxConcurrency: 1,
+                        };
+                        emitEvent(storeCli, cwd, sprintId, pausedEvent);
+                        tree.completeNode(sprintId, "completed");
+                        ctx.ui.notify("forge:run-sprint — sprint paused after task completion.", "info");
+                        ctx.ui.setStatus?.(SPRINT_STATUS_KEY, undefined);
+                        return;
+                    }
+                }
+                // Persist sprint state after each task transition (AC B-10)
+                writeSprintState(cwd, {
+                    sprintId,
+                    taskIndex: i + 1,
+                    completedTaskIds,
+                    halted: false,
+                    savedAt: new Date().toISOString(),
+                });
+            }
+            // ── All tasks complete — clean-complete branch (Plan 12 §3) ──────
+            const sprintEndMs = Date.now();
+            // Delete sprint state on successful completion
+            deleteSprintState(cwd, sprintId);
+            const ceremony = await dispatchSprintCeremony({
+                sprintId,
+                mode: "complete",
+                completedTaskIds,
+                cwd,
+                forgeRoot,
+                ctx,
+                registry,
+                streamFnFactory: options.streamFnFactory,
+                forgeToolDefs: options.forgeToolDefs,
+            });
+            const sprintEvent = {
+                eventId: `${isoCompact(sprintStartMs)}_${sprintId}_sprint_complete`,
+                sprintId,
+                role: "architect",
+                action: "sprint-complete",
+                startTimestamp: new Date(sprintStartMs).toISOString(),
+                endTimestamp: new Date(sprintEndMs).toISOString(),
+                durationMinutes: Math.round(((sprintEndMs - sprintStartMs) / 60000) * 100) / 100,
+                model: ceremony.model ?? lastModel ?? "orchestrator",
+                provider: ceremony.provider ?? lastProvider ?? "orchestrator",
+                type: "sprint-complete",
+                taskCount: taskIds.length,
+                completedTaskIds,
+                verdict: ceremony.verdict === "revision-required" ? "partial" : ceremony.verdict,
+                waveCount: 1,
+                maxConcurrency: 1,
+            };
+            const emitResult = emitEvent(storeCli, cwd, sprintId, sprintEvent);
+            if (!emitResult.ok) {
+                ctx.ui.notify(`⚠ forge:run-sprint — sprint-complete event emit failed: ${emitResult.stderr.trim()}`, "warning");
+            }
+            // ── Emit synthetic sprint-collate-complete event (FORGE-S21-T05) ──
+            // Fires the in-process hook for post-sprint-hook.ts to consume.
+            // Best-effort: failure-to-emit notifies but does NOT halt — sprint is
+            // already complete at this point.
+            try {
+                const collateEvent = {
+                    type: "sprint-collate-complete",
+                    sprintId,
+                    cwd,
+                };
+                await emitSyntheticEvent(collateEvent, ctx);
+            }
+            catch (err) {
+                const e = err;
+                ctx.ui.notify(`⚠ forge:run-sprint — sprint-collate-complete synthetic event emit failed: ${e.message ?? "unknown"}`, "warning");
+            }
+            ctx.ui.setStatus?.(SPRINT_STATUS_KEY, undefined);
+            // Sprint root: mark completed in the tree. "revision-required" → failed
+            // because the architect rejected the sprint; partial → completed (the
+            // sprint itself finished, the progress indicator shows N/M tasks done).
+            const sprintTreeStatus = ceremony.verdict === "revision-required" ? "failed" : "completed";
+            tree.completeNode(sprintId, sprintTreeStatus);
+            if (ceremony.verdict === "complete") {
+                ctx.ui.notify(`〇 forge:run-sprint — sprint ${sprintId} complete (${completedTaskIds.length}/${taskIds.length} tasks).`, "info");
+            }
+            else if (ceremony.verdict === "revision-required") {
+                // Architect did not approve; surface to user.
+                ctx.ui.notify(`▲ forge:run-sprint — sprint ${sprintId} ceremony returned "Revision Required". ` +
+                    `See engineering/sprints/${sprintId}/SPRINT_COMPLETION_REVIEW.md.`, "warning");
+            }
+            else {
+                ctx.ui.notify(`▲ forge:run-sprint — sprint ${sprintId} marked partially-completed by architect.`, "warning");
+            }
+        },
+    });
+}
+//# sourceMappingURL=run-sprint.js.map