@llblab/pi-actors 0.20.2 → 0.22.0

package/BACKLOG.md

@@ -2,78 +2,44 @@
 
 ## Open Work
 
-### Branch Inbox Retention and Transition Scaling
-
-- Priority: Medium.
-- Goal: Keep direct branch message queues reliable for long-lived interactive branch runners without unbounded rewrite amplification.
-- Direction:
-  - Evaluate current whole-file branch inbox status rewrites under realistic long-lived direct-message workloads.
-  - Consider bounded retention, compaction, or append-only transition logs for `queued` / `claimed` / `handled` / `failed` state changes while preserving stable message IDs and exact-once claim semantics.
-  - Keep branch-local inbox append/status mutations lock-guarded and preserve inspector visibility for unread/current-branch filters.
-- Exit:
-  - A documented decision or implementation explains how branch inboxes scale for persistent runners and proves existing direct-message semantics remain compatible.
-
-### Installed Recipe Trust Boundary Hardening
-
-- Priority: Medium.
-- Goal: Keep recipe-library growth local-first without letting operator muscle memory become an accidental sandbox bypass.
-- Direction:
-  - Review packaged recipes, examples, and docs for destructive or external side effects and ensure they require explicit paths, typed args, narrow helper scripts, and clear operator gates.
-  - Keep warnings framed as diagnostics, not a security boundary.
-  - Prefer small audited helper scripts over broad shell templates when recipes touch files, processes, networks, or external services.
-- Exit:
-  - A trust-boundary review confirms packaged recipes and docs preserve the current local-first/not-sandbox-first contract, with any needed hardening captured in tests or docs.
-
-### Direct Branch Message Consumption Semantics
-
-- Priority: Medium.
-- Goal: Make it impossible to misunderstand branch inbox delivery as universal active delivery without a consuming coordinator or runner protocol.
-- Direction:
-  - Audit README, actor-message docs, async-run docs, actors skill, and recipe guidance for branch inbox wording.
-  - Clarify that direct branch messages are queued and become active work only when the relevant coordinator/runner claims, injects, handles, or fails them.
-  - Add or update a bounded smoke scenario that demonstrates queued direct messages, claim/handle transitions, and inspector visibility.
-- Exit:
-  - Public docs and tests show both halves of direct branch delivery: durable branch-local queueing and explicit worker consumption semantics.
-
-### Actor Rooms, Roster, and Cross-Branch Messaging
+### Native Windows Smoke and Runtime Notification Follow-up
 
 - Priority: High.
-- Goal: Continue evolving actor communication without adding a second public messaging model.
+- 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:
-  - Evaluate whether room storage/routing should remain built into the tool adapter or move behind a dedicated non-LLM communication actor recipe/script, possibly singleton-scoped. Preserve the same public `room:<run>` address and envelope either way.
-  - Treat the next backend decision as an evidence-backed experiment, not a rewrite: stress a real room/direct-message workload, compare the current file-backed adapter with a thin communication actor/helper, and record the decision.
-  - Consider reducing direct file-backed state where it improves coherence: model room/roster state as actor-owned data structures served by helper scripts/actors, with files retained only for durable snapshots, recovery, artifacts, or audit logs.
-  - Further storage changes should preserve the current burst/read/concurrency safeguards: branch communication snapshot writes are debounced, root snapshots stay current, roster files are not rewritten during bursts when only `last_seen` changes, room status inspection does not parse full timelines, branch-local inbox append/status rewrites are lock-guarded, and legacy no-ID branch inbox records can be claimed exactly once.
-  - Prevent monolith drift: `actor-rooms.ts` may remain a thin adapter, but growing routing policy, subscription loops, fanout policy, or long-lived state ownership should move behind a focused communication helper/actor rather than accumulating in the tool adapter.
+  - 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:
-  - Any backend/storage change preserves existing `spawn` / `message` / `inspect` semantics and room address compatibility.
-  - A short decision note or changelog entry explains why the room backend stayed file-backed or moved behind a communication actor/helper.
-
-### Graceful Actor Retirement
-
-- Priority: Medium.
-- Goal: Automatically retire coordinator/helper actors that were launched only to supervise a bounded worker tree once their dependent workers have finished.
-- Direction:
-  - Build on the existing `retire_when: "children_terminal"` recipe/run metadata contract and observability retirement-candidate detection for ephemeral supervisors.
-  - Treat auto-retirement as opt-in only; never infer it for arbitrary long-lived services, user tools, or persistent backlog implementers.
-  - Extend candidate detection beyond current active command/proc-descendant gating to full observed child async-run state rather than log text: the supervisor may retire only when all launched child async runs are terminal and required artifacts/outbox events have been flushed.
-  - Prefer graceful stop (`control.stop` / actor message) before process termination; escalate only after a bounded timeout and record the retirement event in run state.
-  - Preserve manual `cancel` / `kill` semantics and make retirement visible through `inspect` / ambient observability.
-- Exit:
-  - A packaged coordinator recipe can launch worker actors, complete its coordination duties, and shut itself down automatically after the worker tree reaches terminal state.
-  - Persistent services and implementer actors remain alive unless their recipe explicitly opts into retirement.
-
-### Coordinator Strategy Boundary
-
-- Priority: Medium.
-- Goal: Keep the generic coordinator from becoming a second overloaded monolith as room/direct-message workflows mature.
-- Direction:
-  - Split only at real pressure points: branch inbox claim/finalize helpers, participant execution, room transcript synthesis, and mode strategies are likely seams, but avoid cosmetic module churn.
-  - Preserve the current principle that the locker stays generic/thin and all orchestration policy stays in coordinator strategy code or recipe composition.
-  - Prefer reusable helper modules or small scripts only when at least two packaged workflows need the same behavior.
-- Exit:
-  - Adding a new coordinator mode or packaged multi-agent workflow does not require editing unrelated mode logic.
-  - Existing room-swarm, locker, and direct-branch-message tests still cover the extracted seams.
+  - 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
 
