@llblab/pi-actors 0.21.0 → 0.22.0

package/BACKLOG.md

@@ -2,6 +2,45 @@
 
 ## Open Work
 
+### Native Windows Smoke and Runtime Notification Follow-up
+
+- Priority: High.
+- Target: Post-0.22.0 validation and hardening.
+- Goal: Validate the cross-platform actor wake/notification layer on native Windows without changing the public actor API or replacing file-backed actor state as the observable source of truth.
+- Decision:
+  - Keep files as durable truth: mailbox/state/event/room files remain canonical for `inspect`, observability, crash recovery, and replay.
+  - Treat runtime notification as an advisory wake layer, not as the queue itself.
+  - Preserve `spawn`, `message`, and `inspect` as the only public actor API; platform transport choices stay internal.
+- Progress:
+  - Prepared the cross-platform runtime notification layer for release with a file-backed runtime notifier boundary using `notify(actor)` / `subscribe(actor, onWake)`, persisted `wake.jsonl` records, `fs.watch` subscription, and periodic fallback coverage.
+  - Notifier subscriptions can now receive explicit reconciliation callbacks for initial scan, wake-triggered scans, and polling fallback.
+  - Run-local `message` delivery now records the durable run inbox entry and advisory wake before attempting the optional live control endpoint; successful endpoint delivery marks the inbox entry `sent`.
+  - Run mailbox inspection now shows recent durable inbox entries alongside recipe-declared mailbox metadata.
+  - Added run inbox claim/handle/fail helpers for runtime loops, including locked claims so reconciliation callbacks can safely dispatch queued mailbox work once.
+  - Added mailbox-only run control endpoints so runtimes can accept `message` through durable inbox/wake state without requiring FIFO or named-pipe delivery.
+  - Migrated the packaged music-player control path to queued mailbox commands as the first concrete script using the mailbox-only runtime direction.
+  - Added a native Windows `wmp` music-player backend using legacy Windows Media Player COM via `powershell.exe`, with `wmplayer.exe` detection in standard Program Files locations and mailbox-backed controls mapped to WMP play/pause/stop operations.
+  - Hardened the music-player mailbox loop to avoid repeated unchanged mailbox reads by combining advisory wake records, `fs.watch`, and inbox signature polling.
+  - Improved Unix-like playback support with the macOS-native `afplay` backend, broader audio extension scanning, and process-group signaling for child playback controls.
+  - Room timeline appends and branch inbox append/status transitions now emit advisory wake records for the addressed room or branch actor.
+- Direction:
+  - Continue wiring mailbox-only endpoints and notifier reconciliation callbacks into concrete packaged actor scripts where file-backed mailbox dispatch should replace transport-specific control loops.
+  - Ensure message delivery writes durable file-backed mailbox/state first, then emits a wake notification.
+  - Require actor runtimes to reconcile mailbox state on wake and also on a periodic fallback so missed notifications do not lose work.
+  - Provide a universal baseline backend using file-system change notification plus periodic reconcile across Linux, macOS, and Windows.
+  - Keep FIFO/named-pipe/socket style endpoints as optional fast wake backends or compatibility paths, not as required durable queues.
+  - Document the model as "wake, not queue": notification wakes a live actor; files remain the queue and audit trail.
+- Windows smoke focus:
+  - Run installed `@llblab/pi-actors@0.22.0` or newer on native Windows.
+  - Verify simple `spawn` / `message` / `inspect` actor communication.
+  - Verify small room-swarm/subagent communication, branch/direct messages, mailbox claim/handled transitions, graceful stop/cancel behavior, and opt-in retirement.
+  - If smoke passes, update docs/release notes from "adapter support" to "Windows smoke-tested subagent communication" for the next release.
+- Exit:
+  - Actor communication works through the cross-platform notifier layer with public API unchanged.
+  - Inspect/observability continue to read canonical file state and do not depend on a live notifier process.
+  - Missed wake notifications are recovered by mailbox reconciliation.
+  - Windows subagent communication smoke is documented with results and any remaining limitations.
+
 ### Consensus-First Build Recipe
 
 - Priority: Medium.

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## 0.22.0: Cross-Platform Runtime Notification Layer
+
+- `[Runtime]` Started the cross-platform notification layer with a file-backed advisory wake notifier (`wake.jsonl`), explicit initial/wake/poll reconciliation callbacks, periodic reconciliation fallback, and run-message/room-message/branch-inbox wake records. Run messages now persist a canonical inbox record before optional endpoint delivery, can accept mailbox-only control endpoints without FIFO/named-pipe transport, mark delivered endpoint messages `sent`, expose recent run inbox entries through `inspect view=mailbox`, and provide locked run-inbox claim/handle/fail helpers for runtime reconciliation loops. Files remain the canonical mailbox/event state for inspection and crash recovery.
+- `[Docs/Tests]` Documented the "wake, not queue" runtime model, added cross-platform music-player smoke guidance, and added coverage for persisted wake events, missed `fs.watch` recovery through polling, and Windows named-pipe message wakes.
+- `[Packaging]` Removed the root JavaScript entrypoint wrapper from packaged files and pointed extension metadata directly at the compiled `dist/index.js` output. Source checkouts keep `index.ts` as the only root entrypoint while installed packages load compiled JavaScript from `dist`.
+- `[Docs/Prompts]` Removed stale FIFO-queue wording from branch-direct message docs and coordinator prompt injection so queued mailbox work is described consistently with the notification/runtime model. Clarified that worker-backed direct branch messages are runner-owned prompt steering, not coordinator follow-ups, while one-shot prompt children do not consume branch inbox records automatically.
+- `[Recipes]` Migrated the packaged music-player control path from Unix FIFO commands to queued mailbox commands, preserving addressed `message` control while making the script align with mailbox-only runtime endpoints.
+- `[Recipes]` Added a native Windows `wmp` music-player backend that drives legacy Windows Media Player through `powershell.exe`/COM, verifies `wmplayer.exe` in the standard Program Files locations, and includes mailbox-backed play, pause, next, previous, and stop controls.
+- `[Recipes]` Reduced music-player mailbox overhead by using advisory wake records, `fs.watch` where available, and inbox file signatures so the loop avoids repeatedly locking and rereading an unchanged mailbox.
+- `[Recipes]` Improved Unix-like playback by adding the macOS-native `afplay` backend, scanning additional common audio extensions, and running child players in their own process group so controls can signal the playback subtree directly.
+- `[Package]` Bumped package metadata, lockfile metadata, and packaged skill metadata for the minor release.
+
 ## 0.21.0: Native Windows Actor Control and Literate Recipes
 
 - `[Async Runs]` Added a platform-adapted run-control path: Unix FIFO behavior remains backward-compatible, native Windows can target named-pipe run-control endpoints recorded in run state, and run message receipts still update events and inbox state through the same actor-message path.
