@fastagent-sh/fastagent 0.15.0 → 0.16.1

package/dist/deploy/container.js

@@ -1,9 +1,15 @@
 /**
  * The portable container — Dockerfile + .dockerignore, host-neutral. Every deploy target ships these
  * unchanged; only the host config (fly.toml / railway.json) and the CLI sequence differ. The image
- * runs `fastagent start /app` on `$PORT` with state under `$FASTAGENT_STATE_DIR` — standard container
- * conventions, no host coupling. Extracted from the Fly plan when Railway became the second target.
+ * runs `fastagent start /app` on `$PORT` with machinery under `$FASTAGENT_STATE_DIR` /
+ * `$FASTAGENT_SECRETS_DIR` — standard container conventions, no host coupling.
+ *
+ * ONE deploy semantic: bake the WORKSPACE as the image (`COPY . .` — what you see is what ships),
+ * with the agent at `./fastagent` inside it. The resolver in the image finds it exactly like dev does.
+ * Deps install under `/app/fastagent`, and the Dockerfile lives there too — namespaced so it never
+ * collides with one the workspace already owns.
  */
+import { SECRETS_DIRNAME, STATE_DIRNAME } from "../paths.js";
 /** Fixed first-line prefix of a fastagent-generated Dockerfile — the ONE source both the generator (the
  *  `head` below) and the "is this ours?" check (cli deploy's kept-Dockerfile apt warn) share, so they
  *  can't drift into detecting a marker the generator no longer writes. */
@@ -15,41 +21,13 @@ export const GENERATED_DOCKERFILE_MARKER = "# Generated by `fastagent deploy`";
 export function isGeneratedDockerfile(content) {
     return content.startsWith(GENERATED_DOCKERFILE_MARKER);
 }
