@humwick/runner 0.0.0-stage → 0.130.1

package/src/provider-double.ts

@@ -0,0 +1,59 @@
+import { writeChildEnv } from "@humwick/sdk/env";
+import type { SpawnProvider } from "@humwick/sdk";
+import type { SpawnArgs } from "./adapter";
+
+export type ProviderProcessRole = "primary" | "tui";
+
+/** The provider-facing invocation after every semantic adapter decision is complete. */
+export interface ProviderInvocation {
+  role: ProviderProcessRole;
+  provider: SpawnProvider;
+  /** The real configured provider command, retained even when a test double executes instead. */
+  logicalCommand: string;
+  /** Final provider argv, forwarded byte-for-byte to the bound executable. */
+  argv: string[];
+  cwd: string;
+  env: Record<string, string>;
+}
+
+export interface ProviderDoubleControl {
+  runId: string;
+  controlRoot: string;
+  deadlineMs: number;
+}
+
+export interface ProviderProcessObservation {
+  transport: "direct" | "claude-tmux";
+  pid?: number;
+  tmuxSession?: string;
+  tmuxSocket?: string;
+}
+
+export interface ProviderDoubleHandle<R> {
+  ready: Promise<void>;
+  result: Promise<R>;
+  stop(reason?: string): Promise<void>;
+}
+
+export interface ProviderDoubleBinding<R> {
+  executable: string;
+  /** Private double control only. This patch is never fed back into semantic assembly. */
+  envPatch: Record<string, string>;
+  observe(started: ProviderProcessObservation): ProviderDoubleHandle<R>;
+}
+
+export interface ProviderDouble<R> {
+  readonly kind: "recorder" | "emulator";
+  prepare(input: ProviderInvocation, control: ProviderDoubleControl): Promise<ProviderDoubleBinding<R>>;
+}
+
+export function primaryProviderInvocation(provider: SpawnProvider, spawnArgs: SpawnArgs): ProviderInvocation {
+  return {
+    role: "primary",
+    provider,
+    logicalCommand: spawnArgs.command,
+    argv: [...spawnArgs.args],
+    cwd: spawnArgs.cwd,
+    env: writeChildEnv({}, { ...spawnArgs.env }),
+  };
+}

package/src/provider-hold.ts

