@fastagent-sh/fastagent 0.21.0 → 0.22.0

package/dist/deploy/preflight.js

@@ -1,96 +1,114 @@
 /**
- * The host-NEUTRAL deploy pre-flight: everything `fastagent deploy <host>` computes and checks BEFORE
- * the target branch (Docker / Fly / Railway). Model-travel gate, channel discovery, model-auth probe, the
- * container facts + their warnings, and the hand-written-Dockerfile apt warning are identical on every
- * host — so they live here, out of the CLI dispatcher, testable in isolation (call it against a temp dir
- * and assert the gate / messages / facts). The CLI stays thin: run this, print the messages, branch by host.
- *
- * It returns messages rather than printing them (the CLI owns stderr) and a `{ ok }` outcome mirroring
- * the run modules' {@link import("./fly/run.ts").FlyRunOutcome}: a model that won't travel is a GATE the
- * CLI stops on, distinct from the advisory warnings/notes it prints and proceeds past.
+ * The host-NEUTRAL deploy pre-flight: everything `fastagent deploy <host>` computes and checks BEFORE the target
+ * branch (Docker / Fly / Railway).
  */
-import { readdir, readFile } from "node:fs/promises";
-import { basename, isAbsolute, join, relative, sep } from "node:path";
-import ignore from "ignore";
-import { classifyBind } from "../bind.js";
-import { resolveAuthPath } from "../engines/pi/config.js";
-import { resolveSecretsDir, resolveStateRoot, exists, readTextIfExists } from "../paths.js";
+import { readFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { basename, join, relative } from "node:path";
+import { isModelSpec, isReleaseAgentName } from "./workspace.js";
+import { providerOf, resolveAuthPath } from "../engines/pi/config.js";
+import { AGENT_MODELS_FILE, exists } from "../paths.js";
 import { inspectChannels } from "../channels/discover.js";
-import { discoverScheduleFiles } from "../schedule/discover.js";
-import { createPiModelRuntime, modelCredentialCarry, probeAuthSource } from "../engines/pi/models.js";
+import { loadRoutines } from "../schedule/discover.js";
+import { resolveAgentTools } from "../engines/pi/create.js";
+import { allSecrets } from "../declared-secrets.js";
+import { createPiModelRuntime, literalKeyProviders, isBuiltinProvider, machineModels, modelCredentialCarry, probeAuthSource, } from "../engines/pi/models.js";
 import { CHANNEL_KINDS } from "../scaffold/add-channel.js";
 import { detectRuntime, readPackageJson } from "../runtime.js";
 import { fastagentVersion } from "../version.js";
-import { isGeneratedDockerfile, isGeneratedDockerignore } from "./container.js";
-import { CONTROL_TOKEN_ENV } from "../channels/control.js";
-import { isEnvKey } from "./secrets.js";
-/**
- * "Would docker's packer drop this path?" — built from a `.dockerignore`'s text via the `ignore`
- * matcher (the same library the workspace ignore files use), so `!` negation and last-match-wins are
- * the library's problem, not ours. Anchoring is normalized: dockerignore patterns are root-anchored
- * while .gitignore's match at any depth, so a bare `foo` becomes `/foo` — without that, a root-only
- * `.secrets` line would read as covering `fastagent/.secrets` and hand back a false all-clear on the
- * exact check that guards credentials.
- *
- * Known dialect gap: `ignore` keeps git's rule that a path under an EXCLUDED directory cannot be
- * re-included, which docker does not have — so an allowlist file (`*` + `!fastagent` + `!fastagent/**`)
- * can read as excluding a path docker would ship. The callers below absorb that: the drop-the-agent
- * gate requires the agent DIRECTORY itself to read as excluded too, which an allowlist re-includes.
- */
-function dockerignoreMatcher(text) {
-    const anchored = text
-        .split("\n")
-        .map((raw) => {
-        const line = raw.trim();
-        if (line === "" || line.startsWith("#"))
-            return line;
-        const negated = line.startsWith("!");
-        const pattern = negated ? line.slice(1) : line;
-        if (pattern.startsWith("/") || pattern.startsWith("**/"))
-            return line;
-        return `${negated ? "!" : ""}/${pattern}`;
-    })
-        .join("\n");
-    const matcher = ignore({ ignorecase: false }).add(anchored);
-    return (path) => matcher.ignores(path);
+import { isGeneratedDockerfile } from "./container.js";
+import { buildContextPaths, checkKeptIgnoreFiles } from "./build-context.js";
+import { CRON_CAN_BE_EXTERNAL, residencyFor } from "./residency.js";
+import { dotEnvPath, loadEnvValues } from "../env.js";
+import { deploymentSecrets, isEnvKey } from "./secrets.js";
+import { DEFAULT_HTTP_PORT, describeAnonymousSurface, shouldServeRun } from "../service.js";
+import { CONTROL_PREFIX } from "../channels/control.js";
+/** The pre-flight's one early exit: thrown by a check, turned into `{ ok: false, gate }` by {@link preflightDeploy}. */
+class DeployGate {
+    text;
+    constructor(text) {
+        this.text = text;
+    }
 }
-/**
- * Run the host-neutral pre-flight. Throws on a real fault (an unreadable channels/ dir, a throwing
- * provider) — the CLI wraps the call in its `failStartup` so the fault surfaces and exits, never silently.
- */
+/** Run the host-neutral pre-flight. */
 export async function preflightDeploy(input) {
-    const { placement: { agentDir, workspace }, config, modelSpec, run, force, externalClock, authPathFlag, } = input;
-    // The ONE derived placement fact every host plan needs: where the agent's files sit relative to the
-    // build context (the workspace). Nested → "fastagent/"; flat → "" (the agent IS the workspace root).
-    const nested = agentDir !== workspace;
-    const agentPrefix = nested ? `${basename(agentDir)}/` : "";
     const messages = [];
-    // The deployed box resolves the model from fastagent.config.ts ONLY (in the image); a model set via
-    // env/flag/.env doesn't travel. `--run` would ship a known crash-loop — hard gate; generate-only warns.
-    const modelIssue = modelTravelIssue(config.model, modelSpec);
-    if (modelIssue) {
-        if (run)
-            return { ok: false, gate: modelIssue };
-        messages.push({ level: "warn", text: modelIssue });
+    const report = {
+        note: (text) => void messages.push({ level: "note", text }),
+        warn: (text) => void messages.push({ level: "warn", text }),
+        issue: (text) => {
+            if (input.run)
+                throw new DeployGate(text);
+            messages.push({ level: "warn", text });
+        },
+    };
+    try {
+        return { ok: true, messages, ...(await gatherFacts(input, report)) };
+    }
+    catch (error) {
+        if (error instanceof DeployGate)
+            return { ok: false, gate: error.text };
+        throw error;
+    }
+}
+async function gatherFacts(input, report) {
+    const { placement: { agentDir, workspace }, config, force, externalClock, publicUrl = true, } = input;
+    // The release manifest carries this name into the container, where it is joined onto the storage root — so `init`'s
+    // "one path segment" is not enough here.
+    if (!isReleaseAgentName(basename(agentDir))) {
+        throw new DeployGate(`the agent directory "${basename(agentDir)}" cannot be deployed — a deployed agent directory ` +
+            `may use only letters, digits, "-" and "_"; rename it (the fastagent.config.ts inside is what ` +
+            `makes it an agent, never its name)`);
     }
-    // The control plane on a deployed box: `start` honors `sessionControl: true`, so `/control/*`
-    // (steer, stop, rewrite or delete a session) rides the PUBLIC host URL, protected only by the bearer token. The token
-    // travels as a deploy secret (see extraSecrets below) so the caller has it; the reach still warrants
-    // a warning — the tunnel path warns loudly and deploy must not be the silent second way to break the
-    // loopback trust story.
-    if (config.sessionControl === true) {
-        messages.push({
-            level: "warn",
-            text: `sessionControl: true — the deployed box serves /control/* (steer, stop, rewrite or delete a session) at its public URL, ` +
-                `protected only by a bearer token. Set ${CONTROL_TOKEN_ENV} (listed with the other secrets) and give the ` +
-                `same value to callers: attach --url <public-url> --token …. Unset, the box mints its own per boot — ` +
-                `readable only by shelling in (\`docker compose exec\`/\`fly ssh console\`: <stateRoot>/control.json, whose ` +
-                `url field is container-loopback) and replaced on every restart. Front the endpoint with real auth for ` +
-                `anything wider (docs/design/session-control.md §14)`,
-        });
+    const agentPrefix = `${basename(agentDir)}/`;
+    // The model this deployment will run on, and where it came from. Resolved HERE so the plan side and the run side
+    // cannot disagree about it.
+    const valueFile = relative(workspace, dotEnvPath(agentDir));
+    const values = loadEnvValues(dotEnvPath(agentDir));
+    const model = resolveDeployModel(config, values, valueFile);
+    if (model.invalid !== undefined) {
+        // A gate rather than a warning even without `--run`: the release manifest validates the spec on the way out, so
+        // there is no artifact to produce either. Same class as the agent-directory-name gate above.
+        throw new DeployGate(`the model in ${model.source} is not a "provider/modelId" spec: ${JSON.stringify(model.invalid)}`);
     }
-    // Known channel kinds only — a custom channel's secrets/webhook are unknown to us; note and let the
-    // author wire them.
+    if (!model.spec) {
+        const issue = `no model resolves for this deployment — set \`model: "provider/id"\` in fastagent.config.ts (it travels ` +
+            `in the image), or FASTAGENT_MODEL in ${valueFile} (deploy records that one in the release manifest)` +
+            // Whoever has the variable set right here sees `fastagent info` report a model, so "no model resolves" reads
+            // like a bug until the message says which environment was read. It states that fact WITHOUT attributing the
+            // value: it may be the operator's shell, or the first-run picker's own pick a second earlier (which prints
+            // its own "set `model:` in your config" hint), and the two remedies are the two sources named above.
+            (process.env.FASTAGENT_MODEL
+                ? `. Note that a FASTAGENT_MODEL in the environment running deploy is not one of those sources — it ` +
+                    `belongs to this machine, not to the deployment`
+                : ``);
+        report.issue(issue);
+    }
+    else {
+        report.note(`model ${model.spec} (source: ${model.source})`);
+    }
+    const modelSpec = model.spec;
+    // Time triggers (static routines or self-scheduling) need a machine kept running, and a declared schedule also
+    // decides whether `POST /run` mounts — so the load happens HERE, before the warning that has to name it.
+    // Loaded, not just listed: the same load answers "are there time triggers" AND "what did they declare they need".
+    // A file that FAILED to load still counts as a trigger — the author will fix it, and a plan that scaled to zero
+    // because a cron was broken on deploy day would sleep through it afterwards.
+    const loadedRoutines = await loadRoutines(agentDir);
+    // What the PUBLIC host URL answers with no authentication of ours, NAMED FROM WHAT WILL ACTUALLY MOUNT (through the
+    // same `shouldServeRun` the assembly uses), never from the host alone: listing an endpoint this deployment does not
+    // serve is how an operator learns to skim past every deploy warning — the same reason `publicUrl` exists.
+    const unauthenticated = describeAnonymousSurface({
+        invoke: config.http?.invoke !== false,
+        run: loadedRoutines.routines.length > 0 && shouldServeRun(config.http),
+        ...(config.sessionControl === true ? { controlPrefix: CONTROL_PREFIX } : {}),
+    });
+    if (publicUrl && unauthenticated.length > 0) {
+        report.warn(`the deployed box answers ${unauthenticated.join(" and ")} at its public URL, UNAUTHENTICATED — ` +
+            `fastagent authenticates nothing. Put a gateway, an IdP-backed proxy or a private network in front of that ` +
+            `URL (docs/design/session-control.md §14)`);
+    }
+    // Known channel kinds only — a custom channel's webhook (and, unless it declared them, its secrets) are unknown to
+    // us; note and let the author wire them.
     const inspected = await inspectChannels(agentDir);
     if (inspected.failures.length > 0) {
         throw new Error(`cannot inspect channel modules: ${inspected.failures.map((failure) => `${failure.label}: ${failure.message}`).join("; ")}`);
@@ -99,46 +117,45 @@ export async function preflightDeploy(input) {
     for (const { name, ingress } of channels) {
         if (CHANNEL_KINDS.includes(name))
             continue;
-        messages.push({
-            level: "note",
-            text: ingress === "long-connection"
-                ? `long-connection channel "${name}" is custom — configure its secrets yourself; generated deploy plans keep the process running and skip webhook registration`
-                : `route channel "${name}" is custom — configure its secrets and webhook yourself`,
-        });
+        const secretsPart = `its variables travel from ${valueFile} like every other`;
+        report.note(ingress === "long-connection"
+            ? `long-connection channel "${name}" is custom — ${secretsPart}; generated deploy plans keep the process running and skip webhook registration`
+            : `route channel "${name}" is custom — ${secretsPart}; configure its webhook yourself`);
     }
     const longConnectionChannels = channels.filter((c) => c.ingress === "long-connection").map((c) => c.name);
-    // Time triggers (static schedules or self-scheduling) need a machine kept running — unlike a webhook,
-    // nothing external wakes a scale-to-zero box for a cron instant or a wake-up. The note is CONDITIONAL
-    // ("the generated plan…"): in KEEP mode an existing fly.toml is not rewritten — the CLI warns separately
-    // when a kept fly.toml still scales to zero.
-    const hasTimeTriggers = (await discoverScheduleFiles(agentDir)).length > 0 || !!config.selfSchedule;
+    // A ROUTINE IS NOT A CRON. `cron` is a field, so counting routine FILES answered a different question: a
+    // definition whose only routine is reached by name (`POST /run`) would pin one machine up forever and print a
+    // note about a cron instant it does not have. `deploy agentcore` already filtered the same way when it turned
+    // routines into EventBridge rules; this is the other reader of that fact, and they must agree.
+    //
+    // A FAILED file still counts, on the conservative side: it may well declare a cron, and a plan that scaled to
+    // zero because the file did not parse would hide that behind silence.
+    const hasCron = loadedRoutines.routines.some((r) => r.cron !== undefined) || loadedRoutines.failures.length > 0;
     if (longConnectionChannels.length > 0 && !externalClock) {
-        messages.push({
-            level: "note",
-            text: `long-connection channel present (${longConnectionChannels.join(", ")}) — a GENERATED plan keeps one machine running ` +
-                `(an outbound connection cannot wake a scaled-to-zero service).`,
-        });
+        report.note(`long-connection channel present (${longConnectionChannels.join(", ")}) — a GENERATED plan keeps one machine running ` +
+            `(an outbound connection cannot wake a scaled-to-zero service).`);
     }
-    if (hasTimeTriggers && !externalClock) {
-        messages.push({
-            level: "note",
-            text: `schedules/self-scheduling present — a GENERATED plan keeps one machine running (cron/wake has ` +
-                `no external wake-up; scale-to-zero would sleep through them).`,
-        });
+    // A cron has an external substitute, and an operator who is paying for an idle box should be told so — unless a
+    // long connection pins the box anyway, which residency.ts decides.
+    if (hasCron && !externalClock) {
+        const wayOut = residencyFor({ channels, hasCron })?.reason === CRON_CAN_BE_EXTERNAL;
+        report.note(`routines/ present — a GENERATED plan keeps one machine running (nothing wakes this box at a cron ` +
+            `instant).` +
+            (wayOut
+                ? ` To scale to zero instead, keep the time in a scheduler you own and let it call ` +
+                    `\`POST /run\` (an API that runs one declared unit of work by name — docs/api-reference.md#post-run).`
+                : ""));
     }
-    // Probe auth from the SAME project-level file the opener/login use — not the global default, which would
-    // miss a `fastagent login` credential and falsely report "none configured". Through the AGENT's model
-    // surface too (its models.json travels into the image), so a custom endpoint is not read as an unknown
-    // provider — this probe feeds the gate that decides whether `--run` may proceed.
-    const authPath = resolveAuthPath(agentDir, authPathFlag);
-    const models = await createPiModelRuntime({ agentDir, authPath });
+    await checkMachineModels(agentDir, modelSpec, report);
+    // Probe auth from the SAME project-level file the opener/login use, on the registry the DEPLOYED agent has: the
+    // machine's models.json does not ship, so an entry there (a gateway over a built-in provider, a key) must not decide
+    // how the credential reaches the host.
+    const authPath = resolveAuthPath(agentDir);
+    const models = await createPiModelRuntime({ agentDir, auth: { path: authPath }, machineLayer: false });
     let modelAuth = modelSpec ? await probeAuthSource(models, modelSpec) : undefined;
     let modelKeyInDefinition = false;
-    // probeAuthSource answers "is it authenticated here", which is not the deploy question ("how does the
-    // credential REACH the host"). It reports every models.json endpoint as "configured API key" — not an
-    // env-var name — so without this the gate below sees no credential and stops the deploy with two
-    // remedies that are both wrong for such an agent: `fastagent login` cannot serve a custom provider,
-    // and the key is already in the environment.
+    // probeAuthSource answers "is it authenticated here", which is not the deploy question ("how does the credential
+    // REACH the host").
     if (modelSpec && !isEnvKey(modelAuth)) {
         const carry = modelCredentialCarry(models, modelSpec);
         if (carry.envVar)
@@ -146,9 +163,19 @@ export async function preflightDeploy(input) {
         else
             modelKeyInDefinition = carry.inDefinition;
     }
-    // Container facts (shared by every host) + the warnings that follow. The facts describe the AGENT —
-    // its package.json/runtime/lockfile drive the image's install step — never the workspace's (the bake
-    // ships the whole tree, but the workspace's own manifest belongs to its own deploy).
+    // Reported, not refused. Whether a string is a credential is the AUTHOR's knowledge: pi's docs prescribe
+    // `"apiKey": "ollama"` for a keyless local server, and no static rule separates that from a leaked key. The
+    // `.dockerignore` check next to this one IS a gate because it catches a packing rule putting FastAgent's OWN
+    // `.secrets/auth.json` into the image — the framework's doing. This is the author's own committed file.
+    // Asked of EVERY provider, not just the selected model's: the file ships whole.
+    const literalKeys = await literalKeyProviders(agentDir);
+    if (literalKeys.length > 0) {
+        report.warn(`${AGENT_MODELS_FILE} carries a literal apiKey for ${literalKeys.map((id) => `"${id}"`).join(", ")} — that ` +
+            `file ships inside the image, where anyone who can pull it reads the layer. If it is a credential, use ` +
+            `"$YOUR_ENV_VAR" (deploy carries it like any provider key) or "!command" (it runs on the box and never ` +
+            `travels); a placeholder for a keyless local server is fine as it is.`);
+    }
+    // Container facts (shared by every host) + the warnings that follow.
     const hasPackageJson = await exists(join(agentDir, "package.json"));
     const pkg = await readPackageJson(agentDir);
     const { runtime, bunVersion, hasLockfile } = detectRuntime(agentDir, pkg);
@@ -156,300 +183,172 @@ export async function preflightDeploy(input) {
     const runner = runtime === "bun" ? "bun run fastagent" : "./node_modules/.bin/fastagent";
     const hasOtherLock = runtime === "node" &&
         ((await exists(join(agentDir, "pnpm-lock.yaml"))) || (await exists(join(agentDir, "yarn.lock"))));
-    // Does the baked workspace ship a `.git`? ONE fact driving both the image's git install (below)
-    // and the plans' runbook wording — the write-back loop needs the history AND the binary together.
+    // Does the baked workspace ship a `.git`?
     const shipsGit = await exists(join(workspace, ".git"));
-    // After the facts: the deps sentence must match the agent's actual shape (a markdown-only agent has
-    // no package.json and installs nothing — the note must not point at a file that doesn't exist).
+    // After the facts: the deps sentence must match the agent's actual shape (a markdown-only agent has no package.json
+    // and installs nothing — the note must not point at a file that doesn't exist).
     const deps = hasPackageJson
-        ? `only the agent's deps (${agentPrefix}package.json) are installed${nested ? " — the workspace's own deps are the agent's runtime concern" : ""}`
+        ? `only the agent's deps (${agentPrefix}package.json) are installed — the workspace's own deps are the agent's runtime concern`
         : `the agent has no package.json, so no deps are installed (the pinned global CLI serves the directory)`;
-    const durability = shipsGit
-        ? `Un-pushed changes on the box do not survive a redeploy; freshness and write-back run through git, ` +
-            `driven by the agent itself (persona owns the policy; GH_TOKEN etc. go in config.deploy.secrets)`
-        : `no .git here, so no history ships and the image does not install git — changes on the box are ` +
-            `ephemeral and do not survive a redeploy`;
-    messages.push({
-        level: "note",
-        text: `the whole directory is baked as the agent's workspace (WYSIWYG — what you see is what ships, ` +
-            `git or not, clean or not); ${deps}. ${durability}.`,
-    });
-    // A code agent with no lockfile builds via a non-frozen install (ranges resolve at build time) — not
-    // reproducible. A pnpm/yarn user gets an accurate message (their lockfile is ignored by the npm Dockerfile).
+    // What a RELEASE does — host-neutral, because how long the storage under it lives is the host's own answer and its
+    // runbook gives it (a Fly volume outlives every deploy; AgentCore's mount does not).
+    report.note(`the whole directory is baked as the agent's workspace (WYSIWYG — what you see is what ships, ` +
+        `git or not, clean or not); ${deps}. The image seeds the storage once; a later release replaces ` +
+        `only ${agentPrefix} and leaves the rest of the workspace, state and credentials in place — for ` +
+        `how long, see this host's storage note below`);
+    // A code agent with no lockfile builds via a non-frozen install (ranges resolve at build time) — not reproducible.
     if (hasPackageJson && !hasLockfile) {
         const lock = runtime === "bun" ? "bun.lock" : "package-lock.json";
-        messages.push({
-            level: "warn",
-            text: hasOtherLock
-                ? `the generated Dockerfile is npm-based — your pnpm/yarn lockfile is NOT used (build runs ` +
-                    `\`npm install\`, not reproducible). Edit the Dockerfile for your package manager, or vendor a package-lock.json.`
-                : `no ${lock} — the image build resolves deps at build time (not reproducible). ` +
-                    `Run \`${install}\` and commit the lockfile for pinned redeploys.`,
-        });
+        report.warn(hasOtherLock
+            ? `the generated Dockerfile is npm-based — your pnpm/yarn lockfile is NOT used (build runs ` +
+                `\`npm install\`, not reproducible). Edit the Dockerfile for your package manager, or vendor a package-lock.json.`
+            : `no ${lock} — the image build resolves deps at build time (not reproducible). ` +
+                `Run \`${install}\` and commit the lockfile for pinned redeploys.`);
     }
-    // The code-path Dockerfile runs `${runner}` — the agent's OWN local dependency, never the
-    // registry — so a package.json missing it means the container fails at start (no bin to run).
+    // The code-path Dockerfile runs `${runner}`.
     if (hasPackageJson && !("@fastagent-sh/fastagent" in { ...pkg.dependencies, ...pkg.devDependencies })) {
-        messages.push({
-            level: "warn",
-            text: `package.json does not list @fastagent-sh/fastagent — the image's \`${runner}\` has no local bin to run, ` +
-                `so the container fails at start. Add it to dependencies and re-run \`${install}\`.`,
-        });
+        report.warn(`package.json does not list @fastagent-sh/fastagent — the image's \`${runner}\` has no local bin to run, ` +
+            `so the container fails at start. Add it to dependencies and re-run \`${install}\`.`);
     }
-    // A KEPT workspace-root .dockerignore silently replaces the generated one's protections — so ASK IT
-    // about the exact paths that matter (the generic "kept" line suggests --force, which never clobbers
-    // the workspace's own file). Two are GATES under --run, same discipline as the model-travel gate:
-    // dropping the agent dir ships a context with no persona/config (the box crash-loops), and an
-    // unexcluded secrets path BAKES CREDENTIALS INTO THE IMAGE. The other two are advisory: the build
-    // machine's node_modules (native binaries for YOUR OS) clobbering the image's, and an excluded .git
-    // killing the agent's pull/push loop (a legitimate slimming choice). Not force-gated — the file is
-    // kept even under --force.
-    // Which paths INSIDE the build context hold secrets — resolved, then made workspace-relative (the
-    // context root). An external secrets dir (a mounted volume) is outside the context: nothing to check
-    // and nothing to exclude. Also fed to the generated .dockerignore, so a custom in-tree dir is
-    // excluded by PATH even though its name is not `.secrets`.
-    const inContext = (p) => {
-        const rel = relative(workspace, p);
-        return rel === "" || rel.startsWith("..") || isAbsolute(rel) ? undefined : rel.split(sep).join("/");
-    };
-    // The secrets DIR is the unit of RESPONSIBILITY, but never the unit of the leak QUESTION below: the
-    // generated ignore excludes the dir's CONTENTS (`**/.secrets/**`) so its two value-free tracked
-    // scaffolds can be re-included, and a directory-level question reads that correct file as "not
-    // excluded" — the generator's own default output gated its own deploy (field-hit: a fresh
-    // kit-layout workspace without --force; --force skips checking our own file, which is why the
-    // combination stayed invisible). What leaks is a FILE, so files are what the gate asks about — see
-    // secretDirFiles below, which enumerates what is actually inside (an atomic-write temp beside
-    // auth.json, a second key file, an editor backup of `.env`: the dir-as-unit worry, covered per
-    // file). The auth path adds an entry only when an override puts it OUTSIDE that dir. An external
-    // secrets dir (the deployed posture: a mounted volume) is outside the context — nothing to check,
-    // nothing to exclude.
-    const secretsRel = inContext(resolveSecretsDir(agentDir));
-    const authRel = inContext(authPath);
-    const authElsewhere = authRel !== undefined && (secretsRel === undefined || !authRel.startsWith(`${secretsRel}/`));
-    const secretPaths = [...(secretsRel ? [secretsRel] : []), ...(authElsewhere ? [authRel] : [])];
-    // ONE rule for every checked path: a file that is not there cannot be baked, so gating on it would
-    // be a refusal about a spelling rather than about what would ship (an agent that has never run
-    // `login` has no auth.json). The generated .dockerignore still excludes them unconditionally —
-    // cheap, and correct the moment they appear.
-    const present = async (rels) => {
-        const found = [];
-        for (const rel of rels)
-            if (await exists(join(workspace, rel)))
-                found.push(rel);
-        return found;
-    };
-    // State gets the same treatment (a custom in-tree FASTAGENT_STATE_DIR is invisible to the
-    // name-based `**/.state`), at warn level: shipping stale sessions is waste, not a credential leak.
-    const stateRel = inContext(resolveStateRoot(agentDir));
-    // Existence gates the WARNING, never the generated exclude (same split as secretPaths vs
-    // leakCandidates): an agent that has never run has no `.state/`, so telling its author a kept ignore
-    // file fails to exclude one is a remark about a spelling — while the file we generate must still carry
-    // the line, since it is written once and correct the moment the directory appears.
-    const stateShips = stateRel !== undefined && (await exists(join(workspace, stateRel))) ? stateRel : undefined;
-    // The `.env` family at the two levels fastagent is RESPONSIBLE for: the agent dir and the workspace
-    // root. Asking only about a root-level `.env` missed both halves that matter — an `<agent>/.env`, the
-    // file habit puts there (env.ts warns about it by name), and the `.env.local` / `.env.production`
-    // spellings. DISCOVERED rather than spelled, so the existing rule still holds: only a file that is
-    // there can be baked, so only it is gated.
-    //
-    // Deliberately NOT the recursive `**/.env` the generated file carries: walking a whole monorepo for
-    // credential files is a secret scanner, not a placement pre-flight, and a bounded walk would be a
-    // heuristic pretending to be a guarantee. The division of responsibility is the honest one — the file
-    // WE generate covers every level; an author who keeps their own owns its coverage of their own tree,
-    // and this gate speaks only for the paths fastagent itself puts credentials in.
-    const dotEnvFiles = async (relDir) => {
-        const names = await readdir(join(workspace, relDir || ".")).catch(() => []);
-        // POSIX separators, like every other context-relative path here (`inContext`): these strings are
-        // matched against dockerignore patterns, and a Windows `fastagent\.env` would match none of them —
-        // silently turning the one check whose failure mode is "credentials in a published image" into a
-        // no-op.
-        return names
-            .filter((n) => (n === ".env" || n.startsWith(".env.")) && n !== ".env.example")
-            .map((n) => join(relDir, n).split(sep).join("/"));
-    };
-    const envFiles = (await Promise.all([...new Set(["", agentPrefix])].map(dotEnvFiles))).flat();
-    // Everything ACTUALLY inside the secrets dir, minus the two tracked scaffolds the image ships on
-    // purpose (they carry no values; the generated ignore re-includes them by name). Existence is the
-    // enumeration itself — readdir lists exactly what could be baked — and a hand-written ignore that
-    // misses the dir now gates NAMING the leaking file, a better diagnostic than pointing at a
-    // directory. Recurses: a subdirectory inside .secrets is unusual but its files leak all the same.
-    const secretDirFiles = async (dirRel) => {
-        const entries = await readdir(join(workspace, dirRel), { withFileTypes: true }).catch(() => []);
-        const files = [];
-        for (const entry of entries) {
-            if (entry.name === ".gitignore" || entry.name === ".env.example")
-                continue;
-            if (entry.isDirectory())
-                files.push(...(await secretDirFiles(`${dirRel}/${entry.name}`)));
-            else
-                files.push(`${dirRel}/${entry.name}`);
-        }
-        return files;
-    };
-    const leakCandidates = [
-        ...(secretsRel ? await secretDirFiles(secretsRel) : []),
-        ...(await present(authElsewhere && authRel !== undefined ? [authRel] : [])),
-        ...envFiles,
-    ];
-    // Same existence rule: a node_modules that is not there cannot be uploaded.
-    const depDirs = await present([...new Set([`${agentPrefix}node_modules`, "node_modules"])]);
-    const machineryPaths = [...secretPaths, ...(stateRel ? [stateRel] : [])];
-    // BOTH ignore files deploy emits get the same interrogation. The workspace-root one is what
-    // flyctl/railway's packers read; the per-Dockerfile one is what BuildKit PREFERS for a plain
-    // `docker build` (so it is the file that actually decides `deploy docker`). Checking only the root one
-    // left the credential gate not covering the path it was written for.
-    for (const rel of [".dockerignore", `${agentPrefix}Dockerfile.dockerignore`]) {
-        const kept = await readTextIfExists(join(workspace, rel));
-        if (kept === undefined)
-            continue;
-        // One WE generated is regenerated by this very run under --force, so checking the stale content on
-        // disk would gate a deploy on a file about to be replaced. Ours + --force: skip. Ours WITHOUT --force
-        // is still checked (it is what would ship), but the remedy differs: hand-adding lines to fastagent's
-        // own output is not the fix — regenerating it is.
-        const keptIsOurs = isGeneratedDockerignore(kept);
-        if (force && keptIsOurs)
-            continue;
-        const remedy = (lines) => keptIsOurs
-            ? `Re-run with --force to regenerate it.`
-            : `Add ${lines.map((p) => `\`${p}\``).join(" and ")} before deploying (the same lines the generated ${rel} writes).`;
-        const excluded = dockerignoreMatcher(kept);
-        // Asked as a DIRECTORY (trailing slash), which is what it is. A bare-name test answers `false` for
-        // the `fastagent/` spelling — a directory-only pattern, and the one a hand-written ignore file is
-        // most likely to carry — so the agent would be dropped from the context with no warning at all. The
-        // pairing this replaced (the directory AND a file inside it) was dead weight rather than a
-        // safeguard: git's rule that a file under an excluded directory cannot be re-included is
-        // implemented by the matcher, so `excluded(dir)` already implies `excluded(dir/persona.md)` and the
-        // second test could never change the answer. What it was aimed at — an allowlist (`*` +
-        // `!fastagent` + `!fastagent/**`) that re-includes the agent — is handled by the first test alone,
-        // which reads `false` there, as it should.
-        if (nested && excluded(`${basename(agentDir)}/`)) {
-            const text = `your ${rel} (kept) excludes \`${basename(agentDir)}\` — the build context would ship WITHOUT the ` +
-                `agent entirely (the deployed box has no persona/config and crash-loops). Remove that rule ` +
-                `before deploying.`;
-            if (run)
-                return { ok: false, gate: text };
-            messages.push({ level: "warn", text });
-        }
-        // Resolved paths, not spellings: dockerignore patterns are root-anchored (unlike .gitignore), so a
-        // bare `.secrets` line does not cover `fastagent/.secrets` — and FASTAGENT_SECRETS_DIR /
-        // FASTAGENT_AUTH_PATH can put credentials anywhere in the baked tree, where the name-based excludes
-        // never reach. This is the one check whose failure mode is "credentials in a published image".
-        const leaks = leakCandidates.filter((p) => !excluded(p));
-        if (leaks.length > 0) {
-            const text = `your ${rel} (kept) does not exclude ${leaks.map((p) => `\`${p}\``).join(", ")} — the build ` +
-                `context would BAKE SECRETS INTO THE IMAGE. ${remedy(leaks.map((p) => `/${p}`))}`;
-            if (run)
-                return { ok: false, gate: text };
-            messages.push({ level: "warn", text });
-        }
-        if (stateShips && !excluded(`${stateShips}/sessions`)) {
-            messages.push({
-                level: "warn",
-                text: `your ${rel} (kept) does not exclude \`${stateRel}\` — the build machine's sessions/channel state would ship in the image. ${remedy([`/${stateRel}`])}`,
-            });
-        }
-        // Both the agent's own node_modules and the workspace's: either would upload the build machine's
-        // deps (native binaries for YOUR OS) and clobber the image's freshly-installed ones. Named by the
-        // PATHS actually found unexcluded, like every other check here — not by a rule's spelling.
-        const unexcludedDeps = depDirs.filter((p) => !excluded(`${p}/.package-lock.json`));
-        if (unexcludedDeps.length > 0) {
-            messages.push({
-                level: "warn",
-                text: `your ${rel} does not exclude ${unexcludedDeps.map((p) => `\`${p}\``).join(" or ")} — the ` +
-                    `build machine's deps (native binaries for YOUR OS) would be uploaded and clobber the image's ` +
-                    `freshly-installed ones. ${remedy(unexcludedDeps.map((p) => `/${p}`))}`,
-            });
-        }
-        if (excluded(".git/HEAD")) {
-            messages.push({
-                level: "note",
-                text: `your ${rel} excludes .git — the baked copy ships WITHOUT history/remote, so the agent ` +
-                    `cannot pull/commit/push it; it must \`git clone\` its repo in the workspace instead (or remove the .git line).`,
-            });
-        }
-    }
-    // Write-back mechanics are fastagent's (the policy is the persona's): the image carries the git
-    // BINARY iff the baked workspace ships a `.git` (history without the binary is a
-    // dead loop; the binary without history is dead weight). A non-git workspace that still needs git
-    // (the agent clones repos as its job) declares config.deploy.apt: ["git"] explicitly. Merged with
-    // (never duplicating) config.deploy.apt.
+    const paths = await buildContextPaths(workspace, agentDir, agentPrefix, authPath);
+    await checkKeptIgnoreFiles({ workspace, agentDir, agentPrefix, force, paths }, report);
+    // Write-back mechanics are fastagent's (the policy is the persona's).
     const apt = shipsGit ? [...new Set(["git", ...(config.deploy?.apt ?? [])])] : config.deploy?.apt;
     const container = {
+        releaseId: randomUUID(),
         agentPrefix,
-        machineryPaths,
+        machineryPaths: paths.machineryPaths,
         hasPackageJson,
         runtime,
         bunVersion,
         hasLockfile,
         version: await fastagentVersion(),
         apt,
+        ...(model.envValue !== undefined ? { modelSpec: model.envValue } : {}),
         shipsGit,
     };
-    const port = config.http?.port ?? 8787;
-    // `http.host` travels in the artifact (config is what deploy ships), and any non-wildcard value that
-    // is right on a laptop is wrong in a container: the wildcard bind is what makes the published port,
-    // the health check and webhook ingress reachable at all. `--bind` is the local-only knob; config is not.
-    const configBind = classifyBind(config.http?.host);
-    if (configBind !== "wildcard") {
-        const issue = `fastagent.config.ts sets http.host: "${config.http?.host}" — it travels into the image, where ` +
-            (configBind === "loopback"
-                ? `nothing outside the container can reach the serve (published port, health check, webhooks).`
-                : `that address does not exist, so the container fails to bind at start.`) +
-            ` Drop it and use \`--bind ${config.http?.host}\` locally instead.`;
-        // Same disposition as the model-travel issue: warn when producing artifacts (the operator may be
-        // deploying somewhere that fronts the port), gate `--run` — which would otherwise ship a box that
-        // answers nothing, or crash-loops on a bind that cannot resolve inside the container.
-        if (run)
-            return { ok: false, gate: issue };
-        messages.push({ level: "warn", text: issue });
-    }
-    // What the agent declared it needs on the box (fastagent.config deploy.secrets) — carried like channel
-    // secrets: listed in the runbook, set from the local env under --run, gated if a value is missing.
-    const extraSecrets = [...(config.deploy?.secrets ?? [])];
-    // The plane's bearer token is the DEPLOYMENT's secret, not the container's: minted inside the box it
-    // is unreadable from outside and replaced on every restart, which is what makes a public /control/*
-    // unusable. Carried like any declared secret — listed in the runbook, taken from the local env under
-    // --run, gated when absent (never minted: a value minted per deploy rotates under its holder).
-    if (config.sessionControl === true)
-        extraSecrets.push(CONTROL_TOKEN_ENV);
-    // deploy.apt only shapes the GENERATED Dockerfile. Warn ONLY when the kept Dockerfile is HAND-WRITTEN
-    // (its apt won't include these) — a fastagent-generated one is handled by writeArtifacts. Don't suggest
-    // --force here: it would overwrite the user's hand-written file.
-    const dockerfileHome = join(agentDir, "Dockerfile");
-    if (config.deploy?.apt?.length && !force && (await exists(dockerfileHome))) {
-        if (!isGeneratedDockerfile(await readFile(dockerfileHome, "utf8"))) {
-            messages.push({
-                level: "warn",
-                text: `kept your hand-written Dockerfile — deploy.apt (${config.deploy.apt.join(", ")}) is ` +
-                    `NOT applied; install those packages in your Dockerfile.`,
-            });
-        }
+    const port = config.http?.port ?? DEFAULT_HTTP_PORT;
+    // EVERYTHING the definition declared it needs, from wherever it was declared. Read through the SAME resolver
+    // dev/start mount with, so "which tool declarations count" has one answer (config.tools declare too; a shadowed
+    // file's declaration is dropped in both places).
+    const resolvedTools = await resolveAgentTools(config, agentDir, workspace);
+    // A code input we could not READ is a code input whose declarations we cannot carry — and the box
+    // WILL read it (its deps are installed there), so its gate fires after the deploy reported success:
+    // a crash loop, which is the failure mode this whole mechanism exists to move to build time. Under
+    // `--run` that is a gate, like a channel that fails to inspect; generate-only warns, since the
+    // operator may be producing artifacts from a machine that never installed the agent's deps.
+    for (const failure of [...resolvedTools.toolFailures, ...loadedRoutines.failures]) {
+        const issue = `${failure.label} failed to load (${failure.message}) — any secrets it declares cannot be carried ` +
+            `to the host, so the deployed box would refuse to start`;
+        report.issue(issue);
     }
+    const declaredSecrets = [
+        ...allSecrets(resolvedTools.toolSecrets),
+        ...allSecrets(loadedRoutines.secrets),
+        ...allSecrets(inspected.secrets),
+    ];
+    await checkKeptDockerfile(agentDir, config, model.envValue, valueFile, report);
     return {
-        ok: true,
-        messages,
         channels,
-        hasTimeTriggers,
+        hasCron,
+        values,
+        valueFile,
         modelAuth,
         modelKeyInDefinition,
         authPath,
         container,
         port,
-        extraSecrets,
+        declaredSecrets,
+        secrets: deploymentSecrets(modelAuth, declaredSecrets, values, valueFile),
     };
 }
 /**
- * Why the resolved model won't reach the deployed box, or undefined if it will — host-neutral. `fastagent.config.ts`
- * is the model's committed home (config's charter: model / tools / http) and the only source deploy ships:
- * a `--model`/`FASTAGENT_MODEL`/`.env` value is builder-local and doesn't travel (`.env` is dockerignored),
- * so a model NOT in config crash-loops the box with "missing model". The pre-flight warns (runbook) or gates
- * (`--run`). Single source on purpose — a host env block (fly.toml `[env]`) is NOT advertised as a second home.
+ * The machine's models.json is this box's environment, not the artifact: whatever the model takes from it is
+ * absent wherever the agent is deployed. Said in so many words here; the credential probe already reads the deployed
+ * registry.
+ */
+async function checkMachineModels(agentDir, modelSpec, report) {
+    const machine = await machineModels(agentDir);
+    const provider = modelSpec ? providerOf(modelSpec) : undefined;
+    if (provider === undefined || !machine?.inherited.includes(provider))
+        return;
+    if (isBuiltinProvider(provider)) {
+        report.warn(`model "${modelSpec}" takes its "${provider}" entry from ${machine.path}, the machine's models.json, which ` +
+            `does not ship — the deployed agent runs pi's built-in "${provider}" without it. Declare the entry in the ` +
+            `agent's own ${AGENT_MODELS_FILE} to deploy it.`);
+    }
+    else {
+        // No built-in to fall back on: the deployed agent cannot resolve the model at all.
+        const issue = `model "${modelSpec}" exists only in ${machine.path}, the machine's models.json, which does not ship — the ` +
+            `deployed agent would fail with an unknown model. Declare "${provider}" in the agent's own ` +
+            `${AGENT_MODELS_FILE} to deploy it.`;
+        report.issue(issue);
+    }
+}
+/**
+ * What a KEPT hand-written Dockerfile drops. `deploy.apt` is the obvious one; the resolved model is the one that
+ * looks safe and is not: the manifest is always written, but only the generated Dockerfile sets
+ * FASTAGENT_RELEASE_FILE, and without it `prepareStartWorkspace` never reads the manifest — so a model that lives
+ * ONLY in the value file would be reported here and absent on the box.
+ *
+ * NOT conditioned on `!force`: `writeArtifacts` refuses a file it did not generate whatever the flag says, so a
+ * hand-written Dockerfile survives `--force` and drops exactly the same things. Short-circuiting here let
+ * `--run --force` ship the crash-loop this gate exists to stop.
+ */
+async function checkKeptDockerfile(agentDir, config, 
+/** The model the release manifest carries (set only when the value file named it). */
+modelFromValueFile, valueFile, report) {
+    const dockerfileHome = join(agentDir, "Dockerfile");
+    const dockerfileText = (await exists(dockerfileHome)) ? await readFile(dockerfileHome, "utf8") : undefined;
+    if (dockerfileText === undefined || isGeneratedDockerfile(dockerfileText))
+        return;
+    if (config.deploy?.apt?.length) {
+        report.warn(`kept your hand-written Dockerfile — deploy.apt (${config.deploy.apt.join(", ")}) is ` +
+            `NOT applied; install those packages in your Dockerfile.`);
+    }
+    // The INSTRUCTION is the question, not the file's authorship: `prepareStartWorkspace` returns early without
+    // FASTAGENT_RELEASE_FILE, so a Dockerfile that sets it reads the manifest whoever wrote it. This gates rather
+    // than warns because it is about FastAgent's OWN delivery arriving — the model would be reported here and
+    // missing on the box.
+    // Anywhere in an `ENV` instruction, not just first: `ENV A=1 FASTAGENT_RELEASE_FILE=/app/x` is ordinary
+    // Dockerfile style and hard-refusing it would be a false gate. A backslash continuation still reads as absent
+    // (covering it means joining lines first) — the remaining over-strict edge.
+    if (modelFromValueFile !== undefined && !/^\s*ENV\s[^\n]*\bFASTAGENT_RELEASE_FILE[=\s]/m.test(dockerfileText)) {
+        const issue = `your Dockerfile does not set FASTAGENT_RELEASE_FILE, and the model comes from ${valueFile} — it travels ` +
+            `in the release manifest, which is only read when that ENV points at it. Add it (see a generated ` +
+            `Dockerfile), or set \`model\` in fastagent.config.ts so it ships in the config instead.`;
+        report.issue(issue);
+    }
+}
+/**
+ * WHICH model this deployment runs on, and where that came from.
+ *
+ * There is ONE precedence chain — `flag > environment > config.model` — and this is it evaluated in the environment
+ * BEING DEPLOYED rather than in this machine's. That environment is declared by the value file, so the operator's
+ * `process.env` simply is not part of it (the same way `dev` never reads another machine's shell); it needs no rule
+ * of its own. `deploy` has no flag layer either, and that follows from the same model rather than from policy: a
+ * generated Dockerfile is rewritten on every deploy, so a flag baked into one would silently vanish on the next run
+ * that omits it. A file does not.
+ *
+ * The value file is the half of the deployed environment we can DECLARE. The other half — variables the platform
+ * already holds — is still on the box and still outranks the image's own `ENV`, which is exactly why the model is
+ * baked rather than delivered as one more platform variable that nothing would ever clear.
  */
-export function modelTravelIssue(configModel, modelSpec) {
-    if (configModel)
-        return undefined;
-    return modelSpec
-        ? `model "${modelSpec}" is set via --model/FASTAGENT_MODEL, not fastagent.config.ts — it won't reach ` +
-            `the deployed box. Add \`model: "${modelSpec}"\` to fastagent.config.ts.`
-        : `no model in fastagent.config.ts — the deployed box can't resolve one. Add \`model: "provider/id"\`.`;
+function resolveDeployModel(config, values, 
+/** The value file AS READ (it follows `FASTAGENT_SECRETS_DIR`), so the reported source is the real one. */
+valueFile) {
+    const fromEnv = values.get("FASTAGENT_MODEL");
+    const source = fromEnv ? valueFile : "fastagent.config";
+    // BOTH sources are checked, at the one point that reads them: a `provider`-less spec resolves to nothing on the
+    // box, so letting `config.model` through would ship exactly the crash-loop this resolution exists to prevent —
+    // `probeAuthSource` reports "unconfigured" for it here and the failure only appears after deployment.
+    const spec = fromEnv || config.model;
+    if (spec && !isModelSpec(spec))
+        return { source, invalid: spec };
+    // `envValue` is what the release manifest records (ContainerInput.modelSpec), so it is set only when the value file
+    // is the source: a `config.model` already travels in the config itself. The manifest is rewritten by every deploy,
+    // so deleting the line and redeploying simply drops it — nothing stale survives.
+    if (fromEnv)
+        return { spec: fromEnv, source, envValue: fromEnv };
+    return { spec: config.model, source };
 }