sequant 2.3.0 → 2.4.0

package/dist/src/lib/cli-ui/scrollback-harness.d.ts

@@ -0,0 +1,112 @@
+/**
+ * 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";
+export interface VirtualTerminalOptions {
+    rows: number;
+    cols: number;
+    /** Newline mode. POSIX shells default to ONLCR which translates `\n` to
+     *  `\r\n`, so most apps see "move down + col 0". Default true. */
+    onlcr?: boolean;
+}
+/**
+ * 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 declare class VirtualTerminal {
+    readonly rows: number;
+    readonly cols: number;
+    private readonly onlcr;
+    /** visible[row][col] = char (always single-codepoint slot). */
+    visible: string[][];
+    /** Scrollback grows oldest-first as rows shift off the top. */
+    scrollback: string[];
+    cursorRow: number;
+    cursorCol: number;
+    constructor(opts: VirtualTerminalOptions);
+    write(text: string): void;
+    /** Visible viewport as a list of trimmed-right rows. */
+    getVisibleLines(): string[];
+    /** Single multi-line string of (scrollback + visible). */
+    getAllText(): string;
+    /** Match count of the regex against (scrollback + visible). */
+    countOccurrences(pattern: RegExp): number;
+    private putChar;
+    private linefeed;
+    /** Returns the index AFTER the consumed escape sequence. */
+    private handleEscape;
+    private handleCSI;
+    private executeCSI;
+    private eraseLine;
+    private eraseFromCursorToEndOfLine;
+    private eraseFromStartOfLineToCursor;
+    private eraseFromCursorToEndOfScreen;
+    private eraseFromStartOfScreenToCursor;
+    private eraseScreen;
+}
+/**
+ * Bundle a VirtualTerminal with a real `log-update` instance writing into it
+ * and a matching `stdoutWrite` for renderer event-line writes. Both paths hit
+ * the same VT, mirroring real-terminal interleaving.
+ *
+ * Production runs frequently hit a width/height mismatch between what
+ * `log-update` reads from `process.stdout` and what the real terminal actually
+ * uses (e.g. `process.stdout.columns` is undefined under `npx` so log-update
+ * falls back to 80 while the terminal is 200 cols). Those mismatches cause
+ * `previousLineCount` to under- or over-count the rows log-update actually
+ * wrote, breaking `eraseLines` and leaving stale rows in scrollback. The
+ * `streamColumns` / `streamRows` overrides let tests reproduce this without
+ * needing a real PTY.
+ */
+export interface TerminalHarness {
+    vt: VirtualTerminal;
+    logUpdate: ReturnType<typeof createLogUpdate>;
+    stdoutWrite: (s: string) => void;
+    /**
+     * Out-of-band write that lands in the same VT as `logUpdate` and
+     * `stdoutWrite` — mirrors how a real pty merges stderr writes with stdout
+     * when both descriptors point at the same terminal. log-update has no
+     * knowledge of these writes, so they advance the cursor in ways
+     * `previousLineCount` cannot account for. Use this to reproduce the
+     * Mechanism #2-class bug (out-of-band writes break log-update's cursor
+     * model) that #647 AC-1 capture diagnosed.
+     */
+    stderrWrite: (s: string) => void;
+}
+export interface HarnessOptions extends VirtualTerminalOptions {
+    /**
+     * Width log-update is told about via `stream.columns`. Defaults to
+     * `opts.cols` (matched terminal). Override to simulate a mismatch where
+     * log-update wraps at one width but the real terminal wraps at another.
+     */
+    streamColumns?: number;
+    /**
+     * Height log-update is told about via `stream.rows`. Defaults to
+     * `opts.rows`. Override to simulate `process.stdout.rows = undefined`
+     * (the `npx` symptom): pass `undefined` explicitly via the harness's stream
+     * by setting this to a non-positive number — log-update then falls through
+     * to its internal `defaultHeight ?? 24`.
+     */
+    streamRows?: number;
+}
+export declare function createTerminalHarness(opts: HarnessOptions): TerminalHarness;

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/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

package/dist/src/lib/workflow/drivers/agent-driver.d.ts

@@ -5,6 +5,22 @@
  * Continue.dev, Copilot SDK, Cursor API) can be added by implementing this
  * interface without touching orchestration logic.
  */
