sequant 2.3.0 → 2.5.0

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

@@ -13,6 +13,8 @@
  *
  * See issue #618.
  */
+import fs from "node:fs";
+import path from "node:path";
 import chalk from "chalk";
 import logUpdate from "log-update";
 import stringWidth from "string-width";
@@ -118,6 +120,11 @@ class BaseRenderer {
     registerIssue(reg) {
         if (this.issues.has(reg.issueNumber))
             return;
+        // #672 AC-2: seed pending cells when the plan is known at registration.
+        // Empty arrays fall back to streaming-only behaviour (AC-2 edge case).
+        const phases = reg.plannedPhases && reg.plannedPhases.length > 0
+            ? reg.plannedPhases.map((name) => ({ name, status: "pending" }))
+            : [];
         this.issues.set(reg.issueNumber, {
             issueNumber: reg.issueNumber,
             title: reg.title,
@@ -125,10 +132,30 @@ class BaseRenderer {
             branch: reg.branch,
             autoDetect: reg.autoDetect,
             status: "queued",
-            phases: [],
+            phases,
         });
         this.afterStateChange();
     }
+    setPhasePlan(issue, phases) {
+        const state = this.issues.get(issue);
+        if (!state)
+            return;
+        // #672 AC-2: rebuild the phase array from the resolved plan, preserving
+        // any phase state already captured from events that fired before the plan
+        // resolved (e.g. spec ran first in auto-detect mode and finished before
+        // setPhasePlan landed). Phases already seen keep their state; new planned
+        // phases enter as `pending`.
+        const existing = new Map(state.phases.map((p) => [p.name, p]));
+        state.phases = phases.map((name) => existing.get(name) ?? { name, status: "pending" });
+        // Any previously-seen phases that aren't in the new plan still belong on
+        // the row — they actually ran. Append them at the end so the planned order
+        // is preserved for unplayed phases.
+        for (const prev of existing.values()) {
+            if (!phases.includes(prev.name))
+                state.phases.push(prev);
+        }
+        this.afterStateChange();
+    }
     onEvent(event) {
         if (this.disposed)
             return;
@@ -162,6 +189,17 @@ class BaseRenderer {
         this.paused = false;
         this.onResume();
     }
+    /**
+     * #647 AC-3: default notice path — just write to the renderer's stdout
+     * channel. NonTTYRenderer keeps this default (no live zone to manage).
+     * TTYRenderer overrides to clear the live zone before writing so
+     * log-update's cursor model stays consistent with the actual terminal.
+     */
+    appendNotice(message) {
+        if (this.disposed)
+            return;
+        this.stdoutWrite(message + "\n");
+    }
     dispose() {
         if (this.disposed)
             return;
@@ -452,10 +490,120 @@ export class TTYRenderer extends BaseRenderer {
             options.multiIssueRowCap ?? DEFAULT_MULTI_ISSUE_ROW_CAP;
         this.maxLoopIterations =
             options.maxLoopIterations ?? DEFAULT_MAX_LOOP_ITERATIONS;
+        // #647 AC-1: render-state instrumentation gated on `SEQUANT_DEBUG_RENDERER=1`.
+        // Emits one JSON line per log-update callsite so a production replay shows
+        // exactly which mechanism from the #647 issue body is firing (column/row
+        // mismatch, wrap-induced row inflation, etc.). The trace doubles as the
+        // evidence required by AC-1's "Pick the fix direction from §2 only after
+        // instrumentation confirms the mechanism." sub-bullet.
+        //
+        // #664: routes to a file sink instead of stderr. In any terminal where
+        // stdout and stderr share a pty (the normal case), stderr writes scroll
+        // the terminal between log-update redraws — log-update has no record of
+        // them, so `eraseLines(previousLineCount)` misses rows and the prior
+        // frame's top survives in scrollback. The AC-1 capture's "2181×" headline
+        // was 2171× of this amplifier, not the underlying #647 bug. Sinking to
+        // a file removes the amplifier while preserving identical JSON schema +
+        // per-op cadence for diagnostic replay.
+        const debugEnabled = process.env.SEQUANT_DEBUG_RENDERER === "1";
+        let debugFd = null;
+        if (debugEnabled) {
+            // Default sink resolves against `process.cwd()` — matches the rest of
+            // the codebase's `.sequant/` convention (see `src/lib/relay/paths.ts:39`,
+            // `src/lib/ci/config.ts:42`). Invoking `sequant` from a subdirectory
+            // puts the file under that subdirectory's `.sequant/`, where the project
+            // root's `.sequant/*` gitignore does not reach — pass an absolute
+            // override via `SEQUANT_DEBUG_RENDERER_FILE` if that's a concern.
+            //
+            // `||` not `??`: treat an empty SEQUANT_DEBUG_RENDERER_FILE as "use
+            // default" rather than passing "" to openSync (which would throw and
+            // suppress all debug output via the fallback path). Locked in by the
+            // "AC-2 + empty string" test in scrollback-harness.test.ts.
+            const debugPath = process.env.SEQUANT_DEBUG_RENDERER_FILE ||
+                path.join(process.cwd(), ".sequant", "debug-renderer.jsonl");
+            try {
+                fs.mkdirSync(path.dirname(debugPath), { recursive: true });
+                debugFd = fs.openSync(debugPath, "a");
+            }
+            catch (err) {
+                // Fall through to no-op rather than crashing the run. One-shot
+                // startup notice so the user sees why debug output didn't appear.
+                const msg = err instanceof Error ? err.message : String(err);
+                this.stderrWrite(`SEQUANT_DEBUG_RENDERER: file sink unavailable at ${debugPath} (${msg}), debug output suppressed\n`);
+                debugFd = null;
+            }
+        }
+        let frameCounter = 0;
+        const emitDebug = (op, text) => {
+            if (debugFd === null)
+                return;
+            // log-update's render path is roughly:
+            //   output = wrapAnsi(text + "\n", stream.columns, {trim:false, hard:true})
+            //   previousLineCount = output.split("\n").length
+            // So `previousLineCount` is wrap-aware: a 100-char line in an 80-col
+            // stream counts as 2, not 1. We approximate that here using `stringWidth`
+            // (already a dep) instead of `text.split("\n").length`. The metric is
+            // intentionally an approximation — wrap-ansi has word-breaking nuances
+            // — but it's correct enough to spot the diagnostic case AC-1 cares
+            // about: when this count diverges from the actual on-terminal row
+            // count, log-update's `eraseLines` will undershoot.
+            const streamCols = process.stdout.columns ?? this.getColumns() ?? Infinity;
+            let logicalLines;
+            let wrappedLineCount;
+            if (text !== undefined) {
+                const lines = text.split("\n");
+                logicalLines = lines.length + (text.endsWith("\n") ? 0 : 1);
+                wrappedLineCount = lines.reduce((acc, line) => {
+                    const w = stringWidth(line);
+                    return acc + Math.max(1, Math.ceil(w / streamCols));
+                }, 0);
+                // log-update appends a trailing \n before wrapping, so count it.
+                if (!text.endsWith("\n"))
+                    wrappedLineCount++;
+            }
+            const record = {
+                t: this.now() - this.runStartedAt,
+                op,
+                frame: frameCounter,
+                rendererCols: this.getColumns(),
+                rendererRows: this.getRows(),
+                stdoutCols: process.stdout.columns ?? null,
+                stdoutRows: process.stdout.rows ?? null,
+                logicalLines,
+                wrappedLineCount,
+            };
+            // Sync append. `O_APPEND` guarantees atomic per-line writes on POSIX,
+            // and the fd lives for the process lifetime — no close on dispose
+            // because late-fire callbacks could still emit after teardown begins.
+            fs.writeSync(debugFd, `SEQUANT_DEBUG_RENDERER ${JSON.stringify(record)}\n`);
+        };
         // log-update writes to process.stdout via a mutable global instance. When
         // tests inject `stdoutWrite`, route renders through it instead so capture
-        // works deterministically.
-        if (options.stdoutWrite) {
+        // works deterministically. The #647 harness tests instead inject a real
+        // `log-update` instance bound to a virtual terminal — that path bypasses
+        // the stub so we can assert on actual cursor/erase semantics.
+        if (options.logUpdateInstance) {
+            // #647: harness path — drive a real `createLogUpdate(stream)` instance
+            // so the scrollback-aware regression test sees the same ANSI cursor
+            // operations a production user's terminal would receive. Stub is left
+            // null because the harness asserts on the VirtualTerminal directly.
+            const lu = options.logUpdateInstance;
+            this._testStub = null;
+            this.logUpdateImpl = (text) => {
+                frameCounter++;
+                emitDebug("impl", text);
+                lu(text);
+            };
+            this.logUpdateClear = () => {
+                emitDebug("clear");
+                lu.clear();
+            };
+            this.logUpdateDone = () => {
+                emitDebug("done");
+                lu.done();
+            };
+        }
+        else if (options.stdoutWrite) {
             // #624 Derived AC-D1: replacement-aware test stub. Tracks each frame
             // replacement so tests can assert on frame churn without parsing buf.out.
             // `clearCalls` / `doneCalls` verify the renderer actually invokes the
@@ -468,25 +616,39 @@ export class TTYRenderer extends BaseRenderer {
             };
             this._testStub = stub;
             this.logUpdateImpl = (text) => {
+                frameCounter++;
+                emitDebug("impl", text);
                 if (stub.lastFrame)
                     stub.replacementCount++;
                 stub.lastFrame = text;
                 options.stdoutWrite(text + "\n");
             };
             this.logUpdateClear = () => {
+                emitDebug("clear");
                 stub.clearCalls++;
                 stub.lastFrame = "";
             };
             this.logUpdateDone = () => {
+                emitDebug("done");
                 stub.doneCalls++;
                 stub.lastFrame = "";
             };
         }
         else {
             this._testStub = null;
-            this.logUpdateImpl = (text) => logUpdate(text);
-            this.logUpdateClear = () => logUpdate.clear();
-            this.logUpdateDone = () => logUpdate.done();
+            this.logUpdateImpl = (text) => {
+                frameCounter++;
+                emitDebug("impl", text);
+                logUpdate(text);
+            };
+            this.logUpdateClear = () => {
+                emitDebug("clear");
+                logUpdate.clear();
+            };
+            this.logUpdateDone = () => {
+                emitDebug("done");
+                logUpdate.done();
+            };
         }
         this.startLiveTimer();
         this.installSignalListeners();
@@ -494,6 +656,14 @@ export class TTYRenderer extends BaseRenderer {
     /**
      * #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`).
+     *
+     * #647 AC-D3 warning: this stub does NOT model `log-update`'s ANSI cursor
+     * or scrollback semantics. Tests that assert on `stub.lastFrame` only see
+     * the most recent frame, not whether earlier frames remained stranded in
+     * scrollback. Header-count / duplicate-header assertions MUST use
+     * `scrollback-harness.ts` (real `createLogUpdate` + VirtualTerminal),
+     * otherwise they will pass green even when the production rendering is
+     * broken — see #624 for the precedent.
      */
     getTestStub() {
         return this._testStub;
@@ -542,6 +712,14 @@ export class TTYRenderer extends BaseRenderer {
         this.redraw();
     }
     appendEventLine(event, state) {
+        // #672 AC-1: drop the `▸ start` journal line. The live zone already shows
+        // the phase as running in place, so appending a permanent scrollback line
+        // duplicates that information and produces the "two-row" visual reported
+        // in #672. `complete` and `failed` still append (they are the durable
+        // record of what ran). The redraw in `afterEvent` keeps the live zone
+        // fresh so the transition pending → running is still visible.
+        if (event.event === "start")
+            return;
         // Clear the live zone so the appended event becomes a real `console.log`
         // line above it; the live zone redraws below.
         this.logUpdateClear();
@@ -553,10 +731,7 @@ export class TTYRenderer extends BaseRenderer {
             ? ""
             : formatRetrySuffix(phase?.loopIteration, this.maxLoopIterations, "events");
         let line;
-        if (event.event === "start") {
-            line = `  ${c.cyan("▸")} #${event.issue} ${event.phase}${retrySuffix}`;
-        }
-        else if (event.event === "complete") {
+        if (event.event === "complete") {
             const durStr = event.durationSeconds !== undefined
                 ? `  ${formatElapsedTime(event.durationSeconds)}`
                 : "";
@@ -619,6 +794,25 @@ export class TTYRenderer extends BaseRenderer {
         // Live zone redraws on next tick / event automatically.
         this.redraw();
     }
+    /**
+     * #647 AC-3: TTYRenderer override. Writes the notice above the live zone
+     * the same way `appendEventLine` does (clear → write → redraw), so
+     * log-update's `previousLineCount` stays consistent with the actual
+     * terminal state. If the renderer is already paused (e.g., during
+     * verbose subprocess streaming), skip the clear/redraw and just write;
+     * the eventual `resume()` will redraw cleanly.
+     */
+    appendNotice(message) {
+        if (this.disposed)
+            return;
+        if (this.paused) {
+            this.stdoutWrite(message + "\n");
+            return;
+        }
+        this.logUpdateClear();
+        this.stdoutWrite(message + "\n");
+        this.redraw();
+    }
     onDispose() {
         if (this.liveTimer !== null) {
             clearInterval(this.liveTimer);
@@ -728,13 +922,25 @@ export class TTYRenderer extends BaseRenderer {
         return lines.join("\n");
     }
     renderSingleIssueFrame(cols) {
-        // AC-11: Single-issue runs use a key:value full-grid table.
+        // AC-11: single-issue runs render as indented `label  value` lines — not a
+        // box-drawing grid.
+        //
+        // The grid was the dominant source of `log-update` `eraseLines` stranding
+        // (#647 / #655): a multi-line bordered frame whose top survives in
+        // scrollback when the erase undershoots, leaving a frozen first paint (the
+        // classic "0s elapsed" ghost with no bottom border). Indented labels keep
+        // the same information at a shorter, border-free height that clears
+        // cleanly, and match the repo's move away from box-drawing in human output
+        // (see feedback_llm_hostile_formatting). Multi-issue still uses the grid.
         const state = [...this.issues.values()][0];
         const c = colorize(this.noColor);
         const header = `SEQUANT WORKFLOW · #${state.issueNumber} · ${formatElapsedTime((this.now() - this.runStartedAt) / 1000)} elapsed`;
-        const labelWidth = 10;
-        const innerWidth = Math.max(40, Math.min(cols, 110) - labelWidth - 7);
-        const valueWidth = innerWidth;
+        // Label column fits the widest label ("Worktree"); value column is the
+        // remaining width after the 2-space indent + 2-space gap. Capped the same
+        // way the grid was so wide / misreported terminals can't push values past a
+        // standard 80-col reader.
+        const labelWidth = 8;
+        const valueWidth = Math.max(40, Math.min(cols, 100) - labelWidth - 4);
         const rows = [];
         const titleSuffix = state.title ? ` — ${state.title}` : "";
         rows.push([
@@ -751,7 +957,7 @@ export class TTYRenderer extends BaseRenderer {
         const lines = [c.bold(header), ""];
         if (this.banner)
             lines.push(c.yellow(this.banner), "");
-        lines.push(this.drawKeyValueTable(rows, labelWidth, valueWidth));
+        lines.push(this.drawKeyValueLines(rows, labelWidth));
         return lines.join("\n");
     }
     renderMultiIssueFrame(cols) {
@@ -761,8 +967,13 @@ export class TTYRenderer extends BaseRenderer {
         // is appended.
         const c = colorize(this.noColor);
         const header = `SEQUANT WORKFLOW · ${this.runHeader()}`;
+        // #647 AC-3: see note in `renderSingleIssueFrame` — cap at 78 (not 110) so
+        // the rendered grid stays narrower than any standard 80-col terminal under
+        // width-misreporting conditions. The box-drawing total is
+        // `issueColW + statusColW + 9`; the prior `- 7` formula compounded the
+        // overflow.
         const issueColW = 8;
-        const innerWidth = Math.max(50, Math.min(cols, 110) - issueColW - 7);
+        const innerWidth = Math.max(50, Math.min(cols, 78) - issueColW - 9);
         const statusColW = innerWidth;
         const lines = [c.bold(header), ""];
         if (this.banner)
@@ -902,7 +1113,13 @@ export class TTYRenderer extends BaseRenderer {
     statusSubLines(state) {
         const c = colorize(this.noColor);
         const lines = [];
-        if (state.status === "running" || state.status === "queued") {
+        // #672 AC-3: include the failed state so the row that just failed still
+        // renders its phase cells (the failing cell shows ✘ in place). Without
+        // this, a failure on an unstarted phase hides the entire pipeline behind
+        // the header summary, making it impossible to see how far the run got.
+        if (state.status === "running" ||
+            state.status === "queued" ||
+            state.status === "failed") {
             const seq = state.phases
                 .filter((p) => p.name !== "loop")
                 .map((p) => {
@@ -912,7 +1129,11 @@ export class TTYRenderer extends BaseRenderer {
                     return c.red(`${p.name} ✘`);
                 if (p.status === "running")
                     return c.cyan(`${p.name} running`);
-                return c.gray(`${p.name} queued`);
+                // #672 AC-3: pending cells render as `name –` (en dash) so the live
+                // zone reads as a roadmap when a phase plan is set via registration
+                // or `setPhasePlan`. Without a plan, no pending cells are seeded so
+                // this branch is unreachable — preserving prior single-row output.
+                return c.gray(`${p.name} –`);
             })
                 .join("  →  ");
             if (seq)
@@ -955,26 +1176,22 @@ export class TTYRenderer extends BaseRenderer {
         return c.dim(`${done} done · ${running} running · ${queued} queued · ${failed} failed`);
     }
     // ---------------- Box drawing ----------------
-    drawKeyValueTable(rows, labelW, valueW) {
+    /**
+     * Single-issue layout: indented `label  value` lines, no box drawing. The
+     * label is cyan and padded to `labelW`; continuation lines (multi-line
+     * status cells) align under the value column with a blank label. See
+     * `renderSingleIssueFrame` for why the bordered grid was dropped.
+     */
+    drawKeyValueLines(rows, labelW) {
         const c = colorize(this.noColor);
-        const dim = c.dim;
-        const total = labelW + valueW + 3;
-        const top = dim("  ┌" + "─".repeat(labelW + 2) + "┬" + "─".repeat(valueW + 2) + "┐");
-        const sep = dim("  ├" + "─".repeat(labelW + 2) + "┼" + "─".repeat(valueW + 2) + "┤");
-        const bottom = dim("  └" + "─".repeat(labelW + 2) + "┴" + "─".repeat(valueW + 2) + "┘");
-        const out = [top];
-        rows.forEach(([label, lines], i) => {
+        const out = [];
+        for (const [label, lines] of rows) {
             const labelPadded = padEndVisible(label, labelW);
             lines.forEach((line, idx) => {
                 const labelCell = idx === 0 ? c.cyan(labelPadded) : " ".repeat(labelW);
-                const valuePadded = padEndVisible(line, valueW);
-                out.push(`  ${dim("│")} ${labelCell} ${dim("│")} ${valuePadded} ${dim("│")}`);
+                out.push(`  ${labelCell}  ${line}`);
             });
-            if (i < rows.length - 1)
-                out.push(sep);
-        });
-        out.push(bottom);
-        void total;
+        }
         return out.join("\n");
     }
     drawIssueGrid(rows, issueW, statusW) {

package/dist/src/lib/cli-ui/scrollback-harness.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Virtual-terminal harness for renderer regression tests (#647).
+ *
+ * The test stub embedded in TTYRenderer (see {@link
+ * ./run-renderer.ts#TTYTestStub}) mocks `log-update` itself — it cannot reveal
+ * whether the real `log-update` actually erases prior frames once the terminal
+ * scrolls. That gap is what allowed #624's fix to ship green while the
+ * underlying duplicate-header bug remained.
+ *
+ * This harness models a real terminal:
+ *   - bounded visible viewport (rows × cols)
+ *   - unbounded scrollback that captures every line that scrolls off the top
+ *   - the ANSI escape vocabulary that `log-update@7` + `ansi-escapes`
+ *     actually emit (cursor up/down/forward/back, eraseLine variants,
+ *     SGR colour stripping, private mode set/reset, save/restore)
+ *
+ * With it, a test can wire the production renderer through a real
+ * `createLogUpdate` instance, replay an event sequence, and assert on
+ * `(visible + scrollback)` to catch any duplicate-header rendering — the
+ * exact regression #647 was opened for.
+ */
+import { createLogUpdate } from "log-update";
+export interface VirtualTerminalOptions {
+    rows: number;
+    cols: number;
+    /** Newline mode. POSIX shells default to ONLCR which translates `\n` to
+     *  `\r\n`, so most apps see "move down + col 0". Default true. */
+    onlcr?: boolean;
+}
+/**
+ * Minimal vt100 model: visible grid + scrollback + cursor. Strips SGR colour
+ * codes (they're styling, not content) and ignores private-mode toggles
+ * (cursor hide/show). Implements the cursor and erase escapes that
+ * `log-update@7` actually emits.
+ */
+export declare class VirtualTerminal {
+    readonly rows: number;
+    readonly cols: number;
+    private readonly onlcr;
+    /** visible[row][col] = char (always single-codepoint slot). */
+    visible: string[][];
+    /** Scrollback grows oldest-first as rows shift off the top. */
+    scrollback: string[];
+    cursorRow: number;
+    cursorCol: number;
+    constructor(opts: VirtualTerminalOptions);
+    write(text: string): void;
+    /** Visible viewport as a list of trimmed-right rows. */
+    getVisibleLines(): string[];
+    /** Single multi-line string of (scrollback + visible). */
+    getAllText(): string;
+    /** Match count of the regex against (scrollback + visible). */
+    countOccurrences(pattern: RegExp): number;
+    private putChar;
+    private linefeed;
+    /** Returns the index AFTER the consumed escape sequence. */
+    private handleEscape;
+    private handleCSI;
+    private executeCSI;
+    private eraseLine;
+    private eraseFromCursorToEndOfLine;
+    private eraseFromStartOfLineToCursor;
+    private eraseFromCursorToEndOfScreen;
+    private eraseFromStartOfScreenToCursor;
+    private eraseScreen;
+}
+/**
+ * Bundle a VirtualTerminal with a real `log-update` instance writing into it
+ * and a matching `stdoutWrite` for renderer event-line writes. Both paths hit
+ * the same VT, mirroring real-terminal interleaving.
+ *
+ * Production runs frequently hit a width/height mismatch between what
+ * `log-update` reads from `process.stdout` and what the real terminal actually
+ * uses (e.g. `process.stdout.columns` is undefined under `npx` so log-update
+ * falls back to 80 while the terminal is 200 cols). Those mismatches cause
+ * `previousLineCount` to under- or over-count the rows log-update actually
+ * wrote, breaking `eraseLines` and leaving stale rows in scrollback. The
+ * `streamColumns` / `streamRows` overrides let tests reproduce this without
+ * needing a real PTY.
+ */
+export interface TerminalHarness {
+    vt: VirtualTerminal;
+    logUpdate: ReturnType<typeof createLogUpdate>;
+    stdoutWrite: (s: string) => void;
+    /**
+     * Out-of-band write that lands in the same VT as `logUpdate` and
+     * `stdoutWrite` — mirrors how a real pty merges stderr writes with stdout
+     * when both descriptors point at the same terminal. log-update has no
+     * knowledge of these writes, so they advance the cursor in ways
+     * `previousLineCount` cannot account for. Use this to reproduce the
+     * Mechanism #2-class bug (out-of-band writes break log-update's cursor
+     * model) that #647 AC-1 capture diagnosed.
+     */
+    stderrWrite: (s: string) => void;
+}
+export interface HarnessOptions extends VirtualTerminalOptions {
+    /**
+     * Width log-update is told about via `stream.columns`. Defaults to
+     * `opts.cols` (matched terminal). Override to simulate a mismatch where
+     * log-update wraps at one width but the real terminal wraps at another.
+     */
+    streamColumns?: number;
+    /**
+     * Height log-update is told about via `stream.rows`. Defaults to
+     * `opts.rows`. Override to simulate `process.stdout.rows = undefined`
+     * (the `npx` symptom): pass `undefined` explicitly via the harness's stream
+     * by setting this to a non-positive number — log-update then falls through
+     * to its internal `defaultHeight ?? 24`.
+     */
+    streamRows?: number;
+}
+export declare function createTerminalHarness(opts: HarnessOptions): TerminalHarness;