sequant 2.9.0 → 2.11.0

package/dist/src/commands/resume.d.ts

@@ -0,0 +1,113 @@
+/**
+ * sequant resume — re-enter runs halted on a waitable rate-limit window
+ * (#892).
+ *
+ * The durable counterpart to `--auto-wait` (#804): when a run halts on an
+ * exhausted `five_hour`/`seven_day` window (#860 classification), the halt
+ * path writes `windowHalt.resumeAt` to issue state and exits cleanly with the
+ * per-issue lock released. This command is the re-entry: a no-op before
+ * `resumeAt` (clear message, exit 0 — safe to invoke from cron/launchd every
+ * few minutes), and after `resumeAt` it re-runs the halted issues through the
+ * normal `sequant run` path with `--resume` semantics, so completed phases
+ * (GitHub markers) and completed issues (#837 state guard) are skipped.
+ *
+ * Re-entries are bounded per issue by {@link MAX_RESUME_REENTRIES} (AC-3), so
+ * a window that never reopens cannot ping-pong a scheduler: the bound halts
+ * with the same labeled terminal message a spent auto-wait produces today.
+ */
+import { StateManager } from "../lib/workflow/state-manager.js";
+import { MAX_RESUME_REENTRIES } from "../lib/workflow/state-schema.js";
+import type { IssueState } from "../lib/workflow/state-schema.js";
+import type { RunOptions } from "../lib/workflow/types.js";
+import type { LockFile } from "../lib/locks/index.js";
+export { MAX_RESUME_REENTRIES };
+/** One resumable (or not-yet / exhausted) issue in a {@link ResumePlan}. */
+export interface ResumeCandidate {
+    issueNumber: number;
+    /** ISO timestamp after which re-entry can proceed. */
+    resumeAt: string;
+    /** Phase that halted. */
+    phase: string;
+    /** Re-entry attempts already consumed. */
+    reentries: number;
+}
+/**
+ * Partition of halted issues by what `sequant resume` should do with them.
+ * Pure data — computed by {@link planResume}, rendered/acted on by the
+ * command shell.
+ */
+export interface ResumePlan {
+    /** Past `resumeAt` and under the re-entry bound: re-run these. */
+    due: ResumeCandidate[];
+    /** Before `resumeAt`: report and exit 0 (AC-2 no-op contract). */
+    notYet: ResumeCandidate[];
+    /** Re-entry bound consumed (AC-3): terminal, needs human attention. */
+    exhausted: ResumeCandidate[];
+}
+/**
+ * Decide what to do with every halted issue (#892 AC-2/AC-3).
+ *
+ * Pure so the before/after-`resumeAt` and bound edges are unit-testable with
+ * an injected clock. Issues whose persisted status is already completed
+ * (#837 vocabulary) are excluded even if a stale `windowHalt` survived — the
+ * run path would skip them anyway, so re-entering buys nothing.
+ *
+ * @param states     All persisted issue states.
+ * @param requested  Restrict to these issue numbers (empty = all halted).
+ * @param now        Epoch ms clock, injectable for tests.
+ */
+export declare function planResume(states: Record<number, IssueState>, requested: number[], now: number): ResumePlan;
+/**
+ * Terminal message for an issue whose re-entry bound is spent (#892 AC-3).
+ * Mirrors today's labeled halt vocabulary (`Rate limited — resets at …`,
+ * `auto-wait N/M`): names the real cause, the consumed bound, and the manual
+ * way out.
+ *
+ * @internal Exported for testing
+ */
+export declare function reentryBoundMessage(candidate: ResumeCandidate): string;
+/**
+ * The delegated run options for a re-entry: `resume: true` (completed phases
+ * are skipped via GitHub markers) and nothing else. `RunOptions` is
+ * normalized so an absent field means "resolve from settings/defaults"
+ * (`config-resolver` only reacts to explicit `false` / `no*` fields), so a
+ * bare object behaves exactly like an attended `sequant run <issue> --resume`
+ * — MCP, retry ladder, rebase, and PR creation all follow the user's settings.
+ *
+ * @internal Exported for testing
+ */
+export declare function buildReentryRunOptions(): RunOptions;
+/** Options accepted by {@link resumeCommand}. */
+export interface ResumeCommandOptions {
+    /** Print the plan without consuming a re-entry or spawning a run. */
+    dryRun?: boolean;
+}
+/**
+ * Injectable collaborators for {@link resumeCommand}.
+ *
+ * @internal For testing only — production callers (bin/cli.ts) omit this and
+ * get the real StateManager / LockManager / runCommand / clock. bin/cli.ts
+ * wraps the action in an arrow function so commander's third positional (the
+ * Command instance) can never land here.
+ */
+export interface ResumeCommandDeps {
+    stateManager?: StateManager;
+    runFn?: (issues: string[], options: RunOptions) => Promise<void>;
+    /** Read-only lock probe; defaults to `LockManager.check`. */
+    checkLock?: (issue: number) => LockFile | null;
+    now?: () => number;
+}
+/**
+ * Command entry for `sequant resume [issues...]`.
+ *
+ * Exit contract (load-bearing for schedulers, AC-2):
+ * - nothing halted / nothing due yet → exit 0 (quiet no-op);
+ * - due issues → re-entry counter consumed, then delegates to the normal run
+ *   path (its exit code stands);
+ * - a due issue whose lock is held by another session is skipped WITHOUT
+ *   consuming a re-entry (the run path would skip it anyway; someone is
+ *   already working on it) — exit 0 when that leaves nothing to run;
+ * - only exhausted issues → exit 1 with the labeled terminal message, so a
+ *   wrapper can alert a human instead of silently looping forever.
+ */
+export declare function resumeCommand(issues: string[], options?: ResumeCommandOptions, deps?: ResumeCommandDeps): Promise<void>;