-/** The repo-as-workspace Dockerfile: bake the repo as cwd, install the kit's deps, run from the kit. */
-function kitDockerfile(input, kit) {
-    const apt = aptLayer(input.apt);
-    if (!input.hasPackageJson) {
-        // Markdown-only kit: no deps to install — the pinned global CLI serves the repo directly.
-        return `${GENERATED_DOCKERFILE_MARKER}. Repo-as-workspace: the whole repo is the agent's cwd; the kit lives in ${kit}/.
-FROM node:22-slim
-${apt}WORKDIR /app
-RUN npm i -g @fastagent-sh/fastagent@${input.version}
-COPY . .
-CMD ["fastagent", "start", "/app"]
-`;
-    }
-    const isBun = input.runtime === "bun";
-    const base = isBun ? `oven/bun:${input.bunVersion ?? "1"}` : "node:22-slim";
-    const head = `${GENERATED_DOCKERFILE_MARKER}. Repo-as-workspace: the whole repo is the agent's cwd; the kit lives in ${kit}/.
-# Only the KIT's deps are installed — the host repo's own deps are the agent's runtime concern (it can
-# install them in its workspace when its job needs them). .git IS shipped: write-back needs it.
-FROM ${base}
-${apt}WORKDIR /app
-`;
-    if (isBun) {
-        const install = input.hasLockfile ? "bun install --frozen-lockfile" : "bun install";
-        return `${head}COPY ${kit}/package.json ${kit}/bun.lock* ./${kit}/
-RUN cd ${kit} && ${install}
-COPY . .
-CMD ["sh", "-c", "cd ${kit} && bun run fastagent start /app"]
-`;
-    }
-    const install = input.hasLockfile ? "npm ci" : "npm install";
-    return `${head}COPY ${kit}/package.json ${kit}/package-lock.json* ./${kit}/
-RUN cd ${kit} && ${install}
-COPY . .
-CMD ["./${kit}/node_modules/.bin/fastagent", "start", "/app"]
-`;
+/** First line of a generated `.dockerignore` — and, for the workspace-root one, the single artifact
+ *  deploy writes outside the agent dir. The marker is what splits the two cases: ours is refreshed
+ *  (regenerated under `--force`), yours is kept. */
+const GENERATED_DOCKERIGNORE_MARKER = "# Generated by `fastagent deploy`";
+/** Did fastagent generate this `.dockerignore`? (Same ownership rule as {@link isGeneratedDockerfile}.) */
+export function isGeneratedDockerignore(content) {
+    return content.startsWith(GENERATED_DOCKERIGNORE_MARKER);
 }
 /** The apt layer (cached right after FROM). Debian default repos only. */
 function aptLayer(packages) {
@@ -61,21 +39,46 @@ function aptLayer(packages) {
         : "";
 }
 function dockerfile(input) {
+    // The whole workspace is baked at /app; deps install (and the local bin lives) under the agent, which
+    // is either a subdirectory of it or /app itself. `into` prefixes a path, `at` runs a command there.
+    const prefix = input.agentPrefix;
+    const into = (p) => `${prefix}${p}`;
+    // A build step that must run IN the agent dir (`RUN` already gets a shell from docker).
+    const at = (cmd) => (prefix ? `cd ${prefix.replace(/\/$/, "")} && ${cmd}` : cmd);
+    // The entrypoint. Only the BUN path needs a working directory (`bun run` resolves the script from the
+    // package.json beside it), and a `cd` there means a shell — with `exec`, or sh stays PID 1 and swallows
+    // the container's SIGTERM. The npm path needs no shell at all: the binary path is context-relative and
+    // `start /app` is absolute, so exec form is both correct and signal-clean. (A `cd` on that path was a
+    // bug: after `cd fastagent`, `./fastagent/node_modules/...` resolves one level too deep.)
+    const bunCmd = prefix
+        ? `["sh", "-c", "cd ${prefix.replace(/\/$/, "")} && exec bun run fastagent start /app"]`
+        : `["bun", "run", "fastagent", "start", "/app"]`;
+    const layoutNote = prefix
+        ? `The whole directory is the agent's workspace; the agent itself lives in ${prefix}`
+        : `The directory IS the agent — it is also its own workspace.`;
     // apt layer right after FROM (cached across code changes): the agent's tools may shell out to git etc.,
     // which node:22-slim lacks. Debian default repos only — a package needing a custom repo (gh) or a
     // different base is the operator's own Dockerfile (kept if present). deploy.apt is package-name-validated.
     const apt = aptLayer(input.apt);
+    // PIN the agent into the image. The container re-resolves placement at `/app` (the baked workspace),
+    // and a workspace may hold SEVERAL agents — all of which ship, since the build context is the whole
+    // tree. Without this the image would pick by the container's own rules (the `fastagent`-named one, or
+    // nothing) instead of the agent this deploy was FOR: the artifact would depend on the builder's
+    // environment, which is the one thing it must never do. Baked whenever the agent sits inside the
+    // workspace, single agent or not — the value is a fact of this image, and asserting it means a build
+    // context that dropped the agent fails loudly rather than serving a sibling.
+    const pin = prefix ? `ENV FASTAGENT_AGENT=${prefix.replace(/\/$/, "")}\n` : "";
     // No package.json → pure markdown/skills agent: install the pinned CLI GLOBALLY and run `fastagent`
     // from PATH. That needs npm + a global bin, which live on node:22-slim, NOT on oven/bun — so this path
     // pins node:22-slim regardless of input.runtime (a stray bun lockfile with no package.json would
     // otherwise select a bun base here and crash the `npm i -g` build). input.runtime is meaningful only
-    // for a code workspace, so the bun-vs-node base below is scoped to that path.
+    // for a code agent, so the bun-vs-node base below is scoped to that path.
     if (!input.hasPackageJson) {
-        return `${GENERATED_DOCKERFILE_MARKER}. The directory IS the agent — no build step.
+        return `${GENERATED_DOCKERFILE_MARKER}. ${layoutNote}
 # npm-based (a markdown/skills agent installs the pinned CLI globally; node:22-slim has npm).
 FROM node:22-slim
 ${apt}WORKDIR /app
-RUN npm i -g @fastagent-sh/fastagent@${input.version}
+${pin}RUN npm i -g @fastagent-sh/fastagent@${input.version}
 COPY . .
 CMD ["fastagent", "start", "/app"]
 `;
@@ -85,14 +88,16 @@ CMD ["fastagent", "start", "/app"]
     const note = isBun
         ? "# Bun-based (packageManager: bun / a bun lockfile detected). fastagent runs under Bun (bun run)."
         : "# npm-based — for pnpm/yarn, adapt the install line + the lockfile COPY (corepack enable, etc.).";
-    const head = `${GENERATED_DOCKERFILE_MARKER}. The directory IS the agent — no build step.
+    const head = `${GENERATED_DOCKERFILE_MARKER}. ${layoutNote}
 ${note}
 FROM ${base}
 ${apt}WORKDIR /app
-`;
+${pin}`;
     // Install ALL deps (no --omit=dev / --production): a repo-as-agent (e.g. an Astro site it operates on)
     // needs its full toolchain — the build/check tools that live in devDependencies — to do its work, and
-    // we can't tell a repo-as-agent from a purpose-built workspace, so the safe default keeps everything.
+    // we can't tell a repo-as-agent from a purpose-built agent, so the safe default keeps everything.
+    // Only the AGENT's deps are installed — the workspace's own deps are the agent's runtime concern
+    // (it can install them in its workspace when its job needs them).
     if (isBun) {
         // `--frozen-lockfile` needs bun.lock and hard-fails without it; fall back to a plain `bun install`
         // (resolves at build time — not reproducible; the CLI warns to commit the lockfile).
@@ -100,13 +105,13 @@ ${apt}WORKDIR /app
         // `bunx fastagent` would fall back to installing the npm package named `fastagent`, which is an
         // unrelated third-party package (ours is the scoped @fastagent-sh/fastagent).
         const install = input.hasLockfile ? "bun install --frozen-lockfile" : "bun install";
-        return `${head}COPY package.json bun.lock* ./
-RUN ${install}
+        return `${head}COPY ${into("package.json")} ${into("bun.lock*")} ./${prefix}
+RUN ${at(install)}
 COPY . .
-CMD ["bun", "run", "fastagent", "start", "/app"]
+CMD ${bunCmd}
 `;
     }
-    // `npm ci` requires a lockfile and hard-fails without one (a common `init --no-install` workspace);
+    // `npm ci` requires a lockfile and hard-fails without one (a common `init --no-install` agent);
     // fall back to `npm install` when there is none so the build never breaks. Caveat: `npm install`
     // resolves caret ranges at build time, so THIS branch is NOT reproducible — unlike the pinned
     // `npm ci` (lockfile) and pinned global (markdown) paths. The CLI warns to commit a lockfile.
@@ -114,60 +119,59 @@ CMD ["bun", "run", "fastagent", "start", "/app"]
     // `fastagent` when the dep is absent — an unrelated third-party package (ours is scoped). The local
     // path fails fast and visibly instead.
     const install = input.hasLockfile ? "npm ci" : "npm install";
-    return `${head}COPY package.json package-lock.json* ./
-RUN ${install}
+    return `${head}COPY ${into("package.json")} ${into("package-lock.json*")} ./${prefix}
+RUN ${at(install)}
 COPY . .
-CMD ["./node_modules/.bin/fastagent", "start", "/app"]
+CMD ["./${into("node_modules/.bin/fastagent")}", "start", "/app"]
 `;
 }
 /** Patterns are RECURSIVE (`**​/`) on purpose — dockerignore patterns are root-anchored (unlike
- *  .gitignore), and a repo-as-agent can hold nested projects: a bare `node_modules` would upload their
- *  build-machine deps (macOS binaries!) and a bare `.env` would bake their secrets into the image.
- *  `.git` stays root-anchored: nested projects' own `.git` ships (the agent's write-back needs it). */
-const DOCKERIGNORE = `**/node_modules
-**/.fastagent
+ *  .gitignore), and a baked workspace can hold nested projects: a bare `node_modules` would upload
+ *  their build-machine deps (macOS binaries!) and a bare `.env` would bake their secrets into the
+ *  image. `.secrets`/`.state` are fastagent machinery — secrets travel through the host's secret
+ *  store, state lives on the volume; neither may ever enter an image. `.cache` is generic hygiene
+ *  (a baked project's own build cache), not a fastagent directory.
+ *  `.git` is deliberately SHIPPED: the deployed agent's write-back (pull/commit/push) needs the
+ *  repo's history+remote — the WYSIWYG bake's freshness/durability loop runs through git, driven by
+ *  the agent itself, not by deploy machinery. Shipping `.git` is only half of that loop: preflight
+ *  bakes the git BINARY into the generated image iff the workspace ships a `.git` (the `shipsGit`
+ *  fact); a non-git workspace that still needs git declares config.deploy.apt. */
+const dockerignore = (input) => DOCKERIGNORE_BASE +
+    (input.machineryPaths ?? [])
+        // Skip what the name-based rules above already cover: the default `<agent>/.secrets` / `<agent>/.state`
+        // and anything inside them. What remains is a relocated dir whose NAME those rules cannot match.
+        .filter((p) => [`${input.agentPrefix}${SECRETS_DIRNAME}`, `${input.agentPrefix}${STATE_DIRNAME}`].every((covered) => p !== covered && !p.startsWith(`${covered}/`)))
+        .map((p) => `# resolved machinery path (FASTAGENT_SECRETS_DIR / FASTAGENT_AUTH_PATH / FASTAGENT_STATE_DIR)\n/${p}\n`)
+        .join("");
+const DOCKERIGNORE_BASE = `${GENERATED_DOCKERIGNORE_MARKER}. Delete this line to take ownership (deploy then keeps your file).
+**/node_modules
+**/${SECRETS_DIRNAME}
+**/${STATE_DIRNAME}
+**/.cache
 **/.env
 **/.env.*
 !**/.env.example
 **/*.log
-# .git is excluded to keep the image small. If your agent runs git on its OWN history
-# (git log/blame over the repo it ships in), delete the next line so that history is in the image.
-.git
-`;
-/** The kit-layout ignore: `.git` is deliberately NOT excluded (write-back wants it — though whether it
- *  survives is host-CLI-dependent; see containerArtifacts). Patterns are RECURSIVE (`**​/`) on purpose —
- *  dockerignore patterns are root-anchored (unlike .gitignore), so a bare `node_modules` would NOT
- *  exclude `agent/node_modules`: the build machine's kit deps (macOS binaries!) would be uploaded by
- *  `COPY . .` and clobber the image's freshly-installed linux ones. */
-const KIT_DOCKERIGNORE = `**/node_modules
-**/.fastagent
-**/.env
-**/.env.*
-!**/.env.example
-**/*.log
-# .git is DELIBERATELY shipped: the agent's write-back (commit/push) needs the repo's history+remote.
+# .git is deliberately shipped: the agent can pull to freshen content and push its work back
+# (the generated image installs the git binary when this directory ships a .git; otherwise
+# add deploy.apt ["git"]). For a smaller image with no git needs, add a ".git" line here.
 `;
 /**
- * The Dockerfile + ignore artifacts — spread into any host's artifact list. Kit layout ({@link
- * ContainerInput.kitDir}): the Dockerfile is namespaced under the kit (`agent/Dockerfile`) so it never
- * collides with the host repo's own. The ignore ships in TWO forms because context packing is
- * host-CLI-owned and inconsistent: (1) a ROOT `.dockerignore` — the only form flyctl/railway's own
- * context packers reliably read (kept if the host already has one — preflight then warns specifically
- * about a .git exclude / missing recursive node_modules) — and (2) a
- * per-Dockerfile `agent/Dockerfile.dockerignore` for plain docker/buildx builds. Whether `.git`
- * actually reaches the box is host-CLI-dependent (some strip it from the upload regardless of any
- * ignore file) — the runbook's write-back note carries the runtime-clone fallback.
+ * The Dockerfile + ignore artifacts — spread into any host's artifact list. Everything is prefixed with
+ * {@link ContainerInput.agentPrefix}, so a NESTED agent's Dockerfile lands under `fastagent/` (never
+ * colliding with one the workspace already owns) while an agent that IS the workspace lands it at the root, where it IS
+ * the agent's own file. The ignore ships in TWO forms because context packing is host-CLI-owned and
+ * inconsistent: (1) a ROOT `.dockerignore` — the only form flyctl/railway's own context packers
+ * reliably read (kept if the workspace already has one — preflight then checks the machinery/secret
+ * excludes it must carry) — and (2) a per-Dockerfile `Dockerfile.dockerignore` for plain docker/buildx
+ * builds. When the agent sits inside the workspace that root file is the ONE write deploy makes outside the agent dir, and
+ * only at deploy time — without it the host CLI's packer would bake `.secrets/` into the image.
  */
 export function containerArtifacts(input) {
-    if (input.kitDir) {
-        return [
-            { path: `${input.kitDir}/Dockerfile`, content: kitDockerfile(input, input.kitDir) },
-            { path: ".dockerignore", content: KIT_DOCKERIGNORE },
-            { path: `${input.kitDir}/Dockerfile.dockerignore`, content: KIT_DOCKERIGNORE },
-        ];
-    }
+    const ignore = dockerignore(input);
     return [
-        { path: "Dockerfile", content: dockerfile(input) },
-        { path: ".dockerignore", content: DOCKERIGNORE },
+        { path: `${input.agentPrefix}Dockerfile`, content: dockerfile(input) },
+        { path: ".dockerignore", content: ignore },
+        { path: `${input.agentPrefix}Dockerfile.dockerignore`, content: ignore },
     ];
 }

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

@@ -25,7 +25,7 @@ export interface DockerPlanInput extends ContainerInput {
 export interface DockerPlan {
     /** fastagent.compose.yml + the shared Dockerfile/ignore artifacts. */
     artifacts: Artifact[];
-    /** Compose file path relative to the workspace root (namespaced for agentDir layouts). */
+    /** Compose file path relative to the workspace root (under the agent prefix). */
     composePath: string;
     /** Ordered local build/run/operate instructions. */
     runbook: string[];

package/dist/deploy/docker/plan.js

@@ -39,23 +39,16 @@ export function dockerWebhookPaths(channels) {
 function composeInterpolation(name) {
     return `\${${name}:-}`;
 }
-/** Relative path from the namespaced Compose file's directory back to the workspace/build root. */
-function buildContext(kitDir) {
-    if (!kitDir)
-        return ".";
-    return kitDir
-        .split("/")
-        .map(() => "..")
-        .join("/");
-}
 function composeYaml(input) {
     const secrets = deploymentSecrets(input.modelAuth, input.channels, input.extraSecrets, input.longConnectionChannels);
     // Always leave the auth-seed seam in the committed topology. `--run` uses it for OAuth/stored auth;
     // it is empty otherwise. Values never land in this file — Compose interpolates them at invocation.
     const envNames = [...new Set([...secrets.map((secret) => secret.name), "FASTAGENT_AUTH_SEED"])];
     const secretEnv = envNames.map((name) => `      ${name}: "${composeInterpolation(name)}"`).join("\n");
-    const context = buildContext(input.kitDir);
-    const dockerfile = input.kitDir ? `${input.kitDir}/Dockerfile` : "Dockerfile";
+    // Compose sits beside the Dockerfile, under the agent prefix; the build context is always the
+    // WORKSPACE, so it climbs back out of the prefix (`..` per level, `.` when there is none).
+    const context = input.agentPrefix ? ".." : ".";
+    const dockerfile = `${input.agentPrefix}Dockerfile`;
     const tunnelService = input.tunnel
         ? `
   # Cloudflare Quick Tunnel: ephemeral URL, generated only with \`deploy docker --tunnel\`.
@@ -90,7 +83,9 @@ services:
       - "127.0.0.1:${input.port}:${input.port}"
     environment:
       PORT: "${input.port}"
-      FASTAGENT_STATE_DIR: "${MOUNT}"
+      # Machinery on the ONE state volume: mutable state and (seeded, possibly rotated) secrets.
+      FASTAGENT_STATE_DIR: "${MOUNT}/.state"
+      FASTAGENT_SECRETS_DIR: "${MOUNT}/.secrets"
 ${secretEnv}
     volumes:
       - state:${MOUNT}
@@ -102,7 +97,7 @@ volumes:
 }
 /** Compute local-Docker artifacts + the runbook; no Docker process is touched here. */
 export function planDockerDeploy(input) {
-    const composePath = input.kitDir ? `${input.kitDir}/${DOCKER_COMPOSE_FILE}` : DOCKER_COMPOSE_FILE;
+    const composePath = `${input.agentPrefix}${DOCKER_COMPOSE_FILE}`;
     const artifacts = [{ path: composePath, content: composeYaml(input) }, ...containerArtifacts(input)];
     const compose = `docker compose -f ${composePath}`;
     const secrets = deploymentSecrets(input.modelAuth, input.channels, input.extraSecrets, input.longConnectionChannels);
@@ -116,7 +111,7 @@ export function planDockerDeploy(input) {
         `# Prereqs: Docker Engine/Desktop with Compose >= ${MIN_DOCKER_COMPOSE_VERSION} (\`docker compose version\`).`,
     ];
     if (required.length > 0) {
-        runbook.push(`# Required environment values (put them in the workspace .env or export them):`, ...required.map((secret) => `#   ${secret.name}: ${secret.hint}`));
+        runbook.push(`# Required environment values (put them in the agent's .secrets/.env or export them):`, ...required.map((secret) => `#   ${secret.name}: ${secret.hint}`));
     }
     if (optional.length > 0) {
         runbook.push(`# Optional environment values:`, ...optional.map((secret) => `#   ${secret.name}: ${secret.hint}`));
@@ -126,9 +121,9 @@ export function planDockerDeploy(input) {
             ? `# Model auth: none found locally — run \`fastagent login\` or set a provider API key before --run.`
             : `# Model auth: local source is "${input.modelAuth}" — \`--run\` carries auth.json as FASTAGENT_AUTH_SEED.`, `# For a manual Compose run, provide a provider API key or set FASTAGENT_AUTH_SEED yourself.`);
     }
-    if (input.kitDir) {
-        runbook.push(`# Repo-as-workspace: run from the REPO ROOT. Compose lives under ${input.kitDir}/ but builds`, `# the whole repository; only the kit's dependencies are installed by ${input.kitDir}/Dockerfile.`);
-    }
+    runbook.push(input.agentPrefix
+        ? `# Run from the WORKSPACE ROOT (the directory containing ${input.agentPrefix}).`
+        : `# Run from this directory — it is both the agent and its workspace.`, `# The build bakes the whole directory as the agent's workspace; only the agent's own`, `# dependencies (${input.agentPrefix}package.json) are installed.`);
     runbook.push(``, `# Build/create/reconcile the service. Re-running this is the complete local redeploy; state stays`, `# in the Compose volume mounted at ${MOUNT}.`, `${compose} up -d --build`, `curl --fail http://127.0.0.1:${input.port}/health`, ``, `# Operate it:`, `${compose} logs -f agent`, `${compose} ps`, `${compose} down        # stops containers; keeps the state volume`, `# ${compose} down -v   # DESTRUCTIVE: also deletes auth, sessions, and channel state`);
     if (input.tunnel) {
         runbook.push(``, `# Quick Tunnel: \`--run\` starts the Compose tunnel service and reads its ephemeral public URL.`, `# Telegram/Feishu/Lark and locally onboarded Slack auto-register; GitHub/manual Slack print console URLs. Re-run after the`, `# tunnel container/Docker daemon restarts: a new Quick Tunnel URL must replace the old webhook URL.`, `${compose} logs -f tunnel`);

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

@@ -49,6 +49,8 @@ export interface FlyPlan {
     /** The ordered, values-resolved deploy runbook — printed to stdout for the coding agent to execute. */
     runbook: string[];
 }
+/** Did fastagent generate this `fly.toml`? */
+export declare function isGeneratedFlyToml(content: string): boolean;
 /** Compute the Fly deploy plan from the resolved definition. */
 export declare function planFlyDeploy(input: FlyPlanInput): FlyPlan;
 /**

package/dist/deploy/fly/plan.js

@@ -18,14 +18,15 @@ function flyToml(appName, port, hasGithub, autostop, scaleToZero, hasTimeTrigger
     const stopLine = autostop === "stop"
         ? `  auto_stop_machines = "stop"      # stop on idle (cold start on the next webhook)`
         : `  auto_stop_machines = "suspend"   # suspend on idle (fast resume on the next webhook)`;
-    return `# Generated by \`fastagent deploy fly\`. Edit freely — it is not regenerated unless you pass --force.
+    return `${GENERATED_FLY_TOML_MARKER}. Edit freely — it is not regenerated unless you pass --force.
 app = "${appName}"
 primary_region = "iad"  # set your region (list: \`fly platform regions\`)
 
 [build]
 
 [env]
-  FASTAGENT_STATE_DIR = "/data"  # the ONE machine-state root — auth, sessions, channel state
+  FASTAGENT_STATE_DIR = "/data/.state"      # mutable machine state — sessions, channel state, schedule
+  FASTAGENT_SECRETS_DIR = "/data/.secrets"  # seeded (and rotated) credentials — must persist across restarts
   PORT = "${port}"
 
 [http_service]
@@ -37,20 +38,27 @@ ${min}
 
 [mounts]
   source = "data"
-  destination = "/data"            # FASTAGENT_STATE_DIR — persists across stop/suspend/redeploy
+  destination = "/data"            # .state + .secrets — persists across stop/suspend/redeploy
 
 [[vm]]
   size = "shared-cpu-1x"
   memory = "512mb"                 # suspend is not recommended above 2 GB
 `;
 }
+/** First line of a generated `fly.toml`, and the predicate that reads it back. Ownership is what decides
+ *  whether `--force` may reset the file (app/region/vm state a user tuned by hand is theirs). */
+const GENERATED_FLY_TOML_MARKER = "# Generated by `fastagent deploy fly`";
+/** Did fastagent generate this `fly.toml`? */
+export function isGeneratedFlyToml(content) {
+    return content.startsWith(GENERATED_FLY_TOML_MARKER);
+}
 /** Compute the Fly deploy plan from the resolved definition. */
 export function planFlyDeploy(input) {
-    const { appName, port, modelAuth, channels, kitDir } = input;
-    // Kit layout: every artifact is namespaced under the kit (agent/fly.toml, agent/Dockerfile) so the
-    // host repo's own deploy files are never touched; the runbook passes explicit -c/--dockerfile flags
-    // (unambiguous across flyctl versions — no reliance on config-relative path resolution).
-    const flyTomlPath = kitDir ? `${kitDir}/fly.toml` : "fly.toml";
+    const { appName, port, modelAuth, channels } = input;
+    // Artifacts sit under the agent prefix, so a NESTED agent never touches the workspace's own deploy
+    // files; the runbook passes explicit -c/--dockerfile flags either way (unambiguous across flyctl
+    // versions — no reliance on config-relative path resolution).
+    const flyTomlPath = `${input.agentPrefix}fly.toml`;
     const artifacts = [
         {
             path: flyTomlPath,
@@ -65,9 +73,7 @@ export function planFlyDeploy(input) {
     const secrets = deploymentSecrets(modelAuth, channels, input.extraSecrets, input.longConnectionChannels);
     const requiredSecrets = secrets.filter((secret) => secret.required);
     const optionalSecrets = secrets.filter((secret) => !secret.required);
-    const deployCmd = kitDir
-        ? `fly deploy . --config ${kitDir}/fly.toml --dockerfile ${kitDir}/Dockerfile --app ${appName}`
-        : `fly deploy --app ${appName}`;
+    const deployCmd = `fly deploy . --config ${flyTomlPath} --dockerfile ${input.agentPrefix}Dockerfile --app ${appName}`;
     const runbook = [
         `# Deploy "${appName}" to Fly.io. ${flyTomlPath} / Dockerfile(.dockerignore) are generated above.`,
         `# Prereqs: flyctl installed (https://fly.io/docs/flyctl/install) and \`fly auth login\`.`,
@@ -76,7 +82,7 @@ export function planFlyDeploy(input) {
         `# Fly app names are GLOBALLY unique: if this fails as taken, set a unique "app" in fly.toml and`,
         `# re-run \`fastagent deploy fly\` — the runbook follows fly.toml's app name.`,
         `fly apps create ${appName}`,
-        `# volume persists FASTAGENT_STATE_DIR=/data (sessions, auth, channel state) across stop/suspend/redeploy.`,
+        `# volume persists /data/.state (sessions, channel state) + /data/.secrets (seeded auth) across stop/suspend/redeploy.`,
         `# <region> MUST equal primary_region in fly.toml (a volume in another region can't mount) — fly.toml`,
         `# is the single source for the region; skip this if the volume exists (fly volumes list --app ${appName}):`,
         `fly volumes create data --app ${appName} --region <region> --size 1`,
@@ -87,20 +93,22 @@ export function planFlyDeploy(input) {
     if (optionalSecrets.length > 0) {
         runbook.push(``, `# Optional secrets — set only when the matching feature is configured:`, ...optionalSecrets.map((s) => `#   ${s.name}: ${s.hint}`), `# fly secrets set --app ${appName} ${optionalSecrets.map((s) => `${s.name}=<value>`).join(" ")}`);
     }
-    if (kitDir) {
-        runbook.push(``, `# Repo-as-workspace: the build context is the REPO ROOT (the whole repo is the agent's cwd); the`, `# config/Dockerfile live under ${kitDir}/ so they never collide with the repo's own deploy files.`, `# Run this from the repo root:`);
+    runbook.push(``, `# The build context is the WORKSPACE ROOT (the whole directory is baked as the agent's cwd).`, ...(input.agentPrefix
+        ? [`# The config/Dockerfile live under ${input.agentPrefix} so they never collide with the workspace's own.`]
+        : []), `# Run this from ${input.agentPrefix ? "the workspace root" : "this directory"}:`, deployCmd);
+    if (input.shipsGit) {
+        runbook.push(``, `# The image is a WYSIWYG snapshot of this directory. Freshness/durability run through git, driven`, `# by the agent itself: .git ships in the image (see .dockerignore) and git is baked in, so the agent`, `# can pull to freshen content and commit/push its work back (creds ride config.deploy.secrets; the`, `# POLICY — push vs PR, identity — lives in persona.md). CAVEAT: whether .git survives the upload is`, `# host-CLI-dependent — verify \`git status\` on the box; if missing, have the agent clone instead.`, `# Un-pushed changes on the box never survive a redeploy; durability lives in git.`);
     }
-    runbook.push(deployCmd);
-    if (kitDir) {
-        runbook.push(``, `# Write-back mechanics: git ships in the image and GH_TOKEN-style creds ride config.deploy.secrets;`, `# the POLICY (push vs PR, identity, remote) lives in persona.md. CAVEAT — whether .git survives is`, `# host-CLI-dependent (some context packers strip it from the upload): verify \`git status\` on the`, `# box after the first deploy; if it is missing, have the agent \`git clone\` its repo in the`, `# workspace instead (same token). Un-pushed changes never survive a redeploy — the image is a`, `# snapshot; durability lives in git.`);
+    else {
+        runbook.push(``, `# The image is a WYSIWYG snapshot of this directory. No .git here, so no history ships and the`, `# generated image does not install git — changes on the box are ephemeral and never survive a`, `# redeploy. If the agent should clone/push repos as part of its work, add deploy: { apt: ["git"] }.`);
     }
     // Model-auth guidance: an env key becomes a secret above. Otherwise the plan can't read the local
     // credential's VALUE to set as a secret — true for OAuth AND a stored API key (both are
     // `AuthResult.source` non-env labels), so the wording doesn't prejudge whether it's migratable.
     if (!isEnvKey(modelAuth)) {
         runbook.push(``, modelAuth === undefined
-            ? `# Model auth: none found at the local auth path — a global \`fastagent login\` isn't read here; pass --auth-path <file> (e.g. ~/.fastagent/auth.json), or \`--run\` carries it automatically.`
-            : `# Model auth: your local auth is "${modelAuth}" — the plan can't read its value to set as a secret.`, `#   Set your provider API key as a Fly secret (fly secrets set KEY=...), OR place auth.json on the /data volume.`);
+            ? `# Model auth: none found at the local auth path — a global \`fastagent login\` isn't read here; pass --auth-path <file> (e.g. ~/.fastagent/.secrets/auth.json), or \`--run\` carries it automatically.`
+            : `# Model auth: your local auth is "${modelAuth}" — the plan can't read its value to set as a secret.`, `#   Set your provider API key as a Fly secret (fly secrets set KEY=...), OR place auth.json at /data/.secrets/ on the volume.`);
     }
     // The fastagent-only post-step: point each channel's webhook at the live URL. Only fastagent knows the routes.
     // The URLs below assume each channel's DEFAULT route key (POST /telegram, POST /webhook). Reading the

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

@@ -26,6 +26,14 @@ import type { CliRunner } from "../runner.ts";
  * is never overwritten by the stale seed, so a box that ran its own OAuth refresh is not rolled back.
  */
 export declare function authSeedBytes(seed: string | undefined, fileExists: boolean): Buffer | undefined;
+/**
+ * Collect the (possibly CHUNKED) auth seed from the environment: `FASTAGENT_AUTH_SEED` plus numbered
+ * continuations (`_2`, `_3`, …) concatenated in order. Hosts whose env values carry a small max
+ * length (AgentCore: 2048 chars — a real OAuth auth.json's base64 exceeds it) split the seed across
+ * them at deploy time; single-var hosts (Fly/Railway) never set a continuation and are unchanged.
+ * Collection stops at the first absent/empty continuation — the writer fills them contiguously.
+ */
+export declare function collectAuthSeed(env: NodeJS.ProcessEnv): string | undefined;
 export interface FlyRunPlan {
     appName: string;
     region: string;
@@ -36,8 +44,11 @@ export interface FlyRunPlan {
     missingSecrets: string[];
     channels: ChannelKind[];
     longConnectionChannels?: string[];
-    /** fly.toml path passed to `fly deploy -c` (relative to the run cwd = the workspace dir). */
+    /** fly.toml path passed to `fly deploy -c` (relative to the run cwd = the workspace root). */
     flyConfig: string;
+    /** Dockerfile path passed explicitly (`fastagent/Dockerfile`, with the workspace as context —
+     *  flyctl would otherwise resolve it relative to the config's own directory). */
+    dockerfile: string;
 }
 /** Done, or a gate the operator must clear before re-running (printed + non-zero exit by the CLI). */
 export type FlyRunOutcome = {

package/dist/deploy/fly/run.js

@@ -7,6 +7,26 @@ import { registrationGate } from "../registration-gate.js";
 export function authSeedBytes(seed, fileExists) {
     return !seed || fileExists ? undefined : Buffer.from(seed, "base64");
 }
+/**
+ * Collect the (possibly CHUNKED) auth seed from the environment: `FASTAGENT_AUTH_SEED` plus numbered
+ * continuations (`_2`, `_3`, …) concatenated in order. Hosts whose env values carry a small max
+ * length (AgentCore: 2048 chars — a real OAuth auth.json's base64 exceeds it) split the seed across
+ * them at deploy time; single-var hosts (Fly/Railway) never set a continuation and are unchanged.
+ * Collection stops at the first absent/empty continuation — the writer fills them contiguously.
+ */
+export function collectAuthSeed(env) {
+    const first = env.FASTAGENT_AUTH_SEED;
+    if (!first)
+        return undefined;
+    let seed = first;
+    for (let i = 2;; i++) {
+        const part = env[`FASTAGENT_AUTH_SEED_${i}`];
+        if (!part)
+            break;
+        seed += part;
+    }
+    return seed;
+}
 /** Whether a `fly … list --json` array contains an object named `name` (Fly capitalizes `Name`; accept both). */
 function listHasName(stdout, name) {
     try {
@@ -74,9 +94,23 @@ export async function deployFlyRun(plan, fly, log, registerTelegram, registerFei
             return gate("`fly secrets import` failed — see the flyctl output above");
         }
     }
-    // 6. Deploy — remote builder (no local Docker), one machine.
+    // 6. Deploy — remote builder (no local Docker), one machine. Context + Dockerfile are passed
+    //    explicitly (the workspace root is the context; the Dockerfile lives under fastagent/).
     log("deploying (remote build)…");
-    if ((await fly(["deploy", "-a", plan.appName, "-c", plan.flyConfig, "--remote-only", "--yes", "--ha=false"])).code !== 0) {
+    const deployArgs = [
+        "deploy",
+        ".",
+        "-a",
+        plan.appName,
+        "-c",
+        plan.flyConfig,
+        "--dockerfile",
+        plan.dockerfile,
+        "--remote-only",
+        "--yes",
+        "--ha=false",
+    ];
+    if ((await fly(deployArgs)).code !== 0) {
         return gate("`fly deploy` failed — see the flyctl output above; fix and re-run");
     }
     // 7. Post-deploy webhook — telegram end-to-end (fastagent has the token + the live URL); github is a

package/dist/deploy/preflight.d.ts

@@ -1,4 +1,5 @@
 import type { FastagentConfig } from "../engines/pi/config.ts";
+import { type ResolvedPlacement } from "../paths.ts";
 import { type ChannelKind } from "../scaffold/add-channel.ts";
 import { type ContainerInput } from "./container.ts";
 /** A stderr line the CLI prints (`[fastagent] warn: …` / `[fastagent] note: …`). Host-neutral advisories. */
@@ -40,17 +41,22 @@ export type DeployPreflight = {
  * provider) — the CLI wraps the call in its `failStartup` so the fault surfaces and exits, never silently.
  */
 export declare function preflightDeploy(input: {
-    target: string;
-    /** The agent-definition dir (config.agentDir resolved against target; = target when unset) — where
-     *  channels are discovered. Container facts (package.json/lockfile) still read `target`, the run root. */
-    agentDir: string;
+    /** The resolved placement. `agentDir` is where channels/schedules are discovered and where the
+     *  container facts (package.json/lockfile) are read — the AGENT's manifest drives the image's install
+     *  step, never the workspace's (whose manifest belongs to its own deploy); `workspace` is the build
+     *  context (the whole tree is baked). One value, because one derives from the other: two loose
+     *  strings could be handed in disagreeing, and nothing would notice. */
+    placement: ResolvedPlacement;
     config: FastagentConfig;
     modelSpec: string | undefined;
     /** `--run` fully deploys, so a model that won't travel is a GATE (a known crash-loop); else it warns. */
     run: boolean;
     /** `--force` regenerates artifacts, so the kept-hand-written-Dockerfile apt warning does not apply. */
     force: boolean;
-    /** The raw `--auth-path` flag; the chain (flag > FASTAGENT_AUTH_PATH > `<state root>/auth.json`)
+    /** The target delivers cron slots from an external clock and holds no resident process (AgentCore):
+     *  resident-host keep-alive notes do not apply; the host branch owns its capability gates. */
+    externalClock?: boolean;
+    /** The raw `--auth-path` flag; the chain (flag > FASTAGENT_AUTH_PATH > `<agentDir>/.secrets/auth.json`)
      *  is resolved HERE via {@link resolveAuthPath} — the one owner, same as every serving command. */
     authPathFlag: string | undefined;
 }): Promise<DeployPreflight>;