sequant 2.8.0 → 2.10.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.d.ts

@@ -9,6 +9,7 @@
  */
 import type { RunRenderer } from "../lib/cli-ui/run-renderer-types.js";
 import type { ResolvedRun, RunResult } from "../lib/workflow/run-orchestrator.js";
+import type { IssueResult } from "../lib/workflow/types.js";
 /**
  * Print pre-run config block.
  *
@@ -16,6 +17,25 @@ import type { ResolvedRun, RunResult } from "../lib/workflow/run-orchestrator.js
  * appear when non-default, matching the pre-#503 format.
  */
 export declare function displayConfig(r: ResolvedRun): void;
+/**
+ * Detect a chain halted by a rate-limit/billing failure and build the summary
+ * notice for it (#761 AC-5). Returns null when the run wasn't a chain, no
+ * issue failed, or the halting failure wasn't rate-limit-classified.
+ *
+ * Extracted from `displaySummary` so the halt-and-print decision is testable
+ * standalone — the same treatment #760 gave `planChainResumeFromState` when it
+ * hit the executeSequential testability wall.
+ *
+ * The failing phase is found with the same reverse non-loop scan as
+ * `toIssueSummary` (#766): the classification must describe the LAST attempt,
+ * not a stale first-iteration failure.
+ *
+ * @internal Exported for testing
+ */
+export declare function buildRateLimitHaltNotice(results: IssueResult[], chainEnabled: boolean): {
+    issueNumber: number;
+    label: string;
+} | null;
 /**
  * Print post-run summary: per-issue grid, log path, reflection, tips.
  *

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

@@ -10,7 +10,9 @@
 import chalk from "chalk";
 import { ui, colors } from "../lib/cli-ui.js";
 import { renderRunSummary } from "../lib/cli-ui/run-renderer.js";
+import { BillingError, RateLimitError, formatRateLimitMessage, isBillingFailure, } from "../lib/errors.js";
 import { analyzeRun, formatReflection } from "../lib/workflow/run-reflect.js";
+import { LOOP_PHASE } from "../lib/workflow/status-derivation.js";
 /**
  * Print pre-run config block.
  *
@@ -59,15 +61,27 @@ 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`.
  */
 function toIssueSummary(r) {
-    const failedPhase = r.phaseResults.find((p) => !p.success);
+    // #766: the reason to show is the LAST failing attempt, not the first.
+    // `phaseResults` accumulates every attempt across every quality-loop
+    // iteration, so `.find()` (first-wins) rendered a stale first-iteration
+    // reason: #762's cell read `Timeout after 1800s` when its real last failure
+    // was an API drop. `verdict`/`unmetCount` below hang off the same entry, so
+    // they were stale for the same reason. `loop` is excluded on the same grounds
+    // the card and log exclude it (see `status-derivation.ts`) — it is auxiliary
+    // recovery, and a trailing loop failure would mask the phase that actually
+    // failed. Reverse scan rather than `findLast`: tsconfig pins `lib: ES2022`
+    // and `findLast` is ES2023.
+    const failedPhase = [...r.phaseResults]
+        .reverse()
+        .find((p) => !p.success && p.phase !== LOOP_PHASE);
     const summary = {
         issueNumber: r.issueNumber,
         success: r.success,
@@ -78,9 +92,12 @@ function toIssueSummary(r) {
         prUrl: r.prUrl,
     };
     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);
@@ -91,6 +108,48 @@ function toIssueSummary(r) {
     }
     return summary;
 }
+/**
+ * Detect a chain halted by a rate-limit/billing failure and build the summary
+ * notice for it (#761 AC-5). Returns null when the run wasn't a chain, no
+ * issue failed, or the halting failure wasn't rate-limit-classified.
+ *
+ * Extracted from `displaySummary` so the halt-and-print decision is testable
+ * standalone — the same treatment #760 gave `planChainResumeFromState` when it
+ * hit the executeSequential testability wall.
+ *
+ * The failing phase is found with the same reverse non-loop scan as
+ * `toIssueSummary` (#766): the classification must describe the LAST attempt,
+ * not a stale first-iteration failure.
+ *
+ * @internal Exported for testing
+ */
+export function buildRateLimitHaltNotice(results, chainEnabled) {
+    if (!chainEnabled)
+        return null;
+    // Chain mode halts at the first failed link, so at most one failed issue
+    // exists; scan defensively anyway.
+    for (const r of results) {
+        if (r.success)
+            continue;
+        const failedPhase = [...r.phaseResults]
+            .reverse()
+            .find((p) => !p.success && p.phase !== LOOP_PHASE);
+        const err = failedPhase?.structuredError;
+        if (err instanceof RateLimitError || err instanceof BillingError) {
+            // Event-derived errors get their message from formatRateLimitMessage, so
+            // re-deriving from metadata is exact and includes resetsAt. But errors
+            // from the assistant-error channel carry no billing/reset metadata —
+            // re-deriving there would mislabel a BillingError as "Rate limited"
+            // (isBillingFailure({}) is false) — so fall back to the typed message
+            // when the metadata carries no signal.
+            const label = err.metadata.resetsAt !== undefined || isBillingFailure(err.metadata)
+                ? formatRateLimitMessage(err.metadata)
+                : err.message;
+            return { issueNumber: r.issueNumber, label };
+        }
+    }
+    return null;
+}
 /**
  * Print post-run summary: per-issue grid, log path, reflection, tips.
  *
@@ -103,7 +162,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,
@@ -120,6 +184,54 @@ 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,
+    // where the user is actually looking, so the next run's fail-fast is expected.
+    const checkpointFailures = results.filter((r) => r.checkpointFailed);
+    if (checkpointFailures.length > 0) {
+        console.log(colors.warning(`  ⚠️  Checkpoint commit failed for ${checkpointFailures
+            .map((r) => `#${r.issueNumber}`)
+            .join(", ")} — uncommitted work is missing from the feature branch.`));
+        console.log(colors.muted("     Resuming this chain will stop at that link until the work is committed (or use --force)."));
+        console.log("");
+    }
+    // #761: a chain halted by a rate limit already stopped at the right link,
+    // but the labeled cause has long scrolled past by now (same rationale as the
+    // #760 restatement above), and #760 added no resume flag — resume IS
+    // re-running the identical command. Say both explicitly, or the halt reads
+    // as a bug and the resume path stays undiscovered.
+    const rateLimitHalt = buildRateLimitHaltNotice(results, mergedOptions.chain === true);
+    if (rateLimitHalt) {
+        console.log(colors.warning(`  ⚠️  ${rateLimitHalt.label} — chain halted at #${rateLimitHalt.issueNumber}.`));
+        console.log(colors.muted(`     Re-run the same command to resume from #${rateLimitHalt.issueNumber} (no flag needed; completed links are skipped).`));
+        console.log("");
+    }
     if (mergedOptions.reflect && results.length > 0) {
         const reflection = analyzeRun({
             results,

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}`));
+    }
+}