limn-review 0.1.172 → 0.1.174

package/dist/ai/providers/codex.js

@@ -57,6 +57,7 @@ import { confirmCodexAccount, recheckCodexAccount } from '../codex/app-server.js
 import { CODEX_API_KEY_NOT_AVAILABLE_MESSAGE, CODEX_SIGN_IN_UNCHECKED_MESSAGE, codexUsageSource, detectCodex, } from '../codex/detect.js';
 import { addUsage, cleanCodexError, codexTokensAsAgentTokens, progressFromEvent, stepFromEvent, stderrRefusals, stderrTail, usageDelta, } from '../codex/events.js';
 import { pathGuardHook, verifyHookTrusted } from '../codex/hook.js';
+import { noteProviderFailure } from '../usage-lockout.js';
 import { codexBinary, codexHome, ensureCodexHomeConfig } from '../codex/home.js';
 import { armCodexThreadSweeps, queueCodexThreadCleanup } from '../codex/threads.js';
 import { runCodexExec } from '../codex/run.js';
@@ -150,6 +151,16 @@ export function codexExecEnv(credential, hook, base = process.env) {
 // ---- shared run plumbing ------------------------------------------------------------------------
 const DEFAULT_AGENT_TIMEOUT_MS = 45 * 60_000;
 const DEFAULT_COMPLETE_TIMEOUT_MS = 5 * 60_000;
+/**
+ * `execFailure`, and a usage limit noted as a LOCKOUT (ai/usage-lockout.ts): every automatic run on
+ * Codex stands down until the reset the error names. Every run kind's failure passes through here.
+ */
+function failureOf(res) {
+    const failure = execFailure(res);
+    if (failure)
+        noteProviderFailure('codex', failure);
+    return failure;
+}
 /** Why a finished `codex exec` did not produce an answer, as one sentence; null when it did. */
 export function execFailure(res) {
     if (res.cancelled)
@@ -295,7 +306,7 @@ async function complete(req) {
         finally {
             queueCodexThreadCleanup(home, res.threadId);
         }
-        const failure = execFailure(res);
+        const failure = failureOf(res);
         if (failure)
             throw new CodexRunError(failure, res.cancelled);
         const text = res.finalResponse.trim();
@@ -547,7 +558,7 @@ export async function runAgentUnchecked(spec) {
             first = await runCodexExec(args, { cwd, env, signal, onEvent, stdin: spec.prompt, timeoutMs });
             final = first;
             usage = first.usage;
-            failure = execFailure(first);
+            failure = failureOf(first);
             if (!failure && resultTool && toolSchema) {
                 let verdict = await judge(z, resultTool, toolSchema, first.finalResponse);
                 if (!verdict.ok) {
@@ -569,7 +580,7 @@ export async function runAgentUnchecked(spec) {
                         if (retry.usage)
                             usage = addUsage(usage, usageDelta(retry.usage, first.usage));
                         final = retry;
-                        failure = execFailure(retry);
+                        failure = failureOf(retry);
                         if (!failure) {
                             verdict = await judge(z, resultTool, toolSchema, retry.finalResponse);
                             if (!verdict.ok)

package/dist/ai/usage-lockout.js

@@ -0,0 +1,108 @@
+import { parseRetryAtMs } from '../review/claude-review/auto-retry.js';
+/** How long a usage limit locks a provider out when its error names no reset time. */
+export const LOCKOUT_DEFAULT_MS = 60 * 60 * 1000;
+/** A lock never runs longer than this (a misread date must not lock a provider out for a month). */
+export const LOCKOUT_MAX_MS = 8 * 24 * 60 * 60 * 1000;
+// ⚠ NARROWER than auto-retry's USAGE_LIMIT: a plain rate limit, a 429 or "too many requests" is a
+// short throttle, not a lockout. Only the account's own usage allowance being used up locks it out.
+// Linear (no nested quantifiers): it runs over provider text.
+const LOCKOUT = /usage limit|hit your (?!rate)[\w'’ ]{0,30}limit|out of (?:usage )?credits|quota exceeded/i;
+/** Does this error say the provider's usage allowance is used up? */
+export function isUsageLockoutError(error) {
+    const e = (error ?? '').slice(0, 2000);
+    return e.trim() !== '' && LOCKOUT.test(e);
+}
+/**
+ * When the lockout this error describes ends (ms), or null when the error is not a usage limit.
+ * The reset the error names when it names one (never before the failure), else the default.
+ */
+export function lockoutUntilFromError(error, failedAtMs) {
+    if (!isUsageLockoutError(error))
+        return null;
+    const named = parseRetryAtMs(error, failedAtMs);
+    const until = named != null && named > failedAtMs ? named : failedAtMs + LOCKOUT_DEFAULT_MS;
+    return Math.min(until, failedAtMs + LOCKOUT_MAX_MS);
+}
+const locks = new Map();
+/**
+ * Record a failure of `provider` when it is a usage limit (any other error is ignored). A later
+ * reset replaces an earlier one; an earlier one never shortens a lock already held.
+ */
+export function noteProviderFailure(provider, error, atMs = Date.now()) {
+    const until = lockoutUntilFromError(error, atMs);
+    if (until == null)
+        return;
+    const held = locks.get(provider);
+    if (!held || held.untilMs < until)
+        locks.set(provider, { untilMs: until });
+}
+/** The provider's lockout now, or null (an ended lock is forgotten). */
+export function usageLockout(provider, nowMs = Date.now()) {
+    const held = locks.get(provider);
+    if (!held)
+        return null;
+    if (held.untilMs <= nowMs) {
+        locks.delete(provider);
+        return null;
+    }
+    return held;
+}
+/** Is any provider locked out now? (cheap: lets a caller skip resolving the default provider). */
+export function anyUsageLockout(nowMs = Date.now()) {
+    for (const p of [...locks.keys()])
+        if (usageLockout(p, nowMs))
+            return true;
+    return false;
+}
+export function isLockedOut(provider, nowMs = Date.now()) {
+    return usageLockout(provider, nowMs) != null;
+}
+/** Forget a lock (a new sign-in) — and the test hook (no provider ⇒ all). */
+export function clearUsageLockout(provider) {
+    if (provider)
+        locks.delete(provider);
+    else
+        locks.clear();
+}
+/**
+ * WHICH PROVIDERS AN AUTOMATIC RUN USES (pure). `pair`: the workspace asks for Claude + Codex.
+ *   • a pair ⇒ every provider in `order` that is ready and not locked out (two ⇒ a pair, one ⇒ alone);
+ *   • a single run ⇒ the default, unless it is LOCKED OUT: then the other provider when it is ready
+ *     and not locked, else none (skipped). A default that is merely not ready is the caller's
+ *     existing wait (it is not moved).
+ * Empty ⇒ do not run now.
+ */
+export function automaticRunProviders(opts) {
+    const { defaultProvider, pair, order, ready, locked } = opts;
+    if (pair)
+        return order.filter((p) => ready(p) && !locked(p));
+    if (!locked(defaultProvider))
+        return [defaultProvider];
+    const other = order.find((p) => p !== defaultProvider && ready(p) && !locked(p));
+    return other ? [other] : [];
+}
+/** The SPA's one line (`MeResponse.ai.providers.<p>.usageLockedUntil`), as ISO-8601, or null. */
+export function usageLockedUntilIso(provider, nowMs = Date.now()) {
+    const l = usageLockout(provider, nowMs);
+    return l ? new Date(l.untilMs).toISOString() : null;
+}
+/**
+ * THE BOOT'S RE-DERIVATION: the newest failed review row per provider, from the last
+ * LOCKOUT_MAX_MS. Each is noted at its finish time (a lock already over is not kept). Never throws.
+ */
+export async function restoreUsageLockouts(read) {
+    try {
+        for (const r of await read()) {
+            if (r.provider !== 'claude' && r.provider !== 'codex')
+                continue;
+            if (r.finishedAtMs == null)
+                continue;
+            noteProviderFailure(r.provider, r.error, r.finishedAtMs);
+            usageLockout(r.provider); // drops it at once when it has already ended
+        }
+    }
+    catch {
+        /* a lock is an optimisation: never fails a boot */
+    }
+}
+//# sourceMappingURL=usage-lockout.js.map

package/dist/api/routes/me.js

@@ -12,6 +12,7 @@ import { getAiRuntimeStatus } from '../../ai/runtime.js';
 import { codexKindStatus, detectClaudeAuth, NO_CLAUDE_AUTH_MESSAGE } from '../../review/auth.js';
 import { resolveAiCredential } from '../../ai/credentials.js';
 import { codexDetailCached } from '../../ai/codex/detect.js';
+import { usageLockedUntilIso } from '../../ai/usage-lockout.js';
 import { aiEffortSettingStatus } from '../../ai/effort.js';
 import { aiProviderSettingStatus, ALL_RUN_KINDS, CODEX_NOT_AVAILABLE_MESSAGE, CODEX_RUNNABLE, getActiveProvider, } from '../../ai/provider.js';
 import { getMyTurn } from '../../db/queries.js';
@@ -226,6 +227,8 @@ function agenticAiStatus() {
                 // models only when it is ready and signed in (the per-run choice, ai/run-choice.ts).
                 runtime: claudeRt.runtime,
                 runtimeMessage: claudeRt.runtimeMessage,
+                // A usage limit's lockout (ai/usage-lockout.ts): the Run area's one line.
+                usageLockedUntil: usageLockedUntilIso('claude'),
             },
             codex: {
                 runtime: codex.runtime,
@@ -245,6 +248,7 @@ function agenticAiStatus() {
                     const r = codexKindStatus(kind);
                     return r.status === 'ok' ? { auth: 'ok', message: null } : { auth: 'none', message: r.message };
                 }),
+                usageLockedUntil: usageLockedUntilIso('codex'),
             },
         },
     };

package/dist/db/erase-account.js

@@ -175,6 +175,8 @@ export async function eraseAccountData(accountId) {
         await tx.delete(schema.sonarSnapshots).where(eq(schema.sonarSnapshots.accountId, accountId)).execute();
         // The team-claim ledger (migration 0138): GitHub logins and heads. No FK, so this is the whole guarantee.
         await tx.delete(schema.teamClaimLines).where(eq(schema.teamClaimLines.accountId, accountId)).execute();
+        // The teammate lines the AI Review tab names (migration 0159): GitHub logins. No FK.
+        await tx.delete(schema.teamClaimSeen).where(eq(schema.teamClaimSeen.accountId, accountId)).execute();
         // The worktree ledger (migration 0146): which PR / ticket a checkout on disk was for. No FK. The
         // directories themselves become unledgered orphans the worktree sweep collects by age.
         await tx.delete(schema.worktreeLedger).where(eq(schema.worktreeLedger.accountId, accountId)).execute();
@@ -366,6 +368,8 @@ export function accountScopedTables() {
         { name: 'sonarSnapshots', col: schema.sonarSnapshots.accountId, table: schema.sonarSnapshots },
         // The team-claim ledger (migration 0138), erased explicitly above.
         { name: 'teamClaimLines', col: schema.teamClaimLines.accountId, table: schema.teamClaimLines },
+        // The teammate lines (migration 0159), erased explicitly above.
+        { name: 'teamClaimSeen', col: schema.teamClaimSeen.accountId, table: schema.teamClaimSeen },
         // The worktree ledger (migration 0146), erased explicitly above.
         { name: 'worktreeLedger', col: schema.worktreeLedger.accountId, table: schema.worktreeLedger },
         { name: 'workspaceSonar', col: schema.workspaceSonar.accountId, table: schema.workspaceSonar },

package/dist/db/migrations/0159_team_claims_default_on.sql

@@ -0,0 +1,21 @@
+-- TEAM CLAIMS ON BY DEFAULT (docs/CLAUDE-REVIEW.md § Team claims, 2026-11-02). The owner: "Just on
+-- by default on all workspaces". Every existing workspace is switched ON (also one switched off
+-- before); a new workspace's NULL now reads as ON (only a stored false is off).
+UPDATE `workspaces` SET `team_claims_enabled` = 1;
+--> statement-breakpoint
+-- A TEAMMATE'S LINE THIS LIMN STOOD DOWN FOR: one row per (account, PR, head, provider), shown on the
+-- AI Review tab ("Robin Dunn reviewed this commit with Claude · no comments").
+CREATE TABLE `team_claim_seen` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`account_id` integer NOT NULL,
+	`pr_id` integer NOT NULL,
+	`head_sha` text NOT NULL,
+	`provider` text NOT NULL,
+	`kind` text NOT NULL,
+	`login` text NOT NULL,
+	`description` text,
+	`line_at` integer NOT NULL,
+	`updated_at` integer DEFAULT (unixepoch()) NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `team_claim_seen_account_pr_head_provider` ON `team_claim_seen` (`account_id`,`pr_id`,`head_sha`,`provider`);

package/dist/db/migrations/meta/_journal.json

@@ -1114,6 +1114,13 @@
       "when": 1792224061016,
       "tag": "0158_repo_docs_unreadable",
       "breakpoints": true
+    },
+    {
+      "idx": 159,
+      "version": "6",
+      "when": 1792224062016,
+      "tag": "0159_team_claims_default_on",
+      "breakpoints": true
     }
   ]
 }

package/dist/db/schema.sqlite.js

@@ -3915,6 +3915,28 @@ export const teamClaimLines = sqliteTable('team_claim_lines', {
     // One head's rows (supersede, Clear, the tab's "Clear" offer).
     prHeadIdx: index('team_claim_lines_account_pr_head').on(t.accountId, t.prId, t.headSha),
 }));
+// 0159. A TEAMMATE'S LINE THIS LIMN STOOD DOWN FOR (docs/CLAUDE-REVIEW.md § Team claims → The
+// teammate's line on the tab): one row per (account, PR, head, provider) — the last `limn/review-<p>`
+// line by someone else that made this machine skip its auto review there. The AI Review tab says
+// "Robin Dunn reviewed this commit with Claude · no comments" from it, after a reload or a restart
+// (the skip memory itself is in process). `kind` 'reviewing' (their pending line) | 'reviewed'
+// (their success line); `description` = their line as GitHub shows it. Written by team-claim.ts on a
+// skip and by the reconciler when it re-reads the head. No FK on pr_id: BOTH delete paths delete its
+// rows (db/team-claim-lines-delete.ts), the erasure deletes everything.
+export const teamClaimSeen = sqliteTable('team_claim_seen', {
+    id: integer('id').primaryKey({ autoIncrement: true }),
+    accountId: integer('account_id').notNull(),
+    prId: integer('pr_id').notNull(),
+    headSha: text('head_sha').notNull(),
+    provider: text('provider').notNull(),
+    kind: text('kind', { enum: ['reviewing', 'reviewed'] }).notNull(),
+    login: text('login').notNull(),
+    description: text('description'),
+    lineAt: integer('line_at', { mode: 'timestamp' }).notNull(),
+    updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull().default(sql `(unixepoch())`),
+}, (t) => ({
+    prHeadProviderUx: uniqueIndex('team_claim_seen_account_pr_head_provider').on(t.accountId, t.prId, t.headSha, t.provider),
+}));
 // 0139. THIS DATABASE'S OWN FACTS (key → value) — never an account's, so not account-scoped and not
 // erased with one. `instance_id`: a random id written once (db/instance-id.ts) that names this
 // database file wherever it is moved; the reference-docs janitor's ownership marker.

package/dist/db/team-claim-lines-delete.js

@@ -14,5 +14,8 @@ export async function deleteSettledClaimLinesForPrs(tx, prIds) {
         .delete(tl)
         .where(and(inArray(tl.prId, prIds), not(and(eq(tl.whose, 'mine'), inArray(tl.state, ['claiming', 'pending'])))))
         .execute();
+    // The teammate lines the AI Review tab names (migration 0159): nothing on GitHub to release, so
+    // every row of these PRs goes.
+    await tx.delete(schema.teamClaimSeen).where(inArray(schema.teamClaimSeen.prId, prIds)).execute();
 }
 //# sourceMappingURL=team-claim-lines-delete.js.map

package/dist/review/budget-gate.js

@@ -1,8 +1,16 @@
+import { activeProviderId } from '../ai/provider-setting.js';
+import { anyUsageLockout, isLockedOut } from '../ai/usage-lockout.js';
 // THE ONE WAY AN AUTOMATIC AGENTIC RUN ASKS THE CLAUDE SPEND BUDGET (ai/budget.ts). False ⇒ skip
 // this run, do not queue it: every caller is a sweep or a hook that re-derives what is due, so the
 // work comes back by itself once the budget is under its limit again. A context without the gate (a
 // test's fake) is always allowed. A gate that throws allows — the budget never wedges a sweep.
-export async function automaticRunAllowed(ctx, accountId, what) {
+// ⚠ A PROVIDER LOCKED OUT BY ITS USAGE LIMIT (ai/usage-lockout.ts) is refused here too, the same
+// way: skipped, not queued. `provider`: the provider the run will use (absent ⇒ the default; null ⇒
+// the caller picks the provider later and asks the lock itself — the auto-review sweep, whose items
+// move to the other provider when the default is locked out).
+export async function automaticRunAllowed(ctx, accountId, what, provider) {
+    if (provider !== null && anyUsageLockout() && isLockedOut(provider ?? activeProviderId()))
+        return false;
     if (!ctx.aiBudget)
         return true;
     try {

package/dist/review/claude-review/auto-retry.js

@@ -24,6 +24,9 @@ const TRANSIENT = new RegExp([
     'service unavailable',
     'temporarily unavailable',
     'interrupted by restart',
+    // The run watchdog (run-watchdog.ts): a sleep, or a run that stopped making progress.
+    'interrupted: the computer slept',
+    'interrupted: the run stopped making progress',
     'not signed in',
     'not logged in',
     'please run /login',
@@ -69,6 +72,13 @@ export function parseRetryAtMs(error, failedAtMs) {
         if (Number.isFinite(ms) && ms > 0)
             return ms;
     }
+    // An ISO-8601 time after the reset words: "try again at 2026-11-02T20:54:00Z" (no zone ⇒ local).
+    const iso = /(?:try again|retry|resets?|available again|until)(?: at| after| on)?:?\s{1,3}(\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d{1,3})?)?(?:Z|[+-]\d{2}:?\d{2})?)/i.exec(e);
+    if (iso) {
+        const ms = Date.parse(iso[1].replace(' ', 'T'));
+        if (Number.isFinite(ms))
+            return ms;
+    }
     // "try again in 2 hours 5 minutes" / "resets in 45m".
     const inAt = /(?:try again|retry|resets?|available again) in\b/i.exec(e);
     if (inAt) {

package/dist/review/claude-review/auto-settings.js

@@ -50,7 +50,8 @@ import { onOff, writeSettingEvent } from '../../db/setting-event-write.js';
 //
 // TEAM CLAIMS ("Mark auto reviews on GitHub") ride the same route as one more column,
 // `team_claims_enabled` (migration 0134): may an AUTO review post a status line on the PR's head so
-// teammates' Limn skips it (team-claim.ts)? OFF by default — only a stored true is on.
+// teammates' Limn skips it (team-claim.ts)? ⚠ ON BY DEFAULT since 2026-11-02 (migration 0159 switched
+// every workspace on) — only a stored false is off, in every reader and in the writer.
 //
 // AUTOMATIC DESIGN DIAGRAMS ride the same route as one more column, `auto_diagrams_enabled`
 // (migration 0126): may a succeeded review (MANUAL OR AUTO) queue its design diagrams
@@ -174,8 +175,8 @@ export function autoReviewOf(row) {
         pairStrictness: resolvePairStrictness(row?.pairStrictness),
         autoPost: resolveAutoPostSettings(row?.autoPostEnabled, row?.autoPostSettings, row?.approveLeftovers),
         autoFix: resolveAutoFixSettings(row?.autoFixSettings),
-        // OFF unless explicitly switched on (0134).
-        teamClaimsEnabled: row?.teamClaimsEnabled === true,
+        // ON unless explicitly switched off (0159).
+        teamClaimsEnabled: row?.teamClaimsEnabled !== false,
     };
 }
 /**
@@ -323,8 +324,8 @@ export async function setWorkspaceAutoReview(ctx, accountId, workspaceId, change
     // Only a stored false is off (ON by default, 0126).
     const diagramsWas = existing.autoDiagramsEnabled !== false;
     const diagrams = autoDiagramsEnabled ?? diagramsWas;
-    // Only a stored true is on (OFF by default, 0134).
-    const claimsWas = existing.teamClaimsEnabled === true;
+    // Only a stored false is off (ON by default, 0159).
+    const claimsWas = existing.teamClaimsEnabled !== false;
     const claims = teamClaimsEnabled ?? claimsWas;
     const capOverride = dailyCap === undefined ? existing.dailyCap : dailyCap === AUTO_REVIEW_DAILY_CAP ? null : dailyCap;
     // Auto-posting: each field optional; a kind left out keeps its stored value.

package/dist/review/claude-review/auto.js

@@ -1,6 +1,7 @@
 import { config } from '../../config.js';
 import { agenticRunReady } from './ai-ready.js';
 import { AUTO_RETRY_BACKOFF_FIRST_MS, AUTO_RETRY_BACKOFF_LATER_MS, AUTO_RETRY_MAX_ATTEMPTS, classifyAutoReviewFailure, parseRetryAtMs, } from './auto-retry.js';
+import { usageLockout } from '../../ai/usage-lockout.js';
 import { automaticRunAllowed } from '../budget-gate.js';
 import { listAutoReviewWorkspaces } from './auto-settings.js';
 import { teamClaimHeldHead } from './team-claim.js';
@@ -65,6 +66,12 @@ export function autoReviewDue(input) {
             return { due: false, reason: 'not_retryable' };
         if (retry.attempts >= AUTO_RETRY_MAX_ATTEMPTS)
             return { due: false, reason: 'attempts_used' };
+        // ⚠ A USAGE LIMIT IS A LOCKOUT: while the provider that hit it is still locked out, the failure is
+        // not retried — not even when the default provider changed (a pair would run the locked half
+        // again; 2026-11-02, PR 199965: three failures a minute apart).
+        if (kind === 'usage_limit' && retry.lockedUntilMs != null && retry.lockedUntilMs > nowMs) {
+            return { due: false, reason: 'retry_wait', retryAtMs: retry.lockedUntilMs };
+        }
         if (retry.failedProvider !== retry.currentProvider)
             return { due: true };
         const resetAtMs = kind === 'usage_limit' ? (parseRetryAtMs(retry.error, retry.failedAtMs) ?? retry.usageResetAtMs ?? null) : null;
@@ -209,7 +216,9 @@ export async function runAutoReviewSweep(ctx, nowMs = Date.now(), press = null)
         // A PRESS does not ask: the reader chose the run (the SPA's two-press confirm ran when over).
         const budgetOk = new Map();
         for (const accountId of pressed ? [] : new Set(roster.map((w) => w.accountId))) {
-            const ok = await automaticRunAllowed(ctx, accountId, 'auto review');
+            // `null`: the budget only — the usage-limit lockout is asked per item, when its provider is
+            // chosen (manager.ts startAutoItem moves a locked default to the other provider).
+            const ok = await automaticRunAllowed(ctx, accountId, 'auto review', null);
             budgetOk.set(accountId, ok);
             if (!ok)
                 result.overBudget = true;
@@ -315,6 +324,7 @@ export async function runAutoReviewSweep(ctx, nowMs = Date.now(), press = null)
                         failedProvider: cand.provider,
                         currentProvider: providerNow,
                         usageResetAtMs,
+                        lockedUntilMs: usageLockout(cand.provider, nowMs)?.untilMs ?? null,
                     },
                     pressed,
                 });

package/dist/review/claude-review/manager.js

@@ -4,10 +4,12 @@ import { config } from '../../config.js';
 import { getTicketSource } from '../../tracker/ticket-source.js';
 import { agenticRunReady } from './ai-ready.js';
 import { automaticRunAllowed } from '../budget-gate.js';
+import { detectWake, FORCE_RELEASE_MS, runsToInterrupt, WATCHDOG_TICK_MS } from './run-watchdog.js';
+import { automaticRunProviders, isLockedOut, LOCKOUT_MAX_MS, noteProviderFailure, restoreUsageLockouts } from '../../ai/usage-lockout.js';
 import { decideReviewMode } from './routing.js';
 import { offeredSpecialists } from './specialists.js';
 import { buildUserPrompt, peerRef, pickReviewNonce, skipSummary, sonarHasContent, systemPromptForMode, untrustedTexts, } from './prompts.js';
-import { pairProvidersReady, readAutoReviewProvidersForPr } from './pair.js';
+import { PAIR_ORDER, pairProvidersReady, readAutoReviewProvidersForPr } from './pair.js';
 import { consolidatePair, notStartedHalf } from './pair-consolidate.js';
 import { markPairBusy } from './pair-view.js';
 import { preflightFor } from '../../ai/run-choice.js';
@@ -17,7 +19,7 @@ import { currentThreadAssessmentsForPrs, priorAssessmentsForProvider } from './t
 import { activeProviderId } from '../../ai/provider-setting.js';
 import { dropSettledReraises, similarTitles } from './settled-by-reply.js';
 import { attachFindingThreads } from './finding-replies.js';
-import { getClaudeReviewById, getLatestClaudeReview, getReviewPeerContexts, getReviewPrContext, insertQueuedReview, markReviewRanOn, markReviewPeersRead, isAutoReReviewSettled, isAutoRetryStillDue, loadPriorReviewForFollowUp, loadSettledByReplyFindings, loadUnjudgedReplyFindings, loadPriorRunForCarry, markReviewCommentsSeen, markReviewCancelled, markReviewFailed, markReviewRouted, reconcileOrphanedReviewRuns, saveReviewSuccess, } from './persist.js';
+import { getClaudeReviewById, getLatestClaudeReview, getReviewPeerContexts, getReviewPrContext, insertQueuedReview, markReviewRanOn, markReviewPeersRead, isAutoReReviewSettled, isAutoRetryStillDue, loadPriorReviewForFollowUp, loadSettledByReplyFindings, loadUnjudgedReplyFindings, loadPriorRunForCarry, markReviewCommentsSeen, markReviewCancelled, markReviewFailed, markReviewRouted, reconcileOrphanedReviewRuns, failedRunsSinceLastSuccess, saveReviewSuccess, } from './persist.js';
 import { emitClaudeReviewCompleted } from '../../platform/event-hooks.js';
 import { claimBeforeAutoRun, finishTeamClaim, postedReviewUrl, saveTeamClaimRecord, startTeamClaimRenew, stopTeamClaimRenew, } from './team-claim.js';
 import { ensureSonarSnapshot } from '../../sonar/snapshot.js';
@@ -338,10 +340,40 @@ async function startAutoItem(a) {
         // exists, or the PR's one automatic review is spent on a failure (ai-ready.ts).
         if (!agenticRunReady(ctx, 'review'))
             return;
+        // An AUTOMATIC run goes to the DEFAULT provider (Settings → AI), read now — unless the workspace
+        // asks for Claude + Codex (`auto_review_providers = 'both'`): then a PAIR when both can review,
+        // else the one that can. ⚠ A provider LOCKED OUT by its usage limit (ai/usage-lockout.ts) never
+        // starts an automatic run: a pair runs its other half alone; a single run moves to the other
+        // provider when that one is ready, else the item is dropped with no row (a skip, not a failure).
+        // A READER'S PRESS is the reader's choice: it is not moved.
+        const detect = preflightFor(ctx);
+        const nowMs = Date.now();
+        const wantsPair = (await readAutoReviewProvidersForPr(ctx, accountId, prId)) === 'both';
+        // ⚠ A PAIR drops a locked half EVEN ON A PRESS while the other half can run: that half would
+        // fail at once (2026-11-03: six pressed Codex halves over the limit, nothing reviewed). Only when
+        // every provider is locked does a press run anyway (the reader's choice).
+        const pick = (lockedOk) => automaticRunProviders({
+            defaultProvider: activeProviderId(),
+            pair: wantsPair,
+            order: PAIR_ORDER,
+            ready: (p) => detect(p, 'review').status === 'ok',
+            locked: (p) => !lockedOk && isLockedOut(p, nowMs),
+        });
+        let providers = pick(a.pressed === true && !wantsPair);
+        if (providers.length === 0 && a.pressed)
+            providers = pick(true);
+        if (providers.length === 0) {
+            ctx.log.info(`auto claude review pr ${prId}: skipped — no provider outside its usage limit`);
+            return;
+        }
+        let provider = providers[0];
+        let pair = providers.length === 2
+            ? { role: 'first', pairId: 0, secondProvider: providers[1], ...(a.pressed ? { pressed: true } : {}) }
+            : undefined;
         // THE CLAUDE SPEND BUDGET (ai/budget.ts): over it, drop the item before its row exists — the
         // sweeper re-derives it once the budget is under its limit again.
         // A READER'S PRESS is not asked again: they chose it (the SPA's over-budget confirm ran).
-        if (!a.pressed && !(await automaticRunAllowed(ctx, accountId, 'auto review')))
+        if (!a.pressed && !(await automaticRunAllowed(ctx, accountId, 'auto review', provider)))
             return;
         const prCtx = await getReviewPrContext(ctx, prId, accountId);
         if (!prCtx?.headSha)
@@ -356,19 +388,6 @@ async function startAutoItem(a) {
         else if (await isAutoReReviewSettled(ctx, prId, accountId, prCtx.headSha, a.commentsAtMs ?? null))
             return;
         const model = DEFAULT_CLAUDE_REVIEW_MODEL;
-        // An AUTOMATIC run goes to the DEFAULT provider (Settings → AI), read now — unless the workspace
-        // asks for Claude + Codex (`auto_review_providers = 'both'`): then a PAIR when both can review,
-        // else the one that can.
-        let provider = activeProviderId();
-        let pair;
-        if ((await readAutoReviewProvidersForPr(ctx, accountId, prId)) === 'both') {
-            const ready = pairProvidersReady(preflightFor(ctx));
-            if (ready.length > 0)
-                provider = ready[0];
-            if (ready.length === 2) {
-                pair = { role: 'first', pairId: 0, secondProvider: ready[1], ...(a.pressed ? { pressed: true } : {}) };
-            }
-        }
         // TEAM CLAIMS ("Mark auto reviews on GitHub", team-claim.ts): a teammate's Limn already holds
         // this head for this provider ⇒ drop the item with NO row (a skip is not a failure: no retry
         // count, no daily-cap use; the tab shows it from memory). Otherwise claim it. Never throws.
@@ -440,7 +459,16 @@ function launch(item) {
     }
     const controller = new AbortController();
     controllers.set(reviewId, controller);
+    item.lastProgressMs = Date.now();
+    item.wokeAtMs = null;
+    startWatchdog();
+    // A run that ignores its abort is released anyway (the watchdog's FORCE_RELEASE_MS): the pipeline
+    // races this, so the end and the seat's release below still run.
+    const hardStop = new Promise((resolve) => {
+        item.forceStop = () => resolve(false);
+    });
     const emit = (progress) => {
+        item.lastProgressMs = Date.now();
         progressByReview.set(reviewId, progress);
         // The PR's stream follows the half in the per-PR seat; a partner's progress is kept for when
         // it moves there.
@@ -460,7 +488,7 @@ function launch(item) {
     }
     // Did this run end the whole job (an ordinary run, or the LAST half of a pair)?
     let ends = true;
-    void runPipeline(item, controller, emit)
+    void Promise.race([runPipeline(item, controller, emit), hardStop])
         .then((succeeded) => {
         item.succeeded = succeeded;
     })
@@ -684,7 +712,7 @@ async function startPairSecond(first) {
     // Why the second half did not start (the pair's one review names it).
     let why = 'error';
     try {
-        if (first.trigger === 'auto' && !pair.pressed && !(await automaticRunAllowed(ctx, accountId, 'auto review (second half)'))) {
+        if (first.trigger === 'auto' && !pair.pressed && !(await automaticRunAllowed(ctx, accountId, 'auto review (second half)', provider))) {
             why = 'budget';
             return;
         }
@@ -946,7 +974,7 @@ async function runPipeline(item, controller, emit) {
         // on Codex, where Limn runs each specialist as its own run — the spend budget asked before each.
         usage: { accountId: item.accountId, prId: item.prId },
         ...(item.trigger === 'auto'
-            ? { allowSpecialistStart: () => automaticRunAllowed(ctx, item.accountId, 'auto review specialist') }
+            ? { allowSpecialistStart: () => automaticRunAllowed(ctx, item.accountId, 'auto review specialist', item.provider) }
             : {}),
         applyAuthEnv: APPLY_AUTH_ENV,
         abortController: controller,
@@ -976,11 +1004,19 @@ async function runPipeline(item, controller, emit) {
         diffCapped: prep.diffCapped,
         ...(res.usageRecorded ? { usageRecorded: true } : {}),
     };
-    if (res.aborted) {
+    if (res.aborted && item.interrupt) {
+        // THE WATCHDOG stopped it (a sleep, or no progress): FAILED with a TRANSIENT reason, so the
+        // auto-retry rule re-runs it when still required — never "cancelled", which is never retried.
+        await markReviewFailed(ctx, reviewId, item.interrupt.reason, { ...telemetry, excludedFiles: prep.excludedFiles });
+        return false;
+    }
+    else if (res.aborted) {
         await markReviewCancelled(ctx, reviewId);
         return false;
     }
     else if (!res.submitted) {
+        // A usage limit locks the provider out of automatic runs until its reset (ai/usage-lockout.ts).
+        noteProviderFailure(item.provider, res.failureReason);
         await markReviewFailed(ctx, reviewId, res.failureReason ?? 'review failed', {
             ...telemetry,
             scope: res.scope,
@@ -1226,6 +1262,68 @@ function pump() {
         void startAutoItem(a);
     }
 }
+// ---- THE RUN WATCHDOG (run-watchdog.ts; docs/CLAUDE-REVIEW.md § Auto review → Sleep and stalled runs) ----
+let watchdogTimer = null;
+let lastWatchdogTickMs = null;
+/** Every run in flight in this process (each half of a pair). */
+function inFlightRuns() {
+    return [...runningItems.values(), ...pairPartners.values()].filter((it) => it.done !== true);
+}
+function startWatchdog() {
+    if (watchdogTimer)
+        return;
+    lastWatchdogTickMs = Date.now();
+    watchdogTimer = setInterval(() => {
+        void watchdogTick(Date.now());
+    }, WATCHDOG_TICK_MS);
+    watchdogTimer.unref?.();
+}
+/**
+ * One watchdog tick (exported for the test). A late tick ⇒ the machine slept: every run in flight is
+ * marked woken. Then each run `runsToInterrupt` names is aborted with its reason (failed, not
+ * cancelled); one still not ended FORCE_RELEASE_MS after its abort is failed in the DB and released.
+ * Stops its timer when nothing is in flight.
+ */
+export async function watchdogTick(nowMs) {
+    const woke = detectWake(lastWatchdogTickMs, nowMs);
+    lastWatchdogTickMs = nowMs;
+    const runs = inFlightRuns();
+    if (woke != null)
+        for (const it of runs)
+            it.wokeAtMs = woke;
+    const byId = new Map(runs.map((it) => [it.reviewId, it]));
+    for (const it of runs) {
+        if (it.interrupt && nowMs - it.interrupt.atMs >= FORCE_RELEASE_MS) {
+            const why = it.interrupt.reason;
+            it.ctx.log.warn(`claude review pr ${it.prId}: run ${it.reviewId} did not stop after "${why}"; releasing it`);
+            await markReviewFailed(it.ctx, it.reviewId, why).catch(() => { });
+            it.forceStop?.();
+        }
+    }
+    const watched = runs
+        .filter((it) => !it.interrupt)
+        .map((it) => ({ reviewId: it.reviewId, lastProgressMs: it.lastProgressMs ?? nowMs, wokeAtMs: it.wokeAtMs ?? null }));
+    for (const { reviewId, reason } of runsToInterrupt(watched, nowMs)) {
+        const it = byId.get(reviewId);
+        if (!it)
+            continue;
+        it.ctx.log.warn(`claude review pr ${it.prId}: run ${reviewId} interrupted — ${reason}`);
+        it.interrupt = { reason, atMs: nowMs };
+        controllers.get(reviewId)?.abort();
+    }
+    if (runs.length === 0 && watchdogTimer) {
+        clearInterval(watchdogTimer);
+        watchdogTimer = null;
+    }
+}
+/** Test seam: the in-flight runs' watchdog view. */
+export function _watchdogRunsForTest() {
+    return inFlightRuns().map((it) => ({ reviewId: it.reviewId, wokeAtMs: it.wokeAtMs ?? null, interrupted: it.interrupt?.reason ?? null }));
+}
+/** Test seam: pretend the previous tick ran at `ms` (null = no tick yet). */
+export function _setWatchdogLastTickForTest(ms) {
+    lastWatchdogTickMs = ms;
+}
 /**
  * Cancel the review for a PR. `accountId` is REQUIRED and enforced against the queue entry's
  * own owner: without it, one tenant could abort another tenant's in-flight (billed) agentic run
@@ -1387,6 +1485,9 @@ export async function listActiveReviews(accountId) {
  */
 export async function reconcileReviewsOnStartup(ctx) {
     const runs = await reconcileOrphanedReviewRuns(ctx);
+    // A provider still inside a usage limit a run hit before the restart stays locked out of
+    // automatic runs (ai/usage-lockout.ts). Cheap: one bounded read.
+    await restoreUsageLockouts(() => failedRunsSinceLastSuccess(ctx, Date.now() - LOCKOUT_MAX_MS));
     if (runs.length > 0)
         ctx.log.info(`reconciled ${runs.length} orphaned claude review(s) -> failed`);
     const pairsFinished = finishInterruptedPairs(ctx, runs).catch((err) => {