@fastagent-sh/fastagent 0.15.0 → 0.16.0

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

@@ -13,11 +13,11 @@ export declare function piDefaultTools(cwd: string): AgentTool[];
 /** `config.tools` semantics: extra tools APPENDED after pi's defaults, never replacing them. */
 export declare function resolveTools(config: FastagentConfig, cwd: string): AgentTool[];
 /**
- * The full tool set a workspace mounts: pi defaults + `config.tools` + discovered `tools/` (deduped,
+ * The full tool set an agent mounts: pi defaults + `config.tools` + discovered `tools/` (deduped,
  * existing win), plus the non-default tool names and collisions to report. One source for the
  * dev/start openers AND `fastagent tool`, so they all mount exactly the same set.
  */
-export declare function resolveWorkspaceTools(config: FastagentConfig, agentDir: string, cwd?: string): Promise<{
+export declare function resolveAgentTools(config: FastagentConfig, agentDir: string, cwd?: string): Promise<{
     tools: AgentTool[];
     toolNames: string[];
     /** Tools registered but not initially active (defineTool `deferred: true`) — discovered/activated
@@ -86,8 +86,8 @@ export interface CreatePiAgentOptions {
      */
     providers?: Provider[];
     /**
-     * Credentials file for stored OAuth/API-key auth. Defaults to `~/.fastagent/auth.json`; the
-     * directory opener passes the project-level `<dir>/.fastagent/auth.json` instead. Env vars are still
+     * Credentials file for stored OAuth/API-key auth. Defaults to `~/.fastagent/.secrets/auth.json`; the
+     * directory opener passes the project-level `<root>/.secrets/auth.json` instead. Env vars are still
      * consulted when a provider is absent from the file (resolution order is upstream-owned).
      */
     authPath?: string;
@@ -121,16 +121,16 @@ export interface CreatePiAgentFromDefinitionOptions {
     tools?: FastagentTool[];
     /**
      * The agent's working directory: where the default tools operate AND whose ancestors are walked for
-     * ② project context (AGENTS.md). Defaults to `dir` (flat: the definition dir is also the run root).
-     * Set it to the enclosing repo so a coding agent whose definition lives in `dir` operates on — and
-     * reads the AGENTS.md of — that repo (core.md scenario grid).
+     * ② project context (AGENTS.md). Defaults to `dir`. Set it to the enclosing repo so a coding agent
+     * whose definition lives in `dir` operates on — and reads the AGENTS.md of — that repo (core.md
+     * scenario grid); that is what the CLI's opener does with the workspace.
      */
     cwd?: string;
     /** Extra providers registered on top of the built-ins (your own gateway / self-hosted endpoint). */
     providers?: Provider[];
     /**
      * Credentials file (see {@link CreatePiAgentOptions.authPath}). Being dir-aware, this rung defaults
-     * to the PROJECT-level `<dir>/.fastagent/auth.json` (matching `fastagent dev`/`start` on the same
+     * to the PROJECT-level `<dir>/.secrets/auth.json` (matching `fastagent dev`/`start` on the same
      * dir) — unlike the dir-less {@link createPiAgent}/{@link createPiModels}, which default global.
      */
     authPath?: string;

package/dist/engines/pi/create.js

@@ -6,14 +6,15 @@
  *   L1  createPiAgent(options)                       — assemble from typed parts (the canonical ctor).
  *   L0  createPiAgentFromHarness({ harnessFactory }) — in invoke.ts (its body is the turn mechanism).
  *
- * Above L2 sits the workspace opener createPiAgentFromWorkspace (workspace.ts), which both `dev` and
+ * Above L2 sits the agent opener createPiAgentFromDir (open.ts), which both `dev` and
  * `start` drive. Each rung calls the one below; options narrow as you go up (L2 owns systemPrompt/skills —
  * they come from the definition; the openers own model/tools — from config resolution).
  */
 import { formatSkillsForSystemPrompt } from "@earendil-works/pi-agent-core";
 import { NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
 import { createCodingTools } from "@earendil-works/pi-coding-agent";
-import { defaultAuthPath, resolveModel, resolveStateRoot } from "./config.js";
+import { defaultAuthPath, resolveModel } from "./config.js";
+import { resolveSecretsDir } from "../../paths.js";
 import { loadAgentDefinition } from "./definition.js";
 import { piHarnessFactory } from "./harness.js";
 import { createPiModels } from "./models.js";
@@ -37,18 +38,18 @@ export function resolveTools(config, cwd) {
     return config.tools ? [...defaults, ...config.tools] : defaults;
 }
 /**
- * The full tool set a workspace mounts: pi defaults + `config.tools` + discovered `tools/` (deduped,
+ * The full tool set an agent mounts: pi defaults + `config.tools` + discovered `tools/` (deduped,
  * existing win), plus the non-default tool names and collisions to report. One source for the
  * dev/start openers AND `fastagent tool`, so they all mount exactly the same set.
  */
-export async function resolveWorkspaceTools(config, agentDir, cwd = agentDir) {
-    // Default coding tools (read/bash/edit/write) are rooted at `cwd` (the run root the agent operates on);
-    // discovered `tools/` come from `agentDir` (the agent's own surface). They coincide in the flat case.
+export async function resolveAgentTools(config, agentDir, cwd = agentDir) {
+    // Default coding tools (read/bash/edit/write) are rooted at `cwd` (the workspace the agent operates
+    // on); discovered `tools/` come from `agentDir` (the agent's own surface).
     const discovered = await loadTools(agentDir);
     const merged = mergeDiscoveredTools(resolveTools(config, cwd), discovered.tools);
-    // The built-in `search_tools` loader mounts here — the one place the workspace's full tool set is
-    // computed — so `dev`/`start`/`info`/`fastagent tool` all see the same surface (idempotent; a
-    // workspace-defined search_tools wins).
+    // The built-in `search_tools` loader mounts here — the one place the agent's full tool set is
+    // computed — so `dev`/`start`/`info`/`fastagent tool` all see the same surface (idempotent; an
+    // agent-defined search_tools wins).
     const tools = withSearchTool(merged.tools);
     // Builtin = a search_tools that was ABSENT before withSearchTool (a reference compare would misfire
     // on the deferred-authored-loader case, where withSearchTool returns a new array without adding one).
@@ -98,7 +99,7 @@ export function piBasePrompt(options = {}) {
     const deferredCount = mounted.length - tools.length;
     const toolsList = tools.length > 0 ? tools.map((t) => `- ${t.name}: ${(t.description ?? "").split("\n")[0]}`).join("\n") : "(none)";
     // Segment ① identity: an authored persona (persona.md) replaces the default engine identity line
-    // (the standalone×code-repo cell's persona; core.md §11), keeping the tools list + guidelines below.
+    // (core.md §11), keeping the tools list + guidelines below.
     const identity = options.persona?.trim() ||
         "You are an expert coding assistant operating inside pi, a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.";
     const deferredNote = deferredCount > 0
@@ -220,9 +221,9 @@ export async function createPiAgentFromDefinition(dir, options) {
         model: options.model,
         thinkingLevel: options.thinkingLevel,
         providers: options.providers,
-        // Dir-aware default: the same state-root-derived file the opener uses for this dir (the opener
+        // Dir-aware default: the same secrets-dir-derived file the opener uses for this dir (the opener
         // passes an explicit authPath, so this only affects direct L2 callers).
-        authPath: options.authPath ?? defaultAuthPath(resolveStateRoot(dir)),
+        authPath: options.authPath ?? defaultAuthPath(resolveSecretsDir(dir)),
         // The directory is the agent, LIVE: re-read the definition on every invoke, so AGENTS.md/skills
         // edits (the author's, or the agent's own self-modification) take effect on the next turn with
         // no process restart — restarts are reserved for code (tools/channels/config, module cache).

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

@@ -32,9 +32,9 @@ export interface LoadedDefinition {
 }
 export interface LoadAgentDefinitionOptions {
     /**
-     * Working directory whose ancestors are walked for context files (segment ②). Default = `agentDir`
-     * (flat: the agent dir is also the run root). The opener passes the run root so a coding agent that
-     * lives in `agentDir` picks up the host repo's AGENTS.md up the tree (core.md scenario grid).
+     * Working directory whose ancestors are walked for context files (segment ②). Default = `agentDir`.
+     * The opener passes the workspace instead, so an agent that lives in `agentDir` picks up the
+     * project's AGENTS.md up the tree (core.md scenario grid).
      */
     cwd?: string;
     env?: ExecutionEnv;
@@ -42,31 +42,12 @@ export interface LoadAgentDefinitionOptions {
 /** Read an agent definition. persona.md/skills come from `agentDir`; ② context = pi's loadProjectContextFiles({ cwd, agentDir }). */
 export declare function loadAgentDefinition(agentDir: string, options?: LoadAgentDefinitionOptions): Promise<LoadedDefinition>;
 /**
- * Whether `targetPath` lives inside `baseDir` (same path counts). The self-ignore guard uses it to ask
- * "does the resolved state root land inside the workspace tree?" — an in-tree root (the default
- * `.fastagent`, or a custom `FASTAGENT_STATE_DIR` pointed inside the agent dir) is ours to self-ignore;
- * a root on an external volume resolves outside and must not be (we never write a `.gitignore` outside
- * the tree). Whether a relative override lands in-tree is a cwd question — see `resolveStateRoot`.
+ * Whether `targetPath` lives inside `baseDir` (same path counts). Used to ask "did an override move
+ * this OUT of the agent?" — the startup report's redeploy notes, `add`'s printed `.env` label, and the
+ * dev watcher's "your .env is not watched" warning all turn on that fact. Reporting only: fastagent
+ * does not act on where a user's paths point.
  */
 export declare function isUnderDir(targetPath: string, baseDir: string): boolean;
-/**
- * The single owner of the self-ignore MECHANISM: iff the resolved state ROOT lands inside the workspace
- * tree, write `<stateRoot>/.gitignore="*"` — which then covers EVERYTHING under it (sessions, auth.json,
- * every channel's `channels/<kind>` home). `ensureStateDirSelfIgnored` is private, so a caller cannot
- * write a `.gitignore` bypassing this.
- *
- * ROOT-based, not path-based: everything derives from the state root (config.ts), so protecting the
- * root protects all of it — INCLUDING a custom in-tree root (a `FASTAGENT_STATE_DIR` inside the agent
- * dir), the case a path-based (`.fastagent`-only) guard would leak. A per-path override
- * (`--sessions-dir`/`--auth-path`) is operator-owned: pointed at an external volume it is out-of-tree
- * (correctly not ours to ignore); pointed at a custom in-tree dir WE DON'T OWN, we do not write a
- * `.gitignore` into it (it may be a directory the operator deliberately tracks).
- *
- * Excludes the user's HOME-global `~/.fastagent` (e.g. `login`/`dev` run from `$HOME`): self-ignore is
- * for protecting state inside an agent PROJECT tree, not for writing a `.gitignore` into the user's
- * home, which a dotfiles repo may track. The global credential file there was never self-ignored.
- */
-export declare function ensureStateRootSelfIgnored(dir: string, stateRoot: string): Promise<void>;
 /** Resolve to a canonical (symlink-free) absolute path so comparisons match `process.cwd()`'s realpath.
  *  A non-existent path can't be realpath'd, so it stays as the plain absolute resolve. */
 export declare function canonicalPath(p: string): string;

package/dist/engines/pi/definition.js

@@ -14,12 +14,11 @@
  * (bad skill files, name collisions) are returned as data. An unreadable ② context file only warns (pi).
  */
 import { realpathSync } from "node:fs";
-import { mkdir, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import { loadSkills } from "@earendil-works/pi-agent-core";
 import { NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
 import { loadProjectContextFiles } from "@earendil-works/pi-coding-agent";
+import { assertInsideAgentDir } from "../../paths.js";
 /** Read an agent definition. persona.md/skills come from `agentDir`; ② context = pi's loadProjectContextFiles({ cwd, agentDir }). */
 export async function loadAgentDefinition(agentDir, options = {}) {
     // One resolved default for the working directory (env cwd AND the context-walk start), so they can
@@ -44,7 +43,9 @@ export async function loadAgentDefinition(agentDir, options = {}) {
     }
     const persona = personaRead.ok ? personaRead.value : undefined;
     // Skills come ONLY from the definition's own skills/ (no external/global mount), so the same
-    // definition loads the same skills on every machine.
+    // definition loads the same skills on every machine — and, like tools/channels/schedules, a symlink
+    // that escapes the agent dir is refused rather than followed (the fourth of four surfaces).
+    await assertInsideAgentDir(root, "skills");
     const { skills: raw, diagnostics } = await loadSkills(e, [join(root, "skills")]);
     const byName = new Map();
     const collisions = [];
@@ -60,62 +61,15 @@ export async function loadAgentDefinition(agentDir, options = {}) {
     return { contextFiles, persona, skills: [...byName.values()], diagnostics, collisions, dir: root };
 }
 /**
- * Whether `targetPath` lives inside `baseDir` (same path counts). The self-ignore guard uses it to ask
- * "does the resolved state root land inside the workspace tree?" — an in-tree root (the default
- * `.fastagent`, or a custom `FASTAGENT_STATE_DIR` pointed inside the agent dir) is ours to self-ignore;
- * a root on an external volume resolves outside and must not be (we never write a `.gitignore` outside
- * the tree). Whether a relative override lands in-tree is a cwd question — see `resolveStateRoot`.
+ * Whether `targetPath` lives inside `baseDir` (same path counts). Used to ask "did an override move
+ * this OUT of the agent?" — the startup report's redeploy notes, `add`'s printed `.env` label, and the
+ * dev watcher's "your .env is not watched" warning all turn on that fact. Reporting only: fastagent
+ * does not act on where a user's paths point.
  */
 export function isUnderDir(targetPath, baseDir) {
     const rel = relative(baseDir, targetPath);
     return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
 }
-/**
- * Self-ignore a state dir: create it if missing, then write `<stateDir>/.gitignore` = "*" (idempotent
- * — an existing one is kept), so a workspace that runs dev/start never shows machine state as
- * untracked. Creates the dir because a caller may self-ignore it before anything else populates it
- * (e.g. `login` writing auth.json into a not-yet-created root).
- *
- * Module-PRIVATE on purpose: the only entry to the leak guard is {@link ensureStateRootSelfIgnored}
- * (home exclusion + containment). Keeping this unexported makes that single-owner claim hold at the
- * type level — a sibling command can't bypass those checks by writing a `.gitignore` directly.
- */
-async function ensureStateDirSelfIgnored(stateDir) {
-    await mkdir(stateDir, { recursive: true });
-    await writeFile(join(stateDir, ".gitignore"), "*\n", { flag: "wx" }).catch((e) => {
-        if (e.code !== "EEXIST")
-            throw e;
-    });
-}
-/**
- * The single owner of the self-ignore MECHANISM: iff the resolved state ROOT lands inside the workspace
- * tree, write `<stateRoot>/.gitignore="*"` — which then covers EVERYTHING under it (sessions, auth.json,
- * every channel's `channels/<kind>` home). `ensureStateDirSelfIgnored` is private, so a caller cannot
- * write a `.gitignore` bypassing this.
- *
- * ROOT-based, not path-based: everything derives from the state root (config.ts), so protecting the
- * root protects all of it — INCLUDING a custom in-tree root (a `FASTAGENT_STATE_DIR` inside the agent
- * dir), the case a path-based (`.fastagent`-only) guard would leak. A per-path override
- * (`--sessions-dir`/`--auth-path`) is operator-owned: pointed at an external volume it is out-of-tree
- * (correctly not ours to ignore); pointed at a custom in-tree dir WE DON'T OWN, we do not write a
- * `.gitignore` into it (it may be a directory the operator deliberately tracks).
- *
- * Excludes the user's HOME-global `~/.fastagent` (e.g. `login`/`dev` run from `$HOME`): self-ignore is
- * for protecting state inside an agent PROJECT tree, not for writing a `.gitignore` into the user's
- * home, which a dotfiles repo may track. The global credential file there was never self-ignored.
- */
-export async function ensureStateRootSelfIgnored(dir, stateRoot) {
-    // Compare CANONICAL paths for the home check: `dir` arrives realpath-resolved (it is `process.cwd()`
-    // or `resolve(".")`) but `homedir()` returns the raw `$HOME`, so a symlinked home would slip past raw
-    // equality and we'd write a `.gitignore` into the real `~/.fastagent` — the very thing the doc forbids
-    // (chat.ts canonicalizes for the same reason).
-    if (canonicalPath(dir) === canonicalPath(homedir()))
-        return;
-    // Containment on RAW paths: stateRoot is resolve()'d (config.ts) and `dir` is absolute, so it is exact
-    // by construction. An external-volume root resolves outside the tree → skip (not ours to ignore).
-    if (isUnderDir(stateRoot, dir))
-        await ensureStateDirSelfIgnored(stateRoot);
-}
 /** Resolve to a canonical (symlink-free) absolute path so comparisons match `process.cwd()`'s realpath.
  *  A non-existent path can't be realpath'd, so it stays as the plain absolute resolve. */
 export function canonicalPath(p) {

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

@@ -1,6 +1,6 @@
 /**
  * `fastagent login`: authenticate a MODEL PROVIDER into the resolved auth file (project-level
- * `<dir>/.fastagent/auth.json` by default, or `--auth-path`/`FASTAGENT_AUTH_PATH`) via the same
+ * `<root>/.secrets/auth.json` by default, or `--auth-path`/`FASTAGENT_AUTH_PATH`) via the same
  * {@link fastagentCredentialStore} the runtime uses (one writer, one lock/corruption semantics).
  *
  * Flow (pi-ai's unified `ProviderAuth` API): pick a method (OAuth or API key), then a provider that

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

@@ -9,8 +9,8 @@ import { ModelRuntime } from "@earendil-works/pi-coding-agent";
 import { type FastagentAuthOptions } from "./auth.ts";
 import { type InteractiveLoginKind } from "./login.ts";
 export interface CreatePiModelsOptions extends FastagentAuthOptions {
-    /** Credentials file path. Defaults to the global `~/.fastagent/auth.json`; the directory opener passes
-     *  the project-level `<dir>/.fastagent/auth.json`. */
+    /** Credentials file path. Defaults to the global `~/.fastagent/.secrets/auth.json`; the directory opener passes
+     *  the project-level `<root>/.secrets/auth.json`. */
     authPath?: string;
     /** Extra providers registered on top of the built-ins (same id overrides a built-in). */
     providers?: Provider[];
@@ -18,7 +18,7 @@ export interface CreatePiModelsOptions extends FastagentAuthOptions {
 /**
  * A `Models` with every built-in pi provider, wired to fastagent's auth: stored credentials from the
  * {@link CreatePiModelsOptions.authPath} file (via {@link fastagentCredentialStore}; the global
- * `~/.fastagent/auth.json` unless the opener passes a project-level path), then ambient env vars. A
+ * `~/.fastagent/.secrets/auth.json` unless the opener passes a project-level path), then ambient env vars. A
  * stored credential owns the provider; env is consulted only when nothing is stored (resolution order
  * is upstream-owned).
  */

package/dist/engines/pi/models.js

@@ -12,7 +12,7 @@ import { interactiveLoginKind } from "./login.js";
 /**
  * A `Models` with every built-in pi provider, wired to fastagent's auth: stored credentials from the
  * {@link CreatePiModelsOptions.authPath} file (via {@link fastagentCredentialStore}; the global
- * `~/.fastagent/auth.json` unless the opener passes a project-level path), then ambient env vars. A
+ * `~/.fastagent/.secrets/auth.json` unless the opener passes a project-level path), then ambient env vars. A
  * stored credential owns the provider; env is consulted only when nothing is stored (resolution order
  * is upstream-owned).
  */

package/dist/engines/pi/{workspace.d.ts → open.d.ts}

@@ -5,21 +5,21 @@ import type { SessionControl } from "../../session.ts";
 import type { SessionObserver } from "./invoke.ts";
 import type { PiSessionReader, PiSessionStore } from "./sessions.ts";
 import type { ModuleLoadFailure } from "../../loader.ts";
-import { type LoadedDefinition } from "./definition.ts";
+import type { LoadedDefinition } from "./definition.ts";
 import type { ToolCollision } from "./tool.ts";
-export interface CreatePiAgentFromWorkspaceOptions {
+export interface CreatePiAgentFromDirOptions {
     /** Model spec override (e.g. the CLI --model flag). Precedence: this > FASTAGENT_MODEL > config.model. */
     model?: string;
     /**
-     * Session store directory. Default `<dir>/.fastagent/sessions` (gitignored machine state). `start`
+     * Session store directory. Default `<agentDir>/.state/sessions` (machine state). `start`
      * overrides it (--sessions-dir / FASTAGENT_SESSIONS_DIR / a mounted volume) so production continuity
      * survives redeploys.
      */
     sessionsDir?: string;
     /**
-     * Credentials file override. Default `<dir>/.fastagent/auth.json` (project-level, gitignored under
-     * the same `*`-ignored `.fastagent`). Override via --auth-path / FASTAGENT_AUTH_PATH; point it at
-     * `~/.fastagent/auth.json` to share one credential across projects.
+     * Credentials file override. Default `<agentDir>/.secrets/auth.json` (project-level, under the
+     * `.secrets/`). Override via --auth-path / FASTAGENT_AUTH_PATH; point it at
+     * the global `~/.fastagent/.secrets/auth.json` to share one credential across projects.
      */
     authPath?: string;
     /**
@@ -28,7 +28,7 @@ export interface CreatePiAgentFromWorkspaceOptions {
      * and never poll). The built-in `wake` tool mounts only when this is set AND `config.selfSchedule` is on.
      */
     serving?: boolean;
-    /** Assemble the session control plane over this workspace's session store and return it as
+    /** Assemble the session control plane over this agent's session store and return it as
      *  {@link sessionControl} — the store is created inside this opener, so the hub must be wired
      *  here too (an external `createPiSessionControl` cannot exist before the store does).
      *  Default: `config.sessionControl` AND {@link serving} — the config key means "serve the control
@@ -43,24 +43,27 @@ export interface CreatePiAgentFromWorkspaceOptions {
     observer?: SessionObserver;
 }
 /**
- * The workspace assembly FRONT HALF — everything that is independent of how pi consumes the
+ * The agent assembly FRONT HALF — everything that is independent of how pi consumes the
  * definition (transient harness for serving vs resident AgentSession for chat / session control):
- * config → model spec → agentDir → the full tool surface ({@link resolveWorkspaceTools} — the ONE
- * place it is computed) → state root → auth path. Both {@link createPiAgentFromWorkspace} and the
+ * placement resolution → config → model spec → the full tool surface ({@link resolveAgentTools} — the
+ * ONE place it is computed) → state root → auth path. Both {@link createPiAgentFromDir} and the
  * session builder (session-builder.ts) consume this, so THESE inputs cannot drift between the two
  * consumption shapes. (Definition loading and prompt assembly stay per-consumer: serving re-reads
  * them live per invoke, the session builder snapshots at startup and lets pi append skills/env.)
  */
-export interface WorkspaceAssembly {
+export interface AgentAssembly {
     config: FastagentConfig;
     configPath?: string;
     /** The resolved "provider/modelId" spec in use. */
     modelSpec: string;
-    /** Absolute agent-definition dir (config.agentDir resolved against dir; = dir when unset). */
+    /** Absolute agent dir — definition + config + machinery live here (resolvePlacement().agentDir). */
     agentDir: string;
-    /** Absolute state root (FASTAGENT_STATE_DIR > <dir>/.fastagent). */
+    /** Absolute workspace — the agent's cwd and the start of the ②-context walk: the agent dir's parent
+     *  when the agent sits inside it, the agent dir ITSELF when you point at the agent. */
+    workspace: string;
+    /** Absolute state root (FASTAGENT_STATE_DIR > <agentDir>/.state). */
     stateRoot: string;
-    /** Absolute credentials file (--auth-path/authPath option > FASTAGENT_AUTH_PATH > <stateRoot>/auth.json). */
+    /** Absolute credentials file (--auth-path/authPath option > FASTAGENT_AUTH_PATH > <agentDir>/.secrets/auth.json). */
     authPath: string;
     /** The full mounted tool surface (config.tools + discovered tools/, search_tools applied). */
     tools: AgentTool[];
@@ -69,25 +72,28 @@ export interface WorkspaceAssembly {
     toolCollisions: ToolCollision[];
     toolFailures: ModuleLoadFailure[];
 }
-export declare function resolveWorkspaceAssembly(dir: string, options?: {
+export declare function resolveAgentAssembly(dir: string, options?: {
     model?: string;
     authPath?: string;
-}): Promise<WorkspaceAssembly>;
+}): Promise<AgentAssembly>;
 /**
- * "Point at a workspace → agent": load the config, resolve model and tools, then L2. Throws a clear
- * error when no model source is set (fail visibly at startup). Returns everything an entry point needs
- * to report what it assembled.
+ * "Point at a directory → agent": resolve the placement (`dir` may be either end — the workspace or
+ * the agent dir itself), load the config, resolve model and tools, then L2. Throws a clear error when
+ * no model source is set (fail visibly at startup). Returns everything an entry point needs to report
+ * what it assembled.
  */
-export declare function createPiAgentFromWorkspace(dir: string, options?: CreatePiAgentFromWorkspaceOptions): Promise<{
+export declare function createPiAgentFromDir(dir: string, options?: CreatePiAgentFromDirOptions): Promise<{
     agent: Agent;
     definition: LoadedDefinition;
     config: FastagentConfig;
     configPath?: string;
     /** The resolved "provider/modelId" spec actually in use. */
     modelSpec: string;
-    /** Absolute agent-definition dir in use (config.agentDir resolved against dir; = dir when unset). Channels/tools/persona come from here. */
+    /** Absolute agent dir in use — channels/tools/persona come from here. */
     agentDir: string;
-    /** Absolute state root in use (FASTAGENT_STATE_DIR > <dir>/.fastagent) — the ChannelContext's stateRoot. */
+    /** Absolute workspace in use — the agent's cwd: ALWAYS the directory that was pointed at. */
+    workspace: string;
+    /** Absolute state root in use (FASTAGENT_STATE_DIR > <agentDir>/.state) — the ChannelContext's stateRoot. */
     stateRoot: string;
     /** Absolute session store directory in use (for the startup report). */
     sessionsDir: string;
@@ -95,7 +101,7 @@ export declare function createPiAgentFromWorkspace(dir: string, options?: Create
     authPath: string;
     /** The session store in use — also a {@link PiSessionReader}. */
     sessions: PiSessionStore & PiSessionReader;
-    /** The observation plane over this workspace's sessions; present iff `options.sessionControl`. */
+    /** The observation plane over this agent's sessions; present iff `options.sessionControl`. */
     sessionControl?: SessionControl;
     /** Non-default, active-by-default tool names in effect: config.tools + discovered tools/. Each name
      *  lives in exactly one report slot — deferred names are in {@link deferredToolNames} instead. */

package/dist/engines/pi/{workspace.js → open.js}

@@ -1,5 +1,5 @@
 /**
- * Open a definition directory into an agent — the single workspace opener BOTH `fastagent dev` and
+ * Open a definition directory into an agent — the single agent opener BOTH `fastagent dev` and
  * `fastagent start` drive.
  *
  * A thin command-posture composition over L2 `createPiAgentFromDefinition`: open the directory →
@@ -9,39 +9,35 @@
  * watch and can point sessions at a mounted volume.
  */
 import { mkdir } from "node:fs/promises";
-import { defaultSessionsDir, loadConfig, resolveAgentDir, resolveAuthPath, resolveModelSpec, resolveStateRoot, } from "./config.js";
-import { createPiAgentFromDefinition, resolveWorkspaceTools } from "./create.js";
+import { defaultSessionsDir, loadConfig, resolveAuthPath, resolveModelSpec, } from "./config.js";
+import { resolveStateRoot, resolvePlacement } from "../../paths.js";
+import { createPiAgentFromDefinition, resolveAgentTools } from "./create.js";
 import { createPiSessionControl } from "./session-control.js";
 import { withWakeTool } from "./wake-tool.js";
-import { ensureStateRootSelfIgnored } from "./definition.js";
 import { jsonlSessionStore } from "./sessions.js";
-export async function resolveWorkspaceAssembly(dir, options = {}) {
-    const { config, path: configPath } = await loadConfig(dir);
+export async function resolveAgentAssembly(dir, options = {}) {
+    // Placement is structural (resolvePlacement): the AGENT DIR carries definition + config + machinery;
+    // its parent — the WORKSPACE — is what the agent works on: its cwd and the start of the ②-context
+    // walk (that is where it reads the project's AGENTS.md from).
+    const { agentDir, workspace } = resolvePlacement(dir);
+    const { config, path: configPath } = await loadConfig(agentDir);
     const modelSpec = resolveModelSpec(options.model, config);
     if (!modelSpec) {
         throw new Error(`missing model: set --model, "model" in fastagent.config.ts, or FASTAGENT_MODEL (e.g. "openai-codex/gpt-5.5")`);
     }
-    // The run root is `dir` (cwd — where config lives, whose AGENTS.md is ② context); the agent's own
-    // surface (persona/skills/tools/channels) lives in `agentDir` (config.agentDir, or `dir` when flat).
-    const agentDir = resolveAgentDir(dir, config);
-    const { tools, toolNames, deferredToolNames, toolCollisions, toolFailures } = await resolveWorkspaceTools(config, agentDir, dir);
-    // The state root: auth/sessions/channel state all derive from it, so FASTAGENT_STATE_DIR moves the
-    // whole machine-state home in one knob (a container mounts one volume); the finer overrides below
-    // still win for their specific path.
-    const stateRoot = resolveStateRoot(dir);
-    // The credentials file: project-level by default (under the state root); only resolved here, never
+    const { tools, toolNames, deferredToolNames, toolCollisions, toolFailures } = await resolveAgentTools(config, agentDir, workspace);
+    // The state root: sessions/channel state/schedule state derive from it (FASTAGENT_STATE_DIR moves it
+    // in one knob — a container points it at its volume); the finer overrides below still win.
+    const stateRoot = resolveStateRoot(agentDir);
+    // The credentials file: project-level by default (under `<agentDir>/.secrets`); only resolved here, never
     // created (a missing file reads as not-configured — `fastagent login` creates it).
-    const authPath = resolveAuthPath(dir, options.authPath);
-    // Self-ignore the state root iff it lands in-tree — which covers everything under it (sessions, auth,
-    // every channel's `channels/<kind>` home). HERE, not in the serving opener: every consumer of this
-    // assembly can WRITE under the state root (serving: sessions/channels; the session builder: pi's
-    // `/login` writing auth.json), so resolving a workspace's state root must make it leak-safe.
-    await ensureStateRootSelfIgnored(dir, stateRoot);
+    const authPath = resolveAuthPath(agentDir, options.authPath);
     return {
         config,
         configPath,
         modelSpec,
         agentDir,
+        workspace,
         stateRoot,
         authPath,
         tools,
@@ -52,18 +48,19 @@ export async function resolveWorkspaceAssembly(dir, options = {}) {
     };
 }
 /**
- * "Point at a workspace → agent": load the config, resolve model and tools, then L2. Throws a clear
- * error when no model source is set (fail visibly at startup). Returns everything an entry point needs
- * to report what it assembled.
+ * "Point at a directory → agent": resolve the placement (`dir` may be either end — the workspace or
+ * the agent dir itself), load the config, resolve model and tools, then L2. Throws a clear error when
+ * no model source is set (fail visibly at startup). Returns everything an entry point needs to report
+ * what it assembled.
  */
-export async function createPiAgentFromWorkspace(dir, options = {}) {
-    const { config, configPath, modelSpec, agentDir, stateRoot, authPath, tools, toolNames, deferredToolNames, toolCollisions, toolFailures, } = await resolveWorkspaceAssembly(dir, options);
+export async function createPiAgentFromDir(dir, options = {}) {
+    const { config, configPath, modelSpec, agentDir, workspace, stateRoot, authPath, tools, toolNames, deferredToolNames, toolCollisions, toolFailures, } = await resolveAgentAssembly(dir, options);
     // Mount the built-in `wake` tool only when BOTH: this is a long-running serve (the poller honors it) AND
-    // the author opted into self-scheduling (config.selfSchedule). The workspace's own `wake` wins if defined.
+    // the author opted into self-scheduling (config.selfSchedule). The agent's own `wake` wins if defined.
     const mountedTools = withWakeTool(tools, stateRoot, !!options.serving && !!config.selfSchedule);
     const sessionsDir = options.sessionsDir ?? defaultSessionsDir(stateRoot);
     await mkdir(sessionsDir, { recursive: true });
-    const sessions = jsonlSessionStore({ dir: sessionsDir, cwd: dir });
+    const sessions = jsonlSessionStore({ dir: sessionsDir, cwd: workspace });
     // The hub is wired HERE because the store is created here: chicken-and-egg otherwise (the hub
     // needs the store; the agent needs the hub's observer). Boundary parts (models/factory/lease)
     // only exist after the assembly below — the hub takes them as a lazy thunk, filled by the
@@ -93,7 +90,7 @@ export async function createPiAgentFromWorkspace(dir, options = {}) {
     const { agent, definition } = await createPiAgentFromDefinition(agentDir, {
         model: modelSpec,
         thinkingLevel: config.thinkingLevel,
-        cwd: dir,
+        cwd: workspace,
         tools: mountedTools,
         authPath,
         // Skills are definition-only (the agent is its directory), so dev mirrors deployment exactly.
@@ -115,6 +112,7 @@ export async function createPiAgentFromWorkspace(dir, options = {}) {
         sessions,
         sessionControl: hub?.control,
         agentDir,
+        workspace,
         config,
         configPath,
         modelSpec,

package/dist/engines/pi/session-builder.d.ts

@@ -3,7 +3,7 @@ export interface BuildSessionRuntimeOptions {
     /** Model spec override (the CLI --model flag). Precedence: this > FASTAGENT_MODEL > config.model. */
     model?: string;
     /** Credentials file override (the CLI --auth-path flag). Precedence: this > FASTAGENT_AUTH_PATH >
-     *  the workspace default `<stateRoot>/auth.json`. */
+     *  the agent's default `<agentDir>/.secrets/auth.json`. */
     authPath?: string;
 }
 /**
@@ -11,6 +11,6 @@ export interface BuildSessionRuntimeOptions {
  * skills, and auth resolved exactly as the serving opener does). Split from the TUI launcher so the
  * assembly — the fidelity-critical part — is inspectable and reusable without launching a TUI.
  */
-export declare function buildWorkspaceSessionRuntime(dir: string, options?: BuildSessionRuntimeOptions, 
+export declare function buildAgentSessionRuntime(dir: string, options?: BuildSessionRuntimeOptions, 
 /** Session backend. Defaults to pi's project-scoped store; tests inject SessionManager.inMemory(). */
 sessionManager?: SessionManager): Promise<AgentSessionRuntime>;