sequant 2.9.0 → 2.10.0

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

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

@@ -37,6 +37,7 @@ export interface PackageManagerConfig {
     exec: string;
     install: string;
     installSilent: string;
+    ciInstall: string;
     addPkg: string;
     removePkg: string;
     updatePkg: string;
@@ -56,12 +57,120 @@ export declare function detectPackageManager(): Promise<PackageManager | null>;
 /**
  * Synchronous version of detectPackageManager for use in startup code.
  * Only checks JS lockfiles (not Python) since sequant is a Node.js tool.
+ *
+ * @param root Directory to look for lockfiles in. Defaults to the process cwd,
+ *        which is what startup code wants; callers that operate on a specific
+ *        repository (e.g. merge-check) must pass that repo's root instead.
+ */
+export declare function detectPackageManagerSync(root?: string): PackageManager;
+/**
+ * Resolve the package manager for a directory, preferring a declared value and
+ * falling back to live lockfile detection.
+ *
+ * The declared value is a *snapshot* — the worktree manifest records whatever
+ * `sequant init` saw, so it is absent on manifest-less or pre-init trees. The
+ * old spelling at those call sites was `(declared as keyof typeof PM_CONFIG)
+ * || "npm"`, which assumed npm whenever the snapshot was missing while the
+ * shell provisioning path (`templates/scripts/new-feature.sh`, PM-aware since
+ * #847) detected live from the lockfile. On a pnpm/yarn/bun project without a
+ * manifest the two paths therefore disagreed about the project's package
+ * manager — the dual-producer drift class of #833. Detecting here makes the
+ * TypeScript path agree with the shell path by construction (#870).
+ *
+ * The own-property membership test also retires that unchecked cast: a
+ * declared value outside `PackageManager` (a hand-edited manifest, a future
+ * `"npm@10"` spelling) used to index `PM_CONFIG` to `undefined` and throw on
+ * the next property access. Such a value now routes to detection instead.
+ * Python managers (`pip`/`poetry`/`uv`) are `PM_CONFIG` keys, so a declared
+ * Python manager still wins over the JS-only detector.
+ *
+ * The test is `hasOwnProperty`, deliberately not `in`: `in` walks the
+ * prototype chain, so `"toString"`, `"constructor"`, and `"__proto__"` would
+ * all pass it and be returned as if they named a package manager. Indexing
+ * `PM_CONFIG` with one yields an inherited function (or `Object.prototype`)
+ * whose `ciInstall` is `undefined`, crashing the caller on `.split(" ")` —
+ * reintroducing the exact failure this guard exists to prevent.
+ *
+ * @param declared Package manager recorded in the manifest, if any
+ * @param root Directory whose lockfiles decide the fallback
  */
-export declare function detectPackageManagerSync(): PackageManager;
+export declare function resolvePackageManager(declared: string | undefined, root: string): PackageManager;
 /**
  * Get package manager command configuration
  */
 export declare function getPackageManagerCommands(pm: PackageManager): PackageManagerConfig;
+/**
+ * Frozen install understood by Yarn 1 (classic).
+ *
+ * Yarn 2+ (berry) renamed this flag to `--immutable`, which is what
+ * `PM_CONFIG.yarn.ciInstall` carries. Both yarn spellings therefore exist, and
+ * both must appear in `new-feature.sh`'s `pm_ci_install()` table — the drift
+ * guard in `__tests__/new-feature-frozen-install.integration.test.ts` asserts
+ * exactly that, which is why this is a named export rather than a literal
+ * buried in `resolvePackageManagerConfig` (#871).
+ */
+export declare const YARN_CLASSIC_CI_INSTALL = "yarn install --frozen-lockfile";
+/**
+ * Detect whether a directory is a Yarn 1 (classic) or Yarn 2+ (berry) project.
+ *
+ * Yarn 1 and berry both use `yarn.lock`, so `detectPackageManagerSync` cannot
+ * tell them apart — it answers "yarn", and this answers "which yarn". They are
+ * separate axes on purpose: adding a `yarn1` member to `PackageManager` would
+ * leak a synthetic name into settings (`pmRun`), doctor output, and templates
+ * for what is, today, a one-flag difference.
+ *
+ * Signals, in order of authority. The ordering follows a single rule: **flag
+ * acceptance is decided by the yarn binary that runs, not by the lockfile it
+ * reads.** So a Corepack pin outranks the lockfile header — a yarn-1 lockfile
+ * under `packageManager: "yarn@4"` still gets berry's `--immutable`, because
+ * yarn 4 is what will execute and yarn 4 rejects `--frozen-lockfile`.
+ *
+ *   1. `packageManager: "yarn@<major>"` in `package.json` — Corepack pins the
+ *      binary.
+ *   2. `.yarnrc.yml` — a berry-only config file; yarn 1 reads `.yarnrc`.
+ *   3. `yarn.lock` header — yarn 1 writes `# yarn lockfile v1`; berry writes
+ *      `__metadata:` instead.
+ *   4. Nothing recognizable → berry, the pre-#871 assumption. Staying with it
+ *      keeps a contentless or unreadable `yarn.lock` behaving exactly as it did
+ *      before this function existed.
+ *
+ * Mirrored by `detect_yarn_major` in `templates/scripts/new-feature.sh` (#871).
+ *
+ * @internal Exported for testing — production code should go through
+ * {@link resolvePackageManagerConfig}, whose whole job is to apply this answer.
+ * The export exists so the cross-path agreement test can run this and the shell
+ * mirror against the same fixtures, which is the gate keeping the two in step.
+ *
+ * @param root Directory to inspect. Defaults to the process cwd.
+ * @returns 1 for Yarn 1 (classic), 2 for Yarn 2+ (berry)
+ */
+export declare function detectYarnMajor(root?: string): 1 | 2;
+/**
+ * Package manager commands for `pm`, with directory-dependent commands resolved
+ * against `root`.
+ *
+ * A drop-in replacement for `PM_CONFIG[pm]` at every call site that knows which
+ * project directory it is acting on. `PM_CONFIG.yarn` is the berry baseline, so
+ * for a Yarn 1 project this substitutes every field whose berry spelling is
+ * wrong on classic — `ciInstall`, `exec`, and `updatePkg` (see
+ * {@link YARN_CLASSIC_OVERRIDES}). Every other package manager, and every
+ * major-agnostic yarn field, is returned untouched.
+ *
+ * Returning the whole config rather than one resolved string is what makes that
+ * cheap: call sites that thread a `PackageManagerConfig` onward — merge-check's
+ * combined-branch test reads `ciInstall` for three commands and two user-facing
+ * messages — stay correct with a single-line change, and each newly discovered
+ * classic/berry split is one entry in the overrides table rather than a new
+ * call-site edit.
+ *
+ * Resolve against the tree you are about to act on, not against wherever the
+ * process started: `root` decides the answer, and in merge-check the combined
+ * (post-merge) state can disagree with the pre-merge one.
+ *
+ * @param pm Package manager identity, e.g. from `detectPackageManagerSync`
+ * @param root Directory whose files decide the directory-dependent commands
+ */
+export declare function resolvePackageManagerConfig(pm: PackageManager, root: string): PackageManagerConfig;
 export interface StackConfig {
     name: string;
     displayName: string;