sequant 2.9.0 → 2.11.0

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

@@ -9,6 +9,7 @@ import type { ShutdownManager } from "../shutdown.js";
 import type { WorktreeInfo } from "./worktree-manager.js";
 import type { SequantError } from "../errors.js";
 import type { ErrorCategory } from "./error-classifier.js";
+import type { ReadyResult } from "./ready-gate.js";
 export type { WorkflowEventEmitter, WorkflowEvents, WorkflowEventListener, IssueEventStatus, BaseEventPayload, RunEventPayload, PhaseStartedPayload, PhaseCompletedPayload, PhaseFailedPayload, IssueStatusChangedPayload, QaVerdictPayload, ProgressPayload, } from "./event-emitter.js";
 /**
  * Canonical Zod schema for all workflow phases.
@@ -131,6 +132,14 @@ export interface ExecutionConfig {
      * poll budget is preserved.
      */
     onActivity?: (text: string) => void;
+    /**
+     * Runtime callback invoked while an auto-wait (#804) is in progress, once
+     * per tick plus once when it ends. Used to keep the renderer and the `-q`
+     * heartbeat showing the wait and its wake time, so a multi-hour pause reads
+     * as deliberate rather than as the silent stall of #574. Not serialized —
+     * set per-call by the orchestrator, like {@link onActivity}.
+     */
+    onAutoWait?: (notice: AutoWaitNotice) => void;
     /**
      * Enable interactive relay (#383). When true, phase-executor sets
      * `SEQUANT_RELAY=true` in the agent environment so the PostToolUse hook
@@ -147,6 +156,75 @@ export interface ExecutionConfig {
      * QA pass does NOT skip the checks that catch the #318/#529/#570 class.
      */
     fullQa?: boolean;
+    /**
+     * Run the post-QA ready gate after the standard phases succeed (#817).
+     *
+     * When true, `runIssueWithLogging` invokes the existing `sequant ready`
+     * engine (`runReadyGate`) at the PR seam — before rebase/PR so the gate's
+     * auto-fix commits land in the PR — driving the issue to the configured
+     * `settings.ready.policy` threshold. It NEVER merges: the run terminates with
+     * the issue in `waiting_for_human_merge` (ready) or `blocked` (guard halt).
+     * Default off; when unset the run path is byte-identical to pre-#817.
+     */
+    readyGate?: boolean;
+    /**
+     * Total wait budget, in minutes, for auto-waiting out an exhausted
+     * rate-limit window (#804). `0` (the default) disables auto-wait entirely,
+     * preserving the #761/#799 halt behavior byte-for-byte.
+     *
+     * When a phase fails with a window-exhausted `RateLimitError` whose reset
+     * lies within the remaining budget, the executor sleeps until the reset and
+     * retries the phase instead of returning the failure. Named for the
+     * *behavior* (waiting), not the mechanism, so it survives a future move from
+     * in-process sleep to out-of-process rescheduling.
+     *
+     * This is a TOTAL budget across the issue, not a per-occurrence allowance —
+     * 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).
+ */
+export interface AutoWaitNotice {
+    /** Issue the wait belongs to. */
+    issueNumber: number;
+    /** Phase whose retry is being waited for. */
+    phase: string;
+    /** Epoch ms at which the wait ends (reset + buffer). */
+    wakeAtMs: number;
+    /** Ms remaining at the time of this notice. `0` on the final notice. */
+    remainingMs: number;
+    /**
+     * Display string, already formatted. Built from `formatRateLimitMessage`
+     * plus the wake time — never by re-appending `resetsAt` to an
+     * already-formatted driver message (the #799 doubled-string trap).
+     */
+    message: string;
+    /** True on the terminal notice, once the wait has ended or been aborted. */
+    done: boolean;
 }
 /**
  * Default execution configuration
@@ -190,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
@@ -205,6 +293,23 @@ export interface IssueResult {
     prNumber?: number;
     /** PR URL if created after successful QA */
     prUrl?: string;
+    /**
+     * Set when PR creation was attempted after passing QA but failed (#879).
+     * A failed `createPR` used to be a non-fatal yellow warning while the issue
+     * still reported success — so a run could "pass" while producing no PR. When
+     * present, `success` is false and the run summary counts the issue as failed
+     * 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
@@ -232,6 +337,25 @@ export interface IssueResult {
      * privacy contract). Absent on success.
      */
     failureCategory?: ErrorCategory;
+    /**
+     * Outcome of the post-QA ready gate (#817), present only when the run was
+     * invoked with `--ready-gate` and the gate actually ran (i.e. the standard
+     * phases succeeded). Carries the terminal reason, the persisted issue status
+     * (`waiting_for_human_merge` / `blocked` — never merged), and the rendered
+     * report the summary and PR body surface. Absent on runs without the flag.
+     */
+    readyGate?: ReadyResult;
+    /**
+     * Why the ready gate did NOT run, when `--ready-gate` was requested but the
+     * gate threw (#817). Mutually exclusive with {@link IssueResult.readyGate}.
+     *
+     * A gate crash is deliberately non-fatal — the phase work is already
+     * committed and the PR still opens — but it must not be silent. Without this
+     * field a run whose gate died is byte-identical in the summary to one that
+     * never asked for a gate, so the user believes a second look happened when it
+     * did not. The summary renders this as an explicit "gate did not run" line.
+     */
+    readyGateError?: string;
 }
 /**
  * CLI options for the run command, merged with settings and env config.
@@ -263,8 +387,6 @@ export interface RunOptions {
     autoDetectPhases?: boolean;
     /** Enable automatic worktree creation for issue isolation */
     worktreeIsolation?: boolean;
-    /** Reuse existing worktrees instead of creating new ones */
-    reuseWorktrees?: boolean;
     /** Suppress version warnings and non-essential output */
     quiet?: boolean;
     /** Chain issues: each branches from previous (requires --sequential) */
@@ -299,6 +421,13 @@ export interface RunOptions {
      * Resolution priority: this CLI flag → settings.run.mcp → default (true)
      */
     noMcp?: boolean;
+    /**
+     * Total minutes willing to wait for an exhausted rate-limit window to reopen
+     * before halting (#804). `0` (default) keeps today's immediate halt.
+     * Resolution priority: this CLI flag → SEQUANT_AUTO_WAIT_MINUTES →
+     * settings.run.autoWaitMinutes → default (0).
+     */
+    autoWaitMinutes?: number;
     /**
      * Resume from last completed phase.
      * Reads phase markers from GitHub issue comments and skips completed phases.
@@ -324,7 +453,9 @@ export interface RunOptions {
     noPr?: boolean;
     /**
      * Force re-execution of issues even if they have completed status.
-     * Bypasses the pre-flight state guard that skips ready_for_merge/merged issues.
+     * Bypasses the pre-flight state guard that skips completed issues — see
+     * `isCompletedIssueStatus` (completed-status.ts) for exactly which statuses
+     * that covers, and why `blocked` is not one of them.
      */
     force?: boolean;
     /**
@@ -361,6 +492,17 @@ export interface RunOptions {
      * #705: now a hidden no-op alias — the boxed Ink TUI is the default, so
      * `--experimental-tui` only parses for backward compatibility and no longer
      * gates rendering. Kept so existing scripts/muscle-memory don't break.
+     *
+     * INTENTIONALLY INERT — do not delete (#810). A dead-surface sweep of
+     * `RunOptions` will correctly observe that nothing branches on this field.
+     * That is the design, not a defect: the flag's whole job is to parse and do
+     * nothing, so scripts written against #705 keep working. Its inertness is
+     * asserted, not incidental — `run-flags.test.ts` ("--experimental-tui is a
+     * no-op"), `cli.integration.test.ts` (hidden from `--help`, still parses),
+     * and `run-tui.integration.test.ts` all pin it. Contrast `reuseWorktrees`,
+     * removed in #810: that field had no flag, no consumer, and no test, so it
+     * promised behavior nothing delivered. The distinction is a flag deliberately
+     * kept parseable versus a type field nobody could ever reach.
      */
     experimentalTui?: boolean;
     /**
@@ -375,6 +517,39 @@ export interface RunOptions {
      * Resolution priority: this CLI flag → settings.run.relay → default (true).
      */
     relay?: boolean;
+    /**
+     * Run the post-QA ready gate after the standard phases succeed (#817). Set via
+     * `--ready-gate`. When true, the run drives the issue to the configured
+     * `settings.ready.policy` threshold through the existing `sequant ready`
+     * engine before creating the PR, then STOPS at the human merge gate — it never
+     * merges. Off by default; opt-in only, so an unset flag leaves the run path
+     * (including the #749 break-to-PR behavior) unchanged. Reuses `ready`'s policy
+     * 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
@@ -415,12 +590,23 @@ export interface BatchResult {
  * `"activity"` (#543): sub-phase activity ping. `extra.text` carries a short
  * one-line snippet (e.g. last line of agent output) for the dashboard's
  * `nowLine`. Fires at most ~10 Hz from the phase executor.
+ *
+ * `"waiting"` (#804): an auto-wait for a rate-limit window is in progress.
+ * `extra.text` is the display message and `extra.wakeAtMs` the wake time;
+ * a `"waiting"` event WITHOUT `wakeAtMs` is the terminal notice that clears
+ * the waiting state. Unlike `"activity"`, this must reach both display paths
+ * — a multi-hour pause with no signal is the #574 complaint at 60x scale.
  */
-export type ProgressCallback = (issue: number, phase: string, event: "start" | "complete" | "failed" | "activity", extra?: {
+export type ProgressCallback = (issue: number, phase: string, event: "start" | "complete" | "failed" | "activity" | "waiting", extra?: {
     durationSeconds?: number;
     error?: string;
     iteration?: number;
     text?: string;
+    /**
+     * `"waiting"` (#804): epoch ms at which an auto-wait ends. Absent on the
+     * terminal notice, which clears the waiting state.
+     */
+    wakeAtMs?: number;
 }) => void;
 /**
  * #672 AC-2: fired once per issue after the executor has resolved the final

package/dist/src/lib/workflow/types.js

@@ -45,4 +45,5 @@ export const DEFAULT_CONFIG = {
     dryRun: false,
     mcp: true,
     retry: true,
+    autoWaitMinutes: 0,
 };

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;
@@ -145,6 +152,21 @@ export declare function filterResumedPhases(issueNumber: number, phases: Phase[]
     phases: Phase[];
     skipped: Phase[];
 };
+/**
+ * Run the frozen dependency install for a freshly provisioned worktree and
+ * surface (rather than swallow) a failed install.
+ *
+ * Mirrors the status check in `reinstallIfLockfileChanged` (#846): a plain
+ * `npm install` self-heals a stale/absent lockfile, but the frozen `npm ci`
+ * hard-fails (exit 1, no node_modules). Without this check a failing install
+ * left a silently dependency-less worktree whose breakage only surfaced later
+ * as a confusing phase error. The warning names the resolved command so the
+ * user can rerun it by hand.
+ *
+ * @returns true if the install succeeded, false if it failed (warn-and-continue)
+ * @internal Exported for testing
+ */
+export declare function installWorktreeDeps(worktreePath: string, packageManager: string | undefined, verbose: boolean): boolean;
 /**
  * Create or reuse a worktree for an issue
  * @param baseBranch - Optional branch to use as base instead of origin/main (for chain mode)
@@ -225,17 +247,25 @@ export declare function rebaseBeforePR(worktreePath: string, issueNumber: number
  * @param opts.qaVerdict QA verdict for the run; a non-A+ stopping state
  *   (anything other than `READY_FOR_MERGE`) surfaces a note so a human reviewer
  *   sees why the run broke to PR without reaching A+ (#749).
+ * @param opts.readyGateReport Rendered `sequant ready` gap report (#817). Set
+ *   only when the run used `--ready-gate`; surfaces the gate outcome (threshold
+ *   reached vs guard halt) in the PR body the same way `sequant ready` does.
  * @internal Exported for testing
  */
 export declare function buildAutomatedPRBody(issueNumber: number, opts?: {
     stackManifest?: string;
     qaVerdict?: string;
+    readyGateReport?: string;
 }): string;
 /**
  * Push branch and create a PR after successful QA.
  *
  * Handles both fresh PR creation and detection of existing PRs.
- * Failures are warnings — they don't fail the run.
+ *
+ * Returns `{ success: false, error }` on failure. As of #879 the caller
+ * (`runIssueWithLogging`) treats an attempted-but-failed PR as a run failure:
+ * a passing run that produced no PR is not a success. This function itself
+ * still only reports — it never throws — so relay teardown runs regardless.
  *
  * @param worktreePath Path to the worktree
  * @param issueNumber Issue number
@@ -246,10 +276,13 @@ export declare function buildAutomatedPRBody(issueNumber: number, opts?: {
  * @param stackOptions When set under --stacked, `prBase` overrides the default
  *   PR target (otherwise gh defaults to the repo's default branch) and
  *   `stackManifest` is appended to the PR body. (#605)
+ * @param qaVerdict QA verdict surfaced in the PR body when non-A+ (#749).
+ * @param readyGateReport Rendered `sequant ready` gap report, set only when the
+ *   run used `--ready-gate` (#817).
  * @returns PRCreationResult with PR info or error
  * @internal Exported for testing
  */
 export declare function createPR(worktreePath: string, issueNumber: number, issueTitle: string, branch: string, verbose: boolean, labels?: string[], stackOptions?: {
     prBase?: string;
     stackManifest?: string;
-}, qaVerdict?: string): PRCreationResult;
+}, qaVerdict?: string, readyGateReport?: string): PRCreationResult;

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

@@ -8,7 +8,8 @@ import chalk from "chalk";
 import { spawnSync } from "child_process";
 import { existsSync, readFileSync } from "fs";
 import path from "path";
-import { PM_CONFIG } from "../stacks.js";
+import { resolvePackageManager, resolvePackageManagerConfig, } from "../stacks.js";
+import { resolveDiffBase } from "./git-diff-utils.js";
 import { getResumablePhasesForIssue } from "./phase-detection.js";
 import { GitHubProvider } from "./platforms/github.js";
 /**
@@ -155,7 +156,11 @@ export function checkWorktreeFreshness(worktreePath, verbose, baseBranch = "main
         const countResult = spawnSync("git", ["-C", worktreePath, "rev-list", "--count", `${mergeBase}..${baseHead}`], { stdio: "pipe" });
         if (countResult.status === 0) {
             result.commitsBehind = parseInt(countResult.stdout.toString().trim(), 10);
-            // Consider stale if more than 5 commits behind (configurable threshold)
+            // Consider stale if more than 5 commits behind. NOT configurable — the
+            // threshold is the literal below, and a stale-but-clean worktree is
+            // force-removed and rebuilt on the strength of it (see the recreate
+            // branch in `ensureWorktree`). Surfaced in #810; left as a literal here
+            // because making it configurable is a behavior change, not a comment fix.
             result.isStale = result.commitsBehind > 5;
         }
     }
@@ -200,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 [];
@@ -231,7 +244,8 @@ export function listWorktrees() {
  * Get changed files in a worktree compared to main
  */
 export function getWorktreeChangedFiles(worktreePath) {
-    const result = spawnSync("git", ["-C", worktreePath, "diff", "--name-only", "main...HEAD"], { stdio: "pipe" });
+    const diffBase = resolveDiffBase(worktreePath, "main");
+    const result = spawnSync("git", ["-C", worktreePath, "diff", "--name-only", `${diffBase}...HEAD`], { stdio: "pipe" });
     if (result.status !== 0)
         return [];
     return result.stdout
@@ -245,7 +259,8 @@ export function getWorktreeChangedFiles(worktreePath) {
  * Returns aggregate metrics only - no file paths to preserve privacy
  */
 export function getWorktreeDiffStats(worktreePath) {
-    const result = spawnSync("git", ["-C", worktreePath, "diff", "--stat", "main...HEAD"], { stdio: "pipe" });
+    const diffBase = resolveDiffBase(worktreePath, "main");
+    const result = spawnSync("git", ["-C", worktreePath, "diff", "--stat", `${diffBase}...HEAD`], { stdio: "pipe" });
     if (result.status !== 0) {
         return { filesChanged: 0, linesAdded: 0 };
     }
@@ -314,6 +329,63 @@ export function filterResumedPhases(issueNumber, phases, resume) {
     const skipped = phases.filter((p) => !resumable.includes(p));
     return { phases: resumable, skipped };
 }
+/**
+ * Run the frozen dependency install for a freshly provisioned worktree and
+ * surface (rather than swallow) a failed install.
+ *
+ * Mirrors the status check in `reinstallIfLockfileChanged` (#846): a plain
+ * `npm install` self-heals a stale/absent lockfile, but the frozen `npm ci`
+ * hard-fails (exit 1, no node_modules). Without this check a failing install
+ * left a silently dependency-less worktree whose breakage only surfaced later
+ * as a confusing phase error. The warning names the resolved command so the
+ * user can rerun it by hand.
+ *
+ * @returns true if the install succeeded, false if it failed (warn-and-continue)
+ * @internal Exported for testing
+ */
+export function installWorktreeDeps(worktreePath, packageManager, verbose) {
+    if (verbose) {
+        console.log(chalk.gray(`    Installing dependencies...`));
+    }
+    // Two independent questions, resolved in order against the worktree itself.
+    //
+    // WHICH manager: the manifest's packageManager is a snapshot and may be
+    // absent, so fall back to the worktree's own lockfile — that keeps this in
+    // agreement with what new-feature.sh would run for the same project (#870).
+    //
+    // WHICH commands for it: yarn's frozen install differs between classic
+    // (`--frozen-lockfile`) and berry (`--immutable`), and both majors use
+    // `yarn.lock`, so the manager's identity alone cannot say which (#871).
+    //
+    // The worktree is checked out by now, so its package.json / .yarnrc.yml /
+    // yarn.lock are all readable here.
+    const pmConfig = resolvePackageManagerConfig(resolvePackageManager(packageManager, worktreePath), worktreePath);
+    // ciInstall, not installSilent: a plain `npm install` normalizes and
+    // rewrites package-lock.json (observed: npm 10 strips the `libc` fields a
+    // newer npm committed), so every provisioned worktree started dirty. That
+    // one unstaged file cascaded: rebaseBeforePR refused to run, stale
+    // worktrees read as having "uncommitted changes" and were never recreated,
+    // and chain checkpoints skipped on an out-of-scope dirty file. A frozen
+    // install never touches the lockfile. Same substitution #803 made for
+    // merge-check's combined-branch test. The `!existsSync(node_modules)`
+    // guard at the call site means `npm ci`'s wipe-and-reinstall has nothing
+    // to wipe.
+    const [cmd, ...args] = pmConfig.ciInstall.split(" ");
+    const command = [cmd, ...args].join(" ");
+    const installResult = spawnSync(cmd, args, {
+        cwd: worktreePath,
+        stdio: "pipe",
+    });
+    if (installResult.status !== 0) {
+        // stderr may be empty on some failures — the resolved command alone is
+        // enough to act on, so always name it (AC-2).
+        const error = installResult.stderr?.toString().trim() ?? "";
+        const detail = error ? `: ${error}` : "";
+        console.log(chalk.yellow(`    !  Dependency install failed (${command})${detail}`));
+        return false;
+    }
+    return true;
+}
 /**
  * Create or reuse a worktree for an issue
  * @param baseBranch - Optional branch to use as base instead of origin/main (for chain mode)
@@ -513,17 +585,7 @@ export async function ensureWorktree(issueNumber, title, verbose, packageManager
     // Install dependencies if needed
     const nodeModulesPath = path.join(worktreePath, "node_modules");
     if (!existsSync(nodeModulesPath)) {
-        if (verbose) {
-            console.log(chalk.gray(`    Installing dependencies...`));
-        }
-        // Use detected package manager or default to npm
-        const pm = packageManager || "npm";
-        const pmConfig = PM_CONFIG[pm];
-        const [cmd, ...args] = pmConfig.installSilent.split(" ");
-        spawnSync(cmd, args, {
-            cwd: worktreePath,
-            stdio: "pipe",
-        });
+        installWorktreeDeps(worktreePath, packageManager, verbose);
     }
     if (verbose) {
         console.log(chalk.green(`    ✔ Worktree ready: ${worktreePath}`));
@@ -742,9 +804,14 @@ export function reinstallIfLockfileChanged(worktreePath, packageManager, verbose
     }
     // Re-run install to sync node_modules with updated lockfile
     console.log(chalk.blue(`    Reinstalling dependencies (lockfile changed)...`));
-    const pm = packageManager || "npm";
-    const pmConfig = PM_CONFIG[pm];
-    const [cmd, ...args] = pmConfig.installSilent.split(" ");
+    // Same two-step resolution as installWorktreeDeps: manifest-or-lockfile for
+    // the manager (#870), then classic-vs-berry for its commands (#871).
+    const pmConfig = resolvePackageManagerConfig(resolvePackageManager(packageManager, worktreePath), worktreePath);
+    // ciInstall for the same reason as provisioning (see ensureWorktree): this
+    // reinstall exists because a rebase pulled in a NEW lockfile, so installing
+    // exactly what that lockfile says — never rewriting it — is the semantic
+    // the function's own name promises.
+    const [cmd, ...args] = pmConfig.ciInstall.split(" ");
     const installResult = spawnSync(cmd, args, {
         cwd: worktreePath,
         stdio: "pipe",
@@ -888,6 +955,9 @@ function qaVerdictNote(verdict) {
  * @param opts.qaVerdict QA verdict for the run; a non-A+ stopping state
  *   (anything other than `READY_FOR_MERGE`) surfaces a note so a human reviewer
  *   sees why the run broke to PR without reaching A+ (#749).
+ * @param opts.readyGateReport Rendered `sequant ready` gap report (#817). Set
+ *   only when the run used `--ready-gate`; surfaces the gate outcome (threshold
+ *   reached vs guard halt) in the PR body the same way `sequant ready` does.
  * @internal Exported for testing
  */
 export function buildAutomatedPRBody(issueNumber, opts) {
@@ -901,9 +971,18 @@ export function buildAutomatedPRBody(issueNumber, opts) {
     ];
     // #749: surface a non-A+ QA verdict in the PR body (not just the run log) so
     // a reviewer sees why the run broke to PR rather than reaching A+.
-    const note = qaVerdictNote(opts?.qaVerdict);
-    if (note) {
-        bodyLines.push(note, ``);
+    //
+    // #817: when the ready gate ran, its report already carries the terminal
+    // verdict and stop reason (a superset of the #749 note), so prefer it and
+    // suppress the standalone note to avoid a contradictory double-headline.
+    if (opts?.readyGateReport) {
+        bodyLines.push(opts.readyGateReport, ``);
+    }
+    else {
+        const note = qaVerdictNote(opts?.qaVerdict);
+        if (note) {
+            bodyLines.push(note, ``);
+        }
     }
     // #605 AC-4: emit stack manifest before the trailer so reviewers see the
     // chain at the top of the body. Manifest is only set under --stacked.
@@ -917,7 +996,11 @@ export function buildAutomatedPRBody(issueNumber, opts) {
  * Push branch and create a PR after successful QA.
  *
  * Handles both fresh PR creation and detection of existing PRs.
- * Failures are warnings — they don't fail the run.
+ *
+ * Returns `{ success: false, error }` on failure. As of #879 the caller
+ * (`runIssueWithLogging`) treats an attempted-but-failed PR as a run failure:
+ * a passing run that produced no PR is not a success. This function itself
+ * still only reports — it never throws — so relay teardown runs regardless.
  *
  * @param worktreePath Path to the worktree
  * @param issueNumber Issue number
@@ -928,10 +1011,13 @@ export function buildAutomatedPRBody(issueNumber, opts) {
  * @param stackOptions When set under --stacked, `prBase` overrides the default
  *   PR target (otherwise gh defaults to the repo's default branch) and
  *   `stackManifest` is appended to the PR body. (#605)
+ * @param qaVerdict QA verdict surfaced in the PR body when non-A+ (#749).
+ * @param readyGateReport Rendered `sequant ready` gap report, set only when the
+ *   run used `--ready-gate` (#817).
  * @returns PRCreationResult with PR info or error
  * @internal Exported for testing
  */
-export function createPR(worktreePath, issueNumber, issueTitle, branch, verbose, labels, stackOptions, qaVerdict) {
+export function createPR(worktreePath, issueNumber, issueTitle, branch, verbose, labels, stackOptions, qaVerdict, readyGateReport) {
     const github = new GitHubProvider();
     // Step 1: Check for existing PR on this branch
     const existingPRInfo = github.viewPRByBranchSync(branch, worktreePath);
@@ -970,6 +1056,7 @@ export function createPR(worktreePath, issueNumber, issueTitle, branch, verbose,
     const prBody = buildAutomatedPRBody(issueNumber, {
         stackManifest: stackOptions?.stackManifest,
         qaVerdict,
+        readyGateReport,
     });
     const prResult = github.createPRCliSync(prTitle, prBody, branch, worktreePath, stackOptions?.prBase);
     if (prResult.exitCode !== 0) {

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;