@fastagent-sh/fastagent 0.15.0 → 0.16.0

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, resolveStateRoot } 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. */
-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,10 +96,10 @@ export async function runDevSupervisor(dir, options = {}) {
                 void startCloudflareTunnel(m.port).then((t) => {
                     if (t) {
                         tunnel = t;
-                        void announceWebhooks(dir, t.url, {
+                        void announceWebhooks(placement.agentDir, t.url, {
                             openUrl: openExternalUrl,
                             routeChannels: m.routeChannels,
-                            stateRoot: resolveStateRoot(dir),
+                            stateRoot: resolveStateRoot(placement.agentDir),
                         });
                     }
                 });
@@ -141,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);
@@ -151,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;

package/dist/engines/pi/auth.js

@@ -1,8 +1,8 @@
 /**
  * Auth for the pi engine: a read-WRITE {@link CredentialStore} over a fastagent credentials file,
  * consumed by the `Models` collection (models.ts). The path is project-level by default
- * (`<dir>/.fastagent/auth.json`, resolved by the opener); {@link GLOBAL_AUTH_PATH} is the global
- * location used as the override target / login default, not an implicit per-provider fallback.
+ * (`<agentDir>/.secrets/auth.json`, resolved by the opener); {@link GLOBAL_AUTH_PATH} is the
+ * global location used as the override target / login default, not an implicit per-provider fallback.
  *
  * Project-level default + NO implicit project↔global fallback, for two reasons: (1) isolation — each
  * agent can use a different account/subscription; (2) fail-visibly — a missing credential surfaces at
@@ -27,18 +27,20 @@
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { GLOBAL_HOME_DIR, SECRETS_DIRNAME } from "../../paths.js";
 import { log } from "../../log.js";
 import { setTimeout as sleep } from "node:timers/promises";
 import lockfile from "proper-lockfile";
 /**
- * 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 const GLOBAL_AUTH_PATH = join(homedir(), ".fastagent", "auth.json");
+export const GLOBAL_AUTH_PATH = join(homedir(), GLOBAL_HOME_DIR, SECRETS_DIRNAME, "auth.json");
 /** A valid stored credential, or undefined — a foreign/old entry reads as not-configured, not a crash. */
 function pick(creds, providerId) {
     const cred = creds[providerId];
@@ -183,7 +185,7 @@ function parseForWrite(raw, where) {
     return creds;
 }
 /** 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 function fastagentCredentialStore(authPath = GLOBAL_AUTH_PATH, options = {}) {
     const warn = options.warn ?? ((message) => log.warn(message));
     return {

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

@@ -23,7 +23,7 @@ export declare function inspectChannels(dir: string): Promise<{
 }>;
 /**
  * Channel file basenames under `<dir>/channels/` — the authoring view (`fastagent info`), which lists
- * WITHOUT importing. A symlinked channels directory must remain inside the workspace.
+ * WITHOUT importing. A symlinked channels directory must remain inside the agent dir.
  */
 export declare function discoverChannelFiles(dir: string): Promise<string[]>;
 /** Discover, validate, and bind all channel modules. No long connection is opened here; the CLI owns it. */

package/dist/engines/pi/channel.js

@@ -6,7 +6,7 @@ import { readdir } from "node:fs/promises";
 import { isAbsolute, join } from "node:path";
 import { parseRouteKey, } from "../../host/node.js";
 import { isModuleFile, loadModuleDir } from "../../loader.js";
-import { assertInsideWorkspace } from "../../workspace.js";
+import { assertInsideAgentDir } from "../../paths.js";
 function longConnectionModule(value) {
     return value !== null && typeof value === "object" && typeof value.connect === "function";
 }
@@ -21,7 +21,7 @@ function validateLongConnectionModule(value, label) {
  * long-connection channels. There is no second ingress/lifecycle declaration to keep in sync.
  */
 export async function inspectChannels(dir) {
-    await assertInsideWorkspace(dir, "channels");
+    await assertInsideAgentDir(dir, "channels");
     const { modules, failures } = await loadModuleDir(join(dir, "channels"));
     const channels = [];
     const routeChannels = [];
@@ -49,10 +49,10 @@ export async function inspectChannels(dir) {
 }
 /**
  * Channel file basenames under `<dir>/channels/` — the authoring view (`fastagent info`), which lists
- * WITHOUT importing. A symlinked channels directory must remain inside the workspace.
+ * WITHOUT importing. A symlinked channels directory must remain inside the agent dir.
  */
 export async function discoverChannelFiles(dir) {
-    await assertInsideWorkspace(dir, "channels");
+    await assertInsideAgentDir(dir, "channels");
     let names;
     try {
         names = await readdir(join(dir, "channels"));
@@ -90,7 +90,7 @@ export async function loadChannels(dir, ctx) {
     if (!isAbsolute(ctx.stateRoot)) {
         throw new Error(`ChannelContext.stateRoot must be absolute, got "${ctx.stateRoot}"`);
     }
-    await assertInsideWorkspace(dir, "channels");
+    await assertInsideAgentDir(dir, "channels");
     const { modules, failures } = await loadModuleDir(join(dir, "channels"));
     const routes = {};
     const longConnections = [];

package/dist/engines/pi/chat.js

@@ -8,13 +8,13 @@
  * pi's TUI `/login`, which writes through the same credential store into the workspace auth file).
  */
 import { InteractiveMode } from "@earendil-works/pi-coding-agent";
-import { buildWorkspaceSessionRuntime } from "./session-builder.js";
+import { buildAgentSessionRuntime } from "./session-builder.js";
 /**
  * Open the workspace's agent in pi's interactive TUI and run until the user exits. The agent is
  * fastagent's assembled agent (same model/tools/skills/prompt/auth as dev/start serve); pi's TUI
  * handles login, rendering, and same-workspace sessions natively.
  */
 export async function runPiChat(dir, options = {}) {
-    const runtime = await buildWorkspaceSessionRuntime(dir, options);
+    const runtime = await buildAgentSessionRuntime(dir, options);
     await new InteractiveMode(runtime, {}).run();
 }

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

@@ -9,14 +9,6 @@ export interface FastagentConfig {
      *  "xhigh" | "max"). Unset = pi's default. Authors tune thinking in the pi TUI while vibing — this
      *  is the serving-side counterpart (fidelity). Levels a model doesn't support are clamped by pi. */
     thinkingLevel?: ThinkingLevel;
-    /**
-     * The agent-definition subdirectory (persona.md, skills/, tools/, channels/), relative to the config
-     * file's directory. Default: the config directory itself (flat — today's behaviour). Point it at a
-     * sibling like `"./agent"` to serve an existing repo as a coding agent: the config dir stays the run
-     * root (cwd, whose AGENTS.md the agent reads as ② context), while the agent's own surface lives in the
-     * subdir and does not collide with the host's `tools/`/`src/` (core.md scenario grid).
-     */
-    agentDir?: string;
     /** Extra custom tools, appended after pi defaults — never replaces them. `FastagentTool` = AgentTool
      *  plus the optional `deferred` marker (see defineTool). */
     tools?: FastagentTool[];
@@ -53,24 +45,13 @@ export interface FastagentConfig {
 export declare function defineConfig(config: FastagentConfig): FastagentConfig;
 export interface LoadedConfig {
     config: FastagentConfig;
-    /** Config file path; undefined when running zero-config. */
+    /** Config file path; undefined when the loader was pointed at a directory holding none. */
     path?: string;
 }
 /** A valid bindable port. */
 export declare function isValidPort(n: number): boolean;
-/** The config filenames that make a directory a fastagent workspace, in load precedence. ONE source: the
- *  loader (below) and `scaffoldWorkspace`'s already-a-workspace refusal both read this, so "is there a
- *  config?" can't diverge between them when the set changes. */
-export declare const WORKSPACE_CONFIG_NAMES: readonly ["fastagent.config.ts", "fastagent.config.js", "fastagent.config.mjs"];
-/** Load `<dir>/fastagent.config.ts|.js|.mjs`. No file = zero-config; a wrong-shape file throws. */
+/** Load `<dir>/fastagent.config.ts|.js|.mjs`. No file = defaults; a wrong-shape file throws. */
 export declare function loadConfig(dir: string): Promise<LoadedConfig>;
-/**
- * The agent-definition dir from config: `config.agentDir` resolved against `dir`, or `dir` itself when
- * unset (flat). The ONE place this is computed — every opener (`dev`/`start`/`info`/`tool`/`deploy`/`chat`)
- * calls it, so the "relative to the config dir, default `.`" rule can never diverge. loadConfig has
- * already validated that agentDir stays under `dir`.
- */
-export declare function resolveAgentDir(dir: string, config: FastagentConfig): string;
 /** The provider prefix of a "provider/modelId" spec. A spec without "/" returns whole — downstream
  *  lookups then miss visibly (an unknown-provider error / a login-required hint), never a mangled id
  *  (`slice(0, indexOf("/"))` silently drops the last char when "/" is absent). */
@@ -82,7 +63,7 @@ export declare function listModels(models: Models): string[];
 /**
  * Rewrite the `model` in a config file's SOURCE TEXT to `spec`, for the first-run picker's write-back.
  * Handles the scaffold's commented placeholder (`// model: "…"`) and an existing `model:` line; returns
- * null when neither is present (zero-config or a hand-shaped config) so the caller falls back to a
+ * null when neither is present (no config file, or a hand-shaped one) so the caller falls back to a
  * printed hint instead of guessing where to insert. Text-level (not AST) on purpose — it only ever
  * touches a line it recognizes, never reformats the author's file.
  */
@@ -95,30 +76,9 @@ export declare function resolveModelSpec(flag: string | undefined, config: Fasta
  * Resolved to absolute so the store and the startup report agree regardless of cwd.
  */
 export declare function resolveSessionsDirOverride(flag: string | undefined, env?: NodeJS.ProcessEnv): string | undefined;
-/**
- * The auth-file override: `--auth-path` flag > `FASTAGENT_AUTH_PATH` env > undefined (the opener then
- * falls back to {@link defaultAuthPath} under the {@link resolveStateRoot} root). Resolved to absolute
- * so the store and the startup report agree regardless of cwd. No implicit project↔global fallback (isolation
- * + fail-visibly; see auth.ts); to share one account across projects, point this at the global
- * `~/.fastagent/auth.json` — sharing ONE file is safe under the store's cross-process refresh lock.
- */
-export declare function resolveAuthPathOverride(flag: string | undefined, env?: NodeJS.ProcessEnv): string | undefined;
-/**
- * The resolved state root — the ONE durable machine-state home everything derives from (auth.json,
- * sessions/, channels/<kind>/): `FASTAGENT_STATE_DIR` env > `<dir>/.fastagent`. Absolute, so channels
- * and the startup report agree regardless of cwd. Definition: single lifecycle (precious, survives
- * redeploy), single process — a container mounts ONE volume here. The finer knobs
- * (`FASTAGENT_SESSIONS_DIR`, `FASTAGENT_AUTH_PATH`) still override their specific path on top.
- *
- * `FASTAGENT_STATE_DIR` is an OPERATOR override, so a relative value resolves against `process.cwd()`
- * — the CLI convention its sibling knobs share (`resolveOverridePath`), NOT against `dir`. Only the
- * DEFAULT (`<dir>/.fastagent`) is dir-anchored. Deployments set an absolute path (a mounted volume);
- * a relative value is in-tree — hence self-ignored — only when run from the definition dir (cwd == dir).
- */
-export declare function resolveStateRoot(dir: string, env?: NodeJS.ProcessEnv): string;
-/** The default credentials file under a resolved state root ({@link resolveStateRoot}). */
-export declare function defaultAuthPath(stateRoot: string): string;
-/** The effective auth file for a workspace: override if present, else the project-level auth.json. */
+/** The default credentials file under a resolved secrets dir ({@link resolveSecretsDir}). */
+export declare function defaultAuthPath(secretsDir: string): string;
+/** The effective auth file for an agent: override if present, else `<secrets dir>/auth.json`. */
 export declare function resolveAuthPath(dir: string, flag: string | undefined, env?: NodeJS.ProcessEnv): string;
 /** The default sessions dir under a resolved state root ({@link resolveStateRoot}). */
 export declare function defaultSessionsDir(stateRoot: string): string;

package/dist/engines/pi/config.js

@@ -11,15 +11,18 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
  * (resolveModel, resolveModelSpec). One concern: everything about fastagent.config.ts.
  *
  * Red line: config describes deployment/runtime choices, never authored identity or expertise (those
- * live in persona.md + skills, with AGENTS.md as project context). Deleting the config still leaves a
- * zero-config agent runnable with a model supplied by --model / FASTAGENT_MODEL.
+ * live in persona.md + skills, with AGENTS.md as project context). It has no say in PLACEMENT either —
+ * that rule lives in the neutral src/paths.ts — but its FILE is what marks a directory as an agent, so a
+ * served agent always has one (its contents may be `export default {}`; a model can still come from
+ * --model / FASTAGENT_MODEL). The loader below stays tolerant of a missing file because it is a loader:
+ * callers that have not resolved a placement (deploy inspection, tests) may point it anywhere.
  */
-import { existsSync, lstatSync, realpathSync, statSync } from "node:fs";
-import { homedir } from "node:os";
-import { basename, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { existsSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { THINKING_LEVELS } from "./harness.js";
 import { moduleLoadHint } from "../../loader.js";
+import { AGENT_CONFIG_NAMES, resolveOverridePath, resolveSecretsDir } from "../../paths.js";
 /** Identity function for typing and IDE completion (vite/next-style). */
 export function defineConfig(config) {
     return config;
@@ -41,13 +44,9 @@ function validateStringList(value, key, shape, desc, path) {
         }
     }
 }
-/** The config filenames that make a directory a fastagent workspace, in load precedence. ONE source: the
- *  loader (below) and `scaffoldWorkspace`'s already-a-workspace refusal both read this, so "is there a
- *  config?" can't diverge between them when the set changes. */
-export const WORKSPACE_CONFIG_NAMES = ["fastagent.config.ts", "fastagent.config.js", "fastagent.config.mjs"];
-/** Load `<dir>/fastagent.config.ts|.js|.mjs`. No file = zero-config; a wrong-shape file throws. */
+/** Load `<dir>/fastagent.config.ts|.js|.mjs`. No file = defaults; a wrong-shape file throws. */
 export async function loadConfig(dir) {
-    const found = WORKSPACE_CONFIG_NAMES.map((name) => join(dir, name)).filter((path) => existsSync(path));
+    const found = AGENT_CONFIG_NAMES.map((name) => join(dir, name)).filter((path) => existsSync(path));
     if (found.length === 0)
         return { config: {} };
     if (found.length > 1) {
@@ -75,17 +74,16 @@ export async function loadConfig(dir) {
     }
     const c = config;
     // Unknown keys throw: defineConfig only type-protects .ts authors; a typo in a .js/.mjs config
-    // (`modle:`) must not silently degrade to zero-config.
+    // (`modle:`) must not silently degrade to defaults.
     for (const key of Object.keys(c)) {
         if (key !== "model" &&
             key !== "thinkingLevel" &&
-            key !== "agentDir" &&
             key !== "tools" &&
             key !== "http" &&
             key !== "deploy" &&
             key !== "selfSchedule" &&
             key !== "sessionControl") {
-            throw new Error(`${path}: unknown key "${key}" (valid keys: model, thinkingLevel, agentDir, tools, http, deploy, selfSchedule, sessionControl)`);
+            throw new Error(`${path}: unknown key "${key}" (valid keys: model, thinkingLevel, tools, http, deploy, selfSchedule, sessionControl)`);
         }
     }
     if (c.model !== undefined && typeof c.model !== "string") {
@@ -97,47 +95,6 @@ export async function loadConfig(dir) {
     if (c.thinkingLevel !== undefined && !THINKING_LEVELS.has(c.thinkingLevel)) {
         throw new Error(`${path}: "thinkingLevel" must be one of ${[...THINKING_LEVELS].join(", ")}`);
     }
-    if (c.agentDir !== undefined && typeof c.agentDir !== "string") {
-        throw new Error(`${path}: "agentDir" must be a string (a subdirectory relative to the config file)`);
-    }
-    if (typeof c.agentDir === "string") {
-        // Enforce the documented "subdirectory of the config dir" contract: an escaping agentDir (e.g.
-        // "../shared") would still resolve for tool/channel/persona discovery, but `dev`'s chokidar only
-        // watches the config dir subtree — edits outside it would silently never trigger a restart. Reject
-        // it here (fail visibly) rather than let hot-reload break without a signal.
-        const rel = relative(dir, resolve(dir, c.agentDir));
-        if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
-            throw new Error(`${path}: "agentDir" ("${c.agentDir}") must be a subdirectory of the config directory, not escape it`);
-        }
-        // An explicitly declared agentDir that doesn't exist is a typo until proven otherwise ("./agnet"):
-        // without this check every opener would assemble an EMPTY agent (no persona, no skills, no tools)
-        // with zero errors — the worst silent failure this config can produce. Deliberately NOT auto-created:
-        // config load is read-only (no implicit operations), and a mkdir would turn the typo into a served
-        // empty agent plus a junk directory.
-        // lstat, not stat: a symlink would pass the literal containment check above while its TARGET lives
-        // outside the config dir — exactly what that check exists to prevent (dev's watch would silently
-        // never see edits). Same rule as init's parent preflight: reject, don't follow.
-        const agentDirAbs = resolve(dir, c.agentDir);
-        const st = lstatSync(agentDirAbs, { throwIfNoEntry: false });
-        if (!st) {
-            throw new Error(`${path}: "agentDir" ("${c.agentDir}") does not exist — create it, or fix the path`);
-        }
-        if (st.isSymbolicLink()) {
-            // Separate message: to its user a symlink LOOKS like a working directory — name the reason and the fix.
-            throw new Error(`${path}: "agentDir" ("${c.agentDir}") is a symlink — not allowed (its target can live outside the ` +
-                `config directory, where dev's watch would never see edits); use a real directory, or point agentDir at the target's real path`);
-        }
-        if (!st.isDirectory()) {
-            throw new Error(`${path}: "agentDir" ("${c.agentDir}") is not a directory`);
-        }
-        // The leaf lstat can't see a symlinked INTERMEDIATE segment (agentDir "./a/b" with `a` → outside):
-        // realpath equality covers every segment under the config dir in one comparison. dir itself is
-        // realpath'd on both sides, so a symlinked config-dir path (macOS /tmp) stays legal.
-        if (realpathSync(agentDirAbs) !== resolve(realpathSync(dir), relative(dir, agentDirAbs))) {
-            throw new Error(`${path}: "agentDir" ("${c.agentDir}") resolves through a symlink — not allowed (the target can ` +
-                `live outside the config directory, where dev's watch would never see edits); use the real path`);
-        }
-    }
     if (c.selfSchedule !== undefined && typeof c.selfSchedule !== "boolean") {
         throw new Error(`${path}: "selfSchedule" must be a boolean`);
     }
@@ -181,15 +138,6 @@ export async function loadConfig(dir) {
     validateStringList(c.deploy?.apt, "deploy.apt", /^[a-z0-9][a-z0-9.+-]*$/, "a Debian package name", path);
     return { config: c, path };
 }
-/**
- * The agent-definition dir from config: `config.agentDir` resolved against `dir`, or `dir` itself when
- * unset (flat). The ONE place this is computed — every opener (`dev`/`start`/`info`/`tool`/`deploy`/`chat`)
- * calls it, so the "relative to the config dir, default `.`" rule can never diverge. loadConfig has
- * already validated that agentDir stays under `dir`.
- */
-export function resolveAgentDir(dir, config) {
-    return resolve(dir, config.agentDir ?? ".");
-}
 /** The provider prefix of a "provider/modelId" spec. A spec without "/" returns whole — downstream
  *  lookups then miss visibly (an unknown-provider error / a login-required hint), never a mangled id
  *  (`slice(0, indexOf("/"))` silently drops the last char when "/" is absent). */
@@ -223,7 +171,7 @@ export function listModels(models) {
 /**
  * Rewrite the `model` in a config file's SOURCE TEXT to `spec`, for the first-run picker's write-back.
  * Handles the scaffold's commented placeholder (`// model: "…"`) and an existing `model:` line; returns
- * null when neither is present (zero-config or a hand-shaped config) so the caller falls back to a
+ * null when neither is present (no config file, or a hand-shaped one) so the caller falls back to a
  * printed hint instead of guessing where to insert. Text-level (not AST) on purpose — it only ever
  * touches a line it recognizes, never reformats the author's file.
  */
@@ -248,19 +196,6 @@ export function rewriteConfigModel(src, spec) {
 export function resolveModelSpec(flag, config, env = process.env) {
     return flag ?? env.FASTAGENT_MODEL ?? config.model;
 }
-/**
- * Resolve a user-supplied path override (a CLI flag or an env var) to an absolute path, expanding a
- * leading `~`/`~/` to the home dir FIRST. Path-valued config from `.env` (or any non-shell source)
- * never gets the shell's `~` expansion, so a bare `resolve("~/x")` would silently create a literal `~`
- * directory — a fail-silently footgun for a secret/state path. Expanding here makes `~` mean home
- * everywhere these knobs are read.
- */
-function resolveOverridePath(raw) {
-    if (!raw)
-        return undefined;
-    const expanded = raw === "~" ? homedir() : raw.startsWith("~/") ? join(homedir(), raw.slice(2)) : raw;
-    return resolve(expanded);
-}
 /**
  * `start`'s sessions-dir override: `--sessions-dir` flag > `FASTAGENT_SESSIONS_DIR` env > undefined
  * (the opener then falls back to {@link defaultSessionsDir} under the {@link resolveStateRoot} root).
@@ -271,43 +206,21 @@ export function resolveSessionsDirOverride(flag, env = process.env) {
 }
 /**
  * The auth-file override: `--auth-path` flag > `FASTAGENT_AUTH_PATH` env > undefined (the opener then
- * falls back to {@link defaultAuthPath} under the {@link resolveStateRoot} root). Resolved to absolute
+ * falls back to {@link defaultAuthPath} under the {@link resolveSecretsDir} dir). Resolved to absolute
  * so the store and the startup report agree regardless of cwd. No implicit project↔global fallback (isolation
  * + fail-visibly; see auth.ts); to share one account across projects, point this at the global
- * `~/.fastagent/auth.json` — sharing ONE file is safe under the store's cross-process refresh lock.
+ * `~/.fastagent/.secrets/auth.json` — sharing ONE file is safe under the store's cross-process refresh lock.
  */
-export function resolveAuthPathOverride(flag, env = process.env) {
+function resolveAuthPathOverride(flag, env = process.env) {
     return resolveOverridePath(flag ?? env.FASTAGENT_AUTH_PATH);
 }
-/**
- * The IN-TREE default state root, `<dir>/.fastagent` — what {@link resolveStateRoot} falls back to when
- * `FASTAGENT_STATE_DIR` moves state nowhere. THE single definition of that path segment.
- */
-function projectStateDir(dir) {
-    return join(dir, ".fastagent");
-}
-/**
- * The resolved state root — the ONE durable machine-state home everything derives from (auth.json,
- * sessions/, channels/<kind>/): `FASTAGENT_STATE_DIR` env > `<dir>/.fastagent`. Absolute, so channels
- * and the startup report agree regardless of cwd. Definition: single lifecycle (precious, survives
- * redeploy), single process — a container mounts ONE volume here. The finer knobs
- * (`FASTAGENT_SESSIONS_DIR`, `FASTAGENT_AUTH_PATH`) still override their specific path on top.
- *
- * `FASTAGENT_STATE_DIR` is an OPERATOR override, so a relative value resolves against `process.cwd()`
- * — the CLI convention its sibling knobs share (`resolveOverridePath`), NOT against `dir`. Only the
- * DEFAULT (`<dir>/.fastagent`) is dir-anchored. Deployments set an absolute path (a mounted volume);
- * a relative value is in-tree — hence self-ignored — only when run from the definition dir (cwd == dir).
- */
-export function resolveStateRoot(dir, env = process.env) {
-    return resolveOverridePath(env.FASTAGENT_STATE_DIR) ?? resolve(projectStateDir(dir));
-}
-/** The default credentials file under a resolved state root ({@link resolveStateRoot}). */
-export function defaultAuthPath(stateRoot) {
-    return join(stateRoot, "auth.json");
+/** The default credentials file under a resolved secrets dir ({@link resolveSecretsDir}). */
+export function defaultAuthPath(secretsDir) {
+    return join(secretsDir, "auth.json");
 }
-/** The effective auth file for a workspace: override if present, else the project-level auth.json. */
+/** The effective auth file for an agent: override if present, else `<secrets dir>/auth.json`. */
 export function resolveAuthPath(dir, flag, env = process.env) {
-    return resolveAuthPathOverride(flag, env) ?? defaultAuthPath(resolveStateRoot(dir, env));
+    return resolveAuthPathOverride(flag, env) ?? defaultAuthPath(resolveSecretsDir(dir, env));
 }
 /** The default sessions dir under a resolved state root ({@link resolveStateRoot}). */
 export function defaultSessionsDir(stateRoot) {