@fastagent-sh/fastagent 0.21.1 → 0.22.1

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

@@ -1,46 +1,26 @@
-/**
- * `fastagent deploy fly` — the Fly.io deploy PLAN, computed from the resolved definition. Pure: facts
- * in, artifact contents + an ordered runbook out; the CLI (deploy side effects live there) writes the
- * files and prints the runbook.
- *
- * fastagent owns the two ends only it can know — generate definition-aware artifacts (state root →
- * volume, autostop tuned to the turn model, the exact secret list) and the post-deploy webhook step —
- * and GUIDES the middle (flyctl app/volume/secrets/deploy) as a precise, values-resolved runbook. By
- * default a coding agent (or you) runs flyctl from that runbook; `deploy fly --run` drives it from the
- * CLI instead. This module stays pure either way — it produces the plan, never runs flyctl. The runbook
- * is a FIRST-deploy sequence: `apps`/`volumes create` are one-time (marked so — re-running would make a
- * second volume, the state split it warns against); a redeploy is `fly deploy` alone.
- *
- * autostop = "suspend": the machine snapshots and suspends when idle (Fly Proxy sees inbound load 0),
- * resumes on the next webhook in ~hundreds of ms. A long turn interrupted by an idle-suspend whose
- * snapshot is discarded replays on the next start (the Telegram L1 turn store) — at-least-once, the
- * documented floor. State on the /data volume survives stop/suspend on the same machine.
- */
+/** `fastagent deploy fly` — the Fly.io 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 FlyPlanInput extends ContainerInput {
     /** Fly app name — globally unique, lowercase; the CLI sanitizes it from the dir basename. */
     appName: string;
     /** The port the app listens on (config.http.port ?? 8787); fly.toml routes to it. */
     port: number;
+    /** What satisfies model auth locally ({@link probeAuthSource}). */
+    modelAuth: string | undefined;
     /**
-     * What satisfies model auth locally ({@link probeAuthSource}): an env-var name (`OPENAI_API_KEY`),
-     * `"OAuth"`/`"stored credential"` (a local login the server can't use), or undefined (unconfigured).
+     * Every declared channel and its ingress — the source of the webhook steps, and whether a machine
+     * must stay up for an outbound connection.
      */
