@humwick/runner 0.130.1 → 0.130.3

package/src/adapters/provider-quota-harvest.ts

@@ -1,61 +1,47 @@
 import { writeChildEnv } from "@humwick/sdk/env";
-import type { QuotaState, HumwickHttpClient } from "@humwick/sdk";
+import type { QuotaState, HeartbeatReport, HeartbeatResult } from "@humwick/sdk";
 import { getManifest } from "@humwick/providers";
 import { quotaStateFromProbeMetrics } from "@humwick/sdk/context-probe";
 import { claudeQuotaGeneration, claudeQuotaUnavailableWindows } from "@humwick/sdk/provider-quota-order";
 import { readRunnerContextProbeState } from "../context-probe-state";
 import { providerHostConfigHome } from "../profile-home";
-import { DEFAULT_PROVIDER_QUOTA_CONFIG, normalizeProviderQuotaConfig, resolveClaudeStatuslineQuotaIdentity, type ProviderQuotaIdentity } from "../quota";
+import { resolveClaudeStatuslineQuotaIdentity, type ProviderQuotaIdentity } from "../quota";
 
-const PASSIVE_QUOTA_CONFIG_REFRESH_MS = 60_000;
 const PASSIVE_QUOTA_SAMPLE_STALE_MS = 10 * 60_000;
-const PASSIVE_QUOTA_LEASE_MAX_TTL_MS = 10 * 60_000;
-const PASSIVE_QUOTA_LEASE_PADDING_MS = 60_000;
 
 interface ProviderQuotaHarvestOptions {
   agentId: string;
   provider: string;
   /** The runner's per-provider config env (central provider-config values), read lazily each publish. */
   providerConfigEnv: () => Record<string, string>;
-  http: () => Pick<HumwickHttpClient, "acquireProviderQuotaPublisherLease" | "getProviderQuotaConfig" | "upsertProviderQuota">;
 }
 
 export class ProviderQuotaHarvest {
-  private config = { ...DEFAULT_PROVIDER_QUOTA_CONFIG };
-  private configRefreshAt = 0;
-  private lastReportAt?: number;
   private lastReportedObservedAt?: number;
-  private lease?: { accountKey: string; leaseToken: string; expiresAt: number };
-  private nextLeaseAttemptAt?: number;
+  private nextAttemptAt = 0;
+  private lease?: { accountKey: string; leaseToken: string };
 
   constructor(private readonly options: ProviderQuotaHarvestOptions) {}
 
-  async publish(): Promise<void> {
-    // #2514 — the statusline harvest serves the whole claude FAMILY (claude + claude-b): the
-    // manifest's shim kind is the family declaration, so a second-subscription provider reuses
-    // this path under its own id without a provider list here.
-    if (getManifest(this.options.provider)?.shim?.kind !== "claude-relay") return;
-    const probeMetrics = readRunnerContextProbeState(this.options.agentId);
-    const now = Date.now();
-    const quota = probeMetrics ? freshQuotaFromProbeMetrics(probeMetrics, now) : undefined;
-    // An idle session re-sends nothing new; skipping lets its lease lapse to an active session (#3082).
+  async sample(): Promise<Pick<HeartbeatReport, "providerQuota" | "quotaLeaseToken"> | undefined> {
+    if (getManifest(this.options.provider)?.shim?.kind !== "claude-relay" || Date.now() < this.nextAttemptAt) return;
+    const metrics = readRunnerContextProbeState(this.options.agentId);
+    const quota = metrics ? freshQuotaFromProbeMetrics(metrics, Date.now()) : undefined;
     if (!quota || (this.lastReportedObservedAt !== undefined && quota.updatedAt <= this.lastReportedObservedAt)) return;
-    const config = await this.refreshConfig();
-    if (!config.enabled) return;
-    if (this.lastReportAt !== undefined && now - this.lastReportAt < config.pollIntervalMs) return;
     const identity = await this.resolveIdentity();
     if (!identity) return;
-    if (!await this.ensurePublisherLease(identity.accountKey, config.pollIntervalMs, now)) return;
-    await this.options.http().upsertProviderQuota({
-      provider: this.options.provider,
-      accountKey: identity.accountKey,
-      quota,
-      unavailableWindows: claudeQuotaUnavailableWindows(quota),
-      lastAttemptAt: now,
-      sourceAgentId: this.options.agentId,
-    });
-    this.lastReportAt = now;
-    this.lastReportedObservedAt = quota.updatedAt;
+    return {
+      providerQuota: { provider: this.options.provider, accountKey: identity.accountKey, quota,
+        unavailableWindows: claudeQuotaUnavailableWindows(quota), lastAttemptAt: Date.now(), sourceAgentId: this.options.agentId },
+      ...(this.lease?.accountKey === identity.accountKey ? { quotaLeaseToken: this.lease.leaseToken } : {}),
+    };
+  }
+
+  accept(report: HeartbeatReport, result: HeartbeatResult["providerQuota"]): void {
+    if (!result || !report.providerQuota) return;
+    this.nextAttemptAt = Date.now() + result.retryAfterMs;
+    if (result.reported) this.lastReportedObservedAt = report.providerQuota.quota?.updatedAt;
+    if (result.leaseToken) this.lease = { accountKey: report.providerQuota.accountKey, leaseToken: result.leaseToken };
   }
 
   // #2514 — quota identity resolves exactly as the LAUNCH authenticates. The primary claude
@@ -77,43 +63,6 @@ export class ProviderQuotaHarvest {
     });
   }
 
