@fastagent-sh/fastagent 0.21.1 → 0.22.1

package/dist/cli/commands/init.js

@@ -1,38 +1,25 @@
-/**
- * `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).
- */
+/** `fastagent init [dir]`: scaffold a runnable agent and install its dependencies. */
 import { spawn } from "node:child_process";
-import { basename, join, resolve } from "node:path";
-import { DEFAULT_AGENT_DIRNAME, SECRETS_DIRNAME, agentsAt, displayPath } from "../../paths.js";
-import { detectRuntime, readPackageJson } from "../../runtime.js";
+import { basename, resolve } from "node:path";
+import { DEFAULT_AGENT_DIRNAME, agentsAt, displayPath } from "../../paths.js";
 import { agentDirName, agentDirNameError, scaffoldAgent } from "../../scaffold/init.js";
 import { failStartup, failUsage } from "../fail.js";
 export async function runInit(dirArg, opts) {
     const dir = resolve(dirArg);
-    // 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).
+    // A rejected flag VALUE is the usage class, same as one the parser rejects.
     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: requested,
-    }).catch(failStartup);
-    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: rel, created } = await scaffoldAgent(dir, { agentDir: requested }).catch(failStartup);
+    // The agent dir is where the manifest lives, so the install runs there — never against a surrounding workspace's
+    // package.json (its deps are its own concern).
     const agentDir = resolve(dir, rel);
-    console.error(`[fastagent] initialized ${dir}${complete ? "" : " (minimal)"} — ${flat ? "the directory IS the agent" : `agent in ./${rel}/`}`);
+    console.error(`[fastagent] initialized ${dir} — 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.
+    // 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.
     const siblings = agentsAt(dir).map((a) => basename(a));
     if (siblings.length > 1) {
         const pick = siblings.includes(DEFAULT_AGENT_DIRNAME)
@@ -40,34 +27,9 @@ export async function runInit(dirArg, opts) {
             : `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}`);
     }
-    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`);
-        }
-    }
-    const willInstall = complete && opts.install && !kept.includes(join(rel, "package.json"));
     let installFailed = false;