@@ -15,7 +27,7 @@
 - `[Coordinator]` Consolidated direct branch inbox claim/finalize rewrites behind one locked mutation helper and moved room-swarm mode dispatch behind an explicit mode registry. Unknown coordinator modes now fail closed, and `pipeline-room-swarm` exposes the supported mode enum.
 - `[Docs]` Documented the local Actor OS smoke matrix covered by `npm test`, spanning room coordination, direct branch delivery, inbox claim/handle transitions, inspector navigation, recipe context injection, persistence suggestions, and opt-in retirement smoke.
 - `[Docs/Tests]` Documented native Windows support scope and added regression coverage for Windows endpoint metadata, mocked named-pipe sends, Windows process-control planning, unchanged Unix FIFO behavior, locker control metadata, branch inbox compaction, mixed room/direct workloads, Markdown recipe loading/discovery/validation, nested child-run retirement gating, and packaged recipe trust diagnostics.
-- `[Package]` Bumped package metadata, lockfile metadata, and packaged skill metadata to `0.21.0` for the minor release.
+- `[Package]` Bumped package metadata, lockfile metadata, and packaged skill metadata for the minor release.
 
 ## 0.20.2: Installed Extension Entrypoint Hotfix
 

package/dist/lib/actor-rooms.js

@@ -6,6 +6,7 @@
 import * as fs from "node:fs";
 import { randomUUID } from "node:crypto";
 import * as path from "node:path";