@@ -90,18 +56,6 @@
   - A packaged recipe can reproduce the interactive-music-instrument workflow shape for another single-artifact task without copying the demo script.
   - Docs and skills point agents to the packaged recipe and explain when to choose it over a free-form room swarm.
 
-### Actor OS Scenario Smoke Matrix
-
-- Priority: Medium.
-- Goal: Convert the 0.19.x actor-communication hardening into repeatable end-to-end scenario checks instead of relying on ad hoc demos.
-- Direction:
-  - Cover one scenario each for shared room coordination, direct branch work delivery, branch inbox claim/handle/fail transitions, inspector navigation, recipe context injection, recipe persistence suggestion, and opt-in retirement candidate detection.
-  - Keep scenarios local-first and bounded: fake `pi`/models where possible, no external services, no long sleeps, no broad golden transcripts.
-  - Prefer packaged recipes and public `spawn` / `message` / `inspect` calls so the smoke matrix exercises the same surface agents use.
-- Exit:
-  - A single validation command or documented test group verifies the actor OS behaviors that made 0.19.x production-useful.
-  - The smoke matrix catches regressions in actor communication, recipe memory, and observability without requiring a manual swarm demo.
-
 ### Persistent Backlog Implementer Workflow
 
 - Priority: Medium.

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 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.
+- `[Async Runs]` Added Windows process-tree termination planning for cancel/kill through `taskkill`, while preserving Unix process-group signaling semantics.
+- `[Scripts]` Migrated `locker.mjs` and coordinator locker calls to platform-adapted control metadata: Unix still uses `control.fifo`, while native Windows can use a deterministic named-pipe endpoint with the same message protocol.
+- `[Branch Messages]` Added bounded branch-inbox terminal retention during status transitions, preserving active queued/claimed work while compacting older handled/failed records for long-lived branch runners.
+- `[Recipe Discovery]` Tightened trust-boundary diagnostics so combined short shell/eval flags such as `bash -lc` and nested recipe command-template objects are surfaced, including the packaged validation wrapper's trusted shell boundary.
+- `[Rooms]` Recorded the backend decision to keep the current file-backed room adapter until real workflows need live subscriptions/fanout or shared mutable state, backed by a mixed room/direct-branch workload regression.
+- `[Recipes]` Added Markdown-authored recipe loading for `.md` files with frontmatter metadata and fenced executable recipe/template blocks, with same-id JSON shadowing Markdown in the same priority layer.
+- `[Retirement]` Extended run summaries to discover nested child async-run state dirs, blocks opt-in retirement while nested children are still running, surfaces child/terminal child counts on candidates, and has the session watcher retire ready candidates with one graceful stop attempt plus owned cancellation fallback. Added an integration smoke where an idle supervisor stops after its nested child is terminal while a non-opt-in service remains running.
+- `[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 for the minor release.
+
 ## 0.20.2: Installed Extension Entrypoint Hotfix
 
 - `[Packaging]` Added a JavaScript extension entrypoint wrapper and changed package metadata to load `./index.js`, so npm-installed packages import compiled `dist/index.js` instead of asking Node to strip `index.ts` under `node_modules`. Source checkouts still fall back to `index.ts` before a local build exists.

package/README.md

@@ -169,6 +169,7 @@ The persistent tool surface is file-discovered:
 
 ```text
 ~/.pi/agent/recipes/*.json
+~/.pi/agent/recipes/*.md
 ```
 
 That directory is operator-managed executable memory.
@@ -178,6 +179,7 @@ Rules:
 - User recipes in `~/.pi/agent/recipes/` are tools by location;
 - Recipe filenames define tool ids;
 - User recipes override same-name lower-priority recipes;
+- Same-id JSON recipes shadow Markdown recipes in the same priority layer;
 - Packaged recipes are standard-library components, not automatically installed operator policy;
 - `register_tool` creates, updates, lists, or deletes user recipe files through the normal agent interface.
 
@@ -220,7 +222,7 @@ Templates support:
 - Retries, recovery, failure policy, delays, and guarded execution;
 - Async run values such as `{run_id}`, `{state_dir}`, `{actor_address}`, `{default_room}`, and `{communication_file}`.
 
-The template owns execution shape. The recipe owns saved metadata, defaults, imports, mailbox, and artifacts. The run actor owns detached lifecycle, state, messages, cancellation, and inspection. File-backed async recipes also provide child `pi -p` actors with a bounded JSONL recipe context bundle by default, including raw entry/import recipe records and a `"you_are_here": true` marker for the recipe node that launched the child. Set `"actor_context": false` or `"off"` in a recipe to suppress that context for minimal prompts.
+The template owns execution shape. The recipe owns saved metadata, defaults, imports, mailbox, and artifacts. JSON is the canonical precise recipe format; Markdown recipes use frontmatter plus fenced `template`/`json recipe` blocks for literate authoring and compile into the same model. The run actor owns detached lifecycle, state, messages, cancellation, and inspection. File-backed async recipes also provide child `pi -p` actors with a bounded JSONL recipe context bundle by default, including raw entry/import recipe records and a `"you_are_here": true` marker for the recipe node that launched the child. Set `"actor_context": false` or `"off"` in a recipe to suppress that context for minimal prompts.
 
 ## Recipe Library
 
@@ -249,6 +251,10 @@ Use artifacts when outputs should survive context compression.
 
 Use mailbox declarations when an actor has a stable conversational surface.
 
+## Platform Support
+
+Core actor state, inspection, foreground tools, and basic async runs are portable Node.js behavior. Run-local messaging and stop/kill use a platform adapter under the same `message` API: Unix-compatible recipes can use their existing local control endpoint, while native Windows recipes can expose a Windows-native endpoint in run state. Some packaged scripts still depend on Unix tools and are WSL/Linux/macOS-only until migrated; their public recipe surface should stay `spawn` / `message` / `inspect` either way.
+
 ## Safety Boundary
 
 `pi-actors` is local-first, not sandbox-first.

package/dist/index.js

@@ -6,6 +6,7 @@
  */
 import { existsSync, readdirSync, watch } from "node:fs";
 import * as ActorInspectorTui from "./lib/actor-inspector-tui.js";
