@fastagent-sh/fastagent 0.21.0 → 0.22.0

package/dist/engines/pi/auth.js

@@ -1,48 +1,18 @@
 /**
- * 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
- * (`<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
- * startup instead of being masked by a machine-global one that won't exist on a fresh deploy box. A
- * *fallback* specifically is refused because the only safe shape (read global, write the rotated token
- * back to the project file) would diverge: OAuth refresh tokens are single-use, so consuming global's
- * token and persisting the new one elsewhere leaves global stale for every other consumer.
- *
- * Sharing is still SAFE the right way: point everything at ONE file (`FASTAGENT_AUTH_PATH` → the
- * global path). One file means one refresh lifecycle under the store's cross-process write lock
- * (refresh re-reads the latest token under the lock), the documented same-machine pattern.
- * fastagent's store stays SEPARATE from the pi CLI's `~/.pi/agent/auth.json` for the same single-
- * lifecycle reason: two uncoordinated files over one grant would each rotate and break the other.
- *
- * Locking is vendored here on `proper-lockfile`, with the same parameters pi's file backend used
- * before pi 0.80.8 stopped exporting it (upstream's stated migration path for SDK consumers is a
- * custom pi-ai `CredentialStore`, which this file is). The lock guards the WRITE path only. `read`
- * is pi-ai's per-request hot path, so it stays UNLOCKED — safe because every write that carries a
- * CREDENTIAL publishes by rename ({@link writeFileAtomic}): a reader sees one whole version of the
- * file or another, never a partial one, so a rotation has no torn-read window for an unlocked read
- * to absorb. The one in-place write left is the `{}` bootstrap below, whose window an unlocked read
- * observes as an empty file — reported as corrupt, which for a zero-byte auth.json is the right
- * answer either way. The write path refuses to overwrite a corrupt file (never clobbering other
- * providers' credentials).
+ * Auth for the pi engine: a read-WRITE {@link CredentialStore} over a fastagent credentials file, consumed by the
+ * `Models` collection (models.ts). The write path refuses to overwrite a corrupt file, so a torn read never clobbers
+ * the other providers' credentials.
  */
-import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, realpathSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-import { GLOBAL_HOME_DIR, SECRETS_DIRNAME, SECRET_FILE_MODE, ensureSecretsDir } from "../../paths.js";
+import { dirname, join, resolve } from "node:path";
+import { GLOBAL_HOME_DIR, SECRETS_DIRNAME, SECRET_FILE_MODE } from "../../paths.js";
 import { writeFileAtomic } from "../../atomic-write.js";
 import { log } from "../../log.js";
 import lockfile from "proper-lockfile";
 /**
- * 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.
+ * The GLOBAL fastagent credentials file (distinct from pi's `~/.pi`), under the user-global machinery home
+ * `~/.fastagent/`.
  */
 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. */
@@ -52,27 +22,33 @@ function pick(creds, providerId) {
 }
 const AUTH_FILE_WRITE_OPTIONS = { encoding: "utf8", mode: SECRET_FILE_MODE };
 /**
- * Serialized cross-process read-modify-write of the credentials file: exponential-backoff retries,
- * 30s staleness, and compromise detection (the parameters pi's `FileAuthStorageBackend` used).
- * Ensures the file exists first (0700 dir, 0600 file, EXCLUSIVE create: a concurrent first write
- * must never be clobbered by the init) because `proper-lockfile` locks an existing path. A
- * compromised lock aborts before the write rather than clobbering a concurrent writer, and a
- * failed unlock after a successful operation rejects instead of leaving a stale lock silently.
+ * The file a write must land IN, which is not always the path it is addressed BY. pi writes the auth file in place,
+ * so it follows a symlink to the target; an atomic rename would replace the link with a regular file instead, and
+ * from then on the two tools would be editing different files — the same split the shared lock exists to prevent,
+ * arriving one write later. A dangling link (a dotfile manager that has not checked the target out yet) still names
+ * where the credentials belong, so it is followed too rather than overwritten.
  */
