sequant 2.2.0 → 2.4.0

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

@@ -7,27 +7,47 @@ import type { LogWriter } from "./log-writer.js";
 import type { StateManager } from "./state-manager.js";
 import type { ShutdownManager } from "../shutdown.js";
 import type { WorktreeInfo } from "./worktree-manager.js";
+export type { WorkflowEventEmitter, WorkflowEvents, WorkflowEventListener, IssueEventStatus, BaseEventPayload, RunEventPayload, PhaseStartedPayload, PhaseCompletedPayload, PhaseFailedPayload, IssueStatusChangedPayload, QaVerdictPayload, ProgressPayload, } from "./event-emitter.js";
 /**
  * Canonical Zod schema for all workflow phases.
  *
- * This is the single source of truth — state-schema.ts and run-log-schema.ts
- * both reference this definition. Add new phases here only.
+ * Backed by the phase registry. `PhaseSchema.parse(name)` succeeds iff
+ * `phaseRegistry.has(name)`. The set of valid phases is the registry's
+ * keys at the time of parsing — registration happens at module load,
+ * so for normal runtime use the set is fixed by the time any code parses.
+ *
+ * This replaces the prior `z.enum([...])` literal. The set of valid names
+ * is identical for the 9 built-in phases; the only observable behavior
+ * change is that `PhaseSchema.options` is no longer available — use
+ * `getPhaseNames()` from `phase-registry.ts` instead.
+ */
+export declare const PhaseSchema: z.ZodString;
+/**
+ * Available workflow phases. Widened from a string-literal union to `string`
+ * after the registry migration — exhaustiveness checking on `switch (phase)`
+ * is now a runtime concern (see the comment in phase-executor.ts where the
+ * only relevant switch lives).
  */
-export declare const PhaseSchema: z.ZodEnum<{
-    qa: "qa";
-    loop: "loop";
-    verify: "verify";
-    spec: "spec";
-    "security-review": "security-review";
-    exec: "exec";
-    testgen: "testgen";
-    test: "test";
-    merger: "merger";
-}>;
+export type Phase = string;
 /**
- * Available workflow phases (inferred from PhaseSchema)
+ * Lifecycle hook for pausing the run renderer's live zone while verbose
+ * Claude streaming writes through stdout, then resuming after the agent
+ * call completes. Replaces the legacy `PhaseSpinner` argument (#618).
+ *
+ * Lives in the workflow types barrel so the cli-ui layer can implement it
+ * without the workflow layer reaching back into cli-ui (#656).
  */
-export type Phase = z.infer<typeof PhaseSchema>;
+export interface PhasePauseHandle {
+    pause(): void;
+    resume(): void;
+    /**
+     * #647 AC-3: print a notice line (e.g., retry/fallback message) without
+     * breaking log-update's cursor model. Implementations clear the live zone,
+     * write the line through the renderer's own stdout channel, then redraw.
+     * In quiet / non-TTY paths this degrades to a plain write.
+     */
+    appendNotice(message: string): void;
+}
 /**
  * Default phases for workflow execution
  */
@@ -101,6 +121,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 +178,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 +210,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 +220,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 +293,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,11 +343,32 @@ 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;
+/**
+ * #672 AC-2: fired once per issue after the executor has resolved the final
+ * phase pipeline (post auto-detect, post resume filter, post testgen /
+ * security-review insertion). Lets the run renderer seed pending cells for
+ * the full roadmap before any phase fires, so users see what is about to run
+ * instead of phases appearing one at a time as they stream.
+ *
+ * Empty `phases` means "no plan known" — the renderer should fall back to
+ * streaming-only display.
+ */
+export type PhasePlanCallback = (issue: number, phases: string[]) => void;
 /**
  * Shared context for executing a batch of issues.
  * Replaces 11 positional parameters in executeBatch (#402).
@@ -294,6 +387,17 @@ export interface BatchExecutionContext {
     packageManager?: string;
     baseBranch?: string;
     onProgress?: ProgressCallback;
+    /** #672 AC-2: forwarded to per-issue context so batch-executor can fire it
+     * once the final phase pipeline is known. */
+    onPhasePlan?: PhasePlanCallback;
+    /**
+     * Optional live-zone pause handle (#656). When set, the phase executor calls
+     * `pause()` before forwarding verbose Claude SDK output to stdout and
+     * `resume()` after the agent call completes — so the 1Hz live grid does not
+     * collide with streaming text. Wired from the active `RunRenderer` at the
+     * composition root in `run.ts`; left undefined for quiet/TUI modes.
+     */
+    phasePauseHandle?: PhasePauseHandle;
 }
 /**
  * Context object for executing a single issue through the workflow.
@@ -325,6 +429,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;
@@ -332,4 +447,12 @@ export interface IssueExecutionContext {
     baseBranch?: string;
     /** Per-phase progress callback (used in parallel mode) */
     onProgress?: ProgressCallback;
+    /** #672 AC-2: invoked once after the per-issue phase plan resolves. */
+    onPhasePlan?: PhasePlanCallback;
+    /**
+     * Optional live-zone pause handle (#656). Forwarded to
+     * `executePhaseWithRetry` so the renderer's `pause`/`resume` hooks fire
+     * around verbose Claude streaming.
+     */
+    phasePauseHandle?: PhasePauseHandle;
 }

package/dist/src/lib/workflow/types.js

@@ -2,23 +2,28 @@
  * Core types for workflow execution
  */
 import { z } from "zod";
+// Importing the registry triggers its side-effect registrations (built-ins
+// live at the bottom of phase-registry.ts), guaranteeing the registry is
+// populated before any PhaseSchema parse runs.
+import { phaseRegistry, getPhaseNames } from "./phase-registry.js";
 /**
  * Canonical Zod schema for all workflow phases.
  *
- * This is the single source of truth — state-schema.ts and run-log-schema.ts
- * both reference this definition. Add new phases here only.
+ * Backed by the phase registry. `PhaseSchema.parse(name)` succeeds iff
+ * `phaseRegistry.has(name)`. The set of valid phases is the registry's
+ * keys at the time of parsing — registration happens at module load,
+ * so for normal runtime use the set is fixed by the time any code parses.
+ *
+ * This replaces the prior `z.enum([...])` literal. The set of valid names
+ * is identical for the 9 built-in phases; the only observable behavior
+ * change is that `PhaseSchema.options` is no longer available — use
+ * `getPhaseNames()` from `phase-registry.ts` instead.
  */
-export const PhaseSchema = z.enum([
-    "spec",
-    "security-review",
-    "exec",
-    "testgen",
-    "test",
-    "verify",
-    "qa",
-    "loop",
-    "merger",
-]);
+export const PhaseSchema = z
+    .string()
+    .refine((name) => phaseRegistry.has(name), {
+    error: (issue) => `Unknown phase "${String(issue.input)}". Available: ${getPhaseNames().join(", ")}`,
+});
 /**
  * Default phases for workflow execution
  */

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`;
+}