@humwick/runner 0.130.1 → 0.130.2

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@humwick/runner",
-  "version": "0.130.1",
+  "version": "0.130.2",
   "description": "Unified provider lifecycle runner for Humwick",
   "type": "module",
   "bin": {
-    "claude-relay": "src/index.ts",
-    "codex-relay": "src/index.ts",
-    "opencode-relay": "src/index.ts",
-    "claude-humwick": "src/index.ts",
-    "codex-humwick": "src/index.ts",
-    "opencode-humwick": "src/index.ts"
+    "claude-relay": "src/bin/claude.ts",
+    "codex-relay": "src/bin/codex.ts",
+    "opencode-relay": "src/bin/opencode.ts",
+    "claude-humwick": "src/bin/claude.ts",
+    "codex-humwick": "src/bin/codex.ts",
+    "opencode-humwick": "src/bin/opencode.ts"
   },
   "files": [
     "src/**/*.ts",
@@ -29,12 +29,11 @@
     "directory": "runner"
   },
   "dependencies": {
-    "@humwick/offload": "0.0.0",
-    "@humwick/providers": "0.104.7",
-    "@humwick/sdk": "0.2.136",
+    "@humwick/offload": "0.130.2",
+    "@humwick/providers": "0.104.8",
+    "@humwick/sdk": "0.2.137",
     "callmux": "0.25.0",
-    "unbash": "6.0.0",
-    "p-queue": "^9.3.3"
+    "unbash": "6.0.0"
   },
   "devDependencies": {
     "@types/bun": "1.4.2",
@@ -42,8 +41,5 @@
   },
   "engines": {
     "bun": ">=1.4.4"
-  },
-  "bundleDependencies": [
-    "@humwick/offload"
-  ]
+  }
 }

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-relay-runner",
   "description": "Thin Humwick runner bridge for Claude Code",
-  "version": "0.130.1",
+  "version": "0.130.2",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/plugins/claude/hooks/gate-run-guard.provisioned.mjs

@@ -260,6 +260,9 @@ function classifyGateRun(command, commands = {}) {
   return null;
 }
 
+// sdk/src/types/host.ts
+var HOST_GATE_KINDS = ["land", "iterate", "validation"];
+
 // sdk/src/land-gates.ts
 import { isAbsolute as isAbsolute2, relative as relative2, resolve as resolve3 } from "path";
 
