sequant 2.8.0 → 2.10.0

package/dist/src/lib/workflow/completed-status.js

@@ -0,0 +1,57 @@
+/**
+ * Which persisted issue statuses mean "this issue is already done" (#837).
+ *
+ * Single source of truth for every pre-flight guard that skips finished work.
+ * It exists because the same predicate was previously spelled out inline at two
+ * sites with two different lists, and #817's `--ready-gate` extended the status
+ * vocabulary without either site following:
+ *
+ * - `chain-resume.ts` peels the completed prefix off a `--chain` run.
+ * - `run-orchestrator.ts` drops finished issues from a non-chain run.
+ *
+ * A gated issue deliberately terminates in `waiting_for_human_merge` (policy
+ * threshold reached) rather than `ready_for_merge`, since `ready_for_merge`
+ * would read as auto-merge-ready and defeat the human merge gate the feature
+ * exists to preserve. Both guards missed it, so re-running re-executed
+ * already-gated issues from phase 0 — a full spec/exec/qa pipeline plus another
+ * full-weight ready gate.
+ *
+ * `blocked` is deliberately NOT a completed status, for two reasons:
+ *
+ * 1. It is a *generic* member of `IssueStatusSchema` ("waiting on external input
+ *    or dependency"), not a ready-gate-exclusive terminal. Admitting it here
+ *    would silently apply to every other writer of that status, present and
+ *    future.
+ * 2. A guard halt IS the human-attention signal. Skipping it as complete would
+ *    report the issue as passed when it demonstrably did not.
+ *
+ * So a `blocked` issue is re-executed rather than skipped — the same
+ * conservative rule already applied to issues whose state lookup fails.
+ * Re-running wastes tokens; silently dropping an issue the user must look at is
+ * the worse failure. Once the user clears the blocker, the re-run is what lets
+ * work resume.
+ *
+ * NOTE: this is "done, do not re-run", which is NOT the same set as "might have
+ * a merged PR" — `state-cleanup.ts`'s merge-detection sweep deliberately keeps
+ * its own wider list (it also scans `in_progress`, #592, and
+ * `waiting_for_qa_gate`, #606). Do not unify the two.
+ *
+ * When adding a status to `IssueStatusSchema`, decide here whether it belongs.
+ */
+export const COMPLETED_ISSUE_STATUSES = [
+    "ready_for_merge",
+    "merged",
+    "waiting_for_human_merge",
+];
+const COMPLETED_ISSUE_STATUS_SET = new Set(COMPLETED_ISSUE_STATUSES);
+/**
+ * True iff `status` marks the issue as already finished, so a re-run should
+ * skip it unless `--force` is passed.
+ *
+ * Accepts `string | undefined` because persisted state may predate the current
+ * schema or be absent entirely; an unknown or missing status is treated as
+ * incomplete (re-execute), never as complete.
+ */
+export function isCompletedIssueStatus(status) {
+    return status !== undefined && COMPLETED_ISSUE_STATUS_SET.has(status);
+}

package/dist/src/lib/workflow/config-resolver.d.ts

@@ -42,6 +42,32 @@ export declare function normalizeCommanderOptions(options: RunOptions): RunOptio
  * This replaces the inline merging logic previously in run.ts.
  */
 export declare function resolveRunOptions(cliOptions: RunOptions, settings: SequantSettings): RunOptions;
