sequant 2.3.0 → 2.5.0

package/dist/src/lib/cli-ui/scrollback-harness.js

@@ -0,0 +1,294 @@
+/**
+ * Virtual-terminal harness for renderer regression tests (#647).
+ *
+ * The test stub embedded in TTYRenderer (see {@link
+ * ./run-renderer.ts#TTYTestStub}) mocks `log-update` itself — it cannot reveal
+ * whether the real `log-update` actually erases prior frames once the terminal
+ * scrolls. That gap is what allowed #624's fix to ship green while the
+ * underlying duplicate-header bug remained.
+ *
+ * This harness models a real terminal:
+ *   - bounded visible viewport (rows × cols)
+ *   - unbounded scrollback that captures every line that scrolls off the top
+ *   - the ANSI escape vocabulary that `log-update@7` + `ansi-escapes`
+ *     actually emit (cursor up/down/forward/back, eraseLine variants,
+ *     SGR colour stripping, private mode set/reset, save/restore)
+ *
+ * With it, a test can wire the production renderer through a real
+ * `createLogUpdate` instance, replay an event sequence, and assert on
+ * `(visible + scrollback)` to catch any duplicate-header rendering — the
+ * exact regression #647 was opened for.
+ */
+import { createLogUpdate } from "log-update";
+const ESC = "";
+/**
+ * Minimal vt100 model: visible grid + scrollback + cursor. Strips SGR colour
+ * codes (they're styling, not content) and ignores private-mode toggles
+ * (cursor hide/show). Implements the cursor and erase escapes that
+ * `log-update@7` actually emits.
+ */
+export class VirtualTerminal {
+    rows;
+    cols;
+    onlcr;
+    /** visible[row][col] = char (always single-codepoint slot). */
+    visible;
+    /** Scrollback grows oldest-first as rows shift off the top. */
+    scrollback = [];
+    cursorRow = 0;
+    cursorCol = 0;
+    constructor(opts) {
+        this.rows = opts.rows;
+        this.cols = opts.cols;
+        this.onlcr = opts.onlcr ?? true;
+        this.visible = Array.from({ length: this.rows }, () => Array(this.cols).fill(" "));
+    }
+    // ---------------------------------------------------------------- input
+    write(text) {
+        let i = 0;
+        while (i < text.length) {
+            const ch = text[i];
+            if (ch === ESC) {
+                i = this.handleEscape(text, i);
+                continue;
+            }
+            if (ch === "\n") {
+                this.linefeed();
+                i++;
+                continue;
+            }
+            if (ch === "\r") {
+                this.cursorCol = 0;
+                i++;
+                continue;
+            }
+            if (ch === "\b") {
+                if (this.cursorCol > 0)
+                    this.cursorCol--;
+                i++;
+                continue;
+            }
+            this.putChar(ch);
+            i++;
+        }
+    }
+    // ---------------------------------------------------------------- output
+    /** Visible viewport as a list of trimmed-right rows. */
+    getVisibleLines() {
+        return this.visible.map((row) => row.join("").replace(/\s+$/, ""));
+    }
+    /** Single multi-line string of (scrollback + visible). */
+    getAllText() {
+        const visibleText = this.getVisibleLines().join("\n");
+        if (this.scrollback.length === 0)
+            return visibleText;
+        return this.scrollback.join("\n") + "\n" + visibleText;
+    }
+    /** Match count of the regex against (scrollback + visible). */
+    countOccurrences(pattern) {
+        const text = this.getAllText();
+        const flags = pattern.flags.includes("g")
+            ? pattern.flags
+            : pattern.flags + "g";
+        const globalPattern = new RegExp(pattern.source, flags);
+        const matches = text.match(globalPattern);
+        return matches?.length ?? 0;
+    }
+    // ------------------------------------------------------- internal: text
+    putChar(ch) {
+        if (this.cursorCol >= this.cols) {
+            // Auto-wrap into the next row. Most terminals do this; log-update wraps
+            // upstream so this rarely triggers in practice.
+            this.cursorCol = 0;
+            this.linefeed();
+        }
+        this.visible[this.cursorRow][this.cursorCol] = ch;
+        this.cursorCol++;
+    }
+    linefeed() {
+        if (this.cursorRow + 1 < this.rows) {
+            this.cursorRow++;
+        }
+        else {
+            // Bottom of viewport: scroll the top row into scrollback.
+            const top = this.visible.shift();
+            this.scrollback.push(top.join("").replace(/\s+$/, ""));
+            this.visible.push(Array(this.cols).fill(" "));
+            // Cursor stays clamped at last visible row.
+        }
+        if (this.onlcr)
+            this.cursorCol = 0;
+    }
+    // --------------------------------------------------- internal: escapes
+    /** Returns the index AFTER the consumed escape sequence. */
+    handleEscape(text, start) {
+        // Bare ESC at end → consume.
+        if (start + 1 >= text.length)
+            return text.length;
+        const next = text[start + 1];
+        // CSI: ESC [ ... <final>
+        if (next === "[") {
+            return this.handleCSI(text, start + 2);
+        }
+        // OSC: ESC ] ... BEL or ESC \
+        if (next === "]") {
+            let i = start + 2;
+            while (i < text.length) {
+                if (text[i] === "")
+                    return i + 1;
+                if (text[i] === ESC && text[i + 1] === "\\")
+                    return i + 2;
+                i++;
+            }
+            return text.length;
+        }
+        // 2-byte non-CSI escapes: ESC 7 / ESC 8 (save/restore — cursor only,
+        // safe to ignore for our uses).
+        return start + 2;
+    }
+    handleCSI(text, start) {
+        let i = start;
+        let isPrivate = false;
+        if (text[i] === "?" || text[i] === ">" || text[i] === "<") {
+            isPrivate = true;
+            i++;
+        }
+        let params = "";
+        while (i < text.length && /[0-9;]/.test(text[i])) {
+            params += text[i];
+            i++;
+        }
+        if (i >= text.length)
+            return text.length;
+        const final = text[i];
+        i++;
+        this.executeCSI(params, final, isPrivate);
+        return i;
+    }
+    executeCSI(params, final, isPrivate) {
+        const parts = params.length === 0 ? [] : params.split(";").map((p) => parseInt(p, 10));
+        const n = (idx, def) => {
+            const v = parts[idx];
+            return v === undefined || isNaN(v) ? def : v;
+        };
+        // Private modes (e.g. ?25l/?25h cursor hide/show) — ignore.
+        if (isPrivate)
+            return;
+        switch (final) {
+            case "A": // cursor up
+                this.cursorRow = Math.max(0, this.cursorRow - n(0, 1));
+                return;
+            case "B": // cursor down (no scroll)
+                this.cursorRow = Math.min(this.rows - 1, this.cursorRow + n(0, 1));
+                return;
+            case "C": // cursor forward
+                this.cursorCol = Math.min(this.cols - 1, this.cursorCol + n(0, 1));
+                return;
+            case "D": // cursor back
+                this.cursorCol = Math.max(0, this.cursorCol - n(0, 1));
+                return;
+            case "E": // cursor next line
+                this.cursorRow = Math.min(this.rows - 1, this.cursorRow + n(0, 1));
+                this.cursorCol = 0;
+                return;
+            case "F": // cursor prev line
+                this.cursorRow = Math.max(0, this.cursorRow - n(0, 1));
+                this.cursorCol = 0;
+                return;
+            case "G": // cursor absolute column (1-based)
+                this.cursorCol = Math.min(this.cols - 1, Math.max(0, n(0, 1) - 1));
+                return;
+            case "H": // cursor position (1-based row;col)
+            case "f":
+                this.cursorRow = Math.min(this.rows - 1, Math.max(0, n(0, 1) - 1));
+                this.cursorCol = Math.min(this.cols - 1, Math.max(0, n(1, 1) - 1));
+                return;
+            case "J": {
+                // erase in display
+                const mode = n(0, 0);
+                if (mode === 0)
+                    this.eraseFromCursorToEndOfScreen();
+                else if (mode === 1)
+                    this.eraseFromStartOfScreenToCursor();
+                else if (mode === 2 || mode === 3)
+                    this.eraseScreen();
+                return;
+            }
+            case "K": {
+                // erase in line
+                const mode = n(0, 0);
+                if (mode === 0)
+                    this.eraseFromCursorToEndOfLine();
+                else if (mode === 1)
+                    this.eraseFromStartOfLineToCursor();
+                else if (mode === 2)
+                    this.eraseLine();
+                return;
+            }
+            case "S": // scroll up
+            case "T": // scroll down
+            case "m": // SGR colour — ignore (we don't model styling)
+            case "s": // save cursor
+            case "u": // restore cursor
+            case "n": // device status report — ignore
+            case "h": // set mode — ignore
+            case "l": // reset mode — ignore
+                return;
+        }
+    }
+    eraseLine() {
+        for (let c = 0; c < this.cols; c++)
+            this.visible[this.cursorRow][c] = " ";
+    }
+    eraseFromCursorToEndOfLine() {
+        for (let c = this.cursorCol; c < this.cols; c++)
+            this.visible[this.cursorRow][c] = " ";
+    }
+    eraseFromStartOfLineToCursor() {
+        for (let c = 0; c <= this.cursorCol; c++)
+            this.visible[this.cursorRow][c] = " ";
+    }
+    eraseFromCursorToEndOfScreen() {
+        this.eraseFromCursorToEndOfLine();
+        for (let r = this.cursorRow + 1; r < this.rows; r++) {
+            for (let c = 0; c < this.cols; c++)
+                this.visible[r][c] = " ";
+        }
+    }
+    eraseFromStartOfScreenToCursor() {
+        for (let r = 0; r < this.cursorRow; r++) {
+            for (let c = 0; c < this.cols; c++)
+                this.visible[r][c] = " ";
+        }
+        this.eraseFromStartOfLineToCursor();
+    }
+    eraseScreen() {
+        for (let r = 0; r < this.rows; r++) {
+            for (let c = 0; c < this.cols; c++)
+                this.visible[r][c] = " ";
+        }
+    }
+}
+export function createTerminalHarness(opts) {
+    const vt = new VirtualTerminal(opts);
+    const stream = {
+        write: (chunk) => {
+            vt.write(chunk);
+            return true;
+        },
+        columns: opts.streamColumns ?? opts.cols,
+        rows: opts.streamRows ?? opts.rows,
+        isTTY: true,
+    };
+    // log-update reads `stream.columns` / `stream.rows` defensively; the cast is
+    // safe because we exercise only those fields plus `write`.
+    const lu = createLogUpdate(stream, {
+        showCursor: true,
+    });
+    return {
+        vt,
+        logUpdate: lu,
+        stdoutWrite: (s) => vt.write(s),
+        stderrWrite: (s) => vt.write(s),
+    };
+}

package/dist/src/lib/merge-check/types.js

@@ -19,7 +19,7 @@ export const BatchVerdictSchema = z.enum(BATCH_VERDICTS);
  */
 export const DEFAULT_MIRROR_PAIRS = [
     { source: ".claude/skills", target: "templates/skills" },
-    { source: "hooks", target: "templates/hooks" },
+    { source: ".claude/hooks", target: "templates/hooks" },
 ];
 /**
  * Get the git ref to use for diff/merge operations on a branch.

package/dist/src/lib/relay/archive.js

@@ -57,6 +57,10 @@ export function archiveRelayDir(issue, options) {
                 copyFileSync(src, join(destDir, name));
             }
         }
+        // Split inbox/outbox counts (#645, Gap 5). Surfaces unanswered queries
+        // (inboxCount > outboxCount) when inspecting archives post-hoc.
+        const inboxCount = countLines(join(srcDir, RELAY_INBOX));
+        const outboxCount = countLines(join(srcDir, RELAY_OUTBOX));
         // Write meta.json.
         const meta = RelayArchiveMetaSchema.parse({
             issue,
@@ -64,6 +68,8 @@ export function archiveRelayDir(issue, options) {
             startedAt: options.startedAt,
             endedAt,
             messageCount: options.messageCount,
+            inboxCount,
+            outboxCount,
         });
         writeFileSync(join(destDir, "meta.json"), JSON.stringify(meta, null, 2), "utf-8");
         // Clear the working relay dir (inbox/outbox/cursor).

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

@@ -64,5 +64,7 @@ export declare const RelayArchiveMetaSchema: z.ZodObject<{
     startedAt: z.ZodString;
     endedAt: z.ZodString;
     messageCount: z.ZodNumber;
+    inboxCount: z.ZodOptional<z.ZodNumber>;
+    outboxCount: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type RelayArchiveMeta = z.infer<typeof RelayArchiveMetaSchema>;

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

@@ -72,5 +72,14 @@ export const RelayArchiveMetaSchema = z.object({
     phase: z.string(),
     startedAt: z.string().datetime(),
     endedAt: z.string().datetime(),
+    /** Total inbox + outbox messages exchanged during the run. */
     messageCount: z.number().int().nonnegative(),
