@fastagent-sh/fastagent 0.12.0

package/dist/deploy/fly/run.js

@@ -0,0 +1,89 @@
+/**
+ * The bytes to seed to the auth file, or undefined to leave it alone — the pure core of `start`'s
+ * FASTAGENT_AUTH_SEED materialization. ABSENT-ONLY by design: a present file (a refreshed volume copy)
+ * is never overwritten by the stale seed, so a box that ran its own OAuth refresh is not rolled back.
+ */
+export function authSeedBytes(seed, fileExists) {
+    return !seed || fileExists ? undefined : Buffer.from(seed, "base64");
+}
+/** Whether a `fly … list --json` array contains an object named `name` (Fly capitalizes `Name`; accept both). */
+function listHasName(stdout, name) {
+    try {
+        const arr = JSON.parse(stdout);
+        return (Array.isArray(arr) &&
+            arr.some((o) => o.Name === name || o.name === name));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Run the deploy through `fly`. `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 deployFlyRun(plan, fly, log, registerTelegram) {
+    const gate = (g) => ({ ok: false, gate: g });
+    // 1. Auth is the one gate a coding agent can't clear itself (browser OAuth). `whoami` succeeds with
+    //    either an interactive login or FLY_API_TOKEN, so one check covers both.
+    if ((await fly(["auth", "whoami"], { capture: true })).code !== 0) {
+        return gate("not logged in to Fly — run `fly auth login` (opens a browser), or set FLY_API_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. App — idempotent (create only if absent; a taken global name is a gate). A FAILED list is its own
+    //    gate: inferring "absent" from an errored query would then misreport the create as a name clash.
+    const appsList = await fly(["apps", "list", "--json"], { capture: true });
+    if (appsList.code !== 0)
+        return gate("`fly apps list` failed — see the flyctl output above; fix and re-run");
+    if (listHasName(appsList.stdout, plan.appName)) {
+        log(`app ${plan.appName} exists — skipping create`);
+    }
+    else {
+        log(`creating app ${plan.appName}…`);
+        if ((await fly(["apps", "create", plan.appName])).code !== 0) {
+            return gate(`\`fly apps create ${plan.appName}\` failed — Fly app names are globally unique and it may be taken. ` +
+                `Set a unique \`app\` in fly.toml and re-run.`);
+        }
+    }
+    // 4. Volume — idempotent; region comes from fly.toml (must match the machine's region). A failed list
+    //    gates for the same reason as the app list above.
+    const volList = await fly(["volumes", "list", "-a", plan.appName, "--json"], { capture: true });
+    if (volList.code !== 0)
+        return gate("`fly volumes list` failed — see the flyctl output above; fix and re-run");
+    if (listHasName(volList.stdout, "data")) {
+        log(`volume data exists — skipping create`);
+    }
+    else {
+        log(`creating volume data in ${plan.region}…`);
+        if ((await fly(["volumes", "create", "data", "-a", plan.appName, "--region", plan.region, "--size", "1", "--yes"]))
+            .code !== 0) {
+            return gate("`fly volumes create` failed — see the flyctl output above");
+        }
+    }
+    // 5. Secrets — staged (no deploy yet; we deploy with fly.toml next). Values over stdin, not argv.
+    const keys = Object.keys(plan.secrets);
+    if (keys.length > 0) {
+        log(`setting ${keys.length} secret(s): ${keys.join(", ")}`);
+        const input = `${keys.map((k) => `${k}=${plan.secrets[k]}`).join("\n")}\n`;
+        if ((await fly(["secrets", "import", "--stage", "-a", plan.appName], { input })).code !== 0) {
+            return gate("`fly secrets import` failed — see the flyctl output above");
+        }
+    }
+    // 6. Deploy — remote builder (no local Docker), one machine.
+    log("deploying (remote build)…");
+    if ((await fly(["deploy", "-a", plan.appName, "-c", plan.flyConfig, "--remote-only", "--yes", "--ha=false"])).code !== 0) {
+        return gate("`fly deploy` failed — see the flyctl output above; fix and re-run");
+    }
+    // 7. Post-deploy webhook — telegram end-to-end (fastagent has the token + the live URL); github is a
+    //    repo-settings step only a human can do.
+    if (plan.channels.includes("telegram")) {
+        log("registering telegram webhook…");
+        await registerTelegram(`https://${plan.appName}.fly.dev`);
+    }
+    if (plan.channels.includes("github")) {
+        log(`github: set the webhook in the repo (Settings → Webhooks) → https://${plan.appName}.fly.dev/webhook`);
+    }
+    return { ok: true };
+}

