@humwick/runner 0.0.0-stage → 0.130.0

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

@@ -0,0 +1,207 @@
+import { errMessage } from "@humwick/sdk";
+import type { ManagedProcess } from "../adapter";
+import { orchestratorBaseDirFromEnv } from "../config";
+import { logger } from "../logger";
+import { PRE_DESTROY_TIMEOUT_MS } from "../session-destroy";
+import { reapSessionLauncher, reapSessionScratch } from "../session-scratch";
+import type { RunnerLaunchOptions } from "./runner-context";
+
+export type StopMilestone = "teardown-started" | "background-stopped" | "provider-shut-down" | "offline-published" | "timers-stopped" | "closed";
+export type RestartMilestone = "work-cleared" | "replacement-adopted" | "launch-seeded" | "teardown-failed";
+
+interface LifecycleMilestoneDeps {
+  options: RunnerLaunchOptions;
+  agentId: string;
+  process(): ManagedProcess | undefined;
+  stopAttachmentCacheSweep(): void;
+  stopTestRunDedupSweep(): void;
+  stopGateRunLeaseProbe(): void;
+  disposeEmptyTurns(): void;
+  resetEmptyTurns(): void;
+  resetLateClearRecovery(): void;
+  clearLifecycleAction(): void;
+  setOffline(): void;
+  publishStatus(): void;
+  stopDrainTimer(): void;
+  stopSubmitRecoveryPoll(): void;
+  stopTaskClaims(): void;
+  stopHttpLiveness(): void;
+  stopCredentials(): void;
+  disarmBusyLivenessReconcile(): void;
+  disarmBusyReconciler(): void;
+  disposeProviderInput(): void;
+  disposeParkPosts(): void;
+  stopReasoningTail(): void;
+  clearNativeSessionCapture(): void;
+  stopObligationCache(): void;
+  closeStores(): void;
+  stopProxy(): void;
+  stopControl(): void;
+  clearTerminalStatus(): void;
+  clearProviderTurnWork(): void;
+  clearSubagentWork(): void;
+  clearBackgroundScriptWork(): void;
+  endLateClearGrace(): void;
+  clearDeliverySubmitHold(): void;
+  clearSubmitFence(): void;
+  clearHeldSubmit(): void;
+  clearSubmitDeliveryAttempts(): void;
+  clearPreDestroyRun(): void;
+  reopenProviderStatus(): void;
+  resumeHeartbeat(): void;
+  settleTerminalTokenUsage(): Promise<void>;
+  closeBus(): Promise<void>;
+  terminalStatusLatched(): boolean;
+  restoreProviderSessionId(value: ReturnType<typeof crypto.randomUUID>): void;
+  restoreLastTranscriptPath(value: string | undefined): void;
+}
+
+export class LifecycleMilestones {
+  constructor(private readonly deps: LifecycleMilestoneDeps) {}
+
+  // Synchronous milestones stay in the caller's stack; only existing I/O boundaries yield.
+  onStop(milestone: "teardown-started" | "offline-published", alreadyStopped: boolean): void;
+  onStop(milestone: "background-stopped" | "timers-stopped"): void;
+  onStop(milestone: "provider-shut-down" | "closed"): Promise<void>;
+  onStop(milestone: StopMilestone, alreadyStopped = false): void | Promise<void> {
+    switch (milestone) {
+      case "teardown-started": return this.teardownStarted(alreadyStopped);
+      case "background-stopped": return this.backgroundStopped();
+      case "provider-shut-down": return this.providerShutDown();
+      case "offline-published": return this.offlinePublished(alreadyStopped);
+      case "timers-stopped": return this.timersStopped();
+      case "closed": return this.closed();
+    }
+  }
+
+  onRestart(milestone: Exclude<RestartMilestone, "teardown-failed">): void;
+  onRestart(milestone: "teardown-failed", priorProviderSessionId: ReturnType<typeof crypto.randomUUID>, priorLastTranscriptPath: string | undefined): Promise<void>;
+  onRestart(milestone: RestartMilestone, priorProviderSessionId?: ReturnType<typeof crypto.randomUUID>, priorLastTranscriptPath?: string): void | Promise<void> {
+    switch (milestone) {
+      case "work-cleared": return this.workCleared();
+      case "replacement-adopted": return this.replacementAdopted();
+      case "launch-seeded": return this.launchSeeded();
+      case "teardown-failed": return this.teardownFailed(priorProviderSessionId!, priorLastTranscriptPath);
+    }
+  }
+
+  private teardownStarted(alreadyStopped: boolean): void {
+    if (!alreadyStopped) this.deps.publishStatus();
+  }
+
+  private backgroundStopped(): void {
+    this.deps.stopAttachmentCacheSweep();
+    this.deps.stopTestRunDedupSweep();
+    this.deps.stopGateRunLeaseProbe();
+    // #2389 — before the shutdown await, not after: an escalation or settle timer firing during a
+    // graceful provider shutdown would publish a "produced nothing" verdict about a turn the
+    // shutdown itself ended.
+    this.deps.disposeEmptyTurns();
+    this.deps.resetLateClearRecovery();
+    const process = this.deps.process();
+    const launcherScript = typeof process?.meta?.launcherScript === "string" ? process.meta.launcherScript : undefined; const tmuxSession = typeof process?.meta?.tmuxSession === "string" ? process.meta.tmuxSession : undefined;
+    reapSessionScratch({ agentId: this.deps.agentId, cwd: this.deps.options.cwd, fallbackBaseDir: orchestratorBaseDirFromEnv() });
+    reapSessionLauncher({ launcherScript, tmuxSession });
+  }
+
+  private async providerShutDown(): Promise<void> {
+    // #2491 review MED-1 — time-boxed like the other two settleTerminalTokenUsage call
+    // sites (restartUnexpectedProviderExit, runPreSessionDestroy): an unsettled capture
+    // must not eat into the graceful-shutdown grace window and push the provider toward a
+    // forced SIGKILL.
+    try {
+      await Promise.race([
+        this.deps.settleTerminalTokenUsage(),
+        new Promise<void>((resolve) => setTimeout(resolve, PRE_DESTROY_TIMEOUT_MS)),
+      ]);
+      await this.deps.options.adapter.shutdown(this.deps.process()!, {
+        graceful: true,
+        timeoutMs: this.deps.options.providerConfig.headless.shutdownTimeoutMs,
+      });
+    } catch (error) {
+      // stop() is already the runner's terminal path. A provider teardown throw is still a
+      // completed attempt: keep going so the terminal frame clears the lifecycle pill and every
+      // timer/outbox/control/bus resource below is closed instead of leaving an orange ghost.
+      logger.error("lifecycle", `provider shutdown during runner stop failed for ${this.deps.agentId}: ${errMessage(error)}`);
+    }
+  }
+
+  private offlinePublished(alreadyStopped: boolean): void {
+    if (!alreadyStopped) {
+      // The terminal edge belongs at teardown completion, not intent. Keeping claims live until
+      // here preserves the dashboard's in-flight pill and the shutdown watchdog. The shared
+      // status projection includes lifecycleAction:null, clearing the server-owned pill on the
+      // same frame that pins the row offline.
+      this.deps.clearLifecycleAction();
+      this.deps.setOffline();
+      this.deps.publishStatus();
+    }
+  }
+
+  private timersStopped(): void {
+    this.deps.stopDrainTimer();
+    this.deps.stopSubmitRecoveryPoll();
+    this.deps.stopTaskClaims();
+    this.deps.stopHttpLiveness();
+    this.deps.stopCredentials();
+    this.deps.disarmBusyLivenessReconcile();
+    this.deps.disarmBusyReconciler();
+    this.deps.disposeProviderInput();
+    this.deps.disposeParkPosts();
+    this.deps.stopReasoningTail();
+    this.deps.clearNativeSessionCapture();
+    this.deps.stopObligationCache();
+  }
+
+  private closed(): Promise<void> {
+    this.deps.closeStores();
+    this.deps.stopProxy();
+    this.deps.stopControl();
+    return this.deps.closeBus();
+  }
+
+  private workCleared(): void {
+    this.deps.clearTerminalStatus();
+    this.deps.clearProviderTurnWork();
+    this.deps.clearSubagentWork();
+    this.deps.clearBackgroundScriptWork();
+    // #2389 — a pre-restart obligation must never be charged against an unrelated post-restart
+    // turn. Covers every restart, including the suppressPrompt one recoverNativeSelfResumeExit
+    // takes, where the agent comes back with no prompt at all.
+    this.deps.resetEmptyTurns();
+  }
+
+  private replacementAdopted(): void {
+    this.deps.endLateClearGrace(); // The installed replacement cannot receive the old /clear.
+  }
+
+  private launchSeeded(): void {
+    // A replacement tmux incarnation can accept new work. The failed inbox row stays
+    // server-side as failed until an operator explicitly retries it.
+    this.deps.clearDeliverySubmitHold();
+    this.deps.stopSubmitRecoveryPoll();
+    this.deps.clearSubmitFence();
+    this.deps.clearHeldSubmit();
+    this.deps.clearSubmitDeliveryAttempts();
+  }
+
+  private async teardownFailed(priorProviderSessionId: ReturnType<typeof crypto.randomUUID>, priorLastTranscriptPath: string | undefined): Promise<void> {
+    const heartbeatNeedsResume = this.deps.terminalStatusLatched();
+    // Restore the surviving process's identity and transcript watermark so its hook frames are
+    // not rejected as stale after the failed teardown. The already-completed restart capture
+    // must NOT survive: this incarnation can produce new content before its eventual shutdown
+    // boundary, which therefore needs a fresh capture.
+    this.deps.restoreProviderSessionId(priorProviderSessionId);
+    this.deps.clearPreDestroyRun();
+    this.deps.restoreLastTranscriptPath(priorLastTranscriptPath);
+    this.deps.reopenProviderStatus();
+    if (heartbeatNeedsResume) this.deps.resumeHeartbeat();
+    if (this.deps.process()) {
+      try {
+        await this.deps.options.adapter.resumeStatusWatchers?.(this.deps.process()!);
+      } catch (error) {
+        logger.error("lifecycle", `failed to resume provider status watchers after restart failure for ${this.deps.agentId}: ${errMessage(error)}`);
+      }
+    }
+  }
+}

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

