sequant 2.9.0 → 2.11.0

package/dist/src/lib/workflow/run-orchestrator.js

@@ -27,6 +27,8 @@ function formatSignalLine(issue, pid, result) {
             return `  Refused to signal PID ${pid} for #${issue} (matches this process or its parent)`;
         case "pid-dead":
             return `  Could not signal PID ${pid} for #${issue} (already exited)`;
+        case "stale-pid-untrusted":
+            return `  Refused to signal PID ${pid} for #${issue} (lock is past the age ceiling; that PID has likely been recycled)`;
         case "kill-failed":
             return `  Could not signal PID ${pid} for #${issue} (kill syscall failed)`;
         case "orchestrator":
@@ -69,11 +71,13 @@ function isWorktreeDirty(worktreePath) {
     }
     return result.stdout.trim().length > 0;
 }
-import { getIssueInfo, sortByDependencies, parseBatches, runIssueWithLogging, emitRunIdLine, } from "./batch-executor.js";
+import { getIssueInfo, sortByDependencies, parseBatches, runIssueWithLogging, recordIssueCompletion, emitRunIdLine, } from "./batch-executor.js";
 import { reconcileStateAtStartup } from "./state-utils.js";
 import { runChainPreflight } from "./chain-preflight.js";
+import { runSkillsPreflight } from "./skills-preflight.js";
 import { getCommitHash } from "./git-diff-utils.js";
 import { planChainResumeFromState, } from "./chain-resume.js";
+import { isCompletedIssueStatus } from "./completed-status.js";
 import { MetricsWriter } from "./metrics-writer.js";
 import { WorkflowEventEmitter } from "./event-emitter.js";
 import { determineOutcome } from "./metrics-schema.js";
@@ -131,6 +135,20 @@ export class RunOrchestrator {
     getEmitter() {
         return this.emitter;
     }
+    /**
+     * The wrapped progress sink handed to the batch executor — every phase
+     * lifecycle event enters the orchestrator through here.
+     *
+     * @internal Exported for testing only. `applyProgressEvent` is private and
+     * depends on `issueStates`/`phaseStartTimes`/`emitter`, so there is no way
+     * to exercise its branches short of a full `run()`. Without this seam the
+     * #804 `waiting` branch would be untestable — and an untested `waiting`
+     * branch is not cosmetic: falling through to the complete/failed handler
+     * marks a merely-paused phase `failed` and emits `phase_failed`.
+     */
+    getProgressCallback() {
+        return this.cfg.onProgress;
+    }
     /**
      * Point-in-time view of the entire run.
      *
@@ -197,6 +215,16 @@ export class RunOrchestrator {
             const wasStatus = state.status;
             if (!state.startedAt)
                 state.startedAt = new Date();
+            // #866: a phase starting means the issue is live again, so any
+            // `completedAt` from an earlier terminal verdict is stale and must not
+            // outlive it. The #766 quality-loop recovery path reaches here holding
+            // one: a non-loop failure pins `failed` and stamps `completedAt` below,
+            // then iteration 2 re-runs the phase through this branch. Leaving it set
+            // published a completion time for a running issue — which froze the TUI's
+            // header clock for the whole recovery window. `startedAt` is deliberately
+            // NOT reset: the header measures the issue's total wall clock, spanning
+            // every iteration.
+            state.completedAt = undefined;
             state.status = "running";
             const now = new Date();
             this.phaseStartTimes.set(`${issue}:${phase}`, now.getTime());
@@ -224,6 +252,25 @@ export class RunOrchestrator {
             }
             return;
         }
+        // #804 AC-7: an auto-wait is a *paused running* phase, not a terminal one.
+        // This branch must precede the complete/failed fall-through below, which
+        // would otherwise close out the phase the moment a wait began. Surfaces the
+        // wait through the same `nowLine` the TUI already renders.
+        if (event === "waiting") {
+            if (!state.currentPhase || state.currentPhase.name !== phase)
+                return;
+            const line = extra?.text;
+            if (!line)
+                return;
+            state.currentPhase.nowLine = line;
+            state.currentPhase.lastActivityAt = new Date();
+            void this.emitter.emit("progress", {
+                issueNumber: issue,
+                phase,
+                text: line,
+            });
+            return;
+        }
         if (event === "activity") {
             // Ignore activity for stale phases (race between completion and a
             // final flushed output chunk).
@@ -369,6 +416,15 @@ export class RunOrchestrator {
      */
     static async run(init, issueArgs, batches) {
         const { manifest, onProgress, phasePauseHandle, settings } = init;
+        // #867: capture the run's start before any service/log setup, so wall clock
+        // is independent of whether the log writer exists (AC-3: correct under
+        // --no-log and when log init fails). This single origin is the source of
+        // truth for both the printed summary and the run log (AC-2).
+        const runStartedAt = Date.now();
+        // Every `return` below — the success path and all six early exits — closes
+        // the bracket the same way, so the subtraction lives in one place rather
+        // than being restated per exit and left to drift.
+        const wallClock = () => (Date.now() - runStartedAt) / 1000;
         // ── Config resolution ──────────────────────────────────────────────
         const resolved = RunOrchestrator.resolveConfig(init, issueArgs, batches);
         const { mergedOptions, config, baseBranch } = resolved;
@@ -384,6 +440,7 @@ export class RunOrchestrator {
                 config,
                 mergedOptions,
                 logWriter: null,
+                wallClockDurationSeconds: wallClock(),
             };
         }
         // ── Services setup ─────────────────────────────────────────────────
@@ -405,6 +462,10 @@ export class RunOrchestrator {
                     logPath: mergedOptions.logPath ?? settings.run.logPath,
                     verbose: config.verbose,
                     startCommit: getCommitHash(process.cwd()),
+                    // #867: share the orchestrator's run origin so the log's stored
+                    // wall clock (finalizeRunLog: (end-start)/1000) is derived from the
+                    // same start as the summary — AC-2/AC-7 (one producer, two consumers).
+                    startTime: new Date(runStartedAt),
                 });
                 await logWriter.initialize(runConfig);
                 const runId = logWriter.getRunId();
