phoebe-agent 0.0.0 → 0.1.1

package/templates/container/Dockerfile

@@ -1,20 +1,32 @@
 # Phoebe runtime image — scaffolded by `phoebe init`.
 #
 # Consumer-owned: commit this file, tweak it as you need. Phoebe treats the
-# resulting image as both orchestrator and execution environment. The engine
-# itself is installed from npm (`{{CLI_BIN}}`) — the source is not vendored.
+# resulting image as both orchestrator and execution environment.
+#
+# The image carries the *bootstrapper* (`{{CLI_BIN}}` from npm), not the engine.
+# `phoebe boot` is the container's long-lived main process: it reads the mounted
+# `phoebe.config.ts`, materializes the engine from the source named there
+# (`engine: { source: "github", ref }` by default), execs it, and keeps
+# supervising it — relaunching on a config or ref change, falling back to the
+# last engine commit that ran healthily if a new one will not boot, and draining
+# it gracefully on `SIGTERM`. So changing engine version is a config edit, not
+# an image rebuild; this image only changes when the toolchain around it does.
 #
 # What ships in this image:
-#   * Node.js (LTS) + git + GitHub CLI (`gh`) — the runtime the engine drives.
-#   * A globally installed `{{CLI_BIN}}` pinned by the compose file.
-#   * A `supervisor.sh` that keeps the engine restarted and self-updating.
+#   * Node.js 24 + git + GitHub CLI (`gh`) — the runtime the engine drives.
+#   * A globally installed `{{CLI_BIN}}` (the bootstrapper).
+#   * Your agent provider's CLI.
 #
 # What lives on named volumes (see compose.yml):
 #   * /data/repo       — Phoebe's private clone of the target repo.
 #   * /data/worktrees  — Per-work-unit git worktrees.
-#   * /data/state      — Lock, watermarks, logs.
+#   * /data/state      — Lock, watermarks, logs, crash-loop record.
+#   * /data/engine     — Engine checkouts, so a restart fetches instead of cloning.
+#
+# The workload runs as the unprivileged `phoebe` user, not root — see the
+# privilege-drop block below for the two things that constrains.
 
-FROM node:22-bookworm-slim
+FROM node:24-bookworm-slim
 
 # gh CLI + git + tini for signal handling; keep the layer small.
 RUN apt-get update \
