sequant 2.10.0 → 2.11.0

package/dist/src/lib/workflow/run-log-schema.js

@@ -42,6 +42,33 @@ export const QaVerdictSchema = z.enum([
     "AC_NOT_MET",
     "NEEDS_VERIFICATION",
 ]);
+/**
+ * Source that produced the resolved spec→run phase recommendation (#921).
+ *
+ * Ordered by resolution priority: a durable structured marker in the spec's
+ * GitHub comment beats the same comment's prose section, which beats the
+ * spec agent's ephemeral chat text, which beats label-based guessing.
+ */
+export const SpecRecommendationSourceSchema = z.enum([
+    "marker",
+    "comment-prose",
+    "chat",
+    "label-fallback",
+]);
+/**
+ * Resolved spec→run phase recommendation, recorded on the issue log so
+ * fallback frequency is auditable (#921 AC-4). Additive/optional — absent on
+ * runs that never reached spec resolution (e.g. spec failed) or predate this
+ * field, keeping the persisted-log schema stable at `version: 1`.
+ */
+export const SpecRecommendationSchema = z.object({
+    /** Which step in the resolution chain produced this result */
+    source: SpecRecommendationSourceSchema,
+    /** Resolved phases, spec excluded (spec already ran) */
+    phases: z.array(PhaseSchema),
+    /** Whether the quality loop should be enabled */
+    qualityLoop: z.boolean(),
+});
 /**
  * File diff statistics for a single file (AC-3)
  */
