phoebe-agent 0.0.0 → 0.1.0

package/prompts/research-prompt.md

@@ -0,0 +1,61 @@
+# Context
+
+## Assigned research ticket
+
+You are resolving **exactly** wayfinder research ticket **#{{ISSUE_NUMBER}}** — the orchestrator selected it before this run started. Do not pick a different ticket. It is a child of a `wayfinder:map` issue and carries the `{{RESEARCH_LABEL}}` label.
+
+!`gh issue view {{ISSUE_NUMBER}} --json number,title,body,labels,comments --jq '{number, title, body, labels: [.labels[].name], comments: [.comments[].body]}'`
+
+## Candidate parent maps
+
+!`gh issue list --label "wayfinder:map" --state open --json number,title --jq '[.[] | {number, title}]'`
+
+# Task
+
+You are Phoebe — resolving a **wayfinder research ticket** (an AFK ticket type: reading primary sources and recording what you found). Your job is to answer the ticket's Question from authoritative sources, produce a Markdown summary, and run wayfinder's resolution protocol.
+
+**Before anything else, read `AGENTS.md` at the repo root, if present**, and — if it exists — the wayfinder skill at `.agents/skills/wayfinder/SKILL.md`. AGENTS.md is the single source of project guidance and overrides your defaults; the wayfinder skill defines the map/ticket protocol you are resolving against.
+
+## Workflow
+
+1. **Read the Question.** The ticket body holds a `## Question` — the decision or investigation this ticket resolves, sized to one session. Resolve _that_, nothing broader.
+
+2. **Find the parent map.** This ticket is a child of one `wayfinder:map` issue. Identify it from a reference in the ticket body, its sub-issue relationship, or by reading the candidate maps listed above (their bodies point at their tickets). Load the map body — you need its `## Decisions so far` and `## Notes` (the Notes name skills every session should consult). If you genuinely cannot identify the map, say so in the resolution comment and continue without the map update.
+
+3. **Investigate primary sources.** Read official documentation, third-party API references, and local resources (knowledge bases, source in this repo). Prefer authoritative **primary** sources over summaries; record exactly where each fact came from. Never invent findings — an honest "the docs don't say" is a valid answer.
+
+4. **Produce the Markdown summary — pick the output shape the finding needs:**
+   - **Issue-level artifact (default).** Most research resolves this way: the summary lives as a comment (or a linked asset) on the ticket, with no code change. Leave the worktree without commits.
+   - **Committed doc (PR).** _Only_ when the finding is naturally a document that belongs in the repo (a reference note others will read from the tree). Write it where the repo already keeps such notes — match the existing convention; do not invent a new location. Commit it with a `Phoebe:` prefix. The host will push the branch and open a PR whose body closes this ticket.
+
+5. **Verify (committed-doc case only).** If you committed a doc and the repo has gates, run `{{READY_COMMAND}}` (or `{{CHECK_COMMAND}}` and `{{TEST_COMMAND}}`) and fix any failure before finishing. A pure issue-level artifact skips this.
+
+6. **Resolve per wayfinder protocol:**
+   1. **Post the resolution comment** on ticket #{{ISSUE_NUMBER}} — the answer itself, or the summary with a link to the committed doc/asset:
+      ```
+      gh issue comment {{ISSUE_NUMBER}} --body "<answer + sources>"
+      ```
+   2. **Close the ticket — but only in the issue-level-artifact case:**
+      ```
+      gh issue close {{ISSUE_NUMBER}}
+      ```
+      If you committed a doc, **do not close it here** — the PR the host opens carries `Closes #{{ISSUE_NUMBER}}` and closes it on merge.
+   3. **Append a pointer to the map's `## Decisions so far`** — one line, referring to the ticket by name (never a bare number), gisting the answer so a future session can judge relevance and zoom the link for detail. Fetch the map body, add the line under that heading, and write it back:
+      ```
+      - [<ticket title>](<ticket url>) — <one-line gist of the answer>
+      ```
+      Use `gh issue edit <map-number> --body-file -` with the amended body. Do not restate the full answer on the map — it is an index, not a store.
+
+## Rules
+
+- Work on **this ticket only** (#{{ISSUE_NUMBER}}). Do not resolve other tickets or edit unrelated parts of the map.
+- Default to an **issue-level artifact**; commit a doc only when it genuinely belongs in the repo.
+- **Close the ticket yourself only when you did not commit a doc.** A committed-doc PR closes it on merge — closing twice or closing before merge is wrong.
+- Cite sources for every finding; do not present guesses as facts.
+- If you are blocked (the Question needs a human decision, a source is inaccessible, the map is unfindable), post what you have as a comment explaining the blocker and leave the ticket **open** — do not close it.
+
+# Done
+
+When ticket #{{ISSUE_NUMBER}} is resolved (or you are blocked and have commented), output the completion signal:
+
+<promise>COMPLETE</promise>

package/src/agent-env.ts

@@ -0,0 +1,32 @@
+// Explicit env allowlist for agent child processes. The agent sees PATH, HOME,
+// git identity, the GitHub token, and the *active* provider's API key — never
+// the other providers' keys, so a prompt-injected agent can't exfiltrate the
+// whole keyring.
+
+import type { PhoebeConfig, ProviderName } from "./config-schema.ts";
+
+const BASE_ALLOWLIST = [
+  "PATH",
+  "HOME",
+  "GH_TOKEN",
+  "GIT_AUTHOR_NAME",
+  "GIT_AUTHOR_EMAIL",
+  "GIT_COMMITTER_NAME",
+  "GIT_COMMITTER_EMAIL",
+] as const;
+
+export function buildAgentEnv(opts: {
+  parentEnv: Record<string, string | undefined>;
+  provider: ProviderName;
+  providerEnv: PhoebeConfig["providerEnv"];
+}): Record<string, string> {
+  const { parentEnv, provider, providerEnv } = opts;
+  const env: Record<string, string> = { CI: "true" };
+  for (const key of [...BASE_ALLOWLIST, providerEnv[provider]]) {
+    const value = parentEnv[key];
+    if (value !== undefined && value !== "") {
+      env[key] = value;
+    }
+  }
+  return env;
+}

package/src/branded.ts

@@ -0,0 +1,19 @@
+// Nominal (branded) types for the three primitive slots that flow through the
+// engine and were previously bare `string` / `number`: git commit SHAs, git
+// branch refs, and PR numbers. Before branding, any two of these passed each
+// other's parameter slot silently — a `headRefName` (branch) could be handed to
+// a function expecting a `headSha`, and tsc said nothing.
+//
+// The brand is a compile-time-only phantom field; it has no runtime footprint.
+// `asSha` / `asBranchRef` / `asPrNumber` are identity casts applied at the trust
+// boundary — where `gh` output is parsed and where config values are loaded —
+// so interior code carries the distinction that tsc then enforces end-to-end.
+// See issue #14.
+
+export type Sha = string & { readonly __brand: "Sha" };
+export type BranchRef = string & { readonly __brand: "BranchRef" };
+export type PrNumber = number & { readonly __brand: "PrNumber" };
+
+export const asSha = (value: string): Sha => value as Sha;
+export const asBranchRef = (value: string): BranchRef => value as BranchRef;
+export const asPrNumber = (value: number): PrNumber => value as PrNumber;

package/src/cli.ts

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+
+// `phoebe` bin — the packaged CLI consumers invoke via
+// `npx phoebe-agent [flags]` (or a pinned `phoebe` script). Recognises two
+// modes:
+//
+//   phoebe init [dir]   Scaffold a consumer-owned runtime (config, prompts,
+//                       .env.example, container templates, gitignore).
+//                       Skips existing files — safe to re-run.
+//   phoebe [flags]      Run the engine. Loads the consumer's
+//                       `phoebe.config.ts`, overlays `PHOEBE_*` env vars,
+//                       installs the resolved config, then hands off to main.
+//
+// This is the only supported v1 programmatic surface: there is no exported
+// `run(config)` — CLI-only. That keeps every consumer on the same load/resolve/
+// install pipeline and leaves the door open to CLI-only concerns (init/pin
+// scaffolding, log formatting) without breaking a library API.
+
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { resolveConfig } from "./config-schema.ts";
+import { formatInitReport, runInit } from "./init.ts";
+import { applyEnvOverlay, loadUserConfig, resolveConfigPath } from "./load-config.ts";
+import { setResolvedConfig } from "./resolved-config.ts";
+
+type ParsedArgs = { configPath: string | undefined; help: boolean; forward: string[] };
+
+/**
+ * Extract `--config <path>` / `--config=<path>` / `-c <path>` and `--help`/`-h`
+ * from argv, forwarding everything else to `runEngine`. A minimal parser is
+ * enough — the engine handles its own boolean flags (`--run-once`, `--dry-run`)
+ * from the forwarded array.
+ */
+export function parseCliArgs(argv: readonly string[]): ParsedArgs {
+  const forward: string[] = [];
+  let configPath: string | undefined;
+  let help = false;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") {
+      help = true;
+      continue;
+    }
+    if (arg === "--config" || arg === "-c") {
+      const next = argv[i + 1];
+      if (next === undefined) {
+        throw new Error(`${arg} requires a path argument (e.g. --config phoebe.config.ts).`);
+      }
+      configPath = next;
+      i += 1;
+      continue;
+    }
+    if (arg !== undefined && arg.startsWith("--config=")) {
+      configPath = arg.slice("--config=".length);
+      continue;
+    }
+    if (arg !== undefined) {
+      forward.push(arg);
+    }
+  }
+  return { configPath, help, forward };
+}
+
+export type ParsedInitArgs = { targetDir: string; help: boolean };
+
+/**
+ * Parse argv left after the leading `init` token has been consumed. Supports
+ * an optional positional target directory (`phoebe init ./my-agent`) and
+ * `--help`. Extra flags are rejected loudly so a typo like `--forcee` fails
+ * fast instead of being silently ignored.
+ */
+export function parseInitArgs(argv: readonly string[]): ParsedInitArgs {
+  let targetDir: string | undefined;
+  let help = false;
+  for (const arg of argv) {
+    if (arg === "--help" || arg === "-h") {
+      help = true;
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      throw new Error(`Unknown flag \`${arg}\` for \`phoebe init\`. See \`phoebe init --help\`.`);
+    }
+    if (targetDir !== undefined) {
+      throw new Error(
+        `\`phoebe init\` takes at most one target directory (got \`${targetDir}\` and \`${arg}\`).`,
+      );
+    }
+    targetDir = arg;
+  }
+  return { targetDir: targetDir ?? ".", help };
+}
+
+const HELP_TEXT = `phoebe — AFK coding agent
+
+Usage:
+  phoebe init [dir]                Scaffold a consumer-owned runtime
+  phoebe [--config <path>] [flags] Run the engine
+
+Options (engine mode):
+  --config, -c <path>   Path to phoebe.config.ts (default: ./phoebe.config.ts)
+  --run-once            Work one unit of the first one-shot-eligible kind, then exit
+  --dry-run             Print the selected unit without executing it
+  --help, -h            Show this message
+
+Environment overlays (each replaces the corresponding config field):
+  PHOEBE_REPO_SLUG, PHOEBE_REPO_URL, PHOEBE_DEFAULT_BRANCH, PHOEBE_BRANCH_PREFIX,
+  PHOEBE_READY_LABEL, PHOEBE_PROCESSING_LABEL, PHOEBE_PR_OPT_OUT_LABEL,
+  PHOEBE_INSTALL_COMMAND, PHOEBE_CHECK_COMMAND, PHOEBE_TEST_COMMAND,
+  PHOEBE_READY_COMMAND, PHOEBE_BLOCKED_BY_PATTERN, PHOEBE_REVIEWS_SUCCESS_HEADING,
+  PHOEBE_PR_SCOPE, PHOEBE_DRAFT_PRS, PHOEBE_DEFAULT_PROVIDER
+
+Runtime toggles (read directly by the engine, not overlaid onto the config):
+  PHOEBE_AGENT           Provider name to use for this run (cursor|claude|codex)
+  PHOEBE_MODEL           Model to use for this run
+  PHOEBE_POLL_INTERVAL_MS Persistent-mode poll interval (default 300000)
+`;
+
+const INIT_HELP_TEXT = `phoebe init — scaffold a consumer-owned runtime
+
+Usage:
+  phoebe init [dir]
+
+Writes into [dir] (default: current directory):
+  phoebe.config.ts             Consumer config starter (edit the five required fields)
+  prompts/                     Copies of the shipped agent prompts (edit to override)
+  .env.example                 Documented environment variables to copy to .env
+  .gitignore                   Additive — appends Phoebe entries only
+  container/Dockerfile         Runtime image (Node 24 + git + gh, entrypoint: phoebe boot)
+  container/compose.yml        Compose config for the long-lived boot container
+  container/compose.local.yml  Dev overlay to run an engine checkout from your host
+
+Existing files are left untouched, so re-running is safe. To regenerate a
+scaffolded file, delete it first and re-run \`phoebe init\`.
+`;
+
+/**
+ * Engine-CLI entry point. Loads the consumer's config, overlays env, installs
+ * the resolved config, then runs the engine (or scaffolds via `init`). The
+ * bootstrapper (bootstrap/cli.ts) delegates here so the engine keeps a single
+ * load/resolve/install pipeline and stays directly runnable. The published bin
+ * is a JS launcher (bootstrap/bin.mjs) that materializes the package outside
+ * node_modules and execs bootstrap/cli.ts there.
+ */
+export async function runCli(): Promise<void> {
+  const args = process.argv.slice(2);
+
+  if (args[0] === "init") {
+    const parsed = parseInitArgs(args.slice(1));
+    if (parsed.help) {
+      process.stdout.write(INIT_HELP_TEXT);
+      return;
+    }
+    const report = runInit({ targetDir: parsed.targetDir });
+    process.stdout.write(formatInitReport(report, parsed.targetDir));
+    return;
+  }
+
+  const parsed = parseCliArgs(args);
+  if (parsed.help) {
+    process.stdout.write(HELP_TEXT);
+    return;
+  }
+
+  const configPath = resolveConfigPath(parsed.configPath, process.cwd());
+  const userConfig = await loadUserConfig(configPath);
+  const overlaid = applyEnvOverlay(userConfig, process.env);
+  setResolvedConfig(resolveConfig(overlaid));
+
+  // Import after the config is installed — main.ts's module-level constants
+  // read `config` at import time via the Proxy in resolved-config.ts.
+  const { runEngine } = await import("./main.ts");
+  await runEngine(parsed.forward);
+}
+
+// Run the engine only when this module is invoked directly (`node …/src/cli.ts`)
+// — how the engine runs standalone. The bootstrapper reaches it by importing
+// `runCli` (bootstrap/cli.ts), so this guard stays dormant there; tests import
+// `parseCliArgs` without triggering the pipeline for the same reason. `argv[1]`
+// is realpath'd so a symlinked entry still matches `import.meta.url`, which Node
+// resolves through symlinks.
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+  runCli().catch((error: unknown) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`[phoebe] ${message}`);
+    process.exit(1);
+  });
+}

