@fastagent-sh/fastagent 0.21.0 → 0.22.0

package/dist/cli/commands/deploy/fly.js

@@ -1,40 +1,21 @@
-/**
- * `deploy fly`: fly.toml + a state volume. KEEP (no --force): an existing fly.toml is authoritative;
- * --force: the template is. `--run` drives flyctl to completion (idempotent, resumable).
- */
-import { readFile } from "node:fs/promises";
+/** `deploy fly`: fly.toml + a state volume. */
 import { basename, join } from "node:path";
-import { isGeneratedFlyToml, parseFlyAppName, parseFlyMinMachines, parseFlyRegion, planFlyDeploy, toFlyAppName, } from "../../../deploy/fly/plan.js";
+import { isGeneratedFlyToml, parseFlyAppName, parseFlyMinMachines, planFlyDeploy, toFlyAppName, } from "../../../deploy/fly/plan.js";
 import { deployFlyRun } from "../../../deploy/fly/run.js";
 import { spawnRunner } from "../../../deploy/runner.js";
 import { readTextIfExists } from "../../../paths.js";
+import { residencyFor } from "../../../deploy/residency.js";
 import { failStartup } from "../../fail.js";
 import { carryCredentials, gateOnModelCredential, registrarsFor } from "./shared.js";
 export const flyHost = {
     isOurs: (path, content) => path.endsWith("fly.toml") && isGeneratedFlyToml(content),
     async deploy(ctx) {
-        const { opts, agentDir, workspace, channels, longConnectionChannels, pre, write } = ctx;
-        const { hasTimeTriggers, modelAuth, modelKeyInDefinition, authPath, container, port, extraSecrets } = pre;
-        // The replay floor that makes scale-to-zero safe is Telegram-only (its L1 turn store). GitHub turns
-        // are fire-and-forget (no replay), so the generated fly.toml keeps one machine running for them —
-        // a note, not a warn, since the plan already did the safe thing (definition-aware autostop).
-        if (channels.some((channel) => channel.name === "github")) {
-            console.error(`[fastagent] note: github turns have no replay — the generated fly.toml uses min_machines_running=1 ` +
-                `(no scale-to-zero) so autostop can't drop an in-flight review. Set it to 0 to accept that trade.`);
-        }
-        // Two consistent modes. KEEP (no --force): an existing fly.toml is authoritative — not rewritten,
-        // and the runbook reads its `app=` (Fly app names are globally unique, so the basename guess may be
-        // taken and the user renamed it). --force: the template is authoritative — the WHOLE fly.toml resets
-        // (app→basename, region→iad, vm→defaults), so we do NOT round-trip `app` and warn that hand edits go.
-        // fly.toml lives in the agent dir (fastagent/fly.toml) — the workspace's own
-        // fly.toml (if any) belongs to the host's product deploy and is never read or written here.
+        const { opts, agentDir, workspace, channels, pre, write } = ctx;
+        const { hasCron, modelAuth, modelKeyInDefinition, authPath, container, port, declaredSecrets, values, valueFile } = pre;
+        // Two consistent modes.
         const flyTomlPath = join(agentDir, "fly.toml");
         const flyToml = await readTextIfExists(flyTomlPath).catch(failStartup);
-        // Every decision below turns on ONE question — will `writeArtifacts` keep this file? — and the answer is
-        // OWNERSHIP, not the flag: `--force` resets a fly.toml we generated and leaves a hand-written one alone.
-        // Keying these on `--force` alone meant a forced deploy of a hand-owned fly.toml took the app name from
-        // the directory basename (shipping that file at a DIFFERENT app than it declares) and skipped the
-        // scale-to-zero gate below (a schedules deploy that silently sleeps). Read once, decide once.
+        // Every decision below turns on ONE question — will `writeArtifacts` keep this file?
         const flyTomlKept = flyToml !== undefined && (!opts.force || !isGeneratedFlyToml(flyToml));
         const keptApp = flyTomlKept ? parseFlyAppName(flyToml) : undefined;
         const appName = keptApp ?? toFlyAppName(basename(workspace));
@@ -43,28 +24,17 @@ export const flyHost = {
         if (flyToml !== undefined && !flyTomlKept) {
             console.error(`[fastagent] warn: --force resets fly.toml to defaults (app, region, vm) — re-apply any hand edits`);
         }
-        // Autostop flags shape the GENERATED fly.toml only. In KEEP mode (fly.toml exists, no --force) it is
-        // not rewritten, so the flags would silently do nothing — surface that instead of a confusing no-op.
-        if (flyTomlKept && (opts.stop || opts.scaleToZero === false)) {
-            console.error(`[fastagent] warn: --stop/--no-scale-to-zero only shape a freshly generated fly.toml — yours exists and ` +
-                `was kept. Edit auto_stop_machines/min_machines_running in fly.toml, or pass --force to regenerate.`);
-        }
-        // KEEP mode + time triggers: the kept fly.toml may still scale to zero — which would sleep through every
-        // cron instant / wake-up. The generated plan can't fix a kept file, so surface it instead of the preflight
-        // note silently not applying (the author who deployed FIRST and added schedules LATER hits exactly this).
-        // Under `--run` this is a GATE (same discipline as the model-travel gate): a full deploy whose schedules
-        // silently never fire is worse than a crash-loop — nothing fails visibly when a cron instant passes on a
-        // sleeping machine, and unlike github's min=0 there is no legitimate trade to accept here.
-        if (flyTomlKept && (hasTimeTriggers || longConnectionChannels.length > 0)) {
+        // KEEP mode: the kept fly.toml may still scale to zero — which would sleep through the very thing the
+        // GENERATED one keeps a machine up for. Same question, same answer: `residencyFor` decides, here too, so the
+        // kept-file gate and the generated setting cannot disagree.
+        const residency = residencyFor({ channels, hasCron });
+        if (flyTomlKept && residency) {
             const min = parseFlyMinMachines(flyToml);
             if ((min ?? 0) === 0) {
-                // undefined = the line is absent — Fly's platform default for min_machines_running is 0, so a
-                // hand-written fly.toml without the line scales to zero exactly like an explicit 0.
-                const reason = hasTimeTriggers
-                    ? `schedules/self-scheduling need a running machine (no external wake-up)`
-                    : `long-connection channel (${longConnectionChannels.map((c) => c.name).join(", ")}) needs an always-on outbound connection`;
+                // undefined = the line is absent — Fly's platform default for min_machines_running is 0, so a hand-written
+                // fly.toml without the line scales to zero exactly like an explicit 0.
                 const msg = `your kept fly.toml scales to zero (min_machines_running = ${min ?? "absent → platform default 0"}), but ` +
-                    `${reason}. Set min_machines_running = 1, or pass --force to regenerate.`;
+                    `${residency.why}. Set min_machines_running = 1, or pass --force to regenerate.`;
                 if (opts.run)
                     failStartup(new Error(`deploy stopped: ${msg}`));
                 console.error(`[fastagent] warn: ${msg}`);
@@ -75,11 +45,9 @@ export const flyHost = {
             port,
             modelAuth,
             channels,
-            extraSecrets,
-            hasTimeTriggers,
+            secrets: pre.secrets,
+            hasCron,
             ...container,
-            autostop: opts.stop ? "stop" : "suspend",
-            scaleToZero: opts.scaleToZero !== false,
         });
         await write(plan.artifacts, { force: !!opts.force });
         if (opts.run) {
@@ -92,35 +60,29 @@ export const flyHost = {
                 modelKeyInDefinition,
                 authPath,
                 channels,
-                flyTomlPath,
-                extraSecrets,
+                declaredSecrets,
+                values,
+                valueFile,
             });
         }
         console.log(plan.runbook.join("\n"));
     },
 };
-/**
- * `deploy fly --run`: drive flyctl to completion (idempotent, resumable). Gathers the secret VALUES
- * from the local env — the model key (env auth) or the whole auth.json as a `FASTAGENT_AUTH_SEED` seed
- * (OAuth/stored auth: the deployed box materializes it onto the /data volume on first boot, so a
- * personal deploy runs on the SAME subscription) plus channel secrets — then runs the flyctl steps
- * behind the shared {@link spawnRunner} seam (spawned `fly`, cwd = the workspace so the build context is the whole workspace).
- */
+/** `deploy fly --run`: drive flyctl to completion (idempotent, resumable). */
 async function runDeployFly(params) {
-    const { agentDir, workspace, agentPrefix, appName, channels, flyTomlPath } = params;
+    const { agentDir, workspace, agentPrefix, appName, channels } = params;
     const fly = spawnRunner("fly", workspace);
     // Fail fast if flyctl is absent (spawn ENOENT → 127), with the install link — not a confusing auth gate.
     if ((await fly(["version"], { capture: true })).code === 127) {
         failStartup(new Error(`flyctl not found — install it: https://fly.io/docs/flyctl/install, then re-run`));
     }
-    const region = parseFlyRegion(await readFile(flyTomlPath, "utf8")) ?? "iad";
     const { secrets, missingSecrets, needsModelCredential } = await carryCredentials(params);
     gateOnModelCredential(needsModelCredential);
     const outcome = await deployFlyRun({
         appName,
-        region,
         secrets,
         missingSecrets,
+        valueFile: params.valueFile,
         channels,
         flyConfig: `${agentPrefix}fly.toml`,
         dockerfile: `${agentPrefix}Dockerfile`,

package/dist/cli/commands/deploy/railway.js

@@ -1,6 +1,6 @@
 /**
- * `deploy railway`: a thin config file, scale-to-zero is a manual dashboard step, the URL is minted
- * (see planRailwayDeploy). `--run` drives the railway CLI to completion; otherwise print the runbook.
+ * `deploy railway`: a thin config file, scale-to-zero is a manual dashboard step, the URL is minted (see
+ * planRailwayDeploy).
  */
 import { basename } from "node:path";
 import { dockerfilePathVar, isGeneratedRailwayJson, planRailwayDeploy, toRailwayName, } from "../../../deploy/railway/plan.js";
@@ -12,22 +12,22 @@ export const railwayHost = {
     isOurs: (path, content) => path.endsWith("railway.json") && isGeneratedRailwayJson(content),
     async deploy(ctx) {
         const { opts, agentDir, workspace, pre, channels, write } = ctx;
-        const { hasTimeTriggers, modelAuth, modelKeyInDefinition, authPath, container, extraSecrets } = pre;
+        const { hasCron, modelAuth, modelKeyInDefinition, authPath, container, declaredSecrets, values, valueFile } = pre;
         const serviceName = toRailwayName(basename(workspace));
         const plan = planRailwayDeploy({
             serviceName,
             modelAuth,
             channels,
-            extraSecrets,
-            hasTimeTriggers,
+            secrets: pre.secrets,
+            hasCron,
             ...container,
         });
         await write(plan.artifacts, { force: !!opts.force });
         if (opts.run) {
-            // The BUILD entry is guaranteed by the RAILWAY_DOCKERFILE_PATH service variable the runner sets
-            // (Railway's documented non-root-Dockerfile route), and Railway's default restart policy already
-            // equals the file's ON_FAILURE — the dashboard-only Config-as-code pointer only adds the /health
-            // deploy gate (boot-crash visibility), so it is an OPTIONAL note, not a gate.
+            // The BUILD entry is guaranteed by the RAILWAY_DOCKERFILE_PATH service variable the runner sets (Railway's
+            // documented non-root-Dockerfile route), and Railway's default restart policy already equals the file's
+            // ON_FAILURE — the dashboard-only Config-as-code pointer only adds the /health deploy gate (boot-crash
+            // visibility), so it is an OPTIONAL note, not a gate.
             console.error(`[fastagent] note: optional — point the service at fastagent/railway.json (Service → Settings → ` +
                 `Config-as-code, dashboard-only) so the /health healthcheck marks a boot-crashing deploy as FAILED; ` +
                 `the build already uses fastagent/Dockerfile via the RAILWAY_DOCKERFILE_PATH variable`);
@@ -39,7 +39,9 @@ export const railwayHost = {
                 modelKeyInDefinition,
                 authPath,
                 channels,
-                extraSecrets,
+                declaredSecrets,
+                values,
+                valueFile,
                 intoLinked: !!opts.intoLinked,
                 dockerfilePath: dockerfilePathVar(pre.container.agentPrefix),
             });
@@ -48,13 +50,7 @@ export const railwayHost = {
         return;
     },
 };
-/**
- * `deploy railway --run`: drive the railway CLI to completion. Mirrors the fly driver — same
- * credential carry (env key OR the OAuth auth.json as `FASTAGENT_AUTH_SEED`) via {@link carryCredentials},
- * same runner seam (spawned `railway`, cwd = the workspace so `railway up`'s upload is the whole workspace). The
- * Railway-specific sequence (linked-check → init/add/volume when fresh → variables → up → domain →
- * webhook) lives in {@link deployRailwayRun}; see there for why Railway differs from Fly.
- */
+/** `deploy railway --run`: drive the railway CLI to completion. */
 async function runDeployRailway(params) {
     const { agentDir, workspace, name, channels, intoLinked, dockerfilePath } = params;
     const railway = spawnRunner("railway", workspace);
@@ -64,7 +60,16 @@ async function runDeployRailway(params) {
     }
     const { secrets, missingSecrets, needsModelCredential } = await carryCredentials(params);
     gateOnModelCredential(needsModelCredential);
-    const outcome = await deployRailwayRun({ name, mountPath: "/data", secrets, missingSecrets, channels, intoLinked, dockerfilePath }, railway, (m) => console.error(`[fastagent] ${m}`), registrarsFor(agentDir));
+    const outcome = await deployRailwayRun({
+        name,
+        mountPath: "/data",
+        secrets,
+        missingSecrets,
+        valueFile: params.valueFile,
+        channels,
+        intoLinked,
+        dockerfilePath,
+    }, railway, (m) => console.error(`[fastagent] ${m}`), registrarsFor(agentDir));
     if (!outcome.ok)
         failStartup(new Error(`deploy stopped: ${outcome.gate}`));
     console.error(`[fastagent] deployed → ${outcome.url}`);

package/dist/cli/commands/deploy/shared.d.ts

@@ -2,21 +2,19 @@ import type { DeclaredChannel } from "../../../channels/discover.ts";
 import type { Registrars } from "../../../deploy/channel-ingress.ts";
 import type { DeployPreflight } from "../../../deploy/preflight.ts";
 import type { FastagentConfig } from "../../../engines/pi/config.ts";
+import type { DeclaredSecret } from "../../../declared-secrets.ts";
 export interface DeployOptions {
     run?: boolean;
     tunnel?: boolean;
     force?: boolean;
-    stop?: boolean;
-    /** false ⇔ `--no-scale-to-zero`. */
-    scaleToZero?: boolean;
     intoLinked?: boolean;
-    model?: string;
-    authPath?: string;
     /** false ⇔ `--no-input`. */
     input?: boolean;
 }
-/** What the dispatcher resolved before handing off: the placement, the flags, the config and the
- *  host-neutral pre-flight, plus the channel lists every host asks about. */
+/**
+ * What the dispatcher resolved before handing off: the placement, the flags, the config and the host-neutral
+ * pre-flight, plus the channel lists every host asks about.
+ */
 interface DeployContext {
     opts: DeployOptions;
     agentDir: string;
@@ -28,10 +26,7 @@ interface DeployContext {
     channels: readonly DeclaredChannel[];
     webhookChannels: readonly DeclaredChannel[];
     longConnectionChannels: readonly DeclaredChannel[];
-    /** Write this host's planned artifacts into the workspace under the ownership rule. The dispatcher
-     *  binds {@link HostDeploy.isOurs} — a host cannot name a predicate here, because every host's has
-     *  the same type: passing a neighbour's, or forgetting a new host's, type-checks and then silently
-     *  turns `--force` into a no-op for that host's own artifact. */
+    /** Write this host's planned artifacts into the workspace under the ownership rule. */
     write(artifacts: {
         path: string;
         content: string;
@@ -40,75 +35,61 @@ interface DeployContext {
         alwaysWrite?: string[];
     }): Promise<void>;
 }
-/** One deploy target, as the dispatcher sees it. A new host is a `deploy/<host>/` (plan + driver)
- *  plus one of these beside it, and a row in `HOSTS` (cli/commands/deploy.ts). */
+/** One deploy target, as the dispatcher sees it. */
 export interface HostDeploy {
-    /** Did this host generate the file at `path`? Only the host's OWN artifacts — the container's
-     *  (Dockerfile, .dockerignore) are answered by {@link writeArtifacts} itself. Read only through the
-     *  {@link DeployContext.write} the dispatcher binds from it. */
+    /** Did this host generate the file at `path`? */
     isOurs(path: string, content: string): boolean;
-    /** Plan the artifacts from the pre-flight facts and what is on disk, write them, then either drive
-     *  the host CLI (`--run`) or print the runbook. Exits through `failStartup` on a gate. */
+    /**
+     * Plan the artifacts from the pre-flight facts and what is on disk, write them, then either drive the host CLI
+     * (`--run`) or print the runbook.
+     */
     deploy(ctx: DeployContext): Promise<void>;
 }
-/** The registrars every host driver gets. One wiring: a channel's credentials are the channel's, not
- *  the host's, so which of them can run end-to-end never varies by deployment target.
- *
- *  All three get {@link DEPLOY_REGISTRATION_ATTEMPTS} rather than the default: a host CLI returns
- *  before the deployment answers, and a registration that gives up first GATES the deploy — reporting
- *  a working deployment as one to re-run. `dev --tunnel` keeps the shorter default; it is a resident
- *  process whose URL is live when it is printed, as does `deploy docker --run` — it reuses that same
- *  announcer, having already health-probed the container and waited for the Quick Tunnel URL.
- *
- *  Accepted cost: pointChannelsAt registers serially, so a deployment whose channels are ALL
- *  unreachable spends the budget once per channel (3 x 180s) before it gates. Registering in parallel
- *  would not shorten a single failing channel, and the failing case is the one nobody is waiting on. */
+/** The registrars every host driver gets. */
 export declare function registrarsFor(agentDir: string): Registrars;
 /**
- * The `--run` credential carry, for every host: the local model credential (an env key, or the whole
- * auth.json as a `FASTAGENT_AUTH_SEED`) plus channel secrets. Four drivers assembled this identically.
+ * The `--run` carry, for every host: the value file's variables plus the local model credential (an env key, or the
+ * whole auth.json as a `FASTAGENT_AUTH_SEED`).
  */
 export declare function carryCredentials(params: {
     modelAuth: string | undefined;
     modelKeyInDefinition: boolean;
     authPath: string;
-    channels: readonly DeclaredChannel[];
-    extraSecrets: string[];
+    declaredSecrets: readonly DeclaredSecret[];
+    /** The deployed environment's declaration, from the pre-flight's single read. */
+    values: ReadonlyMap<string, string>;
 }): Promise<{
     secrets: Record<string, string>;
     missingSecrets: string[];
     needsModelCredential: boolean;
 }>;
-/** Gate a `--run` that has no model credential to carry. Its remediation is `fastagent login`, which
- *  is why it is separate from `missingSecrets` (a `.env` fix) rather than folded into it. Docker states
- *  the same gate inside its driver, where it belongs after the daemon check. */
+/** Gate a `--run` that has no model credential to carry. */
 export declare function gateOnModelCredential(needsModelCredential: boolean): void;
+/** One artifact's verdict under the ownership rule: the bytes to write, or `undefined` to keep what is there. */
+type ArtifactStep = {
+    abs: string;
+    content: string | undefined;
+    message: string;
+};
+/** What `target` would become, and which generated artifacts have drifted from this definition. */
+export type ArtifactPlan = {
+    steps: ArtifactStep[];
+    stale: string[];
+};
 /**
- * Write each generated artifact under `target`, under ONE ownership rule: **deploy only ever overwrites
- * its own output.** Each generated file opens with a marker, so a file on disk is either OURS (a previous
- * `deploy` wrote it) or the author's — and `--force` means "my generated artifact is authoritative",
- * which never licenses clobbering a file we did not write. To hand a path back to fastagent, delete it.
- *
- * That single rule replaced a second mechanism (a per-host list of paths exempt from `--force`), which
- * only described one shape: with the agent inside the workspace, the root `.dockerignore` is the
- * WORKSPACE's file and was listed; with the agent flat, the list was empty — so `--force` would have
- * overwritten a hand-written root `Dockerfile` in a repository `init --flat` had explicitly adopted.
- * Ownership is a property of the file, not of where the agent sits.
- *
- * A KEPT file of OURS that no longer matches what deploy would generate now (config/channel/lockfile/
- * version drift — or the author's edits, which we cannot tell apart) is flagged stale; `--force`
- * regenerates that one.
- *
- * Exported for its own test — this is a four-branch state machine over (exists, ours, force) that used
- * to be proven by spawning the CLI eight times, which is command LOGIC re-run through a subprocess
- * (see vitest.config.ts) and the suite's slowest test.
+ * Decide what happens to each generated artifact under `target`, under ONE ownership rule — reading only, so a
+ * caller can refuse a run BEFORE anything is on disk. `stale` names the paths that would be kept while no longer
+ * matching what this definition generates: a fact, not a verdict, because only the caller knows whether this run is
+ * about to deploy from one.
  */
-export declare function writeArtifacts(target: string, artifacts: {
+export declare function planArtifacts(target: string, artifacts: {
     path: string;
     content: string;
 }[], options: {
     force: boolean;
     alwaysWrite?: string[];
     isOurs: HostDeploy["isOurs"];
-}): Promise<void>;
+}): Promise<ArtifactPlan>;
+/** Carry out a {@link planArtifacts} decision. Reports each path, written or kept. */
+export declare function applyArtifactPlan(plan: ArtifactPlan): Promise<void>;
 export {};

package/dist/cli/commands/deploy/shared.js

@@ -1,7 +1,6 @@
 /**
- * What every host's deploy command shares: the context the dispatcher hands a host, the artifact
- * writer with its ownership rule, and the `--run` credential carry. Host facts live in
- * `cli/commands/deploy/<host>.ts`; this file holds nothing that names one.
+ * What every host's deploy command shares: the context the dispatcher hands a host, the artifact writer with its
+ * ownership rule, and the `--run` credential carry.
  */
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
@@ -10,21 +9,11 @@ import { DEPLOY_REGISTRATION_ATTEMPTS } from "../../../channels/registration.js"
 import { registerSlackWebhook } from "../../../channels/slack/register-webhook.js";
 import { registerTelegramWebhook } from "../../../channels/telegram/register-webhook.js";
 import { isGeneratedDockerfile, isGeneratedDockerignore } from "../../../deploy/container.js";
+import { RELEASE_FILE } from "../../../deploy/workspace.js";
 import { assembleSecrets } from "../../../deploy/secrets.js";
 import { exists, resolveStateRoot } from "../../../paths.js";
 import { failStartup } from "../../fail.js";
-/** The registrars every host driver gets. One wiring: a channel's credentials are the channel's, not
- *  the host's, so which of them can run end-to-end never varies by deployment target.
- *
- *  All three get {@link DEPLOY_REGISTRATION_ATTEMPTS} rather than the default: a host CLI returns
- *  before the deployment answers, and a registration that gives up first GATES the deploy — reporting
- *  a working deployment as one to re-run. `dev --tunnel` keeps the shorter default; it is a resident
- *  process whose URL is live when it is printed, as does `deploy docker --run` — it reuses that same
- *  announcer, having already health-probed the container and waited for the Quick Tunnel URL.
- *
- *  Accepted cost: pointChannelsAt registers serially, so a deployment whose channels are ALL
- *  unreachable spends the budget once per channel (3 x 180s) before it gates. Registering in parallel
- *  would not shorten a single failing channel, and the failing case is the one nobody is waiting on. */
+/** The registrars every host driver gets. */
 export function registrarsFor(agentDir) {
     const attempts = DEPLOY_REGISTRATION_ATTEMPTS;
     return {
@@ -34,64 +23,47 @@ export function registrarsFor(agentDir) {
     };
 }
 /**
- * The `--run` credential carry, for every host: the local model credential (an env key, or the whole
- * auth.json as a `FASTAGENT_AUTH_SEED`) plus channel secrets. Four drivers assembled this identically.
+ * The `--run` carry, for every host: the value file's variables plus the local model credential (an env key, or the
+ * whole auth.json as a `FASTAGENT_AUTH_SEED`).
  */
 export async function carryCredentials(params) {
-    const { modelAuth, modelKeyInDefinition, authPath, channels, extraSecrets } = params;
+    const { modelAuth, modelKeyInDefinition, authPath, declaredSecrets, values } = params;
     return assembleSecrets({
         modelAuth,
         modelKeyInDefinition,
         authFile: (await exists(authPath)) ? await readFile(authPath) : undefined,
-        channels,
-        extraSecrets,
-        env: process.env,
+        declared: declaredSecrets,
+        values,
     });
 }
-/** Gate a `--run` that has no model credential to carry. Its remediation is `fastagent login`, which
- *  is why it is separate from `missingSecrets` (a `.env` fix) rather than folded into it. Docker states
- *  the same gate inside its driver, where it belongs after the daemon check. */
+/** Gate a `--run` that has no model credential to carry. */
 export function gateOnModelCredential(needsModelCredential) {
     if (!needsModelCredential)
         return;
     failStartup(new Error(`deploy stopped: no model credential — run \`fastagent login\`, or set a provider API key in .env, then re-run`));
 }
 /**
- * Write each generated artifact under `target`, under ONE ownership rule: **deploy only ever overwrites
- * its own output.** Each generated file opens with a marker, so a file on disk is either OURS (a previous
- * `deploy` wrote it) or the author's — and `--force` means "my generated artifact is authoritative",
- * which never licenses clobbering a file we did not write. To hand a path back to fastagent, delete it.
- *
- * That single rule replaced a second mechanism (a per-host list of paths exempt from `--force`), which
- * only described one shape: with the agent inside the workspace, the root `.dockerignore` is the
- * WORKSPACE's file and was listed; with the agent flat, the list was empty — so `--force` would have
- * overwritten a hand-written root `Dockerfile` in a repository `init --flat` had explicitly adopted.
- * Ownership is a property of the file, not of where the agent sits.
- *
- * A KEPT file of OURS that no longer matches what deploy would generate now (config/channel/lockfile/
- * version drift — or the author's edits, which we cannot tell apart) is flagged stale; `--force`
- * regenerates that one.
- *
- * Exported for its own test — this is a four-branch state machine over (exists, ours, force) that used
- * to be proven by spawning the CLI eight times, which is command LOGIC re-run through a subprocess
- * (see vitest.config.ts) and the suite's slowest test.
+ * Decide what happens to each generated artifact under `target`, under ONE ownership rule — reading only, so a
+ * caller can refuse a run BEFORE anything is on disk. `stale` names the paths that would be kept while no longer
+ * matching what this definition generates: a fact, not a verdict, because only the caller knows whether this run is
+ * about to deploy from one.
  */
-export async function writeArtifacts(target, artifacts, options) {
+export async function planArtifacts(target, artifacts, options) {
+    const plan = { steps: [], stale: [] };
+    const write = (path, abs, content) => plan.steps.push({ abs, content, message: `[fastagent] wrote ${path}` });
+    const keep = (abs, message) => plan.steps.push({ abs, content: undefined, message });
     for (const a of artifacts) {
         const abs = join(target, a.path);
         // Pure build output, not operator-owned configuration. It must track the generated template/runbook.
-        if (options.alwaysWrite?.includes(a.path)) {
-            await mkdir(dirname(abs), { recursive: true });
-            await writeFile(abs, a.content);
-            console.error(`[fastagent] wrote ${a.path}`);
+        if (a.path.endsWith(`/${RELEASE_FILE}`) || options.alwaysWrite?.includes(a.path)) {
+            write(a.path, abs, a.content);
             continue;
         }
         const existing = (await exists(abs)) ? await readFile(abs, "utf8") : undefined;
         const ours = existing !== undefined && isOurArtifact(a.path, existing, options.isOurs);
         if (existing !== undefined && !ours) {
-            // Only the `.dockerignore` has content checks in preflight — pointing at "the preflight warnings"
-            // for the other kinds would send the reader looking for output that is never printed.
-            console.error(`[fastagent] kept ${a.path} — not generated by fastagent, so --force does not touch it ` +
+            // Only the `.dockerignore` has content checks in preflight.
+            keep(abs, `[fastagent] kept ${a.path} — not generated by fastagent, so --force does not touch it ` +
                 `(delete it to let deploy own the path)` +
                 (a.path.endsWith(".dockerignore")
                     ? `; see the preflight warnings for what it must exclude`
@@ -101,20 +73,29 @@ export async function writeArtifacts(target, artifacts, options) {
             continue;
         }
         if (existing !== undefined && !options.force) {
-            console.error(existing !== a.content
-                ? `[fastagent] kept ${a.path} — it no longer matches what deploy would generate (config changed, or ` +
-                    `you edited it); pass --force to regenerate.`
+            if (existing !== a.content)
+                plan.stale.push(a.path);
+            keep(abs, existing !== a.content
+                ? `[fastagent] kept ${a.path} — it no longer matches what deploy would generate; pass --force to ` +
+                    `regenerate.`
                 : `[fastagent] kept ${a.path} (unchanged)`);
             continue;
         }
-        await mkdir(dirname(abs), { recursive: true }); // artifacts live under fastagent/
-        await writeFile(abs, a.content);
-        console.error(`[fastagent] wrote ${a.path}`);
+        write(a.path, abs, a.content);
     }
+    return plan;
 }
-/** Did fastagent generate the file at `path`? The container's two artifacts are every host's; the
- *  rest is the host's own answer. A kind neither names is permanently classified as the author's,
- *  which silently turns `--force` into a no-op for that file. */
+/** Carry out a {@link planArtifacts} decision. Reports each path, written or kept. */
+export async function applyArtifactPlan(plan) {
+    for (const step of plan.steps) {
+        if (step.content !== undefined) {
+            await mkdir(dirname(step.abs), { recursive: true }); // artifacts live under fastagent/
+            await writeFile(step.abs, step.content);
+        }
+        console.error(step.message);
+    }
+}
+/** Did fastagent generate the file at `path`? */
 function isOurArtifact(path, content, host) {
     if (path.endsWith("Dockerfile"))
         return isGeneratedDockerfile(content);

package/dist/cli/commands/deploy.d.ts

@@ -1,41 +1,24 @@
 /**
- * `fastagent deploy <host> [dir]`: generate host artifacts from the resolved definition and print an
- * ordered deploy runbook. Host-scoped (`docker` | `fly` | `railway` — the extension seam). It does NOT
- * run the host CLI by default: fastagent owns the definition-aware artifacts and precise runbook;
- * Docker may opt into a generated ephemeral tunnel, while durable ingress stays operator-owned. The pre-flight
- * (config/model/channels/container facts) is host-neutral; each host's module (`./deploy/<host>.ts`)
- * adds its artifacts, its kept-file semantics, its gates and its `--run` drive over the neutral
- * `deploy/<host>/` plan + driver. Read-only on the definition; the only writes are generated
- * artifacts (never clobbered without --force). `--run` drives the target CLI instead of printing.
+ * `fastagent deploy <host> [dir]`: generate host artifacts from the resolved definition and print an ordered deploy
+ * runbook.
  */
 import type { DeployHost } from "../../deploy/hosts.ts";
-import { type DeployOptions, type HostDeploy, writeArtifacts } from "./deploy/shared.ts";
-export { writeArtifacts };
-/** Every host, by the name the CLI takes. Typed over {@link DeployHost} so a host added to the list
- *  without a module here fails to compile. */
+import { type DeployOptions, type HostDeploy, applyArtifactPlan, planArtifacts } from "./deploy/shared.ts";
+export { applyArtifactPlan, planArtifacts };
+/** Every host, by the name the CLI takes. */
 export declare const HOSTS: Record<DeployHost, HostDeploy>;
-/** A flag exactly one host honours, and what the OTHERS do instead. `instead` is exhaustive over the
- *  non-owners, so a host added to `DEPLOY_HOSTS` cannot silently lose its line. */
+/** A flag exactly one host honours, and what the OTHERS do instead. */
 interface HostOnlyFlag<Owner extends DeployHost> {
     flag: string;
     owner: Owner;
     passed: (opts: DeployOptions) => boolean;
     instead: Record<Exclude<DeployHost, Owner>, string>;
 }
+/** ONE table for "this flag belongs to that host", because the fact is symmetric and was not stored that way. */
+export declare const HOST_ONLY_FLAGS: HostOnlyFlag<"railway">[];
 /**
- * ONE table for "this flag belongs to that host", because the fact is symmetric and was not stored
- * that way: each host branch stated the OTHER hosts' flags in its own words, so the same sentence
- * existed three times per flag and had already drifted (`Railway-only` twice, `railway-only` once).
- *
- * Every row is a flag that only WARNS elsewhere. `--tunnel` is host-only too and is deliberately not
- * here: it is a usage GATE (`failUsage`, exit 2) raised in `runDeploy`, not a warning — moving it in
- * would downgrade a refusal to a line of advice.
- *
- * Exported for the exhaustiveness test: the type stops a missing `instead` line, and the test stops it
- * from being typed away.
+ * Exported for its own test: nothing covered these six sentences, which is how three of them came to disagree about
+ * the spelling of a host name.
  */
-export declare const HOST_ONLY_FLAGS: (HostOnlyFlag<"fly"> | HostOnlyFlag<"railway">)[];
-/** Exported for its own test: nothing covered these six sentences, which is how three of them came to
- *  disagree about the spelling of a host name. */
 export declare function warnHostOnlyFlags(host: DeployHost, opts: DeployOptions): void;
 export declare function runDeploy(host: DeployHost, dirArg: string, opts: DeployOptions): Promise<void>;