@humwick/runner 0.0.0-stage → 0.130.0

package/src/liveness.ts

@@ -0,0 +1,105 @@
+import { PROVIDER_TURN_EMPTY_TIMELINE_STATUS, PROVIDER_TURN_WATCHDOG_TIMELINE_STATUS, RECONCILED_TURN_TIMELINE_STATUS } from "@humwick/sdk";
+import type { BusyPhase, LivenessSignal } from "@humwick/sdk";
+
+// #2010 — these timeline statuses are the runner ADMITTING it could not confirm progress (a
+// held-but-unproven turn), an end (a force-cleared one), or — #2389 — a turn that demonstrably
+// produced NOTHING. Folding their `timestamp` in as
+// progress would be circular: the watchdog fires exactly when the runner has NO positive
+// evidence, yet its own publish (`timestamp: now`) would otherwise stamp that same status frame
+// as freshly-progressing, poisoning any consumer (e.g. the server's prolonged-hold coordinator
+// wake, #2010) that reads `lastProgressAt` off it. Every OTHER timeline transition (e.g. Claude's
+// `compacting`) is genuine forward progress and must keep counting.
+// #2389 belongs here most sharply of the three: an empty-turn event is the runner reporting the
+// ABSENCE of output, so stamping its own publish as fresh progress would let the frame that says
+// "this agent did nothing" be read as evidence that it just did something.
+const NON_PROGRESS_TIMELINE_STATUSES: ReadonlySet<string> = new Set([
+  PROVIDER_TURN_WATCHDOG_TIMELINE_STATUS,
+  RECONCILED_TURN_TIMELINE_STATUS,
+  PROVIDER_TURN_EMPTY_TIMELINE_STATUS,
+]);
+
+// The raw runner-tracked signals an adapter folds into a normalized LivenessSignal.
+// This is the INPUT to the contract computation (#746): the runner owns this state
+// (transport frames, the last provider event, the pending timeline transition, the
+// active-work set), passes it to the adapter's `liveness()` verdict, and ships the
+// resulting LivenessSignal on the agent card. Provider-raw interpretation stops here —
+// nothing above the runner ever reads these fields again.
+export interface LivenessInputs {
+  /** Runner→server transport frame/ack timestamps (sdk BusClient.transportState). */
+  transport?: { lastServerFrameAt?: number; lastHeartbeatAckAt?: number };
+  /** Epoch-ms of the most recent provider status/token event the runner observed. */
+  lastProviderEventAt?: number;
+  /** The most recent lifecycle/timeline transition the runner published (status + ts). */
+  timelineEvent?: { status?: string; timestamp?: number };
+  /** Active work records. The adapter classifies its own kinds; `provider-turn` is the
+   *  bare turn, anything else (subagent, background-script, tool, subprocess) is live work. */
+  activeWork: Array<{ kind?: string; startedAt?: number }>;
+  /** Fallback progress floor when no other progress evidence exists yet (e.g. work start). */
+  fallbackProgressAt?: number;
+  /** #1980 — the runner's coarse provider status (`claims.currentStatus()`), used together with
+   *  `providerBlocked` + `activeWork` to derive {@link LivenessSignal.busyPhase}. Provider-agnostic:
+   *  `busy` + a live provider-turn ⇒ `active` (the provider is doing turn work — including a
+   *  token-silent foreground `shell` gate), regardless of which provider. Omitted → no phase. */
+  providerStatus?: "idle" | "busy" | "offline" | "error";
+  /** #1980 — the runner's provider-hold flag (rate-limit / pendingQuestion / a `blocked`
+   *  providerState, e.g. Claude `waiting`). When set, the phase is `blocked` — the provider is
+   *  parked, not actively computing — and takes precedence over `active`. */
+  providerBlocked?: boolean;
+}
+
+function num(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+/**
+ * The shared liveness fold (#725 / #746). Both reference adapters (Claude #713, Codex #724)
+ * route through this so the verdict is computed in ONE place; each adapter's `liveness()`
+ * decides WHICH raw signals it feeds in (Claude surfaces a `compacting` timeline transition
+ * as progress; Codex surfaces live subprocess work-kinds). The fold itself is provider-
+ * agnostic, which is the point of the contract: a new provider only has to feed its signals.
+ */
+export function computeLivenessSignal(inputs: LivenessInputs): LivenessSignal {
+  const transportLiveAt = Math.max(
+    num(inputs.transport?.lastServerFrameAt),
+    num(inputs.transport?.lastHeartbeatAckAt),
+  );
+  // Progress = provider tokens OR a lifecycle/timeline transition (e.g. native compaction,
+  // #713) — whichever is latest, with the caller-supplied floor as the baseline. #2010: a
+  // timeline event that is itself an admission of no-confirmed-progress (the prolonged-hold
+  // watchdog, or a reconciled/force-cleared turn) must NOT count as progress — see
+  // NON_PROGRESS_TIMELINE_STATUSES above.
+  const timelineStatus = inputs.timelineEvent?.status;
+  const timelineProgressAt = timelineStatus !== undefined && NON_PROGRESS_TIMELINE_STATUSES.has(timelineStatus)
+    ? 0
+    : num(inputs.timelineEvent?.timestamp);
+  const lastProgressAt = Math.max(
+    num(inputs.lastProviderEventAt),
+    timelineProgressAt,
+    num(inputs.fallbackProgressAt),
+  );
+  // Any work-kind that is NOT the bare provider turn is live tool/subprocess work (#724):
+  // a wedged provider turn with a live `bun test` child must read as progressing.
+  const hasLiveWork = inputs.activeWork.some((work) => Boolean(work.kind && work.kind !== "provider-turn"));
+  const busyPhase = deriveBusyPhase(inputs, hasLiveWork);
+  return { transportLiveAt, lastProgressAt, hasLiveWork, ...(busyPhase ? { busyPhase } : {}) };
+}
+
+/**
+ * #1980 / #1069 — derive the coarse {@link BusyPhase} from the runner's own state. Provider-
+ * agnostic by construction (the point of the #746 contract): a live `provider-turn` while the
+ * runner status is `busy` is `active` for EVERY provider — for Claude that already covers both
+ * `busy` (thinking) and `shell` (a foreground gate), and for Codex it covers `inProgress`,
+ * because the adapter mints/holds the `provider-turn` work-kind for exactly those states. A
+ * provider hold (`providerBlocked`) is `blocked` and wins over `active` (a parked turn is not
+ * computing). Otherwise, live background-script work with no active turn is `passive` (#1856).
+ * `hasLiveWork` stays the narrower "is there background-script work" projection so its existing
+ * stuck-busy veto (#724, a live `bun test` child during an active turn) is unchanged; `passive`
+ * always implies `hasLiveWork`, but `active` deliberately does not.
+ */
+function deriveBusyPhase(inputs: LivenessInputs, hasLiveWork: boolean): BusyPhase | undefined {
+  if (inputs.providerBlocked) return "blocked";
+  const hasProviderTurn = inputs.activeWork.some((work) => work.kind === "provider-turn");
+  if (inputs.providerStatus === "busy" && hasProviderTurn) return "active";
+  if (hasLiveWork) return "passive";
+  return undefined;
+}

package/src/logger.ts

@@ -0,0 +1,108 @@
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { sanitizeFsName } from "@humwick/sdk/fs-name";
+import { logDirFromEnv, logLevelFromEnv } from "./config";
+import { appendBoundedLog, RUNNER_LOG_MAX_BYTES, RUNNER_LOG_RECORD_MAX_BYTES } from "./bounded-log";
+
+// Phase 1 observability (#198): one leveled, runtime-togglable logger for the
+// Runner and the provider adapters below it. Replaces the ad-hoc scatter of
+// `console.error`, `logRunnerDiagnostic` (-> runner-<agent>.log) and
+// `sessionLog`/`sessionDebug` (-> session-mirror-<agent>.log) with a single
+// switch and a single greppable, ANSI-free sink.
+//
+// Sink: the per-agent `session-mirror-<agent>.log` — the file the orchestrator
+// already surfaces to the dashboard log-viewer (captureSessionMirror). One place
+// to look when anything in the Runner misbehaves.
+//
+// Level is read once from AGENT_RELAY_LOG_LEVEL (default "info") and can be
+// flipped at runtime via the control port (no restart) — so a phase refactor can
+// be watched at debug without bouncing the agent.
+
+type LogLevel = "debug" | "info" | "warn" | "error" | "fatal";
+
+const ORDER: Record<LogLevel, number> = { debug: 10, info: 20, warn: 30, error: 40, fatal: 50 };
+export const LOG_LEVELS = Object.keys(ORDER) as LogLevel[];
+
+export function parseLogLevel(value: string | undefined | null): LogLevel | undefined {
+  if (!value) return undefined;
+  const v = value.trim().toLowerCase();
+  return (LOG_LEVELS as string[]).includes(v) ? (v as LogLevel) : undefined;
+}
+
+// Shared with the orchestrator (session-mirror reader) + runner outbox via the
+// SDK helper, so all sites resolve the identical filename for a given agent id.
+function safeLogName(value: string): string {
+  return sanitizeFsName(value, { replacement: "_", maxLen: 180 });
+}
+
+interface LoggerConfig {
+  agentId?: string;
+  level?: LogLevel;
+  headless?: boolean;
+  logDir?: string;
+  logFileMaxBytes?: number;
+}
+
+export class Logger {
+  private level: LogLevel;
+  private agentId: string;
+  private headless: boolean;
+  private logDir: string;
+  private readonly logFileMaxBytes: number;
+  private initializedPath?: string;
+
+  constructor(config: LoggerConfig = {}) {
+    this.level = config.level ?? parseLogLevel(logLevelFromEnv()) ?? "info";
+    this.agentId = config.agentId ?? "runner";
+    this.headless = config.headless ?? false;
+    this.logDir = config.logDir ?? logDirFromEnv() ?? join(process.env.HOME || ".", ".agent-relay", "logs");
+    this.logFileMaxBytes = config.logFileMaxBytes ?? RUNNER_LOG_MAX_BYTES;
+  }
+
+  // Bind the logger to a concrete agent once the runner knows its id. Preserves a
+  // level already set via env/runtime unless an explicit level is passed.
+  configure(config: LoggerConfig): void {
+    if (config.agentId !== undefined) this.agentId = config.agentId;
+    if (config.headless !== undefined) this.headless = config.headless;
+    if (config.logDir !== undefined) this.logDir = config.logDir;
+    if (config.level !== undefined) this.level = config.level;
+  }
+
+  setLevel(level: LogLevel): void { this.level = level; }
+  getLevel(): LogLevel { return this.level; }
+  isEnabled(level: LogLevel): boolean { return ORDER[level] >= ORDER[this.level]; }
+
+  debug(component: string, message: string): void { this.log("debug", component, message); }
+  info(component: string, message: string): void { this.log("info", component, message); }
+  warn(component: string, message: string): void { this.log("warn", component, message); }
+  error(component: string, message: string): void { this.log("error", component, message); }
+  fatal(component: string, message: string): void { this.log("fatal", component, message); }
+
+  log(level: LogLevel, component: string, message: string): void {
+    if (!this.isEnabled(level)) return;
+    const line = `[${new Date().toISOString()}] ${level.toUpperCase().padEnd(5)} [${component.slice(0, 256)}] ${oneLine(message.slice(0, RUNNER_LOG_RECORD_MAX_BYTES))}${message.length > RUNNER_LOG_RECORD_MAX_BYTES ? " …[truncated]" : ""}\n`;
+    try {
+      const path = join(this.logDir, `session-mirror-${safeLogName(this.agentId)}.log`);
+      const firstWrite = this.initializedPath !== path;
+      if (firstWrite) mkdirSync(this.logDir, { recursive: true });
+      appendBoundedLog(path, line, this.logFileMaxBytes, firstWrite);
+      this.initializedPath = path;
+    } catch {
+      this.initializedPath = undefined;
+      // Best-effort. If the per-agent file can't be written, surface error/fatal to
+      // stderr so it is not lost entirely (headless: lands in the orchestrator log).
+      if (ORDER[level] >= ORDER.error) { try { console.error(line.trimEnd()); } catch { /* give up */ } }
+    }
+  }
+}
+
+// Newlines would split one record across several log lines and break greppability;
+// collapse them so a multi-line message stays one line.
+function oneLine(message: string): string {
+  return message.replace(/\r?\n/g, " ⏎ ");
+}
+
+// Process-global logger. A runner process serves exactly one agent, so a singleton
+// is the right scope; the runner calls configure() once it knows its id, and
+// adapters import this instance directly (no constructor threading).
+export const logger = new Logger();

package/src/mcp-outbox.ts

@@ -0,0 +1,204 @@
+import type { SendMessageInput } from "@humwick/sdk";
+import type { HumwickHttpClient } from "@humwick/sdk";
+import { errMessage, resendOnRotatedToken } from "@humwick/sdk";
+import { relayMcpEndpoint } from "./relay-mcp";
+import type { OutboxRecord } from "./outbox";
+import { deliverContinuationArchiveRecord } from "./continuation-archive";
+import { logger } from "./logger";
+import { isDeterministicClientError, isHttpAuthError, isHttpStatusError } from "./runner-helpers";
+
+interface RunnerOutboxDelivery {
+  record: OutboxRecord;
+  http: HumwickHttpClient;
+  relayUrl: string;
+  getToken?(): string | undefined;
+  updatePayload(seq: number, payload: unknown): void;
+  sessionLog(message: string): void;
+  recoverRuntimeTokenAfterAuthFailure(source: string): void;
+}
+
+export async function deliverRunnerOutboxEvent(input: RunnerOutboxDelivery): Promise<void> {
+  const { record, http } = input;
+  try {
+    if (record.kind === "session-message") {
+      await http.sendMessage({
+        ...(record.payload as SendMessageInput),
+        occurredAt: record.occurredAt,
+        idempotencyKey: record.idempotencyKey,
+      });
+      return;
+    }
+    if (record.kind === "session-message-batch") {
+      const messages = Array.isArray((record.payload as { messages?: unknown }).messages)
+        ? (record.payload as { messages: SendMessageInput[] }).messages
+        : [];
+      const batch = messages.map((message, index) => ({
+        ...message,
+        occurredAt: typeof message.occurredAt === "number" ? message.occurredAt : record.occurredAt,
+        idempotencyKey: message.idempotencyKey ?? `${record.idempotencyKey}:${index}`,
+      }));
+      try {
+        await http.sendMessages(batch);
+      } catch (error) {
+        if (!isDeterministicClientError(error)) throw error;
+        await deliverSessionBatchItems(input, batch);
+      }
+      return;
+    }
+    if (record.kind === "insight") {
+      await http.recordInsightObservation({
+        ...(record.payload as Parameters<HumwickHttpClient["recordInsightObservation"]>[0]),
+        occurredAt: record.occurredAt,
+      });
+      return;
+    }
+    if (record.kind === "continuation-archive") {
+      await deliverContinuationArchiveRecord({
+        record,
+        http,
+        updatePayload: input.updatePayload,
+        sessionLog: input.sessionLog,
+      });
+      return;
+    }
+    if (record.kind === "context-reset") {
+      const { agentId, ...fact } = record.payload as { agentId: string } & Parameters<HumwickHttpClient["recordContextReset"]>[1];
+      await http.recordContextReset(agentId, fact);
+      return;
+    }
+    if (record.kind === "mcp-tool-call") {
+      await deliverBufferedMcpCall(input);
+      return;
+    }
+    logger.warn("outbox", `dropping event with unknown kind: ${record.kind}`);
+  } catch (error) {
+    if (isHttpStatusError(error, 409)) {
+      const reason = errMessage(error);
+      if (record.kind === "session-message-batch") {
+        const messages = sessionBatchMessages(record);
+        logger.error("outbox", `relay reported duplicate session batch; acking row seq=${record.seq} batchKey=${record.idempotencyKey} itemKeys=${sessionBatchItemKeys(record).join(",")} error=${reason}`);
+        await emitMirrorDropNotice(input, messages, messages.length, `duplicate idempotency key: ${reason}`, "duplicate-batch");
+      } else if (record.kind === "session-message") {
+        const message = record.payload as SendMessageInput;
+        logger.error("outbox", `relay reported duplicate session message; acking row seq=${record.seq} key=${record.idempotencyKey} error=${reason}`);
+        await emitMirrorDropNotice(input, [message], 1, `duplicate idempotency key: ${reason}`, "duplicate-message");
+      }
+      return;
+    }
+    if (isHttpAuthError(error)) input.recoverRuntimeTokenAfterAuthFailure("outbox");
+    throw error;
+  }
+}
+
+async function deliverSessionBatchItems(input: RunnerOutboxDelivery, messages: SendMessageInput[]): Promise<void> {
+  const dropped: Array<{ message: SendMessageInput; reason: string }> = [];
+  for (const message of messages) {
+    try {
+      await input.http.sendMessage(message);
+    } catch (error) {
+      if (!isDeterministicClientError(error)) throw error;
+      const reason = errMessage(error);
+      logger.error("outbox", `dropping invalid session batch item key=${message.idempotencyKey ?? "(none)"} error=${reason}`);
+      dropped.push({ message, reason });
+    }
+  }
+  for (const item of dropped) {
+    await emitMirrorDropNotice(input, [item.message], 1, item.reason, "invalid-item");
+  }
+}
+
+// Deterministic session validation rejections are classified once in runner-helpers.ts
+// (isDeterministicClientError) and shared with the outbox poison policy (#2433).
+
+function sessionBatchItemKeys(record: OutboxRecord): string[] {
+  const messages = sessionBatchMessages(record);
+  return messages.map((message, index) => message.idempotencyKey ?? `${record.idempotencyKey}:${index}`);
+}
+
+function sessionBatchMessages(record: OutboxRecord): SendMessageInput[] {
+  return Array.isArray((record.payload as { messages?: unknown }).messages)
+    ? (record.payload as { messages: SendMessageInput[] }).messages
+    : [];
+}
+
+// The subset of RunnerOutboxDelivery the notice seam needs — also satisfied by the narrower
+// Outbox.onPoison call site (#2433), which only holds the poisoned record + the HTTP client.
+type MirrorDropNoticeSource = Pick<RunnerOutboxDelivery, "record"> & { http: HumwickHttpClient };
+
+async function emitMirrorDropNotice(input: MirrorDropNoticeSource, messages: SendMessageInput[], count: number, reason: string, suffix: string): Promise<void> {
+  if (count <= 0) return;
+  const anchor = messages[0];
+  const from = typeof anchor?.from === "string" && anchor.from ? anchor.from : "system";
+  const to = typeof anchor?.to === "string" && anchor.to ? anchor.to : "user";
+  const occurredAt = typeof anchor?.occurredAt === "number" ? anchor.occurredAt : input.record.occurredAt;
+  const body = `${count} steps could not be mirrored: ${reason}`;
+  const idempotencyKey = `session-mirror-drop:${input.record.idempotencyKey}:${suffix}:${shortHash(body)}`;
+  logger.error("outbox", `session mirror drop notice seq=${input.record.seq} count=${count} reason=${reason} noticeKey=${idempotencyKey}`);
+  try {
+    await input.http.sendMessage({
+      from,
+      to,
+      kind: "session",
+      body,
+      idempotencyKey,
+      occurredAt,
+      payload: { session: { type: "notice", origin: "provider", label: "mirror-drop", stepId: idempotencyKey } },
+    });
+  } catch (error) {
+    logger.error("outbox", `failed to emit session mirror drop notice seq=${input.record.seq}; acking original row anyway: ${errMessage(error)}`);
+  }
+}
+
+function shortHash(value: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < value.length; i++) {
+    h ^= value.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return (h >>> 0).toString(36);
+}
+
+// #2433 — the Outbox.onPoison seam for SESSION rows. A permanently-dropped session-message /
+// batch is REAL report-up/mirror loss (chat replyTo lineage rides the session outbox), so
+// surface it in-session through the same notice channel as duplicate/invalid drops instead
+// of only in a FATAL host log. Non-session kinds carry no chat lineage to notify about.
+export async function emitSessionPoisonNotice(input: MirrorDropNoticeSource, reason: string): Promise<void> {
+  const { record } = input;
+  if (record.kind === "session-message-batch") {
+    const messages = sessionBatchMessages(record);
+    await emitMirrorDropNotice(input, messages, messages.length, reason, "poisoned");
+    return;
+  }
+  if (record.kind === "session-message") {
+    await emitMirrorDropNotice(input, [record.payload as SendMessageInput], 1, reason, "poisoned");
+  }
+}
+
+export async function deliverBufferedMcpCall(input: {
+  record: OutboxRecord;
+  relayUrl: string;
+  getToken?(): string | undefined;
+  recoverRuntimeTokenAfterAuthFailure(source: string): void;
+}): Promise<void> {
+  const payload = input.record.payload as { tool: string; arguments: Record<string, unknown> };
+  const body = JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: payload.tool, arguments: payload.arguments } });
+  const response = await resendOnRotatedToken(() => input.getToken?.(), (token) => fetch(relayMcpEndpoint(input.relayUrl), {
+    method: "POST",
+    headers: { "content-type": "application/json", ...(token ? { authorization: `Bearer ${token}` } : {}) },
+    body,
+  }));
+  if (response.status === 401 || response.status === 403) {
+    input.recoverRuntimeTokenAfterAuthFailure("mcp-outbox");
+    throw new Error(`relay rejected buffered ${payload.tool} with ${response.status}`);
+  }
+  if (response.status >= 500) throw new Error(`relay ${response.status} on buffered ${payload.tool}`);
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    logger.warn("mcp-outbox", `buffered ${payload.tool} permanently rejected (${response.status}); dropping: ${body.slice(0, 200)}`);
+    return;
+  }
+  const json = await response.json().catch(() => null) as { error?: { message?: string } } | null;
+  if (json?.error) {
+    logger.warn("mcp-outbox", `buffered ${payload.tool} returned a tool error; dropping: ${json.error.message ?? "(no detail)"}`);
+  }
+}

