phoebe-agent 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JesusFilm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,55 @@
+# Phoebe
+
+**Phoebe is an AFK coding agent.** It polls a GitHub repository for ready-to-work
+issues, works each one on its own branch in an isolated git worktree, runs your
+project's gates, and opens a pull request. Between new issues it sweeps open PRs
+for merge conflicts, failing CI, and unresolved review feedback — so work keeps
+moving without a human babysitting every branch.
+
+Phoebe runs as a **single Docker container** that is both orchestrator and
+execution environment. Your host checkout is never touched: the container owns a
+private clone and pushes branches directly to origin. Every repo-specific value
+lives behind one config file, so the same engine drives any repository.
+
+> ⚠️ **Early scaffold.** This repository is being stood up as the public home of
+> Phoebe's engine, extracted from [`JesusFilm/youtube-studio`](https://github.com/JesusFilm/youtube-studio).
+> The engine, CLI packaging, `phoebe init` scaffolder, CI, and first npm release
+> land as the tracked execution issues on this repo. Until `phoebe-agent@0.1.0`
+> is published, treat everything here as work in progress.
+
+## Distribution
+
+The engine is published to npm as **`phoebe-agent`** (unscoped) and consumed as a
+pinned CLI — you never vendor the engine source into your repo, only a small
+config file, your prompt overrides, and the container files `phoebe init`
+scaffolds for you.
+
+## Documentation
+
+Docs live under [`docs/`](docs/) and grow as the engine lands:
+
+- `docs/architecture.md` — topology, worktree isolation, supervisor self-update.
+- `docs/configuration.md` — full config-field reference.
+- `docs/work-kinds.md` — issues / conflicts / checks / reviews mechanics.
+- `docs/operating.md` — controlling Phoebe as a human (labels, drafts, watermarks).
+- `docs/upgrading.md` — the init / pin / upgrade contract.
+- `docs/ai-install.md` — a deterministic, agent-followable install runbook.
+- `docs/releasing.md` — the Changesets + npm trusted-publishing release flow.
+
+Agents landing in this repo should start at [`AGENTS.md`](AGENTS.md).
+
+## History & attribution
+
+Phoebe was designed, built, and dogfooded inside
+[`JesusFilm/youtube-studio`](https://github.com/JesusFilm/youtube-studio), which
+remains its reference consumer. Its execution loop was first prototyped on
+[Sandcastle](https://github.com/mattpocock/sandcastle) (`@ai-hero/sandcastle`, by
+Matt Pocock) — the sandbox-per-run design proved the loop end-to-end and its
+provider wrappers are the design ancestor of `src/providers/`. The dependency was
+removed when the host-spawns-sandboxes topology was replaced by the single
+persistable container. This repository starts with fresh history; the full design
+record lives in the youtube-studio issue tracker.
+
+## License
+
+[MIT](LICENSE) © JesusFilm

package/dist/phoebe.config.d.ts

@@ -0,0 +1,2 @@
+import type { PhoebeConfig } from "./src/config-schema.ts";
+export declare const config: PhoebeConfig;

package/dist/phoebe.config.js

@@ -0,0 +1,43 @@
+// All repo-specific configuration for the Phoebe engine lives here — repo slug,
+// labels, branch prefix, toolchain commands, prompts, work order, provider keys.
+// Engine code under src/ never mentions any concrete repository (enforced by
+// src/config-seam.test.ts), so pointing Phoebe at a repo is a matter of editing
+// this one file. These are the engine's shipped defaults; consumers replace the
+// repo/toolchain values with their own.
+export const config = {
+    repoSlug: "your-org/your-repo",
+    repoUrl: "https://github.com/your-org/your-repo.git",
+    defaultBranch: "main",
+    branchPrefix: "phoebe/",
+    readyLabel: "ready-for-agent",
+    prScope: "phoebe",
+    draftPrs: "skip-non-phoebe",
+    prOptOutLabel: "ready-for-human",
+    installCommand: "npm ci",
+    checkCommand: "npm run check",
+    testCommand: "npm test",
+    promptFiles: {
+        issue: "prompts/prompt.md",
+        conflict: "prompts/conflict-prompt.md",
+        checks: "prompts/checks-prompt.md",
+        reviews: "prompts/reviews-prompt.md",
+    },
+    workOrder: ["conflicts", "checks", "reviews", "issues"],
+    defaultProvider: "cursor",
+    defaultModels: {
+        cursor: "composer-2.5",
+        claude: "claude-sonnet-4-6",
+        codex: "gpt-5.4-mini",
+    },
+    providerEnv: {
+        cursor: "CURSOR_API_KEY",
+        claude: "ANTHROPIC_API_KEY",
+        codex: "OPENAI_KEY",
+    },
+    selfUpdatePaths: ["package.json", "package-lock.json"],
+    paths: {
+        repoDir: "/data/repo",
+        worktreesDir: "/data/worktrees",
+        stateDir: "/data/state",
+    },
+};

package/dist/src/agent-env.d.ts

@@ -0,0 +1,6 @@
+import type { PhoebeConfig, ProviderName } from "./config-schema.ts";
+export declare function buildAgentEnv(opts: {
+    parentEnv: Record<string, string | undefined>;
+    provider: ProviderName;
+    providerEnv: PhoebeConfig["providerEnv"];
+}): Record<string, string>;

package/dist/src/agent-env.js

@@ -0,0 +1,24 @@
+// 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.
+const BASE_ALLOWLIST = [
+    "PATH",
+    "HOME",
+    "GH_TOKEN",
+    "GIT_AUTHOR_NAME",
+    "GIT_AUTHOR_EMAIL",
+    "GIT_COMMITTER_NAME",
+    "GIT_COMMITTER_EMAIL",
+];
+export function buildAgentEnv(opts) {
+    const { parentEnv, provider, providerEnv } = opts;
+    const env = { CI: "true" };
+    for (const key of [...BASE_ALLOWLIST, providerEnv[provider]]) {
+        const value = parentEnv[key];
+        if (value !== undefined && value !== "") {
+            env[key] = value;
+        }
+    }
+    return env;
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+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 declare function parseCliArgs(argv: readonly string[]): ParsedArgs;
+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 declare function parseInitArgs(argv: readonly string[]): ParsedInitArgs;
+export {};

package/dist/src/cli.js

@@ -0,0 +1,161 @@
+#!/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.js";
+import { formatInitReport, runInit } from "./init.js";
+import { applyEnvOverlay, loadUserConfig, resolveConfigPath } from "./load-config.js";
+import { setResolvedConfig } from "./resolved-config.js";
+/**
+ * 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) {
+    const forward = [];
+    let configPath;
+    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 };
+}
+/**
+ * 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) {
+    let targetDir;
+    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)
+  PHOEBE_DEFAULT_BRANCH  Branch the supervisor keeps the clone on (overrides tracked branch only)
+`;
+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 + git + gh + pinned phoebe-agent)
+  container/compose.yml        Base one-shot compose config
+  container/compose.daemon.yml Overlay to run Phoebe as a persistent daemon
+  container/supervisor.sh      Warm-install + engine-restart loop (chmod +x)
+
+Existing files are left untouched, so re-running is safe. To regenerate a
+scaffolded file, delete it first and re-run \`phoebe init\`.
+`;
+async function main() {
+    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.js");
+    await runEngine(parsed.forward);
+}
+// Only run when invoked as the entry point — tests import `parseCliArgs` from
+// this module without triggering the whole CLI pipeline. `argv[1]` is realpath'd
+// so a bin symlink (`node_modules/.bin/phoebe -> ../phoebe-agent/dist/src/cli.js`)
+// still matches `import.meta.url`, which Node resolves through symlinks.
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+    main().catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`[phoebe] ${message}`);
+        process.exit(1);
+    });
+}

package/dist/src/config-schema.d.ts

@@ -0,0 +1,163 @@
+export declare const PROVIDER_NAMES: readonly ["cursor", "claude", "codex"];
+export type ProviderName = (typeof PROVIDER_NAMES)[number];
+export type PromptFilesConfig = {
+    issue: string;
+    conflict: string;
+    checks: string;
+    reviews: 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 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 package root (apps/phoebe). */
+    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>;
+    /**
+     * Repo paths that mean "Phoebe's own code changed" — a fetch of the default
+     * branch touching these makes the orchestrator exit for a supervisor
+     * reinstall + re-exec. Directory entries must end with `/`.
+     */
+    selfUpdatePaths: readonly 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;
+    defaultBranch?: string;
+    branchPrefix?: string;
+    readyLabel?: 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>>;
+    selfUpdatePaths?: readonly 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 declare const CONFIG_DEFAULTS: {
+    readonly defaultBranch: "main";
+    readonly branchPrefix: "phoebe/";
+    readonly readyLabel: "ready-for-agent";
+    readonly processingLabel: "processing";
+    readonly prScope: "phoebe";
+    readonly draftPrs: "skip-non-phoebe";
+    readonly prOptOutLabel: "ready-for-human";
+    readonly readyCommand: "npm run ready";
+    readonly blockedByPattern: string;
+    readonly reviewsSuccessHeading: "## Review feedback addressed";
+    readonly promptFiles: {
+        issue: string;
+        conflict: string;
+        checks: string;
+        reviews: string;
+    };
+    readonly workOrder: readonly string[];
+    readonly defaultProvider: ProviderName;
+    readonly defaultModels: {
+        cursor: string;
+        claude: string;
+        codex: string;
+    };
+    readonly providerEnv: {
+        cursor: string;
+        claude: string;
+        codex: string;
+    };
+    readonly selfUpdatePaths: readonly string[];
+    readonly paths: {
+        repoDir: string;
+        worktreesDir: string;
+        stateDir: string;
+    };
+};
+/**
+ * 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 declare function validateUserConfig(user: PhoebeUserConfig): void;
+/**
+ * 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 declare function resolveConfig(user: PhoebeUserConfig): PhoebeConfig;

package/dist/src/config-schema.js

@@ -0,0 +1,140 @@
+// 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"];
+/**
+ * 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",
+    processingLabel: "processing",
+    prScope: "phoebe",
+    draftPrs: "skip-non-phoebe",
+    prOptOutLabel: "ready-for-human",
+    readyCommand: "npm run ready",
+    blockedByPattern: String.raw `Blocked by\s+#(\d+)`,
+    reviewsSuccessHeading: "## Review feedback addressed",
+    promptFiles: {
+        issue: "prompts/prompt.md",
+        conflict: "prompts/conflict-prompt.md",
+        checks: "prompts/checks-prompt.md",
+        reviews: "prompts/reviews-prompt.md",
+    },
+    workOrder: ["conflicts", "checks", "reviews", "issues"],
+    defaultProvider: "cursor",
+    defaultModels: {
+        cursor: "composer-2.5",
+        claude: "claude-sonnet-4-6",
+        codex: "gpt-5.4-mini",
+    },
+    providerEnv: {
+        cursor: "CURSOR_API_KEY",
+        claude: "ANTHROPIC_API_KEY",
+        codex: "OPENAI_KEY",
+    },
+    selfUpdatePaths: ["package.json", "package-lock.json"],
+    paths: {
+        repoDir: "/data/repo",
+        worktreesDir: "/data/worktrees",
+        stateDir: "/data/state",
+    },
+};
+const REQUIRED_USER_FIELDS = [
+    "repoSlug",
+    "repoUrl",
+    "installCommand",
+    "checkCommand",
+    "testCommand",
+];
+/**
+ * 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) {
+    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) {
+    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.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) {
+    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,
+        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 },
+        selfUpdatePaths: user.selfUpdatePaths ?? CONFIG_DEFAULTS.selfUpdatePaths,
+        paths: { ...CONFIG_DEFAULTS.paths, ...user.paths },
+    };
+}

package/dist/src/execution-gate.d.ts

@@ -0,0 +1,9 @@
+export declare const CONTAINER_MARKER_PATH = "/.phoebe-container";
+export declare function isInsideContainer(exists?: (path: string) => boolean): boolean;
+export type ExecutionDecision = "execute" | "dry-run" | "refuse";
+/** Pure decision: may this process execute the selected work unit? */
+export declare function executionDecision(opts: {
+    dryRun: boolean;
+    inContainer: boolean;
+}): ExecutionDecision;
+export declare const EXECUTION_REFUSED_MESSAGE: string;