sequant 2.8.0 → 2.10.0

package/dist/src/lib/merge-check/types.d.ts

@@ -171,6 +171,15 @@ export interface MergeCommandOptions {
     json?: boolean;
     /** Enable verbose output */
     verbose?: boolean;
+    /**
+     * Watch mode (#818): poll each resolved PR's CI rollup until every check is
+     * terminal, then run the normal merge-check report. Never merges.
+     */
+    watch?: boolean;
+    /** Watch poll interval in seconds (default 30). Only used with `watch`. */
+    interval?: number;
+    /** Watch give-up timeout in seconds (default 1800). Only used with `watch`. */
+    timeout?: number;
 }
 /**
  * Configuration for paired directories (template mirroring)

package/dist/src/lib/merge-check/watch.d.ts

@@ -0,0 +1,121 @@
+/**
+ * `sequant merge --watch` — poll a PR's CI rollup until it is terminal, then let
+ * the existing merge-check report run. This module owns only the *wait*: it
+ * never merges and never runs the checks itself (merge.ts orchestrates that).
+ *
+ * See #818. Design contract:
+ *  - foreground `await sleep` loop — no daemon, no child process, no OS notifier;
+ *  - all `gh` access through `GitHubProvider` (#443), using `statusCheckRollup`
+ *    (the `--json checks` field is known-broken);
+ *  - three dispatch-block signatures short-circuit to BLOCKED instead of polling
+ *    until timeout (AC-3): merge conflict, zero-checks-because-conflicting, and a
+ *    uniformly-failing board whose annotations show the runner never started.
+ */
+import type { RollupEntry, MergeableState } from "../workflow/platforms/github.js";
+import { type AnnotatedCheck } from "../qa/infra-blocked-ci.js";
+/**
+ * The subset of `GitHubProvider` the watch loop depends on. Declared as an
+ * interface so tests inject a fake without spawning real `gh` calls.
+ */
+export interface WatchGitHub {
+    getMergeableStateSync(prNumber: number): MergeableState;
+    getStatusCheckRollupSync(prNumber: number): RollupEntry[];
+    getPRHeadShaSync(prNumber: number): string | null;
+    getCheckRunAnnotationsSync(headSha: string): AnnotatedCheck[];
+}
+/**
+ * Map one rollup entry to a `gh`-style bucket (`pass | fail | pending |
+ * skipping`), normalising the two entry shapes (CheckRun vs StatusContext) so
+ * `allChecksFailing` — which the billing-lockout detector gates on — can be
+ * reused verbatim.
+ */
+export declare function rollupEntryBucket(entry: RollupEntry): string;
+/** Is a rollup entry in a terminal (no-longer-changing) state? */
+export declare function isRollupEntryTerminal(entry: RollupEntry): boolean;
+/** Outcome of classifying a single poll tick. */
+export type TickOutcome = {
+    kind: "terminal";
+} | {
+    kind: "blocked";
+    reason: string;
+    checkName?: string;
+} | {
+    kind: "pending";
+    pending: number;
+    total: number;
+};
+/**
+ * Classify a single poll of `(mergeable, rollup)`.
+ *
+ * Pure except for the lazily-invoked `fetchAnnotations`, which is called ONLY
+ * when the whole board is terminal-and-failing — so healthy or partial boards
+ * never pay for the extra check-run annotation API calls.
+ */
+export declare function classifyTick(mergeable: MergeableState, rollup: RollupEntry[], fetchAnnotations: () => AnnotatedCheck[]): TickOutcome;
+/** Terminal status of a watch. */
+export type WatchStatus = "terminal" | "blocked" | "timeout";
+/** Result of watching a single PR's checks to completion. */
+export interface WatchResult {
+    status: WatchStatus;
+    /** Human-readable cause for `blocked`/`timeout`; undefined when `terminal`. */
+    reason?: string;
+    /** Check name whose annotation matched, for a billing-lockout BLOCKED. */
+    checkName?: string;
+    /** Number of polls performed. */
+    polls: number;
+    /** Elapsed wall-clock time in milliseconds. */
+    elapsedMs: number;
+}
+/** Options for {@link waitForChecks}. */
+export interface WatchOptions {
+    /** Delay between polls, in milliseconds. */
+    intervalMs: number;
+    /** Give-up deadline measured from the first poll, in milliseconds. */
+    timeoutMs: number;
+    /** Optional per-poll progress callback (terminal output). */
+    onPoll?: (message: string) => void;
+}
+/** Default watch poll interval (seconds) when `--interval` is not given. */
+export declare const DEFAULT_WATCH_INTERVAL_S = 30;
+/** Default watch timeout (seconds) when `--timeout` is not given: 30 minutes. */
+export declare const DEFAULT_WATCH_TIMEOUT_S = 1800;
+/**
+ * Smallest poll interval we will ever use, in milliseconds.
+ *
+ * A zero/sub-second interval turns the gate into a tight `gh`-spawning loop that
+ * can trip GitHub rate limiting, so the floor is enforced even against an
+ * explicit request.
+ */
+export declare const MIN_WATCH_INTERVAL_MS = 1000;
+/**
+ * Convert user-supplied `--interval`/`--timeout` *seconds* into validated
+ * milliseconds, falling back to the defaults for anything unusable.
+ *
+ * Why this exists: `??` only defends against `null`/`undefined`, and
+ * `parseInt("abc", 10)` yields `NaN`, which is neither. A `NaN` timeout makes
+ * `start + timeoutMs` `NaN`, so `now >= deadline` is permanently false and the
+ * watch loop never gives up; a `NaN`/`0` interval makes `setTimeout` fire
+ * immediately, so it never sleeps either. The two combine into an unbounded,
+ * zero-delay poll loop. This mirrors the numeric-input guards used elsewhere in
+ * the codebase (`batch-executor.ts` `maxIter`/`autoWait`, `merge.ts` issue-number
+ * parsing) rather than trusting the raw flag value.
+ *
+ * The CLI rejects malformed values outright (see `bin/cli.ts`); this is the
+ * defence for programmatic callers that build `MergeCommandOptions` directly.
+ */
+export declare function resolveWatchTiming(options: {
+    interval?: number;
+    timeout?: number;
+}): {
+    intervalMs: number;
+    timeoutMs: number;
+};
+/**
+ * Poll a PR's rollup until it is terminal, blocked, or timed out.
+ *
+ * `sleepFn`/`nowFn` are injectable so tests run instantly and deterministically
+ * without real timers. The loop always classifies a *fresh* poll before it can
+ * declare a timeout, so a check that turns terminal on the final interval is
+ * never swallowed by the deadline.
+ */
+export declare function waitForChecks(prNumber: number, options: WatchOptions, gh: WatchGitHub, sleepFn?: (ms: number) => Promise<void>, nowFn?: () => number): Promise<WatchResult>;

