sequant 2.3.0 → 2.5.0

package/dist/marketplace/external_plugins/sequant/skills/spec/references/parallel-groups.md

@@ -25,6 +25,13 @@ When the implementation involves 3+ independent tasks that could be parallelized
 
 ## Model Selection
 
+> **Note:** Per anthropics/claude-code#43869, the `[model: ...]` annotation
+> below and the `model=` parameter `/exec` passes to `Agent(...)` are currently
+> ignored — every spawned subagent inherits the parent session's model. The
+> guidance here reflects the *intended* tier for each task once upstream fixes
+> ship; the parser in `exec/SKILL.md` is kept intact so it reactivates
+> automatically.
+
 Include a `[model: haiku]` or `[model: sonnet]` annotation at the end of each task line:
 
 | Task Type | Recommended Model |

package/dist/marketplace/external_plugins/sequant/skills/spec/references/quality-checklist.md

@@ -0,0 +1,75 @@
+# Feature Quality Planning — Full Checklist
+
+Use this checklist for **Complex** tier issues or when the exception-based summary in SKILL.md flags significant gaps. For Simple/Standard tiers, the exception-based approach in the main prompt is sufficient.
+
+## Section Applicability
+
+| Issue Type | Sections Required |
+|------------|-------------------|
+| Bug fix | Completeness, Error Handling, Test Coverage |
+| New feature | All sections |
+| Refactor | Completeness, Code Quality, Test Coverage |
+| UI change | All sections including Polish |
+| Backend/API | Completeness, Error Handling, Code Quality, Test Coverage, Best Practices |
+| CLI/Script | Completeness, Error Handling, Test Coverage, Best Practices |
+| Docs only | Completeness only |
+
+## Completeness Check
+
+- [ ] All AC items have corresponding implementation steps
+- [ ] Integration points with existing features identified
+- [ ] No partial implementations or TODOs planned
+- [ ] State management considered (if applicable)
+- [ ] Data flow is complete end-to-end
+
+## Error Handling
+
+- [ ] Invalid input scenarios identified
+- [ ] API/external service failures handled
+- [ ] Edge cases documented (empty, null, max values)
+- [ ] Error messages are user-friendly
+- [ ] Graceful degradation planned
+
+## Code Quality
+
+- [ ] Types fully defined (no `any` planned)
+- [ ] Follows existing patterns in codebase
+- [ ] Error boundaries where needed
+- [ ] No magic strings/numbers
+- [ ] Consistent naming conventions
+
+## Test Coverage Plan
+
+- [ ] Unit tests for business logic
+- [ ] Integration tests for data flow
+- [ ] Edge case tests identified
+- [ ] Mocking strategy appropriate
+- [ ] Critical paths have test coverage
+
+## Best Practices
+
+- [ ] Logging for debugging/observability
+- [ ] Accessibility considerations (if UI)
+- [ ] Performance implications considered
+- [ ] Security reviewed (auth, validation, sanitization)
+- [ ] Documentation updated (if behavior changes)
+
+## Polish (UI features only)
+
+- [ ] Loading states planned
+- [ ] Error states have UI
+- [ ] Empty states handled
+- [ ] Responsive design considered
+- [ ] Keyboard navigation works
+
+## Derived ACs
+
+Based on quality planning, identify additional ACs:
+
+| Source | Derived AC | Priority |
+|--------|-----------|----------|
+| Error Handling | AC-N: Handle [specific error] with [specific response] | High/Medium/Low |
+| Test Coverage | AC-N+1: Add tests for [specific scenario] | High/Medium/Low |
+| Best Practices | AC-N+2: Add logging for [specific operation] | High/Medium/Low |
+
+Derived ACs are numbered sequentially after original ACs.

package/dist/marketplace/external_plugins/sequant/skills/spec/references/recommended-workflow.md

@@ -14,16 +14,18 @@ This document shows the expected output format for the `## Recommended Workflow`
 
 ## Examples
 