+function writeTarget(authPath) {
+    if (existsSync(authPath))
+        return realpathSync(authPath);
+    const link = lstatSync(authPath, { throwIfNoEntry: false });
+    // ponytail: one hop. A chain of dangling links would have its second link replaced; resolve iteratively if that
+    // ever shows up in a real layout.
+    return link?.isSymbolicLink() ? resolve(dirname(authPath), readlinkSync(authPath)) : authPath;
+}
+/** Serialized cross-process read-modify-write of the credentials file. */
 async function withLockedAuthFile(authPath, fn) {
-    // 0700 unconditionally, including on a directory an operator named with `--auth-path`: pointing a
-    // credential file somewhere is asking for that somewhere to hold a credential. Where the process
-    // cannot chmod (a mount it does not own), this raises — the write fails visibly instead of
-    // quietly leaving the directory readable, which is the trade this repo takes everywhere else.
-    await ensureSecretsDir(dirname(authPath));
+    mkdirSync(dirname(authPath), { recursive: true });
     if (!existsSync(authPath)) {
         try {
+            // `wx` makes this an exclusive CREATE, which is the one case `writeFileSync` honours `mode` in — so no chmod
+            // after it (unlike writeFileAtomic, whose temp may already exist from a crashed writer).
             writeFileSync(authPath, "{}", { ...AUTH_FILE_WRITE_OPTIONS, flag: "wx" });
-            chmodSync(authPath, SECRET_FILE_MODE);
         }
         catch (error) {
-            // EEXIST: another process created the file between the existence check and this exclusive
-            // create; its content (possibly already-written credentials) must not be clobbered.
+            // EEXIST: the path IS taken, by something `existsSync` does not see through — either another process created
+            // the file just now (its credentials must not be clobbered) or the path is a dangling symlink. Both are left
+            // alone: the write below resolves where they belong.
             if (error.code !== "EEXIST")
                 throw error;
         }
@@ -83,6 +59,12 @@ async function withLockedAuthFile(authPath, fn) {
             throw compromised;
     };
     const release = await lockfile.lock(authPath, {
+        // MUST match pi-coding-agent's `core/auth-storage.js`, which locks with `realpath: false`. When the auth file
+        // itself is a symlink (dotfile managers do this), the two settings name DIFFERENT lock files and both locks can
+        // be held at once — so `pi` and `fastagent` would refresh the same provider concurrently, and a rotated refresh
+        // token logs one of them out. Resolving the link would be the stronger rule, but only if BOTH sides did it, and
+        // we do not own the other side.
+        realpath: false,
         retries: { retries: 10, factor: 2, minTimeout: 100, maxTimeout: 10_000, randomize: true },
         stale: 30_000,
         onCompromised: (error) => {
@@ -95,12 +77,11 @@ async function withLockedAuthFile(authPath, fn) {
         const current = existsSync(authPath) ? readFileSync(authPath, "utf8") : undefined;
         const out = await fn(current);
         throwIfCompromised();
-        // Rename, not an in-place rewrite: it is what lets `read` stay unlocked, and it is the only
-        // spelling that applies the mode before the content is reachable — `writeFileSync`'s `mode` is
-        // a no-op on an existing file, so a chmod after it leaves the new credential briefly readable
-        // at whatever mode the old file carried.
-        if (out.next !== undefined)
-            writeFileAtomic(authPath, out.next, SECRET_FILE_MODE);
+        // Rename, not an in-place rewrite: it is what lets `read` stay unlocked, and it is the only spelling that applies
+        // the mode before the content is reachable.
+        if (out.next !== undefined) {
+            writeFileAtomic(writeTarget(authPath), out.next, SECRET_FILE_MODE);
+        }
         throwIfCompromised();
         result = out.result;
     }
@@ -114,10 +95,8 @@ async function withLockedAuthFile(authPath, fn) {
         }
         throw error;
     }
-    // Success path: a failed release is a real cleanup failure (the leftover auth.json.lock stalls
-    // the next writer for the staleness window with zero diagnostics), so it surfaces instead of
-    // resolving a silently degraded operation. A compromise detected after the last in-band check
-    // surfaces here too.
+    // Success path: a failed release is a real cleanup failure (the leftover auth.json.lock stalls the next writer for
+    // the staleness window with zero diagnostics), so it surfaces instead of resolving a silently degraded operation.
     try {
         await release();
     }
@@ -128,12 +107,7 @@ async function withLockedAuthFile(authPath, fn) {
     throwIfCompromised();
     return result;
 }
-/**
- * Decode the credentials JSON, shared by the read and write paths. The root must be a plain
- * non-null, non-array object: `[]`, `null`, and scalar roots pass JSON.parse but break the record
- * semantics (an array root even swallows writes, since JSON.stringify drops string keys on arrays).
- * Structurally invalid = corrupt, exactly like unparsable text.
- */
+/** Decode the credentials JSON, shared by the read and write paths. */
 function decodeCreds(raw) {
     let parsed;
     try {
@@ -146,13 +120,7 @@ function decodeCreds(raw) {
         return undefined;
     return parsed;
 }
-/**
- * UNLOCKED read of the whole credentials file, shared by `read` and `list`. ONE read: the write
- * publishes by rename, so this observes one whole version or another and has nothing to absorb by
- * re-reading. A missing file reads as undefined silently (normal not-configured); anything that
- * does not decode is a real corruption — a hand-edit — and says so immediately, rather than after
- * retrying a race that cannot happen.
- */
+/** UNLOCKED read of the whole credentials file, shared by `read` and `list`. */
 function readCreds(authPath, warn) {
     let raw;
     try {
@@ -171,9 +139,8 @@ function readCreds(authPath, warn) {
     return undefined;
 }
 /**
- * Parse the credentials JSON for a WRITE: a corrupt file must THROW, because serializing `{}` over
- * it would wipe every other provider's credentials. The throw aborts the locked write, leaving the
- * file intact.
+ * Parse the credentials JSON for a WRITE: a corrupt file must THROW, because serializing `{}` over it would wipe every
+ * other provider's credentials.
  */
 function parseForWrite(raw, where) {
     if (!raw)
@@ -184,32 +151,61 @@ 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 `<root>/.secrets/auth.json`). */
+/**
+ * A read-write `CredentialStore` over the given credentials file (default {@link GLOBAL_AUTH_PATH}; the directory
+ * opener passes the project-level `<root>/.secrets/auth.json`), optionally falling back to a second file.
+ *
+ * The fallback is PER PROVIDER, not per file: logging one provider into a project must not hide the others a person
+ * already has globally. And the layer a credential was READ from is the layer its refresh is written back to —
+ * anything else would conjure a second holder of the same OAuth grant, which is the failure this whole area exists
+ * to avoid. A provider present in neither layer is new, and new credentials belong to the primary.
+ */
 export function fastagentCredentialStore(authPath = GLOBAL_AUTH_PATH, options = {}) {
     const warn = options.warn ?? ((message) => log.warn(message));
+    const fallback = options.fallbackPath !== undefined && options.fallbackPath !== authPath ? options.fallbackPath : undefined;
+    /**
+     * The file that owns this provider: where it already is, else the primary.
+     *
+     * Known ceiling: this read is UNLOCKED, so a concurrent `fastagent login` writing the same provider into the
+     * primary between here and the lock below sends this refresh to the fallback instead — the one window in which the
+     * "one grant, one copy" rule can be lost. Re-checking under the lock means locking both files in a fixed order;
+     * worth it only if concurrent logins stop being a rounding error.
+     */
+    const owner = (providerId) => {
+        if (fallback === undefined)
+            return authPath;
+        const primary = readCreds(authPath, warn);
+        if (primary && pick(primary, providerId))
+            return authPath;
+        const secondary = readCreds(fallback, warn);
+        return secondary && pick(secondary, providerId) ? fallback : authPath;
+    };
     return {
         async read(providerId) {
-            const creds = readCreds(authPath, warn);
-            return creds ? pick(creds, providerId) : undefined;
+            for (const path of fallback === undefined ? [authPath] : [authPath, fallback]) {
+                const creds = readCreds(path, warn);
+                const found = creds && pick(creds, providerId);
+                if (found)
+                    return found;
+            }
+            return undefined;
         },
         async list() {
-            // Metadata only, never secrets (the pi-ai `list` contract). Foreign/old entries are filtered
-            // with the same validation as `read`, so both surfaces agree on what "configured" means.
-            const creds = readCreds(authPath, warn);
-            if (!creds)
-                return [];
-            const infos = [];
-            for (const [providerId, cred] of Object.entries(creds)) {
-                if (cred && (cred.type === "oauth" || cred.type === "api_key")) {
-                    infos.push({ providerId, type: cred.type });
+            // Metadata only, never secrets (the pi-ai `list` contract). Reverse order, so the primary's entry for a
+            // provider present in both overwrites the fallback's — the same precedence `read` applies.
+            const infos = new Map();
+            for (const path of fallback === undefined ? [authPath] : [fallback, authPath]) {
+                for (const [providerId, cred] of Object.entries(readCreds(path, warn) ?? {})) {
+                    if (cred && (cred.type === "oauth" || cred.type === "api_key"))
+                        infos.set(providerId, { providerId, type: cred.type });
                 }
             }
-            return infos;
+            return [...infos.values()];
         },
         modify(providerId, fn) {
-            return withLockedAuthFile(authPath, async (current) => {
-                const creds = parseForWrite(current, authPath); // corrupt → throw → no clobber
+            const path = owner(providerId);
+            return withLockedAuthFile(path, async (current) => {
+                const creds = parseForWrite(current, path); // corrupt → throw → no clobber
                 const next = await fn(pick(creds, providerId));
                 if (next === undefined)
                     return { result: pick(creds, providerId) }; // unchanged: no write
@@ -218,12 +214,13 @@ export function fastagentCredentialStore(authPath = GLOBAL_AUTH_PATH, options =
             });
         },
         async delete(providerId) {
-            // No-op when nothing is stored: do NOT take the lock (which would create the file) on a
-            // machine that never stored this provider.
-            if (!existsSync(authPath))
+            const path = owner(providerId);
+            // No-op when nothing is stored: do NOT take the lock (which would create the file) on a machine that never
+            // stored this provider.
+            if (!existsSync(path))
                 return;
-            await withLockedAuthFile(authPath, async (current) => {
-                const creds = parseForWrite(current, authPath);
+            await withLockedAuthFile(path, async (current) => {
+                const creds = parseForWrite(current, path);
                 if (!(providerId in creds))
                     return { result: undefined }; // absent: no write
                 delete creds[providerId];

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

@@ -1,7 +1,3 @@
 import { type BuildSessionRuntimeOptions } from "./session-builder.ts";
-/**
- * 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.
- */
+/** Open the workspace's agent in pi's interactive TUI and run until the user exits. */
 export declare function runPiChat(dir: string, options?: BuildSessionRuntimeOptions): Promise<void>;

package/dist/engines/pi/chat.js

@@ -1,19 +1,7 @@
-/**
- * Chat: open a workspace into pi's interactive TUI (`fastagent chat`). A pi-specific COMMAND, not an
- * engine-neutral channel: it drives pi's full session API (InteractiveMode) for fidelity, so it lives
- * under engines/pi/ and is not re-exported.
- *
- * The TUI is ONE consumer of the shared definition-aware builder (session-builder.ts) — the same
- * assembly, model surface, and fastagent auth that serving uses. Log in with `fastagent login` (or
- * pi's TUI `/login`, which writes through the same credential store into the workspace auth file).
- */
+/** Chat: open a workspace into pi's interactive TUI (`fastagent chat`). */
 import { InteractiveMode } from "@earendil-works/pi-coding-agent";
 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.
- */
+/** Open the workspace's agent in pi's interactive TUI and run until the user exits. */
 export async function runPiChat(dir, options = {}) {
     const runtime = await buildAgentSessionRuntime(dir, options);
     await new InteractiveMode(runtime, {}).run();

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

@@ -2,47 +2,40 @@ import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { FastagentTool } from "./tool.ts";
 import type { Models } from "@earendil-works/pi-ai";
 import type { AnyModel } from "./models.ts";
+import type { HttpSurface } from "../../service.ts";
 export interface FastagentConfig {
-    /** "provider/modelId". Precedence: CLI --model > FASTAGENT_MODEL > config. */
+    /** "provider/modelId". */
     model?: string;
-    /** Reasoning effort for the model, pi's scale ("off" | "minimal" | "low" | "medium" | "high" |
-     *  "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. */
+    /** Reasoning effort for the model, pi's scale ("off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max"). */
     thinkingLevel?: ThinkingLevel;
-    /** Extra custom tools, appended after the pi coding tools — never replaces them. `FastagentTool`
-     *  = AgentTool plus the optional `deferred` marker (see defineTool). */
+    /** Extra custom tools, appended after the pi coding tools — never replaces them. */
     tools?: FastagentTool[];
-    /** `host` is the bind address: unset (or `0.0.0.0`) binds all interfaces — what containers need;
-     *  `127.0.0.1` keeps the serve (including `/control/*`) off the LAN. Precedence: `--bind` > this. */
-    http?: {
+    /** What the serve publishes on its port, and to which browsers (each key is documented on {@link HttpSurface}). */
+    http?: HttpSurface & {
+        /** Default port for `dev` / `start` (`DEFAULT_HTTP_PORT` when unset). */
         port?: number;
-        host?: string;
     };
-    /** Mount the built-in `wake` tool so the agent can schedule its OWN follow-up turns (self-scheduling).
-     *  Off by default — self-scheduling is an autonomy capability, opt in when you want it. Only takes
-     *  effect on the serving path (`dev`/`start`, where the scheduler poller honors a wake-up). */
-    selfSchedule?: boolean;
     /**
-     * Serve the session control plane over HTTP (`/control/*`: state/entries/events + dispatch —
-     * steer/abort/compact + session properties and lifecycle) for remote consumers: a Web panel, a desktop app, `fastagent
-     * attach`. Default off (it is a remote-control surface). When on, `dev`/`start` generate a
-     * per-boot bearer token and write `<stateRoot>/control.json` for local discovery. The serve
-     * binds all interfaces by default, so the routes are LAN-reachable with the token as the only
-     * protection — bind loopback (`--bind 127.0.0.1`; not `http.host`, which travels into a deployed
-     * image), firewall the port, or wrap it for real exposure (docs/design/session-control.md §14).
+     * Serve the session control plane over HTTP (`/control/*`: state/entries/events + dispatch — steer/abort/compact +
+     * session properties and lifecycle) for remote consumers.
      */
     sessionControl?: boolean;
-    /** Deploy-time declarations for what the agent needs on the box, so real agents don't hand-write a
-     *  Dockerfile / hand-set variables. */
+    /**
+     * Deploy-time declarations for what the agent needs on the box, so real agents don't hand-write a Dockerfile /
+     * hand-set variables.
+     */
     deploy?: {
-        /** Extra secret env-var NAMES the deployed agent needs beyond the model key + channel secrets — e.g.
-         *  a `GH_TOKEN` its tools use. `deploy` carries each from the LOCAL env to the host secret store and
-         *  lists them in the runbook; a missing value gates `--run` (like a channel secret). */
-        secrets?: string[];
-        /** Extra apt packages baked into the generated image (Debian default repos: git, ripgrep, jq…). For a
-         *  package needing a custom apt repo (e.g. gh) or a different base image, provide your own Dockerfile
-         *  — `deploy` keeps an existing one. */
+        /** Extra apt packages baked into the generated image (Debian default repos: git, ripgrep, jq…). */
         apt?: string[];
+        /** `deploy agentcore` only. */
+        agentcore?: {
+            /**
+             * How long an idle AgentCore session keeps its microVM, 60–1209600 seconds (default 180). Memory bills for the
+             * whole idle tail, and a session past it cold-starts — the workload picks the trade: a chat agent talked to in
+             * bursts wants a longer tail, a schedule-only agent a shorter one.
+             */
+            idleTimeoutSeconds?: number;
+        };
     };
 }
 /** Identity function for typing and IDE completion (vite/next-style). */
@@ -52,37 +45,46 @@ export interface LoadedConfig {
     /** 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;
-/** Load `<dir>/fastagent.config.ts|.js|.mjs`. No file = defaults; a wrong-shape file throws. */
+/** Load `<dir>/fastagent.config.ts`. */
 export declare function loadConfig(dir: string): Promise<LoadedConfig>;
-/** 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). */
+/** The provider prefix of a "provider/modelId" spec. */
 export declare function providerOf(spec: string): string;
 /** Resolve "provider/modelId" → a pi Model from `models`, so auth resolves from the same collection. */
 export declare function resolveModel(models: Models, spec: string): AnyModel;
 /** All registered "provider/modelId" specs in `models`, sorted — the list behind `fastagent models`. */
 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 (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.
- */
+/** Rewrite the `model` in a config file's SOURCE TEXT to `spec`, for the first-run picker's write-back. */
 export declare function rewriteConfigModel(src: string, spec: string): string | null;
-/** Model selection precedence: CLI flag > FASTAGENT_MODEL env > config default. */
-export declare function resolveModelSpec(flag: string | undefined, config: FastagentConfig, env?: NodeJS.ProcessEnv): string | undefined;
 /**
- * `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).
- * Resolved to absolute so the store and the startup report agree regardless of cwd.
+ * Model selection precedence: CLI flag > FASTAGENT_MODEL env > config default. An EMPTY `FASTAGENT_MODEL` is
+ * "unset", not "no model": `export FASTAGENT_MODEL=` in a shell or CI job, and an `environment:`/`env` entry that
+ * interpolates a missing variable, both arrive as `""` — and a set-but-empty value that shadowed `config.model`
+ * would refuse to start an agent whose config names a model.
  */
-export declare function resolveSessionsDirOverride(flag: string | undefined, env?: NodeJS.ProcessEnv): string | undefined;
+export declare function resolveModelSpec(flag: string | undefined, config: FastagentConfig, env?: NodeJS.ProcessEnv): string | undefined;
 /** 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;
+export declare function resolveAuthPath(dir: string, flag?: string, env?: NodeJS.ProcessEnv): string;
+/**
+ * Which credentials files an agent reads: `path` first, then, per provider, `fallback` — present only when nothing
+ * named the path ({@link resolveAuthFallback}). One value because it is one decision: the opener, the model list, the
+ * startup report and the first-run picker all read through it.
+ */
+export interface AuthLayers {
+    path: string;
+    fallback?: string;
+}
+/** The {@link AuthLayers} an agent directory reads: `authPath` option > `FASTAGENT_AUTH_PATH` > its own file. */
+export declare function resolveAuthLayers(agentDir: string, authPath?: string, env?: NodeJS.ProcessEnv): AuthLayers;
+/**
+ * Where a credential the project does not have is read from instead: the user-global store, because a login is a
+ * PERSON on a machine and not a project — one `login -g` then serves every agent here. Undefined when an explicit
+ * path was named: "use this file" is an instruction, not a preference, so it gets no second layer.
+ *
+ * BOTH knobs {@link resolveAuthPath} reads count as that instruction, `FASTAGENT_SECRETS_DIR` included — it is what
+ * the Fly/Railway/AgentCore artifacts set, and a deployed container must read its mounted credentials and nothing
+ * else (the artifact is the truth).
+ */
+export declare function resolveAuthFallback(flag?: string, env?: NodeJS.ProcessEnv): string | undefined;