sequant 2.2.0 → 2.4.0

package/dist/src/lib/workflow/run-orchestrator.js

@@ -9,17 +9,50 @@
 import chalk from "chalk";
 import { spawnSync } from "child_process";
 import pLimit from "p-limit";
+import { formatCoarseNowLine } from "./run-state.js";
 import { detectDefaultBranch, ensureWorktrees, ensureWorktreesChain, getWorktreeDiffStats, } from "./worktree-manager.js";
 import { LogWriter } from "./log-writer.js";
 import { StateManager } from "./state-manager.js";
 import { ShutdownManager } from "../shutdown.js";
-import { getIssueInfo, sortByDependencies, parseBatches, runIssueWithLogging, } from "./batch-executor.js";
+import { LockManager, formatLockedMessage } from "../locks/index.js";
+import { bracketedConsoleLog } from "./notice.js";
+/** Human-readable line for the run-orchestrator's `--signal-other` log (#637). */
+function formatSignalLine(issue, pid, result) {
+    switch (result.reason) {
+        case "sent":
+            return `  Signaled PID ${pid} (SIGTERM) for #${issue}`;
+        case "cross-host":
+            return `  Could not signal PID ${pid} for #${issue} (cross-host holder)`;
+        case "self-or-parent":
+            return `  Refused to signal PID ${pid} for #${issue} (matches this process or its parent)`;
+        case "pid-dead":
+            return `  Could not signal PID ${pid} for #${issue} (already exited)`;
+        case "kill-failed":
+            return `  Could not signal PID ${pid} for #${issue} (kill syscall failed)`;
+        case "orchestrator":
+            return `  Skipped signal for #${issue} (orchestrator mode)`;
+    }
+}
+import { getIssueInfo, sortByDependencies, parseBatches, runIssueWithLogging, emitRunIdLine, } from "./batch-executor.js";
 import { reconcileStateAtStartup } from "./state-utils.js";
 import { getCommitHash } from "./git-diff-utils.js";
 import { MetricsWriter } from "./metrics-writer.js";
+import { WorkflowEventEmitter } from "./event-emitter.js";
 import { determineOutcome } from "./metrics-schema.js";
 import { getTokenUsageForRun } from "./token-utils.js";
 import { resolveRunOptions, buildExecutionConfig } from "./config-resolver.js";