package/dist/deploy/preflight.d.ts

@@ -0,0 +1,59 @@
+import type { FastagentConfig } from "../engines/pi/config.ts";
+import { type ChannelKind } from "../scaffold/add-channel.ts";
+import { type ContainerInput } from "./container.ts";
+/** A stderr line the CLI prints (`[fastagent] warn: …` / `[fastagent] note: …`). Host-neutral advisories. */
+export interface DeployMessage {
+    level: "warn" | "note";
+    text: string;
+}
+/** The resolved facts every host plan needs (the container shape, channels, model auth, ports/secrets). */
+export interface DeployFacts {
+    messages: DeployMessage[];
+    channels: ChannelKind[];
+    /** Whether the agent has TIME triggers — `schedules/` files or `selfSchedule` (the wake tool). Cron/wake
+     *  has no external wake-up, so the deployment must keep one machine running: the fly plan forces
+     *  `min_machines_running=1`, the railway runbook forbids App Sleeping. */
+    hasTimeTriggers: boolean;
+    /** What satisfies model auth locally ({@link probeAuthSource}) — an env-var name, an OAuth/stored label,
+     *  or undefined. Drives the runbook's secret guidance and `--run`'s credential carry. */
+    modelAuth: string | undefined;
+    /** The project-level auth file `--run` reads to carry the credential (probed with the same path). */
+    authPath: string;
+    /** Container facts shared by the plan and the generated Dockerfile — ONE source, so they can't drift. */
+    container: ContainerInput;
+    port: number;
+    extraSecrets: string[];
+}
+/** Done (facts for the host branch), or a hard gate the CLI stops on (a model that won't reach the box). */
+export type DeployPreflight = {
+    ok: false;
+    gate: string;
+} | ({
+    ok: true;
+} & DeployFacts);
+/**
+ * Run the host-neutral pre-flight. Throws on a real fault (an unreadable channels/ dir, a throwing
+ * provider) — the CLI wraps the call in its `failStartup` so the fault surfaces and exits, never silently.
+ */
+export declare function preflightDeploy(input: {
+    target: string;
+    /** The agent-definition dir (config.agentDir resolved against target; = target when unset) — where
+     *  channels are discovered. Container facts (package.json/lockfile) still read `target`, the run root. */
+    agentDir: string;
+    config: FastagentConfig;
+    modelSpec: string | undefined;
+    /** `--run` fully deploys, so a model that won't travel is a GATE (a known crash-loop); else it warns. */
+    run: boolean;
+    /** `--force` regenerates artifacts, so the kept-hand-written-Dockerfile apt warning does not apply. */
+    force: boolean;
+    /** `--auth-path` / `FASTAGENT_AUTH_PATH`; falls back to the project default `<state root>/auth.json`. */
+    authPathOverride: string | undefined;
+}): Promise<DeployPreflight>;
+/**
+ * Why the resolved model won't reach the deployed box, or undefined if it will — host-neutral. `fastagent.config.ts`
+ * is the model's committed home (config's charter: model / tools / http) and the only source deploy ships:
+ * a `--model`/`FASTAGENT_MODEL`/`.env` value is builder-local and doesn't travel (`.env` is dockerignored),
+ * so a model NOT in config crash-loops the box with "missing model". The pre-flight warns (runbook) or gates
+ * (`--run`). Single source on purpose — a host env block (fly.toml `[env]`) is NOT advertised as a second home.
+ */
+export declare function modelTravelIssue(configModel: string | undefined, modelSpec: string | undefined): string | undefined;

package/dist/deploy/preflight.js

