@code-yeongyu/senpi-agent-core 2026.10.27-2 → 2026.10.30-1

package/dist/durable/testing/wake-cases.js

@@ -0,0 +1,100 @@
+import { expectEqual } from "./store-harness.js";
+import { createSlot, HEARTBEAT_MS, restartHost } from "./wake-harness.js";
+const TEN_MINUTES = 600_000;
+const preArm = async (adapters) => {
+    const slot = await createSlot(adapters);
+    const session = await slot.instance();
+    expectEqual(slot.trace, [`set:+${HEARTBEAT_MS}`, "resume", "clear"], "start arms a fallback before it resumes");
+    slot.trace.length = 0;
+    await session.host.admit(async () => {
+        slot.trace.push(`work alarm=+${await slot.alarmAt()}`);
+    });
+    expectEqual(slot.trace, [`set:+${HEARTBEAT_MS}`, `work alarm=+${HEARTBEAT_MS}`, "clear"], "admit arms durably before work starts, and arms from the idle loop's wake when the work ends");
+    const failing = session.host.admit(async () => {
+        throw new Error("work failed");
+    });
+    await failing.then(() => {
+        throw new Error("a failing admission resolved");
+    }, () => undefined);
+    expectEqual(await slot.alarmAt(), HEARTBEAT_MS, "work that fails leaves the recovery alarm armed");
+    await session.host.admit(() => session.loop.schedule("late", slot.base + TEN_MINUTES));
+    slot.kill();
+    slot.trace.length = 0;
+    await slot.instance();
+    expectEqual(slot.trace, [`set:+${HEARTBEAT_MS}`, "resume", `set:+${TEN_MINUTES}`], "a new instance lowers a later alarm to the fallback before resuming");
+    await (await slot.instance()).host.update({ active: false, at: slot.base + 30_000 });
+    slot.kill();
+    slot.trace.length = 0;
+    await slot.instance();
+    expectEqual(slot.trace, ["resume", `set:+${TEN_MINUTES}`], "an earlier alarm is kept as the fallback");
+};
+const update = async (adapters) => {
+    const slot = await createSlot(adapters);
+    const { host, loop } = await slot.instance();
+    const schedule = (id, offset) => host.admit(() => loop.schedule(id, slot.base + offset));
+    slot.trace.length = 0;
+    await schedule("a", TEN_MINUTES);
+    expectEqual(slot.trace, [`set:+${HEARTBEAT_MS}`, `set:+${HEARTBEAT_MS}`, `set:+${TEN_MINUTES}`], "the commit's update keeps the heartbeat while the admission is in flight; after it, the alarm is the wake");
+    await schedule("b", 300_000);
+    expectEqual(await slot.alarmAt(), 300_000, "an earlier wake lowers the alarm");
+    await schedule("c", 900_000);
+    expectEqual(await slot.alarmAt(), 300_000, "a later wake never raises it past the earliest");
+    await host.update({ active: true, at: slot.base + 300_000 });
+    expectEqual(await slot.alarmAt(), HEARTBEAT_MS, "while active, a heartbeat earlier than the wake");
+    await host.update({ active: true, at: slot.base + 30_000 });
+    expectEqual(await slot.alarmAt(), 30_000, "never later than the earliest wake");
+    await host.update({ active: false });
+    expectEqual(await slot.alarmAt(), undefined, "cleared only when the loop is idle");
+    expectEqual(await slot.ran(), [], "updates run nothing");
+};
+const resume = async (adapters) => {
+    const slot = await createSlot(adapters);
+    const { host, loop } = await slot.instance();
+    for (const [id, offset] of [
+        ["a", 120_000],
+        ["b", 120_000],
+        ["c", TEN_MINUTES],
+    ]) {
+        await host.admit(() => loop.schedule(id, slot.base + offset));
+    }
+    slot.trace.length = 0;
+    await adapters.wake.advanceTo(slot.base + 120_000);
+    expectEqual(slot.fires(), 1, "one fire at the wake");
+    expectEqual(slot.trace.slice(0, 2), [`set:+${120_000 + HEARTBEAT_MS}`, "resume"], "a fire re-arms before resume");
+    expectEqual(await slot.ran(), ["a", "b"], "the due tasks run once, in order");
+    expectEqual(await slot.alarmAt(), TEN_MINUTES, "then the alarm is the next wake");
+    await host.update({ active: true });
+    await adapters.wake.advanceTo(slot.base + 120_000 + HEARTBEAT_MS);
+    expectEqual(await slot.ran(), ["a", "b"], "an early alarm runs nothing");
+    expectEqual(await slot.alarmAt(), TEN_MINUTES, "and re-arms from the loop's wake");
+    await adapters.wake.advanceTo(slot.base + TEN_MINUTES);
+    expectEqual(await slot.ran(), ["a", "b", "c"], "the last task runs at its wake");
+    expectEqual(await slot.alarmAt(), undefined, "an idle loop leaves no alarm");
+    expectEqual(slot.fires(), 3, "no fire beyond the alarms armed");
+};
+const retention = async (adapters) => {
+    const slot = await createSlot(adapters);
+    const { host, loop } = await slot.instance();
+    await host.admit(() => loop.schedule("a", slot.base + TEN_MINUTES));
+    await restartHost(adapters, [slot]);
+    expectEqual(await slot.alarmAt(), TEN_MINUTES, "the alarm is durable across a host restart");
+    await slot.instance();
+    slot.kill();
+    await slot.instance();
+    expectEqual(await slot.alarmAt(), TEN_MINUTES, "reopened instances keep it");
+    await adapters.wake.advanceTo(slot.base + TEN_MINUTES - 1);
+    expectEqual(slot.fires(), 0, "nothing fires early, whatever instances came and went");
+    await adapters.wake.advanceTo(slot.base + TEN_MINUTES);
+    expectEqual(slot.fires(), 1, "it fires once");
+    expectEqual(await slot.ran(), ["a"], "the task runs once");
+    expectEqual(await slot.alarmAt(), undefined, "and the alarm is not retained after the work");
+    await adapters.wake.advanceTo(slot.base + 3 * TEN_MINUTES);
+    expectEqual(slot.fires(), 1, "a consumed alarm never fires again");
+};
+export const WAKE_CASES = new Map([
+    ["WAKE-01", preArm],
+    ["WAKE-02", update],
+    ["WAKE-03", resume],
+    ["WAKE-RET-01", retention],
+]);
+//# sourceMappingURL=wake-cases.js.map

