@fastagent-sh/fastagent 0.21.1 → 0.22.0

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

@@ -1,43 +1,24 @@
-/**
- * `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.
- */
+/** `fastagent deploy railway` — the Railway deploy PLAN, computed from the resolved definition. */
 import type { DeclaredChannel } from "../../channels/discover.ts";
 import { type Artifact, type ContainerInput } from "../container.ts";
+import { type DeploymentSecret } from "../secrets.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. */
+    /** The service name to create (`railway add --service`). */
     serviceName: string;
     /** What satisfies model auth locally: an env-var name, an OAuth/stored label, or undefined. */
     modelAuth: string | undefined;
-    /** Every declared channel and its ingress — the source of the secret list, the webhook steps, and
-     *  whether App Sleeping must stay off for an outbound connection. */
+    /**
+     * Every declared channel and its ingress — the source of the secret list, the webhook steps, and whether App
+     * Sleeping must stay off for an outbound connection.
+     */
     channels: readonly DeclaredChannel[];
-    /** 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;
+    /**
+     * The runbook's variable list (`deploymentSecrets`): what must have a value, then everything else the value file
+     * carries.
+     */
+    secrets?: readonly DeploymentSecret[];
+    /** `routines/` declares a cron — one of the things that forbids App Sleeping (deploy/residency.ts). */
+    hasCron: boolean;
 }
 export interface RailwayPlan {
     /** railway.json / Dockerfile / .dockerignore — written by the CLI (skipped if present unless --force). */
@@ -45,17 +26,10 @@ export interface RailwayPlan {
     /** The ordered, values-resolved deploy runbook — printed to stdout for the coding agent to execute. */
     runbook: string[];
 }
-/** The `RAILWAY_DOCKERFILE_PATH` value for an agent under `prefix` — repo-root-anchored with a leading
- *  slash, the form Railway's builds/dockerfiles docs use for a Dockerfile in another directory. The
- *  config file's `dockerfilePath` spells it WITHOUT the slash (the config-as-code schema's own
- *  convention); two mechanisms, two documented spellings, one fact each. */
+/** The `RAILWAY_DOCKERFILE_PATH` value for an agent under `prefix`. */
 export declare const dockerfilePathVar: (prefix: string) => string;
-/** The name this tool gives BOTH the project and the service, derived from the workspace directory.
- *  Railway names are project-scoped (not globally unique like a Fly app), so this only has to survive
- *  the command — slug anything that would break `railway add --service <name>`, and name the fallback
- *  rather than emitting an empty argument. Shared so the live probe tears down what the CLI creates. */
+/** The name this tool gives BOTH the project and the service, derived from the workspace directory. */
 export declare function toRailwayName(basename: string): string;
-/** Did fastagent generate this `railway.json`? Unparseable or unmarked reads as the author's. */
 export declare function isGeneratedRailwayJson(content: string): boolean;
 /** Compute the Railway deploy plan from the resolved definition. */
 export declare function planRailwayDeploy(input: RailwayPlanInput): RailwayPlan;

package/dist/deploy/railway/plan.js

@@ -1,25 +1,18 @@
 import { webhookRunbook } from "../channel-ingress.js";
 import { containerArtifacts } from "../container.js";
-import { deploymentSecrets, isEnvKey } from "../secrets.js";
-/** State root = the volume mount path, kept in lockstep. `/data` matches the Fly recipe. */
+import { CRON_CAN_BE_EXTERNAL, WAKEUPS_WHEN_ASLEEP, residencyFor } from "../residency.js";
+import { isEnvKey } from "../secrets.js";
+/** State root = the volume mount path, kept in lockstep. */
 const MOUNT = "/data";
-/** The `RAILWAY_DOCKERFILE_PATH` value for an agent under `prefix` — repo-root-anchored with a leading
- *  slash, the form Railway's builds/dockerfiles docs use for a Dockerfile in another directory. The
- *  config file's `dockerfilePath` spells it WITHOUT the slash (the config-as-code schema's own
- *  convention); two mechanisms, two documented spellings, one fact each. */
+/** The `RAILWAY_DOCKERFILE_PATH` value for an agent under `prefix`. */
 export const dockerfilePathVar = (prefix) => `/${prefix}Dockerfile`;
-/** The name this tool gives BOTH the project and the service, derived from the workspace directory.
- *  Railway names are project-scoped (not globally unique like a Fly app), so this only has to survive
- *  the command — slug anything that would break `railway add --service <name>`, and name the fallback
- *  rather than emitting an empty argument. Shared so the live probe tears down what the CLI creates. */
+/** The name this tool gives BOTH the project and the service, derived from the workspace directory. */
 export function toRailwayName(basename) {
     return basename.replace(/[^a-zA-Z0-9-]+/g, "-").replace(/^-+|-+$/g, "") || "agent";
 }
-/** railway.json is JSON, so its ownership marker is a KEY rather than a comment line. Railway ignores
- *  unknown keys; the predicate below is what lets `--force` reset OUR file and keep a hand-written one. */
+/** railway.json is JSON, so its ownership marker is a KEY rather than a comment line. */
 const GENERATED_RAILWAY_KEY = "x-generated-by";
 const GENERATED_RAILWAY_VALUE = "fastagent deploy railway";
-/** Did fastagent generate this `railway.json`? Unparseable or unmarked reads as the author's. */
 export function isGeneratedRailwayJson(content) {
     try {
         return JSON.parse(content)[GENERATED_RAILWAY_KEY] === GENERATED_RAILWAY_VALUE;
@@ -28,8 +21,7 @@ export function isGeneratedRailwayJson(content) {
         return false;
     }
 }
-/** 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. */
+/** railway.json — build/deploy only (Railway's config-as-code scope). */
 function railwayJson(prefix) {
     return `${JSON.stringify({
         $schema: "https://railway.com/railway.schema.json",
@@ -42,31 +34,22 @@ function railwayJson(prefix) {
 /** Compute the Railway deploy plan from the resolved definition. */
 export function planRailwayDeploy(input) {
     const { serviceName, modelAuth, channels } = input;
-    // railway.json is namespaced under the agent dir too (the workspace may carry its own
-    // railway.toml/json for the product). Railway reads config-as-code from the repo root by default and
-    // pointing it at a custom path is DASHBOARD-ONLY — so the BUILD entry travels as the scriptable
-    // RAILWAY_DOCKERFILE_PATH service variable instead (Railway's documented non-root-Dockerfile route),
-    // and the config-as-code pointer degrades to an OPTIONAL enhancement: the /health gate (Railway's
-    // default restart policy already matches the file's ON_FAILURE).
+    // railway.json is namespaced under the agent dir too (the workspace may carry its own railway.toml/json for the
+    // product).
     const configPath = `${input.agentPrefix}railway.json`;
     const artifacts = [
         { path: configPath, content: railwayJson(input.agentPrefix) },
         ...containerArtifacts(input),
     ];
-    const secrets = deploymentSecrets(modelAuth, channels, input.extraSecrets);
-    const requiredSecrets = secrets.filter((secret) => secret.required);
-    const optionalSecrets = secrets.filter((secret) => !secret.required);
-    // 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 secrets = input.secrets ?? [];
+    // 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.
     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.`,
+        `# One-time setup (init → service → volume → variables). Skip it on redeploy: repeating it creates`,
+        `# another project/service/volume, splitting the persistent workspace.`,
         ``,
         `# 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).`,
@@ -85,44 +68,43 @@ export function planRailwayDeploy(input) {
         `# Railway's documented route to a non-root Dockerfile (no dashboard step needed for the build).`,
         `railway variables set FASTAGENT_STATE_DIR=${MOUNT}/.state FASTAGENT_SECRETS_DIR=${MOUNT}/.secrets RAILWAY_DOCKERFILE_PATH=${dockerfilePathVar(input.agentPrefix)}`,
     ];
-    if (requiredSecrets.length > 0) {
-        runbook.push(`# Required secrets:`, `#   ${requiredSecrets.map((s) => `${s.name}: ${s.hint}`).join("\n#   ")}`, `railway variables set ${requiredSecrets.map((s) => `${s.name}=<value>`).join(" ")}`);
+    if (secrets.length > 0) {
+        runbook.push(`# Secrets:`, `#   ${secrets.map((s) => `${s.name}: ${s.hint}`).join("\n#   ")}`, `railway variables set ${secrets.map((s) => `${s.name}=<value>`).join(" ")}`);
     }
-    if (optionalSecrets.length > 0) {
-        runbook.push(`# Optional secrets — set only when the matching feature is configured:`, `#   ${optionalSecrets.map((s) => `${s.name}: ${s.hint}`).join("\n#   ")}`, `# railway variables set ${optionalSecrets.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.
+    // Model-auth guidance: an env key becomes a variable above.
     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/.secrets/auth.json), or \`--run\` carries it automatically.`
+            ? `# Model auth: none found at the local auth path — a global \`fastagent login\` isn't read here; set FASTAGENT_AUTH_PATH (e.g. ~/.fastagent/.secrets/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.`);
     }
     runbook.push(``, `# OPTIONAL — the build already uses the agent's Dockerfile via RAILWAY_DOCKERFILE_PATH (set above),`, `# and Railway's default restart policy equals what ${configPath} declares (ON_FAILURE).`, `# Pointing the service at ${configPath} (Service → Settings → Config-as-code — dashboard-only) adds`, `# the /health healthcheck gate: a boot-crashing deploy is marked FAILED instead of going live dead.`, `# (Zero-downtime switching doesn't apply either way — the ${MOUNT} volume allows one active deployment.)`);
-    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.shipsGit) {
-        runbook.push(``, `# The image is a WYSIWYG snapshot of this directory. Freshness/durability run through git, driven`, `# by the agent itself (pull to freshen, commit/push to write back; creds ride config.deploy.secrets;`, `# git is baked into the image). CAVEAT — \`railway up\` is known to strip .git from its upload:`, `# 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 on the box never survive a redeploy; durability lives in git.`);
-    }
-    else {
-        runbook.push(``, `# The image is a WYSIWYG snapshot of this directory. No .git here, so no history ships and the`, `# generated image does not install git — changes on the box are ephemeral and never survive a`, `# redeploy. If the agent should clone/push repos as part of its work, add deploy: { apt: ["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).
-    // Mint only when something below needs it: with nothing to point at the domain (no channels, or only
-    // long-connection ones), "use it in the step(s) below" would refer to steps that do not follow.
+    runbook.push(``, `# Before a new definition release, run \`fastagent deploy railway\` to refresh the release manifest.`, `# Upload this workspace and build on Railway (no local Docker needed):`, `railway up`);
+    runbook.push(``, `# The volume keeps /data/base (including uncommitted work), .state and .secrets across restarts and deploys.`, `# Each generated release replaces only /data/base/${input.agentPrefix}; other workspace files are initialized once.`, input.shipsGit
+        ? `# Railway uploads may strip .git. Clone inside the persistent workspace when collaboration needs history.`
+        : `# To use Git for collaboration, add deploy: { apt: ["git"] }. Storage durability does not require Git.`);
+    // The public URL is minted, not deterministic (unlike Fly's <app>.fly.dev).
     const steps = webhookRunbook(`https://<your-domain>`, channels);
     if (steps.length > 0) {
         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`, ...steps);
     }
-    // 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.some((channel) => channel.name === "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.`
-            : channels.some((channel) => channel.ingress === "long-connection")
-                ? `# Scale-to-zero: do NOT enable App Sleeping — a long-connection channel must remain connected.`
-                : `# 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.`);
+    // Scale-to-zero: App Sleeping is dashboard-only (no CLI/API) — a manual step, not a generated setting. WHY it is
+    // forbidden is residency.ts's to decide; the SETTING and the path through the dashboard are Railway's.
+    const residency = residencyFor({ channels, hasCron: input.hasCron });
+    runbook.push(``, residency
+        ? `# Scale-to-zero: do NOT enable App Sleeping — ${residency.why}.`
+        : `# Scale-to-zero (optional, dashboard-only — no CLI/API): Settings → Deploy → Serverless → App Sleeping —\n# ${WAKEUPS_WHEN_ASLEEP}.`, ...(residency?.reason === CRON_CAN_BE_EXTERNAL
+        ? [
+            `# To sleep anyway: keep the time in a Railway CRON SERVICE (Settings -> Cron Schedule, >= 5 min) that`,
+            `# calls this service's \`POST /run\` over the private network — traffic from another service in the`,
+            `# project wakes a slept one. A cron service must EXIT, so it cannot be this service.`,
+            `#   set a variable on the cron service and curl it (Railway resolves the reference at deploy):`,
+            `#     AGENT_RUN=http://${serviceName}.railway.internal:\${{${serviceName}.PORT}}/run`,
+            `#     curl --retry 3 -fsS -X POST "$AGENT_RUN" -H 'content-type: application/json' -d '{"name":"<routine>"}'`,
+            `#   --retry because the FIRST request to a slept service may answer 502 (Railway documents it). The`,
+            `#   route has no dedup, so decide for yourself whether a retry that may duplicate work is what you want.`,
+            `# \`POST /run\` is an API, not a clock: read its contract — docs/api-reference.md#post-run.`,
+            `# Asleep, ${WAKEUPS_WHEN_ASLEEP}.`,
+        ]
+        : []), `# 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

@@ -1,59 +1,34 @@
-/**
- * `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_TOKEN`), not the project-scoped `RAILWAY_TOKEN`: `init` creates a project that a project
- * token can't predate.
- */
-import { type Registrars } from "../channel-ingress.ts";
+/** `fastagent deploy railway --run` — drive the Railway CLI to completion. */
+import { type PublicHealthProbe, type Registrars } from "../channel-ingress.ts";
 import type { DeclaredChannel } from "../../channels/discover.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. */
+    /** Names both the project (`railway init --name`) and the service (`railway add --service`). */
     name: string;
-    /** The volume mount path; `FASTAGENT_STATE_DIR`/`FASTAGENT_SECRETS_DIR` are set to `.state`/`.secrets`
-     *  under it (kept in lockstep). `/data`, matching the Fly recipe. */
+    /**
+     * The volume mount path; `FASTAGENT_STATE_DIR`/`FASTAGENT_SECRETS_DIR` are set to `.state`/`.secrets` under it (kept
+     * in lockstep).
+     */
     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. */
+    /**
+     * `KEY=value` secrets set one-per-`variable set --stdin`: the value file's variables + `FASTAGENT_AUTH_SEED` for a
+     * file credential.
+     */
     secrets: Record<string, string>;
-    /** Required secret names with NO local value — the run gates on these before any side effect. */
+    /** Declared names the value file supplies no value for — the run gates on these before any side effect. */
     missingSecrets: string[];
+    /** That value file, workspace-relative, so the gate names the file this deploy actually read. */
+    valueFile: string;
     /** Every declared channel and its ingress — the driver asks which of them have a webhook. */
     channels: readonly DeclaredChannel[];
-    /** 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". */
+    /** Opt-in (CLI `--into-linked`) to provision INTO the project this directory is already linked to. */
     intoLinked: boolean;
-    /** `RAILWAY_DOCKERFILE_PATH` value (`/fastagent/Dockerfile`) — Railway's service-variable route to a
-     *  non-root Dockerfile (builds/dockerfiles docs), set with the machinery variables BEFORE the first
-     *  `up` so the build never falls back to auto-detecting the workspace root. The config-as-code file
-     *  also carries the path, but pointing Railway at `fastagent/railway.json` is dashboard-only — the
-     *  variable is the scriptable way. */
+    /** `RAILWAY_DOCKERFILE_PATH` value (`/fastagent/Dockerfile`). */
     dockerfilePath: string;
 }
-/** Done (with the live URL), or a gate the operator must clear before re-running (printed + non-zero
- *  exit by the CLI). */
+/**
+ * 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;
@@ -61,33 +36,20 @@ export type RailwayRunOutcome = {
     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.
- */
+/** Whether `railway status --json` shows a linked project: non-empty stdout. */
 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).
+ * 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. */
 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; the injected {@link Registrars} perform
- * the post-deploy webhook steps from the builder machine (Slack's control credential never travels to
- * the host). A registrar the caller did not wire becomes the printed manual step. Every gate is
- * fail-visible.
+ * The status of the volume `railway volume list --json` shows mounted at `mountPath` ON `service`, or undefined when
+ * that service has none there. The list is the whole PROJECT's: another service's volume, or one a deleted service
+ * left behind (`serviceName: null` — deleting a service keeps its volume), sits at the same path and is not this
+ * one. Read from any object carrying `mountPath` and `serviceName`, so a wrapper key moving does not matter.
  */
-export declare function deployRailwayRun(plan: RailwayRunPlan, railway: CliRunner, log: (msg: string) => void, registrars: Registrars): Promise<RailwayRunOutcome>;
+export declare function volumeOn(stdout: string, service: string, mountPath: string): string | undefined;
+export declare function deployRailwayRun(plan: RailwayRunPlan, railway: CliRunner, log: (msg: string) => void, registrars: Registrars, healthProbe?: PublicHealthProbe, sleep?: (ms: number) => Promise<void>): Promise<RailwayRunOutcome>;