@fastagent-sh/fastagent 0.14.0 → 0.16.0

package/dist/deploy/railway/plan.js

@@ -2,28 +2,50 @@ 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);
+    const secrets = deploymentSecrets(modelAuth, channels, input.extraSecrets, input.longConnectionChannels);
     const requiredSecrets = secrets.filter((secret) => secret.required);
     const optionalSecrets = secrets.filter((secret) => !secret.required);
     // Order matters, not cosmetics: `railway init` creates a PROJECT with no service, but the volume and
@@ -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,20 +87,24 @@ 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).
     const hasFeishuCloudChannel = ["feishu", "lark"].some((kind) => channels.includes(kind));
-    if (channels.includes("telegram") || channels.includes("github") || hasFeishuCloudChannel) {
+    if (channels.includes("telegram") ||
+        channels.includes("github") ||
+        channels.includes("slack") ||
+        hasFeishuCloudChannel) {
         runbook.push(``, `# Public URL — Railway mints a *.up.railway.app domain (NOT deterministic). Generate it, then read`, `# the printed https URL and use it as <your-domain> in the webhook step(s) below:`, `railway domain`);
     }
     if (channels.includes("telegram")) {
@@ -85,8 +113,11 @@ export function planRailwayDeploy(input) {
     if (channels.includes("github")) {
         runbook.push(`# Set the GitHub webhook (repo Settings → Webhooks). Default route POST /webhook; if you remapped it`, `# in channels/github.ts, use your path:`, `#   Payload URL = https://<your-domain>/webhook, content type application/json, secret = GITHUB_WEBHOOK_SECRET`);
     }
+    if (channels.includes("slack")) {
+        runbook.push(`# Set Slack Event Subscriptions → Request URL (default route POST /slack; the running service`, `# answers Slack's challenge), and match scopes/subscriptions to channels/slack.ts groupBehavior:`, `#   Request URL = https://<your-domain>/slack`);
+    }
     for (const kind of ["feishu", "lark"]) {
-        if (!channels.includes(kind))
+        if (!channels.includes(kind) || input.longConnectionChannels?.includes(kind))
             continue;
         const label = kind === "feishu" ? "Feishu" : "Lark";
         runbook.push(`# Set the ${label} event Request URL (developer console → Events & Callbacks). Default route`, `# POST /${kind}; the service must be RUNNING when you save (the console verifies with a challenge):`, `#   Request URL = https://<your-domain>/${kind}`);
@@ -98,6 +129,8 @@ export function planRailwayDeploy(input) {
         ? `# Scale-to-zero: do NOT enable App Sleeping — github turns have no replay, a sleep mid-review is lost.`
         : input.hasTimeTriggers
             ? `# Scale-to-zero: do NOT enable App Sleeping — schedules/wake-ups have no external wake-up; a sleeping service sleeps through them.`
-            : `# Scale-to-zero (optional, dashboard-only — no CLI/API): Settings → Deploy → Serverless → App Sleeping.`, `# Keep this a SINGLE service: the ${MOUNT} volume is tied to one service; extra replicas split state.`);
+            : (input.longConnectionChannels?.length ?? 0) > 0
+                ? `# Scale-to-zero: do NOT enable App Sleeping — a long-connection channel must remain connected.`
+                : `# Scale-to-zero (optional, dashboard-only — no CLI/API): Settings → Deploy → Serverless → App Sleeping.`, `# 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

@@ -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. */
@@ -38,10 +39,17 @@ export interface RailwayRunPlan {
     /** Required secret names with NO local value — the run gates on these before any side effect. */
     missingSecrets: string[];
     channels: ChannelKind[];
+    longConnectionChannels?: string[];
     /** Opt-in (CLI `--into-linked`) to provision INTO the project this directory is already linked to. Off
      *  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). */
@@ -76,9 +84,9 @@ export declare function parseDomainUrl(stdout: string): string | undefined;
  */
 export declare function parseHasVolume(stdout: string, mountPath: string): boolean;
 /**
- * Run the deploy through `railway`. `log` reports progress; `registerTelegram(baseUrl)` /
- * `registerFeishu(baseUrl, kind)` perform the post-deploy webhook steps (the CLI passes its canonical
- * Feishu registrar, which also serves the Lark compatibility profile). Absent, the manual console
+ * Run the deploy through `railway`. `log` reports progress; the injected Telegram/Feishu/Slack
+ * registrars perform post-deploy webhook steps from the builder machine (Slack's control credential
+ * never travels to the host). Absent, the manual console
  * instruction is printed. Every gate is fail-visible.
  */
-export declare function deployRailwayRun(plan: RailwayRunPlan, railway: CliRunner, log: (msg: string) => void, registerTelegram: (baseUrl: string) => Promise<RegistrationOutcome>, registerFeishu?: (baseUrl: string, kind: "feishu" | "lark") => Promise<RegistrationOutcome>): Promise<RailwayRunOutcome>;
+export declare function deployRailwayRun(plan: RailwayRunPlan, railway: CliRunner, log: (msg: string) => void, registerTelegram: (baseUrl: string) => Promise<RegistrationOutcome>, registerFeishu?: (baseUrl: string, kind: "feishu" | "lark") => Promise<RegistrationOutcome>, registerSlack?: (baseUrl: string) => Promise<RegistrationOutcome>): Promise<RailwayRunOutcome>;

package/dist/deploy/railway/run.js

@@ -62,12 +62,12 @@ export function parseHasVolume(stdout, mountPath) {
     return jsonStrings(stdout).includes(mountPath);
 }
 /**
- * Run the deploy through `railway`. `log` reports progress; `registerTelegram(baseUrl)` /
- * `registerFeishu(baseUrl, kind)` perform the post-deploy webhook steps (the CLI passes its canonical
- * Feishu registrar, which also serves the Lark compatibility profile). Absent, the manual console
+ * Run the deploy through `railway`. `log` reports progress; the injected Telegram/Feishu/Slack
+ * registrars perform post-deploy webhook steps from the builder machine (Slack's control credential
+ * never travels to the host). Absent, the manual console
  * instruction is printed. Every gate is fail-visible.
  */
-export async function deployRailwayRun(plan, railway, log, registerTelegram, registerFeishu) {
+export async function deployRailwayRun(plan, railway, log, registerTelegram, registerFeishu, registerSlack) {
     const gate = (g) => ({ ok: false, gate: g });
     // Every --service below targets plan.name — the name this tool gives BOTH the project and the service
     // (`init --name` + `add --service`). On a fresh create they match; on `--into-linked` into a hand-made
@@ -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)) {
@@ -179,8 +184,18 @@ export async function deployRailwayRun(plan, railway, log, registerTelegram, reg
         log(`github: set the webhook in the repo (Settings → Webhooks) → ${url}/webhook`);
         reg.track("github", "manual"); // always a human step — re-surface it after the registrar output
     }
+    if (plan.channels.includes("slack")) {
+        if (registerSlack) {
+            log("registering slack event URL…");
+            reg.track("slack", await registerSlack(url));
+        }
+        else {
+            log(`slack: set Event Subscriptions → Request URL → ${url}/slack`);
+            reg.track("slack", "manual");
+        }
+    }
     for (const kind of ["feishu", "lark"]) {
-        if (!plan.channels.includes(kind))
+        if (!plan.channels.includes(kind) || plan.longConnectionChannels?.includes(kind))
             continue;
         if (registerFeishu) {
             log(`registering ${kind} event URL…`);

package/dist/deploy/runner.d.ts

@@ -1,8 +1,10 @@
-export interface RunResult {
+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 @@ export 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>;
@@ -19,3 +22,4 @@ export type CliRunner = (args: string[], opts?: {
  * ENOENT (the CLI not on PATH) resolves to code 127 so the caller can gate with an install hint.
  */
 export declare function spawnRunner(bin: string, cwd: string): CliRunner;
+export {};

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/deploy/secrets.d.ts

@@ -17,7 +17,7 @@ export declare function isEnvKey(source: string | undefined): source is string;
  * deployment prerequisites. An OAuth/stored login has no env key here — it carries as
  * `FASTAGENT_AUTH_SEED` on the `--run` path (see each host's run module), not as a named runbook secret.
  */
-export declare function deploymentSecrets(modelAuth: string | undefined, channels: ChannelKind[], extraSecrets?: string[]): {
+export declare function deploymentSecrets(modelAuth: string | undefined, channels: ChannelKind[], extraSecrets?: string[], longConnectionChannels?: string[]): {
     name: string;
     hint: string;
     required: boolean;
@@ -40,6 +40,7 @@ export declare function assembleSecrets(input: {
     modelAuth: string | undefined;
     authFile: Buffer | undefined;
     channels: ChannelKind[];
+    longConnectionChannels?: string[];
     /** Extra secret env-var names from `fastagent.config` deploy.secrets — carried like channel secrets. */
     extraSecrets?: string[];
     env: NodeJS.ProcessEnv;

package/dist/deploy/secrets.js

@@ -19,13 +19,15 @@ export function isEnvKey(source) {
  * deployment prerequisites. An OAuth/stored login has no env key here — it carries as
  * `FASTAGENT_AUTH_SEED` on the `--run` path (see each host's run module), not as a named runbook secret.
  */
-export function deploymentSecrets(modelAuth, channels, extraSecrets = []) {
+export function deploymentSecrets(modelAuth, channels, extraSecrets = [], longConnectionChannels = []) {
     const secrets = [];
     if (isEnvKey(modelAuth))
         secrets.push({ name: modelAuth, hint: "your model provider key", required: true });
     for (const kind of channels) {
-        for (const e of channelSetup(kind).env)
+        const setupMode = longConnectionChannels.includes(kind) ? "websocket" : "webhook";
+        for (const e of channelSetup(kind, setupMode).env) {
             secrets.push({ name: e.name, hint: e.hint, required: e.required });
+        }
     }
     // Dedup: a name already covered by the model key / a channel secret must not appear twice in the runbook.
     for (const name of extraSecrets) {
@@ -67,7 +69,8 @@ export function assembleSecrets(input) {
         needsModelCredential = true; // no env key, no auth.json — `fastagent login` remediation
     }
     for (const kind of input.channels) {
-        for (const e of channelSetup(kind).env) {
+        const setupMode = input.longConnectionChannels?.includes(kind) ? "websocket" : "webhook";
+        for (const e of channelSetup(kind, setupMode).env) {
             const v = input.env[e.name];
             if (v)
                 secrets[e.name] = v; // optional channel values travel when configured
@@ -76,6 +79,23 @@ export function assembleSecrets(input) {
             }
         }
     }
+    // Slack bot-token rotation is an all-or-nothing credential bundle. Its fields remain optional so a
+    // manually configured long-lived token works, but a partial bundle must gate before the container
+    // reaches slackChannel construction.
+    if (input.channels.includes("slack")) {
+        const rotation = [
+            "SLACK_BOT_REFRESH_TOKEN",
+            "SLACK_BOT_TOKEN_EXPIRES_AT",
+            "SLACK_CLIENT_ID",
+            "SLACK_CLIENT_SECRET",
+        ];
+        if (rotation.some((name) => !!input.env[name])) {
+            for (const name of rotation) {
+                if (!input.env[name] && !missingSecrets.includes(name))
+                    missingSecrets.push(name);
+            }
+        }
+    }
     for (const name of input.extraSecrets ?? []) {
         if (name in secrets || missingSecrets.includes(name))
             continue; // already covered by model/channel — no dup

package/dist/dev-supervisor.d.ts

@@ -1,14 +1,15 @@
-/** What the dev watcher restarts on (workspace-relative): the process-bound code inputs only. */
-export declare const WATCHED_HINT = "tools/, channels/, package.json (agent dir), fastagent.config.*, .env (run root)";
+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>;

package/dist/dev-supervisor.js

@@ -1,6 +1,6 @@
 /**
  * The `fastagent dev` process supervisor: re-spawn the CLI as a worker (`FASTAGENT_DEV_WORKER=1`) and
- * restart it on debounced edits to the workspace's CODE inputs. Each restart is a fresh process
+ * restart it on debounced edits to the agent's CODE inputs. Each restart is a fresh process
  * (always-latest, no stale module cache). The supervisor never exits on a bad edit — the worker fails
  * loudly and it waits for the next save.
  *
@@ -13,65 +13,61 @@
 import { spawn } from "node:child_process";
 import { relative, sep } from "node:path";
 import { watch as watchTree } from "chokidar";
-import { loadConfig, resolveAgentDir } from "./engines/pi/config.js";
+import { AGENT_CONFIG_NAMES, resolveStateRoot } from "./paths.js";
+import { isUnderDir } from "./engines/pi/definition.js";
+import { dotEnvPath } from "./env.js";
 import { log } from "./log.js";
 import { installProxyFetch } from "./proxy.js";
 import { openExternalUrl } from "./open-url.js";
 import { announceWebhooks, startCloudflareTunnel } from "./tunnel.js";
-/** What the dev watcher restarts on (workspace-relative): the process-bound code inputs only. */
-export const WATCHED_HINT = "tools/, channels/, package.json (agent dir), fastagent.config.*, .env (run root)";
+/** What the dev watcher restarts on (agent-dir-relative): the process-bound code inputs only. */
+const WATCHED_HINT = "tools/, channels/, schedules/, package.json, fastagent.config.*, .secrets/.env";
 /**
- * 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 function devWatchIgnored(dir, agentDir) {
+export function devWatchIgnored(root, envFile) {
+    // The `.env` is allow-listed by its RESOLVED path, not by the `.secrets` name: FASTAGENT_SECRETS_DIR
+    // can put it in an in-agent directory called anything, and a name-based rule would prune the very
+    // file the worker loads (a credential edit would then silently never restart it).
+    const envRel = relative(root, envFile).split(sep);
     return (path) => {
-        if (path === dir || path === agentDir)
-            return false; // the roots themselves must not be pruned
-        // Never prune a directory on the path from the watch root down to agentDir, so chokidar can descend
-        // into `agentDir/tools` even when agentDir is a subdir (config.agentDir = "./agent").
-        if (agentDir.startsWith(path + sep))
+        if (path === root)
+            return false; // the root itself must not be pruned
+        const rel = relative(root, path);
+        // Code inputs at the agent dir root: config, package.json, and the dirs loaded once per worker
+        // (a restart is their only re-read). Everything else (skills/, persona.md, AGENTS.md) is
+        // live-read — pruned, no restart.
+        // The config NAMES come from paths.ts, not a regex spelled here: adding a name there must not
+        // silently stop `dev` restarting on edits to it.
+        if (AGENT_CONFIG_NAMES.includes(rel))
             return false;
-        const rel = relative(dir, path);
-        // Run-root (cwd) inputs: .env + fastagent.config.* live where config lives, not in agentDir.
-        if (rel === ".env")
+        if (rel === "package.json")
             return false;
-        if (/^fastagent\.config\.[cm]?[jt]s$/.test(rel))
+        const segments = rel.split(sep);
+        if (segments[0] === "tools" || segments[0] === "channels" || segments[0] === "schedules")
+            return false;
+        // The `.env` restarts too (credentials are process-bound). Keep it AND its ancestor directories
+        // un-pruned so chokidar can descend to it; every sibling inside them (auth.json, .env.example)
+        // prunes normally. An out-of-agent `.env` yields a `..`-prefixed envRel that matches nothing here
+        // — the supervisor warns about that case instead of pretending to watch it.
+        if (segments.length <= envRel.length && segments.every((seg, i) => seg === envRel[i]))
             return false;
-        // Agent code inputs live in agentDir: tools/, channels/, schedules/ (loaded once per worker — a
-        // restart is their only re-read), package.json (its own deps). Everything else under agentDir
-        // (skills/, persona.md, AGENTS.md) is live-read — pruned, no restart.
-        const relAgent = relative(agentDir, path);
-        if (!relAgent.startsWith("..")) {
-            const [head] = relAgent.split(sep);
-            if (head === "tools" || head === "channels" || head === "schedules")
-                return false;
-            if (relAgent === "package.json")
-                return false;
-        }
         return true;
     };
 }
-/** Spawn the dev worker and restart it on workspace edits; supervise its lifecycle until the process exits. */
-export async function runDevSupervisor(dir, options = {}) {
-    // The watch root is `dir` (cwd); tools/channels the restart-watch cares about live in agentDir. On a
-    // config error, default agentDir=dir and let the spawned worker surface the real error (fail-visibly).
-    // agentDir is assumed STATIC for the dev session: the supervisor computes it once here and each spawned
-    // worker recomputes its own from the same config — config validation guarantees it stays under `dir`
-    // (so the watch scope is always right); a config edit that changes agentDir mid-session (rare) is out
-    // of scope for watch-scope re-sync (it triggers a worker restart regardless).
-    // A genuine config error (not just a missing agentDir key) — debug-log it here so the silence is not
-    // total before the spawned worker crash-loops and surfaces the real message; default agentDir=dir.
-    const config = await loadConfig(dir)
-        .then((r) => r.config)
-        .catch((err) => {
-        log.debug(`[fastagent] dev: config load failed while resolving agentDir (worker will report): ${String(err)}`);
-        return {};
-    });
-    const agentDir = resolveAgentDir(dir, config);
+/** Spawn the dev worker and restart it on agent-dir edits; supervise its lifecycle until the process exits. */
+export async function runDevSupervisor(placement, options = {}) {
+    // The placement arrives RESOLVED from the command (which already routed its refusal through
+    // failStartup): re-resolving here would duplicate the rule and surface the same user-fixable
+    // refusal as a raw stack. The watch root is the AGENT DIR — every restart-relevant code input lives
+    // under it, so the surrounding workspace costs no watchers at all. Placement is assumed STATIC for
+    // the session (creating/removing `fastagent/` mid-session is out of scope for watch re-sync).
     let worker;
     let reloadPending = false;
     let everServed = false; // has any worker successfully bound (sent `ready`) yet?
@@ -100,7 +96,11 @@ export async function runDevSupervisor(dir, options = {}) {
                 void startCloudflareTunnel(m.port).then((t) => {
                     if (t) {
                         tunnel = t;
-                        void announceWebhooks(agentDir, t.url, { openUrl: openExternalUrl });
+                        void announceWebhooks(placement.agentDir, t.url, {
+                            openUrl: openExternalUrl,
+                            routeChannels: m.routeChannels,
+                            stateRoot: resolveStateRoot(placement.agentDir),
+                        });
                     }
                 });
             }
@@ -137,9 +137,9 @@ export async function runDevSupervisor(dir, options = {}) {
     };
     // chokidar gives reliable cross-platform recursion + structural ignore that native fs.watch
     // cannot; devWatchIgnored (above) narrows the scope to the process-bound code inputs.
-    const watcher = watchTree(dir, {
+    const watcher = watchTree(placement.agentDir, {
         ignoreInitial: true, // the startup scan is not a change
-        ignored: devWatchIgnored(dir, agentDir),
+        ignored: devWatchIgnored(placement.agentDir, dotEnvPath(placement.agentDir)),
     });
     watcher.on("all", () => {
         clearTimeout(timer);
@@ -147,6 +147,12 @@ export async function runDevSupervisor(dir, options = {}) {
     });
     watcher.on("error", (error) => log.warn(`[fastagent] file watching error (${error.message}); some edits may need a manual restart`));
     log.info(`[fastagent] watching ${WATCHED_HINT} — code edits restart the dev worker (--no-watch to disable); AGENTS.md/persona.md/skills edits go live next turn without a restart`);
+    // FASTAGENT_SECRETS_DIR can move the `.env` OUT of the agent dir entirely; the watcher follows it
+    // anywhere inside (the resolved path is allow-listed above), but outside the watch root the worker
+    // would load a file no watcher sees. Say so once instead of leaving the hint above lying.
+    if (!isUnderDir(dotEnvPath(placement.agentDir), placement.agentDir)) {
+        log.warn(`[fastagent] .env lives outside the agent dir (FASTAGENT_SECRETS_DIR → ${dotEnvPath(placement.agentDir)}) — it is NOT watched; restart dev after editing it`);
+    }
     const shutdown = () => {
         worker?.kill("SIGTERM");
         tunnel?.close();

package/dist/engines/pi/auth.d.ts

@@ -1,11 +1,12 @@
 import type { CredentialStore } from "@earendil-works/pi-ai";
 /**
- * The GLOBAL fastagent credentials file (distinct from pi's `~/.pi`). The project-level default is
- * `<dir>/.fastagent/auth.json` (computed by the opener and by `fastagent login`); this is only the
- * `loginFlow()` PROGRAMMATIC fallback (when a caller omits `authPath`) and the path to point
- * `--auth-path`/`FASTAGENT_AUTH_PATH` at to deliberately share ONE credential file across projects
- * (safe — one file, one lock-serialized refresh lifecycle). The `fastagent login` CLI is project-
- * level by default, never this.
+ * The GLOBAL fastagent credentials file (distinct from pi's `~/.pi`), under the user-global machinery
+ * home `~/.fastagent/` — which carries the same unified shape as a workspace (`.secrets/auth.json`).
+ * The project-level default is `<agentDir>/.secrets/auth.json` (computed by the opener and by
+ * `fastagent login`); this is only the `loginFlow()` PROGRAMMATIC fallback (when a caller omits
+ * `authPath`) and the path to point `--auth-path`/`FASTAGENT_AUTH_PATH` at to deliberately share ONE
+ * credential file across projects (safe — one file, one lock-serialized refresh lifecycle). The
+ * `fastagent login` CLI is project-level by default, never this.
  */
 export declare const GLOBAL_AUTH_PATH: string;
 export interface FastagentAuthOptions {
@@ -13,5 +14,5 @@ export interface FastagentAuthOptions {
     warn?: (message: string) => void;
 }
 /** A read-write `CredentialStore` backed by the given credentials file (default {@link GLOBAL_AUTH_PATH};
- *  the directory opener passes the project-level `<dir>/.fastagent/auth.json`). */
+ *  the directory opener passes the project-level `<root>/.secrets/auth.json`). */
 export declare function fastagentCredentialStore(authPath?: string, options?: FastagentAuthOptions): CredentialStore;