+/**
+ * Build the stack-manifest line emitted into PR bodies under --stacked.
+ *
+ * Example for issues `[100, 101, 102]` at `currentIndex=1`:
+ *   `Part of stack: #100 → #101 (this) → #102`
+ *
+ * @internal Exported for testing.
+ */
+export function buildStackManifest(issueNumbers, currentIndex) {
+    const parts = issueNumbers.map((n, i) => i === currentIndex ? `#${n} (this)` : `#${n}`);
+    return `Part of stack: ${parts.join(" → ")}`;
+}
 // ── Orchestrator ────────────────────────────────────────────────────────────
 /**
  * CLI-free workflow execution engine.
@@ -32,9 +65,199 @@ import { resolveRunOptions, buildExecutionConfig } from "./config-resolver.js";
  */
 export class RunOrchestrator {
     cfg;
+    issueStates = new Map();
+    phaseStartTimes = new Map();
+    emitter;
+    done = false;
     constructor(config) {
         this.validate(config);
-        this.cfg = config;
+        // Build the event emitter before wrapProgress so the wrapper can route
+        // status transitions through `issue_status_changed` events (AC-3).
+        this.emitter = new WorkflowEventEmitter({
+            onListenerError: (event, error) => {
+                // Mirror the orchestrator's verbose-gated non-fatal warning style.
+                // Listener failures must never propagate to the run.
+                logNonFatalWarning(`  !  Event listener for "${event}" threw, ignoring`, error, config.config?.verbose ?? false);
+            },
+        });
+        this.cfg = { ...config, onProgress: this.wrapProgress(config.onProgress) };
+        this.initIssueStates();
+    }
+    /**
+     * Returns the workflow event emitter. External consumers (TUI, MCP server,
+     * future webhooks) call `getEmitter().on(...)` to subscribe to lifecycle
+     * events. Subscribing is opt-in — the orchestrator runs unaware of who is
+     * listening (#504, AC-3).
+     */
+    getEmitter() {
+        return this.emitter;
+    }
+    /**
+     * Point-in-time view of the entire run.
+     *
+     * Safe under concurrent reads: the returned object contains only freshly
+     * allocated arrays and plain records; no internal Map or mutable state
+     * reference is leaked. Callers may hold snapshots across awaits without
+     * observing torn writes.
+     */
+    getSnapshot() {
+        const { config } = this.cfg;
+        const snapshotConfig = {
+            concurrency: config.concurrency,
+            baseBranch: this.cfg.baseBranch ?? "main",
+            qualityLoop: config.qualityLoop,
+        };
+        const issues = [];
+        for (const state of this.issueStates.values()) {
+            issues.push(cloneIssueState(state));
+        }
+        return {
+            config: snapshotConfig,
+            issues,
+            done: this.done,
+            capturedAt: new Date(),
+        };
+    }
+    /**
+     * Mark the run as completed so the dashboard can unmount and drop event
+     * subscribers. Drains the emitter to prevent leaks across multiple
+     * `run()` invocations in the same process (e.g. the MCP server).
+     */
+    markDone() {
+        this.done = true;
+        this.emitter.removeAllListeners();
+    }
+    initIssueStates() {
+        const { issueInfoMap, worktreeMap, config } = this.cfg;
+        for (const [num, info] of issueInfoMap.entries()) {
+            const branch = worktreeMap.get(num)?.branch ?? `#${num}`;
+            const phases = config.phases.map((name) => ({
+                name,
+                status: "pending",
+            }));
+            this.issueStates.set(num, {
+                number: num,
+                title: info.title,
+                branch,
+                status: "queued",
+                phases,
+            });
+        }
+    }
+    wrapProgress(external) {
+        return (issue, phase, event, extra) => {
+            this.applyProgressEvent(issue, phase, event, extra);
+            external?.(issue, phase, event, extra);
+        };
+    }
+    applyProgressEvent(issue, phase, event, extra) {
+        const state = this.issueStates.get(issue);
+        if (!state)
+            return;
+        if (event === "start") {
+            const wasStatus = state.status;
+            if (!state.startedAt)
+                state.startedAt = new Date();
+            state.status = "running";
+            const now = new Date();
+            this.phaseStartTimes.set(`${issue}:${phase}`, now.getTime());
+            state.currentPhase = {
+                name: phase,
+                startedAt: now,
+                lastActivityAt: now,
+                nowLine: formatCoarseNowLine(phase),
+            };
+            const p = findOrAppendPhase(state, phase);
+            p.status = "running";
+            p.startedAt = now;
+            // Fire-and-forget — listener safety guaranteed by the emitter (AC-5).
+            void this.emitter.emit("phase_started", {
+                issueNumber: issue,
+                phase,
+                iteration: extra?.iteration,
+            });
+            if (wasStatus !== "running") {
+                void this.emitter.emit("issue_status_changed", {
+                    issueNumber: issue,
+                    from: wasStatus,
+                    to: "running",
+                });
+            }
+            return;
+        }
+        if (event === "activity") {
+            // Ignore activity for stale phases (race between completion and a
+            // final flushed output chunk).
+            if (!state.currentPhase || state.currentPhase.name !== phase)
+                return;
+            const line = extractActivityLine(extra?.text);
+            if (!line)
+                return;
+            state.currentPhase.nowLine = line;
+            state.currentPhase.lastActivityAt = new Date();
+            void this.emitter.emit("progress", {
+                issueNumber: issue,
+                phase,
+                text: line,
+            });
+            return;
+        }
+        // complete / failed
+        const key = `${issue}:${phase}`;
+        const startMs = this.phaseStartTimes.get(key);
+        this.phaseStartTimes.delete(key);
+        const elapsedMs = extra?.durationSeconds != null
+            ? extra.durationSeconds * 1000
+            : startMs != null
+                ? Date.now() - startMs
+                : undefined;
+        const p = findOrAppendPhase(state, phase);
+        p.status = event === "complete" ? "done" : "failed";
+        p.elapsedMs = elapsedMs;
+        state.currentPhase = undefined;
+        const durationSec = elapsedMs !== undefined ? Math.round(elapsedMs / 1000) : undefined;
+        if (event === "failed") {
+            const prev = state.status;
+            state.status = "failed";
+            state.completedAt = new Date();
+            void this.emitter.emit("phase_failed", {
+                issueNumber: issue,
+                phase,
+                duration: durationSec,
+                error: extra?.error ?? "unknown",
+                iteration: extra?.iteration,
+            });
+            if (prev !== "failed") {
+                void this.emitter.emit("issue_status_changed", {
+                    issueNumber: issue,
+                    from: prev,
+                    to: "failed",
+                });
+            }
+            return;
+        }
+        void this.emitter.emit("phase_completed", {
+            issueNumber: issue,
+            phase,
+            duration: durationSec ?? 0,
+            iteration: extra?.iteration,
+        });
+        // Completed phase: if it's the last phase in the plan, mark issue passed.
+        const allDone = state.phases.every((ph) => ph.status === "done" || ph.status === "failed");
+        if (allDone) {
+            const prev = state.status;
+            state.status = state.phases.some((ph) => ph.status === "failed")
+                ? "failed"
+                : "passed";
+            state.completedAt = new Date();
+            if (prev !== state.status) {
+                void this.emitter.emit("issue_status_changed", {
+                    issueNumber: issue,
+                    from: prev,
+                    to: state.status,
+                });
+            }
+        }
     }
     /**
      * Pure config resolution — no side effects.
@@ -95,7 +318,7 @@ export class RunOrchestrator {
      * issue discovery → worktree creation → execution → metrics → cleanup.
      */
     static async run(init, issueArgs, batches) {
-        const { manifest, onProgress, settings } = init;
+        const { manifest, onProgress, phasePauseHandle, settings } = init;
         // ── Config resolution ──────────────────────────────────────────────
         const resolved = RunOrchestrator.resolveConfig(init, issueArgs, batches);
         const { mergedOptions, config, baseBranch } = resolved;
@@ -134,6 +357,9 @@ export class RunOrchestrator {
                     startCommit: getCommitHash(process.cwd()),
                 });
                 await logWriter.initialize(runConfig);
+                const runId = logWriter.getRunId();
+                if (runId)
+                    emitRunIdLine(runId);
             }
             catch (err) {
                 const msg = err instanceof Error ? err.message : String(err);
@@ -203,6 +429,63 @@ export class RunOrchestrator {
                 }
             }
         }
