sequant 2.9.0 → 2.11.0

package/dist/src/lib/workflow/batch-executor.d.ts

@@ -7,6 +7,7 @@
  * (including quality-loop retries, checkpoint commits, rebasing, and PR
  * creation).
  */
+import { LogWriter } from "./log-writer.js";
 import { ExecutionConfig, PhaseResult, IssueResult, type RunOptions, type IssueExecutionContext, type BatchExecutionContext, type ProgressCallback } from "./types.js";
 import { type ErrorCategory } from "./error-classifier.js";
 export type { RunOptions, ProgressCallback, IssueExecutionContext, BatchExecutionContext, } from "./types.js";
@@ -21,15 +22,32 @@ export type { RunOptions, ProgressCallback, IssueExecutionContext, BatchExecutio
  * @param extra - Optional fields: durationSeconds (on complete), error (on failed)
  */
 /**
- * Wrap an `ExecutionConfig` with an `onActivity` hook that re-emits each
- * agent-output ping as a `"activity"` progress event for the dashboard (#543).
+ * Wrap an `ExecutionConfig` with the runtime liveness hooks:
+ * - `onActivity` — re-emits each agent-output ping as an `"activity"` progress
+ *   event for the dashboard (#543).
+ * - `onAutoWait` — re-emits each auto-wait tick as a `"waiting"` progress
+ *   event so the renderer and heartbeat can show the pause and its wake time
+ *   (#804 AC-7). Under `SEQUANT_ORCHESTRATOR` it additionally emits throttled
+ *   `SEQUANT_PROGRESS` waiting lines (#860): an MCP-driven wait was previously
+ *   invisible on the JSON channel — indistinguishable from a hang — AND was
+ *   killed by the MCP inactivity timeout, which resets on progress lines.
+ *   Optionally notifies `onWaitTransition` on wait start/end so the caller
+ *   can persist the wait to issue state (`sequant status` truthfulness).
  *
- * Returns the input config unchanged when no `onProgress` callback is set,
- * so non-TUI runs pay no overhead.
+ * Returns the input config unchanged when there is no consumer at all (no
+ * `onProgress`, no orchestrator channel, no transition callback), so plain
+ * non-TUI runs pay no overhead.
  *
  * @internal Exported for testing only
  */
-export declare function withActivityHook(base: ExecutionConfig, issueNumber: number, phase: string, onProgress: ProgressCallback | undefined): ExecutionConfig;
+export declare function withActivityHook(base: ExecutionConfig, issueNumber: number, phase: string, onProgress: ProgressCallback | undefined, onWaitTransition?: (wakeAtMs: number | null) => void): ExecutionConfig;
+/**
+ * Cadence of orchestrator-channel waiting lines during an auto-wait (#860).
+ * See {@link withActivityHook}.
+ *
+ * @internal Exported for testing only
+ */
+export declare const AUTO_WAIT_PROGRESS_LINE_INTERVAL_MS = 60000;
 /**
  * Build enriched prompt context for the /loop phase from a failed phase result (#488).
  * Passes QA verdict, failed ACs, and error directly so the /loop skill doesn't need
@@ -38,10 +56,12 @@ export declare function withActivityHook(base: ExecutionConfig, issueNumber: num
  * @internal Exported for testing only
  */
 export declare function buildLoopContext(failedResult: PhaseResult): string;
-export declare function emitProgressLine(issue: number, phase: string, event?: "start" | "complete" | "failed", extra?: {
+export declare function emitProgressLine(issue: number, phase: string, event?: "start" | "complete" | "failed" | "waiting", extra?: {
     durationSeconds?: number;
     error?: string;
     iteration?: number;
+    wakeAtMs?: number;
+    remainingMs?: number;
 }): void;
 /**
  * Emit the current run's UUID on stderr so MCP callers can look up the exact
@@ -73,6 +93,32 @@ export declare function parseBatches(batchArgs: string[]): number[][];
  * Parse environment variables for CI configuration
  */
 export declare function getEnvConfig(): Partial<RunOptions>;
+/**
+ * Record an issue's completion in the run log in ONE place (#879): PR info, the
+ * PR-failure status flip, then finalize. Extracted so every batch loop shares a
+ * single completion sequence and cannot drift.
+ *
+ * The #879 defect was exactly such a drift: `markIssueFailed` was wired into
+ * `executeBatch`'s loop, but the live `sequant run` path is
+ * `RunOrchestrator.executeOneIssue`, which called `setPRInfo` + `completeIssue`
+ * without it — so a real run left the run-log status at `success` on a
+ * PR-creation failure. Both call sites now go through this helper.
+ *
+ * A PR-creation failure occurs after every phase has been logged, so
+ * `deriveIssueLogStatus` (last run at phase-log time) leaves the issue at
+ * `success`; the flip here is what counts it under `failed`. Safe post-hoc:
+ * no further phase is logged before `completeIssue`.
+ */
+export declare function recordIssueCompletion(logWriter: LogWriter, result: IssueResult, issueNumber?: number): void;
+/**
+ * @deprecated No live caller — `sequant run` executes issues via
+ * `RunOrchestrator.executeOneIssue`; this survives only as a
+ * `commands/run-compat` re-export. Do not build a new execution loop on it:
+ * any path that completes an issue MUST go through
+ * {@link recordIssueCompletion}, or the #879 status-drift returns (a
+ * completion path that skips the PR-failure flip logs a failed issue as
+ * `success`). Slated for removal with the run-compat surface.
+ */
 export declare function executeBatch(issueNumbers: number[], batchCtx: BatchExecutionContext): Promise<IssueResult[]>;
 /**
  * Derive the bounded-enum failure category for a failed issue (#761 AC-7).
@@ -86,4 +132,77 @@ export declare function executeBatch(issueNumbers: number[], batchCtx: BatchExec
  * @internal Exported for testing
  */
 export declare function deriveFailureCategory(phaseResults: PhaseResult[]): ErrorCategory | undefined;
+/**
+ * "Halt, don't loop" predicate for the outer `-Q` quality loop (#799).
+ *
+ * A billing / out-of-credits failure (`BillingError`) or a window-exhausted
+ * rate limit (reset hours away, per `isWindowExhaustedRateLimit`) cannot be
+ * recovered by re-running the phase — every retry re-spawns into the same
+ * closed window and, worse, mislabels the halt as a downstream
+ * `QA completed without a parseable verdict`. Mirrors the `haltedByCap` (#739)
+ * treatment: surface the real cause and halt so the user resumes once credits
+ * or the rate-limit window are restored.
+ *
+ * A transient / metadata-absent rate limit is NOT a halt: it returns false and
+ * keeps today's outer-loop behavior (the inner retry ladder in `phase-executor`
+ * handles its backoff, per #761 AC-4/AC-9).
+ *
+ * @internal Exported for testing
+ */
+export declare function isBillingOrWindowHalt(result: PhaseResult): boolean;
+/**
+ * The billing half of {@link isBillingOrWindowHalt} (#804 AC-8).
+ *
+ * Split out because the two causes stopped being interchangeable once
+ * `--auto-wait` existed: a closed window can now reopen on its own, while
+ * out-of-credits cannot — credits are purchased, not waited out. Callers that
+ * need to reason about recoverability must be able to tell them apart.
+ *
+ * @internal Exported for testing
+ */
+export declare function isBillingHalt(result: PhaseResult): boolean;
+/**
+ * The rate-limit-window half of {@link isBillingOrWindowHalt} (#804 AC-8).
+ *
+ * NOTE — this predicate needed no behavioral change for auto-wait, and that is
+ * a deliberate finding rather than an oversight. AC-8 anticipated that a phase
+ * which waits and then succeeds would still halt the `-Q` loop. It cannot:
+ * every call site (`:~700` spec, `:~1030` progress label, `:~1150` halt flag)
+ * sits inside the `else` of an `if (result.success)`, so a successful
+ * post-wait result never reaches this predicate at all. When auto-wait does
+ * NOT fire — the default, an exhausted budget, or a spent wait bound — the
+ * result is still a failure carrying a window-exhausted `RateLimitError`, and
+ * halting is then the correct outcome (#799 behavior, preserved exactly).
+ *
+ * @internal Exported for testing
+ */
+export declare function isWindowHalt(result: PhaseResult): boolean;
+/**
+ * Human-readable halt reason for a billing / rate-limit-window failure (#799
+ * AC-3). Surfaces the driver's real cause verbatim — `result.error` is already
+ * the well-formatted message the driver built via `formatRateLimitMessage`
+ * (`Out of credits` for billing, `Rate limited — resets at <local time>` for a
+ * throttle with a known reset), so the phase-failed line and run summary name
+ * the actual cause instead of a downstream `QA completed without a parseable
+ * verdict`.
+ *
+ * Do NOT re-append `resetsAt` here: the rate-limit message already carries the
+ * reset time, and doing so produced a doubled, timezone-inconsistent string
+ * (`… resets at 07-24 14:32 — resets at 2026-…Z`). Credits failures carry no
+ * reset time by design (they need purchasing, not a window wait).
+ *
+ * @internal Exported for testing
+ */
+export declare function billingHaltReason(result: PhaseResult): string;
+/**
+ * Epoch ms after which a waitable-window halt can be re-entered (#892 AC-1):
+ * the window's `resetsAt` normalized to ms plus the same buffer auto-wait
+ * applies (`AUTO_WAIT_BUFFER_MS`), so in-process waits and durable halts wake
+ * on the same clock. Returns `null` when the result carries no future-reset
+ * rate-limit window — callers must then skip the `windowHalt` write rather
+ * than invent a resume time.
+ *
+ * @internal Exported for testing
+ */
+export declare function windowHaltResumeAtMs(result: PhaseResult): number | null;
 export declare function runIssueWithLogging(ctx: IssueExecutionContext): Promise<IssueResult>;