sequant 2.1.2 → 2.3.0

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

@@ -188,10 +188,18 @@ export async function cleanupStaleEntries(options = {}) {
 /**
  * Lightweight state reconciliation at run start
  *
- * Checks issues in `ready_for_merge` state and advances them to `merged`
- * if their PRs are merged or their branches are in main.
+ * Checks issues in `ready_for_merge`, `in_progress`, or `waiting_for_qa_gate`
+ * state and advances them to `merged` if their PRs are merged or their branches
+ * are in main.
  *
- * This prevents re-running already completed issues.
+ * Including `in_progress` covers the case where a PR was merged outside
+ * this sequant session (separate process, `gh pr merge`, web UI) — without
+ * it, the run command would re-execute already-merged issues. See #592.
+ *
+ * Including `waiting_for_qa_gate` covers the symmetric case where a PR
+ * awaiting human QA-gate approval is merged externally before the next
+ * sequant session — without it, `sequant run <N>` re-executes the QA phase
+ * against already-merged work. See #606.
  *
  * @param options - Reconciliation options
  * @returns Result with lists of advanced and still-pending issues
@@ -213,9 +221,13 @@ export async function reconcileStateAtStartup(options = {}) {
         const state = await manager.getState();
         const advanced = [];
         const stillPending = [];
-        // Find issues in ready_for_merge state
+        // Find issues in ready_for_merge, in_progress, or waiting_for_qa_gate state.
+        // in_progress covers PRs merged outside this session (#592).
+        // waiting_for_qa_gate covers PRs merged before the next QA-gate run (#606).
         for (const [issueNumStr, issueState] of Object.entries(state.issues)) {
-            if (issueState.status !== "ready_for_merge") {
+            if (issueState.status !== "ready_for_merge" &&
+                issueState.status !== "in_progress" &&
+                issueState.status !== "waiting_for_qa_gate") {
                 continue;
             }
             const issueNum = parseInt(issueNumStr, 10);

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

@@ -20,7 +20,7 @@
  * const state = await manager.getIssueState(42);
  * ```
  */
-import { type WorkflowState, type IssueState, type Phase, type PhaseStatus, type IssueStatus, type PRInfo, type AcceptanceCriteria, type ACStatus } from "./state-schema.js";
+import { type WorkflowState, type IssueState, type Phase, type PhaseStatus, type IssueStatus, type PRInfo, type AcceptanceCriteria, type ACStatus, type RelayState } from "./state-schema.js";
 import type { ScopeAssessment } from "../scope/types.js";
 export interface StateManagerOptions {
     /** Path to state file (default: .sequant/state.json) */
@@ -133,6 +133,17 @@ export declare class StateManager {
      * Update session ID for an issue (for resume)
      */
     updateSessionId(issueNumber: number, sessionId: string): Promise<void>;
+    /**
+     * Set or clear the relay state for an issue (#383).
+     *
+     * Pass `null` to remove the relay field entirely (deactivation). Pass an
+     * object to overwrite the current relay state (activation or refresh).
+     */
+    setRelayState(issueNumber: number, relay: RelayState | null): Promise<void>;
+    /**
+     * Increment the relay message counter. No-op when relay isn't active.
+     */
+    incrementRelayMessageCount(issueNumber: number, delta?: number): Promise<void>;
     /**
      * Update loop iteration for an issue
      */

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

@@ -392,6 +392,43 @@ export class StateManager {
             await this.saveState(state);
         });
     }
+    /**
+     * Set or clear the relay state for an issue (#383).
+     *
+     * Pass `null` to remove the relay field entirely (deactivation). Pass an
+     * object to overwrite the current relay state (activation or refresh).
+     */
+    async setRelayState(issueNumber, relay) {
+        await this.withLock(async () => {
+            const state = await this.getState();
+            const issueState = state.issues[String(issueNumber)];
+            if (!issueState) {
+                throw new Error(`Issue #${issueNumber} not found in state`);
+            }
+            if (relay === null) {
+                delete issueState.relay;
+            }
+            else {
+                issueState.relay = relay;
+            }
+            issueState.lastActivity = new Date().toISOString();
+            await this.saveState(state);
+        });
+    }
+    /**
+     * Increment the relay message counter. No-op when relay isn't active.
+     */
+    async incrementRelayMessageCount(issueNumber, delta = 1) {
+        await this.withLock(async () => {
+            const state = await this.getState();
+            const issueState = state.issues[String(issueNumber)];
+            if (!issueState || !issueState.relay)
+                return;
+            issueState.relay.messageCount += delta;
+            issueState.lastActivity = new Date().toISOString();
+            await this.saveState(state);
+        });
+    }
     /**
      * Update loop iteration for an issue
      */

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

@@ -156,11 +156,12 @@ export declare function ensureWorktreesChain(issues: Array<{
     title: string;
 }>, verbose: boolean, packageManager?: string, baseBranch?: string): Promise<Map<number, WorktreeInfo>>;
 /**
- * Create a checkpoint commit in the worktree after QA passes
- * This allows recovery in case later issues in the chain fail
+ * Create a checkpoint commit in the worktree after QA passes.
+ * Only stages files that were touched by the issue's commits (diff vs baseBranch).
+ * If unrelated dirty files exist, emits a warning and skips the checkpoint.
  * @internal Exported for testing
  */
-export declare function createCheckpointCommit(worktreePath: string, issueNumber: number, verbose: boolean): boolean;
+export declare function createCheckpointCommit(worktreePath: string, issueNumber: number, verbose: boolean, baseBranch?: string): boolean;
 /**
  * Check if any lockfile changed during a rebase and re-run install if needed.
  * This prevents dependency drift when the lockfile was updated on main.
@@ -199,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

@@ -612,30 +612,80 @@ export async function ensureWorktreesChain(issues, verbose, packageManager, base
     return worktrees;
 }
 /**
- * Create a checkpoint commit in the worktree after QA passes
- * This allows recovery in case later issues in the chain fail
+ * Create a checkpoint commit in the worktree after QA passes.
+ * Only stages files that were touched by the issue's commits (diff vs baseBranch).
+ * If unrelated dirty files exist, emits a warning and skips the checkpoint.
  * @internal Exported for testing
  */
-export function createCheckpointCommit(worktreePath, issueNumber, verbose) {
-    // Check if there are uncommitted changes
-    const statusResult = spawnSync("git", ["-C", worktreePath, "status", "--porcelain"], { stdio: "pipe" });
+export function createCheckpointCommit(worktreePath, issueNumber, verbose, baseBranch) {
+    // Check if there are uncommitted changes.
+    // Use -z (NUL-terminated) so paths with unicode or special chars aren't quoted/escaped.
+    const statusResult = spawnSync("git", ["-C", worktreePath, "status", "--porcelain", "-z"], { stdio: "pipe" });
     if (statusResult.status !== 0) {
         if (verbose) {
             console.log(chalk.yellow(`    !  Could not check git status for checkpoint`));
         }
         return false;
     }
-    const hasChanges = statusResult.stdout.toString().trim().length > 0;
-    if (!hasChanges) {
+    const statusRaw = statusResult.stdout.toString();
+    if (statusRaw.length === 0) {
         if (verbose) {
             console.log(chalk.gray(`    📌 No changes to checkpoint (already committed)`));
         }
         return true;
     }
-    // Stage all changes
-    const addResult = spawnSync("git", ["-C", worktreePath, "add", "-A"], {
-        stdio: "pipe",
-    });
+    // Parse NUL-separated porcelain entries. Each entry is "XY path".
+    // For renames/copies, the next entry is the old path and must be consumed.
+    const entries = statusRaw.split("\0").filter((e) => e.length > 0);
+    const dirtyFiles = [];
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        const xy = entry.slice(0, 2);
+        const path = entry.slice(3);
+        if (path)
+            dirtyFiles.push(path);
+        // Rename (R) and copy (C) entries are followed by the original path — skip it
+        if (xy[0] === "R" || xy[0] === "C") {
+            i++;
+        }
+    }
+    // Determine which files to stage.
+    // When baseBranch is provided (chain mode), scope to feature paths only.
+    // When baseBranch is absent (non-chain), treat all dirty files as in-scope.
+    let inScope;
+    if (baseBranch) {
+        const diffResult = spawnSync("git", ["-C", worktreePath, "diff", "--name-only", "-z", `${baseBranch}...HEAD`], { stdio: "pipe" });
+        const featurePaths = new Set();
+        if (diffResult.status === 0) {
+            diffResult.stdout
+                .toString()
+                .split("\0")
+                .filter((p) => p.length > 0)
+                .forEach((p) => featurePaths.add(p));
+        }
+        inScope = dirtyFiles.filter((f) => featurePaths.has(f));
+        const outOfScope = dirtyFiles.filter((f) => !featurePaths.has(f));
+        // AC-2: If unrelated dirty files exist, warn and skip checkpoint
+        if (outOfScope.length > 0) {
+            console.log(chalk.yellow(`    ⚠  Skipping checkpoint for #${issueNumber}: ${outOfScope.length} unrelated dirty file(s) in worktree:`));
+            for (const f of outOfScope) {
+                console.log(chalk.yellow(`       - ${f}`));
+            }
+            return false;
+        }
+    }
+    else {
+        // Non-chain mode: all dirty files are in-scope
+        inScope = dirtyFiles;
+    }
+    if (inScope.length === 0) {
+        if (verbose) {
+            console.log(chalk.gray(`    📌 No in-scope changes to checkpoint`));
+        }
+        return true;
+    }
+    // AC-1: Stage only in-scope feature paths
+    const addResult = spawnSync("git", ["-C", worktreePath, "add", "--", ...inScope], { stdio: "pipe" });
     if (addResult.status !== 0) {
         if (verbose) {
             console.log(chalk.yellow(`    !  Could not stage changes for checkpoint`));
@@ -793,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);
@@ -832,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.