package/src/mcp-preflight.ts

@@ -0,0 +1,86 @@
+import { existsSync, readFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { basename, isAbsolute } from "node:path";
+import { PORTABLE_SHARED_MCP_SERVER_NAMES, activeSharedMcpServers, portableMcpDescriptorPath, type PortableMcpDescriptor, type ProvisioningMcpServer } from "@humwick/sdk";
+
+// #2729 — a registry descriptor is authored on one host (e.g. the hub's `~/.npm-global/bin/<server>`)
+// but launched on any. A stdio command that does not exist on THIS host would reach the agent as a
+// broken server ("MCP server failed to start (ENOENT)"). A core shared server (tokenlean/...) is
+// swapped for the descriptor this host's orchestrator provisioned (same binary + URL the shared
+// callmux bridge runs); anything else is dropped with a warning.
+
+const SCRIPT_INTERPRETERS = new Set(["node", "bun", "python", "python3", "tsx"]);
+const warned = new Set<string>();
+
+function hasUnresolvedPlaceholder(value: string): boolean {
+  return value.includes("$") || value.startsWith("~");
+}
+
+/**
+ * The first absolute path that makes this stdio descriptor unlaunchable here, or undefined. Only
+ * absolute paths are judged: they are the ones that go stale across hosts. Bare and relative
+ * commands resolve through the provider's own PATH/cwd rules, which are never second-guessed.
+ */
+export function missingMcpExecutable(server: ProvisioningMcpServer): string | undefined {
+  const command = server.command;
+  if (!command || server.url || hasUnresolvedPlaceholder(command)) return undefined;
+  if (isAbsolute(command) && !existsSync(command)) return command;
+  if (!SCRIPT_INTERPRETERS.has(basename(command))) return undefined;
+  const script = server.args?.find((arg) => !arg.startsWith("-"));
+  return script && isAbsolute(script) && !hasUnresolvedPlaceholder(script) && !existsSync(script) ? script : undefined;
+}
+
+export interface McpPreflightOptions {
+  /** This launch carries the shared callmux bridge. */
+  sharedListener: boolean;
+  /** Names exempt from the check (their command is provisioned after launch resolution). */
+  skip?: readonly string[];
+  /** AGENT_RELAY_HOME of this host, where the orchestrator records provisioned core descriptors. */
+  home?: string;
+}
+
+function isCoreName(name: string): boolean {
+  return (PORTABLE_SHARED_MCP_SERVER_NAMES as readonly string[]).includes(name);
+}
+
+function readHostDescriptor(home: string | undefined, name: string): PortableMcpDescriptor | undefined {
+  if (!home || !isCoreName(name)) return undefined;
+  try {
+    const parsed = JSON.parse(readFileSync(portableMcpDescriptorPath(home, name), "utf8")) as PortableMcpDescriptor;
+    return typeof parsed.command === "string" && !missingMcpExecutable(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function warnOnce(name: string, path: string, message: string): void {
+  const key = `${name}\0${path}`;
+  if (warned.has(key)) return;
+  warned.add(key);
+  console.warn(`[runner] MCP server "${name}" on host ${hostname()}: ${path} does not exist here; ${message}`);
+}
+
+export function preflightProvisionedMcpServers(
+  servers: Record<string, ProvisioningMcpServer>,
+  opts: McpPreflightOptions,
+): Record<string, ProvisioningMcpServer> {
+  const kept: Record<string, ProvisioningMcpServer> = {};
+  for (const [name, server] of Object.entries(activeSharedMcpServers(servers))) {
+    const missing = opts.skip?.includes(name) ? undefined : missingMcpExecutable(server);
+    if (!missing) {
+      kept[name] = server;
+      continue;
+    }
+    if (server.serviceAccess?.services.length) throw new Error(`unsupported_execution_boundary:${name}`);
+    const local = readHostDescriptor(opts.home, name);
+    if (local) {
+      const { command: _command, args: _args, env: _env, configEnv: _configEnv, ...rest } = server;
+      kept[name] = { ...rest, command: local.command, ...(local.args ? { args: local.args } : {}), ...(local.env ? { env: local.env } : {}) };
+      warnOnce(name, missing, `using this host's provisioned ${local.command}`);
+      continue;
+    }
+    const viaBridge = opts.sharedListener && isCoreName(name);
+    warnOnce(name, missing, `omitted, ${viaBridge ? "its tools are served by the shared callmux bridge" : "no host-local fallback, so it is not provided to this agent"}`);
+  }
+  return kept;
+}

package/src/mcp-source-selection.ts

@@ -0,0 +1,54 @@
+import type { ProvisioningMcpServer } from "@humwick/sdk";
+import { profileAllowsRelayFeature, type RunnerSpawnConfig } from "./adapter";
+import {
+  launchProvisionedMcpServers,
+  resolveMcpSourceShadows,
+  resolveProjectMcpServers,
+  type ResolvedSourceShadow,
+} from "./provisioning";
+import { isRelayMcpServerName, SHARED_MCP_SERVER_NAME, resolveSharedMcpUrl, sharedMcpBridgeServer } from "./relay-mcp";
+
+export interface McpSourceSelection {
+  /** Higher-priority declarations kept separate for serializers with native host passthrough. */
+  declaredMcp: Record<string, ProvisioningMcpServer>;
+  hostMcp: Record<string, ProvisioningMcpServer>;
+  /** Flattened selection for providers that materialize host and declared servers together. */
+  effectiveMcp: Record<string, ProvisioningMcpServer>;
+  relayEndpoint: boolean;
+  mcpServers: string[];
+  projectServers: string[];
+  hostMcpServers: string[];
+  sharedListenerUrl?: string;
+  sourceShadows: ResolvedSourceShadow[];
+}
+
+// #2368 — providers load their native host declarations, then share this precedence policy.
+// Serialization, service-access overlays and tool deferral consume the selected sources.
+export function resolveMcpSources(
+  config: RunnerSpawnConfig,
+  hostMcp: Record<string, ProvisioningMcpServer>,
+): McpSourceSelection {
+  const provisionedMcp = launchProvisionedMcpServers(config);
+  const mcpServers = Object.keys(provisionedMcp).filter((name) => !isRelayMcpServerName(name));
+  const relayEndpoint = profileAllowsRelayFeature(config, "mcp");
+  const projectMcpRaw = resolveProjectMcpServers(config);
+  const projectMcp = Object.fromEntries(
+    Object.entries(projectMcpRaw).filter(
+      ([name]) => !isRelayMcpServerName(name) && !(name in provisionedMcp),
+    ),
+  );
+  const projectServers = Object.keys(projectMcp);
+
+  // #2114 — sharedMcp is a resolved sibling opt-in, independent of ambient H.mcp.
+  const sharedListenerUrl = config.agentProfile?.sharedMcp ? resolveSharedMcpUrl(config.sharedMcpUrl) : undefined;
+  const sharedMcp: Record<string, ProvisioningMcpServer> = sharedListenerUrl
+    ? { [SHARED_MCP_SERVER_NAME]: sharedMcpBridgeServer(sharedListenerUrl, config.cwd) }
+    : {};
+  const declaredMcp = { ...projectMcp, ...provisionedMcp, ...sharedMcp };
+  const effectiveMcp = { ...hostMcp, ...declaredMcp };
+  const hostMcpServers = Object.keys(hostMcp).filter(
+    (name) => !isRelayMcpServerName(name) && !(name in declaredMcp),
+  );
+  const sourceShadows = resolveMcpSourceShadows(projectMcpRaw, provisionedMcp, hostMcp, declaredMcp, sharedMcp, relayEndpoint);
+  return { declaredMcp, hostMcp, effectiveMcp, relayEndpoint, mcpServers, projectServers, hostMcpServers, sharedListenerUrl, sourceShadows };
+}

package/src/mcp-tool-deferral.ts

@@ -0,0 +1,35 @@
+import { getManifest } from "@humwick/providers";
+import { CODEX_WORKER_ONDEMAND_TOOLS, isCodexLeanWorkerProfile, type AgentProfile } from "@humwick/sdk";
+import { profileWebToolEnabled, WEB_TOOL_NAMES } from "@humwick/sdk/web-tools";
+
+export const META_ONLY_CALLMUX_DEFERRAL_ROUTE = "meta-only-callmux" as const;
+
+/** Resolve the route paired with runner-side manifest narrowing. A declaration that would hide
+ * tools without preserving them downstream is a launch error, never a degraded tool surface. */
+export function runnerManagedToolDeferralRoute(provider: string): typeof META_ONLY_CALLMUX_DEFERRAL_ROUTE | undefined {
+  const manifest = getManifest(provider)?.mcpToolManifest;
+  if (manifest?.runnerManagedToolDeferral !== true) return undefined;
+  if (manifest.runnerManagedToolDeferralRoute !== META_ONLY_CALLMUX_DEFERRAL_ROUTE) {
+    throw new Error(
+      `provider ${provider} declares runnerManagedToolDeferral=true but has no paired meta-only callmux route`,
+    );
+  }
+  return manifest.runnerManagedToolDeferralRoute;
+}
+
+/** The exact production decision for hiding the on-demand Relay set from the direct MCP client. */
+export function runnerManagedRelayOnDemandTools(
+  provider: string,
+  profile: (Pick<AgentProfile, "name" | "sharedMcp" | "webTools"> & { relay?: { mcp?: boolean } }) | undefined,
+): Set<string> | undefined {
+  const route = runnerManagedToolDeferralRoute(provider);
+  if (
+    !route
+    || !isCodexLeanWorkerProfile(profile?.name)
+    || !profile?.sharedMcp
+    || profile.relay?.mcp === false
+    // #3024 — a switched-off web tool keeps the flat bridge (launch-assembly), so nothing fronts this set.
+    || WEB_TOOL_NAMES.some((name) => !profileWebToolEnabled(profile, name))
+  ) return undefined;
+  return new Set(CODEX_WORKER_ONDEMAND_TOOLS);
+}

package/src/mcp-vault-env.ts

@@ -0,0 +1,25 @@
+import { writeChildEnv } from "@humwick/sdk/env";
+import type { ProvisioningMcpServer } from "@humwick/sdk";
+import { shellQuote } from "@humwick/sdk/shell-utils";
+
+/** Codex has env_vars inheritance but no Claude-style interpolation in stdio env. */
+export function codexVaultMcpEnv(server: ProvisioningMcpServer): ProvisioningMcpServer {
+  const env = writeChildEnv({}, { ...server.env });
+  const assignments: string[] = [];
+  const slots = new Set<string>();
+  for (const [key, value] of Object.entries(env)) {
+    const match = /^\$\{(AGENT_RELAY_VAULT_[A-F0-9]{24})\}$/.exec(value);
+    if (!match) continue;
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key) || !server.command) throw new Error("Invalid vault MCP environment projection");
+    assignments.push(`export ${key}="\${${match[1]}:?}"`);
+    slots.add(match[1]!);
+    writeChildEnv(env, {}, [key]);
+  }
+  if (!slots.size) return server;
+  const inherited = Array.isArray(server.env_vars) ? server.env_vars : Object.keys(server.env_vars ?? {});
+  return {
+    ...server, command: "/bin/sh",
+    args: ["-c", `${assignments.join("\n")}\nunset ${[...slots].map(shellQuote).join(" ")}\nexec "$@"`, "relay-mcp", server.command!, ...(server.args ?? [])],
+    env, env_vars: [...new Set([...inherited, ...slots])],
+  };
+}

package/src/message-body-config/config.ts

@@ -0,0 +1,16 @@
+import { relayEnv } from "@humwick/sdk/env";
+export function messageBodyMaxCharsFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_MESSAGE_BODY_MAX_CHARS");
+}
+
+// #1935 — the Claude Code monitor delivery caps (empirically measured against the live harness on
+// 2026-08-02: ~3000 chars per delivered event, ~500 chars per line). Overridable per deployment,
+// since the right ceiling tracks the host's harness build — set on the host/orchestrator that
+// spawns runners. See DEFAULT_MONITOR_DELIVERY_* in adapter.ts for the resolved defaults.
+export function monitorDeliveryMaxCharsFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_MONITOR_DELIVERY_MAX_CHARS");
+}
+
+export function monitorDeliveryLineMaxCharsFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_MONITOR_DELIVERY_LINE_MAX_CHARS");
+}

package/src/message-body-config.ts

@@ -0,0 +1 @@
+export { messageBodyMaxCharsFromEnv, monitorDeliveryMaxCharsFromEnv, monitorDeliveryLineMaxCharsFromEnv } from "./message-body-config/config";