@@ -82,7 +109,7 @@ export const ErrorContextSchema = z.object({
     /**
      * Classified error category (legacy, kept for backwards compatibility).
      * Keep in sync with `ERROR_CATEGORIES` in `error-classifier.ts` —
-     * `rate_limit` / `billing` added by #761 AC-6.
+     * `rate_limit` / `billing` added by #761 AC-6, `pr_creation` by #920.
      */
     category: z.enum([
         "context_overflow",
@@ -92,6 +119,7 @@ export const ErrorContextSchema = z.object({
         "timeout",
         "rate_limit",
         "billing",
+        "pr_creation",
         "unknown",
     ]),
     /** Typed error class name (AC-8), e.g. "ApiError", "BuildError" */
@@ -198,6 +226,8 @@ export const IssueLogSchema = z.object({
     prNumber: z.number().int().positive().optional(),
     /** PR URL if created after successful QA */
     prUrl: z.string().optional(),
+    /** How the spec→run phase recommendation was resolved (#921 AC-4) */
+    specRecommendation: SpecRecommendationSchema.optional(),
 });
 /**
  * Run configuration

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

@@ -1207,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),
@@ -1215,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/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;

package/dist/src/lib/workflow/spec-recommendation.js

@@ -0,0 +1,142 @@
+/**
+ * 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 chalk from "chalk";
+import { z } from "zod";
+import { phaseRegistry } from "./phase-registry.js";
+import { GitHubProvider } from "./platforms/github.js";
+import { stripMarkdownCode } from "./phase-detection.js";
+import { parseRecommendedWorkflow, detectPhasesFromLabels, } from "./phase-mapper.js";
+/** Regex to extract the SEQUANT_SPEC marker JSON from an HTML comment. */
+const SPEC_MARKER_REGEX = /<!-- SEQUANT_SPEC: (\{[^}]+\}) -->/g;
+/**
+ * Structural shape of the marker JSON, before phase names are checked
+ * against the phase registry. `qualityLoop` defaults to `false` when
+ * omitted, matching `parseRecommendedWorkflow`'s prose-parsing default.
+ */
+const SpecMarkerJsonSchema = z.object({
+    phases: z.array(z.string()).min(1),
+    qualityLoop: z.boolean().optional().default(false),
+});
+/**
+ * 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 function parseSpecMarker(commentBodies) {
+    let latestRaw = null;
+    for (const body of commentBodies) {
+        const stripped = stripMarkdownCode(body);
+        SPEC_MARKER_REGEX.lastIndex = 0;
+        let match;
+        while ((match = SPEC_MARKER_REGEX.exec(stripped)) !== null) {
+            latestRaw = match[1];
+        }
+    }
+    if (latestRaw === null) {
+        return null;
+    }
+    let parsedJson;
+    try {
+        parsedJson = JSON.parse(latestRaw);
+    }
+    catch {
+        console.log(chalk.yellow(`    ⚠ SEQUANT_SPEC marker is not valid JSON — falling through to comment prose`));
+        return null;
+    }
+    const result = SpecMarkerJsonSchema.safeParse(parsedJson);
+    if (!result.success) {
+        console.log(chalk.yellow(`    ⚠ SEQUANT_SPEC marker failed schema validation — falling through to comment prose`));
+        return null;
+    }
+    const unknownPhases = result.data.phases.filter((name) => !phaseRegistry.has(name));
+    if (unknownPhases.length > 0) {
+        console.log(chalk.yellow(`    ⚠ SEQUANT_SPEC marker names unknown phase(s): ${unknownPhases.join(", ")} — falling through to comment prose`));
+        return null;
+    }
+    return { phases: result.data.phases, qualityLoop: result.data.qualityLoop };
+}
+/**
+ * Find the most recently posted comment containing a `## Recommended
+ * Workflow` section and parse it with the existing prose regex.
+ *
+ * Scans newest-to-oldest so a later spec re-run's comment takes precedence
+ * over an earlier one — same intuition as the marker step.
+ */
+function parseCommentProse(commentBodies) {
+    for (let i = commentBodies.length - 1; i >= 0; i--) {
+        const parsed = parseRecommendedWorkflow(commentBodies[i]);
+        if (parsed) {
+            return parsed;
+        }
+    }
+    return null;
+}
+/**
+ * Resolve the spec→run phase recommendation through the ordered chain:
+ * comment-marker → comment-prose → chat-text → label-fallback.
+ */
+export function resolveSpecRecommendation(input) {
+    const github = input.githubProvider ?? new GitHubProvider();
+    const commentBodies = github.fetchIssueCommentBodiesSync(String(input.issueNumber));
+    let phases;
+    let qualityLoop;
+    let source;
+    const marker = parseSpecMarker(commentBodies);
+    const prose = marker ? null : parseCommentProse(commentBodies);
+    const chat = marker || prose || !input.chatOutput
+        ? null
+        : parseRecommendedWorkflow(input.chatOutput);
+    if (marker) {
+        ({ phases, qualityLoop } = marker);
+        source = "marker";
+    }
+    else if (prose) {
+        ({ phases, qualityLoop } = prose);
+        source = "comment-prose";
+    }
+    else if (chat) {
+        ({ phases, qualityLoop } = chat);
+        source = "chat";
+    }
+    else {
+        const fallback = detectPhasesFromLabels(input.labels);
+        phases = fallback.phases;
+        qualityLoop = fallback.qualityLoop;
+        source = "label-fallback";
+    }
+    // Spec already ran by the time this resolves — never re-include it,
+    // regardless of which step in the chain produced the result.
+    return { phases: phases.filter((p) => p !== "spec"), qualityLoop, source };
+}

package/dist/src/lib/workflow/types.d.ts

@@ -182,6 +182,28 @@ export interface ExecutionConfig {
      * see {@link AutoWaitLedger}.
      */
     autoWaitMinutes?: number;
+    /**
+     * Resolved per-phase `model`/`effort` overrides (#914), keyed by phase
+     * name. Merged from `settings.run.phases` and the CLI's `--models`/
+     * `--efforts` flags via `resolvePhasePolicies` (CLI > settings > absent) —
+     * see `config-resolver.ts`. Absent/empty by default: `phase-executor.ts`
+     * only sets `AgentExecutionConfig.model`/`.effort` when a phase has an
+     * entry here, so an unconfigured run reaches the SDK unchanged.
+     */
+    phasePolicies?: Record<string, {
+        model?: string;
+        effort?: string;
+    }>;
+    /**
+     * Evidence-based effort escalation on quality-loop retries (#915). CLI >
+     * settings > absent (`false`), resolved by `buildExecutionConfig`
+     * (`config-resolver.ts`) and `ready-gate.ts`'s `buildPhaseConfig` — the same
+     * two producers `phasePolicies` uses, so this cannot drift from that one
+     * (#833 class). Consumed only at dispatch time by
+     * `effort-escalation.ts`'s `withEscalatedEffort`, never baked statically
+     * into `phasePolicies` here — escalation is per-execution, not per-run.
+     */
+    effortEscalation?: boolean;
 }
 /**
  * A single liveness notice emitted during an auto-wait (#804 AC-7).
@@ -246,6 +268,16 @@ export interface PhaseResult {
     stdoutTail?: string[];
     /** Process exit code from the agent driver (#447) */
     exitCode?: number;
+    /**
+     * Set when this execution's effort was escalated one tier above its
+     * resolved base (#915) — a quality-loop retry with `effortEscalation`
+     * enabled. Additive/optional, same shape as `capped?`/`structuredError?`;
+     * absent on every non-escalated execution.
+     */
+    escalatedEffort?: {
+        base: string;
+        escalated: string;
+    };
 }
 /**
  * Result of executing all phases for an issue
@@ -269,6 +301,15 @@ export interface IssueResult {
      * with this string as the reason.
      */
     prCreationError?: string;
+    /**
+     * Set when PR creation was skipped because the branch carried zero commits
+     * ahead of its base (#920) — a phase-restricted run (e.g. `--phases spec`)
+     * that implemented nothing has no deliverable to open a PR for, and
+     * attempting one would only fail with GitHub's "No commits between main and
+     * …" error. Distinct from {@link IssueResult.prCreationError}: this is not
+     * a failure — `success` stays whatever the phases produced.
+     */
+    prSkippedReason?: string;
     /**
      * Set when the issue was skipped because another sequant session holds
      * the per-issue lock (#625). Surfaced in the summary as
@@ -486,6 +527,29 @@ export interface RunOptions {
      * and bounds wholesale — no new settings accompany this flag.
      */
     readyGate?: boolean;
+    /**
+     * Per-phase model override (#914). Either a bare value applied to every
+     * phase (`--models sonnet`) or a comma list of `phase=model` pairs
+     * (`--models spec=fable,exec=sonnet`). Parsed and merged with
+     * `settings.run.phases` by `resolvePhasePolicies` (CLI > settings >
+     * absent) into `ExecutionConfig.phasePolicies`. Malformed specs fail fast
+     * at the Commander option boundary via `cli-flags.ts`.
+     */
+    models?: string;
+    /**
+     * Per-phase reasoning-effort override (#914). Same grammar as {@link
+     * models} (bare value or comma list of `phase=effort` pairs); each value
+     * validates against the SDK's closed `low|medium|high|xhigh|max` enum.
+     */
+    efforts?: string;
+    /**
+     * Evidence-based effort escalation on quality-loop retries (#915). Set via
+     * `--escalate-effort`. When true, a retried phase execution resolves one
+     * effort tier above its configured/inherited base for that execution only
+     * — see `effort-escalation.ts`. Default `false`: escalation raises token
+     * spend, so an unset flag leaves every run byte-identical to pre-#915.
+     */
+    escalateEffort?: boolean;
 }
 /**
  * CLI arguments for run command

package/dist/src/lib/workflow/worktree-manager.d.ts

@@ -104,8 +104,15 @@ export declare function checkWorktreeFreshness(worktreePath: string, verbose: bo
 export declare function removeStaleWorktree(existingPath: string, branch: string, verbose: boolean): boolean;
 /**
  * List all active worktrees with their branches
+ *
+ * `git worktree list` only ever reports worktrees belonging to the repository
+ * containing `cwd`, which is what makes this a repo-scoped lookup: a sibling
+ * project's worktree can never appear here, even though `../worktrees/` is a
+ * single directory shared by every repo under the same parent (#899).
+ *
+ * @param cwd - Directory to run git in. Defaults to the current process cwd.
  */
-export declare function listWorktrees(): Array<{
+export declare function listWorktrees(cwd?: string): Array<{
     path: string;
     branch: string;
     issue: number | null;

package/dist/src/lib/workflow/worktree-manager.js

@@ -205,10 +205,18 @@ export function removeStaleWorktree(existingPath, branch, verbose) {
 }
 /**
  * List all active worktrees with their branches
+ *
+ * `git worktree list` only ever reports worktrees belonging to the repository
+ * containing `cwd`, which is what makes this a repo-scoped lookup: a sibling
+ * project's worktree can never appear here, even though `../worktrees/` is a
+ * single directory shared by every repo under the same parent (#899).
+ *
+ * @param cwd - Directory to run git in. Defaults to the current process cwd.
  */
-export function listWorktrees() {
+export function listWorktrees(cwd) {
     const result = spawnSync("git", ["worktree", "list", "--porcelain"], {
         stdio: "pipe",
+        ...(cwd ? { cwd } : {}),
     });
     if (result.status !== 0)
         return [];

package/dist/src/lib/workflow/worktree-resolver.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Repo-scoped worktree resolution and verification (#899).
+ *
+ * Skill-driven `/fullsolve` used to hand `/exec` an unexpanded glob
+ * (`../worktrees/feature/<issue>-` followed by a star and a slash) and `/exec`
+ * was instructed to trust it without checking. Two things went wrong:
+ *
+ * 1. When nothing had created the worktree, the `cd` failed and the agent
+ *    silently kept working in the main checkout.
+ * 2. `../worktrees/` is one flat namespace shared by every repo under the same
+ *    parent directory, and issue numbers are per-repo — so where the glob *did*
+ *    match, it could match a sibling project's worktree.
+ *
+ * Both are fixed the same way: never resolve worktrees through the filesystem.
+ * `git worktree list` reports only the worktrees of the repository containing
+ * `cwd`, so scoping is structural rather than a filter that can be forgotten,
+ * and it reports the *branch*, which is the real identity — a worktree
+ * directory slug can drift from its branch after a rename.
+ */
+/** Named failure modes for `resolveIssueWorktree`. */
+export type ResolveErrorCode = "WORKTREE_NOT_FOUND" | "WORKTREE_AMBIGUOUS";
+/** Named failure modes for `verifyWorktreePath`. */
+export type VerifyErrorCode = "SEQUANT_WORKTREE_NOT_FOUND" | "SEQUANT_WORKTREE_FOREIGN" | "SEQUANT_WORKTREE_ISSUE_MISMATCH";
+/** A worktree of the current repository, as reported by git. */
+export interface ResolvedWorktree {
+    /** Absolute path, exactly as git reports it. */
+    path: string;
+    /** Branch checked out there, e.g. `feature/899-some-slug`. */
+    branch: string;
+}
+export type ResolveResult = ({
+    ok: true;
+} & ResolvedWorktree) | {
+    ok: false;
+    error: ResolveErrorCode;
+    message: string;
+    /** Populated for WORKTREE_AMBIGUOUS so the caller can report candidates. */
+    candidates: ResolvedWorktree[];
+};
+export type VerifyResult = ({
+    ok: true;
+} & ResolvedWorktree) | {
+    ok: false;
+    error: VerifyErrorCode;
+    message: string;
+};
+/**
+ * Find the worktree of the *current* repository that holds issue `issue`.
+ *
+ * Selection keys on the branch git reports, never on the directory name, so a
+ * worktree whose slug has drifted from its branch still resolves — and a
+ * directory that merely looks like a match (a sibling repo's worktree, or a
+ * stray directory) never does.
+ *
+ * @param issue - Issue number to look up.
+ * @param cwd - Directory inside the repository to search. Defaults to process cwd.
+ */
+export declare function resolveIssueWorktree(issue: number, cwd?: string): ResolveResult;
+/**
+ * Verify that a caller-supplied worktree path is safe to work in.
+ *
+ * This is the guard `/exec` runs before trusting `SEQUANT_WORKTREE`. It fails
+ * closed on every uncertain case — a bad path must halt the run, never degrade
+ * into "keep going in whatever directory we happen to be in".
+ *
+ * @param worktreePath - The path to check (typically `$SEQUANT_WORKTREE`).
+ * @param options.issue - When set, the branch must belong to this issue.
+ * @param options.cwd - Directory inside the repository to check against.
+ */
+export declare function verifyWorktreePath(worktreePath: string, options?: {
+    issue?: number;
+    cwd?: string;
+}): VerifyResult;

package/dist/src/lib/workflow/worktree-resolver.js

@@ -0,0 +1,126 @@
+/**
+ * Repo-scoped worktree resolution and verification (#899).
+ *
+ * Skill-driven `/fullsolve` used to hand `/exec` an unexpanded glob
+ * (`../worktrees/feature/<issue>-` followed by a star and a slash) and `/exec`
+ * was instructed to trust it without checking. Two things went wrong:
+ *
+ * 1. When nothing had created the worktree, the `cd` failed and the agent
+ *    silently kept working in the main checkout.
+ * 2. `../worktrees/` is one flat namespace shared by every repo under the same
+ *    parent directory, and issue numbers are per-repo — so where the glob *did*
+ *    match, it could match a sibling project's worktree.
+ *
+ * Both are fixed the same way: never resolve worktrees through the filesystem.
+ * `git worktree list` reports only the worktrees of the repository containing
+ * `cwd`, so scoping is structural rather than a filter that can be forgotten,
+ * and it reports the *branch*, which is the real identity — a worktree
+ * directory slug can drift from its branch after a rename.
+ */
+import { existsSync, realpathSync, statSync } from "fs";
+import path from "path";
+import { listWorktrees } from "./worktree-manager.js";
+/**
+ * Find the worktree of the *current* repository that holds issue `issue`.
+ *
+ * Selection keys on the branch git reports, never on the directory name, so a
+ * worktree whose slug has drifted from its branch still resolves — and a
+ * directory that merely looks like a match (a sibling repo's worktree, or a
+ * stray directory) never does.
+ *
+ * @param issue - Issue number to look up.
+ * @param cwd - Directory inside the repository to search. Defaults to process cwd.
+ */
+export function resolveIssueWorktree(issue, cwd) {
+    const matches = listWorktrees(cwd)
+        .filter((w) => w.issue === issue)
+        .map(({ path: p, branch }) => ({ path: p, branch }));
+    if (matches.length === 0) {
+        return {
+            ok: false,
+            error: "WORKTREE_NOT_FOUND",
+            message: `WORKTREE_NOT_FOUND: no worktree of this repository has a branch for issue #${issue}. ` +
+                `Create one with \`./scripts/new-feature.sh ${issue}\`.`,
+            candidates: [],
+        };
+    }
+    if (matches.length > 1) {
+        const list = matches.map((m) => `${m.branch} -> ${m.path}`).join("; ");
+        return {
+            ok: false,
+            error: "WORKTREE_AMBIGUOUS",
+            message: `WORKTREE_AMBIGUOUS: ${matches.length} worktrees claim issue #${issue} (${list}). ` +
+                `Remove the stale one, or set SEQUANT_WORKTREE explicitly.`,
+            candidates: matches,
+        };
+    }
+    return { ok: true, ...matches[0] };
+}
+/**
+ * Canonicalize a path for comparison, tolerating paths that do not exist.
+ *
+ * `realpathSync` throws on a missing path, so fall back to resolving the
+ * deepest existing ancestor and re-appending the remainder — enough to make
+ * `/tmp/...` and `/private/tmp/...` compare equal on macOS.
+ */
+function canonicalize(target) {
+    const absolute = path.resolve(target);
+    try {
+        return realpathSync(absolute);
+    }
+    catch {
+        const parent = path.dirname(absolute);
+        if (parent === absolute)
+            return absolute;
+        return path.join(canonicalize(parent), path.basename(absolute));
+    }
+}
+/**
+ * Verify that a caller-supplied worktree path is safe to work in.
+ *
+ * This is the guard `/exec` runs before trusting `SEQUANT_WORKTREE`. It fails
+ * closed on every uncertain case — a bad path must halt the run, never degrade
+ * into "keep going in whatever directory we happen to be in".
+ *
+ * @param worktreePath - The path to check (typically `$SEQUANT_WORKTREE`).
+ * @param options.issue - When set, the branch must belong to this issue.
+ * @param options.cwd - Directory inside the repository to check against.
+ */
+export function verifyWorktreePath(worktreePath, options = {}) {
+    const raw = worktreePath.trim();
+    if (raw.length === 0 || raw.includes("*")) {
+        return {
+            ok: false,
+            error: "SEQUANT_WORKTREE_NOT_FOUND",
+            message: `SEQUANT_WORKTREE_NOT_FOUND: ${raw.length === 0 ? "empty path" : `unexpanded glob "${raw}"`}. Expected a resolved absolute directory.`,
+        };
+    }
+    const absolute = path.resolve(raw);
+    if (!existsSync(absolute) || !statSync(absolute).isDirectory()) {
+        return {
+            ok: false,
+            error: "SEQUANT_WORKTREE_NOT_FOUND",
+            message: `SEQUANT_WORKTREE_NOT_FOUND: "${raw}" is not an existing directory.`,
+        };
+    }
+    const canonical = canonicalize(absolute);
+    const known = listWorktrees(options.cwd);
+    const match = known.find((w) => canonicalize(w.path) === canonical);
+    if (!match) {
+        return {
+            ok: false,
+            error: "SEQUANT_WORKTREE_FOREIGN",
+            message: `SEQUANT_WORKTREE_FOREIGN: "${raw}" is not a worktree of this repository. ` +
+                `It belongs to another project or is stale; \`../worktrees/\` is shared across repos.`,
+        };
+    }
+    if (options.issue !== undefined && match.issue !== options.issue) {
+        return {
+            ok: false,
+            error: "SEQUANT_WORKTREE_ISSUE_MISMATCH",
+            message: `SEQUANT_WORKTREE_ISSUE_MISMATCH: "${raw}" has branch "${match.branch}", ` +
+                `which is not issue #${options.issue}.`,
+        };
+    }
+    return { ok: true, path: match.path, branch: match.branch };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sequant",
-  "version": "2.10.0",
+  "version": "2.11.0",
   "description": "AI coding agent orchestrator — resolve GitHub issues end-to-end with isolated git worktrees, quality gates, and an MCP server. Works with Claude Code or Aider.",
   "type": "module",
   "bin": {
@@ -24,10 +24,11 @@
     "build": "rm -rf dist/src dist/bin dist/dashboard && tsc && chmod +x dist/bin/cli.js",
     "dev": "tsx bin/cli.ts",
     "test": "vitest run",
-    "lint": "eslint src/ bin/ --max-warnings 0",
+    "lint": "eslint src/ bin/ scripts/ --max-warnings 0",
     "sync:skills": "npx tsx scripts/check-skill-sync.ts --fix",
     "sync:hooks": "bash scripts/sync-hooks.sh",
     "validate:skills": "for skill in templates/skills/*/; do case \"$skill\" in *_shared*|*/references/*) continue;; esac; npx skills-ref validate \"$skill\"; done",
+    "typecheck:scripts": "tsc --noEmit -p tsconfig.scripts.json",
     "lint:skill-calls": "npx tsx scripts/lint-skill-calls.ts",
     "lint:skill-gates": "npx tsx scripts/lint-skill-gates.ts",
     "lint:skill-sync": "npx tsx scripts/check-skill-sync.ts",