phoebe-agent 0.0.0 → 0.1.1

package/src/execution-gate.ts

@@ -0,0 +1,27 @@
+// Work-unit execution is gated to the Phoebe container. Selection logic and
+// --dry-run stay host-runnable for fast iteration; anything that mutates a
+// clone, launches an agent CLI, or pushes runs only where the container
+// marker exists (created by the Dockerfile).
+
+import { existsSync } from "node:fs";
+
+export const CONTAINER_MARKER_PATH = "/.phoebe-container";
+
+export function isInsideContainer(exists: (path: string) => boolean = existsSync): boolean {
+  return exists(CONTAINER_MARKER_PATH);
+}
+
+export type ExecutionDecision = "execute" | "dry-run" | "refuse";
+
+/** Pure decision: may this process execute the selected work unit? */
+export function executionDecision(opts: {
+  dryRun: boolean;
+  inContainer: boolean;
+}): ExecutionDecision {
+  if (opts.dryRun) return "dry-run";
+  return opts.inContainer ? "execute" : "refuse";
+}
+
+export const EXECUTION_REFUSED_MESSAGE =
+  "[phoebe] Refusing to execute a work unit outside the Phoebe container. " +
+  "Use --dry-run to preview selection on the host, or start the container loop.";

package/src/git-model.ts

@@ -0,0 +1,145 @@
+// Origin-hub git model: a private clone owns all local git state, work units
+// run in worktrees off it, finished branches push straight to origin. Every
+// function takes the clone directory explicitly so tests can run against a
+// temp clone.
+
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { asSha, type BranchRef, type Sha } from "./branded.ts";
+
+export type GitRunner = (
+  args: string[],
+  opts?: { cwd?: string; stdio?: "inherit" | "ignore" | "pipe"; timeout?: number },
+) => string;
+
+export const defaultGit: GitRunner = (args, opts) =>
+  execFileSync("git", args, {
+    encoding: "utf8",
+    ...(opts?.cwd ? { cwd: opts.cwd } : {}),
+    ...(opts?.stdio ? { stdio: opts.stdio } : {}),
+    // A network git call on the supervisor's event loop (reconcile's `ls-remote`)
+    // must not block it forever on a hung remote — the caller bounds it.
+    ...(opts?.timeout ? { timeout: opts.timeout } : {}),
+  }) as unknown as string;
+
+/**
+ * Clone the repo into `repoDir` unless a clone already exists there.
+ *
+ * An existing clone is only adopted if its `origin` actually points at
+ * `repoUrl`. A `/data/repo` volume is supposed to be this instance's private
+ * clone, but two Phoebe instances on one host can end up sharing it (a compose
+ * project-name collision namespaces the "private" volumes identically). Adopting
+ * a foreign clone by mere presence of `.git` would silently run every worktree,
+ * branch, and push against the wrong repo while `gh` calls still used this
+ * instance's `repoSlug` — reading one repo's issues and doing the work on
+ * another's tree. So a mismatch fails loudly instead: isolate the instances (see
+ * `COMPOSE_PROJECT_NAME`) or wipe the shared volume.
+ */
+export function ensureClone(
+  opts: { repoUrl: string; repoDir: string },
+  git: GitRunner = defaultGit,
+): void {
+  if (existsSync(join(opts.repoDir, ".git"))) {
+    // `git config --get` exits non-zero when the key is unset, which `defaultGit`
+    // surfaces as a throw. An unreadable origin is not the configured `repoUrl`,
+    // so treat it as an absent origin and fall through to the refusal below —
+    // reaching the explicit `<none>` message rather than a raw `Command failed`.
+    let origin = "";
+    try {
+      origin = git(["config", "--get", "remote.origin.url"], { cwd: opts.repoDir }).trim();
+    } catch {
+      origin = "";
+    }
+    if (origin !== opts.repoUrl) {
+      throw new Error(
+        `Existing clone at ${opts.repoDir} has origin \`${origin || "<none>"}\`, but this ` +
+          `Phoebe is configured for \`${opts.repoUrl}\`. Refusing to work a foreign clone — the ` +
+          `state volume is shared with another instance. Give each instance a distinct compose ` +
+          `project (COMPOSE_PROJECT_NAME), or wipe this volume, then retry.`,
+      );
+    }
+    return;
+  }
+  mkdirSync(opts.repoDir, { recursive: true });
+  git(["clone", opts.repoUrl, opts.repoDir], { stdio: "inherit" });
+}
+
+export function fetchOrigin(repoDir: string, git: GitRunner = defaultGit): void {
+  git(["fetch", "origin"], { cwd: repoDir, stdio: "inherit" });
+}
+
+export function originBranchSha(
+  repoDir: string,
+  branch: BranchRef,
+  git: GitRunner = defaultGit,
+): Sha {
+  return asSha(git(["rev-parse", `origin/${branch}`], { cwd: repoDir }).trim());
+}
+
+/** Filesystem-safe worktree directory name for a branch. */
+export function worktreeDirForBranch(worktreesDir: string, branch: BranchRef): string {
+  return join(worktreesDir, branch.toLowerCase().replace(/[^a-z0-9]/g, "-"));
+}
+
+/** Create a worktree on a (possibly new) branch reset to `baseRef`. */
+export function addWorktreeForNewBranch(
+  opts: { repoDir: string; worktreeDir: string; branch: BranchRef; baseRef: string },
+  git: GitRunner = defaultGit,
+): void {
+  git(["worktree", "add", "-B", opts.branch, opts.worktreeDir, opts.baseRef], {
+    cwd: opts.repoDir,
+    stdio: "inherit",
+  });
+}
+
+/** Create a worktree on an existing branch (local first, then origin/<branch>). */
+export function addWorktreeForExistingBranch(
+  opts: { repoDir: string; worktreeDir: string; branch: BranchRef },
+  git: GitRunner = defaultGit,
+): void {
+  try {
+    git(["worktree", "add", opts.worktreeDir, opts.branch], {
+      cwd: opts.repoDir,
+      stdio: "inherit",
+    });
+  } catch {
+    git(["worktree", "add", "-B", opts.branch, opts.worktreeDir, `origin/${opts.branch}`], {
+      cwd: opts.repoDir,
+      stdio: "inherit",
+    });
+  }
+}
+
+export function removeWorktree(
+  repoDir: string,
+  worktreeDir: string,
+  git: GitRunner = defaultGit,
+): void {
+  try {
+    git(["worktree", "remove", "--force", worktreeDir], { cwd: repoDir, stdio: "ignore" });
+  } catch {
+    rmSync(worktreeDir, { recursive: true, force: true });
+  }
+  try {
+    git(["worktree", "prune"], { cwd: repoDir, stdio: "ignore" });
+  } catch {
+    // Best-effort.
+  }
+}
+
+export function commitCount(
+  worktreeDir: string,
+  range: string,
+  git: GitRunner = defaultGit,
+): number {
+  return Number(git(["rev-list", "--count", range], { cwd: worktreeDir }).trim());
+}
+
+export function pushBranch(
+  worktreeDir: string,
+  branch: BranchRef,
+  git: GitRunner = defaultGit,
+): void {
+  git(["push", "origin", branch], { cwd: worktreeDir, stdio: "inherit" });
+}