+    /**
+     * Inbox messages (user → agent). Split out from `messageCount` (#645, Gap 5)
+     * so post-hoc inspection can spot unanswered queries (inboxCount > outboxCount).
+     * Optional for backward compatibility with archives written before this split.
+     */
+    inboxCount: z.number().int().nonnegative().optional(),
+    /** Outbox replies (agent → user). See `inboxCount` for context. */
+    outboxCount: z.number().int().nonnegative().optional(),
 });

package/dist/src/lib/settings.d.ts

@@ -235,6 +235,24 @@ export interface QASettings {
      */
     markdownOnlySafeCiPatterns: string[];
 }
+/**
+ * Gate policy for the `sequant ready` post-resolve A+ QA gate (#683).
+ *
+ * - `ac` (default): loop stops once no `AC_NOT_MET` verdict remains (ACs
+ *   objectively met). Remaining quality/polish gaps are documented in the gap
+ *   report but NOT auto-fixed — predictable, scope-respecting behavior for a
+ *   team engineer with a fixed agenda.
+ * - `a-plus` (opt-in): loop continues until `READY_FOR_MERGE`, auto-fixing
+ *   quality gaps along the way — max-quality behavior for a solo maintainer.
+ */
+export type ReadyPolicy = "ac" | "a-plus";
+/**
+ * Settings for the `sequant ready` command (#683).
+ */
+export interface ReadySettings {
+    /** Default gate policy. Overridable per-invocation with `--policy`. */
+    policy: ReadyPolicy;
+}
 /**
  * Full settings schema
  */
