sequant 2.8.0 → 2.10.0

package/dist/src/lib/workflow/types.d.ts

@@ -8,6 +8,8 @@ import type { StateManager } from "./state-manager.js";
 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.
@@ -130,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
@@ -146,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
@@ -204,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
@@ -216,6 +281,40 @@ export interface IssueResult {
         startedAt: string;
         command: string;
     };
+    /**
+     * Set true when the chain-mode checkpoint commit could not be written after
+     * this link passed QA (#760). The link's own work is done, but the recovery
+     * point resume depends on is missing — surfaced prominently so a later resume
+     * failing fast (AC-3) is expected, not surprising.
+     */
+    checkpointFailed?: boolean;
+    /**
+     * Bounded-enum classification of the failure that halted this issue (#761
+     * AC-7), derived from the last non-loop failing phase's `structuredError`
+     * (preferred) or stderr-regex classification. Carried into
+     * `.sequant/metrics.json` — enum only, never a message string (metrics
+     * 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.
@@ -247,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) */
@@ -265,6 +362,13 @@ export interface RunOptions {
      * from building on potentially broken code.
      */
     qaGate?: boolean;
+    /**
+     * Make `--chain` content pre-flight warnings fatal (#762).
+     * By default the pre-flight (missing AC section, dependency-order and
+     * file-overlap-order contradictions, closed issues) only warns. When true,
+     * any warning aborts the run BEFORE the first worktree is provisioned.
+     */
+    strictPreflight?: boolean;
     /**
      * Base branch for worktree creation.
      * Resolution priority: this CLI flag → settings.run.defaultBase → 'main'
@@ -276,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.
@@ -301,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;
     /**
@@ -338,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;
     /**
@@ -352,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
@@ -392,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

@@ -43,6 +43,19 @@ export interface RebaseResult {
     /** Error message if rebase failed */
     error?: string;
 }
+/**
+ * Result of rebasing a worktree onto a local branch (chain successor → predecessor).
+ */
+export interface LocalRebaseResult {
+    /** Whether the rebase was attempted */
+    performed: boolean;
+    /** Whether the rebase succeeded (branch now contains `ontoBranch`'s commits) */
+    success: boolean;
+    /** Whether a merge conflict caused the rebase to be aborted */
+    conflict: boolean;
+    /** Error message if the rebase failed */
+    error?: string;
+}
 /**
  * Result of PR creation
  */
@@ -132,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)
@@ -176,6 +204,17 @@ export declare function createCheckpointCommit(worktreePath: string, issueNumber
  * @internal Exported for testing
  */
 export declare function reinstallIfLockfileChanged(worktreePath: string, packageManager: string | undefined, verbose: boolean, preRebaseRef?: string): boolean;
+/**
+ * Rebase a worktree's branch onto a *local* branch ref (e.g. a chain
+ * predecessor's feature branch), NOT origin/main. Used to chain a successor
+ * onto its predecessor's committed work at execution time (#748), and to
+ * re-chain a pre-existing worktree onto its chain base.
+ *
+ * On conflict, aborts the rebase to restore the original branch state and
+ * returns `{ success: false, conflict: true }` so callers can warn rather than
+ * silently treat a broken link as healthy.
+ */
+export declare function rebaseOntoLocalBranch(worktreePath: string, ontoBranch: string, verbose?: boolean): LocalRebaseResult;
 /**
  * Rebase the worktree branch onto the base branch before PR creation.
  * This ensures the branch is up-to-date and prevents lockfile drift.
@@ -189,11 +228,37 @@ export declare function reinstallIfLockfileChanged(worktreePath: string, package
  * @internal Exported for testing
  */
 export declare function rebaseBeforePR(worktreePath: string, issueNumber: number, packageManager: string | undefined, verbose: boolean, baseBranch?: string): RebaseResult;
+/**
+ * Build the automated PR body for `sequant run`.
+ *
+ * Pure and I/O-free, kept separate from {@link createPR} (which shells out to
+ * `gh`) so the body — including the non-A+ QA note (#749) — is unit-testable
+ * directly.
+ *
+ * @param issueNumber Issue the PR closes
+ * @param opts.stackManifest Appended before the trailer under --stacked (#605)
+ * @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
@@ -204,10 +269,13 @@ export declare function rebaseBeforePR(worktreePath: string, issueNumber: number
  * @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;
-}): PRCreationResult;
+}, qaVerdict?: string, readyGateReport?: string): PRCreationResult;