+/**
+ * Resume handle for a previous agent session.
+ *
+ * Replaces the opaque `sessionId` string with a driver-tagged value that
+ * records the cwd the session was created in. Drivers use this to enforce
+ * cwd-safe resume (Claude Code: session storage is cwd-namespaced; Codex:
+ * cwd-independent SDK requires driver-side gating). See #674.
+ */
+export interface ResumeHandle {
+    /** Driver name that created this handle (e.g. "claude-code", "codex"). */
+    driver: string;
+    /** Driver-specific resume token (session id, thread id, etc.). */
+    token: string;
+    /** Absolute cwd the session was created in. */
+    originCwd: string;
+}
 /**
  * Configuration passed to an agent for phase execution.
  */
@@ -15,8 +31,17 @@ export interface AgentExecutionConfig {
     phaseTimeout: number;
     verbose: boolean;
     mcp: boolean;
-    /** Resume a previous session (driver-specific; ignored if unsupported) */
+    /**
+     * Resume a previous session (driver-specific; ignored if unsupported).
+     *
+     * @deprecated Use {@link resumeHandle}. The opaque `sessionId` field is
+     * retained for one release to keep in-flight `.sequant/state.json` records
+     * resumable across upgrade. Drivers MUST prefer `resumeHandle` when both
+     * are set. See #674.
+     */
     sessionId?: string;
+    /** Driver-tagged resume handle with originCwd for cwd-safe resume (#674). */
+    resumeHandle?: ResumeHandle;
     /** Callback for streaming output */
     onOutput?: (text: string) => void;
     /** Callback for stderr */
@@ -30,7 +55,14 @@ export interface AgentExecutionConfig {
 export interface AgentPhaseResult {
     success: boolean;
     output: string;
+    /**
+     * @deprecated Use {@link resumeHandle}. Retained as a mirror of
+     * `resumeHandle.token` for one release to ease state-file migration. See
+     * #674.
+     */
     sessionId?: string;
+    /** Driver-tagged resume handle for cwd-safe cross-phase resume (#674). */
+    resumeHandle?: ResumeHandle;
     error?: string;
     /** Last N lines of stderr captured via RingBuffer (#447) */
     stderrTail?: string[];
@@ -53,4 +85,19 @@ export interface AgentDriver {
     executePhase(prompt: string, config: AgentExecutionConfig): Promise<AgentPhaseResult>;
     /** Check if this driver is available/configured */
     isAvailable(): Promise<boolean>;
+    /**
+     * Decide whether a resume handle can be safely used for a target cwd.
+     *
+     * Implementations enforce the asymmetric resume contract (#674):
+     * - Claude Code: session storage is cwd-namespaced; resume only if cwds
+     *   match byte-equal.
+     * - Codex (when added in #497): runtime is cwd-independent; the driver
+     *   enforces cwd match (and AGENTS.md parity) to prevent silent
+     *   misexecution.
+     * - Drivers without a session-resume concept return `false`.
+     *
+     * Drivers MUST also verify `handle.driver === this.name` and reject
+     * cross-driver handles.
+     */
+    canResume(handle: ResumeHandle, targetCwd: string): boolean;
 }

package/dist/src/lib/workflow/drivers/aider.d.ts

@@ -5,12 +5,18 @@
  * for fully non-interactive phase execution. Sequant manages git,
  * not Aider.
  */
-import type { AgentDriver, AgentExecutionConfig, AgentPhaseResult } from "./agent-driver.js";
+import type { AgentDriver, AgentExecutionConfig, AgentPhaseResult, ResumeHandle } from "./agent-driver.js";
 import type { AiderSettings } from "../../settings.js";
 export declare class AiderDriver implements AgentDriver {
     name: string;
     private settings?;
     constructor(settings?: AiderSettings);
+    /**
+     * Aider has no session-resume concept: each invocation is a one-shot
+     * `aider --message <prompt>` against a fresh chat. There is no token to
+     * reattach to, so resume is always declined (#674).
+     */
+    canResume(handle: ResumeHandle, targetCwd: string): boolean;
     executePhase(prompt: string, config: AgentExecutionConfig): Promise<AgentPhaseResult>;
     isAvailable(): Promise<boolean>;
     /** Build the CLI argument list for aider. */