sequant 2.3.0 → 2.4.0

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
     {
       "name": "sequant",
       "description": "Structured workflow system for Claude Code - GitHub issue resolution with spec, exec, test, and QA phases. Includes 17 skills, MCP server with workflow tools, and pre/post-tool hooks.",
-      "version": "2.3.0",
+      "version": "2.4.0",
       "author": {
         "name": "sequant-io",
         "email": "hello@sequant.io"

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "sequant",
   "description": "Structured workflow system for Claude Code - GitHub issue resolution with spec, exec, test, and QA phases",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "author": {
     "name": "sequant-io",
     "email": "hello@sequant.io"

package/README.md

@@ -9,13 +9,16 @@ Solve GitHub issues with structured phases and quality gates — from issue to m
 [![npm version](https://img.shields.io/npm/v/sequant.svg)](https://www.npmjs.com/package/sequant)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
 
-### What's new in 2.0
+### What's new in 2.x
 
 - **MCP server** — `sequant serve` exposes workflow orchestration as MCP tools (`sequant_run`, `sequant_status`, `sequant_logs`). Any MCP client can drive Sequant headlessly.
 - **`/assess` unification** — `/solve` is merged into `/assess` with a 6-action vocabulary (PROCEED, CLOSE, MERGE, REWRITE, CLARIFY, PARK). `/solve` still works as an alias.
-- **Parallel execution** — multi-issue runs are concurrent by default with `--concurrency`.
-- **Multi-agent** — `--agent aider` as an alternative backend, with a driver interface for future agents.
-- **GitHub Actions** — label-triggered and comment-triggered CI workflows out of the box.
+- **Parallel execution with per-issue locks** — multi-issue runs are concurrent by default (`--concurrency`); `.sequant/locks/` prevents two sessions from clobbering the same issue.
+- **Stacked PRs** — `sequant run --stacked` chains issue PRs onto their predecessor branch so reviewers see the incremental diff per issue instead of the cumulative chain diff.
+- **Live run dashboard + cohort analytics** — unified renderer with a two-zone TTY grid (active issues + append-only events log); `sequant stats --label <name> --since YYYY-MM-DD` filters runs for measuring feature- or class-specific success rates.
+- **Interactive relay** — `sequant prompt <issue> "<message>"` sends queries or directives into a running headless `sequant run`, and `sequant watch <issue>` tails the replies. Bidirectional communication with detached and CI-driven sessions.
+- **Worktree isolation for parallel agents** — `sequant run --isolate-parallel` gives each parallel `/exec` agent group its own sub-worktree with merge-back via `git merge --no-ff`, eliminating file conflicts between concurrent agents structurally rather than by convention.
+- **GitHub Actions & multi-agent backends** — label-triggered and comment-triggered CI workflows out of the box; `--agent aider` for non-Claude-Code execution.
 
 Upgrading from v1.x? See the [migration guide](CHANGELOG.md#migration-from-v1x).
 
@@ -71,7 +74,7 @@ Or step-by-step:
 - Git (for worktree-based isolation)
 
 **For npm installation:**
-- Node.js 20+
+- Node.js 22.12+
 
 **Optional MCP servers (enhanced features):**
 - `chrome-devtools` — enables `/test` for browser-based UI testing

package/dist/bin/cli.js

@@ -4,7 +4,7 @@
  *
  * Sequential AI phases with quality gates for any codebase.
  */
-import { Command } from "commander";
+import { Command, InvalidArgumentError } from "commander";
 import chalk from "chalk";
 import { fileURLToPath } from "url";
 import { dirname, resolve } from "path";
@@ -50,7 +50,29 @@ import { conventionsCommand } from "../src/commands/conventions.js";
 import { locksListCommand, locksClearCommand, locksAcquireCommand, locksReleaseCommand, locksCheckCommand, locksCheckBatchCommand, } from "../src/commands/locks.js";
 import { promptCommand } from "../src/commands/prompt.js";
 import { watchCommand } from "../src/commands/watch.js";
+import { abortCommand } from "../src/commands/abort.js";
 import { getManifest } from "../src/lib/manifest.js";
+import { phaseRegistry } from "../src/lib/workflow/phase-registry.js";
+/**
+ * Validate `--phases` argument against the phase registry.
+ *
+ * Splits a comma-separated phase list, checks each name against
+ * `phaseRegistry`, and exits with a clear error message if any phase
+ * is unknown. Returns the original string unchanged so downstream
+ * `RunOptions.phases` parsing in `config-resolver.ts` is undisturbed.
+ */
+function validatePhasesFlag(value) {
+    const names = value
+        .split(",")
+        .map((p) => p.trim())
+        .filter((p) => p.length > 0);
+    const unknown = names.filter((n) => !phaseRegistry.has(n));
+    if (unknown.length > 0) {
+        const available = phaseRegistry.names().join(", ");
+        throw new InvalidArgumentError(`Unknown phase '${unknown[0]}'. Available: ${available}`);
+    }
+    return value;
+}
 const program = new Command();
 // Handle --no-color before parsing
 if (process.argv.includes("--no-color")) {
@@ -141,7 +163,7 @@ program
     .command("run")
     .description("Execute workflow for GitHub issues using Claude Agent SDK")
     .argument("[issues...]", "Issue numbers to process")
-    .option("--phases <list>", "Phases to run (default: spec,exec,qa)")
+    .option("--phases <list>", "Phases to run (default: spec,exec,qa)", validatePhasesFlag)
     .option("--sequential", "Stop on first issue failure (default: continue)")
     .option("-d, --dry-run", "Preview without execution")
     .option("-v, --verbose", "Verbose output with streaming")
@@ -149,14 +171,14 @@ program
     .option("--log-json", "Enable structured JSON logging (default: true)")
     .option("--no-log", "Disable JSON logging for this run")
     .option("--log-path <path>", "Custom log directory path")
-    .option("-q, --quality-loop", "Enable quality loop with auto-retry")
+    .option("-Q, --quality-loop", "Enable quality loop with auto-retry")
     .option("--max-iterations <n>", "Max iterations for quality loop (default: 3)", parseInt)
     .option("--batch <issues>", 'Group of issues to run together (e.g., --batch "1 2" --batch "3")', (value, prev) => prev.concat([value]), [])
     .option("--smart-tests", "Enable smart test detection (default)")
     .option("--no-smart-tests", "Disable smart test detection")
     .option("--testgen", "Run testgen phase after spec")
     .option("--security-review", "Run security-review phase after spec")
-    .option("--quiet", "Suppress version warnings and non-essential output")
+    .option("-q, --quiet", "Suppress version warnings and non-essential output")
     .option("--chain", "Chain issues: each branches from previous (implies --sequential)")
     .option("--stacked", "Stack PRs: middle PRs target predecessor branch instead of main; first/last target main (implies --chain)")
     .option("--qa-gate", "Wait for QA pass before starting next issue in chain (requires --chain)")
@@ -180,12 +202,14 @@ program
     .description("Send a message into a running headless sequant session (#383)")
     .argument("[args...]", '[<issue>] "<message>"')
     .option("--type <type>", "Message type: query (default), directive, abort", "query")
+    .option("--wait <seconds>", "Block until a reply arrives or the timeout elapses (#645, Gap 4)", parseInt)
     .option("--json", "Output as JSON")
     .action((args, options) => {
     return promptCommand({
         args,
         options: {
             type: options.type,
+            waitSeconds: typeof options.wait === "number" ? options.wait : undefined,
             json: Boolean(options.json),
         },
     });
@@ -201,6 +225,24 @@ program
         options: { json: Boolean(options.json) },
     });
 });
+program
+    .command("abort")
+    .description("Out-of-band abort: signal a running sequant session directly (#645)")
+    .argument("[issue]", "Issue number (auto-resolved when a single run is active)")
+    .option("--force", "Skip the SIGINT grace period; SIGTERM immediately")
+    .option("--grace <seconds>", "Seconds to wait after SIGINT before escalating (default: 10)", parseInt)
+    .option("--json", "Output as JSON")
+    .action((issueArg, options) => {
+    const args = issueArg === undefined ? [] : [issueArg];
+    return abortCommand({
+        args,
+        options: {
+            force: Boolean(options.force),
+            graceSeconds: typeof options.grace === "number" ? options.grace : undefined,
+            json: Boolean(options.json),
+        },
+    });
+});
 program
     .command("merge")
     .description("Batch-level integration QA — verify feature branches before merging")

package/dist/src/commands/abort.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `sequant abort <issue>` — out-of-band escape hatch for a running headless
+ * session (#645, Gap 7).
+ *
+ * `sequant prompt --type abort` queues an abort message into the inbox, which
+ * the agent must read via the PostToolUse hook chain. When that chain is
+ * broken (the bug originally reported in #645), no in-band abort can land.
+ *
+ * This command bypasses the inbox entirely: it locates the orchestrator PID
+ * via `state.json.relay.pid` (with the per-issue pidfile as fallback) and
+ * sends signals directly. The receiving end is the existing ShutdownManager
+ * in `sequant run`, which already performs a clean teardown on SIGINT/SIGTERM.
+ */
+export interface AbortCommandOptions {
+    /** Skip the SIGINT grace period; SIGTERM immediately. */
+    force?: boolean;
+    /** Seconds to wait after SIGINT before escalating. Default 10. */
+    graceSeconds?: number;
+    json?: boolean;
+    /** Test seam: override the system kill function. */
+    killFn?: (pid: number, signal: NodeJS.Signals) => void;
+    /** Test seam: override the liveness check. */
+    isAlive?: (pid: number) => boolean;
+    /** Test seam: override the poll interval (ms). Default 250. */
+    pollIntervalMs?: number;
+    /** Test seam: override SIGTERM grace before SIGKILL (ms). Default 3000. */
+    sigtermTimeoutMs?: number;
+    /** Test seam: override SIGKILL final wait (ms). Default 2000. */
+    sigkillTimeoutMs?: number;
+    /** Test seam: override cwd for pidfile resolution. */
+    cwd?: string;
+}
+export declare function abortCommand(argsAndOptions: {
+    args: string[];
+    options: AbortCommandOptions;
+}): Promise<void>;

package/dist/src/commands/abort.js

@@ -0,0 +1,138 @@
+/**
+ * `sequant abort <issue>` — out-of-band escape hatch for a running headless
+ * session (#645, Gap 7).
+ *
+ * `sequant prompt --type abort` queues an abort message into the inbox, which
+ * the agent must read via the PostToolUse hook chain. When that chain is
+ * broken (the bug originally reported in #645), no in-band abort can land.
+ *
+ * This command bypasses the inbox entirely: it locates the orchestrator PID
+ * via `state.json.relay.pid` (with the per-issue pidfile as fallback) and
+ * sends signals directly. The receiving end is the existing ShutdownManager
+ * in `sequant run`, which already performs a clean teardown on SIGINT/SIGTERM.
+ */
+import chalk from "chalk";
+import { isPidAlive, readPidFile } from "../lib/relay/pid.js";
+import { StateManager } from "../lib/workflow/state-manager.js";
+import { findActiveIssues, resolveTargetIssue } from "./prompt.js";
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Send `signal` and wait up to `timeoutMs` for the PID to exit. Returns true
+ * if the process died, false if still alive at the deadline.
+ */
+async function signalAndWait(pid, signal, timeoutMs, isAlive, killFn, pollIntervalMs) {
+    try {
+        killFn(pid, signal);
+    }
+    catch {
+        // ESRCH (process already dead) → success.
+        if (!isAlive(pid))
+            return true;
+        throw new Error(`Failed to send ${signal} to PID ${pid} (signal not delivered)`);
+    }
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!isAlive(pid))
+            return true;
+        await delay(pollIntervalMs);
+    }
+    return !isAlive(pid);
+}
+export async function abortCommand(argsAndOptions) {
+    const { args, options } = argsAndOptions;
+    const json = Boolean(options.json);
+    const killFn = options.killFn ??
+        ((pid, signal) => {
+            process.kill(pid, signal);
+        });
+    const isAlive = options.isAlive ?? isPidAlive;
+    const pollIntervalMs = options.pollIntervalMs ?? 250;
+    const cwd = options.cwd ?? process.cwd();
+    // Resolve target issue: explicit arg or single-active auto-resolve.
+    const stateManager = new StateManager();
+    let issueNumber;
+    const issueArg = args[0];
+    if (issueArg !== undefined) {
+        const n = Number.parseInt(issueArg, 10);
+        if (!Number.isInteger(n) || n <= 0) {
+            throw new Error(`Invalid issue number: '${issueArg}'`);
+        }
+        issueNumber = n;
+    }
+    else {
+        const all = stateManager.stateExists()
+            ? Object.values(await stateManager.getAllIssueStates())
+            : [];
+        const active = findActiveIssues(all, isAlive, cwd);
+        const target = resolveTargetIssue({ explicit: null, activeIssues: active });
+        issueNumber = target.issue;
+    }
+    const issueState = await stateManager.getIssueState(issueNumber);
+    const pid = issueState?.relay?.pid ?? readPidFile(issueNumber, cwd) ?? null;
+    if (pid === null) {
+        const msg = `No relay PID found for #${issueNumber}. Is the run active?`;
+        if (json) {
+            console.log(JSON.stringify({ ok: false, issue: issueNumber, error: msg }));
+        }
+        else {
+            console.error(chalk.yellow(msg));
+        }
+        process.exitCode = 1;
+        return;
+    }
+    if (!isAlive(pid)) {
+        const msg = `PID ${pid} for #${issueNumber} is already dead.`;
+        if (json) {
+            console.log(JSON.stringify({ ok: true, issue: issueNumber, pid, signal: null }));
+        }
+        else {
+            console.log(chalk.gray(msg));
+        }
+        return;
+    }
+    const graceMs = Math.max(0, (options.graceSeconds ?? 10) * 1000);
+    const force = Boolean(options.force);
+    let delivered = "SIGINT";
+    let died = false;
+    if (!force) {
+        if (!json) {
+            console.log(chalk.gray(`Sending SIGINT to PID ${pid} (#${issueNumber}); waiting up to ${graceMs / 1000}s for graceful exit…`));
+        }
+        died = await signalAndWait(pid, "SIGINT", graceMs, isAlive, killFn, pollIntervalMs);
+    }
+    if (!died) {
+        delivered = "SIGTERM";
+        if (!json) {
+            console.log(chalk.yellow(force
+                ? `Sending SIGTERM to PID ${pid} (#${issueNumber}) (--force)…`
+                : `Grace expired; escalating to SIGTERM…`));
+        }
+        died = await signalAndWait(pid, "SIGTERM", options.sigtermTimeoutMs ?? 3000, isAlive, killFn, pollIntervalMs);
+    }
+    if (!died) {
+        delivered = "SIGKILL";
+        if (!json) {
+            console.log(chalk.red(`SIGTERM ignored; escalating to SIGKILL on PID ${pid}…`));
+        }
+        died = await signalAndWait(pid, "SIGKILL", options.sigkillTimeoutMs ?? 2000, isAlive, killFn, pollIntervalMs);
+    }
+    if (!died) {
+        process.exitCode = 1;
+    }
+    if (json) {
+        console.log(JSON.stringify({
+            ok: died,
+            issue: issueNumber,
+            pid,
+            signal: delivered,
+        }));
+    }
+    else if (died) {
+        console.log(chalk.green(`Aborted #${issueNumber} (PID ${pid}, ${delivered}).`));
+    }
+    else {
+        console.error(chalk.red(`Failed to abort #${issueNumber}: PID ${pid} still alive after ${delivered}.`));
+    }
+}

package/dist/src/commands/prompt.d.ts

@@ -7,6 +7,13 @@ import type { IssueState } from "../lib/workflow/state-schema.js";
 export interface PromptCommandOptions {
     type?: string;
     json?: boolean;
+    /**
+     * If set, poll the outbox for a reply that matches the new message ID and
+     * print it inline. Exits 0 on reply, 1 on timeout (#645, Gap 4).
+     */
+    waitSeconds?: number;
+    /** Test seam: override the poll interval (ms). Default 250. */
+    waitPollIntervalMs?: number;
 }
 export interface ParsedPromptArgs {
     issue: number | null;

package/dist/src/commands/prompt.js

@@ -2,10 +2,12 @@
  * `sequant prompt <issue> "<message>"` — send a message into a running
  * headless `sequant run` session via the interactive relay (#383).
  */
+import { existsSync, statSync, readFileSync } from "fs";
 import chalk from "chalk";
-import { RelayMessageTypeSchema, } from "../lib/relay/types.js";
+import { RelayMessageTypeSchema, RelayResponseSchema, } from "../lib/relay/types.js";
 import { appendInboxMessage } from "../lib/relay/writer.js";
 import { cleanupStalePid, readPidFile } from "../lib/relay/pid.js";
+import { outboxPathFor } from "../lib/relay/paths.js";
 import { StateManager } from "../lib/workflow/state-manager.js";
 /** Validate raw CLI args. Throws on invalid type or empty message. */
 export function parseRelayPromptArgs(args, options = {}) {
@@ -150,26 +152,118 @@ export async function promptCommand(argsAndOptions) {
     catch {
         /* swallow */
     }
-    // Build confirmation with current phase + elapsed time.
-    const phase = issueState?.currentPhase ?? "unknown";
+    // Re-fetch state with a fresh manager to bypass any cached snapshot from
+    // the start-of-command read. Without this, `currentPhase` shown in the
+    // confirmation can be a phase-old (#645, Gap 6: user reported "exec phase"
+    // while state.json had advanced to qa).
+    let freshPhase;
+    let freshStartedAt;
+    try {
+        const freshState = await new StateManager().getIssueState(issueNumber);
+        freshPhase = freshState?.currentPhase;
+        freshStartedAt = freshState?.relay?.startedAt;
+    }
+    catch {
+        // Fall back to the issueState we already have.
+        freshPhase = issueState?.currentPhase;
+        freshStartedAt = issueState?.relay?.startedAt;
+    }
     let elapsedSegment = "";
-    if (issueState?.relay?.startedAt) {
-        const ms = Date.now() - new Date(issueState.relay.startedAt).getTime();
+    if (freshStartedAt) {
+        const ms = Date.now() - new Date(freshStartedAt).getTime();
         elapsedSegment = `, ${formatElapsed(ms)} elapsed`;
     }
-    const confirmation = `Message sent to #${issueNumber} (${phase} phase${elapsedSegment})`;
+    // Omit the phase label when we don't have a fresh reading (#645, Gap 6) —
+    // a wrong phase is worse than no phase. Callers asking for JSON still get
+    // an explicit `phase: null` for that case.
+    const phaseSegment = freshPhase
+        ? ` (${freshPhase} phase${elapsedSegment})`
+        : "";
+    const confirmation = `Message sent to #${issueNumber}${phaseSegment}`;
     if (options.json) {
         console.log(JSON.stringify({
             ok: true,
             issue: issueNumber,
             messageId: message.id,
             type: parsed.type,
-            phase,
+            phase: freshPhase ?? null,
         }));
     }
     else {
         console.log(chalk.green(confirmation));
     }
+    // Optional --wait: poll outbox for a reply that references our message id.
+    // Times out with exit 1 if no matching reply lands within the window.
+    if (typeof options.waitSeconds === "number" &&
+        options.waitSeconds > 0 &&
+        parsed.type !== "abort") {
+        const reply = await waitForReply({
+            issueNumber,
+            worktreePath: issueState?.worktree,
+            inReplyTo: message.id,
+            timeoutMs: options.waitSeconds * 1000,
+            pollIntervalMs: options.waitPollIntervalMs ?? 250,
+        });
+        if (reply) {
+            if (options.json) {
+                console.log(JSON.stringify({ ok: true, reply }));
+            }
+            else {
+                console.log(chalk.cyan(`Reply: ${reply.message}`));
+            }
+        }
+        else {
+            const msg = `No reply received within ${options.waitSeconds}s. Message may be archived without a response.`;
+            if (options.json) {
+                console.log(JSON.stringify({ ok: false, timeout: true, error: msg }));
+            }
+            else {
+                console.error(chalk.yellow(msg));
+            }
+            process.exitCode = 1;
+        }
+    }
+}
+async function waitForReply(options) {
+    const outboxPath = outboxPathFor(options.issueNumber, {
+        worktreePath: options.worktreePath,
+    });
+    // Seed offset at current EOF: only NEW replies count for this prompt's wait.
+    let offset = existsSync(outboxPath) ? statSync(outboxPath).size : 0;
+    let partial = "";
+    const deadline = Date.now() + options.timeoutMs;
+    while (Date.now() < deadline) {
+        if (existsSync(outboxPath)) {
+            try {
+                const size = statSync(outboxPath).size;
+                if (size > offset) {
+                    const chunk = readFileSync(outboxPath, "utf-8").slice(offset);
+                    offset = size;
+                    const lines = (partial + chunk).split("\n");
+                    partial = lines.pop() ?? "";
+                    for (const line of lines) {
+                        if (line.trim() === "")
+                            continue;
+                        try {
+                            const parsed = RelayResponseSchema.safeParse(JSON.parse(line));
+                            if (parsed.success &&
+                                parsed.data.inReplyTo === options.inReplyTo) {
+                                return parsed.data;
+                            }
+                        }
+                        catch {
+                            /* skip malformed */
+                        }
+                    }
+                }
+            }
+            catch {
+                /* transient — try again */
+            }
+        }
+        await new Promise((r) => setTimeout(r, options.pollIntervalMs));
+    }
+    return null;
 }
 function formatElapsed(ms) {
     const totalSec = Math.max(0, Math.floor(ms / 1000));

package/dist/src/commands/run-progress.d.ts

@@ -8,11 +8,14 @@
  */
 import type { RunRenderer } from "../lib/cli-ui/run-renderer-types.js";
 import { LivenessHeartbeat } from "../lib/workflow/heartbeat.js";
-import type { ProgressCallback } from "../lib/workflow/types.js";
+import type { ProgressCallback, PhasePlanCallback } from "../lib/workflow/types.js";
 export interface ProgressWiring {
     renderer: RunRenderer | null;
     heartbeat: LivenessHeartbeat | null;
     onProgress: ProgressCallback | undefined;
+    /** #672 AC-2: forwarded to the orchestrator so batch-executor can hand the
+     *  resolved phase pipeline back to the renderer once it's known. */
+    onPhasePlan: PhasePlanCallback | undefined;
 }
 /**
  * Construct the renderer + heartbeat + onProgress callback for a run.
@@ -27,6 +30,13 @@ export declare function buildProgressWiring(args: {
     /** AC-23: when auto-detect mode is on, the renderer shows `Phase: detecting…`
      *  while spec runs (before the resolved plan is known). */
     autoDetectPhases?: boolean;
+    /** #672 AC-2: the base configured phase pipeline. In explicit-phase mode
+     *  (not auto-detect) this is known upfront, so every issue — including those
+     *  still queued behind the active one — can show its roadmap immediately
+     *  rather than only once it starts running. `setPhasePlan` later refines it
+     *  per issue (e.g. testgen/security-review insertion). Ignored in
+     *  auto-detect mode, where the plan isn't known until spec resolves it. */
+    basePhases?: string[];
     /** #624 Item 3 / D2: total allowed quality-loop iterations (from settings). */
     maxLoopIterations?: number;
 }): ProgressWiring;

package/dist/src/commands/run-progress.js

@@ -14,7 +14,7 @@ import { LivenessHeartbeat } from "../lib/workflow/heartbeat.js";
  * `tuiEnabled` and `quiet` are mutually exclusive with the renderer path.
  */
 export function buildProgressWiring(args) {
-    const { tuiEnabled, quiet, issueNumbers, phaseTimeoutSeconds, autoDetectPhases, maxLoopIterations, } = args;
+    const { tuiEnabled, quiet, issueNumbers, phaseTimeoutSeconds, autoDetectPhases, basePhases, maxLoopIterations, } = args;
     const heartbeat = quiet && !tuiEnabled
         ? new LivenessHeartbeat({ phaseTimeoutSeconds })
         : null;
@@ -36,8 +36,20 @@ export function buildProgressWiring(args) {
         })
         : null;
     if (renderer) {
+        // #672 AC-2: seed the planned pipeline at registration when it's known
+        // upfront (explicit-phase mode). This makes queued issues render their
+        // roadmap before they start, matching the issue's multi-row matrix
+        // mock-up. In auto-detect mode the plan isn't known yet, so we leave
+        // `plannedPhases` undefined and rely on `setPhasePlan` once spec resolves.
+        const seedPlan = !autoDetectPhases && basePhases && basePhases.length > 0
+            ? basePhases
+            : undefined;
         for (const issueNumber of issueNumbers) {
-            renderer.registerIssue({ issueNumber, autoDetect: autoDetectPhases });
+            renderer.registerIssue({
+                issueNumber,
+                autoDetect: autoDetectPhases,
+                plannedPhases: seedPlan,
+            });
         }
     }
     let onProgress;
@@ -72,5 +84,10 @@ export function buildProgressWiring(args) {
                 heartbeat.stop({ issueNumber: issue, phase });
         };
     }
-    return { renderer, heartbeat, onProgress };
+    // #672 AC-2: only the renderer path consumes a phase plan; quiet / TUI
+    // modes leave this undefined and the orchestrator no-ops the callback.
+    const onPhasePlan = renderer
+        ? (issue, phases) => renderer.setPhasePlan(issue, phases)
+        : undefined;
+    return { renderer, heartbeat, onProgress, onPhasePlan };
 }

package/dist/src/commands/run.js

@@ -72,12 +72,15 @@ export async function runCommand(issues, options) {
     const tuiEnabled = Boolean(options.experimentalTui) && Boolean(process.stdout.isTTY);
     // RunRenderer (#618) + LivenessHeartbeat (#574) wiring lives in
     // run-progress.ts to keep this adapter under the 200-LOC cap (#503 AC-2).
-    const { renderer, heartbeat, onProgress } = buildProgressWiring({
+    const { renderer, heartbeat, onProgress, onPhasePlan } = buildProgressWiring({
         tuiEnabled,
         quiet: Boolean(options.quiet),
         issueNumbers: resolved.issueNumbers,
         phaseTimeoutSeconds: settings.run.timeout,
         autoDetectPhases: resolved.autoDetectPhases,
+        // #672 AC-2: base pipeline so queued issues show their roadmap upfront in
+        // explicit-phase mode (ignored when auto-detect resolves the plan later).
+        basePhases: resolved.config.phases,
         // #624 Item 3 / D2: route the resolved maxIterations into the renderer so
         // `(attempt N/M)` and `loop N/M` reflect actual configured limits.
         maxLoopIterations: resolved.config.maxIterations,
@@ -97,6 +100,8 @@ export async function runCommand(issues, options) {
             const result = await RunOrchestrator.run({
                 ...init,
                 onProgress,
+                onPhasePlan,
+                phasePauseHandle: renderer ?? undefined,
                 onOrchestratorReady: (orch) => {
                     tuiHandle = renderTui(orch);
                 },
@@ -121,7 +126,12 @@ export async function runCommand(issues, options) {
     if (renderer)
         process.once("SIGINT", sigintHandler);
     try {
-        const result = await RunOrchestrator.run({ ...init, onProgress }, issues, batches);
+        const result = await RunOrchestrator.run({
+            ...init,
+            onProgress,
+            onPhasePlan,
+            phasePauseHandle: renderer ?? undefined,
+        }, issues, batches);
         // Record PR info in renderer state before summary so done rows show PR #s.
         if (renderer) {
             for (const r of result.results) {

package/dist/src/commands/watch.d.ts

@@ -9,6 +9,8 @@ export interface WatchCommandOptions {
     pollIntervalMs?: number;
     /** Abort signal for clean shutdown (tests). */
     signal?: AbortSignal;
+    /** Override cwd for resolving the pid file + archive root (test seam). */
+    cwd?: string;
 }
 export declare function watchCommand(argsAndOptions: {
     args: string[];