-### Simple Bug Fix
+### Simple Bug Fix (spec confirms straightforward scope)
 
 ```markdown
 ## Recommended Workflow
 
 **Phases:** exec → qa
 **Quality Loop:** disabled
-**Reasoning:** Straightforward bug fix with clear root cause. No planning needed.
+**Reasoning:** This spec pass confirmed a clear root cause and narrow scope — no testgen or additional phases required; proceed to exec.
 ```
 
+*Note:* Since #533, spec always runs by default. `**Phases:**` lists phases **after** spec — use `exec → qa` here to indicate "spec is done; only exec and qa remain."
+
 ### Standard Feature
 
 ```markdown

package/dist/marketplace/external_plugins/sequant/skills/test/SKILL.md

@@ -805,33 +805,6 @@ Both can be used together:
 
 ---
 
-## State Tracking
-
-**IMPORTANT:** Update workflow state when running standalone (not orchestrated).
-
-### State Updates (Standalone Only)
-
-When NOT orchestrated (`SEQUANT_ORCHESTRATOR` is not set):
-
-**At skill start:**
-```bash
-npx tsx scripts/state/update.ts start <issue-number> test
-```
-
-**On successful completion:**
-```bash
-npx tsx scripts/state/update.ts complete <issue-number> test
-```
-
-**On failure:**
-```bash
-npx tsx scripts/state/update.ts fail <issue-number> test "X/Y tests failed"
-```
-
-**Why this matters:** State tracking enables dashboard visibility, resume capability, and workflow orchestration. Skills update state when standalone; orchestrators handle state when running workflows.
-
----
-
 ## Output Verification
 
 **Before responding, verify your output includes ALL of these:**

package/dist/marketplace/external_plugins/sequant/skills/testgen/SKILL.md

@@ -39,9 +39,16 @@ When invoked as `/testgen <issue-number>`, your job is to:
 - `/testgen 123` - Generate test stubs for issue #123 based on /spec comment
 - `/testgen` - Generate stubs for the most recently discussed issue in conversation
 
-## Token Optimization with Haiku Sub-Agents
+## Sub-Agent Delegation for Stub Generation
 
-**Purpose:** Test stub generation is highly mechanical and benefits from using haiku sub-agents to minimize token cost.
+**Purpose:** Test stub generation is highly mechanical and is delegated to `sequant-testgen` so the main agent focuses on orchestration.
+
+> **Upstream caveat:** `sequant-testgen` declares `model: haiku`, but per
+> anthropics/claude-code#43869 that declaration is currently ignored — the
+> subagent inherits the parent session's model. Older versions of this doc
+> claimed concrete token-cost savings from haiku. Those numbers are not
+> achievable until the upstream fix ships; treat the haiku claim as the
+> *intended* tier, not the runtime one.
 
 **Pattern:** Use `Agent(subagent_type="sequant-testgen")` for:
 1. Parsing verification criteria from /spec comments
@@ -49,13 +56,12 @@ When invoked as `/testgen <issue-number>`, your job is to:
 3. Writing test file content
 
 **Benefits:**
-- 90% token cost reduction for mechanical generation
-- Faster execution for templated operations
-- Main agent focuses on orchestration and decisions
+- Main agent focuses on orchestration and decisions, not stub templating
+- Designated tier (`haiku`) will yield token savings once anthropics/claude-code#43869 is fixed; today subagents inherit the parent's model
 
 ### Sub-Agent Usage
 
-**Step 1: Parse Verification Criteria (use haiku)**
+**Step 1: Parse Verification Criteria (designated haiku — currently inert per anthropics/claude-code#43869)**
 
 ```javascript
 Agent(subagent_type="sequant-testgen", prompt=`
@@ -87,7 +93,7 @@ ${specComment}
 `)
 ```
 
-**Step 2: Generate Test Stubs (use haiku for each AC)**
+**Step 2: Generate Test Stubs (designated haiku — currently inert per anthropics/claude-code#43869)**
 
 ```javascript
 // For each AC with Unit Test or Integration Test verification method
