phoebe-agent 0.0.0

package/dist/src/providers/providers.js

@@ -0,0 +1,210 @@
+// 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.
+/** Maps allowlisted tool names to the input field carrying the display arg. */
+const TOOL_ARG_FIELDS = {
+    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) => {
+    if (!line.startsWith("{"))
+        return [];
+    try {
+        const obj = JSON.parse(line);
+        const message = obj["message"];
+        if (obj["type"] === "assistant" && Array.isArray(message?.content)) {
+            const events = [];
+            const texts = [];
+            for (const block of message.content) {
+                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) => {
+    if (!line.startsWith("{"))
+        return [];
+    let obj;
+    try {
+        obj = JSON.parse(line);
+    }
+    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;
+    const readToolCall = tc["readToolCall"];
+    if (readToolCall?.args && typeof readToolCall.args.path === "string") {
+        return [{ type: "tool_call", name: "Read", args: readToolCall.args.path }];
+    }
+    const writeToolCall = tc["writeToolCall"];
+    if (writeToolCall?.args && typeof writeToolCall.args.path === "string") {
+        return [{ type: "tool_call", name: "Write", args: writeToolCall.args.path }];
+    }
+    const fn = tc["function"];
+    if (fn && typeof fn.name === "string") {
+        const rawArgs = typeof fn.arguments === "string" ? fn.arguments : "";
+        if (rawArgs) {
+            try {
+                const parsedArgs = JSON.parse(rawArgs);
+                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) => {
+    const err = obj["error"];
+    if (typeof err === "string")
+        return err;
+    if (typeof err === "object" && err !== null) {
+        const e = err;
+        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) => {
+    if (!line.startsWith("{"))
+        return [];
+    try {
+        const obj = JSON.parse(line);
+        const item = obj["item"];
+        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 = {
+    name: "cursor",
+    buildCommand({ prompt, model }) {
+        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 = {
+    name: "claude",
+    buildCommand({ prompt, model }) {
+        return {
+            argv: [
+                "claude",
+                "--print",
+                "--verbose",
+                "--dangerously-skip-permissions",
+                "--output-format",
+                "stream-json",
+                "--model",
+                model,
+                "-p",
+                "-",
+            ],
+            stdin: prompt,
+        };
+    },
+    parseStreamLine: parseClaudeStreamLine,
+};
+const codex = {
+    name: "codex",
+    buildCommand({ prompt, model }) {
+        return {
+            argv: ["codex", "exec", "--json", "--dangerously-bypass-approvals-and-sandbox", "-m", model],
+            stdin: prompt,
+        };
+    },
+    parseStreamLine: parseCodexStreamLine,
+};
+export const PROVIDERS = { cursor, claude, codex };

package/dist/src/providers/run-agent.d.ts

@@ -0,0 +1,34 @@
+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;
+export declare function runAgent(opts: {
+    provider: Provider;
+    model: string;
+    prompt: string;
+    cwd: string;
+    env: Record<string, string>;
+    spawn?: SpawnAgent;
+    log?: (line: string) => void;
+}): Promise<AgentRunResult>;

package/dist/src/providers/run-agent.js

@@ -0,0 +1,57 @@
+// 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";
+const defaultSpawn = (file, args, opts) => nodeSpawn(file, args, { ...opts, stdio: ["pipe", "pipe", "pipe"] });
+export async function runAgent(opts) {
+    const { provider, model, prompt, cwd, env } = opts;
+    const spawn = opts.spawn ?? defaultSpawn;
+    const log = opts.log ?? ((line) => 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((resolve, reject) => {
+        const child = spawn(file, args, { cwd, env });
+        let resultText = "";
+        let stdoutBuffer = "";
+        const handleLine = (line) => {
+            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/dist/src/providers/types.d.ts

@@ -0,0 +1,27 @@
+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/dist/src/providers/types.js

@@ -0,0 +1,6 @@
+// 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.
+export {};

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

@@ -0,0 +1,8 @@
+import type { PhoebeConfig } from "./config-schema.ts";
+/** Install the resolved config. Idempotent — later calls replace the prior value. */
+export declare function setResolvedConfig(next: PhoebeConfig): void;
+/** For test isolation: clear the installed config back to the "not installed" state. */
+export declare function clearResolvedConfig(): void;
+/** Whether a resolved config has been installed. */
+export declare function hasResolvedConfig(): boolean;
+export declare const config: PhoebeConfig;

package/dist/src/resolved-config.js

@@ -0,0 +1,49 @@
+// 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`.
+let resolved = null;
+/** Install the resolved config. Idempotent — later calls replace the prior value. */
+export function setResolvedConfig(next) {
+    resolved = next;
+}
+/** For test isolation: clear the installed config back to the "not installed" state. */
+export function clearResolvedConfig() {
+    resolved = null;
+}
+/** Whether a resolved config has been installed. */
+export function hasResolvedConfig() {
+    return resolved !== null;
+}
+export const config = new Proxy({}, {
+    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];
+    },
+    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/dist/src/supervisor-decision.d.ts

@@ -0,0 +1,70 @@
+/** Deliberate "I need a reinstall + re-exec" exit code, watched by container/supervisor.sh. */
+export declare const SELF_UPDATE_EXIT_CODE = 42;
+/** Consecutive fast crashes of a freshly-pulled SHA before the daemon falls
+ *  back to the last SHA that ran healthily. Mirrored in container/supervisor.sh. */
+export declare const CRASH_LOOP_THRESHOLD = 3;
+/** Seconds an orchestrator run must survive to count as healthy: a startup
+ *  crash from a bad pull dies well within this, a transient runtime error does
+ *  not. Mirrored in container/supervisor.sh. */
+export declare const HEALTHY_RUN_SECONDS = 60;
+/**
+ * Whether any changed file means Phoebe's own code (or the lockfile behind its
+ * dependencies) moved. `selfUpdatePaths` entries ending in `/` match as
+ * directory prefixes; other entries match exactly.
+ */
+export declare function shouldSelfUpdate(changedFiles: readonly string[], selfUpdatePaths: readonly string[]): boolean;
+/**
+ * Whether the orchestrator should exit for a supervisor self-update. Same as
+ * {@link shouldSelfUpdate}, except a run pinned to the last-good SHA (the
+ * supervisor passes the crash-looping SHA it is quarantining) must not
+ * self-update back into that quarantined commit: while `origin/<branch>` still
+ * points at it, stay on the good code.
+ */
+export declare function shouldExitForSelfUpdate(opts: {
+    changedFiles: readonly string[];
+    selfUpdatePaths: readonly string[];
+    /** Current `origin/<defaultBranch>` SHA. */
+    originSha: string;
+    /** The crash-looping SHA the supervisor is avoiding, if any. */
+    quarantinedSha?: string | null;
+}): boolean;
+/** Crash-loop bookkeeping, persisted across container restarts on /data/state. */
+export type CrashLoopState = {
+    /** SHA that last ran healthily — the fallback target. */
+    lastGoodSha: string | null;
+    /** SHA currently accumulating fast-crash counts (or quarantined as bad). */
+    failingSha: string | null;
+    /** Consecutive fast crashes recorded for `failingSha`. */
+    failureCount: number;
+};
+export declare const INITIAL_CRASH_LOOP_STATE: CrashLoopState;
+/**
+ * Whether the supervisor should abandon `target` and re-run the last known-good
+ * SHA — true only once `target` has fast-crashed `threshold` times and a
+ * *different* good SHA exists to fall back to (if the good SHA is `target`
+ * itself, falling back changes nothing, so we keep retrying `target`).
+ */
+export declare function shouldFallBack(target: string, state: CrashLoopState, threshold?: number): boolean;
+/** The SHA the supervisor should check out and run this iteration. */
+export declare function chooseRunSha(target: string, state: CrashLoopState, threshold?: number): string;
+export type RunOutcome = {
+    /** SHA that was run. */
+    sha: string;
+    /** Orchestrator exit code. */
+    exitCode: number;
+    /** Seconds the run survived before exiting. */
+    elapsedSeconds: number;
+};
+/**
+ * A run is healthy — its code booted and worked — if it self-updated, exited
+ * cleanly, or survived the healthy window before exiting. Only a fast non-zero,
+ * non-self-update exit is a crash that counts toward the fallback threshold.
+ */
+export declare function isHealthyRun(outcome: RunOutcome, healthySeconds?: number): boolean;
+/**
+ * Fold a completed run into the crash-loop state. A healthy run becomes the new
+ * last-good, but a quarantine of a *different* crash-looping SHA is preserved
+ * (a fallback run of the good SHA must not clear the bad SHA's record). A fast
+ * crash increments the count for its SHA, resetting when the failing SHA moves.
+ */
+export declare function recordRun(state: CrashLoopState, outcome: RunOutcome, healthySeconds?: number): CrashLoopState;

package/dist/src/supervisor-decision.js

@@ -0,0 +1,94 @@
+// Pure self-update + crash-loop decisions. The container's shell supervisor
+// stays dumb; these functions are the tested specification it mirrors.
+//
+//   - shouldSelfUpdate / shouldExitForSelfUpdate — after each cycle's fetch,
+//     did Phoebe's own code move on the default branch? If so the orchestrator
+//     exits with SELF_UPDATE_EXIT_CODE and the supervisor reinstalls + re-execs.
+//   - chooseRunSha / recordRun — the daemon's last-good crash-loop fallback:
+//     if a freshly-pulled SHA keeps dying on startup, pin to the last SHA that
+//     ran healthily until the default branch advances past the bad one.
+//
+// The supervisor mirrors this logic in POSIX sh (container/supervisor.sh)
+// rather than calling it, so the fallback survives the very failure it guards
+// against — a bad pull that makes this TypeScript itself fail to run. Keep the
+// two in sync; the tests here are the reference semantics.
+/** Deliberate "I need a reinstall + re-exec" exit code, watched by container/supervisor.sh. */
+export const SELF_UPDATE_EXIT_CODE = 42;
+/** Consecutive fast crashes of a freshly-pulled SHA before the daemon falls
+ *  back to the last SHA that ran healthily. Mirrored in container/supervisor.sh. */
+export const CRASH_LOOP_THRESHOLD = 3;
+/** Seconds an orchestrator run must survive to count as healthy: a startup
+ *  crash from a bad pull dies well within this, a transient runtime error does
+ *  not. Mirrored in container/supervisor.sh. */
+export const HEALTHY_RUN_SECONDS = 60;
+/**
+ * Whether any changed file means Phoebe's own code (or the lockfile behind its
+ * dependencies) moved. `selfUpdatePaths` entries ending in `/` match as
+ * directory prefixes; other entries match exactly.
+ */
+export function shouldSelfUpdate(changedFiles, selfUpdatePaths) {
+    return changedFiles.some((file) => selfUpdatePaths.some((path) => (path.endsWith("/") ? file.startsWith(path) : file === path)));
+}
+/**
+ * Whether the orchestrator should exit for a supervisor self-update. Same as
+ * {@link shouldSelfUpdate}, except a run pinned to the last-good SHA (the
+ * supervisor passes the crash-looping SHA it is quarantining) must not
+ * self-update back into that quarantined commit: while `origin/<branch>` still
+ * points at it, stay on the good code.
+ */
+export function shouldExitForSelfUpdate(opts) {
+    if (opts.quarantinedSha && opts.originSha === opts.quarantinedSha)
+        return false;
+    return shouldSelfUpdate(opts.changedFiles, opts.selfUpdatePaths);
+}
+export const INITIAL_CRASH_LOOP_STATE = {
+    lastGoodSha: null,
+    failingSha: null,
+    failureCount: 0,
+};
+/**
+ * Whether the supervisor should abandon `target` and re-run the last known-good
+ * SHA — true only once `target` has fast-crashed `threshold` times and a
+ * *different* good SHA exists to fall back to (if the good SHA is `target`
+ * itself, falling back changes nothing, so we keep retrying `target`).
+ */
+export function shouldFallBack(target, state, threshold = CRASH_LOOP_THRESHOLD) {
+    return (state.failingSha === target &&
+        state.failureCount >= threshold &&
+        state.lastGoodSha !== null &&
+        state.lastGoodSha !== target);
+}
+/** The SHA the supervisor should check out and run this iteration. */
+export function chooseRunSha(target, state, threshold = CRASH_LOOP_THRESHOLD) {
+    return shouldFallBack(target, state, threshold) ? state.lastGoodSha : target;
+}
+/**
+ * A run is healthy — its code booted and worked — if it self-updated, exited
+ * cleanly, or survived the healthy window before exiting. Only a fast non-zero,
+ * non-self-update exit is a crash that counts toward the fallback threshold.
+ */
+export function isHealthyRun(outcome, healthySeconds = HEALTHY_RUN_SECONDS) {
+    return (outcome.exitCode === SELF_UPDATE_EXIT_CODE ||
+        outcome.exitCode === 0 ||
+        outcome.elapsedSeconds >= healthySeconds);
+}
+/**
+ * Fold a completed run into the crash-loop state. A healthy run becomes the new
+ * last-good, but a quarantine of a *different* crash-looping SHA is preserved
+ * (a fallback run of the good SHA must not clear the bad SHA's record). A fast
+ * crash increments the count for its SHA, resetting when the failing SHA moves.
+ */
+export function recordRun(state, outcome, healthySeconds = HEALTHY_RUN_SECONDS) {
+    if (isHealthyRun(outcome, healthySeconds)) {
+        const stillQuarantining = state.failingSha !== null && state.failingSha !== outcome.sha;
+        return {
+            lastGoodSha: outcome.sha,
+            failingSha: stillQuarantining ? state.failingSha : null,
+            failureCount: stillQuarantining ? state.failureCount : 0,
+        };
+    }
+    if (state.failingSha === outcome.sha) {
+        return { ...state, failureCount: state.failureCount + 1 };
+    }
+    return { lastGoodSha: state.lastGoodSha, failingSha: outcome.sha, failureCount: 1 };
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "phoebe-agent",
+  "version": "0.0.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",
+  "bugs": "https://github.com/JesusFilm/phoebe/issues",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JesusFilm/phoebe.git"
+  },
+  "bin": {
+    "phoebe": "./dist/src/cli.js",
+    "phoebe-agent": "./dist/src/cli.js"
+  },
+  "files": [
+    "dist",
+    "prompts",
+    "templates"
+  ],
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    },
+    "./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",
+    "typescript": "^5.7.0",
+    "vite-plus": "^0.2.0"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "packageManager": "pnpm@11.2.2"
+}

package/prompts/checks-prompt.md

@@ -0,0 +1,53 @@
+# Context
+
+## Assigned task
+
+Phoebe's host detected that **PR #{{PR_NUMBER}}** (`{{PR_BRANCH}}`) has failing CI on its current head. Your job is to fix the failures, verify locally, and push — or leave a PR comment if you cannot fix them.
+
+!`gh pr view {{PR_NUMBER}} --json number,title,body,headRefName,baseRefName`
+
+## Failing checks
+
+{{FAILING_CHECKS}}
+
+# Task
+
+You are Phoebe — fixing **failing CI** on an existing PR branch in this repository.
+
+**Before anything else, read `AGENTS.md` at the repo root, if present.** It is the single source of project guidance — toolchain, conventions, and any compliance requirements — and it overrides your defaults.
+
+## Workflow
+
+1. **Investigate** — pull failure logs for each failing check:
+   ```
+   gh run list --branch {{PR_BRANCH}} --limit 5
+   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:
+   - `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:
+   ```
+   gh pr comment {{PR_NUMBER}} --body "<explanation>"
+   ```
+
+## Rules
+
+- Work on **this PR only** (#{{PR_NUMBER}}). Do not pick up issues or other PRs.
+- 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.
+
+# Done
+
+When CI is fixed and pushed, or you have commented (rerun or give-up), output:
+
+<promise>COMPLETE</promise>