sequant 2.1.2 → 2.3.0

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 {};

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

@@ -0,0 +1,194 @@
+/**
+ * LivenessHeartbeat — `-q` mode liveness signal + stall warning.
+ *
+ * Surfaces a per-phase liveness line (TTY only) and a one-shot stall warning
+ * (TTY and non-TTY) so users can distinguish "agent working" from "process hung"
+ * without inspecting `state.json` or `ps`/`lsof`.
+ *
+ * Liveness source: mtime of `.sequant/state.json` — written 3-10x per phase by
+ * `StateManager.saveState()`. Zero new infrastructure.
+ *
+ * @see Issue #574
+ */
+import * as fs from "fs";
+import { formatElapsedTime } from "../cli-ui/format.js";
+const DEFAULT_POLL_INTERVAL_MS = 30_000;
+const DEFAULT_STALL_THRESHOLD_MS = 5 * 60_000;
+const DEFAULT_LIVENESS_FILE = ".sequant/state.json";
+const CLEANUP_NAME = "liveness-heartbeat";
+function keyFor(k) {
+    return `${k.issueNumber}:${k.phase}`;
+}
+/**
+ * Format the stall window's elapsed seconds. Floors to whole seconds.
+ */
+function formatStall(seconds) {
+    return formatElapsedTime(Math.floor(seconds));
+}
+export class LivenessHeartbeat {
+    pollIntervalMs;
+    stallThresholdMs;
+    livenessFile;
+    enabled;
+    phaseTimeoutSeconds;
+    shutdownManager;
+    tty;
+    now;
+    stdoutWrite;
+    stderrWrite;
+    phases = new Map();
+    timer = null;
+    stopped = false;
+    cleanupRegistered = false;
+    constructor(options = {}) {
+        this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+        this.stallThresholdMs =
+            options.stallThresholdMs ?? DEFAULT_STALL_THRESHOLD_MS;
+        this.livenessFile = options.livenessFile ?? DEFAULT_LIVENESS_FILE;
+        this.enabled = options.enabled ?? true;
+        this.phaseTimeoutSeconds = options.phaseTimeoutSeconds;
+        this.shutdownManager = options.shutdownManager;
+        this.tty = options.isTTY ?? Boolean(process.stdout.isTTY);
+        this.now = options.now ?? Date.now;
+        this.stdoutWrite =
+            options.stdoutWrite ?? ((s) => void process.stdout.write(s));
+        this.stderrWrite =
+            options.stderrWrite ?? ((s) => void process.stderr.write(s));
+    }
+    /**
+     * Begin tracking a phase. Starts the shared poll timer on first call.
+     * No-op if `enabled === false`.
+     */
+    start(entry) {
+        if (!this.enabled || this.stopped)
+            return;
+        const key = keyFor(entry);
+        this.phases.set(key, {
+            issueNumber: entry.issueNumber,
+            phase: entry.phase,
+            startedAt: entry.startedAt,
+            warningFired: false,
+        });
+        if (this.timer === null) {
+            this.timer = setInterval(() => this.tick(), this.pollIntervalMs);
+            // Don't keep the event loop alive solely for the heartbeat.
+            if (typeof this.timer.unref === "function")
+                this.timer.unref();
+        }
+        if (this.shutdownManager && !this.cleanupRegistered) {
+            this.shutdownManager.registerCleanup(CLEANUP_NAME, async () => {
+                this.dispose();
+            });
+            this.cleanupRegistered = true;
+        }
+    }
+    /**
+     * Stop tracking a specific phase. When the last phase is removed, the timer
+     * is cleared so no orphaned polls remain.
+     */
+    stop(key) {
+        if (key) {
+            this.phases.delete(keyFor(key));
+        }
+        else {
+            this.phases.clear();
+        }
+        // Clear the timer when no phases remain so we don't poll uselessly between
+        // phases. We do NOT call dispose() here — that would set `stopped = true`
+        // and silently no-op the next start() in a sequential single-issue run
+        // (spec → stop → exec). Terminal teardown is dispose() called from the
+        // run.ts `finally` block.
+        if (this.phases.size === 0 && this.timer !== null) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    /**
+     * Dispose all tracked phases and clear the timer. Idempotent.
+     */
+    dispose() {
+        this.stopped = true;
+        this.phases.clear();
+        if (this.timer !== null) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        if (this.shutdownManager && this.cleanupRegistered) {
+            this.shutdownManager.unregisterCleanup(CLEANUP_NAME);
+            this.cleanupRegistered = false;
+        }
+    }
+    /** Test hook: drive a poll synchronously without waiting on real timers. */
+    tickNow() {
+        this.tick();
+    }
+    tick() {
+        if (this.stopped || this.phases.size === 0)
+            return;
+        const now = this.now();
+        for (const entry of this.phases.values()) {
+            let mtimeMs;
+            try {
+                const stat = fs.statSync(this.livenessFile);
+                mtimeMs = stat.mtimeMs;
+            }
+            catch {
+                // ENOENT (state.json not yet written) or EACCES — treat as no signal.
+                // Skip both heartbeat and stall logic this tick.
+                mtimeMs = null;
+            }
+            if (mtimeMs === null)
+                continue;
+            const sinceActivityMs = Math.max(0, now - mtimeMs);
+            const elapsedSinceStartMs = Math.max(0, now - entry.startedAt);
+            // AC-1: TTY heartbeat line — rewrite via \r.
+            if (this.tty) {
+                this.writeHeartbeat(entry, elapsedSinceStartMs, sinceActivityMs);
+            }
+            // AC-2: One-shot stall warning (TTY and non-TTY).
+            if (sinceActivityMs >= this.stallThresholdMs) {
+                if (!entry.warningFired) {
+                    this.writeStallWarning(entry, sinceActivityMs, elapsedSinceStartMs);
+                    entry.warningFired = true;
+                }
+            }
+            else if (entry.warningFired) {
+                // Activity resumed — reset for the next stall window.
+                entry.warningFired = false;
+            }
+        }
+    }
+    writeHeartbeat(entry, elapsedSinceStartMs, sinceActivityMs) {
+        if (this.stopped)
+            return;
+        const elapsed = formatElapsedTime(Math.floor(elapsedSinceStartMs / 1000));
+        const sinceActivity = formatElapsedTime(Math.floor(sinceActivityMs / 1000));
+        // \r rewrites current line; \x1b[K clears the rest in case the new line is
+        // shorter than the old one.
+        const line = `\r  ▸ #${entry.issueNumber}  ${entry.phase}  (${elapsed} elapsed, last log update ${sinceActivity} ago)`;
+        this.stdoutWrite(line);
+    }
+    writeStallWarning(entry, sinceActivityMs, elapsedSinceStartMs) {
+        if (this.stopped)
+            return;
+        const stallStr = formatStall(sinceActivityMs / 1000);
+        let suffix = "";
+        if (this.phaseTimeoutSeconds !== undefined) {
+            const remaining = this.phaseTimeoutSeconds - elapsedSinceStartMs / 1000;
+            if (remaining > 0) {
+                suffix = ` (phase timeout in ${formatElapsedTime(Math.floor(remaining))})`;
+            }
+        }
+        // Prefix \r\x1b[K to clear any in-flight TTY heartbeat on this line, then
+        // emit the warning on its own line. Non-TTY mode prints leading control
+        // chars too — they are inert when not interpreted, and matter for TTY co-
+        // existence with the heartbeat rewrite.
+        const prefix = this.tty ? "\r" : "";
+        const line = `${prefix}  ⚠ #${entry.issueNumber}  ${entry.phase}  no log activity for ${stallStr}${suffix}\n`;
+        this.stderrWrite(line);
+    }
+}
+/** Convenience factory mirroring `phaseSpinner()`. */
+export function livenessHeartbeat(options) {
+    return new LivenessHeartbeat(options);
+}

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

@@ -8,9 +8,38 @@
  * is agent-agnostic.
  */
 import { ShutdownManager } from "../shutdown.js";
-import { PhaseSpinner } from "../phase-spinner.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 type { QaSummary } from "./run-log-schema.js";
+import type { AgentPhaseResult } from "./drivers/index.js";
+/**
+ * Leading + trailing throttle. Fires the wrapped callback immediately on the
+ * first call, drops subsequent calls that arrive inside `intervalMs` but
+ * remembers the latest payload, and fires one final "trailing" call with that
+ * latest payload after the window closes. Used to bridge the agent driver's
+ * fine-grained `onOutput` stream (#543) to the TUI's `nowLine` without
+ * either burning the 10 Hz snapshot budget on every chunk or losing the last
+ * useful chunk before the agent goes idle.
+ *
+ * `cancel()` clears the pending timer + payload — call after the consuming
+ * phase finishes so a residual trailing fire doesn't outlive its phase
+ * context. (The orchestrator's stale-phase guard catches it anyway, but
+ * cleanup avoids holding even a no-op timer.)
+ *
+ * @internal Exported for testing only.
+ */
+export declare function createThrottledReporter(fn: (text: string) => void, intervalMs: number): {
+    report(text: string): void;
+    cancel(): void;
+};
 /**
  * Spec-specific retry configuration.
  * Spec failures have a higher failure rate (~8.6%) than other phases due to
@@ -40,6 +69,62 @@ export declare function parseQaSummary(output: string): QaSummary | null;
  * Format duration in human-readable format
  */
 export declare function formatDuration(seconds: number): string;
+/**
+ * Resolve the base ref the zero-diff guard should compare against for
+ * this worktree.
+ *
+ * Reads `branch.<current>.sequantBase` — written by `scripts/new-feature.sh`
+ * when a worktree is created with `--base <branch>`. Returns `origin/<base>`
+ * (prepending `origin/` only when the recorded value does not already
+ * reference a remote). Falls back to `"origin/main"` on missing config,
+ * missing branch, or any git error — preserves the pre-#537 behavior
+ * for worktrees that predate this change or are managed outside
+ * `new-feature.sh`.
+ *
+ * Uses `execFileSync` (not `execSync`) so argv is passed directly to
+ * `execve` without shell interpretation — the recorded value originates
+ * from the user-supplied `--base` CLI flag, and shell-interpolating it
+ * would open a shell-injection vector. With `execFileSync`, a malicious
+ * value is at worst treated as an invalid revspec by git (triggering
+ * the fail-open path), never executed as shell.
+ *
+ * @internal Exported for testing only.
+ */
+export declare function resolveBaseRef(cwd: string): string;
+/**
+ * Check whether the exec phase produced any changes in the worktree.
+ * Returns true if HEAD has commits unique to it relative to the resolved
+ * base ref (see {@link resolveBaseRef}) OR uncommitted work is present.
+ *
+ * Uses `git rev-list --count <base>..HEAD` (commits reachable from HEAD
+ * but not the base) instead of `git diff <base>..HEAD`, because the
+ * two-dot diff also fires in reverse when the base has advanced past HEAD
+ * — on stale branches that would falsely report "has commits" even when the
+ * exec phase produced nothing, reintroducing the bug #534 is fixing.
+ *
+ * The base ref defaults to `origin/main` but is overridden to the worktree's
+ * recorded base (see #537) so zero-diff execs are still detected on
+ * custom-base worktrees (e.g. those created with `--base feature/epic`).
+ *
+ * Fails open (returns true) on git errors — a missing origin ref is better
+ * diagnosed as a real zero-diff run than as a false phase failure.
+ *
+ * @internal Exported for testing only.
+ */
+export declare function hasExecChanges(cwd: string): boolean;
+/**
+ * Map a successful AgentPhaseResult to a PhaseResult, applying phase-specific
+ * guards that catch agent sessions which returned success without producing
+ * usable work (#534):
+ *
+ * - `qa`: fails when no parseable verdict is found (empty or malformed output).
+ * - `exec`: fails when no commits and no uncommitted changes exist.
+ *
+ * @internal Exported for testing only.
+ */
+export declare function mapAgentSuccessToPhaseResult(phase: Phase, agentResult: AgentPhaseResult, durationSeconds: number, cwd: string): PhaseResult & {
+    sessionId?: string;
+};
 /**
  * Get the prompt for a phase with the issue number substituted.
  * Selects self-contained prompts for non-Claude agents.
@@ -52,7 +137,7 @@ 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?: PhaseSpinner): Promise<PhaseResult & {
+declare function executePhase(issueNumber: number, phase: Phase, config: ExecutionConfig, sessionId?: string, worktreePath?: string, shutdownManager?: ShutdownManager, spinner?: PhasePauseHandle): Promise<PhaseResult & {
     sessionId?: string;
 }>;
 /**
@@ -69,7 +154,7 @@ 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?: PhaseSpinner, 
+export declare function executePhaseWithRetry(issueNumber: number, phase: Phase, config: ExecutionConfig, sessionId?: string, 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 */