sequant 2.2.0 → 2.4.0

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

@@ -0,0 +1,14 @@
+/**
+ * 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.
+ */
+/**
+ * Format a coarse "now" line for a phase transition.
+ * Used as the M1 default when no finer activity signal exists.
+ */
+export function formatCoarseNowLine(phase) {
+    return `running ${phase}`;
+}

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

@@ -58,9 +58,9 @@ export interface ReconcileOptions {
 export interface ReconcileResult {
     /** Whether reconciliation was successful */
     success: boolean;
-    /** Issues that were advanced from ready_for_merge to merged */
+    /** Issues advanced to `merged` (from `ready_for_merge`, `in_progress`, or `waiting_for_qa_gate`) */
     advanced: number[];
-    /** Issues checked but still ready_for_merge */
+    /** Issues checked but not yet merged (status unchanged) */
     stillPending: number[];
     /** Error message if failed */
     error?: string;
@@ -68,10 +68,18 @@ export interface ReconcileResult {
 /**
  * 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

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) */
@@ -130,9 +130,38 @@ export declare class StateManager {
      */
     updateWorktreeInfo(issueNumber: number, worktree: string, branch: string): Promise<void>;
     /**
-     * Update session ID for an issue (for resume)
+     * Update session ID for an issue (for resume).
+     *
+     * @deprecated Use {@link updateResumeHandle} (#674). This entry point only
+     * writes the legacy `sessionId` field — without an `originCwd`, the next
+     * phase's driver-owned `canResume()` fail-safe will decline resume, so the
+     * data is effectively inert. Retained for one release to keep callers from
+     * older sequant builds compiling.
      */
     updateSessionId(issueNumber: number, sessionId: string): Promise<void>;
+    /**
+     * Update the driver-tagged resume handle for an issue (#674).
+     *
+     * Writes both the new `resumeHandle` field and mirrors the token into
+     * the deprecated `sessionId` field so state files round-trip through
+     * older sequant readers for one release.
+     */
+    updateResumeHandle(issueNumber: number, handle: {
+        driver: string;
+        token: string;
+        originCwd: 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

@@ -378,7 +378,13 @@ export class StateManager {
         }
     }
     /**
-     * Update session ID for an issue (for resume)
+     * Update session ID for an issue (for resume).
+     *
+     * @deprecated Use {@link updateResumeHandle} (#674). This entry point only
+     * writes the legacy `sessionId` field — without an `originCwd`, the next
+     * phase's driver-owned `canResume()` fail-safe will decline resume, so the
+     * data is effectively inert. Retained for one release to keep callers from
+     * older sequant builds compiling.
      */
     async updateSessionId(issueNumber, sessionId) {
         await this.withLock(async () => {
@@ -392,6 +398,63 @@ export class StateManager {
             await this.saveState(state);
         });
     }
+    /**
+     * Update the driver-tagged resume handle for an issue (#674).
+     *
+     * Writes both the new `resumeHandle` field and mirrors the token into
+     * the deprecated `sessionId` field so state files round-trip through
+     * older sequant readers for one release.
+     */
+    async updateResumeHandle(issueNumber, handle) {
+        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`);
+            }
+            issueState.resumeHandle = handle;
+            issueState.sessionId = handle.token;
+            issueState.lastActivity = new Date().toISOString();
+            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

@@ -19,9 +19,14 @@
 import { z } from "zod";
 import { PhaseSchema } from "./types.js";
 /**
- * Workflow phases in order of execution
+ * Workflow phases in order of execution.
+ *
+ * Sourced from the phase registry — replaces the previous `PhaseSchema.options`
+ * literal that existed when `PhaseSchema` was a `z.enum`. Computed at module
+ * load (after `built-in-phases.ts` has run); insertion order is the canonical
+ * pipeline order.
  */
-export declare const WORKFLOW_PHASES: ("qa" | "loop" | "verify" | "spec" | "security-review" | "exec" | "testgen" | "test" | "merger")[];
+export declare const WORKFLOW_PHASES: readonly string[];
 /**
  * Phase status - tracks individual phase progress
  */
@@ -54,17 +59,7 @@ export type { Phase } from "./types.js";
  * Embedded as HTML comments: `<!-- SEQUANT_PHASE: {...} -->`
  */
 export declare const PhaseMarkerSchema: z.ZodObject<{
-    phase: z.ZodEnum<{
-        qa: "qa";
-        loop: "loop";
-        verify: "verify";
-        spec: "spec";
-        "security-review": "security-review";
-        exec: "exec";
-        testgen: "testgen";
-        test: "test";
-        merger: "merger";
-    }>;
+    phase: z.ZodString;
     status: z.ZodEnum<{
         pending: "pending";
         skipped: "skipped";
@@ -186,6 +181,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
  */
@@ -203,17 +228,7 @@ export declare const IssueStateSchema: z.ZodObject<{
     }>;
     worktree: z.ZodOptional<z.ZodString>;
     branch: z.ZodOptional<z.ZodString>;
-    currentPhase: z.ZodOptional<z.ZodEnum<{
-        qa: "qa";
-        loop: "loop";
-        verify: "verify";
-        spec: "spec";
-        "security-review": "security-review";
-        exec: "exec";
-        testgen: "testgen";
-        test: "test";
-        merger: "merger";
-    }>>;
+    currentPhase: z.ZodOptional<z.ZodString>;
     phases: z.ZodRecord<z.ZodString, z.ZodObject<{
         status: z.ZodEnum<{
             pending: "pending";
@@ -301,7 +316,28 @@ 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>;
+    resumeHandle: z.ZodOptional<z.ZodObject<{
+        driver: z.ZodString;
+        token: z.ZodString;
+        originCwd: z.ZodString;
+    }, z.core.$strip>>;
     resolvedAt: z.ZodOptional<z.ZodString>;
     lastActivity: z.ZodString;
     createdAt: z.ZodString;
@@ -330,17 +366,7 @@ export declare const WorkflowStateSchema: z.ZodObject<{
         }>;
         worktree: z.ZodOptional<z.ZodString>;
         branch: z.ZodOptional<z.ZodString>;
-        currentPhase: z.ZodOptional<z.ZodEnum<{
-            qa: "qa";
-            loop: "loop";
-            verify: "verify";
-            spec: "spec";
-            "security-review": "security-review";
-            exec: "exec";
-            testgen: "testgen";
-            test: "test";
-            merger: "merger";
-        }>>;
+        currentPhase: z.ZodOptional<z.ZodString>;
         phases: z.ZodRecord<z.ZodString, z.ZodObject<{
             status: z.ZodEnum<{
                 pending: "pending";
@@ -428,7 +454,28 @@ 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>;
+        resumeHandle: z.ZodOptional<z.ZodObject<{
+            driver: z.ZodString;
+            token: z.ZodString;
+            originCwd: z.ZodString;
+        }, z.core.$strip>>;
         resolvedAt: z.ZodOptional<z.ZodString>;
         lastActivity: z.ZodString;
         createdAt: z.ZodString;

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

@@ -19,10 +19,16 @@
 import { z } from "zod";
 import { ScopeAssessmentSchema } from "../scope/types.js";
 import { PhaseSchema } from "./types.js";
+import { getPhaseNames } from "./phase-registry.js";
 /**
- * Workflow phases in order of execution
+ * Workflow phases in order of execution.
+ *
+ * Sourced from the phase registry — replaces the previous `PhaseSchema.options`
+ * literal that existed when `PhaseSchema` was a `z.enum`. Computed at module
+ * load (after `built-in-phases.ts` has run); insertion order is the canonical
+ * pipeline order.
  */
-export const WORKFLOW_PHASES = PhaseSchema.options;
+export const WORKFLOW_PHASES = getPhaseNames();
 /**
  * Phase status - tracks individual phase progress
  */
@@ -31,7 +37,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 +159,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,8 +215,31 @@ export const IssueStateSchema = z.object({
     acceptanceCriteria: AcceptanceCriteriaSchema.optional(),
     /** Scope assessment result (if performed by /spec) */
     scopeAssessment: ScopeAssessmentSchema.optional(),
-    /** Claude session ID (for resume) */
+    /** 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).
+     * @deprecated Use {@link resumeHandle} (#674). Retained as a read-path
+     * mirror of `resumeHandle.token` for one release so state files written by
+     * prior sequant builds load cleanly. Legacy entries (token without
+     * `originCwd`) intentionally do NOT resume — the driver-owned `canResume`
+     * fail-safe disables them.
+     */
     sessionId: z.string().optional(),
+    /**
+     * Driver-tagged resume handle (#674). Stores the driver name, the
+     * resume token, and the cwd the session was created in so the next phase
+     * can prove cwd-equality before reattaching.
+     */
+    resumeHandle: z
+        .object({
+        driver: z.string(),
+        token: z.string(),
+        originCwd: z.string(),
+    })
+        .optional(),
     /** When the issue transitioned to a terminal status (merged/abandoned/closed) */
     resolvedAt: z.string().datetime().optional(),
     /** Most recent activity timestamp */