@humwick/runner 0.0.0-stage → 0.130.1

package/src/adapters/project-shell.ts

@@ -0,0 +1,80 @@
+import { relayEnv, writeChildEnv } from "@humwick/sdk/env";
+// #2947 — the orchestrator hands the runner the project's toolchain PATH plus shell hooks that re-lead
+// it after the user's shell init. The provider process keeps the host PATH; only its shell tool re-leads.
+// The same hooks keep the agent's private TMPDIR when a login profile resets it (#3084).
+// A hook the user already configured is chained behind ours, never dropped; an inherited Relay hook never is (#3084).
+import { resolve } from "node:path";
+import { browserToolsBinDir, isRecord, PROJECT_ENV_FILE_ENV, PROJECT_PATH_ENV, PROJECT_ZDOTDIR_ENV, RELAY_BIN_PATH_ENV } from "@humwick/sdk";
+import { AGENT_TMPDIR_ENV } from "@humwick/sdk/host-tmpdir";
+import { providerScratchEnv } from "@humwick/sdk/provider-scratch";
+import { composeShellHooks, PROJECT_ENV_SCRIPT, PROJECT_ZDOTDIR } from "@humwick/sdk/shell-hooks";
+import { tomlString } from "../relay-mcp";
+import { humwickHome } from "../config";
+import { providerSourceHome } from "../profile-home";
+import { readCodexConfig } from "./codex-effective-config";
+import { serviceAccessEnvKeys } from "./service-access";
+
+/** #3084 — every launch, orchestrator-spawned or direct: the agent's private TMPDIR plus the hooks that keep
+ *  it (and #2947's toolchain PATH) after shell init. */
+export async function agentShellLaunchEnv(agentId: string, operatorEnv?: Record<string, string>): Promise<Record<string, string>> {
+  return writeChildEnv({}, { ...await providerScratchEnv(agentId, undefined, operatorEnv), [PROJECT_ENV_FILE_ENV]: PROJECT_ENV_SCRIPT, [PROJECT_ZDOTDIR_ENV]: PROJECT_ZDOTDIR, [RELAY_BIN_PATH_ENV]: relayBinPath() });
+}
+
+/** #3489 — this runner's own `agent-relay-browser` and the host's provisioned `playwright-cli`: a login shell's
+ *  PATH (an older global install) can never pick which Relay release or browser tools an agent runs. */
+export function relayBinPath(): string {
+  return [resolve(import.meta.dir, "../../agent-bin"), browserToolsBinDir(humwickHome())].join(":");
+}
+
+/** Claude Code sources CLAUDE_ENV_FILE before every Bash tool command, after the user's shell init. */
+export function claudeProjectShellEnv(env: Record<string, string>): Record<string, string> {
+  const file = relayEnv(env, PROJECT_ENV_FILE_ENV);
+  if (!shellHookNeeded(env) || !file) return {};
+  return composeShellHooks((key) => relayEnv(env, key), { CLAUDE_ENV_FILE: file });
+}
+
+/** Codex runs tool commands as `<login shell> -lc`: bash reads BASH_ENV, zsh reads its startup files from
+ *  ZDOTDIR. `shell_environment_policy.set` reaches those commands only, never the app-server. The user's
+ *  own values come from that same policy (config.toml, then `configArgs`), else the inherited env. */
+export function codexProjectShellConfigArgs(env: Record<string, string>, configArgs: string[] = [], codexHome?: string): string[] {
+  const path = relayEnv(env, PROJECT_PATH_ENV);
+  if (!shellHookNeeded(env)) return [];
+  const configured = codexShellPolicySet(configArgs, codexHome || providerSourceHome("codex"));
+  if (relayEnv(env, "AGENT_RELAY_SERVICE_ACCESS_ENV_FILE")) {
+    for (const key of serviceAccessEnvKeys(env)) if (relayEnv(configured, key) !== undefined && relayEnv(configured, key) !== relayEnv(env, key)) throw new Error("vault_env_conflict:shell:" + key);
+    const policy = codexShellPolicy(configArgs, codexHome || providerSourceHome("codex"));
+    if ((Array.isArray(policy.exclude) && policy.exclude.length) || (Array.isArray(policy.include_only) && policy.include_only.length) || (policy.inherit && policy.inherit !== "all")) throw new Error("vault_env_conflict:shell_environment_policy");
+  }
+  const user = (key: string) => typeof relayEnv(configured, key) === "string" ? relayEnv(configured, key) as string : relayEnv(env, key);
+  const set: Record<string, string | undefined> = writeChildEnv({}, {
+    [PROJECT_PATH_ENV]: path,
+    [RELAY_BIN_PATH_ENV]: relayEnv(env, RELAY_BIN_PATH_ENV),
+    ...composeShellHooks(user, { BASH_ENV: relayEnv(env, PROJECT_ENV_FILE_ENV), ZDOTDIR: relayEnv(env, PROJECT_ZDOTDIR_ENV) }),
+  });
+  // An empty chain variable is set too: it clears a stale one the app-server env would hand down.
+  return [...(relayEnv(env, "AGENT_RELAY_SERVICE_ACCESS_ENV_FILE") ? ["-c", 'shell_environment_policy.inherit="all"', "-c", "shell_environment_policy.ignore_default_excludes=true"] : []),
+    ...Object.entries(set).flatMap(([key, value]) => value === undefined ? [] : ["-c", `shell_environment_policy.set.${key}=${tomlString(value)}`])];
+}
+
+/** OpenCode has no tool-only env: its server env reaches every shell it runs. */
+export function openCodeProjectShellEnv(env: Record<string, string>): Record<string, string> {
+  const file = relayEnv(env, PROJECT_ENV_FILE_ENV), zdotdir = relayEnv(env, PROJECT_ZDOTDIR_ENV);
+  if (!shellHookNeeded(env) || !file) return {};
+  return composeShellHooks((key) => relayEnv(env, key), { BASH_ENV: file, ...(zdotdir ? { ZDOTDIR: zdotdir } : {}) });
+}
+
+function shellHookNeeded(env: Record<string, string>): boolean {
+  return Boolean(relayEnv(env, PROJECT_PATH_ENV) || relayEnv(env, AGENT_TMPDIR_ENV) || relayEnv(env, "AGENT_RELAY_SERVICE_ACCESS_ENV_FILE"));
+}
+
+/** Codex's own `shell_environment_policy.set` without us: CODEX_HOME/config.toml, then `-c` overrides in order. */
+function codexShellPolicySet(configArgs: string[], codexHome: string): Record<string, unknown> {
+  const policy = codexShellPolicy(configArgs, codexHome);
+  return isRecord(policy.set) ? policy.set : {};
+}
+
+function codexShellPolicy(configArgs: string[], codexHome: string): Record<string, unknown> {
+  const config = readCodexConfig(configArgs, codexHome);
+  const policy = config.shell_environment_policy;
+  return isRecord(policy) ? policy : {};
+}

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

