sequant 2.9.0 → 2.10.0

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

@@ -11,7 +11,7 @@ import { ShutdownManager } from "../shutdown.js";
 import { Phase, ExecutionConfig, PhaseResult, QaVerdict, PhasePauseHandle } from "./types.js";
 import type { QaSummary } from "./run-log-schema.js";
 import type { AgentPhaseResult, ResumeHandle } from "./drivers/index.js";
-import { SequantError } from "../errors.js";
+import { RateLimitError, SequantError } from "../errors.js";
 /**
  * Leading + trailing throttle. Fires the wrapped callback immediately on the
  * first call, drops subsequent calls that arrive inside `intervalMs` but
@@ -67,7 +67,150 @@ export declare const RATE_LIMIT_RETRY_BACKOFF_MS = 5000;
  * @internal Exported for testing only
  */
 export declare function isWindowExhaustedRateLimit(error: SequantError | undefined, now?: number): boolean;
+/**
+ * Buffer added to a rate-limit reset before waking (#804 AC-5). `resetsAt` is a
+ * floor, not an exact moment: clock skew between this host and the API, plus
+ * server-side rounding, otherwise produce an immediate second rejection on
+ * wake. One minute is negligible against the five-hour/seven-day windows this
+ * exists for.
+ *
+ * @internal Exported for testing only
+ */
+export declare const AUTO_WAIT_BUFFER_MS: number;
+/**
+ * Hard cap on auto-waits per issue (#804 AC-6), independent of the minutes
+ * budget. A window that is still closed on wake must not produce an unbounded
+ * pause loop, so the count bounds the *number* of pauses while
+ * `autoWaitMinutes` bounds their *total duration*. Either bound being spent
+ * halts with today's labeled message.
+ *
+ * @internal Exported for testing only
+ */
+export declare const AUTO_WAIT_MAX_WAITS = 2;
+/**
+ * Granularity of the auto-wait sleep (#804 AC-7). The wait is performed as a
+ * series of ticks rather than one multi-hour `delayFn` call so that (a) the
+ * renderer/heartbeat can be refreshed with the remaining time, and (b) a
+ * Ctrl-C is observed promptly instead of at the wake time.
+ *
+ * @internal Exported for testing only
+ */
+export declare const AUTO_WAIT_TICK_MS: number;
+/**
+ * Mutable per-issue accounting for auto-wait (#804 AC-6).
+ *
+ * Deliberately per-ISSUE, not per-phase: `executePhaseWithRetry` runs once per
+ * phase, so a ledger created inside it would grant every phase its own full
+ * budget and bound. `runIssueWithLogging` creates one and threads it through
+ * all of an issue's phases.
+ */
+export interface AutoWaitLedger {
+    /** Total wait budget in ms. `0` disables auto-wait entirely. */
+    budgetMs: number;
+    /** Number of waits already granted for this issue. */
+    waits: number;
+    /** Cumulative ms already spent waiting for this issue. */
+    spentMs: number;
+}
+/**
+ * Build a fresh ledger from a minutes budget. A missing, negative or
+ * non-finite budget yields a disabled ledger (`budgetMs: 0`) — the default,
+ * which preserves pre-#804 behavior exactly.
+ */
+export declare function createAutoWaitLedger(budgetMinutes?: number): AutoWaitLedger;
+/**
+ * A granted auto-wait: how long to sleep, when to wake, and the narrowed
+ * rate-limit error that justified it (carried so callers need no cast).
+ */
+export interface AutoWaitDecision {
+    /** Ms to sleep. Always > 0. */
+    waitMs: number;
+    /** Epoch ms to wake at — `resetsAt` normalized to ms, plus the buffer. */
+    wakeAtMs: number;
+    /** The rate limit that triggered the wait. Never a `BillingError`. */
+    error: RateLimitError;
+}
+/**
+ * Decide whether to wait out an exhausted rate-limit window (#804 AC-3).
+ *
+ * Deliberately separate from {@link isWindowExhaustedRateLimit} and
+ * {@link RATE_LIMIT_WINDOW_SKIP_THRESHOLD_MS}, which answer *"is this transient
+ * or exhausted?"*. This answers a different question — *"am I willing to wait
+ * that long?"* — and fires ONLY once the former is already true. Keeping them
+ * apart is what leaves `autoWaitMinutes` the single user-facing dial for the
+ * wait-vs-halt outcome.
+ *
+ * Returns `null` (no wait — halt as before) when:
+ * - auto-wait is off, or the per-issue wait count is spent;
+ * - the failure is not a window-exhausted `RateLimitError`. A `BillingError`
+ *   lands here: it is a sibling class, not a subclass, so the `instanceof`
+ *   check inside `isWindowExhaustedRateLimit` excludes it. That is load-bearing
+ *   — a `BillingError` may still carry `resetsAt` (an explicit
+ *   `credits_required`, or a window that has already passed — see the #860
+ *   narrowing in `isBillingFailure`), so gating on the timestamp's presence
+ *   instead of the error type would wait out a credits failure that no amount
+ *   of waiting can heal (AC-4). Since #860, a *live* recognized window
+ *   (`five_hour`/`seven_day*` + future reset) classifies as `RateLimitError`
+ *   upstream even when `out_of_credits` is present, which is what lets the
+ *   real captured subscription payloads reach this decision at all;
+ * - the reset has already passed (nothing to wait for);
+ * - the required wait exceeds the budget REMAINING, not the total (AC-6).
+ *
+ * @internal Exported for testing only
+ */
+export declare function shouldAutoWaitForReset(error: SequantError | undefined, ledger: AutoWaitLedger, now?: number): AutoWaitDecision | null;
+/**
+ * Sleep until an auto-wait's wake time, in ticks (#804 AC-7).
+ *
+ * Chunking the sleep is what makes a multi-hour pause survivable:
+ * - `onTick` refreshes the live display so the wait is visible rather than a
+ *   silent stall (the #574 complaint at 60x scale);
+ * - each tick races the injected `delayFn` against the abort signal, so Ctrl-C
+ *   returns immediately instead of blocking until the wake.
+ *
+ * Reuses the caller's `delayFn` so the wait stays fully test-injectable.
+ *
+ * Returns the ms actually slept and whether the wait was aborted.
+ *
+ * @internal Exported for testing only
+ */
+export declare function waitForWindowReset(waitMs: number, options: {
+    delayFn: (ms: number) => Promise<void>;
+    signal?: AbortSignal;
+    onTick?: (remainingMs: number) => void;
+    now?: () => number;
+    tickMs?: number;
+}): Promise<{
+    sleptMs: number;
+    aborted: boolean;
+}>;
+/**
+ * Run one granted auto-wait end to end (#804): emit the live notices, sleep,
+ * update the ledger, and report whether Ctrl-C interrupted it.
+ *
+ * Shared by both arms of the retry ladder (the cold-start loop and the
+ * `skipColdStartRetry` single-attempt path) so the two cannot drift on
+ * bookkeeping or messaging.
+ *
+ * @internal Exported for testing only
+ */
+export declare function performAutoWait(issueNumber: number, phase: Phase, config: ExecutionConfig, decision: AutoWaitDecision, ledger: AutoWaitLedger, delayFn: (ms: number) => Promise<void>, shutdownManager?: ShutdownManager, spinner?: PhasePauseHandle): Promise<{
+    aborted: boolean;
+}>;
 export declare function parseQaVerdict(output: string): QaVerdict | null;
