@fastagent-sh/fastagent 0.15.0 → 0.16.0

package/dist/deploy/preflight.js

@@ -9,23 +9,59 @@
  * 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.
  */
-import { readFile } from "node:fs/promises";
-import { join, relative, sep } from "node:path";
+import { readdir, readFile } from "node:fs/promises";
+import { basename, isAbsolute, join, relative, sep } from "node:path";
+import ignore from "ignore";
 import { resolveAuthPath } from "../engines/pi/config.js";
+import { resolveSecretsDir, resolveStateRoot } from "../paths.js";
 import { inspectChannels } from "../engines/pi/channel.js";
 import { discoverScheduleFiles } from "../schedule/discover.js";
 import { createPiModels, probeAuthSource } from "../engines/pi/models.js";
 import { CHANNEL_KINDS } from "../scaffold/add-channel.js";
-import { exists } from "../scaffold/init.js";
+import { exists } from "../paths.js";
 import { detectRuntime, readPackageJson } from "../runtime.js";
 import { fastagentVersion } from "../version.js";
-import { isGeneratedDockerfile } from "./container.js";
+import { isGeneratedDockerfile, isGeneratedDockerignore } from "./container.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);
+}
 /**
  * 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.
  */
 export async function preflightDeploy(input) {
-    const { target, agentDir, config, modelSpec, run, force, authPathFlag } = 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.
@@ -74,14 +110,14 @@ export async function preflightDeploy(input) {
     // ("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;
-    if (longConnectionChannels.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).`,
         });
     }
-    if (hasTimeTriggers) {
+    if (hasTimeTriggers && !externalClock) {
         messages.push({
             level: "note",
             text: `schedules/self-scheduling present — a GENERATED plan keeps one machine running (cron/wake has ` +
@@ -90,46 +126,37 @@ export async function preflightDeploy(input) {
     }
     // 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".
-    const authPath = resolveAuthPath(target, authPathFlag);
+    const authPath = resolveAuthPath(agentDir, authPathFlag);
     const modelAuth = modelSpec ? await probeAuthSource(createPiModels({ authPath }), modelSpec) : undefined;
-    // Container facts (shared by every host) + the warnings that follow. Repo-as-workspace layout
-    // (agentDir ≠ target): the facts describe the KIT — its package.json/runtime/lockfile drive the
-    // image's install step — never the host repo's (whose manifest belongs to the host's own deploy).
-    // POSIX-normalized: kitDir lands verbatim in Dockerfile COPY/CMD lines and fly/railway commands,
-    // which all require forward slashes (a Windows `relative()` would emit backslashes).
-    const kitDir = agentDir === target ? undefined : relative(target, agentDir).split(sep).join("/");
-    const factsDir = kitDir ? agentDir : target;
-    if (kitDir && run) {
-        // The repo-as-workspace deployment shape remains experimental for every target. Generation +
-        // runbook are supported; automated runners stay gated until an explicit end-to-end smoke validates
-        // context packing, ignore rules, installed deps, state, and write-back for this layout.
-        return {
-            ok: false,
-            gate: `--run is not yet supported for the agentDir layout — run the same deploy without --run and follow the printed runbook`,
-        };
-    }
-    const hasPackageJson = await exists(join(factsDir, "package.json"));
-    const pkg = await readPackageJson(factsDir);
-    const { runtime, bunVersion, hasLockfile } = detectRuntime(factsDir, pkg);
+    // 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).
+    const hasPackageJson = await exists(join(agentDir, "package.json"));
+    const pkg = await readPackageJson(agentDir);
+    const { runtime, bunVersion, hasLockfile } = detectRuntime(agentDir, pkg);
     const install = runtime === "bun" ? "bun install" : "npm install";
     const runner = runtime === "bun" ? "bun run fastagent" : "./node_modules/.bin/fastagent";
     const hasOtherLock = runtime === "node" &&
-        ((await exists(join(factsDir, "pnpm-lock.yaml"))) || (await exists(join(factsDir, "yarn.lock"))));
-    if (kitDir) {
-        // After the facts: the deps sentence must match the kit's actual shape (a markdown-only kit has no
-        // package.json and installs nothing — the note must not point at a file that doesn't exist).
-        const deps = hasPackageJson
-            ? `only the kit's deps (${kitDir}/package.json) are installed — the host repo's own deps are the agent's runtime concern`
-            : `the kit has no package.json, so no deps are installed (the pinned global CLI serves the repo)`;
-        messages.push({
-            level: "note",
-            text: `repo-as-workspace image (EXPERIMENTAL — not yet verified end-to-end on a real host): the whole ` +
-                `repo is baked as the agent's cwd; ${deps}. Un-pushed changes on the box do not survive a redeploy ` +
-                `(the image is a snapshot); write-back goes through git (persona owns the policy; GH_TOKEN etc. go ` +
-                `in config.deploy.secrets — see the runbook's caveat on .git surviving the host's upload).`,
-        });
-    }
-    // A code workspace with no lockfile builds via a non-frozen install (ranges resolve at build time) — not
+        ((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.
+    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).
+    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" : ""}`
+        : `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).
     if (hasPackageJson && !hasLockfile) {
         const lock = runtime === "bun" ? "bun.lock" : "package-lock.json";
@@ -142,7 +169,7 @@ export async function preflightDeploy(input) {
                     `Run \`${install}\` and commit the lockfile for pinned redeploys.`,
         });
     }