package/dist/durable/testing/wake-harness.d.ts

@@ -0,0 +1,64 @@
+import type { DurableStore, DurableStoreOptions, StoreWritePoint } from "../store.ts";
+import { type WakeAlarm, type WakeAlarmOptions, type WakeAlarmPoint, type WakeHost, type WakePoint } from "../wake-host.ts";
+import type { StoreCaseAdapters } from "./store-harness.ts";
+import { type TestLoop } from "./wake-test-loop.ts";
+/** The session a host's alarm belongs to. Hosts that persist the alarm in the store use `store` under `epoch`. */
+export interface WakeAlarmSession {
+    readonly medium: string;
+    readonly store: DurableStore;
+    readonly epoch: number;
+    readonly onFire: () => Promise<void>;
+    readonly options?: WakeAlarmOptions;
+}
+/** What a host provides to the WAKE, KILL-WAKE and MULTI-HOST cases, next to its store adapter. */
+export interface WakeConformanceAdapter {
+    /** The host clock, epoch milliseconds; only `advanceTo` moves it. */
+    now(): number;
+    /** Move the clock to `at`, delivering every alarm that falls due on the way, in time order, each awaited. */
+    advanceTo(at: number): Promise<void>;
+    /**
+     * The durable alarm of one session. Opening it again (a new instance after a kill) replaces the earlier instance:
+     * fires go to the newest `onFire` only. The armed time outlives instances and host restarts.
+     */
+    openAlarm(session: WakeAlarmSession): Promise<WakeAlarm>;
+    /** The host process restarts: instances and in-memory timers are lost, durable alarms are kept. */
+    restart(): Promise<void>;
+}
+export interface WakeCaseAdapters extends StoreCaseAdapters {
+    readonly wake: WakeConformanceAdapter;
+}
+export declare const HEARTBEAT_MS = 60000;
+export declare const cutStore: (op: StoreWritePoint["op"], at: StoreWritePoint["at"], nth?: number) => DurableStoreOptions;
+export declare const cutAlarm: (op: WakeAlarmPoint["op"], at: WakeAlarmPoint["at"], nth?: number) => WakeAlarmOptions;
+export declare const cutWake: (op: WakePoint["op"], nth?: number) => ((point: WakePoint) => void);
+export declare function expectWakeCut(operation: Promise<unknown>, what: string): Promise<void>;
+export interface SessionInstance {
+    readonly loop: TestLoop;
+    readonly host: WakeHost;
+}
+export interface BootOptions {
+    readonly store?: DurableStoreOptions;
+    readonly alarm?: WakeAlarmOptions;
+    readonly onWakePoint?: (point: WakePoint) => void;
+}
+/** One session on the host: its medium, its live instance (if any), and what the cases observe. */
+export interface SessionSlot {
+    /** The clock time the slot was created at; trace times are relative to it. */
+    readonly base: number;
+    /** Durable alarm writes (`set:+ms` / `clear`) and `resume` calls, in order, across instances. */
+    readonly trace: string[];
+    /** The live instance; with none, boot one (open + `start`) with `options`. */
+    instance(options?: BootOptions): Promise<SessionInstance>;
+    /** Drop the live instance, as an eviction or crash does. */
+    kill(): void;
+    /** Alarm fires delivered to this session. */
+    fires(): number;
+    /** Task IDs the loop committed as run, in commit order. */
+    ran(): Promise<string[]>;
+    /** The durable alarm, relative to `base`; undefined when cleared. */
+    alarmAt(): Promise<number | undefined>;
+}
+export declare function createSlot(adapters: WakeCaseAdapters, epoch?: number): Promise<SessionSlot>;
+/** Restart the host process: every slot loses its live instance; durable state stays. */
+export declare function restartHost(adapters: WakeCaseAdapters, slots: readonly SessionSlot[]): Promise<void>;
+//# sourceMappingURL=wake-harness.d.ts.map

