@fastagent-sh/fastagent 0.19.0 → 0.21.0

package/dist/cli/commands/dev.js

@@ -3,38 +3,23 @@
  * 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 { reportFindingsIfChanged, reportToolCollisions } from "../../engines/pi/report.js";
-import { reportModuleLoadFailures } from "../../log.js";
-import { CODING_TOOL_NAMES } from "../../engines/pi/create.js";
+import { setLogLevel } from "../../log.js";
 import { createPiAgentFromDir } from "../../engines/pi/open.js";
 import { mountAgentService } from "../../service.js";
-import { setLogLevel } from "../../log.js";
 import { logAgentLoop } from "../../observe.js";
-import { installProxyFetch } from "../../proxy.js";
-import { workspaceHint } from "../../paths.js";
-import { bindAddress } from "../../bind.js";
-import { failStartup, placementOrExit } from "../fail.js";
-import { SHUTDOWN_GRACE_MS, assertTunnelBindable, maybeTunnel, reportServing, serve } from "../serve.js";
-import { parseBind, parsePort, reportAuth, reportLine, resolveFirstRunModel, reportWorkspaceHint } from "../shared.js";
+import { failStartup } from "../fail.js";
+import { assertTunnelBindable, cliMountOptions, resolveBindHost, serveService } from "../serve.js";
+import { enterAgentCommand, parseBind, parsePort, reportAssembly } 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
-    // watch worker inherits the choice via FASTAGENT_MODEL, so it must not prompt again. Load .env and
-    // 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(placement.agentDir);
-        installProxyFetch();
-        await resolveFirstRunModel(placement.agentDir, opts);
-    }
+    // The model is picked ONCE, in the parent process (a TTY; watch and --no-watch both); a spawned
+    // worker inherits the choice through FASTAGENT_MODEL and must not prompt even when the pick was
+    // cancelled.
+    const placement = await enterAgentCommand(dirArg, { ...opts, input: isWorker ? false : opts.input });
     if (isWorker || opts.watch === false) {
-        await serveOnce(dir, opts);
+        await serveOnce(placement, opts);
         return;
     }
     parsePort(opts.port, "--port", "flag"); // flag-shape checks before spawning
@@ -44,64 +29,23 @@ export async function runDev(dirArg, opts) {
     await runDevSupervisor(placement, { tunnel: opts.tunnel ?? false });
 }
 /** Assemble the agent and serve it once (the dev worker; also the --no-watch path). */
