agent-relay-server 0.121.5 → 0.122.1

package/runner/src/launch-assembly.ts

@@ -0,0 +1,508 @@
+import { existsSync, readdirSync } from "node:fs";
+import { resolve, join } from "node:path";
+import type { AgentProfile, AgentProfileBase, 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 { claudeLaunchPromptGateSettings } from "./claude-prompt-gates";
+import {
+  materializeResolvedAssets,
+  resolveClaudeProjectSkills,
+  resolveClaudeHostSkills,
+  resolveProjectClaudeSettings,
+  resolveClaudeProvisionedPlugins,
+  resolveClaudeProvisionedSkills,
+  resolveCodexProvisionedSkills,
+  resolveProjectMcpServers,
+  profileProvisioning,
+} 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 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");
+}
+
+function claudeSettingsArgs(
+  projectSettings: Record<string, unknown>,
+  includeStatusLine: boolean,
+  ...argLists: string[][]
+): string[] {
+  if (argLists.some(hasSettingsArg)) return [];
+  const settings = {
+    ...projectSettings,
+    ...(includeStatusLine ? relayStatusLineSettings() : {}),
+  };
+  return Object.keys(settings).length ? ["--settings", JSON.stringify(settings)] : [];
+}
+
+// ── 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) : [];
+
+  // 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,
+    }),
+    ...claudeSettingsArgs(projectSettings.settings, statusLine, hostDefaultArgs, config.providerArgs),
+    ...(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 } : {}),
+    },
+    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) : [];
+  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: [] },
+    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))));
+  }
+  if (assetHome) materializeResolvedAssets(resolveClaudeProvisionedPlugins(assetHome, config));
+}
+
+function materializeCodexAssets(config: RunnerSpawnConfig): void {
+  const assetHome = providerProvisioningHomePathFor("codex", config);
+  if (assetHome) materializeResolvedAssets(resolveCodexProvisionedSkills(assetHome, config));
+}
+
+/**
+ * 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 (Claude skills + plugins, Codex
+ * skills). 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);
+}

package/runner/src/liveness.ts

@@ -0,0 +1,50 @@
+import type { LivenessSignal } from "agent-relay-sdk";
+
+// The raw runner-tracked signals an adapter folds into a normalized LivenessSignal.
+// This is the INPUT to the contract computation (#746): the runner owns this state
+// (transport frames, the last provider event, the pending timeline transition, the
+// active-work set), passes it to the adapter's `liveness()` verdict, and ships the
+// resulting LivenessSignal on the agent card. Provider-raw interpretation stops here —
+// nothing above the runner ever reads these fields again.
+export interface LivenessInputs {
+  /** Runner→server transport frame/ack timestamps (sdk BusClient.transportState). */
+  transport?: { lastServerFrameAt?: number; lastHeartbeatAckAt?: number };
+  /** Epoch-ms of the most recent provider status/token event the runner observed. */
+  lastProviderEventAt?: number;
+  /** The most recent lifecycle/timeline transition the runner published (status + ts). */
+  timelineEvent?: { status?: string; timestamp?: number };
+  /** Active work records. The adapter classifies its own kinds; `provider-turn` is the
+   *  bare turn, anything else (subagent, background-script, tool, subprocess) is live work. */
+  activeWork: Array<{ kind?: string; startedAt?: number }>;
+  /** Fallback progress floor when no other progress evidence exists yet (e.g. work start). */
+  fallbackProgressAt?: number;
+}
+
+function num(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+/**
+ * The shared liveness fold (#725 / #746). Both reference adapters (Claude #713, Codex #724)
+ * route through this so the verdict is computed in ONE place; each adapter's `liveness()`
+ * decides WHICH raw signals it feeds in (Claude surfaces a `compacting` timeline transition
+ * as progress; Codex surfaces live subprocess work-kinds). The fold itself is provider-
+ * agnostic, which is the point of the contract: a new provider only has to feed its signals.
+ */
+export function computeLivenessSignal(inputs: LivenessInputs): LivenessSignal {
+  const transportLiveAt = Math.max(
+    num(inputs.transport?.lastServerFrameAt),
+    num(inputs.transport?.lastHeartbeatAckAt),
+  );
+  // Progress = provider tokens OR a lifecycle/timeline transition (e.g. native compaction,
+  // #713) — whichever is latest, with the caller-supplied floor as the baseline.
+  const lastProgressAt = Math.max(
+    num(inputs.lastProviderEventAt),
+    num(inputs.timelineEvent?.timestamp),
+    num(inputs.fallbackProgressAt),
+  );
+  // Any work-kind that is NOT the bare provider turn is live tool/subprocess work (#724):
+  // a wedged provider turn with a live `bun test` child must read as progressing.
+  const hasLiveWork = inputs.activeWork.some((work) => Boolean(work.kind && work.kind !== "provider-turn"));
+  return { transportLiveAt, lastProgressAt, hasLiveWork };
+}

package/runner/src/logger.ts

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