package/dist/durable/testing/wake-harness.js

@@ -0,0 +1,127 @@
+import { createWakeHost, } from "../wake-host.js";
+import { openTestLoop } from "./wake-test-loop.js";
+export const HEARTBEAT_MS = 60_000;
+/** A simulated kill inside a wake case; every cut in these cases throws it. */
+class WakeCut extends Error {
+    constructor(where) {
+        super(`cut at ${where}`);
+        this.name = "WakeCut";
+    }
+}
+const isCut = (error) => error instanceof WakeCut;
+/** Throw a WakeCut the `nth` time `matches` sees a point (1-based). */
+function cutNth(matches, nth) {
+    let seen = 0;
+    return (point) => {
+        if (matches(point) && ++seen === nth)
+            throw new WakeCut(JSON.stringify(point));
+    };
+}
+export const cutStore = (op, at, nth = 1) => ({
+    onWritePoint: cutNth((point) => point.op === op && point.at === at, nth),
+});
+export const cutAlarm = (op, at, nth = 1) => ({
+    onAlarmPoint: cutNth((point) => point.op === op && point.at === at, nth),
+});
+export const cutWake = (op, nth = 1) => cutNth((point) => point.op === op, nth);
+export async function expectWakeCut(operation, what) {
+    try {
+        await operation;
+    }
+    catch (error) {
+        if (isCut(error))
+            return;
+        throw new Error(`${what}: expected the cut to surface, got ${String(error)}`);
+    }
+    throw new Error(`${what}: expected the cut to surface, but it resolved`);
+}
+export async function createSlot(adapters, epoch = 1) {
+    const { store: storeAdapter, wake } = adapters;
+    const medium = await storeAdapter.createMedium();
+    const reader = await storeAdapter.open(medium);
+    for (let next = 1; next <= epoch; next++)
+        await reader.claim(next - 1, next);
+    const base = wake.now();
+    const trace = [];
+    let live;
+    let alarm;
+    let fires = 0;
+    const record = (options) => ({
+        onAlarmPoint: (point) => {
+            options?.onAlarmPoint?.(point);
+            if (point.at === "durable")
+                trace.push(point.op === "clear" ? "clear" : `set:+${(point.time ?? 0) - base}`);
+        },
+    });
+    async function boot(options = {}) {
+        const store = await storeAdapter.open(medium, options.store);
+        let host;
+        const loop = await openTestLoop(store, epoch, wake.now, async () => host?.update(loop.wake()));
+        alarm = await wake.openAlarm({
+            medium,
+            store: await storeAdapter.open(medium),
+            epoch,
+            onFire: dispatch,
+            options: record(options.alarm),
+        });
+        host = createWakeHost({
+            alarm,
+            now: wake.now,
+            wake: () => loop.wake(),
+            resume: async () => {
+                trace.push("resume");
+                await loop.resume();
+            },
+            heartbeatMs: HEARTBEAT_MS,
+            onWakePoint: options.onWakePoint,
+        });
+        const instance = { loop, host };
+        live = instance;
+        await host.start();
+        return instance;
+    }
+    async function dispatch() {
+        fires++;
+        try {
+            const instance = live ?? (await boot());
+            await instance.host.fire();
+        }
+        catch (error) {
+            if (!isCut(error))
+                throw error;
+            live = undefined;
+        }
+    }
+    return {
+        base,
+        trace,
+        async instance(options) {
+            if (live !== undefined)
+                return live;
+            try {
+                return await boot(options);
+            }
+            catch (error) {
+                if (isCut(error))
+                    live = undefined;
+                throw error;
+            }
+        },
+        kill: () => {
+            live = undefined;
+        },
+        fires: () => fires,
+        ran: async () => (await reader.scanRecords({ kind: "ran" })).map((record) => record.id.slice("ran:".length)),
+        alarmAt: async () => {
+            const at = await alarm?.read();
+            return at === undefined ? undefined : at - base;
+        },
+    };
+}
+/** Restart the host process: every slot loses its live instance; durable state stays. */
+export async function restartHost(adapters, slots) {
+    await adapters.wake.restart();
+    for (const slot of slots)
+        slot.kill();
+}
+//# sourceMappingURL=wake-harness.js.map

