sequant 2.2.0 → 2.3.0

package/dist/src/lib/workflow/state-schema.d.ts

@@ -186,6 +186,36 @@ export declare const AcceptanceCriteriaSchema: z.ZodObject<{
     }, z.core.$strip>;
 }, z.core.$strip>;
 export type AcceptanceCriteria = z.infer<typeof AcceptanceCriteriaSchema>;
+/**
+ * Single QA stagnation observation.
+ *
+ * Recorded when fullsolve detects a same-SHA same-verdict cycle so future
+ * runs can spot "we've been here before" without re-deriving it from comments.
+ */
+export declare const QAStagnationEntrySchema: z.ZodObject<{
+    sha: z.ZodString;
+    verdict: z.ZodString;
+    detectedAt: z.ZodString;
+    iteration: z.ZodNumber;
+    reason: z.ZodEnum<{
+        SAME_SHA_NO_PROGRESS: "SAME_SHA_NO_PROGRESS";
+        LOOP_NO_DIFF: "LOOP_NO_DIFF";
+    }>;
+}, z.core.$strip>;
+export type QAStagnationEntry = z.infer<typeof QAStagnationEntrySchema>;
+/**
+ * Optional relay state for the interactive bidirectional channel (#383).
+ *
+ * Present when `sequant run` has activated the relay for an issue, absent
+ * otherwise. Legacy state files (no relay field) still parse successfully.
+ */
+export declare const RelayStateSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    pid: z.ZodNumber;
+    startedAt: z.ZodString;
+    messageCount: z.ZodNumber;
+}, z.core.$strip>;
+export type RelayState = z.infer<typeof RelayStateSchema>;
 /**
  * Complete state for a single issue
  */
@@ -301,6 +331,22 @@ export declare const IssueStateSchema: z.ZodObject<{
         }, z.core.$strip>;
         recommendation: z.ZodString;
     }, z.core.$strip>>;
+    qaStagnation: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        sha: z.ZodString;
+        verdict: z.ZodString;
+        detectedAt: z.ZodString;
+        iteration: z.ZodNumber;
+        reason: z.ZodEnum<{
+            SAME_SHA_NO_PROGRESS: "SAME_SHA_NO_PROGRESS";
+            LOOP_NO_DIFF: "LOOP_NO_DIFF";
+        }>;
+    }, z.core.$strip>>>;
+    relay: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        pid: z.ZodNumber;
+        startedAt: z.ZodString;
+        messageCount: z.ZodNumber;
+    }, z.core.$strip>>;
     sessionId: z.ZodOptional<z.ZodString>;
     resolvedAt: z.ZodOptional<z.ZodString>;
     lastActivity: z.ZodString;
@@ -428,6 +474,22 @@ export declare const WorkflowStateSchema: z.ZodObject<{
             }, z.core.$strip>;
             recommendation: z.ZodString;
         }, z.core.$strip>>;
+        qaStagnation: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            sha: z.ZodString;
+            verdict: z.ZodString;
+            detectedAt: z.ZodString;
+            iteration: z.ZodNumber;
+            reason: z.ZodEnum<{
+                SAME_SHA_NO_PROGRESS: "SAME_SHA_NO_PROGRESS";
+                LOOP_NO_DIFF: "LOOP_NO_DIFF";
+            }>;
+        }, z.core.$strip>>>;
+        relay: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodBoolean;
+            pid: z.ZodNumber;
+            startedAt: z.ZodString;
+            messageCount: z.ZodNumber;
+        }, z.core.$strip>>;
         sessionId: z.ZodOptional<z.ZodString>;
         resolvedAt: z.ZodOptional<z.ZodString>;
         lastActivity: z.ZodString;

package/dist/src/lib/workflow/state-schema.js