package/src/init.ts

@@ -0,0 +1,277 @@
+// `phoebe init` scaffolder. Given a target directory, drops the consumer-owned
+// runtime into place: `phoebe.config.ts`, a `prompts/` dir with copies of the
+// shipped defaults (edit-and-commit), `.env.example`, `.gitignore` entries,
+// and the `container/` templates (Dockerfile, compose, and a dev-only overlay
+// for running a local engine checkout). Re-runs are guarded — an existing file
+// is skipped, not silently overwritten, so consumer edits are safe.
+//
+// The plan/render split keeps the pure logic (what files, what placeholders)
+// separately testable from the fs I/O in `runInit`.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CONFIG_DEFAULTS } from "./config-schema.ts";
+
+/** Placeholder tokens rendered into every scaffolded file. */
+export type TemplateParams = {
+  /** The consumer's install command (also written into the config). */
+  installCommand: string;
+  /** The npm package name of the CLI — normally `phoebe-agent`. */
+  cliBin: string;
+};
+
+export const DEFAULT_TEMPLATE_PARAMS: TemplateParams = {
+  installCommand: "npm ci",
+  cliBin: "phoebe-agent",
+};
+
+/**
+ * One consumer-owned output produced by init. Sources are one of:
+ *  - `template`: a file under the shipped `templates/` tree, rendered with
+ *    placeholder substitution.
+ *  - `shipped-prompt`: a file under the shipped `prompts/` tree, copied
+ *    verbatim (prompts already carry their own `{{…}}` markers that the
+ *    engine expands at run time — do NOT substitute those here).
+ *  - `gitignore`: an additive-merge marker; `entries` are appended to any
+ *    existing `.gitignore`, deduped line-wise.
+ */
+export type PlannedOutput = {
+  destRelPath: string;
+  source:
+    | { kind: "template"; templateRelPath: string }
+    | { kind: "shipped-prompt"; promptRelPath: string }
+    | { kind: "gitignore"; entries: readonly string[] };
+};
+
+const GITIGNORE_ENTRIES = [".env", "node_modules/"] as const;
+
+/**
+ * Enumerate every file init will produce. The prompt list is derived from
+ * `CONFIG_DEFAULTS.promptFiles` so adding a new prompt kind to the engine
+ * automatically gets scaffolded — no drift between the two lists.
+ */
+export function planInitOutputs(): PlannedOutput[] {
+  const promptOutputs: PlannedOutput[] = Object.values(CONFIG_DEFAULTS.promptFiles).map(
+    (relPath) => ({
+      destRelPath: relPath,
+      source: { kind: "shipped-prompt", promptRelPath: relPath },
+    }),
+  );
+  return [
+    {
+      destRelPath: "phoebe.config.ts",
+      source: { kind: "template", templateRelPath: "phoebe.config.ts" },
+    },
+    {
+      destRelPath: ".env.example",
+      source: { kind: "template", templateRelPath: ".env.example" },
+    },
+    {
+      destRelPath: "container/Dockerfile",
+      source: { kind: "template", templateRelPath: "container/Dockerfile" },
+    },
+    {
+      destRelPath: "container/compose.yml",
+      source: { kind: "template", templateRelPath: "container/compose.yml" },
+    },
+    {
+      destRelPath: "container/compose.local.yml",
+      source: { kind: "template", templateRelPath: "container/compose.local.yml" },
+    },
+    ...promptOutputs,
+    {
+      destRelPath: ".gitignore",
+      source: { kind: "gitignore", entries: GITIGNORE_ENTRIES },
+    },
+  ];
+}
+
+/**
+ * Substitute `{{KEY}}` tokens with the matching value. Unknown tokens throw
+ * so a typo in a template surfaces during tests rather than silently landing
+ * in a consumer's repo. Iteration is over the params (not a regex over the
+ * source) so a value that happens to contain a `{{…}}`-shaped substring is
+ * never re-scanned.
+ */
+export function renderTemplate(source: string, params: TemplateParams): string {
+  let rendered = source;
+  for (const [key, value] of Object.entries(params) as Array<[keyof TemplateParams, string]>) {
+    const token = `{{${keyToToken(key)}}}`;
+    rendered = rendered.split(token).join(value);
+  }
+  const leftover = /\{\{([A-Z_]+)\}\}/.exec(rendered);
+  if (leftover) {
+    throw new Error(
+      `Template contained an unrenderable placeholder \`{{${leftover[1]}}}\` — ` +
+        `every {{TOKEN}} in a scaffolded file must map to a TemplateParams field.`,
+    );
+  }
+  return rendered;
+}
+
+function keyToToken(key: keyof TemplateParams): string {
+  // installCommand -> INSTALL_COMMAND, cliBin -> CLI_BIN
+  return key.replace(/([A-Z])/g, "_$1").toUpperCase();
+}
+
+/**
+ * Additive `.gitignore` merge — append any missing entries under a `# Phoebe`
+ * header, leaving existing lines untouched. An empty file becomes a bare list
+ * (no header) because there's nothing else to distinguish it from.
+ */
+export function mergeGitignore(existing: string, entries: readonly string[]): string {
+  const existingLines = new Set(
+    existing
+      .split("\n")
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0 && !line.startsWith("#")),
+  );
+  const missing = entries.filter((entry) => !existingLines.has(entry));
+  if (missing.length === 0) {
+    return existing;
+  }
+  if (existing.trim().length === 0) {
+    return `${missing.join("\n")}\n`;
+  }
+  const separator = existing.endsWith("\n") ? "" : "\n";
+  return `${existing}${separator}\n# Phoebe\n${missing.join("\n")}\n`;
+}
+
+export type InitReport = {
+  /** New files written (destination paths, relative to the target dir). */
+  created: string[];
+  /** `.gitignore` entries appended in-place (destination paths). */
+  updated: string[];
+  /** Existing files left alone (destination paths). */
+  skipped: string[];
+};
+
+/**
+ * Walk up from this module's directory to find the shipped resource root. This
+ * runs from `src/init.ts` (no build step) and reads `templates/…` + `prompts/…`
+ * from the package root. Stops at a `node_modules` boundary so an installed dep
+ * never resolves scaffold sources from the consuming repo. (Runtime `promptFiles`
+ * loading is separate — see `resolvePromptFile` in `prompt.ts`, which reads
+ * from the consumer runtime root.)
+ */
+function resolvePackageResource(relativePath: string, moduleDir: string): string {
+  let dir = moduleDir;
+  while (true) {
+    const candidate = join(dir, relativePath);
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+    const parent = dirname(dir);
+    if (parent === dir || basename(parent) === "node_modules") {
+      throw new Error(
+        `Could not find ${relativePath} within the Phoebe package (searched from ${moduleDir})`,
+      );
+    }
+    dir = parent;
+  }
+}
+
+export type RunInitOptions = {
+  /** Directory the scaffolded files land under. Created if missing. */
+  targetDir: string;
+  /** Override template params (`installCommand`, `cliBin`). */
+  params?: Partial<TemplateParams>;
+  /** Root for shipped `templates/` and `prompts/` (test seam). Defaults to
+   *  the walk-up from this module. */
+  packageRoot?: string;
+};
+
+function readShippedFile(
+  relPath: string,
+  packageRoot: string | undefined,
+  moduleDir: string,
+): string {
+  const absolute = packageRoot
+    ? resolvePath(packageRoot, relPath)
+    : resolvePackageResource(relPath, moduleDir);
+  return readFileSync(absolute, "utf8");
+}
+
+/**
+ * Execute the plan: create missing files, additively update `.gitignore`, and
+ * leave every existing file alone. Returns a report so the CLI (and tests)
+ * can render a summary without re-walking the filesystem.
+ *
+ * Not idempotent in the "produces the same output twice" sense — running init
+ * twice on a directory the consumer has edited must not change their files.
+ * That's the entire guarded-re-run contract. A second run into an empty
+ * directory *does* reproduce the first-run output.
+ */
+export function runInit(opts: RunInitOptions): InitReport {
+  const targetDir = resolvePath(opts.targetDir);
+  const params: TemplateParams = { ...DEFAULT_TEMPLATE_PARAMS, ...opts.params };
+  const moduleDir = dirname(fileURLToPath(import.meta.url));
+
+  mkdirSync(targetDir, { recursive: true });
+
+  const report: InitReport = { created: [], updated: [], skipped: [] };
+
+  for (const output of planInitOutputs()) {
+    const destAbs = join(targetDir, output.destRelPath);
+    mkdirSync(dirname(destAbs), { recursive: true });
+
+    if (output.source.kind === "gitignore") {
+      const existing = existsSync(destAbs) ? readFileSync(destAbs, "utf8") : "";
+      const merged = mergeGitignore(existing, output.source.entries);
+      if (merged === existing) {
+        report.skipped.push(output.destRelPath);
+      } else if (existing.length === 0) {
+        writeFileSync(destAbs, merged);
+        report.created.push(output.destRelPath);
+      } else {
+        writeFileSync(destAbs, merged);
+        report.updated.push(output.destRelPath);
+      }
+      continue;
+    }
+
+    if (existsSync(destAbs)) {
+      report.skipped.push(output.destRelPath);
+      continue;
+    }
+
+    if (output.source.kind === "template") {
+      const rawTemplate = readShippedFile(
+        join("templates", output.source.templateRelPath),
+        opts.packageRoot,
+        moduleDir,
+      );
+      const rendered = renderTemplate(rawTemplate, params);
+      writeFileSync(destAbs, rendered);
+    } else {
+      // Shipped prompts ship verbatim — the engine's own render step handles
+      // their `{{PLACEHOLDER}}` tokens at run time.
+      const prompt = readShippedFile(output.source.promptRelPath, opts.packageRoot, moduleDir);
+      writeFileSync(destAbs, prompt);
+    }
+    report.created.push(output.destRelPath);
+  }
+
+  return report;
+}
+
+/** Human-readable summary suitable for the CLI to stdout after init runs. */
+export function formatInitReport(report: InitReport, targetDir: string): string {
+  const lines = [`[phoebe] init → ${targetDir}`];
+  const emit = (label: string, paths: readonly string[]): void => {
+    if (paths.length === 0) return;
+    lines.push(`  ${label}:`);
+    for (const path of paths) {
+      lines.push(`    ${path}`);
+    }
+  };
+  emit("created", report.created);
+  emit("updated", report.updated);
+  emit("skipped (already present)", report.skipped);
+  if (report.skipped.length > 0) {
+    lines.push("");
+    lines.push("Existing files were left untouched. Delete them and re-run init to regenerate.");
+  }
+  return `${lines.join("\n")}\n`;
+}