@@ -424,8 +485,12 @@ export class RunOrchestrator {
         const shutdown = new ShutdownManager();
         if (logWriter) {
             const writer = logWriter;
-            shutdown.registerCleanup("Finalize run logs", async () => {
-                await writer.finalize();
+            // #856: forward the abort cause into the log. This cleanup runs on the
+            // SIGINT/SIGTERM path, where no phase result will ever arrive for the
+            // in-flight issue — without the context, `finalize()` writes that issue
+            // out as if the run had simply ended.
+            shutdown.registerCleanup("Finalize run logs", async (abort) => {
+                await writer.finalize(abort ? { aborted: abort } : undefined);
             });
         }
         // ── Pre-flight state guard ─────────────────────────────────────────
@@ -478,6 +543,7 @@ export class RunOrchestrator {
                         config,
                         mergedOptions,
                         logWriter: null,
+                        wallClockDurationSeconds: wallClock(),
                     };
                 }
                 if (plan.allComplete) {
@@ -492,6 +558,7 @@ export class RunOrchestrator {
                         config,
                         mergedOptions,
                         logWriter: null,
+                        wallClockDurationSeconds: wallClock(),
                     };
                 }
                 if (plan.skipped.length > 0) {
@@ -513,9 +580,7 @@ export class RunOrchestrator {
                 for (const issueNumber of issueNumbers) {
                     try {
                         const issueState = await stateManager.getIssueState(issueNumber);
-                        if (issueState &&
-                            (issueState.status === "ready_for_merge" ||
-                                issueState.status === "merged")) {
+                        if (issueState && isCompletedIssueStatus(issueState.status)) {
                             console.log(chalk.yellow(`  !  #${issueNumber}: already ${issueState.status} — skipping (use --force to re-run)`));
                         }
                         else {
@@ -541,6 +606,7 @@ export class RunOrchestrator {
                             config,
                             mergedOptions,
                             logWriter: null,
+                            wallClockDurationSeconds: wallClock(),
                         };
                     }
                 }
@@ -600,6 +666,7 @@ export class RunOrchestrator {
                     config,
                     mergedOptions,
                     logWriter: null,
+                    wallClockDurationSeconds: wallClock(),
                 };
             }
         }
@@ -630,6 +697,7 @@ export class RunOrchestrator {
                         config,
                         mergedOptions,
                         logWriter: null,
+                        wallClockDurationSeconds: wallClock(),
                     };
                 }
             }
@@ -639,6 +707,49 @@ export class RunOrchestrator {
         for (const issueNumber of issueNumbers) {
             issueInfoMap.set(issueNumber, await getIssueInfo(issueNumber));
         }
+        // ── Skills pre-flight (#813) ───────────────────────────────────────
+        // Fail fast when the driver resolves phases via `.claude/skills/` and a
+        // required skill is missing — BEFORE any worktree is provisioned or
+        // per-issue state entry written. Without this, the phase agent hunts for
+        // a slash command that can never resolve and the run surfaces as a bogus
+        // "spec retry" failure. Skipped for non-skill drivers (aider) and for
+        // --dry-run (no agent executes).
+        if (!config.dryRun) {
+            const preflight = await runSkillsPreflight({
+                agent: config.agent,
+                aiderSettings: config.aiderSettings,
+                phases: config.phases,
+                autoDetectPhases: resolved.autoDetectPhases,
+                qualityLoop: config.qualityLoop,
+                testgen: mergedOptions.testgen,
+                securityReview: mergedOptions.securityReview,
+                issueNumbers,
+                issueInfoMap,
+            });
+            if (!preflight.ok) {
+                bracketedConsoleLog(phasePauseHandle, chalk.red(`\n  ✖ Skills pre-flight failed: ${preflight.cause}`));
+                bracketedConsoleLog(phasePauseHandle, chalk.red(`    ${preflight.remedy}`));
+                shutdown.dispose();
+                return {
+                    results: issueNumbers.map((issueNumber) => ({
+                        issueNumber,
+                        success: false,
+                        phaseResults: [],
+                        durationSeconds: 0,
+                        loopTriggered: false,
+                        abortReason: `skills pre-flight failed: ${preflight.cause}`,
+                    })),
+                    logPath: null,
+                    exitCode: 1,
+                    worktreeMap: new Map(),
+                    issueInfoMap,
+                    config,
+                    mergedOptions,
+                    logWriter: null,
+                    wallClockDurationSeconds: wallClock(),
+                };
+            }
+        }
         const useWorktreeIsolation = mergedOptions.worktreeIsolation !== false && issueNumbers.length > 0;
         let worktreeMap = new Map();
         if (useWorktreeIsolation && !config.dryRun) {
@@ -710,10 +821,15 @@ export class RunOrchestrator {
                     endCommit: getCommitHash(process.cwd()),
                 });
             }
+            // #867: the run's wall clock, computed once from the single origin. Both
+            // the metrics record and the RunResult below derive from this value — no
+            // consumer re-sums per-issue durations (which double-counts under
+            // --parallel). Same notion the log stores via finalizeRunLog above.
+            const wallClockDurationSeconds = wallClock();
             // ── Record metrics ─────────────────────────────────────────────
             if (!config.dryRun && results.length > 0) {
                 try {
-                    await RunOrchestrator.recordMetrics(config, mergedOptions, results, worktreeMap, issueNumbers);
+                    await RunOrchestrator.recordMetrics(config, mergedOptions, results, worktreeMap, issueNumbers, wallClockDurationSeconds);
                 }
                 catch (metricsError) {
                     logNonFatalWarning("  !  Metrics recording failed, continuing...", metricsError, config.verbose);
@@ -729,6 +845,7 @@ export class RunOrchestrator {
                 config,
                 mergedOptions,
                 logWriter,
+                wallClockDurationSeconds,
             };
         }
         finally {
@@ -925,14 +1042,13 @@ export class RunOrchestrator {
                     : undefined,
             });
             results.push(result);
-            if (!result.success) {
-                if (options.qaGate && options.chain) {
-                    const qaFailed = result.phaseResults.some((p) => p.phase === "qa" && !p.success);
-                    if (qaFailed)
-                        break;
-                }
+            // A chain halts on ANY failed link, QA or otherwise: every successor
+            // rebases onto its predecessor's committed work, so continuing past a
+            // failure would build on a broken or absent base. #795 removed a
+            // `--qa-gate` branch here that re-tested for a QA failure before this
+            // same unconditional break — it could never change the outcome.
+            if (!result.success)
                 break;
-            }
         }
         return results;
     }
@@ -1017,11 +1133,12 @@ export class RunOrchestrator {
                     });
                 }
             }
