sequant 2.8.0 → 2.10.0

package/dist/src/lib/workflow/skills-preflight.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Skills pre-flight for `sequant run` (#813).
+ *
+ * The claude-code driver executes phases as slash-command skills loaded from
+ * project scope only (`settingSources: ["project"]`, #19/#711). Without
+ * `.claude/skills/` the phase agent hunts for a command that can never
+ * resolve, does no work, and the run surfaces as a bogus "spec retry"
+ * failure. This module computes the skills a run actually needs — from the
+ * phases resolved for that run, not a hardcoded triple — and checks them via
+ * the same `checkSkillsInstalled` helper `doctor` uses, so the two cannot
+ * drift.
+ *
+ * Drivers whose phase prompts do the work inline (aider's `driverOverrides`
+ * templates in phase-registry.ts) never resolve skills, so the pre-flight is
+ * skipped for them via `AgentDriver.resolvesSkills`.
+ */
+import type { AiderSettings } from "../settings.js";
+import type { Phase } from "./types.js";
+export interface SkillsPreflightInput {
+    /** Agent driver name (default claude-code). */
+    agent?: string;
+    /** Aider settings, forwarded to the driver factory. */
+    aiderSettings?: AiderSettings;
+    /** Base pipeline for explicit-phase runs (`config.phases`). */
+    phases: Phase[];
+    /** True when phases are auto-detected from labels (no explicit --phases). */
+    autoDetectPhases: boolean;
+    /** True when the quality loop may invoke the loop skill. */
+    qualityLoop: boolean;
+    /** Additive phase flags (`--testgen` / `--security-review`). */
+    testgen?: boolean;
+    securityReview?: boolean;
+    /** Issues in the run, with their labels (drives per-issue phase rules). */
+    issueNumbers: number[];
+    issueInfoMap: Map<number, {
+        title: string;
+        labels: string[];
+    }>;
+    /** Project root to check under (default: `process.cwd()`). */
+    cwd?: string;
+}
+export type SkillsPreflightResult = {
+    ok: true;
+} | {
+    ok: false;
+    /** Human-readable cause, e.g. `missing skills: spec, exec, qa`. */
+    cause: string;
+    /** Missing skill names, in required order. */
+    missingSkills: string[];
+    /** Driver whose skill resolution triggered the check. */
+    driverName: string;
+    /** Remedy line for display. */
+    remedy: string;
+};
+/**
+ * Compute the union of skills required by the phases resolved for this run.
+ *
+ * Explicit-phase runs start from `phases` as given; auto-detect runs start
+ * from each issue's label-detected pipeline. Both then apply the additive
+ * `--testgen` / `--security-review` / UI-label rules via
+ * `determinePhasesForIssue`.
+ *
+ * Two deliberate over-approximations keep late-added phases covered:
+ *
+ * - An explicit `--testgen` / `--security-review` flag requires its skill
+ *   unconditionally, even when `determinePhasesForIssue` would not insert
+ *   the phase because `spec` is absent from the pipeline. On a resume where
+ *   spec already completed, batch-executor inserts the phase anyway
+ *   (`phases.includes("spec") || specAlreadyRan`), and the pre-flight cannot
+ *   cheaply know `specAlreadyRan` — requiring the skill the user asked for
+ *   is the safe superset.
+ * - The loop skill is required when the quality loop is enabled up front OR
+ *   when any issue's labels would auto-enable it (`complex`/`refactor`/...,
+ *   via `detectPhasesFromLabels().qualityLoop`), since the loop skill is
+ *   invoked the same way as any phase skill.
+ *
+ * Phases recommended later by spec output (`parseRecommendedWorkflow`)
+ * remain unknowable at pre-flight time — the accepted gap documented on
+ * #813.
+ *
+ * Exported for direct unit testing (AC-2).
+ */
+export declare function resolveRequiredSkills(input: Pick<SkillsPreflightInput, "phases" | "autoDetectPhases" | "qualityLoop" | "testgen" | "securityReview" | "issueNumbers" | "issueInfoMap">): string[];
+/**
+ * Run the skills pre-flight. Returns `{ok: true}` when the run may proceed:
+ * either every required skill is installed, or the selected driver does not
+ * resolve skills at all (AC-3).
+ */
+export declare function runSkillsPreflight(input: SkillsPreflightInput): Promise<SkillsPreflightResult>;

package/dist/src/lib/workflow/skills-preflight.js

@@ -0,0 +1,112 @@
+/**
+ * Skills pre-flight for `sequant run` (#813).
+ *
+ * The claude-code driver executes phases as slash-command skills loaded from
+ * project scope only (`settingSources: ["project"]`, #19/#711). Without
+ * `.claude/skills/` the phase agent hunts for a command that can never
+ * resolve, does no work, and the run surfaces as a bogus "spec retry"
+ * failure. This module computes the skills a run actually needs — from the
+ * phases resolved for that run, not a hardcoded triple — and checks them via
+ * the same `checkSkillsInstalled` helper `doctor` uses, so the two cannot
+ * drift.
+ *
+ * Drivers whose phase prompts do the work inline (aider's `driverOverrides`
+ * templates in phase-registry.ts) never resolve skills, so the pre-flight is
+ * skipped for them via `AgentDriver.resolvesSkills`.
+ */
+import { getDriver } from "./drivers/index.js";
+import { detectPhasesFromLabels, determinePhasesForIssue, } from "./phase-mapper.js";
+import { phaseRegistry } from "./phase-registry.js";
+import { checkSkillsInstalled, SKILLS_DIR } from "../skills-check.js";
+/**
+ * Compute the union of skills required by the phases resolved for this run.
+ *
+ * Explicit-phase runs start from `phases` as given; auto-detect runs start
+ * from each issue's label-detected pipeline. Both then apply the additive
+ * `--testgen` / `--security-review` / UI-label rules via
+ * `determinePhasesForIssue`.
+ *
+ * Two deliberate over-approximations keep late-added phases covered:
+ *
+ * - An explicit `--testgen` / `--security-review` flag requires its skill
+ *   unconditionally, even when `determinePhasesForIssue` would not insert
+ *   the phase because `spec` is absent from the pipeline. On a resume where
+ *   spec already completed, batch-executor inserts the phase anyway
+ *   (`phases.includes("spec") || specAlreadyRan`), and the pre-flight cannot
+ *   cheaply know `specAlreadyRan` — requiring the skill the user asked for
+ *   is the safe superset.
+ * - The loop skill is required when the quality loop is enabled up front OR
+ *   when any issue's labels would auto-enable it (`complex`/`refactor`/...,
+ *   via `detectPhasesFromLabels().qualityLoop`), since the loop skill is
+ *   invoked the same way as any phase skill.
+ *
+ * Phases recommended later by spec output (`parseRecommendedWorkflow`)
+ * remain unknowable at pre-flight time — the accepted gap documented on
+ * #813.
+ *
+ * Exported for direct unit testing (AC-2).
+ */
+export function resolveRequiredSkills(input) {
+    const additiveFlags = {
+        testgen: input.testgen,
+        securityReview: input.securityReview,
+    };
+    const requiredPhases = new Set();
+    let qualityLoop = input.qualityLoop;
+    for (const issueNumber of input.issueNumbers) {
+        const labels = input.issueInfoMap.get(issueNumber)?.labels ?? [];
+        const detected = input.autoDetectPhases
+            ? detectPhasesFromLabels(labels)
+            : null;
+        if (detected?.qualityLoop)
+            qualityLoop = true;
+        const basePhases = detected ? detected.phases : input.phases;
+        for (const phase of determinePhasesForIssue(basePhases, labels, additiveFlags)) {
+            requiredPhases.add(phase);
+        }
+    }
+    if (input.testgen)
+        requiredPhases.add("testgen");
+    if (input.securityReview)
+        requiredPhases.add("security-review");
+    if (qualityLoop)
+        requiredPhases.add("loop");
+    return [...requiredPhases].map((phase) => phaseRegistry.get(phase).skill);
+}
+/**
+ * Run the skills pre-flight. Returns `{ok: true}` when the run may proceed:
+ * either every required skill is installed, or the selected driver does not
+ * resolve skills at all (AC-3).
+ */
+export async function runSkillsPreflight(input) {
+    let driver;
+    try {
+        driver = getDriver(input.agent, {
+            aiderSettings: input.aiderSettings,
+        });
+    }
+    catch {
+        // Unknown driver name (bad `settings.run.agent`). Don't let the
+        // pre-flight be the thing that crashes the run with a raw throw —
+        // skip it and let phase-executor surface the unknown-driver error
+        // through its normal per-issue failure path.
+        return { ok: true };
+    }
+    if (!driver.resolvesSkills)
+        return { ok: true };
+    const requiredSkills = resolveRequiredSkills(input);
+    const { skillsDirExists, missingSkills } = await checkSkillsInstalled(requiredSkills, input.cwd);
+    if (missingSkills.length === 0)
+        return { ok: true };
+    const cause = skillsDirExists
+        ? `missing skills: ${missingSkills.join(", ")}`
+        : `missing ${SKILLS_DIR}/ directory (needs: ${missingSkills.join(", ")})`;
+    return {
+        ok: false,
+        cause,
+        missingSkills,
+        driverName: driver.name,
+        remedy: `The ${driver.name} driver resolves phases from ${SKILLS_DIR}/ — ` +
+            `run \`sequant sync\` to install them, then re-run.`,
+    };
+}

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

@@ -221,13 +221,20 @@ export async function reconcileStateAtStartup(options = {}) {
         const state = await manager.getState();
         const advanced = [];
         const stillPending = [];
-        // Find issues in ready_for_merge, in_progress, or waiting_for_qa_gate state.
+        // Find issues whose PR may have merged since their status was written.
         // in_progress covers PRs merged outside this session (#592).
         // waiting_for_qa_gate covers PRs merged before the next QA-gate run (#606).
+        // waiting_for_human_merge covers #817's `--ready-gate` terminal: a gated
+        // issue never reaches ready_for_merge, so without it a gated issue whose PR
+        // a human then merged stayed here forever and never advanced to merged
+        // (#837). Note this list is deliberately WIDER than `isCompletedIssueStatus`
+        // — it asks "might this have a merged PR?", not "is this done?", which is
+        // why in_progress belongs here but not there.
         for (const [issueNumStr, issueState] of Object.entries(state.issues)) {
             if (issueState.status !== "ready_for_merge" &&
                 issueState.status !== "in_progress" &&
-                issueState.status !== "waiting_for_qa_gate") {
+                issueState.status !== "waiting_for_qa_gate" &&
+                issueState.status !== "waiting_for_human_merge") {
                 continue;
             }
             const issueNum = parseInt(issueNumStr, 10);

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

@@ -126,6 +126,39 @@ export declare class StateManager {
      * Update PR information for an issue
      */
     updatePRInfo(issueNumber: number, pr: PRInfo): Promise<void>;
+    /**
+     * Record or clear an in-progress auto-wait (#860). `wakeAtMs` sets the
+     * pause marker (and which phase is paused); `null` clears it on wake.
+     *
+     * Unlike the sibling updaters this NEVER throws on an untracked issue —
+     * it is called from a liveness hook during a live wait, and a bookkeeping
+     * miss must not interrupt the pause it is describing.
+     */
+    updateAutoWait(issueNumber: number, phase: string, wakeAtMs: number | null): Promise<void>;
+    /**
+     * Record a durable waitable-window halt (#892 AC-1). Preserves an existing
+     * re-entry counter so repeated halts on a still-closed window keep counting
+     * toward the re-entry bound instead of resetting it.
+     *
+     * Like `updateAutoWait`, NEVER throws on an untracked issue — it runs on a
+     * halt path where bookkeeping must not mask the real failure.
+     */
+    updateWindowHalt(issueNumber: number, phase: string, resumeAtMs: number): Promise<void>;
+    /**
+     * Clear a stale window-halt record (#892) — on any phase success (the
+     * window demonstrably reopened; progress also resets the re-entry counter)
+     * or a non-window failure (the halt cause is no longer waitable, so an
+     * unattended re-entry must not fire on it). No-ops (no state write) when
+     * nothing is recorded; never throws on an untracked issue.
+     */
+    clearWindowHalt(issueNumber: number): Promise<void>;
+    /**
+     * Consume one re-entry attempt for a halted issue (#892 AC-3). Returns the
+     * new count, or `null` when the issue has no window-halt record (nothing to
+     * resume). Called by `sequant resume` immediately before re-entry so a
+     * re-entry that halts again (window still closed) is already counted.
+     */
+    incrementWindowHaltReentries(issueNumber: number): Promise<number | null>;
     /**
      * Update worktree information for an issue
      */

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

@@ -364,6 +364,89 @@ export class StateManager {
             console.log(`State: PR #${pr.number} linked to issue #${issueNumber}`);
         }
     }
+    /**
+     * Record or clear an in-progress auto-wait (#860). `wakeAtMs` sets the
+     * pause marker (and which phase is paused); `null` clears it on wake.
+     *
+     * Unlike the sibling updaters this NEVER throws on an untracked issue —
+     * it is called from a liveness hook during a live wait, and a bookkeeping
+     * miss must not interrupt the pause it is describing.
+     */
+    async updateAutoWait(issueNumber, phase, wakeAtMs) {
+        await this.withLock(async () => {
+            const state = await this.getState();
+            const issueState = state.issues[String(issueNumber)];
+            if (!issueState)
+                return;
+            issueState.autoWait =
+                wakeAtMs === null
+                    ? undefined
+                    : { wakeAt: new Date(wakeAtMs).toISOString(), phase };
+            issueState.lastActivity = new Date().toISOString();
+            await this.saveState(state);
+        });
+    }
+    /**
+     * Record a durable waitable-window halt (#892 AC-1). Preserves an existing
+     * re-entry counter so repeated halts on a still-closed window keep counting
+     * toward the re-entry bound instead of resetting it.
+     *
+     * Like `updateAutoWait`, NEVER throws on an untracked issue — it runs on a
+     * halt path where bookkeeping must not mask the real failure.
+     */
+    async updateWindowHalt(issueNumber, phase, resumeAtMs) {
+        await this.withLock(async () => {
+            const state = await this.getState();
+            const issueState = state.issues[String(issueNumber)];
+            if (!issueState)
+                return;
+            issueState.windowHalt = {
+                resumeAt: new Date(resumeAtMs).toISOString(),
+                phase,
+                reentries: issueState.windowHalt?.reentries ?? 0,
+            };
+            issueState.lastActivity = new Date().toISOString();
+            await this.saveState(state);
+        });
+    }
+    /**
+     * Clear a stale window-halt record (#892) — on any phase success (the
+     * window demonstrably reopened; progress also resets the re-entry counter)
+     * or a non-window failure (the halt cause is no longer waitable, so an
+     * unattended re-entry must not fire on it). No-ops (no state write) when
+     * nothing is recorded; never throws on an untracked issue.
+     */
+    async clearWindowHalt(issueNumber) {
+        await this.withLock(async () => {
+            const state = await this.getState();
+            const issueState = state.issues[String(issueNumber)];
+            if (!issueState?.windowHalt)
+                return;
+            issueState.windowHalt = undefined;
+            issueState.lastActivity = new Date().toISOString();
+            await this.saveState(state);
+        });
+    }
+    /**
+     * Consume one re-entry attempt for a halted issue (#892 AC-3). Returns the
+     * new count, or `null` when the issue has no window-halt record (nothing to
+     * resume). Called by `sequant resume` immediately before re-entry so a
+     * re-entry that halts again (window still closed) is already counted.
+     */
+    async incrementWindowHaltReentries(issueNumber) {
+        let newCount = null;
+        await this.withLock(async () => {
+            const state = await this.getState();
+            const issueState = state.issues[String(issueNumber)];
+            if (!issueState?.windowHalt)
+                return;
+            issueState.windowHalt.reentries += 1;
+            newCount = issueState.windowHalt.reentries;
+            issueState.lastActivity = new Date().toISOString();
+            await this.saveState(state);
+        });
+        return newCount;
+    }
     /**
      * Update worktree information for an issue
      */

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

@@ -213,6 +213,14 @@ export declare const RelayStateSchema: z.ZodObject<{
     messageCount: z.ZodNumber;
 }, z.core.$strip>;
 export type RelayState = z.infer<typeof RelayStateSchema>;
+/**
+ * Maximum scheduler re-entries per window-halted issue (#892 AC-3). Mirrors
+ * `AUTO_WAIT_MAX_WAITS` (#804): both bound how often sequant returns to the
+ * same closed rate-limit window before declaring the halt terminal. Lives
+ * here — beside the `windowHalt.reentries` field it bounds — so display
+ * surfaces (`sequant status`) can import it without pulling in the run path.
+ */
+export declare const MAX_RESUME_REENTRIES = 2;
 /**
  * Complete state for a single issue
  */
@@ -342,6 +350,15 @@ export declare const IssueStateSchema: z.ZodObject<{
         token: z.ZodString;
         originCwd: z.ZodString;
     }, z.core.$strip>>;
+    autoWait: z.ZodOptional<z.ZodObject<{
+        wakeAt: z.ZodString;
+        phase: z.ZodString;
+    }, z.core.$strip>>;
+    windowHalt: z.ZodOptional<z.ZodObject<{
+        resumeAt: z.ZodString;
+        phase: z.ZodString;
+        reentries: z.ZodNumber;
+    }, z.core.$strip>>;
     resolvedAt: z.ZodOptional<z.ZodString>;
     lastActivity: z.ZodString;
     createdAt: z.ZodString;
@@ -482,6 +499,15 @@ export declare const WorkflowStateSchema: z.ZodObject<{
             token: z.ZodString;
             originCwd: z.ZodString;
         }, z.core.$strip>>;
+        autoWait: z.ZodOptional<z.ZodObject<{
+            wakeAt: z.ZodString;
+            phase: z.ZodString;
+        }, z.core.$strip>>;
+        windowHalt: z.ZodOptional<z.ZodObject<{
+            resumeAt: z.ZodString;
+            phase: z.ZodString;
+            reentries: z.ZodNumber;
+        }, z.core.$strip>>;
         resolvedAt: z.ZodOptional<z.ZodString>;
         lastActivity: z.ZodString;
         createdAt: z.ZodString;

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

@@ -197,6 +197,14 @@ export const RelayStateSchema = z.object({
     startedAt: z.string().datetime(),
     messageCount: z.number().int().nonnegative(),
 });
+/**
+ * Maximum scheduler re-entries per window-halted issue (#892 AC-3). Mirrors
+ * `AUTO_WAIT_MAX_WAITS` (#804): both bound how often sequant returns to the
+ * same closed rate-limit window before declaring the halt terminal. Lives
+ * here — beside the `windowHalt.reentries` field it bounds — so display
+ * surfaces (`sequant status`) can import it without pulling in the run path.
+ */
+export const MAX_RESUME_REENTRIES = 2;
 /**
  * Complete state for a single issue
  */
@@ -248,6 +256,45 @@ export const IssueStateSchema = z.object({
         originCwd: z.string(),
     })
         .optional(),
+    /**
+     * An in-progress auto-wait (#860): the phase is deliberately paused until a
+     * rate-limit window reopens at `wakeAt`. Written at wait start and cleared
+     * on wake, so `sequant status` can say "waiting until 07:01" instead of
+     * showing an hours-stale in-progress phase indistinguishable from a hang
+     * (#856). The write itself also refreshes `state.json`'s mtime — the
+     * activity proxy several liveness surfaces poll.
+     */
+    autoWait: z
+        .object({
+        /** ISO timestamp of the scheduled wake (resetsAt + buffer). */
+        wakeAt: z.string().datetime(),
+        /** Phase that is paused. */
+        phase: z.string(),
+    })
+        .optional(),
+    /**
+     * A durable halt on an exhausted rate-limit window (#892): the run exited
+     * cleanly (lock released) and can be re-entered by `sequant resume` once
+     * the window reopens at `resumeAt`. Unlike `autoWait` (a live in-process
+     * pause), this record survives reboots — it is the machine-readable
+     * contract between the halt and an unattended scheduler re-entry.
+     * Written at a waitable-window halt, cleared on any phase success or a
+     * non-window failure (the halt cause is then no longer waitable).
+     */
+    windowHalt: z
+        .object({
+        /** ISO timestamp after which re-entry can proceed (resetsAt + buffer). */
+        resumeAt: z.string().datetime(),
+        /** Phase that halted. */
+        phase: z.string(),
+        /**
+         * Re-entry attempts consumed (#892 AC-3). Incremented by `sequant
+         * resume` before each re-entry; a window that never reopens is bounded
+         * by MAX_RESUME_REENTRIES instead of ping-ponging a scheduler.
+         */
+        reentries: z.number().int().min(0),
+    })
+        .optional(),
     /** When the issue transitioned to a terminal status (merged/abandoned/closed) */
     resolvedAt: z.string().datetime().optional(),
     /** Most recent activity timestamp */

package/dist/src/lib/workflow/status-derivation.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared status derivation for the run's live state machines (#766).
+ *
+ * Both the orchestrator's `IssueRuntimeState` machine and the renderer's
+ * `IssueState` machine used to *pin* an issue `failed` on any phase failure and
+ * never de-escalate — so a phase that failed on an early quality-loop iteration
+ * left the card red even after a later iteration recovered and shipped the PR.
+ *
+ * The fix derives the failed verdict from the CURRENT phase slots instead.
+ * `findOrAppendPhase` (orchestrator) and the renderer both key phases by name,
+ * so a retried phase overwrites its slot with the latest attempt — the slot
+ * already holds "the last attempt". The one phase that is NOT overwritten on
+ * recovery is `loop`: it is an auxiliary recovery step that only runs after a
+ * failure, so a stale failed `loop` slot must not pin the issue. Excluding
+ * `loop` never hides a genuine failure — an unrecovered pipeline failure always
+ * leaves a non-loop phase's latest slot failed too (the qa/exec the loop was
+ * trying to fix).
+ */
+/** Auxiliary recovery phase — excluded from the failed verdict (see above). */
+export declare const LOOP_PHASE = "loop";
+/** Minimal phase shape both live state machines satisfy. */
+export interface DerivablePhase {
+    name: string;
+    status: string;
+}
+/**
+ * True iff a non-loop phase's latest slot is `failed`. The single source of
+ * truth for "is this issue failed" across both live state machines (#766 AC-2).
+ */
+export declare function pipelineHasFailed(phases: DerivablePhase[]): boolean;

package/dist/src/lib/workflow/status-derivation.js

@@ -0,0 +1,27 @@
+/**
+ * Shared status derivation for the run's live state machines (#766).
+ *
+ * Both the orchestrator's `IssueRuntimeState` machine and the renderer's
+ * `IssueState` machine used to *pin* an issue `failed` on any phase failure and
+ * never de-escalate — so a phase that failed on an early quality-loop iteration
+ * left the card red even after a later iteration recovered and shipped the PR.
+ *
+ * The fix derives the failed verdict from the CURRENT phase slots instead.
+ * `findOrAppendPhase` (orchestrator) and the renderer both key phases by name,
+ * so a retried phase overwrites its slot with the latest attempt — the slot
+ * already holds "the last attempt". The one phase that is NOT overwritten on
+ * recovery is `loop`: it is an auxiliary recovery step that only runs after a
+ * failure, so a stale failed `loop` slot must not pin the issue. Excluding
+ * `loop` never hides a genuine failure — an unrecovered pipeline failure always
+ * leaves a non-loop phase's latest slot failed too (the qa/exec the loop was
+ * trying to fix).
+ */
+/** Auxiliary recovery phase — excluded from the failed verdict (see above). */
+export const LOOP_PHASE = "loop";
+/**
+ * True iff a non-loop phase's latest slot is `failed`. The single source of
+ * truth for "is this issue failed" across both live state machines (#766 AC-2).
+ */
+export function pipelineHasFailed(phases) {
+    return phases.some((p) => p.name !== LOOP_PHASE && p.status === "failed");
+}