@@ -0,0 +1,80 @@
+import type { LifecycleAction } from "../session-destroy";
+
+interface LifecyclePhaseDeps {
+  suspendHeartbeat(): void;
+  stopStatusWatchers(): void;
+}
+
+export class LifecyclePhase {
+  private stoppedValue = false;
+  // Provider status is one-way once teardown intent is armed. This fences adapter callbacks,
+  // hooks, watchers and semantic heartbeats, but deliberately does NOT pin the runner projection
+  // offline: runner-owned lifecycle pills remain visible until teardown actually completes.
+  private terminalStatusLatchedValue = false;
+  // #2414: signal intent must suppress restart without skipping stop() teardown.
+  private shuttingDownValue = false;
+  private exitCommandInProgressValue = false;
+  private restartInProgressValue = false;
+  // Set for the whole unexpected-exit restart, including the pre-restart backoff
+  // sleep, so a second exit during that window can't launch a parallel restart.
+  private restartPendingValue = false;
+  private lifecycleActionValue?: LifecycleAction;
+  private lifecycleActionAtValue?: number;
+
+  get stopped(): boolean { return this.stoppedValue; }
+  get shuttingDown(): boolean { return this.shuttingDownValue; }
+  get terminalStatusLatched(): boolean { return this.terminalStatusLatchedValue; }
+  get exitCommandInProgress(): boolean { return this.exitCommandInProgressValue; }
+  get restartInProgress(): boolean { return this.restartInProgressValue; }
+  get restartPending(): boolean { return this.restartPendingValue; }
+  get lifecycleAction(): LifecycleAction | undefined { return this.lifecycleActionValue; }
+  get lifecycleActionAt(): number | undefined { return this.lifecycleActionAtValue; }
+
+  constructor(private readonly deps: LifecyclePhaseDeps) {}
+
+  // #2414: latch synchronously in the signal handler, before child exit callbacks.
+  markShuttingDown(): void {
+    this.shuttingDownValue = true;
+    if (!this.lifecycleActionValue) this.setLifecycleAction("shutting-down");
+    this.armTerminal();
+  }
+
+  beginStop(): boolean {
+    const alreadyStopped = this.stoppedValue;
+    this.stoppedValue = true;
+    if (!alreadyStopped && !this.lifecycleActionValue) this.setLifecycleAction("shutting-down");
+    this.armTerminal();
+    return alreadyStopped;
+  }
+
+  markStopped(): void { this.stoppedValue = true; }
+  beginExitCommand(): void { this.exitCommandInProgressValue = true; }
+  beginRestart(): void { this.restartInProgressValue = true; }
+  finishRestart(): void { this.restartInProgressValue = false; }
+  beginUnexpectedExitRestart(): void { this.restartPendingValue = true; }
+  finishUnexpectedExitRestart(): void { this.restartPendingValue = false; }
+  reopenProviderStatus(): void { this.terminalStatusLatchedValue = false; }
+
+  notePublishedFinalizing(action: LifecycleAction, at: number): void {
+    this.lifecycleActionValue = action;
+    this.lifecycleActionAtValue = at;
+  }
+
+  armTerminal(): void {
+    // One synchronous operation closes every provider-originated status source before any teardown
+    // await opens a resurrection window. Claims stay unpinned until confirmed completion so the
+    // runner's own shutting-down/killing/kill-failed projection remains visible.
+    const alreadyLatched = this.terminalStatusLatchedValue;
+    this.terminalStatusLatchedValue = true;
+    if (!alreadyLatched) {
+      this.deps.suspendHeartbeat();
+      this.deps.stopStatusWatchers();
+    }
+  }
+
+  setLifecycleAction(action: LifecycleAction | undefined): void {
+    if (this.lifecycleActionValue === action) return;
+    this.lifecycleActionValue = action;
+    this.lifecycleActionAtValue = action ? Date.now() : undefined;
+  }
+}

