@fastagent-sh/fastagent 0.12.0

package/dist/deploy/railway/run.js

@@ -0,0 +1,176 @@
+/**
+ * Whether `railway status --json` shows a linked project: non-empty stdout. Unlinked prints its message
+ * to stderr and leaves stdout EMPTY (the exit code is 0 either way, so it can't be the signal). ANY
+ * non-empty output — parseable or not — counts as linked, so an unreadable shape is refused, never
+ * mistaken for unlinked (which would `init` a duplicate). Verified against CLI 5.15.0.
+ */
+export function isLinked(stdout) {
+    return stdout.trim() !== "";
+}
+/** The linked project's name for the gate message, or undefined if it can't be read (still linked —
+ *  `railway status --json` puts `name` at the top level on 5.15.0). */
+export function linkedName(stdout) {
+    try {
+        const v = JSON.parse(stdout);
+        if (typeof v.name === "string")
+            return v.name;
+    }
+    catch {
+        /* non-JSON but non-empty → still linked, just no name to show */
+    }
+    return undefined;
+}
+/** Every string leaf of a parsed JSON value — the shape-agnostic scan both readers below share: Railway's
+ *  `--json` field names aren't guaranteed, so we match on VALUES, not paths. `stdout` that isn't JSON
+ *  (an empty/errored query) yields []. */
+function jsonStrings(stdout) {
+    const walk = (v) => typeof v === "string"
+        ? [v]
+        : Array.isArray(v)
+            ? v.flatMap(walk)
+            : v && typeof v === "object"
+                ? Object.values(v).flatMap(walk)
+                : [];
+    try {
+        return walk(JSON.parse(stdout));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * The first Railway-provided domain as an https URL, or undefined if none is present — reads `railway
+ * domain --json` without assuming exact field names: any string value carrying a `*.railway.app` host
+ * wins (unanchored, so a scheme/port/path around it still yields the bare host). Undefined → the CLI
+ * gates (register manually).
+ */
+export function parseDomainUrl(stdout) {
+    for (const s of jsonStrings(stdout)) {
+        const host = s.match(/[a-z0-9-]+(?:\.[a-z0-9-]+)*\.railway\.app/i)?.[0];
+        if (host)
+            return `https://${host}`;
+    }
+    return undefined;
+}
+/**
+ * Whether `railway volume list --json` shows a volume at `mountPath` — shape-agnostic, like
+ * {@link parseDomainUrl}. Drives check-then-act so a half-provisioned project (service created, volume
+ * add failed) self-heals on re-run instead of silently deploying with no volume.
+ */
+export function parseHasVolume(stdout, mountPath) {
+    return jsonStrings(stdout).includes(mountPath);
+}
+/**
+ * Run the deploy through `railway`. `log` reports progress; `registerTelegram(baseUrl)` performs the
+ * post-deploy webhook step (the CLI passes its telegram registrar). Every gate is fail-visible.
+ */
+export async function deployRailwayRun(plan, railway, log, registerTelegram) {
+    const gate = (g) => ({ ok: false, gate: g });
+    // Every --service below targets plan.name — the name this tool gives BOTH the project and the service
+    // (`init --name` + `add --service`). On a fresh create they match; on `--into-linked` into a hand-made
+    // project whose service is named differently, the FIRST --service command (`variables set`) gates —
+    // and it's ordered before the volume (which has no --service), so the mismatch fails visibly with no
+    // side effect. (Pre-checking the name means walking status's nested multi-service shape — not worth it.)
+    const svc = ["--service", plan.name];
+    // 1. Auth needs an ACCOUNT credential (browser login or RAILWAY_API_KEY) — a project token can't
+    //    predate the project `init` creates. `whoami` succeeds with either.
+    if ((await railway(["whoami"], { capture: true })).code !== 0) {
+        return gate("not logged in to Railway — run `railway login`, or set RAILWAY_API_KEY (an account token), then re-run");
+    }
+    // 2. Gate missing required secret VALUES before any side effect (no half-created infra).
+    if (plan.missingSecrets.length > 0) {
+        return gate(`no local value for: ${plan.missingSecrets.join(", ")} — set them in .env (or the environment) and re-run`);
+    }
+    // 3. Linked? `--run` provisions a project and only runs on an UNLINKED directory, so it can never deploy
+    //    into a project it didn't create. A linked directory is REFUSED (naming the project so the operator
+    //    sees what it is) UNLESS they pass --into-linked to provision INTO that project deliberately.
+    //    Unlinked → create. No ownership is tracked — a pre-existing link is never assumed ours; the only
+    //    "yes, this project" signal is the explicit --into-linked. Any non-empty status counts as linked (an
+    //    unreadable shape is refused, not mistaken for unlinked, which would `init` a duplicate).
+    const status = await railway(["status", "--json"], { capture: true });
+    if (isLinked(status.stdout)) {
+        if (!plan.intoLinked) {
+            const name = linkedName(status.stdout);
+            return gate(`this directory is already linked to Railway project ${name ? `"${name}"` : "(name unreadable)"}. ` +
+                "`--run` provisions a NEW project and only runs on an unlinked directory — it won't deploy into an " +
+                "unrelated one. To redeploy an already-provisioned agent, run `railway up`. To provision the agent " +
+                "INTO this project, re-run with --into-linked. To start fresh, `railway unlink` first.");
+        }
+        log(`provisioning into linked project ${linkedName(status.stdout) ?? plan.name} (--into-linked)`);
+    }
+    else {
+        // --into-linked means "provision into the project this dir is linked to" — but it isn't linked. Don't
+        // swallow the flag silently: the operator expected an existing project; say we're creating a fresh one.
+        if (plan.intoLinked) {
+            log("warn: --into-linked was passed but this directory isn't linked to any project — creating a fresh one");
+        }
+        log(`creating project ${plan.name}…`);
+        if ((await railway(["init", "--name", plan.name])).code !== 0) {
+            return gate("`railway init` failed — if you have multiple workspaces, run it once interactively (or pass --workspace) to pick one, then re-run");
+        }
+        // Create + link the service (init makes only a project); it precedes the volume, which has no
+        // --service flag and rides the linked service.
+        log(`creating service ${plan.name}…`);
+        if ((await railway(["add", "--service", plan.name])).code !== 0) {
+            // Precise recovery, not "fix and re-run": init already created + linked the project, so a plain
+            // re-run hits the linked-gate, and --into-linked SKIPS `add` and then fails at the volume (no
+            // service to ride). The clean paths are to create the service by hand then --into-linked, or unlink.
+            return gate(`\`railway add --service\` failed — \`railway init\` already created the project (this directory is now ` +
+                `linked) but not the service. Finish with \`railway add --service ${plan.name}\` here, then re-run with ` +
+                `--into-linked; or \`railway unlink\` to detach and start fresh.`);
+        }
+    }
+    // 3b. Variables — set BEFORE the volume/deploy. This is deliberately the FIRST `--service` command: on
+    //     an --into-linked into a hand-made project whose service name ≠ plan.name, it gates HERE, before the
+    //     volume (which has no --service and would otherwise attach to that service) — so the mismatch fails
+    //     visibly with NO side effect. State root on argv (not secret); secrets one-per-`set --stdin` (value
+    //     on stdin, never argv). Idempotent. (Order vs the volume is free — both just need to precede `up`.)
+    log(`setting FASTAGENT_STATE_DIR + ${Object.keys(plan.secrets).length} secret(s)…`);
+    if ((await railway(["variables", "set", `FASTAGENT_STATE_DIR=${plan.mountPath}`, ...svc])).code !== 0) {
+        return gate("`railway variables set` failed — see the railway output above");
+    }
+    for (const [k, v] of Object.entries(plan.secrets)) {
+        if ((await railway(["variables", "set", k, "--stdin", ...svc], { input: v })).code !== 0) {
+            return gate(`\`railway variables set ${k}\` failed — see the railway output above`);
+        }
+    }
+    // 3c. Volume — check-then-act, ALWAYS (like Fly's per-resource skip-if-present). An --into-linked into an
+    //     existing project may already have it; a first deploy that failed after this step has it, one that
+    //     failed before needs it. Verify + add so we never deploy with NO persistence (FASTAGENT_STATE_DIR
+    //     =/data would be empty every redeploy — silent state loss). Runs after variables so a mismatched
+    //     service (see above) has already gated — this step won't attach a volume to the wrong service.
+    const vols = await railway(["volume", "list", "--json"], { capture: true });
+    if (parseHasVolume(vols.stdout, plan.mountPath)) {
+        log(`volume at ${plan.mountPath} exists — skipping`);
+    }
+    else {
+        log(`creating volume at ${plan.mountPath}…`);
+        if ((await railway(["volume", "add", "--mount-path", plan.mountPath])).code !== 0) {
+            return gate("`railway volume add` failed — see the railway output above");
+        }
+    }
+    // 5. Deploy — CI mode streams build logs then exits (no interactive attach). Build runs on Railway.
+    log("deploying (railway up)…");
+    if ((await railway(["up", "--ci", ...svc])).code !== 0) {
+        return gate("`railway up` failed — see the railway output above; fix and re-run");
+    }
+    // 6. Public domain — a Railway service isn't reachable until one is minted (unlike Fly's deterministic
+    //    <app>.fly.dev), so every deploy needs it (the /invoke + /health surface), not just webhook channels.
+    //    The top-level `railway domain` (no subcommand; --json/--service flags are fine) is the long-standing
+    //    core command: it returns the service domain, minting one if absent. We do NOT pre-check with the
+    //    `domain list` SUBCOMMAND — it's newer, and on a CLI without it `railway domain list` falls through
+    //    to the [DOMAIN] positional and registers a bogus custom domain named "list" (destructive). Version-robust.
+    log("getting the public domain…");
+    const url = parseDomainUrl((await railway(["domain", "--json", ...svc], { capture: true })).stdout);
+    if (!url) {
+        return gate("couldn't read a domain from `railway domain` — run `railway domain` manually, then set any webhook");
+    }
+    if (plan.channels.includes("telegram")) {
+        log("registering telegram webhook…");
+        await registerTelegram(url);
+    }
+    if (plan.channels.includes("github")) {
+        log(`github: set the webhook in the repo (Settings → Webhooks) → ${url}/webhook`);
+    }
+    return { ok: true, url };
+}

package/dist/deploy/runner.d.ts

@@ -0,0 +1,18 @@
+export interface RunResult {
+    code: number;
+    /** Captured stdout (for `--json` queries); empty when the command streamed to the terminal. The CLI's
+     *  stderr is always inherited straight to the terminal, so it is not a field here. */
+    stdout: string;
+}
+/** Run `bin args`: `capture` collects stdout (for `--json` queries), else the command streams to the
+ *  terminal (create/deploy) and stdout is empty; `input` is fed to stdin (secrets over stdin, never argv). */
+export type CliRunner = (args: string[], opts?: {
+    capture?: boolean;
+    input?: string;
+}) => Promise<RunResult>;
+/**
+ * Production {@link CliRunner}: spawn `bin` in `cwd` (the workspace, so a build/upload context is the
+ * agent). stderr is always inherited to the terminal; stdout is inherited unless `capture`. A spawn
+ * ENOENT (the CLI not on PATH) resolves to code 127 so the caller can gate with an install hint.
+ */
+export declare function spawnRunner(bin: string, cwd: string): CliRunner;

package/dist/deploy/runner.js

@@ -0,0 +1,25 @@
+/**
+ * The host-CLI dispatcher seam, shared by every `deploy <host> --run` driver (fly/run.ts, railway/run.ts).
+ * WHAT it does — run a CLI, optionally capture stdout or feed stdin — is identical across hosts; only the
+ * binary and the command sequence differ. Tests inject a fake recorder; production spawns the real CLI.
+ */
+import { spawn } from "node:child_process";
+/**
+ * Production {@link CliRunner}: spawn `bin` in `cwd` (the workspace, so a build/upload context is the
+ * agent). stderr is always inherited to the terminal; stdout is inherited unless `capture`. A spawn
+ * ENOENT (the CLI not on PATH) resolves to code 127 so the caller can gate with an install hint.
+ */
+export function spawnRunner(bin, cwd) {
+    return (args, opts) => new Promise((res) => {
+        const child = spawn(bin, args, {
+            cwd,
+            stdio: [opts?.input ? "pipe" : "inherit", opts?.capture ? "pipe" : "inherit", "inherit"],
+        });
+        let out = "";
+        child.stdout?.on("data", (d) => (out += String(d)));
+        if (opts?.input)
+            child.stdin?.end(opts.input);
+        child.on("close", (code) => res({ code: code ?? 1, stdout: out }));
+        child.on("error", () => res({ code: 127, stdout: "" })); // ENOENT: bin not on PATH
+    });
+}

package/dist/deploy/secrets.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The secret set a deployed agent needs, computed from the definition — host-neutral. WHAT secrets are
+ * required (the model key when local auth is an env key + every discovered channel's secrets) is the
+ * same on every target; only the SET command differs (`fly secrets import` vs `railway variables set`).
+ * The runbooks list these NAMES; `--run` (per host) reads their VALUES from the local env.
+ */
+import { type ChannelKind } from "../scaffold/add-channel.ts";
+/**
+ * Is this local auth source an env-var API key (→ becomes a deploy secret) vs OAuth / stored / none?
+ * Positive match on the UPPER_SNAKE env-var naming shape, NOT a negative exclude of today's sentinel
+ * labels: a new non-env `AuthResult.source` (e.g. `keychain`) then degrades to guidance, never a fake
+ * `keychain=<value>` secret — the two modules don't couple through an exhaustive string list.
+ */
+export declare function isEnvKey(source: string | undefined): source is string;
+/**
+ * The required secret NAMES + hints for a runbook: the model key (when local auth is an env key) plus
+ * every discovered channel's secrets. An OAuth/stored login has no env key here — it carries as
+ * `FASTAGENT_AUTH_SEED` on the `--run` path (see each host's run module), not as a named runbook secret.
+ */
+export declare function requiredSecrets(modelAuth: string | undefined, channels: ChannelKind[], extraSecrets?: string[]): {
+    name: string;
+    hint: string;
+}[];
+/**
+ * Assemble the secret VALUES a `--run` deploy sets on the host, from the local credential + channels —
+ * pure, host-neutral (Fly sets them via `fly secrets import`, Railway via `railway variables set`), so
+ * the security-sensitive key wiring is testable once. The model credential travels one of two ways: an
+ * env-key auth as its own secret (value from `env`), OR an OAuth/stored login (no plaintext key) as
+ * `FASTAGENT_AUTH_SEED` (base64 auth.json) which `start` materializes on first boot. `needsModelCredential`
+ * (neither present) is a DISTINCT signal: its remediation is `fastagent login`, not the `.env` one that
+ * `missingSecrets` (real secret NAMES with no value) carries.
+ *
+ * Channel secrets come from the local env only — NEVER minted. A random mint would be wrong for a
+ * human-shared secret (github's webhook secret must match the value the operator enters in the repo,
+ * which a silent mint never surfaces) and would rotate every run (breaking idempotency). Absent →
+ * `missingSecrets`, same as the plain runbook's operator-filled placeholders.
+ */
+export declare function assembleSecrets(input: {
+    modelAuth: string | undefined;
+    authFile: Buffer | undefined;
+    channels: ChannelKind[];
+    /** Extra secret env-var names from `fastagent.config` deploy.secrets — carried like channel secrets. */
+    extraSecrets?: string[];
+    env: NodeJS.ProcessEnv;
+}): {
+    secrets: Record<string, string>;
+    missingSecrets: string[];
+    needsModelCredential: boolean;
+};

package/dist/deploy/secrets.js

@@ -0,0 +1,88 @@
+/**
+ * The secret set a deployed agent needs, computed from the definition — host-neutral. WHAT secrets are
+ * required (the model key when local auth is an env key + every discovered channel's secrets) is the
+ * same on every target; only the SET command differs (`fly secrets import` vs `railway variables set`).
+ * The runbooks list these NAMES; `--run` (per host) reads their VALUES from the local env.
+ */
+import { channelSetup } from "../scaffold/add-channel.js";
+/**
+ * Is this local auth source an env-var API key (→ becomes a deploy secret) vs OAuth / stored / none?
+ * Positive match on the UPPER_SNAKE env-var naming shape, NOT a negative exclude of today's sentinel
+ * labels: a new non-env `AuthResult.source` (e.g. `keychain`) then degrades to guidance, never a fake
+ * `keychain=<value>` secret — the two modules don't couple through an exhaustive string list.
+ */
+export function isEnvKey(source) {
+    return source !== undefined && /^[A-Z][A-Z0-9_]*$/.test(source);
+}
+/**
+ * The required secret NAMES + hints for a runbook: the model key (when local auth is an env key) plus
+ * every discovered channel's secrets. An OAuth/stored login has no env key here — it carries as
+ * `FASTAGENT_AUTH_SEED` on the `--run` path (see each host's run module), not as a named runbook secret.
+ */
+export function requiredSecrets(modelAuth, channels, extraSecrets = []) {
+    const secrets = [];
+    if (isEnvKey(modelAuth))
+        secrets.push({ name: modelAuth, hint: "your model provider key" });
+    for (const kind of channels) {
+        for (const e of channelSetup(kind).env)
+            secrets.push({ name: e.name, hint: e.hint });
+    }
+    // Dedup: a name already covered by the model key / a channel secret must not appear twice in the runbook.
+    for (const name of extraSecrets) {
+        if (!secrets.some((s) => s.name === name)) {
+            secrets.push({ name, hint: "declared in fastagent.config deploy.secrets" });
+        }
+    }
+    return secrets;
+}
+/**
+ * Assemble the secret VALUES a `--run` deploy sets on the host, from the local credential + channels —
+ * pure, host-neutral (Fly sets them via `fly secrets import`, Railway via `railway variables set`), so
+ * the security-sensitive key wiring is testable once. The model credential travels one of two ways: an
+ * env-key auth as its own secret (value from `env`), OR an OAuth/stored login (no plaintext key) as
+ * `FASTAGENT_AUTH_SEED` (base64 auth.json) which `start` materializes on first boot. `needsModelCredential`
+ * (neither present) is a DISTINCT signal: its remediation is `fastagent login`, not the `.env` one that
+ * `missingSecrets` (real secret NAMES with no value) carries.
+ *
+ * Channel secrets come from the local env only — NEVER minted. A random mint would be wrong for a
+ * human-shared secret (github's webhook secret must match the value the operator enters in the repo,
+ * which a silent mint never surfaces) and would rotate every run (breaking idempotency). Absent →
+ * `missingSecrets`, same as the plain runbook's operator-filled placeholders.
+ */
+export function assembleSecrets(input) {
+    const secrets = {};
+    const missingSecrets = [];
+    let needsModelCredential = false;
+    if (isEnvKey(input.modelAuth)) {
+        const v = input.env[input.modelAuth];
+        if (v)
+            secrets[input.modelAuth] = v;
+        else
+            missingSecrets.push(input.modelAuth); // an env-key name with no value — `.env` remediation fits
+    }
+    else if (input.authFile) {
+        secrets.FASTAGENT_AUTH_SEED = input.authFile.toString("base64");
+    }
+    else {
+        needsModelCredential = true; // no env key, no auth.json — `fastagent login` remediation
+    }
+    for (const kind of input.channels) {
+        for (const e of channelSetup(kind).env) {
+            const v = input.env[e.name];
+            if (v)
+                secrets[e.name] = v;
+            else
+                missingSecrets.push(e.name); // operator-provided (in .env); a human-shared secret can't be minted
+        }
+    }
+    for (const name of input.extraSecrets ?? []) {
+        if (name in secrets || missingSecrets.includes(name))
+            continue; // already covered by model/channel — no dup
+        const v = input.env[name];
+        if (v)
+            secrets[name] = v;
+        else
+            missingSecrets.push(name); // declared in config but no local value — same .env remediation
+    }
+    return { secrets, missingSecrets, needsModelCredential };
+}

package/dist/dev-supervisor.d.ts

@@ -0,0 +1,14 @@
+/** What the dev watcher restarts on (workspace-relative): the process-bound code inputs only. */
+export declare const WATCHED_HINT = "tools/, channels/, package.json (agent dir), fastagent.config.*, .env (run root)";
+/**
+ * chokidar `ignored` matcher for the narrow watch scope (true = ignore). Ignoring a directory prunes
+ * the whole subtree, so everything outside the allowlist — .fastagent state, node_modules, .git, and
+ * any file/dir the agent writes as work product — costs no watchers and triggers no restarts.
+ * Helper code imported from OUTSIDE tools//channels/ is out of scope by design (keep it under
+ * tools/, or restart manually) — the startup log names the watched set.
+ */
+export declare function devWatchIgnored(dir: string, agentDir: string): (path: string) => boolean;
+/** Spawn the dev worker and restart it on workspace edits; supervise its lifecycle until the process exits. */
+export declare function runDevSupervisor(dir: string, options?: {
+    tunnel?: boolean;
+}): Promise<void>;

package/dist/dev-supervisor.js

@@ -0,0 +1,158 @@
+/**
+ * The `fastagent dev` process supervisor: re-spawn the CLI as a worker (`FASTAGENT_DEV_WORKER=1`) and
+ * restart it on debounced edits to the workspace's CODE inputs. Each restart is a fresh process
+ * (always-latest, no stale module cache). The supervisor never exits on a bad edit — the worker fails
+ * loudly and it waits for the next save.
+ *
+ * Watch scope is deliberately narrow: only inputs whose changes REQUIRE a new process — imported
+ * code (tools/, channels/), fastagent.config.*, package.json, .env. The definition (AGENTS.md,
+ * persona.md, skills/) is re-read per invoke by the directory rung, so its edits go live on the next turn with no
+ * restart — and, critically, an agent that writes files into its own workspace (its normal work
+ * product, including editing its own AGENTS.md) never has its in-flight turn killed by the watcher.
+ */
+import { spawn } from "node:child_process";
+import { relative, sep } from "node:path";
+import { watch as watchTree } from "chokidar";
+import { loadConfig, resolveAgentDir } from "./engines/pi/config.js";
+import { log } from "./log.js";
+import { installProxyFetch } from "./proxy.js";
+import { announceWebhooks, startCloudflareTunnel } from "./tunnel.js";
+/** What the dev watcher restarts on (workspace-relative): the process-bound code inputs only. */
+export const WATCHED_HINT = "tools/, channels/, package.json (agent dir), fastagent.config.*, .env (run root)";
+/**
+ * chokidar `ignored` matcher for the narrow watch scope (true = ignore). Ignoring a directory prunes
+ * the whole subtree, so everything outside the allowlist — .fastagent state, node_modules, .git, and
+ * any file/dir the agent writes as work product — costs no watchers and triggers no restarts.
+ * Helper code imported from OUTSIDE tools//channels/ is out of scope by design (keep it under
+ * tools/, or restart manually) — the startup log names the watched set.
+ */
+export function devWatchIgnored(dir, agentDir) {
+    return (path) => {
+        if (path === dir || path === agentDir)
+            return false; // the roots themselves must not be pruned
+        // Never prune a directory on the path from the watch root down to agentDir, so chokidar can descend
+        // into `agentDir/tools` even when agentDir is a subdir (config.agentDir = "./agent").
+        if (agentDir.startsWith(path + sep))
+            return false;
+        const rel = relative(dir, path);
+        // Run-root (cwd) inputs: .env + fastagent.config.* live where config lives, not in agentDir.
+        if (rel === ".env")
+            return false;
+        if (/^fastagent\.config\.[cm]?[jt]s$/.test(rel))
+            return false;
+        // Agent code inputs live in agentDir: tools/, channels/, schedules/ (loaded once per worker — a
+        // restart is their only re-read), package.json (its own deps). Everything else under agentDir
+        // (skills/, persona.md, AGENTS.md) is live-read — pruned, no restart.
+        const relAgent = relative(agentDir, path);
+        if (!relAgent.startsWith("..")) {
+            const [head] = relAgent.split(sep);
+            if (head === "tools" || head === "channels" || head === "schedules")
+                return false;
+            if (relAgent === "package.json")
+                return false;
+        }
+        return true;
+    };
+}
+/** Spawn the dev worker and restart it on workspace edits; supervise its lifecycle until the process exits. */
+export async function runDevSupervisor(dir, options = {}) {
+    // The watch root is `dir` (cwd); tools/channels the restart-watch cares about live in agentDir. On a
+    // config error, default agentDir=dir and let the spawned worker surface the real error (fail-visibly).
+    // agentDir is assumed STATIC for the dev session: the supervisor computes it once here and each spawned
+    // worker recomputes its own from the same config — config validation guarantees it stays under `dir`
+    // (so the watch scope is always right); a config edit that changes agentDir mid-session (rare) is out
+    // of scope for watch-scope re-sync (it triggers a worker restart regardless).
+    // A genuine config error (not just a missing agentDir key) — debug-log it here so the silence is not
+    // total before the spawned worker crash-loops and surfaces the real message; default agentDir=dir.
+    const config = await loadConfig(dir)
+        .then((r) => r.config)
+        .catch((err) => {
+        log.debug(`[fastagent] dev: config load failed while resolving agentDir (worker will report): ${String(err)}`);
+        return {};
+    });
+    const agentDir = resolveAgentDir(dir, config);
+    let worker;
+    let reloadPending = false;
+    let everServed = false; // has any worker successfully bound (sent `ready`) yet?
+    let timer;
+    // The supervisor owns the tunnel so the public URL survives worker reloads (a fresh tunnel per save
+    // would mean a new URL + re-registering the webhook on every edit).
+    let tunnel;
+    // The supervisor itself calls the channel webhook APIs (setWebhook) when announcing the tunnel, so
+    // it needs the proxy too (workers install their own). A region-blocked api.telegram.org fails otherwise.
+    if (options.tunnel)
+        installProxyFetch();
+    const spawnWorker = () => {
+        // ipc fd so the worker can signal readiness once it binds; stdio otherwise inherited.
+        // biome-ignore lint/style/noNonNullAssertion: argv[1] is always the script path under a node entry
+        const w = spawn(process.execPath, [process.argv[1], ...process.argv.slice(2)], {
+            stdio: ["inherit", "inherit", "inherit", "ipc"],
+            env: { ...process.env, FASTAGENT_DEV_WORKER: "1" },
+        });
+        worker = w;
+        w.on("message", (m) => {
+            if (m?.type !== "ready")
+                return;
+            everServed = true;
+            // Start the tunnel once, on the first worker that binds; reuse it across reloads.
+            if (options.tunnel && !tunnel && typeof m.port === "number") {
+                void startCloudflareTunnel(m.port).then((t) => {
+                    if (t) {
+                        tunnel = t;
+                        void announceWebhooks(agentDir, t.url);
+                    }
+                });
+            }
+        });
+        w.on("exit", (code, signal) => {
+            if (worker !== w)
+                return; // already superseded
+            worker = undefined;
+            if (reloadPending) {
+                reloadPending = false;
+                spawnWorker(); // restart requested: the old worker has exited, so the port is free
+            }
+            else if (!everServed) {
+                // Failed BEFORE ever serving — a non-editable startup failure (bad flag, EADDRINUSE, broken
+                // initial workspace) that saving cannot fix. Propagate the exit code (the worker already
+                // printed the error via inherited stdio).
+                process.exit(code ?? 1);
+            }
+            else {
+                // A worker that HAD been serving stopped (broken edit or crash). Fixable; wait for the next save.
+                log.warn(`[fastagent] dev stopped (worker exited: ${signal ?? code}) — save a change to retry`);
+            }
+        });
+    };
+    const triggerReload = () => {
+        log.info(`[fastagent] change detected — restarting…`);
+        if (worker) {
+            reloadPending = true;
+            worker.kill("SIGTERM"); // the exit handler respawns once the port is released
+        }
+        else {
+            spawnWorker(); // worker was down (broken edit) — retry now
+        }
+    };
+    // chokidar gives reliable cross-platform recursion + structural ignore that native fs.watch
+    // cannot; devWatchIgnored (above) narrows the scope to the process-bound code inputs.
+    const watcher = watchTree(dir, {
+        ignoreInitial: true, // the startup scan is not a change
+        ignored: devWatchIgnored(dir, agentDir),
+    });
+    watcher.on("all", () => {
+        clearTimeout(timer);
+        timer = setTimeout(triggerReload, 200);
+    });
+    watcher.on("error", (error) => log.warn(`[fastagent] file watching error (${error.message}); some edits may need a manual restart`));
+    log.info(`[fastagent] watching ${WATCHED_HINT} — code edits restart the dev worker (--no-watch to disable); AGENTS.md/persona.md/skills edits go live next turn without a restart`);
+    const shutdown = () => {
+        worker?.kill("SIGTERM");
+        tunnel?.close();
+        void watcher.close();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    spawnWorker();
+}

package/dist/engines/pi/auth.d.ts

@@ -0,0 +1,17 @@
+import type { CredentialStore } from "@earendil-works/pi-ai";
+/**
+ * The GLOBAL fastagent credentials file (distinct from pi's `~/.pi`). The project-level default is
+ * `<dir>/.fastagent/auth.json` (computed by the opener and by `fastagent login`); this is only the
+ * `loginFlow()` PROGRAMMATIC fallback (when a caller omits `authPath`) and the path to point
+ * `--auth-path`/`FASTAGENT_AUTH_PATH` at to deliberately share ONE credential file across projects
+ * (safe — one file, one lock-serialized refresh lifecycle). The `fastagent login` CLI is project-
+ * level by default, never this.
+ */
+export declare const GLOBAL_AUTH_PATH: string;
+export interface FastagentAuthOptions {
+    /** Sink for non-fatal auth anomalies (unreadable/corrupt file). Defaults to the process logger (warn). */
+    warn?: (message: string) => void;
+}
+/** A read-write `CredentialStore` backed by the given credentials file (default {@link GLOBAL_AUTH_PATH};
+ *  the directory opener passes the project-level `<dir>/.fastagent/auth.json`). */
+export declare function fastagentCredentialStore(authPath?: string, options?: FastagentAuthOptions): CredentialStore;