phoebe-agent 0.0.0 → 0.1.0

package/src/prompt.ts

@@ -0,0 +1,98 @@
+// Prompt template rendering: {{KEY}} argument substitution plus !`command`
+// shell expansion, executed in the work unit's worktree. The marker trick is
+// ported from Sandcastle's PromptPreprocessor: shell blocks present in the raw
+// template are marked *before* argument substitution, so `!`...`` patterns
+// arriving via substituted values are treated as data, never executed.
+//
+// Prompt file paths (`config.promptFiles.*`) resolve against the runtime root
+// (process cwd) — the consumer checkout on the host, `/etc/phoebe` in the
+// container where compose mounts `phoebe.config.ts` and `prompts/`. They do
+// not walk the installed package; `phoebe init` copies shipped prompts into
+// the runtime root for that reason.
+
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import type { PhoebeConfig } from "./config-schema.ts";
+
+export type PromptArgs = Record<string, string>;
+
+/**
+ * Resolve a `promptFiles.*` path against the runtime root. Absolute paths are
+ * used as-is; relative paths join to `runtimeRoot`. Throws when the file is
+ * missing — never falls back into the installed package tree.
+ */
+export function resolvePromptFile(promptPath: string, runtimeRoot: string): string {
+  const absolute = isAbsolute(promptPath) ? promptPath : resolve(runtimeRoot, promptPath);
+  if (!existsSync(absolute)) {
+    throw new Error(
+      `Could not find prompt file ${promptPath} (resolved to ${absolute} from runtime root ${runtimeRoot})`,
+    );
+  }
+  return absolute;
+}
+
+/** Read a prompt template from a path relative to (or absolute under) the runtime root. */
+export function loadPromptTemplate(promptPath: string, runtimeRoot: string): string {
+  return readFileSync(resolvePromptFile(promptPath, runtimeRoot), "utf8");
+}
+
+/**
+ * The standard placeholder set every default prompt template can reference —
+ * derived once per run from the resolved config so callers can retarget the
+ * toolchain by editing `phoebe.config.ts` alone. Per-callsite args
+ * (`ISSUE_NUMBER`, `PR_NUMBER`, …) are merged on top by `runAgentInWorktree`.
+ */
+export function buildDefaultPromptArgs(config: PhoebeConfig): PromptArgs {
+  return {
+    INSTALL_COMMAND: config.installCommand,
+    CHECK_COMMAND: config.checkCommand,
+    TEST_COMMAND: config.testCommand,
+    READY_COMMAND: config.readyCommand,
+    DEFAULT_BRANCH: config.defaultBranch,
+    BRANCH_PREFIX: config.branchPrefix,
+    READY_LABEL: config.readyLabel,
+    RESEARCH_LABEL: config.researchLabel,
+    PROCESSING_LABEL: config.processingLabel,
+    REVIEWS_SUCCESS_HEADING: config.reviewsSuccessHeading,
+  };
+}
+
+/**
+ * Marker inserted between `!` and the opening backtick for shell blocks that
+ * appear in the raw template. Only marked blocks are executed.
+ */
+const SHELL_BLOCK_MARKER = "\x01";
+
+const SHELL_BLOCK_PATTERN = /!`([^`]+)`/g;
+const MARKED_SHELL_BLOCK_PATTERN = new RegExp(`!${SHELL_BLOCK_MARKER}\`([^\`]+)\``, "g");
+const PLACEHOLDER_PATTERN = /\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
+
+export function substitutePromptArgs(template: string, args: PromptArgs): string {
+  const marked = template.replace(SHELL_BLOCK_PATTERN, (_m, cmd: string) => {
+    return `!${SHELL_BLOCK_MARKER}\`${cmd}\``;
+  });
+  return marked.replace(PLACEHOLDER_PATTERN, (match, key: string) => {
+    const value = args[key];
+    if (value === undefined) {
+      throw new Error(`Prompt placeholder {{${key}}} has no value.`);
+    }
+    return value;
+  });
+}
+
+/** Execute marked shell blocks and splice their trimmed stdout into the prompt. */
+export function expandShellBlocks(prompt: string, execShell: (command: string) => string): string {
+  return prompt
+    .replace(MARKED_SHELL_BLOCK_PATTERN, (_m, command: string) => {
+      return execShell(command).trimEnd();
+    })
+    .replaceAll(SHELL_BLOCK_MARKER, "");
+}
+
+export function renderPrompt(
+  template: string,
+  args: PromptArgs,
+  execShell: (command: string) => string,
+): string {
+  return expandShellBlocks(substitutePromptArgs(template, args), execShell);
+}