package/dist/src/lib/merge-check/watch.js

@@ -0,0 +1,215 @@
+/**
+ * `sequant merge --watch` — poll a PR's CI rollup until it is terminal, then let
+ * the existing merge-check report run. This module owns only the *wait*: it
+ * never merges and never runs the checks itself (merge.ts orchestrates that).
+ *
+ * See #818. Design contract:
+ *  - foreground `await sleep` loop — no daemon, no child process, no OS notifier;
+ *  - all `gh` access through `GitHubProvider` (#443), using `statusCheckRollup`
+ *    (the `--json checks` field is known-broken);
+ *  - three dispatch-block signatures short-circuit to BLOCKED instead of polling
+ *    until timeout (AC-3): merge conflict, zero-checks-because-conflicting, and a
+ *    uniformly-failing board whose annotations show the runner never started.
+ */
+import { allChecksFailing, detectInfraBlockedCi, } from "../qa/infra-blocked-ci.js";
+/**
+ * Map one rollup entry to a `gh`-style bucket (`pass | fail | pending |
+ * skipping`), normalising the two entry shapes (CheckRun vs StatusContext) so
+ * `allChecksFailing` — which the billing-lockout detector gates on — can be
+ * reused verbatim.
+ */
+export function rollupEntryBucket(entry) {
+    // CheckRun: progress in `status`, outcome in `conclusion`.
+    if (entry.status !== undefined || entry.conclusion !== undefined) {
+        const status = (entry.status ?? "").toUpperCase();
+        if (status !== "COMPLETED")
+            return "pending"; // QUEUED | IN_PROGRESS | ...
+        const conclusion = (entry.conclusion ?? "").toUpperCase();
+        switch (conclusion) {
+            case "SUCCESS":
+                return "pass";
+            case "NEUTRAL":
+            case "SKIPPED":
+                return "skipping";
+            default:
+                // FAILURE | TIMED_OUT | CANCELLED | ACTION_REQUIRED | STARTUP_FAILURE | STALE
+                return "fail";
+        }
+    }
+    // StatusContext: combined state.
+    const state = (entry.state ?? "").toUpperCase();
+    switch (state) {
+        case "SUCCESS":
+            return "pass";
+        case "FAILURE":
+        case "ERROR":
+            return "fail";
+        default:
+            // PENDING | EXPECTED
+            return "pending";
+    }
+}
+/** Is a rollup entry in a terminal (no-longer-changing) state? */
+export function isRollupEntryTerminal(entry) {
+    return rollupEntryBucket(entry) !== "pending";
+}
+/**
+ * Classify a single poll of `(mergeable, rollup)`.
+ *
+ * Pure except for the lazily-invoked `fetchAnnotations`, which is called ONLY
+ * when the whole board is terminal-and-failing — so healthy or partial boards
+ * never pay for the extra check-run annotation API calls.
+ */
+export function classifyTick(mergeable, rollup, fetchAnnotations) {
+    // (1) Merge conflict blocks CI dispatch entirely — CI never starts against an
+    // unmergeable ref, so waiting on checks is futile. Fire regardless of check
+    // count: this also covers the "zero checks because CONFLICTING" trap (AC-3a,
+    // AC-3b) — the case the issue calls out where 0 checks after a push means
+    // dispatch was blocked, not that CI is slow.
+    if (mergeable === "CONFLICTING") {
+        return {
+            kind: "blocked",
+            reason: "PR is not mergeable (CONFLICTING) — merge conflicts block CI dispatch. " +
+                "Resolve conflicts and re-push before running merge-check.",
+        };
+    }
+    // No checks yet. While GitHub is still computing mergeability or hasn't
+    // dispatched, keep polling; a genuine no-CI PR falls through to the timeout,
+    // whose message names the zero-checks case. We deliberately do NOT declare
+    // terminal here — proceeding on an empty board would skip the very CI the
+    // user asked us to wait for.
+    if (rollup.length === 0) {
+        return { kind: "pending", pending: 0, total: 0 };
+    }
+    const pending = rollup.filter((e) => !isRollupEntryTerminal(e));
+    if (pending.length > 0) {
+        return { kind: "pending", pending: pending.length, total: rollup.length };
+    }
+    // (3) Every check is terminal. If the board is uniformly failing it may be a
+    // billing lockout (runner never started) rather than real test failures —
+    // scan the head-SHA annotations for the not-started signature (AC-3c). Only
+    // then; a healthy or partially-failing board is a real verdict, not a block.
+    const buckets = rollup.map((e) => ({
+        bucket: rollupEntryBucket(e),
+    }));
+    if (allChecksFailing(buckets)) {
+        const infra = detectInfraBlockedCi(fetchAnnotations());
+        if (infra.blocked) {
+            return {
+                kind: "blocked",
+                reason: infra.message ??
+                    "CI runner was not started (infrastructure blocked).",
+                checkName: infra.checkName,
+            };
+        }
+    }
+    return { kind: "terminal" };
+}
+/** Default watch poll interval (seconds) when `--interval` is not given. */
+export const DEFAULT_WATCH_INTERVAL_S = 30;
+/** Default watch timeout (seconds) when `--timeout` is not given: 30 minutes. */
+export const DEFAULT_WATCH_TIMEOUT_S = 1800;
+/**
+ * Smallest poll interval we will ever use, in milliseconds.
+ *
+ * A zero/sub-second interval turns the gate into a tight `gh`-spawning loop that
+ * can trip GitHub rate limiting, so the floor is enforced even against an
+ * explicit request.
+ */
+export const MIN_WATCH_INTERVAL_MS = 1000;
+/**
+ * Convert user-supplied `--interval`/`--timeout` *seconds* into validated
+ * milliseconds, falling back to the defaults for anything unusable.
+ *
+ * Why this exists: `??` only defends against `null`/`undefined`, and
+ * `parseInt("abc", 10)` yields `NaN`, which is neither. A `NaN` timeout makes
+ * `start + timeoutMs` `NaN`, so `now >= deadline` is permanently false and the
+ * watch loop never gives up; a `NaN`/`0` interval makes `setTimeout` fire
+ * immediately, so it never sleeps either. The two combine into an unbounded,
+ * zero-delay poll loop. This mirrors the numeric-input guards used elsewhere in
+ * the codebase (`batch-executor.ts` `maxIter`/`autoWait`, `merge.ts` issue-number
+ * parsing) rather than trusting the raw flag value.
+ *
+ * The CLI rejects malformed values outright (see `bin/cli.ts`); this is the
+ * defence for programmatic callers that build `MergeCommandOptions` directly.
+ */
+export function resolveWatchTiming(options) {
+    const seconds = (value, fallback) => typeof value === "number" && Number.isFinite(value) && value > 0
+        ? value
+        : fallback;
+    return {
+        intervalMs: Math.max(MIN_WATCH_INTERVAL_MS, seconds(options.interval, DEFAULT_WATCH_INTERVAL_S) * 1000),
+        timeoutMs: seconds(options.timeout, DEFAULT_WATCH_TIMEOUT_S) * 1000,
+    };
+}
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Poll a PR's rollup until it is terminal, blocked, or timed out.
+ *
+ * `sleepFn`/`nowFn` are injectable so tests run instantly and deterministically
+ * without real timers. The loop always classifies a *fresh* poll before it can
+ * declare a timeout, so a check that turns terminal on the final interval is
+ * never swallowed by the deadline.
+ */
+export async function waitForChecks(prNumber, options, gh, sleepFn = defaultSleep, nowFn = Date.now) {
+    const { onPoll } = options;
+    // Defensive normalisation. `resolveWatchTiming` already sanitises the CLI
+    // path, but the loop itself must be incapable of running away: a non-finite
+    // deadline makes `now >= deadline` permanently false (never times out) and a
+    // non-finite/zero interval makes `setTimeout` fire immediately (never
+    // sleeps), which together spawn `gh` in a tight loop forever. `timeoutMs: 0`
+    // is deliberately preserved — callers use it to mean "deadline already
+    // exhausted, poll once then give up" (see the shared deadline in
+    // `runWatchGate`).
+    const intervalMs = Math.max(MIN_WATCH_INTERVAL_MS, Number.isFinite(options.intervalMs) ? options.intervalMs : 0);
+    const timeoutMs = Number.isFinite(options.timeoutMs) && options.timeoutMs >= 0
+        ? options.timeoutMs
+        : DEFAULT_WATCH_TIMEOUT_S * 1000;
+    const start = nowFn();
+    const deadline = start + timeoutMs;
+    let polls = 0;
+    // Lazy annotation fetch — only reached from classifyTick's all-failing branch.
+    const fetchAnnotations = () => {
+        const sha = gh.getPRHeadShaSync(prNumber);
+        if (!sha)
+            return [];
+        return gh.getCheckRunAnnotationsSync(sha);
+    };
+    for (;;) {
+        polls++;
+        const mergeable = gh.getMergeableStateSync(prNumber);
+        const rollup = gh.getStatusCheckRollupSync(prNumber);
+        const tick = classifyTick(mergeable, rollup, fetchAnnotations);
+        const elapsedMs = nowFn() - start;
+        if (tick.kind === "blocked") {
+            return {
+                status: "blocked",
+                reason: tick.reason,
+                checkName: tick.checkName,
+                polls,
+                elapsedMs,
+            };
+        }
+        if (tick.kind === "terminal") {
+            return { status: "terminal", polls, elapsedMs };
+        }
+        // Pending: report progress.
+        if (onPoll) {
+            onPoll(tick.total === 0
+                ? "No checks reported yet…"
+                : `${tick.total - tick.pending}/${tick.total} checks terminal…`);
+        }
+        // Deadline reached. The classify above was a fresh poll, so timing out now
+        // cannot swallow a late terminal.
+        if (nowFn() >= deadline) {
+            const timeoutSec = Math.round(timeoutMs / 1000);
+            const reason = tick.total === 0
+                ? `Watch timed out after ${timeoutSec}s: no CI checks ever appeared for PR #${prNumber} ` +
+                    `(CI may not be configured, or dispatch was blocked).`
+                : `Watch timed out after ${timeoutSec}s: ${tick.pending}/${tick.total} checks still pending on PR #${prNumber}.`;
+            return { status: "timeout", reason, polls, elapsedMs };
+        }
+        const remaining = deadline - nowFn();
+        await sleepFn(Math.min(intervalMs, Math.max(0, remaining)));
+    }
+}

