sequant 2.2.0 → 2.3.0

package/dist/src/lib/cli-ui/run-renderer-types.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Types shared between RunRenderer modes (TTY, non-TTY, orchestrator).
+ *
+ * The renderer is event-driven: a `ProgressEvent` flows in and the renderer
+ * decides whether to update the live zone, append an event line, or both.
+ */
+export type ProgressEventKind = "start" | "complete" | "failed";
+/** Raw event from batch-executor `emitProgressLine` / `onProgress` callbacks. */
+export interface ProgressEvent {
+    issue: number;
+    phase: string;
+    event: ProgressEventKind;
+    durationSeconds?: number;
+    error?: string;
+    /**
+     * Quality-loop iteration (1-based). Set on the `loop` phase event and on
+     * retried phase events (exec, qa, ...) once the outer loop iterates past 1.
+     * Surfaced in the events log as `(attempt N/M)` and in the live-zone status
+     * cell as `loop N/M` (#624 Item 3).
+     */
+    iteration?: number;
+}
+/** Per-phase status tracked inside the renderer state machine. */
+export interface PhaseState {
+    name: string;
+    status: "pending" | "running" | "done" | "failed";
+    startedAt?: number;
+    durationMs?: number;
+    /** Loop iteration label (e.g. "loop 2/3"). */
+    loopIteration?: number;
+    /**
+     * #624 Item 4: normalized signature of the most recent failure for THIS
+     * phase (ANSI-stripped, lowercased, first 80 chars, trimmed). Per-phase so
+     * "same failure as attempt N" never references a different phase's attempt.
+     */
+    lastFailureSignature?: string;
+    /**
+     * #624 Item 4: 1-based attempt number for this phase when
+     * `lastFailureSignature` was first observed. Referenced in the abbreviated
+     * form `(attempt N/M, same failure as attempt K)`.
+     */
+    firstAttemptForSignature?: number;
+}
+/** Per-issue status tracked inside the renderer state machine. */
+export interface IssueState {
+    issueNumber: number;
+    title?: string;
+    worktreePath?: string;
+    branch?: string;
+    status: "queued" | "running" | "done" | "failed";
+    phases: PhaseState[];
+    currentPhase?: string;
+    startedAt?: number;
+    completedAt?: number;
+    prNumber?: number;
+    prUrl?: string;
+    /** Optional sub-status line (e.g. "claude streaming · editing src/cli.ts"). */
+    subStatus?: string;
+    /** Last QA verdict / error reason for failed issues. */
+    failureReason?: string;
+    /**
+     * AC-23: auto-detect mode — render `Phase: detecting…` until spec finishes
+     * and the resolved plan is known.
+     */
+    autoDetect?: boolean;
+}
+/** Initial registration payload — fed at runner start so queued rows render. */
+export interface IssueRegistration {
+    issueNumber: number;
+    title?: string;
+    worktreePath?: string;
+    branch?: string;
+    /**
+     * AC-23: when true, the issue runs in auto-detect mode. The renderer shows
+     * `Phase: detecting…` while spec is running (before the resolved phase plan
+     * is known) and switches to the normal phase header once spec completes.
+     */
+    autoDetect?: boolean;
+}
+/** Per-issue summary fields used by the final summary table. */
+export interface IssueSummary {
+    issueNumber: number;
+    success: boolean;
+    durationSeconds?: number;
+    phases: Array<{
+        name: string;
+        success: boolean;
+    }>;
+    loopTriggered?: boolean;
+    prNumber?: number;
+    prUrl?: string;
+    failureReason?: string;
+    qaVerdict?: string;
+    unmetCount?: number;
+}
+/** Inputs needed to render the final summary block. */
+export interface SummaryRenderInput {
+    issues: IssueSummary[];
+    totalDurationSeconds?: number;
+    logPath?: string | null;
+    dryRun?: boolean;
+}
+/** Public renderer interface — all modes implement this. */
+export interface RunRenderer {
+    /** Register an issue so it shows as `queued` before the first phase event. */
+    registerIssue(reg: IssueRegistration): void;
+    /** Feed a progress event from batch-executor. */
+    onEvent(event: ProgressEvent): void;
+    /** Mark an issue as completed with PR info. Called by orchestrator. */
+    setPullRequest(issue: number, prNumber: number, prUrl: string): void;
+    /** Pause live updates so verbose streaming can write through. */
+    pause(): void;
+    /** Resume live updates after streaming ends. */
+    resume(): void;
+    /** Render the final summary block. */
+    renderSummary(input: SummaryRenderInput): void;
+    /** Tear down timers, cursor state, signal listeners. */
+    dispose(): void;
+}
+/**
+ * Options shared by every renderer mode. Most are optional; defaults match
+ * production behaviour (real stdout, real timers, real signals).
+ */
+export interface RenderOptions {
+    /** Override stdout writer. Defaults to `process.stdout.write`. */
+    stdoutWrite?: (s: string) => void;
+    /** Override stderr writer. Defaults to `process.stderr.write`. */
+    stderrWrite?: (s: string) => void;
+    /** Override clock. Defaults to `Date.now`. */
+    now?: () => number;
+    /** Override "wall clock" used for non-TTY timestamps. Defaults to `() => new Date()`. */
+    wallClock?: () => Date;
+    /** Override TTY detection. Defaults to `process.stdout.isTTY`. */
+    isTTY?: boolean;
+    /** Override terminal column count. Defaults to `process.stdout.columns`. */
+    columns?: number;
+    /** Disable color output (NO_COLOR). */
+    noColor?: boolean;
+    /** Heartbeat tick interval for the live zone (ms). Defaults to 1000. */
+    liveTickMs?: number;
+    /** Idle heartbeat interval for non-TTY mode (ms). Defaults to 60_000. */
+    nonTtyHeartbeatMs?: number;
+    /** Don't subscribe to SIGWINCH (used in tests). */
+    noSignalListeners?: boolean;
+    /**
+     * AC-26: when a running phase has been active for longer than this many ms
+     * with no completion event, the status header flips to `⚠ stalled · …`.
+     * Defaults to half the phase timeout when wired from settings; effectively
+     * disabled (10× the default heartbeat) when omitted.
+     */
+    stallThresholdMs?: number;
+    /**
+     * AC-28: cap visible per-issue rows in the multi-issue live grid. When the
+     * total issue count exceeds this, the oldest done rows roll up into a
+     * single `✔ {N} done` summary row at the top. Defaults to 10.
+     */
+    multiIssueRowCap?: number;
+    /**
+     * #624 Item 1: terminal row count. The TTY live zone caps its frame height
+     * at `max(8, rows - 5)` so `log-update` never deals with a frame taller than
+     * the terminal — otherwise it loses cursor tracking and appends fresh frames
+     * instead of replacing them. Defaults to `process.stdout.rows` or 24.
+     */
+    rows?: number;
+    /**
+     * #624 Item 3 / D2: total allowed quality-loop iterations. Used by every
+     * retry-suffix site (`(attempt N/M)` / `loop N/M`) so the M denominator
+     * tracks the configured maximum instead of being hardcoded. Defaults to 3.
+     */
+    maxLoopIterations?: number;
+    /**
+     * When true, `renderSummary` is rendered even if no issues were registered.
+     * Default: false (matches existing displaySummary behaviour).
+     */
+    alwaysRenderSummary?: boolean;
+}
+/**
+ * Mode the renderer should run in. Auto-detected by `createRunRenderer` from
+ * env + TTY, but explicit selection is supported for tests.
+ */
+export type RendererMode = "tty" | "non-tty" | "orchestrator";

