phoebe-agent 0.0.0 → 0.1.0

package/bootstrap/index.ts

@@ -0,0 +1,24 @@
+// Type surface of the `phoebe-agent` bootstrapper package — the `types` entry.
+// The runtime entry is index.mjs (plain JS, because Node 24 won't type-strip the
+// installed package under node_modules); this file exists only to type a
+// consumer's config authoring:
+//
+// ```ts
+// import { defineConfig, type PhoebeUserConfig } from "phoebe-agent";
+// export default defineConfig({ repoSlug: "...", ... });
+// ```
+//
+// `defineConfig` is the identity typing helper; the config types are owned by
+// the engine's config schema. The engine-source reader (engine-source.ts) is the
+// bootstrapper's own internal concern — it is not part of the published surface
+// yet, so it is not re-exported here.
+
+export { defineConfig } from "./define-config.ts";
+export type {
+  EngineSourceField,
+  PhoebeConfig,
+  PhoebeUserConfig,
+  PathsConfig,
+  PromptFilesConfig,
+  ProviderName,
+} from "../src/config-schema.ts";

package/bootstrap/materialize.mjs

@@ -0,0 +1,53 @@
+// Copy the package out of node_modules so Node can run its raw `.ts`. Node 24
+// refuses to type-strip any file under a `node_modules` segment
+// (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING), and the installed package lives
+// exactly there. This is the one irreducible bit of the bootstrapper that must
+// be plain JS: it runs first, still inside node_modules, and its whole job is to
+// get the TypeScript bootstrapper (bootstrap/cli.ts) + engine (src/) to a
+// directory *outside* node_modules, where type-stripping is allowed. Everything
+// downstream — the bootstrapper and engine — is type-checked TypeScript.
+//
+// The bundled copy is the transitional engine source. Later tickets (#40/#41)
+// teach bootstrap/cli.ts to resolve the engine from a local mount / git ref; the
+// "run raw `.ts` from a dir outside node_modules" shape is what stays.
+
+import { cpSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+// Package subtrees to copy: the TypeScript bootstrapper + engine, plus the
+// scaffold resources `phoebe init` reads (init walks up from src/ to find them).
+const MATERIALIZED_PARTS = ["bootstrap", "src", "templates", "prompts"];
+
+/** Version-keyed materialization directory under `baseDir`. */
+export function engineDir(baseDir, version) {
+  return join(baseDir, `engine-${version}`);
+}
+
+/**
+ * Ensure a runnable copy of the package exists outside node_modules and return
+ * the path to the bootstrapper entry (`<dir>/bootstrap/cli.ts`). Idempotent: a
+ * version-keyed marker means repeated invocations (anything that runs the bin
+ * over and over) skip the copy after the first. Callers key `baseDir` per
+ * install and the package version changes on release, so a stale copy is never
+ * reused.
+ */
+export function ensureEngine({ packageRoot, baseDir, version }) {
+  const dir = engineDir(baseDir, version);
+  const marker = join(dir, ".materialized");
+  if (!existsSync(marker)) {
+    mkdirSync(dir, { recursive: true });
+    for (const part of MATERIALIZED_PARTS) {
+      const from = join(packageRoot, part);
+      if (existsSync(from)) {
+        cpSync(from, join(dir, part), { recursive: true });
+      }
+    }
+    // The copied `.ts` modules must load as ESM; the nearest package.json to
+    // `<dir>/bootstrap/cli.ts` is this one. A minimal `{"type":"module"}` is
+    // enough — nothing reads its own package fields at runtime.
+    writeFileSync(join(dir, "package.json"), '{\n  "type": "module"\n}\n');
+    // Write the marker last so a copy interrupted midway re-runs next time.
+    writeFileSync(marker, `${version}\n`);
+  }
+  return join(dir, "bootstrap", "cli.ts");
+}

package/bootstrap/reconcile.ts

@@ -0,0 +1,314 @@
+// The reconcile watch loop — `phoebe boot`'s supervision of the running engine.
+//
+// `boot` is the container's long-lived main process (#40): it resolves the
+// engine source and execs the engine as a long-running child. This module is
+// what it does for the rest of the container's life — poll the two things that
+// decide *which* engine should be running, and reconcile when they diverge:
+//
+//   - the mounted `phoebe.config.ts` (its `engine` field picks the source), and
+//   - the tip of the tracked branch, versus the commit the engine is running.
+//
+// On a change the engine is not killed: it is sent `SIGTERM`, which it treats as
+// a graceful drain (src/drain.ts) — finish the work unit in flight, start no new
+// one, exit 0. Only once it is gone does boot re-resolve the source (re-read the
+// config, fetch and check out the new ref) and spawn the replacement. So a
+// reconcile never interrupts a work unit and never restarts the container.
+//
+// A poll is deliberately cheap: one `stat` of the config plus at most one
+// `git ls-remote` (see bootstrap/github-engine.ts). No fetch, no checkout, and
+// no work at all when nothing moved.
+//
+// Following a branch means eventually following it onto a commit that does not
+// boot, so the loop also reports every finished run and asks whether a
+// self-exit is worth retrying. The policy behind those two hooks — count fast
+// crashes, pin back to the last-good commit — is bootstrap/crash-loop.ts; all
+// the loop knows is that a launch may be avoiding a quarantined commit, which
+// the ref-watch must then stop treating as a change.
+//
+// The loop takes everything impure as a dependency — launching, spawning, the
+// poll clock, the stop latch — so the drain-then-relaunch ordering is unit-tested
+// without processes or timers.
+
+import { statSync } from "node:fs";
+
+/** How often the watch samples the config and the tracked ref. */
+export const DEFAULT_RECONCILE_INTERVAL_MS = 60_000;
+
+/**
+ * How long boot waits before relaunching an engine that crashed. Long enough
+ * that a commit dying instantly cannot spin the loop, short enough that the
+ * crash-loop guard reaches its verdict in well under a minute. Deliberately not
+ * the poll interval: a consumer who slows their reconcile poll down to a
+ * quarter-hour should not thereby wait an hour for a fallback.
+ */
+export const CRASH_BACKOFF_MS = 10_000;
+
+/** Which of the two watched inputs moved, and so why the engine is relaunching. */
+export type ReconcileReason = "config" | "ref";
+
+/**
+ * A single sample of the watched world.
+ * - `config`: the mounted config's stat fingerprint; null when it cannot be read.
+ * - `remoteSha`: the tracked branch's current tip; null when there is nothing to
+ *   watch — a local mount, a pinned SHA/tag, or a ref the remote does not have.
+ */
+export type WatchState = {
+  config: string | null;
+  remoteSha: string | null;
+};
+
+/** A running engine, and the world it was launched from. */
+export type LaunchedEngine = {
+  /** The engine CLI path that was spawned. */
+  entry: string;
+  /** The commit it is running; null for a local mount (nothing to compare). */
+  sha: string | null;
+  /** The config fingerprint at launch. */
+  config: string | null;
+  /** Sample the watched inputs now, bound to the source this engine came from. */
+  sample: () => WatchState;
+  /**
+   * The crash-looping commit this launch is avoiding, when it is a crash-loop
+   * fallback (bootstrap/crash-loop.ts) — the tracked branch still points there,
+   * and the watch must not read that as a change to chase. Null normally.
+   */
+  quarantinedSha: string | null;
+  /**
+   * Whether the crash-loop guard covers this launch — true only for a github
+   * source tracking a moving branch. The loop only carries it through to the
+   * exit hooks; boot.ts is what decides with it.
+   */
+  guarded: boolean;
+};
+
+export type EngineExit = { code: number | null; signal: NodeJS.Signals | null };
+
+/** A finished engine run: what was running, how it ended, and how long it lived. */
+export type EngineRun = {
+  engine: LaunchedEngine;
+  exit: EngineExit;
+  elapsedMs: number;
+  /**
+   * Whether boot ended this run (a reconcile drain, or a container stop) rather
+   * than the engine exiting of its own accord — the difference between evidence
+   * about the engine commit and evidence about nothing.
+   */
+  requestedStop: boolean;
+};
+
+/** The supervised engine child: enough of a process to drain it and await it. */
+export type SupervisedChild = {
+  kill: (signal: NodeJS.Signals) => void;
+  exited: Promise<EngineExit>;
+};
+
+/**
+ * The outside stop request (container `SIGTERM`/`SIGINT`). A one-way latch whose
+ * `wait` doubles as the poll clock, so a shutdown wakes the loop immediately
+ * instead of sleeping out a whole poll interval — `installDrainSignal`
+ * (src/drain.ts) is exactly this shape.
+ */
+export type StopLatch = {
+  readonly requested: boolean;
+  wait: (ms: number) => Promise<void>;
+};
+
+export type SuperviseDeps = {
+  /** Re-read the config, resolve + materialize the engine source. */
+  launch: () => Promise<LaunchedEngine> | LaunchedEngine;
+  /** Spawn the engine as a long-running child. */
+  spawn: (entry: string) => SupervisedChild;
+  stop: StopLatch;
+  intervalMs?: number;
+  /** Reads the clock for run durations; injectable so the loop is tested without waiting. */
+  now?: () => number;
+  onRelaunch?: (reason: ReconcileReason) => void;
+  onLaunchError?: (error: unknown) => void;
+  onSampleError?: (error: unknown) => void;
+  /**
+   * Every finished run, however it ended — drained for a reconcile, stopped with
+   * the container, or crashed. The crash-loop guard's bookkeeping hook: this is
+   * where boot learns a commit ran healthily, or died on startup.
+   */
+  onRunEnd?: (run: EngineRun) => void;
+  /**
+   * Each poll tick, with how long the engine has been up. The guard's other half:
+   * it banks a commit as proven while it is still running, so an engine that has
+   * been up for weeks and is then killed outright still leaves a fallback target
+   * behind.
+   */
+  onRunTick?: (tick: { engine: LaunchedEngine; elapsedMs: number }) => void;
+  /**
+   * The engine exited on its own. True relaunches it — the crash-loop guard
+   * choosing to try again (possibly onto the last-good commit) rather than let a
+   * bad engine take the container down; false propagates the exit, which is the
+   * default and the only behaviour when no guard is wired.
+   */
+  relaunchAfterExit?: (run: EngineRun) => boolean;
+};
+
+/**
+ * A cheap identity for the mounted config: mtime plus size. A stat is all a
+ * no-change poll should cost, and any edit — in place or a replacing rename —
+ * moves the mtime. Unreadable (missing, mid-rewrite, mount blip) is null, which
+ * `detectChange` reads as "unknown", never as a change.
+ */
+export function configFingerprint(
+  path: string,
+  stat: (path: string) => { mtimeMs: number; size: number } = statSync,
+): string | null {
+  try {
+    const stats = stat(path);
+    return `${stats.mtimeMs}:${stats.size}`;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Is the running engine stale? Compares the live sample against what the engine
+ * was launched from — not against the previous sample — so the answer is always
+ * "is what's running still right", which survives a missed poll and cannot
+ * relaunch twice for the same change.
+ *
+ * Either side being null means "nothing to compare" and yields no relaunch: an
+ * unreadable config must not restart the engine, and a null `remoteSha` is how a
+ * local mount and a pinned SHA/tag report an inert ref-watch.
+ *
+ * One tip is deliberately ignored: the quarantined commit a crash-loop fallback
+ * is running away from (bootstrap/crash-loop.ts). While the branch still points
+ * there, "the running engine is not on the tip" is the intended state, not a
+ * change — reading it as one would relaunch straight back into the bad commit.
+ */
+export function detectChange(opts: {
+  launched: { config: string | null; sha: string | null; quarantinedSha?: string | null };
+  current: WatchState;
+}): ReconcileReason | null {
+  const { launched, current } = opts;
+  // Config first: re-reading it can change which ref is even tracked.
+  if (launched.config !== null && current.config !== null && current.config !== launched.config) {
+    return "config";
+  }
+  if (launched.sha !== null && current.remoteSha !== null && current.remoteSha !== launched.sha) {
+    return current.remoteSha === launched.quarantinedSha ? null : "ref";
+  }
+  return null;
+}
+
+type WatchOutcome =
+  | { kind: "exit"; exit: EngineExit }
+  | { kind: "change"; reason: ReconcileReason };
+
+/**
+ * Poll until the engine exits by itself, the container is stopping, or a watched
+ * input moves. Races the child's exit against the poll clock so neither a long
+ * poll interval nor a quiet engine delays the other.
+ */
+async function watchEngine(
+  engine: LaunchedEngine,
+  child: SupervisedChild,
+  deps: SuperviseDeps,
+  clock: { intervalMs: number; startedAt: number; now: () => number },
+): Promise<WatchOutcome> {
+  const { intervalMs } = clock;
+  // One reaction on the child's exit for the whole watch — re-deriving it each
+  // iteration would pile up handlers on a promise that outlives thousands of
+  // polls over a long-lived container.
+  const exitOutcome = child.exited.then((exit) => ({ kind: "exit" as const, exit }));
+  while (true) {
+    const raced = await Promise.race([
+      exitOutcome,
+      deps.stop.wait(intervalMs).then(() => ({ kind: "tick" as const })),
+    ]);
+    if (raced.kind === "exit") return raced;
+
+    if (deps.stop.requested) {
+      // The container is going down. The spawn wrapper forwards the signal to
+      // the child, but one that arrived before this child existed never reached
+      // it — so re-send (the engine's drain latch is one-way and idempotent) and
+      // wait the drain out rather than relaunching into a shutdown.
+      child.kill("SIGTERM");
+      return { kind: "exit", exit: await child.exited };
+    }
+
+    deps.onRunTick?.({ engine, elapsedMs: clock.now() - clock.startedAt });
+
+    let current: WatchState;
+    try {
+      current = engine.sample();
+    } catch (error) {
+      // A failed poll (network blip on `ls-remote`, unreadable mount) is not a
+      // change — leave the engine alone and look again next tick.
+      deps.onSampleError?.(error);
+      continue;
+    }
+
+    const reason = detectChange({
+      launched: { config: engine.config, sha: engine.sha, quarantinedSha: engine.quarantinedSha },
+      current,
+    });
+    if (reason) return { kind: "change", reason };
+  }
+}
+
+/**
+ * Run the engine, and keep the *right* engine running: watch, drain, relaunch,
+ * repeat. Resolves with the exit to give the container when the engine exits on
+ * its own (and the crash-loop guard does not want it retried) or the container
+ * is stopping — the two cases where boot should stop supervising and die with
+ * the engine's status.
+ */
+export async function superviseEngine(deps: SuperviseDeps): Promise<EngineExit> {
+  const intervalMs = deps.intervalMs ?? DEFAULT_RECONCILE_INTERVAL_MS;
+  const now = deps.now ?? Date.now;
+  let everLaunched = false;
+
+  while (true) {
+    if (deps.stop.requested) return { code: 0, signal: null };
+
+    let engine: LaunchedEngine;
+    try {
+      engine = await deps.launch();
+    } catch (error) {
+      // The first launch is the container's whole reason to exist, so a bad
+      // config or a missing mount fails loudly. A *relaunch* failure is
+      // transient by comparison (network blip mid-fetch, a ref deleted between
+      // poll and fetch) and the old engine has already drained — retrying on the
+      // next poll brings the engine back instead of taking the container down.
+      if (!everLaunched) throw error;
+      deps.onLaunchError?.(error);
+      await deps.stop.wait(intervalMs);
+      continue;
+    }
+    everLaunched = true;
+
+    const startedAt = now();
+    const child = deps.spawn(engine.entry);
+    const outcome = await watchEngine(engine, child, deps, { intervalMs, startedAt, now });
+
+    if (outcome.kind === "exit") {
+      // A stop makes the engine's exit the container's exit, whatever the guard
+      // would have preferred — we are going down either way, and the run was cut
+      // short rather than judged.
+      const requestedStop = deps.stop.requested;
+      const run = { engine, exit: outcome.exit, elapsedMs: now() - startedAt, requestedStop };
+      deps.onRunEnd?.(run);
+      if (requestedStop || !deps.relaunchAfterExit?.(run)) return outcome.exit;
+      // Retrying a crash: back off first, so a commit that dies on startup
+      // cannot spin the loop, and re-check the stop latch the wait may have
+      // woken on. `launch` runs again from the top, which is where the fallback
+      // to a last-good commit actually takes effect.
+      await deps.stop.wait(CRASH_BACKOFF_MS);
+      if (deps.stop.requested) return outcome.exit;
+      continue;
+    }
+
+    deps.onRelaunch?.(outcome.reason);
+    child.kill("SIGTERM");
+    // Nothing new starts until the drain finishes: one engine at a time, and the
+    // in-flight work unit runs to completion.
+    const exit = await child.exited;
+    deps.onRunEnd?.({ engine, exit, elapsedMs: now() - startedAt, requestedStop: true });
+    if (deps.stop.requested) return exit;
+  }
+}

package/bootstrap/spawn-engine.mjs

@@ -0,0 +1,78 @@
+// The one home for the bootstrapper's child-process signal plumbing.
+//
+// Both the published bin launcher (bin.mjs) and `phoebe boot` (boot.ts) exec a
+// `node <entry>` child with inherited stdio and need the same behaviour: forward
+// the stop signals so a container SIGTERM reaches the real process (the engine's
+// graceful drain), then die however the child died. Keeping it in one module
+// stops the two callers from drifting on the fiddly exit/re-raise handling.
+//
+// Plain JS, not TypeScript: bin.mjs runs first, still inside node_modules, where
+// Node 24 refuses to type-strip `.ts`. boot.ts imports it untyped (same as
+// materialize.mjs) from the materialized copy outside node_modules.
+
+import { spawn } from "node:child_process";
+
+/**
+ * Die however a child process died: re-raise a killing signal so this process
+ * exits the same way, or exit with the child's code.
+ *
+ * The caller must have removed its own listeners for that signal first —
+ * otherwise re-raising just re-runs them and this process falls through and
+ * exits 0, hiding the child's signal death from its parent.
+ */
+export function propagateExit(code, signal) {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 0);
+}
+
+/**
+ * Spawn `node <entry> <args...>` with inherited stdio, forwarding SIGINT/SIGTERM
+ * to it, and propagate its exit (see propagateExit). Returns the child handle.
+ *
+ * `onSpawnError` overrides the default handling of a spawn failure (print
+ * `[phoebe] <message>` and exit 1); callers that want to surface it differently
+ * pass their own.
+ *
+ * `onExit` overrides dying with the child. `phoebe boot` passes one because it
+ * *supervises* the engine: a child that exited because boot drained it for a
+ * relaunch must not take the container with it (bootstrap/reconcile.ts). Callers
+ * that pass `onExit` own the propagation — propagateExit is exported for them.
+ */
+export function spawnEngine(entry, args, { onSpawnError, onExit } = {}) {
+  const child = spawn(process.execPath, [entry, ...args], { stdio: "inherit" });
+
+  const forwarders = new Map();
+  for (const signal of ["SIGINT", "SIGTERM"]) {
+    const forward = () => child.kill(signal);
+    forwarders.set(signal, forward);
+    process.on(signal, forward);
+  }
+  const clearForwarders = () => {
+    for (const [signal, forward] of forwarders) process.off(signal, forward);
+  };
+
+  child.on("error", (error) => {
+    clearForwarders();
+    if (onSpawnError) {
+      onSpawnError(error);
+      return;
+    }
+    console.error(`[phoebe] ${error.message}`);
+    process.exit(1);
+  });
+  child.on("exit", (code, signal) => {
+    // Removed before propagating: a re-raised signal must not just re-run the
+    // forwarder (a no-op kill on the dead child) and leave this process alive.
+    clearForwarders();
+    if (onExit) {
+      onExit(code, signal);
+      return;
+    }
+    propagateExit(code, signal);
+  });
+
+  return child;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phoebe-agent",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "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",
@@ -11,43 +11,45 @@
     "url": "git+https://github.com/JesusFilm/phoebe.git"
   },
   "bin": {
-    "phoebe": "./dist/src/cli.js",
-    "phoebe-agent": "./dist/src/cli.js"
+    "phoebe": "./bootstrap/bin.mjs",
+    "phoebe-agent": "./bootstrap/bin.mjs"
   },
   "files": [
-    "dist",
+    "bootstrap",
+    "src",
     "prompts",
-    "templates"
+    "templates",
+    "!**/*.test.ts",
+    "!src/test-setup.ts"
   ],
   "type": "module",
-  "main": "./dist/src/index.js",
-  "types": "./dist/src/index.d.ts",
+  "main": "./bootstrap/index.mjs",
+  "types": "./bootstrap/index.ts",
   "exports": {
     ".": {
-      "types": "./dist/src/index.d.ts",
-      "import": "./dist/src/index.js"
+      "types": "./bootstrap/index.ts",
+      "import": "./bootstrap/index.mjs"
     },
     "./package.json": "./package.json"
   },
-  "scripts": {
-    "ready": "vp check && vp run -r lint && vp run -r typecheck && vp run -r test && vp run -r build",
-    "check": "vp check",
-    "lint": "vp lint",
-    "typecheck": "vp exec tsc --noEmit",
-    "test": "vp test",
-    "build": "vp exec tsc -p tsconfig.build.json",
-    "changeset": "changeset",
-    "version-packages": "changeset version",
-    "release": "vp run build && changeset publish"
-  },
   "devDependencies": {
     "@changesets/cli": "^2.31.1",
-    "@types/node": "^22.13.0",
+    "@types/node": "^24.0.0",
     "typescript": "^5.7.0",
     "vite-plus": "^0.2.0"
   },
   "engines": {
-    "node": ">=22.13.0"
+    "node": ">=24"
   },
-  "packageManager": "pnpm@11.2.2"
-}
+  "scripts": {
+    "ready": "vp check && vp run -r lint && vp run -r typecheck && vp run -r test",
+    "check": "vp check",
+    "lint": "vp lint",
+    "typecheck": "vp exec tsc --noEmit",
+    "test": "vp test",
+    "phoebe": "bash .phoebe/run.sh",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "changeset publish"
+  }
+}

