sequant 2.10.0 → 2.11.0

package/dist/src/lib/locks/lock-manager.d.ts

@@ -18,6 +18,7 @@
  * method is a no-op (no fs touches, no warnings). Mirrors the
  * `OrchestratorRenderer` pattern at `src/lib/cli-ui/run-renderer.ts:244`.
  */
+import { renameSync, linkSync } from "fs";
 import { type AcquireResult, type LockFile, type LockListing, type SignalOtherResult, type StaleReason } from "./types.js";
 export interface LockManagerOptions {
     /** Directory holding `<issue>.lock` files (default: `.sequant/locks`). */
@@ -52,7 +53,11 @@ export interface LockManagerOptions {
 }
 /** Detect orchestrator mode purely from env (no caching) so tests can mutate. */
 export declare function isOrchestratorMode(): boolean;
-/** Resolve the locks directory honoring `SEQUANT_LOCKS_DIR` for test isolation. */
+/**
+ * Resolve the locks directory. Priority: explicit option > `SEQUANT_LOCKS_DIR`
+ * > the shared git checkout root (#909) > plain cwd-relative (non-git
+ * fallback, preserves pre-#909 behavior).
+ */
 export declare function resolveLocksDir(explicit?: string): string;
 /**
  * Resolve `SEQUANT_SKILL_LOCK_TTL_MS` (milliseconds) — env override for the
@@ -86,6 +91,81 @@ export declare function classifyStaleness(args: {
     maxLockAgeMs?: number;
     isPidAlive: (pid: number) => boolean;
 }): StaleReason | null;
+/** The fields that uniquely identify a lock's holder (any lock class). */
+export interface StaleLockIdentity {
+    pid: number;
+    hostname: string;
+    startedAt: string;
+}
+/**
+ * Atomically steal a stale lock (#908) — the compare-and-swap replacement for
+ * the old unlink-then-create, shared by both lock classes so they cannot drift
+ * (AC-1, AC-2).
+ *
+ * `unlink(lockPath)` removes whatever inode is at the path — including a fresh
+ * lock a winner created microseconds earlier — so two sessions that both
+ * classified the same lock stale could each destroy the other's fresh lock and
+ * both "win" (two holders, the exact failure the lock exists to prevent). A
+ * bare `rename(lockPath, …)` has the identical flaw: rename moves whatever is
+ * at the path, fresh or not.
+ *
+ * So take possession atomically, THEN check identity:
+ *
+ *   1. `rename(lockPath → tmp)` — atomic on POSIX. Of two racing stealers,
+ *      exactly one moves the current inode; the loser gets `ENOENT`.
+ *   2. Read what we moved. If it is the stale holder we `classified`, discard
+ *      it (`unlink tmp`) — the steal is legitimate and `lockPath` is now free
+ *      for the caller's terminal `openSync(…, "wx")` to claim.
+ *   3. If it is NOT that holder, a fresh lock appeared between our staleness
+ *      read and our rename. We must not destroy it: `link` it back into place
+ *      (never overwrites) and report the steal lost. A third session that
+ *      claimed `lockPath` in the gap is left intact and our copy becomes a
+ *      harmless `*.steal.*` orphan, which `list()` ignores (it matches only
+ *      `.lock`).
+ *
+ * Returns `true` only when this caller legitimately removed the stale lock it
+ * classified. `false` means "lost" — the caller falls through to `writeAtomic`,
+ * whose `O_CREAT|O_EXCL` arbitrates the real holder (accepting the current
+ * occupant on `EEXIST`).
+ *
+ * NOTE ON DEVIATION FROM THE #908 SPEC: the plan prescribed a *plain*
+ * rename-away ("rename, unlink tmp, ENOENT = lost", then fall through). That is
+ * behaviorally identical to the `unlink` it replaces — verified by a
+ * hand-driven interleave: in the issue's own documented ordering
+ * (`A.steal → A.create → B.steal → B.create`) B's rename succeeds on A's fresh
+ * lock and destroys it, two holders, same as today. The identity check in
+ * step 2/3 is what actually makes AC-1 ("loser cannot remove the winner's fresh
+ * lock") hold and makes AC-4's mutation test possible.
+ *
+ * RESIDUAL: the sub-millisecond window at step 3 where a third session's
+ * O_EXCL create races our `link`-back is not fully closed — plain lock files
+ * admit no atomic compare-and-swap on content. It is far narrower than the
+ * original (which failed on a *single* race, every time a stealer's removal
+ * landed on a fresh lock) and never destroys a live lock. Fully closing it is a
+ * larger protocol change (claim file / lease), flagged for follow-up.
+ *
+ * NEVER THROWS. A steal is an opportunistic optimization on the acquire path;
+ * no filesystem error here is worth crashing `acquire` over. Errors degrade to
+ * "lost" (`false`) and the caller's terminal create surfaces any real
+ * environment problem (EACCES etc.) with the same errno the pre-#908 path did.
+ * The one active recovery: if the `link`-back restore fails because the
+ * filesystem refuses hard links (EPERM/ENOTSUP), fall back to renaming `tmp`
+ * back into place — leaving a fresh lock renamed-away IS the two-holder bug,
+ * so restoring it outweighs `link`'s no-overwrite guarantee on such a
+ * filesystem.
+ *
+ * `ops` is a test seam for the link/rename syscalls — production callers omit
+ * it. Injecting a failing `link` is the only way to drive the fallback branch
+ * deterministically (capability errors like ENOTSUP cannot be provoked on a
+ * normal tmpdir).
+ */
+export declare function stealStaleLock(lockPath: string, classified: StaleLockIdentity, self: {
+    pid: number;
+    now: number;
+}, ops?: {
+    link?: typeof linkSync;
+    rename?: typeof renameSync;
+}): boolean;
 export declare class LockManager {
     private readonly locksDir;
     private readonly staleAgeMs;

package/dist/src/lib/locks/lock-manager.js

@@ -18,18 +18,57 @@
  * method is a no-op (no fs touches, no warnings). Mirrors the
  * `OrchestratorRenderer` pattern at `src/lib/cli-ui/run-renderer.ts:244`.
  */
-import { openSync, closeSync, writeSync, readFileSync, existsSync, unlinkSync, mkdirSync, readdirSync, statSync, } from "fs";
-import { join, resolve } from "path";
+import { openSync, closeSync, writeSync, readFileSync, existsSync, unlinkSync, renameSync, linkSync, mkdirSync, readdirSync, statSync, } from "fs";
+import { basename, dirname, join, resolve } from "path";
+import { execFileSync } from "child_process";
 import * as os from "os";
 import { DEFAULT_LOCKS_DIR, DEFAULT_MAX_LOCK_AGE_MS, DEFAULT_SKILL_LOCK_TTL_MS, DEFAULT_STALE_AGE_MS, LockFileSchema, } from "./types.js";
 /** Detect orchestrator mode purely from env (no caching) so tests can mutate. */
 export function isOrchestratorMode() {
     return Boolean(process.env.SEQUANT_ORCHESTRATOR);
 }
-/** Resolve the locks directory honoring `SEQUANT_LOCKS_DIR` for test isolation. */
+/**
+ * Resolve the checkout root shared by the main worktree and every linked
+ * worktree of the same repository (#909). `--git-common-dir` (unlike
+ * `--show-toplevel`) points at the same physical `.git` for all of them, so
+ * a linked worktree lands on the main checkout's `.sequant/locks` instead of
+ * growing its own — matching what `pre-tool.sh`'s checkout guard reads.
+ * Returns `null` outside a git repository (or if `git` is unavailable).
+ *
+ * Deliberately omits `--path-format=absolute` (Git >=2.31, 2021): that flag
+ * failing on an older git would fall into the same `catch` as "not a repo"
+ * and silently re-open the bug this function exists to fix, with no signal
+ * that the cause was an old toolchain rather than a bare directory. Plain
+ * `--git-common-dir` (Git >=2.5, 2015) is resolved by hand instead —
+ * `resolve(cwd, out)` is a no-op when git already returned an absolute path
+ * (the common linked-worktree case) and anchors a relative one (the common
+ * main-checkout case) to `cwd`, so it is correct either way.
+ */
+function resolveGitCheckoutRoot(cwd) {
+    try {
+        const commonDir = execFileSync("git", ["rev-parse", "--git-common-dir"], {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        return commonDir ? dirname(resolve(cwd, commonDir)) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve the locks directory. Priority: explicit option > `SEQUANT_LOCKS_DIR`
+ * > the shared git checkout root (#909) > plain cwd-relative (non-git
+ * fallback, preserves pre-#909 behavior).
+ */
 export function resolveLocksDir(explicit) {
     const fromEnv = process.env.SEQUANT_LOCKS_DIR;
-    return resolve(explicit ?? fromEnv ?? DEFAULT_LOCKS_DIR);
+    if (explicit !== undefined || fromEnv !== undefined) {
+        return resolve(explicit ?? fromEnv ?? DEFAULT_LOCKS_DIR);
+    }
+    const gitRoot = resolveGitCheckoutRoot(process.cwd());
+    return resolve(gitRoot ?? process.cwd(), DEFAULT_LOCKS_DIR);
 }
 /**
  * Resolve `SEQUANT_SKILL_LOCK_TTL_MS` (milliseconds) — env override for the
@@ -121,6 +160,184 @@ export function classifyStaleness(args) {
         return "age-exceeded";
     return null;
 }
+/** Read just the identity fields of a lock file. Null if missing/unparseable. */
+function readLockIdentity(lockPath) {
+    if (!existsSync(lockPath))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(lockPath, "utf-8"));
+        if (parsed &&
+            typeof parsed.pid === "number" &&
+            typeof parsed.hostname === "string" &&
+            typeof parsed.startedAt === "string") {
+            return {
+                pid: parsed.pid,
+                hostname: parsed.hostname,
+                startedAt: parsed.startedAt,
+            };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Best-effort unlink for a steal's private `tmp` file. Failure to remove it is
+ * never worth crashing `acquire` over — the orphan sweep below reclaims it.
+ */
+function unlinkBestEffort(path) {
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        // Best-effort: swept later by sweepStealOrphans.
+    }
+}
+/**
+ * Age past which a `<lock>.steal.<pid>.<ts>` file cannot be an in-flight steal
+ * (the live window is microseconds) and is reclaimed as an orphan.
+ */
+const STEAL_ORPHAN_TTL_MS = 10 * 60 * 1000;
+/**
+ * Reap aged `*.steal.*` orphans left behind by lost restore races (the
+ * documented EEXIST branch below). Best-effort throughout: steals are the only
+ * producer and the only consumer, `list()` never sees these files, and a
+ * failure here must not affect the steal itself.
+ */
+function sweepStealOrphans(lockPath, now) {
+    const prefix = `${basename(lockPath)}.steal.`;
+    try {
+        const dir = dirname(lockPath);
+        for (const name of readdirSync(dir)) {
+            if (!name.startsWith(prefix))
+                continue;
+            const orphan = join(dir, name);
+            try {
+                if (now - statSync(orphan).mtimeMs > STEAL_ORPHAN_TTL_MS) {
+                    unlinkSync(orphan);
+                }
+            }
+            catch {
+                // Raced away or unreadable — skip it.
+            }
+        }
+    }
+    catch {
+        // Locks dir unreadable — nothing to sweep.
+    }
+}
+/**
+ * Atomically steal a stale lock (#908) — the compare-and-swap replacement for
+ * the old unlink-then-create, shared by both lock classes so they cannot drift
+ * (AC-1, AC-2).
+ *
+ * `unlink(lockPath)` removes whatever inode is at the path — including a fresh
+ * lock a winner created microseconds earlier — so two sessions that both
+ * classified the same lock stale could each destroy the other's fresh lock and
+ * both "win" (two holders, the exact failure the lock exists to prevent). A
+ * bare `rename(lockPath, …)` has the identical flaw: rename moves whatever is
+ * at the path, fresh or not.
+ *
+ * So take possession atomically, THEN check identity:
+ *
+ *   1. `rename(lockPath → tmp)` — atomic on POSIX. Of two racing stealers,
+ *      exactly one moves the current inode; the loser gets `ENOENT`.
+ *   2. Read what we moved. If it is the stale holder we `classified`, discard
+ *      it (`unlink tmp`) — the steal is legitimate and `lockPath` is now free
+ *      for the caller's terminal `openSync(…, "wx")` to claim.
+ *   3. If it is NOT that holder, a fresh lock appeared between our staleness
+ *      read and our rename. We must not destroy it: `link` it back into place
+ *      (never overwrites) and report the steal lost. A third session that
+ *      claimed `lockPath` in the gap is left intact and our copy becomes a
+ *      harmless `*.steal.*` orphan, which `list()` ignores (it matches only
+ *      `.lock`).
+ *
+ * Returns `true` only when this caller legitimately removed the stale lock it
+ * classified. `false` means "lost" — the caller falls through to `writeAtomic`,
+ * whose `O_CREAT|O_EXCL` arbitrates the real holder (accepting the current
+ * occupant on `EEXIST`).
+ *
+ * NOTE ON DEVIATION FROM THE #908 SPEC: the plan prescribed a *plain*
+ * rename-away ("rename, unlink tmp, ENOENT = lost", then fall through). That is
+ * behaviorally identical to the `unlink` it replaces — verified by a
+ * hand-driven interleave: in the issue's own documented ordering
+ * (`A.steal → A.create → B.steal → B.create`) B's rename succeeds on A's fresh
+ * lock and destroys it, two holders, same as today. The identity check in
+ * step 2/3 is what actually makes AC-1 ("loser cannot remove the winner's fresh
+ * lock") hold and makes AC-4's mutation test possible.
+ *
+ * RESIDUAL: the sub-millisecond window at step 3 where a third session's
+ * O_EXCL create races our `link`-back is not fully closed — plain lock files
+ * admit no atomic compare-and-swap on content. It is far narrower than the
+ * original (which failed on a *single* race, every time a stealer's removal
+ * landed on a fresh lock) and never destroys a live lock. Fully closing it is a
+ * larger protocol change (claim file / lease), flagged for follow-up.
+ *
+ * NEVER THROWS. A steal is an opportunistic optimization on the acquire path;
+ * no filesystem error here is worth crashing `acquire` over. Errors degrade to
+ * "lost" (`false`) and the caller's terminal create surfaces any real
+ * environment problem (EACCES etc.) with the same errno the pre-#908 path did.
+ * The one active recovery: if the `link`-back restore fails because the
+ * filesystem refuses hard links (EPERM/ENOTSUP), fall back to renaming `tmp`
+ * back into place — leaving a fresh lock renamed-away IS the two-holder bug,
+ * so restoring it outweighs `link`'s no-overwrite guarantee on such a
+ * filesystem.
+ *
+ * `ops` is a test seam for the link/rename syscalls — production callers omit
+ * it. Injecting a failing `link` is the only way to drive the fallback branch
+ * deterministically (capability errors like ENOTSUP cannot be provoked on a
+ * normal tmpdir).
+ */
+export function stealStaleLock(lockPath, classified, self, ops = {}) {
+    const rename = ops.rename ?? renameSync;
+    const link = ops.link ?? linkSync;
+    const tmp = `${lockPath}.steal.${self.pid}.${self.now}`;
+    sweepStealOrphans(lockPath, self.now);
+    try {
+        rename(lockPath, tmp);
+    }
+    catch {
+        // ENOENT: another stealer moved it first — cleanly lost. Anything else
+        // (EACCES, EROFS, …): nothing was moved, so there is nothing to restore;
+        // report lost and let the terminal create surface the environment problem.
+        return false;
+    }
+    const moved = readLockIdentity(tmp);
+    if (moved &&
+        moved.pid === classified.pid &&
+        moved.hostname === classified.hostname &&
+        moved.startedAt === classified.startedAt) {
+        unlinkBestEffort(tmp);
+        return true;
+    }
+    // A fresh (or corrupt) holder slipped in between our read and our rename.
+    // Put back exactly what we took, without overwriting a newer claim, then
+    // lose the steal.
+    try {
+        link(tmp, lockPath);
+        unlinkBestEffort(tmp);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== "EEXIST" && code !== "ENOENT") {
+            // Hard links refused (EPERM/ENOTSUP/…) — restore by rename instead.
+            // The overwrite risk this reintroduces needs a third session's create
+            // to land in this same sub-ms window ON a no-hardlink filesystem;
+            // not restoring at all destroys the fresh lock every time.
+            try {
+                rename(tmp, lockPath);
+            }
+            catch {
+                // Out of options — degrades to pre-#908 behavior on this filesystem.
+            }
+        }
+        // EEXIST: `lockPath` was re-claimed in the gap → leave `tmp` as an orphan
+        // (swept by sweepStealOrphans) rather than clobber the new holder.
+        // ENOENT: `tmp` already gone.
+    }
+    return false;
+}
 export class LockManager {
     locksDir;
     staleAgeMs;
@@ -192,7 +409,15 @@ export class LockManager {
                 isPidAlive: this.isPidAlive,
             });
             if (staleReason) {
-                this.unlinkSafe(lockPath);
+                // Compare-and-swap steal, not a blind unlink (#908): only remove the
+                // stale inode we classified, never a fresh lock a racing winner may
+                // have created at this path in the meantime. Win or lose, fall through
+                // to `writeAtomic` — its `O_CREAT|O_EXCL` arbitrates the real holder.
+                stealStaleLock(lockPath, {
+                    pid: existing.pid,
+                    hostname: existing.hostname,
+                    startedAt: existing.startedAt,
+                }, { pid: this.pid, now: this.now() });
             }
             else {
                 return {

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

@@ -49,6 +49,78 @@ export declare const LockFileSchema: z.ZodObject<{
     skipPidCheck: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type LockFile = z.infer<typeof LockFileSchema>;
+/**
+ * Filename of the checkout-scoped lock (#901), stored alongside the numeric
+ * `<issue>.lock` files. Deliberately non-numeric so `LockManager.list()` —
+ * which parses each filename as an issue number and skips anything else —
+ * ignores it rather than surfacing a bogus `NaN` issue.
+ */
+export declare const CHECKOUT_LOCK_FILENAME = "checkout.lock";
+/**
+ * On-disk payload for the checkout-scoped lock (#901).
+ *
+ * The per-issue lock from #625 is keyed on issue number, so two sessions
+ * working *different* issues take different lock files and never contend —
+ * yet `git checkout`, `reset`, `rebase` and `merge` are global to a working
+ * tree. This lock represents the tree itself.
+ *
+ * Extends `LockFileSchema` with:
+ *  - `issue` — which issue the holder is working on, so a refusal can name it
+ *    (AC-2) and point the loser at the right worktree (AC-3).
+ *  - `sessionId` — Claude Code's per-session id, read from the PreToolUse
+ *    stdin envelope. Optional: it is the *preferred* holder identity because a
+ *    skill shell's PID dies immediately after acquire, but the hook falls back
+ *    to `pid`+`hostname` when the envelope does not carry one, so nothing
+ *    depends on it being present.
+ */
+export declare const CheckoutLockFileSchema: z.ZodObject<{
+    pid: z.ZodNumber;
+    hostname: z.ZodString;
+    startedAt: z.ZodString;
+    command: z.ZodString;
+    skipPidCheck: z.ZodOptional<z.ZodBoolean>;
+    issue: z.ZodNumber;
+    sessionId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CheckoutLockFile = z.infer<typeof CheckoutLockFileSchema>;
+/** Identity of the session asking for the checkout lock. */
+export interface CheckoutHolderIdentity {
+    /** Claude Code session id, when the caller knows it. */
+    sessionId?: string;
+    /** Falls back to these when `sessionId` is absent on either side. */
+    pid: number;
+    hostname: string;
+    /**
+     * The issue this session is working on (#906).
+     *
+     * Last-resort ownership proxy for `skipPidCheck` locks, whose PID is dead
+     * by the time anything checks it. Optional because a live process releasing
+     * its own lock identifies itself by PID and needs none of this — but a
+     * skill shell that omits it can no longer release, which is deliberate.
+     */
+    issue?: number;
+}
+/** Outcome of `CheckoutLock.acquire()`. */
+export type CheckoutAcquireResult = {
+    acquired: true;
+    lockPath: string;
+    /** True when the caller already held it — re-acquire is idempotent. */
+    reentrant: boolean;
+} | {
+    acquired: false;
+    holder: CheckoutLockFile;
+    lockPath: string;
+    stale: false;
+    staleReason: null;
+};
+/** Listing entry for the checkout lock, mirroring `LockListing`. */
+export interface CheckoutLockListing {
+    holder: CheckoutLockFile;
+    ageMs: number;
+    stale: boolean;
+    staleReason: StaleReason | null;
+    lockPath: string;
+}
 /** Outcome of `LockManager.acquire()`. */
 export type AcquireResult = {
     acquired: true;

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

@@ -45,3 +45,31 @@ export const LockFileSchema = z.object({
      */
     skipPidCheck: z.boolean().optional(),
 });
+/**
+ * Filename of the checkout-scoped lock (#901), stored alongside the numeric
+ * `<issue>.lock` files. Deliberately non-numeric so `LockManager.list()` —
+ * which parses each filename as an issue number and skips anything else —
+ * ignores it rather than surfacing a bogus `NaN` issue.
+ */
+export const CHECKOUT_LOCK_FILENAME = "checkout.lock";
+/**
+ * On-disk payload for the checkout-scoped lock (#901).
+ *
+ * The per-issue lock from #625 is keyed on issue number, so two sessions
+ * working *different* issues take different lock files and never contend —
+ * yet `git checkout`, `reset`, `rebase` and `merge` are global to a working
+ * tree. This lock represents the tree itself.
+ *
+ * Extends `LockFileSchema` with:
+ *  - `issue` — which issue the holder is working on, so a refusal can name it
+ *    (AC-2) and point the loser at the right worktree (AC-3).
+ *  - `sessionId` — Claude Code's per-session id, read from the PreToolUse
+ *    stdin envelope. Optional: it is the *preferred* holder identity because a
+ *    skill shell's PID dies immediately after acquire, but the hook falls back
+ *    to `pid`+`hostname` when the envelope does not carry one, so nothing
+ *    depends on it being present.
+ */
+export const CheckoutLockFileSchema = LockFileSchema.extend({
+    issue: z.number().int().positive(),
+    sessionId: z.string().optional(),
+});

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

@@ -57,6 +57,23 @@ export interface AgentSettings {
      */
     isolateParallel: boolean;
 }
+/**
+ * The Agent SDK's closed reasoning-effort enum (#914). Single source of
+ * truth — reused by `PhasePolicySchema`'s zod validation below and by
+ * `cli-flags.ts:parsePhaseSpecFlag` for the `--efforts` CLI boundary, so the
+ * two validation points cannot drift apart on which values are accepted.
+ */
+export declare const EFFORT_LEVELS: readonly ["low", "medium", "high", "xhigh", "max"];
+/**
+ * A single phase's `model`/`effort` override for the claude-code driver
+ * (#914). See `RunSettings.phases`.
+ */
+export interface PhasePolicy {
+    /** Model alias/ID, passed through unvalidated to the Agent SDK. */
+    model?: string;
+    /** Reasoning effort — validated against the SDK's closed enum. */
+    effort?: (typeof EFFORT_LEVELS)[number];
+}
 /**
  * Aider-specific settings for the aider agent driver.
  */
@@ -166,6 +183,21 @@ export interface RunSettings {
      * Default: true.
      */
     relay?: boolean;
+    /**
+     * Per-phase `model`/`effort` overrides for the claude-code driver (#914),
+     * keyed by phase name. Absent by default — zero behavior change until
+     * opted in. Overridable per-invocation with `--models`/`--efforts`
+     * (CLI > settings > absent, resolved by `resolvePhasePolicies` in
+     * `config-resolver.ts`).
+     */
+    phases?: Record<string, PhasePolicy>;
+    /**
+     * Evidence-based effort escalation on quality-loop retries (#915). Default
+     * `false` — raising effort raises token spend, which is the user's call.
+     * Overridable per-invocation with `--escalate-effort` (CLI > settings >
+     * default). See `effort-escalation.ts` for the resolver.
+     */
+    effortEscalation: boolean;
 }
 /**
  * Scope assessment threshold configuration
@@ -304,6 +336,25 @@ export declare const AgentSettingsSchema: z.ZodObject<{
     }>>;
     isolateParallel: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
+/**
+ * Zod schema for a single phase's model/effort override (#914).
+ *
+ * Model aliases/IDs pass through unvalidated — they churn independently of
+ * sequant releases, and the Agent SDK's `query()` call errors clearly on a
+ * bad one. Effort validates against the SDK's closed enum at settings-parse
+ * time since that set is stable and a typo here would otherwise silently
+ * fall through to the SDK default.
+ */
+export declare const PhasePolicySchema: z.ZodObject<{
+    model: z.ZodOptional<z.ZodString>;
+    effort: z.ZodOptional<z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+        xhigh: "xhigh";
+        max: "max";
+    }>>;
+}, z.core.$strip>;
 /** Zod schema for RunSettings */
 export declare const RunSettingsSchema: z.ZodObject<{
     logJson: z.ZodDefault<z.ZodBoolean>;
@@ -335,6 +386,17 @@ export declare const RunSettingsSchema: z.ZodObject<{
         extraArgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>;
     relay: z.ZodDefault<z.ZodBoolean>;
+    phases: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        model: z.ZodOptional<z.ZodString>;
+        effort: z.ZodOptional<z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+            xhigh: "xhigh";
+            max: "max";
+        }>>;
+    }, z.core.$strip>>>;
+    effortEscalation: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
 /** Zod schema for ScopeThreshold (base — fields required, no defaults) */
 export declare const ScopeThresholdSchema: z.ZodObject<{
@@ -428,6 +490,17 @@ export declare const SettingsSchema: z.ZodObject<{
             extraArgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>;
         relay: z.ZodDefault<z.ZodBoolean>;
+        phases: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            model: z.ZodOptional<z.ZodString>;
+            effort: z.ZodOptional<z.ZodEnum<{
+                low: "low";
+                medium: "medium";
+                high: "high";
+                xhigh: "xhigh";
+                max: "max";
+            }>>;
+        }, z.core.$strip>>>;
+        effortEscalation: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
     agents: z.ZodDefault<z.ZodObject<{
         parallel: z.ZodDefault<z.ZodBoolean>;

package/dist/src/lib/settings.js

@@ -13,10 +13,18 @@
 import { readFile, writeFile, fileExists, ensureDir } from "./fs.js";
 import { dirname } from "path";
 import { z } from "zod";
+import { getPhaseNames } from "./workflow/phase-registry.js";
 /** Path to project-level settings file */
 export const SETTINGS_PATH = ".sequant/settings.json";
 /** Current settings schema version */
 export const SETTINGS_VERSION = "1.0";
+/**
+ * The Agent SDK's closed reasoning-effort enum (#914). Single source of
+ * truth — reused by `PhasePolicySchema`'s zod validation below and by
+ * `cli-flags.ts:parsePhaseSpecFlag` for the `--efforts` CLI boundary, so the
+ * two validation points cannot drift apart on which values are accepted.
+ */
+export const EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max"];
 // ─── Zod Schemas (AC-1, AC-5) ────────────────────────────────────────────────
 /** Zod schema for RotationSettings */
 export const RotationSettingsSchema = z.object({
@@ -36,6 +44,19 @@ export const AgentSettingsSchema = z.object({
     model: z.enum(["haiku", "sonnet", "opus"]).default("haiku"),
     isolateParallel: z.boolean().default(false),
 });
+/**
+ * Zod schema for a single phase's model/effort override (#914).
+ *
+ * Model aliases/IDs pass through unvalidated — they churn independently of
+ * sequant releases, and the Agent SDK's `query()` call errors clearly on a
+ * bad one. Effort validates against the SDK's closed enum at settings-parse
+ * time since that set is stable and a typo here would otherwise silently
+ * fall through to the SDK default.
+ */
+export const PhasePolicySchema = z.object({
+    model: z.string().optional(),
+    effort: z.enum(EFFORT_LEVELS).optional(),
+});
 /** Zod schema for RunSettings */
 export const RunSettingsSchema = z.object({
     logJson: z.boolean().default(true),
@@ -66,6 +87,23 @@ export const RunSettingsSchema = z.object({
     agent: z.string().optional(),
     aider: AiderSettingsSchema.optional(),
     relay: z.boolean().default(true),
+    /**
+     * Per-phase `model`/`effort` overrides for the claude-code driver (#914).
+     * Absent by default — zero behavior change until opted in. Keyed by phase
+     * name (validated against `getPhaseNames()` via `KNOWN_KEYS["run.phases"]`
+     * as a non-fatal warning, not a schema-level rejection — a typo'd phase
+     * name here should not crash a run the way an invalid `effort` enum does).
+     */
+    phases: z.record(z.string(), PhasePolicySchema).optional(),
+    /**
+     * Evidence-based effort escalation on quality-loop retries (#915). Default
+     * `false` — raising effort raises token spend, which is the user's call.
+     * When enabled, a retried phase execution (loop iteration ≥ 2, or a
+     * `sequant ready` QA-pass loop re-run) resolves one effort tier above its
+     * configured/inherited base for that execution only. See
+     * `effort-escalation.ts` for the resolver.
+     */
+    effortEscalation: z.boolean().default(false),
 });
 /** Zod schema for ScopeThreshold (base — fields required, no defaults) */
 export const ScopeThresholdSchema = z.object({
@@ -186,7 +224,13 @@ const KNOWN_KEYS = {
         "agent",
         "aider",
         "relay",
+        "phases",
     ]),
+    // #914: keyed by real phase name so a typo (`run.phases.exce`) warns
+    // instead of silently resolving to nothing. Computed from the registry
+    // rather than hardcoded so a new phase registration doesn't need a
+    // matching edit here.
+    "run.phases": new Set(getPhaseNames()),
     agents: new Set(["parallel", "model", "isolateParallel"]),
     scopeAssessment: new Set([
         "enabled",
@@ -406,6 +450,7 @@ export const DEFAULT_SETTINGS = {
         staleBranchThreshold: 5, // Block QA/test if feature is >5 commits behind main
         resolvedIssueTTL: 7, // Auto-prune resolved issues after 7 days
         relay: true, // Enable interactive relay (#383) by default
+        effortEscalation: false, // #915: off by default — raises token spend
     },
     agents: DEFAULT_AGENT_SETTINGS,
     scopeAssessment: DEFAULT_SCOPE_ASSESSMENT_SETTINGS,