@@ -0,0 +1,228 @@
+import { randomUUID } from "node:crypto";
+import type { Message } from "@humwick/sdk";
+
+/**
+ * #2619 — the provider hold/resume state machine: ONE owner for "the provider refused input, hold,
+ * resume exactly once". Pure (no I/O); runner-core drives it and does the delivery.
+ *
+ * State: the active hold EPISODE (id, or none) and ONE parked queue of refused input. Every
+ * refused input parks here, SYNCHRONOUSLY at the refusal (inside the provider-input FIFO slot,
+ * before any await, so no accepted turn can end the episode in between): inbox messages the
+ * provider refused, and refused prompts (the launch prompt, a dashboard or context injection).
+ * A prompt parks PENDING under its heldPromptKey, then runner-core posts it to the agent's own
+ * inbox (idempotency key = heldPromptKey) and binds the durable row — so it survives a runner
+ * restart exactly like unread messages do. A pending prompt is never replayed (it has no inbox
+ * id yet) but counts as parked, so no generic continue goes out while it exists. A prompt that
+ * cannot be made durable is dropped and the CALLER reports failure. Runner-core keeps its
+ * unconfirmed key on disk so a late push or bootstrap settles a row that did commit.
+ *
+ *   state      | event                                   | transition
+ *   -----------|-----------------------------------------|-------------------------------------------
+ *   open       | refusal (hold raised / input refused)   | → held(E), E a fresh episode id
+ *   held(E)    | refusal                                 | held(E); the input parks (framed, once)
+ *   held(E)    | wake(E), parked idle entries            | replay them (in flight), NO continue
+ *   held(E)    | wake(E), parked all in flight/pending   | settle the wake (a replay is underway, or a
+ *              |                                         | prompt is not durable yet)
+ *   held(E)    | wake(E), parked empty                   | deliver ONE generic continue, re-validated
+ *              |                                         | at the offer: episode ≠ E or park non-empty
+ *              |                                         | by then → settle it silently instead
+ *   any        | wake(X ≠ E), or wake while open         | settle the wake silently — never a continue
+ *   held(E)    | provider accepts a turn                 | → open; idle parked entries replay now
+ *   any        | a parked input is accepted / requeued   | it leaves the park
+ *   any        | a turn is refused AFTER its input was   | that input parks again (reparkAcked), framed,
+ *              | acknowledged (late refusal)             | and replays with its own route like any parked input
+ *   any        | a parked input is refused again         | it stays parked, idle (next wake replays it)
+ *   any        | a pending prompt's row is persisted     | bound: parked idle; in flight now if open
+ *   any        | a pending prompt cannot be persisted    | dropped; the caller fails (durable cancellation in runner-core)
+ *   any        | runner restart                          | → open, park empty: confirmed unread input
+ *              |                                         | redelivers; unconfirmed self-posts settle;
+ *              |                                         | every earlier wake is stale
+ *
+ * The episode id rides on the published hold (ProviderState.holdEpisodeId) and the relay copies it
+ * onto its resume wake, so a wake issued for an episode that has since ended is recognisably stale.
+ */
+
+/** The relay's rate-limit resume wake. */
+export function isResumeWake(message: Message): boolean {
+  return message.payload?.kind === "agent.rate_limit_resume";
+}
+
+/** The hold episode a resume wake was issued for; undefined from a relay that predates episodes. */
+export function resumeWakeEpisode(message: Message): string | undefined {
+  const id = message.payload?.holdEpisodeId;
+  return typeof id === "string" && id ? id : undefined;
+}
+
+export const PROVIDER_HELD_REDELIVERY_NOTE = "[agent-relay] Redelivered after a provider usage-limit hold: the provider refused this message before you could act on it, so it may already appear earlier in your conversation unanswered. Handle it now, exactly once.";
+
+/** A late refusal (the turn started, then the provider refused a later call) does not prove the input never ran. */
+export const PROVIDER_HELD_LATE_REDELIVERY_NOTE = "[agent-relay] Redelivered after a provider usage-limit hold: the provider cut off the turn for this message partway, so you may already have acted on part of it. Check what is already done and continue only the unfinished work, then answer once.";
+
+export type ResumeDecision = { action: "settle" } | { action: "continue" } | { action: "replay"; messages: Message[] };
+
+export class ProviderHoldEpisodes {
+  private episode: string | undefined;
+  private readonly parked = new Map<number, { message: Message; inFlight: boolean }>();
+  private readonly pending = new Map<string, Message>();
+  private provisionalId = 0;
+  private readonly offered = new Map<number, Message>();
+  private readonly unsettled = new Set<number>();
+  private readonly reparked = new Set<number>();
+
+  constructor(private readonly newEpisodeId: () => string = randomUUID) {}
+
+  get activeEpisode(): string | undefined {
+    return this.episode;
+  }
+
+  /** Parked (idle or being replayed): an inbox re-offer of this id must not re-enter the queue. */
+  isParked(id: number): boolean {
+    return this.parked.has(id);
+  }
+
+  /** The provider refused input: opens an episode unless one is active. Returns the episode id. */
+  refused(): string {
+    this.episode ??= this.newEpisodeId();
+    return this.episode;
+  }
+
+  /** Park refused inputs under the active episode, framed once as a redelivery. */
+  park(messages: readonly Message[], note = PROVIDER_HELD_REDELIVERY_NOTE): void {
+    if (messages.length === 0) return;
+    this.refused();
+    for (const message of messages) {
+      // The late note is the stronger claim ("may have partly run"): it replaces the early one, never the reverse.
+      const late = message.body.startsWith(PROVIDER_HELD_LATE_REDELIVERY_NOTE);
+      const early = message.body.startsWith(PROVIDER_HELD_REDELIVERY_NOTE);
+      const bare = early ? message.body.slice(PROVIDER_HELD_REDELIVERY_NOTE.length).replace(/^\n\n/, "") : message.body;
+      const body = late || (early && note === PROVIDER_HELD_REDELIVERY_NOTE) ? message.body : `${note}\n\n${bare}`;
+      this.parked.set(message.id, { message: { ...message, body }, inFlight: false });
+    }
+  }
+
+  /** Remember inputs from the moment they go to the provider until their turn ends: a refusal can be read before the offer settles. */
+  noteOffered(messages: readonly Message[]): void {
+    for (const message of messages) {
+      if (isResumeWake(message)) continue;
+      this.offered.set(message.id, message);
+      this.unsettled.add(message.id);
+    }
+  }
+
+  /** The offer settled: these inputs were not accepted (refused, requeued), so they are no longer in a live turn. */
+  forget(ids: Iterable<number>): void {
+    for (const id of ids) this.offered.delete(id);
+  }
+
+  /** The turn ended (success, refusal, interrupt or error): its input can no longer be refused. */
+  endTurn(): void {
+    this.offered.clear();
+  }
+
+  /** The provider refused the turn these inputs belong to: they may have partly run, so they park again with a check-first note. */
+  reparkAcked(ids: readonly number[]): Message[] {
+    const refused = ids.flatMap((id) => {
+      const message = this.offered.get(id);
+      return message ? [message] : [];
+    });
+    this.park(refused, PROVIDER_HELD_LATE_REDELIVERY_NOTE);
+    for (const message of refused) if (this.unsettled.has(message.id)) this.reparked.add(message.id);
+    this.endTurn();
+    return refused;
+  }
+
+  /** Of an offer's inputs, those a refusal re-parked before the offer settled: they must not be acknowledged. */
+  takeReparked(ids: readonly number[]): Set<number> {
+    for (const id of ids) this.unsettled.delete(id);
+    return new Set(ids.filter((id) => this.reparked.delete(id)));
+  }
+
+  /** Park a refused PROMPT before it is durable (see the header). */
+  parkPending(key: string, message: Omit<Message, "id">): void {
+    this.refused();
+    this.pending.set(key, { ...message, id: --this.provisionalId } as Message);
+  }
+
+  isPending(key: string): boolean {
+    return this.pending.has(key);
+  }
+
+  pendingMessage(key: string): Message | undefined {
+    return this.pending.get(key);
+  }
+
+  /** The pending prompt's inbox row exists: it parks as that row. Returns it when no episode is
+   *  active any more (the provider took a turn meanwhile) — it goes out now, in flight. */
+  bind(key: string, durable: Message): Message[] {
+    if (!this.pending.delete(key)) return [];
+    const episodeEnded = this.episode === undefined;
+    this.park([durable]);
+    if (!episodeEnded) return [];
+    // park() would open an episode no relay hold names — no wake would ever come for it.
+    this.episode = undefined;
+    const entry = this.parked.get(durable.id)!;
+    entry.inFlight = true;
+    return [entry.message];
+  }
+
+  /** The pending prompt could not be made durable: the caller reports failure. */
+  drop(key: string): void {
+    this.pending.delete(key);
+  }
+
+  /** The input was accepted, or handed back to the normal queue: it leaves the park. */
+  unpark(id: number): void {
+    this.parked.delete(id);
+  }
+
+  /** The provider accepted a turn: the episode ends and idle parked input goes out now. */
+  turnAccepted(): Message[] {
+    this.episode = undefined;
+    return this.takeIdle();
+  }
+
+  /** Whether a wake for `episodeId` is for the active episode (a pre-episode relay's wake counts). */
+  isCurrent(episodeId: string | undefined): boolean {
+    return this.episode !== undefined && (episodeId === undefined || episodeId === this.episode);
+  }
+
+  /**
+   * The resume wakes in one drain batch: `batch` is what to deliver (the non-wake work, plus the
+   * replayed parked input, or ONE continue wake), `settle` the wakes to mark read undelivered, and
+   * `replay` the parked input now in flight.
+   */
+  planWakes(messages: readonly Message[]): { batch: Message[]; settle: Message[]; replay: Message[] } {
+    const wakes = messages.filter(isResumeWake);
+    const live = wakes.filter((wake) => this.isCurrent(resumeWakeEpisode(wake)));
+    const decision = live.length > 0 ? this.resume() : { action: "settle" as const };
+    const continueWake = decision.action === "continue" ? live[live.length - 1] : undefined;
+    const replay = decision.action === "replay" ? decision.messages : [];
+    const batch = [...messages.filter((message) => !isResumeWake(message) || message === continueWake), ...replay].sort((a, b) => a.id - b.id);
+    return { batch, settle: wakes.filter((wake) => wake !== continueWake), replay };
+  }
+
+  /**
+   * Re-validation at the offer instant: a planned continue still holds only while its episode is
+   * the active one and nothing is parked (input refused since planning replays instead — next wake).
+   */
+  continueStillValid(wake: Message): boolean {
+    return this.isCurrent(resumeWakeEpisode(wake)) && this.parked.size === 0 && this.pending.size === 0;
+  }
+
+  /** A wake for the active episode (check {@link isCurrent} first). */
+  resume(): ResumeDecision {
+    const messages = this.takeIdle();
+    if (messages.length > 0) return { action: "replay", messages };
+    return this.parked.size > 0 || this.pending.size > 0 ? { action: "settle" } : { action: "continue" };
+  }
+
+  private takeIdle(): Message[] {
+    const idle: Message[] = [];
+    for (const entry of this.parked.values()) {
+      if (entry.inFlight) continue;
+      entry.inFlight = true;
+      idle.push(entry.message);
+    }
+    return idle.sort((a, b) => a.id - b.id);
+  }
+}