-  private async refreshConfig() {
-    const now = Date.now();
-    if (now < this.configRefreshAt) return this.config;
-    this.configRefreshAt = now + PASSIVE_QUOTA_CONFIG_REFRESH_MS;
-    try {
-      const map = await this.options.http().getProviderQuotaConfig();
-      const providerCfg = map[this.options.provider];
-      this.config = providerCfg
-        ? normalizeProviderQuotaConfig(providerCfg)
-        : { ...DEFAULT_PROVIDER_QUOTA_CONFIG };
-    } catch {
-      // Keep the previous config; defaults preserve collection if the relay is older
-      // or temporarily unreachable during a liveness tick.
-    }
-    return this.config;
-  }
-
-  private async ensurePublisherLease(accountKey: string, pollIntervalMs: number, now: number): Promise<boolean> {
-    if (this.lease?.accountKey === accountKey && this.lease.expiresAt > now) return true;
-    if (this.nextLeaseAttemptAt !== undefined && now < this.nextLeaseAttemptAt) return false;
-    const leaseToken = this.lease?.accountKey === accountKey ? this.lease.leaseToken : undefined;
-    const result = await this.options.http().acquireProviderQuotaPublisherLease({
-      provider: this.options.provider,
-      accountKey,
-      sourceAgentId: this.options.agentId,
-      ...(leaseToken ? { leaseToken } : {}),
-      ttlMs: Math.min(PASSIVE_QUOTA_LEASE_MAX_TTL_MS, pollIntervalMs + PASSIVE_QUOTA_LEASE_PADDING_MS),
-    });
-    if (!result.acquired || !result.lease) {
-      this.lease = undefined;
-      this.nextLeaseAttemptAt = now + Math.min(result.retryAfterMs ?? pollIntervalMs, pollIntervalMs);
-      return false;
-    }
-    this.lease = { accountKey, leaseToken: result.lease.leaseToken, expiresAt: result.lease.expiresAt };
-    this.nextLeaseAttemptAt = undefined;
-    return true;
-  }
 }
 
 function freshQuotaFromProbeMetrics(metrics: NonNullable<ReturnType<typeof readRunnerContextProbeState>>, now: number): QuotaState | undefined {

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;
@@ -25,7 +24,7 @@ interface LifecycleMilestoneDeps {
   stopDrainTimer(): void;
   stopSubmitRecoveryPoll(): void;
   stopTaskClaims(): void;
-  stopHttpLiveness(): void;
+  stopLiveness(): void;
   stopCredentials(): void;
   disarmBusyLivenessReconcile(): void;
   disarmBusyReconciler(): 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.
@@ -142,7 +140,7 @@ export class LifecycleMilestones {
     this.deps.stopDrainTimer();
     this.deps.stopSubmitRecoveryPoll();
     this.deps.stopTaskClaims();
-    this.deps.stopHttpLiveness();
+    this.deps.stopLiveness();
     this.deps.stopCredentials();
     this.deps.disarmBusyLivenessReconcile();
     this.deps.disarmBusyReconciler();

package/src/agent-runner/liveness-exchange.ts

@@ -0,0 +1,104 @@
+import { errMessage, type HumwickBusClient, type HumwickHttpClient, type HeartbeatReport, type HeartbeatResult, type Message } from "@humwick/sdk";
+import { httpErrorKey, isHttpAuthError, runnerAgentStatus } from "../runner-helpers";
+import type { ClaimTracker } from "../claim-tracker";
+
+const LIVENESS_INTERVAL_MS = 20_000;
+// Shorter than the interval, so a wedged bus exchange falls back to HTTP before the next tick.
+const BUS_LIVENESS_TIMEOUT_MS = 15_000;
+
+interface LivenessExchangeDeps {
+  http: Pick<HumwickHttpClient, "heartbeat">;
+  bus(): Pick<HumwickBusClient, "livenessAvailable" | "reportLiveness">;
+  agentId: string;
+  instanceId: string;
+  logIntervalMs: number;
+  isStopped(): boolean;
+  isTerminalStatusLatched(): boolean;
+  currentStatus: ClaimTracker["currentStatus"];
+  sampleQuota(): Promise<Pick<HeartbeatReport, "providerQuota" | "quotaLeaseToken"> | undefined>;
+  acceptQuota(report: HeartbeatReport, result: HeartbeatResult["providerQuota"]): void;
+  enqueueMessage(message: Message): void;
+  triggerEffort(): void;
+  recoverRuntimeTokenAfterAuthFailure(source: string): void;
+  logRunnerDiagnostic(message: string): void;
+}
+
+/** The runner's periodic liveness exchange (#3608). It rides the registered bus socket and falls
+ *  back to HTTP while the socket is down or the exchange fails on it (#3618). */
+export class LivenessExchange {
+  private timer?: Timer;
+  private inFlight = false;
+  private authFailed = false;
+  private lastLog?: { key: string; at: number };
+
+  constructor(private readonly deps: LivenessExchangeDeps) {}
+
+  stop(): void {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = undefined;
+  }
+
+  resetAuthFailure(): void { this.authFailed = false; }
+
+  start(): void {
+    if (this.timer) clearInterval(this.timer);
+    void this.publish();
+    this.timer = setInterval(() => {
+      void this.publish();
+    }, LIVENESS_INTERVAL_MS);
+  }
+
+  private async publish(): Promise<void> {
+    if (this.deps.isStopped() || this.deps.isTerminalStatusLatched() || this.inFlight || this.authFailed) return;
+    this.inFlight = true;
+    const status = this.deps.currentStatus();
+    const agentStatus = runnerAgentStatus(status);
+    try {
+      const quota = await this.deps.sampleQuota().catch((error) => {
+        this.deps.logRunnerDiagnostic(`passive provider quota sample failed: ${errMessage(error)}`);
+      });
+      // #3608 — inbox recovery and fresh quota samples ride the single liveness exchange.
+      const report: HeartbeatReport = { status: agentStatus, ready: agentStatus !== "offline", unread: true, ...quota };
+      const result = await this.exchange(report);
+      this.deps.acceptQuota(report, result?.providerQuota);
+      for (const message of result?.messages ?? []) this.deps.enqueueMessage(message);
+      this.deps.triggerEffort();
+    } catch (error) {
+      if (!this.deps.isStopped()) this.handleHttpFailure(error);
+    } finally {
+      this.inFlight = false;
+    }
+  }
+
+  private async exchange(report: HeartbeatReport): Promise<HeartbeatResult> {
+    const bus = this.deps.bus();
+    if (bus.livenessAvailable) {
+      try {
+        return await bus.reportLiveness(report, BUS_LIVENESS_TIMEOUT_MS);
+      } catch (error) {
+        // The report is idempotent (status, readiness, unread by id), so a retry over HTTP is safe.
+        this.logFailure(`bus:${errMessage(error)}`, `[runner] bus liveness exchange failed, using HTTP: ${errMessage(error)}`);
+      }
+    }
+    return await this.deps.http.heartbeat(this.deps.agentId, this.deps.instanceId, report);
+  }
+
+  private handleHttpFailure(error: unknown): void {
+    const authFailed = isHttpAuthError(error);
+    const suffix = authFailed ? "auth failed; stopping HTTP liveness retries until restart" : String(error);
+    this.logFailure(httpErrorKey(error), `[runner] HTTP liveness update failed: ${suffix}`);
+    if (!authFailed) return;
+    this.authFailed = true;
+    this.stop();
+    // A 401/403 here is the only timely signal that the token died — stopping the
+    // liveness timer means there is no second chance, so recover from THIS failure.
+    this.deps.recoverRuntimeTokenAfterAuthFailure("http-liveness");
+  }
+
+  private logFailure(key: string, message: string): void {
+    const now = Date.now();
+    if (this.lastLog?.key === key && now - this.lastLog.at < this.deps.logIntervalMs) return;
+    this.lastLog = { key, at: now };
+    this.deps.logRunnerDiagnostic(message);
+  }
+}

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/claude-system-prompt.ts

@@ -0,0 +1,49 @@
+import { dirname, join, resolve } from "node:path";
+import { HARNESS_SUBAGENTS_DISABLED, harnessSubagentsEnabled } from "@humwick/sdk";
+import type { RunnerSpawnConfig } from "./adapter";
+import { bundledIntegrationHome } from "./provider-integration";
+import { composeSystemPromptAppend } from "./project-instructions";
+import { CLAUDE_NO_ATTRIBUTION_RULE } from "./claude-settings";
+import { claudeWebToolsSteer } from "./web-tools";
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+
+const APPEND_FLAGS = ["--append-system-prompt", "--append-system-prompt-file"];
+
+// #3830 — caller/default appends share the same file channel as Relay context.
+export function claudeCallerAppends(args: string[]): { args: string[]; appends: Array<{ value: string; file: boolean }> } {
+  const remaining: string[] = [];
+  const appends: Array<{ value: string; file: boolean }> = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
+    if (arg === "--") { remaining.push(...args.slice(i)); break; }
+    const flag = APPEND_FLAGS.find(flag => arg === flag || arg.startsWith(`${flag}=`));
+    if (!flag) { remaining.push(arg); continue; }
+    const value = arg === flag ? args[++i] : arg.slice(flag.length + 1);
+    if (value === undefined) throw new Error(`${flag} requires a value`);
+    appends.push({ value, file: flag.endsWith("-file") });
+  }
+  return { args: remaining, appends };
+}
+
+export function resolveClaudeSystemPrompt(config: RunnerSpawnConfig, defaultArgs: string[], assetHome?: string) {
+  const composed = composeSystemPromptAppend(config);
+  const parts: Array<{ text: string } | { file: string }> = [{ text: composed.text }];
+  for (const append of claudeCallerAppends([...defaultArgs, ...config.providerArgs]).appends) {
+    parts.push(append.file ? { file: resolve(config.cwd, append.value) } : { text: append.value });
+  }
+  parts.push(...[...(harnessSubagentsEnabled(config) ? [] : [HARNESS_SUBAGENTS_DISABLED]), claudeWebToolsSteer(config), CLAUDE_NO_ATTRIBUTION_RULE].map(text => ({ text })));
+  return {
+    path: join(assetHome ?? bundledIntegrationHome(config), "system-prompt-append.md"),
+    reinjected: composed.reinjected,
+    parts,
+  };
+}
+
+export function materializeClaudeSystemPrompt(file?: ReturnType<typeof resolveClaudeSystemPrompt>): void {
+  if (!file) return;
+  // Report-only assembly never opens caller files; launch materialization owns that failure.
+  const text = file.parts.map(part => "text" in part ? part.text : readFileSync(part.file, "utf8")).filter(Boolean).join("\n\n");
+  mkdirSync(dirname(file.path), { recursive: true, mode: 0o700 });
+  writeFileSync(file.path, text, { mode: 0o600 });
+  chmodSync(file.path, 0o600);
+}

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/launch-assembly.ts

@@ -1,10 +1,10 @@
 import { bundledIntegrationAssets, bundledIntegrationHome, suppressOwnedClaudePlugins, selectClaudePluginDirs } from "./provider-integration";
 import { relayEnv, writeChildEnv } from "@humwick/sdk/env";
 import { codexRetiredMcpConfigArgs } from "./adapters/codex-effective-config";
-import { activeSharedMcpServers, HARNESS_SUBAGENTS_DISABLED, harnessSubagentsEnabled } from "@humwick/sdk";
+import { activeSharedMcpServers } from "@humwick/sdk";
 import { claudeSubagentHooks, claudeSubagentSettings } from "./adapters/claude-subagents";
 import { serviceAccessLaunchEnv, serviceAccessMcpServers } from "./adapters/service-access";
-import { claudeSettingsArgs, CLAUDE_NO_ATTRIBUTION_RULE, extractCallerSettings, stripSettingsArgs, mergeHookSets, hasSettingsArg, sessionStatusLineSettingsArgs } from "./claude-settings";
+import { claudeSettingsArgs, extractCallerSettings, stripSettingsArgs, mergeHookSets, hasSettingsArg, sessionStatusLineSettingsArgs } from "./claude-settings";
 export { stripSettingsArgs, sessionStatusLineSettingsArgs } from "./claude-settings";
 import { rmSync, writeFileSync } from "node:fs";
 import { basename, relative, resolve, join } from "node:path";
@@ -45,8 +45,8 @@ import type { ResolvedProjectClaudeSettings } from "./provisioning";
 import { resolveMcpSources, type McpSourceSelection } from "./mcp-source-selection";
 import { resolveProjectHooks } from "./project-hooks";
 import { agentRedactEnv, agentRedactOn, isAgentRedactInstall, resolveAgentRedact, type AgentRedactState } from "./agent-redact";
-import { composeSystemPromptAppend } from "./project-instructions";
-import { claudeWebToolsSteer, disabledSharedWebTools, webToolsEnv, withDisabledWebTools } from "./web-tools";
+import { resolveClaudeSystemPrompt, materializeClaudeSystemPrompt } from "./claude-system-prompt";
+import { disabledSharedWebTools, webToolsEnv, withDisabledWebTools } from "./web-tools";
 import {
   claudeMcpConfigPayload,
   claudeMcpLaunchArgs,
@@ -160,6 +160,7 @@ export interface AssembledMcp {
 
 export interface AssembledLaunch {
   provider: SpawnProvider;
+  systemPromptFile?: ReturnType<typeof resolveClaudeSystemPrompt>;
   /** The resolved profile this launch was assembled from; undefined for a profile-less
    *  (legacy default) spawn, which behaves as host base with relay features default-on. */
   profile?: AgentProfile;
@@ -546,8 +547,8 @@ function assembleClaude(config: RunnerSpawnConfig, providerConfig: ProviderConfi
   // #2086 — when P.hooks forces the project scope off but P.instructions is on, re-inject the repo
   // CLAUDE.md/AGENTS.md through the controlled append-system-prompt channel so the docs are honored
   // rather than silently dropped (see composeSystemPromptAppend / resolveProjectInstructions).
-  const { text: composedAppend, reinjected: repoInstructionsReinjected } = composeSystemPromptAppend(config);
-  const systemPromptAppend = [composedAppend, ...(harnessSubagentsEnabled(config) ? [] : [HARNESS_SUBAGENTS_DISABLED]), claudeWebToolsSteer(config), CLAUDE_NO_ATTRIBUTION_RULE].filter(Boolean).join("\n\n");
+  const promptFile = resolveClaudeSystemPrompt(config, hostDefaultArgs, assetHome);
+  const repoInstructionsReinjected = promptFile.reinjected;
   const instructions = assembleInstructions(config, {
     projectScopeDropped,
     isolatedHome: Boolean(configHome),
@@ -570,11 +571,12 @@ function assembleClaude(config: RunnerSpawnConfig, providerConfig: ProviderConfi
       ...(mcpConfigFilePath ? { configFilePath: mcpConfigFilePath } : {}),
     }),
     ...settings.args,
-    ...(systemPromptAppend ? ["--append-system-prompt", systemPromptAppend] : []),
+    "--append-system-prompt-file", promptFile.path,
   ];
 
   return {
     provider,
+    systemPromptFile: promptFile,
     ...(config.agentProfile ? { profile: config.agentProfile } : {}),
     base: config.agentProfile?.base ?? "host",
     vanilla,
@@ -938,10 +940,12 @@ export function assembleLaunch(provider: SpawnProvider, config: RunnerSpawnConfi
 /**
  * Write the provisioned assets the assembly describes (skills/plugins/hooks and Codex
  * hooks.json). Driven by the SAME resolvers `assembleLaunch` uses, so disk == launch ==
- * report. Idempotent; the isolated home must already exist (prepare*ProfileHome). No-op
- * for a host-base profile.
+ * report. Idempotent; the isolated home must already exist (prepare*ProfileHome). Claude
+ * system context also uses a private file for host-base and profile-less launches.
  */
-export function materializeLaunchAssembly(provider: SpawnProvider, config: RunnerSpawnConfig): void {
+export function materializeLaunchAssembly(provider: SpawnProvider, config: RunnerSpawnConfig, assembled?: AssembledLaunch): void {
+  // #3830 — every Claude path, including host-base/profile-less, uses a private file.
+  if (getManifest(provider)?.shim?.kind === "claude-relay") materializeClaudeSystemPrompt((assembled ?? assembleLaunch(provider, config, config.providerConfig)).systemPromptFile);
   if (!config.agentProfile && runnerMcpGeneration(config.env) === "humwick") {
     const feature = getManifest(provider)?.provisioning?.bundledSkills ? "skills" : "plugins";
     if (profileAllowsRelayFeature(config, feature)) {

package/src/profile-home.ts

@@ -78,7 +78,7 @@ export function providerHomePathFor(provider: SpawnProvider, config: RunnerSpawn
 // the repo's CLAUDE.md / AGENTS.md as behavioral instructions, NOT "don't
 // operate here" — an isolated agent must still read/edit/execute in its own cwd.
 //
-// #2254 — claude-rig / host-base launches skip the onboarding/theme bootstrap (an
+// #2254 — host-base launches skip the onboarding/theme bootstrap (an
 // onboarded host config already answers those), but they do NOT dodge folder trust:
 // --dangerously-skip-permissions does not bypass the trust gate, and a cwd the host
 // config has never seen still renders the dialog and wedges the spawn. Trust is

package/src/project-instructions.ts

@@ -11,8 +11,8 @@ import { projectSettingSourcesOn } from "./profile-home";
 // the Claude re-injection channel and lists both names the cwd may carry.
 const REPO_INSTRUCTION_FILES = ["CLAUDE.md", "AGENTS.md"] as const;
 
-// Bound each re-injected file so a pathological repo doc can't balloon the launch argv
-// (append-system-prompt rides the command line). Mirrors the spirit of Codex's
+// Bound each re-injected file so a pathological repo doc cannot balloon the context.
+// The composed append travels by private file (#3830). Mirrors Codex's
 // project_doc_max_bytes default; oversized content is truncated with a loud marker
 // rather than silently dropped.
 const REPO_INSTRUCTIONS_MAX_BYTES = 64 * 1024;

package/src/provider-command.ts

@@ -0,0 +1,18 @@
+import { basename } from "node:path";
+import { logger } from "./logger";
+
+const warned = new Set<string>();
+
+/**
+ * The ONE place a provider's launch command is resolved. The launch and the pre-spawn login check
+ * both call it, so the check can never probe a different binary than the launch runs.
+ * A stored `claude-rig` command (the retired wrapper) is treated as plain `claude`, with one warning.
+ */
+export function resolveLaunchCommand(command: string): string {
+  if (basename(command) !== "claude-rig") return command;
+  if (!warned.has(command)) {
+    warned.add(command);
+    logger.warn("provider-command", `stored provider command "${command}" is the retired claude-rig wrapper; launching plain "claude" instead. Set the provider command to "claude" in the dashboard.`);
+  }
+  return "claude";
+}

package/src/provider-setup.ts

@@ -0,0 +1,35 @@
+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";
+import { resolveLaunchCommand } from "./provider-command";
+
+/** 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, resolveLaunchCommand(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));
 }