@whittlelabs/sifter 0.30.8 → 0.30.10

package/bin.js

@@ -9832,6 +9832,29 @@ var require_dist = __commonJS({
   }
 });
 
+// ../../packages/shuttle/dist/executors/types.js
+var require_types2 = __commonJS({
+  "../../packages/shuttle/dist/executors/types.js"(exports2) {
+    "use strict";
+    Object.defineProperty(exports2, "__esModule", { value: true });
+    exports2.ExecutorEnvironmentError = void 0;
+    exports2.isExecutorEnvironmentError = isExecutorEnvironmentError;
+    var ExecutorEnvironmentError = class extends Error {
+      /** What the operator should do, as one clause: "run `claude` and sign in". */
+      remedy;
+      constructor(message, remedy) {
+        super(message);
+        this.name = "ExecutorEnvironmentError";
+        this.remedy = remedy;
+      }
+    };
+    exports2.ExecutorEnvironmentError = ExecutorEnvironmentError;
+    function isExecutorEnvironmentError(err) {
+      return err instanceof Error && err.name === "ExecutorEnvironmentError";
+    }
+  }
+});
+
 // ../../packages/shuttle/dist/executors/validate-output.js
 var require_validate_output = __commonJS({
   "../../packages/shuttle/dist/executors/validate-output.js"(exports2) {
@@ -10005,6 +10028,7 @@ var require_claude_code = __commonJS({
       return mod && mod.__esModule ? mod : { "default": mod };
     };
     Object.defineProperty(exports2, "__esModule", { value: true });
+    exports2.classifyEnvironmentFault = classifyEnvironmentFault;
     exports2.createClaudeCodeExecutor = createClaudeCodeExecutor;
     exports2.parseStreamJson = parseStreamJson;
     exports2.relativeWorkspaceReads = relativeWorkspaceReads;
@@ -10017,6 +10041,7 @@ var require_claude_code = __commonJS({
     var path_1 = __importDefault(require("path"));
     var string_decoder_1 = require("string_decoder");
     var loom_1 = require_dist();
+    var types_1 = require_types2();
     var validate_output_1 = require_validate_output();
     var progress_1 = require_progress();
     var apply_1 = require_apply();
@@ -10030,6 +10055,39 @@ var require_claude_code = __commonJS({
       const subtype = meta.subtype && meta.subtype !== "success" ? `: ${meta.subtype}` : "";
       return `${fallback}${subtype}${status}`;
     }
+    var READINESS_PROMPT = "Reply with the single word: ok";
+    var READINESS_TIMEOUT_MS = 12e4;
+    var STDERR_LIMIT = 4e3;
+    var INSTALL_REMEDY = "install Claude Code (npm install -g @anthropic-ai/claude-code) where this process can find it on PATH";
+    var LOGIN_REMEDY = "run `claude` once and sign in (or set a valid ANTHROPIC_API_KEY)";
+    var LIMIT_REMEDY = "wait for the plan's usage limit to reset, or raise it";
+    var SIGNED_OUT = /invalid api key|please run \/login|not (?:logged|signed) in|oauth token (?:has )?expired|authentication_error|invalid x-api-key/i;
+    var OUT_OF_USAGE = /usage limit|credit balance is too low|out of (?:extra )?usage|hit your (?:\w+ )?(?:usage |spend )?limit|5-hour limit/i;
+    function classifyEnvironmentFault(failure) {
+      if (failure.spawnErrorCode === "ENOENT")
+        return INSTALL_REMEDY;
+      const text = failure.text ?? "";
+      if (failure.apiErrorStatus === 401 || SIGNED_OUT.test(text))
+        return LOGIN_REMEDY;
+      if (failure.apiErrorStatus === 402 || failure.apiErrorStatus === 429 || OUT_OF_USAGE.test(text)) {
+        return LIMIT_REMEDY;
+      }
+      return null;
+    }
+    function firstLine(text) {
+      for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed.length > 0)
+          return trimmed.length > 300 ? `${trimmed.slice(0, 300)}...` : trimmed;
+      }
+      return null;
+    }
+    function runFailure(local, message, facts) {
+      if (!local)
+        return new Error(message);
+      const remedy = classifyEnvironmentFault(facts);
+      return remedy ? new types_1.ExecutorEnvironmentError(message, remedy) : new Error(message);
+    }
     var ClaudeCodeExecutor = class {
       capability;
       strategies = [loom_1.PROMPT_EXECUTION_STRATEGY];
@@ -10094,7 +10152,21 @@ var require_claude_code = __commonJS({
             promptOnlyScratch = await fs_1.promises.mkdtemp(path_1.default.join(tmpBase, "shuttle-cc-run-"));
           }
           const runCwd = workspace?.cwd ?? promptOnlyScratch;
-          const { response, readPaths, toolInputs } = await this.runClaude(prompt, spec, runCwd, childEnv, signal, hintedModel, reporter, void 0, dispatch.job.id);
+          const { response, readPaths, toolInputs } = await this.runClaude(
+            prompt,
+            spec,
+            runCwd,
+            childEnv,
+            signal,
+            hintedModel,
+            reporter,
+            void 0,
+            dispatch.job.id,
+            // Local mode is the operator's own login: a failure of THAT is the
+            // machine's, and the runner pauses on it. With a revealed key it is one
+            // customer's, and only their job fails.
+            modelKey === null
+          );
           if (workspace) {
             const reads = [...readPaths];
             for (const rel of creditOverlayReads(toolInputs, workspace.overlay?.writtenPaths ?? [], runCwd)) {
@@ -10156,14 +10228,84 @@ var require_claude_code = __commonJS({
             outputLabel: handle.outputLabel,
             outputSchema: handle.outputSchema
           };
-          const { response } = await this.runClaude(followUp, spec, scratch, handle.childEnv, signal, handle.model, null, handle.sessionId, `${handle.sessionId}-repair`);
+          const { response } = await this.runClaude(followUp, spec, scratch, handle.childEnv, signal, handle.model, null, handle.sessionId, `${handle.sessionId}-repair`, handle.childEnv === void 0);
           return response;
         } finally {
           await fs_1.promises.rm(scratch, { recursive: true, force: true }).catch(() => {
           });
         }
       }
-      runClaude(prompt, spec, cwd, childEnv, signal, modelOverride, reporter, resumeSessionId, transcriptName) {
+      /**
+       * Can this machine run a job now? One real one-turn call through the CLI,
+       * the same probe `doctor --deep` makes. The runner asks it only while
+       * claiming is paused on an `ExecutorEnvironmentError`, and only in local
+       * mode. A signed-out or missing CLI fails before any model call, so the
+       * re-check spends nothing until the login works again, and then one turn.
+       */
+      async checkReadiness(signal) {
+        return new Promise((resolve) => {
+          let child;
+          try {
+            child = (0, child_process_1.spawn)("claude", ["--print", "--output-format", "stream-json", "--verbose", "--max-turns", "1", READINESS_PROMPT], { stdio: ["ignore", "pipe", "pipe"] });
+          } catch (err) {
+            resolve({ ready: false, reason: err instanceof Error ? err.message : String(err) });
+            return;
+          }
+          let stdout = "";
+          let stderr = "";
+          let settled = false;
+          const settle = (value) => {
+            if (settled)
+              return;
+            settled = true;
+            clearTimeout(timer);
+            signal.removeEventListener("abort", onAbort);
+            resolve(value);
+          };
+          const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            settle({ ready: false, reason: `the claude CLI did not answer within ${READINESS_TIMEOUT_MS / 1e3}s` });
+          }, READINESS_TIMEOUT_MS);
+          function onAbort() {
+            child.kill("SIGTERM");
+            settle({ ready: false, reason: "readiness check aborted" });
+          }
+          if (signal.aborted) {
+            onAbort();
+            return;
+          }
+          signal.addEventListener("abort", onAbort, { once: true });
+          child.stdout?.on("data", (chunk) => {
+            stdout += chunk.toString("utf-8");
+          });
+          child.stderr?.on("data", (chunk) => {
+            if (stderr.length < STDERR_LIMIT)
+              stderr += chunk.toString("utf-8");
+          });
+          child.on("error", (err) => {
+            const code = err.code;
+            settle({
+              ready: false,
+              reason: code === "ENOENT" ? `the claude CLI is not on this machine's PATH (${err.message})` : err.message
+            });
+          });
+          child.on("close", (code) => {
+            let meta = null;
+            try {
+              meta = parseStreamJson(stdout).resultMeta;
+            } catch {
+              meta = null;
+            }
+            if (code === 0 && !meta?.isError) {
+              settle({ ready: true });
+              return;
+            }
+            const said = meta?.detail ?? firstLine(stderr) ?? firstLine(stdout);
+            settle({ ready: false, reason: said ?? `the claude CLI exited with code ${code}` });
+          });
+        });
+      }
+      runClaude(prompt, spec, cwd, childEnv, signal, modelOverride, reporter, resumeSessionId, transcriptName, local = false) {
         const outputLabel = spec.outputLabel;
         const model = modelOverride ?? this.config.model;
         return new Promise((resolve, reject) => {
@@ -10194,6 +10336,7 @@ var require_claude_code = __commonJS({
             return;
           }
           const stdoutChunks = [];
+          let stderrText = "";
           let settled = false;
           const settle = (fn) => {
             if (settled)
@@ -10228,6 +10371,10 @@ var require_claude_code = __commonJS({
             if (tap && decoder)
               tap.push(decoder.write(chunk));
           });
+          child.stderr?.on("data", (chunk) => {
+            if (stderrText.length < STDERR_LIMIT)
+              stderrText += chunk.toString("utf-8");
+          });
           function onAbort() {
             child.kill("SIGTERM");
             settle(() => reject(new Error("Dispatch aborted")));
@@ -10242,6 +10389,11 @@ var require_claude_code = __commonJS({
           child.on("error", (err) => {
             clearTimeout(timer);
             signal.removeEventListener("abort", onAbort);
+            const code = err.code;
+            if (local && code === "ENOENT") {
+              settle(() => reject(new types_1.ExecutorEnvironmentError(`the claude CLI is not on this machine's PATH (${err.message})`, INSTALL_REMEDY)));
+              return;
+            }
             settle(() => reject(err));
           });
           child.on("close", (code) => {
@@ -10259,7 +10411,10 @@ var require_claude_code = __commonJS({
               try {
                 const stream = parseStreamJson(stdout);
                 if (stream.resultMeta?.isError) {
-                  throw new Error(describeClaudeFailure(stream.resultMeta, "Claude Code reported a failure"));
+                  throw runFailure(local, describeClaudeFailure(stream.resultMeta, "Claude Code reported a failure"), {
+                    apiErrorStatus: stream.resultMeta.apiErrorStatus,
+                    text: stream.resultMeta.detail ?? firstLine(stderrText)
+                  });
                 }
                 const answerText = stream.finalText ?? stdout;
                 const parsed = stream.structuredOutput ?? extractJsonObject(answerText);
@@ -10301,7 +10456,17 @@ var require_claude_code = __commonJS({
                 meta = parseStreamJson(stdout).resultMeta;
               } catch {
               }
-              settle(() => reject(new Error(describeClaudeFailure(meta, `Claude Code exited with code ${code}`))));
+              const said = meta?.detail ?? firstLine(stderrText) ?? firstLine(stdout);
+              const fallback = `Claude Code exited with code ${code}`;
+              const failure = runFailure(local, describeClaudeFailure(meta, fallback), {
+                apiErrorStatus: meta?.apiErrorStatus ?? null,
+                text: said
+              });
+              if (failure instanceof types_1.ExecutorEnvironmentError && !meta && said) {
+                settle(() => reject(new types_1.ExecutorEnvironmentError(`${fallback}: ${said}`, failure.remedy)));
+                return;
+              }
+              settle(() => reject(failure));
             }
           });
         });
@@ -11034,16 +11199,97 @@ var require_client = __commonJS({
   }
 });
 
+// ../../packages/keep/dist/rate-limited.js
+var require_rate_limited = __commonJS({
+  "../../packages/keep/dist/rate-limited.js"(exports2) {
+    "use strict";
+    Object.defineProperty(exports2, "__esModule", { value: true });
+    exports2.RateLimitGate = exports2.RATE_LIMIT_DEFAULT_MS = exports2.RATE_LIMIT_CAP_MS = exports2.RATE_LIMIT_FLOOR_MS = exports2.KeepRateLimitedError = void 0;
+    exports2.retryAfterMsOf = retryAfterMsOf;
+    var KeepRateLimitedError = class extends Error {
+      code = "RATE_LIMITED";
+      /** Host the exchange was sent to. */
+      host;
+      /** Keep's own words for the refusal ("Too many attempts. Please try again later."). */
+      reason;
+      /** How long from now to wait before asking again (ms), already floored and capped. */
+      retryAfterMs;
+      /** When the next exchange may be attempted (epoch ms). */
+      retryAt;
+      constructor(message, detail) {
+        super(message);
+        this.name = "KeepRateLimitedError";
+        this.host = detail.host;
+        this.reason = detail.reason;
+        this.retryAt = detail.retryAt;
+        this.retryAfterMs = Math.max(0, detail.retryAt - Date.now());
+      }
+    };
+    exports2.KeepRateLimitedError = KeepRateLimitedError;
+    exports2.RATE_LIMIT_FLOOR_MS = 5e3;
+    exports2.RATE_LIMIT_CAP_MS = 15 * 6e4;
+    exports2.RATE_LIMIT_DEFAULT_MS = 6e4;
+    function retryAfterMsOf(body, headers, now = Date.now()) {
+      return clamp(bodyRetryAfter(body) ?? headerRetryAfter(headers, now) ?? exports2.RATE_LIMIT_DEFAULT_MS);
+    }
+    function bodyRetryAfter(body) {
+      const value = body?.error?.retryAfter;
+      return typeof value === "number" && Number.isFinite(value) ? value * 1e3 : null;
+    }
+    function headerRetryAfter(headers, now) {
+      const raw = headers?.get("retry-after")?.trim();
+      if (!raw)
+        return null;
+      if (/^\d+$/.test(raw))
+        return Number(raw) * 1e3;
+      const at = Date.parse(raw);
+      return Number.isNaN(at) ? null : at - now;
+    }
+    function clamp(ms) {
+      return Math.min(exports2.RATE_LIMIT_CAP_MS, Math.max(exports2.RATE_LIMIT_FLOOR_MS, ms));
+    }
+    var RateLimitGate = class {
+      closed = null;
+      /** Record a 429 and return the error to throw for it. */
+      close(detail) {
+        const retryAt = Date.now() + detail.retryAfterMs;
+        const when = new Date(retryAt).toISOString().replace(/\.\d{3}Z$/, "Z");
+        this.closed = new KeepRateLimitedError(`[${detail.manager}] Keep at ${detail.host} is rate limiting this client's token exchange (429: ${detail.reason}); not asking again before ${when}`, { host: detail.host, reason: detail.reason, retryAt });
+        return this.closed;
+      }
+      /** Throws the rate-limited error while the gate is closed; a no-op once the time has passed. */
+      check() {
+        const closed = this.closed;
+        if (closed === null)
+          return;
+        if (Date.now() >= closed.retryAt) {
+          this.closed = null;
+          return;
+        }
+        throw new KeepRateLimitedError(closed.message, {
+          host: closed.host,
+          reason: closed.reason,
+          retryAt: closed.retryAt
+        });
+      }
+    };
+    exports2.RateLimitGate = RateLimitGate;
+  }
+});
+
 // ../../packages/keep/dist/service-token.js
 var require_service_token = __commonJS({
   "../../packages/keep/dist/service-token.js"(exports2) {
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.ServiceTokenManager = void 0;
+    var rate_limited_1 = require_rate_limited();
     var ServiceTokenManager = class {
       token = null;
       expiresAt = 0;
       pendingExchange = null;
+      /** Closed by a 429 until Keep's retry-after: no exchange is sent before it. */
+      rateLimit = new rate_limited_1.RateLimitGate();
       keepApiUrl;
       clientId;
       clientSecret;
@@ -11072,6 +11318,7 @@ var require_service_token = __commonJS({
         if (this.pendingExchange) {
           return this.pendingExchange;
         }
+        this.rateLimit.check();
         this.pendingExchange = this.exchange();
         try {
           return await this.pendingExchange;
@@ -11090,6 +11337,15 @@ var require_service_token = __commonJS({
           })
         });
         this.onResponse?.(response);
+        if (response.status === 429) {
+          const body = await response.json().catch(() => null);
+          throw this.rateLimit.close({
+            manager: "ServiceTokenManager",
+            host: hostOf(url),
+            reason: body?.error?.message ?? "Too Many Requests",
+            retryAfterMs: (0, rate_limited_1.retryAfterMsOf)(body, response.headers)
+          });
+        }
         const json = await response.json();
         if (!response.ok || !json.success) {
           const msg = json.error?.message ?? `Token exchange failed with status ${response.status}`;
@@ -11101,6 +11357,13 @@ var require_service_token = __commonJS({
       }
     };
     exports2.ServiceTokenManager = ServiceTokenManager;
+    function hostOf(url) {
+      try {
+        return new URL(url).host;
+      } catch {
+        return url;
+      }
+    }
   }
 });
 
@@ -11109,7 +11372,8 @@ var require_agent_token = __commonJS({
   "../../packages/keep/dist/agent-token.js"(exports2) {
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
-    exports2.AgentTokenManager = exports2.AgentCredentialRevokedError = void 0;
+    exports2.AgentTokenManager = exports2.KeepUnavailableError = exports2.AgentCredentialRevokedError = void 0;
+    var rate_limited_1 = require_rate_limited();
     var AgentCredentialRevokedError2 = class extends Error {
       code = "PAIRING_REVOKED";
       constructor(message) {
@@ -11118,10 +11382,26 @@ var require_agent_token = __commonJS({
       }
     };
     exports2.AgentCredentialRevokedError = AgentCredentialRevokedError2;
+    var KeepUnavailableError = class extends Error {
+      code = "SERVICE_UNAVAILABLE";
+      /** Host the exchange was sent to, so a log line names the service that is down. */
+      host;
+      /** The status whatever answered sent, or null when nothing answered at all. */
+      statusCode;
+      constructor(message, detail) {
+        super(message, detail.cause !== void 0 ? { cause: detail.cause } : void 0);
+        this.name = "KeepUnavailableError";
+        this.host = detail.host;
+        this.statusCode = detail.statusCode;
+      }
+    };
+    exports2.KeepUnavailableError = KeepUnavailableError;
     var AgentTokenManager = class {
       token = null;
       expiresAt = 0;
       pendingExchange = null;
+      /** Closed by a 429 until Keep's retry-after: no exchange is sent before it. */
+      rateLimit = new rate_limited_1.RateLimitGate();
       keepApiUrl;
       clientId;
       clientSecret;
@@ -11143,6 +11423,7 @@ var require_agent_token = __commonJS({
         if (this.pendingExchange) {
           return this.pendingExchange;
         }
+        this.rateLimit.check();
         this.pendingExchange = this.exchange();
         try {
           return await this.pendingExchange;
@@ -11152,16 +11433,43 @@ var require_agent_token = __commonJS({
       }
       async exchange() {
         const url = `${this.keepApiUrl}/api/agent-tokens`;
-        const response = await fetch(url, {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({
-            clientId: this.clientId,
-            clientSecret: this.clientSecret
-          })
-        });
+        const host = hostOf(url);
+        let response;
+        try {
+          response = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+              clientId: this.clientId,
+              clientSecret: this.clientSecret
+            })
+          });
+        } catch (err) {
+          throw new KeepUnavailableError(`[AgentTokenManager] could not reach Keep at ${host}: ${describeTransportError(err)}`, { host, statusCode: null, cause: err });
+        }
         this.onResponse?.(response);
-        const json = await response.json();
+        const text = await response.text().catch(() => "");
+        let json;
+        try {
+          json = JSON.parse(text);
+        } catch {
+          json = null;
+        }
+        if (response.status >= 500) {
+          const reason = json?.error?.message ?? `Agent token exchange failed with status ${response.status}`;
+          throw new KeepUnavailableError(`[AgentTokenManager] Keep at ${host} is unavailable (${response.status}): ${reason}`, { host, statusCode: response.status });
+        }
+        if (response.status === 429) {
+          throw this.rateLimit.close({
+            manager: "AgentTokenManager",
+            host,
+            reason: json?.error?.message ?? "Too Many Requests",
+            retryAfterMs: (0, rate_limited_1.retryAfterMsOf)(json, response.headers)
+          });
+        }
+        if (json === null) {
+          throw new Error(`[AgentTokenManager] Keep at ${host} answered ${response.status} with a body that is not JSON`);
+        }
         if (!response.ok || !json.success) {
           const msg = json.error?.message ?? `Agent token exchange failed with status ${response.status}`;
           if (response.status === 401) {
@@ -11175,6 +11483,23 @@ var require_agent_token = __commonJS({
       }
     };
     exports2.AgentTokenManager = AgentTokenManager;
+    function hostOf(url) {
+      try {
+        return new URL(url).host;
+      } catch {
+        return url;
+      }
+    }
+    function describeTransportError(err) {
+      if (err instanceof Error) {
+        const cause = err.cause;
+        if (cause instanceof Error && cause.message && cause.message !== err.message) {
+          return `${err.message}: ${cause.message}`;
+        }
+        return err.message;
+      }
+      return String(err);
+    }
   }
 });
 
@@ -11183,7 +11508,7 @@ var require_dist2 = __commonJS({
   "../../packages/keep/dist/index.js"(exports2) {
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
-    exports2.AgentCredentialRevokedError = exports2.AgentTokenManager = exports2.ServiceTokenManager = exports2.KeepClient = void 0;
+    exports2.KeepRateLimitedError = exports2.KeepUnavailableError = exports2.AgentCredentialRevokedError = exports2.AgentTokenManager = exports2.ServiceTokenManager = exports2.KeepClient = void 0;
     var client_1 = require_client();
     Object.defineProperty(exports2, "KeepClient", { enumerable: true, get: function() {
       return client_1.KeepClient;
@@ -11199,6 +11524,13 @@ var require_dist2 = __commonJS({
     Object.defineProperty(exports2, "AgentCredentialRevokedError", { enumerable: true, get: function() {
       return agent_token_1.AgentCredentialRevokedError;
     } });
+    Object.defineProperty(exports2, "KeepUnavailableError", { enumerable: true, get: function() {
+      return agent_token_1.KeepUnavailableError;
+    } });
+    var rate_limited_1 = require_rate_limited();
+    Object.defineProperty(exports2, "KeepRateLimitedError", { enumerable: true, get: function() {
+      return rate_limited_1.KeepRateLimitedError;
+    } });
   }
 });
 
@@ -12064,6 +12396,13 @@ var require_checks = __commonJS({
           return skip("pairing-live", "no readable pairing; see pairing-present");
         }
         const minted = await probes.mintAgentToken(stored.value);
+        if (!minted.ok && minted.rateLimited) {
+          const at = formatInstant(minted.rateLimited.retryAt);
+          return warn("pairing-live", `Keep is rate limiting this pairing's token exchange (429), so the pairing could not be checked; it asked for no retry before ${at}`, subject.phase === "run" ? `nothing to do; \`run\` waits until ${at}, asks once, and starts claiming when Keep issues a token` : `wait until ${at}, then run doctor again`);
+        }
+        if (!minted.ok && minted.unavailable) {
+          return warn("pairing-live", `Keep did not answer, so the pairing could not be checked: ${oneLine(minted.error).replace(/^\[AgentTokenManager\]\s*/, "")}`, subject.phase === "run" ? "nothing to do if this is a deployment window; `run` waits for Keep and starts claiming when it answers" : `check ${stored.value.keepApiUrl} is reachable, then run doctor again`);
+        }
         if (!minted.ok) {
           return fail("pairing-live", `Keep did not issue a token: ${oneLine(minted.error)}`, `check ${stored.value.keepApiUrl} is reachable, then run \`${subject.brand.product.cliBinary} init\` if the pairing was revoked`);
         }
@@ -12118,6 +12457,9 @@ var require_checks = __commonJS({
         const pairing = stored.value;
         return withConfig("jobs-reachable", probes, async (config) => {
           const result = await probes.reachJobs(config, pairing);
+          if (!result.ok && result.rateLimited) {
+            return warn("jobs-reachable", `${config.auth.jobsApiUrl} was not asked: Keep is rate limiting the token exchange until ${formatInstant(result.rateLimited.retryAt)}`, "see pairing-live; the run loop asks once Keep issues a token");
+          }
           if (!result.ok) {
             return warn("jobs-reachable", `${config.auth.jobsApiUrl} did not answer: ${oneLine(result.error)}`, "nothing to do if this is a deployment window; the run loop will keep trying");
           }
@@ -12399,6 +12741,9 @@ var require_checks = __commonJS({
     function osTmpDirOf(probes) {
       return probes.osTmpDir();
     }
+    function formatInstant(epochMs) {
+      return new Date(epochMs).toISOString().replace(/\.\d{3}Z$/, "Z");
+    }
     function oneLine(message) {
       return message.split("\n").map((line) => line.trim()).filter((line) => line.length > 0).join(" ");
     }
@@ -20092,6 +20437,41 @@ var require_subscribe = __commonJS({
     function sleep(ms) {
       return new Promise((resolve) => setTimeout(resolve, ms));
     }
+    function isUnavailable(err) {
+      if (err instanceof response_1.ServiceUnavailableError)
+        return true;
+      if (err?.code === "SERVICE_UNAVAILABLE")
+        return true;
+      return err instanceof TypeError && err.message === "fetch failed";
+    }
+    function isRateLimited(err) {
+      return err?.code === "RATE_LIMITED";
+    }
+    function rateLimitWaitMs(err) {
+      const e = err ?? {};
+      if (typeof e.retryAfterMs === "number" && Number.isFinite(e.retryAfterMs))
+        return Math.max(0, e.retryAfterMs);
+      if (typeof e.retryAt === "number" && Number.isFinite(e.retryAt))
+        return Math.max(0, e.retryAt - Date.now());
+      return 0;
+    }
+    function formatInstant(epochMs) {
+      return new Date(epochMs).toISOString().replace(/\.\d{3}Z$/, "Z");
+    }
+    function describeOutage(err) {
+      const e = err ?? {};
+      if (typeof e.host === "string" && typeof e.statusCode === "number") {
+        const text = typeof e.statusText === "string" && e.statusText ? ` ${e.statusText}` : "";
+        return `${e.host} answered ${e.statusCode}${text}`;
+      }
+      if (typeof e.host === "string")
+        return `${e.host} did not answer`;
+      if (err instanceof Error) {
+        const cause = err.cause;
+        return cause instanceof Error ? `${err.message}: ${cause.message}` : err.message;
+      }
+      return String(err);
+    }
     function formatDuration(ms) {
       const seconds = Math.round(ms / 1e3);
       if (seconds < 60)
@@ -20100,112 +20480,270 @@ var require_subscribe = __commonJS({
       const rest = seconds % 60;
       return rest === 0 ? `${minutes}m` : `${minutes}m ${rest}s`;
     }
+    function newOutcome() {
+      let resolve;
+      let reject;
+      const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+      });
+      promise.catch(() => {
+      });
+      const outcome = {
+        promise,
+        settled: false,
+        resolve: () => {
+          if (outcome.settled)
+            return;
+          outcome.settled = true;
+          resolve();
+        },
+        reject: (err) => {
+          if (outcome.settled)
+            return;
+          outcome.settled = true;
+          reject(err);
+        }
+      };
+      return outcome;
+    }
+    var STOPPED = Symbol("stopped");
     function subscribe(opts) {
       const logger = opts.logger ?? NULL_LOGGER;
       const pollIntervalMs = opts.pollIntervalMs ?? 2e3;
       const maxConcurrency = opts.maxConcurrency ?? 1;
+      const isFatal = opts.isFatal ?? (() => false);
       let stopped = true;
+      let session = 0;
       let pollTimer = null;
       let inflight = 0;
       let resolvedPoolIds = [];
+      const controllers = /* @__PURE__ */ new Set();
+      const holds = /* @__PURE__ */ new Set();
+      let fatalError = null;
+      let outcome = newOutcome();
+      let wakeStartup = null;
       let unavailableSince = null;
+      let rateLimited = null;
+      function noteReachable() {
+        if (unavailableSince !== null) {
+          logger.info(`Sift is reachable again after ${formatDuration(Date.now() - unavailableSince)}`);
+          unavailableSince = null;
+        }
+        if (rateLimited !== null) {
+          logger.info(`${rateLimited.host} stopped rate limiting the Sifter after ${formatDuration(Date.now() - rateLimited.since)}`);
+          rateLimited = null;
+        }
+      }
+      function noteRateLimited(err) {
+        const waitMs = Math.max(pollIntervalMs, rateLimitWaitMs(err));
+        const e = err ?? {};
+        const host = typeof e.host === "string" ? e.host : "the service";
+        if (rateLimited === null) {
+          rateLimited = { since: Date.now(), host };
+          const reason = typeof e.reason === "string" ? `: ${e.reason}` : "";
+          logger.warn(`${host} is rate limiting the Sifter (429${reason}). It will wait and try again at ${formatInstant(Date.now() + waitMs)} (in ${formatDuration(waitMs)}).`);
+        } else {
+          logger.debug?.("still rate limited", {
+            host,
+            rateLimitedFor: formatDuration(Date.now() - rateLimited.since),
+            nextAttemptIn: formatDuration(waitMs)
+          });
+        }
+        return waitMs;
+      }
+      function noteUnavailable(err) {
+        if (unavailableSince === null) {
+          unavailableSince = Date.now();
+          logger.warn(`Sift is unavailable (${describeOutage(err)}). This is typical during a deployment window; the Sifter will keep trying.`);
+        } else {
+          const e = err ?? {};
+          logger.debug?.("Sift still unavailable", {
+            ...typeof e.host === "string" ? { host: e.host } : {},
+            ...typeof e.statusCode === "number" ? { status: e.statusCode } : {},
+            unavailableFor: formatDuration(Date.now() - unavailableSince)
+          });
+        }
+      }
+      function startupPause(ms) {
+        return new Promise((resolve) => {
+          const timer = setTimeout(() => {
+            wakeStartup = null;
+            resolve();
+          }, ms);
+          wakeStartup = () => {
+            clearTimeout(timer);
+            wakeStartup = null;
+            resolve();
+          };
+        });
+      }
+      async function untilAvailable(call, mySession) {
+        for (; ; ) {
+          let pause = pollIntervalMs;
+          try {
+            const value = await call();
+            noteReachable();
+            return value;
+          } catch (err) {
+            if (isFatal(err))
+              throw err;
+            if (isRateLimited(err))
+              pause = noteRateLimited(err);
+            else if (isUnavailable(err))
+              noteUnavailable(err);
+            else
+              throw err;
+          }
+          await startupPause(pause);
+          if (stopped || mySession !== session)
+            return STOPPED;
+        }
+      }
       async function start() {
         if (!stopped)
           return;
         stopped = false;
+        session += 1;
+        const mySession = session;
+        if (outcome.settled)
+          outcome = newOutcome();
+        fatalError = null;
         resolvedPoolIds = [];
-        for (const ref of opts.pools) {
-          const id = await opts.jobsClient.resolvePoolRef(ref);
-          resolvedPoolIds.push(id);
-          await opts.jobsClient.registerMember(id, {
-            identityType: opts.subscriber.identityType,
-            identityId: opts.subscriber.identityId,
-            intelligence: opts.subscriber.intelligence,
-            ...opts.subscriber.displayName !== void 0 ? { displayName: opts.subscriber.displayName } : {},
-            ...opts.subscriber.metadata !== void 0 ? { metadata: opts.subscriber.metadata } : {}
-          });
+        try {
+          for (const ref of opts.pools) {
+            const id = await untilAvailable(() => opts.jobsClient.resolvePoolRef(ref), mySession);
+            if (id === STOPPED)
+              return;
+            resolvedPoolIds.push(id);
+            const registered = await untilAvailable(() => opts.jobsClient.registerMember(id, {
+              identityType: opts.subscriber.identityType,
+              identityId: opts.subscriber.identityId,
+              intelligence: opts.subscriber.intelligence,
+              ...opts.subscriber.displayName !== void 0 ? { displayName: opts.subscriber.displayName } : {},
+              ...opts.subscriber.metadata !== void 0 ? { metadata: opts.subscriber.metadata } : {}
+            }), mySession);
+            if (registered === STOPPED)
+              return;
+          }
+        } catch (err) {
+          if (mySession === session) {
+            stopped = true;
+            outcome.reject(err);
+          }
+          throw err;
         }
+        if (stopped || mySession !== session)
+          return;
         logger.info("subscribe loop started", { pools: resolvedPoolIds, maxConcurrency });
         schedulePoll(pollIntervalMs);
       }
-      async function stop() {
-        if (stopped)
-          return;
+      async function finish() {
+        while (inflight > 0) {
+          await sleep(100);
+        }
+        logger.info("subscribe loop stopped");
+        if (fatalError !== null)
+          outcome.reject(fatalError.error);
+        else
+          outcome.resolve();
+      }
+      function halt() {
         stopped = true;
         if (pollTimer !== null) {
           clearTimeout(pollTimer);
           pollTimer = null;
         }
-        while (inflight > 0) {
-          await sleep(100);
-        }
-        logger.info("subscribe loop stopped");
+        wakeStartup?.();
+      }
+      async function stop() {
+        if (stopped)
+          return;
+        halt();
+        await finish();
+      }
+      async function fail(err) {
+        if (fatalError === null)
+          fatalError = { error: err };
+        for (const controller of controllers)
+          controller.abort(err);
+        if (stopped)
+          return;
+        halt();
+        await finish();
       }
       function schedulePoll(delayMs) {
+        const mySession = session;
         pollTimer = setTimeout(() => {
-          void poll();
+          void poll(mySession);
         }, delayMs);
       }
-      async function poll() {
-        if (stopped)
+      async function poll(mySession) {
+        if (stopped || mySession !== session)
           return;
+        let nextPollMs = pollIntervalMs;
         if (inflight >= maxConcurrency) {
           schedulePoll(pollIntervalMs);
           return;
         }
         try {
+          const paused = holds.size > 0;
           const { data, directives } = await opts.jobsClient.listDispatchableJobs({
             pools: resolvedPoolIds,
-            limit: maxConcurrency - inflight,
+            limit: paused ? 1 : maxConcurrency - inflight,
             sort: "priority:desc,queued_at:asc"
           });
-          if (unavailableSince !== null) {
-            logger.info(`Sift is reachable again after ${formatDuration(Date.now() - unavailableSince)}`);
-            unavailableSince = null;
-          }
+          noteReachable();
           if (directives && Object.keys(directives).length > 0 && opts.onDirectives) {
             try {
               await opts.onDirectives(directives);
             } catch (err) {
+              if (isFatal(err)) {
+                void fail(err);
+                return;
+              }
               logger.error("onDirectives handler failed", {
                 error: err instanceof Error ? err.message : String(err)
               });
             }
           }
-          if (stopped)
+          if (stopped || mySession !== session)
             return;
-          for (const job of data) {
-            if (inflight >= maxConcurrency)
-              break;
-            inflight++;
-            void runOnce(job).finally(() => {
-              inflight--;
-            });
-          }
-        } catch (err) {
-          if (err instanceof response_1.ServiceUnavailableError) {
-            if (unavailableSince === null) {
-              unavailableSince = Date.now();
-              logger.warn(`Sift is unavailable (${err.host} answered ${err.statusCode}${err.statusText ? ` ${err.statusText}` : ""}). This is typical during a deployment window; the Sifter will keep trying.`);
-            } else {
-              logger.debug?.("Sift still unavailable", {
-                host: err.host,
-                status: err.statusCode,
-                unavailableFor: formatDuration(Date.now() - unavailableSince)
+          if (holds.size === 0) {
+            for (const job of data) {
+              if (inflight >= maxConcurrency)
+                break;
+              inflight++;
+              void runOnce(job).finally(() => {
+                inflight--;
               });
             }
+          }
+        } catch (err) {
+          if (isFatal(err)) {
+            void fail(err);
+            return;
+          }
+          if (isRateLimited(err)) {
+            nextPollMs = noteRateLimited(err);
+          } else if (isUnavailable(err)) {
+            noteUnavailable(err);
           } else {
             logger.error("poll failed", { error: err instanceof Error ? err.message : String(err) });
           }
         }
-        if (!stopped)
-          schedulePoll(pollIntervalMs);
+        if (!stopped && mySession === session)
+          schedulePoll(nextPollMs);
       }
       async function runOnce(available) {
         let dispatch;
         try {
           dispatch = await opts.jobsClient.acceptDispatch(available.id);
         } catch (err) {
+          if (isFatal(err)) {
+            void fail(err);
+            return;
+          }
           const statusCode = err.statusCode;
           if (statusCode === 409) {
             logger.debug?.("claim conflict; another member accepted", { jobId: available.id });
@@ -20218,6 +20756,9 @@ var require_subscribe = __commonJS({
           return;
         }
         const controller = new AbortController();
+        controllers.add(controller);
+        if (fatalError !== null)
+          controller.abort(fatalError.error);
         let quietTimer = null;
         const quietWindowMs = dispatch.deadline ? new Date(dispatch.deadline).getTime() - Date.now() : null;
         const armQuietTimer = () => {
@@ -20243,6 +20784,8 @@ var require_subscribe = __commonJS({
         try {
           result = await opts.onJob(dispatch, controller.signal, activity);
         } catch (err) {
+          if (isFatal(err))
+            void fail(err);
           result = {
             status: "failed",
             reason: `onJob threw: ${err instanceof Error ? err.message : String(err)}`
@@ -20250,6 +20793,11 @@ var require_subscribe = __commonJS({
         } finally {
           if (quietTimer !== null)
             clearTimeout(quietTimer);
+          controllers.delete(controller);
+        }
+        if (fatalError !== null) {
+          logger.debug?.("not submitting a result after a fatal error", { jobId: dispatch.job.id });
+          return;
         }
         try {
           for (const output of result.outputs ?? []) {
@@ -20263,13 +20811,27 @@ var require_subscribe = __commonJS({
             ...result.reason !== void 0 ? { reason: result.reason } : {}
           });
         } catch (err) {
+          if (isFatal(err)) {
+            void fail(err);
+            return;
+          }
           logger.error("submit/close failed", {
             jobId: dispatch.job.id,
             error: err instanceof Error ? err.message : String(err)
           });
         }
       }
-      return { start, stop };
+      return {
+        start,
+        stop,
+        done: () => outcome.promise,
+        pause: (reason) => {
+          holds.add(reason);
+        },
+        resume: (reason) => {
+          holds.delete(reason);
+        }
+      };
     }
   }
 });
@@ -20642,6 +21204,21 @@ var require_probes = __commonJS({
           packageName: options.brand.product.packageName
         });
       };
+      const managers = /* @__PURE__ */ new Map();
+      const tokensFor = (pairing) => {
+        const key = JSON.stringify([pairing.keepApiUrl, pairing.credentials.clientId, pairing.credentials.clientSecret]);
+        let tokens = managers.get(key);
+        if (tokens === void 0) {
+          tokens = new keep_1.AgentTokenManager({
+            keepApiUrl: pairing.keepApiUrl,
+            clientId: pairing.credentials.clientId,
+            clientSecret: pairing.credentials.clientSecret,
+            onResponse: enforceFloor
+          });
+          managers.set(key, tokens);
+        }
+        return tokens;
+      };
       let pairingRead;
       let configRead;
       let scaffoldedRead;
@@ -20770,12 +21347,7 @@ var require_probes = __commonJS({
           return scaffoldedRead;
         },
         async mintAgentToken(pairing) {
-          const tokens = new keep_1.AgentTokenManager({
-            keepApiUrl: pairing.keepApiUrl,
-            clientId: pairing.credentials.clientId,
-            clientSecret: pairing.credentials.clientSecret,
-            onResponse: enforceFloor
-          });
+          const tokens = tokensFor(pairing);
           try {
             const token = await tokens.getToken();
             if (token === null) {
@@ -20785,16 +21357,14 @@ var require_probes = __commonJS({
           } catch (err) {
             if (isRevoked(err) || isUpgradeRequired(err))
               throw err;
-            return { ok: false, error: describe(err) };
+            if (isKeepRateLimited(err)) {
+              return { ok: false, error: describe(err), rateLimited: { retryAt: err.retryAt } };
+            }
+            return { ok: false, error: describe(err), ...isKeepUnavailable(err) ? { unavailable: true } : {} };
           }
         },
         async reachJobs(config, pairing) {
-          const tokens = new keep_1.AgentTokenManager({
-            keepApiUrl: pairing.keepApiUrl,
-            clientId: pairing.credentials.clientId,
-            clientSecret: pairing.credentials.clientSecret,
-            onResponse: enforceFloor
-          });
+          const tokens = tokensFor(pairing);
           const client = new jobs_1.JobsClient({
             baseUrl: config.auth.jobsApiUrl,
             ...config.auth.apiKey ? { apiKey: config.auth.apiKey } : {},
@@ -20811,6 +21381,9 @@ var require_probes = __commonJS({
           } catch (err) {
             if (isRevoked(err) || isUpgradeRequired(err))
               throw err;
+            if (isKeepRateLimited(err)) {
+              return { ok: false, error: describe(err), rateLimited: { retryAt: err.retryAt } };
+            }
             return { ok: false, error: describe(err) };
           }
         },
@@ -20903,6 +21476,12 @@ var require_probes = __commonJS({
     function isRevoked(err) {
       return err instanceof Error && err.name === "AgentCredentialRevokedError";
     }
+    function isKeepUnavailable(err) {
+      return err instanceof Error && err.name === "KeepUnavailableError";
+    }
+    function isKeepRateLimited(err) {
+      return err instanceof Error && err.name === "KeepRateLimitedError";
+    }
     function isUpgradeRequired(err) {
       return err instanceof Error && err.name === "UpgradeRequiredError";
     }
@@ -23465,6 +24044,8 @@ var require_self_update = __commonJS({
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.readUpgradeDirective = readUpgradeDirective;
     exports2.performSelfUpdate = performSelfUpdate;
+    exports2.floorUpdateTarget = floorUpdateTarget;
+    exports2.updateForFloor = updateForFloor;
     var child_process_1 = require("child_process");
     var version_check_1 = require_version_check();
     function readUpgradeDirective(directives, currentVersion, attemptedVersions) {
@@ -23506,6 +24087,32 @@ var require_self_update = __commonJS({
       respawn();
       return true;
     }
+    function floorUpdateTarget(minVersion, latestVersion) {
+      return latestVersion !== null && (0, version_check_1.compareSemver)(latestVersion, minVersion) >= 0 ? latestVersion : minVersion;
+    }
+    async function updateForFloor(opts) {
+      const { productTitle, packageName, currentVersion, minVersion, hosted, logger, hooks } = opts;
+      const refusal = new version_check_1.UpgradeRequiredError({ currentVersion, minVersion, packageName });
+      const target = floorUpdateTarget(minVersion, opts.latestVersion);
+      logger.warn(`The backend now requires ${packageName} ${minVersion} or newer, and this ${productTitle} is ${currentVersion}. It has stopped claiming and is finishing the work in hand, then ` + (hosted ? `exiting: a hosted ${productTitle} is updated by redeploying its image.` : `updating itself to ${target}.`));
+      await hooks.drain();
+      if (hosted) {
+        hooks.exit(refusal);
+        return;
+      }
+      const spec = `${packageName}@${target}`;
+      try {
+        await (hooks.install ?? defaultInstall)(spec);
+      } catch (err) {
+        logger.error(`could not install ${spec}, so this ${productTitle} cannot continue`, {
+          error: err instanceof Error ? err.message : String(err)
+        });
+        hooks.exit(refusal);
+        return;
+      }
+      logger.info("self-update installed; restarting", { packageSpec: spec });
+      (hooks.respawn ?? defaultRespawn)();
+    }
     function defaultInstall(packageSpec) {
       return new Promise((resolve, reject) => {
         const child = (0, child_process_1.spawn)("npm", ["install", "-g", packageSpec], {
@@ -24954,12 +25561,14 @@ var require_shuttle = __commonJS({
     var decommission_1 = require_decommission();
     var loom_1 = require_dist();
     var chain_1 = require_chain();
+    var types_1 = require_types2();
     var workspace_1 = require_workspace();
     var credentials_1 = require_credentials();
     var output_gates_1 = require_output_gates();
     var keep_1 = require_dist2();
     var apply_1 = require_apply();
     var version_check_1 = require_version_check();
+    var typed_exit_1 = require_typed_exit();
     var logger_1 = require_logger();
     var registry_1 = require_registry();
     var claude_code_1 = require_claude_code();
@@ -24972,6 +25581,56 @@ var require_shuttle = __commonJS({
     var spend_tracker_1 = require_spend_tracker();
     var store_1 = require_store();
     var GATE_REPAIR_BUDGET = 2;
+    var ENVIRONMENT_HOLD = "executor-environment";
+    var RECHECK_INITIAL_MS = 15e3;
+    var RECHECK_MAX_MS = 3e5;
+    var KEEP_RETRY_INITIAL_MS = 2e3;
+    var KEEP_RETRY_MAX_MS = 3e4;
+    function formatDuration(ms) {
+      const seconds = Math.round(ms / 1e3);
+      if (seconds < 60)
+        return `${seconds}s`;
+      const minutes = Math.floor(seconds / 60);
+      const rest = seconds % 60;
+      return rest === 0 ? `${minutes}m` : `${minutes}m ${rest}s`;
+    }
+    function abortableSleep(ms, signal) {
+      return new Promise((resolve) => {
+        if (signal?.aborted) {
+          resolve();
+          return;
+        }
+        const timer = setTimeout(() => {
+          signal?.removeEventListener("abort", onAbort);
+          resolve();
+        }, ms);
+        function onAbort() {
+          clearTimeout(timer);
+          resolve();
+        }
+        signal?.addEventListener("abort", onAbort, { once: true });
+      });
+    }
+    function deferred() {
+      let resolve;
+      let reject;
+      const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+      });
+      promise.catch(() => {
+      });
+      return { promise, resolve, reject };
+    }
+    function isKeepUnavailable(err) {
+      return err instanceof Error && err.name === "KeepUnavailableError";
+    }
+    function isKeepRateLimited(err) {
+      return err instanceof Error && err.name === "KeepRateLimitedError";
+    }
+    function formatInstant(epochMs) {
+      return new Date(epochMs).toISOString().replace(/\.\d{3}Z$/, "Z");
+    }
     async function runOutputGates(dispatch, response, executor, signal, ctx) {
       let spec;
       try {
@@ -25007,6 +25666,7 @@ var require_shuttle = __commonJS({
       config;
       profile;
       credentialDeps;
+      environmentRecheck;
       subscription = null;
       spendTracker = null;
       /**
@@ -25015,11 +25675,26 @@ var require_shuttle = __commonJS({
        * (no such config) → consumers reveal nothing and use ambient credentials.
        */
       broker = null;
+      /**
+       * The run's outcome, which `done()` hands out. Resolves on `stop()`.
+       * Rejects with what ended the run otherwise: a refused credential
+       * (`AgentCredentialRevokedError`, exit 3) or a floor this build could not
+       * update past (`UpgradeRequiredError`, exit 2).
+       */
+      lifetime = deferred();
+      /** Aborted by `stop()`: ends the startup waits and the readiness re-checks. */
+      stopping = new AbortController();
+      /** When claiming was paused on an executor environment fault; null while claiming. */
+      environmentPausedAt = null;
       constructor(options) {
         this.brand = options.brand;
         this.config = options.config;
         this.profile = options.profile ?? apply_1.DEFAULT_PROFILE;
         this.credentialDeps = options.credentialDeps ?? {};
+        this.environmentRecheck = options.environmentRecheck ?? {
+          initialMs: RECHECK_INITIAL_MS,
+          maxMs: RECHECK_MAX_MS
+        };
       }
       /** Exposed so the CLI's `caps set` can reload after a write. */
       get spendTrackerHandle() {
@@ -25034,19 +25709,62 @@ var require_shuttle = __commonJS({
         logger.info(`${this.brand.product.title} starting...`);
         const paths = (0, apply_1.resolvePaths)(this.brand, this.profile);
         this.broker = (0, credentials_1.createCredentialBroker)(this.config.credentials, this.credentialDeps);
-        const enforceMinVersion = (response) => {
-          (0, version_check_1.checkResponseMinVersion)({
-            response,
+        const subscribeLogger = {
+          debug: (msg, meta) => logger.debug(msg, meta),
+          info: (msg, meta) => logger.info(msg, meta),
+          warn: (msg, meta) => logger.warn(msg, meta),
+          error: (msg, meta) => logger.error(msg, meta)
+        };
+        let running = false;
+        let latestSeen = null;
+        let floorRising = false;
+        const onBackendResponse = (response) => {
+          latestSeen = (0, version_check_1.readResponseLatestVersion)(response) ?? latestSeen;
+          if (!running) {
+            (0, version_check_1.checkResponseMinVersion)({
+              response,
+              currentVersion: this.brand.product.version,
+              packageName: this.brand.product.packageName
+            });
+            return;
+          }
+          if (floorRising)
+            return;
+          const floor = response.headers.get(version_check_1.MIN_VERSION_HEADER);
+          if (!floor || (0, version_check_1.compareSemver)(this.brand.product.version, floor) >= 0)
+            return;
+          floorRising = true;
+          void (0, self_update_1.updateForFloor)({
+            productTitle: this.brand.product.title,
+            packageName: this.brand.product.packageName,
             currentVersion: this.brand.product.version,
-            packageName: this.brand.product.packageName
-          });
+            minVersion: floor,
+            latestVersion: latestSeen,
+            // A `credentials` block is what makes a deployment hosted (ADR 0027).
+            hosted: this.config.credentials !== void 0,
+            logger: subscribeLogger,
+            hooks: {
+              drain: () => this.subscription?.stop() ?? Promise.resolve(),
+              exit: (err) => this.lifetime.reject(err)
+            }
+          }).catch((err) => this.lifetime.reject(err));
         };
-        const auth = await resolveAuth(this.brand, this.config, paths.configFile, enforceMinVersion);
+        let auth;
+        try {
+          auth = await resolveAuth(this.brand, this.config, paths.configFile, onBackendResponse, {
+            signal: this.stopping.signal,
+            logger: subscribeLogger
+          });
+        } catch (err) {
+          if (this.stopping.signal.aborted)
+            return;
+          throw err;
+        }
         const jobsClient = new jobs_1.JobsClient({
           baseUrl: this.config.auth.jobsApiUrl,
           apiKey: auth.kind === "apiKey" ? auth.apiKey : void 0,
           getAccessToken: auth.kind === "tokenProvider" ? auth.getToken : void 0,
-          onResponse: enforceMinVersion
+          onResponse: onBackendResponse
         });
         const registry = new registry_1.ExecutorRegistry(this.brand.executorAllowlist);
         registerBuiltInExecutors(registry, this.brand.executorAllowlist);
@@ -25137,6 +25855,9 @@ var require_shuttle = __commonJS({
             response = await executor.execute(dispatch, signal, executionCtx);
           } catch (err) {
             const reason = `executor failed: ${err instanceof Error ? err.message : String(err)}`;
+            if (this.broker === null && (0, types_1.isExecutorEnvironmentError)(err)) {
+              this.pauseForEnvironment(executor, err, subscribeLogger);
+            }
             await observerChain.notify({ kind: "attendance.closed", jobId, attendanceId, status: "failed", reason, totalDurationMs: Date.now() - startedAt }, onObserverError);
             return { status: "failed", reason };
           } finally {
@@ -25168,12 +25889,6 @@ var require_shuttle = __commonJS({
           return { status: "completed", outputs };
         };
         const pools = this.config.pools.map((p) => p.id ? { id: p.id } : { name: p.name });
-        const subscribeLogger = {
-          debug: (msg, meta) => logger.debug(msg, meta),
-          info: (msg, meta) => logger.info(msg, meta),
-          warn: (msg, meta) => logger.warn(msg, meta),
-          error: (msg, meta) => logger.error(msg, meta)
-        };
         const attemptedUpgrades = /* @__PURE__ */ new Set();
         this.subscription = (0, jobs_1.subscribe)({
           jobsClient,
@@ -25206,6 +25921,8 @@ var require_shuttle = __commonJS({
               });
               return;
             }
+            if (floorRising)
+              return;
             const directive = (0, self_update_1.readUpgradeDirective)(directives, this.brand.product.version, attemptedUpgrades);
             if (!directive)
               return;
@@ -25216,15 +25933,33 @@ var require_shuttle = __commonJS({
               logger: subscribeLogger,
               hooks: {
                 stopLoop: () => this.subscription?.stop() ?? Promise.resolve(),
-                restartLoop: () => this.subscription?.start() ?? Promise.resolve()
+                // The restarted session's outcome needs the same watch as the
+                // first one's, or a fatal after an upgrade that failed to install
+                // would end nobody's wait. A restart that cannot register ends the
+                // run the same way.
+                restartLoop: () => (this.subscription?.start() ?? Promise.resolve()).then(() => this.watchSession()).catch((err) => this.lifetime.reject(err))
               }
             });
           },
+          // The two failures that end a run with their own exit code and banner:
+          // a refused credential (exit 3) and a below-floor build (exit 2),
+          // matched by name as bin.ts's typed exits are. In-flight jobs are
+          // aborted and their results not submitted (see subscribe's isFatal):
+          // with the credential refused nothing can be submitted anyway, and the
+          // claims lapse back to the pool for another Sifter. A floor rise
+          // normally arrives through onBackendResponse, which drains instead; one
+          // reaching this predicate came from somewhere unexpected and is
+          // treated as the refusal it is.
+          isFatal: typed_exit_1.isTypedExit,
           logger: subscribeLogger,
           pollIntervalMs: this.config.polling.intervalMs,
           maxConcurrency: this.config.concurrency.maxJobs
         });
         await this.subscription.start();
+        if (this.stopping.signal.aborted)
+          return;
+        this.watchSession();
+        running = true;
         logger.info(`${this.brand.product.title} running`, {
           profile: this.profile,
           pools: pools.length,
@@ -25233,13 +25968,72 @@ var require_shuttle = __commonJS({
           observers: observers.length
         });
       }
+      /**
+       * The run's outcome: resolves after `stop()`, rejects with the typed error
+       * that ended it otherwise (a refused credential, or a floor this build could
+       * not update past). `run` awaits this after `start()`, so those errors reach
+       * the whitelabel's exit codes and banners instead of dying in the loop.
+       */
+      done() {
+        return this.lifetime.promise;
+      }
       async stop() {
         const logger = (0, logger_1.getLogger)();
         logger.info(`${this.brand.product.title} stopping...`);
+        this.stopping.abort();
         if (this.subscription) {
           await this.subscription.stop();
         }
         logger.info(`${this.brand.product.title} stopped`);
+        this.lifetime.resolve();
+      }
+      /** Forward the current subscribe session's fatal, if one ends it, to the run's outcome. */
+      watchSession() {
+        this.subscription?.done().catch((err) => this.lifetime.reject(err));
+      }
+      /**
+       * Stop claiming because the executor says this machine cannot run jobs,
+       * and keep checking until it can. One warning says why and what to do; the
+       * re-checks stay at debug; one line says when claiming resumes. Idempotent:
+       * a second failing job while paused (maxJobs > 1) changes nothing.
+       */
+      pauseForEnvironment(executor, err, logger) {
+        if (this.environmentPausedAt !== null || !this.subscription)
+          return;
+        this.environmentPausedAt = Date.now();
+        this.subscription.pause(ENVIRONMENT_HOLD);
+        logger.warn(`Claiming paused: ${executor.capability.id} cannot run jobs on this machine (${err.message}). To fix it, ${err.remedy}. The ${this.brand.product.title} checks again on its own and resumes claiming when it works.`);
+        void this.recheckEnvironment(executor, logger);
+      }
+      async recheckEnvironment(executor, logger) {
+        const signal = this.stopping.signal;
+        let delay = this.environmentRecheck.initialMs;
+        for (; ; ) {
+          await abortableSleep(delay, signal);
+          if (signal.aborted)
+            return;
+          let readiness;
+          try {
+            readiness = executor.checkReadiness ? await executor.checkReadiness(signal) : { ready: true };
+          } catch (err) {
+            readiness = { ready: false, reason: err instanceof Error ? err.message : String(err) };
+          }
+          if (signal.aborted)
+            return;
+          if (readiness.ready) {
+            const pausedFor = formatDuration(Date.now() - (this.environmentPausedAt ?? Date.now()));
+            this.environmentPausedAt = null;
+            this.subscription?.resume(ENVIRONMENT_HOLD);
+            logger.info(`${executor.capability.id} can run jobs again; claiming resumed after ${pausedFor} paused.`);
+            return;
+          }
+          delay = Math.min(delay * 2, this.environmentRecheck.maxMs);
+          logger.debug?.("executor still cannot run jobs", {
+            executor: executor.capability.id,
+            reason: readiness.reason,
+            nextCheckIn: formatDuration(delay)
+          });
+        }
       }
     };
     exports2.Shuttle = Shuttle;
@@ -25267,7 +26061,7 @@ var require_shuttle = __commonJS({
         }
       }
     }
-    async function resolveAuth(brand, config, pairingFile, onResponse) {
+    async function resolveAuth(brand, config, pairingFile, onResponse, options = {}) {
       const store = new store_1.PairingConfigStore(pairingFile);
       if (store.exists()) {
         const pairing = store.read();
@@ -25277,7 +26071,7 @@ var require_shuttle = __commonJS({
           clientSecret: pairing.credentials.clientSecret,
           onResponse
         });
-        const token = await tokens.getToken();
+        const token = await mintWaitingOutKeep(() => tokens.getToken(), brand, options);
         if (token) {
           return {
             kind: "tokenProvider",
@@ -25290,6 +26084,48 @@ var require_shuttle = __commonJS({
       }
       throw new Error(`No credentials available. Run \`${brand.product.cliBinary} init\` to pair, or set auth.apiKey in your config.`);
     }
+    async function mintWaitingOutKeep(mint, brand, options) {
+      const maxDelay = options.retryMaxMs ?? KEEP_RETRY_MAX_MS;
+      const initialDelay = options.retryInitialMs ?? KEEP_RETRY_INITIAL_MS;
+      let delay = initialDelay;
+      let waiting = null;
+      for (; ; ) {
+        let pause;
+        try {
+          const token = await mint();
+          if (waiting?.kind === "unavailable") {
+            options.logger?.info(`Keep is reachable again after ${formatDuration(Date.now() - waiting.since)}`);
+          } else if (waiting?.kind === "rate-limited") {
+            options.logger?.info(`Keep issued a token; the rate limit lifted after ${formatDuration(Date.now() - waiting.since)}`);
+          }
+          return token;
+        } catch (err) {
+          if (isKeepRateLimited(err)) {
+            if (waiting?.kind !== "rate-limited") {
+              waiting = { kind: "rate-limited", since: Date.now() };
+              options.logger?.warn(`Keep is rate limiting this ${brand.product.title}'s token exchange (${err.host ?? "Keep"} answered 429: ${err.reason ?? err.message}). The credentials are not in question; the ${brand.product.title} will wait and ask again at ${formatInstant(err.retryAt)} (in ${formatDuration(err.retryAfterMs)}), and start when Keep issues a token.`);
+            }
+            pause = err.retryAfterMs;
+            delay = initialDelay;
+          } else if (isKeepUnavailable(err)) {
+            if (waiting?.kind !== "unavailable") {
+              waiting = { kind: "unavailable", since: Date.now() };
+              const e = err;
+              const what = typeof e.statusCode === "number" ? `${e.host ?? "Keep"} answered ${e.statusCode}` : `${e.host ?? "Keep"} did not answer`;
+              options.logger?.warn(`Keep is unavailable (${what}). This is typical during a deployment window; the ${brand.product.title} will wait for it and start when it answers.`);
+            }
+            pause = delay;
+            delay = Math.min(delay * 2, maxDelay);
+          } else {
+            throw err;
+          }
+        }
+        await abortableSleep(pause, options.signal);
+        if (options.signal?.aborted) {
+          throw options.signal.reason instanceof Error ? options.signal.reason : new Error("stopped while waiting for Keep");
+        }
+      }
+    }
   }
 });
 
@@ -25361,8 +26197,9 @@ var require_run = __commonJS({
             process.exit(preflight_1.PREFLIGHT_EXIT_CODE);
           }
           const shuttle = new shuttle_1.Shuttle({ brand, config, profile });
-          await shuttle.start();
           (0, shutdown_1.setupShutdownHandler)(() => shuttle.stop());
+          await shuttle.start();
+          await shuttle.done();
         } catch (err) {
           if ((0, typed_exit_1.isTypedExit)(err))
             throw err;
@@ -25714,8 +26551,8 @@ var require_dist5 = __commonJS({
   "../../packages/shuttle/dist/index.js"(exports2) {
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
-    exports2.pair = exports2.scaffoldedConfigPath = exports2.planScaffold = exports2.DEFAULT_REFUSAL_MESSAGE = exports2.DEFAULT_MONTHLY_PERIOD = exports2.DEFAULT_DAILY_PERIOD = exports2.SUBSTRATE_BRAND = exports2.verificationJson = exports2.resolveEnvironment = exports2.renderVerificationLine = exports2.renderEnvironmentReport = exports2.isWorthReporting = exports2.hostOf = exports2.environmentReportJson = exports2.applyEnvironment = exports2.renderTemplate = exports2.expandHome = exports2.resolvePaths = exports2.SpendStore = exports2.AuditLogStore = exports2.createSpendTrackerObserver = exports2.createAuditLogObserver = exports2.createLoggerObserver = exports2.SpendCapExceeded = exports2.ObserverChain = exports2.createCustomScriptExecutor = exports2.createWebhookExecutor = exports2.createHttpApiExecutor = exports2.createClaudeCodeExecutor = exports2.ExecutorRegistry = exports2.AgentCredentialRevokedError = exports2.runPreflight = exports2.renderLines = exports2.renderJson = exports2.printReport = exports2.hasFailure = exports2.createProbes = exports2.checksFor = exports2.PREFLIGHT_FLOORS = exports2.PREFLIGHT_EXIT_CODE = exports2.CHECKS = exports2.readResponseLatestVersion = exports2.checkResponseMinVersion = exports2.compareSemver = exports2.UpgradeRequiredError = exports2.LATEST_VERSION_HEADER = exports2.MIN_VERSION_HEADER = exports2.loadConfig = exports2.Shuttle = exports2.createCli = void 0;
-    exports2.revokePairing = exports2.listPairings = exports2.PairingConfigStore = void 0;
+    exports2.scaffoldedConfigPath = exports2.planScaffold = exports2.DEFAULT_REFUSAL_MESSAGE = exports2.DEFAULT_MONTHLY_PERIOD = exports2.DEFAULT_DAILY_PERIOD = exports2.SUBSTRATE_BRAND = exports2.verificationJson = exports2.resolveEnvironment = exports2.renderVerificationLine = exports2.renderEnvironmentReport = exports2.isWorthReporting = exports2.hostOf = exports2.environmentReportJson = exports2.applyEnvironment = exports2.renderTemplate = exports2.expandHome = exports2.resolvePaths = exports2.SpendStore = exports2.AuditLogStore = exports2.createSpendTrackerObserver = exports2.createAuditLogObserver = exports2.createLoggerObserver = exports2.SpendCapExceeded = exports2.ObserverChain = exports2.createCustomScriptExecutor = exports2.createWebhookExecutor = exports2.createHttpApiExecutor = exports2.createClaudeCodeExecutor = exports2.ExecutorEnvironmentError = exports2.ExecutorRegistry = exports2.AgentCredentialRevokedError = exports2.runPreflight = exports2.renderLines = exports2.renderJson = exports2.printReport = exports2.hasFailure = exports2.createProbes = exports2.checksFor = exports2.PREFLIGHT_FLOORS = exports2.PREFLIGHT_EXIT_CODE = exports2.CHECKS = exports2.readResponseLatestVersion = exports2.checkResponseMinVersion = exports2.compareSemver = exports2.UpgradeRequiredError = exports2.LATEST_VERSION_HEADER = exports2.MIN_VERSION_HEADER = exports2.loadConfig = exports2.Shuttle = exports2.createCli = void 0;
+    exports2.revokePairing = exports2.listPairings = exports2.PairingConfigStore = exports2.pair = void 0;
     var cli_1 = require_cli();
     Object.defineProperty(exports2, "createCli", { enumerable: true, get: function() {
       return cli_1.createCli;
@@ -25786,6 +26623,10 @@ var require_dist5 = __commonJS({
     Object.defineProperty(exports2, "ExecutorRegistry", { enumerable: true, get: function() {
       return registry_1.ExecutorRegistry;
     } });
+    var types_1 = require_types2();
+    Object.defineProperty(exports2, "ExecutorEnvironmentError", { enumerable: true, get: function() {
+      return types_1.ExecutorEnvironmentError;
+    } });
     var claude_code_1 = require_claude_code();
     Object.defineProperty(exports2, "createClaudeCodeExecutor", { enumerable: true, get: function() {
       return claude_code_1.createClaudeCodeExecutor;
@@ -25910,7 +26751,7 @@ var import_path = require("path");
 var import_promises = require("fs/promises");
 var import_yaml = __toESM(require_dist3());
 var import_shuttle = __toESM(require_dist5());
-var buildVersion = true ? "0.30.8" : pkg.version;
+var buildVersion = true ? "0.30.10" : pkg.version;
 var sifterBrand = {
   product: {
     id: "sifter",