package/src/agent-runner/registration.ts

@@ -0,0 +1,163 @@
+import { writeChildEnv } from "@humwick/sdk/env";
+import { isOpenAiApiModel } from "@humwick/sdk";
+import { harnessSubagentsEnabled } from "@humwick/sdk";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import type { ContextProbeMetrics, ContextState } from "@humwick/sdk";
+import type { ManagedProcess, RunnerSpawnConfig } from "../adapter";
+import type { ControlServer } from "../control-server";
+import { forceContextPctFromEnv, runnerInfoFileFromEnv, runtimeTokenFileFromEnv, workspaceModeFromEnv } from "../config";
+import { appliedAgentProfileMetadata, lifecycleCapabilities, runtimeProviderCapabilities } from "../runner-helpers";
+import type { runtimeMetadata } from "../version";
+import { logger } from "../logger";
+import { providerTerminalSession, providerTerminalSocket } from "../process-meta";
+import type { RunnerLaunchOptions } from "./runner-context";
+
+// #2095 test rig — fallback window used to derive tokensUsed for the forced synthetic context when
+// neither the process context nor the probe reports a tokensMax yet. The absolute value is immaterial
+// (only utilization drives the server thresholds); 200k matches the common Claude window.
+const FORCED_CONTEXT_DEFAULT_WINDOW_TOKENS = 200_000;
+
+interface RegistrationDeps {
+  options: RunnerLaunchOptions;
+  agentId: string;
+  process(): ManagedProcess | undefined;
+  control(): ControlServer | undefined;
+  registeredAt(): number | undefined;
+  latestProbeMetrics(): ContextProbeMetrics | null;
+  sessionLog(message: string): void;
+  flushHeartbeat(): void;
+}
+
+export class Registration {
+  // #2095 self-compact e2e test rig — the one-shot forced-context latch. `forceContextPct` is the
+  // synthetic utilization to report (undefined = feature off, production behavior unchanged);
+  // `forceContextArmed` is disarmed after the FIRST forced compaction/clear command this runner
+  // handles, so exactly one trigger→compact→resume cycle runs (no repeat-compaction loop).
+  private readonly forceContextPct = forceContextPctFromEnv();
+  private forceContextArmed = this.forceContextPct !== undefined;
+
+  constructor(private readonly deps: RegistrationDeps) {}
+
+  disarmForcedContext(type: string): void {
+    // #2095 test rig — one-shot latch: the FIRST forced compaction/clear this runner handles disarms
+    // the synthetic forced context, so the next heartbeat reports the real (post-clear, low)
+    // utilization and no second cycle is triggered. Equivalent to "once lastCompactedAt advances".
+    // No-op unless AGENT_RELAY_FORCE_CONTEXT_PCT armed the latch, so production is untouched.
+    if (this.forceContextArmed && (type === "agent.compact" || type === "agent.clearContext")) {
+      this.forceContextArmed = false;
+      this.deps.sessionLog("AGENT_RELAY_FORCE_CONTEXT_PCT one-shot latch disarmed by forced compaction/clear command");
+      // Flush a heartbeat NOW so the server's stored context drops to the real (sub-threshold) value
+      // immediately. Without this, the ~30s heartbeat cadence lets the stale forced utilization
+      // survive several 10s lifecycle ticks and fire a SECOND forced compaction — breaking the strict
+      // one-shot guarantee. applyForcedContext is already disarmed above, so this beat carries real context.
+      this.deps.flushHeartbeat();
+    }
+  }
+
+  // #2095 self-compact e2e test rig — synthesize a ContextState at the forced utilization while the
+  // one-shot latch is armed. lifecycleState is pinned to "working" (a "compacting"/"hibernating"
+  // state makes the server's handleContextPressure early-return, so the trigger would never fire),
+  // and source/confidence marked estimate/estimated so the origin of the synthetic value is honest.
+  // Everything downstream (advisory, forced clear-inject, clear-commit barrier, resume) is the REAL
+  // path — only the reported utilization is fabricated. No-op unless AGENT_RELAY_FORCE_CONTEXT_PCT set.
+  applyForcedContext(context: ContextState | undefined): ContextState | undefined {
+    if (!this.forceContextArmed || this.forceContextPct === undefined) return context;
+    const pct = this.forceContextPct;
+    const tokensMax = context?.tokensMax ?? this.deps.latestProbeMetrics()?.tokensMax ?? FORCED_CONTEXT_DEFAULT_WINDOW_TOKENS;
+    return {
+      warmTopics: context?.warmTopics ?? [],
+      tasksSinceCompact: context?.tasksSinceCompact ?? 0,
+      ...(context?.lastCompactedAt !== undefined ? { lastCompactedAt: context.lastCompactedAt } : {}),
+      utilization: pct,
+      tokensMax,
+      tokensUsed: Math.round(pct * tokensMax),
+      lifecycleState: "working",
+      source: "estimate",
+      confidence: "estimated",
+      lastUpdatedAt: Date.now(),
+    };
+  }
+
+  writeRunnerInfoFile(): void {
+    const file = runnerInfoFileFromEnv();
+    const control = this.deps.control();
+    if (!file || !control) return;
+    try {
+      mkdirSync(dirname(file), { recursive: true });
+      writeFileSync(file, JSON.stringify({
+        agentId: this.deps.agentId,
+        runnerId: this.deps.options.runnerId,
+        provider: this.deps.options.provider,
+        controlUrl: control.url,
+        runtimeTokenFile: runtimeTokenFileFromEnv(),
+        pid: process.pid,
+        ...(providerTerminalSession(this.deps.process()) ? { tmuxSession: providerTerminalSession(this.deps.process()) } : {}),
+        ...(providerTerminalSocket(this.deps.process()) ? { tmuxSocket: providerTerminalSocket(this.deps.process()) } : {}),
+        startedAt: this.deps.options.startedAt,
+        ...(this.deps.registeredAt() ? { registeredAt: this.deps.registeredAt() } : {}),
+      }, null, 2) + "\n", { mode: 0o600 });
+    } catch (error) {
+      logger.error("runner", `failed to write runner info file: ${error}`);
+    }
+  }
+}
+
+interface IdentitySnapshot {
+  tmuxSession?: string;
+  tmuxSocket?: string;
+  auth?: { profileId?: string; jti?: string; expiresAt?: number };
+  runtime?: ReturnType<typeof runtimeMetadata>;
+  agentId?: string;
+}
+
+/** Preserve the registration, status and heartbeat merge-patch key sets. */
+export function runnerIdentityMeta(options: RunnerLaunchOptions, snapshot: IdentitySnapshot, surface: "registration" | "status" | "heartbeat"): Record<string, unknown> {
+  const { tmuxSession, tmuxSocket } = snapshot;
+  if (surface === "heartbeat") return {
+    ...(tmuxSession ? { tmuxSession } : {}),
+    ...(tmuxSocket ? { tmuxSocket } : {}),
+  };
+  const identity = {
+    runnerId: options.runnerId,
+    startedAt: options.startedAt,
+    tmuxSession: tmuxSession ?? options.tmuxSession ?? null,
+    tmuxSocket: tmuxSocket ?? null,
+    policyName: options.policyName ?? null,
+    spawnRequestId: options.spawnRequestId ?? null,
+    taskId: options.taskId ?? null,
+    automationId: options.automationId ?? null,
+    automationRunId: options.automationRunId ?? null,
+    workspace: options.workspace ?? null,
+    lifecycle: options.lifecycle ?? "persistent",
+    workspaceMode: options.workspace?.requestedMode ?? options.workspace?.mode ?? workspaceModeFromEnv() ?? null,
+    profile: options.profile ?? null,
+    auth: {
+      profileId: snapshot.auth?.profileId ?? null,
+      jti: snapshot.auth?.jti ?? null,
+      expiresAt: snapshot.auth?.expiresAt ?? null,
+      rootTokenFallback: options.rootTokenFallback === true,
+    },
+  };
+  if (surface === "status") return identity;
+  return {
+    ...snapshot.runtime,
+    version: snapshot.runtime!.package.version,
+    provider: options.provider,
+    model: options.model ?? null,
+    ...(isOpenAiApiModel(options.provider, options.model) ? { apiAuthMode: "apiKey", apiBackend: "openai", apiBudgetId: "openai-api", billing: "api" } : {}),
+    effort: options.effort ?? null,
+    // #557 — project the same assembled launch; the pure assembler ignores env/controlPort.
+    agentProfile: options.agentProfile ? appliedAgentProfileMetadata(options.provider, options.agentProfile, { ...options, ...options.launchConfig, agentId: snapshot.agentId, env: {}, controlPort: 0 } as RunnerSpawnConfig, options.providerConfig) : null,
+    ...identity,
+    runnerManaged: true,
+    harnessSubagents: harnessSubagentsEnabled(options),
+    cwd: options.cwd,
+    approvalMode: options.approvalMode,
+    launchMode: options.launchMode ?? null,
+    toolchain: options.toolchain ?? null,
+    label: options.label ?? null,
+    lifecycleCapabilities: lifecycleCapabilities(),
+    providerCapabilities: runtimeProviderCapabilities(options),
+  };
+}