package/src/providers/providers.ts

@@ -0,0 +1,222 @@
+// The three agent CLIs Phoebe can drive. Invocation flags and stream-JSON
+// schemas were authored from Sandcastle 0.8.0's AgentProvider.ts (the
+// `@ai-hero/sandcastle` package sources) and carry its field-level
+// knowledge of each CLI's output format.
+
+import type { AgentCommand, AgentEvent, Provider } from "./types.ts";
+import type { ProviderName } from "../config-schema.ts";
+
+/** Maps allowlisted tool names to the input field carrying the display arg. */
+const TOOL_ARG_FIELDS: Record<string, string> = {
+  Bash: "command",
+  WebSearch: "query",
+  WebFetch: "url",
+  Agent: "description",
+};
+
+/**
+ * Claude Code and Cursor share the Claude stream-json line schema:
+ * `assistant` messages with text/tool_use content blocks, plus a terminal
+ * `result` event.
+ */
+const parseClaudeStreamLine = (line: string): AgentEvent[] => {
+  if (!line.startsWith("{")) return [];
+  try {
+    const obj = JSON.parse(line) as Record<string, unknown>;
+    const message = obj["message"] as { content?: unknown } | undefined;
+    if (obj["type"] === "assistant" && Array.isArray(message?.content)) {
+      const events: AgentEvent[] = [];
+      const texts: string[] = [];
+      for (const block of message.content as Array<{
+        type: string;
+        text?: string;
+        name?: string;
+        input?: Record<string, unknown>;
+      }>) {
+        if (block.type === "text" && typeof block.text === "string") {
+          texts.push(block.text);
+        } else if (
+          block.type === "tool_use" &&
+          typeof block.name === "string" &&
+          block.input !== undefined
+        ) {
+          const argField = TOOL_ARG_FIELDS[block.name];
+          if (argField === undefined) continue;
+          const argValue = block.input[argField];
+          if (typeof argValue !== "string") continue;
+          if (texts.length > 0) {
+            events.push({ type: "text", text: texts.join("") });
+            texts.length = 0;
+          }
+          events.push({ type: "tool_call", name: block.name, args: argValue });
+        }
+      }
+      if (texts.length > 0) {
+        events.push({ type: "text", text: texts.join("") });
+      }
+      return events;
+    }
+    if (obj["type"] === "result" && typeof obj["result"] === "string") {
+      return [{ type: "result", result: obj["result"] }];
+    }
+  } catch {
+    // Not valid JSON — skip.
+  }
+  return [];
+};
+
+/** Cursor additionally emits top-level `tool_call` events with per-tool shapes. */
+const parseCursorStreamLine = (line: string): AgentEvent[] => {
+  if (!line.startsWith("{")) return [];
+  let obj: Record<string, unknown>;
+  try {
+    obj = JSON.parse(line) as Record<string, unknown>;
+  } catch {
+    return [];
+  }
+  if (obj["type"] !== "tool_call" || obj["subtype"] !== "started") {
+    return parseClaudeStreamLine(line);
+  }
+  const toolCall = obj["tool_call"];
+  if (!toolCall || typeof toolCall !== "object") return [];
+  const tc = toolCall as Record<string, unknown>;
+
+  const readToolCall = tc["readToolCall"] as { args?: { path?: unknown } } | undefined;
+  if (readToolCall?.args && typeof readToolCall.args.path === "string") {
+    return [{ type: "tool_call", name: "Read", args: readToolCall.args.path }];
+  }
+  const writeToolCall = tc["writeToolCall"] as { args?: { path?: unknown } } | undefined;
+  if (writeToolCall?.args && typeof writeToolCall.args.path === "string") {
+    return [{ type: "tool_call", name: "Write", args: writeToolCall.args.path }];
+  }
+  const fn = tc["function"] as { name?: unknown; arguments?: unknown } | undefined;
+  if (fn && typeof fn.name === "string") {
+    const rawArgs = typeof fn.arguments === "string" ? fn.arguments : "";
+    if (rawArgs) {
+      try {
+        const parsedArgs = JSON.parse(rawArgs) as Record<string, unknown>;
+        if (typeof parsedArgs["command"] === "string") {
+          return [{ type: "tool_call", name: "Bash", args: parsedArgs["command"] }];
+        }
+      } catch {
+        // Fall through to the raw arguments string.
+      }
+      return [{ type: "tool_call", name: fn.name, args: rawArgs }];
+    }
+    return [{ type: "tool_call", name: fn.name, args: "" }];
+  }
+  return [];
+};
+
+const extractErrorMessage = (obj: Record<string, unknown>): string | undefined => {
+  const err = obj["error"];
+  if (typeof err === "string") return err;
+  if (typeof err === "object" && err !== null) {
+    const e = err as { message?: unknown; data?: { message?: unknown } };
+    if (typeof e.message === "string") return e.message;
+    if (typeof e.data?.message === "string") return e.data.message;
+  }
+  if (typeof obj["message"] === "string") return obj["message"];
+  return undefined;
+};
+
+/** Codex `exec --json` emits item/turn events rather than message blocks. */
+const parseCodexStreamLine = (line: string): AgentEvent[] => {
+  if (!line.startsWith("{")) return [];
+  try {
+    const obj = JSON.parse(line) as Record<string, unknown>;
+    const item = obj["item"] as { type?: string; text?: unknown; command?: unknown } | undefined;
+    if (
+      obj["type"] === "item.completed" &&
+      item?.type === "agent_message" &&
+      typeof item.text === "string"
+    ) {
+      return [
+        { type: "text", text: item.text },
+        { type: "result", result: item.text },
+      ];
+    }
+    if (
+      obj["type"] === "item.started" &&
+      item?.type === "command_execution" &&
+      typeof item.command === "string"
+    ) {
+      return [{ type: "tool_call", name: "Bash", args: item.command }];
+    }
+    // Codex reports auth/rate-limit/API errors on stdout, not stderr.
+    if (obj["type"] === "error") {
+      const msg = extractErrorMessage(obj);
+      return msg ? [{ type: "result", result: msg }] : [];
+    }
+  } catch {
+    // Not valid JSON — skip.
+  }
+  return [];
+};
+
+/**
+ * The Cursor CLI takes the prompt as a positional argv argument (stdin is not
+ * documented for prompt delivery). Linux caps a single argument at ~128 KiB;
+ * stay under it so users get a clear error instead of spawn E2BIG.
+ */
+const CURSOR_PROMPT_MAX_BYTES = 120 * 1024;
+
+const cursor: Provider = {
+  name: "cursor",
+  buildCommand({ prompt, model }): AgentCommand {
+    const bytes = Buffer.byteLength(prompt, "utf8");
+    if (bytes > CURSOR_PROMPT_MAX_BYTES) {
+      throw new Error(
+        `Cursor prompt is ${bytes} bytes (max ${CURSOR_PROMPT_MAX_BYTES}). The Cursor CLI only accepts the prompt as an argv argument; shorten the prompt or use another provider.`,
+      );
+    }
+    return {
+      argv: [
+        "agent",
+        "--print",
+        "--output-format",
+        "stream-json",
+        "--model",
+        model,
+        "--force",
+        prompt,
+      ],
+    };
+  },
+  parseStreamLine: parseCursorStreamLine,
+};
+
+const claude: Provider = {
+  name: "claude",
+  buildCommand({ prompt, model }): AgentCommand {
+    return {
+      argv: [
+        "claude",
+        "--print",
+        "--verbose",
+        "--dangerously-skip-permissions",
+        "--output-format",
+        "stream-json",
+        "--model",
+        model,
+        "-p",
+        "-",
+      ],
+      stdin: prompt,
+    };
+  },
+  parseStreamLine: parseClaudeStreamLine,
+};
+
+const codex: Provider = {
+  name: "codex",
+  buildCommand({ prompt, model }): AgentCommand {
+    return {
+      argv: ["codex", "exec", "--json", "--dangerously-bypass-approvals-and-sandbox", "-m", model],
+      stdin: prompt,
+    };
+  },
+  parseStreamLine: parseCodexStreamLine,
+};
+
+export const PROVIDERS: Record<ProviderName, Provider> = { cursor, claude, codex };

