sequant 2.3.0 → 2.5.0

package/dist/src/lib/workflow/run-orchestrator.js

@@ -15,6 +15,7 @@ import { LogWriter } from "./log-writer.js";
 import { StateManager } from "./state-manager.js";
 import { ShutdownManager } from "../shutdown.js";
 import { LockManager, formatLockedMessage } from "../locks/index.js";
+import { bracketedConsoleLog } from "./notice.js";
 /** Human-readable line for the run-orchestrator's `--signal-other` log (#637). */
 function formatSignalLine(issue, pid, result) {
     switch (result.reason) {
@@ -36,6 +37,7 @@ import { getIssueInfo, sortByDependencies, parseBatches, runIssueWithLogging, em
 import { reconcileStateAtStartup } from "./state-utils.js";
 import { getCommitHash } from "./git-diff-utils.js";
 import { MetricsWriter } from "./metrics-writer.js";
+import { WorkflowEventEmitter } from "./event-emitter.js";
 import { determineOutcome } from "./metrics-schema.js";
 import { getTokenUsageForRun } from "./token-utils.js";
 import { resolveRunOptions, buildExecutionConfig } from "./config-resolver.js";
@@ -65,12 +67,31 @@ export class RunOrchestrator {
     cfg;
     issueStates = new Map();
     phaseStartTimes = new Map();
+    emitter;
     done = false;
     constructor(config) {
         this.validate(config);
+        // Build the event emitter before wrapProgress so the wrapper can route
+        // status transitions through `issue_status_changed` events (AC-3).
+        this.emitter = new WorkflowEventEmitter({
+            onListenerError: (event, error) => {
+                // Mirror the orchestrator's verbose-gated non-fatal warning style.
+                // Listener failures must never propagate to the run.
+                logNonFatalWarning(`  !  Event listener for "${event}" threw, ignoring`, error, config.config?.verbose ?? false);
+            },
+        });
         this.cfg = { ...config, onProgress: this.wrapProgress(config.onProgress) };
         this.initIssueStates();
     }
+    /**
+     * Returns the workflow event emitter. External consumers (TUI, MCP server,
+     * future webhooks) call `getEmitter().on(...)` to subscribe to lifecycle
+     * events. Subscribing is opt-in — the orchestrator runs unaware of who is
+     * listening (#504, AC-3).
+     */
+    getEmitter() {
+        return this.emitter;
+    }
     /**
      * Point-in-time view of the entire run.
      *
@@ -97,9 +118,14 @@ export class RunOrchestrator {
             capturedAt: new Date(),
         };
     }
-    /** Mark the run as completed so the dashboard can unmount. */
+    /**
+     * Mark the run as completed so the dashboard can unmount and drop event
+     * subscribers. Drains the emitter to prevent leaks across multiple
+     * `run()` invocations in the same process (e.g. the MCP server).
+     */
     markDone() {
         this.done = true;
+        this.emitter.removeAllListeners();
     }
     initIssueStates() {
         const { issueInfoMap, worktreeMap, config } = this.cfg;
@@ -129,6 +155,7 @@ export class RunOrchestrator {
         if (!state)
             return;
         if (event === "start") {
+            const wasStatus = state.status;
             if (!state.startedAt)
                 state.startedAt = new Date();
             state.status = "running";
@@ -143,6 +170,19 @@ export class RunOrchestrator {
             const p = findOrAppendPhase(state, phase);
             p.status = "running";
             p.startedAt = now;
+            // Fire-and-forget — listener safety guaranteed by the emitter (AC-5).
+            void this.emitter.emit("phase_started", {
+                issueNumber: issue,
+                phase,
+                iteration: extra?.iteration,
+            });
+            if (wasStatus !== "running") {
+                void this.emitter.emit("issue_status_changed", {
+                    issueNumber: issue,
+                    from: wasStatus,
+                    to: "running",
+                });
+            }
             return;
         }
         if (event === "activity") {
@@ -155,6 +195,11 @@ export class RunOrchestrator {
                 return;
             state.currentPhase.nowLine = line;
             state.currentPhase.lastActivityAt = new Date();
+            void this.emitter.emit("progress", {
+                issueNumber: issue,
+                phase,
+                text: line,
+            });
             return;
         }
         // complete / failed
@@ -170,18 +215,48 @@ export class RunOrchestrator {
         p.status = event === "complete" ? "done" : "failed";
         p.elapsedMs = elapsedMs;
         state.currentPhase = undefined;
+        const durationSec = elapsedMs !== undefined ? Math.round(elapsedMs / 1000) : undefined;
         if (event === "failed") {
+            const prev = state.status;
             state.status = "failed";
             state.completedAt = new Date();
+            void this.emitter.emit("phase_failed", {
+                issueNumber: issue,
+                phase,
+                duration: durationSec,
+                error: extra?.error ?? "unknown",
+                iteration: extra?.iteration,
+            });
+            if (prev !== "failed") {
+                void this.emitter.emit("issue_status_changed", {
+                    issueNumber: issue,
+                    from: prev,
+                    to: "failed",
+                });
+            }
             return;
         }
+        void this.emitter.emit("phase_completed", {
+            issueNumber: issue,
+            phase,
+            duration: durationSec ?? 0,
+            iteration: extra?.iteration,
+        });
         // Completed phase: if it's the last phase in the plan, mark issue passed.
         const allDone = state.phases.every((ph) => ph.status === "done" || ph.status === "failed");
         if (allDone) {
+            const prev = state.status;
             state.status = state.phases.some((ph) => ph.status === "failed")
                 ? "failed"
                 : "passed";
             state.completedAt = new Date();
+            if (prev !== state.status) {
+                void this.emitter.emit("issue_status_changed", {
+                    issueNumber: issue,
+                    from: prev,
+                    to: state.status,
+                });
+            }
         }
     }
     /**
@@ -243,7 +318,7 @@ export class RunOrchestrator {
      * issue discovery → worktree creation → execution → metrics → cleanup.
      */
     static async run(init, issueArgs, batches) {
-        const { manifest, onProgress, settings } = init;
+        const { manifest, onProgress, phasePauseHandle, settings } = init;
         // ── Config resolution ──────────────────────────────────────────────
         const resolved = RunOrchestrator.resolveConfig(init, issueArgs, batches);
         const { mergedOptions, config, baseBranch } = resolved;
@@ -450,18 +525,24 @@ export class RunOrchestrator {
             packageManager: manifest.packageManager,
             baseBranch,
             onProgress,
+            onPhasePlan: init.onPhasePlan,
+            phasePauseHandle,
         });
         init.onOrchestratorReady?.(orchestrator);
         try {
             if (resolvedBatches) {
                 for (let batchIdx = 0; batchIdx < resolvedBatches.length; batchIdx++) {
                     const batch = resolvedBatches[batchIdx];
-                    console.log(chalk.blue(`\n  Batch ${batchIdx + 1}/${resolvedBatches.length}: Issues ${batch.map((n) => `#${n}`).join(", ")}`));
+                    // #647 AC-3: between-batches in a multi-batch run, the renderer is
+                    // still alive and may have a populated live zone from the previous
+                    // batch. Route through `bracketedConsoleLog` so log-update's cursor
+                    // model stays consistent.
+                    bracketedConsoleLog(phasePauseHandle, chalk.blue(`\n  Batch ${batchIdx + 1}/${resolvedBatches.length}: Issues ${batch.map((n) => `#${n}`).join(", ")}`));
                     const batchResults = await orchestrator.execute(batch);
                     results.push(...batchResults);
                     const batchFailed = batchResults.some((r) => !r.success);
                     if (batchFailed && config.sequential) {
-                        console.log(chalk.yellow(`\n  !  Batch ${batchIdx + 1} failed, stopping batch execution`));
+                        bracketedConsoleLog(phasePauseHandle, chalk.yellow(`\n  !  Batch ${batchIdx + 1} failed, stopping batch execution`));
                         break;
                     }
                 }
@@ -546,6 +627,8 @@ export class RunOrchestrator {
             packageManager: this.cfg.packageManager,
             baseBranch: this.cfg.baseBranch,
             onProgress: this.cfg.onProgress,
+            onPhasePlan: this.cfg.onPhasePlan,
+            phasePauseHandle: this.cfg.phasePauseHandle,
         };
     }
     async executeSequential(issueNumbers, batchCtx, options) {
@@ -632,7 +715,7 @@ export class RunOrchestrator {
     }
     async executeOneIssue(args) {
         const { issueNumber, batchCtx, chain, parallelIssueNumber } = args;
-        const { config, options, issueInfoMap, worktreeMap, logWriter, stateManager, shutdownManager, packageManager, baseBranch, onProgress, } = batchCtx;
+        const { config, options, issueInfoMap, worktreeMap, logWriter, stateManager, shutdownManager, packageManager, baseBranch, onProgress, onPhasePlan, phasePauseHandle, } = batchCtx;
         const issueInfo = issueInfoMap.get(issueNumber) ?? {
             title: `Issue #${issueNumber}`,
             labels: [],
@@ -655,15 +738,46 @@ export class RunOrchestrator {
             packageManager,
             baseBranch,
             onProgress,
+            onPhasePlan,
+            phasePauseHandle,
         };
-        const result = await runIssueWithLogging(ctx);
-        if (logWriter && result.prNumber && result.prUrl) {
-            logWriter.setPRInfo(result.prNumber, result.prUrl, parallelIssueNumber);
+        // Fire-and-forget — orchestrator does not await listener completion on
+        // the lifecycle bracket events. Listener safety is the emitter's job (AC-5).
+        void this.emitter.emit("run_started", { issueNumber });
+        const issueStartedAt = Date.now();
+        // `run_completed` is emitted in the finally so the bracket stays
+        // symmetric with `run_started` even if `runIssueWithLogging` throws —
+        // subscribers (MCP, dashboard) can rely on every started run ending.
+        let result;
+        try {
+            result = await runIssueWithLogging(ctx);
+            // Surface QA verdicts as a dedicated event so consumers don't have to
+            // re-parse phase output. Emits at most once per QA phase result.
+            for (const pr of result.phaseResults) {
+                if (pr.phase === "qa" && pr.verdict) {
+                    void this.emitter.emit("qa_verdict", {
+                        issueNumber,
+                        phase: "qa",
+                        verdict: pr.verdict,
+                    });
+                }
+            }
+            if (logWriter && result.prNumber && result.prUrl) {
+                logWriter.setPRInfo(result.prNumber, result.prUrl, parallelIssueNumber);
+            }
+            if (logWriter) {
+                logWriter.completeIssue(parallelIssueNumber);
+            }
+            return result;
         }
-        if (logWriter) {
-            logWriter.completeIssue(parallelIssueNumber);
+        finally {
+            const durationSec = Math.round((Date.now() - issueStartedAt) / 1000);
+            void this.emitter.emit("run_completed", {
+                issueNumber,
+                duration: durationSec,
+                success: result?.success ?? false,
+            });
         }
-        return result;
     }
     static async recordMetrics(config, mergedOptions, results, worktreeMap, issueNumbers) {
         const metricsWriter = new MetricsWriter({ verbose: config.verbose });

package/dist/src/lib/workflow/state-manager.d.ts

@@ -130,9 +130,27 @@ export declare class StateManager {
      */
     updateWorktreeInfo(issueNumber: number, worktree: string, branch: string): Promise<void>;
     /**
-     * Update session ID for an issue (for resume)
+     * Update session ID for an issue (for resume).
+     *
+     * @deprecated Use {@link updateResumeHandle} (#674). This entry point only
+     * writes the legacy `sessionId` field — without an `originCwd`, the next
+     * phase's driver-owned `canResume()` fail-safe will decline resume, so the
+     * data is effectively inert. Retained for one release to keep callers from
+     * older sequant builds compiling.
      */
     updateSessionId(issueNumber: number, sessionId: string): Promise<void>;
+    /**
+     * Update the driver-tagged resume handle for an issue (#674).
+     *
+     * Writes both the new `resumeHandle` field and mirrors the token into
+     * the deprecated `sessionId` field so state files round-trip through
+     * older sequant readers for one release.
+     */
+    updateResumeHandle(issueNumber: number, handle: {
+        driver: string;
+        token: string;
+        originCwd: string;
+    }): Promise<void>;
     /**
      * Set or clear the relay state for an issue (#383).
      *

package/dist/src/lib/workflow/state-manager.js

@@ -378,7 +378,13 @@ export class StateManager {
         }
     }
     /**
-     * Update session ID for an issue (for resume)
+     * Update session ID for an issue (for resume).
+     *
+     * @deprecated Use {@link updateResumeHandle} (#674). This entry point only
+     * writes the legacy `sessionId` field — without an `originCwd`, the next
+     * phase's driver-owned `canResume()` fail-safe will decline resume, so the
+     * data is effectively inert. Retained for one release to keep callers from
+     * older sequant builds compiling.
      */
     async updateSessionId(issueNumber, sessionId) {
         await this.withLock(async () => {
@@ -392,6 +398,26 @@ export class StateManager {
             await this.saveState(state);
         });
     }
+    /**
+     * Update the driver-tagged resume handle for an issue (#674).
+     *
+     * Writes both the new `resumeHandle` field and mirrors the token into
+     * the deprecated `sessionId` field so state files round-trip through
+     * older sequant readers for one release.
+     */
+    async updateResumeHandle(issueNumber, handle) {
+        await this.withLock(async () => {
+            const state = await this.getState();
+            const issueState = state.issues[String(issueNumber)];
+            if (!issueState) {
+                throw new Error(`Issue #${issueNumber} not found in state`);
+            }
+            issueState.resumeHandle = handle;
+            issueState.sessionId = handle.token;
+            issueState.lastActivity = new Date().toISOString();
+            await this.saveState(state);
+        });
+    }
     /**
      * Set or clear the relay state for an issue (#383).
      *

package/dist/src/lib/workflow/state-schema.d.ts

@@ -19,9 +19,14 @@
 import { z } from "zod";
 import { PhaseSchema } from "./types.js";
 /**
- * Workflow phases in order of execution
+ * Workflow phases in order of execution.
+ *
+ * Sourced from the phase registry — replaces the previous `PhaseSchema.options`
+ * literal that existed when `PhaseSchema` was a `z.enum`. Computed at module
+ * load (after `built-in-phases.ts` has run); insertion order is the canonical
+ * pipeline order.
  */
-export declare const WORKFLOW_PHASES: ("qa" | "loop" | "verify" | "spec" | "security-review" | "exec" | "testgen" | "test" | "merger")[];
+export declare const WORKFLOW_PHASES: readonly string[];
 /**
  * Phase status - tracks individual phase progress
  */
@@ -41,6 +46,7 @@ export declare const IssueStatusSchema: z.ZodEnum<{
     in_progress: "in_progress";
     not_started: "not_started";
     waiting_for_qa_gate: "waiting_for_qa_gate";
+    waiting_for_human_merge: "waiting_for_human_merge";
     ready_for_merge: "ready_for_merge";
     blocked: "blocked";
     abandoned: "abandoned";
@@ -54,17 +60,7 @@ export type { Phase } from "./types.js";
  * Embedded as HTML comments: `<!-- SEQUANT_PHASE: {...} -->`
  */
 export declare const PhaseMarkerSchema: z.ZodObject<{
-    phase: z.ZodEnum<{
-        qa: "qa";
-        loop: "loop";
-        verify: "verify";
-        spec: "spec";
-        "security-review": "security-review";
-        exec: "exec";
-        testgen: "testgen";
-        test: "test";
-        merger: "merger";
-    }>;
+    phase: z.ZodString;
     status: z.ZodEnum<{
         pending: "pending";
         skipped: "skipped";
@@ -227,23 +223,14 @@ export declare const IssueStateSchema: z.ZodObject<{
         in_progress: "in_progress";
         not_started: "not_started";
         waiting_for_qa_gate: "waiting_for_qa_gate";
+        waiting_for_human_merge: "waiting_for_human_merge";
         ready_for_merge: "ready_for_merge";
         blocked: "blocked";
         abandoned: "abandoned";
     }>;
     worktree: z.ZodOptional<z.ZodString>;
     branch: z.ZodOptional<z.ZodString>;
-    currentPhase: z.ZodOptional<z.ZodEnum<{
-        qa: "qa";
-        loop: "loop";
-        verify: "verify";
-        spec: "spec";
-        "security-review": "security-review";
-        exec: "exec";
-        testgen: "testgen";
-        test: "test";
-        merger: "merger";
-    }>>;
+    currentPhase: z.ZodOptional<z.ZodString>;
     phases: z.ZodRecord<z.ZodString, z.ZodObject<{
         status: z.ZodEnum<{
             pending: "pending";
@@ -348,6 +335,11 @@ export declare const IssueStateSchema: z.ZodObject<{
         messageCount: z.ZodNumber;
     }, z.core.$strip>>;
     sessionId: z.ZodOptional<z.ZodString>;
+    resumeHandle: z.ZodOptional<z.ZodObject<{
+        driver: z.ZodString;
+        token: z.ZodString;
+        originCwd: z.ZodString;
+    }, z.core.$strip>>;
     resolvedAt: z.ZodOptional<z.ZodString>;
     lastActivity: z.ZodString;
     createdAt: z.ZodString;
@@ -370,23 +362,14 @@ export declare const WorkflowStateSchema: z.ZodObject<{
             in_progress: "in_progress";
             not_started: "not_started";
             waiting_for_qa_gate: "waiting_for_qa_gate";
+            waiting_for_human_merge: "waiting_for_human_merge";
             ready_for_merge: "ready_for_merge";
             blocked: "blocked";
             abandoned: "abandoned";
         }>;
         worktree: z.ZodOptional<z.ZodString>;
         branch: z.ZodOptional<z.ZodString>;
-        currentPhase: z.ZodOptional<z.ZodEnum<{
-            qa: "qa";
-            loop: "loop";
-            verify: "verify";
-            spec: "spec";
-            "security-review": "security-review";
-            exec: "exec";
-            testgen: "testgen";
-            test: "test";
-            merger: "merger";
-        }>>;
+        currentPhase: z.ZodOptional<z.ZodString>;
         phases: z.ZodRecord<z.ZodString, z.ZodObject<{
             status: z.ZodEnum<{
                 pending: "pending";
@@ -491,6 +474,11 @@ export declare const WorkflowStateSchema: z.ZodObject<{
             messageCount: z.ZodNumber;
         }, z.core.$strip>>;
         sessionId: z.ZodOptional<z.ZodString>;
+        resumeHandle: z.ZodOptional<z.ZodObject<{
+            driver: z.ZodString;
+            token: z.ZodString;
+            originCwd: z.ZodString;
+        }, z.core.$strip>>;
         resolvedAt: z.ZodOptional<z.ZodString>;
         lastActivity: z.ZodString;
         createdAt: z.ZodString;

package/dist/src/lib/workflow/state-schema.js

@@ -19,10 +19,16 @@
 import { z } from "zod";
 import { ScopeAssessmentSchema } from "../scope/types.js";
 import { PhaseSchema } from "./types.js";
+import { getPhaseNames } from "./phase-registry.js";
 /**
- * Workflow phases in order of execution
+ * Workflow phases in order of execution.
+ *
+ * Sourced from the phase registry — replaces the previous `PhaseSchema.options`
+ * literal that existed when `PhaseSchema` was a `z.enum`. Computed at module
+ * load (after `built-in-phases.ts` has run); insertion order is the canonical
+ * pipeline order.
  */
-export const WORKFLOW_PHASES = PhaseSchema.options;
+export const WORKFLOW_PHASES = getPhaseNames();
 /**
  * Phase status - tracks individual phase progress
  */
@@ -40,6 +46,7 @@ export const IssueStatusSchema = z.enum([
     "not_started", // Issue tracked but no work begun
     "in_progress", // Actively being worked on
     "waiting_for_qa_gate", // QA completed, waiting for gate approval in chain mode
+    "waiting_for_human_merge", // `sequant ready` (#683) finished its A+ gate; awaiting human merge decision (never auto-merges)
     "ready_for_merge", // All phases passed, PR ready for review
     "merged", // PR merged, work complete
     "blocked", // Waiting on external input or dependency
@@ -213,8 +220,27 @@ export const IssueStateSchema = z.object({
     qaStagnation: z.array(QAStagnationEntrySchema).optional(),
     /** Relay state (#383); present when bidirectional relay is active */
     relay: RelayStateSchema.optional(),
-    /** Claude session ID (for resume) */
+    /**
+     * Claude session ID (for resume).
+     * @deprecated Use {@link resumeHandle} (#674). Retained as a read-path
+     * mirror of `resumeHandle.token` for one release so state files written by
+     * prior sequant builds load cleanly. Legacy entries (token without
+     * `originCwd`) intentionally do NOT resume — the driver-owned `canResume`
+     * fail-safe disables them.
+     */
     sessionId: z.string().optional(),
+    /**
+     * Driver-tagged resume handle (#674). Stores the driver name, the
+     * resume token, and the cwd the session was created in so the next phase
+     * can prove cwd-equality before reattaching.
+     */
+    resumeHandle: z
+        .object({
+        driver: z.string(),
+        token: z.string(),
+        originCwd: z.string(),
+    })
+        .optional(),
     /** When the issue transitioned to a terminal status (merged/abandoned/closed) */
     resolvedAt: z.string().datetime().optional(),
     /** Most recent activity timestamp */

package/dist/src/lib/workflow/types.d.ts

@@ -7,27 +7,47 @@ import type { LogWriter } from "./log-writer.js";
 import type { StateManager } from "./state-manager.js";
 import type { ShutdownManager } from "../shutdown.js";
 import type { WorktreeInfo } from "./worktree-manager.js";
+export type { WorkflowEventEmitter, WorkflowEvents, WorkflowEventListener, IssueEventStatus, BaseEventPayload, RunEventPayload, PhaseStartedPayload, PhaseCompletedPayload, PhaseFailedPayload, IssueStatusChangedPayload, QaVerdictPayload, ProgressPayload, } from "./event-emitter.js";
 /**
  * Canonical Zod schema for all workflow phases.
  *
- * This is the single source of truth — state-schema.ts and run-log-schema.ts
- * both reference this definition. Add new phases here only.
+ * Backed by the phase registry. `PhaseSchema.parse(name)` succeeds iff
+ * `phaseRegistry.has(name)`. The set of valid phases is the registry's
+ * keys at the time of parsing — registration happens at module load,
+ * so for normal runtime use the set is fixed by the time any code parses.
+ *
+ * This replaces the prior `z.enum([...])` literal. The set of valid names
+ * is identical for the 9 built-in phases; the only observable behavior
+ * change is that `PhaseSchema.options` is no longer available — use
+ * `getPhaseNames()` from `phase-registry.ts` instead.
+ */
+export declare const PhaseSchema: z.ZodString;
+/**
+ * Available workflow phases. Widened from a string-literal union to `string`
+ * after the registry migration — exhaustiveness checking on `switch (phase)`
+ * is now a runtime concern (see the comment in phase-executor.ts where the
+ * only relevant switch lives).
  */
-export declare const PhaseSchema: z.ZodEnum<{
-    qa: "qa";
-    loop: "loop";
-    verify: "verify";
-    spec: "spec";
-    "security-review": "security-review";
-    exec: "exec";
-    testgen: "testgen";
-    test: "test";
-    merger: "merger";
-}>;
+export type Phase = string;
 /**
- * Available workflow phases (inferred from PhaseSchema)
+ * Lifecycle hook for pausing the run renderer's live zone while verbose
+ * Claude streaming writes through stdout, then resuming after the agent
+ * call completes. Replaces the legacy `PhaseSpinner` argument (#618).
+ *
+ * Lives in the workflow types barrel so the cli-ui layer can implement it
+ * without the workflow layer reaching back into cli-ui (#656).
  */
-export type Phase = z.infer<typeof PhaseSchema>;
+export interface PhasePauseHandle {
+    pause(): void;
+    resume(): void;
+    /**
+     * #647 AC-3: print a notice line (e.g., retry/fallback message) without
+     * breaking log-update's cursor model. Implementations clear the live zone,
+     * write the line through the renderer's own stdout channel, then redraw.
+     * In quiet / non-TTY paths this degrades to a plain write.
+     */
+    appendNotice(message: string): void;
+}
 /**
  * Default phases for workflow execution
  */
@@ -116,6 +136,15 @@ export interface ExecutionConfig {
      * Default: false (opt-in for the initial rollout).
      */
     relayEnabled?: boolean;
+    /**
+     * Force full-weight (standalone) QA even under an orchestrator (#683).
+     * When true, the phase executor sets `SEQUANT_FULL_QA=1` in the agent
+     * environment for the `qa` phase. The QA skill honors this flag by running
+     * its standalone branch-freshness / process-state pre-flight checks even
+     * though `SEQUANT_ORCHESTRATOR` is also set. Used by `sequant ready` so its
+     * QA pass does NOT skip the checks that catch the #318/#529/#570 class.
+     */
+    fullQa?: boolean;
 }
 /**
  * Default execution configuration
@@ -338,6 +367,17 @@ export type ProgressCallback = (issue: number, phase: string, event: "start" | "
     iteration?: number;
     text?: string;
 }) => void;
+/**
+ * #672 AC-2: fired once per issue after the executor has resolved the final
+ * phase pipeline (post auto-detect, post resume filter, post testgen /
+ * security-review insertion). Lets the run renderer seed pending cells for
+ * the full roadmap before any phase fires, so users see what is about to run
+ * instead of phases appearing one at a time as they stream.
+ *
+ * Empty `phases` means "no plan known" — the renderer should fall back to
+ * streaming-only display.
+ */
+export type PhasePlanCallback = (issue: number, phases: string[]) => void;
 /**
  * Shared context for executing a batch of issues.
  * Replaces 11 positional parameters in executeBatch (#402).
@@ -356,6 +396,17 @@ export interface BatchExecutionContext {
     packageManager?: string;
     baseBranch?: string;
     onProgress?: ProgressCallback;
+    /** #672 AC-2: forwarded to per-issue context so batch-executor can fire it
+     * once the final phase pipeline is known. */
+    onPhasePlan?: PhasePlanCallback;
+    /**
+     * Optional live-zone pause handle (#656). When set, the phase executor calls
+     * `pause()` before forwarding verbose Claude SDK output to stdout and
+     * `resume()` after the agent call completes — so the 1Hz live grid does not
+     * collide with streaming text. Wired from the active `RunRenderer` at the
+     * composition root in `run.ts`; left undefined for quiet/TUI modes.
+     */
+    phasePauseHandle?: PhasePauseHandle;
 }
 /**
  * Context object for executing a single issue through the workflow.
@@ -405,4 +456,12 @@ export interface IssueExecutionContext {
     baseBranch?: string;
     /** Per-phase progress callback (used in parallel mode) */
     onProgress?: ProgressCallback;
+    /** #672 AC-2: invoked once after the per-issue phase plan resolves. */
+    onPhasePlan?: PhasePlanCallback;
+    /**
+     * Optional live-zone pause handle (#656). Forwarded to
+     * `executePhaseWithRetry` so the renderer's `pause`/`resume` hooks fire
+     * around verbose Claude streaming.
+     */
+    phasePauseHandle?: PhasePauseHandle;
 }

package/dist/src/lib/workflow/types.js

@@ -2,23 +2,28 @@
  * Core types for workflow execution
  */
 import { z } from "zod";
+// Importing the registry triggers its side-effect registrations (built-ins
+// live at the bottom of phase-registry.ts), guaranteeing the registry is
+// populated before any PhaseSchema parse runs.
+import { phaseRegistry, getPhaseNames } from "./phase-registry.js";
 /**
  * Canonical Zod schema for all workflow phases.
  *
- * This is the single source of truth — state-schema.ts and run-log-schema.ts
- * both reference this definition. Add new phases here only.
+ * Backed by the phase registry. `PhaseSchema.parse(name)` succeeds iff
+ * `phaseRegistry.has(name)`. The set of valid phases is the registry's
+ * keys at the time of parsing — registration happens at module load,
+ * so for normal runtime use the set is fixed by the time any code parses.
+ *
+ * This replaces the prior `z.enum([...])` literal. The set of valid names
+ * is identical for the 9 built-in phases; the only observable behavior
+ * change is that `PhaseSchema.options` is no longer available — use
+ * `getPhaseNames()` from `phase-registry.ts` instead.
  */
-export const PhaseSchema = z.enum([
-    "spec",
-    "security-review",
-    "exec",
-    "testgen",
-    "test",
-    "verify",
-    "qa",
-    "loop",
-    "merger",
-]);
+export const PhaseSchema = z
+    .string()
+    .refine((name) => phaseRegistry.has(name), {
+    error: (issue) => `Unknown phase "${String(issue.input)}". Available: ${getPhaseNames().join(", ")}`,
+});
 /**
  * Default phases for workflow execution
  */