package/dist/src/lib/qa/infra-blocked-ci.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Infra-blocked CI detection helpers used by the `/qa` Phase 1 CI status check.
+ *
+ * A repository that has hit its GitHub Actions spending limit fails **every**
+ * check within seconds of starting: no runner is ever allocated, so no step
+ * executes. `gh pr checks` and `gh run view` report these as ordinary failures,
+ * and the default status mapping (`FAILURE → NOT_MET → blocks merge`) then marks
+ * CI-dependent ACs as unmet for a condition no code change can fix — findings
+ * that would go on to feed `/loop` and burn iterations "fixing" working code.
+ *
+ * The real cause exists only as a check-run annotation. `/qa` uses these helpers
+ * to recognise that signature and reclassify CI as infra-blocked instead.
+ *
+ * Both functions are pure predicates over already-fetched API data; the `gh api`
+ * plumbing lives in the skill prompt, mirroring `./markdown-only-ci.ts`.
+ */
+/** Minimal shape of a `gh pr checks --json name,state,bucket` entry. */
+export interface CiCheckBucket {
+    /** `gh` rollup bucket: `pass` | `fail` | `pending` | `skipping`. */
+    bucket: string;
+}
+/**
+ * Predicate: is *every* check in the `fail` bucket?
+ *
+ * This is the gate for the annotation query. A mix of real failures and
+ * fail-fast ones is not the billing-lockout signature — only a uniformly red
+ * board is — so healthy and partially-failing PRs never pay for the extra API
+ * calls, and their status mapping is untouched.
+ *
+ * An empty list means "no CI configured", which is a separate case handled by
+ * the skill's existing empty-response branch, so it returns `false` here rather
+ * than vacuously true.
+ *
+ * @param checks - Entries from `gh pr checks --json name,state,bucket`.
+ * @returns `true` only if `checks` is non-empty and every entry is `fail`.
+ */
+export declare function allChecksFailing(checks: readonly CiCheckBucket[]): boolean;
+/**
+ * The runner-never-started signature.
+ *
+ * Deliberately matches on the annotation **message only**, with no
+ * `annotation_level` condition. The captured fixture does carry
+ * `annotation_level: "failure"`, but gating on it would add a requirement the
+ * acceptance criteria never state, and a `warning`-level variant of the same
+ * message would then be silently missed — the exact class of failure this
+ * detection exists to prevent.
+ */
+export declare const NOT_STARTED_SIGNATURE: RegExp;
+/** Minimal shape of a GitHub check-run annotation. */
+export interface CheckAnnotation {
+    message?: string | null;
+    annotation_level?: string | null;
+    path?: string | null;
+}
+/** A check paired with the annotations fetched from its `annotations_url`. */
+export interface AnnotatedCheck {
+    checkName: string;
+    annotations?: readonly CheckAnnotation[] | null;
+}
+/** Outcome of scanning failing checks for the not-started signature. */
+export interface InfraBlockedResult {
+    /** `true` when CI is red for infrastructure reasons, not code reasons. */
+    blocked: boolean;
+    /**
+     * The matching annotation message, **verbatim**. `/qa` surfaces this as the
+     * action item rather than paraphrasing it — the message names the remedy
+     * (e.g. the billing settings page), and a paraphrase would lose it.
+     */
+    message?: string;
+    /** Name of the check whose annotation matched, for the QA report. */
+    checkName?: string;
+}
+/**
+ * Scan failing checks' annotations for the not-started signature.
+ *
+ * Returns on the first match: when the board is uniformly red for a billing
+ * lockout, every check carries the same annotation, so one is representative
+ * and the caller can stop fetching.
+ *
+ * Deliberately defensive about its input shape. Callers feed this raw `gh api`
+ * output, and a failed annotations request (404, rate limit, revoked token)
+ * yields an *object* — `{"message":"Not Found"}` — where an array is expected.
+ * Iterating that throws. Since the whole point of this detector is to keep a
+ * broken-CI situation from derailing the QA phase, a malformed payload must
+ * degrade to "not infra-blocked", never crash the run.
+ *
+ * @param checks - Failing checks with their fetched annotations.
+ * @returns `{ blocked: true, message, checkName }` on a match, else `{ blocked: false }`.
+ */
+export declare function detectInfraBlockedCi(checks: readonly AnnotatedCheck[]): InfraBlockedResult;

