sequant 2.9.0 → 2.10.0

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

@@ -164,6 +164,13 @@ export interface RunResult {
     mergedOptions: RunOptions;
     /** Log writer (for reflection access) */
     logWriter: LogWriter | null;
+    /**
+     * Run wall-clock duration in seconds, computed once by the orchestrator from
+     * the run's start and end (#867). The post-run summary reads THIS value rather
+     * than re-summing per-issue durations — under `--parallel` that sum
+     * double-counts overlapping issues and over-reports by ~the concurrency factor.
+     */
+    wallClockDurationSeconds: number;
 }
 /**
  * CLI-free workflow execution engine.
@@ -188,6 +195,18 @@ export declare class RunOrchestrator {
      * listening (#504, AC-3).
      */
     getEmitter(): WorkflowEventEmitter;
+    /**
+     * The wrapped progress sink handed to the batch executor — every phase
+     * lifecycle event enters the orchestrator through here.
+     *
+     * @internal Exported for testing only. `applyProgressEvent` is private and
+     * depends on `issueStates`/`phaseStartTimes`/`emitter`, so there is no way
+     * to exercise its branches short of a full `run()`. Without this seam the
+     * #804 `waiting` branch would be untestable — and an untested `waiting`
+     * branch is not cosmetic: falling through to the complete/failed handler
+     * marks a merely-paused phase `failed` and emits `phase_failed`.
+     */
+    getProgressCallback(): ProgressCallback;
     /**
      * Point-in-time view of the entire run.
      *

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

@@ -27,6 +27,8 @@ function formatSignalLine(issue, pid, result) {
             return `  Refused to signal PID ${pid} for #${issue} (matches this process or its parent)`;
         case "pid-dead":
             return `  Could not signal PID ${pid} for #${issue} (already exited)`;
+        case "stale-pid-untrusted":
+            return `  Refused to signal PID ${pid} for #${issue} (lock is past the age ceiling; that PID has likely been recycled)`;
         case "kill-failed":
             return `  Could not signal PID ${pid} for #${issue} (kill syscall failed)`;
         case "orchestrator":
@@ -69,11 +71,13 @@ function isWorktreeDirty(worktreePath) {
     }
     return result.stdout.trim().length > 0;
 }
-import { getIssueInfo, sortByDependencies, parseBatches, runIssueWithLogging, emitRunIdLine, } from "./batch-executor.js";
+import { getIssueInfo, sortByDependencies, parseBatches, runIssueWithLogging, recordIssueCompletion, emitRunIdLine, } from "./batch-executor.js";
 import { reconcileStateAtStartup } from "./state-utils.js";
 import { runChainPreflight } from "./chain-preflight.js";
+import { runSkillsPreflight } from "./skills-preflight.js";
 import { getCommitHash } from "./git-diff-utils.js";
 import { planChainResumeFromState, } from "./chain-resume.js";
+import { isCompletedIssueStatus } from "./completed-status.js";
 import { MetricsWriter } from "./metrics-writer.js";
 import { WorkflowEventEmitter } from "./event-emitter.js";
 import { determineOutcome } from "./metrics-schema.js";
@@ -131,6 +135,20 @@ export class RunOrchestrator {
     getEmitter() {
         return this.emitter;
     }
+    /**
+     * The wrapped progress sink handed to the batch executor — every phase
+     * lifecycle event enters the orchestrator through here.
+     *
+     * @internal Exported for testing only. `applyProgressEvent` is private and
+     * depends on `issueStates`/`phaseStartTimes`/`emitter`, so there is no way
+     * to exercise its branches short of a full `run()`. Without this seam the
+     * #804 `waiting` branch would be untestable — and an untested `waiting`
+     * branch is not cosmetic: falling through to the complete/failed handler
+     * marks a merely-paused phase `failed` and emits `phase_failed`.
+     */
+    getProgressCallback() {
+        return this.cfg.onProgress;
+    }
     /**
      * Point-in-time view of the entire run.
      *
@@ -197,6 +215,16 @@ export class RunOrchestrator {
             const wasStatus = state.status;
             if (!state.startedAt)
                 state.startedAt = new Date();
+            // #866: a phase starting means the issue is live again, so any
+            // `completedAt` from an earlier terminal verdict is stale and must not
+            // outlive it. The #766 quality-loop recovery path reaches here holding
+            // one: a non-loop failure pins `failed` and stamps `completedAt` below,
+            // then iteration 2 re-runs the phase through this branch. Leaving it set
+            // published a completion time for a running issue — which froze the TUI's
+            // header clock for the whole recovery window. `startedAt` is deliberately
+            // NOT reset: the header measures the issue's total wall clock, spanning
+            // every iteration.
+            state.completedAt = undefined;
             state.status = "running";
             const now = new Date();
             this.phaseStartTimes.set(`${issue}:${phase}`, now.getTime());
@@ -224,6 +252,25 @@ export class RunOrchestrator {
             }
             return;
         }
+        // #804 AC-7: an auto-wait is a *paused running* phase, not a terminal one.
+        // This branch must precede the complete/failed fall-through below, which
+        // would otherwise close out the phase the moment a wait began. Surfaces the
+        // wait through the same `nowLine` the TUI already renders.
+        if (event === "waiting") {
+            if (!state.currentPhase || state.currentPhase.name !== phase)
+                return;
+            const line = extra?.text;
+            if (!line)
+                return;
+            state.currentPhase.nowLine = line;
+            state.currentPhase.lastActivityAt = new Date();
+            void this.emitter.emit("progress", {
+                issueNumber: issue,
+                phase,
+                text: line,
+            });
+            return;
+        }
         if (event === "activity") {
             // Ignore activity for stale phases (race between completion and a
             // final flushed output chunk).
@@ -369,6 +416,15 @@ export class RunOrchestrator {
      */
     static async run(init, issueArgs, batches) {
         const { manifest, onProgress, phasePauseHandle, settings } = init;
+        // #867: capture the run's start before any service/log setup, so wall clock
+        // is independent of whether the log writer exists (AC-3: correct under
+        // --no-log and when log init fails). This single origin is the source of
+        // truth for both the printed summary and the run log (AC-2).
+        const runStartedAt = Date.now();
+        // Every `return` below — the success path and all six early exits — closes
+        // the bracket the same way, so the subtraction lives in one place rather
+        // than being restated per exit and left to drift.
+        const wallClock = () => (Date.now() - runStartedAt) / 1000;
         // ── Config resolution ──────────────────────────────────────────────
         const resolved = RunOrchestrator.resolveConfig(init, issueArgs, batches);
         const { mergedOptions, config, baseBranch } = resolved;
@@ -384,6 +440,7 @@ export class RunOrchestrator {
                 config,
                 mergedOptions,
                 logWriter: null,
+                wallClockDurationSeconds: wallClock(),
             };
         }
         // ── Services setup ─────────────────────────────────────────────────
