@fastagent-sh/fastagent 0.21.0 → 0.22.0

package/dist/deploy/railway/run.js

@@ -1,41 +1,14 @@
-/**
- * `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 { registerWebhooks } from "../channel-ingress.js";
-/**
- * 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.
- */
+/** `fastagent deploy railway --run` — drive the Railway CLI to completion. */
+import { publicHealthGate, registerWebhooks } from "../channel-ingress.js";
+import { missingValuesGate } from "../secrets.js";
+/** Whether `railway status --json` shows a linked project: non-empty stdout. */
 export function isLinked(stdout) {
     return stdout.trim() !== "";
 }
-/** The linked project's name for the gate message, or undefined if it can't be read (still linked —
- *  `railway status --json` puts `name` at the top level on 5.15.0). */
+/**
+ * The linked project's name for the gate message, or undefined if it can't be read (still linked — `railway status
+ * --json` puts `name` at the top level on 5.15.0).
+ */
 export function linkedName(stdout) {
     try {
         const v = JSON.parse(stdout);
@@ -43,13 +16,11 @@ export function linkedName(stdout) {
             return v.name;
     }
     catch {
-        /* non-JSON but non-empty → still linked, just no name to show */
+        // non-JSON but non-empty → still linked, just no name to show
     }
     return undefined;
 }
-/** Every string leaf of a parsed JSON value — the shape-agnostic scan both readers below share: Railway's
- *  `--json` field names aren't guaranteed, so we match on VALUES, not paths. `stdout` that isn't JSON
- *  (an empty/errored query) yields []. */
+/** Every string leaf of a parsed JSON value. */
 function jsonStrings(stdout) {
     const walk = (v) => typeof v === "string"
         ? [v]
@@ -65,12 +36,7 @@ function jsonStrings(stdout) {
         return [];
     }
 }
-/**
- * The first Railway-provided domain as an https URL, or undefined if none is present — reads `railway
- * domain --json` without assuming exact field names: any string value carrying a `*.railway.app` host
- * wins (unanchored, so a scheme/port/path around it still yields the bare host). Undefined → the CLI
- * gates (register manually).
- */
+/** The first Railway-provided domain as an https URL, or undefined if none is present. */
 export function parseDomainUrl(stdout) {
     for (const s of jsonStrings(stdout)) {
         const host = s.match(/[a-z0-9-]+(?:\.[a-z0-9-]+)*\.railway\.app/i)?.[0];
@@ -80,42 +46,50 @@ export function parseDomainUrl(stdout) {
     return undefined;
 }
 /**
- * Whether `railway volume list --json` shows a volume at `mountPath` — shape-agnostic, like
- * {@link parseDomainUrl}. Drives check-then-act so a half-provisioned project (service created, volume
- * add failed) self-heals on re-run instead of silently deploying with no volume.
+ * 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 function parseHasVolume(stdout, mountPath) {
-    return jsonStrings(stdout).includes(mountPath);
+export function volumeOn(stdout, service, mountPath) {
+    const walk = (v) => {
+        if (Array.isArray(v))
+            return v.map(walk).find((status) => status !== undefined);
+        if (!v || typeof v !== "object")
+            return undefined;
+        const o = v;
+        if (o.mountPath === mountPath && o.serviceName === service)
+            return typeof o.status === "string" ? o.status : "";
+        return walk(Object.values(o));
+    };
+    try {
+        return walk(JSON.parse(stdout));
+    }
+    catch {
+        return undefined;
+    }
 }
 /**
- * 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.
+ * How long `--run` waits for a new volume to reach its service before deploying. Railway's `volume add` returns
+ * before the volume is attached, and a deployment started in that window runs WITHOUT it — no `/data` at all —
+ * while a later one gets it (measured 2026-09-27: listed on the service as `Ready` 5s after the add).
  */
-export async function deployRailwayRun(plan, railway, log, registrars) {
+const VOLUME_ATTACH_TIMEOUT_MS = 60_000;
+const VOLUME_POLL_MS = 2_000;
+export async function deployRailwayRun(plan, railway, log, registrars, healthProbe, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
     const gate = (g) => ({ ok: false, gate: g });
-    // Every --service below targets plan.name — the name this tool gives BOTH the project and the service
-    // (`init --name` + `add --service`). On a fresh create they match; on `--into-linked` into a hand-made
-    // project whose service is named differently, the FIRST --service command (`variables set`) gates —
-    // and it's ordered before the volume (which has no --service), so the mismatch fails visibly with no
-    // side effect. (Pre-checking the name means walking status's nested multi-service shape — not worth it.)
+    // Every --service below targets plan.name — the name this tool gives BOTH the project and the service (`init
+    // --name` + `add --service`).
     const svc = ["--service", plan.name];
-    // 1. Auth needs an ACCOUNT credential (browser login or RAILWAY_API_TOKEN) — the project-scoped
-    //    RAILWAY_TOKEN can't predate the project `init` creates. `whoami` succeeds with either.
+    // 1.
     if ((await railway(["whoami"], { capture: true })).code !== 0) {
         return gate("not logged in to Railway — run `railway login`, or set RAILWAY_API_TOKEN (an account token), then re-run");
     }
     // 2. Gate missing required secret VALUES before any side effect (no half-created infra).
-    if (plan.missingSecrets.length > 0) {
-        return gate(`no local value for: ${plan.missingSecrets.join(", ")} — set them in .env (or the environment) and re-run`);
-    }
-    // 3. Linked? `--run` provisions a project and only runs on an UNLINKED directory, so it can never deploy
-    //    into a project it didn't create. A linked directory is REFUSED (naming the project so the operator
-    //    sees what it is) UNLESS they pass --into-linked to provision INTO that project deliberately.
-    //    Unlinked → create. No ownership is tracked — a pre-existing link is never assumed ours; the only
-    //    "yes, this project" signal is the explicit --into-linked. Any non-empty status counts as linked (an
-    //    unreadable shape is refused, not mistaken for unlinked, which would `init` a duplicate).
+    const missingValues = missingValuesGate(plan.missingSecrets, plan.valueFile);
+    if (missingValues)
+        return gate(missingValues);
+    // 3.
     const status = await railway(["status", "--json"], { capture: true });
     if (isLinked(status.stdout)) {
         if (!plan.intoLinked) {
@@ -128,8 +102,7 @@ export async function deployRailwayRun(plan, railway, log, registrars) {
         log(`provisioning into linked project ${linkedName(status.stdout) ?? plan.name} (--into-linked)`);
     }
     else {
-        // --into-linked means "provision into the project this dir is linked to" — but it isn't linked. Don't
-        // swallow the flag silently: the operator expected an existing project; say we're creating a fresh one.
+        // --into-linked means "provision into the project this dir is linked to" — but it isn't linked.
         if (plan.intoLinked) {
             log("warn: --into-linked was passed but this directory isn't linked to any project — creating a fresh one");
         }
@@ -137,29 +110,28 @@ export async function deployRailwayRun(plan, railway, log, registrars) {
         if ((await railway(["init", "--name", plan.name])).code !== 0) {
             return gate("`railway init` failed — if you have multiple workspaces, run it once interactively (or pass --workspace) to pick one, then re-run");
         }
-        // Create + link the service (init makes only a project); it precedes the volume, which has no
-        // --service flag and rides the linked service.
+        // Create + link the service (init makes only a project); it precedes the volume, which has no --service flag and
+        // rides the linked service.
         log(`creating service ${plan.name}…`);
         if ((await railway(["add", "--service", plan.name])).code !== 0) {
-            // Precise recovery, not "fix and re-run": init already created + linked the project, so a plain
-            // re-run hits the linked-gate, and --into-linked SKIPS `add` and then fails at the volume (no
-            // service to ride). The clean paths are to create the service by hand then --into-linked, or unlink.
+            // Precise recovery, not "fix and re-run": init already created + linked the project, so a plain re-run hits the
+            // linked-gate, and --into-linked SKIPS `add` and then fails at the volume (no service to ride).
             return gate(`\`railway add --service\` failed — \`railway init\` already created the project (this directory is now ` +
                 `linked) but not the service. Finish with \`railway add --service ${plan.name}\` here, then re-run with ` +
                 `--into-linked; or \`railway unlink\` to detach and start fresh.`);
         }
     }
-    // 3b. Variables — set BEFORE the volume/deploy. This is deliberately the FIRST `--service` command: on
-    //     an --into-linked into a hand-made project whose service name ≠ plan.name, it gates HERE, before the
-    //     volume (which has no --service and would otherwise attach to that service) — so the mismatch fails
-    //     visibly with NO side effect. State root on argv (not secret); secrets one-per-`set --stdin` (value
-    //     on stdin, never argv). Idempotent. (Order vs the volume is free — both just need to precede `up`.)
+    // 3b.
     const machineryVars = [
         `FASTAGENT_STATE_DIR=${plan.mountPath}/.state`,
         `FASTAGENT_SECRETS_DIR=${plan.mountPath}/.secrets`,
         `RAILWAY_DOCKERFILE_PATH=${plan.dockerfilePath}`,
     ];
-    log(`setting ${machineryVars.map((v) => v.split("=")[0]).join("/")} + ${Object.keys(plan.secrets).length} secret(s)…`);
+    // The secret NAMES, not a count: `--run` uploads the whole value file, so the operator has to be able to see the
+    // list on every host.
+    const secretNames = Object.keys(plan.secrets);
+    log(`setting ${machineryVars.map((v) => v.split("=")[0]).join("/")} + ${secretNames.length} secret(s)` +
+        `${secretNames.length > 0 ? `: ${secretNames.join(", ")}` : ""}…`);
     if ((await railway(["variables", "set", ...machineryVars, ...svc])).code !== 0) {
         return gate("`railway variables set` failed — see the railway output above");
     }
@@ -168,39 +140,53 @@ export async function deployRailwayRun(plan, railway, log, registrars) {
             return gate(`\`railway variables set ${k}\` failed — see the railway output above`);
         }
     }
-    // 3c. Volume — check-then-act, ALWAYS (like Fly's per-resource skip-if-present). An --into-linked into an
-    //     existing project may already have it; a first deploy that failed after this step has it, one that
-    //     failed before needs it. Verify + add so we never deploy with NO persistence (FASTAGENT_STATE_DIR
-    //     =/data would be empty every redeploy — silent state loss). Runs after variables so a mismatched
-    //     service (see above) has already gated — this step won't attach a volume to the wrong service.
-    const vols = await railway(["volume", "list", "--json"], { capture: true });
-    if (parseHasVolume(vols.stdout, plan.mountPath)) {
-        log(`volume at ${plan.mountPath} exists — skipping`);
+    // 3c.
+    const volumeStatus = async () => volumeOn((await railway(["volume", "list", "--json"], { capture: true })).stdout, plan.name, plan.mountPath);
+    if ((await volumeStatus()) !== undefined) {
+        log(`volume at ${plan.mountPath} exists on ${plan.name} — skipping`);
     }
     else {
         log(`creating volume at ${plan.mountPath}…`);
         if ((await railway(["volume", "add", "--mount-path", plan.mountPath])).code !== 0) {
             return gate("`railway volume add` failed — see the railway output above");
         }
+        // Deploying before the volume is attached boots a container with no volume, which `start` refuses (it must
+        // never seed a workspace onto a disk that vanishes on restart).
+        let status;
+        for (let waited = 0;; waited += VOLUME_POLL_MS) {
+            status = await volumeStatus();
+            if (status === "Ready" || waited >= VOLUME_ATTACH_TIMEOUT_MS)
+                break;
+            await sleep(VOLUME_POLL_MS);
+        }
+        if (status !== "Ready") {
+            return gate(`the volume at ${plan.mountPath} is not attached to service ${plan.name} after ` +
+                `${VOLUME_ATTACH_TIMEOUT_MS / 1000}s (${status === undefined ? "not listed on it" : `status ${status}`}) — ` +
+                "check `railway volume list`, then re-run with --into-linked once it shows Ready");
+        }
     }
     // 5. Deploy — CI mode streams build logs then exits (no interactive attach). Build runs on Railway.
     log("deploying (railway up)…");
     if ((await railway(["up", "--ci", ...svc])).code !== 0) {
         return gate("`railway up` failed — see the railway output above; fix and re-run");
     }
-    // 6. Public domain — a Railway service isn't reachable until one is minted (unlike Fly's deterministic
-    //    <app>.fly.dev), so every deploy needs it (the /invoke + /health surface), not just webhook channels.
-    //    The top-level `railway domain` (no subcommand; --json/--service flags are fine) is the long-standing
-    //    core command: it returns the service domain, minting one if absent. We do NOT pre-check with the
-    //    `domain list` SUBCOMMAND — it's newer, and on a CLI without it `railway domain list` falls through
-    //    to the [DOMAIN] positional and registers a bogus custom domain named "list" (destructive). Version-robust.
+    // 6.
     log("getting the public domain…");
     const url = parseDomainUrl((await railway(["domain", "--json", ...svc], { capture: true })).stdout);
     if (!url) {
         return gate("couldn't read a domain from `railway domain` — run `railway domain` manually, then set any webhook");
     }
-    // 7. Post-deploy webhook — which channels, in what words, and the gate policy are all the shared
-    //    kernel's; Railway contributes the minted URL and how to retry.
+    // 6b. `railway up --ci` exits 0 once the build is accepted, so readiness is asked here and not inferred.
+    const healthGate = await publicHealthGate({
+        baseUrl: url,
+        channels: plan.channels,
+        log,
+        inspectHint: "the service itself deployed — inspect `railway logs`, then re-run once it answers",
+        probe: healthProbe,
+    });
+    if (healthGate)
+        return gate(healthGate);
+    // 7.
     const registrationGateMsg = await registerWebhooks({
         baseUrl: url,
         channels: plan.channels,

package/dist/deploy/registration-gate.d.ts

@@ -1,20 +1,13 @@
 /**
- * Host-NEUTRAL step-7 gate policy, shared by the host runners: the registrars report facts
- * ({@link RegistrationOutcome}), this module owns what to do about them.
- *
- * - "failed" gates — exit 0 would tell a coding agent "done" while the deployed agent cannot receive
- *   messages, and the runners' earlier steps are idempotent so a re-run just retries registration.
- * - "manual" does NOT gate — re-running can never change it (an unclearable gate would spin a coding
- *   agent forever) — but is re-surfaced after all registrar output (and before any gate message) so
- *   the operator cannot miss it under the registrar's earlier log lines.
- *
- * The runners attempt ALL channels first (one failure doesn't skip the rest), then apply this policy
- * once. Only the retry remediation differs per host (`retryHint`).
+ * Host-NEUTRAL step-7 gate policy, shared by the host runners: the registrars report facts ({@link
+ * RegistrationOutcome}), this module owns what to do about them.
  */
 import type { RegistrationOutcome } from "../channels/registration.ts";
 export declare function registrationGate(log: (msg: string) => void, retryHint: string): {
     track: (kind: string, outcome: RegistrationOutcome) => void;
-    /** Logs the manual notices; returns the gate message (composes with cli.ts's "deploy stopped:"
-     *  prefix — it leads with the failure, not "the deploy succeeded"), or undefined for no gate. */
+    /**
+     * Logs the manual notices; returns the gate message (composes with cli.ts's "deploy stopped:" prefix — it leads with
+     * the failure, not "the deploy succeeded"), or undefined for no gate.
+     */
     gate: () => string | undefined;
 };

package/dist/deploy/residency.d.ts

@@ -0,0 +1,37 @@
+/**
+ * WHAT FORBIDS SCALING TO ZERO — one rule, read by every host that can scale.
+ *
+ * A host may only phrase its own REMEDY — the setting it owns (`min_machines_running`, App Sleeping) — never
+ * re-derive the reason.
+ *
+ * ORDER IS THE POINT, not just precedence: the reason reported has to be the one an operator cannot work around,
+ * because the message it produces differs. A declared schedule has a substitute, because the clock does not have to
+ * be ours — see {@link CRON_CAN_BE_EXTERNAL}; a long connection has none.
+ *
+ * A WAKE-UP IS NOT A REASON. Every serve mounts `wake`, so counting it would pin every deployment up. It does not
+ * need to: the wake-up store is on the volume and the poll drains what is due when the process starts, so a box that
+ * slept fires it late, when a request next wakes it — never loses it. {@link WAKEUPS_WHEN_ASLEEP} says so where
+ * scaling to zero is offered.
+ */
+import type { DeclaredChannel } from "../channels/discover.ts";
+/** Why one machine has to stay up. Also the order they are checked in. */
+export type ResidencyReason = "long-connection" | "cron";
+export interface Residency {
+    reason: ResidencyReason;
+    /** The host-neutral cause, one clause, for a generated comment or a runbook line. */
+    why: string;
+}
+/**
+ * The ONE reason a caller may offer a way out of: a cron is a TIME, and a time can be kept elsewhere — a platform
+ * scheduler, a CI cron, a crontab — which then calls this agent. Nothing else here can be moved out: a long
+ * connection is one this process holds.
+ */
+export declare const CRON_CAN_BE_EXTERNAL: ResidencyReason;
+/** What scaling to zero costs the agent's own wake-ups — said next to every setting that allows it. */
+export declare const WAKEUPS_WHEN_ASLEEP = "the agent's own wake-ups then fire when a request next wakes the machine, not on time";
+/** What forbids scale-to-zero for this deployment, or `undefined` when nothing does. */
+export declare function residencyFor(facts: {
+    channels: readonly DeclaredChannel[];
+    /** `routines/` declares at least one cron. */
+    hasCron: boolean;
+}): Residency | undefined;

package/dist/deploy/residency.js

@@ -0,0 +1,24 @@
+/**
+ * The ONE reason a caller may offer a way out of: a cron is a TIME, and a time can be kept elsewhere — a platform
+ * scheduler, a CI cron, a crontab — which then calls this agent. Nothing else here can be moved out: a long
+ * connection is one this process holds.
+ */
+export const CRON_CAN_BE_EXTERNAL = "cron";
+/** What scaling to zero costs the agent's own wake-ups — said next to every setting that allows it. */
+export const WAKEUPS_WHEN_ASLEEP = "the agent's own wake-ups then fire when a request next wakes the machine, not on time";
+/** What forbids scale-to-zero for this deployment, or `undefined` when nothing does. */
+export function residencyFor(facts) {
+    if (facts.channels.some((channel) => channel.ingress === "long-connection")) {
+        return {
+            reason: "long-connection",
+            why: "a long-connection channel must stay connected — it cannot wake from zero",
+        };
+    }
+    if (facts.hasCron) {
+        return {
+            reason: "cron",
+            why: "a cron instant has no external wake-up here, so a sleeping box sleeps through it",
+        };
+    }
+    return undefined;
+}

package/dist/deploy/runner.d.ts

@@ -2,14 +2,16 @@ interface RunResult {
     code: number;
     /** Captured stdout (for `--json` queries); empty when the command streamed to the terminal. */
     stdout: string;
-    /** Captured stderr — ONLY when `captureStderr` was set (a caller that must CLASSIFY a failure, e.g.
-     *  "not found" vs "denied"); otherwise undefined and stderr streams to the terminal as always. */
+    /**
+     * Captured stderr — ONLY when `captureStderr` was set (a caller that must CLASSIFY a failure, e.g. "not found" vs
+     * "denied").
+     */
     stderr?: string;
 }
-/** Run `bin args`: `capture` collects stdout (for `--json` queries), else the command streams to the
- *  terminal (create/deploy) and stdout is empty; `input` is fed to stdin (secrets over stdin, never argv).
- *  `env` adds child-only environment values — Docker Compose interpolates secrets from it without putting
- *  values in argv or mutating the long-lived CLI process. */
+/**
+ * Run `bin args`: `capture` collects stdout (for `--json` queries), else the command streams to the terminal
+ * (create/deploy) and stdout is empty.
+ */
 export type CliRunner = (args: string[], opts?: {
     capture?: boolean;
     captureStderr?: boolean;
@@ -17,9 +19,8 @@ export type CliRunner = (args: string[], opts?: {
     env?: NodeJS.ProcessEnv;
 }) => Promise<RunResult>;
 /**
- * Production {@link CliRunner}: spawn `bin` in `cwd` (the workspace, so a build/upload context is the
- * agent). stderr is always inherited to the terminal; stdout is inherited unless `capture`. A spawn
- * ENOENT (the CLI not on PATH) resolves to code 127 so the caller can gate with an install hint.
+ * Production {@link CliRunner}: spawn `bin` in `cwd` (the workspace, so a build/upload context is the agent). stderr
+ * is always inherited to the terminal.
  */
 export declare function spawnRunner(bin: string, cwd: string): CliRunner;
 export {};

package/dist/deploy/runner.js

@@ -1,14 +1,9 @@
-/**
- * The host-CLI dispatcher seam, shared by every `deploy <host> --run` driver (fly/run.ts, railway/run.ts).
- * WHAT it does — run a CLI, optionally capture stdout or feed stdin — is identical across hosts; only the
- * binary and the command sequence differ. Tests inject a fake recorder; production spawns the real CLI.
- */
+/** The host-CLI dispatcher seam, shared by every `deploy <host> --run` driver (fly/run.ts, railway/run.ts). */
 import { spawn } from "node:child_process";
 import { log } from "../log.js";
 /**
- * Production {@link CliRunner}: spawn `bin` in `cwd` (the workspace, so a build/upload context is the
- * agent). stderr is always inherited to the terminal; stdout is inherited unless `capture`. A spawn
- * ENOENT (the CLI not on PATH) resolves to code 127 so the caller can gate with an install hint.
+ * Production {@link CliRunner}: spawn `bin` in `cwd` (the workspace, so a build/upload context is the agent). stderr
+ * is always inherited to the terminal.
  */
 export function spawnRunner(bin, cwd) {
     return (args, opts) => new Promise((res) => {
@@ -27,22 +22,16 @@ export function spawnRunner(bin, cwd) {
         child.stdout?.on("data", (d) => (out += String(d)));
         child.stderr?.on("data", (d) => (err += String(d)));
         if (opts?.input) {
-            // A host CLI that rejects before reading (bad auth, a refused command) closes stdin under us:
-            // the write then emits `error` on a stream with no listener, which Node turns into an uncaught
-            // exception — crashing the deploy and losing the gate message the exit code was about to carry.
-            // HELD, not dropped: the exit code says it only when the CLI exits non-zero (see below).
+            // A host CLI that rejects before reading (bad auth, a refused command) closes stdin under us.
             child.stdin?.on("error", (error) => (stdinError ??= error));
             child.stdin?.end(opts.input);
         }
         child.on("close", (code) => {
-            // A CLI that exits 0 having refused part of its stdin took TRUNCATED input — an auth seed runs
-            // well past the 64KB pipe buffer, so "success" here would deploy a half-written secret and say
-            // nothing. The exit code is what callers read, so the failure has to reach them as one.
+            // A CLI that exits 0 having refused part of its stdin took TRUNCATED input.
             const truncated = stdinError !== undefined && (code ?? 1) === 0;
             if (truncated) {
-                // `error`, not `warn`: this line is the ONLY evidence of the failure — the caller's gate says
-                // "see the output above", and above it the host CLI printed success. A log level that mutes
-                // it (CI often sets `error`) leaves a stopped deploy with no diagnosable cause.
+                // `error`, not `warn`: this line is the ONLY evidence of the failure — the caller's gate says "see the
+                // output above", and above it the host CLI printed success.
                 log.error(`[fastagent] ${bin} exited 0 without reading all of its input — ${stdinError?.message}`);
             }
             res({ code: truncated ? 1 : (code ?? 1), stdout: out, stderr: opts?.captureStderr ? err : undefined });

package/dist/deploy/secrets.d.ts

@@ -1,63 +1,62 @@
-import type { DeclaredChannel } from "../channels/discover.ts";
 /**
- * Is this local auth source an env-var API key (→ becomes a deploy secret) vs OAuth / stored / none?
- * Positive match on the UPPER_SNAKE env-var naming shape, NOT a negative exclude of today's sentinel
- * labels: a new non-env `AuthResult.source` (e.g. `keychain`) then degrades to guidance, never a fake
- * `keychain=<value>` secret — the two modules don't couple through an exhaustive string list.
+ * The environment a deployed agent runs with — host-neutral.
+ *
+ * The value file (`.secrets/.env`) IS the deployed environment: every variable in it travels, on every host. What the
+ * definition declares (`defineTool`/`defineChannel`/`defineRoutine({ secrets })`, plus the model's env key) only says
+ * which of those must have a value, so a missing one stops a deploy before its first side effect instead of a boot.
  */
+import { type DeclaredSecret } from "../declared-secrets.ts";
+/** Is this local auth source an env-var API key (→ becomes a deploy secret) vs OAuth / stored / none? */
 export declare function isEnvKey(source: string | undefined): source is string;
-/**
- * Secret NAMES + hints for a runbook: the model key (when local auth is an env key), discovered channel
- * secrets, and config extras. Channel metadata keeps optional values visible without presenting them as
- * deployment prerequisites. An OAuth/stored login has no env key here — it carries as
- * `FASTAGENT_AUTH_SEED` on the `--run` path (see each host's run module), not as a named runbook secret.
- */
-export declare function deploymentSecrets(modelAuth: string | undefined, channels: readonly DeclaredChannel[], extraSecrets?: string[]): {
+/** One variable a runbook tells the operator to set, and where to look for its value. */
+export interface DeploymentSecret {
     name: string;
     hint: string;
-    required: boolean;
-}[];
+}
 /**
- * Assemble the secret VALUES a `--run` deploy sets on the host, from the local credential + channels —
- * pure, host-neutral (Fly sets them via `fly secrets import`, Railway via `railway variables set`), so
- * the security-sensitive key wiring is testable once. The model credential travels one of two ways: an
- * env-key auth as its own secret (value from `env`), OR an OAuth/stored login (no plaintext key) as
- * `FASTAGENT_AUTH_SEED` (base64 auth.json) which `start` materializes on first boot. `needsModelCredential`
- * (neither present) is a DISTINCT signal: its remediation is `fastagent login`, not the `.env` one that
- * `missingSecrets` (real secret NAMES with no value) carries.
+ * What a runbook lists: the names that must have a value (the model's env key, every declaration — hinted by the file
+ * that declared it) and then every other variable the value file carries.
+ */
+export declare function deploymentSecrets(modelAuth: string | undefined, declared: readonly DeclaredSecret[], values: ReadonlyMap<string, string>, valueFile: string): DeploymentSecret[];
+/**
+ * Assemble the VALUES a `--run` deploy sets on the host: every variable the value file carries, plus the local
+ * credential. Never minted here.
  *
- * Channel secrets come from the local env only — NEVER minted. A random mint would be wrong for a
- * human-shared secret (github's webhook secret must match the value the operator enters in the repo,
- * which a silent mint never surfaces) and would rotate every run (breaking idempotency). An absent
- * required value enters `missingSecrets`; an absent optional value is simply omitted.
+ * `values` is the selected value file, read as data — **the environment running `deploy` is not a source**. A
+ * deployment must be reproducible from what it carries, and a variable that happens to be exported on the builder is
+ * written down nowhere. CI supplies values by writing the file before running the command.
  */
 export declare function assembleSecrets(input: {
     modelAuth: string | undefined;
-    /** The definition carries the model key itself (a models.json literal `apiKey` / `!command`): there is
-     *  no value to carry and no gate to raise — see {@link modelCredentialCarry}. */
+    /**
+     * The definition carries the model key itself (a models.json literal `apiKey` / `!command`): there is no value to
+     * carry and no gate to raise.
+     */
     modelKeyInDefinition?: boolean;
     authFile: Buffer | undefined;
-    channels: readonly DeclaredChannel[];
-    /** Extra secret env-var names from `fastagent.config` deploy.secrets — carried like channel secrets. */
-    extraSecrets?: string[];
-    env: NodeJS.ProcessEnv;
+    /** Every name the definition declared it needs — what must have a value. */
+    declared?: readonly DeclaredSecret[];
+    /** The selected value file's contents (`loadEnvValues`). The ONLY source of operator-supplied values. */
+    values: ReadonlyMap<string, string>;
 }): {
     secrets: Record<string, string>;
     missingSecrets: string[];
     needsModelCredential: boolean;
 };
 /**
- * The bytes to seed to the auth file, or undefined to leave it alone — the pure core of `start`'s
- * FASTAGENT_AUTH_SEED materialization (the read side of {@link assembleSecrets}'s carry). 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.
+ * The ONE refusal for declared names the deployed environment does not supply a value for — every host reaches it
+ * before its first side effect. Host-neutral because the reason is: the value file IS the deployed environment, so a
+ * name missing from it is missing from the deployment, whatever platform receives it.
  */
+export declare function missingValuesGate(missing: readonly string[], valueFile: string): string | undefined;
+/** The bytes to seed to the auth file, or undefined to leave it alone. */
 export declare function authSeedBytes(seed: string | undefined, fileExists: boolean): Buffer | undefined;
+/** `FASTAGENT_AUTH_SEED` (+ `_2`, …): the base64 auth.json a deploy carries. */
+export declare function collectAuthSeed(env: NodeJS.ProcessEnv): string | undefined;
 /**
- * Collect the (possibly CHUNKED) auth seed from the environment: `FASTAGENT_AUTH_SEED` plus numbered
- * continuations (`_2`, `_3`, …) concatenated in order. Hosts whose env values carry a small max
- * length (AgentCore: 2048 chars — a real OAuth auth.json's base64 exceeds it) split the seed across
- * them at deploy time; single-var hosts (Fly/Railway) never set a continuation and are unchanged.
- * Collection stops at the first absent/empty continuation — the writer fills them contiguously.
+ * Expand `FASTAGENT_ENV` into the process environment — what `start` does first on a host that carries the value file
+ * that way. The platform's own variables still win, as they do over a value file anywhere.
  */
-export declare function collectAuthSeed(env: NodeJS.ProcessEnv): string | undefined;
+export declare function applyCarriedEnv(env?: NodeJS.ProcessEnv): void;
+/** The carried variables as the base64 JSON {@link collectCarriedEnv} reads back; empty when nothing travels. */
+export declare function encodeCarriedEnv(carried: Readonly<Record<string, string>>): string;