package/dist/src/commands/resume.js

@@ -0,0 +1,193 @@
+/**
+ * sequant resume — re-enter runs halted on a waitable rate-limit window
+ * (#892).
+ *
+ * The durable counterpart to `--auto-wait` (#804): when a run halts on an
+ * exhausted `five_hour`/`seven_day` window (#860 classification), the halt
+ * path writes `windowHalt.resumeAt` to issue state and exits cleanly with the
+ * per-issue lock released. This command is the re-entry: a no-op before
+ * `resumeAt` (clear message, exit 0 — safe to invoke from cron/launchd every
+ * few minutes), and after `resumeAt` it re-runs the halted issues through the
+ * normal `sequant run` path with `--resume` semantics, so completed phases
+ * (GitHub markers) and completed issues (#837 state guard) are skipped.
+ *
+ * Re-entries are bounded per issue by {@link MAX_RESUME_REENTRIES} (AC-3), so
+ * a window that never reopens cannot ping-pong a scheduler: the bound halts
+ * with the same labeled terminal message a spent auto-wait produces today.
+ */
+import chalk from "chalk";
+import { StateManager } from "../lib/workflow/state-manager.js";
+import { MAX_RESUME_REENTRIES } from "../lib/workflow/state-schema.js";
+import { isCompletedIssueStatus } from "../lib/workflow/completed-status.js";
+import { formatResetTime } from "../lib/errors.js";
+import { LockManager, formatLockedMessage } from "../lib/locks/index.js";
+import { runCommand } from "./run.js";
+// Re-exported for callers that treat the resume command as the feature's
+// entry point; the constant itself lives beside the schema field it bounds.
+export { MAX_RESUME_REENTRIES };
+/**
+ * Decide what to do with every halted issue (#892 AC-2/AC-3).
+ *
+ * Pure so the before/after-`resumeAt` and bound edges are unit-testable with
+ * an injected clock. Issues whose persisted status is already completed
+ * (#837 vocabulary) are excluded even if a stale `windowHalt` survived — the
+ * run path would skip them anyway, so re-entering buys nothing.
+ *
+ * @param states     All persisted issue states.
+ * @param requested  Restrict to these issue numbers (empty = all halted).
+ * @param now        Epoch ms clock, injectable for tests.
+ */
+export function planResume(states, requested, now) {
+    const plan = { due: [], notYet: [], exhausted: [] };
+    const requestedSet = new Set(requested);
+    for (const [key, state] of Object.entries(states)) {
+        const issueNumber = Number(key);
+        if (requested.length > 0 && !requestedSet.has(issueNumber))
+            continue;
+        if (!state.windowHalt)
+            continue;
+        if (isCompletedIssueStatus(state.status))
+            continue;
+        const candidate = {
+            issueNumber,
+            resumeAt: state.windowHalt.resumeAt,
+            phase: state.windowHalt.phase,
+            reentries: state.windowHalt.reentries,
+        };
+        if (candidate.reentries >= MAX_RESUME_REENTRIES) {
+            plan.exhausted.push(candidate);
+        }
+        else if (new Date(candidate.resumeAt).getTime() > now) {
+            plan.notYet.push(candidate);
+        }
+        else {
+            plan.due.push(candidate);
+        }
+    }
+    // Deterministic output order regardless of state-file key order.
+    for (const bucket of [plan.due, plan.notYet, plan.exhausted]) {
+        bucket.sort((a, b) => a.issueNumber - b.issueNumber);
+    }
+    return plan;
+}
+/**
+ * Terminal message for an issue whose re-entry bound is spent (#892 AC-3).
+ * Mirrors today's labeled halt vocabulary (`Rate limited — resets at …`,
+ * `auto-wait N/M`): names the real cause, the consumed bound, and the manual
+ * way out.
+ *
+ * @internal Exported for testing
+ */
+export function reentryBoundMessage(candidate) {
+    const resetLabel = formatResetTime(new Date(candidate.resumeAt).getTime());
+    return (`Rate limited — re-entry bound reached ` +
+        `(${candidate.reentries}/${MAX_RESUME_REENTRIES}), window still closed ` +
+        `at last halt (${candidate.phase} phase, resumable at ${resetLabel}). ` +
+        `Re-run manually with: npx sequant run ${candidate.issueNumber} --resume`);
+}
+/**
+ * The delegated run options for a re-entry: `resume: true` (completed phases
+ * are skipped via GitHub markers) and nothing else. `RunOptions` is
+ * normalized so an absent field means "resolve from settings/defaults"
+ * (`config-resolver` only reacts to explicit `false` / `no*` fields), so a
+ * bare object behaves exactly like an attended `sequant run <issue> --resume`
+ * — MCP, retry ladder, rebase, and PR creation all follow the user's settings.
+ *
+ * @internal Exported for testing
+ */
+export function buildReentryRunOptions() {
+    return { resume: true };
+}
+/**
+ * Command entry for `sequant resume [issues...]`.
+ *
+ * Exit contract (load-bearing for schedulers, AC-2):
+ * - nothing halted / nothing due yet → exit 0 (quiet no-op);
+ * - due issues → re-entry counter consumed, then delegates to the normal run
+ *   path (its exit code stands);
+ * - a due issue whose lock is held by another session is skipped WITHOUT
+ *   consuming a re-entry (the run path would skip it anyway; someone is
+ *   already working on it) — exit 0 when that leaves nothing to run;
+ * - only exhausted issues → exit 1 with the labeled terminal message, so a
+ *   wrapper can alert a human instead of silently looping forever.
+ */
+export async function resumeCommand(issues, options = {}, deps = {}) {
+    const requested = issues.map((raw) => {
+        const n = parseInt(raw, 10);
+        if (isNaN(n) || n <= 0) {
+            console.log(chalk.red(`❌ Invalid issue number: ${raw}`));
+            process.exitCode = 1;
+        }
+        return n;
+    });
+    if (process.exitCode === 1)
+        return;
+    const stateManager = deps.stateManager ?? new StateManager();
+    const runFn = deps.runFn ?? runCommand;
+    const checkLock = deps.checkLock ?? ((issue) => new LockManager().check(issue));
+    const now = deps.now ?? Date.now;
+    const states = await stateManager.getAllIssueStates();
+    const plan = planResume(states, requested, now());
+    if (plan.due.length === 0 &&
+        plan.notYet.length === 0 &&
+        plan.exhausted.length === 0) {
+        console.log(chalk.gray("No halted issues to resume (no windowHalt in state)."));
+        return;
+    }
+    for (const candidate of plan.notYet) {
+        const resetLabel = formatResetTime(new Date(candidate.resumeAt).getTime());
+        console.log(chalk.yellow(`⏸ #${candidate.issueNumber} not yet resumable — window reopens at ` +
+            `${resetLabel} (${candidate.phase} phase halted)`));
+    }
+    for (const candidate of plan.exhausted) {
+        console.log(chalk.red(`❌ #${candidate.issueNumber}: ${reentryBoundMessage(candidate)}`));
+    }
+    if (plan.due.length === 0) {
+        // AC-2: pre-`resumeAt` is a clean no-op (exit 0). Only an exhausted-only
+        // outcome is terminal (exit 1) — there is nothing left for a scheduler to
+        // wait for.
+        if (plan.notYet.length === 0 && plan.exhausted.length > 0) {
+            process.exitCode = 1;
+        }
+        return;
+    }
+    if (options.dryRun) {
+        for (const candidate of plan.due) {
+            console.log(chalk.green(`▶ #${candidate.issueNumber} due for re-entry ` +
+                `(${candidate.reentries + 1}/${MAX_RESUME_REENTRIES}) — dry run, not started`));
+        }
+        return;
+    }
+    // Lock probe BEFORE consuming a re-entry: a due issue another session holds
+    // would be skipped by the run path's lock acquisition anyway, so consuming
+    // one of its bounded re-entries buys nothing. The probe is read-only and
+    // best-effort — a lock acquired in the window between this check and the
+    // run's own acquisition still costs the re-entry, which is the pre-existing
+    // (rare, recoverable) behavior, just with a much smaller race window.
+    const runnable = [];
+    for (const candidate of plan.due) {
+        const holder = checkLock(candidate.issueNumber);
+        if (holder) {
+            console.log(chalk.yellow(`⏭ #${candidate.issueNumber} skipped — re-entry not consumed. ` +
+                formatLockedMessage(candidate.issueNumber, holder)));
+            continue;
+        }
+        runnable.push(candidate);
+    }
+    if (runnable.length === 0) {
+        // Every due issue is being worked on by another session: nothing for a
+        // scheduler to do this tick, nothing terminal — exit 0 and try later.
+        return;
+    }
+    // Consume the re-entry BEFORE running (AC-3): a re-entry that halts again
+    // on a still-closed window must already be counted, or the bound never
+    // trips. A re-entry that makes progress clears the record (and counter)
+    // via the halt path's success handling.
+    for (const candidate of runnable) {
+        const count = await stateManager.incrementWindowHaltReentries(candidate.issueNumber);
+        console.log(chalk.green(`▶ Resuming #${candidate.issueNumber} ` +
+            `(re-entry ${count ?? candidate.reentries + 1}/${MAX_RESUME_REENTRIES}, ` +
+            `halted in ${candidate.phase})`));
+    }
+    await runFn(runnable.map((candidate) => String(candidate.issueNumber)), buildReentryRunOptions());
+}