package/dist/durable/testing/wake-test-loop.d.ts

@@ -0,0 +1,13 @@
+import type { DurableStore } from "../store.ts";
+import type { Wake } from "../wake-host.ts";
+/** A minimal loop over the store: tasks due at a time, each run in one commit. Enough to observe wake ordering. */
+export interface TestLoop {
+    /** Schedule task `id` at `due`, in one commit. */
+    schedule(id: string, due: number): Promise<void>;
+    /** Run every due task, one commit each: a `ran` record and the task's removal, atomically. */
+    resume(): Promise<void>;
+    /** `active` while a task is due now; `at`, the earliest task due later. */
+    wake(): Wake;
+}
+export declare function openTestLoop(store: DurableStore, epoch: number, now: () => number, committed: () => Promise<void>): Promise<TestLoop>;
+//# sourceMappingURL=wake-test-loop.d.ts.map

package/dist/durable/testing/wake-test-loop.js

@@ -0,0 +1,40 @@
+import { createAdmissionLine } from "../store-admission.js";
+const TASK_PREFIX = "task/";
+export async function openTestLoop(store, epoch, now, committed) {
+    const line = createAdmissionLine();
+    const tasks = new Map();
+    for (const document of await store.scanDocuments(TASK_PREFIX)) {
+        if (typeof document.data === "number")
+            tasks.set(document.key.slice(TASK_PREFIX.length), document.data);
+    }
+    const commit = async (writes, adopt) => {
+        await store.commit(epoch, writes, adopt);
+        await committed();
+    };
+    return {
+        schedule: (id, due) => line.admit(() => commit([{ op: "put", key: TASK_PREFIX + id, data: due }], () => void tasks.set(id, due))),
+        resume: () => line.admit(async () => {
+            const due = [...tasks].filter(([, at]) => at <= now()).sort(([a, x], [b, y]) => x - y || (a < b ? -1 : 1));
+            for (const [id] of due) {
+                const writes = [
+                    { op: "append", id: `ran:${id}`, kind: "ran", data: { id } },
+                    { op: "delete", key: TASK_PREFIX + id },
+                ];
+                await commit(writes, () => void tasks.delete(id));
+            }
+        }),
+        wake: () => {
+            const time = now();
+            let active = false;
+            let at;
+            for (const due of tasks.values()) {
+                if (due <= time)
+                    active = true;
+                else if (at === undefined || due < at)
+                    at = due;
+            }
+            return at === undefined ? { active } : { active, at };
+        },
+    };
+}
+//# sourceMappingURL=wake-test-loop.js.map