package/src/config-schema.ts

@@ -0,0 +1,278 @@
+// Shape of the repo-specific configuration the Phoebe engine runs against.
+// The values live in ../phoebe.config.ts — the single file allowed to mention
+// this repository. Engine modules (everything under src/) import the resolved
+// config from ./resolved-config.ts and stay repo-agnostic;
+// src/config-seam.test.ts enforces it.
+//
+// Two shapes live here. `PhoebeUserConfig` is what a consumer writes: only the
+// unavoidable repo/toolchain fields are required; everything else is optional
+// and filled from `CONFIG_DEFAULTS` by `resolveConfig()`. `PhoebeConfig` is the
+// fully-resolved shape the engine sees at runtime — every field populated.
+
+export const PROVIDER_NAMES = ["cursor", "claude", "codex"] as const;
+export type ProviderName = (typeof PROVIDER_NAMES)[number];
+
+/**
+ * Selects where the thin `phoebe boot` bootstrapper materializes the engine
+ * from — a GitHub ref (branch/tag/SHA, defaulting to `main` on the shipped
+ * engine repo) or a local mount. The engine itself never reads this: it is a
+ * bootstrapper concern, resolved by `bootstrap/engine-source.ts`. It lives on
+ * `PhoebeUserConfig` only so a consumer config that sets it still type-checks,
+ * and `resolveConfig` deliberately drops it — it never reaches `PhoebeConfig`.
+ */
+export type EngineSourceField =
+  | { source: "github"; ref?: string; repo?: string }
+  | { source: "local" };
+
+export type PromptFilesConfig = {
+  issue: string;
+  conflict: string;
+  checks: string;
+  reviews: string;
+  research: string;
+};
+
+export type PathsConfig = {
+  /** The private clone (origin hub). */
+  repoDir: string;
+  /** Per-unit git worktrees. */
+  worktreesDir: string;
+  /** Lock, markers, logs. */
+  stateDir: string;
+};
+
+export type PhoebeConfig = {
+  /** GitHub `owner/repo` slug, passed to every `gh -R` call. */
+  repoSlug: string;
+  /** HTTPS clone URL for the container's private clone. */
+  repoUrl: string;
+  /** Branch PRs target and worktrees base off (usually `main`). */
+  defaultBranch: string;
+  /** Prefix for agent branches; issue branches are `<prefix>issue-<n>`. */
+  branchPrefix: string;
+  /** Label marking issues Phoebe may pick up. */
+  readyLabel: string;
+  /** Label marking wayfinder research tickets the `research` work kind picks up. */
+  researchLabel: string;
+  /** Label the agent applies to an issue it has claimed and is working. */
+  processingLabel: string;
+  /** Which open PRs the conflicts/checks/reviews work-kinds scan.
+   *  "phoebe" = only branchPrefix branches. "all" = any same-repo PR. */
+  prScope: "phoebe" | "all";
+  /** Draft PR handling: "skip-non-phoebe" = drafts on non-Phoebe branches are
+   *  off-limits; "skip-all" = never touch drafts; "include" = drafts are fair game. */
+  draftPrs: "skip-non-phoebe" | "skip-all" | "include";
+  /** PRs carrying this label are excluded from the PR scan in every mode. */
+  prOptOutLabel: string;
+  /** Shell command strings — toolchains differ per repo, so these are data. */
+  installCommand: string;
+  checkCommand: string;
+  testCommand: string;
+  /** The all-in-one gate the agent runs before pushing (e.g. `npm run ready`).
+   *  Substituted into default prompts as `{{READY_COMMAND}}`. */
+  readyCommand: string;
+  /**
+   * JavaScript-compatible regex source that matches an issue-blocker reference
+   * in issue body text. Must expose the blocker issue number as capture group 1.
+   * Compiled with the `gi` flags.
+   */
+  blockedByPattern: string;
+  /**
+   * Markdown heading the reviews agent must include when it posts its summary
+   * comment. The orchestrator detects the summary by substring match on this
+   * exact string, so it must be unique enough not to collide with other
+   * comments. Substituted into the default reviews prompt as
+   * `{{REVIEWS_SUCCESS_HEADING}}`.
+   */
+  reviewsSuccessHeading: string;
+  /**
+   * Prompt template paths, relative to the runtime root (process cwd —
+   * consumer checkout on the host; `/etc/phoebe` in the container where
+   * compose mounts config + `prompts/`). Absolute paths are accepted as-is.
+   */
+  promptFiles: PromptFilesConfig;
+  /** Ordered work kinds, validated by the orchestrator at startup. */
+  workOrder: readonly string[];
+  defaultProvider: ProviderName;
+  defaultModels: Record<ProviderName, string>;
+  /** Env var holding each provider's API key — the only key the agent child inherits. */
+  providerEnv: Record<ProviderName, string>;
+  /** Container filesystem layout (named volumes). */
+  paths: PathsConfig;
+};
+
+/**
+ * User-facing shape of `phoebe.config.ts`. Only the five fields with no sane
+ * cross-repo default are required; everything else is optional and filled from
+ * `CONFIG_DEFAULTS` by `resolveConfig()`. Nested objects (`promptFiles`,
+ * `paths`, `defaultModels`, `providerEnv`) are merged key-by-key, so overriding
+ * one provider's model or one prompt file does not force the caller to supply
+ * the rest.
+ */
+export type PhoebeUserConfig = {
+  repoSlug: string;
+  repoUrl: string;
+  installCommand: string;
+  checkCommand: string;
+  testCommand: string;
+  /** Bootstrapper-only engine source (see {@link EngineSourceField}). The
+   *  engine ignores it; `resolveConfig` drops it. Omitted ⇒ github/main. */
+  engine?: EngineSourceField;
+  defaultBranch?: string;
+  branchPrefix?: string;
+  readyLabel?: string;
+  researchLabel?: string;
+  processingLabel?: string;
+  prScope?: PhoebeConfig["prScope"];
+  draftPrs?: PhoebeConfig["draftPrs"];
+  prOptOutLabel?: string;
+  readyCommand?: string;
+  blockedByPattern?: string;
+  reviewsSuccessHeading?: string;
+  promptFiles?: Partial<PromptFilesConfig>;
+  workOrder?: readonly string[];
+  defaultProvider?: ProviderName;
+  defaultModels?: Partial<Record<ProviderName, string>>;
+  providerEnv?: Partial<Record<ProviderName, string>>;
+  paths?: Partial<PathsConfig>;
+};
+
+/**
+ * Engine defaults for every optional user field. These land in the resolved
+ * config whenever the consumer's `phoebe.config.ts` omits them, so a minimal
+ * consumer config only has to name the repo and its three toolchain commands.
+ */
+export const CONFIG_DEFAULTS = {
+  defaultBranch: "main",
+  branchPrefix: "phoebe/",
+  readyLabel: "ready-for-agent",
+  researchLabel: "wayfinder:research",
+  processingLabel: "processing",
+  prScope: "phoebe" as const,
+  draftPrs: "skip-non-phoebe" as const,
+  prOptOutLabel: "ready-for-human",
+  readyCommand: "npm run ready",
+  blockedByPattern: String.raw`Blocked by\s+#(\d+)`,
+  reviewsSuccessHeading: "## Review feedback addressed",
+  promptFiles: {
+    issue: "prompts/issues-prompt.md",
+    conflict: "prompts/conflict-prompt.md",
+    checks: "prompts/checks-prompt.md",
+    reviews: "prompts/reviews-prompt.md",
+    research: "prompts/research-prompt.md",
+  } satisfies PromptFilesConfig,
+  workOrder: ["conflicts", "checks", "reviews", "issues", "research"] as readonly string[],
+  defaultProvider: "cursor" as ProviderName,
+  defaultModels: {
+    cursor: "composer-2.5",
+    claude: "claude-sonnet-4-6",
+    codex: "gpt-5.4-mini",
+  } satisfies Record<ProviderName, string>,
+  providerEnv: {
+    cursor: "CURSOR_API_KEY",
+    claude: "ANTHROPIC_API_KEY",
+    codex: "OPENAI_KEY",
+  } satisfies Record<ProviderName, string>,
+  paths: {
+    repoDir: "/data/repo",
+    worktreesDir: "/data/worktrees",
+    stateDir: "/data/state",
+  } satisfies PathsConfig,
+} as const;
+
+const REQUIRED_USER_FIELDS = [
+  "repoSlug",
+  "repoUrl",
+  "installCommand",
+  "checkCommand",
+  "testCommand",
+] as const satisfies readonly (keyof PhoebeUserConfig)[];
+
+/**
+ * Count the numbered capture groups defined by a regex source. We compile it
+ * with an added empty alternative (`|`) so the resulting regex always matches
+ * the empty string; the match array's length minus one then equals the number
+ * of capture groups, regardless of whether the original pattern would have
+ * matched anything on its own. Escaped parens, non-capturing groups (`(?:…)`),
+ * lookarounds, and named groups are handled correctly because we're asking
+ * the engine's own group count, not parsing the source ourselves.
+ */
+function countCaptureGroups(source: string): number {
+  const compiled = new RegExp(`${source}|`);
+  const match = compiled.exec("");
+  // The extra `|` guarantees a match against ""; TS still narrows to nullable.
+  if (!match) {
+    return 0;
+  }
+  return match.length - 1;
+}
+
+/**
+ * Throw when a required field is missing or blank, or when `blockedByPattern`
+ * is not a valid regex or fails to expose the blocker issue number as capture
+ * group 1. `parseBlockedBy` reads `match[1]`, so a pattern without a capture
+ * group would silently break the entire blocker-detection path — reject it up
+ * front. Kept separate from `resolveConfig` so consumers or tests can validate
+ * a config independent of the defaults merge.
+ */
+export function validateUserConfig(user: PhoebeUserConfig): void {
+  const missing = REQUIRED_USER_FIELDS.filter((key) => {
+    const value = user[key];
+    return typeof value !== "string" || value.trim().length === 0;
+  });
+  if (missing.length > 0) {
+    throw new Error(
+      `phoebe.config.ts is missing required field(s): ${missing.join(", ")}. ` +
+        `Only these five fields are required — the engine fills the rest from its defaults.`,
+    );
+  }
+  if (user.blockedByPattern !== undefined) {
+    try {
+      new RegExp(user.blockedByPattern, "gi");
+    } catch (err) {
+      throw new Error(
+        `phoebe.config.ts blockedByPattern is not a valid regex: ${(err as Error).message}`,
+      );
+    }
+    if (countCaptureGroups(user.blockedByPattern) < 1) {
+      throw new Error(
+        `phoebe.config.ts blockedByPattern must define capture group 1 for the ` +
+          `blocker issue number (parseBlockedBy reads match[1]). Wrap the number ` +
+          `portion in parentheses, e.g. String.raw\`Blocked by\\s+#(\\d+)\`.`,
+      );
+    }
+  }
+}
+
+/**
+ * Merge a user config with `CONFIG_DEFAULTS` and return the fully-populated
+ * shape the engine runs against. Nested records are shallow-merged so partial
+ * overrides (one prompt file, one provider's env var, etc.) work as expected.
+ */
+export function resolveConfig(user: PhoebeUserConfig): PhoebeConfig {
+  validateUserConfig(user);
+  return {
+    repoSlug: user.repoSlug,
+    repoUrl: user.repoUrl,
+    installCommand: user.installCommand,
+    checkCommand: user.checkCommand,
+    testCommand: user.testCommand,
+    defaultBranch: user.defaultBranch ?? CONFIG_DEFAULTS.defaultBranch,
+    branchPrefix: user.branchPrefix ?? CONFIG_DEFAULTS.branchPrefix,
+    readyLabel: user.readyLabel ?? CONFIG_DEFAULTS.readyLabel,
+    researchLabel: user.researchLabel ?? CONFIG_DEFAULTS.researchLabel,
+    processingLabel: user.processingLabel ?? CONFIG_DEFAULTS.processingLabel,
+    prScope: user.prScope ?? CONFIG_DEFAULTS.prScope,
+    draftPrs: user.draftPrs ?? CONFIG_DEFAULTS.draftPrs,
+    prOptOutLabel: user.prOptOutLabel ?? CONFIG_DEFAULTS.prOptOutLabel,
+    readyCommand: user.readyCommand ?? CONFIG_DEFAULTS.readyCommand,
+    blockedByPattern: user.blockedByPattern ?? CONFIG_DEFAULTS.blockedByPattern,
+    reviewsSuccessHeading: user.reviewsSuccessHeading ?? CONFIG_DEFAULTS.reviewsSuccessHeading,
+    promptFiles: { ...CONFIG_DEFAULTS.promptFiles, ...user.promptFiles },
+    workOrder: user.workOrder ?? CONFIG_DEFAULTS.workOrder,
+    defaultProvider: user.defaultProvider ?? CONFIG_DEFAULTS.defaultProvider,
+    defaultModels: { ...CONFIG_DEFAULTS.defaultModels, ...user.defaultModels },
+    providerEnv: { ...CONFIG_DEFAULTS.providerEnv, ...user.providerEnv },
+    paths: { ...CONFIG_DEFAULTS.paths, ...user.paths },
+  };
+}