@@ -0,0 +1,191 @@
+/**
+ * The host-NEUTRAL deploy pre-flight: everything `fastagent deploy <host>` computes and checks BEFORE
+ * the host branch (fly.ts / railway.ts). Model-travel gate, channel discovery, model-auth probe, the
+ * container facts + their warnings, and the hand-written-Dockerfile apt warning are identical on every
+ * host — so they live here, out of the CLI dispatcher, testable in isolation (call it against a temp dir
+ * and assert the gate / messages / facts). The CLI stays thin: run this, print the messages, branch by host.
+ *
+ * It returns messages rather than printing them (the CLI owns stderr) and a `{ ok }` outcome mirroring
+ * the run modules' {@link import("./fly/run.ts").FlyRunOutcome}: a model that won't travel is a GATE the
+ * CLI stops on, distinct from the advisory warnings/notes it prints and proceeds past.
+ */
+import { readFile } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { defaultAuthPath, resolveStateRoot } from "../engines/pi/config.js";
+import { discoverChannelFiles } from "../engines/pi/channel.js";
+import { discoverScheduleFiles } from "../schedule/discover.js";
+import { createPiModels, probeAuthSource } from "../engines/pi/models.js";
+import { CHANNEL_KINDS } from "../scaffold/add-channel.js";
+import { exists } from "../scaffold/init.js";
+import { detectRuntime, readPackageJson } from "../runtime.js";
+import { fastagentVersion } from "../version.js";
+import { isGeneratedDockerfile } from "./container.js";
+/**
+ * Run the host-neutral pre-flight. Throws on a real fault (an unreadable channels/ dir, a throwing
+ * provider) — the CLI wraps the call in its `failStartup` so the fault surfaces and exits, never silently.
+ */
+export async function preflightDeploy(input) {
+    const { target, agentDir, config, modelSpec, run, force, authPathOverride } = input;
+    const messages = [];
+    // The deployed box resolves the model from fastagent.config.ts ONLY (in the image); a model set via
+    // env/flag/.env doesn't travel. `--run` would ship a known crash-loop — hard gate; generate-only warns.
+    const modelIssue = modelTravelIssue(config.model, modelSpec);
+    if (modelIssue) {
+        if (run)
+            return { ok: false, gate: modelIssue };
+        messages.push({ level: "warn", text: modelIssue });
+    }
+    // Known channel kinds only — a custom channel's secrets/webhook are unknown to us; note and let the
+    // author wire them.
+    const discovered = await discoverChannelFiles(agentDir);
+    const channels = discovered.filter((c) => CHANNEL_KINDS.includes(c));
+    for (const c of discovered) {
+        if (!channels.includes(c)) {
+            messages.push({ level: "note", text: `channel "${c}" is custom — set its secrets and webhook yourself` });
+        }
+    }
+    // Time triggers (static schedules or self-scheduling) need a machine kept running — unlike a webhook,
+    // nothing external wakes a scale-to-zero box for a cron instant or a wake-up. The note is CONDITIONAL
+    // ("the generated plan…"): in KEEP mode an existing fly.toml is not rewritten — the CLI warns separately
+    // when a kept fly.toml still scales to zero.
+    const hasTimeTriggers = (await discoverScheduleFiles(agentDir)).length > 0 || !!config.selfSchedule;
+    if (hasTimeTriggers) {
+        messages.push({
+            level: "note",
+            text: `schedules/self-scheduling present — a GENERATED plan keeps one machine running (cron/wake has ` +
+                `no external wake-up; scale-to-zero would sleep through them).`,
+        });
+    }
+    // Probe auth from the SAME project-level file the opener/login use — not the global default, which would
+    // miss a `fastagent login` credential and falsely report "none configured".
+    const authPath = authPathOverride ?? defaultAuthPath(resolveStateRoot(target));
+    const modelAuth = modelSpec ? await probeAuthSource(createPiModels({ authPath }), modelSpec) : undefined;
+    // Container facts (shared by every host) + the warnings that follow. Repo-as-workspace layout
+    // (agentDir ≠ target): the facts describe the KIT — its package.json/runtime/lockfile drive the
+    // image's install step — never the host repo's (whose manifest belongs to the host's own deploy).
+    // POSIX-normalized: kitDir lands verbatim in Dockerfile COPY/CMD lines and fly/railway commands,
+    // which all require forward slashes (a Windows `relative()` would emit backslashes).
+    const kitDir = agentDir === target ? undefined : relative(target, agentDir).split(sep).join("/");
+    const factsDir = kitDir ? agentDir : target;
+    if (kitDir && run) {
+        // Generate + runbook fully support the layout; the fly/railway --run drivers do not yet (their
+        // command sequences assume root artifacts). Fail at the gate, not mid-drive.
+        return {
+            ok: false,
+            gate: `--run is not yet supported for the agentDir layout — run the same deploy without --run and follow the printed runbook`,
+        };
+    }
+    const hasPackageJson = await exists(join(factsDir, "package.json"));
+    const pkg = await readPackageJson(factsDir);
+    const { runtime, bunVersion, hasLockfile } = detectRuntime(factsDir, pkg);
+    const install = runtime === "bun" ? "bun install" : "npm install";
+    const runner = runtime === "bun" ? "bun run fastagent" : "./node_modules/.bin/fastagent";
+    const hasOtherLock = runtime === "node" &&
+        ((await exists(join(factsDir, "pnpm-lock.yaml"))) || (await exists(join(factsDir, "yarn.lock"))));
+    if (kitDir) {
+        // After the facts: the deps sentence must match the kit's actual shape (a markdown-only kit has no
+        // package.json and installs nothing — the note must not point at a file that doesn't exist).
+        const deps = hasPackageJson
+            ? `only the kit's deps (${kitDir}/package.json) are installed — the host repo's own deps are the agent's runtime concern`
+            : `the kit has no package.json, so no deps are installed (the pinned global CLI serves the repo)`;
+        messages.push({
+            level: "note",
+            text: `repo-as-workspace image (EXPERIMENTAL — not yet verified end-to-end on a real host): the whole ` +
+                `repo is baked as the agent's cwd; ${deps}. Un-pushed changes on the box do not survive a redeploy ` +
+                `(the image is a snapshot); write-back goes through git (persona owns the policy; GH_TOKEN etc. go ` +
+                `in config.deploy.secrets — see the runbook's caveat on .git surviving the host's upload).`,
+        });
+    }
+    // A code workspace with no lockfile builds via a non-frozen install (ranges resolve at build time) — not
+    // reproducible. A pnpm/yarn user gets an accurate message (their lockfile is ignored by the npm Dockerfile).
+    if (hasPackageJson && !hasLockfile) {
+        const lock = runtime === "bun" ? "bun.lock" : "package-lock.json";
+        messages.push({
+            level: "warn",
+            text: hasOtherLock
+                ? `the generated Dockerfile is npm-based — your pnpm/yarn lockfile is NOT used (build runs ` +
+                    `\`npm install\`, not reproducible). Edit the Dockerfile for your package manager, or vendor a package-lock.json.`
+                : `no ${lock} — the image build resolves deps at build time (not reproducible). ` +
+                    `Run \`${install}\` and commit the lockfile for pinned redeploys.`,
+        });
+    }
+    // The code-path Dockerfile runs `${runner}` — the workspace's OWN local dependency, never the
+    // registry — so a package.json missing it means the container fails at start (no bin to run).
+    if (hasPackageJson && !("@fastagent-sh/fastagent" in { ...pkg.dependencies, ...pkg.devDependencies })) {
+        messages.push({
+            level: "warn",
+            text: `package.json does not list @fastagent-sh/fastagent — the image's \`${runner}\` has no local bin to run, ` +
+                `so the container fails at start. Add it to dependencies and re-run \`${install}\`.`,
+        });
+    }
+    // A kept host root .dockerignore silently replaces KIT_DOCKERIGNORE's two protections — read it and
+    // warn SPECIFICALLY (the generic "kept" line suggests --force, which would clobber the host's file):
+    // (a) a .git exclude kills the baked write-back (the runtime-clone fallback applies); (b) without a
+    // recursive **/node_modules the build machine's kit deps (native binaries) clobber the image's.
+    // Not force-gated: the host's root .dockerignore is kept even under --force (never ours to clobber),
+    // so these warnings apply regardless.
+    if (kitDir && (await exists(join(target, ".dockerignore")))) {
+        const lines = (await readFile(join(target, ".dockerignore"), "utf8")).split("\n").map((l) => l.trim());
+        if (lines.some((l) => l === ".git" || l === "/.git" || l === ".git/" || l === "**/.git")) {
+            messages.push({
+                level: "warn",
+                text: `your .dockerignore excludes .git — the baked repo ships WITHOUT history/remote, so the agent ` +
+                    `cannot commit/push the baked copy; it must \`git clone\` its repo in the workspace instead ` +
+                    `(or remove the .git line).`,
+            });
+        }
+        if (!lines.some((l) => l === "**/node_modules" || l === "**/node_modules/")) {
+            messages.push({
+                level: "warn",
+                text: `your .dockerignore lacks \`**/node_modules\` — the build machine's ${kitDir}/node_modules ` +
+                    `(native binaries for YOUR OS) would be uploaded and clobber the image's freshly-installed ones. ` +
+                    `Add \`**/node_modules\` to it.`,
+            });
+        }
+    }
+    // Write-back mechanics are fastagent's (the policy is the persona's): a kit-layout image always
+    // carries git, so commit/push can work at all. Merged with (never duplicating) config.deploy.apt.
+    const apt = kitDir ? [...new Set(["git", ...(config.deploy?.apt ?? [])])] : config.deploy?.apt;
+    const container = {
+        hasPackageJson,
+        runtime,
+        bunVersion,
+        hasLockfile,
+        version: await fastagentVersion(),
+        apt,
+        kitDir,
+    };
+    const port = config.http?.port ?? 8787;
+    // What the agent declared it needs on the box (fastagent.config deploy.secrets) — carried like channel
+    // secrets: listed in the runbook, set from the local env under --run, gated if a value is missing.
+    const extraSecrets = config.deploy?.secrets ?? [];
+    // deploy.apt only shapes the GENERATED Dockerfile. Warn ONLY when the kept Dockerfile is HAND-WRITTEN
+    // (its apt won't include these) — a fastagent-generated one is handled by writeArtifacts. Don't suggest
+    // --force here: it would overwrite the user's hand-written file.
+    const dockerfileHome = kitDir ? join(agentDir, "Dockerfile") : join(target, "Dockerfile");
+    if (config.deploy?.apt?.length && !force && (await exists(dockerfileHome))) {
+        if (!isGeneratedDockerfile(await readFile(dockerfileHome, "utf8"))) {
+            messages.push({
+                level: "warn",
+                text: `kept your hand-written Dockerfile — deploy.apt (${config.deploy.apt.join(", ")}) is ` +
+                    `NOT applied; install those packages in your Dockerfile.`,
+            });
+        }
+    }
+    return { ok: true, messages, channels, hasTimeTriggers, modelAuth, authPath, container, port, extraSecrets };
+}
+/**
+ * Why the resolved model won't reach the deployed box, or undefined if it will — host-neutral. `fastagent.config.ts`
+ * is the model's committed home (config's charter: model / tools / http) and the only source deploy ships:
+ * a `--model`/`FASTAGENT_MODEL`/`.env` value is builder-local and doesn't travel (`.env` is dockerignored),
+ * so a model NOT in config crash-loops the box with "missing model". The pre-flight warns (runbook) or gates
+ * (`--run`). Single source on purpose — a host env block (fly.toml `[env]`) is NOT advertised as a second home.
+ */
+export function modelTravelIssue(configModel, modelSpec) {
+    if (configModel)
+        return undefined;
+    return modelSpec
+        ? `model "${modelSpec}" is set via --model/FASTAGENT_MODEL, not fastagent.config.ts — it won't reach ` +
+            `the deployed box. Add \`model: "${modelSpec}"\` to fastagent.config.ts.`
+        : `no model in fastagent.config.ts — the deployed box can't resolve one. Add \`model: "provider/id"\`.`;
+}

