@fastagent-sh/fastagent 0.18.0 → 0.20.0

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.
@@ -330,3 +355,13 @@ export async function assertInsideAgentDir(agentDir, name) {
             `use a real directory or a symlink that stays within it`);
     }
 }
+/**
+ * Whether `targetPath` lives inside `baseDir` (same path counts). Used to ask "did an override move
+ * this OUT of the agent?" — the startup report's redeploy notes, `add`'s printed `.env` label, and the
+ * dev watcher's "your .env is not watched" warning all turn on that fact. Reporting only: fastagent
+ * does not act on where a user's paths point.
+ */
+export function isUnderDir(targetPath, baseDir) {
+    const rel = relative(baseDir, targetPath);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}

package/dist/pi.d.ts

@@ -1,19 +1,25 @@
 export { createPiAgent, createPiAgentFromDefinition, type CreatePiAgentFromDefinitionOptions, type CreatePiAgentOptions, } from "./engines/pi/create.ts";
-export { defineTool, loadTools, type DefineToolOptions, type FastagentTool, type MountedTool, type ToolCollision, type ToolContext, } from "./engines/pi/tool.ts";
+export { defineTool, type DefineToolOptions, type FastagentTool, type MountedTool, type ToolCollision, type ToolContext, } from "./engines/pi/tool.ts";
 export type { ReadonlySessionManager, ToolActivation } from "./engines/pi/tool-context.ts";
 export { z } from "zod";
-export type { AgentTool, ExecutionEnv, Session, SessionTreeEntry, Skill, SkillDiagnostic, } from "@earendil-works/pi-agent-core";
-export { loadChannels, type ChannelCollision } from "./engines/pi/channel.ts";
+export type { AgentTool, ExecutionEnv, Skill, SkillDiagnostic } from "@earendil-works/pi-agent-core";
+/**
+ * A conversation record, as the tool runtime and the control plane hold it. Its entries are pi's own
+ * — exported under a qualified name because `SessionEntry` in this package is the NEUTRAL one the
+ * control plane publishes (session.ts), and the two are different shapes.
+ */
+export type { SessionManager, SessionEntry as PiSessionEntry } from "@earendil-works/pi-coding-agent";
 export { createPiAgentFromDir, type CreatePiAgentFromDirOptions, } from "./engines/pi/open.ts";
 export type { LoadedDefinition, SkillCollision } from "./engines/pi/definition.ts";
-export { defineConfig, listModels, resolveModel, type FastagentConfig } from "./engines/pi/config.ts";
-export type { SessionObserver } from "./engines/pi/invoke.ts";
+export { defineConfig, listModels, resolveModel, type FastagentConfig, } from "./engines/pi/config.ts";
+export type { SessionObserver } from "./engines/pi/turn-kit.ts";
 export { inProcessLease, type Lease, type Release } from "./engines/pi/turn-kit.ts";
 export { createPiSessionControl, type CreatePiSessionControlOptions, } from "./engines/pi/session-control.ts";
-export type { AnyModel } from "./engines/pi/harness.ts";
-export { inMemorySessionStore, jsonlSessionStore, type PiSessionReader, type PiSessionStore, type SessionInheritance, } from "./engines/pi/sessions.ts";
+export { piInMemorySessionRecordStore, piSessionRecordStore, type PiSessionRecordStore, } from "./engines/pi/session-store.ts";
+export type { SessionInheritance } from "./engines/pi/session-inheritance.ts";
 export { GLOBAL_AUTH_PATH, fastagentCredentialStore, type FastagentAuthOptions } from "./engines/pi/auth.ts";
 export { createPiModels, probeAuthSource, type CreatePiModelsOptions } from "./engines/pi/models.ts";
 export type { Models } from "@earendil-works/pi-ai";
-export { createProvider, type Provider, type ProviderAuth } from "@earendil-works/pi-ai";
+export type { Provider, ProviderAuth } from "@earendil-works/pi-ai";
 export type { Model } from "@earendil-works/pi-ai";
+export { createAgentService, type CreateAgentServiceOptions } from "./engines/pi/service.ts";

package/dist/pi.js

@@ -1,13 +1,14 @@
 // The pi reference implementation: assembly, agent discovery, tools, config, models, auth, and state ports.
 export { createPiAgent, createPiAgentFromDefinition, } from "./engines/pi/create.js";
-export { defineTool, loadTools, } from "./engines/pi/tool.js";
+export { defineTool, } from "./engines/pi/tool.js";
 export { z } from "zod";
-export { loadChannels } from "./engines/pi/channel.js";
 export { createPiAgentFromDir, } from "./engines/pi/open.js";
-export { defineConfig, listModels, resolveModel } from "./engines/pi/config.js";
+export { defineConfig, listModels, resolveModel, } from "./engines/pi/config.js";
 export { inProcessLease } from "./engines/pi/turn-kit.js";
 export { createPiSessionControl, } from "./engines/pi/session-control.js";