@@ -30,11 +42,89 @@ RUN apt-get update \
  && apt-get install -y --no-install-recommends gh \
  && rm -rf /var/lib/apt/lists/*
 
-# PHOEBE_VERSION is set by the compose file so consumers can pin the engine
-# without editing the Dockerfile. `latest` is only a build-time default; the
-# compose files should always pass an explicit version.
-ARG PHOEBE_VERSION=latest
-RUN npm install -g {{CLI_BIN}}@${PHOEBE_VERSION}
+# The unprivileged user everything below the privilege drop runs as, and the
+# four volume mount points, created *now* while we are still root.
+#
+# The ordering matters and is not cosmetic: Docker seeds a **fresh named volume
+# from the image's contents at that path, ownership included**. If /data/repo
+# does not exist in the image, Docker creates the mount point as root:root and
+# the first `git clone` fails with EACCES. Creating and chowning them here is
+# what makes the volumes writable after the drop.
+#
+# (`node:24` already ships a uid-1000 `node` user. We add our own so the name
+# in `ps`, in log output, and on the volumes says what it is, and so the uid is
+# stable if the base image ever renumbers `node`. The uid is a literal rather
+# than a build ARG because nothing needs to vary it — everything Phoebe writes
+# lives on named volumes, which take their ownership from this image, not from
+# any host uid. Change it here if you have a reason to.)
+RUN useradd --create-home --shell /bin/bash --uid 10001 --user-group phoebe \
+ && mkdir -p /data/repo /data/worktrees /data/state /data/engine \
+ && chown -R phoebe:phoebe /data
+
+# The bootstrapper. Unpinned on purpose: which *engine* you run is `engine.ref`
+# in phoebe.config.ts, and this package is only the thin launcher around it.
+# Pin it (`{{CLI_BIN}}@<version>`) if you want the launcher itself frozen too.
+#
+# Installed as root into /usr/local, which `phoebe` only ever reads: at boot it
+# copies itself out to PHOEBE_ENGINE_DIR (/data/engine, owned by us) before
+# running anything, because Node 24 refuses to type-strip TypeScript under a
+# `node_modules/` path segment.
+RUN npm install -g {{CLI_BIN}}
+
+# Provider agent CLI. The engine spawns the selected provider's CLI as a child
+# (`agent` for cursor, `claude`, or `codex`), so the one matching your
+# `defaultProvider` / `PHOEBE_AGENT` must be on PATH — otherwise the run dies
+# with `spawn <cli> ENOENT`. Default below installs Cursor. Swap or add the
+# commented lines for the provider you actually run.
+#
+# This is deliberately NOT the `curl https://cursor.com/install | bash` one-liner
+# Cursor documents. That pipes whatever the vendor serves at build time straight
+# into a shell, so two builds of the same Dockerfile can produce different
+# images and neither records which agent it got. Cursor publishes no checksums
+# and no `latest` indirection, but its installer does resolve to a plain
+# versioned artifact, which is what we pin to. The digests below are ours,
+# computed on 2026-07-28 by fetching both architectures' tarballs from the URL
+# below — they pin the build, they are not a vendor attestation.
+#
+# To bump: run the vendor installer once and read the version out of the
+# DOWNLOAD_URL it echoes, then `sha256sum` the linux/x64 *and* linux/arm64
+# tarballs. Both, even if you only build one — an unchecked digest for the other
+# arch turns into a hard build failure the day someone builds on it.
+ARG CURSOR_AGENT_VERSION=2026.07.23-e383d2b
+ARG CURSOR_AGENT_SHA256_X64=702ad595213bee5df0268be9f80a19f29fcceaa2a42fc55e39f2b5199051f0c4
+ARG CURSOR_AGENT_SHA256_ARM64=f40b99647cb24e0da885e97620a2048034f1fe8961910d573d827d77c4d26dcb
+# Set by BuildKit; the fallback keeps the classic builder working.
+ARG TARGETARCH
+RUN set -eux; \
+    case "${TARGETARCH:-$(dpkg --print-architecture)}" in \
+      amd64) cursor_arch=x64;   cursor_sha="${CURSOR_AGENT_SHA256_X64}" ;; \
+      arm64) cursor_arch=arm64; cursor_sha="${CURSOR_AGENT_SHA256_ARM64}" ;; \
+      *) echo "cursor-agent publishes no build for ${TARGETARCH}" >&2; exit 1 ;; \
+    esac; \
+    curl -fsSL -o /tmp/cursor-agent.tar.gz \
+      "https://downloads.cursor.com/lab/${CURSOR_AGENT_VERSION}/linux/${cursor_arch}/agent-cli-package.tar.gz"; \
+    echo "${cursor_sha}  /tmp/cursor-agent.tar.gz" | sha256sum -c -; \
+    mkdir -p /opt/cursor-agent; \
+    tar --strip-components=1 -xzf /tmp/cursor-agent.tar.gz -C /opt/cursor-agent; \
+    rm /tmp/cursor-agent.tar.gz; \
+    ln -s /opt/cursor-agent/cursor-agent /usr/local/bin/agent; \
+    ln -s /opt/cursor-agent/cursor-agent /usr/local/bin/cursor-agent
+# Both symlink names on purpose: the engine spawns `agent`, but the vendor
+# installer we replaced also created `cursor-agent`, and Cursor's own docs use
+# that name. Dropping it would make this a silent behaviour regression for
+# anyone whose scripts follow those docs.
+#
+# The installer would have put these in ~/.local/bin and needed a PATH entry
+# pointing into a home directory. /usr/local/bin is already on PATH for every
+# user, so the agent child resolves `agent` after the privilege drop with no
+# PATH edit — and no root-owned home directory leaks into its env
+# (src/agent-env.ts forwards PATH and HOME to the agent verbatim).
+#
+# Swapping providers? Pin these too — an unpinned `npm install -g` has the same
+# problem as the installer pipe above, just with a lockfile-shaped hole instead
+# of a shell-shaped one. Check the registry for the current version:
+# Claude Code:  RUN npm install -g @anthropic-ai/claude-code@<version>
+# Codex:        RUN npm install -g @openai/codex@<version>
 
 # Consumer install command, kept as an ARG so it lands in the image metadata
 # and can be inspected with `docker image inspect`. The engine re-runs the
@@ -42,13 +132,32 @@ RUN npm install -g {{CLI_BIN}}@${PHOEBE_VERSION}
 ARG PHOEBE_INSTALL_COMMAND="{{INSTALL_COMMAND}}"
 LABEL phoebe.install-command="${PHOEBE_INSTALL_COMMAND}"
 
-COPY supervisor.sh /usr/local/bin/phoebe-supervisor
-RUN chmod +x /usr/local/bin/phoebe-supervisor
+# Execution-gate marker: the engine refuses to mutate a clone, launch an agent,
+# or push unless `/.phoebe-container` exists (src/execution-gate.ts). Without it
+# the container refuses every non-dry-run unit. Root-owned and read-only to us
+# on purpose — the gate is only ever tested for existence, never written.
+RUN touch /.phoebe-container
+
+# The privilege drop. Everything past this line — `boot`, the engine, the agent
+# child, and your repo's install/check/test commands — runs unprivileged.
+#
+# Two things this constrains:
+#   * Anything the workload writes must be under /data (the volumes above) or
+#     $HOME. That covers the package manager and provider CLI caches, which is
+#     why HOME is set explicitly rather than left to the runtime: the engine
+#     forwards HOME to the agent child, and an unwritable one breaks the
+#     provider CLI in ways that surface as unrelated errors.
+#   * Files you bind-mount in (phoebe.config.ts, prompts/) must be readable by
+#     *other* — the default 0644 from a git checkout is, but a 0600 file is not
+#     and boot will fail to read its config.
+ENV HOME=/home/phoebe
+USER phoebe
 
 # Compose's `command:` fully replaces `CMD` (it does not append to
-# `ENTRYPOINT`), so the supervisor path must live in `ENTRYPOINT` — otherwise
-# compose.yml's `command: ["--run-once"]` (or the daemon overlay's `command: []`)
-# strips the supervisor away and tini exits with no child to exec. Keeping
-# `CMD []` here means the compose files only ever contribute engine flags.
-ENTRYPOINT ["/usr/bin/tini", "--", "/usr/local/bin/phoebe-supervisor"]
+# `ENTRYPOINT`), so the whole `phoebe boot` invocation must live in
+# `ENTRYPOINT` — otherwise a compose `command: ["--run-once"]` would strip the
+# bootstrapper away and tini would try to exec `--run-once` as a program.
+# Keeping `CMD []` here means the compose files only ever contribute engine
+# flags, which `boot` forwards to the engine it launches.
+ENTRYPOINT ["/usr/bin/tini", "--", "phoebe", "boot"]
 CMD []

package/templates/container/compose.local.yml

@@ -0,0 +1,37 @@
+# Local-engine overlay — scaffolded by `phoebe init`, consumer-owned.
+#
+# Development only. Instead of `boot` checking the engine out from GitHub, this
+# runs it straight from a checkout on your host, so an edit to the engine source
+# takes effect on the next launch with no rebuild and no push:
+#
+#   PHOEBE_ENGINE_MOUNT=/path/to/phoebe \
+#     docker compose -f compose.yml -f compose.local.yml run --rm phoebe
+#
+# It only takes effect if the mounted phoebe.config.ts also says so:
+#
+#   engine: { source: "local" }
+#
+# `boot` fails loudly when that field says "local" and nothing is mounted at
+# /opt/phoebe-engine — a missing mount is a misconfigured container, not a
+# reason to quietly fall back to GitHub.
+#
+# Two behaviours differ from the deployed topology, both by design:
+#   * No crash-loop fallback. It guards a moving github ref by pinning back to
+#     the last engine commit that ran healthily; a mount has no commit to pin,
+#     so a crashing engine here just exits.
+#   * The ref watch is inert — there is no remote to poll. `boot` still watches
+#     the config, so a config edit relaunches the engine as usual.
+
+services:
+  phoebe:
+    environment:
+      # A minute is a long time to wait when you are iterating; the reconcile
+      # poll is one stat plus (for a github source) one ls-remote, so a tight
+      # interval is cheap here.
+      PHOEBE_RECONCILE_INTERVAL_MS: "${PHOEBE_RECONCILE_INTERVAL_MS:-10000}"
+    volumes:
+      # The engine source `boot` execs for `engine: { source: "local" }`.
+      # Read-only: the engine works its target clone under /data, never its own
+      # source. Mount the repo *root* — package.json's `"type": "module"` has to
+      # sit alongside the `.ts` the engine runs under Node's type-stripping.
+      - "${PHOEBE_ENGINE_MOUNT:?PHOEBE_ENGINE_MOUNT must point at a local engine checkout}:/opt/phoebe-engine:ro"

package/templates/container/compose.yml

@@ -1,41 +1,70 @@
 # Phoebe compose file — scaffolded by `phoebe init`, consumer-owned.
 #
-# Base configuration: builds the runtime image, mounts the three named volumes
-# the engine expects (`/data/repo`, `/data/worktrees`, `/data/state`), and
-# runs the CLI once with `--run-once`. For the persistent daemon topology,
-# stack the daemon overlay:
+# One long-lived container. Its main process is `phoebe boot` (pinned into the
+# image's ENTRYPOINT), which materializes the engine named by `engine` in
+# phoebe.config.ts, runs it, and keeps supervising it for the life of the
+# container — so this file describes a daemon, not a one-shot:
 #
-#   docker compose -f compose.yml -f compose.daemon.yml up -d
+#   docker compose up -d          # run it
+#   docker compose logs -f        # watch it
+#   docker compose stop           # SIGTERM → the engine drains, finishing its
+#                                 # current work unit and starting no new one
 #
-# The image ships a pinned {{CLI_BIN}} — bump PHOEBE_VERSION here (not in the
-# Dockerfile) to upgrade the engine.
+# For a scoped, non-daemon invocation, pass engine flags — the image's `CMD []`
+# means anything here is forwarded straight through `boot` to the engine:
+#
+#   docker compose run --rm phoebe --dry-run --run-once   # selection preview
+#   docker compose run --rm phoebe --run-once             # work exactly one unit
+#
+# To upgrade the engine, edit `engine.ref` in phoebe.config.ts — `boot` notices
+# within a poll interval and relaunches at the next work-unit boundary. No
+# rebuild and no restart; rebuild only when this image's toolchain changes.
+
+# Project name — namespaces this instance's containers and named volumes. It
+# defaults to `phoebe`, but if you run Phoebe for more than one repo on the same
+# host you MUST make it unique per repo (set COMPOSE_PROJECT_NAME in `.env`).
+# Compose otherwise derives the project from this file's parent directory —
+# `container` — which is identical for every consumer, so the "private"
+# /data/repo, /data/state, … volumes would be shared across repos. Set it and
+# each repo gets its own `phoebe-<repo>_phoebe-repo` volume set.
+name: ${COMPOSE_PROJECT_NAME:-phoebe}
 
 services:
   phoebe:
     build:
       context: .
       args:
-        PHOEBE_VERSION: "${PHOEBE_VERSION:-latest}"
         PHOEBE_INSTALL_COMMAND: "{{INSTALL_COMMAND}}"
-    image: phoebe-runtime:${PHOEBE_VERSION:-latest}
-    command: ["--run-once"]
+    image: phoebe-runtime:latest
+    restart: unless-stopped
     environment:
-      PHOEBE_VERSION: "${PHOEBE_VERSION:-latest}"
-      # Secrets — populate via `.env` (see `.env.example`).
+      # Secrets — populate via `.env` (see `.env.example`). GH_TOKEN also
+      # authenticates the engine checkout when `engine.source` is "github".
       GH_TOKEN: "${GH_TOKEN:?GH_TOKEN is required}"
       ANTHROPIC_API_KEY: "${ANTHROPIC_API_KEY:-}"
       CURSOR_API_KEY: "${CURSOR_API_KEY:-}"
       OPENAI_KEY: "${OPENAI_KEY:-}"
+      # Where `boot` keeps engine checkouts. Pointed at a named volume below so
+      # a restart fetches into an existing clone instead of cloning again.
+      PHOEBE_ENGINE_DIR: /data/engine
       # Optional runtime toggles.
       PHOEBE_AGENT: "${PHOEBE_AGENT:-}"
       PHOEBE_MODEL: "${PHOEBE_MODEL:-}"
       PHOEBE_POLL_INTERVAL_MS: "${PHOEBE_POLL_INTERVAL_MS:-}"
+      PHOEBE_RECONCILE_INTERVAL_MS: "${PHOEBE_RECONCILE_INTERVAL_MS:-}"
     volumes:
       - phoebe-repo:/data/repo
       - phoebe-worktrees:/data/worktrees
       - phoebe-state:/data/state
+      - phoebe-engine:/data/engine
       # Consumer config + prompt overrides live in-repo; mount them read-only
-      # so a `docker compose restart` picks up edits without a rebuild.
+      # so `boot` can re-read the config without a rebuild.
+      #
+      # Caveat worth knowing: a single-file bind mount pins the host *inode*, so
+      # a save that writes a new file and renames it over the old one — most
+      # editors' atomic save, and what `git pull` does — is invisible in here,
+      # and `boot`'s config watch will never fire for it. Either edit in place,
+      # or follow the write with `docker compose up -d --force-recreate`.
       - ../phoebe.config.ts:/etc/phoebe/phoebe.config.ts:ro
       - ../prompts:/etc/phoebe/prompts:ro
     working_dir: /etc/phoebe
@@ -44,3 +73,4 @@ volumes:
   phoebe-repo:
   phoebe-worktrees:
   phoebe-state:
+  phoebe-engine:

package/templates/phoebe.config.ts

@@ -1,15 +1,39 @@
 // Phoebe consumer config — scaffolded by `phoebe init`.
 //
-// Only these five fields are required. Everything else has a shipped default
-// (see the `PhoebeUserConfig` type). Add overrides here only when you need
-// them; `phoebe-agent` upgrades pick up new defaults automatically.
+// Only the five fields at the top are required. Everything else has a shipped
+// default (see the `PhoebeUserConfig` type); add overrides here only when you
+// need them, and engine upgrades pick up new defaults automatically.
+//
+// This is a *type-only* import on purpose. The container mounts this file at
+// /etc/phoebe and `phoebe boot` imports it before the engine exists, from a
+// directory with no reachable `node_modules` — a value import of `{{CLI_BIN}}`
+// (the `defineConfig` helper) could not resolve there under ESM. A type-only
+// import is erased at runtime, so it type-checks in your editor and costs
+// nothing in the container.
 
-import { defineConfig } from "{{CLI_BIN}}";
+import type { PhoebeUserConfig } from "{{CLI_BIN}}";
 
-export default defineConfig({
+const config: PhoebeUserConfig = {
   repoSlug: "your-org/your-repo",
   repoUrl: "https://github.com/your-org/your-repo.git",
   installCommand: "{{INSTALL_COMMAND}}",
   checkCommand: "npm run check",
   testCommand: "npm test",
-});
+
+  // Which engine `phoebe boot` runs. This is the upgrade knob: edit it and the
+  // running container drains the engine and relaunches on the new code at the
+  // next work-unit boundary — no rebuild, no restart.
+  //
+  //   ref: "main"      follow the tip — every push lands here. Guarded: a
+  //                    commit that will not boot is quarantined after a few
+  //                    fast crashes and `boot` pins back to the last one that
+  //                    ran healthily, until the branch moves past it.
+  //   ref: "v1.2.3"    pin a tag (or a full SHA). Exactly this commit, always.
+  //                    No fallback — pinning means pinning.
+  //
+  // `repo` defaults to the upstream engine repo; set it to run a fork.
+  // For a checkout on your own machine, see container/compose.local.yml.
+  engine: { source: "github", ref: "main" },
+};
+
+export default config;

package/dist/phoebe.config.d.ts

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

package/dist/phoebe.config.js

@@ -1,43 +0,0 @@
-// 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

@@ -1,6 +0,0 @@
-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

@@ -1,24 +0,0 @@
-// 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

@@ -1,25 +0,0 @@
-#!/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

@@ -1,161 +0,0 @@
-#!/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);
-    });
-}