package/src/providers/run-agent.ts

@@ -0,0 +1,90 @@
+// Spawn an agent CLI for one work unit and stream its output. The child's
+// argv/stdin come from the provider; the env is the caller-built allowlist
+// (see ../agent-env.ts) — never the orchestrator's full process.env.
+
+import { spawn as nodeSpawn } from "node:child_process";
+import type { Provider } from "./types.ts";
+
+export type AgentRunResult = {
+  exitCode: number;
+  /** Last `result` event the provider emitted, if any. */
+  resultText: string;
+};
+
+/** Minimal child-process surface so tests can inject a fake spawn. */
+export type AgentChild = {
+  stdout: { on(event: "data", listener: (chunk: Buffer | string) => void): unknown };
+  stderr: { on(event: "data", listener: (chunk: Buffer | string) => void): unknown };
+  stdin: { write(data: string): unknown; end(): unknown };
+  on(event: "error", listener: (err: Error) => void): unknown;
+  on(event: "close", listener: (code: number | null) => void): unknown;
+};
+
+export type SpawnAgent = (
+  file: string,
+  args: readonly string[],
+  opts: { cwd: string; env: Record<string, string> },
+) => AgentChild;
+
+const defaultSpawn: SpawnAgent = (file, args, opts) =>
+  nodeSpawn(file, args, { ...opts, stdio: ["pipe", "pipe", "pipe"] });
+
+export async function runAgent(opts: {
+  provider: Provider;
+  model: string;
+  prompt: string;
+  cwd: string;
+  env: Record<string, string>;
+  spawn?: SpawnAgent;
+  log?: (line: string) => void;
+}): Promise<AgentRunResult> {
+  const { provider, model, prompt, cwd, env } = opts;
+  const spawn = opts.spawn ?? defaultSpawn;
+  const log = opts.log ?? ((line: string) => console.log(line));
+
+  const command = provider.buildCommand({ prompt, model });
+  const [file, ...args] = command.argv;
+  if (!file) {
+    throw new Error(`Provider "${provider.name}" built an empty command.`);
+  }
+
+  return new Promise<AgentRunResult>((resolve, reject) => {
+    const child = spawn(file, args, { cwd, env });
+    let resultText = "";
+    let stdoutBuffer = "";
+
+    const handleLine = (line: string): void => {
+      for (const event of provider.parseStreamLine(line)) {
+        if (event.type === "text") {
+          const text = event.text.trim();
+          if (text) log(`[${provider.name}] ${text}`);
+        } else if (event.type === "tool_call") {
+          log(`[${provider.name}] ${event.name}: ${event.args}`);
+        } else {
+          resultText = event.result;
+        }
+      }
+    };
+
+    child.stdout.on("data", (chunk) => {
+      stdoutBuffer += chunk.toString();
+      const lines = stdoutBuffer.split("\n");
+      stdoutBuffer = lines.pop() ?? "";
+      for (const line of lines) handleLine(line);
+    });
+    child.stderr.on("data", (chunk) => {
+      const text = chunk.toString().trim();
+      if (text) log(`[${provider.name}:stderr] ${text}`);
+    });
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (stdoutBuffer) handleLine(stdoutBuffer);
+      resolve({ exitCode: code ?? 1, resultText });
+    });
+
+    if (command.stdin !== undefined) {
+      child.stdin.write(command.stdin);
+    }
+    child.stdin.end();
+  });
+}

