sequant 2.10.0 → 2.12.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" */
@@ -101,6 +129,39 @@ export const ErrorContextSchema = z.object({
     /** Whether this error type is retryable (AC-9) */
     isRetryable: z.boolean().optional(),
 });
+/**
+ * Finite taxonomy for a single gap finding surfaced by `/qa` (#937).
+ *
+ * Replaces the lossy prose-scrape gap channel (`parseListSection` against
+ * `**Issues:**`/`**Gaps**` headers, which misses AC-table NOT_MET rows, §6d
+ * Adversarial Re-Read findings, and §5 Risk Assessment). `evidence` is
+ * required so a finding can't be speculative — see #608's 0%-action-rate
+ * result for open-ended "what might we be missing" findings.
+ */
+export const GapCategorySchema = z.enum([
+    "requirement_gap",
+    "dependency_gap",
+    "test_gap",
+    "repository_gap",
+    "risk_gap",
+    "execution_gap",
+]);
+export const GapActionSchema = z.enum([
+    "fix_now",
+    "document",
+    "pause_for_human",
+]);
+export const GapFindingSchema = z.object({
+    category: GapCategorySchema,
+    /** Concrete observation grounding the finding — never speculation. */
+    evidence: z.string().min(1),
+    description: z.string().min(1),
+    recommendedAction: GapActionSchema,
+    /** ACs this finding relates to, e.g. ["AC-3"]. */
+    affectedAcs: z.array(z.string()).optional(),
+    /** True when the finding overlaps one of the issue's Non-Goals. */
+    nonGoal: z.boolean().optional(),
+});
 /**
  * Condensed QA verdict summary for structured log output (#434).
  *
@@ -117,6 +178,13 @@ export const QaSummarySchema = z.object({
     gaps: z.array(z.string()),
     /** List of improvement suggestions from QA */
     suggestions: z.array(z.string()),
+    /**
+     * Structured gap findings parsed from the `SEQUANT_QA_GAPS` marker (#937).
+     * Present only when the marker was found and validated; `gaps` above
+     * always carries the union of marker + prose descriptions (dedupe'd) so
+     * marker-unaware consumers never regress.
+     */
+    findings: z.array(GapFindingSchema).optional(),
 });
 /**
  * Log entry for a single phase execution
@@ -198,6 +266,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/state-schema.d.ts

@@ -149,6 +149,7 @@ export declare const AcceptanceCriterionSchema: z.ZodObject<{
     }>;
     verifiedAt: z.ZodOptional<z.ZodString>;
     notes: z.ZodOptional<z.ZodString>;
+    evidence: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type AcceptanceCriterion = z.infer<typeof AcceptanceCriterionSchema>;
 /**
@@ -172,6 +173,7 @@ export declare const AcceptanceCriteriaSchema: z.ZodObject<{
         }>;
         verifiedAt: z.ZodOptional<z.ZodString>;
         notes: z.ZodOptional<z.ZodString>;
+        evidence: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     extractedAt: z.ZodString;
     summary: z.ZodObject<{
@@ -281,6 +283,7 @@ export declare const IssueStateSchema: z.ZodObject<{
             }>;
             verifiedAt: z.ZodOptional<z.ZodString>;
             notes: z.ZodOptional<z.ZodString>;
+            evidence: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
         extractedAt: z.ZodString;
         summary: z.ZodObject<{
@@ -430,6 +433,7 @@ export declare const WorkflowStateSchema: z.ZodObject<{
                 }>;
                 verifiedAt: z.ZodOptional<z.ZodString>;
                 notes: z.ZodOptional<z.ZodString>;
+                evidence: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>;
             extractedAt: z.ZodString;
             summary: z.ZodObject<{
@@ -538,7 +542,7 @@ export declare function createPhaseState(status?: PhaseStatus): PhaseState;
 /**
  * Create acceptance criterion
  */
-export declare function createAcceptanceCriterion(id: string, description: string, verificationMethod?: ACVerificationMethod): AcceptanceCriterion;
+export declare function createAcceptanceCriterion(id: string, description: string, verificationMethod?: ACVerificationMethod, evidence?: string): AcceptanceCriterion;
 /**
  * Create acceptance criteria tracking structure
  */

package/dist/src/lib/workflow/state-schema.js

@@ -149,6 +149,12 @@ export const AcceptanceCriterionSchema = z.object({
     verifiedAt: z.string().datetime().optional(),
     /** Additional notes about verification */
     notes: z.string().optional(),
+    /**
+     * Explicit `Evidence:` clause declared on the AC line (#938). When present,
+     * this is what verificationMethod was resolved from instead of keyword
+     * inference — see `resolveVerificationMethod` in ac-parser.ts.
+     */
+    evidence: z.string().optional(),
 });
 /**
  * Acceptance criteria tracking for an issue
@@ -369,12 +375,13 @@ export function createPhaseState(status = "pending") {
 /**
  * Create acceptance criterion
  */
-export function createAcceptanceCriterion(id, description, verificationMethod = "manual") {
+export function createAcceptanceCriterion(id, description, verificationMethod = "manual", evidence) {
     return {
         id,
         description,
         verificationMethod,
         status: "pending",
+        ...(evidence !== undefined ? { evidence } : {}),
     };
 }
 /**

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

@@ -83,6 +83,15 @@ export interface ExecutionConfig {
     dryRun: boolean;
     /** Enable MCP servers in headless mode (true by default, false if --no-mcp flag used) */
     mcp: boolean;
+    /**
+     * Claude Desktop MCP server names explicitly opted in via
+     * `settings.run.mcpAllowlist` (#936). Both `ExecutionConfig` producers
+     * (`buildExecutionConfig`, `ready-gate.ts`'s `buildPhaseConfig`) read
+     * this from settings the same way, so it cannot drift between them the
+     * way #833's `phaseTimeout` once did. `phase-executor.ts` forwards it
+     * verbatim onto `AgentExecutionConfig.mcpAllowlist`.
+     */
+    mcpAllowlist?: string[];
     /**
      * Enable automatic retry with MCP fallback.
      * When true (default), failed phases are retried with MCP disabled.
@@ -182,6 +191,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 +277,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 +310,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 +536,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
@@ -641,4 +714,9 @@ export interface IssueExecutionContext {
      * around verbose Claude streaming.
      */
     phasePauseHandle?: PhasePauseHandle;
+    /**
+     * @internal Test seam for the #964 qa-verdict comment post. Defaults to a
+     * real `GitHubProvider().postComment` when unset.
+     */
+    postComment?: (issueNumber: number, body: string) => Promise<void>;
 }

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;