agent-relay-server 0.122.0 → 0.123.0

package/runner/src/outbox.ts

@@ -0,0 +1,342 @@
+import { Database } from "bun:sqlite";
+import { mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { tmpdir } from "node:os";
+import { sanitizeFsName } from "agent-relay-sdk/fs-name";
+import { errMessage } from "agent-relay-sdk";
+import { logger } from "./logger";
+import { runnerOutboxDirFromEnv } from "./config";
+
+// Phase 2 (#196) — the "nothing is ever lost" half. Runner→server events that used to be
+// fire-and-forget over HTTP (session turns, reasoning/tool traces, prompt echoes, insights,
+// hook-fatal reports) were silently dropped whenever the server was momentarily down. This
+// is a durable, FIFO, disk-backed queue that:
+//   - survives Runner/server restart (bun:sqlite file in the runtime dir),
+//   - stamps true event time (`occurredAt`) once at enqueue and preserves it through retries,
+//   - retries with capped exponential backoff, strictly in order (an append log must not
+//     reorder turns),
+//   - poisons a permanently-failing head after maxAttempts so it can't block the queue,
+//   - is bounded with a logged drop policy (never silently truncates).
+//
+// Status deliberately does NOT go through here: it rides the WebSocket bus, which is
+// last-wins and self-heals on reconnect (so it already satisfies "coalesce, don't replay
+// stale busyes"). The coalesce mode below exists so a future state event could migrate here.
+
+type OutboxMode = "append" | "coalesce";
+
+interface OutboxEventInput {
+  kind: string;
+  payload: unknown;
+  mode?: OutboxMode;
+  // Required for coalesce mode: prior un-poisoned rows with the same dedupeKey are replaced.
+  dedupeKey?: string;
+  // Defaults to now. Set explicitly only to backdate (e.g. replaying a captured timestamp).
+  occurredAt?: number;
+  // Defaults to a stable derived key so server-side dedup makes retries exactly-once.
+  idempotencyKey?: string;
+}
+
+export interface OutboxRecord {
+  seq: number;
+  kind: string;
+  mode: OutboxMode;
+  occurredAt: number;
+  idempotencyKey: string;
+  payload: unknown;
+  attempts: number;
+}
+
+// The transport. Resolve = delivered (row deleted). Reject = failed (retried with backoff).
+type OutboxSend = (record: OutboxRecord) => Promise<void>;
+
+interface OutboxOptions {
+  agentId: string;
+  send: OutboxSend;
+  // Storage directory. Defaults to AGENT_RELAY_RUNNER_OUTBOX_DIR, else a per-host temp dir.
+  dir?: string;
+  maxRows?: number;
+  maxAttempts?: number;
+  baseBackoffMs?: number;
+  maxBackoffMs?: number;
+  pollMs?: number;
+}
+
+const DEFAULTS = {
+  maxRows: 5000,
+  maxAttempts: 12,
+  baseBackoffMs: 1_000,
+  maxBackoffMs: 60_000,
+  pollMs: 5_000,
+};
+
+// Pause between forced delivery attempts during flush() — keeps a brief server outage
+// from hot-looping while still retrying fast enough to land within the flush deadline.
+const FLUSH_RETRY_PAUSE_MS = 150;
+
+interface Row {
+  seq: number;
+  kind: string;
+  mode: string;
+  occurred_at: number;
+  idempotency_key: string;
+  payload: string;
+  attempts: number;
+  next_attempt_at: number;
+  poisoned: number;
+}
+
+export class Outbox {
+  private readonly db: Database;
+  private readonly agentId: string;
+  private readonly send: OutboxSend;
+  private readonly maxRows: number;
+  private readonly maxAttempts: number;
+  private readonly baseBackoffMs: number;
+  private readonly maxBackoffMs: number;
+  private readonly pollMs: number;
+  readonly path: string;
+
+  private draining = false;
+  private rerun = false;
+  // Set by flush() to make the next drain pass ignore per-row backoff (deliver NOW).
+  private forceDue = false;
+  private pollTimer?: ReturnType<typeof setInterval>;
+  private dueTimer?: ReturnType<typeof setTimeout>;
+  private stopped = false;
+
+  constructor(options: OutboxOptions) {
+    this.agentId = options.agentId;
+    this.send = options.send;
+    this.maxRows = options.maxRows ?? DEFAULTS.maxRows;
+    this.maxAttempts = options.maxAttempts ?? DEFAULTS.maxAttempts;
+    this.baseBackoffMs = options.baseBackoffMs ?? DEFAULTS.baseBackoffMs;
+    this.maxBackoffMs = options.maxBackoffMs ?? DEFAULTS.maxBackoffMs;
+    this.pollMs = options.pollMs ?? DEFAULTS.pollMs;
+
+    const dir = options.dir ?? runnerOutboxDirFromEnv() ?? join(tmpdir(), "agent-relay-outbox");
+    this.path = options.dir === ":memory:" ? ":memory:" : join(dir, `outbox-${safeName(this.agentId)}.sqlite`);
+    if (this.path !== ":memory:") mkdirSync(dirname(this.path), { recursive: true });
+
+    this.db = new Database(this.path, { create: true });
+    this.db.exec("PRAGMA journal_mode = WAL");
+    this.db.exec("PRAGMA busy_timeout = 2000");
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS outbox (
+        seq INTEGER PRIMARY KEY AUTOINCREMENT,
+        kind TEXT NOT NULL,
+        mode TEXT NOT NULL DEFAULT 'append',
+        dedupe_key TEXT,
+        occurred_at INTEGER NOT NULL,
+        idempotency_key TEXT NOT NULL,
+        payload TEXT NOT NULL,
+        attempts INTEGER NOT NULL DEFAULT 0,
+        next_attempt_at INTEGER NOT NULL DEFAULT 0,
+        poisoned INTEGER NOT NULL DEFAULT 0,
+        created_at INTEGER NOT NULL
+      )
+    `);
+    // A restart is a fresh start: clear any backoff timers left by the prior process so
+    // pending events get an immediate retry (the down server may now be back). `attempts`
+    // is kept so the poison threshold still counts cumulative failures.
+    this.db.exec("UPDATE outbox SET next_attempt_at = 0 WHERE next_attempt_at > 0");
+  }
+
+  // Persist an event. Returns the assigned seq. Triggers a drain.
+  enqueue(input: OutboxEventInput): number {
+    if (this.stopped) throw new Error("outbox is stopped");
+    const mode: OutboxMode = input.mode ?? "append";
+    const occurredAt = input.occurredAt ?? Date.now();
+    const payloadJson = JSON.stringify(input.payload ?? null);
+    const idempotencyKey = input.idempotencyKey ?? `${this.agentId}:${input.kind}:${occurredAt}:${shortHash(payloadJson)}`;
+
+    if (mode === "coalesce") {
+      if (!input.dedupeKey) throw new Error("coalesce mode requires a dedupeKey");
+      this.db.query("DELETE FROM outbox WHERE dedupe_key = ? AND poisoned = 0").run(input.dedupeKey);
+    }
+
+    const info = this.db
+      .query(`INSERT INTO outbox (kind, mode, dedupe_key, occurred_at, idempotency_key, payload, created_at)
+              VALUES (?, ?, ?, ?, ?, ?, ?)`)
+      .run(input.kind, mode, input.dedupeKey ?? null, occurredAt, idempotencyKey, payloadJson, Date.now());
+    const seq = Number(info.lastInsertRowid);
+
+    this.enforceBound();
+    // Defer the drain to a microtask so a synchronous burst of enqueues (e.g. several
+    // coalesce updates) all land — and coalesce — before the pump pulls the head.
+    queueMicrotask(() => { void this.drain(); });
+    return seq;
+  }
+
+  // Bounded ring buffer: if over capacity, drop the oldest rows (defined overflow policy).
+  // Logged, never silent. Prefers dropping already-poisoned rows first, then oldest by seq.
+  private enforceBound(): void {
+    const { n } = this.db.query("SELECT count(*) AS n FROM outbox").get() as { n: number };
+    if (n <= this.maxRows) return;
+    const overflow = n - this.maxRows;
+    // Oldest poisoned first, then oldest live — both by seq.
+    const victims = this.db
+      .query("SELECT seq FROM outbox ORDER BY poisoned DESC, seq ASC LIMIT ?")
+      .all(overflow) as Array<{ seq: number }>;
+    const ids = victims.map((v) => v.seq);
+    if (ids.length === 0) return;
+    const placeholders = ids.map(() => "?").join(",");
+    this.db.query(`DELETE FROM outbox WHERE seq IN (${placeholders})`).run(...ids);
+    logger.warn("outbox", `bound exceeded (${n}/${this.maxRows}) — dropped ${ids.length} oldest event(s)`);
+  }
+
+  // Begin the background pump: an initial drain plus a poll timer as a backstop.
+  start(): void {
+    if (this.pollTimer || this.stopped) return;
+    void this.drain();
+    this.pollTimer = setInterval(() => { void this.drain(); }, this.pollMs);
+    this.pollTimer.unref?.();
+  }
+
+  // Drain everything we can before the process exits, ignoring per-row backoff. Used on
+  // shutdown/kill/crash (#183): the capture seam durably enqueues the end-of-session
+  // Insights datapoint, but the per-agent outbox is never reopened once the agent is gone,
+  // so a row that hasn't been POSTed yet is stranded forever. flush() blocks (bounded) on
+  // delivery — the opposite intent of the polite, backoff-respecting steady-state drain.
+  // Returns true if the queue fully drained within the deadline.
+  async flush(timeoutMs: number): Promise<boolean> {
+    const deadline = Date.now() + Math.max(0, timeoutMs);
+    for (;;) {
+      if (this.stopped) return this.pendingCount() === 0;
+      if (this.pendingCount() === 0) return true;
+      await this.drain(true);
+      if (this.pendingCount() === 0) return true;
+      if (Date.now() >= deadline) return false;
+      await new Promise<void>((resolve) => setTimeout(resolve, FLUSH_RETRY_PAUSE_MS));
+    }
+  }
+
+  // Process the queue strictly oldest-first. Coalesces concurrent calls; if a drain is
+  // requested while one is running, it re-runs once at the end (so an enqueue during a
+  // send isn't missed). `force` (from flush) makes this pass ignore per-row backoff.
+  async drain(force = false): Promise<void> {
+    if (this.stopped) return;
+    if (force) this.forceDue = true;
+    if (this.draining) { this.rerun = true; return; }
+    this.draining = true;
+    try {
+      do {
+        this.rerun = false;
+        const due = this.forceDue;
+        this.forceDue = false;
+        await this.drainOnce(due);
+      } while ((this.rerun || this.forceDue) && !this.stopped);
+    } finally {
+      this.draining = false;
+    }
+  }
+
+  private async drainOnce(force = false): Promise<void> {
+    for (;;) {
+      if (this.stopped) return;
+      const row = this.db
+        .query("SELECT * FROM outbox WHERE poisoned = 0 ORDER BY seq ASC LIMIT 1")
+        .get() as Row | null;
+      if (!row) return;
+
+      const now = Date.now();
+      if (!force && row.next_attempt_at > now) {
+        // Head isn't due yet. Don't reorder past it (FIFO) — schedule a wake-up and stop.
+        this.scheduleDue(row.next_attempt_at - now);
+        return;
+      }
+
+      const record: OutboxRecord = {
+        seq: row.seq,
+        kind: row.kind,
+        mode: row.mode as OutboxMode,
+        occurredAt: row.occurred_at,
+        idempotencyKey: row.idempotency_key,
+        payload: safeParse(row.payload),
+        attempts: row.attempts,
+      };
+
+      try {
+        await this.send(record);
+        this.db.query("DELETE FROM outbox WHERE seq = ?").run(row.seq);
+      } catch (error) {
+        const attempts = row.attempts + 1;
+        const reason = errMessage(error);
+        if (attempts >= this.maxAttempts) {
+          this.db.query("UPDATE outbox SET attempts = ?, poisoned = 1 WHERE seq = ?").run(attempts, row.seq);
+          logger.fatal("outbox", `event seq=${row.seq} kind=${row.kind} poisoned after ${attempts} attempts: ${reason}`);
+          // Move on — the next iteration picks the new head (poison no longer blocks).
+          continue;
+        }
+        const delay = this.backoff(attempts);
+        this.db.query("UPDATE outbox SET attempts = ?, next_attempt_at = ? WHERE seq = ?").run(attempts, now + delay, row.seq);
+        logger.debug("outbox", `event seq=${row.seq} kind=${row.kind} retry ${attempts}/${this.maxAttempts} in ${delay}ms: ${reason}`);
+        this.scheduleDue(delay);
+        return; // head is now scheduled; stop until it's due (preserve order)
+      }
+    }
+  }
+
+  // Pure per-row delay calc: the attempt count lives in SQLite (one outbox row
+  // at a time may be due), so this stays a stateless function rather than the
+  // stateful SDK ReconnectionManager (single in-memory counter) used for the
+  // orchestrator/voice reconnect loops — different model, deliberately not shared.
+  private backoff(attempts: number): number {
+    const exp = Math.min(this.maxBackoffMs, this.baseBackoffMs * 2 ** (attempts - 1));
+    return Math.round(exp / 2 + Math.random() * (exp / 2)); // full-ish jitter, never below half
+  }
+
+  private scheduleDue(delayMs: number): void {
+    if (this.stopped || this.dueTimer) return;
+    this.dueTimer = setTimeout(() => {
+      this.dueTimer = undefined;
+      void this.drain();
+    }, Math.max(0, delayMs));
+    this.dueTimer.unref?.();
+  }
+
+  // Observability / tests.
+  pendingCount(): number {
+    return (this.db.query("SELECT count(*) AS n FROM outbox WHERE poisoned = 0").get() as { n: number }).n;
+  }
+
+  updatePayload(seq: number, payload: unknown): void {
+    const payloadJson = JSON.stringify(payload ?? null);
+    this.db.query("UPDATE outbox SET payload = ? WHERE seq = ? AND poisoned = 0").run(payloadJson, seq);
+  }
+
+  poisonedCount(): number {
+    return (this.db.query("SELECT count(*) AS n FROM outbox WHERE poisoned = 1").get() as { n: number }).n;
+  }
+
+  stop(): void {
+    this.stopped = true;
+    if (this.pollTimer) clearInterval(this.pollTimer);
+    this.pollTimer = undefined;
+    if (this.dueTimer) clearTimeout(this.dueTimer);
+    this.dueTimer = undefined;
+  }
+
+  close(): void {
+    this.stop();
+    try { this.db.close(); } catch { /* already closed */ }
+  }
+}
+
+function safeName(value: string): string {
+  return sanitizeFsName(value, { replacement: "_", maxLen: 180, fallback: "agent" });
+}
+
+function safeParse(json: string): unknown {
+  try { return JSON.parse(json); } catch { return null; }
+}
+
+// Small, fast, stable string hash (FNV-1a, 32-bit) — enough to disambiguate identical
+// kind+timestamp payloads in the idempotency key. Not security-sensitive.
+function shortHash(value: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < value.length; i++) {
+    h ^= value.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return (h >>> 0).toString(36);
+}

package/runner/src/process-meta.ts

@@ -0,0 +1,9 @@
+import type { ManagedProcess } from "./adapter";
+
+export function providerTerminalSession(process?: ManagedProcess): string | undefined {
+  return typeof process?.meta?.tmuxSession === "string" ? process.meta.tmuxSession : undefined;
+}
+
+export function providerTerminalSocket(process?: ManagedProcess): string | undefined {
+  return typeof process?.meta?.tmuxSocket === "string" ? process.meta.tmuxSocket : undefined;
+}

package/runner/src/profile-home.ts

@@ -0,0 +1,260 @@
+import { existsSync, mkdirSync, readFileSync, symlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { sanitizeFsName } from "agent-relay-sdk/fs-name";
+import type { ProvisioningMcpServer, SpawnProvider } from "agent-relay-sdk";
+import { getManifest } from "agent-relay-providers";
+import { profileAllowsRelayFeature, type RunnerSpawnConfig } from "./adapter";
+import { claudeRelayManual } from "./relay-instructions";
+import { providerHomeRootFromEnv } from "./config";
+import { applyClaudeConfigPromptGatePreventions } from "./claude-prompt-gates";
+
+type ProviderHome = {
+  path: string;
+  authLinked: string[];
+};
+
+export function profileUsesHostProviderGlobals(config: { agentProfile?: RunnerSpawnConfig["agentProfile"] }): boolean {
+  return !config.agentProfile || config.agentProfile.base === "host";
+}
+
+export function profileAllowsHostAssets(
+  config: { agentProfile?: RunnerSpawnConfig["agentProfile"] },
+  asset: "skills" | "plugins",
+): boolean {
+  return profileUsesProviderHostGlobals(config) || Boolean(config.agentProfile?.hostAssets?.[asset]);
+}
+
+export function profileAllowsHostGlobalInstructions(config: { agentProfile?: RunnerSpawnConfig["agentProfile"] }): boolean {
+  return !config.agentProfile || config.agentProfile.instructions.globalInstructions === "allow";
+}
+
+export function projectConfigProjectionOn(config: { agentProfile?: RunnerSpawnConfig["agentProfile"] }): boolean {
+  return Boolean(config.agentProfile?.projectSkills || config.agentProfile?.projectSettings);
+}
+
+/** @deprecated Use {@link projectConfigProjectionOn}. */
+export { projectConfigProjectionOn as claudeProjectConfigProjectionOn };
+
+export function profileUsesProviderHostGlobals(config: { agentProfile?: RunnerSpawnConfig["agentProfile"] }): boolean {
+  return profileUsesHostProviderGlobals(config) && !projectConfigProjectionOn(config);
+}
+
+/** @deprecated Use {@link profileUsesProviderHostGlobals}. */
+export { profileUsesProviderHostGlobals as profileUsesClaudeHostProviderGlobals };
+
+function profileRequiresIsolatedHome(_provider: SpawnProvider, config: RunnerSpawnConfig): boolean {
+  if (!config.agentProfile) return false;
+  if (config.agentProfile.base !== "host") return true;
+  return projectConfigProjectionOn(config);
+}
+
+// #557 — PURE: the isolated provider config home path a launch WILL use, or undefined
+// for a host-base profile (which uses the provider's normal home). The launch assembler
+// computes the home this way to report it + build CLAUDE_CONFIG_DIR/skill/plugin paths
+// without side effects; prepare*ProfileHome creates it at the same path at spawn time.
+export function providerHomePathFor(provider: SpawnProvider, config: RunnerSpawnConfig): string | undefined {
+  if (!profileRequiresIsolatedHome(provider, config)) return undefined;
+  return providerHomePath(provider, config);
+}
+
+// Provisioned file-backed assets need a relay-owned materialization root even for
+// host-base profiles, where the provider's real config home stays in use. This path is
+// only passed explicitly through launch args such as Codex skills.config or Claude
+// --plugin-dir; it does not imply CODEX_HOME/CLAUDE_CONFIG_DIR isolation.
+export function providerProvisioningHomePathFor(provider: SpawnProvider, config: RunnerSpawnConfig): string | undefined {
+  if (!config.agentProfile) return undefined;
+  return providerHomePathFor(provider, config) ?? join(providerHomePath(provider, config), "provisioning");
+}
+
+// First-run bootstrap (provider layer)
+// -------------------------------------
+// Isolated profile homes are keyed by instanceId, so every spawn gets a brand
+// new CLAUDE_CONFIG_DIR / CODEX_HOME — to the provider it always looks like the
+// first time it has ever run, even in a repo we've used before. Without
+// bootstrapping, the CLI stalls on first-run gates (theme/onboarding picker,
+// "do you trust this folder?") and the agent never starts; the runner then sees
+// repeated ~2s exits and gives up. bootstrap<Provider>FirstRun makes a fresh
+// home launch-ready non-interactively, guaranteeing three things:
+//   1. host auth is linked in,
+//   2. first-run / onboarding flags are pre-accepted (where the provider has them),
+//   3. the cwd workspace is trusted.
+// Workspace trust is independent of repoInstructions: "ignore" means don't load
+// the repo's CLAUDE.md / AGENTS.md as behavioral instructions, NOT "don't
+// operate here" — an isolated agent must still read/edit/execute in its own cwd.
+// (claude-rig / host-base launches dodge all of this via onboarded host config +
+// --dangerously-skip-permissions; only isolated homes need the bootstrap.)
+
+// Provider-specific first-run bootstrap hooks, registered at module load.
+type BootstrapHook = (home: string, config: RunnerSpawnConfig) => void;
+const BOOTSTRAP_HOOKS = new Map<string, BootstrapHook>();
+
+// Shared skeleton: gate on isolated-profile, make the instance-keyed home,
+// link auth items from the manifest, and run any registered first-run hook.
+function prepareProviderHome(provider: SpawnProvider, config: RunnerSpawnConfig): ProviderHome | undefined {
+  if (!profileRequiresIsolatedHome(provider, config)) return undefined;
+  const target = providerHomePath(provider, config);
+  mkdirSync(target, { recursive: true });
+  const hook = BOOTSTRAP_HOOKS.get(provider);
+  if (hook) hook(target, config);
+  const manifest = getManifest(provider);
+  const authItems = manifest?.home?.authItems ?? [];
+  const sourceHome = providerSourceHome(provider);
+  const authLinked = linkExistingAuthItems(sourceHome, target, authItems);
+  linkHostGlobalInstructionFiles(sourceHome, target, config);
+  return { path: target, authLinked };
+}
+
+export const prepareCodexProfileHome = (config: RunnerSpawnConfig) => prepareProviderHome("codex", config);
+export const prepareClaudeProfileHome = (config: RunnerSpawnConfig) => prepareProviderHome("claude", config);
+
+function bootstrapCodexFirstRun(codexHome: string, config: RunnerSpawnConfig): void {
+  disableCodexAppsConnectors(codexHome);
+  trustWorkspaceForCodex(codexHome, config);
+}
+
+function bootstrapClaudeFirstRun(claudeHome: string, config: RunnerSpawnConfig): void {
+  if (profileAllowsRelayFeature(config, "context") && !profileAllowsHostGlobalInstructions(config)) {
+    writeClaudeRelayManual(claudeHome);
+  }
+  seedClaudeConfigIfMissing(claudeHome, config);
+}
+
+BOOTSTRAP_HOOKS.set("codex", bootstrapCodexFirstRun);
+BOOTSTRAP_HOOKS.set("claude", bootstrapClaudeFirstRun);
+
+export function providerSourceHome(provider: string): string {
+  const manifest = getManifest(provider);
+  const envVar = manifest?.home?.configDirEnvVar;
+  const configDir = manifest?.home?.configDir ?? `.${provider}`;
+  return (envVar && process.env[envVar]) || join(homedir(), configDir);
+}
+
+function seedClaudeConfigIfMissing(claudeHome: string, config: RunnerSpawnConfig): void {
+  const path = join(claudeHome, ".claude.json");
+  if (existsSync(path)) return;
+  const host = readHostClaudeConfig();
+  const seed = applyClaudeConfigPromptGatePreventions({}, host, config);
+  writeFileSync(path, JSON.stringify(seed, null, 2), { mode: 0o600 });
+}
+
+function readHostClaudeConfig(): Record<string, unknown> | undefined {
+  try {
+    const hostPath = join(homedir(), ".claude.json");
+    if (!existsSync(hostPath)) return undefined;
+    return JSON.parse(readFileSync(hostPath, "utf8")) as Record<string, unknown>;
+  } catch {
+    return undefined;
+  }
+}
+
+// #662 — the host USER-scope MCP servers: the top-level `mcpServers` of `~/.claude.json`.
+// These are the ambient host MCP a host-base Claude auto-loads on EVERY launch when NOT
+// strict (user scope is global across all projects — callmux/qmd/gh on this host). Since
+// the #662 wedge fix makes every managed launch `--strict-mcp-config` (so Claude ignores
+// all on-disk config and never renders the project-`.mcp.json` enable modal), an
+// `mcp.mode:"host"` profile must re-inject these explicitly into `--mcp-config` to keep
+// honoring host mode. Deliberately NOT the project-cwd `.mcp.json` (project scope — the
+// modal's source, which must stay excluded) nor `projects[cwd].mcpServers` (local scope).
+export function hostUserScopeMcpServers(): Record<string, ProvisioningMcpServer> {
+  const servers = readHostClaudeConfig()?.mcpServers;
+  if (!servers || typeof servers !== "object") return {};
+  return servers as Record<string, ProvisioningMcpServer>;
+}
+
+function providerHomePath(provider: SpawnProvider, config: RunnerSpawnConfig): string {
+  const root = providerHomeRootFromEnv();
+  const profileName = sanitizePathPart(config.agentProfile?.name || config.profile || "profile");
+  const instance = sanitizePathPart(config.instanceId || config.runnerId);
+  return join(root, provider, profileName, instance);
+}
+
+function sanitizePathPart(value: string): string {
+  return sanitizeFsName(value, { replacement: "-", collapse: false, maxLen: 120, fallback: "profile" });
+}
+
+function linkExistingAuthItems(sourceHome: string, targetHome: string, items: string[]): string[] {
+  const linked: string[] = [];
+  for (const item of items) {
+    if (linkExistingPath(join(sourceHome, item), join(targetHome, item))) linked.push(item);
+  }
+  return linked;
+}
+
+function linkExistingPath(source: string, target: string): boolean {
+  if (!existsSync(source) || existsSync(target)) return false;
+  symlinkSync(source, target);
+  return true;
+}
+
+function linkHostGlobalInstructionFiles(sourceHome: string, targetHome: string, config: RunnerSpawnConfig): void {
+  if (!profileAllowsHostGlobalInstructions(config)) return;
+  for (const file of config.providerConfig.globalInstructionFiles ?? []) {
+    linkExistingPath(join(sourceHome, file), join(targetHome, file));
+  }
+}
+
+function trustWorkspaceForCodex(codexHome: string, config: RunnerSpawnConfig): void {
+  if (!config.cwd) return;
+  const path = join(codexHome, "config.toml");
+  const project = tomlBasicString(resolve(config.cwd));
+  const section = `[projects.${project}]`;
+  const entry = `${section}\ntrust_level = "trusted"\n`;
+  const current = existsSync(path) ? readFileSync(path, "utf8") : "";
+  if (current.includes(section)) return;
+  const prefix = current.trimEnd();
+  writeFileSync(path, `${prefix ? `${prefix}\n\n` : ""}${entry}`, { mode: 0o600 });
+}
+
+function disableCodexAppsConnectors(codexHome: string): void {
+  const path = join(codexHome, "config.toml");
+  const current = existsSync(path) ? readFileSync(path, "utf8") : "";
+  const next = withTomlFeatureFlag(current, "apps", false);
+  if (next === current) return;
+  writeFileSync(path, next, { mode: 0o600 });
+}
+
+function withTomlFeatureFlag(input: string, key: string, value: boolean): string {
+  const lines = input.length ? input.split("\n") : [];
+  const headerIndex = lines.findIndex((line) => line.trim() === "[features]");
+  const entry = `${key} = ${value ? "true" : "false"}`;
+  if (headerIndex === -1) {
+    const prefix = input.trimEnd();
+    return `${prefix ? `${prefix}\n\n` : ""}[features]\n${entry}\n`;
+  }
+
+  let sectionEnd = lines.length;
+  for (let i = headerIndex + 1; i < lines.length; i += 1) {
+    const line = lines[i] ?? "";
+    if (/^\s*\[[^\]]+\]\s*(?:#.*)?$/.test(line)) {
+      sectionEnd = i;
+      break;
+    }
+  }
+
+  const flagPattern = new RegExp(`^\\s*${escapeRegExp(key)}\\s*=`);
+  for (let i = headerIndex + 1; i < sectionEnd; i += 1) {
+    const line = lines[i] ?? "";
+    if (flagPattern.test(line)) {
+      if (lines[i] === entry) return input;
+      lines[i] = entry;
+      return lines.join("\n");
+    }
+  }
+
+  lines.splice(headerIndex + 1, 0, entry);
+  return lines.join("\n");
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function writeClaudeRelayManual(claudeHome: string): void {
+  const path = join(claudeHome, "CLAUDE.md");
+  writeFileSync(path, claudeRelayManual(), { mode: 0o600 });
+}
+
+function tomlBasicString(value: string): string {
+  return JSON.stringify(value);
+}