@@ -249,6 +267,8 @@ export interface SequantSettings {
     scopeAssessment: ScopeAssessmentSettings;
     /** QA skill settings */
     qa: QASettings;
+    /** `sequant ready` gate settings (#683) */
+    ready: ReadySettings;
 }
 /** Zod schema for RotationSettings */
 export declare const RotationSettingsSchema: z.ZodObject<{
@@ -346,6 +366,13 @@ export declare const QASettingsSchema: z.ZodObject<{
     markdownOnlyCiRelaxed: z.ZodDefault<z.ZodBoolean>;
     markdownOnlySafeCiPatterns: z.ZodDefault<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
+/** Zod schema for ReadySettings (#683) */
+export declare const ReadySettingsSchema: z.ZodObject<{
+    policy: z.ZodDefault<z.ZodEnum<{
+        ac: "ac";
+        "a-plus": "a-plus";
+    }>>;
+}, z.core.$strip>;
 /**
  * Zod schema for the full SequantSettings (AC-1, AC-5).
  *
@@ -428,6 +455,12 @@ export declare const SettingsSchema: z.ZodObject<{
         markdownOnlyCiRelaxed: z.ZodDefault<z.ZodBoolean>;
         markdownOnlySafeCiPatterns: z.ZodDefault<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>;
+    ready: z.ZodDefault<z.ZodObject<{
+        policy: z.ZodDefault<z.ZodEnum<{
+            ac: "ac";
+            "a-plus": "a-plus";
+        }>>;
+    }, z.core.$strip>>;
 }, z.core.$loose>;
 /** A single validation warning about an unknown or invalid setting */
 export interface SettingsWarning {
@@ -477,6 +510,7 @@ export declare const DEFAULT_SCOPE_ASSESSMENT_SETTINGS: ScopeAssessmentSettings;
  * Default QA settings
  */
 export declare const DEFAULT_QA_SETTINGS: QASettings;
+export declare const DEFAULT_READY_SETTINGS: ReadySettings;
 /**
  * Default settings
  */

package/dist/src/lib/settings.js

@@ -127,6 +127,10 @@ export const QASettingsSchema = z.object({
         .array(z.string())
         .default(["build (*)", "Plugin Structure Validation"]),
 });
+/** Zod schema for ReadySettings (#683) */
+export const ReadySettingsSchema = z.object({
+    policy: z.enum(["ac", "a-plus"]).default("ac"),
+});
 /**
  * Zod schema for the full SequantSettings (AC-1, AC-5).
  *
@@ -144,6 +148,7 @@ export const SettingsSchema = z
     agents: AgentSettingsSchema.default(() => AgentSettingsSchema.parse({})),
     scopeAssessment: ScopeAssessmentSettingsSchema.default(() => ScopeAssessmentSettingsSchema.parse({})),
     qa: QASettingsSchema.default(() => QASettingsSchema.parse({})),
+    ready: ReadySettingsSchema.default(() => ReadySettingsSchema.parse({})),
 })
     .passthrough();
 /**
@@ -151,7 +156,7 @@ export const SettingsSchema = z
  * Used to detect unknown/misspelled keys and produce warnings.
  */
 const KNOWN_KEYS = {
-    "": new Set(["version", "run", "agents", "scopeAssessment", "qa"]),
+    "": new Set(["version", "run", "agents", "scopeAssessment", "qa", "ready"]),
     run: new Set([
         "logJson",
         "logPath",
@@ -186,6 +191,7 @@ const KNOWN_KEYS = {
         "markdownOnlyCiRelaxed",
         "markdownOnlySafeCiPatterns",
     ]),
+    ready: new Set(["policy"]),
     "run.rotation": new Set(["enabled", "maxSizeMB", "maxFiles"]),
     "run.aider": new Set(["model", "editFormat", "extraArgs"]),
     "scopeAssessment.trivialThresholds": new Set([
@@ -323,6 +329,9 @@ export const DEFAULT_QA_SETTINGS = {
     markdownOnlyCiRelaxed: true,
     markdownOnlySafeCiPatterns: ["build (*)", "Plugin Structure Validation"],
 };
+export const DEFAULT_READY_SETTINGS = {
+    policy: "ac",
+};
 /**
  * Default settings
  */
@@ -348,6 +357,7 @@ export const DEFAULT_SETTINGS = {
     agents: DEFAULT_AGENT_SETTINGS,
     scopeAssessment: DEFAULT_SCOPE_ASSESSMENT_SETTINGS,
     qa: DEFAULT_QA_SETTINGS,
+    ready: DEFAULT_READY_SETTINGS,
 };
 /**
  * Validate aider-specific settings.
@@ -499,6 +509,12 @@ export function generateSettingsJsonc(settings) {
     lines.push(`    "model": ${JSON.stringify(settings.agents.model)},`);
     lines.push(`    // Isolate parallel agent groups in separate worktrees`);
     lines.push(`    "isolateParallel": ${JSON.stringify(settings.agents.isolateParallel)}`);
+    lines.push(`  },`);
+    lines.push("");
+    lines.push(`  // sequant ready — post-resolve A+ QA gate (#683)`);
+    lines.push(`  "ready": {`);
+    lines.push(`    // Gate policy: "ac" (stop at ACs met, report quality gaps) or "a-plus" (loop to READY_FOR_MERGE)`);
+    lines.push(`    "policy": ${JSON.stringify(settings.ready.policy)}`);
     lines.push(`  }`);
     lines.push("}");
     lines.push("");
@@ -646,6 +662,12 @@ Each threshold has \`yellow\` (warning) and \`red\` (split recommended) values:
 | \`markdownOnlyCiRelaxed\` | boolean | \`true\` | When diff touches only \`.md\` files, treat pending CI checks matching \`markdownOnlySafeCiPatterns\` as informational |
 | \`markdownOnlySafeCiPatterns\` | string[] | \`["build (*)", "Plugin Structure Validation"]\` | Glob patterns for CI checks that are safe to ignore when pending on a markdown-only diff |
 
+## \`ready\` — \`sequant ready\` Gate Settings (#683)
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| \`policy\` | enum | \`"ac"\` | Gate policy. \`"ac"\` loops until ACs are objectively met (no \`AC_NOT_MET\`), reporting but not auto-fixing quality gaps. \`"a-plus"\` loops until \`READY_FOR_MERGE\`, auto-fixing quality gaps. Override per-run with \`--policy ac\\|a-plus\`. |
+
 ---
 
 *Unknown keys are preserved but logged as warnings. This allows forward compatibility

package/dist/src/lib/workflow/batch-executor.js

@@ -260,7 +260,7 @@ export function getEnvConfig() {
     return config;
 }
 export async function executeBatch(issueNumbers, batchCtx) {
-    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 results = [];
     for (const issueNumber of issueNumbers) {
         // Check if shutdown was triggered
@@ -289,6 +289,8 @@ export async function executeBatch(issueNumbers, batchCtx) {
             packageManager,
             baseBranch,
             onProgress,
+            onPhasePlan,
+            phasePauseHandle,
         };
         const result = await runIssueWithLogging(ctx);
         results.push(result);
@@ -305,7 +307,7 @@ export async function executeBatch(issueNumbers, batchCtx) {
 }
 export async function runIssueWithLogging(ctx) {
     // Destructure context for use throughout the function
-    const { issueNumber, config, options, title: issueTitle, labels, services: { logWriter, stateManager, shutdownManager }, worktree, chain, packageManager, baseBranch, onProgress, } = ctx;
+    const { issueNumber, config, options, title: issueTitle, labels, services: { logWriter, stateManager, shutdownManager }, worktree, chain, packageManager, baseBranch, onProgress, onPhasePlan, phasePauseHandle, } = ctx;
     const worktreePath = worktree?.path;
     const branch = worktree?.branch;
     const chainMode = chain?.enabled;
@@ -313,7 +315,8 @@ export async function runIssueWithLogging(ctx) {
     const startTime = Date.now();
     const phaseResults = [];
     let loopTriggered = false;
-    let sessionId;
+    // Cross-phase resume token, driver-tagged and cwd-bound (#674).
+    let resumeHandle;
     // In parallel mode, suppress per-issue terminal output to prevent interleaving.
     // The caller (run.ts) handles progress display via updateProgress().
     const log = config.parallel ? () => { } : console.log.bind(console);
@@ -399,15 +402,15 @@ export async function runIssueWithLogging(ctx) {
         }
         const specStartTime = new Date();
         // Note: spec runs in main repo (not worktree) for planning
-        const specResult = await executePhaseWithRetry(issueNumber, "spec", withActivityHook(config, issueNumber, "spec", onProgress), sessionId, worktreePath, // Will be ignored for spec (non-isolated phase)
-        shutdownManager);
+        const specResult = await executePhaseWithRetry(issueNumber, "spec", withActivityHook(config, issueNumber, "spec", onProgress), resumeHandle, worktreePath, // Will be ignored for spec (non-isolated phase)
+        shutdownManager, phasePauseHandle);
         const specEndTime = new Date();
-        if (specResult.sessionId) {
-            sessionId = specResult.sessionId;
-            // Update session ID in state for resume capability
+        if (specResult.resumeHandle) {
+            resumeHandle = specResult.resumeHandle;
+            // Persist resume token + originCwd for cross-process resume (#674).
             if (stateManager) {
                 try {
-                    await stateManager.updateSessionId(issueNumber, specResult.sessionId);
+                    await stateManager.updateResumeHandle(issueNumber, specResult.resumeHandle);
                 }
                 catch {
                     // State tracking errors shouldn't stop execution
@@ -568,6 +571,20 @@ export async function runIssueWithLogging(ctx) {
             }
         }
     }
+    // #672 AC-2: surface the resolved phase pipeline to the renderer so it can
+    // seed pending cells for every phase before any one of them fires. This
+    // runs once per issue after all phase-list mutations (auto-detect, resume
+    // filter, testgen/security-review insertion). The full pipeline for the row
+    // is `spec` (if it already ran) plus the remaining `phases` array.
+    if (onPhasePlan) {
+        const fullPlan = specAlreadyRan ? ["spec", ...phases] : [...phases];
+        try {
+            onPhasePlan(issueNumber, fullPlan);
+        }
+        catch {
+            /* renderer wiring errors must not halt execution */
+        }
+    }
     // Build per-issue config with issue type metadata for skill env propagation
     const lowerLabelsForType = labels.map((l) => l.toLowerCase());
     const issueIsDocs = lowerLabelsForType.some((label) => DOCS_LABELS.some((docsLabel) => label === docsLabel));
@@ -610,15 +627,14 @@ export async function runIssueWithLogging(ctx) {
                 }
             }
             const phaseStartTime = new Date();
-            const result = await executePhaseWithRetry(issueNumber, phase, withActivityHook(issueConfig, issueNumber, phase, onProgress), sessionId, worktreePath, shutdownManager);
+            const result = await executePhaseWithRetry(issueNumber, phase, withActivityHook(issueConfig, issueNumber, phase, onProgress), resumeHandle, worktreePath, shutdownManager, phasePauseHandle);
             const phaseEndTime = new Date();
-            // Capture session ID for subsequent phases
-            if (result.sessionId) {
-                sessionId = result.sessionId;
-                // Update session ID in state for resume capability
+            // Capture resume handle for subsequent phases (#674).
+            if (result.resumeHandle) {
+                resumeHandle = result.resumeHandle;
                 if (stateManager) {
                     try {
-                        await stateManager.updateSessionId(issueNumber, result.sessionId);
+                        await stateManager.updateResumeHandle(issueNumber, result.resumeHandle);
                     }
                     catch {
                         // State tracking errors shouldn't stop execution
@@ -732,7 +748,7 @@ export async function runIssueWithLogging(ctx) {
                         promptContext: buildLoopContext(result),
                     };
                     const loopStartTime = new Date();
-                    const loopResult = await executePhaseWithRetry(issueNumber, "loop", withActivityHook(loopConfig, issueNumber, "loop", onProgress), sessionId, worktreePath, shutdownManager);
+                    const loopResult = await executePhaseWithRetry(issueNumber, "loop", withActivityHook(loopConfig, issueNumber, "loop", onProgress), resumeHandle, worktreePath, shutdownManager, phasePauseHandle);
                     const loopEndTime = new Date();
                     phaseResults.push(loopResult);
                     // Emit loop completion/failure progress event (AC-8)
@@ -757,8 +773,8 @@ export async function runIssueWithLogging(ctx) {
                             /* progress errors must not halt */
                         }
                     }
-                    if (loopResult.sessionId) {
-                        sessionId = loopResult.sessionId;
+                    if (loopResult.resumeHandle) {
+                        resumeHandle = loopResult.resumeHandle;
                     }
                     if (loopResult.success) {
                         // Continue to next iteration