package/prompts/checks-prompt.md

@@ -24,17 +24,31 @@ You are Phoebe — fixing **failing CI** on an existing PR branch in this reposi
    gh run view <run-id> --log-failed
    ```
 2. **Reproduce** — run the same gates locally: `{{CHECK_COMMAND}}` and `{{TEST_COMMAND}}` (or `{{READY_COMMAND}}` if the project ships an all-in-one gate).
-3. **Fix** — make the smallest correct change that resolves the failures.
-4. **Verify** — re-run `{{CHECK_COMMAND}}` and `{{TEST_COMMAND}}` and fix any remaining failures.
-5. **Commit** — one or more commits with the `Phoebe:` prefix. Do **not** force-push.
-6. **Push** — `git push origin {{PR_BRANCH}}`.
-7. **Flaky escape hatch** — if the failure does not reproduce locally and looks environmental or flaky, you may instead:
+3. **Baseline check** — before assuming a local `{{TEST_COMMAND}}` failure is yours, confirm whether it also fails on a clean `{{DEFAULT_BRANCH}}`. This distinguishes breakage _caused by this PR_ from **pre-existing baseline breakage** already red on `{{DEFAULT_BRANCH}}`.
+   - Establish a clean baseline without disturbing this branch, e.g.:
+     ```
+     git worktree add /tmp/baseline origin/{{DEFAULT_BRANCH}}
+     ```
+     then install (`{{INSTALL_COMMAND}}`) and run `{{TEST_COMMAND}}` inside `/tmp/baseline`. Remove it with `git worktree remove /tmp/baseline` when done.
+   - **Same failures present on the baseline → pre-existing and out of scope for this PR.** Do **not** try to fix them here.
+     - Proceed as long as _this change's own_ gate is green: `{{CHECK_COMMAND}}` passes and any tests newly relevant to your change pass.
+     - Leave a short PR comment noting the pre-existing failures. If no tracking issue already covers them, open one and link it:
+       ```
+       gh issue create --title "<baseline test failure>" --body "<what fails on {{DEFAULT_BRANCH}}, and where you saw it>"
+       ```
+   - **Failures absent from the baseline → attributable to this change.** These are yours; fix them in the next step.
+   - **Reconciling disagreeing gates:** a green `{{CHECK_COMMAND}}` with a red `{{TEST_COMMAND}}` clears you to proceed **only** when every red test is baseline-only. If any failing test is _not_ present on the baseline, `{{CHECK_COMMAND}}` passing does not excuse it — fix that test.
+4. **Fix** — make the smallest correct change that resolves the failures **attributable to this change** (those not present on the baseline).
+5. **Verify** — re-run `{{CHECK_COMMAND}}` and `{{TEST_COMMAND}}` and fix any remaining failures that are not baseline-only.
+6. **Commit** — one or more commits with the `Phoebe:` prefix. Do **not** force-push.
+7. **Push** — `git push origin {{PR_BRANCH}}`.
+8. **Flaky escape hatch** — if the failure does not reproduce locally and looks environmental or flaky, you may instead:
    - `gh run rerun --failed` (once)
    - Comment on the PR explaining why no code change was made:
      ```
      gh pr comment {{PR_NUMBER}} --body "<explanation>"
      ```
-8. **Give up** — only if you cannot fix or rerun, leave a PR comment explaining what you tried:
+9. **Give up** — only if you cannot fix or rerun, leave a PR comment explaining what you tried:
    ```
    gh pr comment {{PR_NUMBER}} --body "<explanation>"
    ```
@@ -42,6 +56,7 @@ You are Phoebe — fixing **failing CI** on an existing PR branch in this reposi
 ## Rules
 
 - Work on **this PR only** (#{{PR_NUMBER}}). Do not pick up issues or other PRs.
+- Only failures **caused by this change** are yours to fix. Pre-existing failures already red on `{{DEFAULT_BRANCH}}` are out of scope — note and track them, don't fix them here.
 - Do not leave commented-out code or TODO comments in committed code.
 - Never force-push (`git push --force`).
 - If you are blocked, comment on the PR and finish — do not push a broken fix.

package/prompts/conflict-prompt.md

@@ -28,7 +28,17 @@ When `{{BLOCKER_PR_NUMBERS}}` is empty, merge `origin/{{DEFAULT_BRANCH}}` only (
 
 1. **Assess** — run `git status`. If no merge is in progress, run the merge order above from scratch.
 2. **Resolve** — fix every conflicted file. Prefer preserving both sides' intent; do not drop unrelated changes from `{{DEFAULT_BRANCH}}` or this branch.
-3. **Verify** — run `{{CHECK_COMMAND}}` and `{{TEST_COMMAND}}` (or `{{READY_COMMAND}}` if the project ships an all-in-one gate). Fix any failures before proceeding.
+3. **Verify** — run `{{CHECK_COMMAND}}` and `{{TEST_COMMAND}}` (or `{{READY_COMMAND}}` if the project ships an all-in-one gate). Fix any failures the merge introduced before proceeding.
+   - **Baseline breakage:** if `{{TEST_COMMAND}}` fails, confirm whether the same failures already exist on a clean `{{DEFAULT_BRANCH}}` checkout before assuming the merge caused them:
+     ```
+     git worktree add /tmp/baseline origin/{{DEFAULT_BRANCH}}
+     ```
+     install (`{{INSTALL_COMMAND}}`) and run `{{TEST_COMMAND}}` there, then `git worktree remove /tmp/baseline`.
+   - Failures **present on the baseline** are pre-existing and out of scope for this reconciliation — do **not** fix them here. Proceed once the merge's own gate is green (`{{CHECK_COMMAND}}` passes and the merge introduced no _new_ test failures), then note the pre-existing failures in a PR comment and, if no tracking issue covers them, open one:
+     ```
+     gh issue create --title "<baseline test failure>" --body "<what fails on {{DEFAULT_BRANCH}}, and where you saw it>"
+     ```
+   - A green `{{CHECK_COMMAND}}` with a red `{{TEST_COMMAND}}` clears you only when every red test is baseline-only. Any failure the **merge** introduced must be fixed before you push.
 4. **Commit** — stage the resolution and commit each merge (e.g. `Phoebe: merge blocker PR #N into {{PR_BRANCH}}`, then `Phoebe: merge {{DEFAULT_BRANCH}} into {{PR_BRANCH}}`). Do **not** force-push.
 5. **Push** — `git push origin {{PR_BRANCH}}`.
 6. **Comment** — only if you **cannot** resolve cleanly or tests still fail after resolving:
@@ -42,6 +52,7 @@ When `{{BLOCKER_PR_NUMBERS}}` is empty, merge `origin/{{DEFAULT_BRANCH}}` only (
 ## Rules
 
 - Work on **this PR only** (#{{PR_NUMBER}}). Do not pick up issues or other PRs.
+- Only failures the **merge** introduced are yours to fix. Pre-existing failures already red on `{{DEFAULT_BRANCH}}` are out of scope — note and track them, don't fix them here.
 - Do not leave commented-out code or TODO comments in committed code.
 - Never force-push (`git push --force`).
 - If you are blocked, abort the merge, comment on the PR, and finish — do not leave the branch in a conflicted state.