sequant 2.7.0 → 2.9.0

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

@@ -0,0 +1,116 @@
+/**
+ * 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
+ * (`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 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.
+ */
+/** 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";
+    /** 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. */
+    worktree?: string;
+}
+/** The computed plan for resuming a partially-completed chain. */
+export interface ChainResumePlan {
+    /** Contiguous completed prefix that will be skipped (not re-executed). */
+    skipped: ChainResumeSkip[];
+    /** Issue numbers to actually execute (the incomplete tail). */
+    active: number[];
+    /**
+     * Local branch (or base ref) the first active link must be provisioned from
+     * and rebased onto. Undefined on a fresh run (no completed prefix).
+     */
+    resumeBase?: string;
+    /** Commit the resume base resolves to — reported so the user sees the point. */
+    resumeBaseCommit?: string;
+    /** 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.
+     */
+    failFast?: string;
+    /** True when every link in the chain is already complete. */
+    allComplete: boolean;
+}
+/** Resolves the git refs a resume base depends on. Injected for testability. */
+export interface CompletedLinkResolver {
+    /**
+     * Resolve a local branch ref to its tip commit SHA, or undefined if the
+     * branch does not exist (destroyed worktree/branch — the AC-3 fail-fast case).
+     */
+    resolveBranchTip(branch: string): string | undefined;
+    /** Resolve the base branch tip (for merged-resume reporting). */
+    resolveBaseTip(): string | undefined;
+    /**
+     * True iff the worktree has uncommitted changes (tracked or non-ignored
+     * untracked). Used to detect a resume base whose checkpoint never landed —
+     * see the dirty-tip fail-fast in {@link computeChainResumePlan}. Must return
+     * false (not throw) when the worktree is gone or unreadable; branch-tip
+     * resolution governs that case instead.
+     */
+    isWorktreeDirty(worktreePath: string): boolean;
+}
+/** An ordered chain link with its persisted state (status + branch + worktree). */
+export interface ChainLinkState {
+    issueNumber: number;
+    status?: string;
+    branch?: string;
+    worktree?: string;
+}
+/**
+ * Compute a chain-correct resume plan.
+ *
+ * Peels the *contiguous* completed prefix off the front of the chain (chain
+ * mode breaks on the first failure, so completed links always form a prefix).
+ * A completed link that appears *after* an incomplete one is left in `active`
+ * and re-executed — the conservative choice, since automatic skipping must not
+ * silently drop an issue the user intended to redo.
+ *
+ * @param orderedLinks Chain links in execution order, with persisted state.
+ * @param baseBranch The run's base branch (resume base when the prefix merged).
+ * @param resolver Git-ref resolver (injected for tests).
+ */
+export declare function computeChainResumePlan(orderedLinks: ChainLinkState[], baseBranch: string, resolver: CompletedLinkResolver): ChainResumePlan;
+/** The subset of persisted issue state the resume planner reads. */
+export interface PersistedLinkState {
+    status?: string;
+    branch?: string;
+    worktree?: string;
+}
+/**
+ * Read each link's persisted state and compute the resume plan.
+ *
+ * Split out of `run-orchestrator.ts` so the state-reading half of resume — in
+ * particular "a state lookup failure must treat the link as *incomplete*", the
+ * conservative choice that re-executes rather than skipping on bad data — is
+ * testable without standing up an orchestrator.
+ *
+ * @param issueNumbers Chain issues in execution order.
+ * @param baseBranch The run's base branch.
+ * @param getIssueState Reads persisted state for one issue (may reject).
+ * @param resolver Git-ref resolver.
+ * @param onStateError Called when a lookup throws; the link is then treated as
+ *   incomplete (no status), so it stays in `active`.
+ */
+export declare function planChainResumeFromState(issueNumbers: number[], baseBranch: string, getIssueState: (issueNumber: number) => Promise<PersistedLinkState | null | undefined>, resolver: CompletedLinkResolver, onStateError?: (issueNumber: number, error: unknown) => void): Promise<ChainResumePlan>;

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