+import { notifyRuntimeWake } from "./runtime-notifier.js";
 const STATE_LOCK_MAX_AGE_MS = 5 * 60 * 1000;
 const STATE_LOCK_TIMEOUT_MS = 5000;
 const DEFAULT_ROOM_MAX_MESSAGES = 10000;
@@ -98,6 +99,14 @@ function writeJsonFile(file, value) {
     fs.mkdirSync(path.dirname(file), { recursive: true });
     fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
 }
+function notifyActorWake(stateDir, actor, reason, metadata = {}) {
+    try {
+        notifyRuntimeWake(stateDir, { actor, metadata, reason });
+    }
+    catch {
+        // Runtime wakes are advisory; durable room/inbox state remains canonical.
+    }
+}
 function positiveEnvInt(name, fallback) {
     const value = Number(process.env[name] ?? fallback);
     return Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
@@ -295,6 +304,10 @@ export function appendBranchInboxMessage(stateDir, run, address, message) {
     const releaseLock = acquireBranchInboxLock(stateDir, branch);
     try {
         fs.writeFileSync(branchInboxFile(stateDir, branch), `${JSON.stringify({ ...message, id: randomUUID(), queued_at: new Date().toISOString(), status: "queued" })}\n`, { flag: "a" });
+        notifyActorWake(stateDir, address, "branch.message", {
+            ...(message.from ? { from: message.from } : {}),
+            type: message.type,
+        });
     }
     finally {
         releaseLock();
@@ -320,6 +333,7 @@ export function updateBranchInboxMessageStatus(stateDir, run, address, id, statu
             return false;
         const compacted = compactBranchInboxMessages(updated);
         fs.writeFileSync(file, `${compacted.map((message) => JSON.stringify(message)).join("\n")}\n`);
+        notifyActorWake(stateDir, address, "branch.inbox.status", { id, status });
         return true;
     }
     finally {
@@ -337,6 +351,10 @@ export function appendRoomMessage(stateDir, room, message) {
         const run = runFromRoomAddress(message.to);
         if (run) {
             writeCommunicationSnapshot(stateDir, run);
+            notifyActorWake(stateDir, message.to, "room.message", {
+                ...(message.from ? { from: message.from } : {}),
+                type: message.type,
+            });
             if (message.from && branchIdFromAddress(message.from, run)) {
                 writeBranchCommunicationSnapshotDebounced(stateDir, run, message.from);
             }

package/dist/lib/async-runs.d.ts

@@ -8,7 +8,7 @@ import * as RecipeReferences from "./recipe-references.ts";
 export type AsyncRunLaunchSource = "spawn" | "tool";
 export interface AsyncRunControlEndpoint {
     path: string;
-    type: "fifo" | "named-pipe";
+    type: "fifo" | "mailbox" | "named-pipe";
 }
 export interface AsyncRunStartParams {
     async?: boolean;
@@ -88,6 +88,24 @@ export declare function getRunStatus(runOrDir: string): Record<string, unknown>;
 export declare function listRuns(stateRoot?: string, statusFilter?: string): Array<Record<string, unknown>>;
 export declare function tailRun(runOrDir: string, lines?: number): string;
 export declare function readRunEvents(runOrDir: string, lines?: number): RunOutboxEvent[];
+export type RunInboxStatus = "queued" | "sent" | "claimed" | "handled" | "failed";
+export type RunInboxMessage = Record<string, unknown> & {
+    id?: string;
+    status?: RunInboxStatus | string;
+};
+export interface ProcessRunInboxResult {
+    claimed: number;
+    failed: number;
+    handled: number;
+}
+export declare function readRunInboxMessages(runOrDir: string, lines?: number): RunInboxMessage[];
+export declare function updateRunInboxMessageStatus(runOrDir: string, id: string, nextStatus: RunInboxStatus, metadata?: Record<string, unknown>): boolean;
+export declare function claimRunInboxMessage(runOrDir: string, owner?: string, statuses?: string[]): RunInboxMessage | undefined;
+export declare function processRunInboxMessages(runOrDir: string, handler: (message: RunInboxMessage) => Promise<void> | void, options?: {
+    limit?: number;
+    owner?: string;
+    statuses?: string[];
+}): Promise<ProcessRunInboxResult>;
 export declare function appendRunOutboxEvent(runOrDir: string, event: {
     body?: unknown;
     correlation_id?: string;

package/dist/lib/async-runs.js

@@ -3,6 +3,7 @@
  * Zones: async runtime, lifecycle, state files
  * Owns detached run state, observation, log tailing, listing, and cancellation safety
  */
+import { randomUUID } from "node:crypto";
 import { spawn, spawnSync } from "node:child_process";
 import { closeSync, constants, existsSync, mkdirSync, openSync, readdirSync, readFileSync, readlinkSync, rmSync, statSync, writeFileSync, writeSync, } from "node:fs";
 import { createConnection } from "node:net";
@@ -14,7 +15,9 @@ import { writeJsonAtomic } from "./file-state.js";
 import * as Paths from "./paths.js";
 import * as RecipeReferences from "./recipe-references.js";
 import * as RecipeUsage from "./recipe-usage.js";
+import { notifyRuntimeWake } from "./runtime-notifier.js";
 const START_LOCK_MAX_AGE_MS = 5 * 60 * 1000;
+const RUN_INBOX_LOCK_TIMEOUT_MS = 5000;
 const DEFAULT_STATE_ROOT = Paths.getRunStateRoot();
 const DEFAULT_RECIPE_ROOT = Paths.getRecipeRoot();
 function packageRoot() {
@@ -479,6 +482,145 @@ export function readRunEvents(runOrDir, lines = 40) {
         .map((line, index) => parseRunOutboxEventLine(line, run, stateDir, index))
         .filter((event) => Boolean(event));
 }
+function runInboxFile(stateDir) {
+    return join(stateDir, "inbox.jsonl");
+}
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function acquireRunInboxLock(stateDir) {
+    const lockDir = join(stateDir, ".inbox.lock");
+    const started = Date.now();
+    while (true) {
+        try {
+            mkdirSync(lockDir, { recursive: false });
+            writeFileSync(join(lockDir, "owner.json"), `${JSON.stringify({ pid: process.pid, created_at: new Date().toISOString() })}\n`, "utf8");
+            return () => rmSync(lockDir, { recursive: true, force: true });
+        }
+        catch (error) {
+            try {
+                const stat = statSync(lockDir);
+                if (Date.now() - stat.mtimeMs > START_LOCK_MAX_AGE_MS) {
+                    rmSync(lockDir, { recursive: true, force: true });
+                    continue;
+                }
+            }
+            catch {
+                continue;
+            }
+            if (Date.now() - started > RUN_INBOX_LOCK_TIMEOUT_MS) {
+                throw new Error("Run inbox lock timed out.", { cause: error });
+            }
+            sleepSync(10);
+        }
+    }
+}
+function parseRunInboxLine(line) {
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+}
+function readRunInboxMessagesFromStateDir(stateDir) {
+    const file = runInboxFile(stateDir);
+    if (!existsSync(file))
+        return [];
+    return readFileSync(file, "utf8")
+        .split("\n")
+        .filter((line) => line.trim())
+        .map(parseRunInboxLine)
+        .filter((message) => Boolean(message));
+}
+function writeRunInboxMessages(stateDir, messages) {
+    writeFileSync(runInboxFile(stateDir), messages.length
+        ? `${messages.map((message) => JSON.stringify(message)).join("\n")}\n`
+        : "", "utf8");
+}
+export function readRunInboxMessages(runOrDir, lines = 40) {
+    const status = getRunStatus(runOrDir);
+    const stateDir = String(status.state_dir);
+    return tailLines(runInboxFile(stateDir), lines)
+        .map(parseRunInboxLine)
+        .filter((message) => Boolean(message));
+}
+export function updateRunInboxMessageStatus(runOrDir, id, nextStatus, metadata = {}) {
+    const status = getRunStatus(runOrDir);
+    const stateDir = String(status.state_dir);
+    const releaseLock = acquireRunInboxLock(stateDir);
+    try {
+        const messages = readRunInboxMessagesFromStateDir(stateDir);
+        const timestampKey = `${nextStatus}_at`;
+        let changed = false;
+        const updated = messages.map((message) => {
+            if (message.id !== id)
+                return message;
+            changed = true;
+            return {
+                ...message,
+                ...metadata,
+                [timestampKey]: new Date().toISOString(),
+                status: nextStatus,
+            };
+        });
+        if (changed)
+            writeRunInboxMessages(stateDir, updated);
+        return changed;
+    }
+    finally {
+        releaseLock();
+    }
+}
+export function claimRunInboxMessage(runOrDir, owner = "runtime", statuses = ["queued"]) {
+    const status = getRunStatus(runOrDir);
+    const stateDir = String(status.state_dir);
+    const releaseLock = acquireRunInboxLock(stateDir);
+    try {
+        const messages = readRunInboxMessagesFromStateDir(stateDir);
+        const index = messages.findIndex((message) => statuses.includes(String(message.status ?? "queued")));
+        if (index < 0)
+            return undefined;
+        const claimed = {
+            ...messages[index],
+            claimed_at: new Date().toISOString(),
+            claimed_by: owner,
+            id: typeof messages[index].id === "string" ? messages[index].id : randomUUID(),
+            status: "claimed",
+        };
+        messages[index] = claimed;
+        writeRunInboxMessages(stateDir, messages);
+        return claimed;
+    }
+    finally {
+        releaseLock();
+    }
+}
+export async function processRunInboxMessages(runOrDir, handler, options = {}) {
+    const result = { claimed: 0, failed: 0, handled: 0 };
+    const limit = Math.max(1, Number(options.limit ?? 1));
+    const owner = options.owner ?? "runtime";
+    for (let index = 0; index < limit; index += 1) {
+        const message = claimRunInboxMessage(runOrDir, owner, options.statuses);
+        if (!message?.id)
+            break;
+        result.claimed += 1;
+        try {
+            await handler(message);
+            if (updateRunInboxMessageStatus(runOrDir, message.id, "handled")) {
+                result.handled += 1;
+            }
+        }
+        catch (error) {
+            if (updateRunInboxMessageStatus(runOrDir, message.id, "failed", {
+                error: error instanceof Error ? error.message : String(error),
+            })) {
+                result.failed += 1;
+            }
+        }
+    }
+    return result;
+}
 export function appendRunOutboxEvent(runOrDir, event) {
     const status = getRunStatus(runOrDir);
     const stateDir = String(status.state_dir);
@@ -514,7 +656,9 @@ function getRunControlEndpoint(status, stateDir) {
     const control = status.control;
     if (control && typeof control === "object" && !Array.isArray(control)) {
         const record = control;
-        if ((record.type === "fifo" || record.type === "named-pipe") &&
+        if ((record.type === "fifo" ||
+            record.type === "mailbox" ||
+            record.type === "named-pipe") &&
             typeof record.path === "string" &&
             record.path.trim()) {
             return { path: record.path, type: record.type };
@@ -522,18 +666,34 @@ function getRunControlEndpoint(status, stateDir) {
     }
     return { path: join(stateDir, "control.fifo"), type: "fifo" };
 }
-function writeRunMessageReceipt(stateDir, message, bytes) {
-    const trimmedMessage = message.trim().toLowerCase();
-    const terminalMessage = ["stop", "cancel", "quit", "exit"].includes(trimmedMessage);
+function appendRunInboxMessage(stateDir, message) {
+    const id = randomUUID();
     const ts = new Date().toISOString();
-    writeFileSync(join(stateDir, "events.jsonl"), `${JSON.stringify({ bytes, event: "run.message", terminal: terminalMessage || undefined, ts })}\n`, { flag: "a" });
+    let record;
     try {
-        const envelope = JSON.parse(message);
-        writeFileSync(join(stateDir, "inbox.jsonl"), `${JSON.stringify({ ...envelope, received_at: ts })}\n`, { flag: "a" });
+        const parsed = JSON.parse(message);
+        record = parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : { body: parsed, type: "run.message" };
     }
     catch {
-        // Plain control lines are already represented in events.jsonl.
+        record = { body: message, type: "run.message" };
+    }
+    const releaseLock = acquireRunInboxLock(stateDir);
+    try {
+        writeFileSync(runInboxFile(stateDir), `${JSON.stringify({ ...record, id, queued_at: ts, received_at: ts, status: "queued" })}\n`, { flag: "a" });
     }
+    finally {
+        releaseLock();
+    }
+    return id;
+}
+function writeRunMessageReceipt(stateDir, message, bytes, inboxId) {
+    const trimmedMessage = message.trim().toLowerCase();
+    const terminalMessage = ["stop", "cancel", "quit", "exit"].includes(trimmedMessage);
+    const ts = new Date().toISOString();
+    writeFileSync(join(stateDir, "events.jsonl"), `${JSON.stringify({ bytes, event: "run.message", inbox_id: inboxId, terminal: terminalMessage || undefined, ts })}\n`, { flag: "a" });
+    updateRunInboxMessageStatus(stateDir, inboxId, "sent", { bytes });
     if (terminalMessage) {
         markTerminalHandled(stateDir, {
             event: "run.message",
@@ -558,6 +718,19 @@ function sendRunMessageToFifo(endpoint, payload) {
             closeSync(fd);
     }
 }
+function notifyRunMessageWake(stateDir, run, bytes, endpoint, inboxId) {
+    try {
+        const event = notifyRuntimeWake(stateDir, {
+            actor: `run:${run}`,
+            metadata: { bytes, control_type: endpoint.type, inbox_id: inboxId },
+            reason: "run.message",
+        });
+        return { wake: "wake.jsonl", wake_id: event.id };
+    }
+    catch {
+        return undefined;
+    }
+}
 function sendRunMessageToNamedPipe(endpoint, payload, send) {
     if (send)
         return send(endpoint.path, payload);
@@ -600,15 +773,32 @@ export async function sendRunMessage(runOrDir, message, options = {}) {
         throw new Error(`Run pid owner mismatch: ${run}`);
     const endpoint = getRunControlEndpoint(status, stateDir);
     const payload = message.endsWith("\n") ? message : `${message}\n`;
+    const payloadBytes = Buffer.byteLength(payload);
+    const inboxId = appendRunInboxMessage(stateDir, message);
+    const wake = notifyRunMessageWake(stateDir, run, payloadBytes, endpoint, inboxId);
     const runtimePlatform = options.platform ?? process.platform;
+    if (endpoint.type === "mailbox") {
+        return {
+            ...(wake ?? {}),
+            bytes: payloadBytes,
+            control: "inbox.jsonl",
+            control_path: endpoint.path,
+            control_type: endpoint.type,
+            queued: true,
+            run,
+            sent: true,
+            state_dir: stateDir,
+        };
+    }
     try {
         if (endpoint.type === "fifo") {
             if (runtimePlatform === "win32") {
                 throw new Error("run actor messages on native Windows require a named-pipe control endpoint; this recipe still exposes Unix FIFO control.");
             }
             const bytes = sendRunMessageToFifo(endpoint, payload);
-            writeRunMessageReceipt(stateDir, message, bytes);
+            writeRunMessageReceipt(stateDir, message, bytes, inboxId);
             return {
+                ...(wake ?? {}),
                 bytes,
                 control: "control.fifo",
                 control_path: endpoint.path,
@@ -619,8 +809,9 @@ export async function sendRunMessage(runOrDir, message, options = {}) {
             };
         }
         const bytes = await sendRunMessageToNamedPipe(endpoint, payload, options.namedPipeSend);
-        writeRunMessageReceipt(stateDir, message, bytes);
+        writeRunMessageReceipt(stateDir, message, bytes, inboxId);
         return {
+            ...(wake ?? {}),
             bytes,
             control: endpoint.path,
             control_path: endpoint.path,

package/dist/lib/runtime-notifier.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Runtime wake notifications for actor state.
+ * Zones: advisory wake layer, file-backed runtime state, cross-platform notification boundary
+ * Owns best-effort live wake signals while durable mailbox/state files remain canonical.
+ */
+export interface RuntimeWakeEvent {
+    actor: string;
+    id: string;
+    metadata?: Record<string, unknown>;
+    reason: string;
+    state_dir: string;
+    ts: string;
+}
+export interface RuntimeNotifierSubscription {
+    close(): void;
+}
+export type RuntimeReconcileReason = "initial" | "poll" | "wake";
+export interface RuntimeReconcileEvent {
+    actor: string;
+    reason: RuntimeReconcileReason;
+    state_dir: string;
+    ts: string;
+}
+export interface RuntimeNotifierSubscribeOptions {
+    onReconcile?: (event: RuntimeReconcileEvent) => void;
+}
+export interface FileRuntimeNotifierOptions {
+    pollIntervalMs?: number;
+    replay?: boolean;
+    watch?: boolean;
+}
+export interface RuntimeNotifier {
+    notify(event: {
+        actor: string;
+        metadata?: Record<string, unknown>;
+        reason: string;
+    }): RuntimeWakeEvent;
+    subscribe(actor: string, onWake: (event: RuntimeWakeEvent) => void, options?: RuntimeNotifierSubscribeOptions): RuntimeNotifierSubscription;
+}
+export declare function runtimeWakeFile(stateDir: string): string;
+export declare function notifyRuntimeWake(stateDir: string, event: {
+    actor: string;
+    metadata?: Record<string, unknown>;
+    reason: string;
+}): RuntimeWakeEvent;
+export declare function parseRuntimeWakeEventLine(line: string): RuntimeWakeEvent | undefined;
+export declare function readRuntimeWakeEvents(stateDir: string): RuntimeWakeEvent[];
+export declare function createFileRuntimeNotifier(stateDir: string, options?: FileRuntimeNotifierOptions): RuntimeNotifier;

package/dist/lib/runtime-notifier.js

@@ -0,0 +1,137 @@
+/**
+ * Runtime wake notifications for actor state.
+ * Zones: advisory wake layer, file-backed runtime state, cross-platform notification boundary
+ * Owns best-effort live wake signals while durable mailbox/state files remain canonical.
+ */
+import { randomUUID } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, watch, } from "node:fs";
+import { basename, dirname, join } from "node:path";
+const DEFAULT_POLL_INTERVAL_MS = 1000;
+export function runtimeWakeFile(stateDir) {
+    return join(stateDir, "wake.jsonl");
+}
+function normalizeWakeEvent(stateDir, event) {
+    const actor = event.actor.trim();
+    const reason = event.reason.trim();
+    if (!actor)
+        throw new Error("Runtime wake event requires actor.");
+    if (!reason)
+        throw new Error("Runtime wake event requires reason.");
+    return {
+        actor,
+        id: randomUUID(),
+        ...(event.metadata ? { metadata: event.metadata } : {}),
+        reason,
+        state_dir: stateDir,
+        ts: new Date().toISOString(),
+    };
+}
+export function notifyRuntimeWake(stateDir, event) {
+    const normalized = normalizeWakeEvent(stateDir, event);
+    const file = runtimeWakeFile(stateDir);
+    mkdirSync(dirname(file), { recursive: true });
+    appendFileSync(file, `${JSON.stringify(normalized)}\n`, "utf8");
+    return normalized;
+}
+export function parseRuntimeWakeEventLine(line) {
+    try {
+        const record = JSON.parse(line);
+        if (typeof record.actor !== "string" ||
+            typeof record.id !== "string" ||
+            typeof record.reason !== "string" ||
+            typeof record.state_dir !== "string" ||
+            typeof record.ts !== "string") {
+            return undefined;
+        }
+        return {
+            actor: record.actor,
+            id: record.id,
+            ...(record.metadata &&
+                typeof record.metadata === "object" &&
+                !Array.isArray(record.metadata)
+                ? { metadata: record.metadata }
+                : {}),
+            reason: record.reason,
+            state_dir: record.state_dir,
+            ts: record.ts,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+export function readRuntimeWakeEvents(stateDir) {
+    const file = runtimeWakeFile(stateDir);
+    if (!existsSync(file))
+        return [];
+    return readFileSync(file, "utf8")
+        .split("\n")
+        .filter((line) => line.trim())
+        .map(parseRuntimeWakeEventLine)
+        .filter((event) => Boolean(event));
+}
+export function createFileRuntimeNotifier(stateDir, options = {}) {
+    const file = runtimeWakeFile(stateDir);
+    const pollIntervalMs = Math.max(25, Number(options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS));
+    return {
+        notify: (event) => notifyRuntimeWake(stateDir, event),
+        subscribe: (actor, onWake, subscribeOptions = {}) => {
+            mkdirSync(dirname(file), { recursive: true });
+            let position = options.replay || !existsSync(file) ? 0 : statSync(file).size;
+            let closed = false;
+            const reconcile = (reason) => {
+                if (closed)
+                    return;
+                subscribeOptions.onReconcile?.({
+                    actor,
+                    reason,
+                    state_dir: stateDir,
+                    ts: new Date().toISOString(),
+                });
+            };
+            const drain = () => {
+                if (closed || !existsSync(file))
+                    return;
+                const buffer = readFileSync(file);
+                if (position > buffer.length)
+                    position = 0;
+                const chunk = buffer.subarray(position).toString("utf8");
+                position = buffer.length;
+                for (const line of chunk.split("\n")) {
+                    if (!line.trim())
+                        continue;
+                    const event = parseRuntimeWakeEventLine(line);
+                    if (event && event.actor === actor) {
+                        onWake(event);
+                        reconcile("wake");
+                    }
+                }
+            };
+            let watcher;
+            if (options.watch !== false) {
+                try {
+                    watcher = watch(dirname(file), { persistent: false }, (_eventType, changedFile) => {
+                        if (!changedFile || String(changedFile) === basename(file))
+                            drain();
+                    });
+                }
+                catch {
+                    // fs.watch availability varies by platform/filesystem; polling below is the fallback.
+                }
+            }
+            reconcile("initial");
+            const timer = setInterval(() => {
+                drain();
+                reconcile("poll");
+            }, pollIntervalMs);
+            timer.unref?.();
+            return {
+                close: () => {
+                    closed = true;
+                    clearInterval(timer);
+                    watcher?.close();
+                },
+            };
+        },
+    };
+}