@humwick/server 0.130.1 → 0.130.3

package/runner/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/runner/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/runner/src/provider-setup.ts

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

package/runner/src/providers.ts

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

package/runner/src/runner-core.ts

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

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

package/runner/src/test-run-dedup.ts

@@ -1,41 +1,14 @@
 import { relayEnv } from "@humwick/sdk/env";
-// #2142 — per-agent test-run dedup ("latest wins").
-//
-// Workers run `bun run test:affected` after every file change. When a change touches something
-// broad, a single run takes 10-15 minutes — and the agent starts the NEXT run long before the
-// previous one finishes. The stacked runs saturate the host: each one holds a gate slot, forks
-// its own shard processes, and the oldest run's result is thrown away the moment it lands.
-// Instructions don't fix this (an agent rationalizes around them), so the bound has to be
-// structural and live BELOW the agent: the runner watches its own session's process tree and,
-// whenever it sees more than one independent test run, kills every run except the newest.
-//
-// Scoping is per-agent BY CONSTRUCTION: the sweep only ever looks at processes it can PROVE belong
-// to this agent — descendants of this session's provider process (the tmux pane pid / direct child
-// pid the adapter already resolves for busy-liveness), plus processes carrying this agent's
-// AGENT_RELAY_ID in their environment. A sibling agent's runs satisfy neither test, so this can
-// never fratricide the fleet the way a host-wide `pkill -f` would (#753). It is also
-// provider-agnostic — nothing here knows whether the tree belongs to Claude or Codex.
-//
-// #2461 — the env-tag half of that ownership test is new, and it is why this file exists at all
-// after the lease landed. Ancestry ALONE made this a no-op for the case the issue reports: a
-// `relay_run` gate run executes under the ORCHESTRATOR daemon, a tree that shares no ancestor with
-// the provider pane, so a descendant-scoped sweep could never see it. The orchestrator now stamps
-// AGENT_RELAY_ID onto those children, which is what makes them attributable here.
-//
-// This sweep is now the BACKSTOP, not the primary mechanism. Kill-replace happens at LAUNCH, in
-// sdk/src/gate-run-lease.ts, entered from `scripts/gate-slot` and the orchestrator. What is left
-// for the sweep is the residual shape neither front door sees: a gate run started straight from the
-// provider shell in a repo that does not route through `gate.sh`. It is 15s-late by construction —
-// that is the documented coverage gap, tracked for a launch-exact PATH shim in the follow-up issue.
-// When a live lease holder exists it is AUTHORITATIVE: the sweep keeps it and kills the rest, so
-// the two mechanisms can never disagree about which run survives.
+// #3754 — the lease owns launch-time replacement. The sweep only deduplicates
+// unleased runs with the same captured checkout/revision; ancestry proves ownership,
+// but cannot prove two commands tested the same tree. Live leases protect whole runs.
 import { execFile } from "node:child_process";
 import { readFileSync, readdirSync } from "node:fs";
 import { promisify } from "node:util";
 import { errMessage } from "@humwick/sdk";
 import { killPid, waitForPidsExit } from "@humwick/sdk/process-utils";
 import { classifyGateRun, isTestRunCommand, type GateRunCommands } from "@humwick/sdk/gate-run-classify";
-import { GATE_RUN_AGENT_ENV } from "@humwick/sdk/gate-run-lease";
+import { GATE_RUN_AGENT_ENV, GATE_RUN_CONTEXT_ENV, GATE_RUN_HELD_ENV, readLiveGateRunHolderPids } from "@humwick/sdk/gate-run-lease";
 import type { ManagedProcess } from "./adapter";
 
 // Re-exported so the sweep and both lease front doors share ONE definition of "is this a test run".