package/src/agent-runner/runner-context.ts

@@ -0,0 +1,158 @@
+import { resolveEnvLayers, selectProviderConfigEnv } from "@humwick/sdk/child-env";
+import { runnerMcpGeneration } from "../relay-mcp";
+import { hostSourcesFor } from "../host-asset-plan";
+import type { AgentLifecycle, AgentProfile, LaunchMode, ProjectToolchain, WorkspaceMetadata } from "@humwick/sdk";
+import { errMessage, HumwickBusClient, HumwickHttpClient, type BusClientOptions, type HttpClientOptions } from "@humwick/sdk";
+import type { ProviderAdapter, ProviderConfig, RunnerSpawnConfig } from "../adapter";
+import type { RunnerRelayInjectionEvent } from "../relay-injection-events";
+import type { RunnerTimelineEvent } from "../turn-reconcile-event";
+import { logLevelFromEnv, sessionDebugEnabled } from "../config";
+import { logger, parseLogLevel } from "../logger";
+
+export interface RunnerOptions {
+  provider: string;
+  model?: string;
+  effort?: string;
+  /** #2595 — effective-catalog window from the spawn payload; threaded into the adapter config. */
+  contextWindowTokens?: number;
+  /** #2599 — the full server-resolved model record (protocol ≥ 2); threaded into the adapter config. */
+  modelRecord?: import("@humwick/sdk/provider-catalog").ResolvedModelRecord;
+  runnerId: string;
+  instanceId: string;
+  agentId?: string;
+  relayUrl: string;
+  token?: string;
+  tokenJti?: string;
+  tokenProfileId?: string;
+  tokenExpiresAt?: number;
+  rootTokenFallback?: boolean;
+  cwd: string;
+  headless: boolean;
+  approvalMode: string;
+  label?: string;
+  rig?: string;
+  profile?: string;
+  harnessSubagents?: boolean;
+  agentProfile?: AgentProfile;
+  prompt?: string;
+  systemPromptAppend?: string;
+  relayInjectionEvents?: RunnerRelayInjectionEvent[];
+  tags: string[];
+  capabilities: string[];
+  providerArgs: string[];
+  /** #2773 — the interactive|headless driver this process was launched with. */
+  launchMode?: LaunchMode;
+  toolchain?: ProjectToolchain;
+  policyName?: string;
+  spawnRequestId?: string;
+  taskId?: number;
+  automationId?: string; automationRunId?: string;
+  workspace?: WorkspaceMetadata; lifecycle?: AgentLifecycle;
+  tmuxSession?: string;
+  startedAt: number;
+  providerConfig: ProviderConfig;
+  /** Provider-owned snapshot loaded before registration for truthful synchronous projection. */
+  launchConfig?: Pick<RunnerSpawnConfig, "hostClaudeConfig" | "hostClaudeSettings">;
+  adapter: ProviderAdapter;
+  // #2443 — `reason`, when present, is a human-readable diagnosis of a terminal provider
+  // failure (e.g. "model-unavailable: APIError 404 ..."), passed through so the caller can print
+  // it before the process actually exits — see handleAdapterStatusChange's call site.
+  onProviderExit?: (code: number | null, reason?: string) => void;
+  exitProcessOnShutdown?: boolean;
+  ports?: { http?: (options: HttpClientOptions) => HumwickHttpClient; bus?: (options: BusClientOptions) => HumwickBusClient };
+}
+
+export type RunnerLaunchOptions = Readonly<Omit<RunnerOptions, "token" | "tokenJti" | "tokenProfileId" | "tokenExpiresAt">>;
+
+interface RunnerContextDeps {
+  providerSessionId(): string;
+  setTimelineEvent(event: RunnerTimelineEvent): void;
+  publishStatus(): void;
+}
+
+export class RunnerContext {
+  readonly options: RunnerLaunchOptions;
+  readonly agentId: string;
+  readonly mcpToolGeneration: ReturnType<typeof runnerMcpGeneration>;
+  http!: HumwickHttpClient;
+  bus!: HumwickBusClient;
+  private readonly sessionDebugVerbose = sessionDebugEnabled();
+
+  constructor(options: RunnerOptions, private readonly deps: RunnerContextDeps) {
+    const { token, tokenJti, tokenProfileId, tokenExpiresAt, ...launch } = options;
+    this.options = Object.freeze(launch);
+    this.mcpToolGeneration = runnerMcpGeneration(resolveEnvLayers([process.env, selectProviderConfigEnv(options.providerConfig.env, hostSourcesFor(options).settings)]));
+    this.agentId = options.agentId ?? options.runnerId;
+  }
+
+  configureLogger(): void {
+    // Keep the verbose session alias; an explicit log level still wins.
+    logger.configure({
+      agentId: this.agentId,
+      headless: this.options.headless,
+      ...(this.sessionDebugVerbose && !parseLogLevel(logLevelFromEnv()) ? { level: "debug" as const } : {}),
+    });
+  }
+
+  initializeHttp(token: string | undefined): void {
+    // Enrolled over registration only; never part of launch options or provider config.
+    this.http = (this.options.ports?.http ?? ((opts) => new HumwickHttpClient(opts)))({ baseUrl: this.options.relayUrl, token });
+  }
+
+  initializeBus(options: BusClientOptions): void {
+    this.bus = (this.options.ports?.bus ?? ((opts) => new HumwickBusClient(opts)))(options);
+  }
+
+  publishRunnerTimelineEvent(event: RunnerTimelineEvent): void {
+    this.deps.setTimelineEvent({
+      ...event,
+      metadata: {
+        source: "runner",
+        provider: this.options.provider,
+        runnerId: this.options.runnerId,
+        agentId: this.agentId,
+        policyName: this.options.policyName ?? null,
+        spawnRequestId: this.options.spawnRequestId ?? null,
+        label: this.options.label ?? null,
+        providerSessionId: this.deps.providerSessionId(),
+        ...(event.metadata ?? {}),
+      },
+    });
+    this.deps.publishStatus();
+  }
+
+  // (#1617) — the reporting half of a guarded fire-and-forget call. Bun exits(1) on an unhandled
+  // rejection and the runner installs no `unhandledRejection` handler, so any `void this.foo()`
+  // whose target can reject takes the whole agent down — and nothing respawns it (#1618).
+  //
+  // Deliberately NOT a fire-and-forget wrapper: the `.catch` still has to be written out at every
+  // call site, so adding one stays a visible decision rather than something a helper hides. All
+  // this fixes is the SHAPE of the report — the same logger.error + publishRunnerTimelineEvent
+  // pair attemptInitialPromptDelivery and the #1614 obligation re-injection already use, so a
+  // background operation that dies is loud on the agent's own timeline instead of vanishing.
+  reportBackgroundRejection(scope: string, status: string, title: string, error: unknown): void {
+    const body = errMessage(error);
+    logger.error("runner", `${scope} failed: ${body}`);
+    this.publishRunnerTimelineEvent({ status, timestamp: Date.now(), title, body });
+  }
+
+  // Runner operational diagnostics (HTTP liveness, token renewal failures). Routed
+  // through the leveled logger at warn — see logger.ts. Kept as a thin wrapper so
+  // the existing call sites and their `[runner]` framing stay put.
+  logRunnerDiagnostic(message: string): void {
+    logger.warn("runner", message.replace(/^\[runner\]\s*/, ""));
+  }
+
+  // Session-mirror diagnostics → the leveled logger (component "mirror"), written
+  // to the dashboard-surfaced session-mirror-<agent>.log. Key transitions log at
+  // info; the single place to look when chat/terminal sync misbehaves.
+  sessionLog(message: string): void {
+    logger.info("mirror", message);
+  }
+
+  // Verbose, high-frequency lines (per-probe, per-emit) — surfaced only at log
+  // level "debug" (AGENT_RELAY_LOG_LEVEL=debug, or flip live via /log-level).
+  sessionDebug(message: string): void {
+    logger.debug("mirror", message);
+  }
+}