package/src/providers/types.ts

@@ -0,0 +1,26 @@
+// Agent provider contract — how Phoebe invokes a coding-agent CLI and reads
+// its output stream. Ported from Sandcastle's AgentProvider design (Matt
+// Pocock, https://github.com/mattpocock/sandcastle — the design ancestor of
+// this engine), trimmed to what Phoebe uses: one print-mode run per work unit,
+// no session capture, no interactive mode.
+
+import type { ProviderName } from "../config-schema.ts";
+
+/** A ready-to-spawn CLI invocation. `argv[0]` is the binary; no shell involved. */
+export type AgentCommand = {
+  readonly argv: readonly string[];
+  /** When set, piped to the child's stdin (large prompts don't fit argv). */
+  readonly stdin?: string;
+};
+
+/** Events parsed from one line of the agent's JSONL output stream. */
+export type AgentEvent =
+  | { type: "text"; text: string }
+  | { type: "result"; result: string }
+  | { type: "tool_call"; name: string; args: string };
+
+export type Provider = {
+  readonly name: ProviderName;
+  buildCommand(opts: { prompt: string; model: string }): AgentCommand;
+  parseStreamLine(line: string): AgentEvent[];
+};

package/src/resolved-config.ts

@@ -0,0 +1,55 @@
+// Runtime handle to the resolved, defaults-filled config the engine reads.
+//
+// The engine (everything else under src/) imports `config` from here and stays
+// repo-agnostic; the CLI (src/cli.ts) loads the consumer's `phoebe.config.ts`,
+// applies the `PHOEBE_*` env overlay, resolves defaults, and installs the
+// result via `setResolvedConfig` before importing the engine entry point.
+// Tests install a sample config via the setup file wired in `vite.config.ts`.
+//
+// A `Proxy` gates every field read: reading before install throws with a
+// pointer at the CLI/setup path, so an accidentally repo-coupled engine import
+// fails loudly at the callsite instead of silently reading `undefined`.
+
+import type { PhoebeConfig } from "./config-schema.ts";
+
+let resolved: PhoebeConfig | null = null;
+
+/** Install the resolved config. Idempotent — later calls replace the prior value. */
+export function setResolvedConfig(next: PhoebeConfig): void {
+  resolved = next;
+}
+
+/** For test isolation: clear the installed config back to the "not installed" state. */
+export function clearResolvedConfig(): void {
+  resolved = null;
+}
+
+/** Whether a resolved config has been installed. */
+export function hasResolvedConfig(): boolean {
+  return resolved !== null;
+}
+
+export const config: PhoebeConfig = new Proxy({} as PhoebeConfig, {
+  get(_target, prop) {
+    if (resolved === null) {
+      throw new Error(
+        `Attempted to read config.${String(prop)} before the resolved config was installed. ` +
+          `The Phoebe CLI (src/cli.ts) installs it after loading phoebe.config.ts; ` +
+          `tests install a sample via src/test-setup.ts (wired from vite.config.ts).`,
+      );
+    }
+    return resolved[prop as keyof PhoebeConfig];
+  },
+  ownKeys() {
+    if (resolved === null) return [];
+    return Reflect.ownKeys(resolved);
+  },
+  getOwnPropertyDescriptor(_target, prop) {
+    if (resolved === null) return undefined;
+    return Reflect.getOwnPropertyDescriptor(resolved, prop);
+  },
+  has(_target, prop) {
+    if (resolved === null) return false;
+    return prop in resolved;
+  },
+});