package/dist/durable/wake-host-bun-timer.d.ts

@@ -0,0 +1,31 @@
+import type { WakeAlarm, WakeAlarmOptions } from "./wake-host.ts";
+import type { AlarmPersistence } from "./wake-host-store-alarm.ts";
+/** Schedule `callback` after `ms`; returns its cancel. */
+export type SetTimer = (callback: () => unknown, ms: number) => () => void;
+export interface BunTimerHostOptions {
+    readonly now?: () => number;
+    readonly setTimer?: SetTimer;
+    /**
+     * The longest single timer. Monotonic timers stop while a machine sleeps, so a far alarm re-checks the wall clock
+     * at least this often and an alarm that fell due during a sleep fires within this bound of waking. Default 60 s.
+     */
+    readonly maxDelayMs?: number;
+    /** A fire handler rejected. The alarm stays armed and fires again after `maxDelayMs`. */
+    readonly onFireError: (key: string, error: unknown) => void;
+}
+/**
+ * The Bun process timer host: one instance serves every session of the process, each under its own key, with its
+ * alarm persisted (normally `storeAlarmPersistence`). After a process restart the embedding host opens its sessions'
+ * alarms again; an alarm that fell due meanwhile fires at once.
+ */
+export interface BunTimerHost {
+    /**
+     * The alarm of session `key`, read from `persistence`. Opening a key again replaces the earlier instance: fires go
+     * to the newest `onFire`, and the replaced instance's writes are refused.
+     */
+    openAlarm(key: string, persistence: AlarmPersistence, onFire: () => Promise<void>, options?: WakeAlarmOptions): Promise<WakeAlarm>;
+    /** Cancel every timer. Persisted alarms stay. */
+    close(): void;
+}
+export declare function createBunTimerHost(options: BunTimerHostOptions): BunTimerHost;
+//# sourceMappingURL=wake-host-bun-timer.d.ts.map

package/dist/durable/wake-host-bun-timer.js