@@ -420,7 +423,34 @@ function cleanLandGatesConfigFull(value, worktreePath) {
   const requirements = cleanLandGateRequirements(value);
   const cd = value.cd === true;
   const scope = cleanLandGateScope(value);
-  return { gates, ...deliveryPolicy, ...iterate ? { iterate } : {}, ...cd ? { cd } : {}, ...placement ? { placement } : {}, ...requirements ? { requirements } : {}, ...scope };
+  const resources = cleanGateResources(value);
+  return { gates, ...resources ? { resources } : {}, ...deliveryPolicy, ...iterate ? { iterate } : {}, ...cd ? { cd } : {}, ...placement ? { placement } : {}, ...requirements ? { requirements } : {}, ...scope };
+}
+function cleanGateResources(value) {
+  if (!isRecord(value))
+    throw new ValidationError("land-gates config must be an object");
+  if (value.resources === undefined)
+    return;
+  if (!isRecord(value.resources))
+    throw new ValidationError("resources must be an object");
+  const resources = {};
+  for (const [kind, request] of Object.entries(value.resources)) {
+    if (!HOST_GATE_KINDS.includes(kind))
+      throw new ValidationError(`resources: unknown gate kind '${kind}'; use land, iterate or validation`);
+    if (!isRecord(request))
+      throw new ValidationError(`resources.${kind} must be an object`);
+    const parsed = {};
+    for (const [key, n] of Object.entries(request)) {
+      if (key !== "cpus" && key !== "memoryBytes")
+        throw new ValidationError(`resources.${kind}: unknown field '${key}'`);
+      if (typeof n !== "number" || !Number.isFinite(n) || n <= 0 || key === "memoryBytes" && !Number.isSafeInteger(n)) {
+        throw new ValidationError(`resources.${kind}.${key} must be a positive ${key === "memoryBytes" ? "safe integer" : "finite number"}`);
+      }
+      parsed[key] = n;
+    }
+    resources[kind] = parsed;
+  }
+  return resources;
 }
 function cleanDeliveryGatePolicy(value) {
   if (!isRecord(value))

package/src/adapters/claude-effort.ts

@@ -1,5 +1,5 @@
 import { relayEnv, writeChildEnv } from "@humwick/sdk/env";
-import { findProviderCatalog, findProviderCatalogModel, type SpawnProvider } from "@humwick/sdk";
+import { type SpawnProvider } from "@humwick/sdk";
 import { tmuxCommand, tmuxHasSession } from "@humwick/sdk/tmux-utils";
 import type { ManagedProcess, RunnerSpawnConfig } from "../adapter";
 import { effortSwitchEnabledFromEnv } from "../config";
@@ -24,9 +24,7 @@ export function claudeEffortLaunch(effort: string | undefined, inheritedEnv: Rec
 
 /** Persistent transports can switch effort. Host-base `/effort` would save into the human's own settings. */
 export function claudeEffortSwitchMeta(provider: SpawnProvider, config: RunnerSpawnConfig, oneShot: boolean): { effortSwitch?: true } {
-  const catalog = findProviderCatalog(provider);
-  const model = catalog && findProviderCatalogModel(catalog, config.model ?? catalog.defaultModel);
-  return effortSwitchEnabledFromEnv() && !oneShot && providerHomePathFor(provider, config) && model?.efforts.length ? { effortSwitch: true } : {};
+  return effortSwitchEnabledFromEnv() && !oneShot && providerHomePathFor(provider, config) && (config.modelRecord?.efforts?.length || config.effort) ? { effortSwitch: true } : {};
 }
 
 interface ClaudeEffortOutcome { applied?: string; message: string }

package/src/adapters/codex-launch-config.ts

@@ -10,6 +10,7 @@ import { hostProviderDefaultArgs } from "../host-asset-plan";
 import { bundledSkillConfigArgs } from "../launch-assembly";
 import { codexRetiredMcpConfigArgs } from "./codex-effective-config";
 import { codexWebToolsConfigArgs } from "../web-tools";
+import type { ResolvedModelRecord } from "@humwick/sdk/provider-catalog";
 import { tomlString } from "../relay-mcp";
 
 export const DEFAULT_CODEX_TOOL_OUTPUT_TOKEN_LIMIT = 12_000;
@@ -31,14 +32,12 @@ export const DEFAULT_CODEX_TOOL_OUTPUT_TOKEN_LIMIT = 12_000;
 // advertise longer polls to the model (#2776): agents are steered to end the turn and take the wake.
 const CODEX_BACKGROUND_TERMINAL_MAX_TIMEOUT_MS = 900000;
 
-export function codexModelConfigArgs(model?: string, effort?: string): string[] {
+export function codexModelConfigArgs(model?: string, effort?: string, record?: ResolvedModelRecord): string[] {
   const args: string[] = [];
   if (model) args.push("-c", `model=${tomlString(model)}`);
   if (effort) args.push("-c", `model_reasoning_effort=${tomlString(effort)}`);
-  // The catalog alias `astra` resolves to this provider model before runner launch.
-  if (model === "gpt-6-astra") {
-    args.push("-c", "model_context_window=1000000", "-c", "model_auto_compact_token_limit=272000");
-  }
+  if (record?.contextWindowTokens) args.push("-c", `model_context_window=${record.contextWindowTokens}`);
+  if (record?.contextWindowTokens && record.contextThreshold) args.push("-c", `model_auto_compact_token_limit=${Math.floor(record.contextWindowTokens * record.contextThreshold.selfCompactUtilization)}`);
   return args;
 }
 

package/src/adapters/codex.ts

@@ -688,7 +688,7 @@ export class CodexAdapter implements ProviderAdapter {
       ? [
         "app-server",
         ...codexAppServerConfigArgs(defaultArgs, config.providerArgs),
-        ...codexModelConfigArgs(config.model, config.effort),
+        ...codexModelConfigArgs(config.model, config.effort, config.modelRecord),
         ...codexApprovalConfigArgs(config.approvalMode),
         ...codexToolOutputTokenLimitConfigArgs(config), ...codexHarnessConfigArgs(config), ...codexWebToolsConfigArgs(config),
         ...assembled.args,

package/src/adapters/opencode-provider.ts

@@ -35,14 +35,6 @@ export function openCodeBackendApiKeyEnvVar(backendID: string): string | undefin
   return OPENCODE_STATIC_BACKENDS[backendID]?.envVar;
 }
 
-/** Catalog alias → provider model (older runner protocols carry the alias without a record). */
-function openCodeAliasResolved(model: string | undefined, manifest: ProviderManifest, provider: string): string {
-  const alias = model?.trim() || manifest.catalog.defaultModel;
-  const raw = manifest.catalog.models.find((entry) => entry.alias === alias)?.providerModel || alias;
-  if (!raw) throw new Error(`OpenCode provider ${provider} has no default model.`);
-  return raw;
-}
-
 /**
  * #2659 — the launch model: THE one normalization of a spawn's model through the shared seam
  * (`resolveOpenCodeModelId`). A server-threaded record's qualified name wins over the alias.
@@ -51,8 +43,9 @@ function openCodeAliasResolved(model: string | undefined, manifest: ProviderMani
  * default-backend model id.
  */
 export function openCodeLaunchModel(model: string | undefined, provider = "opencode", record?: ResolvedModelRecord, registry?: OpenCodeModelRegistry): OpenCodeModelId {
-  const { manifest, backend } = openCodeBackend(provider);
-  const input = record?.qualifiedModel || openCodeAliasResolved(model, manifest, provider);
+  const { backend } = openCodeBackend(provider);
+  const input = record?.qualifiedModel || model?.trim();
+  if (!input) throw new Error(`OpenCode provider ${provider} requires a hub-resolved model.`);
   return resolveOpenCodeModelId(input, backend.opencodeProviderID, registry);
 }
 
@@ -111,18 +104,10 @@ export function openCodeCustomBackendIDs(): string[] {
   return getAllManifests().flatMap((entry) => entry.opencode && OPENCODE_STATIC_BACKENDS[entry.opencode.opencodeProviderID]?.custom ? [entry.opencode.opencodeProviderID] : []);
 }
 
-/** Read the current backend's declared context window from the manifest catalog. */
-export function openCodeContextWindowTokens(model: string | undefined, provider = "opencode", record?: ResolvedModelRecord): number | undefined {
-  // #2599 — precedence payload > manifest > undefined: the record's window wins; a malformed
-  // record window never reaches here (the shared parser drops it), so no second gate is needed.
-  if (typeof record?.contextWindowTokens === "number" && Number.isFinite(record.contextWindowTokens) && record.contextWindowTokens > 0) {
-    openCodeBackend(provider); // keep the unknown-provider hard error on the record path too.
-    return record.contextWindowTokens;
-  }
-  const { manifest } = openCodeBackend(provider);
-  const { modelID } = openCodeLaunchModel(model, provider);
-  const value = manifest.catalog.models.find((entry) => entry.alias === modelID || entry.providerModel === modelID)?.limits?.contextWindowTokens?.value;
-  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+/** Context limits come from the hub-resolved launch record. */
+export function openCodeContextWindowTokens(_model: string | undefined, provider = "opencode", record?: ResolvedModelRecord): number | undefined {
+  openCodeBackend(provider);
+  return record?.contextWindowTokens;
 }
 
 /**

package/src/adapters/opencode.ts

@@ -1505,7 +1505,7 @@ export class OpenCodeAdapter implements ProviderAdapter {
       const tokens = countTokens(info?.tokens);
       const sessionUnattributable = Boolean(activeSessionId && sessionID !== activeSessionId);
       if (process && role === "assistant" && tokens !== undefined && !sessionUnattributable) {
-        const model = stringValue(process.meta?.model) ?? openCodeQualifiedModel(undefined, this.provider);
+        const model = stringValue(process.meta?.model);
         this.reportContextUsage(process, model, tokens);
       }
       // #2484 — same door, reused for the spine report: model/createdAt prefer the message's
@@ -1516,7 +1516,7 @@ export class OpenCodeAdapter implements ProviderAdapter {
         scheduleOpenCodeTokenUsage(this.tokenUsagePoster, {
           provider: this.provider,
           sessionId: activeSessionId ?? sessionID,
-          model: openCodeMessageModel(info) ?? stringValue(process.meta?.model) ?? openCodeQualifiedModel(undefined, this.provider),
+          model: openCodeMessageModel(info) ?? stringValue(process.meta?.model),
           messageId: id,
           tokens: info?.tokens,
           createdAt: openCodeMessageObservedAt(info),
@@ -1832,8 +1832,8 @@ export class OpenCodeAdapter implements ProviderAdapter {
       for (const relayContextInput = prepareOpenCodeRelayContext(process, text);;) {
         const client = process.meta?.client as OpenCodeClient | undefined;
         const sessionId = stringValue(process.meta?.sessionId);
-        const model = stringValue(process.meta?.model) ?? openCodeQualifiedModel(undefined, this.provider);
-        if (!client || !sessionId) throw new Error("OpenCode session is not ready");
+        const model = stringValue(process.meta?.model);
+        if (!client || !sessionId || !model) throw new Error("OpenCode session is not ready with a hub-resolved model");
         // #2397 round 5 review (LOW-2) — raised only once we're actually about to run an attempt
         // (past the guard above), so a "session not ready" throw never emits a close for a turn
         // that never started (never emitted its own busy edge below).

package/src/agent-runner/credentials.ts

@@ -14,13 +14,26 @@ interface CredentialsDeps {
   publishRenewalFailure(): void;
   logRunnerDiagnostic(message: string): void;
   reportBackgroundRejection(scope: string, status: string, title: string, error: unknown): void;
+  /** Recovery gave up: the runner must exit so Relay sees a terminal failure, not a mint loop (#3775). */
+  onTerminalAuthFailure(reason: string): void;
 }
 
 const TOKEN_RENEW_LOG_INTERVAL_MS = 5 * 60 * 1000;
 const TOKEN_RENEW_RETRY_MS = 60_000;
-// Debounce reactive token recovery so a burst of 401-ing calls in the same window
-// triggers a single re-mint attempt, not one per failing request.
-const REACTIVE_TOKEN_RECOVERY_DEBOUNCE_MS = 10_000;
+// #3775 — a successful mint does not prove the hub accepts the runner: an orphaned runner kept
+// getting 401 on its fresh token and re-minted ~2/s. Auth recoveries back off (1 s doubling to
+// 5 min, jittered) and stop after a bounded count; only a quiet spell resets the count.
+export const AUTH_RECOVERY_MAX_ATTEMPTS = 10;
+const AUTH_RECOVERY_BASE_MS = 1_000;
+const AUTH_RECOVERY_MAX_DELAY_MS = 5 * 60_000;
+const AUTH_RECOVERY_QUIET_RESET_MS = 30 * 60_000;
+
+/** Delay before auth recovery `attempt` (0-based): the first heals at once, later ones back off with equal jitter. */
+export function authRecoveryDelayMs(attempt: number, random: () => number = Math.random): number {
+  if (attempt <= 0) return 0;
+  const ceiling = Math.min(AUTH_RECOVERY_MAX_DELAY_MS, AUTH_RECOVERY_BASE_MS * 2 ** (attempt - 1));
+  return Math.round(ceiling / 2 + random() * (ceiling / 2));
+}
 
 export class Credentials {
   private currentToken?: string;
@@ -30,7 +43,10 @@ export class Credentials {
   private tokenRenewTimer?: Timer;
   private readonly tokenRotation = new TokenRotation();
   private tokenRenewLastLog?: { key: string; at: number };
-  private reactiveTokenRecoveryAt?: number;
+  private authRecoveryAttempts = 0;
+  private authRecoveryLastAt?: number;
+  private authRecoveryTimer?: Timer;
+  private authRecoveryExhausted = false;
 
   constructor(options: { token?: string; tokenJti?: string; tokenProfileId?: string; tokenExpiresAt?: number }, private readonly deps: CredentialsDeps) {
     this.currentToken = options.token;
@@ -47,6 +63,8 @@ export class Credentials {
   stop(): void {
     if (this.tokenRenewTimer) clearTimeout(this.tokenRenewTimer);
     this.tokenRenewTimer = undefined;
+    if (this.authRecoveryTimer) clearTimeout(this.authRecoveryTimer);
+    this.authRecoveryTimer = undefined;
   }
 
   // Timer/edge callers cannot await renewal; report an escaping rejection so it cannot
@@ -55,22 +73,35 @@ export class Credentials {
     void this.renewRuntimeToken().catch((error) => this.deps.reportBackgroundRejection("runtime token renewal", "runtime-token-renewal-failed", "Runtime token renewal aborted", error));
   }
 
-  // The TTL timer cannot detect revocation: recover on auth failure, coalescing a burst.
+  // The TTL timer cannot detect revocation: recover on auth failure, coalescing a burst into the
+  // one recovery in flight or scheduled.
   // Orchestrator re-mint heals stale/expired tokens but preserves hard revocation (#484).
   recoverRuntimeTokenAfterAuthFailure(source: string): void {
-    if (this.deps.isStopped() || this.tokenRotation.inFlight) return;
+    if (this.deps.isStopped() || this.authRecoveryExhausted || this.tokenRotation.inFlight || this.authRecoveryTimer) return;
     if (!this.isRuntimeTokenRenewable() && !this.canRemintViaOrchestrator()) return;
     const now = Date.now();
-    if (this.reactiveTokenRecoveryAt && now - this.reactiveTokenRecoveryAt < REACTIVE_TOKEN_RECOVERY_DEBOUNCE_MS) return;
-    this.reactiveTokenRecoveryAt = now;
-    this.deps.logRunnerDiagnostic(`[runner] relay auth failure on ${source}; recovering runtime token`);
-    this.renewRuntimeTokenInBackground();
+    if (this.authRecoveryLastAt !== undefined && now - this.authRecoveryLastAt >= AUTH_RECOVERY_QUIET_RESET_MS) this.authRecoveryAttempts = 0;
+    if (this.authRecoveryAttempts >= AUTH_RECOVERY_MAX_ATTEMPTS) {
+      this.authRecoveryExhausted = true;
+      this.stop();
+      this.deps.onTerminalAuthFailure(`runtime-token-auth-failed: relay still rejects the runner (last on ${source}) after ${AUTH_RECOVERY_MAX_ATTEMPTS} token recoveries`);
+      return;
+    }
+    const delayMs = authRecoveryDelayMs(this.authRecoveryAttempts);
+    this.authRecoveryAttempts += 1;
+    this.authRecoveryLastAt = now;
+    this.deps.logRunnerDiagnostic(`[runner] relay auth failure on ${source}; recovering runtime token (attempt ${this.authRecoveryAttempts}/${AUTH_RECOVERY_MAX_ATTEMPTS}${delayMs ? ` in ${Math.ceil(delayMs / 1000)}s` : ""})`);
+    if (!delayMs) return this.renewRuntimeTokenInBackground();
+    this.authRecoveryTimer = setTimeout(() => {
+      this.authRecoveryTimer = undefined;
+      this.renewRuntimeTokenInBackground();
+    }, delayMs);
   }
 
   scheduleRuntimeTokenRenewal(delayMs?: number): void {
     if (this.tokenRenewTimer) clearTimeout(this.tokenRenewTimer);
     this.tokenRenewTimer = undefined;
-    if (this.deps.isStopped()) return;
+    if (this.deps.isStopped() || this.authRecoveryExhausted) return;
     const canSelfRenew = this.isRuntimeTokenRenewable();
     const canRemint = this.canRemintViaOrchestrator();
     // Keep the renewal clock ticking as long as the session can recover its token
@@ -152,7 +183,6 @@ export class Credentials {
     this.currentTokenProfileId = record.profileId ?? this.currentTokenProfileId;
     this.currentTokenExpiresAt = record.expiresAt;
     this.deps.onTokenChanged(token, record);
-    this.reactiveTokenRecoveryAt = undefined;
     this.deps.resumeLivenessAndPublishRotation(status, record.jti);
     this.scheduleRuntimeTokenRenewal();
   }

package/src/agent-runner/inbox.ts

@@ -0,0 +1,27 @@
+import type { Message } from "@humwick/sdk";
+import type { HumwickHttpClient } from "@humwick/sdk/http-client";
+import { isNotificationOnlyInput } from "../inbox-carrier";
+import { logger } from "../logger";
+
+export async function bootstrapUnreadMessages(http: Pick<HumwickHttpClient, "pollMessages">, agentId: string, enqueue: (message: Message) => void): Promise<void> {
+  try {
+    const messages = await http.pollMessages({ for: agentId, unread: true, limit: 100, turnDelivery: true });
+    for (const message of messages) enqueue(message);
+  } catch (error) { logger.error("runner", `inbox bootstrap failed: ${error}`); }
+}
+
+/** Keep startup failure visible to each sender, including mail queued before the check (#3751). */
+export async function reportUnavailableMessages(
+  http: Pick<HumwickHttpClient, "sendMessage" | "markRead">, agentId: string,
+  pending: Map<number, Message>, settled: Set<number>, reason: string,
+): Promise<void> {
+  for (const [id, message] of pending) {
+    try {
+      if (!isNotificationOnlyInput(message)) await http.sendMessage({ from: agentId, to: message.from, replyTo: id,
+        body: reason, idempotencyKey: `provider-startup-${agentId}-${id}`, payload: { kind: "notification" } });
+      await http.markRead(id, agentId);
+      pending.delete(id);
+      settled.add(id);
+    } catch (error) { logger.error("runner", `startup failure reply failed: ${error}`); }
+  }
+}

package/src/agent-runner/lifecycle-milestones.ts

@@ -15,7 +15,6 @@ interface LifecycleMilestoneDeps {
   process(): ManagedProcess | undefined;
   stopAttachmentCacheSweep(): void;
   stopTestRunDedupSweep(): void;
-  stopGateRunLeaseProbe(): void;
   disposeEmptyTurns(): void;
   resetEmptyTurns(): void;
   resetLateClearRecovery(): void;
@@ -92,7 +91,6 @@ export class LifecycleMilestones {
   private backgroundStopped(): void {
     this.deps.stopAttachmentCacheSweep();
     this.deps.stopTestRunDedupSweep();
-    this.deps.stopGateRunLeaseProbe();
     // #2389 — before the shutdown await, not after: an escalation or settle timer firing during a
     // graceful provider shutdown would publish a "produced nothing" verdict about a turn the
     // shutdown itself ended.

package/src/bin/claude.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env -S bun --no-env-file
+import { runCli } from "../index";
+
+runCli("claude");

package/src/bin/codex.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env -S bun --no-env-file
+import { runCli } from "../index";
+
+runCli("codex");

package/src/bin/opencode.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env -S bun --no-env-file
+import { runCli } from "../index";
+
+runCli("opencode");

package/src/index.ts

@@ -375,8 +375,9 @@ export function detectApprovalModeFromArgs(provider: string, defaultArgs: string
   return detector ? detector([...defaultArgs, ...providerArgs]) : undefined;
 }
 
-if (import.meta.main) {
-  main().catch((error) => {
+export function runCli(provider?: string): void {
+  const argv = provider ? [...process.argv.slice(0, 2), provider, ...process.argv.slice(2)] : process.argv;
+  main(argv).catch((error) => {
     // A fatal startup failure (e.g. the runner could not register with the relay within the
     // deadline) must exit non-zero, not hang or swallow — the orchestrator's exit detection
     // then reports it and the spawn-parent is notified instead of waiting on a silent zombie.
@@ -384,3 +385,5 @@ if (import.meta.main) {
     exitRunner(1, `runner fatal: ${errMessage(error)}`);
   });
 }
+
+if (import.meta.main) runCli();

package/src/provider-setup.ts

@@ -0,0 +1,34 @@
+import { errMessage } from "@humwick/sdk";
+import { checkProviderAuth } from "@humwick/sdk/provider-probe";
+import { selectProviderConfigEnv } from "@humwick/sdk/child-env";
+import type { ProviderAdapter, ProviderStatusEvent } from "./adapter";
+import { logger } from "./logger";
+import { hostSourcesFor } from "./host-asset-plan";
+
+/** All real adapters share the managed-spawn login check, including replacements (#3751). */
+export function withProviderSetup(adapter: ProviderAdapter): ProviderAdapter {
+  const spawn = adapter.spawn.bind(adapter);
+  adapter.spawn = async (config) => {
+    const env = selectProviderConfigEnv(config.providerConfig.env, hostSourcesFor(config).settings);
+    const auth = await checkProviderAuth(config.provider, undefined, env, config.providerConfig.command);
+    if (!auth.ok) throw new Error(auth.reason);
+    return spawn(config);
+  };
+  return adapter;
+}
+
+export function providerStartupFailure(error: unknown): ProviderStatusEvent {
+  const message = `Provider startup failed: ${errMessage(error)}`;
+  return { status: "error", reason: "provider-turn", providerState: {
+    state: "blocked", terminal: true, reason: "providerSetupRequired", label: "Provider setup required", message,
+    recommendedAction: "Complete the provider login and first-run setup on this host, then restart the runner.",
+  } };
+}
+
+export async function attemptProviderStartup(start: () => Promise<void>, failed: (status: ProviderStatusEvent) => void): Promise<void> {
+  try { await start(); }
+  catch (error) {
+    logger.error("startup", errMessage(error));
+    failed(providerStartupFailure(error));
+  }
+}

package/src/providers.ts

@@ -1,3 +1,4 @@
+import { withProviderSetup } from "./provider-setup";
 import { ClaudeApiAdapter } from "./adapters/claude-api";
 import type { LaunchMode, SpawnProvider } from "@humwick/sdk";
 import { getAllManifests, supportedLaunchModesForProvider } from "@humwick/providers";
@@ -31,5 +32,5 @@ export function createProviderAdapter(provider: SpawnProvider, providerArgs: str
   if (launchMode && !supportedLaunchModesForProvider(provider).includes(launchMode)) {
     throw new Error(`${provider} does not support launchMode=${launchMode}`);
   }
-  return registration.createAdapter(providerArgs, launchMode);
+  return withProviderSetup(registration.createAdapter(providerArgs, launchMode));
 }

package/src/runner-core.ts

@@ -1,3 +1,5 @@
+import { attemptProviderStartup } from "./provider-setup";
+import { bootstrapUnreadMessages, reportUnavailableMessages } from "./agent-runner/inbox";
 import { writeChildEnv } from "@humwick/sdk/env";
 import { normalizeDeliverResult } from "./delivery-result";
 import { TokenUsageReportCoverage } from "./agent-runner/token-usage-coverage";
@@ -34,7 +36,6 @@ import { AttachmentCacheSweep } from "./attachment-cache-sweep";
 import { resolveTestRunRootPid, TEST_RUN_DEDUP_SWEEP_MS, TestRunDedupSweep } from "./test-run-dedup";
 import { cachedGateRunCommandsForCwd } from "./gate-run-config";
 import { AreaMemoryTracker } from "./area-memory";
-import { GateRunLeaseProbe } from "./gate-run-lease-probe";
 import { ClaimTracker } from "./claim-tracker";
 import { ProviderQuotaHarvest } from "./adapters/provider-quota-harvest";
 import { agentShellLaunchEnv } from "./adapters/project-shell";
@@ -224,7 +225,6 @@ export class AgentRunner {
   private livenessReconcileTimer?: Timer;
   private readonly attachmentCacheSweep: AttachmentCacheSweep;
   private readonly testRunDedupSweep: TestRunDedupSweep;
-  private readonly gateRunLeaseProbe: GateRunLeaseProbe;
   private processStartedAt = 0;
   private providerSessionId = crypto.randomUUID();
   // Last transcript path seen this session — used by end-of-session Insights (#184)
@@ -363,7 +363,7 @@ export class AgentRunner {
     });
     this.lifecycleMilestones = new LifecycleMilestones({
       options: this.options, agentId: this.agentId, process: () => this.process,
-      stopAttachmentCacheSweep: () => this.attachmentCacheSweep.stop(), stopTestRunDedupSweep: () => this.testRunDedupSweep.stop(), stopGateRunLeaseProbe: () => this.gateRunLeaseProbe.stop(),
+      stopAttachmentCacheSweep: () => this.attachmentCacheSweep.stop(), stopTestRunDedupSweep: () => this.testRunDedupSweep.stop(),
       disposeEmptyTurns: () => this.emptyTurns.dispose(), resetEmptyTurns: () => this.emptyTurns.reset(), resetLateClearRecovery: () => { this.lateClearRecovery.reset(); this.continuationFence.reset(); },
       clearLifecycleAction: () => this.lifecycle.setLifecycleAction(undefined), setOffline: () => this.claims.setTerminalStatus("offline"), publishStatus: () => this.publishStatus(),
       stopDrainTimer: () => { if (this.drainTimer) clearTimeout(this.drainTimer); this.drainTimer = undefined; }, stopSubmitRecoveryPoll: () => this.stopSubmitRecoveryPoll(),
@@ -409,14 +409,12 @@ export class AgentRunner {
     const sessionProviderPid = () => resolveTestRunRootPid(this.process, (managedProcess) => this.options.adapter.resolveBusyPid?.(managedProcess));
     // #2461 — ancestry alone made this sweep a no-op for `relay_run` gate runs (a disjoint tree
     // under the orchestrator). It now also owns anything env-tagged with this agent's id, classifies
-    // against the repo's CONFIGURED gate commands, and defers to the launch-time lease holder. The
+    // against the repo's CONFIGURED gate commands, and reads live leases during each sweep. The
     // config read is cached for the session — it is a repo file, so re-reading it every 15s for the
-    // agent's whole life buys nothing. All three helpers live in their own leaves.
-    this.gateRunLeaseProbe = new GateRunLeaseProbe(this.agentId, TEST_RUN_DEDUP_SWEEP_MS);
+    // agent's whole life buys nothing.
     this.testRunDedupSweep = new TestRunDedupSweep({
       rootPid: sessionProviderPid, agentId: () => this.agentId,
       gateCommands: () => cachedGateRunCommandsForCwd(this.options.cwd),
-      leaseHolderPid: () => this.gateRunLeaseProbe.pid(),
       protectedPids: () => [process.pid], log: (message) => this.logRunnerDiagnostic(message),
     });
     this.context.configureLogger();
@@ -450,6 +448,7 @@ export class AgentRunner {
       },
       logRunnerDiagnostic: (message) => this.logRunnerDiagnostic(message),
       reportBackgroundRejection: (scope, status, title, error) => this.reportBackgroundRejection(scope, status, title, error),
+      onTerminalAuthFailure: (reason) => { logger.error("runner", `exiting: ${reason}`); this.options.onProviderExit?.(1, reason); },
     });
     const token = this.credentials.current();
     if (token) publishRuntimeTokenForCli(token, this.credentials.expiresAt, (message) => this.logRunnerDiagnostic(message));
@@ -733,16 +732,17 @@ export class AgentRunner {
     this.ensureScratch();
     void sweepRunnerStaleScratch({ listAgents: () => this.http.listAgents(), agentId: this.agentId, cwd: this.options.cwd, fallbackBaseDir: orchestratorBaseDirFromEnv(), log: (message) => this.logRunnerDiagnostic(message) });
     this.scheduleAttachmentCacheSweep();
-    this.adoptProcess(await this.spawnProvider());
-    this.registration.writeRunnerInfoFile();
-    await this.promptCommands.startLaunchSeededTurn();
-    this.publishStatus();
-    await this.promptCommands.deliverInitialPrompt();
+    await attemptProviderStartup(async () => {
+      this.adoptProcess(await this.spawnProvider());
+      this.registration.writeRunnerInfoFile();
+      await this.promptCommands.startLaunchSeededTurn();
+      this.publishStatus();
+      await this.promptCommands.deliverInitialPrompt();
+    }, (status) => this.setProviderStatus(status));
     await this.bootstrapUnreadMessages();
     this.taskClaims.start();
     this.startHttpLiveness();
     this.testRunDedupSweep.start();
-    this.gateRunLeaseProbe.start();
     this.credentials.scheduleRuntimeTokenRenewal();
     this.scheduleDrain();
   }
@@ -790,6 +790,7 @@ export class AgentRunner {
   }
 
   private handleBusRegistered(): void {
+    if (this.process) this.publishStatus();
     void this.nativeSelfResume.reconcile((id) => this.http.request("GET", `/api/commands/${encodeURIComponent(id)}`)).catch((error) => this.sessionLog(`compact settlement reconcile: ${errMessage(error)}`));
     // #2973 — a re-register follows a relay restart (a deploy): re-list so changed tools reach the agent.
     void this.proxy?.refreshTools().catch(() => {}); this.effort.trigger();
@@ -941,14 +942,7 @@ export class AgentRunner {
     this.scheduleDrain();
   }
 
-  private async bootstrapUnreadMessages(): Promise<void> {
-    try {
-      const messages = await this.http.pollMessages({ for: this.agentId, unread: true, limit: 100, turnDelivery: true });
-      for (const message of messages) this.enqueueMessage(message);
-    } catch (error) {
-      logger.error("runner", `inbox bootstrap failed: ${error}`);
-    }
-  }
+  private bootstrapUnreadMessages = () => bootstrapUnreadMessages(this.http, this.agentId, (message) => this.enqueueMessage(message));
 
   private scheduleDrain(delayMs = 0): void {
     if (this.lifecycle.stopped || this.drainTimer || this.deliverySubmitHold || this.submitResendInFlight) return;
@@ -1363,7 +1357,8 @@ export class AgentRunner {
   private async drainMessages(): Promise<void> {
     if (this.lifecycle.stopped || this.delivering || this.deliverySubmitHold || this.submitResendInFlight || this.pendingMessages.size === 0) return;
     if (!this.process) {
-      this.scheduleDrain(500);
+      if (this.terminalFailure) await reportUnavailableMessages(this.http, this.agentId, this.pendingMessages, this.settledMessageIds, this.terminalFailure.message);
+      if (this.pendingMessages.size) this.scheduleDrain(500);
       return;
     }
     this.delivering = true;
@@ -2822,7 +2817,7 @@ export class AgentRunner {
       ?? (activeWork.length === 0 ? this.emptyTurns.providerState() ?? null : null);
     const published = this.publishRunnerStatus({
       agentStatus,
-      ready: agentStatus !== "offline" && !this.lifecycle.stopped && !teardownLifecycle && !this.startupPaneDialog && !this.deliverySubmitHold,
+      ready: Boolean(this.process) && agentStatus !== "offline" && !this.lifecycle.stopped && !teardownLifecycle && !this.startupPaneDialog && !this.deliverySubmitHold,
       meta: {
         ...runnerIdentityMeta(this.options, { tmuxSession: providerTerminalSession(this.process), tmuxSocket: providerTerminalSocket(this.process), auth: { profileId: this.credentials.profileId, jti: this.credentials.jti, expiresAt: this.credentials.expiresAt } }, "status"),
         lifecycleAction: this.lifecycle.lifecycleAction ?? null,

package/src/spawn-input.ts

@@ -105,6 +105,7 @@ export function parseRunnerCliArgs(
     else if (arg === "--model-record-provider-model" && ownArgs[i + 1]) modelRecordRaw.providerModel = ownArgs[++i];
     else if (arg === "--model-record-qualified" && ownArgs[i + 1]) modelRecordRaw.qualifiedModel = ownArgs[++i];
     else if (arg === "--model-record-effort" && ownArgs[i + 1]) modelRecordRaw.effort = ownArgs[++i];
+    else if (arg === "--model-record-efforts" && ownArgs[i + 1]) { try { modelRecordRaw.efforts = JSON.parse(ownArgs[++i]!); } catch {} }
     else if (arg === "--model-record-window" && ownArgs[i + 1]) {
       const parsed = Number(ownArgs[++i]);
       if (Number.isSafeInteger(parsed) && parsed > 0) modelRecordRaw.contextWindowTokens = parsed;
@@ -143,5 +144,5 @@ export function parseRunnerCliArgs(
 }
 
 export function runnerHelp(provider: string): string {
-  return `${provider}-relay [--headless] [--launch-mode interactive|headless] [--model ALIAS] [--effort LEVEL] [--context-window-tokens N] [--model-record-alias A --model-record-provider-model M --model-record-qualified Q --model-record-effort E --model-record-window N --model-record-max-output N --model-record-threshold JSON] [--rig NAME] [--profile NAME] [--cwd PATH] [--relay-url URL] [--approval MODE] [--label NAME] [--agent-id ID] [--prompt TEXT] [--system-prompt-append TEXT] [--tags a,b] [--caps x,y] [-- provider-args...]`;
+  return `${provider}-humwick [--headless] [--launch-mode interactive|headless] [--model ALIAS] [--effort LEVEL] [--context-window-tokens N] [--model-record-alias A --model-record-provider-model M --model-record-qualified Q --model-record-effort E --model-record-window N --model-record-max-output N --model-record-threshold JSON] [--rig NAME] [--profile NAME] [--cwd PATH] [--relay-url URL] [--approval MODE] [--label NAME] [--agent-id ID] [--prompt TEXT] [--system-prompt-append TEXT] [--tags a,b] [--caps x,y] [-- provider-args...]`;
 }