+import * as AsyncRuns from "./lib/async-runs.js";
 import * as CommandTemplates from "./lib/command-templates.js";
 import * as Observability from "./lib/observability.js";
 import * as Paths from "./lib/paths.js";
@@ -38,6 +39,7 @@ export default function toolRegistryExtension(pi) {
     const runDirWatchers = new Map();
     const observedRuns = new Map();
     const observedRunEventLines = new Map();
+    const retirementAttempts = new Set();
     let runStatusFrame = 0;
     let communicationWidgetVisible = false;
     let actorInspectorRows = 12;
@@ -49,6 +51,14 @@ export default function toolRegistryExtension(pi) {
     let selectedInspectorSequence;
     let recipeWatcherFailureNotified = false;
     const getRunOwnerId = (ctx) => ctx.sessionManager.getSessionId();
+    const retireCandidateRuns = (ctx, summary) => {
+        void Observability.executeRunRetirements(summary, {
+            attempted: retirementAttempts,
+            cancelRun: (candidate) => AsyncRuns.cancelRun(candidate.stateDir),
+            notify: (message, level) => ctx.ui.notify(message, level),
+            sendStop: (candidate) => AsyncRuns.sendRunMessage(candidate.stateDir, "stop"),
+        });
+    };
     const updateRunUi = (ctx, notify = false) => {
         const ownerId = getRunOwnerId(ctx);
         const summary = Observability.summarizeRuns(undefined, ownerId);
@@ -93,6 +103,7 @@ export default function toolRegistryExtension(pi) {
         const outboxEvents = Observability.detectRunOutboxEvents(observedRunEventLines, summary);
         if (!notify)
             return;
+        retireCandidateRuns(ctx, summary);
         for (const transition of transitions) {
             if (!Observability.shouldNotifyRunTransition(transition))
                 continue;

package/dist/lib/actor-rooms.d.ts

@@ -67,6 +67,7 @@ export declare function readBranchInboxMessages(stateDir: string, run: string, a
     queued_at?: string;
     status?: string;
 }>;
+export declare function getBranchInboxTerminalRetainLimit(): number;
 export declare function appendBranchInboxMessage(stateDir: string, run: string, address: string, message: ActorMessage): void;
 export declare function updateBranchInboxMessageStatus(stateDir: string, run: string, address: string, id: string, status: "claimed" | "handled" | "failed", metadata?: Record<string, unknown>): boolean;
 export declare function appendRoomMessage(stateDir: string, room: string, message: ActorMessage): RoomAppendResult;

package/dist/lib/actor-rooms.js

@@ -6,9 +6,11 @@
 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;
+const DEFAULT_BRANCH_INBOX_TERMINAL_RETAINED = 2000;
 const DEFAULT_SNAPSHOT_MIN_INTERVAL_MS = 250;
 function roomDir(stateDir, room) {
     return path.join(stateDir, "rooms", room);
@@ -97,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;
@@ -275,6 +285,18 @@ export function readBranchInboxMessages(stateDir, run, address, limit = 40) {
         throw error;
     }
 }
+export function getBranchInboxTerminalRetainLimit() {
+    const value = Number(process.env.PI_ACTORS_BRANCH_INBOX_TERMINAL_RETAINED ?? "");
+    return Number.isInteger(value) && value >= 0
+        ? value
+        : DEFAULT_BRANCH_INBOX_TERMINAL_RETAINED;
+}
+function compactBranchInboxMessages(messages) {
+    const retainTerminal = getBranchInboxTerminalRetainLimit();
+    const active = messages.filter((message) => message.status !== "handled" && message.status !== "failed");
+    const terminal = messages.filter((message) => message.status === "handled" || message.status === "failed");
+    return [...terminal.slice(-retainTerminal), ...active];
+}
 export function appendBranchInboxMessage(stateDir, run, address, message) {
     const branch = branchIdFromAddress(address, run);
     if (!branch)
@@ -282,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();
@@ -305,7 +331,9 @@ export function updateBranchInboxMessageStatus(stateDir, run, address, id, statu
         });
         if (!changed)
             return false;
-        fs.writeFileSync(file, `${updated.map((message) => JSON.stringify(message)).join("\n")}\n`);
+        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 {
@@ -323,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

@@ -6,8 +6,13 @@
 import type { CommandTemplateFailureScope, CommandTemplateValue } from "./command-templates.ts";
 import * as RecipeReferences from "./recipe-references.ts";
 export type AsyncRunLaunchSource = "spawn" | "tool";
+export interface AsyncRunControlEndpoint {
+    path: string;
+    type: "fifo" | "mailbox" | "named-pipe";
+}
 export interface AsyncRunStartParams {
     async?: boolean;
+    control?: AsyncRunControlEndpoint;
     file?: string;
     launch_source?: AsyncRunLaunchSource;
     name?: string;
@@ -72,6 +77,7 @@ export interface AsyncRunMeta {
     template: CommandTemplateValue;
     values: Record<string, unknown>;
     artifacts?: Record<string, string>;
+    control?: AsyncRunControlEndpoint;
     mailbox?: RecipeReferences.TemplateRecipeMailbox;
     recipe_context_records?: RecipeReferences.TemplateRecipeContextRecord[];
     retire_when?: "children_terminal";
@@ -82,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;
@@ -96,6 +120,16 @@ export declare function appendRunOutboxEvent(runOrDir: string, event: {
     to?: string;
     type?: string;
 }): Record<string, unknown>;
-export declare function sendRunMessage(runOrDir: string, message: string): Record<string, unknown>;
+export interface SendRunMessageOptions {
+    namedPipeSend?: (path: string, payload: string) => Promise<number>;
+    platform?: NodeJS.Platform;
+}
+export declare function sendRunMessage(runOrDir: string, message: string, options?: SendRunMessageOptions): Promise<Record<string, unknown>>;
+export interface RunProcessSignalPlan {
+    args?: string[];
+    command?: string;
+    signalTarget: "processGroup" | "process" | "processTree";
+}
+export declare function getRunProcessSignalPlan(pid: number, signal: NodeJS.Signals, runtimePlatform?: NodeJS.Platform): RunProcessSignalPlan;
 export declare function cancelRun(runOrDir: string): Record<string, unknown>;
 export declare function killRun(runOrDir: string): Record<string, unknown>;