package/src/drain.ts

@@ -0,0 +1,74 @@
+// Graceful-drain coordination for the persistent engine loop.
+//
+// `phoebe boot` (the bootstrapper) runs the engine as a long-lived child and
+// stops it with SIGTERM — on container shutdown, and on a config/ref change the
+// reconcile watch relaunches for (bootstrap/reconcile.ts). A hard SIGTERM would
+// kill the engine mid-work-unit, abandoning a half-finished agent run (a dirty
+// worktree, maybe a partially pushed branch). Instead the engine treats SIGTERM
+// as a *drain* request: finish the unit in flight, start no new one, exit 0.
+//
+// This module is that one-way latch — a boolean that flips on the first signal,
+// plus an interruptible wait so an idle poll-sleep wakes immediately instead of
+// stalling shutdown for a whole poll interval. It takes the emitter and signal
+// names as arguments (defaulting to `process` / `SIGTERM`) so the latch logic is
+// unit-tested without sending real process signals.
+//
+// Both poll loops use it, for the same reason: the engine's work loop drains on
+// it (src/main.ts), and the bootstrapper's reconcile watch takes it as the
+// container's stop request (bootstrap/reconcile.ts) so a shutdown wakes the
+// watch instead of waiting out a poll interval — and so boot survives the moment
+// between draining one engine and spawning its replacement.
+
+export interface DrainSignal {
+  /** True once a drain has been requested; never flips back. */
+  readonly requested: boolean;
+  /**
+   * Resolve after `ms`, or immediately once a drain is requested — whichever
+   * comes first. A drain arriving mid-wait wakes it so the loop stops promptly
+   * rather than sleeping out the full poll interval. Single-waiter: the loop
+   * awaits one wait() at a time.
+   */
+  wait(ms: number): Promise<void>;
+  /** Remove the signal listeners and cancel any pending wait. Idempotent. */
+  dispose(): void;
+}
+
+export function installDrainSignal(
+  emitter: NodeJS.EventEmitter = process,
+  signals: readonly NodeJS.Signals[] = ["SIGTERM"],
+): DrainSignal {
+  let requested = false;
+  // Resolver for an in-flight wait(), so a drain can wake it early. Cleared once
+  // it fires (or the wait times out) so we never resolve a stale promise.
+  let wake: (() => void) | undefined;
+
+  const onSignal = () => {
+    requested = true;
+    wake?.();
+  };
+  for (const signal of signals) emitter.on(signal, onSignal);
+
+  return {
+    get requested() {
+      return requested;
+    },
+    wait(ms: number): Promise<void> {
+      if (requested) return Promise.resolve();
+      return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+          wake = undefined;
+          resolve();
+        }, ms);
+        wake = () => {
+          clearTimeout(timer);
+          wake = undefined;
+          resolve();
+        };
+      });
+    },
+    dispose() {
+      for (const signal of signals) emitter.off(signal, onSignal);
+      wake?.();
+    },
+  };
+}