@@ -0,0 +1,21 @@
+import type { SpawnProvider } from "@humwick/sdk";
+import type { ProviderConfig, RunnerSpawnConfig, SpawnArgs } from "../adapter";
+import { primaryProviderInvocation, type ProviderInvocation } from "../provider-double";
+import { buildCodexTuiSpawnArgs } from "./codex-launch-config";
+
+/** Provider-owned supplemental process roles derived from the production launch configuration. */
+export function buildSupplementalProviderInvocations(
+  provider: SpawnProvider,
+  config: RunnerSpawnConfig,
+  providerConfig: ProviderConfig,
+  primary: SpawnArgs,
+): ProviderInvocation[] {
+  if (provider !== "codex") return [];
+  const tui = buildCodexTuiSpawnArgs(
+    config,
+    providerConfig,
+    primary.env.CODEX_APP_SERVER_URL ?? "",
+    primary.env,
+  );
+  return tui ? [{ ...primaryProviderInvocation(provider, tui), role: "tui" }] : [];
+}

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

@@ -0,0 +1,127 @@
+import { writeChildEnv } from "@humwick/sdk/env";
+import type { QuotaState, HumwickHttpClient } 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";
+
+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;
+
+  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).
+    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;
+  }
+
+  // #2514 — quota identity resolves exactly as the LAUNCH authenticates. The primary claude
+  // runner keeps the historical ambient-env read byte-for-byte. A claude-family provider with
+  // its own subscription (claude-b) must never inherit the ambient primary credential env
+  // (CLAUDE_CODE_OAUTH_TOKEN outranks the file credential, so the B quota would be keyed — and
+  // folded — under the A account): its identity comes from its OWN dedicated home plus its
+  // provider-scoped config env, mirroring the adapter launch scrub and the orchestrator's
+  // providerCredentialProbeEnv precedence.
+  private async resolveIdentity(): Promise<ProviderQuotaIdentity | undefined> {
+    if (this.options.provider === "claude") {
+      return resolveClaudeStatuslineQuotaIdentity({ env: process.env });
+    }
+    const providerEnv = this.options.providerConfigEnv();
+    return resolveClaudeStatuslineQuotaIdentity({
+      provider: this.options.provider,
+      env: writeChildEnv({}, { CLAUDE_CODE_OAUTH_TOKEN: providerEnv.CLAUDE_CODE_OAUTH_TOKEN }),
+      configDir: providerHostConfigHome(this.options.provider),
+    });
+  }
+
+  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 {
+  if (now - (metrics.quotaObservedAt ?? metrics.timestamp) > PASSIVE_QUOTA_SAMPLE_STALE_MS) return undefined;
+  const quota = quotaStateFromProbeMetrics(metrics);
+  if (!quota) return undefined;
+  const windows = quota.windows.filter((window) => window.resetsAt === undefined || window.resetsAt > now);
+  const live: QuotaState = { ...quota, windows };
+  // Do not turn an expired cached 5h reading into a fresh weekly-only observation (#3087).
+  return windows.length > 0 && (claudeQuotaGeneration(live) !== undefined || claudeQuotaUnavailableWindows(quota).length > 0) ? live : undefined;
+}

