agent-relay-server 0.122.0 → 0.123.0

package/runner/src/launch-assembly.ts

@@ -0,0 +1,674 @@
+import { existsSync, readdirSync } from "node:fs";
+import { resolve, join } from "node:path";
+import type { AgentProfile, AgentProfileBase, ProvisioningHookSet, ProvisioningMcpServer, SpawnProvider } from "agent-relay-sdk";
+import { shellQuote } from "agent-relay-sdk/shell-utils";
+import {
+  profileAllowsRelayFeature,
+  profileIsVanillaBase,
+  type ProviderConfig,
+  type RunnerSpawnConfig,
+} from "./adapter";
+import {
+  projectConfigProjectionOn,
+  hostUserScopeMcpServers,
+  profileAllowsHostAssets,
+  profileUsesProviderHostGlobals,
+  providerHomePathFor,
+  providerProvisioningHomePathFor,
+} from "./profile-home";
+import { getManifest } from "agent-relay-providers";
+import { codexHooksSupported } from "./codex-version";
+import { claudeLaunchPromptGateSettings } from "./claude-prompt-gates";
+import {
+  materializeResolvedAssets,
+  renderProvisionedHookSet,
+  resolveClaudeProjectSkills,
+  resolveClaudeHostSkills,
+  resolveProjectClaudeSettings,
+  resolveClaudeProvisionedPlugins,
+  resolveClaudeProvisionedSkills,
+  resolveCodexProvisionedSkills,
+  resolveProvisionedHooks,
+  resolveProjectMcpServers,
+  profileProvisioning,
+  writeCodexHooksJson,
+} from "./provisioning";
+import {
+  claudeMcpLaunchArgs,
+  codexProvisionedMcpArgs,
+  relayMcpCodexConfigArgs,
+  resolveSharedMcpUrl,
+  sharedMcpBridgeServer,
+  tomlString,
+  RELAY_MCP_SERVER_NAME,
+  SHARED_MCP_SERVER_NAME,
+} from "./relay-mcp";
+
+// #557 — THE single launch-assembly contract. Given a resolved AgentProfile (+ its
+// spawn-time ResolvedProvisioning), `assembleLaunch` produces ONE provider-neutral
+// description of the launch: the relay-provisioned skills/plugins/MCP, the bundled relay
+// surface, the instruction-source disposition, and `base:"vanilla"` as the zero-host
+// floor. Both adapters' buildSpawnArgs splice `assembled.args`/`assembled.env`, and
+// profile-projection describes `assembled` directly — so projection and reality come
+// from one source and cannot drift.
+//
+// `assembleLaunch` is PURE (it reads the filesystem to decide which declared dirs
+// resolve, but writes nothing). `materializeLaunchAssembly` performs the disk writes the
+// description implies, driven by the SAME resolvers — so what's written equals what's
+// reported equals what's launched.
+
+export interface AssembledAsset {
+  name: string;
+  /** Materialized/in-place dir feeding the launch (e.g. a --plugin-dir or skills.config path). */
+  dir: string;
+}
+
+export type AssembledInstructionDisposition = "allow" | "suppressed" | "isolated" | "unsupported";
+
+export interface AssembledInstructions {
+  /** Repo CLAUDE.md/AGENTS.md cascade: "allow" left available, "suppressed" by the
+   *  vanilla launch mechanism, "unsupported" requested-but-not-enforced (non-vanilla isolated). */
+  repo: AssembledInstructionDisposition;
+  /** Host/global provider instructions: "allow", "isolated" (dropped by the isolated home), or "unsupported". */
+  global: AssembledInstructionDisposition;
+  /** A composed systemPromptAppend block (project preamble + profile system/append +
+   *  caller context, composed relay-side by composeSpawnInstructions) flows into this launch. */
+  systemPromptAppend: boolean;
+  // ── #559 SEAM ──────────────────────────────────────────────────────────────────
+  // Scoped {profile|user} memory does not exist yet (#559 generalizes Projects' anchor
+  // to project|profile|user). When it lands, the assembled instruction world becomes
+  // "instructions + provisioned assets + scoped knowledge": the relay-side composer
+  // (composeSpawnInstructions) gains a profile/user-scoped preamble beside the existing
+  // project preamble, and THIS field reports which scopes contributed. Until then it is
+  // always "none" — a thin add for #559, not a refactor.
+  scopedKnowledge: "none";
+}
+
+export interface AssembledMcp {
+  /** The identity-bearing relay HTTP MCP endpoint is injected. */
+  relayEndpoint: boolean;
+  /** Only the assembled servers may load (Claude --strict-mcp-config). #662: true for ALL
+   *  managed Claude launches so the project `.mcp.json` enable-modal can't wedge a headless
+   *  agent; relay's endpoint + provisioned servers (via --mcp-config) are preserved. Always
+   *  false for Codex (no equivalent discovery modal). */
+  strict: boolean;
+  /** Relay-provisioned server names (excludes the relay endpoint itself). */
+  servers: string[];
+  /** #667 — project `.mcp.json` server names projected from the spawn cwd's committed
+   *  `.mcp.json` (via `--mcp-config`, so they survive strict). Sourced from the project,
+   *  not ambient host MCP. Empty unless the profile/spawn opted into `projectMcp`, and a
+   *  name already declared by relay-provisioned `servers` wins (not double-listed here). */
+  projectServers: string[];
+  /** #662 — host USER-scope MCP server names (`~/.claude.json` `mcpServers`) re-injected
+   *  into `--mcp-config` for an `mcp.mode:"host"` profile, so `--strict-mcp-config` keeps
+   *  the ambient host MCP (callmux/qmd/gh) instead of dropping it. Empty for non-host mcp
+   *  modes, isolated bases (own config home, never had host MCP), and Codex. */
+  hostServers: string[];
+  /** #672 — when the profile/spawn opted into `sharedMcp`, the agent's NON-IDENTITY MCP
+   *  (tokenlean, github) is routed through one orchestrator-owned shared `callmux` listener via
+   *  a per-agent `callmux bridge --cwd "$WORKTREE"` (session-cwd isolation), injected through
+   *  the same `--mcp-config` / `-c` channel so it survives strict. `url` is the listener the
+   *  bridge connects to. Undefined when projection is OFF (the default). The bridge is opaque
+   *  at assembly time — its server SET is owned by the listener config, not enumerated here.
+   *  The identity-bearing relay endpoint is never on the shared listener (#215). */
+  sharedListener?: { url: string };
+}
+
+export interface AssembledLaunch {
+  provider: SpawnProvider;
+  /** The resolved profile this launch was assembled from; undefined for a profile-less
+   *  (legacy default) spawn, which behaves as host base with relay features default-on. */
+  profile?: AgentProfile;
+  base: AgentProfileBase;
+  vanilla: boolean;
+  /** Isolated provider config home (CLAUDE_CONFIG_DIR / CODEX_HOME), or undefined for host base. */
+  configHome?: string;
+  relayContext: boolean;
+  /** Bundled relay skills are available (Codex skills.config / Claude via the relay plugin). */
+  relaySkills: boolean;
+  /** Bundled relay plugin dir is passed (Claude only). */
+  relayPlugin: boolean;
+  /** Relay status-line context probe is injected (Claude only). */
+  statusLine: boolean;
+  /** Relay-provisioned skills materialized for this launch. */
+  skills: AssembledAsset[];
+  /** Project `.claude/skills` materialized for this Claude launch (#668). */
+  projectSkills: AssembledAsset[];
+  /** Host/global Claude skills explicitly inherited without enabling host MCP. */
+  hostSkills: AssembledAsset[];
+  /** Project `.claude/settings.json` sanitized and injected for this Claude launch (#669). */
+  projectSettings: { applied: boolean; keys: string[]; ignoredKeys: string[]; file?: string };
+  /** Relay-provisioned hooks materialized for this launch. Empty when hooks were resolved
+   *  but could not be delivered — see `hooksSuppressed` (the anti-lie invariant, #1096). */
+  hooks: AssembledAsset[];
+  /** #1096 review — set when this launch RESOLVED provisioned hooks (incl. a baseline safety
+   *  guard) that could NOT be delivered: caller `--settings` was unmergeable (Claude), a
+   *  host-base Codex agent has no managed CODEX_HOME, or the installed Codex is too old to
+   *  consume hooks.json. Drives a LOUD projection warning so a baseline guard is never
+   *  SILENTLY absent while the report says "applied". */
+  hooksSuppressed?: { reason: string; names: string[] };
+  /** #1096 review — Claude only: true when the caller's own `--settings` was folded into the
+   *  relay-emitted `--settings` (relay hooks/projectSettings/statusLine merged in). The adapter
+   *  must then STRIP the caller's `--settings` from the provider args so exactly one reaches the
+   *  launch. False when relay emitted its own settings standalone or added none. */
+  callerSettingsConsumed: boolean;
+  /** Relay-provisioned plugins (Claude --plugin-dir). Empty for Codex (no plugin surface). */
+  plugins: AssembledAsset[];
+  /** Host/global provider plugin dirs explicitly inherited without enabling host MCP. */
+  hostPluginDirs: string[];
+  mcp: AssembledMcp;
+  instructions: AssembledInstructions;
+  /** Provider provisioning/vanilla/instruction launch-arg block, in launch order. */
+  args: string[];
+  /** Provisioning-derived env additions (the isolated config-home var). */
+  env: Record<string, string>;
+}
+
+// ── Bundled relay assets (relocated from the adapters so the assembler — not each
+// adapter — owns launch-arg construction; #557). Adapters re-export for test parity. ──
+
+const CLAUDE_RELAY_PLUGIN_DIR = resolve(import.meta.dir, "../plugins/claude");
+const CODEX_BUNDLED_SKILLS_DIR = resolve(import.meta.dir, "../plugins/codex/skills");
+
+export function bundledCodexSkillDirs(baseDir = CODEX_BUNDLED_SKILLS_DIR): string[] {
+  if (!existsSync(baseDir)) return [];
+  return readdirSync(baseDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && existsSync(join(baseDir, entry.name, "SKILL.md")))
+    .map((entry) => join(baseDir, entry.name))
+    .sort();
+}
+
+export function bundledSkillConfigArgs(skillDirs = bundledCodexSkillDirs()): string[] {
+  if (skillDirs.length === 0) return [];
+  const skillsConfig = skillDirs.map((dir) => `{path=${tomlString(dir)},enabled=true}`).join(",");
+  return ["-c", `skills.config=[${skillsConfig}]`];
+}
+
+// #552 vanilla base (Codex): suppress the AGENTS.md project-doc cascade. project_doc_max_bytes
+// (default 32768) caps bytes Codex reads from AGENTS.md walking root→cwd; 0 stops before adding
+// any, so no repo (or fresh-CODEX_HOME global) project doc loads. The isolated CODEX_HOME already
+// drops host config.toml MCP/hooks; this closes the cwd-resident repo instruction channel.
+export function codexProjectDocSuppressionArgs(config: Pick<RunnerSpawnConfig, "agentProfile">): string[] {
+  return profileIsVanillaBase(config) ? ["-c", "project_doc_max_bytes=0"] : [];
+}
+
+function hasSettingsArg(args: string[]): boolean {
+  return args.some((arg) => arg === "--settings" || arg.startsWith("--settings="));
+}
+
+// Claude relay status-line + readable-thinking settings, injected only when no caller
+// --settings is already present (caller wins). Relocated from claude.ts (#557).
+export function sessionStatusLineSettingsArgs(...argLists: string[][]): string[] {
+  if (argLists.some(hasSettingsArg)) return [];
+  return ["--settings", JSON.stringify(relayStatusLineSettings())];
+}
+
+function relayStatusLineSettings(): Record<string, unknown> {
+  return {
+    statusLine: { type: "command", command: `node ${shellQuote(claudeStatusLineProbePath())}`, refreshInterval: 30 },
+    showThinkingSummaries: true,
+  };
+}
+
+function claudeStatusLineProbePath(): string {
+  return resolve(import.meta.dir, "../plugins/claude/claude-statusline-probe.cjs");
+}
+
+export interface ClaudeSettingsResolution {
+  args: string[];
+  /** The caller's own --settings was merged in and must be stripped from the provider args. */
+  callerSettingsConsumed: boolean;
+  /** Provisioned hook names that could NOT be delivered (caller --settings unmergeable). */
+  suppressedHookNames: string[];
+}
+
+// #1096 review, finding 1 — when the caller (spawn providerArgs / provider defaultArgs) already
+// carries `--settings`, DO NOT silently drop relay's settings (which used to skip the baseline
+// safety hooks + projectSettings + statusLine while projection still claimed "applied"). Merge
+// relay's settings into the caller's INLINE JSON so the guard survives, and signal the adapter to
+// strip the caller's now-redundant `--settings`. If the caller's `--settings` is a FILE PATH or
+// malformed JSON (unmergeable), relay's provisioned hooks are reported as SUPPRESSED (a loud
+// projection warning) rather than a silent absence with an "applied" lie.
+function claudeSettingsArgs(
+  projectSettings: Record<string, unknown>,
+  provisionedHooks: ProvisioningHookSet,
+  hookNames: string[],
+  includeStatusLine: boolean,
+  ...argLists: string[][]
+): ClaudeSettingsResolution {
+  const relaySettings: Record<string, unknown> = {
+    ...projectSettings,
+    ...(Object.keys(provisionedHooks).length ? { hooks: provisionedHooks } : {}),
+    ...(includeStatusLine ? relayStatusLineSettings() : {}),
+  };
+  const hasProvisionedHooks = Object.keys(provisionedHooks).length > 0;
+  const caller = extractCallerSettings(argLists);
+  if (!caller) {
+    return {
+      args: Object.keys(relaySettings).length ? ["--settings", JSON.stringify(relaySettings)] : [],
+      callerSettingsConsumed: false,
+      suppressedHookNames: [],
+    };
+  }
+  if (caller.settings) {
+    const merged = mergeClaudeSettings(caller.settings, relaySettings);
+    return { args: ["--settings", JSON.stringify(merged)], callerSettingsConsumed: true, suppressedHookNames: [] };
+  }
+  // Unmergeable caller --settings (a file path or malformed JSON): relay cannot fold its
+  // settings in without clobbering the caller's file, so the provisioned hooks don't reach
+  // the launch. Report them suppressed (loud) — never claim "applied".
+  return { args: [], callerSettingsConsumed: false, suppressedHookNames: hasProvisionedHooks ? hookNames : [] };
+}
+
+// The caller's `--settings` value, parsed as inline JSON when possible. `settings` is null for a
+// file-path / malformed value (an inline object is required to merge relay settings in).
+function extractCallerSettings(argLists: string[][]): { settings: Record<string, unknown> | null } | null {
+  for (const list of argLists) {
+    for (let i = 0; i < list.length; i += 1) {
+      const arg = list[i];
+      if (arg === "--settings") return { settings: parseInlineSettings(list[i + 1]) };
+      if (arg?.startsWith("--settings=")) return { settings: parseInlineSettings(arg.slice("--settings=".length)) };
+    }
+  }
+  return null;
+}
+
+function parseInlineSettings(value: string | undefined): Record<string, unknown> | null {
+  if (!value) return null;
+  const trimmed = value.trim();
+  if (!trimmed.startsWith("{")) return null; // a settings file path, not inline JSON
+  try {
+    const parsed = JSON.parse(trimmed);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? (parsed as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+// Merge relay settings into the caller's inline settings. The safety-critical `hooks` map is
+// UNIONED per event (caller entries first, relay's baseline guard appended) so both fire; every
+// other relay key is fill-if-absent (the caller's explicit value wins), preserving the historical
+// "caller --settings wins" spirit for non-safety settings.
+function mergeClaudeSettings(caller: Record<string, unknown>, relay: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...caller };
+  for (const [key, value] of Object.entries(relay)) {
+    if (key === "hooks") out.hooks = mergeHookSets(caller.hooks, value);
+    else if (!(key in out)) out[key] = value;
+  }
+  return out;
+}
+
+function mergeHookSets(caller: unknown, relay: unknown): ProvisioningHookSet {
+  const base: ProvisioningHookSet = isHookSet(caller) ? { ...caller } : {};
+  if (!isHookSet(relay)) return base;
+  for (const [event, entries] of Object.entries(relay)) {
+    base[event] = [...(base[event] ?? []), ...entries];
+  }
+  return base;
+}
+
+function isHookSet(value: unknown): value is ProvisioningHookSet {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+// Strip every `--settings <json>` / `--settings=<json>` occurrence from a provider arg list. The
+// adapter applies this to the caller args once the assembler has folded them into its own merged
+// `--settings` (callerSettingsConsumed), so exactly one `--settings` reaches the launch (#1096).
+export function stripSettingsArgs(args: string[]): string[] {
+  const result: string[] = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--settings") { i += 1; continue; }
+    if (arg?.startsWith("--settings=")) continue;
+    if (arg !== undefined) result.push(arg);
+  }
+  return result;
+}
+
+// ── Instruction disposition (the vanilla floor's effect on the host instruction cascade) ──
+
+function repoInstructionDisposition(profile: AgentProfile): AssembledInstructionDisposition {
+  if (profile.instructions.repoInstructions === "allow") return "allow";
+  if (profile.base === "vanilla") return "suppressed";
+  // Non-vanilla isolated bases can request ignore but have no launch-time enforcement yet.
+  return "unsupported";
+}
+
+function globalInstructionDisposition(profile: AgentProfile): AssembledInstructionDisposition {
+  if (profile.instructions.globalInstructions === "allow") return "allow";
+  if (profile.base !== "host") return "isolated";
+  return "unsupported";
+}
+
+function assembleInstructions(config: RunnerSpawnConfig): AssembledInstructions {
+  const profile = config.agentProfile;
+  return {
+    // A profile-less spawn is host-base: the full host instruction cascade is left available.
+    repo: profile ? repoInstructionDisposition(profile) : "allow",
+    global: profile ? globalInstructionDisposition(profile) : "allow",
+    systemPromptAppend: Boolean(config.systemPromptAppend?.trim()),
+    scopedKnowledge: "none",
+  };
+}
+
+// ── Per-provider arg assembly ──────────────────────────────────────────────────────
+
+function assembleClaude(config: RunnerSpawnConfig, providerConfig: ProviderConfig, hostDefaultArgs: string[]): AssembledLaunch {
+  const configHome = providerHomePathFor("claude", config);
+  const assetHome = providerProvisioningHomePathFor("claude", config);
+  const vanilla = profileIsVanillaBase(config);
+  const projectConfigProjection = projectConfigProjectionOn(config);
+  const relayPlugin = profileAllowsRelayFeature(config, "plugins");
+  const relaySkills = profileAllowsRelayFeature(config, "skills");
+  const statusLine = profileAllowsRelayFeature(config, "statusLine");
+
+  const skills = configHome ? resolveClaudeProvisionedSkills(configHome, config) : [];
+  const hostSkills = configHome
+    ? resolveClaudeHostSkills(configHome, config, new Set(skills.map((s) => s.name)))
+    : [];
+  const projectSkills = configHome
+    ? resolveClaudeProjectSkills(configHome, config, new Set([...skills, ...hostSkills].map((s) => s.name)))
+    : [];
+  const projectSettings = resolveProjectClaudeSettings(config);
+  const provisionedPlugins = assetHome ? resolveClaudeProvisionedPlugins(assetHome, config) : [];
+  const hookHome = configHome ?? assetHome;
+  const provisionedHooks = hookHome ? resolveProvisionedHooks(hookHome, config) : [];
+  const provisionedHookSet = renderProvisionedHookSet(provisionedHooks);
+  const settings = claudeSettingsArgs(
+    projectSettings.settings,
+    provisionedHookSet,
+    provisionedHooks.map((h) => h.name),
+    statusLine,
+    hostDefaultArgs,
+    config.providerArgs,
+  );
+  // The anti-lie invariant (#1096): only report hooks as materialized when they actually reach
+  // the launch. If the caller's --settings suppressed them, empty the reported set and surface a
+  // loud suppression reason instead of an "applied" report.
+  const hooksSuppressed = settings.suppressedHookNames.length
+    ? { reason: "caller-provided --settings could not be merged (file path or malformed JSON); relay hooks were not injected", names: settings.suppressedHookNames }
+    : undefined;
+  const deliveredHooks = hooksSuppressed ? [] : provisionedHooks;
+
+  // Plugin dirs (--plugin-dir loads explicitly, independent of --setting-sources):
+  //   relay-bundled plugin → only when relay.plugins (carries the relay monitor +
+  //     turn-lifecycle hooks #556, not reproducible via settings.json).
+  //   relay-provisioned plugins (#556) → materialized into the isolated home.
+  //   host plugin dirs → ONLY host-base profiles; isolated/vanilla must not pull them back in.
+  const relayPluginDirs = !config.agentProfile && relayPlugin ? [CLAUDE_RELAY_PLUGIN_DIR] : [];
+  const provisionedPluginDirs = provisionedPlugins.map((p) => p.dir);
+  const hostPluginDirs = profileAllowsHostAssets(config, "plugins") ? providerConfig.pluginDirs : [];
+  const pluginDirs = [...new Set([...relayPluginDirs, ...provisionedPluginDirs, ...hostPluginDirs])];
+
+  const provisionedMcp = profileProvisioning(config).mcpServers;
+  const mcpServers = Object.keys(provisionedMcp).filter((name) => name !== RELAY_MCP_SERVER_NAME);
+  const relayEndpoint = profileAllowsRelayFeature(config, "mcp");
+
+  // #667 — project `.mcp.json` projection (opt-in). The spawn cwd's committed servers are
+  // injected through the SAME `--mcp-config` channel as relay-provisioned servers, so they
+  // survive `--strict-mcp-config` without the ambient project-discovery modal. A relay-
+  // provisioned server of the same name wins (the profile is the explicit, relay-owned
+  // source); the relay endpoint name is reserved. `declaredMcp` is the union relay injects.
+  const projectMcpRaw = resolveProjectMcpServers(config);
+  const projectMcp = Object.fromEntries(
+    Object.entries(projectMcpRaw).filter(
+      ([name]) => name !== RELAY_MCP_SERVER_NAME && !(name in provisionedMcp),
+    ),
+  );
+  const projectServers = Object.keys(projectMcp);
+
+  // #672 — shared host-listener MCP (opt-in, default OFF). When on, route the agent's
+  // NON-IDENTITY MCP (tokenlean, github) through ONE orchestrator-owned shared `callmux`
+  // listener via a per-agent `callmux bridge --url <listener> --cwd "$WORKTREE"` stdio entry:
+  // the MCP session survives a listener/downstream restart, and --cwd gives each isolated
+  // worktree session-cwd isolation. It's a plain stdio server descriptor, so it rides the same
+  // controlled --mcp-config channel as provisioned servers (survives --strict-mcp-config) — no
+  // ambient discovery, no modal. Relay-owned infra → authoritative on its name (spread last);
+  // the relay endpoint stays per-agent (#215), NEVER on the shared listener.
+  const sharedListenerOn = Boolean(config.agentProfile?.sharedMcp);
+  const sharedListenerUrl = sharedListenerOn ? resolveSharedMcpUrl(config.sharedMcpUrl) : undefined;
+  const sharedMcp: Record<string, ProvisioningMcpServer> = sharedListenerUrl
+    ? { [SHARED_MCP_SERVER_NAME]: sharedMcpBridgeServer(sharedListenerUrl, config.cwd) }
+    : {};
+  const declaredMcp = { ...projectMcp, ...provisionedMcp, ...sharedMcp };
+
+  // #662/#663 — strict controlled MCP is a Claude prompt-gate prevention entry, not a
+  // launch-assembly special case. It prevents the blocking "N new MCP servers found in
+  // this project" modal while preserving every relay-declared server in --mcp-config.
+  const strictMcp = claudeLaunchPromptGateSettings(config).strictMcpConfig;
+
+  // #662 follow-up — strict drops ALL on-disk config, including the host user-scope
+  // `~/.claude.json` MCP that a host-base agent loaded ambiently before strict. That
+  // over-reached: it stopped honoring `mcp.mode:"host"`, so default-relay workers/reviewers
+  // lost callmux/qmd/gh. Re-inject the host USER-scope servers (NOT the project `.mcp.json`,
+  // still excluded) when the launch both uses the host config home AND its mcp mode is host.
+  // An isolated/minimal base has its own config home and never had the real host's user MCP,
+  // so it stays relay+provisioned only even if a profile sets mode:"host".
+  const usesHostMcp = profileUsesProviderHostGlobals(config)
+    && (!config.agentProfile || config.agentProfile.mcp.mode === "host");
+  const hostMcp = usesHostMcp ? hostUserScopeMcpServers() : {};
+  const hostMcpServers = Object.keys(hostMcp).filter(
+    (name) => name !== RELAY_MCP_SERVER_NAME && !(name in declaredMcp),
+  );
+
+  const instructions = assembleInstructions(config);
+
+  // Launch order matches the historical claude buildSpawnArgs block exactly so existing
+  // arg assertions hold: vanilla scope → plugin dirs → MCP → status-line → append.
+  const args = [
+    ...(vanilla || projectConfigProjection ? ["--setting-sources", "user"] : []),
+    ...pluginDirs.flatMap((dir) => ["--plugin-dir", dir]),
+    ...claudeMcpLaunchArgs({
+      relayUrl: config.relayUrl,
+      ...(config.relayMcpEndpoint ? { endpoint: config.relayMcpEndpoint } : {}),
+      includeRelay: relayEndpoint,
+      servers: declaredMcp,
+      hostServers: hostMcp,
+      strict: strictMcp,
+    }),
+    ...settings.args,
+    ...(config.systemPromptAppend ? ["--append-system-prompt", config.systemPromptAppend] : []),
+  ];
+
+  return {
+    provider: "claude",
+    ...(config.agentProfile ? { profile: config.agentProfile } : {}),
+    base: config.agentProfile?.base ?? "host",
+    vanilla,
+    ...(configHome ? { configHome } : {}),
+    relayContext: profileAllowsRelayFeature(config, "context"),
+    relaySkills,
+    relayPlugin,
+    statusLine,
+    skills: skills.map((s) => ({ name: s.name, dir: s.dir })),
+    hostSkills: hostSkills.map((s) => ({ name: s.name, dir: s.dir })),
+    projectSkills: projectSkills.map((s) => ({ name: s.name, dir: s.dir })),
+    projectSettings: {
+      applied: projectSettings.applied,
+      keys: projectSettings.keys,
+      ignoredKeys: projectSettings.ignoredKeys,
+      ...(projectSettings.file ? { file: projectSettings.file } : {}),
+    },
+    hooks: deliveredHooks.map((h) => ({ name: h.name, dir: h.dir })),
+    ...(hooksSuppressed ? { hooksSuppressed } : {}),
+    callerSettingsConsumed: settings.callerSettingsConsumed,
+    plugins: provisionedPlugins.map((p) => ({ name: p.name, dir: p.dir })),
+    hostPluginDirs,
+    mcp: {
+      relayEndpoint, strict: strictMcp, servers: mcpServers, projectServers, hostServers: hostMcpServers,
+      ...(sharedListenerUrl ? { sharedListener: { url: sharedListenerUrl } } : {}),
+    },
+    instructions,
+    args,
+    env: configHomeEnv("claude", configHome),
+  };
+}
+
+function assembleCodex(config: RunnerSpawnConfig, providerConfig: ProviderConfig): AssembledLaunch {
+  const configHome = providerHomePathFor("codex", config);
+  const assetHome = providerProvisioningHomePathFor("codex", config);
+  const vanilla = profileIsVanillaBase(config);
+  const relaySkills = profileAllowsRelayFeature(config, "skills");
+  const relayEndpoint = profileAllowsRelayFeature(config, "mcp");
+
+  const provisionedSkills = assetHome ? resolveCodexProvisionedSkills(assetHome, config) : [];
+  // #1096 review, findings 3 & 4 — Codex delivers hooks via CODEX_HOME/hooks.json, so a launch
+  // can only carry them when it has an isolated CODEX_HOME (host-base profiles reuse the real
+  // ~/.codex, which relay must not clobber) AND the installed Codex is new enough to consume the
+  // file. Resolve the profile's hook definitions to decide whether there was anything to deliver;
+  // any absence is reported LOUDLY (hooksSuppressed) instead of a silent "not-applicable".
+  const resolvedHookDefs = profileProvisioning(config).hooks ?? [];
+  const hooksSupported = codexHooksSupported(providerConfig.command);
+  const provisionedHooks = configHome && hooksSupported ? resolveProvisionedHooks(configHome, config) : [];
+  const hooksSuppressed = resolvedHookDefs.length && provisionedHooks.length === 0
+    ? {
+      reason: !configHome
+        ? "Codex host-base profile has no managed CODEX_HOME; relay will not overwrite the host ~/.codex/hooks.json, so the baseline guard cannot be delivered"
+        : "installed Codex is older than 0.124 and ignores CODEX_HOME/hooks.json (set AGENT_RELAY_CODEX_VERSION to override the probe)",
+      names: resolvedHookDefs.map((h) => h.name),
+    }
+    : undefined;
+  const bundledSkillDirs = !config.agentProfile && relaySkills ? bundledCodexSkillDirs() : [];
+  const skillDirs = [...bundledSkillDirs, ...provisionedSkills.map((s) => s.dir)];
+
+  const provisionedMcp = profileProvisioning(config).mcpServers;
+  const mcpServers = Object.keys(provisionedMcp).filter((name) => name !== RELAY_MCP_SERVER_NAME);
+
+  // #667 — project `.mcp.json` projection (opt-in), same union rule as Claude: a relay-
+  // provisioned server of the same name wins; the relay endpoint name is reserved. Codex has
+  // no `.mcp.json` discovery of its own, so this is purely additive (no strict/modal concern).
+  const projectMcpRaw = resolveProjectMcpServers(config);
+  const projectMcp = Object.fromEntries(
+    Object.entries(projectMcpRaw).filter(
+      ([name]) => name !== RELAY_MCP_SERVER_NAME && !(name in provisionedMcp),
+    ),
+  );
+  const projectServers = Object.keys(projectMcp);
+
+  // #672 — shared host-listener MCP (opt-in, default OFF), same as Claude: a per-agent
+  // `callmux bridge --url <listener> --cwd "$WORKTREE"` stdio entry routes the agent's
+  // NON-IDENTITY MCP (tokenlean, github) through the shared listener (session survives a
+  // restart; --cwd gives session-cwd isolation). Emitted via the same `-c mcp_servers.*`
+  // overrides as provisioned servers. The relay endpoint stays per-agent (#215).
+  const sharedListenerOn = Boolean(config.agentProfile?.sharedMcp);
+  const sharedListenerUrl = sharedListenerOn ? resolveSharedMcpUrl(config.sharedMcpUrl) : undefined;
+  const sharedMcp: Record<string, ProvisioningMcpServer> = sharedListenerUrl
+    ? { [SHARED_MCP_SERVER_NAME]: sharedMcpBridgeServer(sharedListenerUrl, config.cwd) }
+    : {};
+  const declaredMcp = { ...projectMcp, ...provisionedMcp, ...sharedMcp };
+
+  const instructions = assembleInstructions(config);
+
+  // The skills/MCP/project-doc block; core launch config (model/approval/listen) stays
+  // in the adapter. -c overrides are order-independent, so the assembled block is contiguous.
+  const args = [
+    ...bundledSkillConfigArgs(skillDirs),
+    ...(relayEndpoint ? relayMcpCodexConfigArgs(config.relayUrl, config.relayMcpEndpoint) : []),
+    ...codexProvisionedMcpArgs(declaredMcp),
+    ...codexProjectDocSuppressionArgs(config),
+  ];
+
+  return {
+    provider: "codex",
+    ...(config.agentProfile ? { profile: config.agentProfile } : {}),
+    base: config.agentProfile?.base ?? "host",
+    vanilla,
+    ...(configHome ? { configHome } : {}),
+    relayContext: profileAllowsRelayFeature(config, "context"),
+    relaySkills,
+    relayPlugin: false,
+    statusLine: false,
+    skills: provisionedSkills.map((s) => ({ name: s.name, dir: s.dir })),
+    hostSkills: [],
+    projectSkills: [],
+    projectSettings: { applied: false, keys: [], ignoredKeys: [] },
+    hooks: provisionedHooks.map((h) => ({ name: h.name, dir: h.dir })),
+    ...(hooksSuppressed ? { hooksSuppressed } : {}),
+    callerSettingsConsumed: false,
+    plugins: [],
+    hostPluginDirs: [],
+    mcp: {
+      relayEndpoint, strict: false, servers: mcpServers, projectServers, hostServers: [],
+      ...(sharedListenerUrl ? { sharedListener: { url: sharedListenerUrl } } : {}),
+    },
+    instructions,
+    args,
+    env: configHomeEnv("codex", configHome),
+  };
+}
+
+// ── Manifest-driven env + dispatch ────────────────────────────────────────────
+
+function configHomeEnv(provider: string, configHome: string | undefined): Record<string, string> {
+  if (!configHome) return {};
+  const manifest = getManifest(provider);
+  const envVar = manifest?.home?.configDirEnvVar;
+  return envVar ? { [envVar]: configHome } : {};
+}
+
+type Assembler = (config: RunnerSpawnConfig, providerConfig: ProviderConfig, hostDefaultArgs: string[]) => AssembledLaunch;
+type Materializer = (config: RunnerSpawnConfig) => void;
+
+const ASSEMBLERS: Record<string, Assembler> = {
+  claude: assembleClaude,
+  codex: (config, providerConfig) => assembleCodex(config, providerConfig),
+};
+
+const MATERIALIZERS: Record<string, Materializer> = {
+  claude: materializeClaudeAssets,
+  codex: materializeCodexAssets,
+};
+
+function materializeClaudeAssets(config: RunnerSpawnConfig): void {
+  const configHome = providerHomePathFor("claude", config);
+  const assetHome = providerProvisioningHomePathFor("claude", config);
+  if (configHome) {
+    const skills = resolveClaudeProvisionedSkills(configHome, config);
+    materializeResolvedAssets(skills);
+    const hostSkills = resolveClaudeHostSkills(configHome, config, new Set(skills.map((s) => s.name)));
+    materializeResolvedAssets(hostSkills);
+    materializeResolvedAssets(resolveClaudeProjectSkills(configHome, config, new Set([...skills, ...hostSkills].map((s) => s.name))));
+    materializeResolvedAssets(resolveProvisionedHooks(configHome, config));
+  }
+  if (assetHome) materializeResolvedAssets(resolveClaudeProvisionedPlugins(assetHome, config));
+  if (!configHome && assetHome) materializeResolvedAssets(resolveProvisionedHooks(assetHome, config));
+}
+
+function materializeCodexAssets(config: RunnerSpawnConfig): void {
+  const assetHome = providerProvisioningHomePathFor("codex", config);
+  if (assetHome) materializeResolvedAssets(resolveCodexProvisionedSkills(assetHome, config));
+  const configHome = providerHomePathFor("codex", config);
+  // #1096 review, finding 4 — don't write CODEX_HOME/hooks.json for a Codex that would ignore it;
+  // keep disk == report (the assembler reports these hooks suppressed for such a launch).
+  if (configHome && codexHooksSupported(config.providerConfig.command)) {
+    const hooks = resolveProvisionedHooks(configHome, config);
+    materializeResolvedAssets(hooks);
+    writeCodexHooksJson(configHome, renderProvisionedHookSet(hooks));
+  }
+}
+
+/**
+ * Assemble the launch for `provider` from the resolved profile + provisioning. PURE:
+ * resolves which declared assets exist (filesystem reads) but writes nothing. A missing
+ * `agentProfile` assembles the legacy default (host base, relay features on, no provisioning).
+ */
+export function assembleLaunch(provider: SpawnProvider, config: RunnerSpawnConfig, providerConfig: ProviderConfig): AssembledLaunch {
+  const assembler = ASSEMBLERS[provider];
+  if (!assembler) throw new Error(`no launch assembler registered for provider: ${provider}`);
+  const hostDefaultArgs = profileUsesProviderHostGlobals(config) ? providerConfig.defaultArgs : [];
+  return assembler(config, providerConfig, hostDefaultArgs);
+}
+
+/**
+ * Write the provisioned assets the assembly describes (skills/plugins/hooks and Codex
+ * hooks.json). Driven by the SAME resolvers `assembleLaunch` uses, so disk == launch ==
+ * report. Idempotent; the isolated home must already exist (prepare*ProfileHome). No-op
+ * for a host-base profile.
+ */
+export function materializeLaunchAssembly(provider: SpawnProvider, config: RunnerSpawnConfig): void {
+  const configHome = providerHomePathFor(provider, config);
+  const assetHome = providerProvisioningHomePathFor(provider, config);
+  if (!configHome && !assetHome) return;
+  const materializer = MATERIALIZERS[provider];
+  if (materializer) materializer(config);
+}