package/dist/src/lib/cli-ui/run-renderer-types.js

@@ -0,0 +1,7 @@
+/**
+ * Types shared between RunRenderer modes (TTY, non-TTY, orchestrator).
+ *
+ * The renderer is event-driven: a `ProgressEvent` flows in and the renderer
+ * decides whether to update the live zone, append an event line, or both.
+ */
+export {};

package/dist/src/lib/cli-ui/run-renderer.d.ts

@@ -0,0 +1,239 @@
+/**
+ * RunRenderer — single coordinator for all `sequant run` stdout output.
+ *
+ * Replaces the dual-output regression where `PhaseSpinner` (legacy, #244) and
+ * the parallel-mode `▸/✔` lines (#458) both wrote to stdout for single-issue
+ * runs and produced overwritten / missing-duration lines.
+ *
+ * Three modes implement the same `RunRenderer` interface:
+ *   - TTYRenderer:           live grid (top, redrawn ~1Hz) + events log (below)
+ *   - NonTTYRenderer:        append-only `[HH:MM:SS]` events + 60s heartbeat
+ *   - OrchestratorRenderer:  no-op when SEQUANT_ORCHESTRATOR is set so MCP's
+ *                            `emitProgressLine` JSON is the only stdout
+ *
+ * See issue #618.
+ */
+import type { IssueRegistration, IssueState, ProgressEvent, RenderOptions, RendererMode, RunRenderer, SummaryRenderInput } from "./run-renderer-types.js";
+/**
+ * #624 Item 4: normalized failure signature for dedup decisions.
+ *
+ * Strips ANSI escape sequences, lowercases, trims whitespace, and truncates to
+ * the first 80 visible chars. The plan deliberately chose a length-bounded
+ * prefix over a crypto hash so debugging can match signatures by eye.
+ */
+export declare function failureSignature(error: string | undefined): string;
+/**
+ * #624 Item 3 / Derived AC-D2: shared suffix builder used by all three retry
+ * sites (NonTTY events log, TTY events log, TTY status header). Centralizes
+ * the `(attempt N/M)` / `loop N/M` literals so they cannot drift between paths.
+ *
+ * `kind` selects the surface:
+ *   - "events" → events-log line: leading space + parentheses
+ *   - "header" → status cell: leading space, no parentheses
+ *
+ * Returns the empty string when the attempt counter does not apply
+ * (no iteration, iteration === 1, or non-positive).
+ */
+export declare function formatRetrySuffix(iteration: number | undefined, maxIterations: number, kind: "events" | "header"): string;
+declare abstract class BaseRenderer implements RunRenderer {
+    protected readonly issues: Map<number, IssueState>;
+    protected readonly stdoutWrite: (s: string) => void;
+    protected readonly stderrWrite: (s: string) => void;
+    protected readonly now: () => number;
+    protected readonly wallClock: () => Date;
+    protected readonly noColor: boolean;
+    protected readonly runStartedAt: number;
+    protected paused: boolean;
+    protected disposed: boolean;
+    constructor(options: RenderOptions);
+    registerIssue(reg: IssueRegistration): void;
+    onEvent(event: ProgressEvent): void;
+    setPullRequest(issue: number, prNumber: number, prUrl: string): void;
+    pause(): void;
+    resume(): void;
+    abstract renderSummary(input: SummaryRenderInput): void;
+    dispose(): void;
+    protected applyEvent(state: IssueState, event: ProgressEvent): void;
+    /** Mark an issue done after PR is recorded — derived from phase completion. */
+    protected maybeMarkIssueDone(state: IssueState): void;
+    protected afterEvent(_event: ProgressEvent, state: IssueState): void;
+    protected afterStateChange(): void;
+    protected onPause(): void;
+    protected onResume(): void;
+    protected onDispose(): void;
+}
+/**
+ * No-op renderer used when `SEQUANT_ORCHESTRATOR` is set.
+ *
+ * The orchestrator (e.g. MCP server) consumes `emitProgressLine` JSON from
+ * batch-executor directly. Rendering anything else from the CLI would be
+ * double-emission. We still track state so `renderSummary` could be useful
+ * if explicitly invoked, but neither stdout nor stderr is touched.
+ */
+export declare class OrchestratorRenderer extends BaseRenderer {
+    renderSummary(): void;
+}
+export declare class NonTTYRenderer extends BaseRenderer {
+    private heartbeatTimer;
+    private readonly heartbeatMs;
+    private readonly columnsOverride?;
+    private readonly maxLoopIterations;
+    private lastEventAt;
+    constructor(options: RenderOptions);
+    private getColumns;
+    private startHeartbeat;
+    /** Test hook: drive a heartbeat without waiting on real timers. */
+    tickHeartbeatNow(): void;
+    private tickHeartbeat;
+    protected afterEvent(event: ProgressEvent, state: IssueState): void;
+    private emitEventLine;
+    /** Append a single `\n`-terminated line with `[HH:MM:SS]` prefix. */
+    private emitLine;
+    setPullRequest(issue: number, prNumber: number, prUrl: string): void;
+    renderSummary(input: SummaryRenderInput): void;
+    protected onDispose(): void;
+}
+/**
+ * #624 Derived AC-D1: test-only observability for the log-update stub. Tests
+ * can read `replacementCount` and `lastFrame` to verify the frame is *replaced*
+ * on each redraw rather than appended — the foundational guarantee that Items
+ * 1 and 2 rely on.
+ *
+ * `clearCalls` / `doneCalls` (added in the hardening pass) let AC-2.2 verify
+ * the renderer actually invokes `logUpdate.clear()` + `logUpdate.done()` during
+ * `renderSummary` teardown — not just that the stub's local `lastFrame` was
+ * reset.
+ */
+export interface TTYTestStub {
+    /** Number of times the live frame was replaced (not the initial write). */
+    readonly replacementCount: number;
+    /** The most recent live frame text passed to log-update. */
+    readonly lastFrame: string;
+    /** Number of times `logUpdate.clear()` was invoked. */
+    readonly clearCalls: number;
+    /** Number of times `logUpdate.done()` was invoked. */
+    readonly doneCalls: number;
+}
+export declare class TTYRenderer extends BaseRenderer {
+    private readonly liveTickMs;
+    private liveTimer;
+    private spinnerFrame;
+    private readonly columnsOverride?;
+    private readonly rowsOverride?;
+    private readonly noSignalListeners;
+    private readonly stallThresholdMs;
+    private readonly multiIssueRowCap;
+    private readonly maxLoopIterations;
+    private readonly logUpdateImpl;
+    private readonly logUpdateClear;
+    private readonly logUpdateDone;
+    private resizeListener;
+    private banner;
+    private readonly _testStub;
+    constructor(options: RenderOptions);
+    /**
+     * #624 Derived AC-D1: expose the test-only log-update stub. Returns `null`
+     * when not in test mode (production renders go through real `log-update`).
+     */
+    getTestStub(): TTYTestStub | null;
+    private startLiveTimer;
+    private installSignalListeners;
+    /** Test hook: drive a tick without waiting on real timers. */
+    tickNow(): void;
+    private tick;
+    protected afterEvent(event: ProgressEvent, state: IssueState): void;
+    protected afterStateChange(): void;
+    /** Set a banner that renders above the live grid (e.g. worktree-loss). */
+    setBanner(text: string | null): void;
+    private appendEventLine;
+    setPullRequest(issue: number, prNumber: number, prUrl: string): void;
+    renderSummary(input: SummaryRenderInput): void;
+    protected onPause(): void;
+    protected onResume(): void;
+    protected onDispose(): void;
+    private getColumns;
+    /**
+     * #624 Item 1: terminal row count, with a safe default for piped / detached
+     * stdout where `process.stdout.rows` is undefined.
+     */
+    private getRows;
+    /**
+     * #624 Item 1: hard ceiling on live-zone height. The cap is
+     * `max(8, rows - 5)`, dropping to `max(8, rows - 7)` when a banner is active
+     * so the banner + a few separator rows still fit. The floor of 8 prevents
+     * the live zone from collapsing on tiny terminals.
+     */
+    private getMaxLiveRows;
+    private redraw;
+    /** Public for tests — render the live zone to a string without emitting. */
+    renderLiveFrame(columns?: number): string;
+    /**
+     * #624 Item 1 (AC-1.1): hard ceiling on rendered frame height. The interior
+     * `applyRowCap` already collapses excess issues into the rollup row, but the
+     * frame can still drift over the cap if many issues have multi-line status
+     * cells (sub-status + phase sequence). This is the belt-and-braces clamp
+     * that guarantees `log-update` never sees a frame taller than the terminal.
+     *
+     * Always engages — when `rows` isn't explicitly provided, `getRows()` returns
+     * `DEFAULT_TERMINAL_ROWS` (100) so the cap is generous but never disengaged.
+     */
+    private clampFrameHeight;
+    private renderNarrowFrame;
+    private renderSingleIssueFrame;
+    private renderMultiIssueFrame;
+    /**
+     * AC-28 + #624 Item 1: enforce the per-frame issue row cap, derived from
+     * the smaller of `multiIssueRowCap` (static config) and a dynamic ceiling
+     * computed from terminal height. The dynamic ceiling reserves ~3 lines per
+     * issue (status header + sub-status + separator) and a fixed overhead for
+     * the frame header, blank lines, grid borders, and the rollup line.
+     *
+     * If the cap is not exceeded, returns all issues unchanged. Otherwise: keep
+     * all non-done rows, then fill remaining slots with the most recently
+     * completed done rows; older done rows roll up into a single summary entry.
+     */
+    private applyRowCap;
+    /**
+     * #624 Item 1 (AC-1.1): smaller of the configured static cap and the
+     * dynamic terminal-height-derived cap. Each issue row takes roughly 3 grid
+     * lines (header, sub-status, separator); the fixed overhead covers the
+     * frame title, blank lines, grid borders, and the rollup row.
+     *
+     * Always engages — when `rows` isn't explicitly provided, `getRows()` returns
+     * `DEFAULT_TERMINAL_ROWS` (100) which produces a dynamic cap of ~30, well
+     * above the static `multiIssueRowCap` default of 10, so the static cap stays
+     * in charge for normal-height terminals.
+     */
+    private effectiveRowCap;
+    private statusHeader;
+    private statusSubLines;
+    private statusCellLines;
+    private runHeader;
+    private rollupLine;
+    private drawKeyValueTable;
+    private drawIssueGrid;
+}
+export interface CreateRendererOptions extends RenderOptions {
+    /** Force a specific mode (otherwise auto-detected from env + TTY). */
+    mode?: RendererMode;
+}
+/**
+ * Create a `RunRenderer` matching the current execution context.
+ *
+ * Detection order:
+ *   1. Explicit `mode` override.
+ *   2. `SEQUANT_ORCHESTRATOR` env var → orchestrator (no-op).
+ *   3. `process.stdout.isTTY` (or `options.isTTY`) → TTY renderer.
+ *   4. Otherwise → non-TTY renderer.
+ */
+export declare function createRunRenderer(options?: CreateRendererOptions): RunRenderer;
+/**
+ * Public summary helper — used by the legacy displaySummary path so callers
+ * that bypass the renderer still get the new grid layout.
+ */
+export declare function renderRunSummary(input: SummaryRenderInput, options?: {
+    stdoutWrite?: (s: string) => void;
+    noColor?: boolean;
+    columns?: number;
+}): void;
+export {};