sequant 2.9.0 → 2.10.0

package/dist/src/commands/merge.js

@@ -13,8 +13,12 @@
  */
 import { spawnSync } from "child_process";
 import { ui, colors } from "../lib/cli-ui.js";
-import { runMergeChecks, formatReportMarkdown, } from "../lib/merge-check/index.js";
+import { runMergeChecks, formatReportMarkdown, resolveBranches, findMostRecentLog, resolveLogDir, } from "../lib/merge-check/index.js";
 import { LockManager, formatLockedMessage } from "../lib/locks/index.js";
+import { waitForChecks, resolveWatchTiming } from "../lib/merge-check/watch.js";
+import { GitHubProvider } from "../lib/workflow/platforms/github.js";
+/** Exit code for a watch that timed out — distinct from the 0/1/2 verdicts. */
+const EXIT_WATCH_TIMEOUT = 3;
 /**
  * Determine exit code from batch verdict
  */
@@ -43,6 +47,126 @@ function getRepoRoot() {
     }
     return result.stdout.trim();
 }
+/**
+ * Resolve the PR numbers to watch for a set of issues.
+ *
+ * Reuses `resolveBranches` (git remote + worktree scan) for the issue→branch
+ * map, then prefers the run-log `prNumber` and falls back to
+ * `viewPRByBranchSync`. Issues with no discoverable PR are returned in
+ * `unresolved` so the caller can report them rather than silently skipping.
+ */
+function resolveWatchTargets(issueNumbers, repoRoot, gh) {
+    const runLog = findMostRecentLog(resolveLogDir());
+    const branches = resolveBranches(issueNumbers, repoRoot, runLog);
+    const targets = [];
+    const unresolved = [];
+    for (const b of branches) {
+        const pr = b.prNumber ?? gh.viewPRByBranchSync(b.branch)?.number ?? null;
+        if (pr) {
+            targets.push({ issue: b.issueNumber, pr });
+        }
+        else {
+            unresolved.push(b.issueNumber);
+        }
+    }
+    return { targets, unresolved };
+}
+/**
+ * Watch gate (#818): before the normal merge-check report runs, poll each
+ * resolved PR's CI rollup until every check is terminal.
+ *
+ * Contract: this **never merges**. It only decides *when* the existing report
+ * runs. Returns `true` when it has handled the outcome and the caller must stop
+ * (a dispatch block → BLOCKED/exit 2, a timeout → distinct message/exit 3, or no
+ * PR could be resolved); returns `false` when every PR reached a terminal state
+ * and the caller should fall through to `runMergeChecks` unchanged.
+ *
+ * Multiple PRs share a single wall-clock deadline so `--timeout` bounds the whole
+ * gate, not each PR independently.
+ */
+async function runWatchGate(issueNumbers, options, repoRoot) {
+    const gh = new GitHubProvider();
+    // Auto-detect issues from the most recent run log when none were given,
+    // mirroring runMergeChecks so `--watch` composes with auto-detection.
+    let issues = issueNumbers;
+    if (issues.length === 0) {
+        const runLog = findMostRecentLog(resolveLogDir());
+        if (runLog) {
+            issues = runLog.issues.map((i) => i.issueNumber);
+        }
+    }
+    const { targets, unresolved } = resolveWatchTargets(issues, repoRoot, gh);
+    if (targets.length === 0) {
+        const message = "Watch: no open PR found for " +
+            (issues.length > 0
+                ? `issue(s) ${issues.map((i) => `#${i}`).join(", ")}`
+                : "the most recent run") +
+            ". Push the branch and open a PR before running `merge --watch`.";
+        if (options.json) {
+            console.log(JSON.stringify({ watch: "blocked", error: message }, null, 2));
+        }
+        else {
+            console.error(ui.errorBox("Watch Blocked", message));
+        }
+        process.exitCode = 2;
+        return true;
+    }
+    // Validated, never NaN — the shared deadline below depends on it (a NaN
+    // deadline would make every per-PR `remaining` NaN and defeat --timeout).
+    const { intervalMs, timeoutMs } = resolveWatchTiming(options);
+    const deadline = Date.now() + timeoutMs;
+    if (unresolved.length > 0 && !options.json) {
+        console.log(colors.muted(`  !  No PR resolved for: ${unresolved.map((i) => `#${i}`).join(", ")} — skipping in watch.`));
+    }
+    for (const { issue, pr } of targets) {
+        if (!options.json) {
+            console.log(colors.muted(`Watching PR #${pr} (issue #${issue})…`));
+        }
+        const remaining = deadline - Date.now();
+        const result = await waitForChecks(pr, {
+            intervalMs,
+            // Share the deadline across PRs so the whole gate honors --timeout.
+            timeoutMs: Math.max(0, remaining),
+            onPoll: options.json
+                ? undefined
+                : (msg) => console.log(colors.muted(`  #${pr}: ${msg}`)),
+        }, gh);
+        if (result.status === "blocked") {
+            const reason = result.reason ?? "CI dispatch is blocked.";
+            if (options.json) {
+                console.log(JSON.stringify({
+                    watch: "blocked",
+                    pr,
+                    issue,
+                    reason,
+                    checkName: result.checkName,
+                }, null, 2));
+            }
+            else {
+                console.log(ui.errorBox("BLOCKED", `PR #${pr} (issue #${issue}) — ${reason}` +
+                    (result.checkName ? `\n\nCheck: ${result.checkName}` : "")));
+            }
+            process.exitCode = 2;
+            return true;
+        }
+        if (result.status === "timeout") {
+            const reason = result.reason ?? "Watch timed out.";
+            if (options.json) {
+                console.log(JSON.stringify({ watch: "timeout", pr, issue, reason }, null, 2));
+            }
+            else {
+                console.error(ui.errorBox("Watch Timed Out", reason));
+            }
+            process.exitCode = EXIT_WATCH_TIMEOUT;
+            return true;
+        }
+        // terminal → this PR is ready to be checked; continue to the next PR.
+        if (!options.json) {
+            console.log(colors.muted(`  #${pr}: all checks terminal after ${result.polls} poll(s).`));
+        }
+    }
+    return false;
+}
 /**
  * Main merge command handler
  */
@@ -51,7 +175,14 @@ export async function mergeCommand(issues, options) {
     if (!options.check && !options.scan && !options.review && !options.all) {
         options.check = true;
     }
-    const repoRoot = getRepoRoot();
+    let repoRoot;
+    try {
+        repoRoot = getRepoRoot();
+    }
+    catch {
+        console.error(colors.error("❌ Not in a git repository. Run merge from inside your project repo."));
+        process.exit(1);
+    }
     const issueNumbers = issues
         .map((i) => parseInt(i, 10))
         .filter((n) => !isNaN(n));
@@ -81,6 +212,27 @@ export async function mergeCommand(issues, options) {
         }
         console.log("");
     }
+    // Watch gate (#818): wait for CI to reach a terminal state before running the
+    // report. Returns true when it has already handled the outcome (dispatch
+    // block, timeout, or no PR to watch) and set the exit code — stop here.
+    if (options.watch) {
+        try {
+            const handled = await runWatchGate(issueNumbers, options, repoRoot);
+            if (handled)
+                return;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (options.json) {
+                console.log(JSON.stringify({ watch: "error", error: message }, null, 2));
+            }
+            else {
+                console.error(ui.errorBox("Watch Failed", message));
+            }
+            process.exitCode = 2;
+            return;
+        }
+    }
     try {
         const report = await runMergeChecks(issueNumbers, options, repoRoot);
         if (options.json) {

package/dist/src/commands/ready-tui-adapter.js

@@ -77,7 +77,12 @@ export class ReadySnapshotAdapter {
                     this.status = "failed";
                 break;
             }
-            case "activity": {
+            // #804: an auto-wait surfaces here the same way activity does — as a
+            // refreshed nowLine on the still-running phase. Sharing one body is
+            // deliberate: a wait must NOT reach the complete/failed case, which
+            // would close out a phase that is merely paused.
+            case "activity":
+            case "waiting": {
                 if (this.currentPhase) {
                     this.currentPhase = {
                         ...this.currentPhase,

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

@@ -14,7 +14,7 @@
  * human / no implementation), persists that state, and emits a structured gap
  * report. See `src/lib/workflow/ready-gate.ts` for the engine.
  */
-import { type ReadyPolicy } from "../lib/settings.js";
+import { type ReadyPolicy, type SequantSettings } from "../lib/settings.js";
 import { type ReadyResult } from "../lib/workflow/ready-gate.js";
 export interface ReadyCommandOptions {
     policy?: string;
@@ -29,8 +29,11 @@ export interface ReadyCommandOptions {
 /**
  * Exit code from a ready result.
  * - 0: ready (awaiting human merge)
- * - 1: not ready — needs human intervention (budget/iterations/stagnation)
- * - 2: not ready — no implementation (#534) or hard error
+ * - 1: not ready — needs human intervention (budget/iterations/stagnation,
+ *      or a NO_VERDICT QA turn (#853): the implementation may exist, so this
+ *      is a re-run case, not the "nothing there" exit)
+ * - 2: not ready — no implementation (#534), uncommitted-only work (#879), or
+ *      hard error. Same class: nothing certifiable exists on the branch.
  */
 export declare function getReadyExitCode(result: ReadyResult): number;
 /**
@@ -40,6 +43,25 @@ export declare function getReadyExitCode(result: ReadyResult): number;
  * @internal Exported for testing only.
  */
 export declare function resolvePolicy(flag: string | undefined, settingsPolicy: ReadyPolicy): ReadyPolicy;
+/**
+ * Resolve the numeric limits for a ready-gate run: CLI → settings → default.
+ *
+ * #833: these previously guarded only the CLI value (`typeof x === "number" &&
+ * x > 0`) and fell straight through to `settings.run.*` unchecked. But
+ * `settings.run.timeout` is user-authored JSON, and `ready`'s value does NOT
+ * pass through `buildExecutionConfig` — `ready-gate.ts`'s `buildPhaseConfig`
+ * assembles its own `ExecutionConfig`. So a `"timeout": 0` in settings.json
+ * reached `setTimeout` as a 0 ms delay and aborted every ready-gate phase on
+ * its first tick, with no warning: the #833 defect, on the path the original
+ * fix did not cover. Chaining `positiveOr` leaves no layer unchecked.
+ *
+ * @internal Exported for testing only.
+ */
+export declare function resolveReadyLimits(options: Pick<ReadyCommandOptions, "maxIterations" | "budget" | "timeout">, settings: Pick<SequantSettings, "run">): {
+    maxIterations: number;
+    tokenBudget: number | undefined;
+    phaseTimeout: number;
+};
 /**
  * Locate the worktree path for an issue from `git worktree list`.
  *

package/dist/src/commands/ready.js

@@ -15,25 +15,32 @@
  * report. See `src/lib/workflow/ready-gate.ts` for the engine.
  */
 import { ui, colors } from "../lib/cli-ui.js";
-import { getSettings } from "../lib/settings.js";
+import { getSettings, } from "../lib/settings.js";
 import { listWorktrees } from "../lib/workflow/worktree-manager.js";
 import { GitHubProvider } from "../lib/workflow/platforms/github.js";
 import { getStateManager } from "../lib/workflow/state-manager.js";
 import { executePhaseWithRetry } from "../lib/workflow/phase-executor.js";
 import { buildProgressWiring } from "./run-progress.js";
 import { ReadySnapshotAdapter } from "./ready-tui-adapter.js";
+import { DEFAULT_CONFIG } from "../lib/workflow/types.js";
+import { positiveOr } from "../lib/workflow/config-resolver.js";
 import { runReadyGate, parseNonGoals, } from "../lib/workflow/ready-gate.js";
 /**
  * Exit code from a ready result.
  * - 0: ready (awaiting human merge)
- * - 1: not ready — needs human intervention (budget/iterations/stagnation)
- * - 2: not ready — no implementation (#534) or hard error
+ * - 1: not ready — needs human intervention (budget/iterations/stagnation,
+ *      or a NO_VERDICT QA turn (#853): the implementation may exist, so this
+ *      is a re-run case, not the "nothing there" exit)
+ * - 2: not ready — no implementation (#534), uncommitted-only work (#879), or
+ *      hard error. Same class: nothing certifiable exists on the branch.
  */
 export function getReadyExitCode(result) {
     if (result.ready)
         return 0;
-    if (result.reason === "NO_IMPLEMENTATION")
+    if (result.reason === "NO_IMPLEMENTATION" ||
+        result.reason === "UNCOMMITTED_ONLY") {
         return 2;
+    }
     return 1;
 }
 /**
@@ -47,6 +54,33 @@ export function resolvePolicy(flag, settingsPolicy) {
         return flag;
     return settingsPolicy;
 }
+/**
+ * Resolve the numeric limits for a ready-gate run: CLI → settings → default.
+ *
+ * #833: these previously guarded only the CLI value (`typeof x === "number" &&
+ * x > 0`) and fell straight through to `settings.run.*` unchecked. But
+ * `settings.run.timeout` is user-authored JSON, and `ready`'s value does NOT
+ * pass through `buildExecutionConfig` — `ready-gate.ts`'s `buildPhaseConfig`
+ * assembles its own `ExecutionConfig`. So a `"timeout": 0` in settings.json
+ * reached `setTimeout` as a 0 ms delay and aborted every ready-gate phase on
+ * its first tick, with no warning: the #833 defect, on the path the original
+ * fix did not cover. Chaining `positiveOr` leaves no layer unchecked.
+ *
+ * @internal Exported for testing only.
+ */
+export function resolveReadyLimits(options, settings) {
+    return {
+        maxIterations: positiveOr(options.maxIterations, positiveOr(settings.run.maxIterations, DEFAULT_CONFIG.maxIterations)),
+        // Budget is genuinely optional — `undefined` means "no budget", not "use a
+        // default" — so it keeps the two-state form rather than chaining.
+        tokenBudget: typeof options.budget === "number" &&
+            Number.isFinite(options.budget) &&
+            options.budget > 0
+            ? options.budget
+            : undefined,
+        phaseTimeout: positiveOr(options.timeout, positiveOr(settings.run.timeout, DEFAULT_CONFIG.phaseTimeout)),
+    };
+}
 /**
  * Locate the worktree path for an issue from `git worktree list`.
  *
@@ -70,15 +104,7 @@ export async function readyCommand(issueArg, options) {
     }
     const settings = await getSettings();
     const policy = resolvePolicy(options.policy, settings.ready.policy);
-    const maxIterations = typeof options.maxIterations === "number" && options.maxIterations > 0
-        ? options.maxIterations
-        : settings.run.maxIterations;
-    const tokenBudget = typeof options.budget === "number" && options.budget > 0
-        ? options.budget
-        : undefined;
-    const phaseTimeout = typeof options.timeout === "number" && options.timeout > 0
-        ? options.timeout
-        : settings.run.timeout;
+    const { maxIterations, tokenBudget, phaseTimeout } = resolveReadyLimits(options, settings);
     const mcp = options.mcp !== false;
     // Resolve the issue's existing worktree (reuses run/state worktree infra).
     const worktreePath = resolveWorktreePath(issueNumber);

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