package/templates/.env.example

@@ -1,8 +1,12 @@
 # Phoebe environment — scaffolded by `phoebe init`. Copy to `.env` and fill in.
 #
-# GH_TOKEN is required; every `gh` call in the engine reads it. The provider
-# key is required only for whichever agent you actually run — set the one that
-# matches your `defaultProvider` (or `PHOEBE_AGENT` at runtime).
+# GH_TOKEN is required; every `gh` call in the engine reads it, and `phoebe
+# boot` uses it to check the engine out from GitHub. The provider key is
+# required only for whichever agent you actually run — set the one that matches
+# your `defaultProvider` (or `PHOEBE_AGENT` at runtime).
+#
+# Which engine version runs is NOT set here: it is `engine.ref` in
+# phoebe.config.ts, which `boot` re-reads while the container runs.
 
 # --- Required ---
 GH_TOKEN=
@@ -16,6 +20,8 @@ OPENAI_KEY=
 # PHOEBE_AGENT=claude
 # PHOEBE_MODEL=claude-sonnet-4-6
 # PHOEBE_POLL_INTERVAL_MS=300000
+# How often `boot` checks the config and the tracked engine ref (default 60000).
+# PHOEBE_RECONCILE_INTERVAL_MS=60000
 
-# --- Engine version pin (compose.yml reads this) ---
-PHOEBE_VERSION=latest
+# --- Local engine checkout (compose.local.yml only, development) ---
+# PHOEBE_ENGINE_MOUNT=/path/to/phoebe

package/templates/container/Dockerfile

@@ -1,20 +1,29 @@
 # 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.
 
-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 +39,21 @@ 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 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.
+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: its executable is
+# symlinked as `agent` into ~/.local/bin, which we add to PATH. Swap or add the
+# commented lines for the provider you actually run.
+RUN curl -fsSL https://cursor.com/install | bash
+ENV PATH="/root/.local/bin:${PATH}"
+# Claude Code:  RUN npm install -g @anthropic-ai/claude-code
+# Codex:        RUN npm install -g @openai/codex
 
 # 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 +61,16 @@ 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.
+RUN touch /.phoebe-container
 
 # 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"