package/src/load-config.ts

@@ -0,0 +1,168 @@
+// Consumer-facing config plumbing: `loadUserConfig` (dynamic TS import via
+// native Node type-stripping) and `applyEnvOverlay` (`PHOEBE_*` overrides for
+// scalar fields). The `defineConfig` typing helper lives in the bootstrapper
+// (bootstrap/define-config.ts), the published package surface.
+//
+// The Phoebe CLI (src/cli.ts) chains these: load the user's config, overlay
+// env vars, then `resolveConfig` fills the shipped defaults. Kept separate from
+// `config-schema.ts` so the schema stays a pure data contract and only the CLI
+// path pulls in Node's fs/url runtime.
+
+import { pathToFileURL } from "node:url";
+import { existsSync } from "node:fs";
+import { isAbsolute, resolve as resolvePath } from "node:path";
+import type { PhoebeUserConfig, ProviderName } from "./config-schema.ts";
+import { PROVIDER_NAMES } from "./config-schema.ts";
+
+/**
+ * Scalar-only overlay: each `PHOEBE_*` env var, when set to a non-empty
+ * string, replaces the corresponding user-config field. Nested records
+ * (`promptFiles`, `paths`, `defaultModels`, `providerEnv`, `workOrder`) stay
+ * config-file territory — env vars are for one-off run overrides where the
+ * consumer doesn't want to edit `phoebe.config.ts`, and expanding structured
+ * shapes into env keys defeats the point.
+ *
+ * A field-scoped list (rather than magic name-mangling) keeps the surface
+ * documented and predictable: users can grep for `PHOEBE_` here and see the
+ * complete overlay contract.
+ */
+export const ENV_OVERLAY_KEYS = [
+  { env: "PHOEBE_REPO_SLUG", key: "repoSlug" },
+  { env: "PHOEBE_REPO_URL", key: "repoUrl" },
+  { env: "PHOEBE_DEFAULT_BRANCH", key: "defaultBranch" },
+  { env: "PHOEBE_BRANCH_PREFIX", key: "branchPrefix" },
+  { env: "PHOEBE_READY_LABEL", key: "readyLabel" },
+  { env: "PHOEBE_RESEARCH_LABEL", key: "researchLabel" },
+  { env: "PHOEBE_PROCESSING_LABEL", key: "processingLabel" },
+  { env: "PHOEBE_PR_OPT_OUT_LABEL", key: "prOptOutLabel" },
+  { env: "PHOEBE_INSTALL_COMMAND", key: "installCommand" },
+  { env: "PHOEBE_CHECK_COMMAND", key: "checkCommand" },
+  { env: "PHOEBE_TEST_COMMAND", key: "testCommand" },
+  { env: "PHOEBE_READY_COMMAND", key: "readyCommand" },
+  { env: "PHOEBE_BLOCKED_BY_PATTERN", key: "blockedByPattern" },
+  { env: "PHOEBE_REVIEWS_SUCCESS_HEADING", key: "reviewsSuccessHeading" },
+] as const satisfies ReadonlyArray<{ env: string; key: keyof PhoebeUserConfig }>;
+
+const PR_SCOPE_VALUES = ["phoebe", "all"] as const;
+const DRAFT_PRS_VALUES = ["skip-non-phoebe", "skip-all", "include"] as const;
+
+function readNonEmpty(env: NodeJS.ProcessEnv, key: string): string | undefined {
+  const raw = env[key];
+  if (typeof raw !== "string" || raw.length === 0) return undefined;
+  return raw;
+}
+
+/**
+ * Apply the `PHOEBE_*` overlay onto a user config and return a new object.
+ * The overlay is additive over what the config file declared — an unset env
+ * var leaves the field untouched (so `resolveConfig` can still fall back to
+ * `CONFIG_DEFAULTS` if the field was also absent from the config file).
+ */
+export function applyEnvOverlay(user: PhoebeUserConfig, env: NodeJS.ProcessEnv): PhoebeUserConfig {
+  const overlaid: PhoebeUserConfig = { ...user };
+  for (const { env: envKey, key } of ENV_OVERLAY_KEYS) {
+    const value = readNonEmpty(env, envKey);
+    if (value !== undefined) {
+      (overlaid as Record<string, unknown>)[key] = value;
+    }
+  }
+
+  const prScope = readNonEmpty(env, "PHOEBE_PR_SCOPE");
+  if (prScope !== undefined) {
+    if (!(PR_SCOPE_VALUES as readonly string[]).includes(prScope)) {
+      throw new Error(
+        `PHOEBE_PR_SCOPE must be one of ${PR_SCOPE_VALUES.join(", ")} (got "${prScope}").`,
+      );
+    }
+    overlaid.prScope = prScope as PhoebeUserConfig["prScope"];
+  }
+
+  const draftPrs = readNonEmpty(env, "PHOEBE_DRAFT_PRS");
+  if (draftPrs !== undefined) {
+    if (!(DRAFT_PRS_VALUES as readonly string[]).includes(draftPrs)) {
+      throw new Error(
+        `PHOEBE_DRAFT_PRS must be one of ${DRAFT_PRS_VALUES.join(", ")} (got "${draftPrs}").`,
+      );
+    }
+    overlaid.draftPrs = draftPrs as PhoebeUserConfig["draftPrs"];
+  }
+
+  const defaultProvider = readNonEmpty(env, "PHOEBE_DEFAULT_PROVIDER");
+  if (defaultProvider !== undefined) {
+    if (!(PROVIDER_NAMES as readonly string[]).includes(defaultProvider)) {
+      throw new Error(
+        `PHOEBE_DEFAULT_PROVIDER must be one of ${PROVIDER_NAMES.join(", ")} (got "${defaultProvider}").`,
+      );
+    }
+    overlaid.defaultProvider = defaultProvider as ProviderName;
+  }
+
+  return overlaid;
+}
+
+/**
+ * Resolve a `--config` argument (or the default) to an absolute path and
+ * assert the file exists. Split from `loadUserConfig` so the CLI can print
+ * a precise "file not found" message before attempting the dynamic import.
+ */
+export function resolveConfigPath(argPath: string | undefined, cwd: string): string {
+  const candidate = argPath ?? "phoebe.config.ts";
+  const absolute = isAbsolute(candidate) ? candidate : resolvePath(cwd, candidate);
+  if (!existsSync(absolute)) {
+    throw new Error(
+      argPath
+        ? `Config file not found: ${absolute} (passed via --config).`
+        : `Config file not found: ${absolute}. ` +
+            `Create a phoebe.config.ts in the current directory or pass --config <path>.`,
+    );
+  }
+  return absolute;
+}
+
+/**
+ * Dynamically import a `phoebe.config.ts` and return the user shape. Native
+ * Node type-stripping (unflagged on Node ≥ 24, the version Phoebe requires)
+ * handles the TS syntax — no bundler needed on the consumer side. Accepts
+ * either a default export or a named `config` export so the pre-`defineConfig`
+ * scaffold still loads.
+ *
+ * `reloadKey` busts Node's ESM module cache, which is keyed by URL and would
+ * otherwise hand back the first import forever. The engine never needs it (each
+ * run is a fresh process); `phoebe boot` does, because it re-reads the mounted
+ * config in-process when the reconcile watch sees it change (#42). Pass the
+ * config's fingerprint, not a counter: an unchanged config then reuses the
+ * cached module instead of leaking a new registry entry per read.
+ */
+export async function loadUserConfig(
+  configPath: string,
+  opts: { reloadKey?: string } = {},
+): Promise<PhoebeUserConfig> {
+  const fileUrl = pathToFileURL(configPath);
+  if (opts.reloadKey !== undefined) {
+    fileUrl.searchParams.set("phoebe-reload", opts.reloadKey);
+  }
+  const url = fileUrl.href;
+  let mod: unknown;
+  try {
+    mod = await import(url);
+  } catch (error) {
+    throw new Error(
+      `Failed to load ${configPath}: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  const record = mod as Record<string, unknown>;
+  const candidate =
+    (typeof record["default"] === "object" && record["default"] !== null
+      ? record["default"]
+      : undefined) ??
+    (typeof record["config"] === "object" && record["config"] !== null
+      ? record["config"]
+      : undefined);
+  if (!candidate) {
+    throw new Error(
+      `${configPath} must export a Phoebe config as \`export default defineConfig({ ... })\` ` +
+        `or a named \`export const config = { ... }\`.`,
+    );
+  }
+  return candidate as PhoebeUserConfig;
+}