package/dist/src/commands/run-display.js

@@ -61,9 +61,9 @@ export function displayConfig(r) {
     if (r.mergedOptions.chain) {
         console.log(chalk.gray(`  Chain mode: enabled (each issue branches from previous)`));
     }
-    if (r.mergedOptions.qaGate) {
-        console.log(chalk.gray(`  QA gate: enabled (chain waits for QA pass)`));
-    }
+    // #795 deliberately prints nothing for `--qa-gate`: the old
+    // `QA gate: enabled (chain waits for QA pass)` line advertised gating the
+    // flag never performed. `runCommand` prints a deprecation notice instead.
 }
 /**
  * Convert workflow `IssueResult` to renderer `IssueSummary`.
@@ -90,11 +90,15 @@ function toIssueSummary(r) {
         loopTriggered: r.loopTriggered,
         prNumber: r.prNumber,
         prUrl: r.prUrl,
+        prSkippedReason: r.prSkippedReason,
     };
     if (!r.success) {
+        // #879: a PR-creation failure has no failed phase — fall back to its error
+        // so the summary cell reads the real reason, not the useless "phase failed".
         summary.failureReason =
             failedPhase?.error ??
                 r.abortReason ??
+                r.prCreationError ??
                 `${failedPhase?.phase ?? "phase"} failed`;
         if (failedPhase?.verdict) {
             summary.qaVerdict = String(failedPhase.verdict);
@@ -159,7 +163,12 @@ export function displaySummary(result, renderer) {
     if (results.length === 0)
         return;
     const issueSummaries = results.map(toIssueSummary);
-    const totalSeconds = results.reduce((sum, r) => sum + (r.durationSeconds ?? 0), 0);
+    // #867: run wall clock, computed once by the orchestrator (RunResult), NOT
+    // `results.reduce(sum + durationSeconds)`. Under --parallel that sum
+    // double-counts overlapping issues and over-reports by ~the concurrency
+    // factor (a 36m 18s run printed 1h 12m at concurrency 3). The orchestrator is
+    // the only component that brackets the whole run, so it owns this value.
+    const totalSeconds = result.wallClockDurationSeconds;
     if (renderer) {
         renderer.renderSummary({
             issues: issueSummaries,
@@ -176,6 +185,31 @@ export function displaySummary(result, renderer) {
             dryRun: config.dryRun,
         });
     }
+    // #817: when `--ready-gate` ran, surface each issue's gate outcome (threshold
+    // reached vs guard halt) in the summary the same way `sequant ready` reports
+    // it — the "never merged" contract and stop reason are the human's cue to
+    // review and merge manually. Only issues that actually ran the gate carry it.
+    //
+    // A gate that *failed* is listed here too. It is non-fatal (the PR still
+    // opens), but omitting it would make a run whose gate crashed look exactly
+    // like one that gated cleanly — the user opted into a second look and needs
+    // to know it never happened.
+    const gated = results.filter((r) => r.readyGate || r.readyGateError);
+    if (gated.length > 0) {
+        console.log(colors.muted("  Ready gate (#817) — never merged:"));
+        for (const r of gated) {
+            if (!r.readyGate) {
+                console.log(`     #${r.issueNumber}: ${colors.warning("✗ gate did not run")} · ${r.readyGateError} · PR opened ungated — re-run \`sequant ready ${r.issueNumber}\``);
+                continue;
+            }
+            const g = r.readyGate;
+            const label = g.ready
+                ? colors.success(`✓ ${g.reason}`)
+                : colors.warning(`⚠️  ${g.reason}`);
+            console.log(`     #${r.issueNumber}: ${label} · policy \`${g.policy}\` · ${g.iterations} QA pass(es) · status \`${g.issueStatus}\``);
+        }
+        console.log("");
+    }
     // #760: a chain link whose checkpoint commit failed keeps its own work but
     // loses the recovery point resume depends on, and the per-issue warning has
     // long scrolled past by now on a multi-hour chain. Restate it at the summary,

package/dist/src/commands/run-flags.d.ts

@@ -1,9 +1,10 @@
 /**
  * Run flag normalization (#705) — keeps run.ts thin (#503 AC-2: <200 LOC).
  *
- * Two pure resolvers for the `run` command's flag surface:
+ * Pure resolvers for the `run` command's flag surface:
  *   - `normalizeQualityLoop`: ORs the hidden `-q` alias into `--quality-loop`.
  *   - `resolveTuiEnabled`: decides whether the boxed Ink TUI mounts.
+ *   - `deprecatedFlagNotices`: messages for flags kept only for compatibility.
  *
  * Extracted as pure functions so the flag behavior is unit-testable without
  * driving the full `runCommand` side effects.
@@ -29,3 +30,43 @@ export declare function normalizeQualityLoop(options: RunOptions): boolean;
  *   it, so it is intentionally not consulted here.
  */
 export declare function resolveTuiEnabled(options: RunOptions, isTTY: boolean): boolean;