package/src/provider-home-marker.ts

@@ -0,0 +1,3 @@
+// Re-export shim (#2547) — the marker moved to the SDK so the runner (writer), the server
+// reaper and the per-orchestrator-host reaper script share one implementation.
+export * from "@humwick/sdk/provider-home-marker";

package/src/provider-home-tombstone.ts

@@ -0,0 +1,4 @@
+// Re-export shim (#2547) — tombstone naming + spawn-side reclaim moved to the SDK so the
+// runner, the server reaper and the per-orchestrator-host reaper script share one
+// implementation of the quarantine name-spaces.
+export * from "@humwick/sdk/provider-home-tombstone";

package/src/provider-input-queue.ts

@@ -0,0 +1,134 @@
+// One agent, ONE provider input stream (#1565 F1).
+//
+// Every payload the runner hands to a provider — a relay message batch, an injected prompt, a
+// self-resume continuation, a memory preamble — ends up in the same place: the provider's single
+// input channel. None of the transports are atomic:
+//
+//   • Claude tmux is paste → sleep → Enter (adapters/claude-tmux.ts). Two concurrent delivers
+//     paste BOTH buffers before either Enter fires, so two payloads are submitted as ONE prompt
+//     plus a stray Enter — the continuity envelope and the memory block merged into each other.
+//   • Codex issues `turn/start` per payload, and a second turn/start on a live turn is dropped by
+//     the app-server. Concurrent delivers both pass the adapter's in-turn guard and one payload is
+//     silently lost — while its command still reports `succeeded`, disarming the relay backstop
+//     that would otherwise re-send it.
+//
+// Nothing upstream serializes this: the relay creates the boundary payloads in one synchronous
+// block, broadcasts them without a queue, and the runner dispatches commands fire-and-forget
+// (`void this.handleCommand(...)`). So the gate belongs here, at the one seam every payload
+// crosses — which fixes the general hazard rather than one pair of payloads.
+//
+// FIFO, AND THE ORDER IS TAKEN SYNCHRONOUSLY. `reserve()` claims a place in the queue with no
+// `await` in between, so a caller that reserves first is served first. That is what makes the
+// ordering guarantee meaningful for the boundary pair: the relay creates the continuation BEFORE
+// the memory block, the bus delivers commands in that order, and the runner reserves in dispatch
+// order — so if only one payload can survive (Codex, one turn), the survivor is the continuation.
+//
+// A ticket that is never released would wedge the stream forever, which is worse than the race it
+// prevents. So every ticket is watchdogged: after `stuckAfterMs` it auto-releases and reports,
+// rather than silently stopping all delivery to the agent.
+
+import { clearTimeout, setTimeout } from "node:timers";
+
+const DEFAULT_STUCK_AFTER_MS = 120_000;
+
+export interface ProviderInputTicket {
+  /** Resolves when it is this ticket's turn. Never rejects. */
+  readonly turn: Promise<void>;
+  /** Hand the stream to the next ticket. Idempotent. */
+  release(): void;
+}
+
+export interface ProviderInputQueueOptions {
+  /** How long a held ticket may block the stream before it is force-released. */
+  stuckAfterMs?: number;
+  /** Reported (never thrown) when a ticket is force-released. */
+  onStuck?: (heldMs: number) => void;
+  /** Timer seam for deterministic watchdog tests. */
+  schedule?: (fn: () => void, ms: number) => () => void;
+}
+
+export class ProviderInputQueue {
+  private tail: Promise<void> = Promise.resolve();
+  private readonly stuckAfterMs: number;
+  private readonly onStuck?: (heldMs: number) => void;
+  private readonly schedule: (fn: () => void, ms: number) => () => void;
+  private readonly watchdogs = new Set<() => void>();
+  private disposed = false;
+  private lastWarningAt?: number;
+
+  constructor(options: ProviderInputQueueOptions = {}) {
+    this.stuckAfterMs = options.stuckAfterMs ?? DEFAULT_STUCK_AFTER_MS;
+    if (options.onStuck) this.onStuck = options.onStuck;
+    // Capture native timers: another subsystem's synchronous timer shim must not expire
+    // a freshly granted slot and feed an immediate delivery/re-arm loop (#2668).
+    this.schedule = options.schedule ?? ((fn, ms) => {
+      const timer = setTimeout(fn, ms);
+      timer.unref();
+      return () => clearTimeout(timer);
+    });
+  }
+
+  /** Cancel outstanding watchdogs when the runner/fixture is torn down. */
+  dispose(): void {
+    this.disposed = true;
+    for (const cancel of this.watchdogs) cancel();
+    this.watchdogs.clear();
+  }
+
+  /**
+   * Take a place in the queue NOW, without awaiting. The caller may do other async work before
+   * awaiting `turn` — its position is already fixed, so arrival order is preserved even when the
+   * work before the delivery takes different amounts of time per payload.
+   */
+  reserve(): ProviderInputTicket {
+    const previous = this.tail;
+    let handOff!: () => void;
+    const held = new Promise<void>((resolve) => { handOff = resolve; });
+    // `previous` is built from settled-on-both-paths handlers below, so it never rejects.
+    this.tail = previous.then(() => held);
+    let released = false;
+    let cancelWatchdog: (() => void) | undefined;
+    const release = (stuck?: number) => {
+      if (released) return;
+      released = true;
+      if (cancelWatchdog) {
+        this.watchdogs.delete(cancelWatchdog);
+        cancelWatchdog();
+        cancelWatchdog = undefined;
+      }
+      handOff();
+      if (stuck !== undefined && !this.disposed) {
+        const now = performance.now();
+        if (this.lastWarningAt === undefined || now - this.lastWarningAt >= Math.max(0, this.stuckAfterMs - 2)) {
+          this.lastWarningAt = now;
+          try { this.onStuck?.(stuck); } catch { /* diagnostics cannot wedge the input stream */ }
+        }
+      }
+    };
+    const turn = previous.then(() => {
+      if (released) return;
+      if (this.disposed) return;
+      cancelWatchdog = this.schedule(() => release(this.stuckAfterMs), this.stuckAfterMs);
+      if (released) cancelWatchdog();
+      else this.watchdogs.add(cancelWatchdog);
+    }, () => {});
+    return { turn, release: () => release() };
+  }
+
+  /**
+   * Run `fn` with exclusive use of the provider's input stream. Pass a `ticket` reserved earlier to
+   * keep that reservation's place in the queue; otherwise a fresh one is taken here.
+   *
+   * Only the delivery itself belongs inside — never the bookkeeping around it — so a slow relay
+   * round-trip cannot hold the stream shut.
+   */
+  async run<T>(fn: () => Promise<T>, ticket?: ProviderInputTicket): Promise<T> {
+    const slot = ticket ?? this.reserve();
+    await slot.turn;
+    try {
+      return await fn();
+    } finally {
+      slot.release();
+    }
+  }
+}