package/src/adapters/service-access.ts

@@ -0,0 +1,153 @@
+import { relayEnv, writeChildEnv } from "@humwick/sdk/env";
+import { X509Certificate } from "node:crypto";
+import { accessSync, constants, existsSync, mkdirSync, mkdtempSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
+import { rootCertificates } from "node:tls";
+import type { ProvisioningMcpServer } from "@humwick/sdk";
+import { shellQuote } from "@humwick/sdk/shell-utils";
+import { activeSharedMcpServers, PROJECT_ENV_FILE_ENV, PROJECT_ZDOTDIR_ENV } from "@humwick/sdk";
+import { PROJECT_ENV_SCRIPT, PROJECT_ZDOTDIR } from "@humwick/sdk/shell-hooks";
+import type { RunnerSpawnConfig } from "../adapter";
+import { extractCallerSettings } from "../claude-settings";
+import { codexConfigOverrides, isRecord } from "@humwick/sdk";
+import { projectSettingSources, providerHomePathFor, providerSourceHome } from "../profile-home";
+
+export const SERVICE_ACCESS_ENV_FILE = "AGENT_RELAY_SERVICE_ACCESS_ENV_FILE";
+const PROXY_CA_ENV_KEYS = ["SSL_CERT_FILE", "CURL_CA_BUNDLE", "GIT_SSL_CAINFO", "NODE_EXTRA_CA_CERTS", "REQUESTS_CA_BUNDLE"] as const;
+export const PROXY_TRUST_ENV_KEYS = ["HTTPS_PROXY", "HTTP_PROXY", "https_proxy", "http_proxy", "NO_PROXY", "no_proxy", "NODE_USE_ENV_PROXY", ...PROXY_CA_ENV_KEYS] as const;
+
+function fail(code: string): never { throw new Error(code); }
+
+function readLaunchFile(file: string): string {
+  const stat = statSync(file);
+  if (!stat.isFile() || stat.size > 4 * 1024 * 1024) fail("vault_invalid_launch_file");
+  return readFileSync(file, "utf8");
+}
+
+export function serviceAccessEnvKeys(env: Record<string, string>): string[] {
+  return [...PROXY_TRUST_ENV_KEYS, SERVICE_ACCESS_ENV_FILE, ...Object.keys(env).filter((key) => relayEnv(env, key) === "__relay_dummy__")];
+}
+
+/** Runs after profile/provider env merging, before hydration or any child starts. */
+export function prepareServiceAccessConfig(config: RunnerSpawnConfig): RunnerSpawnConfig {
+  const access = config.serviceAccess;
+  if (!access) {
+    const servers = Object.values(config.agentProfile?.provisioning?.mcpServers ?? {});
+    if (servers.some((server) => server.serviceAccess?.services.length)) fail("vault_mcp_service_ungranted");
+    return config;
+  }
+  if (!access.caPem || !access.caFingerprint || !access.services?.length) fail("vault_missing_trust");
+  try {
+    const cert = new X509Certificate(access.caPem);
+    if (!cert.ca || cert.fingerprint256.replaceAll(":", "").toLowerCase() !== access.caFingerprint || Date.parse(cert.validTo) <= Date.now()) fail("vault_ca_mismatch");
+  } catch { fail("vault_ca_mismatch"); }
+  if (access.expiresAt <= Date.now()) fail("vault_token_expired");
+  const inherited = writeChildEnv({}, { ...config.env, ...config.providerConfig.env });
+  if (inherited.NODE_TLS_REJECT_UNAUTHORIZED === "0" || inherited.GIT_SSL_NO_VERIFY === "true") fail("vault_tls_verification_disabled");
+  // Ambient routing cannot silently bypass a brokered host, even through ALL_PROXY.
+  for (const key of ["HTTPS_PROXY", "HTTP_PROXY", "https_proxy", "http_proxy", "ALL_PROXY", "all_proxy", "NO_PROXY", "no_proxy"]) {
+    if (relayEnv(inherited, key)) fail("vault_env_conflict:" + key);
+  }
+  const proxy = new URL(access.proxyUrl);
+  if (!["http:", "https:"].includes(proxy.protocol) || proxy.username || proxy.password) fail("vault_invalid_proxy");
+  proxy.username = access.token; proxy.password = access.vault;
+  const bypass = new Set(["localhost", "127.0.0.1", "[::1]"]);
+  for (const endpoint of [config.relayUrl, config.relayMcpEndpoint, config.sharedMcpUrl]) {
+    if (endpoint) bypass.add(new URL(endpoint).hostname);
+  }
+  if (access.services.some((service) => bypass.has(service.host))) fail("vault_service_bypass");
+  const extraRoots: string[] = [];
+  for (const key of PROXY_CA_ENV_KEYS) {
+    const value = relayEnv(inherited, key);
+    if (!value) continue;
+    try { extraRoots.push(readLaunchFile(value)); } catch { fail("vault_missing_trust:" + key); }
+  }
+  const scratch = inherited.TMPDIR;
+  if (!scratch || !isAbsolute(scratch)) fail("vault_missing_private_tmpdir");
+  const dummy: Record<string, string> = {};
+  for (const service of access.services) for (const [key, value] of Object.entries(service.dummyEnv)) {
+    if (!/^[A-Z][A-Z0-9_]*$/.test(key) || value !== "__relay_dummy__" || (relayEnv(inherited, key) && relayEnv(inherited, key) !== value) || (PROXY_TRUST_ENV_KEYS as readonly string[]).includes(key)) fail("vault_env_conflict:" + key);
+    dummy[key] = value;
+  }
+  mkdirSync(scratch, { recursive: true, mode: 0o700 });
+  const dir = mkdtempSync(join(scratch, "vault-launch-"));
+  const bundle = join(dir, "roots.pem"), script = join(dir, "env.sh");
+  const systemRoots = ["/etc/ssl/certs/ca-certificates.crt", "/etc/pki/tls/certs/ca-bundle.crt", "/etc/ssl/cert.pem"].flatMap((file) => {
+    try { return [readLaunchFile(file)]; } catch { return []; }
+  });
+  const combined = [...rootCertificates, ...systemRoots, ...extraRoots, access.caPem].join("\n");
+  writeFileSync(bundle, combined, { mode: 0o600 });
+  accessSync(bundle, constants.R_OK);
+  const env: Record<string, string> = writeChildEnv({}, {
+    ...dummy, HTTPS_PROXY: proxy.href, HTTP_PROXY: proxy.href, https_proxy: proxy.href, http_proxy: proxy.href,
+    NO_PROXY: [...bypass].join(","), no_proxy: [...bypass].join(","),
+    ...Object.fromEntries(PROXY_CA_ENV_KEYS.map((key) => [key, bundle])), NODE_USE_ENV_PROXY: "1", [SERVICE_ACCESS_ENV_FILE]: script,
+  });
+  writeFileSync(script, Object.entries(env).map(([key, value]) => `export ${key}=${shellQuote(value)}`).join("\n") + "\n", { mode: 0o600 });
+  return { ...config, providerConfig: { ...config.providerConfig, env: writeChildEnv({}, { ...config.providerConfig.env, ...env }) }, serviceAccessEnv: env, env: writeChildEnv({}, { ...config.env, ...env, [PROJECT_ENV_FILE_ENV]: PROJECT_ENV_SCRIPT, [PROJECT_ZDOTDIR_ENV]: PROJECT_ZDOTDIR }) };
+}
+
+/** References carry the child's env into native MCP config without writing the proxy token. */
+export function serviceAccessMcpServers(config: RunnerSpawnConfig, servers: Record<string, ProvisioningMcpServer>): Record<string, ProvisioningMcpServer> {
+  servers = activeSharedMcpServers(servers);
+  if (!config.serviceAccessEnv) {
+    return servers;
+  }
+  const keys = Object.keys(config.serviceAccessEnv);
+  return Object.fromEntries(Object.entries(servers).map(([name, server]) => {
+    const required = server.serviceAccess?.services ?? [];
+    if (required.some((service) => !config.serviceAccess?.services?.some((entry) => entry.name === service))) fail("vault_mcp_service_ungranted:" + name);
+    if (!server.command || server.url) {
+      const referencesDummy = Object.keys(config.serviceAccessEnv!).some((key) => key in (server.env ?? {}) || key in (server.configEnv ?? {}));
+      if (required.length || referencesDummy) fail("unsupported_execution_boundary:" + name);
+      return [name, server];
+    }
+    for (const key of keys) {
+      const value = relayEnv(server.env, key) ?? relayEnv(server.configEnv, key);
+      if (value !== undefined && value !== `\${${key}}` && value !== config.serviceAccessEnv![key]) fail("vault_env_conflict:mcp:" + name + ":" + key);
+    }
+    if (config.provider === "codex") {
+      const env = writeChildEnv({}, { ...server.env }), configEnv = writeChildEnv({}, { ...server.configEnv });
+      for (const key of keys) { writeChildEnv(env, {}, [key]); writeChildEnv(configEnv, {}, [key]); }
+      return [name, { ...server, env, configEnv, env_vars: [...new Set([...(Array.isArray(server.env_vars) ? server.env_vars : Object.keys(server.env_vars ?? {})), ...keys])] }];
+    }
+    return [name, { ...server, env: writeChildEnv({}, { ...server.env, ...Object.fromEntries(keys.map((key) => [key, `\${${key}}`])) }) }];
+  }));
+}
+
+export function serviceAccessLaunchEnv(config: RunnerSpawnConfig): Record<string, string> {
+  if (config.serviceAccess && !config.serviceAccessEnv) fail("vault_overlay_not_prepared");
+  for (const [key, value] of Object.entries(config.serviceAccessEnv ?? {})) {
+    if (relayEnv(config.env, key) !== value || (relayEnv(config.providerConfig.env, key) !== undefined && relayEnv(config.providerConfig.env, key) !== value)) fail("vault_env_conflict:" + key);
+  }
+  if (config.serviceAccessEnv) {
+    const caller = extractCallerSettings([config.providerConfig.defaultArgs, config.providerArgs], config.cwd);
+    if (caller && !caller.settings) fail("vault_unreadable_settings");
+    const settingsEnv = caller?.settings?.env;
+    const checkSettings = (settings: unknown) => {
+      const env = isRecord(settings) && isRecord(settings.env) ? settings.env : {};
+      for (const key of Object.keys(config.serviceAccessEnv!)) if (relayEnv(env, key) !== undefined && relayEnv(env, key) !== config.serviceAccessEnv![key]) fail("vault_env_conflict:settings:" + key);
+      if (env.NODE_TLS_REJECT_UNAUTHORIZED === "0") fail("vault_tls_verification_disabled");
+    };
+    checkSettings({ env: settingsEnv });
+    if (config.provider.startsWith("claude")) {
+      let sources = projectSettingSources(config) ?? ["user", "project", "local"];
+      const args = [...config.providerConfig.defaultArgs, ...config.providerArgs];
+      for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--setting-sources") sources = (args[++i] ?? "").split(",");
+        else if (args[i]!.startsWith("--setting-sources=")) sources = args[i]!.slice("--setting-sources=".length).split(",");
+      }
+      const files = sources.includes("user") ? [join(providerHomePathFor(config.provider, config) ?? providerSourceHome(config.provider), "settings.json")] : [];
+      for (let dir = config.cwd; ; dir = dirname(dir)) {
+        if (sources.includes("project")) files.push(join(dir, ".claude/settings.json"));
+        if (sources.includes("local")) files.push(join(dir, ".claude/settings.local.json"));
+        if (dirname(dir) === dir) break;
+      }
+      for (const file of files) if (existsSync(file)) checkSettings(JSON.parse(readLaunchFile(file)));
+    }
+    if (config.provider === "codex") for (const override of codexConfigOverrides([config.providerConfig.defaultArgs, config.providerArgs].flat())) {
+      if (/^mcp_servers\./.test(override) && /\.(?:env|env_vars)(?:\.|\s*=)/.test(override)) fail("vault_env_conflict:codex_mcp_override");
+    }
+  }
+  return config.serviceAccessEnv ?? {};
+}

