sequant 2.3.0 → 2.4.0

package/dist/src/lib/workflow/drivers/aider.js

@@ -14,6 +14,15 @@ export class AiderDriver {
     constructor(settings) {
         this.settings = settings;
     }
+    /**
+     * 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).
+     */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    canResume(handle, targetCwd) {
+        return false;
+    }
     async executePhase(prompt, config) {
         const args = this.buildArgs(prompt, config.files);
         return new Promise((resolve) => {

package/dist/src/lib/workflow/drivers/claude-code.d.ts

@@ -4,7 +4,7 @@
  * Owns the `@anthropic-ai/claude-agent-sdk` import. No other file in the
  * orchestration layer should import the SDK directly.
  */
-import type { AgentDriver, AgentExecutionConfig, AgentPhaseResult } from "./agent-driver.js";
+import type { AgentDriver, AgentExecutionConfig, AgentPhaseResult, ResumeHandle } from "./agent-driver.js";
 export declare class ClaudeCodeDriver implements AgentDriver {
     name: string;
     /**
@@ -12,6 +12,22 @@ export declare class ClaudeCodeDriver implements AgentDriver {
      * Set after each executePhase() call.
      */
     private lastSessionId?;
+    /**
+     * Decide whether a resume handle can be used for a target cwd.
+     *
+     * Claude Code namespaces session storage by encoded cwd
+     * (`~/.claude/projects/<encoded-cwd>/<session-id>.jsonl`), so a session
+     * created in cwd A cannot be located when resuming from cwd B — the SDK
+     * returns `error_during_execution` ("No conversation found") rather than
+     * crashing (verified against `@anthropic-ai/claude-agent-sdk@0.3.142`,
+     * see #674).
+     *
+     * We use byte-equal comparison, not a normalized path: the SDK's storage
+     * key is derived from the literal cwd string, so normalizing here would
+     * risk false-positive resumes whose token would then miss on disk.
+     */
+    canResume(handle: ResumeHandle, targetCwd: string): boolean;
     executePhase(prompt: string, config: AgentExecutionConfig): Promise<AgentPhaseResult>;
+    private buildResumeHandle;
     isAvailable(): Promise<boolean>;
 }

package/dist/src/lib/workflow/drivers/claude-code.js

@@ -14,6 +14,25 @@ export class ClaudeCodeDriver {
      * Set after each executePhase() call.
      */
     lastSessionId;
+    /**
+     * Decide whether a resume handle can be used for a target cwd.
+     *
+     * Claude Code namespaces session storage by encoded cwd
+     * (`~/.claude/projects/<encoded-cwd>/<session-id>.jsonl`), so a session
+     * created in cwd A cannot be located when resuming from cwd B — the SDK
+     * returns `error_during_execution` ("No conversation found") rather than
+     * crashing (verified against `@anthropic-ai/claude-agent-sdk@0.3.142`,
+     * see #674).
+     *
+     * We use byte-equal comparison, not a normalized path: the SDK's storage
+     * key is derived from the literal cwd string, so normalizing here would
+     * risk false-positive resumes whose token would then miss on disk.
+     */
+    canResume(handle, targetCwd) {
+        if (handle.driver !== this.name)
+            return false;
+        return handle.originCwd === targetCwd;
+    }
     async executePhase(prompt, config) {
         const abortController = new AbortController();
         // Wire external abort signal
@@ -30,6 +49,23 @@ export class ClaudeCodeDriver {
         let capturedStderr = "";
         const stderrBuffer = new RingBuffer(50);
         const stdoutBuffer = new RingBuffer(50);
+        // Resolve resume token with cwd-safety check.
+        //
+        // Prefer the driver-tagged `resumeHandle` over the legacy `sessionId`
+        // string (#674). On cwd mismatch we silently drop the resume — Claude
+        // Code's cwd-mismatched resume is recoverable (`error_during_execution`,
+        // "No conversation found"), but starting fresh is the cleaner outcome
+        // than surfacing a per-phase error the caller can't act on.
+        let resumeToken;
+        if (config.resumeHandle &&
+            this.canResume(config.resumeHandle, config.cwd)) {
+            resumeToken = config.resumeHandle.token;
+        }
+        else if (!config.resumeHandle && config.sessionId) {
+            // Back-compat: legacy state (sessionId without originCwd) cannot prove
+            // cwd parity. Per #674's fail-safe rule, do NOT resume — start fresh.
+            resumeToken = undefined;
+        }
         try {
             // Get MCP servers config if enabled
             const mcpServers = config.mcp ? getMcpServersConfig() : undefined;
@@ -43,8 +79,8 @@ export class ClaudeCodeDriver {
                     tools: { type: "preset", preset: "claude_code" },
                     permissionMode: "bypassPermissions",
                     allowDangerouslySkipPermissions: true,
-                    // Resume from previous session if provided
-                    ...(config.sessionId ? { resume: config.sessionId } : {}),
+                    // Resume from previous session only when cwd matches origin (#674).
+                    ...(resumeToken ? { resume: resumeToken } : {}),
                     env: config.env,
                     ...(mcpServers ? { mcpServers } : {}),
                     stderr: (data) => {
@@ -84,12 +120,17 @@ export class ClaudeCodeDriver {
             }
             clearTimeout(timeoutId);
             this.lastSessionId = resultSessionId;
+            // Build the cwd-bound resume handle from the session created in
+            // `config.cwd`. `sessionId` is mirrored for one release (#674) so
+            // upgraded callers can still drive resume off the deprecated field.
+            const resumeHandle = this.buildResumeHandle(resultSessionId, config.cwd);
             if (resultMessage) {
                 if (resultMessage.subtype === "success") {
                     return {
                         success: true,
                         output: capturedOutput,
                         sessionId: resultSessionId,
+                        resumeHandle,
                         stderrTail: stderrBuffer.getLines(),
                         stdoutTail: stdoutBuffer.getLines(),
                     };
@@ -113,6 +154,7 @@ export class ClaudeCodeDriver {
                     success: false,
                     output: capturedOutput,
                     sessionId: resultSessionId,
+                    resumeHandle,
                     error,
                     stderrTail: stderrBuffer.getLines(),
                     stdoutTail: stdoutBuffer.getLines(),
@@ -122,6 +164,7 @@ export class ClaudeCodeDriver {
                 success: false,
                 output: capturedOutput,
                 sessionId: resultSessionId,
+                resumeHandle,
                 error: "No result received from Claude",
                 stderrTail: stderrBuffer.getLines(),
                 stdoutTail: stdoutBuffer.getLines(),
@@ -146,12 +189,18 @@ export class ClaudeCodeDriver {
                 success: false,
                 output: capturedOutput,
                 sessionId: resultSessionId,
+                resumeHandle: this.buildResumeHandle(resultSessionId, config.cwd),
                 error: error + stderrSuffix,
                 stderrTail: stderrBuffer.getLines(),
                 stdoutTail: stdoutBuffer.getLines(),
             };
         }
     }
+    buildResumeHandle(token, originCwd) {
+        if (!token)
+            return undefined;
+        return { driver: this.name, token, originCwd };
+    }
     async isAvailable() {
         try {
             // If we can import the SDK, it's available

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

@@ -6,7 +6,7 @@
  */
 import type { AgentDriver } from "./agent-driver.js";
 import type { AiderSettings } from "../../settings.js";
-export type { AgentDriver, AgentExecutionConfig, AgentPhaseResult, } from "./agent-driver.js";
+export type { AgentDriver, AgentExecutionConfig, AgentPhaseResult, ResumeHandle, } from "./agent-driver.js";
 export interface DriverOptions {
     aiderSettings?: AiderSettings;
 }

package/dist/src/lib/workflow/event-emitter.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Typed workflow event emitter (#504).
+ *
+ * Provides a strongly-typed `EventEmitter` for `RunOrchestrator` lifecycle
+ * events. Multiple consumers (TUI, MCP server, future webhooks) can subscribe
+ * without the orchestrator knowing they exist.
+ *
+ * Design notes:
+ * - Wraps Node's built-in `node:events.EventEmitter` (no third-party deps per
+ *   AC-2). The typing is compile-time only — at runtime this is a vanilla
+ *   `EventEmitter`.
+ * - `emit()` is overridden to invoke listeners through `Promise.allSettled`
+ *   so a slow or throwing listener can never crash the pipeline (AC-5). The
+ *   override returns `Promise<void>` so callers in critical paths can `await`
+ *   the wrapper; fire-and-forget callers (e.g. `progress` ticks) just drop
+ *   the returned promise.
+ * - The orchestrator coexists with the existing `onProgress` callback rather
+ *   than replacing it. `onProgress` remains the synchronous TUI render hook;
+ *   events are the async multi-subscriber surface. Consolidation is an
+ *   intentional non-goal (see issue #504, descope comment 2026-04-09).
+ *
+ * @module
+ */
+import type { QaVerdict } from "./run-log-schema.js";
+/** Issue lifecycle status surfaced through `issue_status_changed`. */
+export type IssueEventStatus = "queued" | "running" | "passed" | "failed";
+/**
+ * Base fields present on every workflow event payload.
+ *
+ * Payloads are JSON-serializable: only primitives and plain records, no
+ * class instances or circular references. This keeps MCP/webhook consumers
+ * cheap (`JSON.stringify(payload)` is always safe).
+ */
+export interface BaseEventPayload {
+    /** GitHub issue number this event is about. */
+    issueNumber: number;
+    /** ISO 8601 timestamp captured when the event was emitted. */
+    timestamp: string;
+}
+/** Payload for `run_started` / `run_completed`. */
+export interface RunEventPayload extends BaseEventPayload {
+    /** Wall-clock duration in seconds. Present on `run_completed` only. */
+    duration?: number;
+    /** Aggregate success across all phases. Present on `run_completed` only. */
+    success?: boolean;
+}
+/** Payload for `phase_started`. */
+export interface PhaseStartedPayload extends BaseEventPayload {
+    /** Phase name (e.g. `spec`, `exec`, `qa`). */
+    phase: string;
+    /** Outer-loop iteration (1-based). Present when running under quality-loop. */
+    iteration?: number;
+}
+/** Payload for `phase_completed`. */
+export interface PhaseCompletedPayload extends BaseEventPayload {
+    phase: string;
+    /** Phase wall-clock duration in seconds (matches `PhaseLog.durationSeconds`). */
+    duration: number;
+    iteration?: number;
+}
+/** Payload for `phase_failed`. */
+export interface PhaseFailedPayload extends BaseEventPayload {
+    phase: string;
+    duration?: number;
+    /** Stringified error message. Class instances are flattened to strings. */
+    error: string;
+    iteration?: number;
+}
+/** Payload for `issue_status_changed`. */
+export interface IssueStatusChangedPayload extends BaseEventPayload {
+    /** Previous lifecycle status. */
+    from: IssueEventStatus;
+    /** New lifecycle status. */
+    to: IssueEventStatus;
+}
+/** Payload for `qa_verdict`. Emitted once per QA phase that produces a verdict. */
+export interface QaVerdictPayload extends BaseEventPayload {
+    phase: "qa";
+    verdict: QaVerdict;
+}
+/** Payload for `progress` (sub-phase activity ping, ~10 Hz). */
+export interface ProgressPayload extends BaseEventPayload {
+    phase: string;
+    /** Short one-line snippet for the dashboard activity row. */
+    text?: string;
+}
+/**
+ * Discriminated map of event name → payload type. Add new events by
+ * extending this map; the `emit`/`on`/`off` overloads below pick them up
+ * automatically. Reject `string` index signatures so consumers cannot
+ * subscribe to typo'd event names without a TypeScript error (AC-1, AC-2).
+ *
+ * Event names use `snake_case` intentionally — they match the issue body and
+ * common JSON-payload conventions, and they are part of the public contract
+ * for MCP / webhook consumers. Payload field names stay `camelCase`. Do not
+ * "normalize" the event-name casing.
+ */
+export interface WorkflowEvents {
+    run_started: RunEventPayload;
+    run_completed: RunEventPayload;
+    phase_started: PhaseStartedPayload;
+    phase_completed: PhaseCompletedPayload;
+    phase_failed: PhaseFailedPayload;
+    issue_status_changed: IssueStatusChangedPayload;
+    qa_verdict: QaVerdictPayload;
+    progress: ProgressPayload;
+}
+/** Listener signature for a given event name. */
+export type WorkflowEventListener<E extends keyof WorkflowEvents> = (payload: WorkflowEvents[E]) => void | Promise<void>;
+/**
+ * Build an ISO 8601 timestamp for an event payload. Centralized so tests can
+ * inject a fixed clock via the constructor.
+ *
+ * @internal
+ */
+export type Clock = () => Date;
+/**
+ * Typed wrapper around `node:events.EventEmitter`.
+ *
+ * Type parameter `E` is the event-name → payload map. `on`, `off`, and
+ * `emit` are all narrowed to that map; passing an unknown event name fails
+ * compilation (AC-2).
+ */
+export declare class WorkflowEventEmitter {
+    private readonly inner;
+    private readonly clock;
+    private readonly onListenerError;
+    constructor(opts?: {
+        clock?: Clock;
+        /**
+         * Invoked whenever a listener throws or rejects. Defaults to a no-op
+         * because rejection logging is the orchestrator's call (it knows whether
+         * `verbose` is enabled). Tests use this to assert isolation.
+         */
+        onListenerError?: (eventName: string, error: unknown) => void;
+    });
+    /** Register a listener for the given event. */
+    on<E extends keyof WorkflowEvents>(event: E, listener: WorkflowEventListener<E>): this;
+    /** Remove a previously registered listener. */
+    off<E extends keyof WorkflowEvents>(event: E, listener: WorkflowEventListener<E>): this;
+    /** Number of listeners attached to `event`. Useful in tests. */
+    listenerCount<E extends keyof WorkflowEvents>(event: E): number;
+    /** Drop all listeners. Call from `RunOrchestrator` teardown to avoid leaks. */
+    removeAllListeners(): this;
+    /**
+     * Emit an event. Listeners are invoked through `Promise.allSettled` so a
+     * single misbehaving subscriber cannot crash the pipeline (AC-5).
+     *
+     * Returns `Promise<void>` so critical-path callers may `await`. Fire-and-
+     * forget callers (`progress`, etc.) ignore the returned promise — the
+     * `Promise.allSettled` swallowing handles unhandled rejection warnings.
+     *
+     * The `timestamp` field on the payload is populated automatically when
+     * absent so call sites stay terse.
+     */
+    emit<E extends keyof WorkflowEvents>(event: E, payload: Omit<WorkflowEvents[E], "timestamp"> & Partial<Pick<WorkflowEvents[E], "timestamp">>): Promise<void>;
+}

package/dist/src/lib/workflow/event-emitter.js

@@ -0,0 +1,102 @@
+/**
+ * Typed workflow event emitter (#504).
+ *
+ * Provides a strongly-typed `EventEmitter` for `RunOrchestrator` lifecycle
+ * events. Multiple consumers (TUI, MCP server, future webhooks) can subscribe
+ * without the orchestrator knowing they exist.
+ *
+ * Design notes:
+ * - Wraps Node's built-in `node:events.EventEmitter` (no third-party deps per
+ *   AC-2). The typing is compile-time only — at runtime this is a vanilla
+ *   `EventEmitter`.
+ * - `emit()` is overridden to invoke listeners through `Promise.allSettled`
+ *   so a slow or throwing listener can never crash the pipeline (AC-5). The
+ *   override returns `Promise<void>` so callers in critical paths can `await`
+ *   the wrapper; fire-and-forget callers (e.g. `progress` ticks) just drop
+ *   the returned promise.
+ * - The orchestrator coexists with the existing `onProgress` callback rather
+ *   than replacing it. `onProgress` remains the synchronous TUI render hook;
+ *   events are the async multi-subscriber surface. Consolidation is an
+ *   intentional non-goal (see issue #504, descope comment 2026-04-09).
+ *
+ * @module
+ */
+import { EventEmitter } from "node:events";
+const defaultClock = () => new Date();
+/**
+ * Typed wrapper around `node:events.EventEmitter`.
+ *
+ * Type parameter `E` is the event-name → payload map. `on`, `off`, and
+ * `emit` are all narrowed to that map; passing an unknown event name fails
+ * compilation (AC-2).
+ */
+export class WorkflowEventEmitter {
+    inner = new EventEmitter();
+    clock;
+    onListenerError;
+    constructor(opts) {
+        this.clock = opts?.clock ?? defaultClock;
+        this.onListenerError = opts?.onListenerError ?? (() => { });
+        // Effectively no listener cap — multiple consumers (TUI, MCP, log writer
+        // in the future) can subscribe to popular events like `progress`.
+        this.inner.setMaxListeners(0);
+    }
+    /** Register a listener for the given event. */
+    on(event, listener) {
+        this.inner.on(event, listener);
+        return this;
+    }
+    /** Remove a previously registered listener. */
+    off(event, listener) {
+        this.inner.off(event, listener);
+        return this;
+    }
+    /** Number of listeners attached to `event`. Useful in tests. */
+    listenerCount(event) {
+        return this.inner.listenerCount(event);
+    }
+    /** Drop all listeners. Call from `RunOrchestrator` teardown to avoid leaks. */
+    removeAllListeners() {
+        this.inner.removeAllListeners();
+        return this;
+    }
+    /**
+     * Emit an event. Listeners are invoked through `Promise.allSettled` so a
+     * single misbehaving subscriber cannot crash the pipeline (AC-5).
+     *
+     * Returns `Promise<void>` so critical-path callers may `await`. Fire-and-
+     * forget callers (`progress`, etc.) ignore the returned promise — the
+     * `Promise.allSettled` swallowing handles unhandled rejection warnings.
+     *
+     * The `timestamp` field on the payload is populated automatically when
+     * absent so call sites stay terse.
+     */
+    emit(event, payload) {
+        const finalPayload = {
+            ...payload,
+            timestamp: payload.timestamp ?? this.clock().toISOString(),
+        };
+        const listeners = this.inner.listeners(event);
+        if (listeners.length === 0) {
+            return Promise.resolve();
+        }
+        // Wrap each listener in `Promise.resolve().then(() => listener(payload))`
+        // so synchronous throws are reified into rejections before
+        // `Promise.allSettled` runs. Without the resolve-then trampoline, a
+        // synchronous throw inside a non-async listener would propagate
+        // immediately and bypass `allSettled`.
+        const settled = Promise.allSettled(listeners.map((listener) => Promise.resolve().then(() => listener(finalPayload))));
+        return settled.then((results) => {
+            for (const r of results) {
+                if (r.status === "rejected") {
+                    try {
+                        this.onListenerError(event, r.reason);
+                    }
+                    catch {
+                        /* swallow — error handler must not propagate */
+                    }
+                }
+            }
+        });
+    }
+}

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

@@ -0,0 +1,32 @@
+/**
+ * Renderer-aware notice routing (#647 AC-3).
+ *
+ * Lives in its own module so both `phase-executor` and `run-orchestrator`
+ * can import without creating a backwards dependency (orchestrator → executor).
+ *
+ * @module
+ */
+import type { PhasePauseHandle } from "./types.js";
+/**
+ * Print a line to stdout while the renderer is active without breaking
+ * log-update's cursor model.
+ *
+ * `log-update` tracks `previousLineCount` from its own writes only; any
+ * out-of-band write to the same pty advances the cursor without its
+ * knowledge, so the next `eraseLines(previousLineCount)` undershoots and
+ * strands the prior frame's top rows in scrollback as duplicate headers.
+ *
+ * Routing:
+ *   - With a `PhasePauseHandle` (TTY run): route through `appendNotice`,
+ *     which clears the live zone, writes through the renderer's own
+ *     stdout channel, then redraws. log-update's bookkeeping stays
+ *     correct because the clear+redraw goes through the same path as
+ *     a normal event line.
+ *   - Without a handle (quiet mode / non-TTY / orchestrator): fall back
+ *     to `console.log` — there's no live zone to corrupt.
+ *
+ * Callers in `phase-executor.ts` / `run-orchestrator.ts` must use this
+ * helper instead of raw `console.log` — enforced by ESLint
+ * `no-restricted-syntax` rule in `eslint.config.js`.
+ */
+export declare function bracketedConsoleLog(spinner: PhasePauseHandle | undefined, message: string): void;

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

@@ -0,0 +1,38 @@
+/**
+ * Renderer-aware notice routing (#647 AC-3).
+ *
+ * Lives in its own module so both `phase-executor` and `run-orchestrator`
+ * can import without creating a backwards dependency (orchestrator → executor).
+ *
+ * @module
+ */
+/**
+ * Print a line to stdout while the renderer is active without breaking
+ * log-update's cursor model.
+ *
+ * `log-update` tracks `previousLineCount` from its own writes only; any
+ * out-of-band write to the same pty advances the cursor without its
+ * knowledge, so the next `eraseLines(previousLineCount)` undershoots and
+ * strands the prior frame's top rows in scrollback as duplicate headers.
+ *
+ * Routing:
+ *   - With a `PhasePauseHandle` (TTY run): route through `appendNotice`,
+ *     which clears the live zone, writes through the renderer's own
+ *     stdout channel, then redraws. log-update's bookkeeping stays
+ *     correct because the clear+redraw goes through the same path as
+ *     a normal event line.
+ *   - Without a handle (quiet mode / non-TTY / orchestrator): fall back
+ *     to `console.log` — there's no live zone to corrupt.
+ *
+ * Callers in `phase-executor.ts` / `run-orchestrator.ts` must use this
+ * helper instead of raw `console.log` — enforced by ESLint
+ * `no-restricted-syntax` rule in `eslint.config.js`.
+ */
+export function bracketedConsoleLog(spinner, message) {
+    if (spinner) {
+        spinner.appendNotice(message);
+    }
+    else {
+        console.log(message);
+    }
+}

package/dist/src/lib/workflow/phase-executor.d.ts

@@ -8,18 +8,9 @@
  * is agent-agnostic.
  */
 import { ShutdownManager } from "../shutdown.js";
-/**
- * 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).
- */
-export interface PhasePauseHandle {
-    pause(): void;
-    resume(): void;
-}
-import { Phase, ExecutionConfig, PhaseResult, QaVerdict } from "./types.js";
+import { Phase, ExecutionConfig, PhaseResult, QaVerdict, PhasePauseHandle } from "./types.js";
 import type { QaSummary } from "./run-log-schema.js";
-import type { AgentPhaseResult } from "./drivers/index.js";
+import type { AgentPhaseResult, ResumeHandle } from "./drivers/index.js";
 /**
  * Leading + trailing throttle. Fires the wrapped callback immediately on the
  * first call, drops subsequent calls that arrive inside `intervalMs` but
@@ -40,16 +31,10 @@ export declare function createThrottledReporter(fn: (text: string) => void, inte
     report(text: string): void;
     cancel(): void;
 };
-/**
- * Spec-specific retry configuration.
- * Spec failures have a higher failure rate (~8.6%) than other phases due to
- * transient GitHub API issues and rate limits. One extra retry with backoff
- * recovers most of these without user intervention.
- */
 /** @internal Exported for testing only */
-export declare const SPEC_RETRY_BACKOFF_MS = 5000;
+export declare const SPEC_RETRY_BACKOFF_MS: number;
 /** @internal Exported for testing only */
-export declare const SPEC_EXTRA_RETRIES = 1;
+export declare const SPEC_EXTRA_RETRIES: number;
 export declare function parseQaVerdict(output: string): QaVerdict | null;
 /**
  * Parse condensed QA summary from QA phase output (#434).
@@ -124,6 +109,7 @@ export declare function hasExecChanges(cwd: string): boolean;
  */
 export declare function mapAgentSuccessToPhaseResult(phase: Phase, agentResult: AgentPhaseResult, durationSeconds: number, cwd: string): PhaseResult & {
     sessionId?: string;
+    resumeHandle?: ResumeHandle;
 };
 /**
  * Get the prompt for a phase with the issue number substituted.
@@ -137,8 +123,9 @@ export declare function getPhasePrompt(phase: Phase, issueNumber: number, agent?
 /**
  * Execute a single phase for an issue using the configured AgentDriver.
  */
-declare function executePhase(issueNumber: number, phase: Phase, config: ExecutionConfig, sessionId?: string, worktreePath?: string, shutdownManager?: ShutdownManager, spinner?: PhasePauseHandle): Promise<PhaseResult & {
+declare function executePhase(issueNumber: number, phase: Phase, config: ExecutionConfig, resumeHandle?: ResumeHandle, worktreePath?: string, shutdownManager?: ShutdownManager, spinner?: PhasePauseHandle): Promise<PhaseResult & {
     sessionId?: string;
+    resumeHandle?: ResumeHandle;
 }>;
 /**
  * Execute a phase with automatic retry for cold-start failures and MCP fallback.
@@ -154,11 +141,12 @@ declare function executePhase(issueNumber: number, phase: Phase, config: Executi
 /**
  * @internal Exported for testing only
  */
-export declare function executePhaseWithRetry(issueNumber: number, phase: Phase, config: ExecutionConfig, sessionId?: string, worktreePath?: string, shutdownManager?: ShutdownManager, spinner?: PhasePauseHandle, 
+export declare function executePhaseWithRetry(issueNumber: number, phase: Phase, config: ExecutionConfig, resumeHandle?: ResumeHandle, worktreePath?: string, shutdownManager?: ShutdownManager, spinner?: PhasePauseHandle, 
 /** @internal Injected for testing — defaults to module-level executePhase */
 executePhaseFn?: typeof executePhase, 
 /** @internal Injected for testing — defaults to setTimeout-based delay */
 delayFn?: (ms: number) => Promise<void>): Promise<PhaseResult & {
     sessionId?: string;
+    resumeHandle?: ResumeHandle;
 }>;
 export {};