@@ -0,0 +1,66 @@
+const DEFAULT_MAX_DELAY_MS = 60_000;
+const defaultSetTimer = (callback, ms) => {
+    const handle = setTimeout(callback, ms);
+    return () => clearTimeout(handle);
+};
+export function createBunTimerHost(options) {
+    const now = options.now ?? Date.now;
+    const setTimer = options.setTimer ?? defaultSetTimer;
+    const maxDelayMs = options.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+    const entries = new Map();
+    const delivering = new Set();
+    function schedule(key, entry, retry = false) {
+        entry.cancel?.();
+        entry.cancel = undefined;
+        if (entry.at === undefined || entries.get(key) !== entry || delivering.has(key))
+            return;
+        const delay = retry ? maxDelayMs : Math.min(Math.max(0, entry.at - now()), maxDelayMs);
+        entry.cancel = setTimer(() => tick(key, entry), delay);
+    }
+    async function tick(key, entry) {
+        entry.cancel = undefined;
+        const firedAt = entry.at;
+        if (firedAt === undefined || entries.get(key) !== entry)
+            return;
+        if (now() < firedAt)
+            return schedule(key, entry);
+        delivering.add(key);
+        try {
+            await entry.onFire();
+        }
+        catch (error) {
+            options.onFireError(key, error);
+        }
+        finally {
+            delivering.delete(key);
+            const current = entries.get(key);
+            if (current !== undefined)
+                schedule(key, current, current === entry && current.at === firedAt);
+        }
+    }
+    return {
+        async openAlarm(key, persistence, onFire, alarmOptions = {}) {
+            const entry = { at: await persistence.read(), cancel: undefined, onFire };
+            entries.get(key)?.cancel?.();
+            entries.set(key, entry);
+            schedule(key, entry);
+            const write = async (at) => {
+                if (entries.get(key) !== entry)
+                    throw new Error(`the alarm instance of ${key} was replaced by a newer one`);
+                const point = (stage) => alarmOptions.onAlarmPoint?.(at === undefined ? { op: "clear", at: stage } : { op: "set", at: stage, time: at });
+                point("before");
+                await persistence.write(at);
+                entry.at = at;
+                schedule(key, entry);
+                point("durable");
+            };
+            return { read: () => persistence.read(), set: (at) => write(at), clear: () => write(undefined) };
+        },
+        close() {
+            for (const entry of entries.values())
+                entry.cancel?.();
+            entries.clear();
+        },
+    };
+}
+//# sourceMappingURL=wake-host-bun-timer.js.map

package/dist/durable/wake-host-store-alarm.d.ts

@@ -0,0 +1,13 @@
+import type { DurableStore } from "./store.ts";
+/** Where a timer host keeps one session's armed alarm, durably. */
+export interface AlarmPersistence {
+    read(): Promise<number | undefined>;
+    /** Durably arm at `at`, or clear with `undefined`. */
+    write(at: number | undefined): Promise<void>;
+}
+/**
+ * The alarm as a document in the session's own DurableStore, written under the owner `epoch`: an old owner's alarm
+ * write is refused (`stale-epoch`) like any other write of it, and the alarm moves with the store on claim + import.
+ */
+export declare function storeAlarmPersistence(store: DurableStore, epoch: number): AlarmPersistence;
+//# sourceMappingURL=wake-host-store-alarm.d.ts.map

package/dist/durable/wake-host-store-alarm.js

@@ -0,0 +1,20 @@
+const WAKE_ALARM_DOCUMENT = "durable.wake.alarm";
+/**
+ * The alarm as a document in the session's own DurableStore, written under the owner `epoch`: an old owner's alarm
+ * write is refused (`stale-epoch`) like any other write of it, and the alarm moves with the store on claim + import.
+ */
+export function storeAlarmPersistence(store, epoch) {
+    return {
+        read: async () => {
+            const at = await store.getDocument(WAKE_ALARM_DOCUMENT);
+            return typeof at === "number" ? at : undefined;
+        },
+        write: async (at) => {
+            const write = at === undefined
+                ? { op: "delete", key: WAKE_ALARM_DOCUMENT }
+                : { op: "put", key: WAKE_ALARM_DOCUMENT, data: at };
+            await store.commit(epoch, [write], () => { });
+        },
+    };
+}
+//# sourceMappingURL=wake-host-store-alarm.js.map

