sequant 2.9.0 → 2.10.0

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/types.d.ts

@@ -9,6 +9,7 @@ import type { ShutdownManager } from "../shutdown.js";
 import type { WorktreeInfo } from "./worktree-manager.js";
 import type { SequantError } from "../errors.js";
 import type { ErrorCategory } from "./error-classifier.js";
+import type { ReadyResult } from "./ready-gate.js";
 export type { WorkflowEventEmitter, WorkflowEvents, WorkflowEventListener, IssueEventStatus, BaseEventPayload, RunEventPayload, PhaseStartedPayload, PhaseCompletedPayload, PhaseFailedPayload, IssueStatusChangedPayload, QaVerdictPayload, ProgressPayload, } from "./event-emitter.js";
 /**
  * Canonical Zod schema for all workflow phases.
@@ -131,6 +132,14 @@ export interface ExecutionConfig {
      * poll budget is preserved.
      */
     onActivity?: (text: string) => void;
+    /**
+     * Runtime callback invoked while an auto-wait (#804) is in progress, once
+     * per tick plus once when it ends. Used to keep the renderer and the `-q`
+     * heartbeat showing the wait and its wake time, so a multi-hour pause reads
+     * as deliberate rather than as the silent stall of #574. Not serialized —
+     * set per-call by the orchestrator, like {@link onActivity}.
+     */
+    onAutoWait?: (notice: AutoWaitNotice) => void;
     /**
      * Enable interactive relay (#383). When true, phase-executor sets
      * `SEQUANT_RELAY=true` in the agent environment so the PostToolUse hook
@@ -147,6 +156,53 @@ export interface ExecutionConfig {
      * QA pass does NOT skip the checks that catch the #318/#529/#570 class.
      */
     fullQa?: boolean;
+    /**
+     * Run the post-QA ready gate after the standard phases succeed (#817).
+     *
+     * When true, `runIssueWithLogging` invokes the existing `sequant ready`
+     * engine (`runReadyGate`) at the PR seam — before rebase/PR so the gate's
+     * auto-fix commits land in the PR — driving the issue to the configured
+     * `settings.ready.policy` threshold. It NEVER merges: the run terminates with
+     * the issue in `waiting_for_human_merge` (ready) or `blocked` (guard halt).
+     * Default off; when unset the run path is byte-identical to pre-#817.
+     */
+    readyGate?: boolean;
+    /**
+     * Total wait budget, in minutes, for auto-waiting out an exhausted
+     * rate-limit window (#804). `0` (the default) disables auto-wait entirely,
+     * preserving the #761/#799 halt behavior byte-for-byte.
+     *
+     * When a phase fails with a window-exhausted `RateLimitError` whose reset
+     * lies within the remaining budget, the executor sleeps until the reset and
+     * retries the phase instead of returning the failure. Named for the
+     * *behavior* (waiting), not the mechanism, so it survives a future move from
+     * in-process sleep to out-of-process rescheduling.
+     *
+     * This is a TOTAL budget across the issue, not a per-occurrence allowance —
+     * see {@link AutoWaitLedger}.
+     */
+    autoWaitMinutes?: number;
+}
+/**
+ * A single liveness notice emitted during an auto-wait (#804 AC-7).
+ */
+export interface AutoWaitNotice {
+    /** Issue the wait belongs to. */
+    issueNumber: number;
+    /** Phase whose retry is being waited for. */
+    phase: string;
+    /** Epoch ms at which the wait ends (reset + buffer). */
+    wakeAtMs: number;
+    /** Ms remaining at the time of this notice. `0` on the final notice. */
+    remainingMs: number;
+    /**
+     * Display string, already formatted. Built from `formatRateLimitMessage`
+     * plus the wake time — never by re-appending `resetsAt` to an
+     * already-formatted driver message (the #799 doubled-string trap).
+     */
+    message: string;
+    /** True on the terminal notice, once the wait has ended or been aborted. */
+    done: boolean;
 }
 /**
  * Default execution configuration
@@ -205,6 +261,14 @@ export interface IssueResult {
     prNumber?: number;
     /** PR URL if created after successful QA */
     prUrl?: string;
+    /**
+     * Set when PR creation was attempted after passing QA but failed (#879).
+     * A failed `createPR` used to be a non-fatal yellow warning while the issue
+     * still reported success — so a run could "pass" while producing no PR. When
+     * present, `success` is false and the run summary counts the issue as failed
+     * with this string as the reason.
+     */
+    prCreationError?: string;
     /**
      * Set when the issue was skipped because another sequant session holds
      * the per-issue lock (#625). Surfaced in the summary as
@@ -232,6 +296,25 @@ export interface IssueResult {
      * privacy contract). Absent on success.
      */
     failureCategory?: ErrorCategory;