-export { inMemorySessionStore, jsonlSessionStore, } from "./engines/pi/sessions.js";
+export { piInMemorySessionRecordStore, piSessionRecordStore, } from "./engines/pi/session-store.js";
 export { GLOBAL_AUTH_PATH, fastagentCredentialStore } from "./engines/pi/auth.js";
 export { createPiModels, probeAuthSource } from "./engines/pi/models.js";
-export { createProvider } from "@earendil-works/pi-ai";
+// The product's one-call assembly: a directory becomes a live service. On the pi surface because
+// it opens a directory the pi way (channels, schedules, the assembled agent).
+export { createAgentService } from "./engines/pi/service.js";

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/persona.md

@@ -2,9 +2,9 @@
 
 You are this workspace's agent. This file is your identity — it overrides the engine's default identity line, and it is re-read every turn along with the rest of your definition (`skills/` — capabilities you load when a task calls for them; `tools/` — code tools your author added, in the same directory as this file). An edit to any of them takes effect on your next message, no restart.
 
-Your definition is this directory: `persona.md`, `skills/`, `tools/`, and the config beside them. Your WORKSPACE is the directory you were started in — the project you work on, and where your `read` / `write` / `edit` / `bash` tools operate. It may be this same directory, or the one containing it; `fastagent info` prints both. If the workspace has an `AGENTS.md`, it is project context — read it to learn the project's conventions.
+Your definition is this directory: `persona.md`, `skills/`, `tools/`, and the config beside them. Your WORKSPACE is the directory you were started in — the project you work on. It may be this same directory, or the one containing it; `fastagent info` prints both. Use only the tools actually listed in your system prompt. If the workspace has an `AGENTS.md`, it is project context — follow it without assuming a file tool is available.
 
-You can improve yourself. When a task reveals something durable — a repeatable process, a standing preference, a hard-won fact — write it into your definition instead of losing it:
+When your mounted tools allow it, you can improve yourself. When a task reveals something durable — a repeatable process, a standing preference, a hard-won fact — write it into your definition instead of losing it:
 
 - A repeatable process or capability → a new skill beside this file: `skills/<name>/SKILL.md`. Only the `skills/` next to this file is scanned. Read `skills/writing-great-skills/SKILL.md` first; it is the guide to authoring skills well.
 - A standing instruction or fact → edit this file.

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/state.js

@@ -4,12 +4,10 @@
  *  - `fires.json` — schedule name → last-fired ISO (durability for the cron catch-up-once);
  *  - `wakeups.json` — the agent's pending self-scheduled one-shot wake-ups (wakeups.ts).
  * No .gitignore is written here: the agent's own (scaffolded by `init`) excludes `.state/`.
- *
- * ponytail: this atomic read/write duplicates channels/telegram/state.ts's primitive (both KB-JSON
- * tmp+rename). Extract a neutral src/state.ts and have both import it when a third consumer appears.
  */
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { writeFileAtomic } from "../atomic-write.js";
 import { log } from "../log.js";
 /** Path of a JSON file under `<stateRoot>/schedule/`. */
 export function scheduleFile(stateRoot, name) {
@@ -42,10 +40,7 @@ export function readScheduleFile(path) {
     }
 }
 export function writeScheduleFile(path, value) {
-    mkdirSync(dirname(path), { recursive: true });
-    const tmp = `${path}.tmp`;
-    writeFileSync(tmp, JSON.stringify(value));
-    renameSync(tmp, path);
+    writeFileAtomic(path, JSON.stringify(value));
 }
 export function loadFires(stateRoot) {
     const v = readScheduleFile(scheduleFile(stateRoot, "fires"));

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 = {
@@ -73,7 +73,7 @@ export declare function takeFirstDueWakeup(stateRoot: string, now?: Date): Wakeu
  * already advanced the entry, and its next occurrence comes by definition — a busy one is skipped + audited.
  *
  * Known residual: between the claim (removed from the store) and this re-add there is a microtask-scale
- * window (the busy reject yields before any harness IO) where an `unwake` for this id reports "not found"
+ * window (the busy reject yields before any engine IO) where an `unwake` for this id reports "not found"
  * and the defer then resurrects it — the one-shot cousin of the recurring resurrection the advance-in-place
  * claim eliminated. Accepted: closing it needs a claim-lease with expiry, disproportionate to the window.
  */

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)}`);
@@ -201,7 +204,7 @@ export function takeFirstDueWakeup(stateRoot, now = new Date()) {
  * already advanced the entry, and its next occurrence comes by definition — a busy one is skipped + audited.
  *
  * Known residual: between the claim (removed from the store) and this re-add there is a microtask-scale
- * window (the busy reject yields before any harness IO) where an `unwake` for this id reports "not found"
+ * window (the busy reject yields before any engine IO) where an `unwake` for this id reports "not found"
  * and the defer then resurrects it — the one-shot cousin of the recurring resurrection the advance-in-place
  * claim eliminated. Accepted: closing it needs a claim-lease with expiry, disproportionate to the window.
  */