-async function serveOnce(dir, opts) {
+async function serveOnce(placement, opts) {
     const portFlag = parsePort(opts.port, "--port", "flag");
     const bindFlag = parseBind(opts.bind);
-    loadDotEnv(placementOrExit(dir).agentDir);
-    installProxyFetch();
-    const a = await createPiAgentFromDir(dir, {
+    const tunnel = opts.tunnel ?? false;
+    const a = await createPiAgentFromDir(placement.workspace, {
         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);
-    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.agentDir, 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.
-    // `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");
+    // The same report `start` prints; `config:` is dev's own extra (see reportAssembly on the asymmetry).
+    await reportAssembly(a, { beforeModel: [["config", a.configPath ?? "(none)"]] });
+    const host = resolveBindHost(bindFlag, a.config.http?.host, tunnel);
     // The SAME assembly an embedder gets from `createAgentService` — channels, control plane,
     // schedules, long connections. `dev` opens the directory itself only because its startup report
-    // prints the opened values before anything mounts.
-    const service = await mountAgentService(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.
-        wrapAgent: logAgentLoop,
-        closeTimeoutMs: SHUTDOWN_GRACE_MS,
-        control: { tunnel: opts.tunnel ?? false, ...(host !== undefined ? { host } : {}) },
-        onChannelClosed: (name, error) => failStartup(new Error(`${name} ${error === undefined ? "closed unexpectedly" : `failed: ${String(error)}`}`)),
-    }).catch(failStartup);
-    serve(service.handler, { port: portFlag ?? a.config.http?.port ?? 8787, host }, {
-        ready: service.ready,
-        onListening: (p) => {
-            reportServing(service, host, p);
-            service.announce(p);
-            maybeTunnel(a.agentDir, service.channels.routes, p, opts.tunnel ?? false, a.stateRoot);
-        },
-        onShutdown: () => service.close(),
-    });
-}
-/** The agents/skills/tools/collisions report lines. */
-function reportAgentsSkillsTools(a) {
-    reportLine("context", a.definition.contextFiles.map((f) => f.path).join(", ") || "(none)");
-    if (a.definition.persona)
-        reportLine("persona", "persona.md");
-    reportLine("skills", a.definition.skills.map((s) => s.name).join(", ") || "(none)");
-    reportLine("codingTools", CODING_TOOL_NAMES.join(", "));
-    if (a.toolNames.length > 0)
-        reportLine("tools", a.toolNames.join(", "));
-    if (a.deferredToolNames.length > 0) {
-        reportLine("deferred", `${a.deferredToolNames.join(", ")} (activated via search_tools)`);
-    }
-    reportToolCollisions(a.toolCollisions);
-    reportModuleLoadFailures(a.toolFailures);
-    reportFindingsIfChanged(a.definition.dir, a.definition);
+    // prints the opened values before anything mounts. The turn trace (tool calls + reply) logs at
+    // debug level: shown here, gated out in start (level info), keeping end-user content out of
+    // production logs.
+    const service = await mountAgentService(a, cliMountOptions(logAgentLoop)).catch(failStartup);
+    serveService(service, { port: portFlag ?? a.config.http?.port ?? 8787, host }, { tunnel, agentDir: a.agentDir, stateRoot: a.stateRoot });
 }

package/dist/cli/commands/fire.js

@@ -4,23 +4,17 @@
  * 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 { join, resolve } from "node:path";
-import { loadDotEnv } from "../../env.js";
+import { join } from "node:path";
 import { displayPath } from "../../paths.js";
-import { reportModuleLoadFailures } from "../../log.js";
+import { reportModuleLoadFailures } from "../../loader.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, placementOrExit } from "../fail.js";
-import { reportAuth, resolveFirstRunModel } from "../shared.js";
+import { failStartup } from "../fail.js";
+import { enterAgentCommand, reportAuth } from "../shared.js";
 export async function runFire(name, dirArg, opts) {
-    const fireDir = resolve(dirArg);
-    const placement = placementOrExit(fireDir);
-    loadDotEnv(placement.agentDir);
-    installProxyFetch();
-    await resolveFirstRunModel(placement.agentDir, opts);
+    const placement = await enterAgentCommand(dirArg, 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);
@@ -32,7 +26,7 @@ export async function runFire(name, dirArg, opts) {
         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 createPiAgentFromDir(fireDir, {
+    const { agent, modelSpec, authPath } = await createPiAgentFromDir(placement.workspace, {
         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

@@ -8,8 +8,8 @@ import { resolveStateRoot, workspaceHint } from "../../paths.js";
 import { CODING_TOOL_NAMES, resolveAgentTools } from "../../engines/pi/create.js";
 import { loadAgentDefinition } from "../../engines/pi/definition.js";
 import { reportFindingsIfChanged, reportToolCollisions } from "../../engines/pi/report.js";
-import { reportModuleLoadFailures } from "../../log.js";
 import { log } from "../../log.js";
+import { reportModuleLoadFailures } from "../../loader.js";
 import { nextRun } from "../../schedule/cron.js";
 import { loadSchedules } from "../../schedule/discover.js";
 import { failStartup, placementOrExit } from "../fail.js";

package/dist/cli/commands/init.js

@@ -7,10 +7,9 @@
  */
 import { spawn } from "node:child_process";
 import { basename, join, resolve } from "node:path";
-import { DEFAULT_AGENT_DIRNAME, SECRETS_DIRNAME, agentsAt } from "../../paths.js";
+import { DEFAULT_AGENT_DIRNAME, SECRETS_DIRNAME, agentsAt, displayPath } 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);

package/dist/cli/commands/invoke.js

@@ -1,19 +1,12 @@
 /** `fastagent invoke <message> [dir]`: run ONE turn against the assembled agent, then exit. */
 import { randomUUID } from "node:crypto";
-import { resolve } from "node:path";
-import { loadDotEnv } from "../../env.js";
 import { createPiAgentFromDir } from "../../engines/pi/open.js";
 import { runInvokeStream } from "../invoke-stream.js";
-import { installProxyFetch } from "../../proxy.js";
-import { failStartup, placementOrExit } from "../fail.js";
-import { reportAuth, resolveFirstRunModel } from "../shared.js";
+import { failStartup } from "../fail.js";
+import { enterAgentCommand, reportAuth } from "../shared.js";
 export async function runInvoke(message, dirArg, opts) {
-    const invokeDir = resolve(dirArg);
-    const placement = placementOrExit(invokeDir);
-    loadDotEnv(placement.agentDir);
-    installProxyFetch();
-    await resolveFirstRunModel(placement.agentDir, opts);
-    const { agent, modelSpec, authPath } = await createPiAgentFromDir(invokeDir, {
+    const placement = await enterAgentCommand(dirArg, opts);
+    const { agent, modelSpec, authPath } = await createPiAgentFromDir(placement.workspace, {
         model: opts.model,
         authPath: opts.authPath, // flag > FASTAGENT_AUTH_PATH > default — resolved by the opener (one owner)
     }).catch(failStartup);

package/dist/cli/commands/schedule.js

@@ -6,7 +6,7 @@
 import { resolve } from "node:path";
 import { loadDotEnv } from "../../env.js";
 import { resolveStateRoot } from "../../paths.js";
-import { reportModuleLoadFailures } from "../../log.js";
+import { reportModuleLoadFailures } from "../../loader.js";
 import { readRuns } from "../../schedule/audit.js";
 import { nextRun } from "../../schedule/cron.js";
 import { loadSchedules } from "../../schedule/discover.js";

package/dist/cli/commands/start.js

@@ -2,67 +2,49 @@
  * `fastagent start [dir]`: run the agent in production posture — the SAME assembly as dev (your
  * directory is the agent), just no file-watching. No build step: start reads the definition directly.
  */
-import { mkdir, writeFile } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
-import { authSeedBytes, collectAuthSeed } from "../../deploy/fly/run.js";
-import { loadDotEnv } from "../../env.js";
+import { dirname } from "node:path";
+import { writeFileAtomic } from "../../atomic-write.js";
+import { authSeedBytes, collectAuthSeed } from "../../deploy/secrets.js";
 import { resolveAuthPath, resolveSessionsDirOverride } from "../../engines/pi/config.js";
-import { resolveSecretsDir, workspaceHint } from "../../paths.js";
-import { isUnderDir } from "../../paths.js";
-import { reportFindingsIfChanged, reportToolCollisions } from "../../engines/pi/report.js";
-import { reportModuleLoadFailures } from "../../log.js";
-import { CODING_TOOL_NAMES } from "../../engines/pi/create.js";
+import { SECRET_FILE_MODE, ensureSecretsDir, resolveSecretsDir, isUnderDir, exists } from "../../paths.js";
+import { log, setLogLevel } from "../../log.js";
 import { createPiAgentFromDir } from "../../engines/pi/open.js";
 import { mountAgentService } from "../../service.js";
-import { log, setLogLevel } from "../../log.js";
 import { logAgentLoop } from "../../observe.js";
-import { installProxyFetch } from "../../proxy.js";
-import { exists } from "../../paths.js";
-import { bindAddress } from "../../bind.js";
 import { isAgentcoreRuntime, mountAgentcoreService } from "../../channels/agentcore-service.js";
-import { createWakeAlarmSink, reconcileWakeAlarms } from "../../schedule/wake-alarm.js";
+import { createWakeAlarmSink } from "../../schedule/wake-alarm.js";
 import { setWakeupsSink } from "../../schedule/wakeups.js";
-import { failStartup, placementOrExit } from "../fail.js";
-import { SHUTDOWN_GRACE_MS, assertTunnelBindable, maybeTunnel, reportServing, serve } from "../serve.js";
-import { parseBind, parsePort, reportAuth, reportLine, resolveFirstRunModel, reportWorkspaceHint } from "../shared.js";
+import { failStartup } from "../fail.js";
+import { cliMountOptions, resolveBindHost, serveService } from "../serve.js";
+import { enterAgentCommand, parseBind, parsePort, reportAssembly } from "../shared.js";
 export async function runStart(dirArg, opts) {
-    const dir = resolve(dirArg);
     // Flag validation first: a bad --port is a USAGE error (exit 2), and reporting it must not depend on
     // the directory being an agent (which is a runtime/environment failure, exit 1).
     const portFlag = parsePort(opts.port, "--port", "flag");
     const bindFlag = parseBind(opts.bind);
-    const placement = placementOrExit(dir);
+    const tunnel = opts.tunnel ?? false;
     setLogLevel("info"); // production posture: info+, the debug turn trace (and its end-user content) gated out
-    loadDotEnv(placement.agentDir);
-    installProxyFetch();
-    await resolveFirstRunModel(placement.agentDir, opts);
+    const placement = await enterAgentCommand(dirArg, opts);
     // A `deploy --run` may carry the operator's local credential as FASTAGENT_AUTH_SEED —
     // materialize it into the writable secrets dir BEFORE the opener resolves auth (once, absent-only).
     // Same resolveAuthPath the opener uses — ONE owner of the flag > env > default chain.
     await maybeSeedAuth(resolveAuthPath(placement.agentDir, opts.authPath));
     // The same opener dev uses (single assembly source), just no watch.
-    const sessionsDirOverride = resolveSessionsDirOverride(opts.sessionsDir);
-    const opened = await openStartDir(dir, opts, sessionsDirOverride);
-    const { agent, definition, agentDir, workspace, config, modelSpec, stateRoot, sessionsDir, authPath, toolNames, deferredToolNames, toolCollisions, toolFailures, } = opened;
-    reportLine("agent", agentDir);
-    reportLine("workspace", workspace);
-    reportWorkspaceHint(workspaceHint({ agentDir, workspace }));
-    reportLine("model", `${modelSpec}${config.thinkingLevel ? ` (thinking: ${config.thinkingLevel})` : ""}`);
-    await reportAuth(agentDir, modelSpec, authPath);
-    reportLine("context", definition.contextFiles.map((f) => f.path).join(", ") || "(none)");
-    if (definition.persona)
-        reportLine("persona", "persona.md");
-    reportLine("skills", definition.skills.map((s) => s.name).join(", ") || "(none)");
-    reportLine("codingTools", CODING_TOOL_NAMES.join(", "));
-    if (toolNames.length > 0)
-        reportLine("tools", toolNames.join(", "));
-    if (deferredToolNames.length > 0) {
-        reportLine("deferred", `${deferredToolNames.join(", ")} (activated via search_tools)`);
-    }
-    reportToolCollisions(toolCollisions);
-    reportModuleLoadFailures(toolFailures);
-    reportLine("state", stateRoot);
-    reportLine("sessions", sessionsDir);
+    const opened = await createPiAgentFromDir(placement.workspace, {
+        model: opts.model,
+        sessionsDir: resolveSessionsDirOverride(opts.sessionsDir),
+        authPath: opts.authPath,
+        serving: true, // long-running serve: the scheduler poller runs (wake mounts iff config.selfSchedule)
+    }).catch(failStartup);
+    const { agent, agentDir, config, stateRoot, sessionsDir } = opened;
+    // The same report `dev` prints; `state:`/`sessions:` are start's own extras, and the persistence
+    // notes below are why (see reportAssembly on the asymmetry).
+    await reportAssembly(opened, {
+        afterTools: [
+            ["state", stateRoot],
+            ["sessions", sessionsDir],
+        ],
+    });
     // State defaults under the agent dir, which a redeploy may replace wholesale. Gate on where the
     // state root ACTUALLY resolved (inside the agent dir?), not on the raw env var: an empty
     // `FASTAGENT_STATE_DIR=""` reads as unset (resolveStateRoot) and still lands in-agent, so a raw
@@ -81,15 +63,9 @@ export async function runStart(dirArg, opts) {
         log.info(`[fastagent] note: secrets (.env, rotated auth.json) live under the definition dir; point ` +
             `FASTAGENT_SECRETS_DIR at a persistent volume so a redeploy that replaces the dir does not wipe them.`);
     }
-    reportFindingsIfChanged(definition.dir, definition);
-    // Same debug turn trace as dev; gated out here by the info level (see dev.ts serveOnce).
+    // Same debug turn trace as dev; gated out here by the info level.
     const traced = logAgentLoop(agent);
-    // `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 = config.http?.host;
-    const host = bindFlag ?? (configured === undefined ? undefined : bindAddress(configured));
-    assertTunnelBindable(host, opts.tunnel ?? false, bindFlag ? "flag" : "config");
-    const control = { tunnel: opts.tunnel ?? false, ...(host !== undefined ? { host } : {}) };
+    const host = resolveBindHost(bindFlag, config.http?.host, tunnel);
     // ONE branch for the whole posture. AgentCore assembles differently — lazy channels over a
     // pre-restore state mount, an external clock, no resident connections — but it yields the same
     // AgentService, so everything below this point is common.
@@ -98,22 +74,9 @@ export async function runStart(dirArg, opts) {
     // handed to something that can, without inventing an ownership the singleton does not have.
     const onStateReady = isAgentcoreRuntime() && config.selfSchedule ? armWakeAlarms(stateRoot) : undefined;
     const service = await (isAgentcoreRuntime()
-        ? mountAgentcoreService(opened, { wrapAgent: () => traced, control, onStateReady })
-        : mountAgentService(opened, {
-            wrapAgent: () => traced,
-            closeTimeoutMs: SHUTDOWN_GRACE_MS,
-            control,
-            onChannelClosed: (name, error) => failStartup(new Error(`${name} ${error === undefined ? "closed unexpectedly" : `failed: ${String(error)}`}`)),
-        })).catch(failStartup);
-    serve(service.handler, { port: portFlag ?? parsePort(process.env.PORT, "PORT env", "env") ?? config.http?.port ?? 8787, host }, {
-        ready: service.ready,
-        onListening: (p) => {
-            reportServing(service, host, p);
-            service.announce(p);
-            maybeTunnel(agentDir, service.channels.routes, p, opts.tunnel ?? false, stateRoot);
-        },
-        onShutdown: () => service.close(),
-    });
+        ? mountAgentcoreService(opened, { wrapAgent: () => traced, onStateReady })
+        : mountAgentService(opened, cliMountOptions(() => traced))).catch(failStartup);
+    serveService(service, { port: portFlag ?? parsePort(process.env.PORT, "PORT env", "env") ?? config.http?.port ?? 8787, host }, { tunnel, agentDir, stateRoot });
     // No graceful drain: webhook turns run fire-and-forget; SIGTERM just exits mid-turn. Whether an
     // in-flight turn is LOST depends on the channel: the Telegram channel persists turn intent pre-ACK
     // and replays it next start (turn-store.ts, L1 durable execution, at-least-once); HTTP and other
@@ -125,23 +88,19 @@ export async function runStart(dirArg, opts) {
  * volume copy is never clobbered by the stale seed. Lets a deploy carry the operator's local
  * OAuth/API credential so the box runs on the SAME subscription. No-op locally (the seed is unset).
  */
-/** The opener, kept as its own call so `opened` can also feed the shared assembly below. */
-function openStartDir(dir, opts, sessionsDir) {
-    return createPiAgentFromDir(dir, {
-        model: opts.model,
-        sessionsDir,
-        authPath: opts.authPath,
-        serving: true, // long-running serve: the scheduler poller runs (wake mounts iff config.selfSchedule)
-    }).catch(failStartup);
-}
 async function maybeSeedAuth(authPath) {
     // collectAuthSeed: the seed may arrive CHUNKED (FASTAGENT_AUTH_SEED + _2…) on hosts with a small
     // env-value max length (AgentCore); single-var hosts are unchanged.
     const bytes = authSeedBytes(collectAuthSeed(process.env), await exists(authPath));
     if (!bytes)
         return;
-    await mkdir(dirname(authPath), { recursive: true });
-    await writeFile(authPath, bytes);
+    await ensureSecretsDir(dirname(authPath));
+    // Same spelling as the credential store: the mode is applied before the content is reachable, so
+    // the seed can never be published at some other file's looser permissions. It does NOT close the
+    // gap between the `exists` check and the write — the rename would overwrite a file created in
+    // between, against this function's absent-only promise. That window needs two `start` processes on
+    // one secrets dir, which no supported deployment runs (one container, one volume).
+    writeFileAtomic(authPath, bytes, SECRET_FILE_MODE);
     log.info(`[fastagent] seeded ${authPath} from FASTAGENT_AUTH_SEED (first boot)`);
 }
 /**
@@ -160,5 +119,7 @@ function armWakeAlarms(stateRoot) {
     const sink = createWakeAlarmSink({ secret });
     setWakeupsSink(sink);
     log.info(`[fastagent] wake alarms: EventBridge-backed via the forwarder`);
-    return () => reconcileWakeAlarms(stateRoot, sink);
+    // Boot reconcile: pending wake-ups may exist while their alarms were lost (a deploy replaced the
+    // forwarder, a sink call failed). The sink re-reads the store, so a bare notification is enough.
+    return () => sink(stateRoot);
 }

package/dist/cli/commands/tool.js

@@ -1,10 +1,9 @@
 /** `fastagent tool <name> '<json>' [dir]`: run one tool's body directly with JSON args — no model. */
 import { resolve } from "node:path";
-import { NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
 import { loadDotEnv } from "../../env.js";
 import { loadConfig } from "../../engines/pi/config.js";
 import { resolveAgentTools } from "../../engines/pi/create.js";
-import { reportModuleLoadFailures } from "../../log.js";
+import { reportModuleLoadFailures } from "../../loader.js";
 import { turnContext } from "../../engines/pi/tool-context.js";
 import { failStartup, failUsage, placementOrExit } from "../fail.js";
 export async function runTool(name, argsJson, dirArg) {
@@ -26,12 +25,8 @@ export async function runTool(name, argsJson, dirArg) {
     if (!tool) {
         failStartup(new Error(`unknown tool "${name}". available: ${tools.map((t) => t.name).join(", ") || "(none)"}`));
     }
-    // Authored tools read cwd from turnContext; coding tools are already rooted at the workspace. Keep
-    // the fifth-argument env for lower-level MountedTools that explicitly consume it.
-    const env = new NodeExecutionEnv({ cwd: workspace });
-    const result = await turnContext
-        .run({ cwd: workspace }, () => tool.execute(`cli-${name}`, args, undefined, undefined, { env }))
-        .catch(failStartup);
+    // Authored tools read cwd from turnContext; coding tools are already rooted at the workspace.
+    const result = await turnContext.run({ cwd: workspace }, () => tool.execute(`cli-${name}`, args)).catch(failStartup);
     const out = result?.details !== undefined
         ? result.details
         : (result?.content ?? []).map((c) => ("text" in c ? c.text : "")).join("");

package/dist/cli/kernel.d.ts

@@ -24,8 +24,6 @@ interface ArgSpec {
 export interface FlagSpec {
     flags: string;
     description: string;
-    /** Parses but does not appear in help — for retired flags that should still explain themselves. */
-    hidden?: boolean;
     /** Mutually exclusive with these {@link optionKey} values — validated at build time. */
     conflicts?: string[];
 }

package/dist/cli/kernel.js

@@ -114,8 +114,6 @@ function register(parent, spec) {
     }
     for (const f of spec.flags ?? []) {
         const opt = new Option(f.flags, f.description);
-        if (f.hidden)
-            opt.hideHelp();
         if (f.conflicts)
             opt.conflicts(f.conflicts);
         cmd.addOption(opt);

package/dist/cli/program.js

@@ -6,6 +6,7 @@
  */
 import { fastagentVersion } from "../version.js";
 import { buildProgram } from "./kernel.js";
+import { DEPLOY_HOSTS } from "../deploy/hosts.js";
 // Help groups (clig: most common commands first) — the authoring loop leads, operations close.
 // Shared flags — same name, same meaning, on every command that supports them (clig: consistency).
 const DIR_ARG = {
@@ -256,8 +257,6 @@ const start = {
         input: f.input !== false,
     }),
 };
-/** The retired app-creation flag — parsed so it can explain itself, hidden from help. */
-const CREATE_APP = { flags: "--create-app", description: "(retired)", hidden: true };
 const INGRESS = {
     flags: "--ingress <mode>",
     description: "Feishu/Lark ingress: websocket or webhook (interactive when omitted)",
@@ -280,18 +279,14 @@ const channelSub = (kind, summary, description, notes) => ({
     summary,
     description,
     args: [DIR_ARG],
-    flags: [
-        CREATE_APP,
-        ...(kind === "feishu" || kind === "lark"
-            ? [INGRESS, GROUP_BEHAVIOR]
-            : kind === "slack"
-                ? [GROUP_BEHAVIOR, NO_ONBOARD, REPLACE_CONFIG]
-                : []),
-    ],
+    flags: kind === "feishu" || kind === "lark"
+        ? [INGRESS, GROUP_BEHAVIOR]
+        : kind === "slack"
+            ? [GROUP_BEHAVIOR, NO_ONBOARD, REPLACE_CONFIG]
+            : [],
     examples: [{ cmd: `fastagent add ${kind}` }],
     ...(notes ? { notes } : {}),
     run: async (args, f) => (await import("./commands/add.js")).runAddChannel(kind, args[0], {
-        createApp: f.createApp === true,
         ingress: f.ingress,
         groupBehavior: f.groupBehavior,
         onboard: f.onboard !== false,
@@ -357,7 +352,7 @@ const deploy = {
         "CloudFormation stack (AWS Bedrock AgentCore Runtime + forwarder Lambda for webhooks + " +
         "EventBridge rules for schedules; linux/arm64 image built locally). Durable ingress " +
         "remains operator-owned (agentcore's forwarder URL is the exception — the stack owns it).",
-    args: [{ name: "<host>", description: "deploy target", choices: ["docker", "fly", "railway", "agentcore"] }, DIR_ARG],
+    args: [{ name: "<host>", description: "deploy target", choices: [...DEPLOY_HOSTS] }, DIR_ARG],
     flags: [
         {
             flags: "--run",

package/dist/cli/serve.d.ts

@@ -1,15 +1,5 @@
-import type { ChannelHandler } from "../channel.ts";
-import type { AgentService } from "../service.ts";
-/**
- * Mount the session control plane (`/control/*`) when the agent enabled it
- * (`config.sessionControl`): merge the bearer-authenticated routes and return an announcer that
- * writes `<stateRoot>/control.json` — `{ url, token }`, 0600 — once the port is known. The file is
- * the LOCAL discovery channel (`fastagent attach`, a local desktop app); filesystem permissions are
- * its trust boundary, and each boot overwrites it with a fresh per-boot token. A user channel
- * colliding on `/control/*` fails startup — the same disposition as a channel-channel collision
- * (routesFor): `sessionControl` is an explicit opt-in, so declaring both is a configuration error,
- * and silently shadowing either side would serve a surface the author didn't write.
- */
+import type { Agent } from "../agent.ts";
+import type { AgentService, MountAgentServiceOptions } from "../service.ts";
 /**
  * Refuse `--tunnel` with a bind that cloudflared cannot reach: it dials the NAME `localhost:<port>`
  * (the dev supervisor's tunnel too), so anything outside `127.0.0.1`/`::1`/wildcard — including a
@@ -20,6 +10,32 @@ import type { AgentService } from "../service.ts";
  * came from config is broken runtime configuration (1).
  */
 export declare function assertTunnelBindable(host: string | undefined, tunnel: boolean, source: "flag" | "config"): void;
+/**
+ * The bind address a serve uses: the flag, else `http.host` from the config — through `bindAddress`,
+ * so a configured `localhost` is an ADDRESS by the time anything binds, renders or dials it — checked
+ * against `--tunnel` with the exit code the SOURCE of the value earns (serve.ts assertTunnelBindable).
+ */
+export declare function resolveBindHost(bindFlag: string | undefined, configured: string | undefined, tunnel: boolean): string | undefined;
+/** What the CLI adds to the assembly: its shutdown grace, and exit on a connection that drops. */
+export declare function cliMountOptions(wrapAgent: (agent: Agent) => Agent): MountAgentServiceOptions;
+/**
+ * Bind, report, announce the control plane, open the tunnel, and close in order on a signal — the
+ * tail dev's worker and start share once the service is assembled.
+ */
+export declare function serveService(service: AgentService, bind: {
+    port: number;
+    host?: string;
+}, posture: {
+    tunnel: boolean;
+    agentDir: string;
+    stateRoot: string;
+}): void;
+/**
+ * The "we are serving" report: the supervisor message `dev`'s watcher waits for, the addresses, and
+ * what mounted. One function because both commands must say the same thing at the same moment —
+ * after readiness, never at socket bind.
+ */
+export declare function reportServing(service: AgentService, host: string | undefined, boundPort: number): void;
 /**
  * The startup lines that name WHERE the serve is: the bind report, and the curl the reader copies.
  * ONE function because they are one message — they were two, and `--bind` updated the first while the
@@ -29,29 +45,21 @@ export declare function assertTunnelBindable(host: string | undefined, tunnel: b
  * A wildcard bind is every interface, and naming one address there would understate it — but the curl
  * still needs one to dial, which is what `clientHost` gives (loopback for a wildcard, itself otherwise).
  */
-/**
- * The "we are serving" report: the supervisor message `dev`'s watcher waits for, the addresses, and
- * what mounted. One function because both commands must say the same thing at the same moment —
- * after readiness, never at socket bind.
- */
-export declare function reportServing(service: AgentService, host: string | undefined, boundPort: number): void;
 export declare function readyAddressLines(host: string | undefined, boundPort: number, builtinInvoke: boolean): string[];
 /**
- * Bind HTTP, open long-connection channels, and report ready only when both forms are usable. Each
- * adapter owns reconnects; a terminal close rejects `closed` and fails the process visibly. Abort is
- * the sole clean-shutdown command. `host` unset binds all interfaces.
+ * Write `<stateRoot>/control.json` so a LOCAL client (`fastagent attach`) can find the control plane
+ * once the port is known, and say what reaches it. Returns the file's removal — wired into the
+ * shutdown so a stale file cannot point a client at a dead port (`attach` then fails with "cannot
+ * read", accurate, instead of a stale token's misleading 401/ECONNREFUSED). A hard exit leaves the
+ * file behind: advisory, overwritten by the next boot.
+ *
+ * Here and not in the assembly: the file, its permissions and the warnings are how THIS process's
+ * operator finds and protects the plane. An embedder distributes `service.control` itself.
  */
-/** What the CLI gives a service to stop in, and the hard exit that follows it. The order matters:
- *  a forced exit before the service answers would report a clean shutdown over a stuck channel. */
-export declare const SHUTDOWN_GRACE_MS = 800;
-export declare function serve(handler: ChannelHandler, bind: {
-    port: number;
+export declare function announceControl(control: {
+    token: string;
+    prefix: string;
+} | undefined, stateRoot: string, bind: {
     host?: string;
-}, hooks?: {
-    /** Awaited before anything is reported ready — see the listening handler. */
-    ready?: Promise<void>;
-    onListening?: (boundPort: number) => void;
-    onShutdown?: () => Promise<void> | void;
-}): void;
-/** Start a Cloudflare tunnel for route channels only. */
-export declare function maybeTunnel(agentDir: string, routeChannels: string[], boundPort: number, tunnel: boolean, stateRoot?: string): void;
+    tunnel: boolean;
+}, boundPort: number): () => void;