phoebe-agent 0.1.0 → 0.1.1

package/bootstrap/boot.ts

@@ -22,6 +22,7 @@
 // the fallback policy in crash-loop.ts, and everything impure is passed in from
 // here.
 
+import { execFileSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -56,6 +57,48 @@ import { propagateExit, spawnEngine } from "./spawn-engine.mjs";
 /** Where the local-engine compose overlay mounts the engine for `source: "local"`. */
 export const LOCAL_ENGINE_DIR = "/opt/phoebe-engine";
 
+/**
+ * Runs `gh` with the given argv. Injectable so boot's credential-helper setup is
+ * unit-tested without a real `gh` binary or a writable `~/.gitconfig`.
+ */
+export type GhRunner = (args: readonly string[]) => void;
+
+export const defaultGh: GhRunner = (args) => {
+  execFileSync("gh", args, { stdio: "inherit" });
+};
+
+/**
+ * Configure a global git credential helper from `GH_TOKEN` so every later git
+ * call against github.com authenticates — the engine's `ensureClone` /
+ * `fetchOrigin` / `pushBranch`, and the agent child's own `git push`/`fetch`.
+ *
+ * Uses `gh auth setup-git --hostname github.com`, which writes a
+ * `!gh auth git-credential` helper into `~/.gitconfig`. That helper reads
+ * `GH_TOKEN` live per call, so no secret is written to disk and token rotation
+ * keeps working. Only `github.com` is configured (Phoebe is github-only).
+ *
+ * Skipped when no token is present (public/anonymous path unchanged). A failed
+ * setup warns and continues — a missing helper is better diagnosed at the first
+ * private-repo clone than by aborting the container here.
+ */
+export function setupGitCredentials(deps: {
+  token: string | undefined;
+  gh?: GhRunner;
+  warn?: (message: string) => void;
+}): void {
+  if (!deps.token) return;
+  const gh = deps.gh ?? defaultGh;
+  const warn = deps.warn ?? ((message) => console.warn(message));
+  try {
+    gh(["auth", "setup-git", "--hostname", "github.com"]);
+  } catch (error) {
+    warn(
+      `[phoebe] boot: could not configure git credentials — ${describe(error)}. ` +
+        `Continuing without a credential helper.`,
+    );
+  }
+}
+
 /**
  * Resolve a `local` engine source to the mounted engine's `src/cli.ts`, failing
  * loudly if it is absent — a missing/empty mount means a misconfigured
@@ -322,6 +365,11 @@ function runOutcome(run: EngineRun): RunOutcome | null {
  * persistent loop).
  */
 export async function runBoot(argv: readonly string[]): Promise<void> {
+  // Before any engine git call (ensureClone, fetch/push, agent child): one
+  // global github.com credential helper from GH_TOKEN. Survives reconcile
+  // relaunches via ~/.gitconfig + the agent-env HOME/GH_TOKEN allowlist.
+  setupGitCredentials({ token: process.env["GH_TOKEN"] });
+
   const configPath = resolveConfigPath(undefined, process.cwd());
   const guard = await createBootCrashGuard(configPath);
   const intervalMs = reconcileIntervalMs();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phoebe-agent",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": false,
   "description": "Phoebe — an AFK coding agent: a configurable engine that works a GitHub issue tracker one ticket at a time, distributed as a pinned CLI.",
   "homepage": "https://github.com/JesusFilm/phoebe#readme",

package/src/git-model.ts

@@ -23,12 +23,44 @@ export const defaultGit: GitRunner = (args, opts) =>
     ...(opts?.timeout ? { timeout: opts.timeout } : {}),
   }) as unknown as string;
 
-/** Clone the repo into `repoDir` unless a clone already exists there. */
+/**
+ * Clone the repo into `repoDir` unless a clone already exists there.
+ *
+ * An existing clone is only adopted if its `origin` actually points at
+ * `repoUrl`. A `/data/repo` volume is supposed to be this instance's private
+ * clone, but two Phoebe instances on one host can end up sharing it (a compose
+ * project-name collision namespaces the "private" volumes identically). Adopting
+ * a foreign clone by mere presence of `.git` would silently run every worktree,
+ * branch, and push against the wrong repo while `gh` calls still used this
+ * instance's `repoSlug` — reading one repo's issues and doing the work on
+ * another's tree. So a mismatch fails loudly instead: isolate the instances (see
+ * `COMPOSE_PROJECT_NAME`) or wipe the shared volume.
+ */
 export function ensureClone(
   opts: { repoUrl: string; repoDir: string },
   git: GitRunner = defaultGit,
 ): void {
-  if (existsSync(join(opts.repoDir, ".git"))) return;
+  if (existsSync(join(opts.repoDir, ".git"))) {
+    // `git config --get` exits non-zero when the key is unset, which `defaultGit`
+    // surfaces as a throw. An unreadable origin is not the configured `repoUrl`,
+    // so treat it as an absent origin and fall through to the refusal below —
+    // reaching the explicit `<none>` message rather than a raw `Command failed`.
+    let origin = "";
+    try {
+      origin = git(["config", "--get", "remote.origin.url"], { cwd: opts.repoDir }).trim();
+    } catch {
+      origin = "";
+    }
+    if (origin !== opts.repoUrl) {
+      throw new Error(
+        `Existing clone at ${opts.repoDir} has origin \`${origin || "<none>"}\`, but this ` +
+          `Phoebe is configured for \`${opts.repoUrl}\`. Refusing to work a foreign clone — the ` +
+          `state volume is shared with another instance. Give each instance a distinct compose ` +
+          `project (COMPOSE_PROJECT_NAME), or wipe this volume, then retry.`,
+      );
+    }
+    return;
+  }
   mkdirSync(opts.repoDir, { recursive: true });
   git(["clone", opts.repoUrl, opts.repoDir], { stdio: "inherit" });
 }

package/templates/.env.example

@@ -16,6 +16,12 @@ ANTHROPIC_API_KEY=
 CURSOR_API_KEY=
 OPENAI_KEY=
 
+# --- One host, multiple repos (set this if so) ---
+# Namespaces this instance's containers and named volumes. REQUIRED to be unique
+# per repo when you run Phoebe for more than one repo on the same host —
+# otherwise every instance shares one /data/repo clone and works the wrong repo.
+# COMPOSE_PROJECT_NAME=phoebe-your-org-your-repo
+
 # --- Runtime toggles (optional) ---
 # PHOEBE_AGENT=claude
 # PHOEBE_MODEL=claude-sonnet-4-6

package/templates/container/Dockerfile

@@ -22,6 +22,9 @@
 #   * /data/worktrees  — Per-work-unit git worktrees.
 #   * /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:24-bookworm-slim
 
@@ -39,21 +42,89 @@ RUN apt-get update \
  && apt-get install -y --no-install-recommends gh \
  && rm -rf /var/lib/apt/lists/*
 
+# 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: its executable is
-# symlinked as `agent` into ~/.local/bin, which we add to PATH. Swap or add the
+# with `spawn <cli> ENOENT`. Default below installs Cursor. 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
+#
+# 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
@@ -63,9 +134,25 @@ LABEL phoebe.install-command="${PHOEBE_INSTALL_COMMAND}"
 
 # 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.
+# 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 whole `phoebe boot` invocation must live in
 # `ENTRYPOINT` — otherwise a compose `command: ["--run-once"]` would strip the

package/templates/container/compose.yml

@@ -20,6 +20,15 @@
 # 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: