@humwick/runner 0.0.0-stage → 0.130.0

package/src/free-port.ts

@@ -0,0 +1,25 @@
+// #2719 — the ONE free-loopback-port allocator for provider launches.
+//
+// A provider serve port must never be derived from another port: the runner control port
+// comes from the OS (`bind :0`), and `controlPort + 1000` overflows 65535 whenever the OS
+// answers from a high ephemeral range (macOS: 49152-65535).
+
+// The child does not fail loudly on an out-of-range port — it binds a DIFFERENT one, so
+// readiness polling the derived URL times out and the launch dies with no diagnosis. Binding
+// :0 and reading the kernel's own answer is always a valid, currently-free port.
+
+export function allocateLoopbackPort(): number {
+  // Bun binds before serve() returns, so `.port` already holds the kernel-assigned number;
+  // read it BEFORE stop(): the probe reports 0 once closed.
+  const probe = Bun.serve({ port: 0, hostname: "127.0.0.1", fetch: () => new Response(null, { status: 204 }) });
+  try {
+    const port = probe.port;
+    if (typeof port !== "number" || !Number.isInteger(port) || port < 1 || port > 65535) throw new Error(`free-port probe reported an unusable port: ${port}`);
+    return port;
+  } finally {
+    // TOCTOU: the probe closes before the provider binds, so a concurrent launch can still
+    // take the port in between — the same window the server's ephemeral-profile allocator
+    // takes (src/ephemeral/ports.ts), bounded by the provider's own bind/readiness failure.
+    probe.stop(true);
+  }
+}

package/src/fs-offload.ts

@@ -0,0 +1,26 @@
+// Process-scoped, bounded async filesystem work for runner paths that must never pin
+// its event loop. The runner's normal delivery and boot sequencing can enqueue work
+// here without letting a slow host filesystem stall bus frames or timers.
+import { createAsyncRunner, createWorkerPool, type AsyncRunner, type WorkerPool } from "@humwick/offload";
+
+let runner: AsyncRunner | undefined;
+let hostConfigPool: WorkerPool | undefined;
+
+export function runnerFsOffload(): AsyncRunner {
+  return (runner ??= createAsyncRunner({ concurrency: 2 }));
+}
+
+/** Full JSON parse belongs off-thread too: host ~/.claude.json can be tens of MB. */
+export function runnerHostConfigOffload(): WorkerPool {
+  return (hostConfigPool ??= createWorkerPool({
+    worker: new URL("./host-claude-config-worker.js", import.meta.url), size: 1,
+  }));
+}
+
+export async function destroyRunnerFsOffload(): Promise<void> {
+  const current = runner;
+  const currentPool = hostConfigPool;
+  runner = undefined;
+  hostConfigPool = undefined;
+  await Promise.all([current?.destroy(), currentPool?.destroy()]);
+}

package/src/gate-run-config.ts

@@ -0,0 +1,35 @@
+// #2461 — resolve the repo's CONFIGURED gate commands for a runner session's cwd.
+//
+// The backstop sweep used to classify a gate run by argv shape alone, which is why a foreign repo's
+// own runner (`pnpm tier:run static fast` — observed live on wbox) was invisible to it. Relay
+// already knows every repo's real gate commands from `.agent-relay/land-gates.json`; this is the
+// runner-side reader for them. Mirrors orchestrator/src/gate-run-guard.ts's `gateCommandsForCwd` —
+// the two workspaces cannot import each other, and the shared piece that matters (the matching
+// rule) lives in sdk/src/gate-run-classify.ts, so only this four-line projection is repeated.
+import { findRepoLandGatesConfig, resolveIterateCommand } from "@humwick/sdk/land-gates";
+import type { GateRunCommands } from "@humwick/sdk/gate-run-classify";
+
+/** Never throws: a cwd with no (or an unreadable) land-gates config just leaves the heuristic. */
+export function gateRunCommandsForCwd(cwd: string): GateRunCommands {
+  try {
+    const found = findRepoLandGatesConfig(cwd);
+    if (!found) return {};
+    return {
+      iterate: resolveIterateCommand(found.config),
+      delivery: found.config.delivery,
+      gates: found.config.gates.map((gate) => gate.command),
+    };
+  } catch {
+    return {};
+  }
+}
+
+/** Per-cwd memo of {@link gateRunCommandsForCwd}. The config is a repo file: re-reading it every
+ *  15s for an agent's whole life buys nothing, and a change to it means a new checkout anyway. */
+const cache = new Map<string, GateRunCommands>();
+
+export function cachedGateRunCommandsForCwd(cwd: string): GateRunCommands {
+  let commands = cache.get(cwd);
+  if (!commands) { commands = gateRunCommandsForCwd(cwd); cache.set(cwd, commands); }
+  return commands;
+}