package/dist/deploy/railway/plan.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `fastagent deploy railway` — the Railway deploy PLAN, computed from the resolved definition. Pure:
+ * facts in, artifact contents + an ordered runbook out; the CLI writes the files and prints the runbook.
+ *
+ * Railway is the second target, and it is NOT a copy of Fly — three asymmetries drive this module:
+ *
+ *  1. The config file is thin. `railway.json` (config-as-code) holds ONLY build/deploy settings; the
+ *     volume, the variables (state root + secrets), and App Sleeping are Railway service settings applied
+ *     by CLI/dashboard, not the file. So Fly's "one committed file is the single source" does not carry:
+ *     Railway's source of truth is the linked project's platform state, not a file we generate.
+ *
+ *  2. Scale-to-zero is not scriptable. Railway's App Sleeping is a dashboard-only toggle (no CLI/API),
+ *     so unlike Fly's `auto_stop_machines`, we cannot generate it — the runbook states the manual step.
+ *     This is a real capability downgrade vs Fly, named rather than hidden.
+ *
+ *  3. The public URL is minted, not deterministic. Fly gives `<app>.fly.dev` up front; Railway mints a
+ *     `*.up.railway.app` domain that must be read back (`railway domain`), so the webhook step points at
+ *     "the domain from `railway domain`" rather than a precomputed URL.
+ *
+ * What IS shared with Fly comes from the neutral modules: the container (Dockerfile + .dockerignore) and
+ * the required-secret list. `railway.json`'s `healthcheckPath=/health` also fixes the "routed before the
+ * server is listening" boot race Fly's deploy hit — Railway only routes once /health passes.
+ */
+import type { ChannelKind } from "../../scaffold/add-channel.ts";
+import { type Artifact, type ContainerInput } from "../container.ts";
+export interface RailwayPlanInput extends ContainerInput {
+    /** The service name to create (`railway add --service`). Railway service names are project-scoped, not
+     *  globally unique (unlike a Fly app), so the CLI derives it from the dir basename — any value works. */
+    serviceName: string;
+    /** What satisfies model auth locally: an env-var name, an OAuth/stored label, or undefined. */
+    modelAuth: string | undefined;
+    /** Channels discovered in the workspace — each contributes its required secrets + webhook step. */
+    channels: ChannelKind[];
+    /** Extra secret env-var names (fastagent.config deploy.secrets) — added to the runbook's secret list. */
+    extraSecrets?: string[];
+    /** Time triggers present (schedules/ or selfSchedule) — the runbook forbids App Sleeping: cron/wake has
+     *  no external wake-up, so a sleeping service sleeps through them. Required (like FlyPlanInput's) so a
+     *  caller can't silently omit it and degrade the sleeping guidance to "optional". */
+    hasTimeTriggers: boolean;
+}
+export interface RailwayPlan {
+    /** railway.json / Dockerfile / .dockerignore — written by the CLI (skipped if present unless --force). */
+    artifacts: Artifact[];
+    /** The ordered, values-resolved deploy runbook — printed to stdout for the coding agent to execute. */
+    runbook: string[];
+}
+/** Compute the Railway deploy plan from the resolved definition. */
+export declare function planRailwayDeploy(input: RailwayPlanInput): RailwayPlan;

