@humwick/runner 0.130.2 → 0.130.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humwick/runner",
-  "version": "0.130.2",
+  "version": "0.130.4",
   "description": "Unified provider lifecycle runner for Humwick",
   "type": "module",
   "bin": {
@@ -29,9 +29,9 @@
     "directory": "runner"
   },
   "dependencies": {
-    "@humwick/offload": "0.130.2",
-    "@humwick/providers": "0.104.8",
-    "@humwick/sdk": "0.2.137",
+    "@humwick/offload": "0.130.4",
+    "@humwick/providers": "0.104.10",
+    "@humwick/sdk": "0.2.139",
     "callmux": "0.25.0",
     "unbash": "6.0.0"
   },

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.2",
+  "version": "0.130.4",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/src/adapters/claude-api.ts

@@ -49,7 +49,7 @@ export class ClaudeApiAdapter extends ClaudeHeadlessAdapter {
       env: resolveProviderApiAuth(this.provider, built.env, {
         ANTHROPIC_API_KEY_FILE: providerConfig.env.ANTHROPIC_API_KEY_FILE ?? process.env.ANTHROPIC_API_KEY_FILE
           ?? "~/.config/agent-relay/secrets/anthropic-api.key",
-      }) };
+      }, config.env) };
   }
 
   override async spawn(config: RunnerSpawnConfig): Promise<ManagedProcess> {

package/src/adapters/claude-headless.ts

@@ -137,7 +137,7 @@ export class ClaudeHeadlessAdapter implements ProviderAdapter {
     if (!config.headless) throw new Error("Claude stream-json transport requires --headless");
     // Use the existing provisioning, permission policy and credential-isolation seam.
     // Prompts enter through stdin only; no positional/one-shot prompt at launch.
-    const args = this.launch.buildSpawnArgs({ ...config, prompt: undefined, rig: undefined }, { ...providerConfig, command: "claude" });
+    const args = this.launch.buildSpawnArgs({ ...config, prompt: undefined, rig: undefined }, providerConfig);
     const transportArgs: string[] = [];
     for (let i = 0; i < args.args.length; i++) {
       const arg = args.args[i]!;

package/src/adapters/claude-launch-exit.ts

@@ -0,0 +1,26 @@
+import { readIncrementalFileRange, statIncrementalFile } from "./incremental-file";
+import type { ProviderStatusUpdate } from "../adapter";
+import { readOneShotExitCode } from "../session-scratch";
+
+/** Read only the diagnostic tail, even after a long provider session. */
+async function stderrTail(path: string): Promise<string> {
+  try {
+    const { size } = await statIncrementalFile(path);
+    return new TextDecoder().decode(await readIncrementalFileRange(path, Math.max(0, size - 4096), size)).trim();
+  } catch { return ""; }
+}
+
+// #3830 — a vanished pane is not evidence of a successful provider launch.
+export async function claudeLaunchExitStatus(exitCodeFile: string | undefined, ready: boolean, oneShot: boolean, paneTail = ""): Promise<ProviderStatusUpdate> {
+  const code = exitCodeFile ? await readOneShotExitCode(exitCodeFile) : undefined;
+  // A successful interactive exec replaces the shell and its EXIT trap.
+  if ((code === undefined && ready && !oneShot) || (code === "0" && (ready || oneShot))) return "offline";
+  const tail = exitCodeFile ? await stderrTail(`${exitCodeFile}.stderr`) : "";
+  const reason = ready || oneShot ? "provider-exited" : "spawn_failed";
+  const message = `Claude ${ready || oneShot ? "provider exited" : "launch failed before ready"} (${code === undefined ? "exit code unavailable" : `exit code ${code}`})${tail || paneTail ? `: ${tail || paneTail.slice(-4096)}` : ""}`;
+  return {
+    status: "error",
+    providerState: { state: "failed", reason, message, source: "provider", terminal: true },
+    metadata: { terminalFailureReason: reason, terminalFailureMessage: message },
+  };
+}

package/src/adapters/claude-session-probe.ts

@@ -10,7 +10,7 @@
 // This is the single home (DRY) for reading + version-gating + mapping that probe.
 // `probeActivity`, the BusyReconciler backstop, and the monitorless turn-watch all
 // delegate here; the legacy pane-scrape stays only as the graceful fallback for
-// pre-2.1.119 / probe-missing sessions (e.g. a claude-rig host whose real config
+// pre-2.1.119 / probe-missing sessions (e.g. a host whose real config
 // home the runner can't resolve). Schema is reverse-engineered (pbauermeister/
 // claude-busy-monitor), so we gate on `version`/presence and degrade gracefully if
 // Anthropic ever drifts it.

package/src/adapters/claude-tmux.ts

@@ -1,4 +1,4 @@
-import { relayEnv } from "@humwick/sdk/env";
+import { relayEnv, writeChildEnv } from "@humwick/sdk/env";
 import { envPipeSource, prepareEnvPipe, providerSecretEnvKeys } from "@humwick/sdk/child-env";
 import { PROVIDER_SCRATCH_ENV_KEYS } from "@humwick/sdk/provider-scratch";
 // Claude tmux transport plumbing (extracted from ./claude for the file-size
@@ -15,12 +15,12 @@ import { TMUX_SESSION_OWNER_OPTION, managedTmuxSocketName, renderTmuxSessionTarg
 import { claudeClearCommitted, claudeConversationAnchor, claudePaneIsBusy, claudePaneLooksReady } from "./claude-status-detectors";
 import { ClaudeSubmitFence, ClaudeSubmitTranscriptProbe, claudeSubmitRecoveryConfirmed, submitClaudePromptConfirmed } from "./claude-submit-confirmation";
 import type { ClaudePromptHookExpectation, ClaudePromptHookLedger } from "./claude-prompt-hook";
-import type { ProviderInputObserver } from "../adapter";
+import type { ProviderInputObserver, RunnerSpawnConfig, SpawnArgs } from "../adapter";
 import { logger } from "../logger";
 import { claudeClearSessionVerdict, type ClaudeClearSessionReading } from "./claude-session-probe";
 import { tmuxOwnerIdFromEnv } from "../config";
 import { spawnSyncBounded } from "../bounded-spawn-sync";
-import { launcherGatePathForSession, launcherScriptPathForSession, readOneShotExitCode } from "../session-scratch";
+import { launcherGatePathForSession, launcherScriptPathForSession } from "../session-scratch";
 import { captureTmuxPaneAsync, captureTmuxVisiblePaneAsync, loadTmuxBufferFromStdin, runTmuxInput, tmuxSessionPresence, type TmuxReadOpts, type TmuxSessionPresence } from "./tmux-offload";
 
 export const CLAUDE_TMUX_SUBMIT_DELAY_MS = 250;
@@ -50,11 +50,6 @@ export function seedClaudeInitialPrompt(args: string[], prompt: string, options:
   return { stdinFile: promptFile, exitCodeFile, stdinContents: prompt };
 }
 
-/** A missing sentinel means the one-shot process was killed before its shell could report success. */
-export async function claudeOneShotExitStatus(exitCodeFile?: string): Promise<"offline" | "error"> {
-  if (!exitCodeFile) return "offline";
-  return (await readOneShotExitCode(exitCodeFile)) === "0" ? "offline" : "error";
-}
 
 export function tmuxSessionName(prefix: string, instanceId: string, label?: string): string {
   if (label) return `${prefix}-${sanitizeFsName(label, { replacement: "-", collapse: false, lowercase: true })}`;
@@ -487,8 +482,12 @@ export function writeLauncherScript(sessionName: string, env: Record<string, str
   const unsets = unsetKeys.map((key) => `unset ${shellEnvKey(key)}`).join("\n");
   const gate = gateFifo ? `read -r _ < ${shellQuote(gateFifo)} || true\n` : "";
   const stdin = stdinFile ? `exec < ${shellQuote(stdinFile)}\n` : "";
-  const command = exitCodeFile ? `${shellCmd}\nexit_code=$?\nprintf '%s' "$exit_code" > ${shellQuote(exitCodeFile)}\nexit "$exit_code"` : `exec ${shellCmd}`;
-  writeFileSync(scriptPath, `#!/usr/bin/env bash\n${exports ? `${exports}\n` : ""}${Object.keys(env).length ? `${envPipeSource()}\n` : ""}${unsets ? `${unsets}\n` : ""}rm -f -- "$0"\n${gate}${stdin}${command}\n`, { mode: 0o700 });
+  const codeFile = exitCodeFile ?? `${scriptPath}.exit-code`;
+  // Interactive Claude must own pane_pid for its session probe. execfail lets a
+  // failed exec return to EXIT; print mode keeps a parent to record completion (#3830).
+  const recordExit = `trap ${shellQuote(`exit_code=$?; printf '%s' "$exit_code" > ${shellQuote(codeFile)}; exit "$exit_code"`)} EXIT`;
+  const command = exitCodeFile ? `( ${shellCmd} )` : `exec ${shellCmd}`;
+  writeFileSync(scriptPath, `#!/usr/bin/env bash\numask 077\nshopt -s execfail\nrm -f -- ${shellQuote(codeFile)} ${shellQuote(`${codeFile}.stderr`)}\n${recordExit}\nexec 2> >(tee ${shellQuote(`${codeFile}.stderr`)} >&2)\n${exports ? `${exports}\n` : ""}${Object.keys(env).length ? `${envPipeSource()}\n` : ""}${unsets ? `${unsets}\n` : ""}rm -f -- "$0"\n${gate}${stdin}${command}\n`, { mode: 0o700 });
   return scriptPath;
 }
 
@@ -546,3 +545,32 @@ export function tmuxEnvKeys(env: Record<string, string>, providerEnv: Record<str
   }
   return [...keys].sort();
 }
+
+export function buildClaudeTmuxArgs(config: RunnerSpawnConfig, spawnArgs: SpawnArgs, provider: string): { sessionName: string; socketName: string; args: string[]; launcherScript: string; gateFifo?: string; printMode: boolean } {
+    const requestedSessionName = config.tmuxSession || tmuxSessionName(config.providerConfig.headless.tmuxPrefix, config.instanceId, config.label);
+    // Keep the socket derived from the orchestrator's stable identity, but carry
+    // tmux's rendered session name everywhere we later target the pane. Without
+    // this, `opus-4.8` is created as `opus-4_8` and every watcher/restart lookup
+    // immediately misses it.
+    const socketName = tmuxSocketName(requestedSessionName); const sessionName = tmuxSessionTargetName(requestedSessionName);
+    const shellCmd = [spawnArgs.command, ...spawnArgs.args].map(shellQuote).join(" ");
+    const tmuxArgs = ["new-session", "-d", "-s", sessionName, "-x", "200", "-y", "50"];
+
+    const envKeys = tmuxEnvKeys(spawnArgs.env, config.providerConfig.env, provider);
+    const env: Record<string, string> = {};
+    for (const key of envKeys) if (relayEnv(spawnArgs.env, key) !== undefined) writeChildEnv(env, { [key]: relayEnv(spawnArgs.env, key)! });
+
+    // Only gate the launch behind pipe-pane attachment when there's a log file to
+    // protect (#1317) — no point serializing dev/interactive spawns that never
+    // read AGENT_RELAY_LOG_FILE.
+    const gateFifo = relayEnv(spawnArgs.env, "AGENT_RELAY_LOG_FILE") ? launcherGatePathForSession(sessionName) : undefined;
+
+    // tmux new-session has a hard command-length limit that includes every argv item,
+    // including `-e KEY=value`. The script holds the command; its private FIFO
+    // carries env values without writing credentials to disk or argv.
+    const printMode = spawnArgs.args.some(arg => arg === "-p" || arg === "--print");
+    const exitCodeFile = spawnArgs.exitCodeFile ?? (printMode ? `${launcherScriptPathForSession(sessionName)}.exit-code` : undefined);
+    const launcherScript = writeLauncherScript(sessionName, env, shellCmd, gateFifo, spawnArgs.stdinFile, exitCodeFile, spawnArgs.envUnset);
+    tmuxArgs.push("-c", spawnArgs.cwd, `bash ${shellQuote(launcherScript)}`);
+    return { sessionName, socketName, args: tmuxArgs, launcherScript, gateFifo, printMode };
+}

package/src/adapters/claude.ts

@@ -3,9 +3,9 @@ import { claudeSubagentEnv, claudeSubagentPolicy, configureClaudeSubagentLaunch,
 import { submitClaudeContextCommand } from "./claude-context-command";
 import { scopeClaudeCredentialEnv } from "./claude-credentials";
 import { claudeEffortLaunch, claudeEffortSwitchMeta, switchClaudeEffort } from "./claude-effort";
-import { existsSync } from "node:fs";
-import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { claudeLaunchExitStatus } from "./claude-launch-exit";
+import { claudeCallerAppends } from "../claude-system-prompt";
+import { resolveLaunchCommand } from "../provider-command";
 import { fireAndForget, sanitizeLaunchBoundary, sanitizeLaunchText, type LivenessSignal, type Message } from "@humwick/sdk";
 import { shellEscape as shellQuote } from "@humwick/sdk/shell-utils";
 import { tmuxCommand, tmuxHasSession } from "@humwick/sdk/tmux-utils";
@@ -25,13 +25,13 @@ import { claudeActivityFromProbeAndPane, claudeBypassDialogDisplayGate, claudeBy
 import { ClaudeSessionCapture, collectClaudeTranscriptArchiveSegment, collectClaudeTranscriptSessionEvents } from "./claude-session-capture";
 import { claudeToolHookPaths, extractLatestContextUsage } from "./claude-transcript";
 import { ClaudeTranscriptTokenUsageCapture } from "./claude-token-usage-capture";
-import { CLAUDE_CLEAR_COMMIT_CAPTURE, CLAUDE_TMUX_READY_TIMEOUT_MS, claudeOneShotExitStatus, confirmClaudeSubmitRecovery, confirmTmuxSessionGone, createLauncherGate, createTmuxSessionWithEnv, releaseClaudeSubmitFence, releaseLauncherGate, seedClaudeInitialPrompt, submitTextToTmux, tmuxEnvKeys, tmuxSessionName, tmuxSessionTargetName, tmuxSocketName, waitForClaudeClearCommitted, waitForClaudeInputReady, writeLauncherScript } from "./claude-tmux";
+import { CLAUDE_CLEAR_COMMIT_CAPTURE, CLAUDE_TMUX_READY_TIMEOUT_MS, buildClaudeTmuxArgs, confirmClaudeSubmitRecovery, confirmTmuxSessionGone, createLauncherGate, createTmuxSessionWithEnv, releaseClaudeSubmitFence, releaseLauncherGate, seedClaudeInitialPrompt, submitTextToTmux, waitForClaudeClearCommitted, waitForClaudeInputReady } from "./claude-tmux";
 import { captureTmuxPaneAsync, captureTmuxVisiblePaneAsync, resolveClaudePanePidAsync, tmuxSessionPresence } from "./tmux-offload";
 import { claudeShutdownGraceMs, shutdownClaudeTmux, type ClaudeShutdownDeps } from "./claude-shutdown";
 import { claudePermissionPromptHandler } from "./claude-permission";
 import { claudeHarnessTrim, claudeProfileDisallowedToolsArgs } from "./claude-tool-policy";
 import { claudeProjectShellEnv } from "./project-shell";
-import { launcherGatePathForSession, stageOneShotPrompt } from "../session-scratch";
+import { stageOneShotPrompt } from "../session-scratch";
 
 type MonitorlessTurnWatchDeps = {
   resolvePanePid: typeof resolveClaudePanePidAsync;
@@ -635,32 +635,22 @@ export class ClaudeAdapter implements ProviderAdapter {
     // #557 — ONE assembler owns the provisioning/vanilla/instruction launch surface
     // (--setting-sources, --plugin-dir, --mcp-config, status-line, --append-system-prompt);
     // profile-projection describes the SAME assembled result, so report == launch. The
-    // adapter only adds the bits the assembler does not own: claude-rig command resolution,
+    // adapter only adds the bits the assembler does not own: launch command resolution,
     // headless permission flags, --model, and the positional prompt. materializeLaunchAssembly
     // writes the provisioned skills/plugins the assembled args point at.
     const assembled = assembleLaunch(this.provider, config, providerConfig);
-    materializeLaunchAssembly(this.provider, config);
+    materializeLaunchAssembly(this.provider, config, assembled);
     const defaultArgs = assembled.hostDefaultArgs;
-    const isClaudeRig = /claude-rig/.test(providerConfig.command);
-    // Profiled launches run their own CLAUDE_CONFIG_DIR (#3387) and must never route through
-    // claude-rig — claude-rig resolves host rig config and would redirect the assembled home.
-    // Only a profile-less (user-wrapped) session may use claude-rig.
-    const usesClaudeRig = isClaudeRig && !assembled.configHome;
-    const bypassRigDefaults = config.headless && usesClaudeRig && config.approvalMode !== "open";
-    const rigPrefix = usesClaudeRig && !bypassRigDefaults && config.rig ? ["launch", config.rig] : [];
-    const command = !usesClaudeRig || bypassRigDefaults || (!config.rig && !findClaudeRigRC(config.cwd))
-      ? "claude"
-      : providerConfig.command;
-    const providerArgs = config.headless
+    const command = resolveLaunchCommand(providerConfig.command);
+    const providerArgs = claudeCallerAppends(config.headless
       ? claudeLaunchArgs(defaultArgs, config.providerArgs, config.approvalMode)
-      : [...defaultArgs, ...config.providerArgs];
+      : [...defaultArgs, ...config.providerArgs]).args;
     // #1096 — when the assembler merged the caller's own `--settings` into relay's (so the
     // baseline hooks/projectSettings/statusLine survive), drop the caller's now-redundant
     // `--settings` here so exactly ONE reaches the launch (relay's merged copy in assembled.args).
     // #2453 — the coding/review profiles' --disallowedTools trim unions in at this single
     // claude-family launch seam (helpers + per-profile config in ./claude-tool-policy).
     const args = claudeProfileDisallowedToolsArgs([
-      ...rigPrefix,
       ...assembled.args,
       ...(assembled.callerSettingsConsumed ? stripSettingsArgs(providerArgs) : providerArgs),
     ], config);
@@ -673,12 +663,10 @@ export class ClaudeAdapter implements ProviderAdapter {
       ...config.env,
       // #557 — the assembler owns the isolated config-home env (CLAUDE_CONFIG_DIR).
       ...assembled.env,
-      // Plain `claude` (isolated profiles) runs its own CLAUDE_CONFIG_DIR and never
-      // routes through claude-rig, so it never inherits the host's long-lived
-      // CLAUDE_CODE_OAUTH_TOKEN. Without it, claude falls back to the (often stale)
-      // file-based .credentials.json and bails to /login (401). claude-rig launches
-      // inject their own token, so only thread it for the plain-claude path, and
-      // never override an explicit per-launch value.
+      // Bare `claude` runs its own CLAUDE_CONFIG_DIR and so never inherits the host's long-lived
+      // CLAUDE_CODE_OAUTH_TOKEN; without it claude falls back to the (often stale) file-based
+      // .credentials.json and bails to /login (401). A custom wrapper command manages its own
+      // token, and an explicit per-launch value always wins.
       ...(command === "claude" && process.env.CLAUDE_CODE_OAUTH_TOKEN && !config.env?.CLAUDE_CODE_OAUTH_TOKEN
         ? { CLAUDE_CODE_OAUTH_TOKEN: process.env.CLAUDE_CODE_OAUTH_TOKEN }
         : {}),
@@ -758,36 +746,13 @@ export class ClaudeAdapter implements ProviderAdapter {
     });
   }
 
-  buildTmuxArgs(config: RunnerSpawnConfig, spawnArgs: SpawnArgs): { sessionName: string; socketName: string; args: string[]; launcherScript: string; gateFifo?: string } {
-    const requestedSessionName = config.tmuxSession || tmuxSessionName(config.providerConfig.headless.tmuxPrefix, config.instanceId, config.label);
-    // Keep the socket derived from the orchestrator's stable identity, but carry
-    // tmux's rendered session name everywhere we later target the pane. Without
-    // this, `opus-4.8` is created as `opus-4_8` and every watcher/restart lookup
-    // immediately misses it.
-    const socketName = tmuxSocketName(requestedSessionName); const sessionName = tmuxSessionTargetName(requestedSessionName);
-    const shellCmd = [spawnArgs.command, ...spawnArgs.args].map(shellQuote).join(" ");
-    const tmuxArgs = ["new-session", "-d", "-s", sessionName, "-x", "200", "-y", "50"];
-
-    const envKeys = tmuxEnvKeys(spawnArgs.env, config.providerConfig.env, this.provider);
-    const env: Record<string, string> = {};
-    for (const key of envKeys) if (relayEnv(spawnArgs.env, key) !== undefined) writeChildEnv(env, { [key]: relayEnv(spawnArgs.env, key)! });
-
-    // Only gate the launch behind pipe-pane attachment when there's a log file to
-    // protect (#1317) — no point serializing dev/interactive spawns that never
-    // read AGENT_RELAY_LOG_FILE.
-    const gateFifo = relayEnv(spawnArgs.env, "AGENT_RELAY_LOG_FILE") ? launcherGatePathForSession(sessionName) : undefined;
-
-    // tmux new-session has a hard command-length limit that includes every argv item,
-    // including `-e KEY=value`. The script holds the command; its private FIFO
-    // carries env values without writing credentials to disk or argv.
-    const launcherScript = writeLauncherScript(sessionName, env, shellCmd, gateFifo, spawnArgs.stdinFile, spawnArgs.exitCodeFile, spawnArgs.envUnset);
-    tmuxArgs.push("-c", spawnArgs.cwd, `bash ${shellQuote(launcherScript)}`);
-    return { sessionName, socketName, args: tmuxArgs, launcherScript, gateFifo };
+  buildTmuxArgs(config: RunnerSpawnConfig, spawnArgs: SpawnArgs): ReturnType<typeof buildClaudeTmuxArgs> {
+    return buildClaudeTmuxArgs(config, spawnArgs, this.provider);
   }
 
   private async spawnHeadless(config: RunnerSpawnConfig, spawnArgs: SpawnArgs): Promise<ManagedProcess> {
     if (spawnArgs.stdinFile && spawnArgs.exitCodeFile && spawnArgs.stdinContents !== undefined) await stageOneShotPrompt(spawnArgs.stdinFile, spawnArgs.exitCodeFile, spawnArgs.stdinContents);
-    const { sessionName, socketName, args: tmuxArgs, launcherScript, gateFifo } = this.buildTmuxArgs(config, spawnArgs);
+    const { sessionName, socketName, args: tmuxArgs, launcherScript, gateFifo, printMode } = this.buildTmuxArgs(config, spawnArgs);
     const providerEpoch = ++this.providerEpoch;
     this.modelUnavailableObservationState = initialClaudeModelUnavailableObservationState();
     this.connectionRetryActive = false;
@@ -802,7 +767,8 @@ export class ClaudeAdapter implements ProviderAdapter {
 
     await createTmuxSessionWithEnv(sessionName, socketName, tmuxArgs, launcherScript, spawnArgs.env, config.providerConfig.env, gateFifo, this.provider);
 
-    this.watchTmuxSession(sessionName, socketName, spawnArgs.exitCodeFile);
+    const exitCodeFile = spawnArgs.exitCodeFile ?? `${launcherScript}.exit-code`;
+    this.watchTmuxSession(sessionName, socketName, exitCodeFile, printMode);
     // #1838 review MED — resolve the pane pid OFF the loop now that the session exists and cache
     // it, so the synchronous resolveBusyPid() never has to shell out on a hot busy edge. Fenced
     // on providerEpoch so a resolve that lands after a restart can't stamp a stale pid.
@@ -832,14 +798,15 @@ export class ClaudeAdapter implements ProviderAdapter {
         tmuxSession: sessionName,
         tmuxSocket: socketName,
         launcherScript,
-        ...claudeEffortSwitchMeta(this.provider, config, Boolean(spawnArgs.exitCodeFile)),
-        ...(spawnArgs.exitCodeFile ? { oneShotExitCodeFile: spawnArgs.exitCodeFile } : {}),
+        exitCodeFile,
+        ...claudeEffortSwitchMeta(this.provider, config, printMode),
+        printMode,
         providerEpoch,
       },
     };
   }
 
-  private watchTmuxSession(sessionName: string, socketName?: string, oneShotExitCodeFile?: string): void {
+  private watchTmuxSession(sessionName: string, socketName?: string, exitCodeFile?: string, oneShot = false): void {
     if (this.tmuxWatcher) clearInterval(this.tmuxWatcher);
     // #1838 row 12 — the highest-frequency blocking site in the runner (every 2s for the
     // agent's whole lifetime). Its two tmux subprocesses (has-session + capture-pane) now run
@@ -849,6 +816,7 @@ export class ClaudeAdapter implements ProviderAdapter {
     // probe on the same pane. `this.tmuxWatcher !== watcher` still fences a predecessor tick
     // whose session was replaced by a respawn.
     let tickInFlight = false;
+    let lastPane = "";
     const watcher = setInterval(() => {
       if (this.tmuxWatcher !== watcher || tickInFlight) return;
       tickInFlight = true;
@@ -866,7 +834,7 @@ export class ClaudeAdapter implements ProviderAdapter {
           // confirm itself only returns true when BOTH reads are `absent` (#1838 HIGH-2).
           const gone = await confirmTmuxSessionGone(sessionName, socketName).catch(() => false);
           if (this.tmuxWatcher !== watcher || !gone) return;
-          const exitStatus = await claudeOneShotExitStatus(oneShotExitCodeFile);
+          const exitStatus = await claudeLaunchExitStatus(exitCodeFile, this.startupReadyObserved, oneShot, lastPane);
           if (this.tmuxWatcher !== watcher) return;
           clearInterval(watcher); this.tmuxWatcher = undefined; this.publishConfirmedTmuxExit(exitStatus);
           return;
@@ -879,6 +847,7 @@ export class ClaudeAdapter implements ProviderAdapter {
         }
         // #1838 HIGH-1: fence again after the capture await, before any observation/status emit.
         if (this.tmuxWatcher !== watcher) return;
+        lastPane = pane;
         // A reused tmux pane can leave an old ready footer in scrollback. Until the
         // current launch is visibly ready, derive both readiness and modal state
         // from the visible grid. After that, avoid an extra capture every tick.
@@ -938,7 +907,7 @@ export class ClaudeAdapter implements ProviderAdapter {
     this.tmuxWatcher = watcher;
   }
 
-  private publishConfirmedTmuxExit(status: "offline" | "error"): void {
+  private publishConfirmedTmuxExit(status: ProviderStatusUpdate): void {
     // The pane and turn pollers are independent. Invalidate the turn generation BEFORE publishing
     // the terminal edge so an in-flight incarnation/activity read cannot land a later idle and
     // resurrect the row with its shutting-down lifecycle pill still latched (#2505).
@@ -962,7 +931,7 @@ export class ClaudeAdapter implements ProviderAdapter {
     const socketName = process.meta?.tmuxSocket as string | undefined;
     const turnWatchResume = this.turnWatchResume?.process === process ? this.turnWatchResume : undefined;
     this.statusWatchersStopped = false;
-    if (sessionName) this.watchTmuxSession(sessionName, socketName, process.meta?.oneShotExitCodeFile as string | undefined);
+    if (sessionName) this.watchTmuxSession(sessionName, socketName, process.meta?.exitCodeFile as string | undefined, process.meta?.printMode === true);
     if (turnWatchResume) await this.beginMonitorlessTurnWatch(process, turnWatchResume.sessionName, turnWatchResume.socketName, false);
   }
 
@@ -1058,22 +1027,6 @@ export { claudeActivityFromProbeAndPane, claudePaneLooksReady, claudePaneIsBusy,
 // Shared shell-quoting; re-exported so `./claude` consumers + tests resolve it.
 export { shellQuote };
 
-export function findClaudeRigRC(cwd: string): string | null {
-  const home = homedir();
-  let dir = resolve(cwd);
-  while (true) {
-    // Stop at $HOME without inspecting it: ~/.claude-rig is the claude-rig tool's
-    // own config home, not a per-project rc marker. Matching it would make every
-    // project under $HOME look like a claude-rig project.
-    if (dir === home) return null;
-    const rc = join(dir, ".claude-rig");
-    if (existsSync(rc)) return rc;
-    const parent = resolve(dir, "..");
-    if (parent === dir) return null;
-    dir = parent;
-  }
-}
-
 async function terminateSingleProcess(process: ManagedProcess, opts: { graceful: boolean; timeoutMs: number }): Promise<ShutdownOutcome> {
   const proc = process.process;
   if (!proc) return "killed"; // nothing to kill — vacuously terminal

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/lifecycle-milestones.ts

@@ -24,7 +24,7 @@ interface LifecycleMilestoneDeps {
   stopDrainTimer(): void;
   stopSubmitRecoveryPoll(): void;
   stopTaskClaims(): void;
-  stopHttpLiveness(): void;
+  stopLiveness(): void;
   stopCredentials(): void;
   disarmBusyLivenessReconcile(): void;
   disarmBusyReconciler(): void;
@@ -140,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/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/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

@@ -4,13 +4,14 @@ 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, config.providerConfig.command);
+    const auth = await checkProviderAuth(config.provider, undefined, env, resolveLaunchCommand(config.providerConfig.command), config.env);
     if (!auth.ok) throw new Error(auth.reason);
     return spawn(config);
   };
@@ -21,7 +22,7 @@ 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.",
+    recommendedAction: "Resolve the provider startup failure shown above, then restart the runner.",
   } };
 }
 

package/src/runner-core.ts

@@ -11,7 +11,7 @@ import { PromptCommands, promptOrigin } from "./agent-runner/commands/prompt";
 import type { NativeSelfResumeHandoff } from "./native-self-resume";
 import { LifecyclePhase } from "./agent-runner/lifecycle-phase";
 import { startRunnerMcpProxy, runnerWebToolLog, runnerWebSearch, runnerMcpHiddenTools } from "./runner-mcp-proxy";
-import { HttpLiveness } from "./agent-runner/http-liveness";
+import { LivenessExchange } from "./agent-runner/liveness-exchange";
 import { TaskClaims } from "./agent-runner/task-claims";
 import { TurnReport } from "./agent-runner/turn-report";
 import { SessionMirror } from "./agent-runner/session-mirror";
@@ -22,7 +22,7 @@ import { hostname } from "node:os";
 import { resolveEnvLayers, selectProviderConfigEnv } from "@humwick/sdk/child-env";
 import { createHash } from "node:crypto";
 import { join } from "node:path";
-import { type ContextState, type Message, type ProviderState, HELD_FOR_PAYLOAD_KEY, PROVIDER_SUBMIT_UNCONFIRMED, PROXY_AUTH_HOLD_KIND, errMessage, frameSuppressedFromTurn, stringValue } from "@humwick/sdk";
+import { type ContextState, type Message, type ProviderState, HELD_FOR_PAYLOAD_KEY, PROVIDER_SUBMIT_UNCONFIRMED, PROXY_AUTH_HOLD_KIND, errMessage, frameSuppressedFromTurn, relayBusUrl, stringValue } from "@humwick/sdk";
 import { exitRunner } from "./runner-exit";
 import { isResumeWake, ProviderHoldEpisodes } from "./provider-hold";
 import { contextStateFromProbeMetrics, quotaStateFromProbeMetrics } from "@humwick/sdk/context-probe";
@@ -88,7 +88,6 @@ import {
   providerMonitorUnavailableMessage,
   providerStateFromActiveWork,
   registerWithinDeadline,
-  relayBusUrl,
   runnerAgentStatus,
   runnerBusErrorAction,
   runnerMessageMatches,
@@ -218,7 +217,7 @@ export class AgentRunner {
   private terminalProviderExit?: Record<string, unknown>;
   private nativeSelfResume = new NativeSelfResumeTracker();
   private readonly registration: Registration;
-  private readonly httpLiveness: HttpLiveness;
+  private readonly liveness: LivenessExchange;
   private readonly taskClaims: TaskClaims;
   private delivering = false;
   private drainTimer?: Timer;
@@ -367,7 +366,7 @@ export class AgentRunner {
       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(),
-      stopTaskClaims: () => this.taskClaims.stop(), stopHttpLiveness: () => this.httpLiveness.stop(), stopCredentials: () => this.credentials.stop(),
+      stopTaskClaims: () => this.taskClaims.stop(), stopLiveness: () => this.liveness.stop(), stopCredentials: () => this.credentials.stop(),
       disarmBusyLivenessReconcile: () => this.disarmBusyLivenessReconcile(), disarmBusyReconciler: () => this.busyReconciler.disarm(),
       disposeProviderInput: () => this.providerInput.dispose(), disposeParkPosts: () => this.parkPosts.dispose(),
       stopReasoningTail: () => this.sessionMirror.stopReasoningTail(), clearNativeSessionCapture: () => this.sessionMirror.clearNativeSessionCapture(), stopObligationCache: () => this.obligationCache.stop(),
@@ -433,11 +432,11 @@ export class AgentRunner {
     void this.proxy?.refreshTools().catch(() => {});
       },
       resumeLivenessAndPublishRotation: (status, jti) => {
-        this.httpLiveness.resetAuthFailure();
+        this.liveness.resetAuthFailure();
         // An earlier auth failure may have stopped the liveness loop; restart it so the
-        // agent reports live again on the fresh token. startHttpLiveness clears any
+        // agent reports live again on the fresh token. startLiveness clears any
         // existing timer first, so this is safe on the normal (proactive) renew path too.
-        this.startHttpLiveness();
+        this.startLiveness();
         this.pendingTimelineEvent = { status, id: jti, timestamp: Date.now() };
         this.bus.reconnectTransport(status === "runtime-token-reminted" ? "runtime token re-minted" : "runtime token renewed");
         this.publishStatus();
@@ -469,14 +468,14 @@ export class AgentRunner {
       // #2514 — the per-provider config env carries a dedicated-home provider's (claude-b's) own
       // credential, which the quota harvest needs to key its reports under the B subscription.
       providerConfigEnv: () => this.options.providerConfig.env,
-      http: () => this.http,
     });
-    this.httpLiveness = new HttpLiveness({
-      http: this.http, agentId: this.agentId, instanceId: options.instanceId, logIntervalMs: HTTP_LIVENESS_LOG_INTERVAL_MS,
+    this.liveness = new LivenessExchange({
+      http: this.http, bus: () => this.bus, agentId: this.agentId, instanceId: options.instanceId, logIntervalMs: HTTP_LIVENESS_LOG_INTERVAL_MS,
       isStopped: () => this.lifecycle.stopped, isTerminalStatusLatched: () => this.lifecycle.terminalStatusLatched,
       currentStatus: () => this.claims.currentStatus(),
-      publishQuota: () => this.providerQuotaHarvest.publish(),
-      bootstrapUnreadMessages: () => this.bootstrapUnreadMessages(), triggerEffort: () => this.effort.trigger(),
+      sampleQuota: () => this.providerQuotaHarvest.sample(),
+      acceptQuota: (report, result) => this.providerQuotaHarvest.accept(report, result),
+      enqueueMessage: (message) => this.enqueueMessage(message), triggerEffort: () => this.effort.trigger(),
       recoverRuntimeTokenAfterAuthFailure: (source) => this.credentials.recoverRuntimeTokenAfterAuthFailure(source),
       logRunnerDiagnostic: (message) => this.logRunnerDiagnostic(message),
     });
@@ -741,7 +740,7 @@ export class AgentRunner {
     }, (status) => this.setProviderStatus(status));
     await this.bootstrapUnreadMessages();
     this.taskClaims.start();
-    this.startHttpLiveness();
+    this.startLiveness();
     this.testRunDedupSweep.start();
     this.credentials.scheduleRuntimeTokenRenewal();
     this.scheduleDrain();
@@ -2861,7 +2860,7 @@ export class AgentRunner {
     if (published && this.pendingTimelineEvent === timelineEvent) this.pendingTimelineEvent = undefined;
   }
 
-  private startHttpLiveness(): void { this.httpLiveness.start(); }
+  private startLiveness(): void { this.liveness.start(); }
 
   private logRunnerDiagnostic(message: string): void { this.context.logRunnerDiagnostic(message); }
   private sessionLog(message: string): void { this.context.sessionLog(message); }

package/src/runner-helpers.ts

@@ -133,14 +133,6 @@ export function csvTags(raw: string | undefined): string[] {
   return (raw || "").split(",").map((tag) => tag.trim()).filter(Boolean);
 }
 
-export function relayBusUrl(relayUrl: string): string {
-  const url = new URL(relayUrl);
-  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
-  url.pathname = `${url.pathname.replace(/\/+$/, "")}/bus`;
-  url.search = "";
-  return url.toString();
-}
-
 export function runnerAgentStatus(status: "idle" | "busy" | "offline" | "error"): "idle" | "busy" | "offline" {
   return status === "error" ? "offline" : status;
 }

package/src/session-scratch.ts

@@ -194,9 +194,13 @@ export function reapSessionScratch(target: SessionScratchTarget): void {
 // scratch dir reap to avoid leaking one file per spawn.
 export function reapSessionLauncher(target: SessionLauncherTarget): string[] {
   const removed: string[] = [];
-  for (const path of dedupePaths([
+  const launchers = dedupePaths([
     target.launcherScript,
     target.tmuxSession ? launcherScriptPathForSession(target.tmuxSession, target.launcherDir) : undefined,
+  ]);
+  for (const path of dedupePaths([
+    ...launchers,
+    ...launchers.flatMap(path => [`${path}.exit-code`, `${path}.exit-code.stderr`]),
     target.tmuxSession ? launcherGatePathForSession(target.tmuxSession, target.launcherDir) : undefined,
   ])) {
     try {
@@ -286,7 +290,7 @@ export async function sweepStaleLaunchersAsync(opts: LauncherSweepOptions): Prom
     try {
       const current = await stat(scriptPath);
       if (!current.isFile() || opts.now - current.mtimeMs < minAge) continue;
-      const agentId = await launcherAgentId(scriptPath);
+      const agentId = await launcherAgentId(scriptPath.replace(/\.exit-code(?:\.stderr)?$/, ""));
       if (agentId && opts.keepAgentIds.has(agentId)) continue;
       await rm(scriptPath, { force: true });
       removed.push(scriptPath);

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

@@ -1,85 +0,0 @@
-import { errMessage, type HumwickHttpClient } from "@humwick/sdk";
-import { httpErrorKey, isHttpAuthError, runnerAgentStatus } from "../runner-helpers";
-import type { ClaimTracker } from "../claim-tracker";
-
-const HTTP_LIVENESS_INTERVAL_MS = 20_000;
-
-interface HttpLivenessDeps {
-  http: Pick<HumwickHttpClient, "heartbeat">;
-  agentId: string;
-  instanceId: string;
-  logIntervalMs: number;
-  isStopped(): boolean;
-  isTerminalStatusLatched(): boolean;
-  currentStatus: ClaimTracker["currentStatus"];
-  publishQuota(): Promise<void>;
-  bootstrapUnreadMessages(): Promise<void>;
-  triggerEffort(): void;
-  recoverRuntimeTokenAfterAuthFailure(source: string): void;
-  logRunnerDiagnostic(message: string): void;
-}
-
-export class HttpLiveness {
-  private httpLivenessTimer?: Timer;
-  private httpLivenessInFlight = false;
-  private httpLivenessAuthFailed = false;
-  private httpLivenessLastLog?: { key: string; at: number };
-
-  constructor(private readonly deps: HttpLivenessDeps) {}
-
-  stop(): void {
-    if (this.httpLivenessTimer) clearInterval(this.httpLivenessTimer);
-    this.httpLivenessTimer = undefined;
-  }
-
-  resetAuthFailure(): void { this.httpLivenessAuthFailed = false; }
-
-  start(): void {
-    if (this.httpLivenessTimer) clearInterval(this.httpLivenessTimer);
-    void this.publishHttpLiveness();
-    this.httpLivenessTimer = setInterval(() => {
-      void this.publishHttpLiveness();
-    }, HTTP_LIVENESS_INTERVAL_MS);
-  }
-
-  private async publishHttpLiveness(): Promise<void> {
-    if (this.deps.isStopped() || this.deps.isTerminalStatusLatched() || this.httpLivenessInFlight || this.httpLivenessAuthFailed) return;
-    this.httpLivenessInFlight = true;
-    const status = this.deps.currentStatus();
-    const agentStatus = runnerAgentStatus(status);
-    try {
-      // #3606 — one call; the hub writes and emits only when status or readiness actually changed.
-      await this.deps.http.heartbeat(this.deps.agentId, this.deps.instanceId, { status: agentStatus, ready: agentStatus !== "offline" });
-      await this.deps.publishQuota().catch((error) => this.deps.logRunnerDiagnostic(`passive provider quota publish failed: ${errMessage(error)}`));
-      await this.deps.bootstrapUnreadMessages(); this.deps.triggerEffort();
-    } catch (error) {
-      if (!this.deps.isStopped()) this.handleHttpLivenessFailure(error);
-    } finally {
-      this.httpLivenessInFlight = false;
-    }
-  }
-
-  private handleHttpLivenessFailure(error: unknown): void {
-    const authFailed = isHttpAuthError(error);
-    this.logHttpLivenessFailure(error, authFailed);
-    if (!authFailed) return;
-    this.httpLivenessAuthFailed = true;
-    if (this.httpLivenessTimer) clearInterval(this.httpLivenessTimer);
-    this.httpLivenessTimer = undefined;
-    // 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 logHttpLivenessFailure(error: unknown, authFailed: boolean): void {
-    const key = httpErrorKey(error);
-    const now = Date.now();
-    if (
-      this.httpLivenessLastLog?.key === key &&
-      now - this.httpLivenessLastLog.at < this.deps.logIntervalMs
-    ) return;
-    this.httpLivenessLastLog = { key, at: now };
-    const suffix = authFailed ? "auth failed; stopping HTTP liveness retries until restart" : String(error);
-    this.deps.logRunnerDiagnostic(`[runner] HTTP liveness update failed: ${suffix}`);
-  }
-}