package/dist/src/lib/qa/infra-blocked-ci.js

@@ -0,0 +1,80 @@
+/**
+ * Infra-blocked CI detection helpers used by the `/qa` Phase 1 CI status check.
+ *
+ * A repository that has hit its GitHub Actions spending limit fails **every**
+ * check within seconds of starting: no runner is ever allocated, so no step
+ * executes. `gh pr checks` and `gh run view` report these as ordinary failures,
+ * and the default status mapping (`FAILURE → NOT_MET → blocks merge`) then marks
+ * CI-dependent ACs as unmet for a condition no code change can fix — findings
+ * that would go on to feed `/loop` and burn iterations "fixing" working code.
+ *
+ * The real cause exists only as a check-run annotation. `/qa` uses these helpers
+ * to recognise that signature and reclassify CI as infra-blocked instead.
+ *
+ * Both functions are pure predicates over already-fetched API data; the `gh api`
+ * plumbing lives in the skill prompt, mirroring `./markdown-only-ci.ts`.
+ */
+/**
+ * Predicate: is *every* check in the `fail` bucket?
+ *
+ * This is the gate for the annotation query. A mix of real failures and
+ * fail-fast ones is not the billing-lockout signature — only a uniformly red
+ * board is — so healthy and partially-failing PRs never pay for the extra API
+ * calls, and their status mapping is untouched.
+ *
+ * An empty list means "no CI configured", which is a separate case handled by
+ * the skill's existing empty-response branch, so it returns `false` here rather
+ * than vacuously true.
+ *
+ * @param checks - Entries from `gh pr checks --json name,state,bucket`.
+ * @returns `true` only if `checks` is non-empty and every entry is `fail`.
+ */
+export function allChecksFailing(checks) {
+    if (checks.length === 0)
+        return false;
+    return checks.every((check) => check.bucket === "fail");
+}
+/**
+ * The runner-never-started signature.
+ *
+ * Deliberately matches on the annotation **message only**, with no
+ * `annotation_level` condition. The captured fixture does carry
+ * `annotation_level: "failure"`, but gating on it would add a requirement the
+ * acceptance criteria never state, and a `warning`-level variant of the same
+ * message would then be silently missed — the exact class of failure this
+ * detection exists to prevent.
+ */
+export const NOT_STARTED_SIGNATURE = /job was not started/i;
+/**
+ * Scan failing checks' annotations for the not-started signature.
+ *
+ * Returns on the first match: when the board is uniformly red for a billing
+ * lockout, every check carries the same annotation, so one is representative
+ * and the caller can stop fetching.
+ *
+ * Deliberately defensive about its input shape. Callers feed this raw `gh api`
+ * output, and a failed annotations request (404, rate limit, revoked token)
+ * yields an *object* — `{"message":"Not Found"}` — where an array is expected.
+ * Iterating that throws. Since the whole point of this detector is to keep a
+ * broken-CI situation from derailing the QA phase, a malformed payload must
+ * degrade to "not infra-blocked", never crash the run.
+ *
+ * @param checks - Failing checks with their fetched annotations.
+ * @returns `{ blocked: true, message, checkName }` on a match, else `{ blocked: false }`.
+ */
+export function detectInfraBlockedCi(checks) {
+    if (!Array.isArray(checks))
+        return { blocked: false };
+    for (const check of checks) {
+        const annotations = check?.annotations;
+        if (!Array.isArray(annotations))
+            continue;
+        for (const annotation of annotations) {
+            const message = annotation?.message;
+            if (typeof message === "string" && NOT_STARTED_SIGNATURE.test(message)) {
+                return { blocked: true, message, checkName: check.checkName };
+            }
+        }
+    }
+    return { blocked: false };
+}