@@ -31,7 +31,7 @@ export const PhaseStatusSchema = z.enum([
     "in_progress", // Phase currently executing
     "completed", // Phase finished successfully
     "failed", // Phase finished with errors
-    "skipped", // Phase intentionally skipped (e.g., bug labels skip spec)
+    "skipped", // Phase intentionally skipped (e.g., prior phase marker already exists)
 ]);
 /**
  * Issue status - tracks overall issue progress
@@ -153,6 +153,36 @@ export const AcceptanceCriteriaSchema = z.object({
         blocked: z.number().int().nonnegative(),
     }),
 });
+/**
+ * Single QA stagnation observation.
+ *
+ * Recorded when fullsolve detects a same-SHA same-verdict cycle so future
+ * runs can spot "we've been here before" without re-deriving it from comments.
+ */
+export const QAStagnationEntrySchema = z.object({
+    /** HEAD SHA at the time of detection */
+    sha: z.string(),
+    /** QA verdict that repeated (e.g., AC_NOT_MET) */
+    verdict: z.string(),
+    /** ISO 8601 timestamp of detection */
+    detectedAt: z.string().datetime(),
+    /** QA loop iteration number where stagnation was detected */
+    iteration: z.number().int().nonnegative(),
+    /** Reason code: SAME_SHA_NO_PROGRESS or LOOP_NO_DIFF */
+    reason: z.enum(["SAME_SHA_NO_PROGRESS", "LOOP_NO_DIFF"]),
+});
+/**
+ * Optional relay state for the interactive bidirectional channel (#383).
+ *
+ * Present when `sequant run` has activated the relay for an issue, absent
+ * otherwise. Legacy state files (no relay field) still parse successfully.
+ */
+export const RelayStateSchema = z.object({
+    enabled: z.boolean(),
+    pid: z.number().int().positive(),
+    startedAt: z.string().datetime(),
+    messageCount: z.number().int().nonnegative(),
+});
 /**
  * Complete state for a single issue
  */