package/src/gate-run-lease-probe.ts

@@ -0,0 +1,38 @@
+// #2461 — keep the runner's view of this agent's gate-run LEASE HOLDER fresh, off the dedup sweep's
+// own path. The sweep must not block on a file read plus a `ps` every tick, and the holder only
+// changes when a gate run starts or ends, so a cheap self-arming probe on the same cadence is
+// enough. When a holder exists it is AUTHORITATIVE for the sweep: the launch-time lease already
+// decided which run survives, and the backstop must not independently re-decide.
+import { readLiveGateRunHolderPid } from "@humwick/sdk/gate-run-lease";
+
+export class GateRunLeaseProbe {
+  private timer?: ReturnType<typeof setInterval>;
+  private holderPid: number | undefined;
+
+  constructor(private readonly agentId: string, private readonly intervalMs: number) {}
+
+  /** Last observed holder pid, or undefined when this agent has no live gate run. */
+  pid(): number | undefined {
+    return this.holderPid;
+  }
+
+  start(): void {
+    if (this.timer) return;
+    const probe = () => {
+      void readLiveGateRunHolderPid(this.agentId)
+        .then((pid) => { this.holderPid = pid; })
+        // A failed read must read as "no holder", which returns the sweep to newest-wins rather
+        // than pinning it to a stale pid it can no longer verify.
+        .catch(() => { this.holderPid = undefined; });
+    };
+    probe();
+    this.timer = setInterval(probe, this.intervalMs);
+    this.timer.unref?.();
+  }
+
+  stop(): void {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = undefined;
+    this.holderPid = undefined;
+  }
+}

package/src/host-asset-plan.ts