+/**
+ * #795: notices for flags that still parse but no longer do anything.
+ *
+ * `--qa-gate` promised to "wait for QA pass before starting the next issue in
+ * chain", but the chain loop halts on any failed link unconditionally, so the
+ * flag never changed behavior and no runtime path ever wrote the
+ * `waiting_for_qa_gate` status it advertised. It is kept parseable so existing
+ * scripts do not hard-error — the previous `--qa-gate requires --chain` check
+ * aborted the whole run, which is exactly the breakage a deprecation window
+ * exists to avoid — and it no longer requires `--chain`.
+ *
+ * Returned rather than printed so the wording is unit-testable without driving
+ * `runCommand`'s side effects.
+ */
+export declare function deprecatedFlagNotices(options: RunOptions): string[];
+/**
+ * Prints every notice from {@link deprecatedFlagNotices}.
+ *
+ * Lives here rather than inline in `run.ts` to keep that adapter under the
+ * #503 AC-2 200-LOC budget, alongside the pure resolver it wraps.
+ *
+ * Two deliberate choices, both flagged because a future reader may mistake
+ * them for oversights:
+ *
+ * 1. **stderr, not stdout.** Deprecation notices are warnings, and warnings
+ *    go on stderr (same as `abort.ts`). This keeps a script's piped stdout
+ *    clean while still surfacing the notice on a terminal.
+ * 2. **Not gated on `options.quiet`.** `--quiet` suppresses progress and
+ *    version chatter; it is not a warning switch. The scripts most likely to
+ *    still pass `--qa-gate` are CI scripts, which are also the most likely to
+ *    pass `--quiet` — suppressing there would defeat the deprecation window
+ *    for exactly its target audience. Silencing warnings should be an
+ *    explicit opt-out, not a side effect of asking for less progress output.
+ *
+ * `runCommand` calls this immediately after the header box, ahead of the
+ * manifest and settings checks: a dead flag is a fact about argv, not about
+ * project state, so it should be reported even from an uninitialized
+ * directory where those checks would return early.
+ */
+export declare function warnDeprecatedFlags(options: RunOptions): void;