@@ -405,6 +462,10 @@ export class RunOrchestrator {
                     logPath: mergedOptions.logPath ?? settings.run.logPath,
                     verbose: config.verbose,
                     startCommit: getCommitHash(process.cwd()),
+                    // #867: share the orchestrator's run origin so the log's stored
+                    // wall clock (finalizeRunLog: (end-start)/1000) is derived from the
+                    // same start as the summary — AC-2/AC-7 (one producer, two consumers).
+                    startTime: new Date(runStartedAt),
                 });
                 await logWriter.initialize(runConfig);
                 const runId = logWriter.getRunId();
@@ -424,8 +485,12 @@ export class RunOrchestrator {
         const shutdown = new ShutdownManager();
         if (logWriter) {
             const writer = logWriter;
-            shutdown.registerCleanup("Finalize run logs", async () => {
-                await writer.finalize();
+            // #856: forward the abort cause into the log. This cleanup runs on the
+            // SIGINT/SIGTERM path, where no phase result will ever arrive for the
+            // in-flight issue — without the context, `finalize()` writes that issue
+            // out as if the run had simply ended.
+            shutdown.registerCleanup("Finalize run logs", async (abort) => {
+                await writer.finalize(abort ? { aborted: abort } : undefined);
             });
         }
         // ── Pre-flight state guard ─────────────────────────────────────────
@@ -478,6 +543,7 @@ export class RunOrchestrator {
                         config,
                         mergedOptions,
                         logWriter: null,
+                        wallClockDurationSeconds: wallClock(),
                     };
                 }
                 if (plan.allComplete) {
@@ -492,6 +558,7 @@ export class RunOrchestrator {
                         config,
                         mergedOptions,
                         logWriter: null,
+                        wallClockDurationSeconds: wallClock(),
                     };
                 }
                 if (plan.skipped.length > 0) {
@@ -513,9 +580,7 @@ export class RunOrchestrator {
                 for (const issueNumber of issueNumbers) {
                     try {
                         const issueState = await stateManager.getIssueState(issueNumber);
-                        if (issueState &&
-                            (issueState.status === "ready_for_merge" ||
-                                issueState.status === "merged")) {
+                        if (issueState && isCompletedIssueStatus(issueState.status)) {
                             console.log(chalk.yellow(`  !  #${issueNumber}: already ${issueState.status} — skipping (use --force to re-run)`));
                         }
                         else {
@@ -541,6 +606,7 @@ export class RunOrchestrator {
                             config,
                             mergedOptions,
                             logWriter: null,
+                            wallClockDurationSeconds: wallClock(),
                         };
                     }
                 }
@@ -600,6 +666,7 @@ export class RunOrchestrator {
                     config,
                     mergedOptions,
                     logWriter: null,
+                    wallClockDurationSeconds: wallClock(),
                 };
             }
         }
@@ -630,6 +697,7 @@ export class RunOrchestrator {
                         config,
                         mergedOptions,
                         logWriter: null,
+                        wallClockDurationSeconds: wallClock(),
                     };
                 }
             }
@@ -639,6 +707,49 @@ export class RunOrchestrator {
         for (const issueNumber of issueNumbers) {
             issueInfoMap.set(issueNumber, await getIssueInfo(issueNumber));
         }
+        // ── Skills pre-flight (#813) ───────────────────────────────────────
+        // Fail fast when the driver resolves phases via `.claude/skills/` and a
+        // required skill is missing — BEFORE any worktree is provisioned or
+        // per-issue state entry written. Without this, the phase agent hunts for
+        // a slash command that can never resolve and the run surfaces as a bogus
+        // "spec retry" failure. Skipped for non-skill drivers (aider) and for
+        // --dry-run (no agent executes).
+        if (!config.dryRun) {
+            const preflight = await runSkillsPreflight({
+                agent: config.agent,
+                aiderSettings: config.aiderSettings,
+                phases: config.phases,
+                autoDetectPhases: resolved.autoDetectPhases,
+                qualityLoop: config.qualityLoop,
+                testgen: mergedOptions.testgen,
+                securityReview: mergedOptions.securityReview,
+                issueNumbers,
+                issueInfoMap,
+            });
+            if (!preflight.ok) {
+                bracketedConsoleLog(phasePauseHandle, chalk.red(`\n  ✖ Skills pre-flight failed: ${preflight.cause}`));
+                bracketedConsoleLog(phasePauseHandle, chalk.red(`    ${preflight.remedy}`));
+                shutdown.dispose();
+                return {
+                    results: issueNumbers.map((issueNumber) => ({
+                        issueNumber,
+                        success: false,
+                        phaseResults: [],
+                        durationSeconds: 0,
+                        loopTriggered: false,
+                        abortReason: `skills pre-flight failed: ${preflight.cause}`,
+                    })),
+                    logPath: null,
+                    exitCode: 1,
+                    worktreeMap: new Map(),
+                    issueInfoMap,
+                    config,
+                    mergedOptions,
+                    logWriter: null,
+                    wallClockDurationSeconds: wallClock(),
+                };
+            }
+        }
         const useWorktreeIsolation = mergedOptions.worktreeIsolation !== false && issueNumbers.length > 0;
         let worktreeMap = new Map();
         if (useWorktreeIsolation && !config.dryRun) {
@@ -710,10 +821,15 @@ export class RunOrchestrator {
                     endCommit: getCommitHash(process.cwd()),
                 });
             }
+            // #867: the run's wall clock, computed once from the single origin. Both
+            // the metrics record and the RunResult below derive from this value — no
+            // consumer re-sums per-issue durations (which double-counts under
+            // --parallel). Same notion the log stores via finalizeRunLog above.
+            const wallClockDurationSeconds = wallClock();
             // ── Record metrics ─────────────────────────────────────────────
             if (!config.dryRun && results.length > 0) {
                 try {
-                    await RunOrchestrator.recordMetrics(config, mergedOptions, results, worktreeMap, issueNumbers);
+                    await RunOrchestrator.recordMetrics(config, mergedOptions, results, worktreeMap, issueNumbers, wallClockDurationSeconds);
                 }
                 catch (metricsError) {
                     logNonFatalWarning("  !  Metrics recording failed, continuing...", metricsError, config.verbose);
@@ -729,6 +845,7 @@ export class RunOrchestrator {
                 config,
                 mergedOptions,
                 logWriter,
+                wallClockDurationSeconds,
             };
         }
         finally {
@@ -925,14 +1042,13 @@ export class RunOrchestrator {
                     : undefined,
             });
             results.push(result);
-            if (!result.success) {
-                if (options.qaGate && options.chain) {
-                    const qaFailed = result.phaseResults.some((p) => p.phase === "qa" && !p.success);
-                    if (qaFailed)
-                        break;
-                }
+            // A chain halts on ANY failed link, QA or otherwise: every successor
+            // rebases onto its predecessor's committed work, so continuing past a
+            // failure would build on a broken or absent base. #795 removed a
+            // `--qa-gate` branch here that re-tested for a QA failure before this
+            // same unconditional break — it could never change the outcome.
+            if (!result.success)
                 break;
-            }
         }
         return results;
     }
@@ -1017,11 +1133,12 @@ export class RunOrchestrator {
                     });
                 }
             }