-            if (logWriter && result.prNumber && result.prUrl) {
-                logWriter.setPRInfo(result.prNumber, result.prUrl, parallelIssueNumber);
-            }
+            // Record PR info, flip status on a PR-creation failure (#879), and
+            // finalize — via the shared helper so this live path stays in lockstep
+            // with executeBatch. Before #879 this block omitted the failure flip, so
+            // a real `sequant run` left the run-log status at `success` on PR failure.
             if (logWriter) {
-                logWriter.completeIssue(parallelIssueNumber);
+                recordIssueCompletion(logWriter, result, parallelIssueNumber);
             }
             return result;
         }
@@ -1034,9 +1151,13 @@ export class RunOrchestrator {
             });
         }
     }
-    static async recordMetrics(config, mergedOptions, results, worktreeMap, issueNumbers) {
+    static async recordMetrics(config, mergedOptions, results, worktreeMap, issueNumbers, wallClockDurationSeconds) {
         const metricsWriter = new MetricsWriter({ verbose: config.verbose });
-        const totalDuration = results.reduce((sum, r) => sum + (r.durationSeconds ?? 0), 0);
+        // #867: run wall clock, not the sum of per-issue durations — under
+        // --parallel that sum double-counts overlapping issues (same defect the
+        // SUMMARY header had). The orchestrator owns the run's start/end and passes
+        // the single authoritative value in.
+        const totalDuration = wallClockDurationSeconds;
         const allPhases = new Set();
         for (const result of results) {
             for (const pr of result.phaseResults) {
@@ -1086,6 +1207,29 @@ export class RunOrchestrator {
         // issue is the halting one; in parallel runs it is the earliest-listed
         // failure. Undefined on success — the field is omitted from the record.
         const failureCategory = results.find((r) => !r.success && r.failureCategory)?.failureCategory;
+        // #915: one entry per escalated phase execution, from both retry sites —
+        // the outer quality loop (`phaseResults[].escalatedEffort`) and the
+        // `--ready-gate` QA-pass loop (`readyGate.effortEscalations`).
+        const effortEscalations = [
+            ...results.flatMap((r) => r.phaseResults
+                .filter((p) => p.escalatedEffort)
+                .map((p) => ({
+                phase: p.phase,
+                base: p.escalatedEffort.base,
+                escalated: p.escalatedEffort.escalated,
+            }))),
+            ...results.flatMap((r) => r.readyGate?.effortEscalations ?? []),
+        ];
+        // #915: the outer quality loop already logs its own escalations live at
+        // the batch-executor dispatch site — only the `--ready-gate` QA-pass loop
+        // has no equivalent live print, so surface those here.
+        if (config.verbose) {
+            for (const r of results) {
+                for (const e of r.readyGate?.effortEscalations ?? []) {
+                    console.log(chalk.gray(`  effort: ${e.base} → ${e.escalated} (ready-gate retry, #${r.issueNumber})`));
+                }
+            }
+        }
         await metricsWriter.recordRun({
             issues: issueNumbers,
             phases: Array.from(allPhases),
@@ -1094,6 +1238,10 @@ export class RunOrchestrator {
             model: process.env.ANTHROPIC_MODEL ?? "opus",
             flags: cliFlags,
             failureCategory,
+            // #914: resolved per-phase model/effort, when any phase had one.
+            phasePolicies: config.phasePolicies,
+            // #915: escalated tiers, when any phase execution escalated.
+            effortEscalations,
             metrics: {
                 tokensUsed: tokenUsage.tokensUsed,
                 filesChanged: totalFilesChanged,

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

@@ -0,0 +1,89 @@
+/**
+ * Skills pre-flight for `sequant run` (#813).
+ *
+ * The claude-code driver executes phases as slash-command skills loaded from
+ * project scope only (`settingSources: ["project"]`, #19/#711). Without
+ * `.claude/skills/` the phase agent hunts for a command that can never
+ * resolve, does no work, and the run surfaces as a bogus "spec retry"
+ * failure. This module computes the skills a run actually needs — from the
+ * phases resolved for that run, not a hardcoded triple — and checks them via
+ * the same `checkSkillsInstalled` helper `doctor` uses, so the two cannot
+ * drift.
+ *
+ * Drivers whose phase prompts do the work inline (aider's `driverOverrides`
+ * templates in phase-registry.ts) never resolve skills, so the pre-flight is
+ * skipped for them via `AgentDriver.resolvesSkills`.
+ */
+import type { AiderSettings } from "../settings.js";
+import type { Phase } from "./types.js";
+export interface SkillsPreflightInput {
+    /** Agent driver name (default claude-code). */
+    agent?: string;
+    /** Aider settings, forwarded to the driver factory. */
+    aiderSettings?: AiderSettings;
+    /** Base pipeline for explicit-phase runs (`config.phases`). */
+    phases: Phase[];
+    /** True when phases are auto-detected from labels (no explicit --phases). */
+    autoDetectPhases: boolean;
+    /** True when the quality loop may invoke the loop skill. */
+    qualityLoop: boolean;
+    /** Additive phase flags (`--testgen` / `--security-review`). */
+    testgen?: boolean;
+    securityReview?: boolean;
+    /** Issues in the run, with their labels (drives per-issue phase rules). */
+    issueNumbers: number[];
+    issueInfoMap: Map<number, {
+        title: string;
+        labels: string[];
+    }>;
+    /** Project root to check under (default: `process.cwd()`). */
+    cwd?: string;
+}
+export type SkillsPreflightResult = {
+    ok: true;
+} | {
+    ok: false;
+    /** Human-readable cause, e.g. `missing skills: spec, exec, qa`. */
+    cause: string;
+    /** Missing skill names, in required order. */
+    missingSkills: string[];
+    /** Driver whose skill resolution triggered the check. */
+    driverName: string;
+    /** Remedy line for display. */
+    remedy: string;
+};
+/**
+ * Compute the union of skills required by the phases resolved for this run.
+ *
+ * Explicit-phase runs start from `phases` as given; auto-detect runs start
+ * from each issue's label-detected pipeline. Both then apply the additive
+ * `--testgen` / `--security-review` / UI-label rules via
+ * `determinePhasesForIssue`.
+ *
+ * Two deliberate over-approximations keep late-added phases covered:
+ *
+ * - An explicit `--testgen` / `--security-review` flag requires its skill
+ *   unconditionally, even when `determinePhasesForIssue` would not insert
+ *   the phase because `spec` is absent from the pipeline. On a resume where
+ *   spec already completed, batch-executor inserts the phase anyway
+ *   (`phases.includes("spec") || specAlreadyRan`), and the pre-flight cannot
+ *   cheaply know `specAlreadyRan` — requiring the skill the user asked for
+ *   is the safe superset.
+ * - The loop skill is required when the quality loop is enabled up front OR
+ *   when any issue's labels would auto-enable it (`complex`/`refactor`/...,
+ *   via `detectPhasesFromLabels().qualityLoop`), since the loop skill is
+ *   invoked the same way as any phase skill.
+ *
+ * Phases recommended later by spec output (`parseRecommendedWorkflow`)
+ * remain unknowable at pre-flight time — the accepted gap documented on
+ * #813.
+ *
+ * Exported for direct unit testing (AC-2).
+ */
+export declare function resolveRequiredSkills(input: Pick<SkillsPreflightInput, "phases" | "autoDetectPhases" | "qualityLoop" | "testgen" | "securityReview" | "issueNumbers" | "issueInfoMap">): string[];
+/**
+ * Run the skills pre-flight. Returns `{ok: true}` when the run may proceed:
+ * either every required skill is installed, or the selected driver does not
+ * resolve skills at all (AC-3).
+ */
+export declare function runSkillsPreflight(input: SkillsPreflightInput): Promise<SkillsPreflightResult>;

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

@@ -0,0 +1,112 @@
+/**
+ * Skills pre-flight for `sequant run` (#813).
+ *
+ * The claude-code driver executes phases as slash-command skills loaded from
+ * project scope only (`settingSources: ["project"]`, #19/#711). Without
+ * `.claude/skills/` the phase agent hunts for a command that can never
+ * resolve, does no work, and the run surfaces as a bogus "spec retry"
+ * failure. This module computes the skills a run actually needs — from the
+ * phases resolved for that run, not a hardcoded triple — and checks them via
+ * the same `checkSkillsInstalled` helper `doctor` uses, so the two cannot
+ * drift.
+ *
+ * Drivers whose phase prompts do the work inline (aider's `driverOverrides`
+ * templates in phase-registry.ts) never resolve skills, so the pre-flight is
+ * skipped for them via `AgentDriver.resolvesSkills`.
+ */
+import { getDriver } from "./drivers/index.js";
+import { detectPhasesFromLabels, determinePhasesForIssue, } from "./phase-mapper.js";
+import { phaseRegistry } from "./phase-registry.js";
+import { checkSkillsInstalled, SKILLS_DIR } from "../skills-check.js";
+/**
+ * Compute the union of skills required by the phases resolved for this run.
+ *
+ * Explicit-phase runs start from `phases` as given; auto-detect runs start
+ * from each issue's label-detected pipeline. Both then apply the additive
+ * `--testgen` / `--security-review` / UI-label rules via
+ * `determinePhasesForIssue`.
+ *
+ * Two deliberate over-approximations keep late-added phases covered:
+ *
+ * - An explicit `--testgen` / `--security-review` flag requires its skill
+ *   unconditionally, even when `determinePhasesForIssue` would not insert
+ *   the phase because `spec` is absent from the pipeline. On a resume where
+ *   spec already completed, batch-executor inserts the phase anyway
+ *   (`phases.includes("spec") || specAlreadyRan`), and the pre-flight cannot
+ *   cheaply know `specAlreadyRan` — requiring the skill the user asked for
+ *   is the safe superset.
+ * - The loop skill is required when the quality loop is enabled up front OR
+ *   when any issue's labels would auto-enable it (`complex`/`refactor`/...,
+ *   via `detectPhasesFromLabels().qualityLoop`), since the loop skill is
+ *   invoked the same way as any phase skill.
+ *
+ * Phases recommended later by spec output (`parseRecommendedWorkflow`)
+ * remain unknowable at pre-flight time — the accepted gap documented on
+ * #813.
+ *
+ * Exported for direct unit testing (AC-2).
+ */
+export function resolveRequiredSkills(input) {
+    const additiveFlags = {
+        testgen: input.testgen,
+        securityReview: input.securityReview,
+    };
+    const requiredPhases = new Set();
+    let qualityLoop = input.qualityLoop;
+    for (const issueNumber of input.issueNumbers) {
+        const labels = input.issueInfoMap.get(issueNumber)?.labels ?? [];
+        const detected = input.autoDetectPhases
+            ? detectPhasesFromLabels(labels)
+            : null;
+        if (detected?.qualityLoop)
+            qualityLoop = true;
+        const basePhases = detected ? detected.phases : input.phases;
+        for (const phase of determinePhasesForIssue(basePhases, labels, additiveFlags)) {
+            requiredPhases.add(phase);
+        }
+    }
+    if (input.testgen)
+        requiredPhases.add("testgen");
+    if (input.securityReview)
+        requiredPhases.add("security-review");
+    if (qualityLoop)
+        requiredPhases.add("loop");
+    return [...requiredPhases].map((phase) => phaseRegistry.get(phase).skill);
+}
+/**
+ * Run the skills pre-flight. Returns `{ok: true}` when the run may proceed:
+ * either every required skill is installed, or the selected driver does not
+ * resolve skills at all (AC-3).
+ */
+export async function runSkillsPreflight(input) {
+    let driver;
+    try {
+        driver = getDriver(input.agent, {
+            aiderSettings: input.aiderSettings,
+        });
+    }
+    catch {
+        // Unknown driver name (bad `settings.run.agent`). Don't let the
+        // pre-flight be the thing that crashes the run with a raw throw —
+        // skip it and let phase-executor surface the unknown-driver error
+        // through its normal per-issue failure path.
+        return { ok: true };
+    }
+    if (!driver.resolvesSkills)
+        return { ok: true };
+    const requiredSkills = resolveRequiredSkills(input);
+    const { skillsDirExists, missingSkills } = await checkSkillsInstalled(requiredSkills, input.cwd);
+    if (missingSkills.length === 0)
+        return { ok: true };
+    const cause = skillsDirExists
+        ? `missing skills: ${missingSkills.join(", ")}`
+        : `missing ${SKILLS_DIR}/ directory (needs: ${missingSkills.join(", ")})`;
+    return {
+        ok: false,
+        cause,
+        missingSkills,
+        driverName: driver.name,
+        remedy: `The ${driver.name} driver resolves phases from ${SKILLS_DIR}/ — ` +
+            `run \`sequant sync\` to install them, then re-run.`,
+    };
+}

package/dist/src/lib/workflow/spec-recommendation.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Structured resolution of the spec→run phase recommendation (#921).
+ *
+ * `parseRecommendedWorkflow` (phase-mapper.ts) regexes the spec agent's
+ * *ephemeral chat text* for a `## Recommended Workflow` section. When the
+ * spec agent posts its plan via a body file instead of restating it in
+ * chat, that regex has nothing to match and the run silently falls back to
+ * label-based phase detection — dropping any recommended phase the label
+ * fallback can never produce (e.g. `testgen`). See #814.
+ *
+ * This module resolves the recommendation through an ordered chain, each
+ * step falling through loudly to the next on failure:
+ *
+ *   1. `marker`         — the durable `<!-- SEQUANT_SPEC: {json} --> `
+ *                          comment marker (this issue's fix)
+ *   2. `comment-prose`  — the same regex as `chat`, applied to the spec
+ *                          plan's GitHub comment body instead of chat text
+ *   3. `chat`           — `parseRecommendedWorkflow` over the agent's
+ *                          captured chat output (existing behavior)
+ *   4. `label-fallback` — `detectPhasesFromLabels` (existing behavior)
+ *
+ * The durable comment marker is the system's existing idiom — see
+ * `SEQUANT_PHASE` in `phase-detection.ts` and the `/assess` HTML markers in
+ * `assess-comment-parser.ts`.
+ */
+import type { Phase } from "./types.js";
+import { GitHubProvider } from "./platforms/github.js";
+import type { SpecRecommendationSource } from "./run-log-schema.js";
+export interface ResolvedSpecRecommendation {
+    phases: Phase[];
+    qualityLoop: boolean;
+    source: SpecRecommendationSource;
+}
+/**
+ * Extract and validate the latest `SEQUANT_SPEC` marker across a set of
+ * comment bodies (oldest-to-newest order, matching `gh`'s natural order).
+ *
+ * Returns `null` when no marker is present at all. Returns `null` and logs a
+ * visible warning when the latest marker is malformed JSON, fails schema
+ * validation, or names a phase the registry doesn't recognize — per AC-2,
+ * an invalid marker falls through to the next resolution step rather than
+ * silently dropping the recommendation or silently ignoring the bad phase.
+ *
+ * Only the *latest* marker is considered (last comment, last match within
+ * it) — a re-spec's marker supersedes an earlier one, matching how a human
+ * reader would interpret the thread.
+ */
+export declare function parseSpecMarker(commentBodies: string[]): {
+    phases: Phase[];
+    qualityLoop: boolean;
+} | null;
+export interface ResolveSpecRecommendationInput {
+    /** The spec agent's captured chat output (existing `chat` fallback). */
+    chatOutput: string;
+    /** GitHub issue number, used to fetch its comments for the marker/prose steps. */
+    issueNumber: number;
+    /** Issue labels, used for the final label-based fallback. */
+    labels: string[];
+    /**
+     * Injectable for tests — defaults to a real `GitHubProvider`. Comment
+     * fetch failures are already handled by `fetchIssueCommentBodiesSync`
+     * (returns `[]`), so the chain degrades to `chat`/`label-fallback`
+     * gracefully when GitHub is unreachable.
+     */
+    githubProvider?: Pick<GitHubProvider, "fetchIssueCommentBodiesSync">;
+}
+/**
+ * Resolve the spec→run phase recommendation through the ordered chain:
+ * comment-marker → comment-prose → chat-text → label-fallback.
+ */
+export declare function resolveSpecRecommendation(input: ResolveSpecRecommendationInput): ResolvedSpecRecommendation;