@humwick/server 0.0.0-stage → 0.130.1

package/runner/src/launch-assembly.ts

@@ -0,0 +1,955 @@
+import { bundledIntegrationAssets, bundledIntegrationHome, suppressOwnedClaudePlugins, selectClaudePluginDirs } from "./provider-integration";
+import { relayEnv, writeChildEnv } from "@humwick/sdk/env";
+import { codexRetiredMcpConfigArgs } from "./adapters/codex-effective-config";
+import { activeSharedMcpServers, HARNESS_SUBAGENTS_DISABLED, harnessSubagentsEnabled } from "@humwick/sdk";
+import { claudeSubagentHooks, claudeSubagentSettings } from "./adapters/claude-subagents";
+import { serviceAccessLaunchEnv, serviceAccessMcpServers } from "./adapters/service-access";
+import { claudeSettingsArgs, CLAUDE_NO_ATTRIBUTION_RULE, extractCallerSettings, stripSettingsArgs, mergeHookSets, hasSettingsArg, sessionStatusLineSettingsArgs } from "./claude-settings";
+export { stripSettingsArgs, sessionStatusLineSettingsArgs } from "./claude-settings";
+import { rmSync, writeFileSync } from "node:fs";
+import { basename, relative, resolve, join } from "node:path";
+import { isCodexLeanWorkerProfile, profileMcpCells, type AgentProfile, type AgentProfileBase, type ProvisioningHookSet, type ProvisioningMcpServer, type SpawnProvider } from "@humwick/sdk";
+import { shellQuote } from "@humwick/sdk/shell-utils";
+import {
+  profileAllowsRelayFeature,
+  resolveRelayContext,
+  profileIsVanillaBase,
+  type ProviderConfig,
+  type RunnerSpawnConfig,
+} from "./adapter";
+import {
+  hostUserScopeMcpServers,
+  providerHomePathFor, materializeProviderHome,
+  providerHostConfigHome,
+  providerSourceHome,
+  projectSettingSources,
+} from "./profile-home";
+import { claudeHostPlan, claudeHostReport, nativeHostPlan, nativeHostReport, writeCodexHostSettings, codexHostPlan, codexHostReport, hostProviderDefaultArgs, hostSourcesFor, materializeHostAssets, skillDirsUnder, type HostSourceReport } from "./host-asset-plan";
+import { hostClaudeHooks, hostCodexHooks, hostCodexMcpServers } from "./host-sources";
+import { getAllManifests, getManifest } from "@humwick/providers";
+import { codexHooksSupported } from "./adapters/codex-version";
+import { claudeLaunchPromptGateSettings } from "./adapters/claude-prompt-gates";
+import { claudeHarnessTrim } from "./adapters/claude-tool-policy";
+import {
+  materializeResolvedAssets,
+  renderProvisionedHookSet,
+  resolveClaudeSkillSources, resolveClaudeProvisionedPlugins,
+  resolveCodexProvisionedSkills,
+  resolveProvisionedHooks,
+  profileProvisioning, fffMcpHookEnv,
+  codexSessionHookArgs,
+  writeCodexHooksJson,
+  writeClaudeSettingsJson, claudeBypassPermissionSettings, claudeGuardedRelaySettings, claudeHostInstructionExcludeSettings, mergeClaudeRelayPermissions, withManagedClaudePermissions, type ResolvedSourceShadow,
+} from "./provisioning";
+import type { ResolvedProjectClaudeSettings } from "./provisioning";
+import { resolveMcpSources, type McpSourceSelection } from "./mcp-source-selection";
+import { resolveProjectHooks } from "./project-hooks";
+import { agentRedactEnv, agentRedactOn, isAgentRedactInstall, resolveAgentRedact, type AgentRedactState } from "./agent-redact";
+import { composeSystemPromptAppend } from "./project-instructions";
+import { claudeWebToolsSteer, disabledSharedWebTools, webToolsEnv, withDisabledWebTools } from "./web-tools";
+import {
+  claudeMcpConfigPayload,
+  claudeMcpLaunchArgs,
+  codexProvisionedMcpArgs,
+  codexProvisionedMcpTimeoutArgs,
+  openCodeMcpConfigPayload,
+  relayMcpCodexConfigArgs, runnerMcpGeneration,
+  sharedMcpMetaOnlyServer,
+  writeSharedMcpMetaOnlyConfig,
+  SHARED_MCP_METAONLY_CONFIG_FILENAME,
+  type MetaOnlyRelayDownstream,
+  tomlInlineValue,
+  tomlString,
+  upsertTomlTable,
+  writeCodexMcpServersToml,
+  SHARED_MCP_SERVER_NAME, runnerManagedToolDeferralRoute,
+} from "./relay-mcp";
+import {
+  applyNativeMemoryBelt,
+  claudeManagedNativeMemorySettings,
+  resolveClaudeNativeMemoryLever,
+  resolveNativeMemoryLever,
+  writeCodexFeaturesToml,
+  type NativeMemoryLever,
+} from "./native-memory-lever";
+
+// #1565 P5.7 — relay's inline `--settings` actually reaches this launch. Same gate
+// `claudeSettingsArgs` applies below, passed to the lever so its applied/suppressed report cannot
+// claim a settings key the merge then drops.
+const callerSettingsMergeable = (argLists: string[][], cwd?: string): boolean => {
+  const caller = extractCallerSettings(argLists, cwd);
+  return !caller || Boolean(caller.settings);
+};
+
+// #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" | "reinjected" | "isolated" | "unsupported";
+
+export interface AssembledInstructions {
+  /** Repo CLAUDE.md/AGENTS.md cascade: "allow" left available, "suppressed" by the
+   *  vanilla launch mechanism, "reinjected" when the native project scope is dropped (to gate
+   *  ambient hooks) but P.instructions re-injects the repo docs through the controlled
+   *  append-system-prompt channel (#2086), "unsupported" requested-but-not-enforced. */
+  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) is configured for this launch. `launchContextPending` distinguishes providers that
+   *  can only transport it with their first turn from providers that emit it at process 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 {
+  generation?: import("@humwick/sdk").ToolGeneration;
+  /** 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/#2075 — 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. Isolated homes receive the
+   *  explicit host cell too; non-host modes stay empty. Codex reports its host config.toml
+   *  servers through the same field. */
+  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). #1450 —
+   *  `relayFronted` marks a metaOnly callmux that ALSO fronts the relay endpoint on-demand as a
+   *  second downstream (via the runner proxy, so identity/#215 hold); the relay stays per-agent. */
+  sharedListener?: { url: string; metaOnly?: boolean; relayFronted?: boolean };
+}
+
+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;
+  /** #1963 N3 — the effective Claude `--setting-sources` this launch emits, or undefined when the
+   *  flag is ABSENT. Absent means the provider default loads EVERY scope: empirically
+   *  `user,project,local` on Claude 2.1.x (measured with a controlled probe — the CLI documents the
+   *  valid sources but not the absent-flag default; see #1963 R1.0). An explicit array names the ONLY
+   *  scopes that load, so the ambient project (`.claude/settings.json`, repo CLAUDE.md/AGENTS.md) and
+   *  local (`.claude/settings.local.json`) scopes are DROPPED. Always undefined for Codex, which has
+   *  no `--setting-sources` surface (it suppresses the project doc via `project_doc_max_bytes=0`). */
+  settingSources?: string[];
+  /** Generic Relay context emitted at launch / reserved for a first provider turn; `launchContextPending` is the composed systemPromptAppend counterpart. */ relayContext: boolean; relayContextPending?: boolean; launchContextPending?: boolean;
+  /** Bundled Relay skills are emitted through the provider's native channel. */
+  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` stays on Claude's native project-settings path (#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[];
+  /** Host hooks explicitly re-injected into an isolated Claude settings.json. */
+  hostHooks: boolean;
+  /** Whether this provider exposes a lever for host hooks in an isolated config home. */
+  hostHooksEnforceable: boolean;
+  /** Project-committed hooks resolved through the trust-gated materializer. */
+  projectHooks: AssembledAsset[];
+  /** Project hooks requested by the source matrix but denied by the server trust gate. */
+  projectHooksSuppressed?: { reason: string };
+  /** #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[] };
+  /** #1565 P5.7 — the provider-NATIVE-memory lever this launch carries. `policy:"default"` means
+   *  the profile declared nothing: no env/arg/settings key was emitted and the launch is
+   *  byte-identical to a pre-P5.7 one. Any other policy renders EXPLICITLY in both directions.
+   *  `suppressed` names a lever that was resolved but could not be delivered on this base — the
+   *  `hooksSuppressed` anti-lie precedent (#1096), so a lever is never silently absent. */
+  nativeMemory: NativeMemoryLever;
+  /** #1096 review — Claude only: true when the caller's own `--settings` was folded into the
+   *  relay-emitted `--settings` (relay hooks/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[];
+  /** #3387 — native host plugins (Claude installed-plugin registry ids) this launch's home carries. */
+  hostPlugins: string[];
+  /** #3387 — per host asset class: applied, selected-empty, disabled or unsupported. */
+  hostSources: HostSourceReport;
+  /** #3387 — the central provider defaultArgs this launch carries (Settings/defaults class). */
+  hostDefaultArgs: string[];
+  mcp: AssembledMcp;
+  /** Lower-precedence source assets intentionally omitted from the emitted launch. */
+  sourceShadows?: ResolvedSourceShadow[];
+  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>;
+  /** #3025 — whether agent-redact's post-tool hooks reached this launch, and how. */
+  redaction: AgentRedactState;
+}
+
+// ── 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 CODEX_BUNDLED_SKILLS_DIR = resolve(import.meta.dir, "../plugins/codex/skills");
+
+export function bundledCodexSkillDirs(baseDir = CODEX_BUNDLED_SKILLS_DIR): string[] {
+  return skillDirsUnder(baseDir);
+}
+
+export function bundledSkillConfigArgs(skillDirs = bundledCodexSkillDirs(), disabledDirs: string[] = []): string[] {
+  const entries = [...skillDirs.map((dir) => `{path=${tomlString(dir)},enabled=true}`), ...disabledDirs.map((dir) => `{path=${tomlString(dir)},enabled=false}`)];
+  return entries.length ? ["-c", `skills.config=[${entries.join(",")}]`] : [];
+}
+
+function codexSkillSources(config: RunnerSpawnConfig) {
+  const home = providerHomePathFor("codex", config);
+  const provisioned = home ? resolveCodexProvisionedSkills(home, config) : [];
+  const bundled = !config.agentProfile && profileAllowsRelayFeature(config, "skills") ? bundledIntegrationAssets(config).map(asset => asset.dir) : [];
+  // #3387 — the managed CODEX_HOME hides the host's own skills; Host Skills on names them as roots,
+  // off disables the ambient ones Codex would still discover from HOME.
+  const host = home ? codexHostPlan(config, providerSourceHome("codex")) : undefined;
+  const hostRoots = host?.skillRoots ?? [];
+  return { provisioned, bundled, hostRoots, disabled: host?.disabledSkillRoots ?? [], roots: [...bundled, ...provisioned.map((skill) => skill.dir), ...hostRoots] };
+}
+
+/** The same selected roots feed both enablement config and native discovery. */
+export function codexSkillRoots(config: RunnerSpawnConfig): string[] {
+  return codexSkillSources(config).roots;
+}
+
+// #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"] : [];
+}
+
+// #1096 — the settings.json relay WRITES into an isolated managed Claude home so the provisioned
+// hooks (baseline guard included) land in the DOCUMENTED hook source Claude honors
+// ($CLAUDE_CONFIG_DIR/settings.json — loaded under `--setting-sources "user"` and the default),
+// rather than riding ONLY the inline `--settings` CLI flag. Claude does not document `--settings`
+// as a hook source, and — unlike a file written straight to disk — that flag's JSON must survive
+// shell/tmux launcher transit and passes Claude's "silently ignore settings that fail validation"
+// gate; a written settings.json bypasses both, so the baseline guard can't be silently absent
+// (the #1096 inert-at-runtime symptom). Returns null when:
+//   • there is NO isolated managed home (host base reuses the real ~/.claude — relay must not
+//     clobber it; that path keeps the inline --settings delivery), or
+//   • a caller --settings is present (the merge/suppression path owns hook delivery inline; see
+//     claudeSettingsArgs) — so the file and inline channels never DOUBLE-register the same hook.
+// Both assembleClaude (to keep these hooks OUT of the inline --settings) and materializeClaudeAssets
+// (to write the file) call this, so the launch and the disk agree.
+export function claudeManagedHookSettings(config: RunnerSpawnConfig, configHome: string | undefined, provider: string = "claude"): { hooks: ProvisioningHookSet } | null {
+  if (!configHome) return null;
+  if (hasSettingsArg(hostProviderDefaultArgs(config)) || hasSettingsArg(config.providerArgs)) return null;
+  const relayHooks = renderProvisionedHookSet([...resolveProjectHooks(config), ...resolveProvisionedHooks(configHome, config)]);
+  const hostHooks = hostSourcesFor(config).hooks ? hostClaudeHooks(config, provider) : {};
+  const redact = resolveAgentRedact();
+  const hookSet = mergeHookSets(mergeHookSets(mergeHookSets(hostHooks, relayHooks), isAgentRedactInstall(redact) ? redact.claudeHooks : {}), claudeSubagentHooks(config));
+  return Object.keys(hookSet).length ? { hooks: hookSet } : null;
+}
+
+// ── Instruction disposition (the vanilla floor's effect on the host instruction cascade) ──
+
+// #1963 N1/N3 — the disposition follows the launch FACT, not the profile's declared policy alone.
+// `projectScopeDropped` is true whenever the project setting-source is not loaded (Claude
+// `--setting-sources user`, emitted for a vanilla base OR a projectConfigProjection launch; Codex
+// `project_doc_max_bytes=0` for a vanilla base). When it is dropped, the repo CLAUDE.md/AGENTS.md
+// cascade genuinely does not load — so we report `suppressed` even without an explicit `ignore`
+// policy, instead of the old `allow` that lied for every projectConfigProjection agent (the live
+// worker/reviewer). `isolatedHome` is true when a managed provider config home is in use, which
+// never loads host/global provider config regardless of the `globalInstructions` policy — so a
+// minimal/isolated base OR a base:"host"+projectConfigProjection agent reports `isolated`, not the
+// old `allow` that lied for the isolated prod reviewer.
+function repoInstructionDisposition(profile: AgentProfile, projectScopeDropped: boolean, reinjected: boolean): AssembledInstructionDisposition {
+  // #2086 — the drop is not silent when P.instructions re-injects the repo docs through the
+  // controlled channel: the cascade is honored, just via append-system-prompt instead of the
+  // native project scope. Report that FACT so the anti-lie projection never says "suppressed"
+  // for a launch that actually carries the repo instructions.
+  if (reinjected) return "reinjected";
+  if (projectScopeDropped) return "suppressed";
+  if (profile.instructions.repoInstructions === "allow") return "allow";
+  // The project scope is still loaded, so an `ignore` request is not enforced at launch yet.
+  return "unsupported";
+}
+
+function globalInstructionDisposition(profile: AgentProfile, isolatedHome: boolean): AssembledInstructionDisposition {
+  // #1963 N1 review (P1): key on whether host globals are ACTUALLY linked, not on is-isolated-home.
+  // `linkHostGlobalInstructionFiles` (profile-home.ts) symlinks the host global CLAUDE.md into the
+  // managed home whenever `globalInstructions:"allow"` — even for an isolated base — so "allow" means
+  // globals ARE present and reporting "isolated" there would be a false report. Only an `ignore`
+  // request on an isolated home actually omits them.
+  if (profile.instructions.globalInstructions === "allow") return "allow";
+  if (isolatedHome) return "isolated";
+  // Host config home + `ignore`: no isolation to enforce the drop at launch yet.
+  return "unsupported";
+}
+
+function assembleInstructions(config: RunnerSpawnConfig, opts: { projectScopeDropped: boolean; isolatedHome: boolean; repoInstructionsReinjected: boolean }): 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, opts.projectScopeDropped, opts.repoInstructionsReinjected) : "allow",
+    global: profile ? globalInstructionDisposition(profile, opts.isolatedHome) : "allow",
+    systemPromptAppend: Boolean(config.systemPromptAppend?.trim()),
+    scopedKnowledge: "none",
+  };
+}
+
+// ── Per-provider MCP resolution (shared by assemble + materialize) ─────────────────
+
+interface ClaudeMcpResolution extends McpSourceSelection {
+  strictMcp: boolean;
+}
+
+// Assembly and materialization consume identical sources; only provider serialization differs.
+function resolveFlatDeclaredMcp(
+  config: RunnerSpawnConfig,
+  hostMcp: Record<string, ProvisioningMcpServer>,
+  strictMcp: boolean,
+): ClaudeMcpResolution {
+  const selected = resolveMcpSources(config, activeSharedMcpServers(hostMcp));
+  return {
+    ...selected,
+    declaredMcp: serviceAccessMcpServers(config, selected.declaredMcp),
+    hostMcp: serviceAccessMcpServers(config, selected.hostMcp),
+    strictMcp,
+  };
+}
+
+function resolveClaudeDeclaredMcp(config: RunnerSpawnConfig): ClaudeMcpResolution {
+  const hostMcpInjected = !config.agentProfile || profileMcpCells(config.agentProfile).host;
+  return resolveFlatDeclaredMcp(
+    config,
+    hostMcpInjected ? hostUserScopeMcpServers(config) : {},
+    claudeLaunchPromptGateSettings(config).strictMcpConfig,
+  );
+}
+
+// OpenCode always launches under an isolated XDG tree, so no ambient host MCP config is copied.
+// The Relay endpoint, trusted project declarations, provisioned servers, and shared callmux bridge
+// still use the same flat-source resolver as Claude so precedence/projection cannot drift.
+function resolveOpenCodeDeclaredMcp(config: RunnerSpawnConfig): ClaudeMcpResolution {
+  return resolveFlatDeclaredMcp(config, {}, false);
+}
+
+/** The exact native MCP map materialized into this OpenCode launch's `opencode.json`. */
+export function openCodeMcpConfigForLaunch(config: RunnerSpawnConfig): Record<string, unknown> {
+  const { declaredMcp, relayEndpoint } = resolveOpenCodeDeclaredMcp(config);
+  return openCodeMcpConfigPayload({
+    relayUrl: config.relayUrl,
+    generation: runnerMcpGeneration(config.env),
+    ...(config.relayMcpEndpoint ? { endpoint: config.relayMcpEndpoint } : {}),
+    includeRelay: relayEndpoint,
+    servers: declaredMcp,
+  });
+}
+
+interface CodexMcpResolution extends McpSourceSelection {
+  /** #1575 — set when the shared-listener route is served through a per-agent metaOnly callmux
+   *  (Codex worker) rather than the plain flat bridge. Carries the exact config path/url/cwd so
+   *  materializeCodexAssets writes the SAME file assembleCodex's descriptor points at. #1450 —
+   *  `relay` adds the identity-bearing relay endpoint as a SECOND downstream (via the runner proxy)
+   *  when the proxy is active, so the on-demand relay set loads through callmux_call. */
+  metaOnlyCallmux?: { configPath: string; url: string; cwd: string; relay?: MetaOnlyRelayDownstream };
+}
+
+// #1575 — a Codex worker swaps the flat shared-listener bridge for a per-agent metaOnly callmux so
+// the ~40 downstream schemas load on demand. Gated exactly like phase C's relay allowlist (#1570):
+// an explicitly worker-classified profile AND a provider whose manifest eager-loads every tool
+// schema (no client-native deferral). Data-driven from the manifest, never a provider-identity
+// branch — Claude (client-defers) never takes this path, coordinators/reviewers keep the flat
+// bridge. Requires a relay-owned provisioning home to materialize the per-agent config into (never
+// the host ~/.codex); worker profiles are isolated, so this holds.
+function codexMetaOnlyCallmuxConfigPath(config: RunnerSpawnConfig): string | undefined {
+  if (!isCodexLeanWorkerProfile(config.agentProfile?.name)) return undefined;
+  // #3024 — callmux_call reaches every listener tool and callmux has no per-downstream denylist, so a
+  // profile with a web tool off keeps the flat bridge, where Codex's disabled_tools hides it.
+  if (disabledSharedWebTools(config).length) return undefined;
+  if (!runnerManagedToolDeferralRoute("codex")) return undefined;
+  const home = providerHomePathFor("codex", config);
+  return home ? join(home, SHARED_MCP_METAONLY_CONFIG_FILENAME) : undefined;
+}
+
+// Codex counterpart to resolveClaudeDeclaredMcp — same purity/consistency contract, shared
+// by assembleCodex and materializeCodexAssets.
+function resolveCodexDeclaredMcp(config: RunnerSpawnConfig): CodexMcpResolution {
+  const hostMcpInjected = !config.agentProfile || profileMcpCells(config.agentProfile).host;
+  const selected = resolveMcpSources(config, hostMcpInjected ? hostCodexMcpServers() : {});
+  const { sharedListenerUrl, relayEndpoint } = selected;
+  const metaOnlyConfigPath = sharedListenerUrl ? codexMetaOnlyCallmuxConfigPath(config) : undefined;
+  // #1450 — front the relay endpoint on-demand through the SAME metaOnly callmux, but ONLY when the
+  // runner proxy is active (config.relayMcpEndpoint = the proxy URL, config.mcpProxySecret = its
+  // secret) AND the profile has the relay endpoint on. Routing through the proxy keeps the live
+  // token off disk (#215). This gate matches runner-core's proxy on-demand-hiding gate exactly, so
+  // the direct client's on-demand tools are hidden ONLY when this front simultaneously exists.
+  const metaOnlyRelay: MetaOnlyRelayDownstream | undefined =
+    metaOnlyConfigPath && relayEndpoint && config.relayMcpEndpoint && config.mcpProxySecret
+      ? { endpoint: config.relayMcpEndpoint, authSecret: config.mcpProxySecret, generation: runnerMcpGeneration(config.env) }
+      : undefined;
+  const metaOnlyCallmux = sharedListenerUrl && metaOnlyConfigPath
+    ? { configPath: metaOnlyConfigPath, url: sharedListenerUrl, cwd: config.cwd, ...(metaOnlyRelay ? { relay: metaOnlyRelay } : {}) }
+    : undefined;
+  const declaredMcp = serviceAccessMcpServers(config, {
+    ...selected.effectiveMcp,
+    ...(sharedListenerUrl ? {
+      [SHARED_MCP_SERVER_NAME]: metaOnlyCallmux
+        ? sharedMcpMetaOnlyServer(metaOnlyCallmux.configPath)
+        : withDisabledWebTools(selected.declaredMcp[SHARED_MCP_SERVER_NAME]!, config),
+    } : {}),
+  });
+  return { ...selected, declaredMcp, ...(metaOnlyCallmux ? { metaOnlyCallmux } : {}) };
+}
+
+// ── Per-provider arg assembly ──────────────────────────────────────────────────────
+
+// #2513 — `provider` parameterizes the claude family: claude-b reuses this assembler whole,
+// and every home/env derivation (providerHomePathFor, configHomeEnv) keys off the id so its
+// launch resolves the claude-b manifest's configDir instead of claude's.
+function assembleClaude(config: RunnerSpawnConfig, providerConfig: ProviderConfig, hostDefaultArgs: string[], provider: string = "claude"): AssembledLaunch {
+  const configHome = providerHomePathFor(provider, config);
+  const assetHome = configHome;
+  const hostPlan = configHome ? claudeHostPlan(config, providerSourceHome(provider), providerConfig) : nativeHostPlan(config, providerConfig);
+  const vanilla = profileIsVanillaBase(config);
+  const relayPlugin = profileAllowsRelayFeature(config, "plugins");
+  const relaySkills = profileAllowsRelayFeature(config, "skills");
+  // #3181 — the status line is how Relay tracks a Claude agent's context, so every profile gets it.
+  const statusLine = true;
+
+  const skillSources = configHome ? resolveClaudeSkillSources(configHome, config, provider) : { relay: [], project: [], host: [], shadows: [] };
+  const { relay: skills, project: projectSkills, host: hostSkills, shadows: skillSourceShadows } = skillSources;
+  // dec#11 — Project settings are ambient native Claude settings, not a Relay-owned
+  // copy. Keep the projection fact for the event/report contract, but do not read or
+  // materialize `.claude/settings.json` here.
+  const projectSettings: ResolvedProjectClaudeSettings = { applied: false, settings: {}, keys: [], ignoredKeys: [] };
+  const provisionedPlugins = assetHome ? resolveClaudeProvisionedPlugins(assetHome, config) : [];
+  const hookHome = configHome ?? assetHome;
+  const provisionedHooks = hookHome ? resolveProvisionedHooks(hookHome, config) : [];
+  const projectHooks = resolveProjectHooks(config);
+  const projectHooksSuppressed = config.agentProfile?.sources?.project?.hooks?.enabled && !config.agentProfile.projectGates?.hooks?.allowed
+    ? { reason: config.agentProfile.projectGates?.hooks?.detail ?? "partial — not acknowledged" }
+    : undefined;
+  const provisionedHookSet = renderProvisionedHookSet([...projectHooks, ...provisionedHooks]);
+  // #1096 — for an isolated managed home with no caller --settings, the provisioned hooks are
+  // delivered through the managed settings.json (the documented, transit-safe hook source), so
+  // keep them OUT of the inline --settings to avoid double-registering the same guard. Host-base
+  // and caller-`--settings` launches keep inline delivery (see claudeManagedHookSettings).
+  const managedHookSettings = claudeManagedHookSettings(config, configHome, provider);
+  const hostHooks = Boolean(configHome && managedHookSettings && hostPlan.selection.hooks && Object.keys(hostClaudeHooks(config, provider)).length);
+  const redact = resolveAgentRedact();
+  const inlineHookSet = managedHookSettings ? {} : mergeHookSets(mergeHookSets(provisionedHookSet, isAgentRedactInstall(redact) ? redact.claudeHooks : {}), claudeSubagentHooks(config));
+  const redaction = isAgentRedactInstall(redact) ? agentRedactOn(managedHookSettings ? "settings.json PostToolUse hooks" : "inline --settings PostToolUse hooks") : redact;
+  // #1565 P5.7 — the native-memory lever. Resolved BEFORE the settings args so its keys can ride
+  // relay's inline `--settings` (the only settings channel a host-base launch has); the env var
+  // below is the one that must always be present, and outranks both settings channels.
+  const nativeMemory = resolveClaudeNativeMemoryLever(config, configHome, hostDefaultArgs, (lists) => callerSettingsMergeable(lists, config.cwd), provider);
+  const settings = claudeSettingsArgs(
+    { ...projectSettings.settings, ...(relayPlugin ? { enabledPlugins: suppressOwnedClaudePlugins(undefined) } : {}), ...claudeGuardedRelaySettings(config.approvalMode, runnerMcpGeneration(config.env)), ...claudeHostInstructionExcludeSettings(config), ...claudeBypassPermissionSettings(config.approvalMode), ...claudeHarnessTrim(config).settings, ...claudeSubagentSettings(config) },
+    inlineHookSet,
+    [...projectHooks, ...provisionedHooks].map((h) => h.name),
+    statusLine,
+    nativeMemory.settings,
+    { cwd: config.cwd, model: config.model, generation: runnerMcpGeneration(config.env) },
+    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 ? bundledIntegrationAssets(config).map(asset => asset.dir) : [];
+  // `force-for-plugin: true` in this tiny plugin takes precedence over a caller or
+  // ambient `outputStyle` setting, so a host-base launch is covered too (there is no
+  // Relay-owned CLAUDE_CONFIG_DIR in which to write a custom style file).
+  const provisionedPluginDirs = provisionedPlugins.map((p) => p.dir);
+  const hostPluginDirs = selectClaudePluginDirs(hostPlan.pluginDirs, runnerMcpGeneration(config.env), relayPlugin);
+  const pluginDirs = [...new Set([resolve(import.meta.dir, "../plugins/claude-output-style"), ...relayPluginDirs, ...provisionedPluginDirs, ...hostPluginDirs])];
+
+  const { declaredMcp, hostMcp, relayEndpoint, strictMcp, mcpServers, projectServers, hostMcpServers, sharedListenerUrl, sourceShadows: mcpSourceShadows } =
+    resolveClaudeDeclaredMcp(config);
+
+  // #1292 — a provisioned/host server's env/headers can carry a literal secret; inline JSON
+  // in --mcp-config lands verbatim in argv (world-readable via ps/proc). Whenever there's a
+  // relay-owned scratch dir to write into (any launch with an agentProfile — see
+  // providerProvisioningHomePathFor, which gives even host-base profiles a relay-owned dir
+  // distinct from the real ~/.claude), route through a 0600 file instead. materializeClaudeAssets
+  // writes the file this path points at, from the SAME resolveClaudeDeclaredMcp(config) inputs.
+  const mcpConfigFilePath = assetHome ? join(assetHome, "mcp-config.json") : undefined;
+
+  // #2067 — derive Claude's native setting-source cascade from the Project cells.
+  // P.mcp and P.skills have their own controlled channels and are intentionally not
+  // triggers. The same list drives the instruction disposition report.
+  const settingSources = projectSettingSources(config);
+  const projectScopeDropped = Boolean(settingSources && !settingSources.includes("project"));
+  // #2086 — when P.hooks forces the project scope off but P.instructions is on, re-inject the repo
+  // CLAUDE.md/AGENTS.md through the controlled append-system-prompt channel so the docs are honored
+  // rather than silently dropped (see composeSystemPromptAppend / resolveProjectInstructions).
+  const { text: composedAppend, reinjected: repoInstructionsReinjected } = composeSystemPromptAppend(config);
+  const systemPromptAppend = [composedAppend, ...(harnessSubagentsEnabled(config) ? [] : [HARNESS_SUBAGENTS_DISABLED]), claudeWebToolsSteer(config), CLAUDE_NO_ATTRIBUTION_RULE].filter(Boolean).join("\n\n");
+  const instructions = assembleInstructions(config, {
+    projectScopeDropped,
+    isolatedHome: Boolean(configHome),
+    repoInstructionsReinjected,
+  });
+
+  // Launch order matches the historical claude buildSpawnArgs block exactly so existing
+  // arg assertions hold: vanilla scope → plugin dirs → MCP → status-line → append.
+  const args = [
+    ...(settingSources ? ["--setting-sources", settingSources.join(",")] : []),
+    ...pluginDirs.flatMap((dir) => ["--plugin-dir", dir]),
+    ...claudeMcpLaunchArgs({
+      relayUrl: config.relayUrl,
+    generation: runnerMcpGeneration(config.env),
+      ...(config.relayMcpEndpoint ? { endpoint: config.relayMcpEndpoint } : {}),
+      includeRelay: relayEndpoint,
+      servers: declaredMcp,
+      hostServers: hostMcp,
+      strict: strictMcp,
+      ...(mcpConfigFilePath ? { configFilePath: mcpConfigFilePath } : {}),
+    }),
+    ...settings.args,
+    ...(systemPromptAppend ? ["--append-system-prompt", systemPromptAppend] : []),
+  ];
+
+  return {
+    provider,
+    ...(config.agentProfile ? { profile: config.agentProfile } : {}),
+    base: config.agentProfile?.base ?? "host",
+    vanilla,
+    ...(configHome ? { configHome } : {}),
+    ...(settingSources ? { settingSources } : {}),
+    relayContext: resolveRelayContext({ slug: "relay.context.claude", config }).available,
+    // The Claude bundled skill channel is the bundled plugin itself. Profiled launches
+    // intentionally do not receive that plugin, even when relay.skills was requested.
+    relaySkills: relayPluginDirs.length > 0,
+    relayPlugin: relayPluginDirs.length > 0,
+    statusLine: settings.statusLineApplied,
+    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 })),
+    hostHooks,
+    hostHooksEnforceable: true,
+    projectHooks: projectHooks.map((h) => ({ name: h.name, dir: h.dir })),
+    ...(projectHooksSuppressed ? { projectHooksSuppressed } : {}),
+    ...(hooksSuppressed ? { hooksSuppressed } : {}),
+    nativeMemory,
+    callerSettingsConsumed: settings.callerSettingsConsumed,
+    plugins: provisionedPlugins.map((p) => ({ name: p.name, dir: p.dir })),
+    hostPluginDirs,
+    hostPlugins: hostPlan.pluginIds,
+    hostSources: claudeHostReport(hostPlan, { mcp: hostMcpServers.length > 0, hooks: hostHooks || (!configHome && hostPlan.selection.hooks), skills: hostSkills.length > 0, defaultArgs: hostDefaultArgs.length > 0, env: Object.keys(providerConfig.env ?? {}).length > 0 && hostPlan.selection.settings }),
+    hostDefaultArgs,
+    mcp: {
+      ...(runnerMcpGeneration(config.env) === "humwick" ? { generation: "humwick" as const } : {}),
+      relayEndpoint, strict: strictMcp, servers: mcpServers, projectServers, hostServers: hostMcpServers,
+      ...(sharedListenerUrl ? { sharedListener: { url: sharedListenerUrl } } : {}),
+    },
+    sourceShadows: [...skillSourceShadows, ...mcpSourceShadows],
+    instructions,
+    args,
+    env: writeChildEnv({}, { ...configHomeEnv(provider, configHome, config.env), ...nativeMemory.env, ...fffMcpHookEnv(config), ...webToolsEnv(config), ...agentRedactEnv(redaction) }),
+    redaction,
+  };
+}
+
+function assembleCodex(config: RunnerSpawnConfig, providerConfig: ProviderConfig, hostDefaultArgs: string[]): AssembledLaunch {
+  const configHome = providerHomePathFor("codex", config);
+  const vanilla = profileIsVanillaBase(config);
+  const relayEndpoint = profileAllowsRelayFeature(config, "mcp");
+
+  const { provisioned: provisionedSkills, bundled: bundledSkillDirs, hostRoots, disabled: disabledSkillDirs, roots: skillDirs } = codexSkillSources(config);
+  const hostPlan = configHome ? codexHostPlan(config, providerSourceHome("codex")) : undefined;
+  const hostSelection = hostSourcesFor(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 { declaredMcp, hostMcpServers, mcpServers, projectServers, sharedListenerUrl, metaOnlyCallmux, sourceShadows: mcpSourceShadows } = resolveCodexDeclaredMcp(config);
+  // Supported Codex releases consume CODEX_HOME/hooks.json. Host hooks are copied only when
+  // that real provider lever is available; older releases are left untouched and reported as
+  // unenforceable rather than claiming an artifact the provider ignores.
+  const hostHookSet = configHome && hooksSupported && hostSelection.hooks ? hostCodexHooks() : {};
+  const hostHooks = Object.keys(hostHookSet).length > 0;
+  // #3025 — redaction rides the `-c` session-flags layer, so host-base launches keep ~/.codex.
+  const redact = resolveAgentRedact();
+  const redaction: AgentRedactState = !isAgentRedactInstall(redact) ? redact
+    : !hooksSupported ? { state: "unavailable", reason: "installed Codex is older than 0.124 and ignores hooks" }
+      : agentRedactOn("-c session-flags PostToolUse hook (pre-trusted)");
+
+  // Codex has no `--setting-sources`: only a vanilla base drops the ambient project doc
+  // (`project_doc_max_bytes=0`); an isolated CODEX_HOME drops host/global config.toml. There is
+  // no P.hooks→scope-drop interference here (only a vanilla base suppresses the project doc), so
+  // Codex never re-injects repo instructions (#2086 is Claude's `--setting-sources` surface).
+  const instructions = assembleInstructions(config, {
+    projectScopeDropped: vanilla,
+    isolatedHome: Boolean(configHome),
+    repoInstructionsReinjected: false,
+  });
+
+  // #1292 — a provisioned/project server's env can carry a literal secret; `-c
+  // mcp_servers.<name>.env.<K>=<V>` lands verbatim in argv (world-readable via ps/proc).
+  // An ISOLATED CODEX_HOME is a relay-owned per-instance dir Codex actually reads as its
+  // config home, so route command/args/url/env through CODEX_HOME/config.toml instead
+  // (materializeCodexAssets writes it) and keep only the non-secret timeout overrides in
+  // argv. Host-base Codex has no isolated CODEX_HOME to write into (it reuses the real
+  // ~/.codex, which relay must not persist provisioned secrets into) — same accepted gap as
+  // the hooksSuppressed carve-out above, unchanged from prior behavior.
+  const mcpArgs = configHome ? codexProvisionedMcpTimeoutArgs(declaredMcp) : codexProvisionedMcpArgs(declaredMcp);
+
+  // 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.
+  // #1565 P5.7 — Codex's native-memory lever rides the same `-c` argv precedent as the
+  // project-doc suppressor above it (`-c project_doc_max_bytes=0`). Argv outranks config.toml, so
+  // this is the portable/authoritative half; the isolated CODEX_HOME config.toml is the belt.
+  const nativeMemory = resolveNativeMemoryLever({ provider: "codex", config, isolatedHome: Boolean(configHome) });
+
+  const args = [
+    ...bundledSkillConfigArgs(skillDirs, disabledSkillDirs),
+    ...(relayEndpoint ? relayMcpCodexConfigArgs(config.relayUrl, config.relayMcpEndpoint, runnerMcpGeneration(config.env)) : []),
+    ...mcpArgs,
+    ...codexRetiredMcpConfigArgs(config),
+    ...codexProjectDocSuppressionArgs(config),
+    ...nativeMemory.args,
+    ...(redaction.state === "on" && isAgentRedactInstall(redact) ? codexSessionHookArgs(redact.codexHooks) : []),
+  ];
+
+  return {
+    provider: "codex",
+    ...(config.agentProfile ? { profile: config.agentProfile } : {}),
+    base: config.agentProfile?.base ?? "host",
+    vanilla,
+    ...(configHome ? { configHome } : {}),
+    relayContext: false, relayContextPending: resolveRelayContext({ slug: "relay.context.codex", config }).available,
+    // Profiled launches use only resolved provisioning; bundled skill dirs are emitted
+    // exclusively for profile-less launches.
+    relaySkills: bundledSkillDirs.length > 0,
+    relayPlugin: false,
+    statusLine: false,
+    skills: provisionedSkills.map((s) => ({ name: s.name, dir: s.dir })),
+    hostSkills: hostRoots.map((dir) => ({ name: basename(dir), dir })),
+    projectSkills: [],
+    projectSettings: { applied: false, keys: [], ignoredKeys: [] },
+    projectHooks: [],
+    hooks: provisionedHooks.map((h) => ({ name: h.name, dir: h.dir })),
+    hostHooks,
+    hostHooksEnforceable: !configHome || !hostSelection.hooks || hooksSupported,
+    ...(hooksSuppressed ? { hooksSuppressed } : {}),
+    nativeMemory,
+    callerSettingsConsumed: false,
+    plugins: [],
+    hostPluginDirs: [],
+    hostPlugins: [],
+    hostSources: hostPlan
+      ? codexHostReport(hostPlan, {
+        mcp: hostMcpServers.length > 0,
+        hooks: !hostSelection.hooks ? "disabled" : !hooksSupported ? "unsupported" : hostHooks ? "applied" : "selected-empty",
+        defaultArgs: hostDefaultArgs.length > 0,
+        env: Object.keys(providerConfig.env ?? {}).length > 0 && hostSelection.settings,
+      })
+      : nativeHostReport(),
+    hostDefaultArgs,
+    mcp: {
+      ...(runnerMcpGeneration(config.env) === "humwick" ? { generation: "humwick" as const } : {}),
+      relayEndpoint, strict: false, servers: mcpServers, projectServers, hostServers: hostMcpServers,
+      ...(sharedListenerUrl ? { sharedListener: { url: sharedListenerUrl, ...(metaOnlyCallmux ? { metaOnly: true } : {}), ...(metaOnlyCallmux?.relay ? { relayFronted: true } : {}) } } : {}),
+    },
+    sourceShadows: mcpSourceShadows,
+    instructions,
+    args,
+    env: writeChildEnv({}, { ...configHomeEnv("codex", configHome), ...webToolsEnv(config), ...agentRedactEnv(redaction) }),
+    redaction,
+  };
+}
+
+// OpenCode owns an isolated XDG tree inside its adapter rather than consuming Relay's generic
+// provider-home asset formats. It still needs a complete projection object: RunnerCore assembles
+// every normal provider before registration and launch-injection reporting.
+function assembleOpenCode(config: RunnerSpawnConfig, provider: string): AssembledLaunch {
+  const { relayEndpoint, mcpServers, projectServers, hostMcpServers, sharedListenerUrl, sourceShadows } = resolveOpenCodeDeclaredMcp(config);
+  const instructions = assembleInstructions(config, {
+    projectScopeDropped: false,
+    isolatedHome: true,
+    repoInstructionsReinjected: false,
+  });
+  const redact = resolveAgentRedact();
+  const redaction = isAgentRedactInstall(redact) ? agentRedactOn("OpenCode config plugins/agent-redact.ts (serve without --pure)") : redact;
+  return {
+    provider,
+    ...(config.agentProfile ? { profile: config.agentProfile } : {}),
+    base: config.agentProfile?.base ?? "host",
+    vanilla: profileIsVanillaBase(config),
+    // OpenCode has no launch-level instruction field: both independently gated blocks are sent
+    // only with the first initial/inbox turn. Keep availability distinct from an emitted launch
+    // artifact so projection never mistakes configured systemPromptAppend for delivery proof.
+    relayContext: false, relayContextPending: resolveRelayContext({ slug: "relay.context.opencode", config }).available, launchContextPending: Boolean(config.systemPromptAppend?.trim()),
+    relaySkills: false,
+    relayPlugin: false,
+    statusLine: false,
+    skills: [],
+    hostSkills: [],
+    projectSkills: [],
+    projectSettings: { applied: false, keys: [], ignoredKeys: [] },
+    hooks: [],
+    hostHooks: false,
+    hostHooksEnforceable: false,
+    projectHooks: [],
+    nativeMemory: resolveNativeMemoryLever({ provider, config }),
+    callerSettingsConsumed: false,
+    plugins: [],
+    hostPluginDirs: [],
+    hostPlugins: [],
+    // OpenCode owns its isolated XDG tree; no host class reaches it.
+    hostSources: { instructions: "unsupported", mcp: "unsupported", hooks: "unsupported", skills: "unsupported", plugins: "unsupported", settings: "unsupported" },
+    hostDefaultArgs: [],
+    mcp: {
+      ...(runnerMcpGeneration(config.env) === "humwick" ? { generation: "humwick" as const } : {}),
+      relayEndpoint, strict: false, servers: mcpServers, projectServers, hostServers: hostMcpServers,
+      ...(sharedListenerUrl ? { sharedListener: { url: sharedListenerUrl } } : {}),
+    },
+    sourceShadows,
+    instructions,
+    args: [],
+    env: writeChildEnv({}, { ...webToolsEnv(config), ...agentRedactEnv(redaction) }),
+    redaction,
+  };
+}
+
+// ── Manifest-driven env + dispatch ────────────────────────────────────────────
+
+function configHomeEnv(provider: string, configHome: string | undefined, launchEnv?: Record<string, string>): Record<string, string> {
+  const manifest = getManifest(provider);
+  const envVar = manifest?.home?.configDirEnvVar;
+  if (!envVar) return {};
+  if (configHome) return { [envVar]: configHome };
+  // #2513 review HIGH-1 — a dedicatedHome provider (claude-b) pins the env var at its OWN
+  // effective host home even on host-base/profile-less launches, so the provider binary
+  // never falls back to the primary family home (~/.claude). The primary providers
+  // (claude, codex) keep their historical no-export host-base behavior.
+  const hostHome = providerHostConfigHome(provider);
+  if (hostHome) return { [envVar]: hostHome };
+  // #772 — a caller passing launchEnv (claude) opts in to pinning the effective dir (launch
+  // env, else the runner's) so the session-status probe, which falls back to the runner's
+  // value, reads the dir the provider process uses. Unset everywhere stays unpinned.
+  if (!launchEnv) return {};
+  const effective = relayEnv(launchEnv, envVar) || relayEnv(process.env, envVar);
+  return effective ? { [envVar]: effective } : {};
+}
+
+type Assembler = (config: RunnerSpawnConfig, providerConfig: ProviderConfig, hostDefaultArgs: string[]) => AssembledLaunch;
+type Materializer = (config: RunnerSpawnConfig) => void;
+
+const claudeFamily = getAllManifests().filter((manifest) => manifest.shim?.kind === "claude-relay");
+const ASSEMBLERS: Record<string, Assembler> = {
+  ...Object.fromEntries(claudeFamily.map((manifest) => [manifest.id, (config: RunnerSpawnConfig, providerConfig: ProviderConfig, hostDefaultArgs: string[]) => assembleClaude(config, providerConfig, hostDefaultArgs, manifest.id)])),
+  codex: assembleCodex,
+  ...Object.fromEntries(getAllManifests().filter((manifest) => manifest.opencode).map((manifest) => [manifest.id, (config: RunnerSpawnConfig) => assembleOpenCode(config, manifest.id)])),
+};
+
+const MATERIALIZERS: Record<string, Materializer> = {
+  ...Object.fromEntries(claudeFamily.map((manifest) => [manifest.id, (config: RunnerSpawnConfig) => materializeClaudeAssets(config, manifest.id)])),
+  codex: materializeCodexAssets,
+};
+
+function materializeClaudeAssets(config: RunnerSpawnConfig, provider: string = "claude"): void {
+  const configHome = providerHomePathFor(provider, config);
+  if (!configHome) return;
+  const hostPlan = claudeHostPlan(config, providerSourceHome(provider));
+  const skillSources = resolveClaudeSkillSources(configHome, config, provider);
+  // #3387 — host classes first: drop what an opted-out class left in this reused home, then link
+  // the selected ones, before Relay/Project skills claim their names.
+  materializeHostAssets(configHome, hostPlan.links, hostPlan.files, skillSources.host.map((skill) => relative(configHome, skill.dir)));
+  materializeResolvedAssets(skillSources.relay);
+  materializeResolvedAssets(skillSources.project);
+  materializeResolvedAssets(skillSources.host);
+  materializeResolvedAssets(resolveProvisionedHooks(configHome, config));
+  materializeResolvedAssets(resolveProjectHooks(config));
+  // #1096 — land the provisioned hooks in the managed home's settings.json (the documented
+  // hook source), matching the assembler's decision to keep them out of the inline --settings.
+  // #1565 P5.7 — the native-memory keys ride the SAME file (the isolated-home belt behind the
+  // env lever). #3387 — so do the selected host settings and native plugin enablement: this is
+  // the one writer of the managed settings.json, so nothing later can wipe plugin enablement.
+  const managedHookSettings = claudeManagedHookSettings(config, configHome, provider);
+  const nativeMemorySettings = claudeManagedNativeMemorySettings(config, configHome, (lists) => callerSettingsMergeable(lists, config.cwd), provider);
+  // T3182 — the SendFeedback deny rides EVERY managed settings.json this launch writes (the
+  // file-channel belt behind the CLAUDE_CODE_SEND_FEEDBACK=0 env lever, so a stripped env
+  // still removes the tool): merged into the full payload AND the belt-retry payload so the
+  // retry can never drop it.
+  const withManagedPermissions = (settings: Record<string, unknown>) => withManagedClaudePermissions(settings, config.approvalMode, runnerMcpGeneration(config.env));
+  const baseSettings = { ...hostPlan.settings, ...(managedHookSettings ?? {}) };
+  // The hook and selected-host halves of this file are NOT best-effort (a missing baseline guard
+  // is a real regression, #1096; a selected host class must never silently vanish, #3387), so
+  // only the native-memory contribution is guarded: on a write failure, retry without it.
+  if (applyNativeMemoryBelt("the Claude managed settings.json", () => writeClaudeSettingsJson(configHome, withManagedPermissions({ ...baseSettings, ...nativeMemorySettings }))) && Object.keys(baseSettings).length) {
+    writeClaudeSettingsJson(configHome, withManagedPermissions(baseSettings));
+  }
+  materializeResolvedAssets(resolveClaudeProvisionedPlugins(configHome, config));
+  // #1292 — write the file assembleClaude's --mcp-config <path> points at, from the SAME
+  // resolveClaudeDeclaredMcp(config) inputs (see the purity/consistency note there). Keeps
+  // provisioned/host-server env/headers secrets out of argv.
+  const { declaredMcp, hostMcp, relayEndpoint, strictMcp } = resolveClaudeDeclaredMcp(config);
+  const mcpServers = claudeMcpConfigPayload({
+    relayUrl: config.relayUrl,
+    generation: runnerMcpGeneration(config.env),
+    ...(config.relayMcpEndpoint ? { endpoint: config.relayMcpEndpoint } : {}),
+    includeRelay: relayEndpoint,
+    servers: declaredMcp,
+    hostServers: hostMcp,
+  });
+  const mcpConfigPath = join(configHome, "mcp-config.json");
+  if (Object.keys(mcpServers).length || strictMcp) {
+    writeFileSync(mcpConfigPath, JSON.stringify({ mcpServers }, null, 2), { mode: 0o600 });
+  } else {
+    rmSync(mcpConfigPath, { force: true });
+  }
+}
+
+function materializeCodexAssets(config: RunnerSpawnConfig): void {
+  const configHome = providerHomePathFor("codex", config);
+  if (!configHome) return;
+  const hostPlan = codexHostPlan(config, providerSourceHome("codex"));
+  materializeHostAssets(configHome, hostPlan.links, []);
+  writeCodexHostSettings(configHome, hostPlan.settings, tomlInlineValue);
+  materializeResolvedAssets(resolveCodexProvisionedSkills(configHome, 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 (codexHooksSupported(config.providerConfig.command)) {
+    const relayHooks = resolveProvisionedHooks(configHome, config);
+    materializeResolvedAssets(relayHooks);
+    const relayHookSet = renderProvisionedHookSet(relayHooks);
+    const hostHookSet = hostPlan.selection.hooks ? hostCodexHooks() : {};
+    writeCodexHooksJson(configHome, mergeHookSets(hostHookSet, relayHookSet));
+  }
+  // #1292 — write the CODEX_HOME/config.toml sections assembleCodex's non-secret -c
+  // timeout-only overrides expect to find command/args/url/env in (see the mcpArgs branch
+  // there). Same resolveCodexDeclaredMcp(config) inputs, so disk == launch.
+  const { declaredMcp, metaOnlyCallmux } = resolveCodexDeclaredMcp(config);
+  writeCodexMcpServersToml(configHome, declaredMcp);
+  // #1565 P5.7 — the isolated-home belt behind the `-c features.memories=…` argv lever. Same
+  // resolveNativeMemoryLever inputs assembleCodex used, so disk == launch. No-op for an
+  // undeclared profile (`configToml` is empty, so nothing is written). Guarded: never fails the spawn.
+  applyNativeMemoryBelt("the Codex CODEX_HOME/config.toml [features] table", () => {
+    writeCodexFeaturesToml(configHome, resolveNativeMemoryLever({ provider: "codex", config, isolatedHome: true }).configToml);
+  });
+  // #1575/#1450 — write the per-agent metaOnly config the shared-listener descriptor points at
+  // (`callmux --config <path>`), from the SAME resolveCodexDeclaredMcp inputs so disk == launch.
+  // The optional relay downstream (#1450) rides here too, so the on-demand relay front and the
+  // agent's stdio callmux descriptor come from one resolution.
+  if (metaOnlyCallmux) {
+    writeSharedMcpMetaOnlyConfig(metaOnlyCallmux.configPath, metaOnlyCallmux.url, metaOnlyCallmux.cwd, metaOnlyCallmux.relay);
+  }
+}
+
+/**
+ * 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}`);
+  runnerManagedToolDeferralRoute(provider);
+  const hostDefaultArgs = hostProviderDefaultArgs(config, providerConfig);
+  const serviceEnv = serviceAccessLaunchEnv(config);
+  const assembled = assembler(config, providerConfig, hostDefaultArgs);
+  return { ...assembled, env: writeChildEnv({}, { ...assembled.env, ...serviceEnv }) };
+}
+
+/**
+ * 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 {
+  if (!config.agentProfile && runnerMcpGeneration(config.env) === "humwick") {
+    const feature = getManifest(provider)?.provisioning?.bundledSkills ? "skills" : "plugins";
+    if (profileAllowsRelayFeature(config, feature)) {
+      materializeProviderHome(bundledIntegrationHome(config), { provider, profile: "integrations", instanceId: config.instanceId || config.runnerId, agentId: config.agentId });
+      materializeResolvedAssets(bundledIntegrationAssets(config));
+    }
+  }
+  if (!providerHomePathFor(provider, config)) return;
+  const materializer = MATERIALIZERS[provider];
+  if (materializer) materializer(config);
+}