@fastagent-sh/fastagent 0.15.0 → 0.16.1

package/dist/cli/commands/dev.js

@@ -1,21 +1,24 @@
 /**
  * `fastagent dev`: a SUPERVISOR that spawns a worker (this command with FASTAGENT_DEV_WORKER set) to
- * assemble + serve, restarting it on workspace edits. A fresh process per reload means what is served
+ * assemble + serve, restarting it on agent edits. A fresh process per reload means what is served
  * is always the latest code, including modules a tool/config imports.
  */
 import { resolve } from "node:path";
 import { runDevSupervisor } from "../../dev-supervisor.js";
 import { loadDotEnv } from "../../env.js";
 import { reportDefinitionWarnings, reportModuleLoadFailures, reportToolCollisions } from "../../engines/pi/report.js";
-import { createPiAgentFromWorkspace } from "../../engines/pi/workspace.js";
-import { log, setLogLevel } from "../../log.js";
+import { createPiAgentFromDir } from "../../engines/pi/open.js";
+import { setLogLevel } from "../../log.js";
 import { logAgentLoop } from "../../observe.js";
 import { installProxyFetch } from "../../proxy.js";
-import { failStartup } from "../fail.js";
-import { maybeTunnel, mountSessionControl, routesFor, serve, startSchedules } from "../serve.js";
-import { parsePort, reportAuth, resolveFirstRunModel } from "../shared.js";
+import { workspaceHint } from "../../paths.js";
+import { bindAddress } from "../../bind.js";
+import { failStartup, placementOrExit } from "../fail.js";
+import { assertTunnelBindable, maybeTunnel, mountSessionControl, routesFor, serve, startSchedules } from "../serve.js";
+import { parseBind, parsePort, reportAuth, reportLine, resolveFirstRunModel, reportWorkspaceHint } from "../shared.js";
 export async function runDev(dirArg, opts) {
     const dir = resolve(dirArg);
+    const placement = placementOrExit(dir);
     setLogLevel("debug"); // dev posture: verbose, includes the debug turn trace (content) — supervisor and worker both
     const isWorker = process.env.FASTAGENT_DEV_WORKER === "1";
     // Pick a model interactively once, in the parent (both watch and --no-watch have a TTY); a spawned
@@ -23,58 +26,68 @@ export async function runDev(dirArg, opts) {
     // the proxy FIRST (as invoke/start do): the picker reads FASTAGENT_MODEL and provider keys from
     // .env, and getAuth's OAuth refresh must go through HTTPS_PROXY. The worker re-loads both in serveOnce.
     if (!isWorker) {
-        loadDotEnv(dir);
+        loadDotEnv(placement.agentDir);
         installProxyFetch();
-        await resolveFirstRunModel(dir, opts);
+        await resolveFirstRunModel(placement.agentDir, opts);
     }
     if (isWorker || opts.watch === false) {
         await serveOnce(dir, opts);
         return;
     }
-    parsePort(opts.port, "--port", "flag"); // flag-shape check before spawning
-    await runDevSupervisor(dir, { tunnel: opts.tunnel ?? false });
+    parsePort(opts.port, "--port", "flag"); // flag-shape checks before spawning
+    // The --bind/--tunnel conflict is decidable from flags alone: refuse it HERE, before a worker and a
+    // tunnel exist. The worker repeats the check because `http.host` can supply the address instead.
+    assertTunnelBindable(parseBind(opts.bind), opts.tunnel ?? false, "flag");
+    await runDevSupervisor(placement, { tunnel: opts.tunnel ?? false });
 }
-/** Assemble the workspace agent and serve it once (the dev worker; also the --no-watch path). */
+/** Assemble the agent and serve it once (the dev worker; also the --no-watch path). */
 async function serveOnce(dir, opts) {
     const portFlag = parsePort(opts.port, "--port", "flag");
-    loadDotEnv(dir);
+    const bindFlag = parseBind(opts.bind);
+    loadDotEnv(placementOrExit(dir).agentDir);
     installProxyFetch();
-    const a = await createPiAgentFromWorkspace(dir, {
+    const a = await createPiAgentFromDir(dir, {
         model: opts.model,
         authPath: opts.authPath, // flag > FASTAGENT_AUTH_PATH > default — resolved by the opener (one owner)
         serving: true, // long-running serve: the scheduler poller runs (wake mounts iff config.selfSchedule)
     }).catch(failStartup);
-    log.info(`[fastagent] dir:    ${dir}`);
-    if (a.agentDir !== dir)
-        log.info(`[fastagent] agent:  ${a.agentDir}`);
-    log.info(`[fastagent] config: ${a.configPath ?? "(zero-config)"}`);
-    log.info(`[fastagent] model:  ${a.modelSpec}${a.config.thinkingLevel ? ` (thinking: ${a.config.thinkingLevel})` : ""}`);
+    reportLine("agent", a.agentDir);
+    reportLine("workspace", a.workspace);
+    reportWorkspaceHint(workspaceHint(a));
+    reportLine("config", a.configPath ?? "(none)");
+    reportLine("model", `${a.modelSpec}${a.config.thinkingLevel ? ` (thinking: ${a.config.thinkingLevel})` : ""}`);
     await reportAuth(a.modelSpec, a.authPath);
     reportAgentsSkillsTools(a);
     // Trace each turn's agent loop (tool calls + reply) to the log at debug level — shown in dev, gated
     // out in start (level info), keeping end-user content out of production logs. Wired in both postures.
     const traced = logAgentLoop(a.agent);
     const routed = await routesFor(a.agentDir, traced, a.stateRoot, a.sessionControl).catch(failStartup);
+    // `http.host` enters here the way the flag enters `parseBind` — through `bindAddress`, so a
+    // configured `localhost` is an ADDRESS by the time anything binds, renders or dials it.
+    const configured = a.config.http?.host;
+    const host = bindFlag ?? (configured === undefined ? undefined : bindAddress(configured));
+    assertTunnelBindable(host, opts.tunnel ?? false, bindFlag ? "flag" : "config");
     const withControl = mountSessionControl(routed.routes, a.sessionControl, a.stateRoot, {
         tunnel: opts.tunnel ?? false,
         agent: traced, // the remote data plane (POST /control/invoke) drives the SAME traced agent
+        host,
     });
     await startSchedules(a.agentDir, traced, a.stateRoot, a.config.selfSchedule ?? false);
-    serve({ ...routed, routes: withControl.routes }, portFlag ?? a.config.http?.port ?? 8787, (p) => {
+    serve({ ...routed, routes: withControl.routes }, { port: portFlag ?? a.config.http?.port ?? 8787, host }, (p) => {
         withControl.announce(p);
-        maybeTunnel(dir, routed.routeChannels, p, opts.tunnel ?? false, a.stateRoot);
+        maybeTunnel(a.agentDir, routed.routeChannels, p, opts.tunnel ?? false, a.stateRoot);
     });
 }
 /** The agents/skills/tools/collisions report lines. */
 function reportAgentsSkillsTools(a) {
-    log.info(`[fastagent] context: ${a.definition.contextFiles.map((f) => f.path).join(", ") || "(none)"}`);
+    reportLine("context", a.definition.contextFiles.map((f) => f.path).join(", ") || "(none)");
     if (a.definition.persona)
-        log.info(`[fastagent] persona: persona.md`);
-    log.info(`[fastagent] skills: ${a.definition.skills.map((s) => s.name).join(", ") || "(none)"}`);
+        reportLine("persona", "persona.md");
+    reportLine("skills", a.definition.skills.map((s) => s.name).join(", ") || "(none)");
     if (a.toolNames.length > 0)
-        log.info(`[fastagent] tools:  ${a.toolNames.join(", ")}`);
+        reportLine("tools", a.toolNames.join(", "));
     if (a.deferredToolNames.length > 0) {
-        log.info(`[fastagent] deferred: ${a.deferredToolNames.join(", ")} (activated via search_tools)`);
+        reportLine("deferred", `${a.deferredToolNames.join(", ")} (activated via search_tools)`);
     }
     reportToolCollisions(a.toolCollisions);
     reportModuleLoadFailures(a.toolFailures);

package/dist/cli/commands/fire.js

@@ -4,36 +4,35 @@
  * the schedule's stable session (faithful to the served behavior). Does NOT advance the schedule's fire
  * state — a test run must never make the scheduler skip the real next run.
  */
-import { relative, resolve, sep } from "node:path";
+import { join, resolve } from "node:path";
 import { loadDotEnv } from "../../env.js";
-import { loadConfig, resolveAgentDir } from "../../engines/pi/config.js";
+import { displayPath } from "../../paths.js";
 import { reportModuleLoadFailures } from "../../engines/pi/report.js";
-import { createPiAgentFromWorkspace } from "../../engines/pi/workspace.js";
+import { createPiAgentFromDir } from "../../engines/pi/open.js";
 import { runInvokeStream } from "../invoke-stream.js";
 import { installProxyFetch } from "../../proxy.js";
 import { loadSchedules } from "../../schedule/discover.js";
 import { scheduleSession } from "../../schedule/scheduler.js";
-import { failStartup } from "../fail.js";
+import { failStartup, placementOrExit } from "../fail.js";
 import { reportAuth, resolveFirstRunModel } from "../shared.js";
 export async function runFire(name, dirArg, opts) {
     const fireDir = resolve(dirArg);
-    loadDotEnv(fireDir);
+    const placement = placementOrExit(fireDir);
+    loadDotEnv(placement.agentDir);
     installProxyFetch();
-    await resolveFirstRunModel(fireDir, opts);
-    // Schedules are agent surface — discover them where dev/start/`schedule list` do (agentDir), not the
-    // run root, so `fire` sees the same set the scheduler serves in the kit layout.
-    const { config: fireConfig } = await loadConfig(fireDir).catch(failStartup);
-    const fireAgentDir = resolveAgentDir(fireDir, fireConfig);
-    const { schedules, failures } = await loadSchedules(fireAgentDir).catch(failStartup);
+    await resolveFirstRunModel(placement.agentDir, opts);
+    // Schedules are agent surface — discover them where dev/start/`schedule list` do (the agent
+    // dir), so `fire` sees the same set the scheduler serves.
+    const { schedules, failures } = await loadSchedules(placement.agentDir).catch(failStartup);
     reportModuleLoadFailures(failures);
     const schedule = schedules.find((s) => s.name === name);
     if (!schedule) {
-        // Name the discovery path in the kit layout: a schedule misplaced at the run root should read as
-        // "wrong place", not "broken file".
-        const looked = fireAgentDir === fireDir ? "" : ` (looked in ${relative(fireDir, fireAgentDir).split(sep).join("/")}/schedules)`;
-        failStartup(new Error(`unknown schedule "${name}"${looked}. available: ${schedules.map((s) => s.name).join(", ") || "(none)"}`));
+        // Name the discovery path: a schedule misplaced in the workspace (outside the agent dir)
+        // should read as "wrong place", not "broken file".
+        failStartup(new Error(`unknown schedule "${name}" (looked in ${displayPath(process.cwd(), join(placement.agentDir, "schedules")) ?? "schedules"}). ` +
+            `available: ${schedules.map((s) => s.name).join(", ") || "(none)"}`));
     }
-    const { agent, modelSpec, authPath } = await createPiAgentFromWorkspace(fireDir, {
+    const { agent, modelSpec, authPath } = await createPiAgentFromDir(fireDir, {
         model: opts.model,
         authPath: opts.authPath, // flag > FASTAGENT_AUTH_PATH > default — resolved by the opener (one owner)
     }).catch(failStartup);

package/dist/cli/commands/info.js

@@ -2,27 +2,29 @@
 import { resolve } from "node:path";
 import { loadDotEnv } from "../../env.js";
 import { discoverChannelFiles } from "../../engines/pi/channel.js";
-import { defaultSessionsDir, loadConfig, resolveAgentDir, resolveAuthPath, resolveModelSpec, resolveSessionsDirOverride, resolveStateRoot, } from "../../engines/pi/config.js";
-import { resolveWorkspaceTools } from "../../engines/pi/create.js";
+import { defaultSessionsDir, loadConfig, resolveAuthPath, resolveModelSpec, resolveSessionsDirOverride, } from "../../engines/pi/config.js";
+import { resolveStateRoot, workspaceHint } from "../../paths.js";
+import { resolveAgentTools } from "../../engines/pi/create.js";
 import { loadAgentDefinition } from "../../engines/pi/definition.js";
 import { reportDefinitionWarnings, reportModuleLoadFailures, reportToolCollisions } from "../../engines/pi/report.js";
 import { log } from "../../log.js";
 import { nextRun } from "../../schedule/cron.js";
 import { loadSchedules } from "../../schedule/discover.js";
-import { failStartup } from "../fail.js";
+import { failStartup, placementOrExit } from "../fail.js";
 export async function runInfo(dirArg, opts) {
     const dir = resolve(dirArg);
-    loadDotEnv(dir); // skills/tools may read env at load time
-    const { config, path: configPath } = await loadConfig(dir).catch(failStartup);
+    const { agentDir, workspace } = placementOrExit(dir);
+    loadDotEnv(agentDir); // skills/tools may read env at load time
+    const { config, path: configPath } = await loadConfig(agentDir).catch(failStartup);
     const modelSpec = resolveModelSpec(opts.model, config);
-    // dir = the run root (cwd, whose AGENTS.md is ② context); the agent's own surface lives in agentDir.
-    const agentDir = resolveAgentDir(dir, config);
-    const definition = await loadAgentDefinition(agentDir, { cwd: dir }).catch(failStartup);
+    // agentDir = where the agent lives (definition + config + machinery); workspace = what it works ON
+    // (its cwd, whose AGENTS.md ancestors are ② context).
+    const definition = await loadAgentDefinition(agentDir, { cwd: workspace }).catch(failStartup);
     // A tool that fails to load, for any reason (a missing dep, a top-level throw, or just not being a
     // tool), is isolated the same way everywhere (G2): info, dev, AND start report it and keep going with
     // the tools that loaded. The `error`/`.catch` below only fires for a whole-load fault (an unreadable
     // tools/ dir), not a single bad file.
-    const tools = await resolveWorkspaceTools(config, agentDir, dir)
+    const tools = await resolveAgentTools(config, agentDir)
         .then((r) => ({
         names: r.toolNames,
         deferred: r.deferredToolNames,
@@ -50,13 +52,13 @@ export async function runInfo(dirArg, opts) {
     }));
     // The default sessions/auth paths WITHOUT creating anything (info is read-only; dev/start mkdir/login
     // create them, info must not).
-    const stateRoot = resolveStateRoot(dir);
+    const stateRoot = resolveStateRoot(agentDir);
     const sessionsDir = resolveSessionsDirOverride(opts.sessionsDir) ?? defaultSessionsDir(stateRoot);
-    const authPath = resolveAuthPath(dir, opts.authPath); // flag > FASTAGENT_AUTH_PATH > default — the one owner
+    const authPath = resolveAuthPath(agentDir, opts.authPath); // flag > FASTAGENT_AUTH_PATH > default — the one owner
     if (opts.json) {
         console.log(JSON.stringify({
-            dir,
             agentDir,
+            workspace,
             configPath: configPath ?? null,
             model: modelSpec ?? null,
             thinkingLevel: config.thinkingLevel ?? null,
@@ -80,25 +82,30 @@ export async function runInfo(dirArg, opts) {
         }, null, 2));
         return;
     }
-    console.log(`dir:      ${dir}`);
-    if (agentDir !== dir)
-        console.log(`agent:    ${agentDir}`);
-    console.log(`config:   ${configPath ?? "(none)"}`);
-    console.log(`model:    ${modelSpec ?? "(not set — pass --model, set FASTAGENT_MODEL, or config.model)"}`);
+    // One padded label writer: hand-spaced labels drifted out of alignment the moment a longer one
+    // (agent/workspace/selfSchedule) joined the report.
+    const line = (label, value) => console.log(`${`${label}:`.padEnd(13)} ${value}`);
+    line("agent", agentDir);
+    line("workspace", workspace);
+    const hint = workspaceHint({ agentDir, workspace });
+    if (hint)
+        line("hint", hint);
+    line("config", configPath ?? "(none)");
+    line("model", modelSpec ?? "(not set — pass --model, set FASTAGENT_MODEL, or config.model)");
     if (config.thinkingLevel)
-        console.log(`thinking: ${config.thinkingLevel}`);
-    console.log(`context:  ${definition.contextFiles.map((f) => f.path).join(", ") || "(none)"}`);
-    console.log(`persona:  ${definition.persona ? "persona.md" : "(none)"}`);
-    console.log(`skills:   ${definition.skills.map((skill) => skill.name).join(", ") || "(none)"}`);
-    console.log(`tools:    ${tools.error ? "(could not load — see warning below)" : tools.names.join(", ") || "(none)"}`);
+        line("thinking", config.thinkingLevel);
+    line("context", definition.contextFiles.map((f) => f.path).join(", ") || "(none)");
+    line("persona", definition.persona ? "persona.md" : "(none)");
+    line("skills", definition.skills.map((skill) => skill.name).join(", ") || "(none)");
+    line("tools", tools.error ? "(could not load — see warning below)" : tools.names.join(", ") || "(none)");
     if (tools.deferred.length > 0)
-        console.log(`deferred: ${tools.deferred.join(", ")} (activated via search_tools)`);
-    console.log(`channels: ${channels.join(", ") || "(none)"}`);
-    console.log(`schedules: ${schedules.map((s) => `${s.name} (next ${s.next ?? "never"})`).join(", ") || "(none)"}`);
-    console.log(`selfSchedule: ${config.selfSchedule ? "on (mounts the wake tool when serving)" : "off"}`);
-    console.log(`state:    ${stateRoot}`);
-    console.log(`sessions: ${sessionsDir}`);
-    console.log(`auth:     ${authPath}`);
+        line("deferred", `${tools.deferred.join(", ")} (activated via search_tools)`);
+    line("channels", channels.join(", ") || "(none)");
+    line("schedules", schedules.map((s) => `${s.name} (next ${s.next ?? "never"})`).join(", ") || "(none)");
+    line("selfSchedule", config.selfSchedule ? "on (mounts the wake tool when serving)" : "off");
+    line("state", stateRoot);
+    line("sessions", sessionsDir);
+    line("auth", authPath);
     reportToolCollisions(tools.collisions);
     reportModuleLoadFailures(tools.failures);
     reportModuleLoadFailures(sched.failures);

package/dist/cli/commands/init.d.ts

@@ -2,7 +2,7 @@ export interface InitOptions {
     minimal: boolean;
     /** false ⇔ `--no-install`. */
     install: boolean;
-    flat: boolean;
+    /** The agent directory's name inside `dir` — undefined = the default, `"."` = `dir` itself (`--flat`). */
     agentDir?: string;
 }
 export declare function runInit(dirArg: string, opts: InitOptions): Promise<void>;

package/dist/cli/commands/init.js

@@ -1,73 +1,85 @@
 /**
- * `fastagent init [dir]`: scaffold a runnable agent and install its dependencies. Layout: flags force;
- * otherwise the jurisdiction rule decides (see detectHostSignals) and the reason is printed.
- * Deliberately no prompt — non-interactive executors (coding agents) get a deterministic default they
- * can read and override.
+ * `fastagent init [dir]`: scaffold a runnable agent and install its dependencies. Where the files land is
+ * a default plus one knob, never a detection and never a prompt — non-interactive executors (coding
+ * agents) get deterministic behavior they can read. By default the agent goes into `./fastagent/` and the
+ * directory around it is untouched; `--agent-dir <name>` names that directory anything, and `--agent-dir .`
+ * (spelled `--flat`) makes the directory itself the agent (a standalone agent repo, a monorepo package).
  */
 import { spawn } from "node:child_process";
-import { isAbsolute, join, relative, resolve, sep } from "node:path";
-import { detectHostSignals, nextStepCd, scaffoldWorkspace } from "../../scaffold/init.js";
+import { basename, join, resolve } from "node:path";
+import { DEFAULT_AGENT_DIRNAME, SECRETS_DIRNAME, agentsAt } from "../../paths.js";
+import { detectRuntime, readPackageJson } from "../../runtime.js";
+import { agentDirName, agentDirNameError, scaffoldAgent } from "../../scaffold/init.js";
+import { displayPath } from "../../paths.js";
 import { failStartup, failUsage } from "../fail.js";
 export async function runInit(dirArg, opts) {
     const dir = resolve(dirArg);
-    let agentDir;
-    let signals = [];
-    if (opts.agentDir) {
-        // Same containment contract loadConfig enforces on config.agentDir: an escaping value would write
-        // the kit outside the workspace AND produce a config that can never load — refuse up front.
-        // POSIX-normalized: this lands verbatim in the generated config (agentDir: "./a/b") and the persona
-        // locator note — a Windows `relative()` would write backslashes into both.
-        const rel = relative(dir, resolve(dir, opts.agentDir)).split(sep).join("/");
-        if (rel === "" || rel === ".." || rel.startsWith("../") || isAbsolute(rel)) {
-            // An invalid flag VALUE is a usage error (exit 2), same class as a value the parser rejects.
-            failUsage(`--agent-dir ("${opts.agentDir}") must be a subdirectory of ${dir}`);
-        }
-        agentDir = `./${rel}`;
-    }
-    else if (!opts.flat) {
-        signals = await detectHostSignals(dir).catch(failStartup);
-        if (signals.length > 0)
-            agentDir = "./agent";
-    }
-    const { complete, created, skipped, patched, intoNonEmpty, warnings } = await scaffoldWorkspace(dir, {
+    // A rejected flag VALUE is the usage class, same as one the parser rejects — so it is checked here,
+    // where exit 2 lives, not inside the scaffolder (whose throws are runtime failures, exit 1).
+    const requested = agentDirName(opts.agentDir);
+    const invalid = agentDirNameError(requested);
+    if (invalid)
+        failUsage(`--agent-dir "${requested}" ${invalid}`);
+    const { complete, agentDir: rel, created, kept, } = await scaffoldAgent(dir, {
         minimal: opts.minimal,
-        agentDir,
+        agentDir: requested,
     }).catch(failStartup);
-    // The layout reason prints only once the scaffold actually happened — an "already a workspace" refusal
-    // must not be preceded by an announced decision that then never takes place.
-    if (signals.length > 0) {
-        console.error(`[fastagent] found ${signals.join(", ")} — an existing toolchain/deploy claims this directory, so the agent kit goes into ./agent (its own namespace; config.agentDir points there). cwd stays this directory. Override: --flat`);
+    const flat = rel === ".";
+    // The agent dir is where the manifest lives, so any install runs there — never against a surrounding
+    // workspace's package.json (its deps are its own concern). With `.` they are the same directory.
+    const agentDir = resolve(dir, rel);
+    console.error(`[fastagent] initialized ${dir}${complete ? "" : " (minimal)"} — ${flat ? "the directory IS the agent" : `agent in ./${rel}/`}`);
+    console.error(`  created: ${created.join(", ")}`);
+    // A second agent beside an existing one is a supported shape, not an accident (an engineer's, a PM's
+    // and a content owner's agent can drive one repository), but it changes how this workspace resolves
+    // from now on — so say it HERE, at the moment it becomes true, instead of at the next command's
+    // refusal. The default name is the tie-break, so a workspace keeping `fastagent/` needs nothing.
+    const siblings = agentsAt(dir).map((a) => basename(a));
+    if (siblings.length > 1) {
+        const pick = siblings.includes(DEFAULT_AGENT_DIRNAME)
+            ? `\`${DEFAULT_AGENT_DIRNAME}\` answers by default; set FASTAGENT_AGENT=<name> for another`
+            : `set FASTAGENT_AGENT=<name> (in your shell or .envrc) to pick one`;
+        console.error(`[fastagent] note: ${dir} now holds ${siblings.length} agents (${siblings.join(", ")}) — ${pick}`);
     }
-    console.error(`[fastagent] initialized ${dir}${complete ? "" : " (minimal)"}${agentDir ? ` — agent kit in ${agentDir}` : ""}`);
-    if (created.length > 0)
-        console.error(`  created: ${created.join(", ")}`);
-    if (skipped.length > 0)
-        console.error(`  kept existing: ${skipped.join(", ")}`);
-    if (patched.length > 0)
-        console.error(`  updated: ${patched.join(", ")} (missing fastagent excludes appended)`);
-    if (intoNonEmpty && !agentDir) {
-        console.error(`  note: scaffolded flat into a non-empty directory (nothing claims it — the directory is the agent); use --agent-dir <name> to put the kit in a subdir instead`);
+    if (kept.length > 0) {
+        // Adopting a directory: its own files win, always. Say which ones — and for the two that carry a
+        // consequence, say what that consequence is, because keeping them silently leaves the agent broken
+        // (package.json) or its machinery committable (.gitignore).
+        console.error(`  kept your existing: ${kept.join(", ")}`);
+        if (kept.includes(join(rel, "package.json")) && complete) {
+            const add = detectRuntime(agentDir, await readPackageJson(agentDir)).runtime === "bun" ? "bun add" : "npm install";
+            console.error(`[fastagent] note: your package.json is untouched, so it does not list @fastagent-sh/fastagent — ` +
+                `run \`${add} @fastagent-sh/fastagent\` there or the scaffolded tools/ cannot resolve`);
+        }
+        const keptSecretsIgnore = kept.includes(join(rel, SECRETS_DIRNAME, ".gitignore"));
+        if (kept.includes(join(rel, ".gitignore"))) {
+            // The "credentials are covered either way" reassurance holds only when `.secrets/.gitignore` is
+            // OURS. On an adopted directory it may be the author's too, and then we know nothing about it —
+            // `add <channel>` defends that file with a write; `init` must not claim more than it did.
+            console.error(`[fastagent] note: your .gitignore is untouched — make sure it ignores node_modules, .state ` +
+                `and .cache` +
+                (keptSecretsIgnore ? `` : ` (.secrets/ carries its own .gitignore, so credentials are covered either way)`));
+        }
+        if (keptSecretsIgnore) {
+            console.error(`[fastagent] note: your ${join(rel, SECRETS_DIRNAME, ".gitignore")} is untouched — verify it ignores ` +
+                `everything but .env.example, because credentials land in that directory`);
+        }
     }
-    for (const w of warnings)
-        console.error(`[fastagent] warn: ${w}`);
-    // Install deps only for a complete agent whose package.json we just wrote (a kept one is not ours).
-    // The manifest lives with the kit (agentDir when set), so the install runs there — never against a
-    // host repo's own package.json.
-    const kitDir = resolve(dir, agentDir ?? ".");
-    const willInstall = complete && opts.install && created.includes(join(agentDir ?? ".", "package.json"));
+    const willInstall = complete && opts.install && !kept.includes(join(rel, "package.json"));
     let installFailed = false;
     if (willInstall) {
-        console.error(`[fastagent] installing dependencies (npm install${agentDir ? ` in ${agentDir}` : ""})…`);
-        installFailed = (await npmInstall(kitDir)) !== 0;
+        console.error(`[fastagent] installing dependencies (npm install${flat ? "" : ` in ${rel}`})…`);
+        installFailed = (await npmInstall(agentDir)) !== 0;
         if (installFailed)
-            console.error(`[fastagent] warn: npm install failed — run it manually in ${kitDir} before \`fastagent dev\``);
+            console.error(`[fastagent] warn: npm install failed — run it manually in ${agentDir} before \`fastagent dev\``);
     }
     console.error(`  next steps:`);
-    const cdTarget = nextStepCd(process.cwd(), dir);
+    const cdTarget = displayPath(process.cwd(), dir);
     if (cdTarget)
         console.error(`    cd ${cdTarget}`);
-    if (complete && (!opts.install || installFailed))
-        console.error(`    ${agentDir ? `(cd ${agentDir} && npm install)` : "npm install"}`);
+    if (complete && (!willInstall || installFailed)) {
+        console.error(`    ${flat ? "npm install" : `(cd ${rel} && npm install)`}`);
+    }
     console.error(`    fastagent dev   # serve locally and iterate`);
     console.error(`    fastagent add skill <owner/repo/path>   # vendor more skills from GitHub`);
 }

package/dist/cli/commands/invoke.js

@@ -2,21 +2,24 @@
 import { randomUUID } from "node:crypto";
 import { resolve } from "node:path";
 import { loadDotEnv } from "../../env.js";
-import { createPiAgentFromWorkspace } from "../../engines/pi/workspace.js";
+import { createPiAgentFromDir } from "../../engines/pi/open.js";
 import { runInvokeStream } from "../invoke-stream.js";
 import { installProxyFetch } from "../../proxy.js";
-import { failStartup } from "../fail.js";
+import { failStartup, placementOrExit } from "../fail.js";
 import { reportAuth, resolveFirstRunModel } from "../shared.js";
 export async function runInvoke(message, dirArg, opts) {
     const invokeDir = resolve(dirArg);
-    loadDotEnv(invokeDir);
+    const placement = placementOrExit(invokeDir);
+    loadDotEnv(placement.agentDir);
     installProxyFetch();
-    await resolveFirstRunModel(invokeDir, opts);
-    const { agent, modelSpec, authPath } = await createPiAgentFromWorkspace(invokeDir, {
+    await resolveFirstRunModel(placement.agentDir, opts);
+    const { agent, modelSpec, authPath } = await createPiAgentFromDir(invokeDir, {
         model: opts.model,
         authPath: opts.authPath, // flag > FASTAGENT_AUTH_PATH > default — resolved by the opener (one owner)
     }).catch(failStartup);
-    console.error(`[fastagent] invoke: ${invokeDir} (${modelSpec})`);
+    // BOTH directories, like dev/start: from the workspace, `placement.workspace` alone equals the dir you
+    // typed, so it cannot tell you which agent actually ran.
+    console.error(`[fastagent] invoke: ${placement.agentDir} (workspace ${placement.workspace}, ${modelSpec})`);
     await reportAuth(modelSpec, authPath);
     // Fresh session per invoke (one-shot, no resume). runInvokeStream maps events→IO: reply→stdout,
     // tool/failure→stderr, exit 1 iff the turn failed (so CI can gate on it).

package/dist/cli/commands/login.js

@@ -1,39 +1,53 @@
 /**
  * `fastagent login [provider]`: authenticate a model provider into the project-level auth file
- * (`<cwd>/.fastagent/auth.json`) by default, or `--auth-path`/`FASTAGENT_AUTH_PATH`. The positional is
- * the PROVIDER (not a dir), so the project is cwd — `cd` into your agent before logging in (running it
- * from $HOME writes the global `~/.fastagent/auth.json`).
+ * (`<agentDir>/.secrets/auth.json`) by default, or `--auth-path`/`FASTAGENT_AUTH_PATH`. The
+ * positional is the PROVIDER (not a dir), so the agent resolves from cwd — `cd` into your agent
+ * before logging in. OUTSIDE an agent there is no project credential to write, so the target is the
+ * user-global `~/.fastagent/.secrets/auth.json` (which is what running it from $HOME has always
+ * meant) — announced on stderr BEFORE the flow, because that is a different credential than the one
+ * `dev`/`start` in a real agent would read, and a silent scope switch is exactly the surprise this
+ * command must not ship.
  *
- * Creates and self-ignores `<cwd>/.fastagent/` (the credential's gitignored home) BEFORE the auth flow,
- * so the secret can never land untracked — a flow that then fails (bad provider, abort) leaves that
- * empty state dir behind, by design (no secret without its `.gitignore`). Skipped for the HOME-global dir.
+ * fastagent writes no `.gitignore` here or anywhere else at runtime: `init` scaffolds the agent's one
+ * ignore file (covering `.secrets/`) and the author owns it from then on. The credential store creates
+ * its own directory, mode 0700.
  */
+import { homedir } from "node:os";
+import { join } from "node:path";
 import { loadDotEnv } from "../../env.js";
-import { resolveAuthPath, resolveStateRoot } from "../../engines/pi/config.js";
-import { ensureStateRootSelfIgnored, isUnderDir } from "../../engines/pi/definition.js";
+import { resolveAuthPath } from "../../engines/pi/config.js";
+import { GLOBAL_HOME_DIR, findAgentDir, placementDeadEnd } from "../../paths.js";
 import { LoginCancelled } from "../../engines/pi/login.js";
 import { installProxyFetch } from "../../proxy.js";
-import { failStartup } from "../fail.js";
+import { failStartup, placementOrExit } from "../fail.js";
 import { isInteractive, loginWithKeyCheck } from "../shared.js";
 export async function runLogin(provider, opts) {
-    const loginDir = process.cwd();
+    const cwd = process.cwd();
+    const agentDir = findAgentDir(cwd);
+    // "Outside an agent" must mean exactly that: a position with its own way out (inside an agent, or on a
+    // directory holding several) is a dead end every other command refuses, and taking the global fallback
+    // there would write a credential to a different scope under a message saying there is no agent here.
+    if (!agentDir && placementDeadEnd(cwd))
+        placementOrExit(cwd);
+    // Outside any agent the target is the user-global machinery home — handed over explicitly, so the
+    // path resolvers need no "is this $HOME?" special case to infer it.
+    const loginDir = agentDir ?? join(homedir(), GLOBAL_HOME_DIR);
     loadDotEnv(loginDir); // FASTAGENT_AUTH_PATH / a proxy (HTTPS_PROXY) may be configured in the project .env
     installProxyFetch(); // the OAuth token exchange must go through HTTPS_PROXY (region-locked providers)
-    const stateRoot = resolveStateRoot(loginDir);
     const authPath = resolveAuthPath(loginDir, opts.authPath); // flag > FASTAGENT_AUTH_PATH > default — the one owner
-    // login is the command that CREATES the credential file, so the leak guard binds HERE too (not only
-    // in the opener): on an adapted project dir, a `login` before the first dev/start would otherwise
-    // leave the secret untracked-but-committable. Unlike the opener (which populates the WHOLE root, so
-    // it always self-ignores an in-tree root), login writes ONLY auth.json — so guard iff the credential
-    // actually lands under the in-tree root. An external `--auth-path`/`FASTAGENT_AUTH_PATH` writes
-    // nothing in-tree (don't create an empty `.fastagent`); the guard also skips the HOME-global root.
-    if (isUnderDir(authPath, stateRoot))
-        await ensureStateRootSelfIgnored(loginDir, stateRoot);
+    // Announce when the FALLBACK is what decided the target: outside an agent with no explicit path,
+    // the credential lands somewhere no agent will read. An explicit `--auth-path`/FASTAGENT_AUTH_PATH
+    // is the user naming the file, so there is no surprise to announce (and announcing a path this run
+    // does not write would be worse than saying nothing). The resolved path goes in the message.
+    if (!agentDir && !opts.authPath && !process.env.FASTAGENT_AUTH_PATH) {
+        console.error(`[fastagent] no agent here (no fastagent.config.*, here or one level inside) — ` +
+            `logging in GLOBALLY (${authPath}). An agent reads its own .secrets/auth.json: \`cd\` into one ` +
+            `first, or point this run at it with --auth-path.`);
+    }
     // login is inherently interactive — loginFlow renders provider/method menus and opens a browser (or
     // prompts for a key). In a non-TTY (a pipe, CI, a coding-agent shell) the menu can't receive keystrokes
     // and would hang; --no-input asks for the same posture explicitly. Fail fast with the reason instead
-    // of stalling on an unanswerable prompt. (After the secret-hygiene self-ignore above, which is cheap
-    // prep, so a later terminal login is safe.)
+    // of stalling on an unanswerable prompt.
     if (opts.input === false || !isInteractive()) {
         failStartup(new Error(`login is interactive (it shows a menu and opens a browser) — run it in a terminal, not a pipe/CI`));
     }

package/dist/cli/commands/schedule.js

@@ -5,20 +5,20 @@
  */
 import { resolve } from "node:path";
 import { loadDotEnv } from "../../env.js";
-import { loadConfig, resolveAgentDir, resolveStateRoot } from "../../engines/pi/config.js";
+import { resolveStateRoot } from "../../paths.js";
 import { reportModuleLoadFailures } from "../../engines/pi/report.js";
 import { readRuns } from "../../schedule/audit.js";
 import { nextRun } from "../../schedule/cron.js";
 import { loadSchedules } from "../../schedule/discover.js";
 import { listWakeups, removeWakeup } from "../../schedule/wakeups.js";
-import { failStartup } from "../fail.js";
+import { failStartup, placementOrExit } from "../fail.js";
 /**
  * `fastagent schedule history <name> [dir]`: print the run audit for one schedule (or "wake") — fired
  * time, outcome, duration, reply/error. Read-only (reads `<stateRoot>/schedule/runs.jsonl`); the answer
  * to "did last night's run silently fail?". Text mode previews the reply/error; --json is the full record.
  */
 export function runScheduleHistory(name, dirArg, json) {
-    const target = resolve(dirArg);
+    const { agentDir: target } = placementOrExit(resolve(dirArg));
     loadDotEnv(target); // FASTAGENT_STATE_DIR may live in .env — read the SAME state root the scheduler wrote
     const runs = readRuns(resolveStateRoot(target), name);
     if (json) {
@@ -45,11 +45,9 @@ export function runScheduleHistory(name, dirArg, json) {
 /** `fastagent schedule list [dir]`: everything that will fire — BOTH producers: the static `schedules/`
  *  files (with their next instant) and the agent's pending self-scheduled wake-ups. Read-only. */
 export async function runScheduleList(dirArg, json) {
-    const target = resolve(dirArg);
+    const { agentDir: target } = placementOrExit(resolve(dirArg));
     loadDotEnv(target);
-    const { config } = await loadConfig(target).catch(failStartup);
-    const agentDir = resolveAgentDir(target, config);
-    const { schedules, failures } = await loadSchedules(agentDir).catch(failStartup);
+    const { schedules, failures } = await loadSchedules(target).catch(failStartup);
     reportModuleLoadFailures(failures);
     const wakeups = listWakeups(resolveStateRoot(target));
     if (json) {
@@ -75,7 +73,7 @@ export async function runScheduleList(dirArg, json) {
 /** `fastagent schedule cancel <id> [dir]`: remove a pending wake-up — the operator's kill switch (the
  *  agent's own is the `unwake` tool). Unlike unwake it is NOT session-scoped: the operator owns the box. */
 export function runScheduleCancel(id, dirArg) {
-    const target = resolve(dirArg);
+    const { agentDir: target } = placementOrExit(resolve(dirArg));
     loadDotEnv(target);
     if (removeWakeup(resolveStateRoot(target), id)) {
         // ponytail: the store's load→save is lock-free — a serving scheduler's claim-advance can race this

package/dist/cli/commands/start.d.ts

@@ -1,5 +1,6 @@
 export interface StartOptions {
     port?: string;
+    bind?: string;
     model?: string;
     sessionsDir?: string;
     authPath?: string;