package/dist/deploy/railway/plan.js

@@ -0,0 +1,91 @@
+import { containerArtifacts } from "../container.js";
+import { isEnvKey, requiredSecrets } from "../secrets.js";
+/** State root = the volume mount path, kept in lockstep. `/data` matches the Fly recipe. */
+const MOUNT = "/data";
+/** railway.json — build/deploy only (Railway's config-as-code scope). No env/volume/sleeping here: those
+ *  are service settings the runbook applies via CLI. healthcheckPath gates routing on a live server. */
+function railwayJson(kitDir) {
+    return `${JSON.stringify({
+        $schema: "https://railway.com/railway.schema.json",
+        // dockerfilePath is relative to the repo root (`railway up`'s upload context) in BOTH layouts.
+        build: { builder: "DOCKERFILE", dockerfilePath: kitDir ? `${kitDir}/Dockerfile` : "Dockerfile" },
+        deploy: { healthcheckPath: "/health", restartPolicyType: "ON_FAILURE" },
+    }, null, 2)}\n`;
+}
+/** Compute the Railway deploy plan from the resolved definition. */
+export function planRailwayDeploy(input) {
+    const { serviceName, modelAuth, channels } = input;
+    // Kit layout: railway.json is namespaced under the kit too (the host repo may carry its own
+    // railway.toml/json for the product). Railway reads config-as-code from the repo root by default,
+    // so the runbook adds the dashboard step that points the service at the kit's file (no CLI flag exists).
+    const configPath = input.kitDir ? `${input.kitDir}/railway.json` : "railway.json";
+    const artifacts = [
+        { path: configPath, content: railwayJson(input.kitDir) },
+        ...containerArtifacts(input),
+    ];
+    const secrets = requiredSecrets(modelAuth, channels, input.extraSecrets);
+    // Order matters, not cosmetics: `railway init` creates a PROJECT with no service, but the volume and
+    // variables are service-scoped and `railway up` deploys THE service — so the service must exist first
+    // (`railway add --service`), and variables must be set BEFORE the first `up` or the box boots without a
+    // model key / FASTAGENT_STATE_DIR and crash-loops against restartPolicy ON_FAILURE + the healthcheck.
+    const runbook = [
+        `# Deploy to Railway. ${configPath} / Dockerfile(.dockerignore) are generated above.`,
+        `# Prereqs: the Railway CLI (https://docs.railway.com/guides/cli) and \`railway login\`.`,
+        ``,
+        `# One-time setup (init → service → volume → variables). SKIP all of it on a redeploy — a redeploy is`,
+        `# just \`railway up\` (below). Re-running these makes a second project, a DUPLICATE service (Railway`,
+        `# service names are project-scoped, NOT unique — no error), and another volume, splitting state.`,
+        ``,
+        `# Create + link a project (writes .railway link state in this dir; the project — not a committed`,
+        `# file — is Railway's source of truth for identity, variables, and the volume).`,
+        `railway init            # or \`railway link\` to attach an existing project`,
+        ``,
+        `# Create the service. \`railway init\` makes only a project; the volume/variables below are`,
+        `# service-scoped and \`railway up\` deploys THIS service. \`add\` auto-links it to this directory, so`,
+        `# the later commands resolve it without --service (--run passes --service to stay non-interactive).`,
+        `railway add --service ${serviceName}`,
+        ``,
+        `# Persistent volume at ${MOUNT} — sessions, auth, channel state. FASTAGENT_STATE_DIR is set to match.`,
+        `railway volume add --mount-path ${MOUNT}`,
+        ``,
+        `# Variables — set BEFORE the first deploy so the box boots with them. Railway injects PORT itself.`,
+        `railway variables set FASTAGENT_STATE_DIR=${MOUNT}`,
+    ];
+    if (secrets.length > 0) {
+        runbook.push(`#   ${secrets.map((s) => `${s.name}: ${s.hint}`).join("\n#   ")}`, `railway variables set ${secrets.map((s) => `${s.name}=<value>`).join(" ")}`);
+    }
+    // Model-auth guidance: an env key becomes a variable above. Otherwise the plan can't read the local
+    // credential's value (OAuth or a stored key) to set it — same wording discipline as the Fly plan.
+    if (!isEnvKey(modelAuth)) {
+        runbook.push(modelAuth === undefined
+            ? `# Model auth: none found at the local auth path — a global \`fastagent login\` isn't read here; pass --auth-path <file> (e.g. ~/.fastagent/auth.json), or \`--run\` carries it automatically.`
+            : `# Model auth: your local auth is "${modelAuth}" — the plan can't read its value to set as a variable.`, `#   Set your provider API key as a variable (railway variables set KEY=...), OR place auth.json on the ${MOUNT} volume.`);
+    }
+    if (input.kitDir) {
+        runbook.push(``, `# Repo-as-workspace: point the service at the kit's config file BEFORE the first deploy —`, `# dashboard-only, like App Sleeping (no CLI flag): Service → Settings → Config-as-code →`, `# set the file path to ${configPath}. Without it Railway would read the repo root's own config.`);
+    }
+    runbook.push(``, `# Deploy — uploads this dir and builds the Dockerfile on Railway (no local Docker needed). This is`, `# also the ENTIRE redeploy: re-run \`railway up\` alone (the one-time setup above is not repeated).`, `railway up`);
+    if (input.kitDir) {
+        runbook.push(``, `# Write-back mechanics: git ships in the image and GH_TOKEN-style creds ride config.deploy.secrets;`, `# the POLICY (push vs PR, identity, remote) lives in persona.md. CAVEAT — \`railway up\` is known to`, `# strip .git from its upload, so expect NO baked history on the box: the agent should \`git clone\``, `# its repo in the workspace (same token) before making changes. Un-pushed changes never survive a`, `# redeploy — the image is a snapshot; durability lives in git.`);
+    }
+    // The public URL is minted, not deterministic (unlike Fly's <app>.fly.dev) — ONE mint step, then each
+    // channel's webhook uses that domain (mint once even when both channels are present).
+    if (channels.includes("telegram") || channels.includes("github")) {
+        runbook.push(``, `# Public URL — Railway mints a *.up.railway.app domain (NOT deterministic). Generate it, then read`, `# the printed https URL and use it as <your-domain> in the webhook step(s) below:`, `railway domain`);
+    }
+    if (channels.includes("telegram")) {
+        runbook.push(`# Register the Telegram webhook (default route POST /telegram; if you remapped it in`, `# channels/telegram.ts, use your path). secret_token MUST equal TELEGRAM_SECRET_TOKEN:`, `curl "https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/setWebhook" \\`, `  -d url=https://<your-domain>/telegram -d secret_token=<TELEGRAM_SECRET_TOKEN>`);
+    }
+    if (channels.includes("github")) {
+        runbook.push(`# Set the GitHub webhook (repo Settings → Webhooks). Default route POST /webhook; if you remapped it`, `# in channels/github.ts, use your path:`, `#   Payload URL = https://<your-domain>/webhook, content type application/json, secret = GITHUB_WEBHOOK_SECRET`);
+    }
+    // Scale-to-zero: App Sleeping is dashboard-only (no CLI/API) — a manual step, not a generated setting.
+    // A github channel should NOT enable it: fire-and-forget reviews have no replay (unlike Telegram's L1
+    // turn store), so a sleep mid-review would drop it — the same floor the Fly plan enforces via config.
+    runbook.push(``, channels.includes("github")
+        ? `# Scale-to-zero: do NOT enable App Sleeping — github turns have no replay, a sleep mid-review is lost.`
+        : input.hasTimeTriggers
+            ? `# Scale-to-zero: do NOT enable App Sleeping — schedules/wake-ups have no external wake-up; a sleeping service sleeps through them.`
+            : `# Scale-to-zero (optional, dashboard-only — no CLI/API): Settings → Deploy → Serverless → App Sleeping.`, `# Keep this a SINGLE service: the ${MOUNT} volume is tied to one service; extra replicas split state.`);
+    return { artifacts, runbook };
+}

