sequant 2.8.0 → 2.10.0

package/dist/src/lib/ci/outputs.js

@@ -18,10 +18,17 @@ export function formatOutputs(result) {
 }
 /**
  * Format multiple issue results into combined outputs.
+ *
+ * @param wallClockDurationSeconds - The run's wall-clock duration, computed by
+ * whoever brackets the run (the orchestrator surfaces it as
+ * `RunResult.wallClockDurationSeconds`). It is a required argument rather than
+ * something derived here because the per-issue durations this function receives
+ * cannot express it: under `--parallel` they overlap, so summing them
+ * double-counts and over-reports by roughly the concurrency factor (#867).
  */
-export function formatMultiOutputs(results) {
+export function formatMultiOutputs(results, wallClockDurationSeconds) {
     const allSuccess = results.every((r) => r.success);
-    const totalDuration = results.reduce((sum, r) => sum + (r.durationSeconds ?? 0), 0);
+    const totalDuration = wallClockDurationSeconds;
     const prUrls = results
         .map((r) => r.prUrl)
         .filter(Boolean)
@@ -54,8 +61,14 @@ export function outputCommands(outputs) {
 }
 /**
  * Generate a GitHub Actions step summary (Markdown).
+ *
+ * @param wallClockDurationSeconds - The run's wall-clock duration. Required for
+ * the same reason as in {@link formatMultiOutputs}: the per-issue durations
+ * below overlap under `--parallel`, so the "Total duration" line cannot be
+ * derived by summing them (#867). Per-*phase* durations in the tables are
+ * unaffected — phases within an issue run sequentially.
  */
-export function formatSummary(results) {
+export function formatSummary(results, wallClockDurationSeconds) {
     const lines = [];
     lines.push("## Sequant Workflow Results\n");
     for (const result of results) {
@@ -78,7 +91,6 @@ export function formatSummary(results) {
         }
         lines.push("");
     }
-    const total = results.reduce((sum, r) => sum + (r.durationSeconds ?? 0), 0);
-    lines.push(`**Total duration:** ${total}s`);
+    lines.push(`**Total duration:** ${wallClockDurationSeconds}s`);
     return lines.join("\n");
 }

package/dist/src/lib/cli-flags.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Commander argument coercions for numeric CLI flags.
+ *
+ * Lives here rather than inline in `bin/cli.ts` so it can be unit-tested
+ * directly — `bin/cli.ts` calls `program.parse()` at import time and cannot be
+ * imported from a test.
+ *
+ * @module
+ */
+/** Error-text shaping for a numeric flag. Affects messages only, not parsing. */
+export interface WholeNumberOptions {
+    /** Smallest accepted value. Use 0 where 0 is a meaningful "off" setting. */
+    min: number;
+    /** Plural unit, e.g. `"seconds"`. Omit for a flag that reads better bare. */
+    unit?: string;
+    /** Singular unit, used when `min` is 1 ("at least 1 second"). */
+    unitSingular?: string;
+}
+/**
+ * Build a commander coercion for a whole-number flag.
+ *
+ * A bare `parseInt` is unsafe for these: `parseInt("abc", 10)` is `NaN`, which
+ * is not nullish and so survives a `?? default`, and `parseInt("30m", 10)`
+ * silently yields `30` — the user asked for 30 minutes and got 30 seconds.
+ * Requiring the whole string to be digits rejects both instead of accepting a
+ * value that is unusable or quietly wrong (#818, #833).
+ */
+export declare function parseWholeNumber(flag: string, opts: WholeNumberOptions): (value: string) => number;
+/**
+ * A positive-integer *seconds* flag — the #831 shape, preserved verbatim so the
+ * `merge --watch` messages this originally shipped with do not change.
+ */
+export declare function parsePositiveSeconds(flag: string): (value: string) => number;

package/dist/src/lib/cli-flags.js

@@ -0,0 +1,46 @@
+/**
+ * Commander argument coercions for numeric CLI flags.
+ *
+ * Lives here rather than inline in `bin/cli.ts` so it can be unit-tested
+ * directly — `bin/cli.ts` calls `program.parse()` at import time and cannot be
+ * imported from a test.
+ *
+ * @module
+ */
+import { InvalidArgumentError } from "commander";
+/**
+ * Build a commander coercion for a whole-number flag.
+ *
+ * A bare `parseInt` is unsafe for these: `parseInt("abc", 10)` is `NaN`, which
+ * is not nullish and so survives a `?? default`, and `parseInt("30m", 10)`
+ * silently yields `30` — the user asked for 30 minutes and got 30 seconds.
+ * Requiring the whole string to be digits rejects both instead of accepting a
+ * value that is unusable or quietly wrong (#818, #833).
+ */
+export function parseWholeNumber(flag, opts) {
+    const { min, unit, unitSingular } = opts;
+    const ofUnit = unit ? ` of ${unit}` : "";
+    const minUnit = min === 1 ? (unitSingular ?? unit) : unit;
+    const minSuffix = minUnit ? ` ${minUnit}` : "";
+    return (value) => {
+        if (!/^\d+$/.test(value.trim())) {
+            throw new InvalidArgumentError(`${flag} expects a whole number${ofUnit} (got '${value}').`);
+        }
+        const parsed = Number(value);
+        if (!Number.isSafeInteger(parsed) || parsed < min) {
+            throw new InvalidArgumentError(`${flag} must be at least ${min}${minSuffix} (got '${value}').`);
+        }
+        return parsed;
+    };
+}
+/**
+ * A positive-integer *seconds* flag — the #831 shape, preserved verbatim so the
+ * `merge --watch` messages this originally shipped with do not change.
+ */
+export function parsePositiveSeconds(flag) {
+    return parseWholeNumber(flag, {
+        min: 1,
+        unit: "seconds",
+        unitSingular: "second",
+    });
+}

package/dist/src/lib/cli-ui/run-renderer-types.d.ts

@@ -4,7 +4,7 @@
  * The renderer is event-driven: a `ProgressEvent` flows in and the renderer
  * decides whether to update the live zone, append an event line, or both.
  */
-export type ProgressEventKind = "start" | "complete" | "failed";
+export type ProgressEventKind = "start" | "complete" | "failed" | "waiting";
 /** Raw event from batch-executor `emitProgressLine` / `onProgress` callbacks. */
 export interface ProgressEvent {
     issue: number;
@@ -19,15 +19,34 @@ export interface ProgressEvent {
      * cell as `loop N/M` (#624 Item 3).
      */
     iteration?: number;
+    /**
+     * `"waiting"` (#804): display message for an in-progress auto-wait.
+     */
+    text?: string;
+    /**
+     * `"waiting"` (#804): epoch ms at which the auto-wait ends. Absent on the
+     * terminal notice, which returns the phase to `running`.
+     */
+    wakeAtMs?: number;
 }
 /** Per-phase status tracked inside the renderer state machine. */
 export interface PhaseState {
     name: string;
-    status: "pending" | "running" | "done" | "failed";
+    /**
+     * `"waiting"` (#804) is a *paused* running phase, not a terminal state: the
+     * phase spawn has failed on an exhausted rate-limit window and the executor
+     * is sleeping until it reopens. It returns to `"running"` on wake.
+     */
+    status: "pending" | "running" | "done" | "failed" | "waiting";
     startedAt?: number;
     durationMs?: number;
     /** Loop iteration label (e.g. "loop 2/3"). */
     loopIteration?: number;
+    /**
+     * #804: epoch ms at which an in-progress auto-wait ends. Set only while
+     * `status === "waiting"`; cleared on resume.
+     */
+    wakeAtMs?: number;
     /**
      * #624 Item 4: normalized signature of the most recent failure for THIS
      * phase (ANSI-stripped, lowercased, first 80 chars, trimmed). Per-phase so
@@ -191,11 +210,6 @@ export interface RenderOptions {
      * tracks the configured maximum instead of being hardcoded. Defaults to 3.
      */
     maxLoopIterations?: number;
-    /**
-     * When true, `renderSummary` is rendered even if no issues were registered.
-     * Default: false (matches existing displaySummary behaviour).
-     */
-    alwaysRenderSummary?: boolean;
     /**
      * #647: inject a `log-update` instance (typically built via
      * `createLogUpdate(stream)` against a custom stream). Used by the

package/dist/src/lib/cli-ui/run-renderer.d.ts

@@ -88,6 +88,8 @@ export declare class NonTTYRenderer extends BaseRenderer {
     private readonly columnsOverride?;
     private readonly maxLoopIterations;
     private lastEventAt;
+    /** #860 AC-6: `issue:phase` keys whose auto-wait start line was emitted. */
+    private readonly announcedWaits;
     constructor(options: RenderOptions);
     private getColumns;
     private startHeartbeat;
@@ -95,6 +97,14 @@ export declare class NonTTYRenderer extends BaseRenderer {
     tickHeartbeatNow(): void;
     private tickHeartbeat;
     protected afterEvent(event: ProgressEvent, state: IssueState): void;
+    /**
+     * Announce auto-wait transitions (#860 AC-6). Only the first notice of a
+     * wait and the terminal notice that ends it produce lines — the ~15s ticks
+     * in between are absorbed here (the periodic signal is `tickHeartbeat`).
+     * Before this, waiting events fell through `emitEventLine`'s failure branch
+     * and printed a spurious `✘` line per tick.
+     */
+    private emitWaitTransitionLine;
     private emitEventLine;
     /** Append a single `\n`-terminated line with `[HH:MM:SS]` prefix. */
     private emitLine;

package/dist/src/lib/cli-ui/run-renderer.js

@@ -19,6 +19,8 @@ import chalk from "chalk";
 import logUpdate from "log-update";
 import stringWidth from "string-width";
 import { formatElapsedTime, formatTimestamp } from "./format.js";
+import { formatResetTime } from "../errors.js";
+import { pipelineHasFailed } from "../workflow/status-derivation.js";
 const DEFAULT_LIVE_TICK_MS = 1000;
 const DEFAULT_NON_TTY_HEARTBEAT_MS = 60_000;
 const NARROW_TERMINAL_THRESHOLD = 80;
@@ -228,6 +230,23 @@ class BaseRenderer {
             state.subStatus = undefined;
             return;
         }
+        // #804 AC-7: an auto-wait pauses a phase rather than ending it. Presence of
+        // `wakeAtMs` distinguishes an in-progress wait from the terminal notice
+        // that resumes it, so the live zone never strands a "waiting" cell.
+        if (event.event === "waiting") {
+            if (event.wakeAtMs !== undefined) {
+                phase.status = "waiting";
+                phase.wakeAtMs = event.wakeAtMs;
+                state.subStatus = event.text;
+            }
+            else {
+                if (phase.status === "waiting")
+                    phase.status = "running";
+                phase.wakeAtMs = undefined;
+                state.subStatus = undefined;
+            }
+            return;
+        }
         if (event.event === "complete") {
             phase.status = "done";
             if (event.durationSeconds !== undefined) {
@@ -248,8 +267,13 @@ class BaseRenderer {
         else if (phase.startedAt !== undefined) {
             phase.durationMs = this.now() - phase.startedAt;
         }
-        state.status = "failed";
-        state.completedAt = this.now();
+        // #766: derive from the phase slots (loop excluded) instead of pinning
+        // `failed`, so a loop failure on an early quality-loop iteration doesn't
+        // stick after a later iteration recovers. Mirrors the orchestrator's card.
+        const nowFailed = pipelineHasFailed(state.phases);
+        state.status = nowFailed ? "failed" : "running";
+        if (nowFailed)
+            state.completedAt = this.now();
         state.currentPhase = undefined;
         if (event.error !== undefined)
             state.failureReason = event.error;
@@ -267,20 +291,22 @@ class BaseRenderer {
     }
     /** Mark an issue done after PR is recorded — derived from phase completion. */
     maybeMarkIssueDone(state) {
-        if (state.status === "failed")
-            return;
         const allTerminal = state.phases.every((p) => p.status === "done" || p.status === "failed");
         if (allTerminal && state.phases.length > 0) {
-            state.status = state.phases.some((p) => p.status === "failed")
-                ? "failed"
-                : "done";
+            // #766: derive the verdict (loop excluded) so a run that failed the loop
+            // on an early iteration and then recovered every planned phase resolves
+            // to `done`. No early `failed` guard: a stale loop failure must be able
+            // to de-escalate once the pipeline recovers.
+            state.status = pipelineHasFailed(state.phases) ? "failed" : "done";
             state.completedAt = this.now();
         }
     }
     // ------------ Hooks for subclasses ------------
     afterEvent(_event, state) {
-        if (state.status !== "failed")
-            this.maybeMarkIssueDone(state);
+        // #766: always re-derive — `maybeMarkIssueDone` guards internally and must
+        // run even when `state.status` is currently `failed` so a recovered loop
+        // failure can de-escalate to `done`.
+        this.maybeMarkIssueDone(state);
         this.afterStateChange();
     }
     afterStateChange() {
@@ -321,6 +347,8 @@ export class NonTTYRenderer extends BaseRenderer {
     columnsOverride;
     maxLoopIterations;
     lastEventAt;
+    /** #860 AC-6: `issue:phase` keys whose auto-wait start line was emitted. */
+    announcedWaits = new Set();
     constructor(options) {
         super(options);
         this.heartbeatMs =
@@ -359,15 +387,53 @@ export class NonTTYRenderer extends BaseRenderer {
             return;
         const parts = running.map((s) => {
             const elapsedSec = s.startedAt !== undefined ? (this.now() - s.startedAt) / 1000 : 0;
+            // #860 AC-6: a phase paused on an auto-wait names its wake time instead
+            // of masquerading as ordinary running time — this heartbeat is the only
+            // periodic signal a non-TTY (background) run gets during a multi-hour
+            // wait, and without the wake time it is indistinguishable from a hang.
+            const waiting = s.phases.find((p) => p.name === s.currentPhase && p.status === "waiting");
+            if (waiting?.wakeAtMs !== undefined) {
+                const leftSec = Math.max(0, (waiting.wakeAtMs - this.now()) / 1000);
+                return `#${s.issueNumber} ${s.currentPhase} ⏸ rate-limit window — resuming at ${formatResetTime(waiting.wakeAtMs)} (${formatElapsedTime(leftSec)} left)`;
+            }
             return `#${s.issueNumber} ${s.currentPhase} (${formatElapsedTime(elapsedSec)})`;
         });
         this.emitLine(`⏱ still running: ${parts.join(", ")}`);
     }
     afterEvent(event, state) {
         super.afterEvent(event, state);
+        // #860 AC-6: waiting notices are liveness, not progress. The wait emits a
+        // tick every ~15s, so counting them as events would hold `lastEventAt`
+        // fresh forever and silence the heartbeat for the entire multi-hour wait.
+        if (event.event === "waiting") {
+            this.emitWaitTransitionLine(event);
+            return;
+        }
         this.lastEventAt = this.now();
         this.emitEventLine(event, state);
     }
+    /**
+     * Announce auto-wait transitions (#860 AC-6). Only the first notice of a
+     * wait and the terminal notice that ends it produce lines — the ~15s ticks
+     * in between are absorbed here (the periodic signal is `tickHeartbeat`).
+     * Before this, waiting events fell through `emitEventLine`'s failure branch
+     * and printed a spurious `✘` line per tick.
+     */
+    emitWaitTransitionLine(event) {
+        const key = `${event.issue}:${event.phase}`;
+        const c = colorize(this.noColor);
+        if (event.wakeAtMs !== undefined) {
+            if (this.announcedWaits.has(key))
+                return;
+            this.announcedWaits.add(key);
+            this.emitLine(`${c.yellow("⏸")} #${event.issue} ${event.phase} ${event.text ?? `rate-limit window — resuming at ${formatResetTime(event.wakeAtMs)}`}`);
+        }
+        else {
+            if (!this.announcedWaits.delete(key))
+                return;
+            this.emitLine(`${c.cyan("▸")} #${event.issue} ${event.phase} ${event.text ?? "auto-wait complete — resuming"}`);
+        }
+    }
     emitEventLine(event, state) {
         const c = colorize(this.noColor);
         const phase = state.phases.find((p) => p.name === event.phase);
@@ -1127,6 +1193,10 @@ export class TTYRenderer extends BaseRenderer {
                     return c.green(`${p.name} ✔${p.durationMs ? ` ${formatElapsedTime(p.durationMs / 1000)}` : ""}`);
                 if (p.status === "failed")
                     return c.red(`${p.name} ✘`);
+                // #804: a paused phase reads as `qa waiting 14:33`, so the wake time
+                // is visible in the live zone itself, not only the sub-status line.
+                if (p.status === "waiting")
+                    return c.yellow(`${p.name} waiting${p.wakeAtMs ? ` ${formatResetTime(p.wakeAtMs)}` : ""}`);
                 if (p.status === "running")
                     return c.cyan(`${p.name} running`);
                 // #672 AC-3: pending cells render as `name –` (en dash) so the live

package/dist/src/lib/errors.d.ts

@@ -145,17 +145,87 @@ export interface RateLimitInfoLike {
     hasChargeableSavedPaymentMethod?: boolean;
 }
 /**
- * True when the rate-limit info represents a billing/credits failure (which a
- * retry cannot fix), rather than a transient throttle.
+ * True when the rate-limit info describes an exhausted *window* that will
+ * reopen at a known future time: a recognized window `rateLimitType` plus a
+ * `resetsAt` still in the future (#860 AC-1).
+ *
+ * This is the discriminator between "subscription window closed until 07:00"
+ * and "account needs credits". The fields that would answer that directly
+ * (`canUserPurchaseCredits`, `hasChargeableSavedPaymentMethod`) are absent
+ * from every real captured payload, so the window shape is the proxy — and
+ * any unrecognized shape returns false (fail closed, #860 AC-3).
+ *
+ * Explicitly informational statuses (`allowed` / `allowed_warning`) are never
+ * waitable. The driver retains marker-carrying warnings as failure-grade
+ * (pre-#732 semantics, unchanged), so a stale "you are nearing your limit"
+ * warning can be misattributed to an unrelated phase failure — classifying it
+ * waitable would upgrade that misattribution from a cheap immediate halt to a
+ * multi-hour sleep. The 26 real captures carry no `status` field at all, so
+ * absent status stays waitable; only a status that affirmatively says
+ * "not a rejection" is excluded.
+ */
+export declare function isWaitableWindow(info: RateLimitInfoLike, now?: number): boolean;
+/**
+ * Vocabulary-drift telemetry for the #860 fail-closed path: returns a hint
+ * string when a payload was terminal ONLY because its `rateLimitType` is not
+ * in the recognized window allowlist — i.e. it carries `out_of_credits` plus a
+ * live future `resetsAt` and a *present but unrecognized* window type, and no
+ * explicit `credits_required`. If Anthropic renames or adds a window type,
+ * the halt message names the rejected type instead of silently reading as an
+ * ordinary wallet failure. A missing `rateLimitType` is NOT drift evidence
+ * (API-account payloads may legitimately omit it), so no hint fires there.
  */
-export declare function isBillingFailure(info: RateLimitInfoLike): boolean;
+export declare function unrecognizedWindowHint(info: RateLimitInfoLike, now?: number): string | null;
+/**
+ * True when the rate-limit info represents a billing/credits failure (which
+ * waiting cannot fix), rather than a transient throttle or an exhausted
+ * window.
+ *
+ * Narrowed by #860: a subscription plan hitting its five-hour cap with
+ * overage disabled emits `overageDisabledReason: "out_of_credits"` *plus* a
+ * window type and a live `resetsAt` — a pause, not a wallet failure. That
+ * shape is excluded here so it classifies as a retryable {@link RateLimitError}
+ * and `--auto-wait` (#804) can act on it. An explicit
+ * `errorCode: "credits_required"` stays terminal even alongside window
+ * evidence — it is the SDK's direct "purchase needed" signal (#860 AC-2).
+ * Anything short of the full recognized window shape remains terminal
+ * (fail closed, #860 AC-3).
+ */
+export declare function isBillingFailure(info: RateLimitInfoLike, now?: number): boolean;
 /**
  * True when the rate-limit info represents an actual failure (rejection or
  * billing), as opposed to an informational `allowed` / `allowed_warning`
  * event. The driver uses this to avoid mis-attributing a stale warning event
  * to an unrelated phase failure.
+ *
+ * Built on the raw billing *markers*, not the #860-narrowed classification:
+ * the captured five-hour payloads cannot prove they carried
+ * `status: "rejected"`, so narrowing here could silently drop the very events
+ * #860 exists to keep (they'd fall back to a metadata-less assistant error and
+ * auto-wait would stay inert). Retention semantics are unchanged; only the
+ * billing-vs-waitable *classification* narrowed.
  */
 export declare function isRateLimitFailureInfo(info: RateLimitInfoLike): boolean;
+/**
+ * Normalize a `resetsAt` timestamp to milliseconds. The SDK does not pin the
+ * unit, so use the same heuristic everywhere a `resetsAt` is compared or
+ * displayed: values below ~1e12 are seconds, otherwise milliseconds.
+ */
+export declare function resetsAtToMs(resetsAt: number): number;
+/**
+ * Format a Unix timestamp (seconds or ms) as a local time string.
+ *
+ * Bare `HH:MM` when the reset falls on the current local calendar day;
+ * date-qualified `MM-DD HH:MM` otherwise. Also used for #804's auto-wait wake
+ * time (a wake is `resetsAt + buffer`, already in ms, which `resetsAtToMs`
+ * passes through unchanged) so both render in one convention.
+ *
+ * Multi-day windows
+ * (`rateLimitType: seven_day*`) can reset days out — a bare `HH:MM` there reads
+ * as "later today" and misleads the user (#732 QA follow-up), so the date is
+ * included whenever the reset is not today.
+ */
+export declare function formatResetTime(resetsAt: number): string;
 /**
  * Build a user-facing message from rate-limit info, naming the real cause:
  * - billing/credits → "Out of credits" (enriched with purchasable vs hard
@@ -163,14 +233,22 @@ export declare function isRateLimitFailureInfo(info: RateLimitInfoLike): boolean
  * - transient throttle → "Rate limited — resets at HH:MM" (date-qualified as
  *   "MM-DD HH:MM" when the reset is not today; reset time omitted entirely when
  *   `resetsAt` is absent)
+ *
+ * `now` feeds the #860 waitable-window classification so message and error
+ * type are derived against the same instant (and tests can pin the clock).
+ * A waitable window renders through the rate-limited branch — its reset time
+ * is the actionable fact; "Out of credits" would misname a pause as a wallet
+ * failure.
  */
-export declare function formatRateLimitMessage(info: RateLimitInfoLike): string;
+export declare function formatRateLimitMessage(info: RateLimitInfoLike, now?: number): string;
 /**
  * Construct the appropriate typed error from structured rate-limit info.
  * Billing/credits failures become a non-retryable {@link BillingError};
- * transient throttles become a retryable {@link RateLimitError}.
+ * transient throttles AND exhausted-but-reopening windows (#860) become a
+ * retryable {@link RateLimitError}. `now` pins the waitable-window check to
+ * one instant across message and classification.
  */
-export declare function createRateLimitError(info: RateLimitInfoLike): RateLimitError | BillingError;
+export declare function createRateLimitError(info: RateLimitInfoLike, now?: number): RateLimitError | BillingError;
 /**
  * Map of error type names to their constructors.
  * Used for deserialization from logs.