sequant 2.8.0 → 2.10.0

package/dist/src/lib/workflow/metrics-schema.js

@@ -17,10 +17,19 @@
  */
 import { randomUUID } from "node:crypto";
 import { z } from "zod";
+import { ERROR_CATEGORIES } from "./error-classifier.js";
 /**
  * Outcome of a workflow run
  */
 export const RunOutcomeSchema = z.enum(["success", "partial", "failed"]);
+/**
+ * Bounded-enum classification of the failure that ended a run (#761 AC-7).
+ *
+ * Sourced from `ERROR_CATEGORIES` so the metric can never carry free text —
+ * error *messages* stay excluded per the privacy contract above MetricRunSchema
+ * (they could contain sensitive info); a closed enum cannot.
+ */
+export const FailureCategorySchema = z.enum(ERROR_CATEGORIES);
 /**
  * Available phases (aligned with run-log-schema.ts)
  */
@@ -81,6 +90,12 @@ export const MetricRunSchema = z.object({
     model: z.string(),
     /** CLI flags used (e.g., ["--chain", "--sequential"]) */
     flags: z.array(z.string()),
+    /**
+     * Category of the failure that ended the run (#761 AC-7). Optional and
+     * enum-only; absent on success and on records written before this field
+     * existed (additive — no `version` bump required).
+     */
+    failureCategory: FailureCategorySchema.optional(),
     /** Aggregate metrics */
     metrics: RunMetricsSchema,
 });
@@ -121,6 +136,7 @@ export function createMetricRun(options) {
         duration: options.duration,
         model: options.model ?? "unknown",
         flags: options.flags ?? [],
+        failureCategory: options.failureCategory,
         metrics: {
             tokensUsed: options.metrics?.tokensUsed ?? 0,
             filesChanged: options.metrics?.filesChanged ?? 0,

package/dist/src/lib/workflow/metrics-writer.d.ts

@@ -20,7 +20,7 @@
  * });
  * ```
  */
-import { type Metrics, type MetricRun, type MetricPhase, type RunOutcome, type RunMetrics } from "./metrics-schema.js";
+import { type Metrics, type MetricRun, type MetricPhase, type RunOutcome, type RunMetrics, type FailureCategory } from "./metrics-schema.js";
 export interface MetricsWriterOptions {
     /** Path to metrics file (default: .sequant/metrics.json) */
     metricsPath?: string;
@@ -69,6 +69,7 @@ export declare class MetricsWriter {
         duration: number;
         model?: string;
         flags?: string[];
+        failureCategory?: FailureCategory;
         metrics?: Partial<RunMetrics>;
     }): Promise<MetricRun>;
     /**

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

@@ -11,6 +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 { 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
@@ -35,7 +36,181 @@ export declare function createThrottledReporter(fn: (text: string) => void, inte
 export declare const SPEC_RETRY_BACKOFF_MS: number;
 /** @internal Exported for testing only */
 export declare const SPEC_EXTRA_RETRIES: number;
+/**
+ * A rate limit whose window resets further out than this is treated as
+ * exhausted rather than transient (#761 AC-2): no retry can succeed inside a
+ * closed window, so consuming cold-start retries (each burning up to a full
+ * `phaseTimeout`) only delays the labeled halt. Five minutes comfortably
+ * exceeds any backoff this executor performs while staying far below the
+ * five-hour/seven-day windows the check exists to catch.
+ *
+ * @internal Exported for testing only
+ */
+export declare const RATE_LIMIT_WINDOW_SKIP_THRESHOLD_MS: number;
+/**
+ * Base backoff for transient rate-limit retries (#761 AC-4), doubled per
+ * attempt (5s, 10s). Same scale as `SPEC_RETRY_BACKOFF_MS` — long enough to
+ * outlive a momentary throttle, short enough to be negligible next to a
+ * phase's runtime.
+ *
+ * @internal Exported for testing only
+ */
+export declare const RATE_LIMIT_RETRY_BACKOFF_MS = 5000;
+/**
+ * True when a failure is a rate limit whose reset lies beyond
+ * {@link RATE_LIMIT_WINDOW_SKIP_THRESHOLD_MS} — i.e. window exhaustion, not a
+ * transient throttle. Metadata-absent rate limits (the assistant-error channel
+ * carries no `resetsAt`, see #761 AC-9) return false and fall through to the
+ * transient path: with no timing signal, retry-with-backoff is the safe
+ * default, skipping all retries is not.
+ *
+ * @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).
  *
@@ -77,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).
+ *
+ * - `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 the
- * exec phase produced nothing, reintroducing the bug #534 is fixing.
+ * 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`).
+ *
+ * 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.
  *
- * 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.
+ * 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.
  */
@@ -163,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;
 }>;