package/dist/src/lib/settings.d.ts

@@ -112,6 +112,18 @@ export interface RunSettings {
      * Default: true
      */
     retry: boolean;
+    /**
+     * Total minutes willing to wait for an exhausted rate-limit window to reopen
+     * before halting the run (#804).
+     *
+     * `0` (default) disables auto-wait: a window-exhausted rate limit halts
+     * immediately, exactly as it did before #804. Any positive value is a TOTAL
+     * budget per issue, not a per-occurrence allowance.
+     *
+     * The wait is in-process — it does not survive closing the terminal.
+     * Overridable per-invocation with `--auto-wait <minutes>`.
+     */
+    autoWaitMinutes: number;
     /**
      * Threshold for stale branch detection in pre-flight checks.
      * If feature branch is more than this many commits behind main,
@@ -311,6 +323,7 @@ export declare const RunSettingsSchema: z.ZodObject<{
     defaultBase: z.ZodOptional<z.ZodString>;
     mcp: z.ZodDefault<z.ZodBoolean>;
     retry: z.ZodDefault<z.ZodBoolean>;
+    autoWaitMinutes: z.ZodDefault<z.ZodNumber>;
     staleBranchThreshold: z.ZodDefault<z.ZodNumber>;
     resolvedIssueTTL: z.ZodDefault<z.ZodNumber>;
     pmRun: z.ZodOptional<z.ZodString>;
@@ -403,6 +416,7 @@ export declare const SettingsSchema: z.ZodObject<{
         defaultBase: z.ZodOptional<z.ZodString>;
         mcp: z.ZodDefault<z.ZodBoolean>;
         retry: z.ZodDefault<z.ZodBoolean>;
+        autoWaitMinutes: z.ZodDefault<z.ZodNumber>;
         staleBranchThreshold: z.ZodDefault<z.ZodNumber>;
         resolvedIssueTTL: z.ZodDefault<z.ZodNumber>;
         pmRun: z.ZodOptional<z.ZodString>;

package/dist/src/lib/settings.js

@@ -41,16 +41,24 @@ export const RunSettingsSchema = z.object({
     logJson: z.boolean().default(true),
     logPath: z.string().default(".sequant/logs"),
     autoDetectPhases: z.boolean().default(true),
-    timeout: z.number().default(1800),
+    // #833: `.positive()` on the three that feed a timer or a loop bound. A `0`
+    // or negative here is not a weaker setting — it is an instant abort
+    // (`setTimeout` clamps a non-positive delay to 0) or a loop that never runs
+    // (`while (iteration < maxIterations)` is false on entry). The resolvers now
+    // guard these too; the schema is what gets the bad key *named* at load
+    // instead of silently swapped for a default. Left unconstrained elsewhere
+    // (`staleBranchThreshold`, `resolvedIssueTTL`) where 0 is meaningful.
+    timeout: z.number().positive().default(1800),
     sequential: z.boolean().default(false),
-    concurrency: z.number().default(3),
+    concurrency: z.number().positive().default(3),
     qualityLoop: z.boolean().default(false),
-    maxIterations: z.number().default(3),
+    maxIterations: z.number().positive().default(3),
     smartTests: z.boolean().default(true),
     rotation: RotationSettingsSchema.default(() => RotationSettingsSchema.parse({})),
     defaultBase: z.string().optional(),
     mcp: z.boolean().default(true),
     retry: z.boolean().default(true),
+    autoWaitMinutes: z.number().min(0).default(0),
     staleBranchThreshold: z.number().default(5),
     resolvedIssueTTL: z.number().default(7),
     pmRun: z.string().optional(),
@@ -243,6 +251,43 @@ function formatZodErrors(error) {
         return { path, message };
     });
 }
+/**
+ * Delete the values Zod rejected from a deep clone of `raw`, so a re-parse can
+ * fill just those with their defaults and keep every valid sibling (#833).
+ *
+ * An array index in the path means one element of an array failed. Deleting by
+ * index would leave a hole that re-parses as `undefined` and fails again, so
+ * the whole array is dropped and re-defaulted instead.
+ */
+function stripInvalidPaths(raw, issues) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return {};
+    const clone = structuredClone(raw);
+    for (const issue of issues) {
+        // An empty path means the root object itself was rejected — nothing to
+        // salvage, so fall back to a bare defaults parse.
+        if (issue.path.length === 0)
+            return {};
+        // Truncate at the first array index: drop the array, not an element.
+        const firstIndex = issue.path.findIndex((seg) => typeof seg === "number");
+        const path = firstIndex === -1 ? issue.path : issue.path.slice(0, firstIndex);
+        if (path.length === 0)
+            return {};
+        let cursor = clone;
+        for (const key of path.slice(0, -1)) {
+            const next = cursor?.[key];
+            cursor =
+                next && typeof next === "object" && !Array.isArray(next)
+                    ? next
+                    : undefined;
+            if (!cursor)
+                break;
+        }
+        if (cursor)
+            delete cursor[path[path.length - 1]];
+    }
+    return clone;
+}
 /**
  * Validate a raw settings object against the Zod schema (AC-2).
  *
@@ -262,8 +307,15 @@ export function validateSettings(raw) {
     }
     // Zod validation failed — report errors as warnings and fall back to defaults
     warnings.push(...formatZodErrors(result.error));
-    // Try to salvage what we can: parse with defaults for the invalid parts
-    // by stripping invalid fields and re-parsing
+    // Salvage the valid settings by dropping only the rejected keys and
+    // re-parsing. #833: this previously re-parsed `{}` despite a comment saying
+    // it stripped invalid fields, so a single bad value — one typo in
+    // `run.timeout` — silently discarded the user's entire settings.json and
+    // reverted every unrelated key to its default.
+    const salvaged = SettingsSchema.safeParse(stripInvalidPaths(raw, result.error.issues));
+    if (salvaged.success) {
+        return { settings: salvaged.data, warnings };
+    }
     const fallback = SettingsSchema.safeParse({});
     const settings = (fallback.success ? fallback.data : DEFAULT_SETTINGS);
     return { settings, warnings };
@@ -350,6 +402,7 @@ export const DEFAULT_SETTINGS = {
         rotation: DEFAULT_ROTATION_SETTINGS,
         mcp: true, // Enable MCP servers by default in headless mode
         retry: true, // Enable automatic retry with MCP fallback by default
+        autoWaitMinutes: 0, // #804: auto-wait off by default — window exhaustion halts
         staleBranchThreshold: 5, // Block QA/test if feature is >5 commits behind main
         resolvedIssueTTL: 7, // Auto-prune resolved issues after 7 days
         relay: true, // Enable interactive relay (#383) by default
@@ -592,11 +645,11 @@ Generated by \`sequant init\`. See defaults below.
 | \`logJson\` | boolean | \`true\` | Enable JSON logging |
 | \`logPath\` | string | \`".sequant/logs"\` | Path to log directory |
 | \`autoDetectPhases\` | boolean | \`true\` | Auto-detect phases from GitHub issue labels |
-| \`timeout\` | number | \`1800\` | Default timeout per phase in seconds |
+| \`timeout\` | number (> 0) | \`1800\` | Default timeout per phase in seconds. Must be positive — 0 or negative is rejected with a warning and the default used (#833) |
 | \`sequential\` | boolean | \`false\` | Run issues sequentially by default |
-| \`concurrency\` | number | \`3\` | Max concurrent issues in parallel mode |
+| \`concurrency\` | number (> 0) | \`3\` | Max concurrent issues in parallel mode. Must be positive (#833) |
 | \`qualityLoop\` | boolean | \`false\` | Enable quality loop by default |
-| \`maxIterations\` | number | \`3\` | Max iterations for quality loop |
+| \`maxIterations\` | number (> 0) | \`3\` | Max iterations for quality loop. Must be positive (#833) |
 | \`smartTests\` | boolean | \`true\` | Enable smart test detection |
 | \`defaultBase\` | string | — | Default base branch for worktree creation |
 | \`mcp\` | boolean | \`true\` | Enable MCP servers in headless mode |