+/**
+ * Fall back to `fallback` unless `value` is a usable positive number.
+ *
+ * `??` alone is not enough for these (#833). `NaN` is not nullish, so a
+ * malformed value survives `?? default` and flows on into `setTimeout`, which
+ * clamps a `NaN` delay to 0 and aborts the phase on its first tick, or into
+ * `while (iteration < maxIterations)`, which is false on entry and runs zero
+ * phases. Both read as a phase/agent fault rather than a bad input, which is
+ * what makes the silent version expensive. Non-finite and non-positive values
+ * therefore fall back *to* the default instead of through it.
+ *
+ * `bin/cli.ts` rejects these at the flag boundary with a message naming the
+ * flag — that is the user-facing fix. This is the structural backstop for
+ * programmatic callers, `settings.json`, and whatever calls this next.
+ *
+ * Exported because `phaseTimeout` has two producers, not one: this module and
+ * `commands/ready.ts`, whose value reaches the driver through
+ * `ready-gate.ts`'s own `buildPhaseConfig` and never passes through
+ * `buildExecutionConfig`. Guarding only here would have left that path open.
+ * Chain it to express the layering — CLI, then settings, then the default:
+ *
+ * ```ts
+ * positiveOr(options.timeout, positiveOr(settings.run.timeout, DEFAULT))
+ * ```
+ */
+export declare function positiveOr(value: number | undefined, fallback: number): number;
 /**
  * Build an ExecutionConfig from merged RunOptions and settings.
  * Extracts the phase-timeout, MCP, retry, and mode resolution logic

package/dist/src/lib/workflow/config-resolver.js

@@ -97,6 +97,10 @@ export function normalizeCommanderOptions(options) {
         ...(raw.retry === false && { noRetry: true }),
         ...(raw.rebase === false && { noRebase: true }),
         ...(raw.pr === false && { noPr: true }),
+        // #804: map the flag-derived key onto the interface field. Guarded on
+        // `undefined` (not truthiness) so an explicit `--auto-wait 0` still
+        // overrides a non-zero setting.
+        ...(raw.autoWait !== undefined && { autoWaitMinutes: raw.autoWait }),
     };
 }
 /**
@@ -117,6 +121,7 @@ export function resolveRunOptions(cliOptions, settings) {
         qualityLoop: defined.qualityLoop ?? settings.run.qualityLoop,
         maxIterations: defined.maxIterations ?? settings.run.maxIterations,
         noSmartTests: defined.noSmartTests ?? !settings.run.smartTests,
+        autoWaitMinutes: defined.autoWaitMinutes ?? settings.run.autoWaitMinutes,
         // Agent settings
         isolateParallel: defined.isolateParallel ?? settings.agents.isolateParallel,
         // Env overrides
@@ -129,6 +134,36 @@ export function resolveRunOptions(cliOptions, settings) {
     merged.autoDetectPhases = autoDetectPhases;
     return merged;
 }
+/**
+ * Fall back to `fallback` unless `value` is a usable positive number.
+ *
+ * `??` alone is not enough for these (#833). `NaN` is not nullish, so a
+ * malformed value survives `?? default` and flows on into `setTimeout`, which
+ * clamps a `NaN` delay to 0 and aborts the phase on its first tick, or into
+ * `while (iteration < maxIterations)`, which is false on entry and runs zero
+ * phases. Both read as a phase/agent fault rather than a bad input, which is
+ * what makes the silent version expensive. Non-finite and non-positive values
+ * therefore fall back *to* the default instead of through it.
+ *
+ * `bin/cli.ts` rejects these at the flag boundary with a message naming the
+ * flag — that is the user-facing fix. This is the structural backstop for
+ * programmatic callers, `settings.json`, and whatever calls this next.
+ *
+ * Exported because `phaseTimeout` has two producers, not one: this module and
+ * `commands/ready.ts`, whose value reaches the driver through
+ * `ready-gate.ts`'s own `buildPhaseConfig` and never passes through
+ * `buildExecutionConfig`. Guarding only here would have left that path open.
+ * Chain it to express the layering — CLI, then settings, then the default:
+ *
+ * ```ts
+ * positiveOr(options.timeout, positiveOr(settings.run.timeout, DEFAULT))
+ * ```
+ */
+export function positiveOr(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0
+        ? value
+        : fallback;
+}
 /**
  * Build an ExecutionConfig from merged RunOptions and settings.
  * Extracts the phase-timeout, MCP, retry, and mode resolution logic
@@ -157,15 +192,32 @@ export function buildExecutionConfig(mergedOptions, settings, issueCount) {
         parallel: isParallel,
         dryRun: mergedOptions.dryRun ?? false,
         verbose: mergedOptions.verbose ?? false,
-        phaseTimeout: mergedOptions.timeout ?? DEFAULT_CONFIG.phaseTimeout,
+        // #833: chained so the layering is CLI → settings → default, matching
+        // `commands/ready.ts`. A malformed CLI value falls back to the user's
+        // configured setting rather than skipping past it to the hardcoded
+        // default; a malformed setting falls back to the default. In the normal
+        // path `mergedOptions` already carries the settings value, so this only
+        // differs when one of the two layers is unusable — which is the case that
+        // matters.
+        phaseTimeout: positiveOr(mergedOptions.timeout, positiveOr(settings.run.timeout, DEFAULT_CONFIG.phaseTimeout)),
         qualityLoop: mergedOptions.qualityLoop ?? false,
-        maxIterations: mergedOptions.maxIterations ?? DEFAULT_CONFIG.maxIterations,
+        maxIterations: positiveOr(mergedOptions.maxIterations, positiveOr(settings.run.maxIterations, DEFAULT_CONFIG.maxIterations)),
         noSmartTests: mergedOptions.noSmartTests ?? false,
         mcp: mcpEnabled,
         retry: retryEnabled,
+        // #804: default 0 (off) — the whole regression contract for auto-wait is
+        // that an unset flag leaves the #761/#799 halt path untouched.
+        autoWaitMinutes: mergedOptions.autoWaitMinutes ??
+            settings.run.autoWaitMinutes ??
+            DEFAULT_CONFIG.autoWaitMinutes,
         agent: mergedOptions.agent ?? settings.run.agent,
         aiderSettings: settings.run.aider,
         isolateParallel: mergedOptions.isolateParallel,
         relayEnabled,
+        // #817: opt-in only, no settings backing (AC-4). A missing `--ready-gate`
+        // resolves to false, keeping the run path byte-identical (AC-5). This is the
+        // load-bearing wire the #795 inert-flag class guards against — the flag is
+        // useless if it stops reaching the executor here.
+        readyGate: mergedOptions.readyGate ?? false,
     };
 }

package/dist/src/lib/workflow/dependency-markers.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared parser for line-leading dependency markers in an issue body (#767).
+ *
+ * Two callers extract issue numbers from `depends on #N` / `blocked by #N`
+ * declarations:
+ *
+ *   - `chain-preflight.ts:parseDeclaredBlockers` — warn-only pre-flight, honors
+ *     BOTH `depends on` and `blocked by`.
+ *   - `batch-executor.ts:parseDependencies` — feeds `sortByDependencies`, which
+ *     *silently reorders the run*, so it honors ONLY `depends on`.
+ *
+ * The hardened mechanics (line anchoring, required `#`, code/comment stripping)
+ * were introduced for the pre-flight in #762/PR #764 and lived only in
+ * `chain-preflight.ts`. #767 promotes them here so the sorter can adopt the same
+ * hardening without the two regexes drifting — while keeping the **marker set
+ * per-caller** so sharing the parser does NOT make the sorter start reordering
+ * on `blocked by` (a new, unrequested silent-reorder class; #762 Open Q #3).
+ */
+/** A dependency-declaration marker a caller opts into honoring. */
+export type DepMarker = "depends on" | "blocked by";
+/**
+ * Parse the issue numbers a body declares itself dependent on / blocked by,
+ * honoring only the requested `markers`. Deduped, order-preserving.
+ *
+ * Only line-leading markers count as declarations — see `buildMarkerRegex` for
+ * why mid-sentence prose mentions are deliberately ignored. Code blocks, inline
+ * code spans, and HTML comments are stripped first.
+ */
+export declare function parseBodyDependencyMarkers(body: string, markers: DepMarker[]): number[];