+    /**
+     * Outcome of the post-QA ready gate (#817), present only when the run was
+     * invoked with `--ready-gate` and the gate actually ran (i.e. the standard
+     * phases succeeded). Carries the terminal reason, the persisted issue status
+     * (`waiting_for_human_merge` / `blocked` — never merged), and the rendered
+     * report the summary and PR body surface. Absent on runs without the flag.
+     */
+    readyGate?: ReadyResult;
+    /**
+     * Why the ready gate did NOT run, when `--ready-gate` was requested but the
+     * gate threw (#817). Mutually exclusive with {@link IssueResult.readyGate}.
+     *
+     * A gate crash is deliberately non-fatal — the phase work is already
+     * committed and the PR still opens — but it must not be silent. Without this
+     * field a run whose gate died is byte-identical in the summary to one that
+     * never asked for a gate, so the user believes a second look happened when it
+     * did not. The summary renders this as an explicit "gate did not run" line.
+     */
+    readyGateError?: string;
 }
 /**
  * CLI options for the run command, merged with settings and env config.
@@ -263,8 +346,6 @@ export interface RunOptions {
     autoDetectPhases?: boolean;
     /** Enable automatic worktree creation for issue isolation */
     worktreeIsolation?: boolean;
-    /** Reuse existing worktrees instead of creating new ones */
-    reuseWorktrees?: boolean;
     /** Suppress version warnings and non-essential output */
     quiet?: boolean;
     /** Chain issues: each branches from previous (requires --sequential) */
@@ -299,6 +380,13 @@ export interface RunOptions {
      * Resolution priority: this CLI flag → settings.run.mcp → default (true)
      */
     noMcp?: boolean;
+    /**
+     * Total minutes willing to wait for an exhausted rate-limit window to reopen
+     * before halting (#804). `0` (default) keeps today's immediate halt.
+     * Resolution priority: this CLI flag → SEQUANT_AUTO_WAIT_MINUTES →
+     * settings.run.autoWaitMinutes → default (0).
+     */
+    autoWaitMinutes?: number;
     /**
      * Resume from last completed phase.
      * Reads phase markers from GitHub issue comments and skips completed phases.
@@ -324,7 +412,9 @@ export interface RunOptions {
     noPr?: boolean;
     /**
      * Force re-execution of issues even if they have completed status.
-     * Bypasses the pre-flight state guard that skips ready_for_merge/merged issues.
+     * Bypasses the pre-flight state guard that skips completed issues — see
+     * `isCompletedIssueStatus` (completed-status.ts) for exactly which statuses
+     * that covers, and why `blocked` is not one of them.
      */
     force?: boolean;
     /**
@@ -361,6 +451,17 @@ export interface RunOptions {
      * #705: now a hidden no-op alias — the boxed Ink TUI is the default, so
      * `--experimental-tui` only parses for backward compatibility and no longer
      * gates rendering. Kept so existing scripts/muscle-memory don't break.
+     *
+     * INTENTIONALLY INERT — do not delete (#810). A dead-surface sweep of
+     * `RunOptions` will correctly observe that nothing branches on this field.
+     * That is the design, not a defect: the flag's whole job is to parse and do
+     * nothing, so scripts written against #705 keep working. Its inertness is
+     * asserted, not incidental — `run-flags.test.ts` ("--experimental-tui is a
+     * no-op"), `cli.integration.test.ts` (hidden from `--help`, still parses),
+     * and `run-tui.integration.test.ts` all pin it. Contrast `reuseWorktrees`,
+     * removed in #810: that field had no flag, no consumer, and no test, so it
+     * promised behavior nothing delivered. The distinction is a flag deliberately
+     * kept parseable versus a type field nobody could ever reach.
      */
     experimentalTui?: boolean;
     /**
@@ -375,6 +476,16 @@ export interface RunOptions {
      * Resolution priority: this CLI flag → settings.run.relay → default (true).
      */
     relay?: boolean;
+    /**
+     * Run the post-QA ready gate after the standard phases succeed (#817). Set via
+     * `--ready-gate`. When true, the run drives the issue to the configured
+     * `settings.ready.policy` threshold through the existing `sequant ready`
+     * engine before creating the PR, then STOPS at the human merge gate — it never
+     * merges. Off by default; opt-in only, so an unset flag leaves the run path
+     * (including the #749 break-to-PR behavior) unchanged. Reuses `ready`'s policy
+     * and bounds wholesale — no new settings accompany this flag.
+     */
+    readyGate?: boolean;
 }
 /**
  * CLI arguments for run command
@@ -415,12 +526,23 @@ export interface BatchResult {
  * `"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.
+ *
+ * `"waiting"` (#804): an auto-wait for a rate-limit window is in progress.
+ * `extra.text` is the display message and `extra.wakeAtMs` the wake time;
+ * a `"waiting"` event WITHOUT `wakeAtMs` is the terminal notice that clears
+ * the waiting state. Unlike `"activity"`, this must reach both display paths
+ * — a multi-hour pause with no signal is the #574 complaint at 60x scale.
  */