package/dist/deploy/railway/run.d.ts

@@ -0,0 +1,81 @@
+/**
+ * `fastagent deploy railway --run` — drive the Railway CLI to completion. The middle of the deploy the
+ * plain runbook hands to the operator; `--run` executes it so a coding agent runs ONE command.
+ *
+ * Railway's model forces differences from the Fly runner (fly/run.ts), all validated against CLI 5.15.0:
+ *
+ *  - **`--run` PROVISIONS a project and only runs on an UNLINKED directory** — so it can never deploy
+ *    into a project it didn't create. `railway init` isn't check-then-act (it ALWAYS makes a new project)
+ *    and `railway status` exits 0 even when unlinked (linkedness is read from stdout: JSON when linked,
+ *    empty when not). We do NOT track ownership: a pre-existing link is refused (Railway has no globally
+ *    unique name to give free identity like Fly's app name, and synthesizing one — a machine-local marker
+ *    — was a large, bug-prone premature optimization). The only "yes, this project" signal is the operator's
+ *    explicit `--into-linked`, which provisions INTO the linked project; a routine redeploy is just
+ *    `railway up`. The volume is check-then-act, so `--into-linked` (or a create that failed at volume-add) still gets it.
+ *  - **Every command needs `--service` explicitly** to stay non-interactive (a bare command prompts to
+ *    pick a service). `railway volume add` is the exception — it has NO `--service` flag and rides the
+ *    linked service, so the service must be created (and thus linked) first.
+ *  - **The public URL is minted, not deterministic** — bare `railway domain --json` returns the service
+ *    domain (minting one if absent), read for the webhook. We avoid the newer `domain list` subcommand:
+ *    on a CLI without it, `railway domain list` registers a bogus custom domain named "list" (destructive).
+ *
+ * Secrets go in one-per-`variable set --stdin` (value on stdin, never argv/process listing — Railway has
+ * no bulk stdin import like Fly's `secrets import`). Auth needs an ACCOUNT credential (login or
+ * `RAILWAY_API_KEY`), not a project token: `init` creates a project that a project token can't predate.
+ */
+import type { ChannelKind } from "../../scaffold/add-channel.ts";
+import type { CliRunner } from "../runner.ts";
+export interface RailwayRunPlan {
+    /** Names both the project (`railway init --name`) and the service (`railway add --service`). Railway
+     *  names are project-scoped, not globally unique — the CLI derives it from the dir basename. */
+    name: string;
+    /** The volume mount path AND `FASTAGENT_STATE_DIR` (kept in lockstep). `/data`, matching the Fly recipe. */
+    mountPath: string;
+    /** `KEY=value` secrets set one-per-`variable set --stdin`: model key (env auth) or `FASTAGENT_AUTH_SEED`
+     *  (file auth) + channel secrets. Never on argv. */
+    secrets: Record<string, string>;
+    /** Required secret names with NO local value — the run gates on these before any side effect. */
+    missingSecrets: string[];
+    channels: ChannelKind[];
+    /** Opt-in (CLI `--into-linked`) to provision INTO the project this directory is already linked to. Off
+     *  by default so `--run` only creates on an unlinked dir and never deploys into a pre-existing (possibly
+     *  unrelated/production) project; the flag is the operator's explicit "yes, this project". */
+    intoLinked: boolean;
+}
+/** Done (with the live URL), or a gate the operator must clear before re-running (printed + non-zero
+ *  exit by the CLI). */
+export type RailwayRunOutcome = {
+    ok: true;
+    url: string;
+} | {
+    ok: false;
+    gate: string;
+};
+/**
+ * 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 declare function isLinked(stdout: string): boolean;
+/** 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 declare function linkedName(stdout: string): string | undefined;
+/**
+ * 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 declare function parseDomainUrl(stdout: string): string | 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 declare function parseHasVolume(stdout: string, mountPath: string): boolean;
+/**
+ * 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 declare function deployRailwayRun(plan: RailwayRunPlan, railway: CliRunner, log: (msg: string) => void, registerTelegram: (baseUrl: string) => Promise<void>): Promise<RailwayRunOutcome>;