-    modelAuth: string | undefined;
-    /** Every declared channel and its ingress — the source of the secret list, the webhook steps, and
-     *  whether a machine must stay up 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[];
-    /** `auto_stop_machines` — `"suspend"` (default, fast resume) or `"stop"` (cold start). CLI `--stop`. */
-    autostop: "suspend" | "stop";
-    /** Allow scaling to zero when idle (default true → `min_machines_running=0`). CLI `--no-scale-to-zero`
-     *  forces one machine up; a github channel forces it too (fire-and-forget turns have no replay). */
-    scaleToZero: boolean;
-    /** Time triggers present (schedules/ or selfSchedule) — forces one machine up: cron/wake has no
-     *  external wake-up, so a scaled-to-zero box would sleep through them. */
-    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 forces a machine up (deploy/residency.ts). */
+    hasCron: boolean;
 }
 export interface FlyPlan {
     /** fly.toml / Dockerfile / .dockerignore — written by the CLI (skipped if present unless --force). */
@@ -48,21 +28,12 @@ export interface FlyPlan {
     /** The ordered, values-resolved deploy runbook — printed to stdout for the coding agent to execute. */
     runbook: string[];
 }
-/** Did fastagent generate this `fly.toml`? */
 export declare function isGeneratedFlyToml(content: string): boolean;
 /** Compute the Fly deploy plan from the resolved definition. */
 export declare function planFlyDeploy(input: FlyPlanInput): FlyPlan;
-/**
- * The `app` name from an existing fly.toml's `app = "…"` line, or undefined if absent — the KEEP-mode
- * single source (a user who renamed the app is not overridden by the basename guess). Accepts TOML's
- * double OR single quotes; anything else (or no `app`) is undefined → the caller falls back to basename.
- */
+/** The `app` name from an existing fly.toml's `app = "…"` line, or undefined if absent. */
 export declare function parseFlyAppName(toml: string): string | undefined;
-/** The `primary_region` from a fly.toml, or undefined — `--run` passes it to `fly volumes create` so the
- *  volume lands in the machine's region (fly.toml is the single source; see {@link parseFlyAppName}). */
-export declare function parseFlyRegion(toml: string): string | undefined;
-/** The `min_machines_running` from a fly.toml, or undefined — the KEEP-mode check reads it so a kept
- *  file that still scales to zero can be warned about when time triggers (schedules/wake) exist. */
+/** The `min_machines_running` from a fly.toml, or undefined. */
 export declare function parseFlyMinMachines(toml: string): number | undefined;
 /** Sanitize a directory basename into a Fly app name: lowercase, [a-z0-9-], must start with a letter. */
 export declare function toFlyAppName(basename: string): string;

package/dist/deploy/fly/plan.js

@@ -1,24 +1,23 @@
 import { webhookRunbook } from "../channel-ingress.js";
 import { containerArtifacts } from "../container.js";
-import { deploymentSecrets, isEnvKey } from "../secrets.js";
-function flyToml(appName, port, hasGithub, autostop, scaleToZero, hasTimeTriggers, hasLongConnectionChannel) {
-    // min_machines_running: 1 (keep one up) when a github channel is present, TIME triggers exist, OR the
-    // operator opted out of scale-to-zero. GitHub's is a SAFETY default — its fire-and-forget turns have no
-    // replay, so scaling to zero could drop an in-flight review. Time triggers (schedules/wake) have no
-    // external wake-up at all — a scaled-to-zero box sleeps through the cron instant. Reason-tagged so the
-    // comment is honest.
-    const min = hasGithub
-        ? `  min_machines_running = 1         # github turns have no replay — don't scale to zero (an in-flight review would be lost)`
-        : hasTimeTriggers
-            ? `  min_machines_running = 1         # schedules/wake-ups need a running machine (no external wake-up for a cron instant)`
-            : hasLongConnectionChannel
-                ? `  min_machines_running = 1         # long-connection channel needs a running machine (cannot wake from zero)`
-                : !scaleToZero
-                    ? `  min_machines_running = 1         # kept running (--no-scale-to-zero)`
-                    : `  min_machines_running = 0         # scale to zero`;
-    const stopLine = autostop === "stop"
-        ? `  auto_stop_machines = "stop"      # stop on idle (cold start on the next webhook)`
-        : `  auto_stop_machines = "suspend"   # suspend on idle (fast resume on the next webhook)`;
+import { CRON_CAN_BE_EXTERNAL, WAKEUPS_WHEN_ASLEEP, residencyFor } from "../residency.js";
+import { isEnvKey } from "../secrets.js";
+function flyToml(appName, port, residency) {
+    // WHY is residency.ts's to decide; the SETTING and its wording are Fly's. Anything else is an edit to the
+    // generated file, which is the artifact's job.
+    const min = residency
+        ? `  min_machines_running = 1         # ${residency.why}`
+        : `  min_machines_running = 0         # scale to zero — ${WAKEUPS_WHEN_ASLEEP}`;
+    // The one reason with a way out gets it stated NEXT TO the line it is about, which is where an operator reading
+    // `min_machines_running = 1` and wondering what it costs them is looking.
+    const alternative = residency?.reason === CRON_CAN_BE_EXTERNAL
+        ? `  # …or keep the time somewhere else and set this to 0: a scheduler you own (Fly Cron Manager,\n` +
+            `  # supercronic, GitHub Actions) calls \`POST /run\`, which runs one declared unit of work by name.\n` +
+            `  # It is an API, not a clock: read its contract first — docs/api-reference.md#post-run.\n` +
+            `  # At 0, ${WAKEUPS_WHEN_ASLEEP}.\n`
+        : "";
+    // Suspend, not stop: a resume is fast enough that a webhook does not time out. Edit the line to change it.
+    const stopLine = `  auto_stop_machines = "suspend"   # suspend on idle (fast resume on the next webhook)`;
     return `${GENERATED_FLY_TOML_MARKER}. Edit freely — it is not regenerated unless you pass --force.
 app = "${appName}"
 primary_region = "iad"  # set your region (list: \`fly platform regions\`)
@@ -36,44 +35,36 @@ primary_region = "iad"  # set your region (list: \`fly platform regions\`)
 ${stopLine}
   auto_start_machines = true
 ${min}
-
+${alternative}
 [mounts]
   source = "data"
-  destination = "/data"            # .state + .secrets — persists across stop/suspend/redeploy
+  destination = "/data"            # workspace, state and credentials survive stop/suspend/redeploy
+  initial_size = "1gb"             # the volume is created by the FIRST deploy — it is pinned to one host, and only
+                                   # deploy tells the scheduler which machine (size + image) must fit there too
 
 [[vm]]
   size = "shared-cpu-1x"
   memory = "512mb"                 # suspend is not recommended above 2 GB
 `;
 }
-/** First line of a generated `fly.toml`, and the predicate that reads it back. Ownership is what decides
- *  whether `--force` may reset the file (app/region/vm state a user tuned by hand is theirs). */
+/** First line of a generated `fly.toml`, and the predicate that reads it back. */
 const GENERATED_FLY_TOML_MARKER = "# Generated by `fastagent deploy fly`";
-/** Did fastagent generate this `fly.toml`? */
 export function isGeneratedFlyToml(content) {
     return content.startsWith(GENERATED_FLY_TOML_MARKER);
 }
 /** Compute the Fly deploy plan from the resolved definition. */
 export function planFlyDeploy(input) {
     const { appName, port, modelAuth, channels } = input;
-    // Artifacts sit under the agent prefix, so a NESTED agent never touches the workspace's own deploy
-    // files; the runbook passes explicit -c/--dockerfile flags either way (unambiguous across flyctl
-    // versions — no reliance on config-relative path resolution).
+    // Artifacts sit under the agent prefix, so they never touch the workspace's own deploy files.
     const flyTomlPath = `${input.agentPrefix}fly.toml`;
     const artifacts = [
         {
             path: flyTomlPath,
-            content: flyToml(appName, port, channels.some((channel) => channel.name === "github"), input.autostop, input.scaleToZero, input.hasTimeTriggers, channels.some((channel) => channel.ingress === "long-connection")),
+            content: flyToml(appName, port, residencyFor({ channels, hasCron: input.hasCron })),
         },
         ...containerArtifacts(input),
     ];
-    // The exact secret list the deployed machine needs, computed from the definition (host-neutral): the
-    // model key (when local auth is an env key) + every discovered channel's secrets. Names + hints as
-    // COMMENT lines (a `#` inside a `\`-continued command would break the shell), then one flat, executable
-    // `fly secrets set` the coding agent fills — `<value>` placeholders, never inline comments.
-    const secrets = deploymentSecrets(modelAuth, channels, input.extraSecrets);
-    const requiredSecrets = secrets.filter((secret) => secret.required);
-    const optionalSecrets = secrets.filter((secret) => !secret.required);
+    const secrets = input.secrets ?? [];
     const deployCmd = `fly deploy . --config ${flyTomlPath} --dockerfile ${input.agentPrefix}Dockerfile --app ${appName}`;
     const runbook = [
         `# Deploy "${appName}" to Fly.io. ${flyTomlPath} / Dockerfile(.dockerignore) are generated above.`,
@@ -83,10 +74,9 @@ export function planFlyDeploy(input) {
         `# Fly app names are GLOBALLY unique: if this fails as taken, set a unique "app" in fly.toml and`,
         `# re-run \`fastagent deploy fly\` — the runbook follows fly.toml's app name.`,
         `fly apps create ${appName}`,
-        `# volume persists /data/.state (sessions, channel state) + /data/.secrets (seeded auth) across stop/suspend/redeploy.`,
-        `# <region> MUST equal primary_region in fly.toml (a volume in another region can't mount) — fly.toml`,
-        `# is the single source for the region; skip this if the volume exists (fly volumes list --app ${appName}):`,
-        `fly volumes create data --app ${appName} --region <region> --size 1`,
+        `# The volume (workspace, state, credentials — kept across stop/suspend/redeploy) is created by the deploy`,
+        `# below, in primary_region and sized by [mounts].initial_size. Creating it yourself first pins it to a host`,
+        `# picked without the machine, which can fail the deploy with "insufficient resources … existing volume".`,
         ``,
         `# An address to be reached ON: [http_service] declares a service, it does not allocate an IP.`,
         `# \`fly deploy\` allocates one on a FIRST deploy only, and merely WARNS when that fails — which`,
@@ -95,55 +85,33 @@ export function planFlyDeploy(input) {
         `fly ips allocate-v4 --shared --app ${appName}`,
         `fly ips allocate-v6 --app ${appName}`,
     ];
-    if (requiredSecrets.length > 0) {
-        runbook.push(``, `# Required secrets (replace each <value>):`, ...requiredSecrets.map((s) => `#   ${s.name}: ${s.hint}`), `fly secrets set --app ${appName} ${requiredSecrets.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}`), `# fly secrets set --app ${appName} ${optionalSecrets.map((s) => `${s.name}=<value>`).join(" ")}`);
-    }
-    runbook.push(``, `# The build context is the WORKSPACE ROOT (the whole directory is baked as the agent's cwd).`, ...(input.agentPrefix
-        ? [`# The config/Dockerfile live under ${input.agentPrefix} so they never collide with the workspace's own.`]
-        : []), `# Run this from ${input.agentPrefix ? "the workspace root" : "this directory"}:`, deployCmd);
-    if (input.shipsGit) {
-        runbook.push(``, `# The image is a WYSIWYG snapshot of this directory. Freshness/durability run through git, driven`, `# by the agent itself: .git ships in the image (see .dockerignore) and git is baked in, so the agent`, `# can pull to freshen content and commit/push its work back (creds ride config.deploy.secrets; the`, `# POLICY — push vs PR, identity — lives in persona.md). CAVEAT: whether .git survives the upload is`, `# host-CLI-dependent — verify \`git status\` on the box; if missing, have the agent clone instead.`, `# Un-pushed changes on the box never survive a redeploy; durability lives in git.`);
+    if (secrets.length > 0) {
+        runbook.push(``, `# Secrets (replace each <value>):`, ...secrets.map((s) => `#   ${s.name}: ${s.hint}`), `fly secrets set --app ${appName} ${secrets.map((s) => `${s.name}=<value>`).join(" ")}`);
     }
-    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"] }.`);
-    }
-    // Model-auth guidance: an env key becomes a secret above. Otherwise the plan can't read the local
-    // credential's VALUE to set as a secret — true for OAuth AND a stored API key (both are
-    // `AuthResult.source` non-env labels), so the wording doesn't prejudge whether it's migratable.
+    runbook.push(``, `# The build context is the WORKSPACE ROOT (the whole directory is baked as the agent's cwd).`, `# The config/Dockerfile live under ${input.agentPrefix} so they never collide with the workspace's own.`, `# Before a new definition release, run \`fastagent deploy fly\` to refresh the release manifest.`, `# Run this from the workspace root:`, deployCmd);
+    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
+        ? `# Git is available for optional collaboration. Verify uploaded history with \`git status\`; clone if the host stripped it.`
+        : `# To use Git for collaboration, add deploy: { apt: ["git"] }. Storage durability does not require Git.`);
+    // Model-auth guidance: an env key becomes a secret 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 secret.`, `#   Set your provider API key as a Fly secret (fly secrets set KEY=...), OR place auth.json at /data/.secrets/ on the volume.`);
     }
-    // The fastagent-only post-step: point each channel at the live URL. WHICH channels and in what words
-    // is the shared channel-ingress kernel's answer; Fly's contribution is that its URL is deterministic.
+    // The fastagent-only post-step: point each channel at the live URL.
     const steps = webhookRunbook(`https://${appName}.fly.dev`, channels);
     const post = steps.length > 0 ? [`# After deploy:`, ...steps] : [];
     if (post.length > 0)
         runbook.push(``, ...post);
-    // Single-machine tier: state lives on ONE volume tied to ONE machine. Scaling to multiple machines
-    // splits state (each gets its own volume) — that needs a shared/external backend, not this recipe.
+    // Single-machine tier: state lives on ONE volume tied to ONE machine.
     runbook.push(``, `# Keep this a SINGLE machine: the /data volume (and all state on it) is tied to one machine.`, `# Multiple machines would each get their own volume and split sessions/turns — don't scale past 1.`);
     return { artifacts, runbook };
 }
-/**
- * The `app` name from an existing fly.toml's `app = "…"` line, or undefined if absent — the KEEP-mode
- * single source (a user who renamed the app is not overridden by the basename guess). Accepts TOML's
- * double OR single quotes; anything else (or no `app`) is undefined → the caller falls back to basename.
- */
+/** The `app` name from an existing fly.toml's `app = "…"` line, or undefined if absent. */
 export function parseFlyAppName(toml) {
     return toml.match(/^\s*app\s*=\s*["']([^"']+)["']/m)?.[1];
 }
-/** The `primary_region` from a fly.toml, or undefined — `--run` passes it to `fly volumes create` so the
- *  volume lands in the machine's region (fly.toml is the single source; see {@link parseFlyAppName}). */
-export function parseFlyRegion(toml) {
-    return toml.match(/^\s*primary_region\s*=\s*["']([^"']+)["']/m)?.[1];
-}
-/** The `min_machines_running` from a fly.toml, or undefined — the KEEP-mode check reads it so a kept
- *  file that still scales to zero can be warned about when time triggers (schedules/wake) exist. */
+/** The `min_machines_running` from a fly.toml, or undefined. */
 export function parseFlyMinMachines(toml) {
     const m = toml.match(/^\s*min_machines_running\s*=\s*(\d+)/m)?.[1];
     return m === undefined ? undefined : Number(m);

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

@@ -1,39 +1,23 @@
-/**
- * `fastagent deploy fly --run` — drive flyctl to completion. The middle of the deploy (app / volume /
- * secrets / deploy) that the plain runbook hands to the operator; `--run` executes it instead, so a
- * coding agent runs ONE command. Idempotent (app/volume check-then-act; channel secrets come from the
- * local env — NOT minted — so a re-run sets the same values) and resumable: it STOPS at a human gate
- * (not logged in, a missing secret value, a taken app name, a failed webhook registration) with one actionable line and a non-zero
- * exit, so the agent clears the gate and re-runs. A `generate` channel secret absent from `.env` is a
- * gate too (`missingSecrets`), not a silent mint — fill it in `.env` (use the random string that
- * `add <channel>` prints).
- *
- * flyctl is behind the shared {@link CliRunner} seam — production spawns `fly`, tests inject a fake that
- * records the command sequence and scripts outputs. That seam is the benchmark: the agent's journey
- * encoded as an asserted command sequence + gate behavior, validated without a real Fly account.
- *
- * Non-interactive incantations the agent would otherwise get wrong: `--remote-only` (build on Fly's
- * builders — no local Docker in a sandbox), `--yes` (no prompts), `--ha=false` + the mounted volume
- * (one machine, the single-machine tier). Secrets go in via `secrets import` over stdin, so values
- * never land in argv/process listings.
- */
-import { type Registrars } from "../channel-ingress.ts";
+/** `fastagent deploy fly --run` — drive flyctl 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 FlyRunPlan {
     appName: string;
-    region: string;
-    /** `KEY=value` secrets to set on Fly: model key (env auth) or `FASTAGENT_AUTH_SEED` (file auth) +
-     *  channel secrets. Set via stdin, never argv. */
+    /** `KEY=value` secrets to set on Fly: 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[];
     /** fly.toml path passed to `fly deploy -c` (relative to the run cwd = the workspace root). */
     flyConfig: string;
-    /** Dockerfile path passed explicitly (`fastagent/Dockerfile`, with the workspace as context —
-     *  flyctl would otherwise resolve it relative to the config's own directory). */
+    /**
+     * Dockerfile path passed explicitly (`fastagent/Dockerfile`, with the workspace as context — flyctl would otherwise
+     * resolve it relative to the config's own directory).
+     */
     dockerfile: string;
 }
 /** Done, or a gate the operator must clear before re-running (printed + non-zero exit by the CLI). */
@@ -44,36 +28,17 @@ export type FlyRunOutcome = {
     gate: string;
 };
 /**
- * Which PUBLIC ingress families `fly ips list --json` shows — asked per family, because "has an
- * ingress address" is not the question the two allocate commands answer. An app holding only a `v6`
- * passes the coarse test and still resolves `<app>.fly.dev` to an AAAA record alone, so an IPv4-only
- * webhook sender (Telegram, GitHub) reproduces #425 against it.
- *
- * The list is EVERY assignment the app holds, and a Flycast or egress address carries a non-empty
- * `Address` too — reading one as routable pre-empts flyctl's own first-deploy fallback, which returns
- * early once any assignment exists.
- *
- * Output that is not a JSON array THROWS rather than reading as "no address": the caller turns that
- * into a gate, because a list we cannot read is not a state we can act on.
+ * Which PUBLIC ingress families `fly ips list --json` shows — asked per family, because "has an ingress address" is
+ * not the question the two allocate commands answer.
  */
 export declare function ingressAddresses(stdout: string): {
     v4: boolean;
     v6: boolean;
 };
 /**
- * Whether a `fly … list --json` array contains an object named `name` (Fly capitalizes `Name`; accept
- * both). Exported for the same reason railway's parsers are: what it encodes is an assumption about
- * another tool's output, and the live probe checks that assumption against the real `flyctl`.
- *
- * THROWS on output that is not a JSON array, for the same reason {@link ingressAddresses} does —
- * `false` here means "the host does not have it", and answering that for a list nobody could read
- * creates a SECOND volume, or in teardown destroys nothing at all.
+ * Whether `fly apps list --json` lists an app called `name`. flyctl capitalizes the field; the live probe
+ * (test/live/fly.live.test.ts) is what pins that against real output, since an offline fixture can only repeat what
+ * we already believe.
  */
 export declare function listHasName(stdout: string, name: string): boolean;
-/**
- * Run the deploy through `fly`. `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.
- */
-export declare function deployFlyRun(plan: FlyRunPlan, fly: CliRunner, log: (msg: string) => void, registrars: Registrars): Promise<FlyRunOutcome>;
+export declare function deployFlyRun(plan: FlyRunPlan, fly: CliRunner, log: (msg: string) => void, registrars: Registrars, healthProbe?: PublicHealthProbe): Promise<FlyRunOutcome>;

package/dist/deploy/fly/run.js

@@ -1,40 +1,14 @@
+/** `fastagent deploy fly --run` — drive flyctl to completion. */
+import { publicHealthGate, registerWebhooks } from "../channel-ingress.js";
+import { missingValuesGate } from "../secrets.js";
 /**
- * `fastagent deploy fly --run` — drive flyctl to completion. The middle of the deploy (app / volume /
- * secrets / deploy) that the plain runbook hands to the operator; `--run` executes it instead, so a
- * coding agent runs ONE command. Idempotent (app/volume check-then-act; channel secrets come from the
- * local env — NOT minted — so a re-run sets the same values) and resumable: it STOPS at a human gate
- * (not logged in, a missing secret value, a taken app name, a failed webhook registration) with one actionable line and a non-zero
- * exit, so the agent clears the gate and re-runs. A `generate` channel secret absent from `.env` is a
- * gate too (`missingSecrets`), not a silent mint — fill it in `.env` (use the random string that
- * `add <channel>` prints).
- *
- * flyctl is behind the shared {@link CliRunner} seam — production spawns `fly`, tests inject a fake that
- * records the command sequence and scripts outputs. That seam is the benchmark: the agent's journey
- * encoded as an asserted command sequence + gate behavior, validated without a real Fly account.
- *
- * Non-interactive incantations the agent would otherwise get wrong: `--remote-only` (build on Fly's
- * builders — no local Docker in a sandbox), `--yes` (no prompts), `--ha=false` + the mounted volume
- * (one machine, the single-machine tier). Secrets go in via `secrets import` over stdin, so values
- * never land in argv/process listings.
+ * The `Type` values that put an app on `https://<app>.fly.dev`, BY FAMILY — one entry per allocate command, because
+ * that is the granularity the answer is acted on at.
  */
-import { registerWebhooks } from "../channel-ingress.js";
-/** The `Type` values that put an app on `https://<app>.fly.dev`, BY FAMILY — one entry per allocate
- *  command, because that is the granularity the answer is acted on at. The rest of flyctl's
- *  vocabulary — `private_v6` (Flycast), `egress_v4`, `egress_v6`, `egress_pair` — is internal or
- *  outbound. */
 const INGRESS_TYPES = { v4: ["v4", "shared_v4"], v6: ["v6"] };
 /**
- * Which PUBLIC ingress families `fly ips list --json` shows — asked per family, because "has an
- * ingress address" is not the question the two allocate commands answer. An app holding only a `v6`
- * passes the coarse test and still resolves `<app>.fly.dev` to an AAAA record alone, so an IPv4-only
- * webhook sender (Telegram, GitHub) reproduces #425 against it.
- *
- * The list is EVERY assignment the app holds, and a Flycast or egress address carries a non-empty
- * `Address` too — reading one as routable pre-empts flyctl's own first-deploy fallback, which returns
- * early once any assignment exists.
- *
- * Output that is not a JSON array THROWS rather than reading as "no address": the caller turns that
- * into a gate, because a list we cannot read is not a state we can act on.
+ * Which PUBLIC ingress families `fly ips list --json` shows — asked per family, because "has an ingress address" is
+ * not the question the two allocate commands answer.
  */
 export function ingressAddresses(stdout) {
     const entries = JSON.parse(stdout);
@@ -44,30 +18,22 @@ export function ingressAddresses(stdout) {
     return { v4: has(INGRESS_TYPES.v4), v6: has(INGRESS_TYPES.v6) };
 }
 /**
- * Whether a `fly … list --json` array contains an object named `name` (Fly capitalizes `Name`; accept
- * both). Exported for the same reason railway's parsers are: what it encodes is an assumption about
- * another tool's output, and the live probe checks that assumption against the real `flyctl`.
- *
- * THROWS on output that is not a JSON array, for the same reason {@link ingressAddresses} does —
- * `false` here means "the host does not have it", and answering that for a list nobody could read
- * creates a SECOND volume, or in teardown destroys nothing at all.
+ * Whether `fly apps list --json` lists an app called `name`. flyctl capitalizes the field; the live probe
+ * (test/live/fly.live.test.ts) is what pins that against real output, since an offline fixture can only repeat what
+ * we already believe.
  */
 export function listHasName(stdout, name) {
     const entries = JSON.parse(stdout);
     if (!Array.isArray(entries))
         throw new Error(`expected a JSON array, got ${typeof entries}`);
-    return entries.some((o) => o.Name === name || o.name === name);
+    return entries.some((o) => o.Name === name);
 }
 /**
- * A read-only `fly … list --json`, reduced to the question the next step asks of it — or the gate for
- * a list we cannot act on. THE place the three answers stay three: the command failed, the output was
- * unreadable, or the host gave a verdict. Collapsing the middle one into `false` is what shipped #425
- * and what would have skipped a teardown.
+ * A read-only `fly … list --json`, reduced to the question the next step asks of it — or the gate for a list we cannot
+ * act on.
  */
 async function readList(fly, args, read) {
-    // The command as RUN, not a restatement of it: a gate that tells the operator to run it themselves
-    // has to name one that works from their cwd, and `fly ips list --json` without `-a <app>` does not
-    // (fly.toml lives under the agent prefix, so flyctl finds no app).
+    // The command as RUN, not a restatement of it.
     const cmd = `fly ${args.join(" ")}`;
     const result = await fly(args, { capture: true });
     if (result.code !== 0)
@@ -76,34 +42,24 @@ async function readList(fly, args, read) {
         return { value: read(result.stdout) };
     }
     catch (error) {
-        // The one place a parse failure is allowed to stop being an exception: this IS the boundary that
-        // turns it into the operator's gate (printed + non-zero exit), never a default answer.
+        // The one place a parse failure is allowed to stop being an exception.
         return {
             gate: `\`${cmd}\` was unreadable (${error instanceof Error ? error.message : String(error)}) — ` +
                 `run it yourself and check the flyctl version; fix and re-run`,
         };
     }
 }
-/**
- * Run the deploy through `fly`. `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.
- */
-export async function deployFlyRun(plan, fly, log, registrars) {
+export async function deployFlyRun(plan, fly, log, registrars, healthProbe) {
     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.
+    // 1.
     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). An unusable list is its
-    //    own gate ({@link readList}): inferring "absent" from a query nobody could read would then
-    //    misreport the create as a name clash.
+    const missingValues = missingValuesGate(plan.missingSecrets, plan.valueFile);
+    if (missingValues)
+        return gate(missingValues);
+    // 3.
     const appExists = await readList(fly, ["apps", "list", "--json"], (out) => listHasName(out, plan.appName));
     if ("gate" in appExists)
         return gate(appExists.gate);
@@ -117,34 +73,15 @@ export async function deployFlyRun(plan, fly, log, registrars) {
                 `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 volumeExists = await readList(fly, ["volumes", "list", "-a", plan.appName, "--json"], (out) => listHasName(out, "data"));
-    if ("gate" in volumeExists)
-        return gate(volumeExists.gate);
-    if (volumeExists.value) {
-        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. Ingress address — `[http_service]` in fly.toml DECLARES a service; it does not create an address
-    //    to reach it on. `fly launch` allocates one as part of its flow, and this driver does not use it,
-    //    so without this step the deploy succeeds, the machine serves, and `https://<app>.fly.dev` has no
-    //    DNS record at all — reported as a healthy deploy, and handed to the webhook registrars as a URL
-    //    they then fail to reach.
+    // 4. NO volume step: `fly deploy` creates it from [mounts] on a first deploy, and only it can tell the scheduler
+    // which machine (guest size + image) must fit on the host the volume is pinned to. Pre-creating one here placed it
+    // blind, and a host with disk but no compute failed the deploy with `insufficient resources … with existing volume`.
+    // 5.
     const addresses = await readList(fly, ["ips", "list", "-a", plan.appName, "--json"], ingressAddresses);
     if ("gate" in addresses)
         return gate(addresses.gate);
-    // Check-then-act PER FAMILY: an app that already holds one must still be given the other, or the
-    // gate between the two allocations below heals into a permanent half-state — the re-run the gate
-    // asks for sees the v4 it just made, skips, and reports success on an app with no v6 (and, the way
-    // that matters, no v4). v4 SHARED and v6 are both free; a dedicated v4 is billed, so it stays an
-    // operator decision — `fly ips allocate-v4 -a <app>` after the fact, which this step reads as v4.
+    // Check-then-act PER FAMILY: an app that already holds one must still be given the other, or the gate between the
+    // two allocations below heals into a permanent half-state.
     for (const [family, allocate] of [
         ["v4", ["ips", "allocate-v4", "--shared", "-a", plan.appName]],
         ["v6", ["ips", "allocate-v6", "-a", plan.appName]],
@@ -167,8 +104,7 @@ export async function deployFlyRun(plan, fly, log, registrars) {
             return gate("`fly secrets import` failed — see the flyctl output above");
         }
     }
-    // 7. Deploy — remote builder (no local Docker), one machine. Context + Dockerfile are passed
-    //    explicitly (the workspace root is the context; the Dockerfile lives under fastagent/).
+    // 7.
     log("deploying (remote build)…");
     const deployArgs = [
         "deploy",
@@ -186,10 +122,21 @@ export async function deployFlyRun(plan, fly, log, registrars) {
     if ((await fly(deployArgs)).code !== 0) {
         return gate("`fly deploy` failed — see the flyctl output above; fix and re-run");
     }
-    // 8. Post-deploy webhook — which channels, in what words, and the gate policy are all the shared
-    //    kernel's; Fly contributes its deterministic URL and how to retry.
+    // 8. `fly deploy` exits 0 on a machine that then crash-loops, so readiness is asked here and not inferred.
+    const baseUrl = `https://${plan.appName}.fly.dev`;
+    const healthGate = await publicHealthGate({
+        baseUrl,
+        channels: plan.channels,
+        log,
+        inspectHint: `the app itself deployed — inspect \`fly logs -a ${plan.appName}\`, then re-run once it answers ` +
+            `(a re-run repeats the remote build)`,
+        probe: healthProbe,
+    });
+    if (healthGate)
+        return gate(healthGate);
+    // 9.
     const registrationGateMsg = await registerWebhooks({
-        baseUrl: `https://${plan.appName}.fly.dev`,
+        baseUrl,
         channels: plan.channels,
         registrars,
         log,

package/dist/deploy/hosts.d.ts

@@ -1,5 +1,26 @@
-/** The deploy targets, as a value: the CLI's `<host>` choices and the host-only-flag table's
- *  exhaustiveness check both read it. Dependency-free, so `cli/program.ts` can import it at load
- *  time without pulling a command module. */
+/**
+ * The deploy targets, as a value: the CLI's `<host>` choices and the host-only-flag table's
+ * exhaustiveness check both read it. Dependency-free, so `cli/program.ts` can import it at load
+ * time without pulling a command module.
+ *
+ * ── ADDING A HOST ───────────────────────────────────────────────────────────
+ *
+ * Three edits: a directory beside this file (copy `fly/`: `plan.ts` pure, `run.ts` driving the host
+ * CLI behind the runner seam), its `HostDeploy` in `cli/commands/deploy/<host>.ts` (kept-file
+ * semantics, gates, the drive glue — the half that may exit the process), and its name in the array
+ * below. `deploy/` itself is a neutral kernel plus one directory per host; nothing host-specific
+ * belongs in the kernel, and no host may hold a fact about another one (a host-only flag is a row in
+ * `HOST_ONLY_FLAGS` in `cli/commands/deploy.ts`, warning elsewhere; `--tunnel` stays a usage GATE in `runDeploy`
+ * because a refusal is not a row).
+ *
+ * BEFORE writing one, read that host's docs for what it does NOT do implicitly — above all, whether
+ * a created resource is REACHABLE without a further step. On Fly, `[http_service]` declares a service and allocates
+ * no address, and v4 and v6 are separate commands, so an app with only v6 is unreachable from an IPv4-only webhook
+ * sender. The host's own docs and CLI source usually say so; read them before a real deploy has to.
+ *
+ * And when a driver PARSES what a host CLI printed: the judgement must match the GRANULARITY of the
+ * action it drives (one question per command), and "we could not read the host" is a third answer,
+ * never "absent".
+ */
 export declare const DEPLOY_HOSTS: readonly ["docker", "fly", "railway", "agentcore"];
 export type DeployHost = (typeof DEPLOY_HOSTS)[number];