@@ -179,6 +209,10 @@ export const IssueStateSchema = z.object({
     acceptanceCriteria: AcceptanceCriteriaSchema.optional(),
     /** Scope assessment result (if performed by /spec) */
     scopeAssessment: ScopeAssessmentSchema.optional(),
+    /** QA stagnation log: same-SHA same-verdict cycles detected during fullsolve */
+    qaStagnation: z.array(QAStagnationEntrySchema).optional(),
+    /** Relay state (#383); present when bidirectional relay is active */
+    relay: RelayStateSchema.optional(),
     /** Claude session ID (for resume) */
     sessionId: z.string().optional(),
     /** When the issue transitioned to a terminal status (merged/abandoned/closed) */

package/dist/src/lib/workflow/types.d.ts

@@ -101,6 +101,21 @@ export interface ExecutionConfig {
      * Propagated as SEQUANT_FAILED_ACS env var to skills.
      */
     failedAcs?: string;
+    /**
+     * Runtime callback invoked when the agent driver emits a chunk of output
+     * during phase execution (#543). Used by the multi-issue TUI to enrich
+     * `nowLine` with sub-phase activity. Not serialized — set per-call by the
+     * orchestrator. The phase executor throttles calls to ~10 Hz so the TUI's
+     * poll budget is preserved.
+     */
+    onActivity?: (text: string) => void;
+    /**
+     * Enable interactive relay (#383). When true, phase-executor sets
+     * `SEQUANT_RELAY=true` in the agent environment so the PostToolUse hook
+     * starts polling `<worktree>/.sequant/relay/inbox.jsonl` for user messages.
+     * Default: false (opt-in for the initial rollout).
+     */
+    relayEnabled?: boolean;
 }
 /**
  * Default execution configuration
@@ -143,6 +158,18 @@ export interface IssueResult {
     prNumber?: number;
     /** PR URL if created after successful QA */
     prUrl?: string;
+    /**
+     * Set when the issue was skipped because another sequant session holds
+     * the per-issue lock (#625). Surfaced in the summary as
+     * `locked by PID <n>`. When present, `success` is false and the issue
+     * was not executed.
+     */
+    locked?: {
+        pid: number;
+        hostname: string;
+        startedAt: string;
+        command: string;
+    };
 }
 /**
  * CLI options for the run command, merged with settings and env config.
@@ -163,6 +190,7 @@ export interface RunOptions {
     smartTests?: boolean;
     noSmartTests?: boolean;
     testgen?: boolean;
+    securityReview?: boolean;
     autoDetectPhases?: boolean;
     /** Enable automatic worktree creation for issue isolation */
     worktreeIsolation?: boolean;
@@ -172,6 +200,12 @@ export interface RunOptions {
     quiet?: boolean;
     /** Chain issues: each branches from previous (requires --sequential) */
     chain?: boolean;
+    /**
+     * Stacked PRs: each non-first PR targets its predecessor branch instead of
+     * `main`. Implies --chain. The final PR still targets `main` so partial
+     * progress can land without the whole stack. (#605)
+     */
+    stacked?: boolean;
     /**
      * Wait for QA pass before starting next issue in chain mode.
      * When enabled, the chain pauses if QA fails, preventing downstream issues
@@ -239,6 +273,24 @@ export interface RunOptions {
      * Resolution priority: CLI flag → settings.agents.isolateParallel → false
      */
     isolateParallel?: boolean;
+    /**
+     * Render a live multi-issue dashboard during the run.
+     * Requires a TTY; auto-falls back to linear output when stdout is piped.
+     * Experimental — surface and behavior may change.
+     */
+    experimentalTui?: boolean;
+    /**
+     * With `--force`, SIGTERM the prior PID holding the per-issue lock
+     * before claiming it. Only acts on same-host alive PIDs. (#625)
+     */
+    signalOther?: boolean;
+    /**
+     * Interactive relay (#383). Set via `--no-relay`, which Commander surfaces as
+     * `options.relay = false`. When `false`, the PostToolUse hook is not
+     * activated and `sequant prompt` cannot reach this run.
+     * Resolution priority: this CLI flag → settings.run.relay → default (true).
+     */
+    relay?: boolean;
 }
 /**
  * CLI arguments for run command
@@ -271,10 +323,20 @@ export interface BatchResult {
 /**
  * Callback type for per-phase progress updates.
  * Used by parallel mode in run.ts to render phase status to the terminal.
+ *
+ * `extra.iteration` (#624 Item 3): outer quality-loop iteration. Threaded
+ * through to the renderer as `(attempt N/M)` on retried phase events and
+ * `loop N/M` on loop-phase live-zone status cells.
+ *
+ * `"activity"` (#543): sub-phase activity ping. `extra.text` carries a short
+ * one-line snippet (e.g. last line of agent output) for the dashboard's
+ * `nowLine`. Fires at most ~10 Hz from the phase executor.
  */
-export type ProgressCallback = (issue: number, phase: string, event: "start" | "complete" | "failed", extra?: {
+export type ProgressCallback = (issue: number, phase: string, event: "start" | "complete" | "failed" | "activity", extra?: {
     durationSeconds?: number;
     error?: string;
+    iteration?: number;
+    text?: string;
 }) => void;
 /**
  * Shared context for executing a batch of issues.
@@ -325,6 +387,17 @@ export interface IssueExecutionContext {
     chain?: {
         enabled: boolean;
         isLast: boolean;
+        /**
+         * Stacked-PR base branch for this issue. Set only when --stacked is active
+         * and this issue has a predecessor in the chain. When set, createPR targets
+         * this branch instead of `main`. (#605)
+         */
+        predecessorBranch?: string;
+        /**
+         * Pre-rendered stack manifest line for the PR body, e.g.
+         * `Part of stack: #100 → #101 (this) → #102`. Set only under --stacked.
+         */
+        stackManifest?: string;
     };
     /** Package manager name (e.g., "npm", "pnpm") */
     packageManager?: string;

package/dist/src/lib/workflow/worktree-manager.d.ts

@@ -200,7 +200,14 @@ export declare function rebaseBeforePR(worktreePath: string, issueNumber: number
  * @param issueTitle Issue title (for PR title)
  * @param branch Branch name
  * @param verbose Whether to show verbose output
+ * @param labels Issue labels (used to pick `fix(...)` vs `feat(...)` prefix)
+ * @param stackOptions When set under --stacked, `prBase` overrides the default
+ *   PR target (otherwise gh defaults to the repo's default branch) and
+ *   `stackManifest` is appended to the PR body. (#605)
  * @returns PRCreationResult with PR info or error
  * @internal Exported for testing
  */
-export declare function createPR(worktreePath: string, issueNumber: number, issueTitle: string, branch: string, verbose: boolean, labels?: string[]): PRCreationResult;
+export declare function createPR(worktreePath: string, issueNumber: number, issueTitle: string, branch: string, verbose: boolean, labels?: string[], stackOptions?: {
+    prBase?: string;
+    stackManifest?: string;
+}): PRCreationResult;

package/dist/src/lib/workflow/worktree-manager.js

@@ -843,10 +843,14 @@ export function rebaseBeforePR(worktreePath, issueNumber, packageManager, verbos
  * @param issueTitle Issue title (for PR title)
  * @param branch Branch name
  * @param verbose Whether to show verbose output
+ * @param labels Issue labels (used to pick `fix(...)` vs `feat(...)` prefix)
+ * @param stackOptions When set under --stacked, `prBase` overrides the default
+ *   PR target (otherwise gh defaults to the repo's default branch) and
+ *   `stackManifest` is appended to the PR body. (#605)
  * @returns PRCreationResult with PR info or error
  * @internal Exported for testing
  */
-export function createPR(worktreePath, issueNumber, issueTitle, branch, verbose, labels) {
+export function createPR(worktreePath, issueNumber, issueTitle, branch, verbose, labels, stackOptions) {
     const github = new GitHubProvider();
     // Step 1: Check for existing PR on this branch
     const existingPRInfo = github.viewPRByBranchSync(branch, worktreePath);
@@ -882,17 +886,22 @@ export function createPR(worktreePath, issueNumber, issueTitle, branch, verbose,
     const isBug = labels?.some((l) => /^bug/i.test(l));
     const prefix = isBug ? "fix" : "feat";
     const prTitle = `${prefix}(#${issueNumber}): ${issueTitle}`;
-    const prBody = [
+    const bodyLines = [
         `## Summary`,
         ``,
         `Automated PR for issue #${issueNumber}.`,
         ``,
         `Fixes #${issueNumber}`,
         ``,
-        `---`,
-        `🤖 Generated by \`sequant run\``,
-    ].join("\n");
-    const prResult = github.createPRCliSync(prTitle, prBody, branch, worktreePath);
+    ];
+    // #605 AC-4: emit stack manifest before the trailer so reviewers see the
+    // chain at the top of the body. Manifest is only set under --stacked.
+    if (stackOptions?.stackManifest) {
+        bodyLines.push(stackOptions.stackManifest, ``);
+    }
+    bodyLines.push(`---`, `🤖 Generated by \`sequant run\``);
+    const prBody = bodyLines.join("\n");
+    const prResult = github.createPRCliSync(prTitle, prBody, branch, worktreePath, stackOptions?.prBase);
     if (prResult.exitCode !== 0) {
         const prError = prResult.stderr.trim() || "Unknown error";
         // Check if PR already exists (race condition or push-before-PR scenarios)

package/dist/src/mcp/tools/run.d.ts

@@ -50,6 +50,16 @@ interface RunToolResponse {
  *   spawnAsync(command, [...prefixArgs, "run", ...userArgs])
  */
 export declare function resolveCliBinary(): [string, string[]];
+/**
+ * Find and parse a run log file by its exact runId suffix (#631).
+ *
+ * Avoids the recency-window heuristic in `readLatestRunLog`, which can
+ * return another concurrent run's log or a stale same-issue log when
+ * filesystem ordering doesn't favor the current run.
+ *
+ * Returns null on miss, parse failure, or I/O error (no new failure mode).
+ */
+export declare function readRunLogById(runId: string): Promise<RunLog | null>;
 /**
  * Find and parse the most recent run log file.
  *
@@ -58,10 +68,26 @@ export declare function resolveCliBinary(): [string, string[]];
  * stale logs from a previous run being returned.
  */
 export declare function readLatestRunLog(runStartTime?: Date): Promise<RunLog | null>;
+/**
+ * Resolve the run log for an MCP `sequant_run` invocation (#631).
+ *
+ * Prefers exact-filename lookup by captured runId; falls back to the
+ * time-window heuristic when no runId was captured (older CLI, startup
+ * race) or when the runId lookup returned null (corrupted file, slow
+ * fsync). On lookup-miss with a captured runId, emit a debug line on
+ * the MCP server's own stderr so the silent fallback is observable.
+ */
+export declare function resolveRunLog(capturedRunId: string | null, runStartTime: Date): Promise<RunLog | null>;
 /**
  * Build a structured response from a parsed RunLog
  */
 export declare function buildStructuredResponse(runLog: RunLog, rawOutput: string, overallStatus: "success" | "failure", exitCode?: number | null, errorOutput?: string): RunToolResponse;
+/**
+ * Parse a SEQUANT_RUN_ID line emitted by the batch executor (#631).
+ * Returns the runId UUID or null if the line isn't a runId line or the
+ * payload isn't a well-formed UUID.
+ */
+export declare function parseRunIdLine(line: string): string | null;
 /** Parsed progress event from a SEQUANT_PROGRESS line. */
 export interface ProgressEvent {
     issue: number;
@@ -75,6 +101,24 @@ export interface ProgressEvent {
  * Returns the parsed event or null if the line isn't a progress line.
  */
 export declare function parseProgressLine(line: string): ProgressEvent | null;
+/**
+ * Stateful capture of the per-run UUID emitted on stderr by the spawned
+ * CLI (#631). Each MCP request creates its own capture instance.
+ *
+ * `routeLine` consumes a complete stderr line:
+ * - Until a `SEQUANT_RUN_ID:` line is seen, attempts to capture it.
+ * - After capture (or for non-runId lines), delegates to `parseProgressLine`
+ *   and returns the parsed `ProgressEvent`, if any.
+ *
+ * Returning `ProgressEvent | null` (instead of side-effecting) keeps the
+ * factory pure and lets callers wire emission (`emitProgress`) at the
+ * outer layer. This separation also makes the capture logic directly
+ * testable without driving the full MCP request handler.
+ */
+export declare function createRunIdCapture(): {
+    routeLine: (line: string) => ProgressEvent | null;
+    getCapturedRunId: () => string | null;
+};
 /**
  * Build a human-readable message for a progress notification (AC-3).
  * @internal Exported for testing only.

package/dist/src/mcp/tools/run.js

@@ -71,6 +71,30 @@ function resolveLogDir() {
     }
     return projectPath;
 }
+/**
+ * Find and parse a run log file by its exact runId suffix (#631).
+ *
+ * Avoids the recency-window heuristic in `readLatestRunLog`, which can
+ * return another concurrent run's log or a stale same-issue log when
+ * filesystem ordering doesn't favor the current run.
+ *
+ * Returns null on miss, parse failure, or I/O error (no new failure mode).
+ */
+export async function readRunLogById(runId) {
+    try {
+        const logDir = resolveLogDir();
+        const entries = await readdir(logDir);
+        // Filename format: run-<timestamp>-<runId>.json — match by exact suffix.
+        const match = entries.find((f) => f.endsWith(`-${runId}.json`));
+        if (!match)
+            return null;
+        const content = await readFile(join(logDir, match), "utf-8");
+        return RunLogSchema.parse(JSON.parse(content));
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Find and parse the most recent run log file.
  *
@@ -109,6 +133,24 @@ export async function readLatestRunLog(runStartTime) {
         return null;
     }
 }
+/**
+ * Resolve the run log for an MCP `sequant_run` invocation (#631).
+ *
+ * Prefers exact-filename lookup by captured runId; falls back to the
+ * time-window heuristic when no runId was captured (older CLI, startup
+ * race) or when the runId lookup returned null (corrupted file, slow
+ * fsync). On lookup-miss with a captured runId, emit a debug line on
+ * the MCP server's own stderr so the silent fallback is observable.
+ */
+export async function resolveRunLog(capturedRunId, runStartTime) {
+    if (capturedRunId !== null) {
+        const byId = await readRunLogById(capturedRunId);
+        if (byId)
+            return byId;
+        console.error(`[mcp:run] runId ${capturedRunId} lookup miss — falling back to readLatestRunLog`);
+    }
+    return readLatestRunLog(runStartTime);
+}
 /**
  * Build a structured response from a parsed RunLog
  */
@@ -199,6 +241,21 @@ function buildFallbackResponse(stdout, issueNumbers, overallStatus, phases, exit
 }
 /** Prefix used by the batch executor to emit structured progress lines. */
 const PROGRESS_LINE_PREFIX = "SEQUANT_PROGRESS:";
+/** Prefix used by the batch executor to emit the current run's UUID (#631). */
+const RUN_ID_LINE_PREFIX = "SEQUANT_RUN_ID:";
+/** UUID v4 pattern produced by `crypto.randomUUID()`. */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Parse a SEQUANT_RUN_ID line emitted by the batch executor (#631).
+ * Returns the runId UUID or null if the line isn't a runId line or the
+ * payload isn't a well-formed UUID.
+ */
+export function parseRunIdLine(line) {
+    if (!line.startsWith(RUN_ID_LINE_PREFIX))
+        return null;
+    const id = line.slice(RUN_ID_LINE_PREFIX.length).trim();
+    return UUID_RE.test(id) ? id : null;
+}
 /**
  * Parse a SEQUANT_PROGRESS line emitted by the batch executor.
  * Returns the parsed event or null if the line isn't a progress line.
@@ -233,6 +290,38 @@ export function parseProgressLine(line) {
         return null;
     }
 }
+/**
+ * Stateful capture of the per-run UUID emitted on stderr by the spawned
+ * CLI (#631). Each MCP request creates its own capture instance.
+ *
+ * `routeLine` consumes a complete stderr line:
+ * - Until a `SEQUANT_RUN_ID:` line is seen, attempts to capture it.
+ * - After capture (or for non-runId lines), delegates to `parseProgressLine`
+ *   and returns the parsed `ProgressEvent`, if any.
+ *
+ * Returning `ProgressEvent | null` (instead of side-effecting) keeps the
+ * factory pure and lets callers wire emission (`emitProgress`) at the
+ * outer layer. This separation also makes the capture logic directly
+ * testable without driving the full MCP request handler.
+ */
+export function createRunIdCapture() {
+    let capturedRunId = null;
+    return {
+        routeLine(line) {
+            if (capturedRunId === null) {
+                const id = parseRunIdLine(line);
+                if (id) {
+                    capturedRunId = id;
+                    return null;
+                }
+            }
+            return parseProgressLine(line);
+        },
+        getCapturedRunId() {
+            return capturedRunId;
+        },
+    };
+}
 /**
  * Build a human-readable message for a progress notification (AC-3).
  * @internal Exported for testing only.
@@ -368,22 +457,21 @@ export function registerRunTool(server) {
                 // Swallow synchronous errors (AC-6)
             }
         };
-        /**
-         * Handle a complete line of subprocess stderr, checking for progress events.
-         * The batch executor emits SEQUANT_PROGRESS:{json} lines at phase boundaries.
-         */
+        // Per-request capture of the runId line emitted by the spawned CLI
+        // (#631). `routeLine` also parses progress events; we wire emission
+        // at this layer so the capture factory stays pure / testable.
+        const { routeLine, getCapturedRunId } = createRunIdCapture();
         const handleLine = (line) => {
-            const event = parseProgressLine(line);
+            const event = routeLine(line);
             if (event)
                 emitProgress(event);
         };
-        // Line-buffer stderr to handle chunk boundaries correctly.
-        // When a progressToken is present, we also enable spawnAsync's
-        // internal progress detection for timeout reset (AC-4).
+        // `hasProgressToken` no longer gates the line buffer (always-on so
+        // runId capture works without a subscriber); it still gates the
+        // `onProgress` callback below, which controls spawnAsync's
+        // timeout-reset behavior on progress events.
         const hasProgressToken = progressToken !== undefined;
-        const stderrLineBuffer = hasProgressToken
-            ? createLineBuffer(handleLine)
-            : undefined;
+        const stderrLineBuffer = createLineBuffer(handleLine);
         // Register all issues as active runs for real-time status polling
         for (const issue of issues) {
             registerRun(issue);
@@ -405,8 +493,11 @@ export function registerRunTool(server) {
             const stdout = result.stdout || "";
             const stderr = result.stderr || "";
             const overallStatus = result.exitCode === 0 ? "success" : "failure";
-            // Try to read structured log file for rich per-issue data
-            const runLog = await readLatestRunLog(runStartTime);
+            // Try to read structured log file for rich per-issue data.
+            // Prefer exact-filename lookup by captured runId (#631); fall back to
+            // the time-window heuristic when the CLI didn't emit a runId (older
+            // CLI, startup race) or the file is not yet visible on disk.
+            const runLog = await resolveRunLog(getCapturedRunId(), runStartTime);
             let response;
             if (runLog) {
                 response = buildStructuredResponse(runLog, stdout, overallStatus, result.exitCode, stderr || undefined);

package/dist/src/ui/tui/App.d.ts

@@ -0,0 +1,14 @@
+import { type JSX } from "react";
+import type { RunSnapshot } from "../../lib/workflow/run-state.js";
+/**
+ * Root TUI component.
+ *
+ * Polls `getSnapshot` at 10 Hz. A 1 Hz "now" tick keeps the
+ * last-activity stamp moving even when the snapshot itself is unchanged.
+ * When the snapshot reports `done`, the component stops polling and
+ * invokes `onDone` so the caller can `unmount` the ink instance.
+ */
+export declare function App({ getSnapshot, onDone, }: {
+    getSnapshot: () => RunSnapshot;
+    onDone?: () => void;
+}): JSX.Element;

package/dist/src/ui/tui/App.js

@@ -0,0 +1,41 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import { Box, useStdout } from "ink";
+import { Header } from "./Header.js";
+import { IssueBox } from "./IssueBox.js";
+const POLL_MS = 100; // 10 Hz
+/**
+ * Root TUI component.
+ *
+ * Polls `getSnapshot` at 10 Hz. A 1 Hz "now" tick keeps the
+ * last-activity stamp moving even when the snapshot itself is unchanged.
+ * When the snapshot reports `done`, the component stops polling and
+ * invokes `onDone` so the caller can `unmount` the ink instance.
+ */
+export function App({ getSnapshot, onDone, }) {
+    const [snapshot, setSnapshot] = useState(() => getSnapshot());
+    const [now, setNow] = useState(() => Date.now());
+    const doneFired = useRef(false);
+    const { stdout } = useStdout();
+    // Snapshot poller (drives all state transitions).
+    useEffect(() => {
+        const id = setInterval(() => {
+            const next = getSnapshot();
+            setSnapshot(next);
+            if (next.done && !doneFired.current) {
+                doneFired.current = true;
+                clearInterval(id);
+                onDone?.();
+            }
+        }, POLL_MS);
+        return () => clearInterval(id);
+    }, [getSnapshot, onDone]);
+    // Coarse 1 Hz tick for the last-activity stamp.
+    useEffect(() => {
+        const id = setInterval(() => setNow(Date.now()), 1000);
+        return () => clearInterval(id);
+    }, []);
+    const columns = stdout?.columns ?? 80;
+    const boxWidth = Math.min(columns - 2, 100);
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Header, { snapshot: snapshot }), snapshot.issues.map((issue, i) => (_jsx(IssueBox, { state: issue, slot: i, width: boxWidth, now: now }, issue.number)))] }));
+}

package/dist/src/ui/tui/ElapsedTimer.d.ts

@@ -0,0 +1,10 @@
+import { type JSX } from "react";
+/**
+ * Per-issue elapsed timer. Owns its own interval so tick-driven re-renders
+ * are scoped to this leaf component and do not propagate to `IssueBox`.
+ */
+export declare function ElapsedTimer({ startedAt }: {
+    startedAt?: Date;
+}): JSX.Element;
+/** Format an absolute timestamp as the "last activity Xs ago" stamp. */
+export declare function formatSinceActivity(now: number, activityAt: Date): string;

package/dist/src/ui/tui/ElapsedTimer.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+import { Text } from "ink";
+/**
+ * Per-issue elapsed timer. Owns its own interval so tick-driven re-renders
+ * are scoped to this leaf component and do not propagate to `IssueBox`.
+ */
+export function ElapsedTimer({ startedAt }) {
+    const [now, setNow] = useState(() => Date.now());
+    useEffect(() => {
+        const id = setInterval(() => setNow(Date.now()), 1000);
+        return () => clearInterval(id);
+    }, []);
+    if (!startedAt)
+        return _jsx(Text, { children: "--:--" });
+    const secs = Math.max(0, Math.floor((now - startedAt.getTime()) / 1000));
+    const mm = Math.floor(secs / 60)
+        .toString()
+        .padStart(2, "0");
+    const ss = (secs % 60).toString().padStart(2, "0");
+    return _jsx(Text, { children: `${mm}:${ss}` });
+}
+/** Format an absolute timestamp as the "last activity Xs ago" stamp. */
+export function formatSinceActivity(now, activityAt) {
+    const secs = Math.max(0, Math.floor((now - activityAt.getTime()) / 1000));
+    if (secs < 60)
+        return `${secs}s ago`;
+    const mm = Math.floor(secs / 60);
+    const ss = secs % 60;
+    return `${mm}m ${ss}s ago`;
+}

package/dist/src/ui/tui/Header.d.ts

@@ -0,0 +1,6 @@
+import type { JSX } from "react";
+import type { RunSnapshot } from "../../lib/workflow/run-state.js";
+/** Top-of-dashboard summary: count, concurrency, base, quality-loop. */
+export declare function Header({ snapshot }: {
+    snapshot: RunSnapshot;
+}): JSX.Element;