-    // The code-path Dockerfile runs `${runner}` — the workspace's OWN local dependency, never the
+    // 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).
     if (hasPackageJson && !("@fastagent-sh/fastagent" in { ...pkg.dependencies, ...pkg.devDependencies })) {
         messages.push({
@@ -151,42 +178,167 @@ export async function preflightDeploy(input) {
                 `so the container fails at start. Add it to dependencies and re-run \`${install}\`.`,
         });
     }
-    // A kept host root .dockerignore silently replaces KIT_DOCKERIGNORE's two protections — read it and
-    // warn SPECIFICALLY (the generic "kept" line suggests --force, which would clobber the host's file):
-    // (a) a .git exclude kills the baked write-back (the runtime-clone fallback applies); (b) without a
-    // recursive **/node_modules the build machine's kit deps (native binaries) clobber the image's.
-    // Not force-gated: the host's root .dockerignore is kept even under --force (never ours to clobber),
-    // so these warnings apply regardless.
-    if (kitDir && (await exists(join(target, ".dockerignore")))) {
-        const lines = (await readFile(join(target, ".dockerignore"), "utf8")).split("\n").map((l) => l.trim());
-        if (lines.some((l) => l === ".git" || l === "/.git" || l === ".git/" || l === "**/.git")) {
+    // 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, not the two filenames we happen to know: an atomic-write temp beside
+    // auth.json, a second key file, an editor backup of `.env` — all of it must stay out of the image, and
+    // `resolveSecretsDir` says as much ("everything fastagent manages that must never leave the machine").
+    // 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();
+    const leakCandidates = [...(await present(secretPaths)), ...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 readFile(join(workspace, rel), "utf8").catch(() => undefined);
+        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 .dockerignore excludes .git — the baked repo ships WITHOUT history/remote, so the agent ` +
-                    `cannot commit/push the baked copy; it must \`git clone\` its repo in the workspace instead ` +
-                    `(or remove the .git line).`,
+                text: `your ${rel} (kept) does not exclude \`${stateRel}\` — the build machine's sessions/channel state would ship in the image. ${remedy([`/${stateRel}`])}`,
             });
         }
-        if (!lines.some((l) => l === "**/node_modules" || l === "**/node_modules/")) {
+        // 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 .dockerignore lacks \`**/node_modules\` — the build machine's ${kitDir}/node_modules ` +
-                    `(native binaries for YOUR OS) would be uploaded and clobber the image's freshly-installed ones. ` +
-                    `Add \`**/node_modules\` to it.`,
+                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): a kit-layout image always
-    // carries git, so commit/push can work at all. Merged with (never duplicating) config.deploy.apt.
-    const apt = kitDir ? [...new Set(["git", ...(config.deploy?.apt ?? [])])] : config.deploy?.apt;
+    // 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 apt = shipsGit ? [...new Set(["git", ...(config.deploy?.apt ?? [])])] : config.deploy?.apt;
     const container = {
+        agentPrefix,
+        machineryPaths,
         hasPackageJson,
         runtime,
         bunVersion,
         hasLockfile,
         version: await fastagentVersion(),
         apt,
-        kitDir,
+        shipsGit,
     };
     const port = config.http?.port ?? 8787;
     // What the agent declared it needs on the box (fastagent.config deploy.secrets) — carried like channel
@@ -195,7 +347,7 @@ export async function preflightDeploy(input) {
     // 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 = kitDir ? join(agentDir, "Dockerfile") : join(target, "Dockerfile");
+    const dockerfileHome = join(agentDir, "Dockerfile");
     if (config.deploy?.apt?.length && !force && (await exists(dockerfileHome))) {
         if (!isGeneratedDockerfile(await readFile(dockerfileHome, "utf8"))) {
             messages.push({

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

@@ -46,5 +46,12 @@ export interface RailwayPlan {
     /** The ordered, values-resolved deploy runbook — printed to stdout for the coding agent to execute. */
     runbook: string[];
 }
+/** The `RAILWAY_DOCKERFILE_PATH` value for an agent under `prefix` — repo-root-anchored with a leading
+ *  slash, the form Railway's builds/dockerfiles docs use for a Dockerfile in another directory. The
+ *  config file's `dockerfilePath` spells it WITHOUT the slash (the config-as-code schema's own
+ *  convention); two mechanisms, two documented spellings, one fact each. */
+export declare const dockerfilePathVar: (prefix: string) => string;
+/** Did fastagent generate this `railway.json`? Unparseable or unmarked reads as the author's. */
+export declare function isGeneratedRailwayJson(content: string): boolean;
 /** Compute the Railway deploy plan from the resolved definition. */
 export declare function planRailwayDeploy(input: RailwayPlanInput): RailwayPlan;

package/dist/deploy/railway/plan.js

@@ -2,25 +2,47 @@ import { containerArtifacts } from "../container.js";
 import { deploymentSecrets, isEnvKey } from "../secrets.js";
 /** State root = the volume mount path, kept in lockstep. `/data` matches the Fly recipe. */
 const MOUNT = "/data";
+/** The `RAILWAY_DOCKERFILE_PATH` value for an agent under `prefix` — repo-root-anchored with a leading
+ *  slash, the form Railway's builds/dockerfiles docs use for a Dockerfile in another directory. The
+ *  config file's `dockerfilePath` spells it WITHOUT the slash (the config-as-code schema's own
+ *  convention); two mechanisms, two documented spellings, one fact each. */
+export const dockerfilePathVar = (prefix) => `/${prefix}Dockerfile`;
 /** railway.json — build/deploy only (Railway's config-as-code scope). No env/volume/sleeping here: those
  *  are service settings the runbook applies via CLI. healthcheckPath gates routing on a live server. */
-function railwayJson(kitDir) {
+/** railway.json is JSON, so its ownership marker is a KEY rather than a comment line. Railway ignores
+ *  unknown keys; the predicate below is what lets `--force` reset OUR file and keep a hand-written one. */
+const GENERATED_RAILWAY_KEY = "x-generated-by";
+const GENERATED_RAILWAY_VALUE = "fastagent deploy railway";
+/** Did fastagent generate this `railway.json`? Unparseable or unmarked reads as the author's. */
+export function isGeneratedRailwayJson(content) {
+    try {
+        return JSON.parse(content)[GENERATED_RAILWAY_KEY] === GENERATED_RAILWAY_VALUE;
+    }
+    catch {
+        return false;
+    }
+}
+function railwayJson(prefix) {
     return `${JSON.stringify({
         $schema: "https://railway.com/railway.schema.json",
-        // dockerfilePath is relative to the repo root (`railway up`'s upload context) in BOTH layouts.
-        build: { builder: "DOCKERFILE", dockerfilePath: kitDir ? `${kitDir}/Dockerfile` : "Dockerfile" },
+        [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, modelAuth, channels } = input;
-    // Kit layout: railway.json is namespaced under the kit too (the host repo may carry its own
-    // railway.toml/json for the product). Railway reads config-as-code from the repo root by default,
-    // so the runbook adds the dashboard step that points the service at the kit's file (no CLI flag exists).
-    const configPath = input.kitDir ? `${input.kitDir}/railway.json` : "railway.json";
+    // railway.json is namespaced under the agent dir too (the workspace may carry its own
+    // railway.toml/json for the product). Railway reads config-as-code from the repo root by default and
+    // pointing it at a custom path is DASHBOARD-ONLY — so the BUILD entry travels as the scriptable
+    // RAILWAY_DOCKERFILE_PATH service variable instead (Railway's documented non-root-Dockerfile route),
+    // and the config-as-code pointer degrades to an OPTIONAL enhancement: the /health gate (Railway's
+    // default restart policy already matches the file's ON_FAILURE).
+    const configPath = `${input.agentPrefix}railway.json`;
     const artifacts = [
-        { path: configPath, content: railwayJson(input.kitDir) },
+        { path: configPath, content: railwayJson(input.agentPrefix) },
         ...containerArtifacts(input),
     ];
     const secrets = deploymentSecrets(modelAuth, channels, input.extraSecrets, input.longConnectionChannels);
@@ -47,11 +69,13 @@ export function planRailwayDeploy(input) {
         `# the later commands resolve it without --service (--run passes --service to stay non-interactive).`,
         `railway add --service ${serviceName}`,
         ``,
-        `# Persistent volume at ${MOUNT} — sessions, auth, channel state. FASTAGENT_STATE_DIR is set to match.`,
+        `# Persistent volume at ${MOUNT} — .state (sessions, channel state) + .secrets (seeded auth).`,
         `railway volume add --mount-path ${MOUNT}`,
         ``,
         `# Variables — set BEFORE the first deploy so the box boots with them. Railway injects PORT itself.`,
-        `railway variables set FASTAGENT_STATE_DIR=${MOUNT}`,
+        `# 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)}`,
     ];
     if (requiredSecrets.length > 0) {
         runbook.push(`# Required secrets:`, `#   ${requiredSecrets.map((s) => `${s.name}: ${s.hint}`).join("\n#   ")}`, `railway variables set ${requiredSecrets.map((s) => `${s.name}=<value>`).join(" ")}`);
@@ -63,15 +87,16 @@ export function planRailwayDeploy(input) {
     // credential's value (OAuth or a stored key) to set it — same wording discipline as the Fly plan.
     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: 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 variable.`, `#   Set your provider API key as a variable (railway variables set KEY=...), OR place auth.json on the ${MOUNT} volume.`);
     }
-    if (input.kitDir) {
-        runbook.push(``, `# Repo-as-workspace: point the service at the kit's config file BEFORE the first deploy —`, `# dashboard-only, like App Sleeping (no CLI flag): Service → Settings → Config-as-code →`, `# set the file path to ${configPath}. Without it Railway would read the repo root's own config.`);
-    }
+    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(``, `# Deploy — uploads this dir and builds the Dockerfile on Railway (no local Docker needed). This is`, `# also the ENTIRE redeploy: re-run \`railway up\` alone (the one-time setup above is not repeated).`, `railway up`);
-    if (input.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 — \`railway up\` is known to`, `# strip .git from its upload, so expect NO baked history on the box: the agent should \`git clone\``, `# its repo in the workspace (same token) before making changes. Un-pushed changes never survive a`, `# redeploy — the image is a snapshot; durability lives in git.`);
+    if (input.shipsGit) {
+        runbook.push(``, `# The image is a WYSIWYG snapshot of this directory. Freshness/durability run through git, driven`, `# by the agent itself (pull to freshen, commit/push to write back; creds ride config.deploy.secrets;`, `# git is baked into the image). CAVEAT — \`railway up\` is known to strip .git from its upload:`, `# expect NO baked history on the box; the agent should \`git clone\` its repo in the workspace`, `# (same token) before making changes.`, `# Un-pushed changes on the box never survive a redeploy; 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"] }.`);
     }
     // The public URL is minted, not deterministic (unlike Fly's <app>.fly.dev) — ONE mint step, then each
     // channel's webhook uses that domain (mint once even when both channels are present).

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

@@ -30,7 +30,8 @@ export interface RailwayRunPlan {
     /** Names both the project (`railway init --name`) and the service (`railway add --service`). Railway
      *  names are project-scoped, not globally unique — the CLI derives it from the dir basename. */
     name: string;
-    /** The volume mount path AND `FASTAGENT_STATE_DIR` (kept in lockstep). `/data`, matching the Fly recipe. */
+    /** The volume mount path; `FASTAGENT_STATE_DIR`/`FASTAGENT_SECRETS_DIR` are set to `.state`/`.secrets`
+     *  under it (kept in lockstep). `/data`, matching the Fly recipe. */
     mountPath: string;
     /** `KEY=value` secrets set one-per-`variable set --stdin`: model key (env auth) or `FASTAGENT_AUTH_SEED`
      *  (file auth) + channel secrets. Never on argv. */
@@ -43,6 +44,12 @@ export interface RailwayRunPlan {
      *  by default so `--run` only creates on an unlinked dir and never deploys into a pre-existing (possibly
      *  unrelated/production) project; the flag is the operator's explicit "yes, this project". */
     intoLinked: boolean;
+    /** `RAILWAY_DOCKERFILE_PATH` value (`/fastagent/Dockerfile`) — Railway's service-variable route to a
+     *  non-root Dockerfile (builds/dockerfiles docs), set with the machinery variables BEFORE the first
+     *  `up` so the build never falls back to auto-detecting the workspace root. The config-as-code file
+     *  also carries the path, but pointing Railway at `fastagent/railway.json` is dashboard-only — the
+     *  variable is the scriptable way. */
+    dockerfilePath: 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

@@ -128,8 +128,13 @@ export async function deployRailwayRun(plan, railway, log, registerTelegram, reg
     //     volume (which has no --service and would otherwise attach to that service) — so the mismatch fails
     //     visibly with NO side effect. State root on argv (not secret); secrets one-per-`set --stdin` (value
     //     on stdin, never argv). Idempotent. (Order vs the volume is free — both just need to precede `up`.)
-    log(`setting FASTAGENT_STATE_DIR + ${Object.keys(plan.secrets).length} secret(s)…`);
-    if ((await railway(["variables", "set", `FASTAGENT_STATE_DIR=${plan.mountPath}`, ...svc])).code !== 0) {
+    const machineryVars = [
+        `FASTAGENT_STATE_DIR=${plan.mountPath}/.state`,
+        `FASTAGENT_SECRETS_DIR=${plan.mountPath}/.secrets`,
+        `RAILWAY_DOCKERFILE_PATH=${plan.dockerfilePath}`,
+    ];
+    log(`setting ${machineryVars.map((v) => v.split("=")[0]).join("/")} + ${Object.keys(plan.secrets).length} secret(s)…`);
+    if ((await railway(["variables", "set", ...machineryVars, ...svc])).code !== 0) {
         return gate("`railway variables set` failed — see the railway output above");
     }
     for (const [k, v] of Object.entries(plan.secrets)) {

package/dist/deploy/runner.d.ts

@@ -1,8 +1,10 @@
 interface RunResult {
     code: number;
-    /** Captured stdout (for `--json` queries); empty when the command streamed to the terminal. The CLI's
-     *  stderr is always inherited straight to the terminal, so it is not a field here. */
+    /** Captured stdout (for `--json` queries); empty when the command streamed to the terminal. */
     stdout: string;
+    /** Captured stderr — ONLY when `captureStderr` was set (a caller that must CLASSIFY a failure, e.g.
+     *  "not found" vs "denied"); otherwise undefined and stderr streams to the terminal as always. */
+    stderr?: string;
 }
 /** Run `bin args`: `capture` collects stdout (for `--json` queries), else the command streams to the
  *  terminal (create/deploy) and stdout is empty; `input` is fed to stdin (secrets over stdin, never argv).
@@ -10,6 +12,7 @@ interface RunResult {
  *  values in argv or mutating the long-lived CLI process. */
 export type CliRunner = (args: string[], opts?: {
     capture?: boolean;
+    captureStderr?: boolean;
     input?: string;
     env?: NodeJS.ProcessEnv;
 }) => Promise<RunResult>;

package/dist/deploy/runner.js

@@ -14,13 +14,19 @@ export function spawnRunner(bin, cwd) {
         const child = spawn(bin, args, {
             cwd,
             env: opts?.env ? { ...process.env, ...opts.env } : process.env,
-            stdio: [opts?.input ? "pipe" : "inherit", opts?.capture ? "pipe" : "inherit", "inherit"],
+            stdio: [
+                opts?.input ? "pipe" : "inherit",
+                opts?.capture ? "pipe" : "inherit",
+                opts?.captureStderr ? "pipe" : "inherit",
+            ],
         });
         let out = "";
+        let err = "";
         child.stdout?.on("data", (d) => (out += String(d)));
+        child.stderr?.on("data", (d) => (err += String(d)));
         if (opts?.input)
             child.stdin?.end(opts.input);
-        child.on("close", (code) => res({ code: code ?? 1, stdout: out }));
-        child.on("error", () => res({ code: 127, stdout: "" })); // ENOENT: bin not on PATH
+        child.on("close", (code) => res({ code: code ?? 1, stdout: out, stderr: opts?.captureStderr ? err : undefined }));
+        child.on("error", () => res({ code: 127, stdout: "", stderr: opts?.captureStderr ? "" : undefined })); // ENOENT
     });
 }

package/dist/dev-supervisor.d.ts

@@ -1,12 +1,15 @@
+import { type ResolvedPlacement } from "./paths.ts";
 /**
- * chokidar `ignored` matcher for the narrow watch scope (true = ignore). Ignoring a directory prunes
- * the whole subtree, so everything outside the allowlist — .fastagent state, node_modules, .git, and
- * any file/dir the agent writes as work product — costs no watchers and triggers no restarts.
- * Helper code imported from OUTSIDE tools//channels/ is out of scope by design (keep it under
- * tools/, or restart manually) — the startup log names the watched set.
+ * chokidar `ignored` matcher for the narrow watch scope (true = ignore), rooted at the AGENT DIR. When
+ * the agent sits INSIDE the workspace that means the surrounding tree never triggers a restart at all;
+ * when the agent IS the workspace the root is that tree, and the allowlist below is what keeps the
+ * author's own files out of scope. Ignoring a directory prunes the whole subtree, so everything outside it —
+ * `.state/` machine state, node_modules, .git, and any file/dir the agent writes as work product —
+ * costs no watchers and triggers no restarts. Helper code imported from OUTSIDE tools//channels/ is
+ * out of scope by design (keep it under tools/, or restart manually) — the startup log names the set.
  */
-export declare function devWatchIgnored(dir: string, agentDir: string): (path: string) => boolean;
-/** Spawn the dev worker and restart it on workspace edits; supervise its lifecycle until the process exits. */
-export declare function runDevSupervisor(dir: string, options?: {
+export declare function devWatchIgnored(root: string, envFile: string): (path: string) => boolean;
+/** Spawn the dev worker and restart it on agent-dir edits; supervise its lifecycle until the process exits. */
+export declare function runDevSupervisor(placement: ResolvedPlacement, options?: {
     tunnel?: boolean;
 }): Promise<void>;