package/src/adapters/tmux-offload.ts

@@ -0,0 +1,207 @@
+// Off-loop tmux subprocess transport (#1838 Wave 2, rows 12/14/15/16 — first real
+// adoption of the #1809/#1822 offload primitive).
+//
+// Every tmux subprocess the runner spawns from a HOT PATH — the 2s pane watcher, the 4s
+// busy reconciler, the 1.5s monitorless turn watch, and the per-payload input transport —
+// runs through the shared `SubprocessRunner` created here so it executes as an async
+// `Bun.spawn`, bounded by a hard deadline (SIGTERM → SIGKILL of the whole process group
+// after a grace window), instead of a synchronous `Bun.spawnSync` that pins the runner's
+// single event loop for the entire 10s deadline while a wedged tmux socket hangs (the
+// #1760 class; #1815 findings 1/6/7/10). A blocked tmux call here would otherwise freeze
+// this agent's bus connection, control server, heartbeat, and every timer at once.
+//
+// AT-MOST-ONCE — a property of the backend, not a per-call flag. The offload envelope's
+// `retrySafe` flag is a WorkerPool-only knob (only the CPU worker pool ever re-dispatches
+// after an ambiguous worker death); the SubprocessRunner NEVER re-runs a spawn under any
+// circumstance. So every tmux command routed through here is at-most-once by construction.
+// That is exactly what the SIDE-EFFECTING sites require — a silently re-run `send-keys` or
+// `paste-buffer` would double-type into the live pane — and it is equally fine for the
+// READ-ONLY sites (capture-pane / has-session / display-message), whose next poll tick
+// simply re-reads. No site here is idempotent-and-expensive enough to want retry, so none
+// passes `retrySafe`; the default at-most-once behaviour is correct for all of them.
+import { createSubprocessRunner, type SubprocessResult, type SubprocessRunner } from "@humwick/offload";
+import { tmuxCommand } from "@humwick/sdk/tmux-utils";
+import { SYNC_SUBPROCESS_TIMEOUT_MS } from "../bounded-spawn-sync";
+
+let runner: SubprocessRunner | undefined;
+
+// Lazily created so merely importing this module spawns nothing. concurrency > 1 keeps the
+// three independent pollers plus an occasional input transport from head-of-line blocking
+// each other behind a single slot, while still bounding fan-out onto the one tmux server a
+// runner process talks to. Each run is bounded by the same 10s deadline the old sync
+// wrapper (`spawnSyncBounded`) used, so timeout semantics are unchanged — only the blocking
+// is gone.
+function tmuxRunner(): SubprocessRunner {
+  return (runner ??= createSubprocessRunner({ concurrency: 4, defaultTimeoutMs: SYNC_SUBPROCESS_TIMEOUT_MS }));
+}
+
+// Test/teardown seam: cancel in-flight tmux spawns and drop the shared runner. Not wired
+// into adapter shutdown (the runner is process-scoped and shared across adapter instances;
+// a live child is SIGKILLed by the offload module's process `exit` hook regardless), but
+// tests that want a clean slate can await this.
+export async function destroyTmuxRunner(): Promise<void> {
+  const current = runner;
+  runner = undefined;
+  if (current) await current.destroy();
+}
+
+/** Per-call bounding for a read that sits inside a caller's OWN deadline loop (#1838 round-3
+ * MED): pass the REMAINING outer budget as `timeoutMs` so the subprocess deadline shrinks with
+ * the loop, and/or a `signal` the caller aborts at its absolute deadline. Without this each run
+ * would get the runner's full ~10s default and blow the caller's (e.g. 500ms) deadline. */
+export interface TmuxReadOpts { signal?: AbortSignal; timeoutMs?: number }
+
+async function runTmux(
+  taskName: string,
+  argv: string[],
+  opts: { okExitCodes?: readonly number[] | "any" } & TmuxReadOpts = {},
+): Promise<SubprocessResult> {
+  return tmuxRunner().run(taskName, { command: argv, okExitCodes: opts.okExitCodes }, { signal: opts.signal, timeoutMs: opts.timeoutMs });
+}
+
+/**
+ * Off-loop `tmux capture-pane` (read-only, idempotent). Throws on a non-zero exit / timeout
+ * / abort exactly like the synchronous `captureTmuxPane` it replaces on the hot paths, so
+ * the existing `try { … } catch { … }` call sites are unchanged apart from the `await`.
+ */
+export async function captureTmuxPaneAsync(sessionName: string, socketName?: string, opts: TmuxReadOpts = {}): Promise<string> {
+  const result = await runTmux("tmux-capture-pane", tmuxCapturePaneArgv(sessionName, socketName, TMUX_CAPTURE_SCROLLBACK_LINES), opts);
+  return result.stdout;
+}
+
+/** Lines of tmux HISTORY the scrollback capture reaches back over, on top of the visible screen. */
+export const TMUX_CAPTURE_SCROLLBACK_LINES = 80;
+
+/**
+ * The `tmux capture-pane` argv, with the scrollback window as the single explicit knob.
+ * `scrollbackLines` omitted/0 ⇒ the VISIBLE SCREEN ONLY (no `-S`). Exported so the two capture
+ * scopes are assertable in a unit test — the #2261 regression was exactly a caller reading the
+ * wrong one.
+ */
+export function tmuxCapturePaneArgv(sessionName: string, socketName?: string, scrollbackLines = 0, styled = false): string[] {
+  const style = styled ? ["-e"] : [];
+  return scrollbackLines > 0
+    ? tmuxCommand(socketName, "capture-pane", "-p", ...style, "-t", sessionName, "-S", `-${scrollbackLines}`)
+    : tmuxCommand(socketName, "capture-pane", "-p", ...style, "-t", sessionName);
+}
+
+/**
+ * Off-loop `tmux capture-pane` of the VISIBLE SCREEN ONLY — no `-S` scrollback window.
+ *
+ * #2261: the difference matters for anything that reads a repaint as evidence. Claude Code's
+ * `/clear` repaints only the visible screen (`ESC[H` + a per-line `ESC[2K`; it never emits the
+ * `ESC[3J` that would drop tmux's history), so the pre-clear conversation SURVIVES verbatim in
+ * scrollback. A `-S -80` capture therefore still contains the wiped conversation long after the
+ * clear committed — which made the clear-commit barrier's "the anchor is gone" test unsatisfiable
+ * and turned every successful self-resume clear on a scrolled pane into a false negative. Detectors
+ * that ask "did the TUI repaint this away?" must read this window, not the scrollback one.
+ */
+export async function captureTmuxVisiblePaneAsync(sessionName: string, socketName?: string, opts: TmuxReadOpts & { styled?: boolean } = {}): Promise<string> {
+  const { styled, ...readOpts } = opts;
+  // `styled` keeps SGR escapes (`-e`) for readers that must tell dim placeholder text from input (#2664).
+  const result = await runTmux("tmux-capture-pane", tmuxCapturePaneArgv(sessionName, socketName, 0, styled), readOpts);
+  return result.stdout;
+}
+
+/** Off-loop `tmux has-session` outcome. `unreadable` is NOT `absent` — see below. */
+export type TmuxSessionPresence = "present" | "absent" | "unreadable";
+
+/**
+ * Off-loop `tmux has-session` (read-only, idempotent), as a TRI-STATE (#1838 review HIGH-2).
+ *
+ * A boolean `present`/`!present` collapses "the session is gone" together with "I could not
+ * find out", so a wedged-but-LIVE tmux server (has-session SIGKILLed at its deadline) would
+ * read as death and let a watcher emit `offline` / abandon live work. The states are kept
+ * distinct here and only the caller decides what a non-`present` reading means:
+ *   - `present`    — tmux exited 0: the session exists.
+ *   - `absent`     — tmux exited 1: the ONLY positive proof of death. `has-session` exits 1
+ *                    both for a missing session and for "no server running", and a dead server
+ *                    genuinely took all its sessions with it, so both are real absence.
+ *   - `unreadable` — timeout / abort / spawn error / any exit ≥ 2: a fact about the READ, never
+ *                    about the session. The caller MUST hold its current state and retry, never
+ *                    treat this as death.
+ * `okExitCodes: [0, 1]` lets the two real answers through without a throw/strike; everything
+ * else (including the deadline SIGKILL that bounds a wedged socket) rejects and maps to
+ * `unreadable`.
+ */
+export async function tmuxSessionPresence(sessionName: string, socketName?: string, opts: TmuxReadOpts = {}): Promise<TmuxSessionPresence> {
+  try {
+    const result = await runTmux("tmux-has-session", tmuxCommand(socketName, "has-session", "-t", sessionName), { okExitCodes: [0, 1], ...opts });
+    return result.exitCode === 0 ? "present" : "absent";
+  } catch {
+    return "unreadable";
+  }
+}
+
+/**
+ * Off-loop resolve of a tmux session's active-pane pid via `display-message` (read-only,
+ * idempotent). Returns the direct pid untouched, or undefined when the session is gone /
+ * unreadable / the query times out. The launcher `exec`s claude, so the pane pid IS the claude
+ * pid. `okExitCodes: "any"` so a non-zero exit is undefined rather than a throw+strike.
+ */
+export async function resolveClaudePanePidAsync(directPid: number | undefined, tmuxSession?: string, tmuxSocket?: string): Promise<number | undefined> {
+  if (typeof directPid === "number" && directPid > 0) return directPid;
+  if (!tmuxSession) return undefined;
+  try {
+    const result = await runTmux("tmux-pane-pid", tmuxCommand(tmuxSocket, "display-message", "-p", "-t", tmuxSession, "-F", "#{pane_pid}"), { okExitCodes: "any" });
+    if (result.exitCode !== 0) return undefined;
+    const pid = Number.parseInt(result.stdout.trim(), 10);
+    return Number.isFinite(pid) && pid > 0 ? pid : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Off-loop, side-effecting tmux command (send-keys / paste-buffer / delete-buffer). Throws
+ * on a non-zero exit / timeout / abort. At-most-once by backend (see the module header): a
+ * failure is never silently re-run, so a delivered keystroke can never be double-typed.
+ */
+export async function runTmuxInput(taskName: string, argv: string[], signal?: AbortSignal): Promise<SubprocessResult> {
+  return runTmux(taskName, argv, { signal });
+}
+
+/**
+ * Off-loop `tmux load-buffer -b <name> -`, streaming the payload on STDIN (#1838 row 16).
+ *
+ * This replaces the old `set-buffer -b <name> <text>` whose payload rode in argv — an
+ * ARG_MAX exposure for a large delivered message (up to the platform's arg limit, beyond
+ * which the spawn fails outright). load-buffer reading from stdin has no such bound.
+ *
+ * The offload `SubprocessRunner` hard-codes `stdin: "ignore"`, so a stdin-bearing spawn
+ * cannot go through it; this is a directly-managed async `Bun.spawn` bounded by the same
+ * deadline (SIGKILL on timeout) so it is off-loop and cannot outlive its bound either. It is
+ * side-effecting (it mutates a tmux buffer) and, like the runner-backed sends, never retried.
+ */
+export async function loadTmuxBufferFromStdin(
+  bufferName: string,
+  text: string,
+  socketName?: string,
+  timeoutMs = SYNC_SUBPROCESS_TIMEOUT_MS,
+): Promise<void> {
+  const proc = Bun.spawn(tmuxCommand(socketName, "load-buffer", "-b", bufferName, "-"), {
+    stdin: new TextEncoder().encode(text),
+    stdout: "ignore",
+    stderr: "pipe",
+  });
+  // Drain stderr concurrently so a chatty failure can never wedge the child on a full pipe.
+  // `.catch` keeps this floating drain from surfacing as an unhandled rejection on the success
+  // path (where it is never awaited).
+  const stderrText = new Response(proc.stderr).text().catch(() => "");
+  let killTimer: ReturnType<typeof setTimeout> | undefined;
+  const timedOut = await Promise.race([
+    proc.exited.then(() => false),
+    new Promise<true>((resolve) => { killTimer = setTimeout(() => resolve(true), timeoutMs); }),
+  ]);
+  if (killTimer) clearTimeout(killTimer);
+  if (timedOut) {
+    try { proc.kill("SIGKILL"); } catch { /* already gone */ }
+    await proc.exited.catch(() => {});
+    throw new Error(`tmux load-buffer timed out after ${timeoutMs}ms`);
+  }
+  const exitCode = await proc.exited;
+  if (exitCode !== 0) {
+    const stderr = (await stderrText).trim();
+    throw new Error(`tmux load-buffer failed: ${stderr || `exit code ${exitCode}`}`);
+  }
+}