@humwick/runner 0.0.0-stage → 0.130.0

package/src/profile-home.ts

@@ -0,0 +1,419 @@
+import { relayEnv } from "@humwick/sdk/env";
+import { existsSync, lstatSync, mkdirSync, readFileSync, renameSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { sanitizeFsName } from "@humwick/sdk/fs-name";
+import { isRecord, projectSettingSourcesOn as sdkProjectSettingSourcesOn, type ProvisioningMcpServer, type SpawnProvider } from "@humwick/sdk";
+import { getManifest } from "@humwick/providers";
+import { profileAllowsRelayFeature, type RunnerSpawnConfig } from "./adapter";
+import { claudeRelayManual } from "./relay-instructions";
+import { providerHomeRootFromEnv } from "./config";
+import { applyClaudeConfigPromptGatePreventions } from "./adapters/claude-prompt-gates";
+import { ensureClaudeWorkspaceTrust } from "./claude-workspace-trust";
+import { logger } from "./logger";
+import { writeProviderHomeMarker } from "./provider-home-marker";
+import { reclaimProviderHomeTombstone } from "./provider-home-tombstone";
+import { runnerHostConfigOffload } from "./fs-offload";
+import { hostSourcesFor, writeFileAtomic } from "./host-asset-plan";
+
+type ProviderHome = {
+  path: string;
+  authLinked: string[];
+};
+
+export function profileAllowsHostGlobalInstructions(config: { agentProfile?: RunnerSpawnConfig["agentProfile"] }): boolean {
+  return hostSourcesFor(config).instructions;
+}
+
+/**
+ * Whether a profile enables any Project setting-source cell. This is deliberately
+ * separate from the managed-home decision: the native Claude cascade is the
+ * Project re-injection mechanism.
+ *
+ * The predicate itself lives in the sdk ({@link sdkProjectSettingSourcesOn}) so the
+ * effective-profile survey and the v2 cell deriver stay in step with the runner's
+ * actual launch derivation — see #2084.
+ */
+export function projectSettingSourcesOn(config: { agentProfile?: RunnerSpawnConfig["agentProfile"] }): boolean {
+  const profile = config.agentProfile;
+  if (!profile) return false;
+  return sdkProjectSettingSourcesOn(profile);
+}
+
+/** The exact Claude setting-source list for a profiled launch. */
+export function projectSettingSources(config: { agentProfile?: RunnerSpawnConfig["agentProfile"] }): string[] | undefined {
+  if (!config.agentProfile) return undefined;
+  return projectSettingSourcesOn(config) ? ["user", "project"] : ["user"];
+}
+
+// #3387 — every runner-managed profiled launch runs in a Relay-owned home; `base:"host"` only
+// changes which host classes an omitted Host field inherits (see hostSourcesFor). A profile-less
+// launch is a user's own wrapped session and keeps the provider's native home.
+function profileRequiresIsolatedHome(config: RunnerSpawnConfig): boolean {
+  return Boolean(config.agentProfile);
+}
+
+// #557 — PURE: the Relay-owned provider config home path a launch WILL use, or undefined for a
+// profile-less launch (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(config)) return undefined;
+  return providerHomePath(provider, config);
+}
+
+// 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.
+//
+// #2254 — claude-rig / host-base launches skip the onboarding/theme bootstrap (an
+// onboarded host config already answers those), but they do NOT dodge folder trust:
+// --dangerously-skip-permissions does not bypass the trust gate, and a cwd the host
+// config has never seen still renders the dialog and wedges the spawn. Trust is
+// therefore seeded for EVERY Claude launch — see prepareClaudeProfileHome.
+
+// Provider-specific first-run bootstrap hooks, registered at module load.
+type BootstrapHook = (home: string, config: RunnerSpawnConfig) => void;
+const BOOTSTRAP_HOOKS = new Map<string, BootstrapHook>();
+
+/**
+ * The ONE materialization seam for an instance-keyed provider home
+ * (`<root>/<provider>/<profile>/<instanceId>`) — every adapter that creates one MUST route
+ * through it (#2624: the OpenCode family built its home by hand, so its homes carried no
+ * owner-marker and no tombstone reclaim, and the reaper skipped every one of them as
+ * "unmarked" forever). `identity` must be exactly the path segments of `target`: the reaper
+ * refuses a marker that does not describe its own directory.
+ */
+export function materializeProviderHome(target: string, identity: { provider: string; profile: string; instanceId: string; agentId?: string }, mode?: number): void {
+  // #1256 spawn-side reclaim — FIRST recover any quarantine tombstone the reaper left for
+  // this exact instanceId (atomic rename back to `target`), BEFORE creating a fresh home.
+  // This makes reconnection always safe (a reconnecting/resuming agent recovers its home)
+  // and lets a crash-stranded tombstone self-heal. A lost reclaim race just falls through
+  // to a fresh mkdir below — never a corrupt home.
+  reclaimProviderHomeTombstone(target);
+  mkdirSync(target, { recursive: true, ...(mode === undefined ? {} : { mode }) });
+  // #1256 — stamp the owner-marker so the reaper can later reclaim this home if it becomes
+  // orphaned, but only ever on THIS host (cross-host safety).
+  writeProviderHomeMarker(target, identity);
+}
+
+// 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(config)) return undefined;
+  const target = providerHomePath(provider, config);
+  materializeProviderHome(target, {
+    provider,
+    profile: sanitizePathPart(config.agentProfile?.name || config.profile || "profile"),
+    instanceId: sanitizePathPart(config.instanceId || config.runnerId),
+    agentId: config.agentId,
+  });
+  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);
+  return { path: target, authLinked };
+}
+
+export const prepareCodexProfileHome = (config: RunnerSpawnConfig) => prepareProviderHome("codex", config);
+
+/**
+ * #2254 — every Claude launch, isolated or host-base, leaves this function with folder trust
+ * already granted in the config file it will read. `prepareProviderHome` returns undefined for
+ * a host-base profile (and for a profile-less spawn), which is exactly the class that used to
+ * be seeded nowhere and wedged on the trust dialog; `ensureClaudeWorkspaceTrust` therefore runs
+ * unconditionally, targeting the shared host config when there is no isolated home.
+ *
+ * #2513 — provider-id-dynamic for the claude family: claude-b passes its own id so the
+ * isolated home, bootstrap hook, and auth links resolve against `~/.claude-b` (its manifest
+ * configDir), never `~/.claude`.
+ */
+export const prepareClaudeProfileHome = (config: RunnerSpawnConfig, provider: SpawnProvider = "claude"): ProviderHome | undefined => {
+  const home = prepareProviderHome(provider, config);
+  // #2513 review HIGH-1 — a dedicatedHome provider's host-base launch still reads the
+  // provider's OWN effective home (launch assembly exports CLAUDE_CONFIG_DIR at it), so
+  // folder trust must be seeded in THAT home's .claude.json, not the shared ~/.claude.json.
+  const trust = ensureClaudeWorkspaceTrust(config.cwd, home?.path ?? providerHostConfigHome(provider));
+  // A seed that did not land puts this launch straight back into the #2254 wedge — CC opens
+  // its trust dialog and the spawn hangs until a human answers. The failure modes are all
+  // environmental (an unparseable or unwritable host config, an operator opt-out), so the fix
+  // cannot self-heal; it must at least say so instead of failing silently the way the missing
+  // seed did for months. "no-cwd" is the one benign case: no cwd, nothing to trust.
+  if (!trust.verified && trust.skipped !== "no-cwd") {
+    logger.warn("profile-home", `claude workspace trust NOT seeded (${trust.skipped ?? "unverified"}) in ${trust.path} for keys [${trust.keys.join(", ")}] — this launch may wedge on the folder-trust dialog`);
+  }
+  return home;
+};
+
+function bootstrapCodexFirstRun(codexHome: string, config: RunnerSpawnConfig): void {
+  // Keep bootstrap to one config read/write while repairing auth links (#2670).
+  const path = join(codexHome, "config.toml");
+  const current = existsSync(path) ? readFileSync(path, "utf8") : "";
+  const next = withCodexWorkspaceTrust(withTomlFeatureFlag(current, "apps", false), config);
+  if (next !== current) writeFileSync(path, next, { mode: 0o600 });
+}
+
+function bootstrapClaudeFirstRun(claudeHome: string, config: RunnerSpawnConfig): void {
+  if (profileAllowsRelayFeature(config, "context") && !profileAllowsHostGlobalInstructions(config)) {
+    writeClaudeRelayManual(claudeHome);
+  }
+  ensureClaudeConfigSeed(claudeHome, config);
+}
+
+BOOTSTRAP_HOOKS.set("codex", bootstrapCodexFirstRun);
+BOOTSTRAP_HOOKS.set("claude", bootstrapClaudeFirstRun);
+// #2513 — the claude-b provider runs the identical claude first-run bootstrap (relay
+// manual + config seed) inside its own claude-b-keyed home.
+BOOTSTRAP_HOOKS.set("claude-b", bootstrapClaudeFirstRun);
+BOOTSTRAP_HOOKS.set("claude-api", bootstrapClaudeFirstRun);
+
+export function providerSourceHome(provider: string): string {
+  const manifest = getManifest(provider);
+  const envVar = manifest?.home?.configDirEnvVar;
+  const configDir = manifest?.home?.configDir ?? `.${provider}`;
+  const sourceEnvVar = manifest?.home?.sourceEnvVar ?? envVar;
+  return (sourceEnvVar && relayEnv(process.env, sourceEnvVar)) || join(homedir(), configDir);
+}
+
+/**
+ * #2513 — the effective HOST config home a `dedicatedHome` provider (claude-b) launches
+ * from when it has no isolated managed home, or undefined for the primary provider
+ * (claude), whose host-base launches keep their historical behavior of falling back to
+ * the binary's own resolution ($CLAUDE_CONFIG_DIR ?? ~/.claude). Callers that need one
+ * config dir for EVERY launch of a dedicated-home provider use
+ * `isolatedHome ?? providerHostConfigHome(provider)`.
+ */
+export function providerHostConfigHome(provider: SpawnProvider): string | undefined {
+  return getManifest(provider)?.home?.dedicatedHome ? providerSourceHome(provider) : undefined;
+}
+
+function ensureClaudeConfigSeed(claudeHome: string, config: RunnerSpawnConfig): void {
+  const path = join(claudeHome, ".claude.json");
+  const host = config.hostClaudeConfig;
+  const seed = applyClaudeConfigPromptGatePreventions({}, host, config);
+  if (!existsSync(path)) {
+    writeJsonAtomic(path, seed);
+    return;
+  }
+  // #1368/#harden — the isolated home is instance-keyed and PERSISTS across resumes/reconnects, so a
+  // relaunch (e.g. auto-resume after a tmux/provider exit) reuses the existing `.claude.json` and
+  // never re-runs the absent-file seed above. Re-heal every prompt-gate key the seed would have
+  // applied on a fresh home (onboarding, theme, bypass-permissions, workspace-trust): a resumed
+  // config stale/missing on ANY of them boots straight into that gate's interactive prompt, can't
+  // answer headlessly, and crash-loops the agent offline. A corrupt/unparseable/non-object existing
+  // file can't be surgically merged — its prior contents are unrecoverable anyway — so it gets a
+  // full reseed instead of bailing and leaving every gate unguarded; a well-formed file gets a
+  // sibling-preserving merge.
+  const existing = readExistingClaudeConfig(path);
+  if (!existing) {
+    writeJsonAtomic(path, seed);
+    return;
+  }
+  if (mergeClaudeConfigGates(existing, seed)) writeJsonAtomic(path, existing);
+}
+
+// Parses an existing `.claude.json`. Returns undefined when the file is unparseable JSON or not a
+// plain object, signaling the caller to reseed fully rather than merge into it.
+function readExistingClaudeConfig(path: string): Record<string, unknown> | undefined {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as unknown;
+    return isRecord(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+// Idempotently re-applies every key the seed computed onto an already-existing, well-formed config,
+// without touching any sibling key the provider has written since first spawn (session history,
+// other project entries, etc.). Boolean gate keys (hasCompletedOnboarding, bypassPermissionsModeAccepted,
+// and the two workspace-trust flags) are forced to `true` whenever they aren't already `true`, so a
+// stale `false` is promoted the same as a missing key. Non-boolean keys (theme, lastOnboardingVersion)
+// are only filled in when entirely absent, so a value the provider or user has since set is never
+// clobbered. `seed` already reflects each prevention's own gating (e.g. bypassPermissionsModeAccepted
+// is simply absent unless approvalMode is "open"), so a guarded profile is never forced into it here.
+// Returns whether anything changed.
+function mergeClaudeConfigGates(existing: Record<string, unknown>, seed: Record<string, unknown>): boolean {
+  let dirty = false;
+  for (const [key, value] of Object.entries(seed)) {
+    if (key === "projects") continue;
+    if (typeof value === "boolean") {
+      if (existing[key] !== true) {
+        existing[key] = true;
+        dirty = true;
+      }
+    } else if (existing[key] === undefined) {
+      existing[key] = value;
+      dirty = true;
+    }
+  }
+  if (isRecord(seed.projects)) {
+    const existingProjects = isRecord(existing.projects) ? existing.projects : {};
+    for (const [projectPath, seedEntry] of Object.entries(seed.projects)) {
+      if (!isRecord(seedEntry)) continue;
+      const existingEntry = isRecord(existingProjects[projectPath]) ? existingProjects[projectPath] : {};
+      for (const [entryKey, entryValue] of Object.entries(seedEntry)) {
+        if (typeof entryValue !== "boolean") continue;
+        if (existingEntry[entryKey] !== true) {
+          existingEntry[entryKey] = true;
+          dirty = true;
+        }
+      }
+      existingProjects[projectPath] = existingEntry;
+    }
+    existing.projects = existingProjects;
+  }
+  return dirty;
+}
+
+// Atomic write: temp file in the SAME directory, then rename(2). A crash or kill mid-write leaves
+// only an orphaned temp file — never a truncated/corrupt `.claude.json` — because rename only ever
+// swaps in a complete file.
+function writeJsonAtomic(path: string, value: unknown): void {
+  const tmpPath = `${path}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
+  writeFileSync(tmpPath, JSON.stringify(value, null, 2), { mode: 0o600 });
+  renameSync(tmpPath, path);
+}
+
+/**
+ * Reads and parses the potentially multi-megabyte host config before launch assembly. The whole
+ * operation runs in the bounded worker pool: async file I/O alone would still leave JSON.parse
+ * pinning the runner event loop for large host history files.
+ */
+export async function hydrateClaudeHostConfig(config: RunnerSpawnConfig, provider: SpawnProvider = "claude"): Promise<RunnerSpawnConfig> {
+  const [hostClaudeConfig, hostClaudeSettings] = await Promise.all([
+    config.hostClaudeConfig === undefined ? readClaudeHostConfig(provider) : Promise.resolve(config.hostClaudeConfig),
+    config.hostClaudeSettings === undefined ? readClaudeHostSettings(provider) : Promise.resolve(config.hostClaudeSettings),
+  ]);
+  return {
+    ...config,
+    ...(hostClaudeConfig ? { hostClaudeConfig } : {}),
+    ...(hostClaudeSettings ? { hostClaudeSettings } : {}),
+  };
+}
+
+/**
+ * Loads only the seed values and host-scope MCP declaration required by a Claude launch. This
+ * shared worker-pool seam gives registration projection and synchronous launch assembly the same
+ * snapshot without ever parsing the host's potentially huge config on the runner event loop.
+ * #2513 — keyed by provider id so a claude-family provider (claude-b) reads ITS source home.
+ */
+export async function readClaudeHostConfig(provider: SpawnProvider = "claude"): Promise<Record<string, unknown> | undefined> {
+  const hostPath = join(providerSourceHome(provider), ".claude.json");
+  return runnerHostConfigOffload().run<{ path: string }, Record<string, unknown> | undefined>("runner-claude-host-config-read", { path: hostPath });
+}
+
+/** Load only the executable hooks portion of host settings.json off-thread. */
+export async function readClaudeHostSettings(provider: SpawnProvider = "claude"): Promise<Record<string, unknown> | undefined> {
+  const settingsPath = join(providerSourceHome(provider), "settings.json");
+  return runnerHostConfigOffload().run<{ path: string; kind: "settings" }, Record<string, unknown> | undefined>("runner-claude-host-config-read", { path: settingsPath, kind: "settings" });
+}
+
+// #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(config: Pick<RunnerSpawnConfig, "hostClaudeConfig">): Record<string, ProvisioningMcpServer> {
+  const servers = config.hostClaudeConfig?.mcpServers;
+  return isRecord(servers) ? 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;
+  // #2670 — existsSync follows links; a reaped auth source leaves a dangling entry behind.
+  if (lstatSync(target, { throwIfNoEntry: false })?.isSymbolicLink()) unlinkSync(target);
+  symlinkSync(source, target);
+  return true;
+}
+
+function withCodexWorkspaceTrust(current: string, config: RunnerSpawnConfig): string {
+  if (!config.cwd) return current;
+  const project = tomlBasicString(resolve(config.cwd));
+  const section = `[projects.${project}]`;
+  const entry = `${section}\ntrust_level = "trusted"\n`;
+  if (current.includes(section)) return current;
+  const prefix = current.trimEnd();
+  return `${prefix ? `${prefix}\n\n` : ""}${entry}`;
+}
+
+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, "\\$&");
+}
+
+// A reused home may still hold the host CLAUDE.md link from an Instructions-on launch: never write
+// through it into the host file.
+function writeClaudeRelayManual(claudeHome: string): void {
+  writeFileAtomic(join(claudeHome, "CLAUDE.md"), claudeRelayManual());
+}
+
+function tomlBasicString(value: string): string {
+  return JSON.stringify(value);
+}