@@ -122,16 +128,16 @@ The main agent handles file operations to ensure proper coordination:
 
 | Task | Agent | Reasoning |
 |------|-------|-----------|
-| Parse /spec comment | haiku | Mechanical text extraction |
-| Generate test stub code | haiku | Templated generation |
-| Identify failure scenarios | haiku | Pattern matching |
+| Parse /spec comment | `sequant-testgen` (declared haiku, inert per #43869) | Mechanical text extraction |
+| Generate test stub code | `sequant-testgen` (declared haiku, inert per #43869) | Templated generation |
+| Identify failure scenarios | `sequant-testgen` (declared haiku, inert per #43869) | Pattern matching |
 | Decide file locations | main | Requires codebase context |
 | Write files | main | File system coordination |
 | Post GitHub comment | main | Session context needed |
 
 ### Parallel Sub-Agent Execution
 
-When multiple ACs need test stubs, spawn haiku agents in parallel:
+When multiple ACs need test stubs, spawn `sequant-testgen` agents in parallel (declared haiku tier, currently inert per anthropics/claude-code#43869):
 
 ```javascript
 // Spawn all stub generation agents in a single message
@@ -143,11 +149,12 @@ const stubPromises = criteria
 // Main agent writes all files
 ```
 
-**Cost savings example:**
-- 5 AC items with Unit Test verification
-- Without haiku: ~50K tokens (main agent generates all)
-- With haiku: ~5K tokens (main orchestrates, haiku generates)
-- Savings: ~90%
+**Cost savings (when upstream lands):**
+Once anthropics/claude-code#43869 is fixed and the declared haiku tier takes
+effect, delegating mechanical stub generation to `sequant-testgen` will
+substantially reduce token cost vs. having the main agent generate every stub.
+Concrete savings are not measured here because the declaration is currently
+inert.
 
 ## Workflow
 
@@ -626,7 +633,7 @@ Cannot generate test files - no feature worktree exists for Issue #<N>.
 
 **Options:**
 1. Run `/exec <issue>` first (creates worktree automatically)
-2. Create worktree manually: `./scripts/dev/new-feature.sh <issue>`
+2. Create worktree manually: `./scripts/new-feature.sh <issue>`
 3. Use the browser/manual test scenarios from this comment
 ```
 
@@ -672,33 +679,6 @@ Generated with [Claude Code](https://claude.com/claude-code)
 
 ---
 
-## State Tracking
-
-**IMPORTANT:** Update workflow state when running standalone (not orchestrated).
-
-### State Updates (Standalone Only)
-
-When NOT orchestrated (`SEQUANT_ORCHESTRATOR` is not set):
-
-**At skill start:**
-```bash
-npx tsx scripts/state/update.ts start <issue-number> testgen
-```
-
-**On successful completion:**
-```bash
-npx tsx scripts/state/update.ts complete <issue-number> testgen
-```
-
-**On failure:**
-```bash
-npx tsx scripts/state/update.ts fail <issue-number> testgen "Failed to generate test stubs"
-```
-
-**Note:** `/testgen` is an optional skill that generates test stubs. State tracking is informational - it doesn't block subsequent phases.
-
----
-
 ## Output Verification
 
 **Before responding, verify your output includes ALL of these:**

package/dist/src/commands/abort.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `sequant abort <issue>` — out-of-band escape hatch for a running headless
+ * session (#645, Gap 7).
+ *
+ * `sequant prompt --type abort` queues an abort message into the inbox, which
+ * the agent must read via the PostToolUse hook chain. When that chain is
+ * broken (the bug originally reported in #645), no in-band abort can land.
+ *
+ * This command bypasses the inbox entirely: it locates the orchestrator PID
+ * via `state.json.relay.pid` (with the per-issue pidfile as fallback) and
+ * sends signals directly. The receiving end is the existing ShutdownManager
+ * in `sequant run`, which already performs a clean teardown on SIGINT/SIGTERM.
+ */
+export interface AbortCommandOptions {
+    /** Skip the SIGINT grace period; SIGTERM immediately. */
+    force?: boolean;
+    /** Seconds to wait after SIGINT before escalating. Default 10. */
+    graceSeconds?: number;
+    json?: boolean;
+    /** Test seam: override the system kill function. */
+    killFn?: (pid: number, signal: NodeJS.Signals) => void;
+    /** Test seam: override the liveness check. */
+    isAlive?: (pid: number) => boolean;
+    /** Test seam: override the poll interval (ms). Default 250. */
+    pollIntervalMs?: number;
+    /** Test seam: override SIGTERM grace before SIGKILL (ms). Default 3000. */
+    sigtermTimeoutMs?: number;
+    /** Test seam: override SIGKILL final wait (ms). Default 2000. */
+    sigkillTimeoutMs?: number;
+    /** Test seam: override cwd for pidfile resolution. */
+    cwd?: string;
+}
+export declare function abortCommand(argsAndOptions: {
+    args: string[];
+    options: AbortCommandOptions;
+}): Promise<void>;

package/dist/src/commands/abort.js

@@ -0,0 +1,138 @@
+/**
+ * `sequant abort <issue>` — out-of-band escape hatch for a running headless
+ * session (#645, Gap 7).
+ *
+ * `sequant prompt --type abort` queues an abort message into the inbox, which
+ * the agent must read via the PostToolUse hook chain. When that chain is
+ * broken (the bug originally reported in #645), no in-band abort can land.
+ *
+ * This command bypasses the inbox entirely: it locates the orchestrator PID
+ * via `state.json.relay.pid` (with the per-issue pidfile as fallback) and
+ * sends signals directly. The receiving end is the existing ShutdownManager
+ * in `sequant run`, which already performs a clean teardown on SIGINT/SIGTERM.
+ */
+import chalk from "chalk";
+import { isPidAlive, readPidFile } from "../lib/relay/pid.js";
+import { StateManager } from "../lib/workflow/state-manager.js";
+import { findActiveIssues, resolveTargetIssue } from "./prompt.js";
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Send `signal` and wait up to `timeoutMs` for the PID to exit. Returns true
+ * if the process died, false if still alive at the deadline.
+ */
+async function signalAndWait(pid, signal, timeoutMs, isAlive, killFn, pollIntervalMs) {
+    try {
+        killFn(pid, signal);
+    }
+    catch {
+        // ESRCH (process already dead) → success.
+        if (!isAlive(pid))
+            return true;
+        throw new Error(`Failed to send ${signal} to PID ${pid} (signal not delivered)`);
+    }
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!isAlive(pid))
+            return true;
+        await delay(pollIntervalMs);
+    }
+    return !isAlive(pid);
+}
+export async function abortCommand(argsAndOptions) {
+    const { args, options } = argsAndOptions;
+    const json = Boolean(options.json);
+    const killFn = options.killFn ??
+        ((pid, signal) => {
+            process.kill(pid, signal);
+        });
+    const isAlive = options.isAlive ?? isPidAlive;
+    const pollIntervalMs = options.pollIntervalMs ?? 250;
+    const cwd = options.cwd ?? process.cwd();
+    // Resolve target issue: explicit arg or single-active auto-resolve.
+    const stateManager = new StateManager();
+    let issueNumber;
+    const issueArg = args[0];
+    if (issueArg !== undefined) {
+        const n = Number.parseInt(issueArg, 10);
+        if (!Number.isInteger(n) || n <= 0) {
+            throw new Error(`Invalid issue number: '${issueArg}'`);
+        }
+        issueNumber = n;
+    }
+    else {
+        const all = stateManager.stateExists()
+            ? Object.values(await stateManager.getAllIssueStates())
+            : [];
+        const active = findActiveIssues(all, isAlive, cwd);
+        const target = resolveTargetIssue({ explicit: null, activeIssues: active });
+        issueNumber = target.issue;
+    }
+    const issueState = await stateManager.getIssueState(issueNumber);
+    const pid = issueState?.relay?.pid ?? readPidFile(issueNumber, cwd) ?? null;
+    if (pid === null) {
+        const msg = `No relay PID found for #${issueNumber}. Is the run active?`;
+        if (json) {
+            console.log(JSON.stringify({ ok: false, issue: issueNumber, error: msg }));
+        }
+        else {
+            console.error(chalk.yellow(msg));
+        }
+        process.exitCode = 1;
+        return;
+    }
+    if (!isAlive(pid)) {
+        const msg = `PID ${pid} for #${issueNumber} is already dead.`;
+        if (json) {
+            console.log(JSON.stringify({ ok: true, issue: issueNumber, pid, signal: null }));
+        }
+        else {
+            console.log(chalk.gray(msg));
+        }
+        return;
+    }
+    const graceMs = Math.max(0, (options.graceSeconds ?? 10) * 1000);
+    const force = Boolean(options.force);
+    let delivered = "SIGINT";
+    let died = false;
+    if (!force) {
+        if (!json) {
+            console.log(chalk.gray(`Sending SIGINT to PID ${pid} (#${issueNumber}); waiting up to ${graceMs / 1000}s for graceful exit…`));
+        }
+        died = await signalAndWait(pid, "SIGINT", graceMs, isAlive, killFn, pollIntervalMs);
+    }
+    if (!died) {
+        delivered = "SIGTERM";
+        if (!json) {
+            console.log(chalk.yellow(force
+                ? `Sending SIGTERM to PID ${pid} (#${issueNumber}) (--force)…`
+                : `Grace expired; escalating to SIGTERM…`));
+        }
+        died = await signalAndWait(pid, "SIGTERM", options.sigtermTimeoutMs ?? 3000, isAlive, killFn, pollIntervalMs);
+    }
+    if (!died) {
+        delivered = "SIGKILL";
+        if (!json) {
+            console.log(chalk.red(`SIGTERM ignored; escalating to SIGKILL on PID ${pid}…`));
+        }
+        died = await signalAndWait(pid, "SIGKILL", options.sigkillTimeoutMs ?? 2000, isAlive, killFn, pollIntervalMs);
+    }
+    if (!died) {
+        process.exitCode = 1;
+    }
+    if (json) {
+        console.log(JSON.stringify({
+            ok: died,
+            issue: issueNumber,
+            pid,
+            signal: delivered,
+        }));
+    }
+    else if (died) {
+        console.log(chalk.green(`Aborted #${issueNumber} (PID ${pid}, ${delivered}).`));
+    }
+    else {
+        console.error(chalk.red(`Failed to abort #${issueNumber}: PID ${pid} still alive after ${delivered}.`));
+    }
+}

package/dist/src/commands/prompt.d.ts

@@ -7,6 +7,13 @@ import type { IssueState } from "../lib/workflow/state-schema.js";
 export interface PromptCommandOptions {
     type?: string;
     json?: boolean;
+    /**
+     * If set, poll the outbox for a reply that matches the new message ID and
+     * print it inline. Exits 0 on reply, 1 on timeout (#645, Gap 4).
+     */
+    waitSeconds?: number;
+    /** Test seam: override the poll interval (ms). Default 250. */
+    waitPollIntervalMs?: number;
 }
 export interface ParsedPromptArgs {
     issue: number | null;

package/dist/src/commands/prompt.js

@@ -2,10 +2,12 @@
  * `sequant prompt <issue> "<message>"` — send a message into a running
  * headless `sequant run` session via the interactive relay (#383).
  */
+import { existsSync, statSync, readFileSync } from "fs";
 import chalk from "chalk";
-import { RelayMessageTypeSchema, } from "../lib/relay/types.js";
+import { RelayMessageTypeSchema, RelayResponseSchema, } from "../lib/relay/types.js";
 import { appendInboxMessage } from "../lib/relay/writer.js";
 import { cleanupStalePid, readPidFile } from "../lib/relay/pid.js";
+import { outboxPathFor } from "../lib/relay/paths.js";
 import { StateManager } from "../lib/workflow/state-manager.js";
 /** Validate raw CLI args. Throws on invalid type or empty message. */
 export function parseRelayPromptArgs(args, options = {}) {
@@ -150,26 +152,118 @@ export async function promptCommand(argsAndOptions) {
     catch {
         /* swallow */
     }
-    // Build confirmation with current phase + elapsed time.
-    const phase = issueState?.currentPhase ?? "unknown";
+    // Re-fetch state with a fresh manager to bypass any cached snapshot from
+    // the start-of-command read. Without this, `currentPhase` shown in the
+    // confirmation can be a phase-old (#645, Gap 6: user reported "exec phase"
+    // while state.json had advanced to qa).
+    let freshPhase;
+    let freshStartedAt;
+    try {
+        const freshState = await new StateManager().getIssueState(issueNumber);
+        freshPhase = freshState?.currentPhase;
+        freshStartedAt = freshState?.relay?.startedAt;
+    }
+    catch {
+        // Fall back to the issueState we already have.
+        freshPhase = issueState?.currentPhase;
+        freshStartedAt = issueState?.relay?.startedAt;
+    }
     let elapsedSegment = "";
-    if (issueState?.relay?.startedAt) {
-        const ms = Date.now() - new Date(issueState.relay.startedAt).getTime();
+    if (freshStartedAt) {
+        const ms = Date.now() - new Date(freshStartedAt).getTime();
         elapsedSegment = `, ${formatElapsed(ms)} elapsed`;
     }
-    const confirmation = `Message sent to #${issueNumber} (${phase} phase${elapsedSegment})`;
+    // Omit the phase label when we don't have a fresh reading (#645, Gap 6) —
+    // a wrong phase is worse than no phase. Callers asking for JSON still get
+    // an explicit `phase: null` for that case.
+    const phaseSegment = freshPhase
+        ? ` (${freshPhase} phase${elapsedSegment})`
+        : "";
+    const confirmation = `Message sent to #${issueNumber}${phaseSegment}`;
     if (options.json) {
         console.log(JSON.stringify({
             ok: true,
             issue: issueNumber,
             messageId: message.id,
             type: parsed.type,
-            phase,
+            phase: freshPhase ?? null,
         }));
     }
     else {
         console.log(chalk.green(confirmation));
     }
+    // Optional --wait: poll outbox for a reply that references our message id.
+    // Times out with exit 1 if no matching reply lands within the window.
+    if (typeof options.waitSeconds === "number" &&
+        options.waitSeconds > 0 &&
+        parsed.type !== "abort") {
+        const reply = await waitForReply({
+            issueNumber,
+            worktreePath: issueState?.worktree,
+            inReplyTo: message.id,
+            timeoutMs: options.waitSeconds * 1000,
+            pollIntervalMs: options.waitPollIntervalMs ?? 250,
+        });
+        if (reply) {
+            if (options.json) {
+                console.log(JSON.stringify({ ok: true, reply }));
+            }
+            else {
+                console.log(chalk.cyan(`Reply: ${reply.message}`));
+            }
+        }
+        else {
+            const msg = `No reply received within ${options.waitSeconds}s. Message may be archived without a response.`;
+            if (options.json) {
+                console.log(JSON.stringify({ ok: false, timeout: true, error: msg }));
+            }
+            else {
+                console.error(chalk.yellow(msg));
+            }
+            process.exitCode = 1;
+        }
+    }
+}
+async function waitForReply(options) {
+    const outboxPath = outboxPathFor(options.issueNumber, {
+        worktreePath: options.worktreePath,
+    });
+    // Seed offset at current EOF: only NEW replies count for this prompt's wait.
+    let offset = existsSync(outboxPath) ? statSync(outboxPath).size : 0;
+    let partial = "";
+    const deadline = Date.now() + options.timeoutMs;
+    while (Date.now() < deadline) {
+        if (existsSync(outboxPath)) {
+            try {
+                const size = statSync(outboxPath).size;
+                if (size > offset) {
+                    const chunk = readFileSync(outboxPath, "utf-8").slice(offset);
+                    offset = size;
+                    const lines = (partial + chunk).split("\n");
+                    partial = lines.pop() ?? "";
+                    for (const line of lines) {
+                        if (line.trim() === "")
+                            continue;
+                        try {
+                            const parsed = RelayResponseSchema.safeParse(JSON.parse(line));
+                            if (parsed.success &&
+                                parsed.data.inReplyTo === options.inReplyTo) {
+                                return parsed.data;
+                            }
+                        }
+                        catch {
+                            /* skip malformed */
+                        }
+                    }
+                }
+            }
+            catch {
+                /* transient — try again */
+            }
+        }
+        await new Promise((r) => setTimeout(r, options.pollIntervalMs));
+    }
+    return null;
 }
 function formatElapsed(ms) {
     const totalSec = Math.max(0, Math.floor(ms / 1000));

package/dist/src/commands/ready-tui-adapter.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Single-issue snapshot adapter for `sequant ready` (#699 Part A).
+ *
+ * The Ink TUI is pull-based: `App` polls `getSnapshot(): RunSnapshot` at 10 Hz
+ * (see `src/ui/tui/index.ts`). But `ready` has no `RunOrchestrator` — its
+ * progress arrives push-style via the gate's `onProgress` hook (#697). This
+ * adapter bridges the two: a small mutable tracker the gate feeds, exposing a
+ * `getSnapshot()` that returns a one-issue `RunSnapshot` for the TUI to mount.
+ *
+ * The gate fires `start`/`complete`/`failed` around each `qa`/`loop` pass; we
+ * model those passes as the phase row, with a coarse `nowLine`
+ * (`formatCoarseNowLine`) — no agent-stream enrichment (a stated Non-Goal).
+ */
+import type { ProgressCallback } from "../lib/workflow/types.js";
+import { type RunSnapshot } from "../lib/workflow/run-state.js";
+export interface ReadySnapshotAdapterOptions {
+    issueNumber: number;
+    title: string;
+    branch: string;
+    /** Surfaced in the snapshot config header; `ready` always loops. */
+    qualityLoop?: boolean;
+}
+/**
+ * Mutable single-issue runtime tracker that doubles as a TUI snapshot provider.
+ *
+ * Lifecycle: construct → mount `renderTui(adapter)` → pass `adapter.onProgress`
+ * to the gate → on gate resolution call `markDone(ready)` so the polling `App`
+ * sees `done` and unmounts.
+ */
+export declare class ReadySnapshotAdapter {
+    private readonly issueNumber;
+    private readonly title;
+    private readonly branch;
+    private readonly qualityLoop;
+    private status;
+    private readonly phases;
+    private currentPhase;
+    private startedAt;
+    private completedAt;
+    private finished;
+    constructor(opts: ReadySnapshotAdapterOptions);
+    /**
+     * `ProgressCallback`-shaped sink wired into the gate's `onProgress`.
+     *
+     * - `start`    → append a running phase + set `currentPhase` (coarse nowLine).
+     * - `complete` → mark the active phase done, record elapsed, clear nowLine.
+     * - `failed`   → mark the active phase failed, flip issue status to failed.
+     * - `activity` → refresh the activity stamp / nowLine if a finer signal lands.
+     */
+    readonly onProgress: ProgressCallback;
+    /**
+     * Mark the run finished after `runReadyGate` resolves. Flips the snapshot's
+     * `done` flag so the polling `App` unmounts, and sets a terminal status
+     * (failed wins if a phase already failed).
+     */
+    markDone(ready: boolean): void;
+    /** Pull-based snapshot consumed by the TUI's 10 Hz poll loop. */
+    getSnapshot(): RunSnapshot;
+}