phoebe-agent 0.0.0 → 0.1.1

package/dist/src/providers/providers.js

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

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

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

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

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

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

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

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

@@ -1,94 +0,0 @@
-// 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/templates/container/compose.daemon.yml

@@ -1,16 +0,0 @@
-# Persistent-daemon overlay — scaffolded by `phoebe init`, consumer-owned.
-#
-# Layer on top of compose.yml to run Phoebe as a long-lived poller:
-#
-#   docker compose -f compose.yml -f compose.daemon.yml up -d
-#
-# Drops the `--run-once` flag so the engine enters its polling loop, and
-# adds a restart policy so the container comes back after a crash or host
-# reboot. The engine's own self-update path uses `SELF_UPDATE_EXIT_CODE`
-# (75), which the supervisor handles inside the container without needing
-# a restart.
-
-services:
-  phoebe:
-    command: []
-    restart: unless-stopped

package/templates/container/supervisor.sh

@@ -1,50 +0,0 @@
-#!/usr/bin/env bash
-# Phoebe supervisor — scaffolded by `phoebe init`, consumer-owned.
-#
-# Keeps the engine (`{{CLI_BIN}}`) restarted when it exits deliberately for a
-# self-update, and re-runs the consumer's install command (`{{INSTALL_COMMAND}}`)
-# after every self-update so the private clone stays warm. Exits 0 only when
-# the engine returns 0 in one-shot mode.
-
-set -euo pipefail
-
-: "${PHOEBE_REPO_DIR:=/data/repo}"
-: "${PHOEBE_STATE_DIR:=/data/state}"
-
-# Exit code the engine uses to request a supervisor re-exec after a self-update
-# (kept in sync with SELF_UPDATE_EXIT_CODE in src/supervisor-decision.ts).
-SELF_UPDATE_EXIT_CODE=75
-
-mkdir -p "${PHOEBE_REPO_DIR}" "${PHOEBE_STATE_DIR}"
-
-warm_install() {
-  # Best-effort: on first boot the clone doesn't exist yet, and the engine will
-  # populate it on its first tick. Skip silently when there's nothing to install.
-  if [ -f "${PHOEBE_REPO_DIR}/package.json" ]; then
-    ( cd "${PHOEBE_REPO_DIR}" && {{INSTALL_COMMAND}} ) || true
-  fi
-}
-
-while true; do
-  warm_install
-  set +e
-  {{CLI_BIN}} "$@"
-  status=$?
-  set -e
-
-  if [ "${status}" -eq "${SELF_UPDATE_EXIT_CODE}" ]; then
-    echo "[phoebe-supervisor] Engine exited ${SELF_UPDATE_EXIT_CODE} — reinstalling and re-execing."
-    npm install -g "{{CLI_BIN}}@${PHOEBE_VERSION:-latest}" || true
-    continue
-  fi
-
-  # Non-self-update exit — one-shot runs propagate the exit code, persistent
-  # runs treat any exit as unexpected and get restarted after a short backoff.
-  case " $* " in
-    *" --run-once "*|*" --dry-run "*)
-      exit "${status}"
-      ;;
-  esac
-  echo "[phoebe-supervisor] Engine exited ${status} — restarting in 10s."
-  sleep 10
-done