sequant 2.9.0 → 2.11.0

package/dist/src/lib/settings.d.ts

@@ -57,6 +57,23 @@ export interface AgentSettings {
      */
     isolateParallel: boolean;
 }
+/**
+ * The Agent SDK's closed reasoning-effort enum (#914). Single source of
+ * truth — reused by `PhasePolicySchema`'s zod validation below and by
+ * `cli-flags.ts:parsePhaseSpecFlag` for the `--efforts` CLI boundary, so the
+ * two validation points cannot drift apart on which values are accepted.
+ */
+export declare const EFFORT_LEVELS: readonly ["low", "medium", "high", "xhigh", "max"];
+/**
+ * A single phase's `model`/`effort` override for the claude-code driver
+ * (#914). See `RunSettings.phases`.
+ */
+export interface PhasePolicy {
+    /** Model alias/ID, passed through unvalidated to the Agent SDK. */
+    model?: string;
+    /** Reasoning effort — validated against the SDK's closed enum. */
+    effort?: (typeof EFFORT_LEVELS)[number];
+}
 /**
  * Aider-specific settings for the aider agent driver.
  */
@@ -112,6 +129,18 @@ export interface RunSettings {
      * Default: true
      */
     retry: boolean;
+    /**
+     * Total minutes willing to wait for an exhausted rate-limit window to reopen
+     * before halting the run (#804).
+     *
+     * `0` (default) disables auto-wait: a window-exhausted rate limit halts
+     * immediately, exactly as it did before #804. Any positive value is a TOTAL
+     * budget per issue, not a per-occurrence allowance.
+     *
+     * The wait is in-process — it does not survive closing the terminal.
+     * Overridable per-invocation with `--auto-wait <minutes>`.
+     */
+    autoWaitMinutes: number;
     /**
      * Threshold for stale branch detection in pre-flight checks.
      * If feature branch is more than this many commits behind main,
@@ -154,6 +183,21 @@ export interface RunSettings {
      * Default: true.
      */
     relay?: boolean;
+    /**
+     * Per-phase `model`/`effort` overrides for the claude-code driver (#914),
+     * keyed by phase name. Absent by default — zero behavior change until
+     * opted in. Overridable per-invocation with `--models`/`--efforts`
+     * (CLI > settings > absent, resolved by `resolvePhasePolicies` in
+     * `config-resolver.ts`).
+     */
+    phases?: Record<string, PhasePolicy>;
+    /**
+     * Evidence-based effort escalation on quality-loop retries (#915). Default
+     * `false` — raising effort raises token spend, which is the user's call.
+     * Overridable per-invocation with `--escalate-effort` (CLI > settings >
+     * default). See `effort-escalation.ts` for the resolver.
+     */
+    effortEscalation: boolean;
 }
 /**
  * Scope assessment threshold configuration
@@ -292,6 +336,25 @@ export declare const AgentSettingsSchema: z.ZodObject<{
     }>>;
     isolateParallel: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
+/**
+ * Zod schema for a single phase's model/effort override (#914).
+ *
+ * Model aliases/IDs pass through unvalidated — they churn independently of
+ * sequant releases, and the Agent SDK's `query()` call errors clearly on a
+ * bad one. Effort validates against the SDK's closed enum at settings-parse
+ * time since that set is stable and a typo here would otherwise silently
+ * fall through to the SDK default.
+ */
+export declare const PhasePolicySchema: z.ZodObject<{
+    model: z.ZodOptional<z.ZodString>;
+    effort: z.ZodOptional<z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+        xhigh: "xhigh";
+        max: "max";
+    }>>;
+}, z.core.$strip>;
 /** Zod schema for RunSettings */
 export declare const RunSettingsSchema: z.ZodObject<{
     logJson: z.ZodDefault<z.ZodBoolean>;
@@ -311,6 +374,7 @@ export declare const RunSettingsSchema: z.ZodObject<{
     defaultBase: z.ZodOptional<z.ZodString>;
     mcp: z.ZodDefault<z.ZodBoolean>;
     retry: z.ZodDefault<z.ZodBoolean>;
+    autoWaitMinutes: z.ZodDefault<z.ZodNumber>;
     staleBranchThreshold: z.ZodDefault<z.ZodNumber>;
     resolvedIssueTTL: z.ZodDefault<z.ZodNumber>;
     pmRun: z.ZodOptional<z.ZodString>;
@@ -322,6 +386,17 @@ export declare const RunSettingsSchema: z.ZodObject<{
         extraArgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>;
     relay: z.ZodDefault<z.ZodBoolean>;
+    phases: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        model: z.ZodOptional<z.ZodString>;
+        effort: z.ZodOptional<z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+            xhigh: "xhigh";
+            max: "max";
+        }>>;
+    }, z.core.$strip>>>;
+    effortEscalation: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
 /** Zod schema for ScopeThreshold (base — fields required, no defaults) */
 export declare const ScopeThresholdSchema: z.ZodObject<{
@@ -403,6 +478,7 @@ export declare const SettingsSchema: z.ZodObject<{
         defaultBase: z.ZodOptional<z.ZodString>;
         mcp: z.ZodDefault<z.ZodBoolean>;
         retry: z.ZodDefault<z.ZodBoolean>;
+        autoWaitMinutes: z.ZodDefault<z.ZodNumber>;
         staleBranchThreshold: z.ZodDefault<z.ZodNumber>;
         resolvedIssueTTL: z.ZodDefault<z.ZodNumber>;
         pmRun: z.ZodOptional<z.ZodString>;
@@ -414,6 +490,17 @@ export declare const SettingsSchema: z.ZodObject<{
             extraArgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>;
         relay: z.ZodDefault<z.ZodBoolean>;
+        phases: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            model: z.ZodOptional<z.ZodString>;
+            effort: z.ZodOptional<z.ZodEnum<{
+                low: "low";
+                medium: "medium";
+                high: "high";
+                xhigh: "xhigh";
+                max: "max";
+            }>>;
+        }, z.core.$strip>>>;
+        effortEscalation: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
     agents: z.ZodDefault<z.ZodObject<{
         parallel: z.ZodDefault<z.ZodBoolean>;

package/dist/src/lib/settings.js

@@ -13,10 +13,18 @@
 import { readFile, writeFile, fileExists, ensureDir } from "./fs.js";
 import { dirname } from "path";
 import { z } from "zod";
+import { getPhaseNames } from "./workflow/phase-registry.js";
 /** Path to project-level settings file */
 export const SETTINGS_PATH = ".sequant/settings.json";
 /** Current settings schema version */
 export const SETTINGS_VERSION = "1.0";
+/**
+ * The Agent SDK's closed reasoning-effort enum (#914). Single source of
+ * truth — reused by `PhasePolicySchema`'s zod validation below and by
+ * `cli-flags.ts:parsePhaseSpecFlag` for the `--efforts` CLI boundary, so the
+ * two validation points cannot drift apart on which values are accepted.
+ */
+export const EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max"];
 // ─── Zod Schemas (AC-1, AC-5) ────────────────────────────────────────────────
 /** Zod schema for RotationSettings */
 export const RotationSettingsSchema = z.object({
@@ -36,21 +44,42 @@ export const AgentSettingsSchema = z.object({
     model: z.enum(["haiku", "sonnet", "opus"]).default("haiku"),
     isolateParallel: z.boolean().default(false),
 });
+/**
+ * Zod schema for a single phase's model/effort override (#914).
+ *
+ * Model aliases/IDs pass through unvalidated — they churn independently of
+ * sequant releases, and the Agent SDK's `query()` call errors clearly on a
+ * bad one. Effort validates against the SDK's closed enum at settings-parse
+ * time since that set is stable and a typo here would otherwise silently
+ * fall through to the SDK default.
+ */
+export const PhasePolicySchema = z.object({
+    model: z.string().optional(),
+    effort: z.enum(EFFORT_LEVELS).optional(),
+});
 /** Zod schema for RunSettings */
 export const RunSettingsSchema = z.object({
     logJson: z.boolean().default(true),
     logPath: z.string().default(".sequant/logs"),
     autoDetectPhases: z.boolean().default(true),
-    timeout: z.number().default(1800),
+    // #833: `.positive()` on the three that feed a timer or a loop bound. A `0`
+    // or negative here is not a weaker setting — it is an instant abort
+    // (`setTimeout` clamps a non-positive delay to 0) or a loop that never runs
+    // (`while (iteration < maxIterations)` is false on entry). The resolvers now
+    // guard these too; the schema is what gets the bad key *named* at load
+    // instead of silently swapped for a default. Left unconstrained elsewhere
+    // (`staleBranchThreshold`, `resolvedIssueTTL`) where 0 is meaningful.
+    timeout: z.number().positive().default(1800),
     sequential: z.boolean().default(false),
-    concurrency: z.number().default(3),
+    concurrency: z.number().positive().default(3),
     qualityLoop: z.boolean().default(false),
-    maxIterations: z.number().default(3),
+    maxIterations: z.number().positive().default(3),
     smartTests: z.boolean().default(true),
     rotation: RotationSettingsSchema.default(() => RotationSettingsSchema.parse({})),
     defaultBase: z.string().optional(),
     mcp: z.boolean().default(true),
     retry: z.boolean().default(true),
+    autoWaitMinutes: z.number().min(0).default(0),
     staleBranchThreshold: z.number().default(5),
     resolvedIssueTTL: z.number().default(7),
     pmRun: z.string().optional(),
@@ -58,6 +87,23 @@ export const RunSettingsSchema = z.object({
     agent: z.string().optional(),
     aider: AiderSettingsSchema.optional(),
     relay: z.boolean().default(true),
+    /**
+     * Per-phase `model`/`effort` overrides for the claude-code driver (#914).
+     * Absent by default — zero behavior change until opted in. Keyed by phase
+     * name (validated against `getPhaseNames()` via `KNOWN_KEYS["run.phases"]`
+     * as a non-fatal warning, not a schema-level rejection — a typo'd phase
+     * name here should not crash a run the way an invalid `effort` enum does).
+     */
+    phases: z.record(z.string(), PhasePolicySchema).optional(),
+    /**
+     * Evidence-based effort escalation on quality-loop retries (#915). Default
+     * `false` — raising effort raises token spend, which is the user's call.
+     * When enabled, a retried phase execution (loop iteration ≥ 2, or a
+     * `sequant ready` QA-pass loop re-run) resolves one effort tier above its
+     * configured/inherited base for that execution only. See
+     * `effort-escalation.ts` for the resolver.
+     */
+    effortEscalation: z.boolean().default(false),
 });
 /** Zod schema for ScopeThreshold (base — fields required, no defaults) */
 export const ScopeThresholdSchema = z.object({
@@ -178,7 +224,13 @@ const KNOWN_KEYS = {
         "agent",
         "aider",
         "relay",
+        "phases",
     ]),
+    // #914: keyed by real phase name so a typo (`run.phases.exce`) warns
+    // instead of silently resolving to nothing. Computed from the registry
+    // rather than hardcoded so a new phase registration doesn't need a
+    // matching edit here.
+    "run.phases": new Set(getPhaseNames()),
     agents: new Set(["parallel", "model", "isolateParallel"]),
     scopeAssessment: new Set([
         "enabled",
@@ -243,6 +295,43 @@ function formatZodErrors(error) {
         return { path, message };
     });
 }
+/**
+ * Delete the values Zod rejected from a deep clone of `raw`, so a re-parse can
+ * fill just those with their defaults and keep every valid sibling (#833).
+ *
+ * An array index in the path means one element of an array failed. Deleting by
+ * index would leave a hole that re-parses as `undefined` and fails again, so
+ * the whole array is dropped and re-defaulted instead.
+ */
+function stripInvalidPaths(raw, issues) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return {};
+    const clone = structuredClone(raw);
+    for (const issue of issues) {
+        // An empty path means the root object itself was rejected — nothing to
+        // salvage, so fall back to a bare defaults parse.
+        if (issue.path.length === 0)
+            return {};
+        // Truncate at the first array index: drop the array, not an element.
+        const firstIndex = issue.path.findIndex((seg) => typeof seg === "number");
+        const path = firstIndex === -1 ? issue.path : issue.path.slice(0, firstIndex);
+        if (path.length === 0)
+            return {};
+        let cursor = clone;
+        for (const key of path.slice(0, -1)) {
+            const next = cursor?.[key];
+            cursor =
+                next && typeof next === "object" && !Array.isArray(next)
+                    ? next
+                    : undefined;
+            if (!cursor)
+                break;
+        }
+        if (cursor)
+            delete cursor[path[path.length - 1]];
+    }
+    return clone;
+}
 /**
  * Validate a raw settings object against the Zod schema (AC-2).
  *
@@ -262,8 +351,15 @@ export function validateSettings(raw) {
     }
     // Zod validation failed — report errors as warnings and fall back to defaults
     warnings.push(...formatZodErrors(result.error));
-    // Try to salvage what we can: parse with defaults for the invalid parts
-    // by stripping invalid fields and re-parsing
+    // Salvage the valid settings by dropping only the rejected keys and
+    // re-parsing. #833: this previously re-parsed `{}` despite a comment saying
+    // it stripped invalid fields, so a single bad value — one typo in
+    // `run.timeout` — silently discarded the user's entire settings.json and
+    // reverted every unrelated key to its default.
+    const salvaged = SettingsSchema.safeParse(stripInvalidPaths(raw, result.error.issues));
+    if (salvaged.success) {
+        return { settings: salvaged.data, warnings };
+    }
     const fallback = SettingsSchema.safeParse({});
     const settings = (fallback.success ? fallback.data : DEFAULT_SETTINGS);
     return { settings, warnings };
@@ -350,9 +446,11 @@ export const DEFAULT_SETTINGS = {
         rotation: DEFAULT_ROTATION_SETTINGS,
         mcp: true, // Enable MCP servers by default in headless mode
         retry: true, // Enable automatic retry with MCP fallback by default
+        autoWaitMinutes: 0, // #804: auto-wait off by default — window exhaustion halts
         staleBranchThreshold: 5, // Block QA/test if feature is >5 commits behind main
         resolvedIssueTTL: 7, // Auto-prune resolved issues after 7 days
         relay: true, // Enable interactive relay (#383) by default
+        effortEscalation: false, // #915: off by default — raises token spend
     },
     agents: DEFAULT_AGENT_SETTINGS,
     scopeAssessment: DEFAULT_SCOPE_ASSESSMENT_SETTINGS,
@@ -592,11 +690,11 @@ Generated by \`sequant init\`. See defaults below.
 | \`logJson\` | boolean | \`true\` | Enable JSON logging |
 | \`logPath\` | string | \`".sequant/logs"\` | Path to log directory |
 | \`autoDetectPhases\` | boolean | \`true\` | Auto-detect phases from GitHub issue labels |
-| \`timeout\` | number | \`1800\` | Default timeout per phase in seconds |
+| \`timeout\` | number (> 0) | \`1800\` | Default timeout per phase in seconds. Must be positive — 0 or negative is rejected with a warning and the default used (#833) |
 | \`sequential\` | boolean | \`false\` | Run issues sequentially by default |
-| \`concurrency\` | number | \`3\` | Max concurrent issues in parallel mode |
+| \`concurrency\` | number (> 0) | \`3\` | Max concurrent issues in parallel mode. Must be positive (#833) |
 | \`qualityLoop\` | boolean | \`false\` | Enable quality loop by default |
-| \`maxIterations\` | number | \`3\` | Max iterations for quality loop |
+| \`maxIterations\` | number (> 0) | \`3\` | Max iterations for quality loop. Must be positive (#833) |
 | \`smartTests\` | boolean | \`true\` | Enable smart test detection |
 | \`defaultBase\` | string | — | Default base branch for worktree creation |
 | \`mcp\` | boolean | \`true\` | Enable MCP servers in headless mode |

package/dist/src/lib/shutdown.d.ts

@@ -20,6 +20,36 @@
  * shutdown.dispose();
  * ```
  */
+/**
+ * Why the process is shutting down, handed to every cleanup task so they can
+ * record the cause rather than silently persisting a truncated record (#856).
+ */
+export interface AbortContext {
+    /** Signal that triggered the shutdown, e.g. `SIGTERM`. */
+    signal: string;
+    /** Human-readable cause, from `describeSignalCause`. */
+    reason: string;
+}
+/**
+ * Conventional shell exit code for death-by-signal: `128 + signum`
+ * (SIGINT → 130, SIGTERM → 143). Falls back to 1 for anything unmapped.
+ *
+ * #856: this used to be a flat `0`. A run killed from outside therefore
+ * exited *successfully*, so nothing downstream — CI, a wrapping script, the
+ * user reading `$?` — could tell a completed run from a terminated one.
+ */
+export declare function exitCodeForSignal(signal: string): number;
+/**
+ * Human-readable cause for a termination signal (#856, AC-4).
+ *
+ * SIGINT is the user pressing Ctrl+C — self-explanatory. SIGTERM is not:
+ * no interactive user sends it by hand, so it always means something else
+ * killed the run, and the user needs to be told that rather than left to
+ * infer it from truncated output. The known offender on macOS is Claude
+ * Code's `[bg-pty]` host-dead watchdog, which group-SIGKILLs a process tree
+ * containing the run; see `docs/incidents/856/`.
+ */
+export declare function describeSignalCause(signal: string): string;
 /**
  * Options for ShutdownManager
  */
@@ -46,6 +76,8 @@ export interface ShutdownManagerOptions {
 export declare class ShutdownManager {
     private cleanupTasks;
     private _isShuttingDown;
+    /** Cause of the in-progress shutdown; null until a signal arrives (#856). */
+    private _abortContext;
     /** Active abort controllers — supports concurrent phase execution (#404) */
     private abortControllers;
     private forceExitTimeout;
@@ -63,6 +95,12 @@ export declare class ShutdownManager {
      * Alias for isShuttingDown (matches proposed API)
      */
     get shuttingDown(): boolean;
+    /**
+     * Why the process is shutting down, or `null` if it isn't (#856).
+     * Lets code outside a cleanup task — e.g. a `finally` block that also
+     * finalizes state — record the same cause the cleanup tasks saw.
+     */
+    get abortContext(): AbortContext | null;
     /**
      * Register an abort controller for a running phase.
      *
@@ -91,9 +129,11 @@ export declare class ShutdownManager {
      * This allows dependent cleanup to happen in correct order.
      *
      * @param name - Human-readable name for user feedback
-     * @param task - Async function to execute during cleanup
+     * @param task - Async function to execute during cleanup. Receives the
+     *   `AbortContext` when the shutdown was signal-triggered, or `null` on a
+     *   programmatic teardown. Tasks that don't care may ignore the argument.
      */
-    registerCleanup(name: string, task: () => Promise<void>): void;
+    registerCleanup(name: string, task: (abort: AbortContext | null) => Promise<void>): void;
     /**
      * Unregister a cleanup task by name
      *

package/dist/src/lib/shutdown.js

@@ -21,6 +21,43 @@
  * ```
  */
 import chalk from "chalk";
+/** POSIX signal numbers for the signals we install handlers for. */
+const SIGNAL_NUMBERS = {
+    SIGINT: 2,
+    SIGTERM: 15,
+};
+/**
+ * Conventional shell exit code for death-by-signal: `128 + signum`
+ * (SIGINT → 130, SIGTERM → 143). Falls back to 1 for anything unmapped.
+ *
+ * #856: this used to be a flat `0`. A run killed from outside therefore
+ * exited *successfully*, so nothing downstream — CI, a wrapping script, the
+ * user reading `$?` — could tell a completed run from a terminated one.
+ */
+export function exitCodeForSignal(signal) {
+    const num = SIGNAL_NUMBERS[signal];
+    return num === undefined ? 1 : 128 + num;
+}
+/**
+ * Human-readable cause for a termination signal (#856, AC-4).
+ *
+ * SIGINT is the user pressing Ctrl+C — self-explanatory. SIGTERM is not:
+ * no interactive user sends it by hand, so it always means something else
+ * killed the run, and the user needs to be told that rather than left to
+ * infer it from truncated output. The known offender on macOS is Claude
+ * Code's `[bg-pty]` host-dead watchdog, which group-SIGKILLs a process tree
+ * containing the run; see `docs/incidents/856/`.
+ */
+export function describeSignalCause(signal) {
+    switch (signal) {
+        case "SIGINT":
+            return "interrupted by user (Ctrl+C)";
+        case "SIGTERM":
+            return "terminated by an external SIGTERM (not sent by sequant)";
+        default:
+            return `terminated by ${signal}`;
+    }
+}
 /**
  * Manages graceful shutdown for sequant run
  *
@@ -34,6 +71,8 @@ import chalk from "chalk";
 export class ShutdownManager {
     cleanupTasks = [];
     _isShuttingDown = false;
+    /** Cause of the in-progress shutdown; null until a signal arrives (#856). */
+    _abortContext = null;
     /** Active abort controllers — supports concurrent phase execution (#404) */
     abortControllers = new Set();
     forceExitTimeout;
@@ -67,6 +106,14 @@ export class ShutdownManager {
     get shuttingDown() {
         return this._isShuttingDown;
     }
+    /**
+     * Why the process is shutting down, or `null` if it isn't (#856).
+     * Lets code outside a cleanup task — e.g. a `finally` block that also
+     * finalizes state — record the same cause the cleanup tasks saw.
+     */
+    get abortContext() {
+        return this._abortContext;
+    }
     /**
      * Register an abort controller for a running phase.
      *
@@ -104,7 +151,9 @@ export class ShutdownManager {
      * This allows dependent cleanup to happen in correct order.
      *
      * @param name - Human-readable name for user feedback
-     * @param task - Async function to execute during cleanup
+     * @param task - Async function to execute during cleanup. Receives the
+     *   `AbortContext` when the shutdown was signal-triggered, or `null` on a
+     *   programmatic teardown. Tasks that don't care may ignore the argument.
      */
     registerCleanup(name, task) {
         this.cleanupTasks.push({ name, task });
@@ -138,6 +187,13 @@ export class ShutdownManager {
             return;
         }
         this._isShuttingDown = true;
+        // #856 AC-4: name the cause up front. A truncated run whose last words
+        // were "shutting down gracefully" reads as an orderly stop; it isn't one.
+        const abort = {
+            signal,
+            reason: describeSignalCause(signal),
+        };
+        this._abortContext = abort;
         this.output(chalk.yellow(`\n!  Received ${signal}, shutting down gracefully...`));
         // Abort all in-flight phases immediately
         if (this.abortControllers.size > 0) {
@@ -157,7 +213,7 @@ export class ShutdownManager {
         const tasksToRun = [...this.cleanupTasks].reverse();
         for (const { name, task } of tasksToRun) {
             try {
-                await task();
+                await task(abort);
                 this.output(chalk.green(`✓ ${name}`));
             }
             catch (err) {
@@ -166,9 +222,22 @@ export class ShutdownManager {
             }
         }
         clearTimeout(forceExitTimer);
-        // Print summary
-        this.output(chalk.yellow("\nInterrupted. Cleanup complete."));
-        this.exit(0);
+        // #856 AC-4: report the abort AS an abort, with its cause and a non-zero
+        // exit code. The old banner ("Interrupted. Cleanup complete.") plus
+        // `exit(0)` made an externally-killed run indistinguishable from a
+        // successful one — and because this path exits the process, the normal
+        // `displaySummary` / `abortReason` rendering in run-display.ts is never
+        // reached, so this banner is the only thing the user sees.
+        const code = exitCodeForSignal(signal);
+        this.errorOutput(chalk.red(`\n✗ Run aborted — ${abort.reason}.`));
+        this.output(chalk.yellow(`  Cleanup completed. No phase results beyond this point were recorded.`));
+        if (signal === "SIGTERM") {
+            this.output(chalk.gray(`  sequant does not send itself SIGTERM. If this run was launched as a\n` +
+                `  backgrounded task inside an interactive Claude Code session, see\n` +
+                `  docs/incidents/856/ — relaunch from a plain terminal instead.`));
+        }
+        this.output(chalk.gray(`  Exit code: ${code}`));
+        this.exit(code);
     }
     /**
      * Remove signal handlers and clean up
@@ -181,6 +250,7 @@ export class ShutdownManager {
         process.removeListener("SIGTERM", this.sigtermHandler);
         this.cleanupTasks = [];
         this.abortControllers.clear();
+        this._abortContext = null;
     }
 }
 /**

package/dist/src/lib/skills-check.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Skills installation check — single source of truth for the
+ * `.claude/skills/<skill>/SKILL.md` layout.
+ *
+ * Shared by `doctor` (Checks 2+3) and the `run` pre-flight (#813) so the two
+ * cannot drift. The claude-code driver loads skills from project scope only
+ * (`settingSources: ["project"]`, see #19 AC-3 / #711), which makes
+ * `.claude/skills/` a hard runtime dependency: a phase prompt like
+ * "Run the /spec workflow" can never resolve without it.
+ */
+/** Directory (relative to a project root) that skills are resolved from. */
+export declare const SKILLS_DIR = ".claude/skills";
+export interface SkillsCheckResult {
+    /** True when the `.claude/skills/` directory exists. */
+    skillsDirExists: boolean;
+    /** Requested skills whose `SKILL.md` is missing, in input order. */
+    missingSkills: string[];
+}
+/**
+ * Check that each requested skill is installed at
+ * `<cwd>/.claude/skills/<skill>/SKILL.md`.
+ *
+ * @param skills - Skill directory names to require (e.g. `["spec", "exec"]`).
+ * @param cwd - Project root to check under (default: `process.cwd()`).
+ */
+export declare function checkSkillsInstalled(skills: string[], cwd?: string): Promise<SkillsCheckResult>;

package/dist/src/lib/skills-check.js

@@ -0,0 +1,31 @@
+/**
+ * Skills installation check — single source of truth for the
+ * `.claude/skills/<skill>/SKILL.md` layout.
+ *
+ * Shared by `doctor` (Checks 2+3) and the `run` pre-flight (#813) so the two
+ * cannot drift. The claude-code driver loads skills from project scope only
+ * (`settingSources: ["project"]`, see #19 AC-3 / #711), which makes
+ * `.claude/skills/` a hard runtime dependency: a phase prompt like
+ * "Run the /spec workflow" can never resolve without it.
+ */
+import { join } from "path";
+import { fileExists } from "./fs.js";
+/** Directory (relative to a project root) that skills are resolved from. */
+export const SKILLS_DIR = ".claude/skills";
+/**
+ * Check that each requested skill is installed at
+ * `<cwd>/.claude/skills/<skill>/SKILL.md`.
+ *
+ * @param skills - Skill directory names to require (e.g. `["spec", "exec"]`).
+ * @param cwd - Project root to check under (default: `process.cwd()`).
+ */
+export async function checkSkillsInstalled(skills, cwd = process.cwd()) {
+    const skillsDirExists = await fileExists(join(cwd, SKILLS_DIR));
+    const missingSkills = [];
+    for (const skill of skills) {
+        if (!(await fileExists(join(cwd, SKILLS_DIR, skill, "SKILL.md")))) {
+            missingSkills.push(skill);
+        }
+    }
+    return { skillsDirExists, missingSkills };
+}