package/dist/src/lib/workflow/dependency-markers.js

@@ -0,0 +1,79 @@
+/**
+ * Shared parser for line-leading dependency markers in an issue body (#767).
+ *
+ * Two callers extract issue numbers from `depends on #N` / `blocked by #N`
+ * declarations:
+ *
+ *   - `chain-preflight.ts:parseDeclaredBlockers` — warn-only pre-flight, honors
+ *     BOTH `depends on` and `blocked by`.
+ *   - `batch-executor.ts:parseDependencies` — feeds `sortByDependencies`, which
+ *     *silently reorders the run*, so it honors ONLY `depends on`.
+ *
+ * The hardened mechanics (line anchoring, required `#`, code/comment stripping)
+ * were introduced for the pre-flight in #762/PR #764 and lived only in
+ * `chain-preflight.ts`. #767 promotes them here so the sorter can adopt the same
+ * hardening without the two regexes drifting — while keeping the **marker set
+ * per-caller** so sharing the parser does NOT make the sorter start reordering
+ * on `blocked by` (a new, unrequested silent-reorder class; #762 Open Q #3).
+ */
+/**
+ * Build the anchored marker regex for the requested marker set.
+ *
+ * Matches a declared marker, optionally bold-wrapped, colon-separated, and/or
+ * written as a list item, e.g. `- **Depends on**: #123`.
+ *
+ * Anchored to line start because a *declaration* is a line about the issue's
+ * own dependencies, whereas prose that merely mentions the marker mid-sentence
+ * is not. #762's own body is the motivating case: it contains both `...when #39
+ * says blocked by #38` and `...real markers like "Blocked by #36"` as examples,
+ * and an unanchored match reported #762 as blocked by #38 and #36 — exactly the
+ * false inference #604 says is worse than none. That matters most under
+ * `--strict-preflight`, where a bogus warning hard-aborts a legitimate chain.
+ *
+ * The `#` is required (unlike the historic looser `#?` in `parseDependencies`)
+ * so a line such as `Blocked by 5 days of review` — or the prose
+ * `Issue 14 depends on 12+13` — cannot parse as an issue number.
+ */
+function buildMarkerRegex(markers) {
+    const alternation = markers.map((m) => m.split(/\s+/).join("\\s+")).join("|");
+    return new RegExp(`^\\s*(?:[-*]\\s*)?\\*?\\*?(?:${alternation})\\*?\\*?:?\\s*#(\\d+)`, "gim");
+}
+/**
+ * Strip fenced code blocks, inline code spans, and HTML comments so markers
+ * inside quoted shell snippets, documentation examples, or commented-out drafts
+ * don't count as real declarations. Inline spans are matched within a single
+ * line so an unbalanced backtick cannot swallow the rest of the body.
+ *
+ * Deliberately diverges from `assess-collision-detect.ts:stripCodeBlocksAndComments`,
+ * which keeps inline spans: its PATH_REGEX only matches backtick-wrapped paths,
+ * so stripping them there would find nothing. Same syntax, opposite meaning —
+ * a backticked marker here is an example, a backticked path there is the target.
+ * Keep the two separate (see PR #770).
+ */
+function stripCodeAndComments(body) {
+    return body
+        .replace(/```[\s\S]*?```/g, "")
+        .replace(/<!--[\s\S]*?-->/g, "")
+        .replace(/`[^`\n]*`/g, "");
+}
+/**
+ * Parse the issue numbers a body declares itself dependent on / blocked by,
+ * honoring only the requested `markers`. Deduped, order-preserving.
+ *
+ * Only line-leading markers count as declarations — see `buildMarkerRegex` for
+ * why mid-sentence prose mentions are deliberately ignored. Code blocks, inline
+ * code spans, and HTML comments are stripped first.
+ */
+export function parseBodyDependencyMarkers(body, markers) {
+    if (markers.length === 0)
+        return [];
+    const cleaned = stripCodeAndComments(body);
+    const regex = buildMarkerRegex(markers);
+    const found = [];
+    for (const m of cleaned.matchAll(regex)) {
+        const n = parseInt(m[1], 10);
+        if (!isNaN(n) && !found.includes(n))
+            found.push(n);
+    }
+    return found;
+}

package/dist/src/lib/workflow/drivers/agent-driver.d.ts

@@ -98,6 +98,13 @@ export interface AgentPhaseResult {
 export interface AgentDriver {
     /** Human-readable name for logging */
     name: string;
+    /**
+     * True when this driver executes phases by resolving slash-command skills
+     * from the project's `.claude/skills/` directory (claude-code). Drivers
+     * whose prompts do the work inline (aider's `driverOverrides` templates)
+     * return false, and the `run` skills pre-flight (#813) is skipped for them.
+     */
+    resolvesSkills: boolean;
     /** Execute a phase prompt and return structured result */
     executePhase(prompt: string, config: AgentExecutionConfig): Promise<AgentPhaseResult>;
     /** Check if this driver is available/configured */

package/dist/src/lib/workflow/drivers/aider.d.ts

@@ -9,6 +9,8 @@ import type { AgentDriver, AgentExecutionConfig, AgentPhaseResult, ResumeHandle
 import type { AiderSettings } from "../../settings.js";
 export declare class AiderDriver implements AgentDriver {
     name: string;
+    /** Aider phases use inline `driverOverrides` prompts — no skills (#813). */
+    resolvesSkills: boolean;
     private settings?;
     constructor(settings?: AiderSettings);
     /**

package/dist/src/lib/workflow/drivers/aider.js

@@ -10,6 +10,8 @@ import { execSync } from "child_process";
 import { RingBuffer } from "../ring-buffer.js";
 export class AiderDriver {
     name = "aider";
+    /** Aider phases use inline `driverOverrides` prompts — no skills (#813). */
+    resolvesSkills = false;
     settings;
     constructor(settings) {
         this.settings = settings;

package/dist/src/lib/workflow/drivers/claude-code.d.ts

@@ -7,6 +7,8 @@
 import type { AgentDriver, AgentExecutionConfig, AgentPhaseResult, ResumeHandle } from "./agent-driver.js";
 export declare class ClaudeCodeDriver implements AgentDriver {
     name: string;
+    /** Phases run slash-command skills from `.claude/skills/` (#813). */
+    resolvesSkills: boolean;
     /**
      * Track session ID across calls so callers can implement resume.
      * Set after each executePhase() call.
@@ -42,12 +44,31 @@ export declare class ClaudeCodeDriver implements AgentDriver {
      * RateLimitError would wrongly re-enable the retry / MCP-fallback path. When
      * the `rate_limit_event` is itself a billing failure its richer metadata
      * (`canUserPurchaseCredits`, etc.) is preserved.
+     *
+     * Counter-exception (#860): when the `rate_limit_event` carries the FULL
+     * captured subscription-window shape — waitable window evidence (recognized
+     * window type + future `resetsAt`) *plus* the `out_of_credits` marker — the
+     * richer structured signal wins over the bare `billing_error` enum. A
+     * subscription plan's five-hour exhaustion surfaces assistant-side as a
+     * billing error, and overriding on that enum here would strip the metadata
+     * `--auto-wait` needs and re-inert the feature this classification exists
+     * to enable. Deliberately no wider than the evidenced shape: a pure
+     * throttle event (window, no billing markers) beside a `billing_error`
+     * enum keeps the #732 rule — billing wins — because there the two signals
+     * genuinely conflict and no capture justifies trusting the throttle.
      */
     private buildStructuredError;
     /**
      * Map the SDK's assistant/api-retry error enum to a typed error. Only
      * rate-limit / billing variants are mapped; other variants (auth, etc.)
      * return undefined and defer to the existing classification path.
+     *
+     * The assistant-error channel carries no `resetsAt`/`rateLimitType` (the
+     * enum is the whole signal — `SDKAssistantMessageError` is a bare string),
+     * so the originating variant is recorded in metadata to keep `rate_limit`
+     * and `overloaded` distinguishable downstream (#761 AC-9). With no
+     * `resetsAt`, these errors are treated as transient by the executor's
+     * window-exhaustion check — the mandatory metadata-absent fallback.
      */
     private errorFromAssistantError;
     private buildResumeHandle;

package/dist/src/lib/workflow/drivers/claude-code.js

@@ -6,10 +6,12 @@
  */
 import { query } from "@anthropic-ai/claude-agent-sdk";
 import { getMcpServersConfig } from "../../system.js";
-import { RateLimitError, BillingError, createRateLimitError, isRateLimitFailureInfo, } from "../../errors.js";
+import { RateLimitError, BillingError, createRateLimitError, isWaitableWindow, isRateLimitFailureInfo, } from "../../errors.js";
 import { RingBuffer } from "../ring-buffer.js";
 export class ClaudeCodeDriver {
     name = "claude-code";
+    /** Phases run slash-command skills from `.claude/skills/` (#813). */
+    resolvesSkills = true;
     /**
      * Track session ID across calls so callers can implement resume.
      * Set after each executePhase() call.
@@ -228,10 +230,22 @@ export class ClaudeCodeDriver {
             clearTimeout(timeoutId);
             const error = err instanceof Error ? err.message : String(err);
             if (error.includes("abort") || error.includes("AbortError")) {
+                // A rate limit can manifest as a hang rather than a stream event
+                // reaching the result: the SDK stalls, the phase timeout fires, and
+                // the abort lands here. Only failure-grade signals are ever captured
+                // (see the stream loop), so attaching them cannot mask a genuine
+                // timeout — with no signal, `abortStructuredError` is undefined and
+                // the bare timeout message survives unchanged (#761 AC-1). Without
+                // this, the captured `rateLimitInfo` was discarded and downstream
+                // classification saw only `Timeout after Ns`, sending a closed
+                // rate-limit window into the full retry + MCP-fallback ladder.
+                const abortStructuredError = this.buildStructuredError(rateLimitInfo, assistantError, apiRetryError);
                 return {
                     success: false,
                     output: capturedOutput,
-                    error: `Timeout after ${config.phaseTimeout}s`,
+                    error: abortStructuredError?.message ??
+                        `Timeout after ${config.phaseTimeout}s`,
+                    structuredError: abortStructuredError,
                     stderrTail: stderrBuffer.getLines(),
                     stdoutTail: stdoutBuffer.getLines(),
                 };
@@ -239,8 +253,7 @@ export class ClaudeCodeDriver {
             // If the stream surfaced a failure-grade rate-limit/billing signal before
             // throwing, prefer that typed cause (#732) over the raw thrown message — a
             // mid-stream throw after a *rejected* rate_limit_event is very likely the
-            // proximate cause. Abort/timeout is handled above first, so a genuine
-            // timeout is never masked by a stale rate-limit signal.
+            // proximate cause.
             const structuredError = this.buildStructuredError(rateLimitInfo, assistantError, apiRetryError);
             const stderrSuffix = capturedStderr
                 ? `\nStderr: ${capturedStderr.slice(0, 500)}`
@@ -271,11 +284,27 @@ export class ClaudeCodeDriver {
      * RateLimitError would wrongly re-enable the retry / MCP-fallback path. When
      * the `rate_limit_event` is itself a billing failure its richer metadata
      * (`canUserPurchaseCredits`, etc.) is preserved.
+     *
+     * Counter-exception (#860): when the `rate_limit_event` carries the FULL
+     * captured subscription-window shape — waitable window evidence (recognized
+     * window type + future `resetsAt`) *plus* the `out_of_credits` marker — the
+     * richer structured signal wins over the bare `billing_error` enum. A
+     * subscription plan's five-hour exhaustion surfaces assistant-side as a
+     * billing error, and overriding on that enum here would strip the metadata
+     * `--auto-wait` needs and re-inert the feature this classification exists
+     * to enable. Deliberately no wider than the evidenced shape: a pure
+     * throttle event (window, no billing markers) beside a `billing_error`
+     * enum keeps the #732 rule — billing wins — because there the two signals
+     * genuinely conflict and no capture justifies trusting the throttle.
      */
     buildStructuredError(rateLimitInfo, assistantError, apiRetryError) {
         if (rateLimitInfo) {
             const err = createRateLimitError(rateLimitInfo);
-            if (err instanceof RateLimitError && assistantError === "billing_error") {
+            const isCapturedSubscriptionShape = isWaitableWindow(rateLimitInfo) &&
+                rateLimitInfo.overageDisabledReason === "out_of_credits";
+            if (err instanceof RateLimitError &&
+                assistantError === "billing_error" &&
+                !isCapturedSubscriptionShape) {
                 return new BillingError("Billing error");
             }
             return err;
@@ -287,15 +316,28 @@ export class ClaudeCodeDriver {
      * Map the SDK's assistant/api-retry error enum to a typed error. Only
      * rate-limit / billing variants are mapped; other variants (auth, etc.)
      * return undefined and defer to the existing classification path.
+     *
+     * The assistant-error channel carries no `resetsAt`/`rateLimitType` (the
+     * enum is the whole signal — `SDKAssistantMessageError` is a bare string),
+     * so the originating variant is recorded in metadata to keep `rate_limit`
+     * and `overloaded` distinguishable downstream (#761 AC-9). With no
+     * `resetsAt`, these errors are treated as transient by the executor's
+     * window-exhaustion check — the mandatory metadata-absent fallback.
      */
     errorFromAssistantError(error) {
         switch (error) {
             case "billing_error":
-                return new BillingError("Billing error");
+                return new BillingError("Billing error", {
+                    assistantError: "billing_error",
+                });
             case "rate_limit":
-                return new RateLimitError("Rate limited");
+                return new RateLimitError("Rate limited", {
+                    assistantError: "rate_limit",
+                });
             case "overloaded":
-                return new RateLimitError("API overloaded");
+                return new RateLimitError("API overloaded", {
+                    assistantError: "overloaded",
+                });
             default:
                 return undefined;
         }

package/dist/src/lib/workflow/error-classifier.d.ts

@@ -5,8 +5,15 @@
  * categories. Exit codes are the primary signal; stderr patterns are secondary.
  */
 import { SequantError } from "../errors.js";
-/** All recognized error categories (kept for backwards compatibility). */
-export declare const ERROR_CATEGORIES: readonly ["context_overflow", "api_error", "hook_failure", "build_error", "timeout", "unknown"];
+/**
+ * All recognized error categories (kept for backwards compatibility).
+ *
+ * `rate_limit` / `billing` (#761 AC-6) only arise from the driver's structured
+ * errors — `classifyError` never produces them, since stderr text cannot
+ * distinguish a window-exhausted limit from a transient 429 (`api_error`).
+ * Keep in sync with the inline category enum in `run-log-schema.ts`.
+ */
+export declare const ERROR_CATEGORIES: readonly ["context_overflow", "api_error", "hook_failure", "build_error", "timeout", "rate_limit", "billing", "unknown"];
 export type ErrorCategory = (typeof ERROR_CATEGORIES)[number];
 /**
  * Map from error type name to legacy category string.

package/dist/src/lib/workflow/error-classifier.js

@@ -5,13 +5,22 @@
  * categories. Exit codes are the primary signal; stderr patterns are secondary.
  */
 import { ContextOverflowError, ApiError, HookFailureError, BuildError, TimeoutError, SubprocessError, } from "../errors.js";
-/** All recognized error categories (kept for backwards compatibility). */
+/**
+ * All recognized error categories (kept for backwards compatibility).
+ *
+ * `rate_limit` / `billing` (#761 AC-6) only arise from the driver's structured
+ * errors — `classifyError` never produces them, since stderr text cannot
+ * distinguish a window-exhausted limit from a transient 429 (`api_error`).
+ * Keep in sync with the inline category enum in `run-log-schema.ts`.
+ */
 export const ERROR_CATEGORIES = [
     "context_overflow",
     "api_error",
     "hook_failure",
     "build_error",
     "timeout",
+    "rate_limit",
+    "billing",
     "unknown",
 ];
 /**
@@ -30,6 +39,10 @@ export function errorTypeToCategory(error) {
             return "build_error";
         case "TimeoutError":
             return "timeout";
+        case "RateLimitError":
+            return "rate_limit";
+        case "BillingError":
+            return "billing";
         default:
             return "unknown";
     }

package/dist/src/lib/workflow/git-diff-utils.d.ts

@@ -18,18 +18,50 @@ export interface GitDiffStatsResult {
     /** Total lines deleted across all files */
     totalDeletions: number;
 }
+/**
+ * Resolve the ref diff stats should compare against (#878).
+ *
+ * Worktrees are created from `origin/<base>` (worktree-manager), but callers
+ * historically passed the bare branch name and the diff ran against the
+ * *local* ref. When local `<base>` lags the remote — routine, since nothing
+ * in the run path updates it — `<base>...HEAD` attributes commits the run
+ * never made (phantom filesModified).
+ *
+ * Candidates are the origin-qualified and bare forms of `baseBranch`
+ * (already-remote-qualified input keeps a single candidate). Among the
+ * candidates that resolve to a commit, pick the one nearest to HEAD
+ * (smallest `rev-list --count <cand>..HEAD`), preferring the
+ * origin-qualified form on a tie. Nearest-wins matches the worktree's
+ * actual creation point in both staleness directions: a stale local
+ * default branch (this issue) and a chain-mode worktree branched from a
+ * local base that is ahead of its pushed counterpart. Falls back to
+ * `baseBranch` verbatim when no candidate resolves (e.g. remote-less repo
+ * with a missing branch) — the diff then fails gracefully to empty, the
+ * pre-#878 behavior.
+ */
+export declare function resolveDiffBase(worktreePath: string, baseBranch: string): string;
 /**
  * Get git commit SHA for a worktree (AC-2)
  *
+ * When `baseRef` is provided, returns undefined if HEAD has no commits
+ * unique to it (#878) — a branch that never moved off its base would
+ * otherwise log the base tip as if it were the phase's commit. Callers
+ * recording plain "where is HEAD" markers (run start/end) omit `baseRef`.
+ *
  * @param worktreePath - Path to the git worktree
- * @returns The current HEAD commit SHA, or undefined on error
+ * @param baseRef - Optional resolved base ref (see resolveDiffBase); when
+ *   given, a HEAD with zero commits past it yields undefined
+ * @returns The current HEAD commit SHA, or undefined on error / no unique
+ *   commits
  */
-export declare function getCommitHash(worktreePath: string): string | undefined;
+export declare function getCommitHash(worktreePath: string, baseRef?: string): string | undefined;
 /**
  * Get git diff statistics for a worktree (AC-1, AC-3, AC-4)
  *
  * Efficiently captures both filesModified and fileDiffStats using
- * minimal git commands. Uses main...HEAD comparison by default.
+ * minimal git commands. The base is resolved via resolveDiffBase (#878) so
+ * the comparison targets the ref the worktree was actually created from
+ * (origin/<base> in the common case) rather than a possibly-stale local ref.
  *
  * @param worktreePath - Path to the git worktree
  * @param baseBranch - Branch to compare against (default: "main")