package/src/provider-integration.ts

@@ -0,0 +1,93 @@
+// #3470 — bounded provider bridge; project owned metadata, never user assets or physical paths.
+import { readFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { getManifest } from "@humwick/providers";
+import { sanitizeFsName } from "@humwick/sdk/fs-name";
+import type { RunnerSpawnConfig } from "./adapter";
+import type { ResolvedAsset } from "./provisioning";
+import { providerHomeRootFromEnv } from "./config";
+import { runnerMcpGeneration } from "./relay-mcp";
+import { isRecord, mcpServerInfo, wireToolName, wireToolText, type ProvisioningAssetFile, type ToolGeneration } from "@humwick/sdk";
+
+export const CLAUDE_OWNED_PLUGIN_IDS = ["agent-relay@agent-relay", "humwick@humwick"];
+const OWNED_PLUGIN_NAMES = new Set(["agent-relay", "agent-relay-runner", "humwick", "humwick-runner"]);
+
+function ownedClaudePluginName(dir: string): string | undefined {
+  try { const name = JSON.parse(readFileSync(join(dir, ".claude-plugin/plugin.json"), "utf8")).name; return OWNED_PLUGIN_NAMES.has(name) ? name : undefined; }
+  catch { return undefined; }
+}
+
+export function selectClaudePluginDirs(dirs: string[], generation: ToolGeneration, ownedProvided: boolean): string[] {
+  const entries = [...new Set(dirs)].map(dir => ({ dir, name: ownedClaudePluginName(dir) }));
+  const owned = ownedProvided ? undefined : entries.find(entry => entry.name === mcpServerInfo(generation).name || entry.name === `${mcpServerInfo(generation).name}-runner`) ?? entries.find(entry => entry.name);
+  return entries.filter(entry => !entry.name || entry === owned).map(entry => entry.dir);
+}
+
+export function providerIntegrationFiles(name: string, files: ProvisioningAssetFile[], generation: ToolGeneration): ProvisioningAssetFile[] {
+  if (generation === "relay" || !(name === "agent-relay-claude-plugin" || name.startsWith("agent-relay-codex-"))) return files;
+  return files.map(file => {
+    if (file.path === ".claude-plugin/plugin.json") {
+      const manifest = JSON.parse(file.content);
+      if (OWNED_PLUGIN_NAMES.has(manifest.name)) manifest.name = manifest.name.replace("agent-relay", "humwick");
+      if (typeof manifest.description === "string") manifest.description = manifest.description.replace(/\bAgent Relay\b/g, "Humwick");
+      return { ...file, content: JSON.stringify(manifest, null, 2) };
+    }
+    if (!file.path.endsWith(".md")) return file;
+    return { ...file, content: wireToolText(file.content, generation)
+      .replace(/\bAgent Relay\b/g, "Humwick")
+      .replace(/(?<![\w/.-])agent-relay(?![\w/.-])/g, "humwick") };
+  });
+}
+
+const bundleCache = new Map<string, ProvisioningAssetFile[]>();
+
+// The same manifest overrides as registry seeding make relocated monitors self-contained.
+export function bundledIntegrationAsset(config: RunnerSpawnConfig, source: string, name: string): ResolvedAsset {
+  const generation = runnerMcpGeneration(config.env);
+  if (generation === "relay") return { name, dir: source, source: { kind: "inPlace" } };
+  let files = bundleCache.get(source);
+  if (!files) {
+    const descriptor = getManifest(config.provider)?.provisioning?.bundledPlugin;
+    const overrides = new Map(descriptor?.fileOverrides?.map(file => [file.path, file.sourcePath]) ?? []);
+    const omitted = new Set(descriptor?.omitFiles ?? []);
+    files = [...new Bun.Glob("**/*").scanSync({ cwd: source, dot: true, onlyFiles: true })]
+      .filter(path => !omitted.has(path)).sort().map(path => ({ path, content: readFileSync(join(source, overrides.get(path) ?? path), "utf8") }));
+    bundleCache.set(source, files);
+  }
+  return { name, dir: join(bundledIntegrationHome(config), basename(source)),
+    source: { kind: "files", files: providerIntegrationFiles(name, files, generation) } };
+}
+
+export function bundledIntegrationAssets(config: RunnerSpawnConfig): ResolvedAsset[] {
+  if (config.agentProfile) return [];
+  const provisioning = getManifest(config.provider)?.provisioning;
+  const plugin = provisioning?.bundledPlugin;
+  const packagePath = (path: string) => resolve(import.meta.dir, "..", path.replace(/^runner\//, ""));
+  if (plugin) return [bundledIntegrationAsset(config, packagePath(plugin.dir), plugin.ref)];
+  const skills = provisioning?.bundledSkills;
+  if (!skills) return [];
+  const root = packagePath(skills.dir);
+  return [...new Bun.Glob(`*/${skills.entryFile}`).scanSync({ cwd: root })].sort().map(path => {
+    const leaf = path.split("/")[0]!;
+    return bundledIntegrationAsset(config, join(root, leaf), `${skills.refPrefix}${leaf}`);
+  });
+}
+
+export function suppressOwnedClaudePlugins(enabledPlugins: unknown): Record<string, unknown> {
+  return { ...(enabledPlugins && typeof enabledPlugins === "object" ? enabledPlugins : {}),
+    ...Object.fromEntries(CLAUDE_OWNED_PLUGIN_IDS.map(id => [id, false])) };
+}
+
+export function bundledIntegrationHome(config: RunnerSpawnConfig): string {
+  return join(providerHomeRootFromEnv(), config.provider, "integrations", sanitizeFsName(config.instanceId || config.runnerId));
+}
+
+export function projectClaudePermissionRules(settings: Record<string, unknown>, generation: ToolGeneration): Record<string, unknown> {
+  if (!isRecord(settings.permissions)) return settings;
+  const permissions = { ...settings.permissions };
+  for (const kind of ["allow", "deny", "ask"]) {
+    if (Array.isArray(permissions[kind])) permissions[kind] = permissions[kind].map(rule => typeof rule === "string"
+      ? rule.replace(/^mcp__(?:agent-relay|humwick)__(.*)$/, (_match, tool) => `mcp__${mcpServerInfo(generation).name}__${wireToolName(tool, generation)}`) : rule);
+  }
+  return { ...settings, permissions };
+}

package/src/provider-processes.ts

@@ -0,0 +1,17 @@
+import { isPidAlive, killPid, processTreePids, waitForPidsExit } from "@humwick/sdk/process-utils";
+import type { ShutdownOutcome } from "./adapter";
+
+/** Capture descendants before their parents exit and orphan local MCP/tool children. */
+export async function terminateProviderProcesses(processes: Bun.Subprocess[], opts: { graceful: boolean; timeoutMs: number }, closeInput?: () => void): Promise<ShutdownOutcome> {
+  const roots = processes.map((child) => child.pid).filter((pid) => pid > 0);
+  if (!roots.length) return "killed";
+  const pids = await processTreePids(roots);
+  if (opts.graceful && closeInput) closeInput();
+  else for (const pid of pids) killPid(pid, opts.graceful ? "SIGTERM" : "SIGKILL");
+  if (!await waitForPidsExit(pids, opts.timeoutMs) || pids.some(isPidAlive)) {
+    for (const pid of pids.filter(isPidAlive)) killPid(pid, "SIGKILL");
+    await waitForPidsExit(pids, 1_000);
+  }
+  await Promise.race([Promise.all(processes.map((child) => child.exited.catch(() => {}))), Bun.sleep(1_000)]);
+  return pids.some(isPidAlive) ? "failed-to-kill" : "killed";
+}

package/src/provider-submit-failure.ts

@@ -0,0 +1,15 @@
+/** A provider input may already have reached the TUI when confirmation fails. */
+export class ProviderSubmitFailure extends Error {
+  readonly retrySafe: boolean;
+
+  constructor(message: string, retrySafe: boolean, cause?: unknown) {
+    super(message, { cause });
+    this.name = "ProviderSubmitFailure";
+    this.retrySafe = retrySafe;
+  }
+}
+
+export const PROVIDER_SUBMIT_MAX_DELIVERIES = 3;
+export function providerSubmitRetryDelayMs(attempt: number): number {
+  return Math.min(2_000 * 2 ** (attempt - 1), 30_000);
+}

package/src/providers.ts

@@ -0,0 +1,35 @@
+import { ClaudeApiAdapter } from "./adapters/claude-api";
+import type { LaunchMode, SpawnProvider } from "@humwick/sdk";
+import { getAllManifests, supportedLaunchModesForProvider } from "@humwick/providers";
+import type { ProviderAdapter } from "./adapter";
+import { createClaudeTransportAdapter } from "./adapters/claude-headless";
+import { CodexAdapter } from "./adapters/codex";
+import { OpenCodeAdapter } from "./adapters/opencode";
+
+interface RunnerProviderRegistration {
+  provider: SpawnProvider;
+  createAdapter: (providerArgs: string[], launchMode?: LaunchMode) => ProviderAdapter;
+}
+
+const RUNNER_PROVIDERS: Record<string, RunnerProviderRegistration> = {
+  claude: { provider: "claude", createAdapter: (args, mode) => createClaudeTransportAdapter("claude", args, mode) },
+  // #2513 — claude-b reuses the Claude adapter under its own id (the OpenCodeAdapter/zai
+  // pattern): same binary and launch wiring, its own manifest home/credential.
+  "claude-b": { provider: "claude-b", createAdapter: (args, mode) => createClaudeTransportAdapter("claude-b", args, mode) },
+  "claude-api": { provider: "claude-api", createAdapter: () => new ClaudeApiAdapter() },
+  codex: { provider: "codex", createAdapter: () => new CodexAdapter() },
+  ...Object.fromEntries(
+    getAllManifests()
+      .filter((manifest) => manifest.opencode)
+      .map((manifest) => [manifest.id, { provider: manifest.id, createAdapter: () => new OpenCodeAdapter(manifest.id) }]),
+  ),
+};
+
+export function createProviderAdapter(provider: SpawnProvider, providerArgs: string[] = [], launchMode?: LaunchMode): ProviderAdapter {
+  const registration = RUNNER_PROVIDERS[provider];
+  if (!registration) throw new Error(`unsupported provider adapter: ${provider}`);
+  if (launchMode && !supportedLaunchModesForProvider(provider).includes(launchMode)) {
+    throw new Error(`${provider} does not support launchMode=${launchMode}`);
+  }
+  return registration.createAdapter(providerArgs, launchMode);
+}