@@ -0,0 +1,166 @@
+/**
+ * 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
+ * (`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 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"]);
+/**
+ * Compute a chain-correct resume plan.
+ *
+ * Peels the *contiguous* completed prefix off the front of the chain (chain
+ * mode breaks on the first failure, so completed links always form a prefix).
+ * A completed link that appears *after* an incomplete one is left in `active`
+ * and re-executed — the conservative choice, since automatic skipping must not
+ * silently drop an issue the user intended to redo.
+ *
+ * @param orderedLinks Chain links in execution order, with persisted state.
+ * @param baseBranch The run's base branch (resume base when the prefix merged).
+ * @param resolver Git-ref resolver (injected for tests).
+ */
+export function computeChainResumePlan(orderedLinks, baseBranch, resolver) {
+    const skipped = [];
+    let firstIncomplete = 0;
+    for (const link of orderedLinks) {
+        if (link.status && COMPLETED_STATUSES.has(link.status)) {
+            skipped.push({
+                issueNumber: link.issueNumber,
+                status: link.status,
+                branch: link.branch,
+                worktree: link.worktree,
+            });
+            firstIncomplete++;
+        }
+        else {
+            break;
+        }
+    }
+    const allNumbers = orderedLinks.map((l) => l.issueNumber);
+    // No completed prefix → fresh run, nothing to resume.
+    if (skipped.length === 0) {
+        return { skipped: [], active: allNumbers, allComplete: false };
+    }
+    // Every link already complete → nothing to execute.
+    if (firstIncomplete >= orderedLinks.length) {
+        return { skipped, active: [], allComplete: true };
+    }
+    const active = allNumbers.slice(firstIncomplete);
+    const last = skipped[skipped.length - 1];
+    let resumeBase;
+    let resumeBaseCommit;
+    if (last.status === "merged") {
+        // The completed prefix's work is in the merged base (origin/main). Provision
+        // the first incomplete link from the base branch — the same base a fresh
+        // first link would use — rather than a local tip that squash-merge may have
+        // orphaned (never rebase a successor onto a stale post-merge local tip).
+        resumeBase = baseBranch;
+        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).
+        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 — ` +
+                    `cannot reconstruct the resume base. Re-run with --force to redo the chain from scratch.`,
+            };
+        }
+        const tip = resolver.resolveBranchTip(last.branch);
+        if (!tip) {
+            return {
+                skipped,
+                active,
+                resumeIssue: active[0],
+                allComplete: false,
+                failFast: `#${last.issueNumber} is ready_for_merge 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.
+        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 — ` +
+                    `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.`,
+            };
+        }
+        resumeBase = last.branch;
+        resumeBaseCommit = tip;
+    }
+    return {
+        skipped,
+        active,
+        resumeBase,
+        resumeBaseCommit,
+        resumeIssue: active[0],
+        allComplete: false,
+    };
+}
+/**
+ * Read each link's persisted state and compute the resume plan.
+ *
+ * Split out of `run-orchestrator.ts` so the state-reading half of resume — in
+ * particular "a state lookup failure must treat the link as *incomplete*", the
+ * conservative choice that re-executes rather than skipping on bad data — is
+ * testable without standing up an orchestrator.
+ *
+ * @param issueNumbers Chain issues in execution order.
+ * @param baseBranch The run's base branch.
+ * @param getIssueState Reads persisted state for one issue (may reject).
+ * @param resolver Git-ref resolver.
+ * @param onStateError Called when a lookup throws; the link is then treated as
+ *   incomplete (no status), so it stays in `active`.
+ */
+export async function planChainResumeFromState(issueNumbers, baseBranch, getIssueState, resolver, onStateError) {
+    const orderedLinks = [];
+    for (const issueNumber of issueNumbers) {
+        let status;
+        let branch;
+        let worktree;
+        try {
+            const issueState = await getIssueState(issueNumber);
+            status = issueState?.status;
+            branch = issueState?.branch;
+            worktree = issueState?.worktree;
+        }
+        catch (error) {
+            // Unknown state → treat as incomplete and re-execute. Skipping on a
+            // failed lookup could silently drop an issue the user meant to run.
+            onStateError?.(issueNumber, error);
+        }
+        orderedLinks.push({ issueNumber, status, branch, worktree });
+    }
+    return computeChainResumePlan(orderedLinks, baseBranch, resolver);
+}

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

@@ -5,6 +5,7 @@
  * Continue.dev, Copilot SDK, Cursor API) can be added by implementing this
  * interface without touching orchestration logic.
  */
+import type { SequantError } from "../../errors.js";
 /**
  * Resume handle for a previous agent session.
  *
@@ -64,6 +65,22 @@ export interface AgentPhaseResult {
     /** Driver-tagged resume handle for cwd-safe cross-phase resume (#674). */
     resumeHandle?: ResumeHandle;
     error?: string;
+    /**
+     * Set when the agent hit its `maxTurns` ceiling (`error_max_turns`). The
+     * `output` is partial-but-usable rather than a hard failure, so consumers
+     * can treat it as inconclusive/incomplete instead of discarding the work.
+     * See #733.
+     */
+    capped?: boolean;
+    /**
+     * Typed error carrying structured cause data (#732). Set by drivers that can
+     * observe structured failure signals (e.g. ClaudeCodeDriver reading the SDK's
+     * `rate_limit_event` / assistant `error`). The executor prefers this over
+     * stderr-regex classification and uses its type to gate retry behavior (e.g.
+     * skipping the MCP fallback for non-retryable billing failures). Left
+     * undefined by drivers without structured signals (aider, subprocess paths).
+     */
+    structuredError?: SequantError;
     /** Last N lines of stderr captured via RingBuffer (#447) */
     stderrTail?: string[];
     /** Last N lines of stdout captured via RingBuffer (#447) */

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

@@ -28,6 +28,35 @@ export declare class ClaudeCodeDriver implements AgentDriver {
      */
     canResume(handle: ResumeHandle, targetCwd: string): boolean;
     executePhase(prompt: string, config: AgentExecutionConfig): Promise<AgentPhaseResult>;
+    /**
+     * Derive a typed {@link SequantError} from structured SDK failure signals
+     * (#732). Precedence: a captured `rate_limit_event` (richest signal) wins;
+     * otherwise the assistant-level `error`; otherwise the last `api_retry`
+     * error. Returns undefined when no rate-limit/billing signal was seen, so
+     * the executor falls back to stderr-regex classification.
+     *
+     * Exception: a non-retryable billing failure must never be downgraded to a
+     * retryable {@link RateLimitError}. If the `rate_limit_event` was only a
+     * transient throttle but the assistant separately reported `billing_error`,
+     * the billing cause wins — a retry cannot refill credits, and a
+     * 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.
+     */
+    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;
     isAvailable(): Promise<boolean>;
 }