-export type ProgressCallback = (issue: number, phase: string, event: "start" | "complete" | "failed" | "activity", extra?: {
+export type ProgressCallback = (issue: number, phase: string, event: "start" | "complete" | "failed" | "activity" | "waiting", extra?: {
     durationSeconds?: number;
     error?: string;
     iteration?: number;
     text?: string;
+    /**
+     * `"waiting"` (#804): epoch ms at which an auto-wait ends. Absent on the
+     * terminal notice, which clears the waiting state.
+     */
+    wakeAtMs?: number;
 }) => void;
 /**
  * #672 AC-2: fired once per issue after the executor has resolved the final

package/dist/src/lib/workflow/types.js

@@ -45,4 +45,5 @@ export const DEFAULT_CONFIG = {
     dryRun: false,
     mcp: true,
     retry: true,
+    autoWaitMinutes: 0,
 };

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

@@ -145,6 +145,21 @@ export declare function filterResumedPhases(issueNumber: number, phases: Phase[]
     phases: Phase[];
     skipped: Phase[];
 };
+/**
+ * Run the frozen dependency install for a freshly provisioned worktree and
+ * surface (rather than swallow) a failed install.
+ *
+ * Mirrors the status check in `reinstallIfLockfileChanged` (#846): a plain
+ * `npm install` self-heals a stale/absent lockfile, but the frozen `npm ci`
+ * hard-fails (exit 1, no node_modules). Without this check a failing install
+ * left a silently dependency-less worktree whose breakage only surfaced later
+ * as a confusing phase error. The warning names the resolved command so the
+ * user can rerun it by hand.
+ *
+ * @returns true if the install succeeded, false if it failed (warn-and-continue)
+ * @internal Exported for testing
+ */
+export declare function installWorktreeDeps(worktreePath: string, packageManager: string | undefined, verbose: boolean): boolean;
 /**
  * Create or reuse a worktree for an issue
  * @param baseBranch - Optional branch to use as base instead of origin/main (for chain mode)
@@ -225,17 +240,25 @@ export declare function rebaseBeforePR(worktreePath: string, issueNumber: number
  * @param opts.qaVerdict QA verdict for the run; a non-A+ stopping state
  *   (anything other than `READY_FOR_MERGE`) surfaces a note so a human reviewer
  *   sees why the run broke to PR without reaching A+ (#749).
+ * @param opts.readyGateReport Rendered `sequant ready` gap report (#817). Set
+ *   only when the run used `--ready-gate`; surfaces the gate outcome (threshold
+ *   reached vs guard halt) in the PR body the same way `sequant ready` does.
  * @internal Exported for testing
  */
 export declare function buildAutomatedPRBody(issueNumber: number, opts?: {
     stackManifest?: string;
     qaVerdict?: string;
+    readyGateReport?: string;
 }): string;
 /**
  * Push branch and create a PR after successful QA.
  *
  * Handles both fresh PR creation and detection of existing PRs.
- * Failures are warnings — they don't fail the run.
+ *
+ * Returns `{ success: false, error }` on failure. As of #879 the caller
+ * (`runIssueWithLogging`) treats an attempted-but-failed PR as a run failure:
+ * a passing run that produced no PR is not a success. This function itself
+ * still only reports — it never throws — so relay teardown runs regardless.
  *
  * @param worktreePath Path to the worktree
  * @param issueNumber Issue number
@@ -246,10 +269,13 @@ export declare function buildAutomatedPRBody(issueNumber: number, opts?: {
  * @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)
+ * @param qaVerdict QA verdict surfaced in the PR body when non-A+ (#749).
+ * @param readyGateReport Rendered `sequant ready` gap report, set only when the
+ *   run used `--ready-gate` (#817).
  * @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[], stackOptions?: {
     prBase?: string;
     stackManifest?: string;
-}, qaVerdict?: string): PRCreationResult;
+}, qaVerdict?: string, readyGateReport?: string): PRCreationResult;