@@ -0,0 +1,450 @@
+import { CLAUDE_OWNED_PLUGIN_IDS, selectClaudePluginDirs } from "./provider-integration";
+import { runnerMcpGeneration } from "./relay-mcp";
+// #3387 — the host half of a launch plan. Every runner-managed profiled launch runs in a Relay-owned
+// provider home; this module decides, per host asset class, what that home receives from the real
+// host home, and materializes exactly that (removing what an opted-out class left behind on reuse).
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, renameSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { effectiveHostSources, isRecord, type HostSourceClass, type HostSourceSelection, type ToolGeneration } from "@humwick/sdk";
+import type { RunnerSpawnConfig } from "./adapter";
+
+export type HostSourceDisposition = "applied" | "selected-empty" | "disabled" | "unsupported";
+export type HostSourceReport = Record<HostSourceClass, HostSourceDisposition>;
+
+export function hostSourcesFor(config: Pick<RunnerSpawnConfig, "agentProfile">): HostSourceSelection {
+  return effectiveHostSources(config.agentProfile);
+}
+
+/** Central provider defaultArgs are host settings: they reach a launch only with Settings/defaults on. */
+export function hostProviderDefaultArgs(config: Pick<RunnerSpawnConfig, "agentProfile" | "providerConfig">, providerConfig = config.providerConfig): string[] {
+  return hostSourcesFor(config).settings ? providerConfig.defaultArgs : [];
+}
+
+/** A named launch error: a selected host class whose source cannot be honored. Never fall back. */
+export class HostSourceError extends Error {
+  constructor(hostClass: HostSourceClass, path: string, detail: string) {
+    super(`host ${hostClass}: ${detail} (${path})`);
+    this.name = "HostSourceError";
+  }
+}
+
+export function disposition(selected: boolean, applied: boolean): HostSourceDisposition {
+  if (!selected) return "disabled";
+  return applied ? "applied" : "selected-empty";
+}
+
+/** Read a selected JSON source: missing = empty class, unreadable/malformed = named launch error. */
+export function readSelectedJson(hostClass: HostSourceClass, path: string): Record<string, unknown> | undefined {
+  if (!existsSync(path)) return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    throw new HostSourceError(hostClass, path, `unreadable or malformed (${(error as Error).message})`);
+  }
+  if (!isRecord(parsed)) throw new HostSourceError(hostClass, path, "not a JSON object");
+  return parsed;
+}
+
+// ── Claude settings partition ─────────────────────────────────────────────────────────────────
+
+// Keys of the host settings.json that belong to a specific class. Everything else is the residual
+// Settings/defaults class. Relay-owned runtime keys win over every host class in the final writer.
+const CLAUDE_SETTINGS_CLASS: Readonly<Record<string, HostSourceClass>> = {
+  hooks: "hooks",
+  disableAllHooks: "hooks",
+  enabledPlugins: "plugins",
+  extraKnownMarketplaces: "plugins",
+  enableAllProjectMcpServers: "mcp",
+  enabledMcpjsonServers: "mcp",
+  disabledMcpjsonServers: "mcp",
+  claudeMdExcludes: "instructions",
+};
+
+export function claudeSettingsClass(key: string): HostSourceClass {
+  return CLAUDE_SETTINGS_CLASS[key] ?? "settings";
+}
+
+/** The host settings keys of one class. */
+export function claudeHostSettingsFor(settings: Record<string, unknown> | undefined, hostClass: HostSourceClass): Record<string, unknown> {
+  if (!settings) return {};
+  return Object.fromEntries(Object.entries(settings).filter(([key]) => claudeSettingsClass(key) === hostClass));
+}
+
+// ── Claude native plugin registry ─────────────────────────────────────────────────────────────
+
+export interface ClaudeHostPluginRegistry {
+  /** plugins/installed_plugins.json, user-scope entries only. */
+  installed?: Record<string, unknown>;
+  /** plugins/known_marketplaces.json, the marketplaces the kept entries or declarations need. */
+  known?: Record<string, unknown>;
+  /** The plugin-owned settings keys (enabledPlugins / extraKnownMarketplaces), filtered to Host scope. */
+  settings: Record<string, unknown>;
+  /** Kept plugin ids, enabled or not. */
+  ids: string[];
+}
+
+/**
+ * The Host share of Claude's native plugin state: user-scope installs (project/local ones are
+ * Project), their host enablement (a disabled plugin stays disabled) and their marketplaces.
+ * Payload paths stay absolute; only the registry files are private copies.
+ */
+export function selectClaudeHostPlugins(sourceHome: string, hostSettings: Record<string, unknown> | undefined, bridge?: { generation: ToolGeneration; ownedProvided: boolean }): ClaudeHostPluginRegistry {
+  const installedPath = join(sourceHome, "plugins", "installed_plugins.json");
+  const knownPath = join(sourceHome, "plugins", "known_marketplaces.json");
+  const installed = readSelectedJson("plugins", installedPath);
+  const known = readSelectedJson("plugins", knownPath);
+  const pluginSettings = claudeHostSettingsFor(hostSettings, "plugins");
+  const enabled = isRecord(pluginSettings.enabledPlugins) ? pluginSettings.enabledPlugins : {};
+  const keptPlugins: Record<string, unknown[]> = {};
+  if (installed) {
+    if (installed.version !== 2 || !isRecord(installed.plugins)) throw new HostSourceError("plugins", installedPath, `unsupported registry format (version ${String(installed.version)})`);
+    for (const [id, entries] of Object.entries(installed.plugins)) {
+      if (!Array.isArray(entries)) continue;
+      const user = entries.filter((entry) => isRecord(entry) && entry.scope === "user");
+      if (!user.length) continue;
+      keptPlugins[id] = user;
+    }
+  }
+  if (bridge) {
+    const preferred = bridge.generation === "humwick" ? CLAUDE_OWNED_PLUGIN_IDS[1]! : CLAUDE_OWNED_PLUGIN_IDS[0]!;
+    const candidates = [preferred, ...CLAUDE_OWNED_PLUGIN_IDS].filter(id => keptPlugins[id]);
+    const selected = bridge.ownedProvided ? undefined : candidates.find(id => enabled[id] === true) ?? candidates[0];
+    for (const id of CLAUDE_OWNED_PLUGIN_IDS) if (id !== selected) delete keptPlugins[id];
+  }
+  for (const [id, user] of Object.entries(keptPlugins)) {
+    if (enabled[id] === true) {
+      for (const entry of user as Array<Record<string, unknown>>) {
+        if (typeof entry.installPath !== "string" || !existsSync(entry.installPath)) {
+          throw new HostSourceError("plugins", installedPath, `enabled plugin ${id} has no payload at ${String(entry.installPath)}`);
+        }
+      }
+    }
+  }
+  const ids = Object.keys(keptPlugins).sort();
+  const extra = isRecord(pluginSettings.extraKnownMarketplaces) ? pluginSettings.extraKnownMarketplaces : undefined;
+  const marketplaces = new Set([...ids.map((id) => id.slice(id.lastIndexOf("@") + 1)), ...Object.keys(extra ?? {})]);
+  const keptKnown = known ? Object.fromEntries(Object.entries(known).filter(([name]) => marketplaces.has(name))) : {};
+  const keptEnabled = Object.fromEntries(Object.entries(enabled).filter(([id]) => Object.hasOwn(keptPlugins, id)));
+  return {
+    ...(ids.length ? { installed: { ...installed, plugins: keptPlugins } } : {}),
+    ...(Object.keys(keptKnown).length ? { known: keptKnown } : {}),
+    settings: {
+      ...(Object.keys(keptEnabled).length ? { enabledPlugins: keptEnabled } : {}),
+      ...(extra ? { extraKnownMarketplaces: extra } : {}),
+    },
+    ids,
+  };
+}
+
+// ── Host links (instructions, rules, commands, agents) ────────────────────────────────────────
+
+export interface HostLink {
+  hostClass: HostSourceClass;
+  /** Path relative to the managed home. */
+  target: string;
+  /** Absolute host path the link points at. */
+  source: string;
+}
+
+function existing(sourceHome: string, name: string): string | undefined {
+  const path = join(sourceHome, name);
+  return existsSync(path) ? path : undefined;
+}
+
+// Relative `@path` imports in a linked instruction file resolve against the managed home, so the
+// top-level entry each import names is linked beside it.
+function instructionImports(sourceHome: string, file: string): string[] {
+  let text: string;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch {
+    return [];
+  }
+  const names = new Set<string>();
+  for (const match of text.matchAll(/(?:^|\s)@([^\s`'"]+)/g)) {
+    const ref = match[1]!;
+    if (isAbsolute(ref) || ref.startsWith("~") || ref.includes("://")) continue;
+    const resolved = resolve(dirname(file), ref);
+    const inside = relative(sourceHome, resolved);
+    if (!inside || inside.startsWith("..") || isAbsolute(inside) || !existsSync(resolved)) continue;
+    names.add(inside.split(sep)[0]!);
+  }
+  return [...names];
+}
+
+/** Links a Claude home receives for its selected Instructions / Skills / Settings classes. */
+export function claudeHostLinks(sourceHome: string, selection: HostSourceSelection, instructionFiles: string[]): HostLink[] {
+  const links: HostLink[] = [];
+  const add = (hostClass: HostSourceClass, name: string) => {
+    const source = existing(sourceHome, name);
+    if (source && !links.some((link) => link.target === name)) links.push({ hostClass, target: name, source });
+  };
+  if (selection.instructions) {
+    for (const file of instructionFiles) {
+      add("instructions", file);
+      const source = existing(sourceHome, file);
+      if (source) for (const name of instructionImports(sourceHome, source)) add("instructions", name);
+    }
+    add("instructions", "rules");
+  }
+  if (selection.skills) add("skills", "commands");
+  if (selection.settings) add("settings", "agents");
+  return links;
+}
+
+/** Links a Codex home receives for its selected Instructions class. */
+export function codexHostLinks(sourceHome: string, selection: HostSourceSelection, instructionFiles: string[]): HostLink[] {
+  if (!selection.instructions) return [];
+  return instructionFiles.flatMap((file) => {
+    const source = existing(sourceHome, file);
+    return source ? [{ hostClass: "instructions" as const, target: file, source }] : [];
+  });
+}
+
+// The links and host-only registry files a previous launch wrote into this home. Reuse removes
+// whatever the current plan no longer selects, so on→off→on in one home never keeps stale assets.
+const HOST_ASSET_MANIFEST = ".relay-host-assets.json";
+
+interface HostAssetManifest {
+  links: string[];
+  files: string[];
+}
+
+function stringList(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === "string") : [];
+}
+
+function readManifest(home: string): HostAssetManifest {
+  try {
+    const parsed = JSON.parse(readFileSync(join(home, HOST_ASSET_MANIFEST), "utf8")) as unknown;
+    return isRecord(parsed) ? { links: stringList(parsed.links), files: stringList(parsed.files) } : { links: [], files: [] };
+  } catch {
+    return { links: [], files: [] };
+  }
+}
+
+function isSymlink(path: string): boolean {
+  return lstatSync(path, { throwIfNoEntry: false })?.isSymbolicLink() ?? false;
+}
+
+/** Point `target` at `source`, replacing a stale link but never writing through one. */
+function ensureLink(source: string, target: string): void {
+  if (isSymlink(target)) {
+    if (readlinkSync(target) === source) return;
+    unlinkSync(target);
+  } else if (existsSync(target)) {
+    rmSync(target, { recursive: true, force: true });
+  }
+  mkdirSync(dirname(target), { recursive: true });
+  symlinkSync(source, target);
+}
+
+export function writeFileAtomic(path: string, content: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  if (isSymlink(path)) unlinkSync(path);
+  const pending = `${path}.relay-${process.pid}.tmp`;
+  writeFileSync(pending, content, { mode: 0o600 });
+  renameSync(pending, path);
+}
+
+/**
+ * Materialize one plan's host links and generated files after dropping what the previous plan wrote
+ * and this one does not select (a stale link only while still a link). Generated files are copies,
+ * never links. `extraLinks` tracks links another materializer creates (host skills).
+ */
+export function materializeHostAssets(home: string, links: HostLink[], files: Array<{ target: string; content: string }>, extraLinks: string[] = []): void {
+  const next: HostAssetManifest = { links: [...links.map((link) => link.target), ...extraLinks].sort(), files: files.map((file) => file.target).sort() };
+  const previous = readManifest(home);
+  for (const stale of previous.links) {
+    if (!next.links.includes(stale) && isSymlink(join(home, stale))) unlinkSync(join(home, stale));
+  }
+  for (const stale of previous.files) {
+    if (!next.files.includes(stale)) rmSync(join(home, stale), { force: true });
+  }
+  for (const link of links) ensureLink(link.source, join(home, link.target));
+  for (const file of files) writeFileAtomic(join(home, file.target), file.content);
+  writeFileAtomic(join(home, HOST_ASSET_MANIFEST), JSON.stringify(next));
+}
+
+// ── Claude plan ───────────────────────────────────────────────────────────────────────────────
+
+/** Marks a host settings snapshot the off-thread reader could not parse (fs-offload worker). */
+export const HOST_SNAPSHOT_READ_ERROR = "__relayHostReadError";
+
+/** The host settings.json a selected Settings/Plugins class reads: the hydrated snapshot, else disk. */
+export function claudeHostSettingsSnapshot(config: Pick<RunnerSpawnConfig, "hostClaudeSettings">, sourceHome: string, hostClass: HostSourceClass): Record<string, unknown> | undefined {
+  const path = join(sourceHome, "settings.json");
+  const snapshot = config.hostClaudeSettings;
+  if (!snapshot) return readSelectedJson(hostClass, path);
+  const error = snapshot[HOST_SNAPSHOT_READ_ERROR];
+  if (typeof error === "string") throw new HostSourceError(hostClass, path, `unreadable or malformed (${error})`);
+  return snapshot;
+}
+
+export interface ClaudeHostPlan {
+  selection: HostSourceSelection;
+  links: HostLink[];
+  /** Host-only generated files (the native plugin registry copies). */
+  files: Array<{ target: string; content: string }>;
+  /** Host settings keys the managed settings.json receives (residual Settings + plugin keys). */
+  settings: Record<string, unknown>;
+  /** Native installed plugin ids the home carries. */
+  pluginIds: string[];
+  /** Explicit providerConfig.pluginDirs passed as --plugin-dir. */
+  pluginDirs: string[];
+}
+
+/** A profile-less launch keeps the provider's native home: every class is native, nothing is planned. */
+export function nativeHostPlan(config: RunnerSpawnConfig, providerConfig = config.providerConfig): ClaudeHostPlan {
+  return { selection: hostSourcesFor(config), links: [], files: [], settings: {}, pluginIds: [], pluginDirs: providerConfig.pluginDirs };
+}
+
+export function claudeHostPlan(config: RunnerSpawnConfig, sourceHome: string, providerConfig = config.providerConfig): ClaudeHostPlan {
+  const selection = hostSourcesFor(config);
+  const settingsClass: HostSourceClass | undefined = selection.plugins ? "plugins" : selection.settings ? "settings" : undefined;
+  const hostSettings = settingsClass ? claudeHostSettingsSnapshot(config, sourceHome, settingsClass) : undefined;
+  const ownedProvided = !config.agentProfile || Boolean(config.agentProfile.provisioning?.plugins.some(plugin => plugin.name === "agent-relay-claude-plugin"));
+  const registry = selection.plugins ? selectClaudeHostPlugins(sourceHome, hostSettings, { generation: runnerMcpGeneration(config.env), ownedProvided }) : undefined;
+  const files = [
+    ...(registry?.installed ? [{ target: join("plugins", "installed_plugins.json"), content: JSON.stringify(registry.installed, null, 2) }] : []),
+    ...(registry?.known ? [{ target: join("plugins", "known_marketplaces.json"), content: JSON.stringify(registry.known, null, 2) }] : []),
+  ];
+  return {
+    selection,
+    links: claudeHostLinks(sourceHome, selection, providerConfig.globalInstructionFiles ?? []),
+    files,
+    settings: { ...(selection.settings ? claudeHostSettingsFor(hostSettings, "settings") : {}), ...(registry?.settings ?? {}) },
+    pluginIds: registry?.ids ?? [],
+    pluginDirs: selection.plugins ? selectClaudePluginDirs(providerConfig.pluginDirs, runnerMcpGeneration(config.env), ownedProvided || Boolean(registry?.ids.some(id => CLAUDE_OWNED_PLUGIN_IDS.includes(id) && (registry.settings.enabledPlugins as Record<string, unknown> | undefined)?.[id] === true))) : [],
+  };
+}
+
+/** Per-class disposition of a Claude launch, from the same plan and resolvers the launch uses. */
+export function claudeHostReport(plan: ClaudeHostPlan, applied: { mcp: boolean; hooks: boolean; skills: boolean; defaultArgs: boolean; env: boolean }): HostSourceReport {
+  const linked = (hostClass: HostSourceClass) => plan.links.some((link) => link.hostClass === hostClass);
+  const { selection } = plan;
+  return {
+    instructions: disposition(selection.instructions, linked("instructions")),
+    mcp: disposition(selection.mcp, applied.mcp),
+    hooks: disposition(selection.hooks, applied.hooks),
+    skills: disposition(selection.skills, applied.skills || linked("skills")),
+    plugins: disposition(selection.plugins, plan.pluginIds.length > 0 || plan.pluginDirs.length > 0),
+    settings: disposition(selection.settings, linked("settings") || applied.defaultArgs || applied.env || Object.keys(plan.settings).some((key) => claudeSettingsClass(key) === "settings")),
+  };
+}
+
+// ── Codex plan ────────────────────────────────────────────────────────────────────────────────
+
+// Native skill roots outside CODEX_HOME that Codex discovers from the user's HOME.
+function codexAmbientSkillRoots(userHome: string): string[] {
+  return [join(userHome, ".agents", "skills")];
+}
+
+/** Skill dirs under `root`: real or symlinked directories holding a SKILL.md. */
+export function skillDirsUnder(root: string): string[] {
+  if (!existsSync(root)) return [];
+  return readdirSync(root, { withFileTypes: true })
+    .filter((entry) => (entry.isDirectory() || entry.isSymbolicLink()) && !entry.name.startsWith(".") && existsSync(join(root, entry.name, "SKILL.md")))
+    .map((entry) => join(root, entry.name))
+    .sort();
+}
+
+// Top-level config.toml keys another class or Relay's runtime owns. Codex-written state in the
+// managed home (trust, features) stays Relay's; MCP and hooks have their own classes.
+const CODEX_NON_SETTINGS_KEYS = new Set(["mcp_servers", "hooks", "skills", "projects", "features"]);
+
+export interface CodexHostPlan {
+  selection: HostSourceSelection;
+  links: HostLink[];
+  /** Host skill dirs enabled and registered as discovery roots. */
+  skillRoots: string[];
+  /** Ambient host skill dirs Codex would discover on its own, explicitly disabled. */
+  disabledSkillRoots: string[];
+  /** Residual host config.toml (Settings class), top-level keys only. */
+  settings: Record<string, unknown>;
+}
+
+export function codexHostPlan(config: RunnerSpawnConfig, sourceHome: string, userHome = homedir()): CodexHostPlan {
+  const selection = hostSourcesFor(config);
+  const ambient = codexAmbientSkillRoots(userHome).flatMap(skillDirsUnder);
+  let settings: Record<string, unknown> = {};
+  if (selection.settings) {
+    const path = join(sourceHome, "config.toml");
+    if (existsSync(path)) {
+      let parsed: unknown;
+      try {
+        parsed = Bun.TOML.parse(readFileSync(path, "utf8"));
+      } catch (error) {
+        throw new HostSourceError("settings", path, `unreadable or malformed (${(error as Error).message})`);
+      }
+      if (isRecord(parsed)) settings = Object.fromEntries(Object.entries(parsed).filter(([key]) => !CODEX_NON_SETTINGS_KEYS.has(key)));
+    }
+  }
+  return {
+    selection,
+    links: codexHostLinks(sourceHome, selection, config.providerConfig.globalInstructionFiles ?? []),
+    skillRoots: selection.skills ? [...skillDirsUnder(join(sourceHome, "skills")), ...ambient] : [],
+    disabledSkillRoots: selection.skills ? [] : ambient,
+    settings,
+  };
+}
+
+export function codexHostReport(plan: CodexHostPlan, applied: { mcp: boolean; hooks: HostSourceDisposition; defaultArgs: boolean; env: boolean }): HostSourceReport {
+  const { selection } = plan;
+  return {
+    instructions: disposition(selection.instructions, plan.links.length > 0),
+    mcp: disposition(selection.mcp, applied.mcp),
+    hooks: applied.hooks,
+    skills: disposition(selection.skills, plan.skillRoots.length > 0),
+    // Relay has no Codex native-plugin serializer yet: never claim an inherited plugin.
+    plugins: selection.plugins ? "unsupported" : "disabled",
+    settings: disposition(selection.settings, Object.keys(plan.settings).length > 0 || applied.defaultArgs || applied.env),
+  };
+}
+
+const CODEX_SETTINGS_BEGIN = "# >>> agent-relay host settings (generated; edits are replaced)";
+const CODEX_SETTINGS_END = "# <<< agent-relay host settings";
+
+function withoutCodexSettingsRegion(text: string): string {
+  const begin = text.indexOf(CODEX_SETTINGS_BEGIN);
+  if (begin < 0) return text;
+  const end = text.indexOf(CODEX_SETTINGS_END, begin);
+  if (end < 0) return text;
+  return (text.slice(0, begin) + text.slice(end + CODEX_SETTINGS_END.length)).replace(/^\n+/, "");
+}
+
+/**
+ * Write the selected residual host settings as a generated region at the top of the managed
+ * config.toml (inline values, so later tables cannot absorb them). Keys the file already defines
+ * outside the region win; an off class removes the region on reuse.
+ */
+export function writeCodexHostSettings(codexHome: string, settings: Record<string, unknown>, inline: (value: unknown) => string): void {
+  const path = join(codexHome, "config.toml");
+  const current = existsSync(path) ? readFileSync(path, "utf8") : "";
+  const rest = withoutCodexSettingsRegion(current);
+  let owned: Record<string, unknown> = {};
+  try {
+    owned = Bun.TOML.parse(rest) as Record<string, unknown>;
+  } catch {
+    // An unparseable managed file is the provider's to report; never guess which keys it owns.
+    owned = {};
+  }
+  const lines: string[] = [];
+  for (const [key, value] of Object.entries(settings)) {
+    if (Object.hasOwn(owned, key)) continue;
+    try {
+      lines.push(`${JSON.stringify(key)} = ${inline(value)}`);
+    } catch (error) {
+      throw new HostSourceError("settings", join(codexHome, "config.toml"), `host config.toml key ${key} has no supported form (${(error as Error).message})`);
+    }
+  }
+  const next = lines.length ? `${CODEX_SETTINGS_BEGIN}\n${lines.join("\n")}\n${CODEX_SETTINGS_END}\n\n${rest}` : rest;
+  if (next !== current) writeFileAtomic(path, next);
+}
+
+/** A profile-less launch runs in the provider's native home: every class is native. */
+export function nativeHostReport(): HostSourceReport {
+  return { instructions: "applied", mcp: "applied", hooks: "applied", skills: "applied", plugins: "applied", settings: "applied" };
+}

package/src/host-claude-config-worker.ts

@@ -0,0 +1,34 @@
+import { isRecord } from "@humwick/sdk";
+import type { OffloadWorkerTask } from "@humwick/offload/worker";
+
+// Mirrors HOST_SNAPSHOT_READ_ERROR (host-asset-plan.ts); a worker entry stays dependency-light.
+const READ_ERROR = "__relayHostReadError";
+
+const task: OffloadWorkerTask<{ path: string; kind?: "config" | "settings" }, Record<string, unknown> | undefined> = async ({ path, kind = "config" }) => {
+  try {
+    const file = Bun.file(path);
+    if (!await file.exists()) return undefined;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(await file.text());
+    } catch (error) {
+      // #3387 — a selected host class must fail loudly on a malformed settings.json, never launch as if empty.
+      if (kind === "settings") return { [READ_ERROR]: (error as Error).message };
+      throw error;
+    }
+    if (!isRecord(parsed)) return kind === "settings" ? { [READ_ERROR]: "not a JSON object" } : undefined;
+    // settings.json is small; the launch partitions it per host class (#3387).
+    if (kind === "settings") return parsed;
+    // Keep only the three host-level launch inputs. Returning Claude's entire history/session
+    // object would transfer tens of MB back to the runner and recreate the same event-loop stall.
+    const snapshot: Record<string, unknown> = {};
+    if (typeof parsed.theme === "string") snapshot.theme = parsed.theme;
+    if (typeof parsed.lastOnboardingVersion === "string") snapshot.lastOnboardingVersion = parsed.lastOnboardingVersion;
+    if (isRecord(parsed.mcpServers)) snapshot.mcpServers = parsed.mcpServers;
+    return snapshot;
+  } catch {
+    return undefined;
+  }
+};
+
+export default task;

package/src/host-sources.ts

@@ -0,0 +1,40 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { isRecord, type ProvisioningHookSet, type ProvisioningMcpServer } from "@humwick/sdk";
+import type { RunnerSpawnConfig } from "./adapter";
+import { claudeHostSettingsSnapshot } from "./host-asset-plan";
+import { providerSourceHome } from "./profile-home";
+
+/** Host Claude hooks are stored in the host settings.json, not .claude.json; a host that set
+ * `disableAllHooks` carries none, so a managed home never re-enables them (#3387).
+ * #2513 — keyed by provider id so a dedicatedHome claude-family provider (claude-b)
+ * reads ITS OWN source home's settings, never ~/.claude's. */
+export function hostClaudeHooks(config: Pick<RunnerSpawnConfig, "hostClaudeSettings">, provider: string = "claude"): ProvisioningHookSet {
+  const settings = claudeHostSettingsSnapshot(config, providerSourceHome(provider), "hooks");
+  if (!settings || settings.disableAllHooks === true || !isRecord(settings.hooks)) return {};
+  return settings.hooks as ProvisioningHookSet;
+}
+
+/** Read the host Codex MCP tables that an isolated CODEX_HOME would otherwise lose. */
+export function hostCodexMcpServers(): Record<string, ProvisioningMcpServer> {
+  const path = join(providerSourceHome("codex"), "config.toml");
+  if (!existsSync(path)) return {};
+  try {
+    const parsed = Bun.TOML.parse(readFileSync(path, "utf8")) as { mcp_servers?: unknown };
+    return isRecord(parsed.mcp_servers) ? parsed.mcp_servers as Record<string, ProvisioningMcpServer> : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Host Codex hooks are consumed from CODEX_HOME/hooks.json by supported Codex releases. */
+export function hostCodexHooks(): ProvisioningHookSet {
+  const path = join(providerSourceHome("codex"), "hooks.json");
+  if (!existsSync(path)) return {};
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as unknown;
+    return isRecord(parsed) && isRecord(parsed.hooks) ? parsed.hooks as ProvisioningHookSet : {};
+  } catch {
+    return {};
+  }
+}

package/src/inbox-carrier.ts

@@ -0,0 +1,7 @@
+import { isMechanicalMessageKind, type Message } from "@humwick/sdk";
+
+/** A delivered notice owes no answer, so it must not arm the empty-turn/input-stalled ladder. */
+export function isNotificationOnlyInput(message: Message): boolean {
+  return isMechanicalMessageKind(message.kind) || message.replyExpected === false ||
+    message.payload?.notification != null;
+}