sequant 2.2.0 → 2.4.0

package/dist/src/lib/workflow/config-resolver.js

@@ -146,6 +146,9 @@ export function buildExecutionConfig(mergedOptions, settings, issueCount) {
         : (settings.run.retry ?? true);
     const isSequential = mergedOptions.sequential ?? false;
     const isParallel = !isSequential && issueCount > 1;
+    // `--no-relay` arrives from Commander as `mergedOptions.relay === false`;
+    // explicit `false` overrides settings, otherwise settings/default win.
+    const relayEnabled = mergedOptions.relay === false ? false : (settings.run.relay ?? true);
     return {
         ...DEFAULT_CONFIG,
         phases: explicitPhases ?? DEFAULT_PHASES,
@@ -163,5 +166,6 @@ export function buildExecutionConfig(mergedOptions, settings, issueCount) {
         agent: mergedOptions.agent ?? settings.run.agent,
         aiderSettings: settings.run.aider,
         isolateParallel: mergedOptions.isolateParallel,
+        relayEnabled,
     };
 }

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

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/heartbeat.d.ts

@@ -0,0 +1,71 @@
+import type { ShutdownManager } from "../shutdown.js";
+export interface LivenessHeartbeatOptions {
+    /** Polling cadence for heartbeat ticks. Default: 30_000ms */
+    pollIntervalMs?: number;
+    /** Stall threshold (mtime gap) before warning fires. Default: 5min */
+    stallThresholdMs?: number;
+    /** Liveness file whose mtime is the activity proxy. Default: .sequant/state.json */
+    livenessFile?: string;
+    /** When false, no timer is started (heartbeat fully suppressed). Default: true */
+    enabled?: boolean;
+    /**
+     * Per-phase timeout in seconds, used for the "phase timeout in N" suffix
+     * on stall warnings. When omitted, suffix is dropped.
+     */
+    phaseTimeoutSeconds?: number;
+    /** Optional ShutdownManager for graceful cleanup */
+    shutdownManager?: ShutdownManager;
+    /** Override TTY detection (testing). Default: process.stdout.isTTY */
+    isTTY?: boolean;
+    /** Override clock (testing). Default: Date.now */
+    now?: () => number;
+    /** Override stdout writer (testing). Default: process.stdout.write */
+    stdoutWrite?: (s: string) => void;
+    /** Override stderr writer (testing). Default: process.stderr.write */
+    stderrWrite?: (s: string) => void;
+}
+interface PhaseKey {
+    issueNumber: number;
+    phase: string;
+}
+export declare class LivenessHeartbeat {
+    private readonly pollIntervalMs;
+    private readonly stallThresholdMs;
+    private readonly livenessFile;
+    private readonly enabled;
+    private readonly phaseTimeoutSeconds?;
+    private readonly shutdownManager?;
+    private readonly tty;
+    private readonly now;
+    private readonly stdoutWrite;
+    private readonly stderrWrite;
+    private readonly phases;
+    private timer;
+    private stopped;
+    private cleanupRegistered;
+    constructor(options?: LivenessHeartbeatOptions);
+    /**
+     * Begin tracking a phase. Starts the shared poll timer on first call.
+     * No-op if `enabled === false`.
+     */
+    start(entry: PhaseKey & {
+        startedAt: number;
+    }): void;
+    /**
+     * Stop tracking a specific phase. When the last phase is removed, the timer
+     * is cleared so no orphaned polls remain.
+     */
+    stop(key?: PhaseKey): void;
+    /**
+     * Dispose all tracked phases and clear the timer. Idempotent.
+     */
+    dispose(): void;
+    /** Test hook: drive a poll synchronously without waiting on real timers. */
+    tickNow(): void;
+    private tick;
+    private writeHeartbeat;
+    private writeStallWarning;
+}
+/** Convenience factory mirroring `phaseSpinner()`. */
+export declare function livenessHeartbeat(options?: LivenessHeartbeatOptions): LivenessHeartbeat;
+export {};