sequant 2.2.0 → 2.4.0

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/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,20 +8,33 @@
  * is agent-agnostic.
  */
 import { ShutdownManager } from "../shutdown.js";
-import { PhaseSpinner } from "../phase-spinner.js";
-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";
 /**
- * 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.
+ * 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;
+};
 /** @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).
@@ -41,17 +54,43 @@ 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 origin/main
- * OR uncommitted work is present.
+ * 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 origin/main..HEAD` (commits reachable from HEAD
- * but not origin/main) instead of `git diff origin/main..HEAD`, because the
- * two-dot diff also fires in reverse when origin/main has advanced past HEAD
+ * 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.
  *
@@ -70,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.
@@ -83,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?: PhaseSpinner): 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.
@@ -100,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?: PhaseSpinner, 
+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 {};