package/dist/src/commands/run-flags.js

@@ -1,13 +1,15 @@
 /**
  * Run flag normalization (#705) — keeps run.ts thin (#503 AC-2: <200 LOC).
  *
- * Two pure resolvers for the `run` command's flag surface:
+ * Pure resolvers for the `run` command's flag surface:
  *   - `normalizeQualityLoop`: ORs the hidden `-q` alias into `--quality-loop`.
  *   - `resolveTuiEnabled`: decides whether the boxed Ink TUI mounts.
+ *   - `deprecatedFlagNotices`: messages for flags kept only for compatibility.
  *
  * Extracted as pure functions so the flag behavior is unit-testable without
  * driving the full `runCommand` side effects.
  */
+import chalk from "chalk";
 /**
  * #705: `-q` is a hidden alias for the quality loop (it no longer maps to
  * `--quiet`, which moved to `-s`). Returns the effective quality-loop flag so
@@ -32,3 +34,53 @@ export function normalizeQualityLoop(options) {
 export function resolveTuiEnabled(options, isTTY) {
     return options.tui !== false && isTTY && !options.quiet;
 }
+/**
+ * #795: notices for flags that still parse but no longer do anything.
+ *
+ * `--qa-gate` promised to "wait for QA pass before starting the next issue in
+ * chain", but the chain loop halts on any failed link unconditionally, so the
+ * flag never changed behavior and no runtime path ever wrote the
+ * `waiting_for_qa_gate` status it advertised. It is kept parseable so existing
+ * scripts do not hard-error — the previous `--qa-gate requires --chain` check
+ * aborted the whole run, which is exactly the breakage a deprecation window
+ * exists to avoid — and it no longer requires `--chain`.
+ *
+ * Returned rather than printed so the wording is unit-testable without driving
+ * `runCommand`'s side effects.
+ */
+export function deprecatedFlagNotices(options) {
+    const notices = [];
+    if (options.qaGate) {
+        notices.push("--qa-gate is deprecated and has no effect (#795). --chain already halts the chain on any failed issue, QA included. Remove the flag; it will be deleted in a future major release.");
+    }
+    return notices;
+}
+/**
+ * Prints every notice from {@link deprecatedFlagNotices}.
+ *
+ * Lives here rather than inline in `run.ts` to keep that adapter under the
+ * #503 AC-2 200-LOC budget, alongside the pure resolver it wraps.
+ *
+ * Two deliberate choices, both flagged because a future reader may mistake
+ * them for oversights:
+ *
+ * 1. **stderr, not stdout.** Deprecation notices are warnings, and warnings
+ *    go on stderr (same as `abort.ts`). This keeps a script's piped stdout
+ *    clean while still surfacing the notice on a terminal.
+ * 2. **Not gated on `options.quiet`.** `--quiet` suppresses progress and
+ *    version chatter; it is not a warning switch. The scripts most likely to
+ *    still pass `--qa-gate` are CI scripts, which are also the most likely to
+ *    pass `--quiet` — suppressing there would defeat the deprecation window
+ *    for exactly its target audience. Silencing warnings should be an
+ *    explicit opt-out, not a side effect of asking for less progress output.
+ *
+ * `runCommand` calls this immediately after the header box, ahead of the
+ * manifest and settings checks: a dead flag is a fact about argv, not about
+ * project state, so it should be reported even from an uninitialized
+ * directory where those checks would return early.
+ */
+export function warnDeprecatedFlags(options) {
+    for (const notice of deprecatedFlagNotices(options)) {
+        console.error(chalk.yellow(`  !  ${notice}`));
+    }
+}

