@fastagent-sh/fastagent 0.24.4 → 0.26.0

package/dist/deploy/railway/plan.js

@@ -1,55 +1,26 @@
 import { webhookRunbook } from "../channel-ingress.js";
-import { containerArtifacts } from "../container.js";
+import { containerArtifacts, imageHasGit } from "../container.js";
 import { deploymentLoginCommand } from "../box-shell.js";
-import { CRON_CAN_BE_EXTERNAL, WAKEUPS_WHEN_ASLEEP, residencyFor } from "../residency.js";
+import { WAKEUPS_WHEN_ASLEEP, residencyFor } from "../residency.js";
 /** State root = the volume mount path, kept in lockstep. */
 const MOUNT = "/data";
-/** The `RAILWAY_DOCKERFILE_PATH` value for an agent under `prefix`. */
-export const dockerfilePathVar = (prefix) => `/${prefix}Dockerfile`;
-/** The name this tool gives BOTH the project and the service, derived from the workspace directory. */
+/** The name this tool gives BOTH the project and the service, derived from the agent directory's name. */
 export function toRailwayName(basename) {
     return basename.replace(/[^a-zA-Z0-9-]+/g, "-").replace(/^-+|-+$/g, "") || "agent";
 }
-/** railway.json is JSON, so its ownership marker is a KEY rather than a comment line. */
-const GENERATED_RAILWAY_KEY = "x-generated-by";
-const GENERATED_RAILWAY_VALUE = "fastagent deploy railway";
-export function isGeneratedRailwayJson(content) {
-    try {
-        return JSON.parse(content)[GENERATED_RAILWAY_KEY] === GENERATED_RAILWAY_VALUE;
-    }
-    catch {
-        return false;
-    }
-}
-/** railway.json — build/deploy only (Railway's config-as-code scope). */
-function railwayJson(prefix) {
-    return `${JSON.stringify({
-        $schema: "https://railway.com/railway.schema.json",
-        [GENERATED_RAILWAY_KEY]: GENERATED_RAILWAY_VALUE,
-        // dockerfilePath is relative to the workspace root (`railway up`'s upload context).
-        build: { builder: "DOCKERFILE", dockerfilePath: `${prefix}Dockerfile` },
-        deploy: { healthcheckPath: "/health", restartPolicyType: "ON_FAILURE" },
-    }, null, 2)}\n`;
-}
 /** Compute the Railway deploy plan from the resolved definition. */
 export function planRailwayDeploy(input) {
     const { serviceName, channels } = input;
-    // railway.json is namespaced under the agent dir too (the workspace may carry its own railway.toml/json for the
-    // product).
-    const configPath = `${input.agentPrefix}railway.json`;
-    const artifacts = [
-        { path: configPath, content: railwayJson(input.agentPrefix) },
-        ...containerArtifacts(input),
-    ];
+    const artifacts = containerArtifacts(input);
     const secrets = input.secrets ?? [];
     // Order matters, not cosmetics: `railway init` creates a PROJECT with no service, but the volume and variables are
     // service-scoped and `railway up` deploys THE service.
     const runbook = [
-        `# Deploy to Railway. ${configPath} / Dockerfile(.dockerignore) are generated above.`,
+        `# Deploy to Railway. Dockerfile(.dockerignore) are generated above.`,
         `# Prereqs: the Railway CLI (https://docs.railway.com/guides/cli) and \`railway login\`.`,
         ``,
         `# One-time setup (init → service → volume → variables). Skip it on redeploy: repeating it creates`,
-        `# another project/service/volume, splitting the persistent workspace.`,
+        `# another project/service/volume, splitting the agent's state.`,
         ``,
         `# Create + link a project (writes .railway link state in this dir; the project — not a committed`,
         `# file — is Railway's source of truth for identity, variables, and the volume).`,
@@ -64,22 +35,21 @@ export function planRailwayDeploy(input) {
         `railway volume add --mount-path ${MOUNT}`,
         ``,
         `# Variables — set BEFORE the first deploy so the box boots with them. Railway injects PORT itself.`,
-        `# RAILWAY_DOCKERFILE_PATH points the build at the agent's Dockerfile — a service variable,`,
-        `# Railway's documented route to a non-root Dockerfile (no dashboard step needed for the build).`,
-        `railway variables set FASTAGENT_STATE_DIR=${MOUNT}/.state FASTAGENT_SECRETS_DIR=${MOUNT}/.secrets RAILWAY_DOCKERFILE_PATH=${dockerfilePathVar(input.agentPrefix)}`,
+        `railway variables set FASTAGENT_STATE_DIR=${MOUNT}/.state FASTAGENT_SECRETS_DIR=${MOUNT}/.secrets`,
     ];
     if (secrets.length > 0) {
         runbook.push(`# Secrets:`, `#   ${secrets.map((s) => `${s.name}: ${s.hint}`).join("\n#   ")}`, `railway variables set ${secrets.map((s) => `${s.name}=<value>`).join(" ")}`);
     }
-    runbook.push(``, `# OPTIONAL — the build already uses the agent's Dockerfile via RAILWAY_DOCKERFILE_PATH (set above),`, `# and Railway's default restart policy equals what ${configPath} declares (ON_FAILURE).`, `# Pointing the service at ${configPath} (Service → Settings → Config-as-code — dashboard-only) adds`, `# the /health healthcheck gate: a boot-crashing deploy is marked FAILED instead of going live dead.`, `# (Zero-downtime switching doesn't apply either way — the ${MOUNT} volume allows one active deployment.)`);
-    runbook.push(``, `# Before a new definition release, run \`fastagent deploy railway\` to refresh the release manifest.`, `# Upload this workspace and build on Railway (no local Docker needed):`, `railway up`);
+    runbook.push(``, `# Before a new definition release, run \`fastagent deploy railway\` to refresh the release manifest.`, `# Upload the agent directory and build on Railway (no local Docker needed): Railway builds the`, `# Dockerfile at its root. It marks the deploy live once the container starts, without waiting for`, `# /health: \`railway logs\` shows a box that crashes on boot.`, `railway up`);
     // The credential is created on the box, never carried: the box is then the only holder of its grant.
     if (input.boxLogin) {
-        runbook.push(``, `# Model auth: once it is up, the deployment logs in to ${input.boxLogin} itself (from this workspace):`, `${deploymentLoginCommand("railway", input.boxLogin)}`);
+        runbook.push(``, `# Model auth: once it is up, the deployment logs in to ${input.boxLogin} itself (from the agent directory):`, `${deploymentLoginCommand("railway", input.boxLogin)}`);
     }
-    runbook.push(``, `# The volume keeps /data/base (including uncommitted work), .state and .secrets across restarts and deploys.`, `# Each generated release replaces only /data/base/${input.agentPrefix}; other workspace files are initialized once.`, input.shipsGit
-        ? `# Railway uploads may strip .git. Clone inside the persistent workspace when collaboration needs history.`
-        : `# To use Git for collaboration, add deploy: { apt: ["git"] }. Storage durability does not require Git.`);
+    runbook.push(``, `# The volume keeps .state and .secrets across restarts and deploys; each release replaces /data/definition.`, input.shipsGit
+        ? `# Railway uploads may strip .git, so the deployed definition may have no history.`
+        : imageHasGit(input)
+            ? `# Git is installed (github content is cloned here, or context.json declares it in aptPackages).`
+            : `# To give the agent git, declare it: fastagent env add apt:git`);
     // The public URL is minted, not deterministic (unlike Fly's <app>.fly.dev).
     const steps = webhookRunbook(`https://<your-domain>`, channels);
     if (steps.length > 0) {
@@ -90,19 +60,6 @@ export function planRailwayDeploy(input) {
     const residency = residencyFor({ channels, hasCron: input.hasCron });
     runbook.push(``, residency
         ? `# Scale-to-zero: do NOT enable App Sleeping — ${residency.why}.`
-        : `# Scale-to-zero (optional, dashboard-only — no CLI/API): Settings → Deploy → Serverless → App Sleeping —\n# ${WAKEUPS_WHEN_ASLEEP}.`, ...(residency?.reason === CRON_CAN_BE_EXTERNAL
-        ? [
-            `# To sleep anyway: keep the time in a Railway CRON SERVICE (Settings -> Cron Schedule, >= 5 min) that`,
-            `# calls this service's \`POST /run\` over the private network — traffic from another service in the`,
-            `# project wakes a slept one. A cron service must EXIT, so it cannot be this service.`,
-            `#   set a variable on the cron service and curl it (Railway resolves the reference at deploy):`,
-            `#     AGENT_RUN=http://${serviceName}.railway.internal:\${{${serviceName}.PORT}}/run`,
-            `#     curl --retry 3 -fsS -X POST "$AGENT_RUN" -H 'content-type: application/json' -d '{"name":"<routine>"}'`,
-            `#   --retry because the FIRST request to a slept service may answer 502 (Railway documents it). The`,
-            `#   route has no dedup, so decide for yourself whether a retry that may duplicate work is what you want.`,
-            `# \`POST /run\` is an API, not a clock: read its contract — docs/api-reference.md#post-run.`,
-            `# Asleep, ${WAKEUPS_WHEN_ASLEEP}.`,
-        ]
-        : []), `# Keep this a SINGLE service: the ${MOUNT} volume is tied to one service; extra replicas split state.`);
+        : `# Scale-to-zero (optional, dashboard-only — no CLI/API): Settings → Deploy → Serverless → App Sleeping —\n# ${WAKEUPS_WHEN_ASLEEP}.`, `# Keep this a SINGLE service: the ${MOUNT} volume is tied to one service; extra replicas split state.`);
     return { artifacts, runbook };
 }

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

@@ -15,19 +15,24 @@ export interface RailwayRunPlan {
     secrets: Record<string, string>;
     /** Declared names the value file supplies no value for — the run gates on these before any side effect. */
     missingSecrets: string[];
-    /** That value file, workspace-relative, so the gate names the file this deploy actually read. */
+    /** That value file, agent-dir-relative, so the gate names the file this deploy actually read. */
     valueFile: string;
     /** Every declared channel and its ingress — the driver asks which of them have a webhook. */
     channels: readonly DeclaredChannel[];
     /** Opt-in (CLI `--into-linked`) to provision INTO the project this directory is already linked to. */
     intoLinked: boolean;
-    /** `RAILWAY_DOCKERFILE_PATH` value (`/fastagent/Dockerfile`). */
-    dockerfilePath: string;
     /**
      * Log the box in (`fastagent login --deployment`) once it is up and before any webhook is pointed at it: a channel pointed at
      * a box with no model credential answers every message with a failure. Resolves a gate line, or undefined.
      */
     boxLogin?: BoxLoginStep;
+    /**
+     * Sign the host's CLI in when it is signed out, through whoever can (host-login.ts): resolves a gate line, or
+     * undefined once signed in. Absent: nobody can, and the run stops naming how.
+     */
+    hostLogin?: () => Promise<string | undefined>;
+    /** The command a coding agent runs to deploy this, its person's steps handed to its user (`--run --json`). */
+    forAgent: string;
 }
 /**
  * Done (with the live URL), or a gate the operator must clear before re-running (printed + non-zero exit by the CLI).

package/dist/deploy/railway/run.js

@@ -1,6 +1,6 @@
 import { loginGate, publicHealthGate, registerWebhooks, } from "../channel-ingress.js";
 import { readOutput } from "../runner.js";
-import { missingValuesGate } from "../secrets.js";
+import { hostSignedOutGate, missingValuesGate } from "../secrets.js";
 /** Whether `railway status --json` shows a linked project: non-empty stdout. */
 export function isLinked(stdout) {
     return stdout.trim() !== "";
@@ -77,14 +77,19 @@ export async function deployRailwayRun(plan, railway, log, registrars, healthPro
     // 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.
-    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).
+    // 1. Gate missing required secret VALUES before any side effect (no half-created infra), and before asking a
+    // person to sign in for a deploy that would stop here anyway.
     const missingValues = missingValuesGate(plan.missingSecrets, plan.valueFile);
     if (missingValues)
         return gate(missingValues);
+    // 2.
+    if ((await railway(["whoami"], { capture: true })).code !== 0) {
+        const failed = plan.hostLogin
+            ? await plan.hostLogin()
+            : hostSignedOutGate("Railway", "railway login", "RAILWAY_API_TOKEN (an account token)", plan.forAgent);
+        if (failed)
+            return gate(failed);
+    }
     // 3.
     const status = await railway(["status", "--json"], { capture: true });
     if (isLinked(status.stdout)) {
@@ -124,7 +129,6 @@ export async function deployRailwayRun(plan, railway, log, registrars, healthPro
     const machineryVars = [
         `FASTAGENT_STATE_DIR=${plan.mountPath}/.state`,
         `FASTAGENT_SECRETS_DIR=${plan.mountPath}/.secrets`,
-        `RAILWAY_DOCKERFILE_PATH=${plan.dockerfilePath}`,
     ];
     // 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.
@@ -153,7 +157,7 @@ export async function deployRailwayRun(plan, railway, log, registrars, healthPro
             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).
+        // never publish a definition onto a disk that vanishes on restart).
         let status;
         for (let waited = 0;; waited += VOLUME_POLL_MS) {
             const read = await volumeStatus();

package/dist/deploy/residency.d.ts

@@ -4,9 +4,8 @@
  * 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 schedule is the agent's own clock: it keeps one machine up, and nothing here offers a way around that. Scaling to
+ * zero with timed work means not declaring the schedule and keeping the time elsewhere (docs/deploy.md), never both.
  *
  * 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
@@ -15,23 +14,18 @@
  */
 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";
+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. */
+    /** `schedules/` declares at least one schedule. */
     hasCron: boolean;
 }): Residency | undefined;
+export {};

package/dist/deploy/residency.js

@@ -1,9 +1,3 @@
-/**
- * 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. */

package/dist/deploy/runner.d.ts

@@ -29,7 +29,7 @@ export declare function readOutput<T>(run: CliRunner, bin: string, args: string[
     gate: string;
 }>;
 /**
- * Production {@link CliRunner}: spawn `bin` in `cwd` (the workspace, so a build/upload context is the agent). stderr
+ * Production {@link CliRunner}: spawn `bin` in `cwd` (the agent directory, which is the build/upload context). stderr
  * is always inherited to the terminal.
  */
 export declare function spawnRunner(bin: string, cwd: string): CliRunner;

package/dist/deploy/runner.js

@@ -24,7 +24,7 @@ export async function readOutput(run, bin, args, read) {
     }
 }
 /**
- * Production {@link CliRunner}: spawn `bin` in `cwd` (the workspace, so a build/upload context is the agent). stderr
+ * Production {@link CliRunner}: spawn `bin` in `cwd` (the agent directory, which is the build/upload context). stderr
  * is always inherited to the terminal.
  */
 export function spawnRunner(bin, cwd) {

package/dist/deploy/secrets.d.ts

@@ -1,13 +1,15 @@
 /**
  * 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
+ * The production value file (`.secrets/production/.env`) IS the deployed environment: every variable in it travels, on every host. What the
+ * definition declares (`defineTool`/`defineChannel`, the `variables` of `context.json`, 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;
+/** Is `name` one the deployment sets itself (see {@link DEPLOY_OWNED}), including the chunked carriers? */
+export declare function isDeployOwned(name: string): boolean;
 /** One variable a runbook tells the operator to set, and where to look for its value. */
 export interface DeploymentSecret {
     name: string;
@@ -38,12 +40,24 @@ export declare function assembleSecrets(input: {
     secrets: Record<string, string>;
     missingSecrets: string[];
 };
+/**
+ * The stop for a host CLI signed out with nobody to sign it in. A token goes in the shell's (or CI's) environment,
+ * never in the production value file: everything there travels to the box, which runs an agent with a shell.
+ */
+export declare function hostSignedOutGate(host: string, login: string, token: string, forAgent: string): string;
 /**
  * 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 refusal for a setting that shapes what `deploy` plans (a channel's ingress, read when `deploy` imports the
+ * channel here) and differs between this process and the value file. The box imports the channel with the file's
+ * value, so planning with this one would deploy a different channel than the one planned for: an export in this shell
+ * is the usual cause.
+ */
+export declare function divergentSettingsGate(names: readonly string[], env: NodeJS.ProcessEnv, values: ReadonlyMap<string, string>, valueFile: string): string | undefined;
 /**
  * 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.

package/dist/deploy/secrets.js

@@ -1,11 +1,13 @@
 /**
  * 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
+ * The production value file (`.secrets/production/.env`) IS the deployed environment: every variable in it travels, on every host. What the
+ * definition declares (`defineTool`/`defineChannel`, the `variables` of `context.json`, 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 { dedupeSecrets } from "../declared-secrets.js";
+import { DEV_SERVE_ENV } from "../serving-command.js";
+import { AGENT_ENVIRONMENT_ENV } from "../paths.js";
 /** Is this local auth source an env-var API key (→ becomes a deploy secret) vs OAuth / stored / none? */
 export function isEnvKey(source) {
     return source !== undefined && /^[A-Z][A-Z0-9_]*$/.test(source);
@@ -16,7 +18,6 @@ export function isEnvKey(source) {
  */
 const DEPLOY_OWNED = new Set([
     "PORT",
-    "FASTAGENT_AGENT",
     "FASTAGENT_MODEL",
     "FASTAGENT_STATE_DIR",
     "FASTAGENT_SECRETS_DIR",
@@ -27,9 +28,11 @@ const DEPLOY_OWNED = new Set([
     "FASTAGENT_INGRESS_SECRET",
     "FASTAGENT_WAKE_SECRET",
     "FASTAGENT_DEV_WORKER",
+    DEV_SERVE_ENV,
+    AGENT_ENVIRONMENT_ENV,
 ]);
 /** Is `name` one the deployment sets itself (see {@link DEPLOY_OWNED}), including the chunked carriers? */
-function isDeployOwned(name) {
+export function isDeployOwned(name) {
     return DEPLOY_OWNED.has(name) || /^FASTAGENT_ENV(_\d+)?$/.test(name);
 }
 /** The value-file variables that travel: everything with a value that the deployment does not set itself. */
@@ -52,8 +55,9 @@ export function deploymentSecrets(modelAuth, declared, values, valueFile) {
     };
     if (isEnvKey(modelAuth))
         add(modelAuth, "your model provider key");
-    for (const { name, source } of dedupeSecrets(declared))
-        add(name, `required by ${source}`);
+    for (const { name, source, description } of dedupeSecrets(declared)) {
+        add(name, `required by ${source}${description ? `: ${description}` : ""}`);
+    }
     for (const name of Object.keys(carriedValues(values)))
         add(name, `from ${valueFile}`);
     return secrets;
@@ -79,6 +83,15 @@ export function assembleSecrets(input) {
     }
     return { secrets, missingSecrets };
 }
+/**
+ * The stop for a host CLI signed out with nobody to sign it in. A token goes in the shell's (or CI's) environment,
+ * never in the production value file: everything there travels to the box, which runs an agent with a shell.
+ */
+export function hostSignedOutGate(host, login, token, forAgent) {
+    return (`not logged in to ${host} — run \`${login}\` in a terminal (it opens a browser), or set ${token} in this ` +
+        `shell's environment, never in .secrets/production/.env (everything there travels to the box); then re-run. ` +
+        `From a coding agent, \`${forAgent}\` hands the sign-in to its user`);
+}
 /**
  * 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
@@ -90,6 +103,20 @@ export function missingValuesGate(missing, valueFile) {
     return (`no value for: ${missing.join(", ")} — the deployed environment is declared by ${valueFile}, and this deploy ` +
         `reads only that file (exporting the variable here does not reach the deployment). Add them there and re-run`);
 }
+/**
+ * The refusal for a setting that shapes what `deploy` plans (a channel's ingress, read when `deploy` imports the
+ * channel here) and differs between this process and the value file. The box imports the channel with the file's
+ * value, so planning with this one would deploy a different channel than the one planned for: an export in this shell
+ * is the usual cause.
+ */
+export function divergentSettingsGate(names, env, values, valueFile) {
+    const differing = names.filter((name) => (env[name] ?? "") !== (values.get(name) ?? ""));
+    if (differing.length === 0)
+        return undefined;
+    const said = differing.map((name) => `${name} is "${env[name] ?? ""}" here and "${values.get(name) ?? ""}" in ${valueFile}`);
+    return (`${said.join("; ")} — the deployment receives only ${valueFile}, and this deploy would plan for a different ` +
+        `channel than the one it starts. Set it in ${valueFile} (or unset it here) and re-run`);
+}
 /**
  * Collect a (possibly CHUNKED) carrier from the environment: `<name>` plus numbered continuations (`_2`, `_3`, …)
  * concatenated in order. A host whose env values have a length cap splits a long value this way.

package/dist/deploy/workspace.d.ts

@@ -1,4 +1,6 @@
 export declare const RELEASE_FILE = "fastagent.release.json";
+/** Where the storage holds the deployed definition, the agent's working directory on the host. */
+export declare const DEPLOYED_DEFINITION_DIR = "definition";
 export interface DeploymentRelease {
     version: 1;
     id: string;
@@ -11,14 +13,14 @@ export interface DeploymentRelease {
      */
     model?: string;
 }
-/** The manifest names a directory the container joins onto the workspace root, so the spelling is
- *  constrained. `deploy` asks BEFORE generating artifacts — a name `init` accepts but this rejects
- *  is the author's directory name, not a corrupt manifest. */
+/** The manifest names the agent the storage belongs to, and that name is also a content entry's name rule (one path
+ *  segment). `deploy` asks BEFORE generating artifacts — a name `init` accepts but this rejects is the author's
+ *  directory name, not a corrupt manifest. */
 export declare function isReleaseAgentName(name: string): boolean;
 export declare function parseDeploymentRelease(raw: string): DeploymentRelease;
 /**
  * Project a release's own declarations into the environment it was resolved FOR — the receiving half of the model
- * chain, run by `prepareStartWorkspace` BEFORE the workspace's `.env` is read (so either source outranks a value
+ * chain, run by `prepareStartWorkspace` BEFORE the agent's `.env` is read (so either source outranks a value
  * edited on the box).
  *
  * `||=`: a variable the platform already holds still wins, because the deployment declares only the half of this
@@ -29,7 +31,10 @@ export declare function applyReleaseEnv(release: DeploymentRelease, env?: NodeJS
 /** A `provider/modelId` spec. The id itself may carry `/` and `~` (`baseten/zai-org/GLM-5.3`, openrouter aliases);
  *  resolution only ever splits on the first slash. */
 export declare function isModelSpec(value: string): boolean;
-/** Call while holding the workspace lease. No deployment replaces existing work outside the definition. */
+/**
+ * Call while holding the deployment lease. Replaces the deployed definition with the release's (`source`, the image's
+ * copy) and returns where it now is; nothing else on the storage is touched.
+ */
 export declare function applyDeploymentRelease(source: string, root: string, release: DeploymentRelease): Promise<string>;
 /** An unmounted directory must never look like a new disk. */
 export declare function assertStorageMounted(root: string, paths?: string[]): Promise<void>;
@@ -37,7 +42,7 @@ export declare function assertStorageMounted(root: string, paths?: string[]): Pr
  *  passes a short one rather than waiting out the deployment default. */
 export declare function leaseDeployment(metadata: string, waitSeconds?: number): Promise<() => Promise<void>>;
 /**
- * Prepare the deployed workspace and return its path.
+ * Prepare the deployed definition and return its path.
  *
  * The lease is NOT returned: it stays held for the process lifetime, because channel activation can
  * start background writers that `close()` does not drain. The kernel drops it when the process exits.

package/dist/deploy/workspace.js

@@ -1,19 +1,25 @@
-/** Deployment-owned initialization; the workspace itself belongs to the running agent. */
-import { cp, lstat, mkdir, readFile, rename, rm } from "node:fs/promises";
+/**
+ * Deployment-owned initialization of a host's storage: the lease, the release journal, and the definition each
+ * release replaces. The instance's state, credentials and content (`.state/`, `.secrets/`, `content/`) sit beside the
+ * definition and outlive every release; each release links its `content/` to the storage's.
+ */
+import { cp, lstat, mkdir, readFile, rename, rm, symlink } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { spawn } from "node:child_process";
 import { closeSync, openSync } from "node:fs";
 import { once } from "node:events";
 import { writeFileAtomic } from "../atomic-write.js";
 import { log } from "../log.js";
-import { exists } from "../paths.js";
+import { CONTENT_DIRNAME, exists } from "../paths.js";
 import { detectRuntime, readPackageJson } from "../runtime.js";
 export const RELEASE_FILE = "fastagent.release.json";
+/** Where the storage holds the deployed definition, the agent's working directory on the host. */
+export const DEPLOYED_DEFINITION_DIR = "definition";
 /** The deployment's own bookkeeping on the storage: the lease, the release journal, the install marker. */
 const deploymentMeta = (root) => join(root, ".deployment");
-/** The manifest names a directory the container joins onto the workspace root, so the spelling is
- *  constrained. `deploy` asks BEFORE generating artifacts — a name `init` accepts but this rejects
- *  is the author's directory name, not a corrupt manifest. */
+/** The manifest names the agent the storage belongs to, and that name is also a content entry's name rule (one path
+ *  segment). `deploy` asks BEFORE generating artifacts — a name `init` accepts but this rejects is the author's
+ *  directory name, not a corrupt manifest. */
 export function isReleaseAgentName(name) {
     return /^[a-zA-Z0-9_-]+$/.test(name);
 }
@@ -31,7 +37,7 @@ export function parseDeploymentRelease(raw) {
 }
 /**
  * Project a release's own declarations into the environment it was resolved FOR — the receiving half of the model
- * chain, run by `prepareStartWorkspace` BEFORE the workspace's `.env` is read (so either source outranks a value
+ * chain, run by `prepareStartWorkspace` BEFORE the agent's `.env` is read (so either source outranks a value
  * edited on the box).
  *
  * `||=`: a variable the platform already holds still wins, because the deployment declares only the half of this
@@ -47,7 +53,7 @@ export function applyReleaseEnv(release, env = process.env) {
         return;
     log.info(`[fastagent] model ${effective} — from ${fromPlatform
         ? `a FASTAGENT_MODEL already set in this environment${release.model ? ", which outranks the release manifest" : ""}`
-        : "the release manifest (redeploy to change it)"}; editing FASTAGENT_MODEL in this workspace's .env does not override it`);
+        : "the release manifest (redeploy to change it)"}; editing FASTAGENT_MODEL in the deployed agent's .env does not override it`);
 }
 /** A `provider/modelId` spec. The id itself may carry `/` and `~` (`baseten/zai-org/GLM-5.3`, openrouter aliases);
  *  resolution only ever splits on the first slash. */
@@ -55,12 +61,12 @@ export function isModelSpec(value) {
     return /^\S+\/\S+$/.test(value);
 }
 /** A completed staging tree is published before its journal; readers start only after recovery. */
-async function finishRelease(root, pending) {
+async function finishRelease(root, release) {
     const meta = deploymentMeta(root), staged = join(meta, "staged"), previous = join(meta, "previous");
-    const target = pending.initial ? join(root, "base") : join(root, "base", pending.release.agent);
+    const target = join(root, DEPLOYED_DEFINITION_DIR);
     if (await exists(staged)) {
         if (await exists(target)) {
-            if (pending.initial || (await exists(previous)))
+            if (await exists(previous))
                 throw new Error(`deployment recovery conflict at ${target}`);
             await rename(target, previous);
         }
@@ -69,48 +75,59 @@ async function finishRelease(root, pending) {
     else if (!(await exists(target))) {
         throw new Error(`deployment recovery has neither staged nor active content: ${target}`);
     }
-    writeFileAtomic(join(meta, "applied.json"), JSON.stringify(pending.release));
+    writeFileAtomic(join(meta, "applied.json"), JSON.stringify(release));
     await rm(previous, { recursive: true, force: true });
     await rm(join(meta, "pending.json"));
 }
-/** Call while holding the workspace lease. No deployment replaces existing work outside the definition. */
+/**
+ * Call while holding the deployment lease. Replaces the deployed definition with the release's (`source`, the image's
+ * copy) and returns where it now is; nothing else on the storage is touched.
+ */
 export async function applyDeploymentRelease(source, root, release) {
     const meta = deploymentMeta(root), staged = join(meta, "staged"), pendingPath = join(meta, "pending.json");
     await mkdir(meta, { recursive: true });
+    await mkdir(join(root, CONTENT_DIRNAME), { recursive: true });
+    // A storage an earlier FastAgent laid out holds the agent's whole workspace there, which this one would leave
+    // behind unread: said, never silently abandoned.
+    const formerWorkspace = join(root, "base");
+    if (await exists(formerWorkspace)) {
+        throw new Error(`${formerWorkspace} holds a workspace from an earlier FastAgent, which no longer copies one to the host — ` +
+            `move out what you need and delete it, or deploy onto fresh storage`);
+    }
     if (await exists(pendingPath)) {
-        const pending = JSON.parse(await readFile(pendingPath, "utf8"));
-        pending.release = parseDeploymentRelease(JSON.stringify(pending.release));
-        if (typeof pending.initial !== "boolean")
-            throw new Error("invalid pending deployment journal");
+        const pending = parseDeploymentRelease(await readFile(pendingPath, "utf8"));
         await finishRelease(root, pending);
     }
     const appliedPath = join(meta, "applied.json");
     const applied = (await exists(appliedPath)) ? parseDeploymentRelease(await readFile(appliedPath, "utf8")) : undefined;
-    const workspace = join(root, "base");
+    const definition = join(root, DEPLOYED_DEFINITION_DIR);
     if (applied?.agent !== undefined && applied.agent !== release.agent) {
-        throw new Error(`deployment selects ${release.agent}, but this workspace belongs to ${applied.agent}`);
+        throw new Error(`deployment selects ${release.agent}, but this storage belongs to ${applied.agent}`);
     }
     // Logged on BOTH paths: rebuilding an image without regenerating the manifest keeps the id, and a
     // deployment that silently kept the old definition looks identical to one that took the new one.
     if (applied?.id === release.id) {
-        log.info(`[fastagent] release ${release.id} is already applied — keeping the workspace's definition`);
-        return workspace;
+        log.info(`[fastagent] release ${release.id} is already applied — keeping the deployed definition`);
+        return definition;
+    }
+    if (applied === undefined && (await exists(definition))) {
+        throw new Error(`refusing to initialize over an existing unowned definition: ${definition}`);
+    }
+    if (!(await exists(source)) || !(await lstat(source)).isDirectory()) {
+        throw new Error(`the release must contain its agent directory: ${source}`);
     }
-    const initial = applied === undefined;
-    if (initial && (await exists(workspace)))
-        throw new Error(`refusing to initialize over an existing unowned workspace: ${workspace}`);
-    const definition = join(source, release.agent);
-    if (!(await exists(definition)) || !(await lstat(definition)).isDirectory())
-        throw new Error(`the release must contain its agent directory: ${definition}`);
-    log.info(initial
-        ? `[fastagent] seeding the workspace from release ${release.id}`
-        : `[fastagent] publishing release ${release.id} over base/${release.agent}`);
+    log.info(`[fastagent] publishing release ${release.id} as ${DEPLOYED_DEFINITION_DIR}/`);
     await rm(staged, { recursive: true, force: true });
-    await cp(initial ? source : join(source, release.agent), staged, { recursive: true, verbatimSymlinks: true });
-    const pending = { release, initial };
-    writeFileAtomic(pendingPath, JSON.stringify(pending));
-    await finishRelease(root, pending);
-    return workspace;
+    await cp(source, staged, { recursive: true, verbatimSymlinks: true });
+    // Where the agent reaches each content entry, on every instance: here, the storage's, which no release replaces.
+    await symlink(join("..", CONTENT_DIRNAME), join(staged, CONTENT_DIRNAME)).catch((error) => {
+        if (error.code !== "EEXIST")
+            throw error;
+        throw new Error(`the release holds ${CONTENT_DIRNAME}/, which a deploy keeps out of the image — rebuild it`);
+    });
+    writeFileAtomic(pendingPath, JSON.stringify(release));
+    await finishRelease(root, release);
+    return definition;
 }
 async function mountedPaths() {
     const mounts = await readFile("/proc/self/mountinfo", "utf8");
@@ -142,7 +159,7 @@ export async function leaseDeployment(metadata, waitSeconds = 35) {
         });
         const [code, signal] = await once(child, "close");
         if (code !== 0)
-            throw new Error(`could not acquire workspace lease at ${metadata}: flock ${signal ?? code} ${stderr.trim()}`);
+            throw new Error(`could not acquire deployment lease at ${metadata}: flock ${signal ?? code} ${stderr.trim()}`);
         return async () => {
             closeSync(fd);
         };
@@ -152,12 +169,12 @@ export async function leaseDeployment(metadata, waitSeconds = 35) {
         // A custom base image without util-linux fails every boot; the bare spawn error names neither
         // the binary nor why a lease needs one.
         if (error.code === "ENOENT")
-            throw new Error(`the deployed workspace lease needs the \`flock\` binary (util-linux): ${String(error)}`);
+            throw new Error(`the deployment lease needs the \`flock\` binary (util-linux): ${String(error)}`);
         throw error;
     }
 }
 /**
- * Prepare the deployed workspace and return its path.
+ * Prepare the deployed definition and return its path.
  *
  * The lease is NOT returned: it stays held for the process lifetime, because channel activation can
  * start background writers that `close()` does not drain. The kernel drops it when the process exits.