+        // ── Concurrency lock (#625) ────────────────────────────────────────
+        // Acquired here — after the state guard, before worktree creation — so
+        // that issues already filtered as ready_for_merge don't claim locks they
+        // wouldn't release. Locked issues are skipped from the run with a
+        // synthetic IssueResult so the batch continues.
+        const lockManager = new LockManager();
+        const lockedResults = [];
+        if (!lockManager.isNoop && !config.dryRun) {
+            const commandLabel = `npx sequant run ${issueNumbers.join(" ")}`;
+            const claimed = [];
+            for (const issueNumber of issueNumbers) {
+                const claim = mergedOptions.force
+                    ? (() => {
+                        const { previous } = lockManager.forceAcquire(issueNumber, commandLabel);
+                        if (previous && mergedOptions.signalOther) {
+                            const result = lockManager.signalOther(previous);
+                            console.log(chalk.gray(formatSignalLine(issueNumber, previous.pid, result)));
+                        }
+                        return { acquired: true };
+                    })()
+                    : lockManager.acquire(issueNumber, commandLabel);
+                if (claim.acquired) {
+                    claimed.push(issueNumber);
+                }
+                else {
+                    lockedResults.push(buildLockedResult(issueNumber, claim.holder));
+                    console.log(chalk.yellow(`  !  ${formatLockedMessage(issueNumber, claim.holder)}`));
+                }
+            }
+            issueNumbers = claimed;
+            if (claimed.length > 0) {
+                shutdown.registerCleanup("Release issue locks", async () => {
+                    lockManager.releaseAll();
+                });
+                // Sync cleanup for SIGKILL / uncaughtException paths. process.on('exit')
+                // only fires sync handlers; this is the best-effort safety net for
+                // events ShutdownManager doesn't catch.
+                const exitHandler = () => lockManager.releaseAll();
+                process.on("exit", exitHandler);
+                shutdown.registerCleanup("Detach exit-handler", async () => {
+                    process.off("exit", exitHandler);
+                });
+            }
+            if (issueNumbers.length === 0) {
+                shutdown.dispose();
+                return {
+                    results: lockedResults,
+                    logPath: null,
+                    exitCode: lockedResults.length > 0 ? 1 : 0,
+                    worktreeMap: new Map(),
+                    issueInfoMap: new Map(),
+                    config,
+                    mergedOptions,
+                    logWriter: null,
+                };
+            }
+        }
         // ── Issue info + worktree setup ────────────────────────────────────
         const issueInfoMap = new Map();
         for (const issueNumber of issueNumbers) {
@@ -233,26 +516,33 @@ export class RunOrchestrator {
         }
         // ── Execute ────────────────────────────────────────────────────────
         let results = [];
+        const orchestrator = new RunOrchestrator({
+            config,
+            options: mergedOptions,
+            issueInfoMap,
+            worktreeMap,
+            services: { logWriter, stateManager, shutdownManager: shutdown },
+            packageManager: manifest.packageManager,
+            baseBranch,
+            onProgress,
+            onPhasePlan: init.onPhasePlan,
+            phasePauseHandle,
+        });
+        init.onOrchestratorReady?.(orchestrator);
         try {
-            const orchestrator = new RunOrchestrator({
-                config,
-                options: mergedOptions,
-                issueInfoMap,
-                worktreeMap,
-                services: { logWriter, stateManager, shutdownManager: shutdown },
-                packageManager: manifest.packageManager,
-                baseBranch,
-                onProgress,
-            });
             if (resolvedBatches) {
                 for (let batchIdx = 0; batchIdx < resolvedBatches.length; batchIdx++) {
                     const batch = resolvedBatches[batchIdx];
-                    console.log(chalk.blue(`\n  Batch ${batchIdx + 1}/${resolvedBatches.length}: Issues ${batch.map((n) => `#${n}`).join(", ")}`));
+                    // #647 AC-3: between-batches in a multi-batch run, the renderer is
+                    // still alive and may have a populated live zone from the previous
+                    // batch. Route through `bracketedConsoleLog` so log-update's cursor
+                    // model stays consistent.
+                    bracketedConsoleLog(phasePauseHandle, chalk.blue(`\n  Batch ${batchIdx + 1}/${resolvedBatches.length}: Issues ${batch.map((n) => `#${n}`).join(", ")}`));
                     const batchResults = await orchestrator.execute(batch);
                     results.push(...batchResults);
                     const batchFailed = batchResults.some((r) => !r.success);
                     if (batchFailed && config.sequential) {
-                        console.log(chalk.yellow(`\n  !  Batch ${batchIdx + 1} failed, stopping batch execution`));
+                        bracketedConsoleLog(phasePauseHandle, chalk.yellow(`\n  !  Batch ${batchIdx + 1} failed, stopping batch execution`));
                         break;
                     }
                 }
@@ -276,10 +566,11 @@ export class RunOrchestrator {
                     logNonFatalWarning("  !  Metrics recording failed, continuing...", metricsError, config.verbose);
                 }
             }
+            const allResults = [...lockedResults, ...results];
             return {
-                results,
+                results: allResults,
                 logPath,
-                exitCode: results.some((r) => !r.success) && !config.dryRun ? 1 : 0,
+                exitCode: allResults.some((r) => !r.success) && !config.dryRun ? 1 : 0,
                 worktreeMap,
                 issueInfoMap,
                 config,
@@ -288,6 +579,7 @@ export class RunOrchestrator {
             };
         }
         finally {
+            orchestrator.markDone();
             shutdown.dispose();
         }
     }
@@ -335,6 +627,8 @@ export class RunOrchestrator {
             packageManager: this.cfg.packageManager,
             baseBranch: this.cfg.baseBranch,
             onProgress: this.cfg.onProgress,
+            onPhasePlan: this.cfg.onPhasePlan,
+            phasePauseHandle: this.cfg.phasePauseHandle,
         };
     }
     async executeSequential(issueNumbers, batchCtx, options) {
@@ -345,11 +639,34 @@ export class RunOrchestrator {
             if (shutdown?.shuttingDown) {
                 break;
             }
+            // #605: under --stacked, non-first PRs target the predecessor branch.
+            // The final PR still targets `main` (AC-3 open-question default) so the
+            // stack can land partially. Manifest renders for every PR in the stack.
+            let predecessorBranch;
+            let stackManifest;
+            if (options.chain && options.stacked) {
+                if (i > 0 && i < issueNumbers.length - 1) {
+                    // Invariant: chain breaks on prior failure (see `break` below), so the
+                    // predecessor's worktree is always in worktreeMap when we reach this
+                    // branch. The optional-chained fallback to undefined is unreachable.
+                    predecessorBranch = this.cfg.worktreeMap.get(issueNumbers[i - 1])?.branch;
+                }
+                else if (i > 0) {
+                    // Last PR: still emit manifest, but base stays main (no predecessor).
+                    // intentionally undefined predecessorBranch
+                }
+                stackManifest = buildStackManifest(issueNumbers, i);
+            }
             const result = await this.executeOneIssue({
                 issueNumber,
                 batchCtx,
                 chain: options.chain
-                    ? { enabled: true, isLast: i === issueNumbers.length - 1 }
+                    ? {
+                        enabled: true,
+                        isLast: i === issueNumbers.length - 1,
+                        predecessorBranch,
+                        stackManifest,
+                    }
                     : undefined,
             });
             results.push(result);
@@ -398,7 +715,7 @@ export class RunOrchestrator {
     }
     async executeOneIssue(args) {
         const { issueNumber, batchCtx, chain, parallelIssueNumber } = args;
-        const { config, options, issueInfoMap, worktreeMap, logWriter, stateManager, shutdownManager, packageManager, baseBranch, onProgress, } = batchCtx;
+        const { config, options, issueInfoMap, worktreeMap, logWriter, stateManager, shutdownManager, packageManager, baseBranch, onProgress, onPhasePlan, phasePauseHandle, } = batchCtx;
         const issueInfo = issueInfoMap.get(issueNumber) ?? {
             title: `Issue #${issueNumber}`,
             labels: [],
@@ -421,15 +738,46 @@ export class RunOrchestrator {
             packageManager,
             baseBranch,
             onProgress,
+            onPhasePlan,
+            phasePauseHandle,
         };
-        const result = await runIssueWithLogging(ctx);
-        if (logWriter && result.prNumber && result.prUrl) {
-            logWriter.setPRInfo(result.prNumber, result.prUrl, parallelIssueNumber);
+        // Fire-and-forget — orchestrator does not await listener completion on
+        // the lifecycle bracket events. Listener safety is the emitter's job (AC-5).
+        void this.emitter.emit("run_started", { issueNumber });
+        const issueStartedAt = Date.now();
+        // `run_completed` is emitted in the finally so the bracket stays
+        // symmetric with `run_started` even if `runIssueWithLogging` throws —
+        // subscribers (MCP, dashboard) can rely on every started run ending.
+        let result;
+        try {
+            result = await runIssueWithLogging(ctx);
+            // Surface QA verdicts as a dedicated event so consumers don't have to
+            // re-parse phase output. Emits at most once per QA phase result.
+            for (const pr of result.phaseResults) {
+                if (pr.phase === "qa" && pr.verdict) {
+                    void this.emitter.emit("qa_verdict", {
+                        issueNumber,
+                        phase: "qa",
+                        verdict: pr.verdict,
+                    });
+                }
+            }
+            if (logWriter && result.prNumber && result.prUrl) {
+                logWriter.setPRInfo(result.prNumber, result.prUrl, parallelIssueNumber);
+            }
+            if (logWriter) {
+                logWriter.completeIssue(parallelIssueNumber);
+            }
+            return result;
         }
-        if (logWriter) {
-            logWriter.completeIssue(parallelIssueNumber);
+        finally {
+            const durationSec = Math.round((Date.now() - issueStartedAt) / 1000);
+            void this.emitter.emit("run_completed", {
+                issueNumber,
+                duration: durationSec,
+                success: result?.success ?? false,
+            });
         }
-        return result;
     }
     static async recordMetrics(config, mergedOptions, results, worktreeMap, issueNumbers) {
         const metricsWriter = new MetricsWriter({ verbose: config.verbose });
@@ -501,6 +849,97 @@ export class RunOrchestrator {
         }
     }
 }
+function findOrAppendPhase(state, name) {
+    let p = state.phases.find((ph) => ph.name === name);
+    if (!p) {
+        p = { name, status: "pending" };
+        state.phases.push(p);
+    }
+    return p;
+}
+/**
+ * Activity is considered stale (and `nowLine` falls back to the coarse
+ * `running <phase>` form) once it goes this long without an update (#543).
+ */
+const ACTIVITY_STALE_MS = 5_000;
+function cloneIssueState(s) {
+    return {
+        number: s.number,
+        title: s.title,
+        branch: s.branch,
+        status: s.status,
+        startedAt: s.startedAt,
+        completedAt: s.completedAt,
+        phases: s.phases.map((p) => ({
+            name: p.name,
+            status: p.status,
+            startedAt: p.startedAt,
+            elapsedMs: p.elapsedMs,
+        })),
+        currentPhase: s.currentPhase
+            ? {
+                name: s.currentPhase.name,
+                startedAt: s.currentPhase.startedAt,
+                lastActivityAt: s.currentPhase.lastActivityAt,
+                nowLine: nowLineWithStaleFallback(s.currentPhase),
+                logPath: s.currentPhase.logPath,
+            }
+            : undefined,
+    };
+}
+function nowLineWithStaleFallback(current) {
+    const ageMs = Date.now() - current.lastActivityAt.getTime();
+    if (ageMs >= ACTIVITY_STALE_MS) {
+        return formatCoarseNowLine(current.name);
+    }
+    return current.nowLine;
+}
+/**
+ * Reduce a chunk of streamed agent output to a single line suitable for the
+ * activity row. Strips ANSI sequences and trailing whitespace; returns the
+ * last non-empty line, truncated to keep the cell render cheap. Returns
+ * `undefined` when the chunk contains no usable content.
+ */
+function extractActivityLine(raw) {
+    if (!raw)
+        return undefined;
+    // Strip ANSI CSI escapes — covers SGR (colour/bold, `…m`), cursor-movement
+    // and line-clear codes (`\x1b[2K`, `\x1b[G`), and DEC private-mode toggles
+    // (`\x1b[?25l`), any of which can leak through chalk/ink in agent output.
+    // eslint-disable-next-line no-control-regex
+    const cleaned = raw.replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, "");
+    const lines = cleaned.split(/\r?\n/);
+    let last = "";
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const trimmed = lines[i].trim();
+        if (trimmed.length > 0) {
+            last = trimmed;
+            break;
+        }
+    }
+    if (!last)
+        return undefined;
+    // Bound at 200 chars; the TUI truncates further per row width.
+    return last.length > 200 ? last.slice(0, 200) : last;
+}
+/**
+ * Build the synthetic `IssueResult` returned for an issue that was skipped
+ * because another sequant session holds its lock (#625).
+ */
+export function buildLockedResult(issueNumber, holder) {
+    return {
+        issueNumber,
+        success: false,
+        phaseResults: [],
+        abortReason: `locked by PID ${holder.pid}`,
+        locked: {
+            pid: holder.pid,
+            hostname: holder.hostname,
+            startedAt: holder.startedAt,
+            command: holder.command,
+        },
+    };
+}
 /** Log a non-fatal warning: one-line summary always, detail in verbose. */
 export function logNonFatalWarning(message, error, verbose) {
     console.log(chalk.yellow(message));

package/dist/src/lib/workflow/run-reflect.js

@@ -33,7 +33,7 @@ function analyzeTimingPatterns(input, observations, suggestions) {
         // If spec times are similar (within 30%) despite different issues, flag it
         if (max > 0 && min / max > 0.7 && max - min < 120) {
             observations.push(`Spec times similar across issues (${formatSec(min)}–${formatSec(max)}) despite varying complexity`);
-            suggestions.push("Consider `--phases exec,qa` for simple fixes to skip spec");
+            suggestions.push("Consider `--phases exec,qa` for issues where spec is not adding value (the default includes spec, #533)");
         }
     }
     // Flag individual phases that took unusually long

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

@@ -0,0 +1,71 @@
+/**
+ * Runtime state snapshots for multi-issue dashboard rendering.
+ *
+ * Decouples the TUI from the orchestrator: `getSnapshot()` returns an
+ * immutable, plain-object view of current run state that can be safely
+ * read from a render loop without holding locks.
+ */
+import type { Phase } from "./types.js";
+/** Top-level lifecycle status of a single issue. */
+export type IssueStatus = "queued" | "running" | "passed" | "failed";
+/** Per-phase status within an issue. */
+export type PhaseStatus = "pending" | "running" | "done" | "failed";
+/**
+ * One phase's runtime state.
+ * `elapsedMs` is populated once a phase reaches `done` or `failed`.
+ */
+export interface PhaseRuntimeState {
+    name: string;
+    status: PhaseStatus;
+    startedAt?: Date;
+    elapsedMs?: number;
+}
+/**
+ * State of the currently running phase for an issue.
+ * Populated only while a phase is active. Dashboard consumers render
+ * `nowLine` as the activity row and tick `lastActivityAt` for the stamp.
+ */
+export interface CurrentPhaseState {
+    name: string;
+    startedAt: Date;
+    lastActivityAt: Date;
+    nowLine: string;
+    logPath?: string;
+}
+/** Complete runtime state for a single issue. */
+export interface IssueRuntimeState {
+    number: number;
+    title: string;
+    branch: string;
+    status: IssueStatus;
+    phases: PhaseRuntimeState[];
+    currentPhase?: CurrentPhaseState;
+    startedAt?: Date;
+    completedAt?: Date;
+}
+/** Run-level configuration captured at start for the header. */
+export interface RunSnapshotConfig {
+    concurrency: number;
+    baseBranch: string;
+    baseSha?: string;
+    baseFetchedAt?: Date;
+    qualityLoop: boolean;
+}
+/**
+ * A consistent point-in-time view of the entire run.
+ *
+ * Returned as a freshly-allocated plain object by `getSnapshot()`; callers
+ * may read fields concurrently without further synchronization because no
+ * internal mutable references are leaked.
+ */
+export interface RunSnapshot {
+    config: RunSnapshotConfig;
+    issues: IssueRuntimeState[];
+    done: boolean;
+    capturedAt: Date;
+}
+/**
+ * Format a coarse "now" line for a phase transition.
+ * Used as the M1 default when no finer activity signal exists.
+ */
+export declare function formatCoarseNowLine(phase: Phase | string): string;