sequant 2.3.0 → 2.5.0

package/dist/src/commands/watch.js

@@ -6,6 +6,8 @@
 import { existsSync, statSync, createReadStream, watch } from "fs";
 import chalk from "chalk";
 import { outboxPathFor } from "../lib/relay/paths.js";
+import { listArchives } from "../lib/relay/archive.js";
+import { readPidFile } from "../lib/relay/pid.js";
 import { StateManager } from "../lib/workflow/state-manager.js";
 import { RelayResponseSchema } from "../lib/relay/types.js";
 function formatTimestamp(iso) {
@@ -82,8 +84,10 @@ export async function watchCommand(argsAndOptions) {
     }
     const stateManager = new StateManager();
     const issueState = await stateManager.getIssueState(issueNumber);
+    const cwd = options.cwd ?? process.cwd();
     const outboxPath = outboxPathFor(issueNumber, {
         worktreePath: issueState?.worktree,
+        cwd,
     });
     const pollIntervalMs = options.pollIntervalMs ?? 200;
     const tail = { offset: 0, partial: "" };
@@ -91,16 +95,43 @@ export async function watchCommand(argsAndOptions) {
     if (existsSync(outboxPath)) {
         tail.offset = statSync(outboxPath).size;
     }
+    // Dead-relay detection (#645, Gap 3). The pidfile is written by activateRelay
+    // and removed by deactivateRelay. If it's absent and the outbox is absent at
+    // startup, there is nothing alive to watch — print a useful pointer and exit.
+    const initialPidPresent = readPidFile(issueNumber, cwd) !== null;
+    const initialOutboxPresent = existsSync(outboxPath);
+    if (!initialPidPresent && !initialOutboxPresent) {
+        const archives = listArchives(issueNumber, cwd);
+        const summary = `No active relay for #${issueNumber}.`;
+        const hint = archives[0]
+            ? ` Most recent archive: ${archives[0]}`
+            : " (no archived runs found)";
+        if (options.json) {
+            console.log(JSON.stringify({
+                ok: false,
+                issue: issueNumber,
+                reason: "no-active-relay",
+                archive: archives[0] ?? null,
+            }));
+        }
+        else {
+            console.log(chalk.yellow(summary + hint));
+        }
+        return;
+    }
     if (!options.json) {
         console.log(chalk.gray(`Watching #${issueNumber} outbox — Ctrl+C to stop`));
     }
     let stopped = false;
-    const stop = () => {
+    let endReason = null;
+    const stop = (reason = "signal") => {
         stopped = true;
+        if (!endReason)
+            endReason = reason;
     };
-    options.signal?.addEventListener("abort", stop);
+    options.signal?.addEventListener("abort", () => stop("signal"));
     process.on("SIGINT", () => {
-        stop();
+        stop("signal");
         if (!options.json)
             console.log(chalk.gray("\nStopped watching."));
         process.exit(0);
@@ -125,6 +156,7 @@ export async function watchCommand(argsAndOptions) {
     };
     // Polling loop — also used as a heartbeat when fs.watch is active so we
     // don't miss events on filesystems where watch is unreliable.
+    let sawLivePid = initialPidPresent;
     while (!stopped) {
         try {
             const replies = await readNewLines(outboxPath, tail);
@@ -133,6 +165,23 @@ export async function watchCommand(argsAndOptions) {
         catch {
             /* transient — try again next tick */
         }
+        // Dead-relay detection (#645, Gap 3). Once we've seen a live pidfile, its
+        // absence means the run has deactivated relay (archive complete). Drain
+        // one more poll for late writes, then exit cleanly.
+        const pidAlive = readPidFile(issueNumber, cwd) !== null;
+        if (sawLivePid && !pidAlive) {
+            try {
+                const finalReplies = await readNewLines(outboxPath, tail);
+                emit(finalReplies);
+            }
+            catch {
+                /* swallow */
+            }
+            stop("relay-ended");
+            break;
+        }
+        if (pidAlive)
+            sawLivePid = true;
         await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
     }
     if (watcher) {
@@ -144,4 +193,19 @@ export async function watchCommand(argsAndOptions) {
         }
     }
     void useWatcher; // currently unused beyond best-effort init
+    if (endReason === "relay-ended") {
+        const archives = listArchives(issueNumber, cwd);
+        if (options.json) {
+            console.log(JSON.stringify({
+                ok: true,
+                issue: issueNumber,
+                reason: "relay-ended",
+                archive: archives[0] ?? null,
+            }));
+        }
+        else {
+            const hint = archives[0] ? ` Archive: ${archives[0]}` : "";
+            console.log(chalk.gray(`Run for #${issueNumber} ended.${hint}`));
+        }
+    }
 }

package/dist/src/lib/assess-collision-detect.js

@@ -208,7 +208,7 @@ export function formatCollisionAnnotations(results) {
         if (r.issues.length >= 3 && !chainSuggestion) {
             const ids = r.issues.join(" ");
             chainSuggestion =
-                `Chain: npx sequant run ${ids} --chain --qa-gate -q   ` +
+                `Chain: npx sequant run ${ids} --chain --qa-gate -Q   ` +
                     `# alternative — ${r.issues.length} issues modify ${r.file} ` +
                     `(chain length≥3 historically 1/6 = 17%; see docs/reference/chain-mode-analysis-2026-05.md)`;
         }

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

@@ -76,6 +76,15 @@ export interface IssueRegistration {
      * is known) and switches to the normal phase header once spec completes.
      */
     autoDetect?: boolean;
+    /**
+     * #672 AC-2: the resolved phase pipeline for this issue. When set, the live
+     * zone seeds one pending cell per planned phase so users see the full
+     * roadmap before any phase fires. Cells transition pending → running → ✔/✘
+     * in place via subsequent `onEvent` calls (#672 AC-3). When the plan isn't
+     * known at registration time (auto-detect mode), call `setPhasePlan` once
+     * spec resolves it.
+     */
+    plannedPhases?: string[];
 }
 /** Per-issue summary fields used by the final summary table. */
 export interface IssueSummary {
@@ -106,12 +115,26 @@ export interface RunRenderer {
     registerIssue(reg: IssueRegistration): void;
     /** Feed a progress event from batch-executor. */
     onEvent(event: ProgressEvent): void;
+    /**
+     * #672 AC-2: set or replace the planned phase pipeline for an already-
+     * registered issue. Used by auto-detect mode after spec resolves the plan.
+     * No-op for unregistered issues (defensive — same as `setPullRequest`).
+     * An empty `phases` array clears the plan back to streaming-only behaviour.
+     */
+    setPhasePlan(issue: number, phases: string[]): 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;
+    /**
+     * #647 AC-3: print a notice line above the live zone without breaking
+     * log-update's cursor model. Use for retry/fallback messages emitted
+     * from outside the renderer's event flow (e.g., phase-executor retry
+     * paths).
+     */
+    appendNotice(message: string): void;
     /** Render the final summary block. */
     renderSummary(input: SummaryRenderInput): void;
     /** Tear down timers, cursor state, signal listeners. */
@@ -173,6 +196,22 @@ export interface RenderOptions {
      * Default: false (matches existing displaySummary behaviour).
      */
     alwaysRenderSummary?: boolean;
+    /**
+     * #647: inject a `log-update` instance (typically built via
+     * `createLogUpdate(stream)` against a custom stream). Used by the
+     * scrollback-harness regression test to drive the real `log-update`
+     * through a virtual terminal that tracks scrollback. When set, this takes
+     * precedence over both `stdoutWrite` (for the log-update path) and the
+     * default `process.stdout`-bound `logUpdate` import.
+     *
+     * Production code never sets this. Tests that need to assert on
+     * `log-update`'s actual erase semantics use it to replace the test stub.
+     */
+    logUpdateInstance?: {
+        (text: string): void;
+        clear(): void;
+        done(): void;
+    };
 }
 /**
  * Mode the renderer should run in. Auto-detected by `createRunRenderer` from

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

@@ -13,6 +13,7 @@
  *
  * See issue #618.
  */
+import type { PhasePauseHandle } from "../workflow/types.js";
 import type { IssueRegistration, IssueState, ProgressEvent, RenderOptions, RendererMode, RunRenderer, SummaryRenderInput } from "./run-renderer-types.js";
 /**
  * #624 Item 4: normalized failure signature for dedup decisions.
@@ -35,7 +36,7 @@ export declare function failureSignature(error: string | undefined): string;
  * (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 {
+declare abstract class BaseRenderer implements RunRenderer, PhasePauseHandle {
     protected readonly issues: Map<number, IssueState>;
     protected readonly stdoutWrite: (s: string) => void;
     protected readonly stderrWrite: (s: string) => void;
@@ -47,10 +48,18 @@ declare abstract class BaseRenderer implements RunRenderer {
     protected disposed: boolean;
     constructor(options: RenderOptions);
     registerIssue(reg: IssueRegistration): void;
+    setPhasePlan(issue: number, phases: string[]): void;
     onEvent(event: ProgressEvent): void;
     setPullRequest(issue: number, prNumber: number, prUrl: string): void;
     pause(): void;
     resume(): void;
+    /**
+     * #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: string): void;
     abstract renderSummary(input: SummaryRenderInput): void;
     dispose(): void;
     protected applyEvent(state: IssueState, event: ProgressEvent): void;
@@ -134,6 +143,14 @@ export declare 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(): TTYTestStub | null;
     private startLiveTimer;
@@ -150,6 +167,15 @@ export declare class TTYRenderer extends BaseRenderer {
     renderSummary(input: SummaryRenderInput): void;
     protected onPause(): void;
     protected onResume(): void;
+    /**
+     * #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: string): void;
     protected onDispose(): void;
     private getColumns;
     /**
@@ -210,7 +236,13 @@ export declare class TTYRenderer extends BaseRenderer {
     private statusCellLines;
     private runHeader;
     private rollupLine;
-    private drawKeyValueTable;
+    /**
+     * 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.
+     */
+    private drawKeyValueLines;
     private drawIssueGrid;
 }
 export interface CreateRendererOptions extends RenderOptions {