package/dist/src/commands/run-progress.js

@@ -58,6 +58,18 @@ export function buildProgressWiring(args) {
             // #543: activity events only feed the TUI's nowLine — skip the line renderer.
             if (event === "activity")
                 return;
+            // #804 AC-7: unlike activity, a waiting event MUST reach the renderer —
+            // it is the only signal during a pause that can last hours.
+            if (event === "waiting") {
+                renderer.onEvent({
+                    issue,
+                    phase,
+                    event,
+                    text: extra?.text,
+                    wakeAtMs: extra?.wakeAtMs,
+                });
+                return;
+            }
             // #624 Item 3: pass the outer-loop iteration through so the renderer can
             // render `(attempt N/M)` / `loop N/M`.
             renderer.onEvent({
@@ -71,9 +83,22 @@ export function buildProgressWiring(args) {
         };
     }
     else if (heartbeat) {
-        onProgress = (issue, phase, event) => {
+        onProgress = (issue, phase, event, extra) => {
             if (event === "activity")
                 return;
+            // #804 AC-7: mark/clear the auto-wait so the heartbeat reports the wait
+            // and, critically, does not report it as a stall. Must be handled before
+            // the `else` below, which would otherwise `stop()` the phase entirely and
+            // leave a multi-hour wait with no liveness signal at all.
+            if (event === "waiting") {
+                if (extra?.wakeAtMs !== undefined) {
+                    heartbeat.pauseForWait({ issueNumber: issue, phase }, extra.wakeAtMs);
+                }
+                else {
+                    heartbeat.resumeFromWait({ issueNumber: issue, phase });
+                }
+                return;
+            }
             if (event === "start")
                 heartbeat.start({
                     issueNumber: issue,

package/dist/src/commands/run.js

@@ -8,15 +8,21 @@ import { parseBatches } from "../lib/workflow/batch-executor.js";
 import { RunOrchestrator } from "../lib/workflow/run-orchestrator.js";
 import { displayConfig, displaySummary } from "./run-display.js";
 import { buildProgressWiring } from "./run-progress.js";
-import { normalizeQualityLoop, resolveTuiEnabled } from "./run-flags.js";
+import { normalizeQualityLoop, resolveTuiEnabled, warnDeprecatedFlags, } from "./run-flags.js";
 // Re-export public API for backwards compatibility
 export * from "./run-compat.js";
+// #848: red pre-flight rejection + non-zero exit (process.exitCode, not exit()).
+function rejectPreflight(message) {
+    console.log(chalk.red(message));
+    process.exitCode = 1;
+}
 /** Parse CLI args → validate → delegate to RunOrchestrator.run() → display summary. */
 export async function runCommand(issues, options) {
     // #705: fold the hidden `-q` alias into qualityLoop before any consumer reads
     // it (`-q` no longer maps to --quiet, which moved to `-s`). See run-flags.ts.
     options.qualityLoop = normalizeQualityLoop(options);
     console.log(ui.headerBox("SEQUANT WORKFLOW"));
+    warnDeprecatedFlags(options);
     if (!options.quiet) {
         try {
             const v = await checkVersionCached();
@@ -31,31 +37,26 @@ export async function runCommand(issues, options) {
     }
     const manifest = await getManifest();
     if (!manifest) {
-        console.log(chalk.red("❌ Sequant is not initialized. Run `sequant init` first."));
+        rejectPreflight("❌ Sequant is not initialized. Run `sequant init` first.");
         return;
     }
     const settings = await getSettings();
     // #605: --stacked implies --chain; reject explicit --no-chain combo before
     // we evaluate any --chain-dependent constraint below.
     if (options.stacked && options.chain === false) {
-        console.log(chalk.red("❌ --stacked cannot be combined with --no-chain"));
+        rejectPreflight("❌ --stacked cannot be combined with --no-chain");
         return;
     }
     if (options.stacked) {
         options.chain = true;
     }
-    // Validate constraints
     if (options.chain && options.batch?.length) {
-        console.log(chalk.red("❌ --chain cannot be used with --batch"));
+        rejectPreflight("❌ --chain cannot be used with --batch");
         return;
     }
     if (options.concurrency !== undefined &&
         (options.concurrency < 1 || !Number.isInteger(options.concurrency))) {
-        console.log(chalk.red(`❌ Invalid --concurrency value: ${options.concurrency}. Must be a positive integer.`));
-        return;
-    }
-    if (options.qaGate && !options.chain) {
-        console.log(chalk.red("❌ --qa-gate requires --chain flag"));
+        rejectPreflight(`❌ Invalid --concurrency value: ${options.concurrency}. Must be a positive integer.`);
         return;
     }
     let batches = null;

package/dist/src/commands/state.js

@@ -27,10 +27,13 @@ export async function stateInitCommand(options = {}) {
     const result = await discoverUntrackedWorktrees(discoverOptions);
     if (options.json) {
         console.log(JSON.stringify(result, null, 2));
+        if (!result.success)
+            process.exitCode = 1;
         return;
     }
     if (!result.success) {
         console.log(chalk.red(`✗ Discovery failed: ${result.error}`));
+        process.exitCode = 1;
         return;
     }
     if (result.discovered.length === 0) {
@@ -106,6 +109,7 @@ export async function stateRebuildCommand(options = {}) {
         else {
             console.log(chalk.red(`✗ Log rebuild failed: ${logResult.error}`));
         }
+        process.exitCode = 1;
         return;
     }
     // Step 2: Discover and add untracked worktrees
@@ -204,10 +208,13 @@ export async function stateCleanCommand(options = {}) {
     });
     if (options.json) {
         console.log(JSON.stringify(result, null, 2));
+        if (!result.success)
+            process.exitCode = 1;
         return;
     }
     if (!result.success) {
         console.log(chalk.red(`✗ Cleanup failed: ${result.error}`));
+        process.exitCode = 1;
         return;
     }
     const orphanedCount = result.orphaned.length;

package/dist/src/commands/status.d.ts

@@ -1,6 +1,7 @@
 /**
  * sequant status - Show version, configuration, and workflow state
  */
+import { type IssueState } from "../lib/workflow/state-schema.js";
 export interface StatusCommandOptions {
     /** Show only issues state */
     issues?: boolean;
@@ -21,4 +22,12 @@ export interface StatusCommandOptions {
     /** Skip GitHub API queries (offline mode) */
     offline?: boolean;
 }
+/**
+ * Format a single issue state for display
+ *
+ * @internal Exported for testing only (#892: the windowHalt/autoWait pause
+ * lines are display contract — a halted issue must read as resumable, not as
+ * a bare failure).
+ */
+export declare function formatIssueState(issue: IssueState): string;
 export declare function statusCommand(options?: StatusCommandOptions): Promise<void>;