package/dist/durable/wake-host.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The WakeHost contract of the durable core (packages/agent/docs/durable-core-adr.md): wake ordering for hosts that can
+ * be evicted (a Durable Object) or put to sleep (a laptop). A process timer is lost with its host and runs late across
+ * a sleep, so the host keeps a durable alarm and follows one ordering, shared by every host here:
+ *
+ * - admit: arm a recovery heartbeat durably BEFORE work that can commit starts. A commit whose host dies before the
+ *   alarm update would otherwise strand its wake; an early alarm is harmless, a missing one loses work. The host counts
+ *   admissions in flight and arms as active while any is, so no concurrent update or fire can clear that heartbeat
+ *   before the admitted work commits; when the last admitted work succeeds, it arms from the loop's wake.
+ * - update: after each commit, arm min(heartbeat if active, the loop's earliest wake); clear only when idle.
+ * - fire: re-arm the heartbeat before resuming, so a resume that dies is retried; then arm from the loop's wake.
+ * - start (a new instance): arm a fallback before anything can throw, then resume what a lost instance left.
+ *
+ * Timers inside the loop are not the WakeHost's. Where a host can neither be evicted nor sleep it reduces to a timer.
+ */
+/** The loop's wake state: `active` while some work can run now or is running; `at`, the earliest later wake. */
+export interface Wake {
+    readonly active: boolean;
+    readonly at?: number;
+}
+/** A host's durable alarm for one session; the armed time (epoch ms) survives instance loss and host restarts. */
+export interface WakeAlarm {
+    read(): Promise<number | undefined>;
+    set(at: number): Promise<void>;
+    clear(): Promise<void>;
+}
+/** A point inside an alarm write. `before`: nothing is durable yet. `durable`: the write is durable. */
+export type WakeAlarmPoint = {
+    readonly op: "set";
+    readonly at: "before" | "durable";
+    readonly time: number;
+} | {
+    readonly op: "clear";
+    readonly at: "before" | "durable";
+    readonly time?: undefined;
+};
+export interface WakeAlarmOptions {
+    /** Test seam for cuts and kills: a throw at `before` leaves the alarm unchanged, at `durable` leaves it written. */
+    readonly onAlarmPoint?: (point: WakeAlarmPoint) => void;
+}
+/** The point after an operation's arm is durable and before its work (`admit`) or resume (`start`, `fire`) runs. */
+export interface WakePoint {
+    readonly op: "start" | "admit" | "fire";
+    readonly at: "armed";
+}
+export interface WakeHostOptions {
+    readonly alarm: WakeAlarm;
+    /** The host clock, epoch milliseconds; the same clock the loop's wake times use. */
+    readonly now: () => number;
+    readonly wake: () => Wake;
+    /** Run what the loop can run now: due wakes and work a lost instance left. Resolves when it has. */
+    readonly resume: () => Promise<void>;
+    /** The recovery interval while work is active or admitted. Default 60 s. */
+    readonly heartbeatMs?: number;
+    /** Test seam for kills between an arm and the work it protects. */
+    readonly onWakePoint?: (point: WakePoint) => void;
+}
+export interface WakeHost {
+    /** A new instance: arm a fallback, resume, then arm from the loop's wake. */
+    start(): Promise<void>;
+    /** Run work that can commit, after a recovery heartbeat is durable. */
+    admit<T>(work: () => Promise<T>): Promise<T>;
+    update(wake: Wake): Promise<void>;
+    /** The alarm fired: re-arm the heartbeat, resume, then arm from the loop's wake. */
+    fire(): Promise<void>;
+}
+export declare function createWakeHost(options: WakeHostOptions): WakeHost;
+//# sourceMappingURL=wake-host.d.ts.map

package/dist/durable/wake-host.js

@@ -0,0 +1,70 @@
+/**
+ * The WakeHost contract of the durable core (packages/agent/docs/durable-core-adr.md): wake ordering for hosts that can
+ * be evicted (a Durable Object) or put to sleep (a laptop). A process timer is lost with its host and runs late across
+ * a sleep, so the host keeps a durable alarm and follows one ordering, shared by every host here:
+ *
+ * - admit: arm a recovery heartbeat durably BEFORE work that can commit starts. A commit whose host dies before the
+ *   alarm update would otherwise strand its wake; an early alarm is harmless, a missing one loses work. The host counts
+ *   admissions in flight and arms as active while any is, so no concurrent update or fire can clear that heartbeat
+ *   before the admitted work commits; when the last admitted work succeeds, it arms from the loop's wake.
+ * - update: after each commit, arm min(heartbeat if active, the loop's earliest wake); clear only when idle.
+ * - fire: re-arm the heartbeat before resuming, so a resume that dies is retried; then arm from the loop's wake.
+ * - start (a new instance): arm a fallback before anything can throw, then resume what a lost instance left.
+ *
+ * Timers inside the loop are not the WakeHost's. Where a host can neither be evicted nor sleep it reduces to a timer.
+ */
+const DEFAULT_HEARTBEAT_MS = 60_000;
+/** The alarm time for a wake state: a heartbeat while active, never later than the earliest wake. */
+function recoveryAlarmAt(wake, now, heartbeatMs) {
+    const heartbeat = wake.active ? now + heartbeatMs : undefined;
+    if (heartbeat === undefined)
+        return wake.at;
+    return wake.at === undefined ? heartbeat : Math.min(heartbeat, wake.at);
+}
+export function createWakeHost(options) {
+    const { alarm, now, wake, resume } = options;
+    const heartbeatMs = options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
+    const point = (op) => options.onWakePoint?.({ op, at: "armed" });
+    let admitted = 0;
+    const arm = async (state) => {
+        const at = recoveryAlarmAt(admitted > 0 ? { ...state, active: true } : state, now(), heartbeatMs);
+        if (at === undefined)
+            await alarm.clear();
+        else
+            await alarm.set(at);
+    };
+    return {
+        async start() {
+            const fallback = now() + heartbeatMs;
+            const current = await alarm.read();
+            if (current === undefined || current > fallback)
+                await alarm.set(fallback);
+            point("start");
+            await resume();
+            await arm(wake());
+        },
+        async admit(work) {
+            admitted++;
+            let result;
+            try {
+                await arm({ ...wake(), active: true });
+                point("admit");
+                result = await work();
+            }
+            finally {
+                admitted--;
+            }
+            if (admitted === 0)
+                await arm(wake());
+            return result;
+        },
+        update: (state) => arm(state),
+        async fire() {
+            await arm({ ...wake(), active: true });
+            point("fire");
+            await resume();
+            await arm(wake());
+        },
+    };
+}
+//# sourceMappingURL=wake-host.js.map

package/dist/harness/utils/read-folders/index.d.ts

@@ -3,7 +3,7 @@ export * from "./types.ts";
 /** Frozen measured selection, not a runtime registry that can enable unmeasured grammars. */
 export declare const READ_FOLDER_SELECTION: Readonly<{
     readonly head: "6da8ef1361ef73928df8685e071f2a1826d3b17e";
-    readonly selectionSha256: "d7c502a1597e652f584877c0004ba6cde7c9393c8661ccbc388e3661ae66a634";
+    readonly selectionSha256: "dd4b1fa66ed151e330cd7efaf7ca649d244257d52e2a79422e868da60c0edd8b";
     readonly wasm: true;
     readonly rawReasons: Readonly<{
         readonly ts: "wasm_candidate_below_threshold";

package/dist/harness/utils/read-folders/index.js

@@ -4,7 +4,7 @@ export * from "./types.js";
 /** Frozen measured selection, not a runtime registry that can enable unmeasured grammars. */
 export const READ_FOLDER_SELECTION = Object.freeze({
     head: "6da8ef1361ef73928df8685e071f2a1826d3b17e",
-    selectionSha256: "d7c502a1597e652f584877c0004ba6cde7c9393c8661ccbc388e3661ae66a634",
+    selectionSha256: "dd4b1fa66ed151e330cd7efaf7ca649d244257d52e2a79422e868da60c0edd8b",
     wasm: true,
     rawReasons: Object.freeze({
         ts: "wasm_candidate_below_threshold",

package/dist/harness/utils/read-folders/tree-sitter/engine.d.ts

@@ -11,7 +11,7 @@ export type TreeSitterFolderOptions = {
     readonly parseBudgetMs?: number;
     readonly resolveGrammar?: GrammarResolver;
     readonly resolveRuntime?: () => Promise<string | undefined>;
-    /** Off for tests that inject resolvers; the shipped read path always shares one loaded grammar. */
+    /** Controls grammar/parser sharing; runtime initialization is always shared by resolved path. */
     readonly cache?: boolean;
 };
 /**