-    if (willInstall) {
-        console.error(`[fastagent] installing dependencies (npm install${flat ? "" : ` in ${rel}`})…`);
+    if (opts.install) {
+        console.error(`[fastagent] installing dependencies (npm install in ${rel})…`);
         installFailed = (await npmInstall(agentDir)) !== 0;
         if (installFailed)
             console.error(`[fastagent] warn: npm install failed — run it manually in ${agentDir} before \`fastagent dev\``);
@@ -76,13 +38,12 @@ export async function runInit(dirArg, opts) {
     const cdTarget = displayPath(process.cwd(), dir);
     if (cdTarget)
         console.error(`    cd ${cdTarget}`);
-    if (complete && (!willInstall || installFailed)) {
-        console.error(`    ${flat ? "npm install" : `(cd ${rel} && npm install)`}`);
-    }
+    if (!opts.install || installFailed)
+        console.error(`    (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`);
 }
-/** Run `npm install` in `cwd` (inherit stdio). Returns the exit code. */
+/** Run `npm install` in `cwd` (inherit stdio). */
 function npmInstall(cwd) {
     return new Promise((resolveCode) => {
         const child = spawn("npm", ["install"], { cwd, stdio: "inherit" });

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

@@ -1,6 +1,5 @@
 export interface InvokeOptions {
     model?: string;
-    authPath?: string;
     /** false ⇔ `--no-input`. */
     input?: boolean;
 }

package/dist/cli/commands/invoke.js

@@ -6,19 +6,17 @@ import { failStartup } from "../fail.js";
 import { enterAgentCommand, reportAuth } from "../shared.js";
 export async function runInvoke(message, dirArg, opts) {
     const placement = await enterAgentCommand(dirArg, opts);
-    const { agent, modelSpec, authPath } = await createPiAgentFromDir(placement.workspace, {
+    const { agent, modelSpec, auth } = await createPiAgentFromDir(placement.agentDir, {
         model: opts.model,
-        authPath: opts.authPath, // flag > FASTAGENT_AUTH_PATH > default — resolved by the opener (one owner)
     }).catch(failStartup);
-    // 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.
+    // BOTH directories, like dev/start: which agent ran, and what it worked on.
     console.error(`[fastagent] invoke: ${placement.agentDir} (workspace ${placement.workspace}, ${modelSpec})`);
-    await reportAuth(placement.agentDir, modelSpec, authPath);
+    await reportAuth(placement.agentDir, modelSpec, auth);
     // 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).
     const exitCode = await runInvokeStream(agent.invoke({ session: randomUUID() }, { text: message }), (text) => process.stdout.write(text), (line) => console.error(line));
     process.stdout.write("\n");
-    // Always exit explicitly: the undici proxy agent's keep-alive sockets would otherwise hold the
-    // event loop open after a successful one-shot turn.
+    // Always exit explicitly: the undici proxy agent's keep-alive sockets would otherwise hold the event loop open
+    // after a successful one-shot turn.
     process.exit(exitCode);
 }

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

@@ -1,5 +1,6 @@
 export interface LoginOptions {
-    authPath?: string;
+    /** `-g`: store in the user-global file every agent on this machine falls back to. */
+    global?: boolean;
     /** false ⇔ `--no-input`. */
     input?: boolean;
 }

package/dist/cli/commands/login.js

@@ -1,59 +1,54 @@
 /**
  * `fastagent login [provider]`: authenticate a model provider into the project-level auth file
- * (`<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.
- *
- * 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.
+ * (`<agentDir>/.secrets/auth.json`) by default, or `FASTAGENT_AUTH_PATH`.
  */
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { loadDotEnv } from "../../env.js";
+import { enterAgentEnv } from "../../env.js";
 import { resolveAuthPath } from "../../engines/pi/config.js";
+import { GLOBAL_AUTH_PATH } from "../../engines/pi/auth.js";
 import { GLOBAL_HOME_DIR, findAgentDir, placementDeadEnd } from "../../paths.js";
-import { LoginCancelled } from "../../engines/pi/login.js";
-import { installProxyFetch } from "../../proxy.js";
+import { LoginCancelled, loginFlow } from "../../engines/pi/login.js";
 import { failStartup, placementOrExit } from "../fail.js";
-import { isInteractive, loginWithKeyCheck } from "../shared.js";
+import { isInteractive, terminalLoginIO } from "../shared.js";
 export async function runLogin(provider, opts) {
     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.
+    // "Outside an agent" must mean exactly that.
     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.
+    // 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 authPath = resolveAuthPath(loginDir, opts.authPath); // flag > FASTAGENT_AUTH_PATH > default — the one owner
-    // 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.`);
+    // FASTAGENT_AUTH_PATH and a proxy may both be configured in the project .env, and the OAuth token exchange must go
+    // through that proxy (region-locked providers).
+    enterAgentEnv(loginDir);
+    // `-g` names the global file outright. Otherwise: FASTAGENT_AUTH_PATH > default — the one owner. The
+    // store built here is deliberately UNLAYERED: reading falls back to the global file, but writing must land
+    // exactly where the operator said, or a second `login` for a provider they already have globally would silently
+    // rewrite the global credential instead of creating the project-level override they asked for.
+    const authPath = opts.global ? GLOBAL_AUTH_PATH : resolveAuthPath(loginDir);
+    // Announce when the FALLBACK is what decided the target: outside an agent with no explicit path, the credential
+    // lands somewhere no agent will read.
+    if (!agentDir && !opts.global && !process.env.FASTAGENT_AUTH_PATH) {
+        console.error(`[fastagent] no agent here (no fastagent.config.ts, here or one level inside) — ` +
+            `logging in GLOBALLY (${authPath}). Every agent on this machine reads this file for providers its own ` +
+            `.secrets/auth.json does not have, so this is usually what you want; \`cd\` into an agent to give that ` +
+            `one its own account instead.`);
     }
-    // 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.
+    // login is inherently interactive — loginFlow renders provider/method menus and opens a browser (or prompts for a
+    // key).
     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`));
     }
-    // loginWithKeyCheck: an entered API key is verified with one minimal request; a rejected key (401)
-    // re-prompts in place, so a returned result is always a stored-and-not-definitively-bad credential.
-    const result = await loginWithKeyCheck(provider, authPath).catch((error) => {
+    // An entered API key is verified with one minimal request (login.ts); a rejected one is asked for again.
+    // Inside an agent, the key is checked on that agent's registry: its models.json may point a provider at a gateway.
+    // Not with `-g`: the global file serves every agent on the machine, so no one agent's routing may judge its key.
+    const result = await loginFlow(terminalLoginIO(), {
+        authPath,
+        ...(provider ? { provider } : {}),
+        ...(agentDir && !opts.global ? { agentDir } : {}),
+    }).catch((error) => {
         if (error instanceof LoginCancelled) {
             // A decision, not a failure — neutral wording; non-zero exit because no credential was stored.
             console.error(`[fastagent] login cancelled`);

package/dist/cli/commands/logs.js

@@ -3,15 +3,14 @@ import { basename, resolve } from "node:path";
 import { agentcoreName } from "../../deploy/agentcore/plan.js";
 import { tailAgentcoreLogs } from "../../deploy/agentcore/logs.js";
 import { spawnRunner } from "../../deploy/runner.js";
-import { loadDotEnv } from "../../env.js";
+import { enterAgentEnv } from "../../env.js";
 import { failStartup, failUsage, placementOrExit } from "../fail.js";
 export async function runLogs(host, dirArg, opts) {
-    // The host argument is DISPATCHED here, as in runDeploy — the parser's `choices` happens to have a
-    // single member today, and a future second host must land on its own reader, not silently on this one.
+    // The host argument is DISPATCHED here, as in runDeploy.
     if (host !== "agentcore")
         failUsage(`logs: unsupported host "${host}" — only agentcore has remote logs`);
     const placement = placementOrExit(resolve(dirArg));
-    loadDotEnv(placement.agentDir); // AWS_PROFILE/region/proxy may be definition-local, as on deploy
+    enterAgentEnv(placement.agentDir); // AWS_PROFILE/region/proxy may be definition-local, as on deploy
     const source = opts.source ?? "runtime";
     if (source !== "runtime" && source !== "forwarder") {
         failUsage(`logs: --source must be "runtime" or "forwarder"`);

package/dist/cli/commands/models.js

@@ -1,8 +1,4 @@
-/**
- * `fastagent models [search]`: print every registered "provider/modelId"; `[search]` filters by
- * substring. This module pulls the pi model catalog (heavy) — it is lazy-imported by the spec, so
- * only an actual `models` invocation pays for it.
- */
+/** `fastagent models [search]`: print every registered "provider/modelId"; `[search]` filters by substring. */
 import { formatModelsCommand } from "../models-view.js";
 import { listModels } from "../../engines/pi/config.js";
 import { createPiModels } from "../../engines/pi/models.js";

package/dist/cli/commands/routine-run.d.ts

@@ -0,0 +1,6 @@
+export interface RoutineRunOptions {
+    model?: string;
+    /** false ⇔ `--no-input`. */
+    input?: boolean;
+}
+export declare function runRoutine(name: string, dirArg: string, opts: RoutineRunOptions): Promise<void>;

package/dist/cli/commands/routine-run.js

@@ -0,0 +1,47 @@
+/**
+ * `fastagent routine run <name> [dir]`: run ONE routine's turn immediately — the authoring loop for routines (like
+ * `invoke` is for a prompt). Cron or not: a routine that declares none has no other local entry.
+ */
+import { join } from "node:path";
+import { displayPath } from "../../paths.js";
+import { reportModuleLoadFailures } from "../../loader.js";
+import { createPiAgentFromDir } from "../../engines/pi/open.js";
+import { runInvokeStream } from "../invoke-stream.js";
+import { loadRoutines } from "../../schedule/discover.js";
+import { routineSession } from "../../schedule/routine.js";
+import { failStartup, gateSecretsOrExit } from "../fail.js";
+import { enterAgentCommand, reportAuth } from "../shared.js";
+export async function runRoutine(name, dirArg, opts) {
+    const placement = await enterAgentCommand(dirArg, opts);
+    // Routines are agent surface — discovered where dev/start/`routine list` do (the agent dir), so this command
+    // sees the same set the clock serves.
+    const { routines, secrets, failures } = await loadRoutines(placement.agentDir).catch(failStartup);
+    // Reported BEFORE the name is looked up: a routine file that failed to import is missing from
+    // `routines`, so "unknown routine" is the case where the author most needs to hear about it.
+    reportModuleLoadFailures(failures);
+    const routine = routines.find((r) => r.name === name);
+    if (!routine) {
+        // 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 routine "${name}" (looked in ${displayPath(process.cwd(), join(placement.agentDir, "routines")) ?? "routines"}). ` +
+            `available: ${routines.map((r) => r.name).join(", ") || "(none)"}`));
+    }
+    // This RUNS the routine, so it takes the serving path's guarantee: a prompt built from an
+    // unset declared value is the degraded turn this feature exists to prevent (`Post the digest to `
+    // — sent and executed), and the loader resolved it into a string before anything could notice.
+    // THIS schedule only (`owner`): running one routine must not fail because a SIBLING ROUTINE needs a
+    // credential this machine has no reason to hold. The agent assembled below is a different question
+    // and gates every mounted tool — a run's turn can call any of them — so this command is not free of a
+    // tool's declaration, only of another routine's. The failures go to the gate too, even though they
+    // were printed above: its guarantee must not depend on this call site remembering (a repeated line
+    // on the refusal path is the cheaper failure).
+    gateSecretsOrExit({ declared: secrets, failures, owner: name });
+    const { agent, modelSpec, auth } = await createPiAgentFromDir(placement.agentDir, {
+        model: opts.model,
+    }).catch(failStartup);
+    console.error(`[fastagent] routine run: ${name} (${modelSpec})`);
+    await reportAuth(placement.agentDir, modelSpec, auth);
+    const exitCode = await runInvokeStream(agent.invoke({ session: routineSession(name) }, { text: routine.prompt }), (text) => process.stdout.write(text), (line) => console.error(line));
+    process.stdout.write("\n");
+    process.exit(exitCode);
+}

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

@@ -0,0 +1,25 @@
+/**
+ * `fastagent routine history <name> [dir]`: print this routine's fired slots — when each fired, how it ended, how
+ * long it took.
+ *
+ * The history IS the claims (`schedule/claims/<name>/`), so it is bounded by construction and carries no turn text:
+ * what the run SAID is in its session (`routine:<name>`), stored once, like any other turn's, under the state
+ * root's `sessions/` — which is where this command points rather than copying any of it here.
+ *
+ * This command does NOT try to say which turn belongs to which fire. Nothing links them: a routine's fires share
+ * ONE continuing conversation, so the session id is the same for all of them, and the turn-level identifier would
+ * have to cross the engine-neutral contract (no `AgentEvent` carries an entry id) or cost the shared conversation.
+ * A claim's timestamp against a time-ordered journal is what an operator reads anyway — matching them HERE only
+ * moves a human's judgement into a heuristic that cannot be right about a session other writers also append to.
+ */
+export declare function runRoutineHistory(name: string, dirArg: string, json: boolean): void;
+/**
+ * `fastagent routine list [dir]`: every declared routine, and when (or whether) a clock fires it.
+ *
+ * IT ALSO READS the agent's pending wake-ups. They are a different owner (the state, not the definition) but the
+ * same question when an operator is asking it: "what is going to wake this agent up?". Deleting the command that
+ * CANCELLED one was right — `unwake({ id })` covers it, and a serve that can receive the alarm can also be spoken
+ * to — but that argument is about WRITING. Without a read, the only way to learn why an agent wakes at 3am is to
+ * open `<stateRoot>/schedule/wakeups.json` by hand.
+ */
+export declare function runRoutineList(dirArg: string, json: boolean): Promise<void>;

package/dist/cli/commands/routine.js

@@ -0,0 +1,122 @@
+/**
+ * `fastagent routine history|list` — the routines this DEFINITION declares.
+ *
+ * The agent's own pending wake-ups are not here and have no command: they live in the state, not the definition,
+ * and `unwake({ id })` is what cancels one (schedule/wakeups.ts says why).
+ */
+import { resolve } from "node:path";
+import { enterAgentEnv } from "../../env.js";
+import { resolveSessionsDir, resolveStateRoot } from "../../paths.js";
+import { reportModuleLoadFailures } from "../../loader.js";
+import { nextRun } from "../../schedule/cron.js";
+import { loadRoutines } from "../../schedule/discover.js";
+import { routineSession } from "../../schedule/routine.js";
+import { isSafeScheduleName, readFires } from "../../schedule/state.js";
+import { listWakeups } from "../../schedule/wakeups.js";
+import { failStartup, placementOrExit } from "../fail.js";
+/**
+ * `fastagent routine history <name> [dir]`: print this routine's fired slots — when each fired, how it ended, how
+ * long it took.
+ *
+ * The history IS the claims (`schedule/claims/<name>/`), so it is bounded by construction and carries no turn text:
+ * what the run SAID is in its session (`routine:<name>`), stored once, like any other turn's, under the state
+ * root's `sessions/` — which is where this command points rather than copying any of it here.
+ *
+ * This command does NOT try to say which turn belongs to which fire. Nothing links them: a routine's fires share
+ * ONE continuing conversation, so the session id is the same for all of them, and the turn-level identifier would
+ * have to cross the engine-neutral contract (no `AgentEvent` carries an entry id) or cost the shared conversation.
+ * A claim's timestamp against a time-ordered journal is what an operator reads anyway — matching them HERE only
+ * moves a human's judgement into a heuristic that cannot be right about a session other writers also append to.
+ */
+export function runRoutineHistory(name, dirArg, json) {
+    const { agentDir: target } = placementOrExit(resolve(dirArg));
+    enterAgentEnv(target); // FASTAGENT_STATE_DIR may live in .env — read the SAME state root the scheduler wrote
+    const stateRoot = resolveStateRoot(target);
+    // A name that cannot be a routine is a MISTYPED ARGUMENT, and it must not look like an empty history: exit 1 the
+    // way every other user-input refusal does, so `--json` printing nothing is never read as "the command succeeded".
+    if (!isSafeScheduleName(name)) {
+        failStartup(new Error(`"${name}" cannot be a routine name (no path separators, "." or "..")`));
+    }
+    // `readFires` throws a raw fs error on unreadable state, because its other caller is the serving boot, which must
+    // fail rather than arm a schedule it cannot read. This caller is a read-only CLI command: the same fact is an
+    // operator's to fix, so it exits the way every other refusal in this file does instead of printing a Node stack.
+    let fires;
+    try {
+        fires = readFires(stateRoot, name);
+    }
+    catch (e) {
+        failStartup(new Error(`the fired-slot claims for "${name}" are unreadable (state: ${stateRoot}): ${String(e)}`));
+    }
+    if (json) {
+        console.log(JSON.stringify(fires, null, 2));
+        return;
+    }
+    if (fires.length === 0) {
+        // No special case for "wake": it is an ordinary schedule name now (`discover.ts` stopped reserving it).
+        console.error(`no recorded fires for "${name}" (state: ${stateRoot})`);
+        return;
+    }
+    // The question is "did LAST NIGHT's run fail?", so text mode tails the most recent fires; --json above is the
+    // whole retained window.
+    const TAIL = 20;
+    const shown = fires.slice(-TAIL);
+    for (const f of shown) {
+        // An unreported fire has no duration to print, and `0ms` would be a value a fast turn really produces — the
+        // column stays empty rather than claiming the turn took no time.
+        const took = f.ms === undefined ? "" : `${f.ms}ms`;
+        console.log(`${f.firedAt}  ${(f.outcome ?? "unreported").padEnd(11)} ${took.padStart(8)}`);
+    }
+    if (fires.length > shown.length) {
+        console.error(`(the last ${shown.length} of ${fires.length} fires — --json for all)`);
+    }
+    // The other half of the answer, and where it lives: these rows say a fire happened, not what it produced. The
+    // session id comes from the ONE place that spells it and the directory from the ONE place that resolves it. The
+    // record is one level further down and under a name pi accepts (`piSessionId` escapes the `:`), so the pointer
+    // says how to recognise the file rather than claiming a path the reader can paste.
+    console.error(`(what these runs said: session ${routineSession(name)} — a JSON-lines journal under ${resolveSessionsDir(target)}, ` +
+        `in the file whose name carries "${name}")`);
+}
+/**
+ * `fastagent routine list [dir]`: every declared routine, and when (or whether) a clock fires it.
+ *
+ * IT ALSO READS the agent's pending wake-ups. They are a different owner (the state, not the definition) but the
+ * same question when an operator is asking it: "what is going to wake this agent up?". Deleting the command that
+ * CANCELLED one was right — `unwake({ id })` covers it, and a serve that can receive the alarm can also be spoken
+ * to — but that argument is about WRITING. Without a read, the only way to learn why an agent wakes at 3am is to
+ * open `<stateRoot>/schedule/wakeups.json` by hand.
+ */
+export async function runRoutineList(dirArg, json) {
+    const { agentDir: target } = placementOrExit(resolve(dirArg));
+    enterAgentEnv(target);
+    const { routines, failures } = await loadRoutines(target).catch(failStartup);
+    reportModuleLoadFailures(failures);
+    const wakeups = listWakeups(resolveStateRoot(target));
+    if (json) {
+        console.log(JSON.stringify({
+            routines: routines.map((r) => ({
+                ...r,
+                next: r.cron === undefined ? null : (nextRun(r.cron, r.tz, new Date())?.toISOString() ?? null),
+            })),
+            wakeups,
+        }, null, 2));
+        return;
+    }
+    if (routines.length === 0 && wakeups.length === 0) {
+        console.error(`nothing declared or pending — no routines/ files, no wake-ups (agent: ${target})`);
+        return;
+    }
+    for (const r of routines) {
+        // A routine with no cron is not broken and not idle: it is reached by NAME (`routine run`, `POST /run`), and
+        // saying "on demand" is the difference between that and a cron that will never fire again.
+        const when = r.cron === undefined
+            ? "on demand".padEnd(26)
+            : `${(nextRun(r.cron, r.tz, new Date())?.toISOString() ?? "(never)").padEnd(26)}cron ${r.cron}${r.tz ? ` ${r.tz}` : ""}`;
+        console.log(`${r.name.padEnd(20)} ${when}`);
+    }
+    // Labelled, because these two are NOT the same kind of thing: a routine is the author's, a wake-up is the
+    // agent's own and is cancelled with `unwake` rather than a command here.
+    for (const w of wakeups) {
+        const kind = w.cron ? `cron ${w.cron}${w.tz ? ` ${w.tz}` : ""}` : "one-shot";
+        console.log(`wake ${w.id}  ${w.fireAt}  ${kind}  session=${w.session}  ${w.prompt.slice(0, 60)}`);
+    }
+}

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

@@ -1,11 +1,39 @@
+import { type AgentService } from "../../service.ts";
 export interface StartOptions {
     port?: string;
     bind?: string;
     model?: string;
-    sessionsDir?: string;
-    authPath?: string;
     tunnel?: boolean;
-    /** false ⇔ `--no-input`. */
+    /** false ⇔ `--no-invoke`: withhold `POST /invoke` for THIS run (`http.invoke` is the persistent form). */
+    invoke?: boolean;
     input?: boolean;
 }
+type StartedService = AgentService & {
+    stateRoot: string;
+    port: number;
+};
 export declare function runStart(dirArg: string, opts: StartOptions): Promise<void>;
+/** What the storage stage hands the opening stage. */
+export interface PreparedWorkspace {
+    /** The workspace to open — the volume's `base/` when a release manifest selected one. */
+    dir: string;
+    /** Set when this process took a deployed workspace. */
+    deployed?: {
+        root: string;
+        agent: string;
+    };
+}
+/**
+ * Stage one — TAKE the workspace: verify the storage is mounted, apply the release, and point the machinery at the
+ * volume.
+ */
+export declare function prepareStartWorkspace(dirArg: string): Promise<PreparedWorkspace>;
+/**
+ * Stage two — RUN in the prepared workspace: install the agent's dependencies, then open through the workspace's own
+ * FastAgent install.
+ */
+export declare function openPreparedWorkspace(prepared: PreparedWorkspace, opts: StartOptions): Promise<StartedService>;
+export declare function openStartService(dirArg: string, opts: StartOptions): Promise<StartedService>;
+/** Internal entry loaded from the active workspace's installed package after storage initialization. */
+export declare function openPreparedStartService(dirArg: string, opts: StartOptions): Promise<StartedService>;
+export {};