+/**
+ * Distinguish a QA turn that produced *no verdict at all* from one whose output
+ * was present but unparseable (#853). Returns true when the output is empty /
+ * whitespace, or when its tail contains deferral language — the agent treating
+ * its one-shot phase as if a later turn were available.
+ *
+ * Both cases are hard failures either way; this only refines which message is
+ * emitted, so a false positive is harmless (it swaps one failing message for
+ * another). Kept deliberately conservative and literal to stay ReDoS-safe.
+ *
+ * @internal Exported for testing only.
+ */
+export declare function endedWithoutVerdict(output: string | undefined): boolean;
 /**
  * Parse condensed QA summary from QA phase output (#434).
  *
@@ -109,22 +252,59 @@ export declare function formatDuration(seconds: number): string;
  */
 export declare function resolveBaseRef(cwd: string): string;
 /**
- * Check whether the exec phase produced any changes in the worktree.
- * Returns true if HEAD has commits unique to it relative to the resolved
- * base ref (see {@link resolveBaseRef}) OR uncommitted work is present.
+ * Three-way classification of what the exec phase left in the worktree (#879).
  *
- * Uses `git rev-list --count <base>..HEAD` (commits reachable from HEAD
- * but not the base) instead of `git diff <base>..HEAD`, because the
- * two-dot diff also fires in reverse when the base has advanced past HEAD
- * — on stale branches that would falsely report "has commits" even when the
- * exec phase produced nothing, reintroducing the bug #534 is fixing.
+ * - `commits`: HEAD has commits unique to it relative to the base ref — real,
+ *   deliverable work that can rebase, push, and become a PR.
+ * - `uncommitted`: no such commits, but the tree is dirty. This is NOT a
+ *   deliverable: uncommitted work cannot rebase, push, or become a PR (#879's
+ *   defect — a dirty tree used to be counted as exec success, producing a run
+ *   that "passed" with no commits and no PR). `paths` names the dirty files.
+ * - `none`: no commits and a clean tree — exec produced literally nothing
+ *   (#534's original empty-branch class).
+ * - `unknown`: a git command failed. Callers fail OPEN on this (treat as work)
+ *   — a transient git error is better diagnosed as a real run than as a
+ *   spurious phase failure on every exec.
+ */
+export type ExecChangeState = {
+    kind: "commits";
+} | {
+    kind: "uncommitted";
+    paths: string[];
+} | {
+    kind: "none";
+} | {
+    kind: "unknown";
+};
+/**
+ * Classify what the exec phase produced in the worktree (#879).
+ *
+ * Uses `git rev-list --count <base>..HEAD` (commits reachable from HEAD but not
+ * the base) instead of `git diff <base>..HEAD`, because the two-dot diff also
+ * fires in reverse when the base has advanced past HEAD — on stale branches
+ * that would falsely report "has commits" even when exec produced nothing,
+ * reintroducing the bug #534 is fixing.
  *
  * The base ref defaults to `origin/main` but is overridden to the worktree's
- * recorded base (see #537) so zero-diff execs are still detected on
- * custom-base worktrees (e.g. those created with `--base feature/epic`).
+ * recorded base (see #537) so zero-diff execs are still detected on custom-base
+ * worktrees (e.g. those created with `--base feature/epic`).
  *
- * Fails open (returns true) on git errors — a missing origin ref is better
- * diagnosed as a real zero-diff run than as a false phase failure.
+ * Read-only: runs only `git rev-list` and `git status --porcelain`, so it never
+ * mutates the worktree — an exec phase that fails on an `uncommitted` result
+ * leaves the dirty files exactly where the agent left them (#879 AC-3).
+ *
+ * @internal Exported for testing only.
+ */
+export declare function classifyExecChanges(cwd: string): ExecChangeState;
+/**
+ * Check whether the exec phase produced deliverable work in the worktree.
+ *
+ * Thin boolean wrapper over {@link classifyExecChanges}: only `commits` (real
+ * work) and `unknown` (git error — fail open) count as "has changes". Note the
+ * #879 behaviour change: an `uncommitted`-only tree now returns **false**, since
+ * uncommitted work is not a deliverable. Both callers (the exec guard in
+ * {@link mapAgentSuccessToPhaseResult} and the ready gate) want this stricter
+ * semantics.
  *
  * @internal Exported for testing only.
  */
@@ -195,7 +375,16 @@ export declare function executePhaseWithRetry(issueNumber: number, phase: Phase,
 /** @internal Injected for testing — defaults to module-level executePhase */
 executePhaseFn?: typeof executePhase, 
 /** @internal Injected for testing — defaults to setTimeout-based delay */
-delayFn?: (ms: number) => Promise<void>): Promise<PhaseResult & {
+delayFn?: (ms: number) => Promise<void>, 
+/**
+ * Per-issue auto-wait accounting (#804). Deliberately the LAST parameter:
+ * the #761/#799 regression tests call this function positionally with
+ * `executePhaseFn` at 8 and `delayFn` at 9, and AC-2 requires those tests to
+ * pass unmodified. Defaults to a fresh disabled-or-config-derived ledger, so
+ * a caller that does not thread one still gets correct (bounded) behavior —
+ * just scoped to this phase rather than the issue.
+ */
+autoWaitLedger?: AutoWaitLedger): Promise<PhaseResult & {
     sessionId?: string;
     resumeHandle?: ResumeHandle;
 }>;