@tokenfactory/acc-runner 0.44.1 → 0.44.3

package/dist/watch.js

@@ -32,8 +32,10 @@ import { applyBootstrapConfig, concurrencyEnvExplicit, loadConfig, resolveEffect
 // existing tests that import them from `../src/watch.js` keep resolving.
 export { resolveConcurrencyLimit, resolveReservedReviewSlots } from "./config.js";
 import { getTokenProvider } from "./token-provider.js";
-import { machineIdentity, detectInstalledModels, runnerCapsWithRepos } from "./login.js";
+import { advertisedCapabilities, machineIdentity, detectInstalledModels, runnerCapsWithRepos, registerRunnerCaps, } from "./login.js";
 import { detectCapableEngines } from "./doctor.js";
+import { safeText } from "./machine-capabilities/redact.js";
+import { resolveCredentialIdentity } from "./credential-identity.js";
 import { createRunnerClient } from "./supabase.js";
 import { releaseHeldLocks } from "./locks/index.js";
 // SH-4 (PAUSE-CHECKPOINT-RESUME): the additive task_paused broadcast + the
@@ -42,7 +44,7 @@ import { TASK_PAUSED_EVENT, captureWorktreeCheckpoint, parseTaskPausedBroadcast,
 import { worktreePath } from "./runtime/worktree.js";
 import { runTask } from "./task-runner.js";
 import { runReview, } from "./runtime/reviewer.js";
-import { getQuarantine, setQuarantine, clearQuarantine, } from "./runtime/quarantine.js";
+import { getQuarantine, publishedQuarantineState, setQuarantine, clearQuarantine, } from "./runtime/quarantine.js";
 import { acquireSingletonLock, singletonRunnerId, SingletonLockHeldError, } from "./runtime/singleton.js";
 import { getClaudeVersion, recordTaskClaudeVersion, } from "./runtime/version-drift.js";
 import { autoUpgradeDisabled, maybeSelfUpgrade, maybeSelfUpdateOn426, } from "./runtime/self-upgrade.js";
@@ -62,7 +64,7 @@ import { AccountProbeScheduler } from "./engines/account-probe.js";
 // AX-H1 (MACHINE-CAPABILITIES): the host-capability probe + reporter. Driven by
 // the AS-1 account-probe cadence above, never by a loop of its own.
 import { MachineCapabilityReporter, probeMachineCapabilities, } from "./machine-capabilities/index.js";
-import { getChatEngine, getEngine } from "./engines/registry.js";
+import { getConfiguredChatEngine, getEngine } from "./engines/registry.js";
 // FLEET-SERVE (wire): fleet-fallback chat serving runs ALONGSIDE the task pump on
 // a `watch` runner — the runner serves its bound user's chat turns behind their
 // companion. Glue lives in watch-chat/wire.ts to keep this file the task loop.
@@ -71,6 +73,8 @@ import { ClaimDeadman, readDispatchSignal, DEFAULT_DEADMAN_CHECK_MS, DEFAULT_FAL
 import { unknownAccountIdentity } from "./engines/account-identity.js";
 import { checkVersion, compareSemver } from "./version-check.js";
 import { PACKAGE_VERSION } from "./pkg-version.js";
+import { buildFingerprintCaps, publishBuildFingerprintCaps, LOADED_BUILD_FINGERPRINT, } from "./build-fingerprint.js";
+import { recordRunningBuild } from "./runtime/running-build.js";
 import { authPrecedenceHint, servingAuthKind, describeServingAuthKind, forwardsAmbientKey, anthropicApiKey, } from "./provider-auth.js";
 // RUNNER-SERVING-AUTH: the org's subscription-vs-BYOK choice, resolved once
 // per boot and expressed through the same ACC_RUNNER_SERVING_AUTH_KIND var the
@@ -82,6 +86,7 @@ import { fetchServingAuth, installServingAuth, servingAuthKindIsPinned, describe
 import { RefreshReuseDetectedError, classifyHeartbeatError, expiresSoon, nextHeartbeatDelayMs, refreshAccessToken, } from "./runtime/auth-lifecycle.js";
 // AU-7 RUNNER-FLAP-ROOT-CAUSE: bounded + write-then-read-verified heartbeat.
 import { HEARTBEAT_RPC_TIMEOUT_MS, HeartbeatVerifier, nextBeatDelayMs, sendHeartbeat, withDeadline, } from "./heartbeat/beat.js";
+import { buildEnv, requireExecutable } from "./bin-resolve.js";
 export { RefreshReuseDetectedError, classifyHeartbeatError, nextHeartbeatDelayMs, };
 const REFRESH_CHECK_MS = 30 * 60 * 1000;
 // v0.12.0 (T-52-7): idle-TTL check cadence ceiling. The actual cadence is
@@ -226,6 +231,21 @@ export function resolveIdleTtlMs(env = process.env) {
     }
     return minutes * 60_000;
 }
+/**
+ * The DEFAULT reviewer factory. FAIL CLOSED: constrain every review to the engines
+ * THIS runner ALREADY PUBLISHED into `acc.runners.caps.engines` — the value the
+ * assignment was routed against — threaded as a FIXED `advertisedEngineIds`.
+ * `advertisedEngines` is resolved ONCE at watch startup from the same
+ * `detectCapableEngines()` source that feeds the register_runner caps payload, so
+ * it is a stable snapshot. It deliberately does NOT pass a live `detectEngines`
+ * probe: a per-review re-probe could drift from the published caps (an engine
+ * appearing/disappearing mid-session) and silently route a review to an engine the
+ * assignment never assumed. `run` is injectable for the wiring test; production
+ * uses `runReview`.
+ */
+export function capsConstrainedReviewerFactory(advertisedEngines, run = runReview) {
+    return (assignment, deps) => run(assignment, { ...deps, advertisedEngineIds: advertisedEngines });
+}
 /** v0.12.0 (T-52-7): record work-related activity for the idle TTL clock. */
 function touchActivity(state) {
     state.lastActivityMs = Date.now();
@@ -242,15 +262,27 @@ function failOnReuse(err) {
 }
 // Single source of truth for "this task is new — push it into the runner
 // queue". Both the Realtime listener and the polling loop go through here.
-function enqueue(state, taskId, factory) {
+function enqueue(state, taskId, factory, engine) {
     if (state.seen.has(taskId))
         return false;
+    // CLAIM-LOCK-GLOB: a task that lost the claim to a live
+    // file-lock holder and spent its fast attempts is held out of the queue until
+    // its bounded yield elapses (AC3). Skip re-driving it until then; the periodic
+    // claim-scan / backstop re-lists it once the yield expires. Expired stamps are
+    // dropped so the very next pass re-drives the task.
+    const yieldUntil = state.claimYieldUntil.get(taskId);
+    if (yieldUntil != null) {
+        if (Date.now() < yieldUntil)
+            return false;
+        state.claimYieldUntil.delete(taskId);
+    }
     // v0.10 T-49-2: check the running Map (replaces v0.9 state.current check).
     if (state.running.has(taskId)) {
         state.seen.add(taskId);
         return false;
     }
     state.seen.add(taskId);
+    state.taskEngines.set(taskId, capacityEngine(engine));
     state.queue.push(taskId);
     touchActivity(state);
     // CLAIM-DEADMAN: a claim was processed via SOME path
@@ -263,6 +295,33 @@ function enqueue(state, taskId, factory) {
     void pump(state, factory);
     return true;
 }
+async function lookupAssignedQueuedTaskEngine(state, taskId) {
+    const { data, error } = await state.supabase.rpc("list_assigned_queued_tasks", {
+        p_runner_id: state.session.runner_id,
+        p_since: "1970-01-01T00:00:00.000Z",
+    });
+    if (error) {
+        process.stderr.write(`[acc-runner] task_assigned engine lookup failed for ${taskId}: ${error.message}\n`);
+        return { found: false };
+    }
+    const row = (data ?? []).find((candidate) => candidate?.id === taskId);
+    return row ? { found: true, engine: row.engine } : { found: false };
+}
+async function enqueueAssignedTaskBroadcast(state, taskId, factory, payload) {
+    if (Object.prototype.hasOwnProperty.call(payload, "engine")) {
+        enqueue(state, taskId, factory, payload.engine);
+        return;
+    }
+    const resolved = await lookupAssignedQueuedTaskEngine(state, taskId);
+    if (state.stopped || state.seen.has(taskId) || state.running.has(taskId))
+        return;
+    // Enqueue even when the lookup can't confirm the row (empty result or a
+    // transient error). Dropping it would leave the id un-`seen`, so a later
+    // delta-poll re-claims the same no-op and drags its watermark past newer
+    // tasks (the watch-claim-scan wedge). This mirrors the pre-engine broadcast
+    // path, which always enqueued; a still-unknown engine falls back to default.
+    enqueue(state, taskId, factory, resolved.found ? resolved.engine : undefined);
+}
 // Single source of truth for "this review is new — push it into the review
 // queue". The Realtime listener AND the periodic review scan (v0.65 T-65-2)
 // both go through here; the shared `seenReviews` guard dedupes a review that
@@ -340,6 +399,7 @@ async function handleTaskPaused(state, payload) {
     }
     // Let the resume redispatch of this SAME id through the dedupe set.
     state.seen.delete(taskId);
+    state.taskEngines.delete(taskId);
 }
 function subscribeChannel(state, taskRunnerFactory) {
     state.channel = state.supabase
@@ -348,8 +408,9 @@ function subscribeChannel(state, taskRunnerFactory) {
     })
         .on("broadcast", { event: "task_assigned" }, ({ payload }) => {
         const taskId = payload?.task_id;
-        if (taskId)
-            enqueue(state, taskId, taskRunnerFactory);
+        if (taskId) {
+            void enqueueAssignedTaskBroadcast(state, taskId, taskRunnerFactory, payload);
+        }
     })
         .on("broadcast", { event: "task_cancelled" }, ({ payload }) => {
         const taskId = payload?.task_id;
@@ -366,6 +427,7 @@ function subscribeChannel(state, taskRunnerFactory) {
         // Drop from seen so a re-queue (cancel → re-start) is honored on
         // the next broadcast or poll.
         state.seen.delete(taskId);
+        state.taskEngines.delete(taskId);
     })
         .on("broadcast", { event: TASK_PAUSED_EVENT }, ({ payload }) => {
         void handleTaskPaused(state, payload);
@@ -458,6 +520,15 @@ export async function reassertRunningClaims(state) {
         }
     }));
 }
+function capacityEngine(engine) {
+    return getEngine(engine ?? null).id;
+}
+function hasCapacityPause(state) {
+    return state.pausedCapacity.size > 0;
+}
+function isCapacityPausedFor(state, engine) {
+    return state.pausedCapacity.has(capacityEngine(engine));
+}
 // Single-flight poll. The watermark advances only after a clean response so
 // a transient error doesn't permanently skip rows.
 async function pollOnce(state, factory) {
@@ -489,7 +560,7 @@ async function pollOnce(state, factory) {
             // keeps the watermark a conservative "newest task I claimed by polling"
             // mark and stops the delta-poll losing still-queued work. The periodic
             // full claim scan (claimScan) is the belt to this braces.
-            const claimed = enqueue(state, row.id, factory);
+            const claimed = enqueue(state, row.id, factory, row.engine);
             if (claimed && row.updated_at && row.updated_at > maxSeen) {
                 maxSeen = row.updated_at;
             }
@@ -536,7 +607,7 @@ async function claimScan(state, factory, context) {
         for (const row of rows) {
             if (!row?.id)
                 continue;
-            if (enqueue(state, row.id, factory))
+            if (enqueue(state, row.id, factory, row.engine))
                 enqueued += 1;
         }
         if (context === "startup") {
@@ -603,13 +674,8 @@ async function claimWatchdogScan(state, factory) {
             state.claimWatchdogSince.clear();
             return;
         }
-        // v0.41.4: never answer a DELIBERATE not-claiming state with a transport
-        // remedy. While quarantined or capacity-paused the runner is SUPPOSED to
-        // leave its tasks queued; a resubscribe changes nothing and produced the
-        // resubscribe storm interleaved with QUARANTINED in the claim-livelock
-        // incident. Mirror the backstop's guard and drop the stale timers so an
-        // age never spans the pause and falsely trips the instant it lifts.
-        if (state.quarantined || state.pausedCapacity) {
+        // A quarantined runner is deliberately not claiming; resubscribe cannot help.
+        if (state.quarantined) {
             state.claimWatchdogSince.clear();
             return;
         }
@@ -625,8 +691,12 @@ async function claimWatchdogScan(state, factory) {
         const now = Date.now();
         const currentIds = new Set();
         for (const row of rows) {
-            if (row?.id)
-                currentIds.add(row.id);
+            if (!row?.id)
+                continue;
+            // Paused-engine rows are deliberately unclaimed; still watch other engines.
+            if (isCapacityPausedFor(state, row.engine))
+                continue;
+            currentIds.add(row.id);
         }
         // Reset: drop timers for tasks no longer assigned+queued (claimed/unassigned).
         for (const id of [...state.claimWatchdogSince.keys()]) {
@@ -639,6 +709,17 @@ async function claimWatchdogScan(state, factory) {
             if (!currentIds.has(id))
                 state.claimContentionSince.delete(id);
         }
+        // CLAIM-LOCK-GLOB: same reset for the claim-loss back-off
+        // — a task that left the queue is no longer contending, so its attempt count
+        // and yield window are stale.
+        for (const id of [...state.claimLossState.keys()]) {
+            if (!currentIds.has(id))
+                state.claimLossState.delete(id);
+        }
+        for (const id of [...state.claimYieldUntil.keys()]) {
+            if (!currentIds.has(id))
+                state.claimYieldUntil.delete(id);
+        }
         // Observe: stamp the first-seen instant for newly assigned-unclaimed tasks;
         // collect any that have now been stale past the threshold, splitting off
         // those that are merely waiting on file-lock contention (v0.41.4).
@@ -755,10 +836,8 @@ async function claimWatchdogScan(state, factory) {
 async function claimBackstopScan(state, factory) {
     if (state.stopped || state.backstopScanning)
         return;
-    // Don't fight a deliberate not-claiming state. While quarantined or capacity-
-    // paused the task SHOULD sit queued; re-enqueueing only churns. A later pass
-    // recovers any genuine `seen`-trap once the runner is claiming again.
-    if (state.quarantined || state.pausedCapacity)
+    // Quarantine is a deliberate whole-runner stop; capacity is checked per row.
+    if (state.quarantined)
         return;
     state.backstopScanning = true;
     try {
@@ -776,6 +855,9 @@ async function claimBackstopScan(state, factory) {
         for (const row of rows) {
             if (!row?.id)
                 continue;
+            // Leave paused-engine rows queued; recover rows for claimable engines.
+            if (isCapacityPausedFor(state, row.engine))
+                continue;
             // The wedge signature: DB says assigned+queued, but the id is trapped in
             // `seen` while live in neither `queue` nor `running`. Clear `seen` and let
             // enqueue() re-drive it (enqueue re-adds to `seen` + pumps).
@@ -783,7 +865,7 @@ async function claimBackstopScan(state, factory) {
                 !state.running.has(row.id) &&
                 !inQueue.has(row.id)) {
                 state.seen.delete(row.id);
-                if (enqueue(state, row.id, factory))
+                if (enqueue(state, row.id, factory, row.engine))
                     recovered.push(row.id);
             }
         }
@@ -821,17 +903,39 @@ async function claimBackstopScan(state, factory) {
  * incident). This pass re-probes claude while quarantined under `env_broken`
  * and, when the probe passes, clears the quarantine and resumes claiming.
  *
- * Scoped to `env_broken` ONLY: usage_limit clears via the capacity resume path
- * and auth_expired via a token refresh — a claude re-probe must not paper over
- * those. Single-flight; never throws out of the loop.
+ * The sentinel is authoritative for every cause: an operator clearing this
+ * instance's file releases a running watcher on the next pass. Automatic
+ * probing remains scoped to `env_broken`; a usage_limit with a known reset is
+ * also released by capacity resume, while a hard billing wall and auth_expired
+ * require explicit operator action. Single-flight; never throws out of the loop.
  */
 async function quarantineRecoveryScan(state, factory) {
     if (state.stopped || state.quarantineRecovering)
         return;
-    if (!state.quarantined || state.quarantineCause !== "env_broken")
-        return;
     state.quarantineRecovering = true;
     try {
+        const sentinel = await getQuarantine();
+        if (!sentinel) {
+            if (!state.quarantined)
+                return;
+            const cause = state.quarantineCause;
+            state.quarantined = false;
+            state.quarantineCause = null;
+            process.stderr.write(chalk.green(`[acc-runner] quarantine cleared for this instance (${cause ?? "unknown"}); ` +
+                `resuming task claims without a restart.\n`));
+            if (cause === "usage_limit" && state.pausedCapacity) {
+                state.resumeController.resumeByOperator();
+                await state.resumeController.settle();
+                return;
+            }
+            void pollOnce(state, factory);
+            void pump(state, factory);
+            return;
+        }
+        state.quarantined = true;
+        state.quarantineCause = sentinel.cause;
+        if (sentinel.cause !== "env_broken")
+            return;
         const probe = await state.healthProbe();
         if (!probe.ok)
             return; // still broken — stay quarantined, try again next tick.
@@ -867,12 +971,11 @@ async function quarantineRecoveryScan(state, factory) {
  * CLAIM-DEADMAN: a runner may have free capacity but be
  * deliberately not claiming (quarantined, capacity-paused, review-claim-paused,
  * or already at its effective task-claim ceiling). In those states pending work
- * SHOULD sit queued, so it must NOT be read as a wedge. Mirrors the
- * claimBackstopScan guard. Returns true only when the runner both wants to and
- * can claim another task.
+ * SHOULD sit queued, so it must NOT be read as a wedge. Returns true only when
+ * the runner both wants to and can claim another task.
  */
 function deadmanCanClaim(state) {
-    if (state.quarantined || state.pausedCapacity || state.capacityClaimPaused) {
+    if (state.quarantined || hasCapacityPause(state) || state.capacityClaimPaused) {
         return false;
     }
     const limit = computeTaskClaimLimit({
@@ -1112,7 +1215,7 @@ async function reviewScan(state, context) {
         return;
     // v0.56 (T-56-1) parity with pumpReviews: don't claim reviews while paused
     // for capacity. The scheduled resume re-drives the review pump.
-    if (state.pausedCapacity)
+    if (hasCapacityPause(state))
         return;
     state.reviewScanning = true;
     try {
@@ -1362,6 +1465,7 @@ export async function watchCommand(options = {}) {
                 gitAuthProbeOnce: async () => false,
                 quarantineRecoveryOnce: async () => { },
                 runningCount: () => 0,
+                pausedEnginesSnapshot: () => [],
             };
         }
         // Park: release our flock so a manual restart / operator install isn't
@@ -1444,22 +1548,41 @@ export async function watchCommand(options = {}) {
         concurrency: concurrencyLimit,
         reservedReviewSlots,
     };
-    // v0.12.0 (T-52-7): env-token (ephemeral) runners had no `login` flow, so
-    // nothing registered an acc.runners row yet. Register on boot under the
-    // acc-eph-<random> identity. register_runner may resolve to an existing
-    // row (same bound user + machine, e.g. a restarted container with a
-    // pinned hostname) — adopt whatever id it returns so the realtime
-    // channel, heartbeats, and polling all agree.
-    if (tokenProvider.mode === "env") {
+    // AC2 (upstream WINDOWS-RUNNER-DISPATCH-1): a runner must never register/
+    // heartbeat as healthy while it cannot resolve the default task engine —
+    // otherwise it accepts claude-code work that can only fail at phase=claude_exit.
+    // This guard runs on EVERY startup path (kept from upstream, ahead of the
+    // unconditional register below); only an explicit options.claudePreflight
+    // override skips it, so a test opts out visibly.
+    const claudePreflight = options.claudePreflight ?? (() => requireExecutable("claude", { env: buildEnv() }));
+    try {
+        claudePreflight();
+    }
+    catch (err) {
+        await singletonLock?.release();
+        process.stderr.write(`[acc-runner] ${chalk.red(err.message)}\n`);
+        exitFn(1);
+        throw err;
+    }
+    // CAPS-ENGINES-STALE-KEYCHAIN-1 (AC1/AC2): caps.engines must be THIS watcher
+    // process's live surface, so refresh it on every boot for EVERY token mode
+    // (was gated to mode==="env"). Env-token runners also create/adopt their row here.
+    {
         const boot = createRunnerClient(cfg, session.access_token, session.realtime_config);
         const models = await detectInstalledModels();
-        // M5: an env-token (autonomous) runner re-registers on every boot, so this
-        // also refreshes caps.engines each restart — installing/removing an engine
-        // then restarting takes effect without a re-login. Mirror of the models
-        // detection above; drives the engine-aware dispatch gate (mig 0229).
-        const engines = await detectCapableEngines();
+        // AC11: advertise what THIS serving process resolves (seam defaults to real).
+        const engines = await (options.detectEngines ?? detectCapableEngines)();
+        // Record the SERVING model-credential account (from upstream's capacity-
+        // attribution work) so a keychain OR env-token runner's account is
+        // comparable in the runners table from its first heartbeat.
+        const identity = await resolveCredentialIdentity();
         const { data: resolvedId, error: regErr } = await boot.rpc("register_runner", {
             p_id: session.runner_id,
+            // finding-4: send p_name = runner_id on EVERY boot. For an env row that
+            // IS its name; for a keychain row, register_runner (mig 0349) treats an
+            // incoming name equal to the row id as "no rename" and PRESERVES the
+            // existing (possibly operator-renamed) name — so a boot caps-refresh never
+            // clobbers an operator-set runner name.
             p_name: session.runner_id,
             p_owner: session.email ?? session.user_id,
             p_machine: machineIdentity(),
@@ -1471,18 +1594,37 @@ export async function watchCommand(options = {}) {
             // CONC-1: pass the once-resolved concurrency so caps.concurrency /
             // caps.reserved_review_slots match the watch loop's real capacity and
             // survive register_runner's per-heartbeat caps replace (mig 0153).
-            p_caps: runnerCapsWithRepos(cfg.repos, engines, concurrencyCaps),
+            // AC10: SAME shared builder login.ts uses — boot ≡ login caps (now rich:
+            // process caps + serving identity + build fingerprint folded in).
+            p_caps: registerRunnerCaps(cfg, engines, concurrencyCaps, identity, await buildFingerprintCaps()),
             p_version: PACKAGE_VERSION,
+            // REGISTER-CAPS-PRESERVE-1: same explicit send as the login path — an
+            // env-token runner re-registers on EVERY boot, so this was the
+            // highest-frequency door into the capability wipe. Mig 0349 now
+            // union-merges capabilities (never shrinks), so this refresh is non-destructive.
+            p_capabilities: advertisedCapabilities(cfg),
         });
         if (regErr) {
-            process.stderr.write(`[acc-runner] ephemeral register_runner failed: ${regErr.message}\n`);
-            process.exit(1);
+            // AC3: env path keeps its exact "ephemeral" wording; keychain path is new.
+            process.stderr.write(`[acc-runner] ${tokenProvider.mode === "env" ? "ephemeral" : "boot"} register_runner failed: ${safeText(regErr.message, 300) ?? "unknown error"}\n`);
+            if (tokenProvider.mode === "env")
+                process.exit(1);
         }
-        if (typeof resolvedId === "string" && resolvedId && resolvedId !== session.runner_id) {
-            session = { ...session, runner_id: resolvedId };
+        else {
+            // AC-SAFETY: ONLY env-token runners (no login flow; id may be server-minted)
+            // adopt a resolved id and persist it. A keychain runner has a valid
+            // logged-in identity — refresh its caps only, NEVER rewrite its stored
+            // session (an unguarded identity rewrite risks orphaning the credential).
+            if (tokenProvider.mode === "env") {
+                if (typeof resolvedId === "string" && resolvedId && resolvedId !== session.runner_id) {
+                    session = { ...session, runner_id: resolvedId };
+                }
+                await tokenProvider.save(session);
+            }
+            console.log(chalk.green(tokenProvider.mode === "env"
+                ? `✓ Registered ephemeral runner: ${session.runner_id}`
+                : `✓ Refreshed runner caps: ${session.runner_id}`));
         }
-        await tokenProvider.save(session);
-        console.log(chalk.green(`✓ Registered ephemeral runner: ${session.runner_id}`));
     }
     // RUNNER-SERVING-AUTH: ask the control plane which serving auth this ORG
     // chose in Settings, before the banner below reads it. This is what turns
@@ -1575,15 +1717,29 @@ export async function watchCommand(options = {}) {
     const taskRunnerFactory = options.taskRunnerFactory ?? runTask;
     const heartbeatMs = options.heartbeatMs ?? 4_000;
     const pollMs = options.pollMs ?? POLL_INTERVAL_MS;
-    const reviewerFactory = options.reviewerFactory ?? ((assignment, deps) => runReview(assignment, deps));
+    // CROSS-ENGINE-REVIEW-1 (AC3) — FAIL CLOSED: constrain reviewer-engine selection
+    // to the engines THIS runner ALREADY PUBLISHED into `acc.runners.caps.engines` —
+    // the value the assignment was routed against — NOT a fresh per-review probe.
+    // Resolved ONCE here from the SAME `detectCapableEngines()` source that feeds the
+    // register_runner caps payload, then threaded as a fixed `advertisedEngineIds`.
+    // A per-review re-probe could drift from the published caps (an engine appearing
+    // or disappearing mid-session), silently routing a review to an engine the
+    // assignment never assumed; the fixed snapshot cannot. A claude-only runner is
+    // never routed to codex, and an empty set fails closed downstream (no candidate →
+    // no-route infra error) rather than falling back to the local registry. Tests
+    // inject `options.reviewerFactory`.
+    const advertisedEngines = await detectCapableEngines();
+    const reviewerFactory = options.reviewerFactory ?? capsConstrainedReviewerFactory(advertisedEngines);
     // v0.48: check for an existing quarantine file before opening the
     // realtime connection. If quarantined, emit a loud warning — the
     // runner will not claim tasks until `acc-runner quarantine clear` runs.
     const startupQuarantine = await getQuarantine().catch(() => null);
     if (startupQuarantine) {
         process.stderr.write(chalk.red.bold(`[acc-runner] QUARANTINED (${startupQuarantine.cause}): ${startupQuarantine.detail}\n`));
-        process.stderr.write(chalk.red(`[acc-runner] Runner will NOT claim tasks. Resolve the issue then run ` +
-            `\`acc-runner quarantine clear\`.\n`));
+        process.stderr.write(chalk.red(`[acc-runner] Runner will NOT claim tasks. Resolve the issue, then run ` +
+            `\`acc-runner quarantine clear\` for this named instance; repeat for each ` +
+            `instance on the host. The running watcher resumes on its next recovery tick; ` +
+            `no restart is required.\n`));
     }
     // v0.12.0 (T-52-7): idle TTL — option override wins (tests), then env.
     const idleTtlMs = options.idleTtlMs !== undefined ? options.idleTtlMs : resolveIdleTtlMs();
@@ -1609,6 +1765,8 @@ export async function watchCommand(options = {}) {
         claimWatchdogChecking: false,
         // v0.41.4: file-lock contention tracker (see WatchState doc).
         claimContentionSince: new Map(),
+        claimLossState: new Map(),
+        claimYieldUntil: new Map(),
         // FIX-D: periodic DB-poll claim backstop.
         claimBackstopTimer: undefined,
         claimBackstopIntervalMs: options.claimBackstopIntervalMs ?? DEFAULT_CLAIM_BACKSTOP_INTERVAL_MS,
@@ -1625,6 +1783,7 @@ export async function watchCommand(options = {}) {
             wedgeThresholdMs: options.claimDeadmanWedgeMs ?? DEFAULT_CLAIM_DEADMAN_WEDGE_MS,
             rebuildGraceMs: options.claimDeadmanRebuildGraceMs ?? DEFAULT_CLAIM_DEADMAN_REBUILD_GRACE_MS,
             maxRebuilds: options.claimDeadmanMaxRebuilds ?? DEFAULT_CLAIM_DEADMAN_MAX_REBUILDS,
+            now: options.claimDeadmanNow,
         }),
         claimDeadmanTimer: undefined,
         claimDeadmanCheckMs: options.claimDeadmanCheckMs ?? DEFAULT_DEADMAN_CHECK_MS,
@@ -1666,6 +1825,7 @@ export async function watchCommand(options = {}) {
         // RVU-2 (FU-RVU2R): claim-pause starts off; set under review capacity pressure.
         capacityClaimPaused: false,
         queue: [],
+        droppedEngines: new Set(),
         seen: new Set(),
         pumping: false,
         stopped: false,
@@ -1691,10 +1851,12 @@ export async function watchCommand(options = {}) {
         selfUpgradeFn: options.selfUpgrade ?? ((input) => maybeSelfUpgrade(input)),
         selfUpgrading: false,
         taskRunnerFactory,
-        pausedCapacity: false,
+        pausedCapacity: new Set(),
         pausedUntil: null,
         capacityTriggerTaskId: null,
         capacityPauseDetail: "",
+        capacityPauseEngine: null,
+        taskEngines: new Map(),
         // AS-3 (RESUME-WIRE): assigned immediately below once `state` exists (the
         // controller's seams close over `state`). `undefined as unknown as` mirrors
         // the channel/timer bootstrap fields above.
@@ -1815,7 +1977,7 @@ export async function watchCommand(options = {}) {
     state.claimBackstopTimer = setInterval(() => {
         void claimBackstopScan(state, taskRunnerFactory);
     }, state.claimBackstopIntervalMs);
-    // v0.41.4: env_broken quarantine auto-recovery re-probe.
+    // Reconcile operator clears for every cause and probe env_broken recovery.
     state.quarantineRecoveryTimer = setInterval(() => {
         void quarantineRecoveryScan(state, taskRunnerFactory);
     }, state.quarantineRecoveryIntervalMs);
@@ -1848,10 +2010,20 @@ export async function watchCommand(options = {}) {
     // requiring a full `acc-runner login` re-flow. Default-empty is the
     // backward-compat path for 0.6.3 runners and matches any task with
     // an empty required_capabilities array.
-    {
+    //
+    // REGISTER-CAPS-PRESERVE-1: skip the publish when this runner declared NO
+    // tags. set_runner_capabilities (0114) is an unconditional `capabilities =
+    // coalesce(p_capabilities, '{}')`, so an empty array is a pure WIPE carrying
+    // no information — and it is the OTHER door into the fleet-starvation
+    // incidents (the 03:20 launchctl reload took this path, not register_runner:
+    // a local-token runner never re-runs the boot register). Clearing tags is a
+    // board action, not a side effect of an unset env var. A non-empty set is
+    // still published verbatim, so narrowing from the env stays one restart.
+    const advertised = advertisedCapabilities(cfg);
+    if (advertised.length > 0) {
         const { error: capsErr } = await state.supabase.rpc("set_runner_capabilities", {
             p_id: state.session.runner_id,
-            p_capabilities: cfg.capabilities ?? [],
+            p_capabilities: advertised,
         });
         if (capsErr) {
             // Non-fatal: a pre-0114 server (or an Old DB the runner is
@@ -1892,11 +2064,25 @@ export async function watchCommand(options = {}) {
     if (cfg.repos && cfg.repos.length > 0) {
         console.log(chalk.gray(`  serving repos: ${cfg.repos.join(", ")}`));
     }
+    // BUILD-FINGERPRINT-RUNNING-1: stamp the build THIS long-running process
+    // loaded onto disk so a fresh `acc version` or `acc doctor` can later tell
+    // whether an on-disk `npm i -g` has been picked up by this launchd process
+    // yet — a question a fresh CLI invocation (loaded === installed) cannot
+    // answer. Both `acc version` and `acc doctor` read this record.
+    await recordRunningBuild(LOADED_BUILD_FINGERPRINT).catch((err) => {
+        process.stderr.write(`[acc-runner] running-build record failed (continuing): ${err.message}\n`);
+    });
     // Initial heartbeat fires immediately so the runner page reflects "online".
     await state.supabase.rpc("heartbeat_runner", {
         p_id: state.session.runner_id,
         p_version: PACKAGE_VERSION,
     });
+    await publishBuildFingerprintCapsDetail(state).catch((err) => {
+        process.stderr.write(`[acc-runner] build fingerprint publish failed (continuing): ${err.message}\n`);
+    });
+    await publishQuarantineDetail(state).catch((err) => {
+        process.stderr.write(`[acc-runner] quarantine detail publish failed (continuing): ${err.message}\n`);
+    });
     // RUNCFG-1: pull + apply any server-set concurrency at startup (and publish
     // the effective ceiling + source into caps) so a runner that boots with an
     // operator override already in place honours it from the first tick, not only
@@ -2057,8 +2243,49 @@ export async function watchCommand(options = {}) {
         gitAuthProbeOnce: () => gitAuthProbeScan(state), // GIT-AUTH-ALERT
         quarantineRecoveryOnce: () => quarantineRecoveryScan(state, taskRunnerFactory), // v0.41.4
         runningCount: () => state.running.size,
+        pausedEnginesSnapshot: () => [...state.pausedCapacity],
     };
 }
+async function publishQuarantineDetail(state) {
+    const sentinel = await getQuarantine().catch(() => null);
+    const published = publishedQuarantineState(sentinel);
+    if (sentinel && !published) {
+        await clearQuarantine().catch(() => undefined);
+        state.quarantined = false;
+        state.quarantineCause = null;
+    }
+    const { data, error: readErr } = await state.supabase
+        .from("runners")
+        .select("detail")
+        .eq("id", state.session.runner_id)
+        .maybeSingle();
+    if (readErr)
+        throw new Error(readErr.message);
+    const current = data?.detail && typeof data.detail === "object" && !Array.isArray(data.detail)
+        ? { ...data.detail }
+        : {};
+    if (published)
+        current.quarantine = published;
+    else
+        delete current.quarantine;
+    const { error: writeErr } = await state.supabase
+        .from("runners")
+        .update({ detail: current })
+        .eq("id", state.session.runner_id);
+    if (writeErr)
+        throw new Error(writeErr.message);
+}
+/**
+ * BUILD-FINGERPRINT-ON-CAPS: refresh the build fingerprint on the caps
+ * contract (acc.runners.caps.build) — the same field the boot register
+ * populates — so the loaded build is published the same way for every auth
+ * mode, not left to a best-effort `detail` side-channel. Id-scoped self-update
+ * (never register_runner) so a named-instance keychain runner can't re-home
+ * onto a sibling's row.
+ */
+async function publishBuildFingerprintCapsDetail(state) {
+    await publishBuildFingerprintCaps(state.supabase, state.session.runner_id, await buildFingerprintCaps());
+}
 /**
  * RUNCFG-1: apply the operator's server-set concurrency to the LIVE watch-loop
  * ceiling, precedence server-set > env > default. Idempotent: a no-change row
@@ -2141,6 +2368,58 @@ async function syncConcurrency(state, factory) {
     const row = (Array.isArray(data) ? data[0] : data);
     applyServerConcurrency(state, row, factory);
 }
+export async function repairUnknownAdvertisedEngine(state, engineId, err, deps = {}) {
+    const detail = safeText(err.message, 300) ?? "unknown engine";
+    // AC6: redact the engine id too before it reaches the log line / event payload
+    // (the DROP below keeps the RAW id — filtering must match caps.engines exactly).
+    const safeEngineId = safeText(engineId, 80) ?? "<redacted>";
+    // AC12: PERSIST the drop so a later republish can never re-advertise it.
+    state.droppedEngines.add(engineId);
+    process.stderr.write(`[acc-runner] runner.engine_caps_self_inconsistent runner=${state.session.runner_id} ` +
+        `engine=${safeEngineId}: ${detail}\n`);
+    try {
+        await state.supabase.rpc("log_activity", {
+            p_verb: "runner.engine_caps_self_inconsistent",
+            p_target_id: state.session.runner_id,
+            p_target_type: "runner",
+            p_payload: {
+                engine: safeEngineId,
+                error: detail,
+                action: "republish_caps",
+            },
+        });
+    }
+    catch { /* best-effort signal */ }
+    try {
+        const engines = await (deps.detectEngines ?? detectCapableEngines)();
+        const models = await (deps.detectModels ?? detectInstalledModels)();
+        const { error } = await state.supabase.rpc("register_runner", {
+            p_id: state.session.runner_id,
+            // finding-4: p_name = runner_id preserves the operator-set name (mig 0349
+            // treats incoming-name==id as "no rename"), for both env and keychain rows.
+            p_name: state.session.runner_id,
+            p_owner: state.session.email ?? state.session.user_id,
+            p_machine: machineIdentity(),
+            p_models: models,
+            p_caps: runnerCapsWithRepos(state.cfg.repos, 
+            // AC12: filter EVERY persisted drop, not just this engineId — otherwise a
+            // repair for one engine re-advertises another that was dropped earlier.
+            engines.filter((id) => !state.droppedEngines.has(id)), {
+                concurrency: state.concurrencyLimit,
+                reservedReviewSlots: state.reservedReviewSlots,
+            }, state.concurrencySource),
+            p_version: PACKAGE_VERSION,
+            p_capabilities: advertisedCapabilities(state.cfg),
+        });
+        if (error) {
+            process.stderr.write(`[acc-runner] runner.engine_caps_self_inconsistent caps repair failed: ${safeText(error.message, 300) ?? "unknown error"}\n`);
+        }
+    }
+    catch (repairErr) {
+        process.stderr.write(`[acc-runner] runner.engine_caps_self_inconsistent caps repair crashed: ` +
+            `${safeText(repairErr.message, 300) ?? "unknown error"}\n`);
+    }
+}
 /**
  * AU-7: the transport `sendHeartbeat` drives. `readHeartbeatAt` is the audit
  * half of the write-then-read verify — one indexed single-row read of the
@@ -2187,6 +2466,14 @@ function scheduleHeartbeat(state, taskRunnerFactory, baseMs, lastRoundMs = 0) {
             const error = beat.ok ? null : { message: `${beat.kind}: ${beat.message}` };
             if (!error) {
                 state.heartbeatFailures = 0;
+                // BUILD-FINGERPRINT: the fingerprint is published ONCE at boot (it cannot
+                // change within a process). It is deliberately NOT re-published on the
+                // heartbeat timer — heartbeat_runner does not touch caps, so the boot
+                // value persists, and a per-beat read-merge-write would amplify the caps
+                // clobber tracked in T-1788838000022 across every runner, every few seconds.
+                await publishQuarantineDetail(state).catch((err) => {
+                    process.stderr.write(`[acc-runner] quarantine detail publish failed (continuing): ${err.message}\n`);
+                });
                 // CLAIM-DEADMAN: capture the pending-dispatch count
                 // + suspect flag when the heartbeat RESPONSE carries them, so the runner
                 // learns it is being offered work even with a dead WS. Forward-compatible:
@@ -2271,7 +2558,8 @@ function scheduleHeartbeat(state, taskRunnerFactory, baseMs, lastRoundMs = 0) {
 async function maybeSelfUpgradeTick(state) {
     if (state.stopped || state.idleExiting || state.selfUpgrading)
         return;
-    if (state.pausedCapacity)
+    // Process lifecycle actions wait until all capacity pauses have resumed.
+    if (hasCapacityPause(state))
         return;
     if (state.running.size > 0 ||
         state.queue.length > 0 ||
@@ -2314,10 +2602,8 @@ async function maybeSelfUpgradeTick(state) {
 async function maybeIdleExit(state, stop, exitFn) {
     if (state.stopped || state.idleExiting || state.idleTtlMs === null)
         return;
-    // v0.56 (T-56-1): a capacity pause is not idleness — the runner is
-    // deliberately waiting for its session window to reopen. Don't TTL-exit
-    // it out from under the scheduled resume.
-    if (state.pausedCapacity)
+    // A capacity pause is not idleness; keep the process alive for resume.
+    if (hasCapacityPause(state))
         return;
     if (state.running.size > 0 ||
         state.queue.length > 0 ||
@@ -2345,6 +2631,9 @@ async function maybeIdleExit(state, stop, exitFn) {
             p_id: state.session.runner_id,
             p_version: PACKAGE_VERSION,
         });
+        // No fingerprint re-publish on idle exit: it was published at boot and the
+        // process is shutting down, so a read-merge-write here is pure clobber risk.
+        await publishQuarantineDetail(state);
     }
     catch { /* best-effort */ }
     await stop();
@@ -2399,19 +2688,22 @@ async function pumpReviews(state) {
     // v0.56 (T-56-1): don't claim reviews while paused for capacity, and hold
     // reviews back during the single-probe window so the probe TASK confirms
     // the session reopened before we spend more capacity on reviews.
-    if (state.pausedCapacity || state.capacityProbe)
+    if (hasCapacityPause(state) || state.capacityProbe)
         return;
     state.reviewPumping = true;
     try {
         while (!state.stopped &&
-            !state.pausedCapacity &&
+            !hasCapacityPause(state) &&
             !state.capacityProbe &&
             state.reviewQueue.length > 0) {
             const next = state.reviewQueue.shift();
             if (!next)
                 continue;
             try {
-                const outcome = await state.runReview(next, { supabase: state.supabase });
+                const outcome = await state.runReview(next, {
+                    supabase: state.supabase,
+                    onUnknownAdvertisedEngine: (engineId, err) => repairUnknownAdvertisedEngine(state, engineId, err),
+                });
                 const tag = outcome.decision === "reviewer_error" ? chalk.red : chalk.gray;
                 console.log(tag(`[acc-runner] review ${next.review_id} task=${next.task_id} pr=${next.pr_number} decision=${outcome.decision} confidence=${outcome.confidence.toFixed(2)}`));
                 // RVU-2 (FU-RVU2R): claim-pause before review-pause. A review that ran
@@ -2426,7 +2718,7 @@ async function pumpReviews(state) {
                 // reviewer_capacity row; here we pause the whole runner exactly as a
                 // capacity_exhausted task does.
                 if (outcome.decision === "reviewer_capacity") {
-                    enterCapacityPause(state, next.task_id, outcome.resume_at ?? null, `reviewer ${next.review_id} hit session/usage limit`);
+                    enterCapacityPause(state, next.task_id, outcome.resume_at ?? null, `reviewer ${next.review_id} hit session/usage limit`, outcome.engine);
                     return;
                 }
             }
@@ -2445,7 +2737,7 @@ async function pumpReviews(state) {
     // to protect, so release the claim-pause and let queued tasks resume claiming.
     // (A whole-chain reviewer_capacity `return`s above and never reaches here;
     //  pausedCapacity keeps everything paused until the window reopens.)
-    if (state.capacityClaimPaused && !state.pausedCapacity) {
+    if (state.capacityClaimPaused && !hasCapacityPause(state)) {
         state.capacityClaimPaused = false;
         void pump(state, state.taskRunnerFactory);
     }
@@ -2557,11 +2849,27 @@ function enterQuarantine(state, taskId, cause, detail,
 // v0.53 T-53-4: how many consecutive instant-empty exits produced an
 // env_broken cause (1 = definitive, 2 = heuristic confirmed by the
 // retry). Persisted into quarantine.json's additive `consecutive` field.
-consecutive) {
+consecutive, 
+// USAGE-LIMIT-INVISIBLE-1 (AC4): the fleet capacity reset this quarantine
+// was folded onto (see signalUsageLimitCapacity), when cause is
+// usage_limit — null for an indefinite cap. Threaded through so the
+// operator-facing bus message + audit event carry a concrete retry path
+// instead of a bare "quarantined" with no next step: the RUNNER auto-clears
+// on this reset (restartClaims), but the specific failed task does not
+// requeue itself and needs a manual retry_task / `/acc retry`.
+usageLimitResumeAtIso, engine) {
     if (state.quarantined)
         return;
     state.quarantined = true;
     state.quarantineCause = cause; // v0.41.4: gates env_broken auto-recovery.
+    // Attribute an engine ONLY for a genuine per-engine capacity cap. `usage_limit`
+    // is the sole cap cause that quarantines (capacity_exhausted PAUSES instead),
+    // so it alone names the engine that hit the cap. Every other cause
+    // (env_broken, auth_expired, claude_unavailable, …) is a whole-runner fault
+    // with no provider to blame — labelling it with the task's engine would be a
+    // false attribution in the audit field (capacityEngine() also defaults a
+    // missing engine to claude-code). null = "no specific engine".
+    const engineId = cause === "usage_limit" && engine ? capacityEngine(engine) : null;
     const qState = {
         cause,
         classifiedAt: new Date().toISOString(),
@@ -2574,6 +2882,12 @@ consecutive) {
     });
     process.stderr.write(chalk.red.bold(`[acc-runner] QUARANTINE: runner ${state.session.runner_id} quarantined ` +
         `(${cause}) after task ${taskId} failed.\n`));
+    const retryHint = cause === "usage_limit"
+        ? `capacity-paused fleet-wide (see /api/health fleet_pause); resumes ` +
+            `${usageLimitResumeAtIso ?? "at an unknown time (indefinite cap)"} — this ` +
+            `runner un-quarantines automatically on resume, but task ${taskId} must be ` +
+            `retried manually (retry_task RPC / \`/acc retry\`) once capacity returns.`
+        : undefined;
     void postRunnerStateMessage(state.supabase, {
         task_id: taskId,
         sender_id: state.session.runner_id,
@@ -2583,7 +2897,9 @@ consecutive) {
             capacity_alert: true,
             quarantine_cause: cause,
             runner_id: state.session.runner_id,
+            engine: engineId,
             detail,
+            ...(retryHint ? { retry_hint: retryHint, capacity_resume_at: usageLimitResumeAtIso ?? null } : {}),
         },
         kind: "blocked",
     }).catch((err) => {
@@ -2594,7 +2910,13 @@ consecutive) {
             await state.supabase.rpc("log_activity", {
                 p_verb: "runner.quarantine_enter",
                 p_target_id: state.session.runner_id,
-                p_payload: { cause, task_id: taskId, detail },
+                p_payload: {
+                    cause,
+                    engine: engineId,
+                    task_id: taskId,
+                    detail,
+                    ...(retryHint ? { retry_hint: retryHint, capacity_resume_at: usageLimitResumeAtIso ?? null } : {}),
+                },
                 p_target_type: "runner",
             });
         }
@@ -2618,7 +2940,7 @@ consecutive) {
  * Idempotent: a straggler cap while already paused only ever pushes the reset
  * later (the window fold's extend-only rule), never shortens the wait.
  */
-function enterCapacityPause(state, triggerTaskId, resumeAtIso, detail) {
+function enterCapacityPause(state, triggerTaskId, resumeAtIso, detail, engine) {
     const now = Date.now();
     const parsed = resumeAtIso ? Date.parse(resumeAtIso) : NaN;
     const baseResumeMs = Number.isFinite(parsed) && parsed > now ? parsed : now + state.capacityBackoffMs;
@@ -2632,17 +2954,53 @@ function enterCapacityPause(state, triggerTaskId, resumeAtIso, detail) {
     // canonical pause payload + bus message (the seam only sees {account, reset}).
     state.capacityTriggerTaskId = triggerTaskId;
     state.capacityPauseDetail = detail;
+    state.capacityPauseEngine = capacityEngine(engine);
     // Stop claiming SYNCHRONOUSLY (the controller's stopClaims seam runs on the
     // serialized action tail a microtask later; pump()/pumpReviews() read this
     // flag between their own awaits, so setting it here closes the gap and keeps
     // the v0.56 "no new claim the instant a 429 lands" guarantee byte-identical).
-    state.pausedCapacity = true;
+    state.pausedCapacity.add(state.capacityPauseEngine);
     state.resumeController.reportCapacity({
         accountKey: state.resumeAccountKey ?? state.session.runner_id,
         resetAtMs: resumeMs,
         detail,
     });
 }
+/**
+ * USAGE-LIMIT-INVISIBLE-1: fold a usage_limit quarantine into the SAME
+ * fleet-visible capacity signal `enterCapacityPause` emits for
+ * capacity_exhausted, so `/api/health` fleet_pause and the FH-1b dispatch
+ * governor see the account as out of capacity instead of reading a live
+ * `paused_count: 0` while every task quietly dies (the 2026-08-30 incident:
+ * four usage_limit exits, zero capacity signal anywhere).
+ *
+ * Deliberately NOT `enterCapacityPause`: that helper falls back to a fixed
+ * backoff (`now + capacityBackoffMs`) when no reset was parsed, which is the
+ * right call for a KNOWN-recoverable 429 but would fabricate a retry time for
+ * a class the classifier does not promise resets on. Here a null resume
+ * folds onto the account window as an INDEFINITE cap (account-window.ts
+ * `isStillCapped`) — visible in fleet_pause as `resume_at: null` on a
+ * `paused_count > 0` row (never silently indistinguishable from "no pause"),
+ * and it only clears on an account swap, a positive probe ping, or the
+ * runner's own quarantine being cleared and re-observing the account.
+ *
+ * Runner-local claiming is already halted by `state.quarantined` (set by the
+ * caller's `enterQuarantine`); this only drives the fleet-visible signal +
+ * the resume bookkeeping so OTHER runners sharing the account — and the
+ * dispatcher — stop feeding it work too.
+ */
+function signalUsageLimitCapacity(state, triggerTaskId, resumeAtIso, detail, engine) {
+    const parsed = resumeAtIso ? Date.parse(resumeAtIso) : NaN;
+    const resetAtMs = Number.isFinite(parsed) ? parsed : null;
+    state.capacityTriggerTaskId = triggerTaskId;
+    state.capacityPauseDetail = detail;
+    state.capacityPauseEngine = capacityEngine(engine);
+    state.resumeController.reportCapacity({
+        accountKey: state.resumeAccountKey ?? state.session.runner_id,
+        resetAtMs,
+        detail,
+    });
+}
 /**
  * AS-3 (RESUME-WIRE): the ResumeController side-effect seams, backed by the REAL
  * runner path (log_activity RPCs + pollOnce/pump). Exported so the account-switch
@@ -2671,6 +3029,7 @@ export function buildResumeControllerDeps(state, factory) {
             const resumeAtIso = resetAtMs !== null ? new Date(resetAtMs).toISOString() : null;
             const detail = state.capacityPauseDetail;
             const triggerTaskId = state.capacityTriggerTaskId;
+            const engine = state.capacityPauseEngine;
             state.accountProbe?.setPaused(true);
             process.stderr.write(chalk.yellow(`[acc-runner] PAUSED (capacity) on ${account}: ${detail}. Not claiming ` +
                 `tasks or reviews; resuming at ${resumeAtIso ?? "reset / account change"}.\n`));
@@ -2682,6 +3041,7 @@ export function buildResumeControllerDeps(state, factory) {
                         runner_id: state.session.runner_id,
                         resume_at: resumeAtIso,
                         reason: detail,
+                        engine,
                         account,
                         version: PACKAGE_VERSION,
                     },
@@ -2703,6 +3063,7 @@ export function buildResumeControllerDeps(state, factory) {
                         capacity_paused: true,
                         runner_id: state.session.runner_id,
                         resume_at: resumeAtIso,
+                        engine,
                         detail,
                     },
                     kind: "blocked",
@@ -2712,7 +3073,8 @@ export function buildResumeControllerDeps(state, factory) {
             }
         },
         stopClaims: () => {
-            state.pausedCapacity = true;
+            if (state.capacityPauseEngine)
+                state.pausedCapacity.add(state.capacityPauseEngine);
         },
         clearServerPause: async () => {
             try {
@@ -2744,7 +3106,34 @@ export function buildResumeControllerDeps(state, factory) {
         restartClaims: async () => {
             if (state.stopped)
                 return;
-            state.pausedCapacity = false;
+            // USAGE-LIMIT-INVISIBLE-1 (AC4): a usage_limit quarantine anchored to
+            // the SAME account window that just reopened is released automatically
+            // — the account is no longer capped, so there is nothing left for an
+            // operator to "fix" by hand. Scoped to `usage_limit` only: env_broken
+            // has its own probe-gated auto-recovery (quarantineRecoveryScan) and
+            // auth_expired needs a fresh token, not a capacity reset. The task this
+            // runner already failed still needs a manual `retry_task` / `/acc
+            // retry` (it is NOT re-queued here) — see the retry hint on the
+            // quarantine's blocked/error_context message.
+            if (state.quarantined && state.quarantineCause === "usage_limit") {
+                await clearQuarantine().catch(() => { });
+                state.quarantined = false;
+                state.quarantineCause = null;
+                process.stderr.write(chalk.green(`[acc-runner] quarantine auto-cleared: usage_limit capacity window reopened. ` +
+                    `Resuming task claims (the quarantined task itself still needs a manual retry).\n`));
+                try {
+                    await state.supabase.rpc("log_activity", {
+                        p_verb: "runner.quarantine_auto_cleared",
+                        p_target_id: state.session.runner_id,
+                        p_payload: { cause: "usage_limit", version: PACKAGE_VERSION },
+                        p_target_type: "runner",
+                    });
+                }
+                catch { /* best-effort */ }
+            }
+            // Resume is account-wide, so clear all engine pauses in this window.
+            state.pausedCapacity.clear();
+            state.capacityPauseEngine = null;
             state.pausedUntil = null;
             // RVU-2 (FU-RVU2R): a full pause supersedes the soft claim-pause; clear it
             // so the probe window (task limit pinned to 1) isn't zeroed out.
@@ -2783,7 +3172,7 @@ async function wireCapacityResume(state, factory, options) {
     // accountIdentity() otherwise (an honest per-host synthetic account when no
     // real login introspects). Never throws — a failed probe degrades to unknown
     // here, and to a logged no-op on the scheduler's later cadence probes.
-    const chatEngine = getChatEngine();
+    const chatEngine = getConfiguredChatEngine();
     const probe = options.accountProbe ??
         (async () => {
             if (chatEngine.accountIdentity)
@@ -2879,12 +3268,9 @@ async function pump(state, factory) {
         // v0.48: check quarantine before claiming any task.
         if (state.quarantined) {
             process.stderr.write(`[acc-runner] QUARANTINED: runner ${state.session.runner_id} is not claiming tasks.\n` +
-                `[acc-runner] Fix the underlying issue then run \`acc-runner quarantine clear\`.\n`);
-            return;
-        }
-        // v0.56 (T-56-1): out of session/usage capacity — don't claim. Queued
-        // tasks stay queued; the scheduled resume re-drives pump().
-        if (state.pausedCapacity) {
+                `[acc-runner] Fix the underlying issue, then run \`acc-runner quarantine clear\` ` +
+                `for this named instance; repeat for each instance on the host. The running ` +
+                `watcher resumes on its next recovery tick; no restart is required.\n`);
             return;
         }
         // v0.56 (T-56-1): during the post-resume probe window, claim exactly one
@@ -2906,10 +3292,12 @@ async function pump(state, factory) {
         // Fill available concurrency slots from the queue.
         while (!state.stopped &&
             !state.quarantined &&
-            !state.pausedCapacity &&
             state.queue.length > 0 &&
             state.running.size < effectiveLimit) {
-            const next = state.queue.shift();
+            const nextIndex = state.queue.findIndex((id) => !isCapacityPausedFor(state, state.taskEngines.get(id)));
+            if (nextIndex === -1)
+                return;
+            const [next] = state.queue.splice(nextIndex, 1);
             if (!next)
                 continue;
             const ctrl = factory(next, {
@@ -2920,6 +3308,11 @@ async function pump(state, factory) {
                     runnerId: state.session.runner_id,
                 },
                 publicUrl: state.cfg.publicUrl,
+                onUnknownAdvertisedEngine: (engineId, err) => repairUnknownAdvertisedEngine(state, engineId, err),
+                // CLAIM-LOCK-GLOB: hand the per-runner claim-loss map
+                // to runTask so file-lock conflicts count attempts across re-dispatch
+                // and back off after the fast attempts are spent (AC3).
+                claimLossState: state.claimLossState,
             });
             state.running.set(next, ctrl);
             // Detached completion handler. Runs AFTER pump() returns so the
@@ -2929,9 +3322,7 @@ async function pump(state, factory) {
                 .then((outcome) => {
                 state.running.delete(next);
                 touchActivity(state); // v0.12.0 (T-52-7): idle clock restarts at task end
-                // v0.56 (T-56-1): capacity exhaustion pauses the WHOLE runner —
-                // never a task_error, never quarantine. Do not re-fire pump for new
-                // work; the scheduled resume does that with a single probe.
+                // Capacity exhaustion pauses only the refused engine's task claims.
                 //
                 // FH-1a: runTask now CLEANLY REQUEUES the in-flight task
                 // (running→queued) instead of abandoning it to the stale-running
@@ -2945,7 +3336,7 @@ async function pump(state, factory) {
                 // seen.delete (cancel → re-start).
                 if (outcome.status === "capacity_paused" || outcome.capacity_exhausted) {
                     state.seen.delete(next);
-                    enterCapacityPause(state, next, outcome.resume_at ?? null, outcome.error || "task hit session/usage limit");
+                    enterCapacityPause(state, next, outcome.resume_at ?? null, outcome.error || "task hit session/usage limit", outcome.engine ?? state.taskEngines.get(next));
                     return;
                 }
                 // Repo-scoped ignore: the task's repo is outside this runner's
@@ -2989,6 +3380,17 @@ async function pump(state, factory) {
                     // does not answer it with a resubscribe storm.
                     if (outcome.phase === "claim_locks") {
                         state.claimContentionSince.set(next, Date.now());
+                        // CLAIM-LOCK-GLOB: once the fast attempts are
+                        // spent runTask returns a bounded yield instant — hold the task
+                        // out of the re-dispatch queue until then (AC3) so a losing task
+                        // actually backs off instead of re-claiming every backstop cycle.
+                        // A null yield leaves it eligible for the next fast retry.
+                        if (outcome.claim_lock_yield_until_ms != null) {
+                            state.claimYieldUntil.set(next, outcome.claim_lock_yield_until_ms);
+                        }
+                        else {
+                            state.claimYieldUntil.delete(next);
+                        }
                     }
                     // v0.48: machine-level failure → quarantine. Guard with
                     // !state.quarantined so concurrent tasks don't fire duplicate
@@ -3031,12 +3433,22 @@ async function pump(state, factory) {
                                     void pump(state, factory);
                                 }
                                 else {
-                                    enterQuarantine(state, next, cause, reason, outcome.quarantine_consecutive);
+                                    enterQuarantine(state, next, cause, reason, outcome.quarantine_consecutive, undefined, outcome.engine ?? state.taskEngines.get(next));
                                 }
                             });
                             return;
                         }
-                        enterQuarantine(state, next, cause, reason, outcome.quarantine_consecutive);
+                        // USAGE-LIMIT-INVISIBLE-1: a usage_limit quarantine is ALSO a
+                        // fleet capacity signal — the account (not just this runner) is
+                        // out of room. Fold it into the same account-window / fleet_pause
+                        // machinery capacity_exhausted uses, carrying whatever reset the
+                        // provider stated (outcome.resume_at) or an explicit indefinite
+                        // cap (null) — BEFORE quarantining so a paused-fleet dispatcher
+                        // read never races an empty fleet_pause against the new quarantine.
+                        if (cause === "usage_limit") {
+                            signalUsageLimitCapacity(state, next, outcome.resume_at ?? null, reason, outcome.engine ?? state.taskEngines.get(next));
+                        }
+                        enterQuarantine(state, next, cause, reason, outcome.quarantine_consecutive, cause === "usage_limit" ? outcome.resume_at ?? null : undefined, outcome.engine ?? state.taskEngines.get(next));
                         // Quarantined — do not re-fire pump for new tasks.
                         // Other in-flight tasks (still in state.running) complete
                         // normally; we just stop accepting new work.