sequant 2.8.0 → 2.9.0

package/dist/src/lib/workflow/batch-executor.js

@@ -10,10 +10,11 @@
 import chalk from "chalk";
 import { spawnSync } from "child_process";
 import { createPhaseLogFromTiming } from "./log-writer.js";
-import { classifyError, errorTypeToCategory } from "./error-classifier.js";
+import { classifyError, errorTypeToCategory, } from "./error-classifier.js";
 import { getGitDiffStats, getCommitHash } from "./git-diff-utils.js";
 import { createCheckpointCommit, rebaseBeforePR, createPR, readCacheMetrics, filterResumedPhases, } from "./worktree-manager.js";
 import { executePhaseWithRetry } from "./phase-executor.js";
+import { parseBodyDependencyMarkers } from "./dependency-markers.js";
 import { detectPhasesFromLabels, parseRecommendedWorkflow, determinePhasesForIssue, DOCS_LABELS, } from "./phase-mapper.js";
 import { activateRelay, deactivateRelay, } from "../relay/activation.js";
 /**
@@ -137,17 +138,13 @@ export function parseDependencies(issueNumber) {
             return [];
         const data = JSON.parse(result.stdout.toString());
         const dependencies = [];
-        // Parse from body: "Depends on: #123" or "**Depends on**: #123"
+        // Parse from body: line-leading "Depends on: #123" / "**Depends on**: #123".
+        // Delegates to the shared, hardened parser (#767): mid-sentence prose,
+        // in-fence examples, and inline-code mentions are ignored, and the `#` is
+        // required. Honors ONLY `depends on` — the sorter must not start reordering
+        // on `blocked by`, which would be a new silent-reorder class (#762 Open Q #3).
         if (data.body) {
-            const bodyMatch = data.body.match(/\*?\*?depends\s+on\*?\*?:?\s*#?(\d+)/gi);
-            if (bodyMatch) {
-                for (const match of bodyMatch) {
-                    const numMatch = match.match(/(\d+)/);
-                    if (numMatch) {
-                        dependencies.push(parseInt(numMatch[1], 10));
-                    }
-                }
-            }
+            dependencies.push(...parseBodyDependencyMarkers(data.body, ["depends on"]));
         }
         // Parse from labels: "depends-on/123" or "depends-on-123"
         if (data.labels && Array.isArray(data.labels)) {
@@ -305,6 +302,27 @@ export async function executeBatch(issueNumbers, batchCtx) {
     }
     return results;
 }
+/**
+ * Derive the bounded-enum failure category for a failed issue (#761 AC-7).
+ *
+ * Scans for the LAST non-loop failing phase — the same reverse scan
+ * `toIssueSummary` uses (#766), so the recorded category and the displayed
+ * failure reason describe the same attempt. Prefers the driver's structured
+ * cause over stderr-regex classification (#732). Returns only the enum value;
+ * message strings never leave this function (metrics privacy contract).
+ *
+ * @internal Exported for testing
+ */
+export function deriveFailureCategory(phaseResults) {
+    const failedPhase = [...phaseResults]
+        .reverse()
+        .find((p) => !p.success && p.phase !== "loop");
+    if (!failedPhase)
+        return undefined;
+    const typedError = failedPhase.structuredError ??
+        classifyError(failedPhase.stderrTail ?? [], failedPhase.exitCode);
+    return errorTypeToCategory(typedError);
+}
 export async function runIssueWithLogging(ctx) {
     // Destructure context for use throughout the function
     const { issueNumber, config, options, title: issueTitle, labels, services: { logWriter, stateManager, shutdownManager }, worktree, chain, packageManager, baseBranch, onProgress, onPhasePlan, phasePauseHandle, } = ctx;
@@ -454,10 +472,13 @@ export async function runIssueWithLogging(ctx) {
         // Log spec phase result
         // Note: Spec runs in main repo, not worktree, so no git diff stats
         if (logWriter) {
-            // Build errorContext from captured stderr/stdout tails (#447)
+            // Build errorContext from captured stderr/stdout tails (#447). Prefer
+            // the driver's structured cause (#761 AC-6) — stderr-regex
+            // classification never sees the SDK's rate-limit/billing signals.
             let specErrorContext;
             if (!specResult.success && specResult.stderrTail) {
-                const specError = classifyError(specResult.stderrTail ?? [], specResult.exitCode);
+                const specError = specResult.structuredError ??
+                    classifyError(specResult.stderrTail ?? [], specResult.exitCode);
                 specErrorContext = {
                     stderrTail: specResult.stderrTail ?? [],
                     stdoutTail: specResult.stdoutTail ?? [],
@@ -518,6 +539,7 @@ export async function runIssueWithLogging(ctx) {
                 phaseResults,
                 durationSeconds,
                 loopTriggered: false,
+                failureCategory: deriveFailureCategory(phaseResults),
             };
         }
         // Parse recommended workflow from spec output
@@ -710,10 +732,13 @@ export async function runIssueWithLogging(ctx) {
                     : undefined;
                 // Read cache metrics for QA phase (AC-7)
                 const cacheMetrics = phase === "qa" ? readCacheMetrics(worktreePath) : undefined;
-                // Build errorContext from captured stderr/stdout tails (#447, AC-7/AC-8)
+                // Build errorContext from captured stderr/stdout tails (#447, AC-7/AC-8).
+                // Prefer the driver's structured cause (#761 AC-6) — stderr-regex
+                // classification never sees the SDK's rate-limit/billing signals.
                 let errorContext;
                 if (!result.success && result.stderrTail) {
-                    const typedError = classifyError(result.stderrTail ?? [], result.exitCode);
+                    const typedError = result.structuredError ??
+                        classifyError(result.stderrTail ?? [], result.exitCode);
                     errorContext = {
                         stderrTail: result.stderrTail ?? [],
                         stdoutTail: result.stdoutTail ?? [],
@@ -801,6 +826,23 @@ export async function runIssueWithLogging(ctx) {
                     const loopResult = await executePhaseWithRetry(issueNumber, "loop", withActivityHook(loopConfig, issueNumber, "loop", onProgress), resumeHandle, worktreePath, shutdownManager, phasePauseHandle);
                     const loopEndTime = new Date();
                     phaseResults.push(loopResult);
+                    // #766: record the loop phase in the run log — spec (:655) and the
+                    // regular phases (:982) log via logWriter, but the loop was never
+                    // logged, so a loop that decided the card's verdict was absent from
+                    // the log you'd use to debug it (AC-6). Loop status never determines
+                    // the issue verdict (see deriveIssueLogStatus), but the entry with
+                    // phase/status/duration/error must exist.
+                    if (logWriter) {
+                        const loopPhaseLog = createPhaseLogFromTiming("loop", issueNumber, loopStartTime, loopEndTime, loopResult.success
+                            ? "success"
+                            : loopResult.error?.includes("Timeout")
+                                ? "timeout"
+                                : "failure", {
+                            error: loopResult.error,
+                            capped: loopResult.capped,
+                        });
+                        logWriter.logPhase(loopPhaseLog);
+                    }
                     // Emit loop completion/failure progress event (AC-8)
                     const loopDurationSec = Math.round((loopEndTime.getTime() - loopStartTime.getTime()) / 1000);
                     if (loopResult.success) {
@@ -864,9 +906,25 @@ export async function runIssueWithLogging(ctx) {
             // State tracking errors shouldn't stop execution
         }
     }
-    // Create checkpoint commit in chain mode after QA passes
+    // Create checkpoint commit in chain mode after QA passes.
+    // #760: chain resume rebases the next link onto this checkpoint, so a failure
+    // here is not silent — warn prominently and record it on the result (AC-4).
+    //
+    // Note the status above is already `ready_for_merge`, so a re-run reads this
+    // link as a completed prefix and does NOT redo it. Its uncommitted work is
+    // therefore absent from the branch tip, which `computeChainResumePlan` detects
+    // (dirty worktree → fail fast) rather than wrong-basing the next link. The
+    // message states that outcome exactly: the work must be committed, or --force.
+    let checkpointFailed = false;
     if (success && chainMode && worktreePath) {
-        createCheckpointCommit(worktreePath, issueNumber, config.verbose, baseBranch);
+        const checkpointOk = createCheckpointCommit(worktreePath, issueNumber, config.verbose, baseBranch);
+        if (!checkpointOk) {
+            checkpointFailed = true;
+            log(chalk.yellow(`  ⚠️  Checkpoint commit for #${issueNumber} could not be created — its uncommitted ` +
+                `changes are NOT on branch ${branch ?? "the feature branch"}. #${issueNumber} stays ` +
+                `ready_for_merge, so a re-run will skip it and refuse to resume the chain here until the ` +
+                `work is committed in ${worktreePath} (or re-run with --force to redo the whole chain).`));
+        }
     }
     // Rebase onto the base branch before PR creation (unless --no-rebase)
     // This ensures the branch is up-to-date and prevents lockfile drift
@@ -893,7 +951,10 @@ export async function runIssueWithLogging(ctx) {
                 stackManifest: chain.stackManifest,
             }
             : undefined;
-        const prResult = createPR(worktreePath, issueNumber, issueTitle, branch, config.verbose, labels, stackOptions);
+        // #749: surface a non-A+ qa verdict (e.g. AC_MET_BUT_NOT_A_PLUS) in the PR
+        // body so a reviewer sees why the run broke to PR rather than reaching A+.
+        const qaVerdict = phaseResults.find((p) => p.phase === "qa")?.verdict;
+        const prResult = createPR(worktreePath, issueNumber, issueTitle, branch, config.verbose, labels, stackOptions, qaVerdict);
         if (prResult.success && prResult.prNumber && prResult.prUrl) {
             prNumber = prResult.prNumber;
             prUrl = prResult.prUrl;
@@ -936,5 +997,7 @@ export async function runIssueWithLogging(ctx) {
         loopTriggered,
         prNumber,
         prUrl,
+        checkpointFailed,
+        failureCategory: success ? undefined : deriveFailureCategory(phaseResults),
     };
 }

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

@@ -0,0 +1,89 @@
+/**
+ * Lightweight content pre-flight for `--chain` runs (#762).
+ *
+ * Chain flag-validation only checks flag *combinations* (see `run.ts`); nothing
+ * inspects the *content* of the issues being chained. This module adds a fast,
+ * warn-by-default pre-flight that runs before the first worktree is provisioned
+ * and surfaces four cheap content-level problems:
+ *
+ *   1. An issue has no (or an empty) Acceptance Criteria section.
+ *   2. An issue declares a blocker (`blocked by #N` / `depends on #N`) that runs
+ *      *after* it in the CLI order — the order contradicts the declaration.
+ *   3. Two chained issues are predicted to modify the same file, but the CLI
+ *      order contradicts the predicted (ascending) land order.
+ *   4. An issue is CLOSED on GitHub — chaining a closed/merged issue is almost
+ *      certainly unintended.
+ *
+ * The design follows the #604 philosophy: **suggest, never auto-decide**. False
+ * dependency inference is worse than none, so warnings are non-fatal by default;
+ * `--strict-preflight` opts in to a hard stop.
+ *
+ * Overlap prediction is delegated to `assess-collision-detect` (AC-3) rather
+ * than reimplemented. The pure `computePreflightWarnings` function is the unit
+ * surface (AC-1/AC-5); `runChainPreflight` adds the `gh` fetch and warn-degrades
+ * if a fetch fails — the pre-flight must never be the thing that breaks a run.
+ */
+/** The class of content problem a warning describes. */
+export type PreflightWarningKind = "missing-ac" | "dependency-order" | "file-overlap-order" | "closed-issue";
+/** A single content-level pre-flight warning. */
+export interface PreflightWarning {
+    /** Primary issue the warning is attached to. */
+    issue: number;
+    /** The class of problem (one warning per class per AC-1). */
+    kind: PreflightWarningKind;
+    /** Human-readable, ready to print after a `⚠` prefix. */
+    message: string;
+}
+/** Fetched issue content the pure computation operates over. */
+export interface PreflightIssue {
+    number: number;
+    /** Raw issue body markdown. */
+    body: string;
+    /** GitHub issue state, e.g. `"OPEN"` / `"CLOSED"`. */
+    state: string;
+    /** Issue title (for message context). */
+    title: string;
+}
+/**
+ * Parse the issue numbers a body declares itself blocked by / dependent on.
+ * Catches both `depends on #N` and `blocked by #N` (deduped, order-preserving).
+ * Only line-leading markers count as declarations — see the shared
+ * `dependency-markers.ts` parser for why mid-sentence prose mentions are
+ * deliberately ignored.
+ *
+ * The pre-flight honors BOTH markers (unlike `batch-executor.ts`, which honors
+ * only `depends on` so the sorter's ordering semantics stay untouched — #762
+ * Open Q #3). The hardened mechanics are shared; the marker set is per-caller.
+ */
+export declare function parseDeclaredBlockers(body: string): number[];
+/**
+ * Detect whether a body has a non-empty Acceptance Criteria section.
+ *
+ * Fast path reuses `hasAcceptanceCriteria` (ac-parser) so `AC-N:`-prefixed
+ * checklists are recognized directly. The fallback catches AC sections written
+ * as bare checkboxes under an "Acceptance Criteria" heading (e.g. this very
+ * issue, #762) — those are legitimately non-empty AC sections that the
+ * `AC-N:` patterns don't match, and warning on them would be a false positive
+ * (worse than no warning, per #604).
+ */
+export declare function hasNonEmptyAcSection(body: string): boolean;
+/**
+ * Compute chain pre-flight warnings over already-fetched issue content.
+ *
+ * Pure and deterministic — this is the unit-test surface (AC-1/AC-5). Issues
+ * absent from `issues` (e.g. a `gh` fetch failed for them) are silently skipped
+ * so a fetch error degrades to fewer checks rather than aborting the run.
+ *
+ * @param cliOrder Raw CLI issue order (NOT dep-sorted — see #762 Open Q #1).
+ * @param issues   Map of issue number → fetched content.
+ */
+export declare function computePreflightWarnings(cliOrder: number[], issues: Map<number, PreflightIssue>): PreflightWarning[];
+/**
+ * Run the chain content pre-flight: fetch each issue's body/state/title, then
+ * compute warnings. Fetch failures warn-degrade (a gray note is printed and the
+ * issue's checks are skipped) — the pre-flight never aborts a run on its own.
+ *
+ * @param cliOrder Raw CLI issue order (NOT dep-sorted).
+ * @returns The list of content warnings (empty when everything looks consistent).
+ */
+export declare function runChainPreflight(cliOrder: number[]): Promise<PreflightWarning[]>;

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

@@ -0,0 +1,199 @@
+/**
+ * Lightweight content pre-flight for `--chain` runs (#762).
+ *
+ * Chain flag-validation only checks flag *combinations* (see `run.ts`); nothing
+ * inspects the *content* of the issues being chained. This module adds a fast,
+ * warn-by-default pre-flight that runs before the first worktree is provisioned
+ * and surfaces four cheap content-level problems:
+ *
+ *   1. An issue has no (or an empty) Acceptance Criteria section.
+ *   2. An issue declares a blocker (`blocked by #N` / `depends on #N`) that runs
+ *      *after* it in the CLI order — the order contradicts the declaration.
+ *   3. Two chained issues are predicted to modify the same file, but the CLI
+ *      order contradicts the predicted (ascending) land order.
+ *   4. An issue is CLOSED on GitHub — chaining a closed/merged issue is almost
+ *      certainly unintended.
+ *
+ * The design follows the #604 philosophy: **suggest, never auto-decide**. False
+ * dependency inference is worse than none, so warnings are non-fatal by default;
+ * `--strict-preflight` opts in to a hard stop.
+ *
+ * Overlap prediction is delegated to `assess-collision-detect` (AC-3) rather
+ * than reimplemented. The pure `computePreflightWarnings` function is the unit
+ * surface (AC-1/AC-5); `runChainPreflight` adds the `gh` fetch and warn-degrades
+ * if a fetch fails — the pre-flight must never be the thing that breaks a run.
+ */
+import { spawnSync } from "child_process";
+import chalk from "chalk";
+import { hasAcceptanceCriteria } from "../ac-parser.js";
+import { extractPathsFromIssueBody, detectFileCollisions, } from "../assess-collision-detect.js";
+import { parseBodyDependencyMarkers } from "./dependency-markers.js";
+/**
+ * Parse the issue numbers a body declares itself blocked by / dependent on.
+ * Catches both `depends on #N` and `blocked by #N` (deduped, order-preserving).
+ * Only line-leading markers count as declarations — see the shared
+ * `dependency-markers.ts` parser for why mid-sentence prose mentions are
+ * deliberately ignored.
+ *
+ * The pre-flight honors BOTH markers (unlike `batch-executor.ts`, which honors
+ * only `depends on` so the sorter's ordering semantics stay untouched — #762
+ * Open Q #3). The hardened mechanics are shared; the marker set is per-caller.
+ */
+export function parseDeclaredBlockers(body) {
+    return parseBodyDependencyMarkers(body, ["depends on", "blocked by"]);
+}
+/**
+ * Detect whether a body has a non-empty Acceptance Criteria section.
+ *
+ * Fast path reuses `hasAcceptanceCriteria` (ac-parser) so `AC-N:`-prefixed
+ * checklists are recognized directly. The fallback catches AC sections written
+ * as bare checkboxes under an "Acceptance Criteria" heading (e.g. this very
+ * issue, #762) — those are legitimately non-empty AC sections that the
+ * `AC-N:` patterns don't match, and warning on them would be a false positive
+ * (worse than no warning, per #604).
+ */
+export function hasNonEmptyAcSection(body) {
+    if (hasAcceptanceCriteria(body))
+        return true;
+    const lines = body.split("\n");
+    let inSection = false;
+    for (const line of lines) {
+        if (/^#{1,6}\s+.*acceptance\s+criteria/i.test(line)) {
+            inSection = true;
+            continue;
+        }
+        // A subsequent heading closes the AC section.
+        if (inSection && /^#{1,6}\s+/.test(line))
+            break;
+        // A checkbox item inside the section proves it is non-empty.
+        if (inSection && /^\s*-\s*\[[x\s]\]/i.test(line))
+            return true;
+    }
+    return false;
+}
+/**
+ * Compute chain pre-flight warnings over already-fetched issue content.
+ *
+ * Pure and deterministic — this is the unit-test surface (AC-1/AC-5). Issues
+ * absent from `issues` (e.g. a `gh` fetch failed for them) are silently skipped
+ * so a fetch error degrades to fewer checks rather than aborting the run.
+ *
+ * @param cliOrder Raw CLI issue order (NOT dep-sorted — see #762 Open Q #1).
+ * @param issues   Map of issue number → fetched content.
+ */
+export function computePreflightWarnings(cliOrder, issues) {
+    const warnings = [];
+    const positionOf = new Map();
+    cliOrder.forEach((n, i) => positionOf.set(n, i));
+    // Per-issue checks, in CLI order for deterministic output.
+    for (const num of cliOrder) {
+        const issue = issues.get(num);
+        if (!issue)
+            continue;
+        // AC-4: closed/merged issue check (consistent with the #305 state guard).
+        if (issue.state.toUpperCase() === "CLOSED") {
+            warnings.push({
+                issue: num,
+                kind: "closed-issue",
+                message: `#${num} is CLOSED on GitHub — chaining a closed/merged issue is ` +
+                    `likely unintended (consistent with the #305 ready_for_merge/merged ` +
+                    `guard; the #592 in_progress-but-merged gap is not covered here).`,
+            });
+        }
+        // AC-1: missing/empty Acceptance Criteria section.
+        if (!hasNonEmptyAcSection(issue.body)) {
+            warnings.push({
+                issue: num,
+                kind: "missing-ac",
+                message: `#${num} has no non-empty Acceptance Criteria section — the chain ` +
+                    `cannot verify it is ready to implement.`,
+            });
+        }
+        // AC-1: CLI order contradicts a declared dependency marker.
+        for (const blocker of parseDeclaredBlockers(issue.body)) {
+            const blockerPos = positionOf.get(blocker);
+            // Only meaningful if the blocker is itself in this chain.
+            if (blockerPos === undefined)
+                continue;
+            if (blockerPos > positionOf.get(num)) {
+                warnings.push({
+                    issue: num,
+                    kind: "dependency-order",
+                    message: `#${num} declares it is blocked by / depends on #${blocker}, but ` +
+                        `#${blocker} runs AFTER #${num} in the chain order — reorder so ` +
+                        `#${blocker} comes first.`,
+                });
+            }
+        }
+    }
+    // AC-1/AC-3: CLI order contradicts predicted file-overlap order.
+    const issuePaths = new Map();
+    for (const num of cliOrder) {
+        const issue = issues.get(num);
+        if (issue)
+            issuePaths.set(num, extractPathsFromIssueBody(issue.body));
+    }
+    for (const collision of detectFileCollisions(issuePaths)) {
+        // `collision.issues` is ascending issue-number order = the predicted land
+        // order used by /assess. Restrict to issues actually in the chain.
+        const predicted = collision.issues.filter((n) => positionOf.has(n));
+        if (predicted.length < 2)
+            continue;
+        const cliRelative = [...predicted].sort((a, b) => positionOf.get(a) - positionOf.get(b));
+        const contradicts = predicted.some((n, i) => n !== cliRelative[i]);
+        if (contradicts) {
+            warnings.push({
+                issue: predicted[0],
+                kind: "file-overlap-order",
+                message: `#${predicted.join(", #")} are predicted to modify ${collision.file}; ` +
+                    `predicted land order is #${predicted.join(" → #")} but the CLI order ` +
+                    `is #${cliRelative.join(" → #")} — landing out of order risks the ` +
+                    `downstream-staleness class (#133).`,
+            });
+        }
+    }
+    return warnings;
+}
+/**
+ * Fetch a single issue's pre-flight content via `gh`. Returns `null` on any
+ * failure so the caller can warn-degrade (skip that issue's checks) rather than
+ * abort the run.
+ */
+function fetchPreflightIssue(issueNumber) {
+    try {
+        const result = spawnSync("gh", ["issue", "view", String(issueNumber), "--json", "body,state,title"], { stdio: "pipe" });
+        if (result.status !== 0)
+            return null;
+        const data = JSON.parse(result.stdout.toString());
+        return {
+            number: issueNumber,
+            body: typeof data.body === "string" ? data.body : "",
+            state: typeof data.state === "string" ? data.state : "",
+            title: typeof data.title === "string" ? data.title : `Issue #${issueNumber}`,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Run the chain content pre-flight: fetch each issue's body/state/title, then
+ * compute warnings. Fetch failures warn-degrade (a gray note is printed and the
+ * issue's checks are skipped) — the pre-flight never aborts a run on its own.
+ *
+ * @param cliOrder Raw CLI issue order (NOT dep-sorted).
+ * @returns The list of content warnings (empty when everything looks consistent).
+ */
+export async function runChainPreflight(cliOrder) {
+    const issues = new Map();
+    for (const num of cliOrder) {
+        const fetched = fetchPreflightIssue(num);
+        if (fetched) {
+            issues.set(num, fetched);
+        }
+        else {
+            console.log(chalk.gray(`  (pre-flight: could not fetch #${num} — skipping its content checks)`));
+        }
+    }
+    return computePreflightWarnings(cliOrder, issues);
+}

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>;