-            if (logWriter && result.prNumber && result.prUrl) {
-                logWriter.setPRInfo(result.prNumber, result.prUrl, parallelIssueNumber);
-            }
+            // Record PR info, flip status on a PR-creation failure (#879), and
+            // finalize — via the shared helper so this live path stays in lockstep
+            // with executeBatch. Before #879 this block omitted the failure flip, so
+            // a real `sequant run` left the run-log status at `success` on PR failure.
             if (logWriter) {
-                logWriter.completeIssue(parallelIssueNumber);
+                recordIssueCompletion(logWriter, result, parallelIssueNumber);
             }
             return result;
         }
@@ -1034,9 +1151,13 @@ export class RunOrchestrator {
             });
         }
     }
-    static async recordMetrics(config, mergedOptions, results, worktreeMap, issueNumbers) {
+    static async recordMetrics(config, mergedOptions, results, worktreeMap, issueNumbers, wallClockDurationSeconds) {
         const metricsWriter = new MetricsWriter({ verbose: config.verbose });
-        const totalDuration = results.reduce((sum, r) => sum + (r.durationSeconds ?? 0), 0);
+        // #867: run wall clock, not the sum of per-issue durations — under
+        // --parallel that sum double-counts overlapping issues (same defect the
+        // SUMMARY header had). The orchestrator owns the run's start/end and passes
+        // the single authoritative value in.
+        const totalDuration = wallClockDurationSeconds;
         const allPhases = new Set();
         for (const result of results) {
             for (const pr of result.phaseResults) {

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
      */