sequant 2.9.0 → 2.10.0

package/dist/src/lib/workflow/chain-resume.d.ts

@@ -2,28 +2,29 @@
  * Chain resume planning (#760).
  *
  * When a `--chain` run fails mid-way, earlier links may already be complete
- * (`ready_for_merge`) with a checkpoint commit on their feature branch
+ * (see `completed-status.ts`) with a checkpoint commit on their feature branch
  * (`createCheckpointCommit`, worktree-manager.ts). Re-running the same chain
  * should skip that completed prefix and resume at the first incomplete link,
  * rebased onto the last completed link's committed tip — NOT `main` (which is
  * the #748 wrong-base failure this reuses the #748 rebase path to avoid).
  *
- * The existing pre-flight guard (`run-orchestrator.ts`) already drops
- * `ready_for_merge`/`merged` issues from the run, but it is chain-unaware:
- * dropping the completed prefix leaves the first incomplete link at index 0,
- * where `executeSequential`'s successor-rebase never fires, so it silently
- * builds on `main`. This module computes a *chain-correct* resume plan that
- * preserves the completed prefix as the resume base.
+ * The non-chain pre-flight guard (`run-orchestrator.ts`) drops completed issues
+ * from the run using the same {@link isCompletedIssueStatus} predicate, but it
+ * is chain-unaware: dropping the completed prefix leaves the first incomplete
+ * link at index 0, where `executeSequential`'s successor-rebase never fires, so
+ * it silently builds on `main`. This module computes a *chain-correct* resume
+ * plan that preserves the completed prefix as the resume base.
  *
  * The planner is pure over an injected {@link CompletedLinkResolver} so the
  * skip/fail-fast state machine (AC-3) is unit-testable without real git; the
  * real-git rebase is covered by the integration test.
  */
+import { type CompletedIssueStatus } from "./completed-status.js";
 /** A completed link that will be skipped (not re-executed) on resume. */
 export interface ChainResumeSkip {
     issueNumber: number;
     /** Why it was skipped — the terminal-ish status that made it complete. */
-    status: "ready_for_merge" | "merged";
+    status: CompletedIssueStatus;
     /** The link's local feature branch (from state), if known. */
     branch?: string;
     /** The link's worktree path (from state), if known — used for the dirty check. */
@@ -45,9 +46,10 @@ export interface ChainResumePlan {
     /** First incomplete issue number (the resume point), if any. */
     resumeIssue?: number;
     /**
-     * Set when resume cannot proceed safely (AC-3): a `ready_for_merge` link's
-     * branch/checkpoint is gone and its tip is unreconstructable. The caller must
-     * abort rather than silently execute the successor on the wrong base.
+     * Set when resume cannot proceed safely (AC-3): an unmerged completed link's
+     * (`ready_for_merge` or `waiting_for_human_merge`) branch/checkpoint is gone
+     * and its tip is unreconstructable. The caller must abort rather than
+     * silently execute the successor on the wrong base.
      */
     failFast?: string;
     /** True when every link in the chain is already complete. */

package/dist/src/lib/workflow/chain-resume.js

@@ -2,24 +2,24 @@
  * Chain resume planning (#760).
  *
  * When a `--chain` run fails mid-way, earlier links may already be complete
- * (`ready_for_merge`) with a checkpoint commit on their feature branch
+ * (see `completed-status.ts`) with a checkpoint commit on their feature branch
  * (`createCheckpointCommit`, worktree-manager.ts). Re-running the same chain
  * should skip that completed prefix and resume at the first incomplete link,
  * rebased onto the last completed link's committed tip — NOT `main` (which is
  * the #748 wrong-base failure this reuses the #748 rebase path to avoid).
  *
- * The existing pre-flight guard (`run-orchestrator.ts`) already drops
- * `ready_for_merge`/`merged` issues from the run, but it is chain-unaware:
- * dropping the completed prefix leaves the first incomplete link at index 0,
- * where `executeSequential`'s successor-rebase never fires, so it silently
- * builds on `main`. This module computes a *chain-correct* resume plan that
- * preserves the completed prefix as the resume base.
+ * The non-chain pre-flight guard (`run-orchestrator.ts`) drops completed issues
+ * from the run using the same {@link isCompletedIssueStatus} predicate, but it
+ * is chain-unaware: dropping the completed prefix leaves the first incomplete
+ * link at index 0, where `executeSequential`'s successor-rebase never fires, so
+ * it silently builds on `main`. This module computes a *chain-correct* resume
+ * plan that preserves the completed prefix as the resume base.
  *
  * The planner is pure over an injected {@link CompletedLinkResolver} so the
  * skip/fail-fast state machine (AC-3) is unit-testable without real git; the
  * real-git rebase is covered by the integration test.
  */
-const COMPLETED_STATUSES = new Set(["ready_for_merge", "merged"]);
+import { isCompletedIssueStatus, } from "./completed-status.js";
 /**
  * Compute a chain-correct resume plan.
  *
@@ -37,7 +37,7 @@ export function computeChainResumePlan(orderedLinks, baseBranch, resolver) {
     const skipped = [];
     let firstIncomplete = 0;
     for (const link of orderedLinks) {
-        if (link.status && COMPLETED_STATUSES.has(link.status)) {
+        if (isCompletedIssueStatus(link.status)) {
             skipped.push({
                 issueNumber: link.issueNumber,
                 status: link.status,
@@ -72,17 +72,18 @@ export function computeChainResumePlan(orderedLinks, baseBranch, resolver) {
         resumeBaseCommit = resolver.resolveBaseTip();
     }
     else {
-        // ready_for_merge: the checkpoint tip lives only on the local feature
-        // branch. If that branch is gone (worktree/branch destroyed mid-way), the
-        // tip is unreconstructable — fail fast instead of wrong-basing the
-        // successor onto main (which would miss the completed link's work).
+        // ready_for_merge / waiting_for_human_merge: the checkpoint tip lives only
+        // on the local feature branch. If that branch is gone (worktree/branch
+        // destroyed mid-way), the tip is unreconstructable — fail fast instead of
+        // wrong-basing the successor onto main (which would miss the completed
+        // link's work).
         if (!last.branch) {
             return {
                 skipped,
                 active,
                 resumeIssue: active[0],
                 allComplete: false,
-                failFast: `#${last.issueNumber} is ready_for_merge but no branch is recorded in state — ` +
+                failFast: `#${last.issueNumber} is ${last.status} but no branch is recorded in state — ` +
                     `cannot reconstruct the resume base. Re-run with --force to redo the chain from scratch.`,
             };
         }
@@ -93,24 +94,27 @@ export function computeChainResumePlan(orderedLinks, baseBranch, resolver) {
                 active,
                 resumeIssue: active[0],
                 allComplete: false,
-                failFast: `#${last.issueNumber} is ready_for_merge but its branch "${last.branch}" no longer exists — ` +
+                failFast: `#${last.issueNumber} is ${last.status} but its branch "${last.branch}" no longer exists — ` +
                     `the resume base is unreconstructable. Re-run with --force to redo the chain from scratch.`,
             };
         }
         // The branch exists, but a tip is only a valid resume base if it actually
         // contains the link's work. `createCheckpointCommit` sweeps trailing
         // uncommitted changes into a checkpoint commit; when it fails (commit hook,
-        // staging error, or unrelated dirty files) the status was *already* written
-        // as ready_for_merge, so this link still reads as a completed prefix while
-        // its tip is missing work. Rebasing the successor onto it would be exactly
-        // the silent wrong-base execution AC-3 forbids — fail fast instead.
+        // staging error, or unrelated dirty files) a completed status was *already*
+        // written — `ready_for_merge` on a plain run, or `waiting_for_human_merge`
+        // when #817's `--ready-gate` owned the terminal status (#837) — so this link
+        // still reads as a completed prefix while its tip is missing work. Both
+        // statuses reach this branch, so the check covers gated links too. Rebasing
+        // the successor onto such a tip would be exactly the silent wrong-base
+        // execution AC-3 forbids — fail fast instead.
         if (last.worktree && resolver.isWorktreeDirty(last.worktree)) {
             return {
                 skipped,
                 active,
                 resumeIssue: active[0],
                 allComplete: false,
-                failFast: `#${last.issueNumber} is ready_for_merge but its worktree has uncommitted changes — ` +
+                failFast: `#${last.issueNumber} is ${last.status} but its worktree has uncommitted changes — ` +
                     `its checkpoint commit never landed, so branch "${last.branch}" is missing that work and ` +
                     `resuming #${active[0]} here would build on an incomplete base. Commit them in ${last.worktree}, ` +
                     `or re-run with --force to redo the chain from scratch.`,

package/dist/src/lib/workflow/completed-status.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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 declare const COMPLETED_ISSUE_STATUSES: readonly ["ready_for_merge", "merged", "waiting_for_human_merge"];
+/** A persisted status that counts as completed work. */
+export type CompletedIssueStatus = (typeof COMPLETED_ISSUE_STATUSES)[number];
+/**
+ * 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 declare function isCompletedIssueStatus(status: string | undefined): status is CompletedIssueStatus;

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/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,6 +44,18 @@ 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;
     /**

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.
@@ -282,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;

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")