@@ -215,6 +188,9 @@ export interface TestRunDedupScope {
   /** Classifier override. Defaults to the argv-shape heuristic; the sweep passes a classifier bound
    *  to the repo's CONFIGURED gate commands so a foreign runner (`pnpm tier:run …`) is matched too. */
   isGateRun?: (args: string) => boolean;
+  /** Launch-time checkout/revision identity. Missing identity cannot prove a duplicate. */
+  contextByPid?: ReadonlyMap<number, string>;
+  leasedPids?: readonly number[];
 }
 
 export function planTestRunDedup(
@@ -278,29 +254,34 @@ export function planTestRunDedup(
   }
   if (runRoots.length < 2) return EMPTY_PLAN;
 
-  // Lower elapsed = started later = the run the agent actually wants. `ps etime` only has
-  // second precision, though, and a Codex agent can launch two commands within that second.
-  // Pids are allocated in start order within the host pid namespace, so the higher pid is the
-  // newer root for this otherwise-unresolvable tie. Without this deterministic tie-breaker, two
-  // same-second delivery runs remain tied forever and #2142 fails to bound the exact burst it
-  // was added for. The scope is still this session's process tree only.
-  // A live lease holder wins outright — it is the run the launch-time mechanism already chose. Only
-  // when there is none (an ungated run in a repo without gate.sh) does newest-wins decide.
-  const leaseKeep = scope.keepPid !== undefined && runRoots.includes(scope.keepPid) ? scope.keepPid : undefined;
-  const keptPid = leaseKeep ?? runRoots.reduce((newest, pid) => {
-    const candidate = byPid.get(pid)!;
-    const current = byPid.get(newest)!;
-    return candidate.elapsedSeconds < current.elapsedSeconds
-      || (candidate.elapsedSeconds === current.elapsedSeconds && pid > newest)
-      ? pid
-      : newest;
-  });
-  const newestElapsed = byPid.get(keptPid)!.elapsedSeconds;
-  const staleRoots = runRoots
-    // With a lease holder the age comparison is meaningless — the holder may be the OLDER run, and
-    // it still wins. Without one, keep the original guard so a mis-ranked row is never killed.
-    .filter((pid) => pid !== keptPid && (leaseKeep !== undefined || byPid.get(pid)!.elapsedSeconds >= newestElapsed))
-    .sort((a, b) => a - b);
+  // A lease may belong to a child of the outer shell. Spare the WHOLE run, including
+  // ancestors and descendants, rather than signalling its owner indirectly (#3754).
+  const leased = new Set(scope.leasedPids ?? []);
+  const groups = new Map<string, number[]>();
+  const leasedRoots = new Set<number>();
+  for (const pid of runRoots) {
+    if (subtree(pid).some((child) => leased.has(child))) leasedRoots.add(pid);
+    const context = scope.contextByPid ? scope.contextByPid.get(pid) : "legacy";
+    if (!context) continue;
+    const group = groups.get(context) ?? [];
+    group.push(pid);
+    groups.set(context, group);
+  }
+  const staleRoots: number[] = [];
+  let keptPid: number | undefined;
+  for (const group of groups.values()) {
+    if (group.length < 2) continue;
+    const leaseKeep = scope.keepPid !== undefined && group.includes(scope.keepPid) ? scope.keepPid : undefined;
+    const newest = group.find((pid) => leasedRoots.has(pid)) ?? leaseKeep ?? group.reduce((current, pid) => {
+      const candidate = byPid.get(pid)!;
+      const prior = byPid.get(current)!;
+      return candidate.elapsedSeconds < prior.elapsedSeconds
+        || (candidate.elapsedSeconds === prior.elapsedSeconds && pid > current) ? pid : current;
+    });
+    keptPid = newest;
+    staleRoots.push(...group.filter((pid) => pid !== newest && !leasedRoots.has(pid)));
+  }
+  staleRoots.sort((a, b) => a - b);
   if (staleRoots.length === 0) return EMPTY_PLAN;
 
   const protectedSet = new Set([rootPid, ...protectedPids]);
@@ -334,6 +315,17 @@ export async function readProcessTable(timeoutMs: number = PROCESS_TABLE_TIMEOUT
   return stdout;
 }
 
+/** Only launch-time metadata can distinguish revisions; today's HEAD cannot (#3754). */
+export function readTestRunContext(pid: number): { context?: string; leased?: boolean } {
+  try {
+    const env = Object.fromEntries(readFileSync(`/proc/${pid}/environ`, "utf8").split("\0").map((entry) => {
+      const equals = entry.indexOf("=");
+      return [entry.slice(0, equals), entry.slice(equals + 1)];
+    }));
+    return { context: relayEnv(env, GATE_RUN_CONTEXT_ENV), leased: !!relayEnv(env, GATE_RUN_HELD_ENV) };
+  } catch { return {}; }
+}
+
 export interface TestRunDedupDeps {
   /** Resolve this session's provider pid. undefined ⇒ ancestry proves nothing; the env tag may. */
   rootPid: () => number | undefined;
@@ -344,6 +336,8 @@ export interface TestRunDedupDeps {
   gateCommands?: () => GateRunCommands;
   /** The live lease holder pid, when one exists — authoritative over newest-wins. */
   leaseHolderPid?: () => number | undefined;
+  readRunContext?: (pid: number) => { context?: string; leased?: boolean };
+  liveLeasePids?: () => Promise<number[]>;
   collectOwnedPids?: (agentId: string) => Promise<number[]>;
   readProcessTable?: () => Promise<string>;
   kill?: (pid: number, signal: "SIGTERM" | "SIGKILL") => void;
@@ -374,8 +368,17 @@ export async function runTestRunDedupSweep(deps: TestRunDedupDeps): Promise<numb
   }
 
   const gateCommands = deps.gateCommands?.() ?? {};
-  const plan = planTestRunDedup(parseProcessTable(table), rootPid, deps.protectedPids?.() ?? [], {
-    ownedPids,
+  const rows = parseProcessTable(table);
+  const contextByPid = new Map<number, string>();
+  const leasedPids = await (deps.liveLeasePids ?? (() => agentId ? readLiveGateRunHolderPids(agentId) : Promise.resolve([])))();
+  for (const row of rows) {
+    if (classifyGateRun(row.args, gateCommands) === null) continue;
+    const context = (deps.readRunContext ?? readTestRunContext)(row.pid);
+    if (context.context) contextByPid.set(row.pid, context.context);
+    if (context.leased) leasedPids.push(row.pid);
+  }
+  const plan = planTestRunDedup(rows, rootPid, deps.protectedPids?.() ?? [], {
+    ownedPids, contextByPid, leasedPids,
     keepPid: deps.leaseHolderPid?.(),
     isGateRun: (args) => classifyGateRun(args, gateCommands) !== null,
   });

package/runner/test-support/provisioning-context.ts

@@ -1,3 +1,5 @@
+import { readFileSync } from "node:fs";
+import { getManifest } from "@humwick/providers";
 import type { SpawnProvider } from "@humwick/sdk";
 import type { RunnerSpawnConfig, SpawnArgs } from "../src/adapter";
 import { codexLaunchContext } from "../src/adapters/codex";
@@ -16,8 +18,8 @@ export function systemPromptAppendFromSpawnArgs(
   spawnArgs: Pick<SpawnArgs, "args">,
   runnerConfig: RunnerSpawnConfig,
 ): string {
-  return provider === "claude"
-    ? flagValue(spawnArgs.args, "--append-system-prompt") ?? ""
+  return getManifest(provider)?.shim?.kind === "claude-relay"
+    ? readFileSync(flagValue(spawnArgs.args, "--append-system-prompt-file")!, "utf8")
     : codexLaunchContext({ meta: { config: runnerConfig } }) ?? "";
 }
 

package/runner/test-support/runner-harness.ts

@@ -91,7 +91,8 @@ export class RunnerHttp {
     });
     for (const method of ["listPromptTemplates", "listReplyObligations", "listAgents", "pollMessages"] as const) this.when(method, async () => []);
     this.when("getProviderQuotaConfig", async () => ({}));
-    for (const method of ["setStatus", "setReady", "heartbeat", "markRead"] as const) this.when(method, async () => {});
+    this.when("heartbeat", async () => ({ ok: true, messages: [] }));
+    for (const method of ["setStatus", "setReady", "markRead"] as const) this.when(method, async () => {});
     this.when("recordMessageDeliveryAttempt", async () => ({}) as Awaited<ReturnType<HumwickHttpClient["recordMessageDeliveryAttempt"]>>);
     this.when("claimMessageResult", async () => ({ ok: true, claimExpiresAt: Date.now() + 60_000 }));
     this.when("updateTaskStatus", async () => ({}) as Awaited<ReturnType<HumwickHttpClient["updateTaskStatus"]>>);

package/scripts/cd-config.ts

@@ -172,6 +172,14 @@ export function claimCanonicalDeployLease(input: { commitSha: string; version: s
   return tryBeginDeployEvent(input);
 }
 
+/** A scoped release step borrows its parent's lease, including when deploying a rollback SHA (#3470). */
+export function attachCutoverDeployLease(id: string): DeployEvent {
+  openCanonicalDeployLedger();
+  const event = getDeployEvent(id);
+  if (!event || event.status !== "pending" || !event.initiatedBy.startsWith("humwick-cutover:")) throw new Error(`Not a pending cutover lease: ${id}`);
+  return event;
+}
+
 /**
  * #2105 — stamp THIS driver process onto the lease it just claimed, so cd-watcher's reconcile can
  * reclaim a stranded row on executor liveness (minutes) instead of the 2h lease TTL. Best-effort by

package/scripts/gate-run-lease.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env bun
-import { relayEnv } from "@humwick/sdk/env";
+import { relayEnv, writeChildEnv } from "@humwick/sdk/env";
 /**
  * #2461 — the gate-run lease CLI. ONE implementation of the per-agent single-run invariant.
  *
@@ -49,6 +49,8 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import {
   claimGateRunLease,
+  gateRunContext,
+  GATE_RUN_CONTEXT_ENV,
   gateRunLeaseDir,
   gateRunLeaseEnabled,
   gateRunWasSuperseded,
@@ -136,17 +138,18 @@ export async function claim(options: {
   // here, which is one read and therefore no disagreement.
   const category = carried ?? classifyGateRun(options.command, gateCommandsForCwd(options.cwd));
   if (!category) return { state: "skip", dir: "", epoch: "" };
-  // The directory is a pure function of the agent id and the environment, so it cannot drift
-  // between two calls in the same shell — but a caller that names one is asserting which snapshot
-  // it decided in, and an assertion that does not hold must never publish.
-  if (options.dir && options.dir !== gateRunLeaseDir(agentId, env)) return { state: "skip", dir: "", epoch: "" };
+  // Preflight captured HEAD. Reuse that identity even if the checkout moves before claim (#3754).
+  const carriedContext = options.dir?.split("/").at(-1);
+  const context = options.dir ? (/^[a-f0-9]{64}$/.test(carriedContext ?? "") ? carriedContext : undefined) : gateRunContext(options.cwd);
+  const scopedEnv = writeChildEnv({ ...env }, { [GATE_RUN_CONTEXT_ENV]: context });
+  if (options.dir && options.dir !== gateRunLeaseDir(agentId, scopedEnv)) return { state: "skip", dir: "", epoch: "" };
 
   const handle = await claimGateRunLease({
     agentId,
     category,
     command: options.command,
     selfPid: options.pid,
-    env,
+    env: scopedEnv,
     ...(options.epoch ? { epoch: options.epoch } : {}),
     ...clampedLockWait(env),
     ...(options.log ? { log: options.log } : {}),
@@ -190,7 +193,7 @@ export function preflight(options: { cwd: string; command: string; env?: Record<
   if ((relayEnv(env, GATE_RUN_HELD_ENV) ?? "").trim()) return { state: "nested", dir: gateRunLeaseDir(agentId, env), category: "" };
   const category = classifyGateRun(options.command, gateCommandsForCwd(options.cwd));
   if (!category) return { state: "skip", dir: "", category: "" };
-  return { state: "claim", dir: gateRunLeaseDir(agentId, env), category };
+  return { state: "claim", dir: gateRunLeaseDir(agentId, env, options.cwd), category };
 }
 
 /** A carried category is honoured only if it is one this protocol actually has. Anything else is

package/scripts/gate.sh

@@ -1,6 +1,10 @@
 #!/usr/bin/env sh
 # Explicit override, managed native delegate, then the bundled compatibility launcher.
+# CI runs this checkout's own launcher: the managed delegate execs the host's DEPLOYED runtime,
+# so a broken deploy would turn every CI run red (T7319). Both share the host admission ledger.
 GS="${GATE_SLOT_BIN:-}"
+BUNDLED="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)/gate-slot"
+[ -x "$GS" ] || { [ "${GITHUB_ACTIONS:-}" = true ] && GS="$BUNDLED"; }
 [ -x "$GS" ] || GS="$HOME/.local/bin/gate-slot"
-[ -x "$GS" ] || GS="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)/gate-slot"
+[ -x "$GS" ] || GS="$BUNDLED"
 exec "$GS" "$@"