@fastagent-sh/fastagent 0.19.0 → 0.20.0

package/dist/loader.d.ts

@@ -1,5 +1,48 @@
-/** Whether `name` is an importable agent module (a discovery candidate, not a type declaration). */
-export declare function isModuleFile(name: string): boolean;
+/** One module file a directory declares. `name` is what the domain knows it by; nothing is imported
+ *  to produce this. */
+export interface InventoryEntry {
+    /** Basename without extension — the authoritative name for tools/channels/schedules. */
+    name: string;
+    /** "tools/foo.ts"-style label for errors and collisions. */
+    label: string;
+    file: string;
+}
+/**
+ * WHAT A CODE-INPUT DIRECTORY DECLARES — the single answer to "which files here are modules",
+ * without importing any of them.
+ *
+ * It exists because four consumers need that answer and only one of them may import: the loader
+ * below, `fastagent info`'s channel listing, `--tunnel`'s webhook registration, and the deploy
+ * pre-flight's schedule probe. When they each read the directory themselves they disagreed — on
+ * what counts as a module file, on how to strip the extension, on which errno means "no such
+ * directory" — and a fix had to be applied in four places, which is why the fourth kept being
+ * missed. There is one reading now; what to DO with a failure stays with the caller, because that
+ * genuinely differs (the loader throws, the tunnel cannot).
+ *
+ * A missing directory is an empty inventory. Everything else throws, ENOTDIR included: `channels`
+ * and `schedules` are named directories, so the path existing as a FILE is a mistake in the agent
+ * rather than an agent without one (`service.test.ts` pins that for `schedules`). `paths.ts` folds
+ * ENOTDIR into its empty scan for the opposite reason — it asks which children HAPPEN to be agent
+ * dirs, where a file simply is not one. `not_found` is a non-Node runtime's ENOENT.
+ *
+ * SYMLINKS ARE SKIPPED, and that is a boundary rather than an oversight: `assertInsideAgentDir`
+ * guards the code-input DIRECTORY against escaping the definition, and nothing guards the entries
+ * inside it, so following a link would import from anywhere on the box past the very check meant to
+ * prevent it. Do not "fix" this by following them — report them, which this does.
+ *
+ * The skip is WARNED HERE, not handed back, because "this file is not loadable" holds for all four
+ * consumers and only one of them imports — a listing that reports the name it cannot load reads as
+ * "I never created it". What to do about a load FAILURE does differ per caller, so that travels as
+ * data. One warning per READ, so a command that both lists and loads the same directory (`deploy
+ * agentcore` does) says it twice — both readings are true, and remembering what was already said
+ * would mean a restart stops mentioning a skip that is still there.
+ *
+ * A skip is therefore a warning ONLY, unlike a {@link ModuleLoadFailure}: it is absent from `info
+ * --json` and `deploy` does not gate on it. That is the deliberate cost of one report for four
+ * consumers, three of which list names and have nowhere to put data. To give a machine consumer the
+ * skips, return them beside the entries — do not reconstruct them from stderr.
+ */
+export declare function moduleInventory(subDir: string): Promise<InventoryEntry[]>;
 export interface DiscoveredModule {
     /** Basename without extension — the authoritative name for tools/channels. */
     name: string;
@@ -21,11 +64,10 @@ export interface ModuleLoadFailure {
     message: string;
 }
 /**
- * Import every module file in `subDir`, sorted by name. Missing dir returns none. A file that fails to
- * IMPORT is collected into `failures` (with {@link moduleLoadHint}) rather than thrown, so the caller can
- * report every bad file and apply domain policy; `loadTools`/`loadChannels` add validation failures the
- * same way. (A missing DIRECTORY still returns empty; an unreadable directory still throws
- * — that's not a per-file problem.)
+ * Import every module the directory declares ({@link moduleInventory}). A file that fails to IMPORT
+ * is collected into `failures` (with {@link moduleLoadHint}) rather than thrown, so the caller can
+ * report every bad file and apply domain policy; `loadTools`/`loadChannels` add validation failures
+ * the same way. Entries the inventory SKIPPED are already reported by it, for every consumer.
  */
 export declare function loadModuleDir(subDir: string): Promise<{
     modules: DiscoveredModule[];

package/dist/loader.js

@@ -9,40 +9,101 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { readdir } from "node:fs/promises";
 import { basename, extname, join } from "node:path";
 import { pathToFileURL } from "node:url";
+import { log } from "./log.js";
 const MODULE_EXTS = new Set([".ts", ".js", ".mjs"]);
 /** Whether `name` is an importable agent module (a discovery candidate, not a type declaration). */
-export function isModuleFile(name) {
+function isModuleFile(name) {
     return MODULE_EXTS.has(extname(name)) && !name.endsWith(".d.ts");
 }
+/** The name a module is known by: its basename without the extension. */
+function moduleName(fileName) {
+    return basename(fileName, extname(fileName));
+}
 /**
- * Import every module file in `subDir`, sorted by name. Missing dir returns none. A file that fails to
- * IMPORT is collected into `failures` (with {@link moduleLoadHint}) rather than thrown, so the caller can
- * report every bad file and apply domain policy; `loadTools`/`loadChannels` add validation failures the
- * same way. (A missing DIRECTORY still returns empty; an unreadable directory still throws
- * — that's not a per-file problem.)
+ * WHAT A CODE-INPUT DIRECTORY DECLARES — the single answer to "which files here are modules",
+ * without importing any of them.
+ *
+ * It exists because four consumers need that answer and only one of them may import: the loader
+ * below, `fastagent info`'s channel listing, `--tunnel`'s webhook registration, and the deploy
+ * pre-flight's schedule probe. When they each read the directory themselves they disagreed — on
+ * what counts as a module file, on how to strip the extension, on which errno means "no such
+ * directory" — and a fix had to be applied in four places, which is why the fourth kept being
+ * missed. There is one reading now; what to DO with a failure stays with the caller, because that
+ * genuinely differs (the loader throws, the tunnel cannot).
+ *
+ * A missing directory is an empty inventory. Everything else throws, ENOTDIR included: `channels`
+ * and `schedules` are named directories, so the path existing as a FILE is a mistake in the agent
+ * rather than an agent without one (`service.test.ts` pins that for `schedules`). `paths.ts` folds
+ * ENOTDIR into its empty scan for the opposite reason — it asks which children HAPPEN to be agent
+ * dirs, where a file simply is not one. `not_found` is a non-Node runtime's ENOENT.
+ *
+ * SYMLINKS ARE SKIPPED, and that is a boundary rather than an oversight: `assertInsideAgentDir`
+ * guards the code-input DIRECTORY against escaping the definition, and nothing guards the entries
+ * inside it, so following a link would import from anywhere on the box past the very check meant to
+ * prevent it. Do not "fix" this by following them — report them, which this does.
+ *
+ * The skip is WARNED HERE, not handed back, because "this file is not loadable" holds for all four
+ * consumers and only one of them imports — a listing that reports the name it cannot load reads as
+ * "I never created it". What to do about a load FAILURE does differ per caller, so that travels as
+ * data. One warning per READ, so a command that both lists and loads the same directory (`deploy
+ * agentcore` does) says it twice — both readings are true, and remembering what was already said
+ * would mean a restart stops mentioning a skip that is still there.
+ *
+ * A skip is therefore a warning ONLY, unlike a {@link ModuleLoadFailure}: it is absent from `info
+ * --json` and `deploy` does not gate on it. That is the deliberate cost of one report for four
+ * consumers, three of which list names and have nowhere to put data. To give a machine consumer the
+ * skips, return them beside the entries — do not reconstruct them from stderr.
  */
-export async function loadModuleDir(subDir) {
-    let entries;
+export async function moduleInventory(subDir) {
+    let dirents;
     try {
-        entries = await readdir(subDir, { withFileTypes: true });
+        dirents = await readdir(subDir, { withFileTypes: true });
     }
     catch (error) {
-        const e = error;
-        if (e.code === "ENOENT" || e.code === "not_found")
-            return { modules: [], failures: [] };
+        const code = error.code;
+        if (code === "ENOENT" || code === "not_found")
+            return [];
         throw new Error(`cannot read ${subDir}: ${error.message}`);
     }
     const sub = basename(subDir);
+    const entries = [];
+    // Sorted by the NAME a consumer sees, so none of them re-sorts and none can disagree about order.
+    // Filename breaks a tie: `foo.js` and `foo.ts` both read as `foo`, and the domain loaders document
+    // that the FIRST wins — deciding that here keeps it from depending on readdir's order.
+    const byName = (a, b) => moduleName(a.name).localeCompare(moduleName(b.name)) || a.name.localeCompare(b.name);
+    for (const dirent of dirents.sort(byName)) {
+        if (!isModuleFile(dirent.name))
+            continue;
+        const label = `${sub}/${dirent.name}`;
+        if (dirent.isFile()) {
+            entries.push({ name: moduleName(dirent.name), label, file: join(subDir, dirent.name) });
+        }
+        else if (dirent.isSymbolicLink()) {
+            log.warn(`[fastagent] ${label} is a symlink — code inputs must be real files inside the agent dir — not loaded`);
+        }
+        else if (dirent.isDirectory()) {
+            log.warn(`[fastagent] ${label} is a directory, not a file — not loaded`);
+        }
+        else {
+            log.warn(`[fastagent] ${label} is not a regular file — not loaded`);
+        }
+    }
+    return entries;
+}
+/**
+ * Import every module the directory declares ({@link moduleInventory}). A file that fails to IMPORT
+ * is collected into `failures` (with {@link moduleLoadHint}) rather than thrown, so the caller can
+ * report every bad file and apply domain policy; `loadTools`/`loadChannels` add validation failures
+ * the same way. Entries the inventory SKIPPED are already reported by it, for every consumer.
+ */
+export async function loadModuleDir(subDir) {
+    const entries = await moduleInventory(subDir);
     const modules = [];
     const failures = [];
-    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
-        if (!entry.isFile() || !isModuleFile(entry.name))
-            continue;
-        const file = join(subDir, entry.name);
-        const label = `${sub}/${entry.name}`;
+    for (const { name, label, file } of entries) {
         try {
             const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(file).href)));
-            modules.push({ name: basename(entry.name, extname(entry.name)), label, file, mod });
+            modules.push({ name, label, file, mod });
         }
         catch (error) {
             failures.push({

package/dist/paths.d.ts

@@ -136,6 +136,25 @@ export declare function resolveStateRoot(dir: string, env?: NodeJS.ProcessEnv):
  * auth.json but cannot move the file it is read from (env.ts dotEnvPath).
  */
 export declare function resolveSecretsDir(dir: string, env?: NodeJS.ProcessEnv): string;
+/** What a file under {@link resolveSecretsDir} is written with (auth.json, .env). */
+export declare const SECRET_FILE_MODE = 384;
+/**
+ * Create the secrets directory with the mode its contents require — and REPAIR it when it already
+ * exists, which is the case that matters.
+ *
+ * The DIRECTORY is the boundary that actually protects a credential: without its `x` bit nothing
+ * below it is reachable, whatever a file's own mode says. And it is decided ONCE, by whichever
+ * writer gets there first — `mkdir`'s `mode` is ignored for a directory that already exists, so a
+ * later, more careful caller silently inherits the first one's answer. Four callers create this
+ * directory (`init`, `add <channel>`, the credential store, the deploy seed) and the ordinary order
+ * is init → add → login, so the careful one is LAST: the rule has to live where all of them can
+ * reach it, and it has to chmod rather than trust the create.
+ *
+ * A chmod the caller never asked for owes them its reason: the raw `EPERM ... chmod '/shared/creds'`
+ * reads as a bug in whatever they WERE doing (storing a credential), not as fastagent tightening a
+ * directory they pointed it at, and says nothing about the way out.
+ */
+export declare function ensureSecretsDir(dir: string): Promise<void>;
 /**
  * Guard that `<agentDir>/<name>` resolves INSIDE the agent dir — a symlink that escapes (or an
  * absolute target) is rejected, so discovery/scaffolding never reaches out of the definition directory.

package/dist/paths.js

@@ -16,8 +16,7 @@
  * modules depend on it for something the engine has no say in.
  */
 import { existsSync, readdirSync, statSync } from "node:fs";
-import { access } from "node:fs/promises";
-import { realpath } from "node:fs/promises";
+import { access, chmod, mkdir, realpath } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 /**
@@ -309,6 +308,32 @@ export function resolveStateRoot(dir, env = process.env) {
 export function resolveSecretsDir(dir, env = process.env) {
     return resolveOverridePath(env.FASTAGENT_SECRETS_DIR) ?? join(resolve(dir), SECRETS_DIRNAME);
 }
+/** What a file under {@link resolveSecretsDir} is written with (auth.json, .env). */
+export const SECRET_FILE_MODE = 0o600;
+/** What the secrets directory itself is created with. */
+const SECRETS_DIR_MODE = 0o700;
+/**
+ * Create the secrets directory with the mode its contents require — and REPAIR it when it already
+ * exists, which is the case that matters.
+ *
+ * The DIRECTORY is the boundary that actually protects a credential: without its `x` bit nothing
+ * below it is reachable, whatever a file's own mode says. And it is decided ONCE, by whichever
+ * writer gets there first — `mkdir`'s `mode` is ignored for a directory that already exists, so a
+ * later, more careful caller silently inherits the first one's answer. Four callers create this
+ * directory (`init`, `add <channel>`, the credential store, the deploy seed) and the ordinary order
+ * is init → add → login, so the careful one is LAST: the rule has to live where all of them can
+ * reach it, and it has to chmod rather than trust the create.
+ *
+ * A chmod the caller never asked for owes them its reason: the raw `EPERM ... chmod '/shared/creds'`
+ * reads as a bug in whatever they WERE doing (storing a credential), not as fastagent tightening a
+ * directory they pointed it at, and says nothing about the way out.
+ */
+export async function ensureSecretsDir(dir) {
+    await mkdir(dir, { recursive: true, mode: SECRETS_DIR_MODE });
+    await chmod(dir, SECRETS_DIR_MODE).catch((e) => {
+        throw new Error(`cannot secure secrets dir ${dir} (fastagent keeps it 0700): ${e.message} — point --auth-path/FASTAGENT_SECRETS_DIR at a directory this process owns`, { cause: e });
+    });
+}
 /**
  * Guard that `<agentDir>/<name>` resolves INSIDE the agent dir — a symlink that escapes (or an
  * absolute target) is rejected, so discovery/scaffolding never reaches out of the definition directory.

package/dist/scaffold/add-channel.js

@@ -7,7 +7,7 @@
 import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { detectRuntime } from "../runtime.js";
-import { SECRETS_DIRNAME, assertInsideAgentDir, exists } from "../paths.js";
+import { SECRETS_DIRNAME, assertInsideAgentDir, ensureSecretsDir, exists } from "../paths.js";
 import { baseTemplate, channelBundleFiles, channelTemplate } from "./templates.js";
 import { dotEnvPath, envExamplePath, parseEnvContent } from "../env.js";
 const CHANNEL_SCAFFOLDS = {
@@ -229,7 +229,7 @@ function mentionsEnvName(content, name) {
 export async function appendChannelDotEnv(dir, kind, generated, overwrite = [], ingress = "webhook") {
     const file = dotEnvPath(dir);
     const secretsDir = dirname(file);
-    await mkdir(secretsDir, { recursive: true });
+    await ensureSecretsDir(secretsDir);
     // THE one exception to "fastagent has no opinion about git": the directory it writes secrets into
     // carries its own `.gitignore`. `init` writes it, and so does this — the reachable case where it is
     // missing (a hand-made agent) is exactly the one where the next line mints an unrecoverable app

package/dist/scaffold/init.js

@@ -27,7 +27,7 @@
  */
 import { lstat, mkdir, readdir, rm, rmdir, writeFile } from "node:fs/promises";
 import { basename, dirname, join, resolve, sep } from "node:path";
-import { AGENT_CONFIG_NAMES, DEFAULT_AGENT_DIRNAME, SECRETS_DIRNAME, agentDefinitionOwner, agentsAt, displayPath, exists, } from "../paths.js";
+import { AGENT_CONFIG_NAMES, DEFAULT_AGENT_DIRNAME, SECRETS_DIRNAME, agentDefinitionOwner, agentsAt, displayPath, ensureSecretsDir, exists, } from "../paths.js";
 import { baseTemplate, packageJson, toPackageName } from "./templates.js";
 import { fastagentVersion } from "../version.js";
 /** The agent directory name for a raw `--agent-dir` value: the default when unset, and `./bot` read as
@@ -191,7 +191,12 @@ export async function scaffoldAgent(dir, options = {}) {
     try {
         for (const file of files) {
             const abs = join(dir, file.rel);
-            await mkdir(dirname(abs), { recursive: true });
+            // The secrets dir carries a mode; every other directory here is ordinary. `init` is usually the
+            // FIRST of the four writers to create it, and whoever creates it decides the mode for the rest.
+            if (basename(dirname(abs)) === SECRETS_DIRNAME)
+                await ensureSecretsDir(dirname(abs));
+            else
+                await mkdir(dirname(abs), { recursive: true });
             try {
                 await writeFile(abs, file.content, { flag: "wx" });
                 created.push(file.rel);

package/dist/scaffold/templates/tools/fetch-url.ts

@@ -3,8 +3,6 @@ import { defineTool, z } from "@fastagent-sh/fastagent";
 // A code tool: filename (fetch-url.ts) is the tool name. tools/ is auto-discovered,
 // so it needs no registration in fastagent.config. Test it without a model:
 //   fastagent tool fetch-url '{"url":"https://example.com"}'
-// Serving this behind a public channel? The URL then comes from untrusted users — add an
-// allowlist or block private-network addresses (localhost, 169.254.169.254, …) to prevent SSRF.
 const MAX_TEXT = 20_000; // keep a huge page from flooding the model's context
 
 export default defineTool({

package/dist/schedule/discover.js

@@ -4,9 +4,8 @@
  * named from its filename. This is the FILE producer of scheduled invocations (the author's, declarative,
  * git-tracked, deploy-guaranteed); the agent's `wake` tool is the second producer.
  */
-import { readdir } from "node:fs/promises";
 import { join } from "node:path";
-import { isModuleFile, loadModuleDir } from "../loader.js";
+import { loadModuleDir, moduleInventory } from "../loader.js";
 import { assertInsideAgentDir } from "../paths.js";
 import { cronError } from "./cron.js";
 /** Schedule file basenames under `<dir>/schedules/` — an existence probe listed WITHOUT importing
@@ -14,19 +13,8 @@ import { cronError } from "./cron.js";
  *  since it also reports broken files and next instants). */
 export async function discoverScheduleFiles(dir) {
     await assertInsideAgentDir(dir, "schedules");
-    let names;
-    try {
-        names = await readdir(join(dir, "schedules"));
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return [];
-        throw error;
-    }
-    return names
-        .filter(isModuleFile)
-        .map((n) => n.replace(/\.(ts|js|mjs)$/, ""))
-        .sort();
+    const entries = await moduleInventory(join(dir, "schedules"));
+    return entries.map((entry) => entry.name);
 }
 /**
  * Discover schedules in `<dir>/schedules/`: each file default-exports a `defineSchedule({...})`, named

package/dist/schedule/wake-alarm.d.ts

@@ -1,4 +1,4 @@
-import type { Wakeup } from "./wakeups.ts";
+import { type Wakeup } from "./wakeups.ts";
 /** The forwarder's reserved wake-alarm path — never forwarded to channel routes. */
 export declare const WAKE_ALARM_PATH = "/__fastagent/wake-alarm";
 /** One desired alarm: mirror of a pending wake-up (id names the EventBridge schedule; at = fireAt). */
@@ -31,6 +31,17 @@ export declare function toAlarms(pending: Wakeup[], now: Date): WakeAlarm[];
  * when `FASTAGENT_AGENTCORE=1` + `FASTAGENT_WAKE_SECRET` are present). Fire-and-forget by contract:
  * failures are logged, never thrown — a broken alarm degrades to the pre-alarm behavior (the wake
  * still fires on the next time the box happens to be awake), it must never break the store write.
+ *
+ * A single-flight RECONCILER, not a per-mutation delivery: a notification only marks the desired
+ * state dirty, and the loop re-derives it from the store before every attempt. So a mutation during
+ * a retry needs no ordering rule — there is one desired state, never two snapshots to rank — and the
+ * {@link DUE_MARGIN_MS} filter is re-applied with a fresh clock, which a captured payload could not
+ * do: entries that became due mid-retry would keep being POSTed with a past `at()`, a rejection no
+ * number of retries could clear.
+ *
+ * Assumes ONE sink per process over ONE state root (what `start` builds): the loop keeps the root of
+ * the call that started it, and its dirty flag is shared, so a second root would fold into the first
+ * one's pass.
  */
 export declare function createWakeAlarmSink(options: {
     secret: string;
@@ -39,9 +50,4 @@ export declare function createWakeAlarmSink(options: {
     now?: () => Date;
     /** Injectable retry pause (tests); defaults to exponential-ish backoff off RETRY_BASE_MS. */
     delay?: (ms: number) => Promise<void>;
-}): (stateRoot: string, pending: Wakeup[]) => void;
-/**
- * One boot-time reconcile: pending wake-ups may exist while their alarms were lost (a deploy
- * replaced the forwarder, a sink call failed) — re-mirror the current set once at start.
- */
-export declare function reconcileWakeAlarms(stateRoot: string, sink: (stateRoot: string, pending: Wakeup[]) => void): void;
+}): (stateRoot: string) => void;

package/dist/schedule/wake-alarm.js

@@ -17,7 +17,8 @@
  * Function URL at cold start), and the adapter persists it here; every wake write happens inside a
  * turn, and every ingress turn arrived through an envelope, so the URL is always known by then.
  *
- * Reconciliation is DECLARATIVE (the full pending set travels each time) and deletion is lazy: a
+ * Reconciliation is DECLARATIVE (the sink is told only THAT the store changed and reads the full
+ * pending set back per attempt, so no retry ever carries a stale view) and deletion is lazy: a
  * cancelled wake-up's alarm still fires its poke, finds nothing due, and self-deletes — a harmless
  * wasted wake-up of the box, traded for never needing list/delete choreography.
  */
@@ -71,66 +72,107 @@ export function toAlarms(pending, now) {
  * when `FASTAGENT_AGENTCORE=1` + `FASTAGENT_WAKE_SECRET` are present). Fire-and-forget by contract:
  * failures are logged, never thrown — a broken alarm degrades to the pre-alarm behavior (the wake
  * still fires on the next time the box happens to be awake), it must never break the store write.
+ *
+ * A single-flight RECONCILER, not a per-mutation delivery: a notification only marks the desired
+ * state dirty, and the loop re-derives it from the store before every attempt. So a mutation during
+ * a retry needs no ordering rule — there is one desired state, never two snapshots to rank — and the
+ * {@link DUE_MARGIN_MS} filter is re-applied with a fresh clock, which a captured payload could not
+ * do: entries that became due mid-retry would keep being POSTed with a past `at()`, a rejection no
+ * number of retries could clear.
+ *
+ * Assumes ONE sink per process over ONE state root (what `start` builds): the loop keeps the root of
+ * the call that started it, and its dirty flag is shared, so a second root would fold into the first
+ * one's pass.
  */
 export function createWakeAlarmSink(options) {
     const { secret, fetchImpl = fetch, now = () => new Date() } = options;
     const delay = options.delay ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
-    // Supersession token: a newer mutation's sync REPLACES an older one still retrying — without it,
-    // an old in-flight set could win the race and mirror stale state.
-    let latest;
-    async function sync(url, body, token) {
+    let running = false;
+    let dirty = false;
+    /** One POST of the CURRENT desired set. Returns false to retry, true when there is nothing left
+     *  to do (converged, or nothing this loop can act on). */
+    async function attemptOnce(stateRoot, attempt) {
+        const alarms = toAlarms(listWakeups(stateRoot), now());
+        // Nothing future to mirror: converged. Deletion is lazy by design — alarms already mirrored for
+        // cancelled wake-ups fire, find nothing, self-delete — so an empty set is never POSTed.
+        if (alarms.length === 0)
+            return true;
+        const url = readWakeAlarmUrl(stateRoot);
+        if (!url) {
+            // Before the first envelope, or an unreadable state mount (readWakeAlarmUrl folds both into
+            // undefined). The wake itself is stored; the next store mutation or boot re-mirrors it.
+            log.warn("[schedule] wake alarm skipped — forwarder URL unavailable (not seen yet, or unreadable)");
+            return true;
+        }
+        const body = { secret, alarms };
+        try {
+            const res = await fetchImpl(`${url.replace(/\/$/, "")}${WAKE_ALARM_PATH}`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(SYNC_TIMEOUT_MS),
+            });
+            if (res.ok)
+                return true;
+            log.warn(`[schedule] wake alarm sync attempt ${attempt}/${MAX_SYNC_ATTEMPTS} failed: HTTP ${res.status}`);
+        }
+        catch (e) {
+            log.warn(`[schedule] wake alarm sync attempt ${attempt}/${MAX_SYNC_ATTEMPTS} failed: ${String(e)}`);
+        }
+        return false;
+    }
+    async function reconcile(stateRoot) {
         // Counted as in-flight work: the retry loop is exactly the window where the box must not be
         // reclaimed — idle away mid-retry and a pending wake has no alarm until the next boot.
         const workDone = beginWork();
+        // Consecutive failures ACROSS passes, not within one. A mid-retry mutation restarts the attempt
+        // sequence (the backoff and the log's `n/N` are about the new desired set), but it must not renew
+        // the budget: a store mutating faster than the backoff would keep the loop alive forever, and the
+        // one loud line saying the forwarder is down — the per-attempt warns are filterable — would never
+        // be reached. This counter is the thing that survives to reach it.
+        let failures = 0;
         try {
-            for (let attempt = 1; attempt <= MAX_SYNC_ATTEMPTS; attempt++) {
-                if (latest !== token)
-                    return; // superseded by a newer set — that sync owns correctness now
-                try {
-                    const res = await fetchImpl(`${url.replace(/\/$/, "")}${WAKE_ALARM_PATH}`, {
-                        method: "POST",
-                        headers: { "content-type": "application/json" },
-                        body: JSON.stringify(body),
-                        signal: AbortSignal.timeout(SYNC_TIMEOUT_MS),
-                    });
-                    if (res.ok)
-                        return;
-                    log.warn(`[schedule] wake alarm sync attempt ${attempt}/${MAX_SYNC_ATTEMPTS} failed: HTTP ${res.status}`);
+            while (dirty && failures < MAX_SYNC_ATTEMPTS) {
+                dirty = false;
+                for (let attempt = 1; attempt <= MAX_SYNC_ATTEMPTS; attempt++) {
+                    if (await attemptOnce(stateRoot, attempt)) {
+                        failures = 0;
+                        break;
+                    }
+                    failures++;
+                    if (attempt === MAX_SYNC_ATTEMPTS || failures >= MAX_SYNC_ATTEMPTS)
+                        break;
+                    await delay(RETRY_BASE_MS * attempt);
+                    // A mutation landed mid-retry: the desired state moved, so this budget is spent on a set
+                    // that no longer exists. Restart the attempt count against the new one.
+                    if (dirty)
+                        break;
                 }
-                catch (e) {
-                    log.warn(`[schedule] wake alarm sync attempt ${attempt}/${MAX_SYNC_ATTEMPTS} failed: ${String(e)}`);
-                }
-                await delay(RETRY_BASE_MS * attempt);
             }
-            log.error(`[schedule] wake alarm sync FAILED after ${MAX_SYNC_ATTEMPTS} attempts — pending wake-ups have no ` +
-                `external alarm until the next store change or boot re-mirrors them`);
+            if (failures >= MAX_SYNC_ATTEMPTS) {
+                log.error(`[schedule] wake alarm sync FAILED after ${MAX_SYNC_ATTEMPTS} attempts — pending wake-ups have no ` +
+                    `external alarm until the next store change or boot re-mirrors them`);
+            }
+        }
+        catch (e) {
+            // The END of the error path: nothing awaits this loop, so an escape is an unhandled rejection
+            // that kills the container. `listWakeups` throws by design on an unreadable store (state.ts),
+            // exactly the fault a wake alarm cannot fix — report it and leave the store write untouched,
+            // which is this sink's whole contract. The next mutation or boot re-runs the mirror.
+            log.error(`[schedule] wake alarm reconcile failed (alarms are stale until the next store change): ${String(e)}`);
         }
         finally {
+            running = false;
             workDone();
         }
     }
-    return (stateRoot, pending) => {
-        const url = readWakeAlarmUrl(stateRoot);
-        if (!url) {
-            // First-ever boot before any envelope: nothing to call yet. The wake itself is stored; the
-            // alarm catches up on the next store mutation after an envelope has arrived.
-            log.warn("[schedule] wake alarm skipped — forwarder URL not seen yet (it arrives with the first envelope)");
+    // Single-flight: a save arriving while the loop runs only marks it dirty, so a burst coalesces
+    // into one more pass instead of one concurrent loop each.
+    return (stateRoot) => {
+        dirty = true;
+        if (running)
             return;
-        }
-        const alarms = toAlarms(pending, now());
-        if (alarms.length === 0)
-            return; // nothing future to mirror (deletion is lazy by design)
-        const token = Symbol("wake-alarm-sync");
-        latest = token;
-        void sync(url, { secret, alarms }, token);
+        running = true;
+        void reconcile(stateRoot);
     };
 }
-/**
- * One boot-time reconcile: pending wake-ups may exist while their alarms were lost (a deploy
- * replaced the forwarder, a sink call failed) — re-mirror the current set once at start.
- */
-export function reconcileWakeAlarms(stateRoot, sink) {
-    const pending = listWakeups(stateRoot);
-    if (pending.length > 0)
-        sink(stateRoot, pending);
-}

package/dist/schedule/wakeups.d.ts

@@ -26,7 +26,7 @@ export declare const MAX_PENDING_WAKEUPS = 20;
  *  wake into an active conversation fires in the first gap between the user's turns; this generous
  *  ceiling (~1h) only gives up on a pathologically stuck session (then logs, operator-visible). */
 export declare const MAX_WAKE_ATTEMPTS = 120;
-export declare function setWakeupsSink(sink: ((stateRoot: string, pending: Wakeup[]) => void) | undefined): void;
+export declare function setWakeupsSink(sink: ((stateRoot: string) => void) | undefined): void;
 /** The current pending wake-ups (`fastagent schedule list` uses this). */
 export declare function listWakeups(stateRoot: string): Wakeup[];
 export type AddWakeupResult = {

package/dist/schedule/wakeups.js

@@ -48,12 +48,15 @@ function isWakeup(e) {
             (typeof w.cron === "string" && cronError(w.cron, typeof w.tz === "string" ? w.tz : undefined) === undefined)));
 }
 /**
- * The wake-ALARM sink: notified after EVERY wakeups-store mutation with the new pending set. The
- * AgentCore deployment registers one (schedule/wake-alarm.ts) that mirrors pending wake-ups into
- * one-shot EventBridge schedules — the external clock that makes `wake` reliable on a host with no
- * resident process. Neutral seam: this module knows only "someone wants to observe changes"; a
- * resident host registers nothing and behaves exactly as before. The sink is fire-and-forget and
- * must own its errors; a throw is caught here so a broken alarm never corrupts a store write.
+ * The wake-ALARM sink: notified after EVERY wakeups-store mutation. A notification, not a delivery
+ * — it carries no set, because the sink reconciles by re-reading the store, and handing it a set
+ * captured here would go stale in its retries. The AgentCore deployment registers one
+ * (schedule/wake-alarm.ts) that mirrors pending wake-ups into one-shot EventBridge schedules — the
+ * external clock that makes `wake` reliable on a host with no resident process. Neutral seam: this
+ * module knows only "someone wants to observe changes"; a resident host registers nothing and
+ * behaves exactly as before. The sink is fire-and-forget and must own its errors. The guard below
+ * catches a SYNCHRONOUS throw so a broken alarm never corrupts a store write; an async sink returns
+ * before it does any work, so its rejections are ITS to terminate — nothing here can see them.
  */
 let wakeupsSink;
 export function setWakeupsSink(sink) {
@@ -81,7 +84,7 @@ function load(stateRoot) {
 function save(stateRoot, wakeups) {
     writeScheduleFile(scheduleFile(stateRoot, "wakeups"), wakeups);
     try {
-        wakeupsSink?.(stateRoot, wakeups);
+        wakeupsSink?.(stateRoot);
     }
     catch (e) {
         log.error(`[schedule] wake-alarm sink failed (store write is unaffected): ${String(e)}`);

package/dist/service.d.ts

@@ -1,8 +1,8 @@
 import type { Agent } from "./agent.ts";
+import { type PrefixMount } from "./channels/serve.ts";
 import { type LoadedLongConnectionChannel } from "./channels/discover.ts";
 import type { SessionControl } from "./session.ts";
 import type { ChannelHandler, Routes } from "./channel.ts";
-import { type PrefixMount } from "./channels/serve.ts";
 import type { LoadedSchedule } from "./schedule/schedule.ts";
 export interface ServingSurface {
     routes: Routes;
@@ -12,7 +12,6 @@ export interface ServingSurface {
     /** Route-channel basenames; the tunnel registers only this subset. */
     routeChannels: string[];
     builtinInvoke: boolean;
-    /** Marks the built-in health route ready after every long-connection channel first connects. */
     /** Flip health between 200 and 503. Two-way on purpose: a long connection that dies after coming
      *  up leaves the surface serving something it no longer has, and a load balancer should hear it. */
     setReady(value: boolean): void;