@llblab/pi-actors 0.21.0 → 0.22.0

package/dist/lib/tools.js

@@ -235,9 +235,9 @@ function compactCommunicationSnapshot(snapshot) {
         return "\n(no communication snapshot)";
     return `\nself=${snapshot.self} root=${snapshot.root} rooms=${snapshot.rooms.length} updated_at=${snapshot.updated_at}`;
 }
-function compactBranchInbox(messages) {
+function compactInboxMessages(messages, emptyLabel) {
     if (messages.length === 0)
-        return "\n(no branch inbox messages)";
+        return `\n(no ${emptyLabel} messages)`;
     return `\n${messages
         .map((message) => [
         ...(message.id ? [`id=${String(message.id)}`] : []),
@@ -246,12 +246,19 @@ function compactBranchInbox(messages) {
         `from=${String(message.from ?? "")}`,
         `to=${String(message.to ?? "")}`,
         ...(message.queued_at ? [`queued_at=${String(message.queued_at)}`] : []),
+        ...(message.sent_at ? [`sent_at=${String(message.sent_at)}`] : []),
         ...(message.claimed_at ? [`claimed_at=${String(message.claimed_at)}`] : []),
         ...(message.handled_at ? [`handled_at=${String(message.handled_at)}`] : []),
         ...(message.failed_at ? [`failed_at=${String(message.failed_at)}`] : []),
     ].join(" "))
         .join("\n")}`;
 }
+function compactBranchInbox(messages) {
+    return compactInboxMessages(messages, "branch inbox");
+}
+function compactRunMailbox(run, mailbox, messages) {
+    return `\nrun=${run} accepts=${Array.isArray(mailbox.accepts) ? mailbox.accepts.join(",") : ""} emits=${Array.isArray(mailbox.emits) ? mailbox.emits.join(",") : ""}${compactInboxMessages(messages, "run inbox")}`;
+}
 function compactActorFiles(status) {
     const run = String(status.run ?? "<unknown>");
     const artifacts = asRecord(status.artifacts);
@@ -726,14 +733,16 @@ export function createInspectToolDefinition(deps = {}) {
                 case "mailbox": {
                     const status = assertRunAccessibleToContext(runId, ctx);
                     const mailbox = asRecord(status.mailbox);
+                    const messages = AsyncRuns.readRunInboxMessages(runId, Number(input.lines || 40));
+                    const details = { mailbox, messages };
                     return {
                         content: [
                             {
                                 type: "text",
-                                text: maybeJsonText(mailbox, input.verbose === true, `\nrun=${String(status.run ?? runId)} accepts=${Array.isArray(mailbox.accepts) ? mailbox.accepts.join(",") : ""} emits=${Array.isArray(mailbox.emits) ? mailbox.emits.join(",") : ""}`),
+                                text: maybeJsonText(details, input.verbose === true, compactRunMailbox(String(status.run ?? runId), mailbox, messages)),
                             },
                         ],
-                        details: { mailbox },
+                        details,
                     };
                 }
                 case "communication": {

package/docs/actor-messages.md

@@ -44,7 +44,7 @@ An alternate implementation shape is a dedicated non-LLM communication actor: a
 
 That actor-backed shape can also reduce direct file storage. Instead of every protocol feature owning JSON files as primary state, a helper actor can keep live room/roster structures in memory or another local structure and write files only as snapshots, audit logs, artifacts, or recovery checkpoints. The decision boundary is practical: keep files when durability and inspectability are the main value; prefer actor-owned structures when live coordination, subscriptions, fanout, unread state, or mutation consistency becomes the main value.
 
-Current backend decision: keep the file-backed adapter for now. The covered workload is append-heavy room coordination plus direct branch inbox queueing/claiming, where durable local files are still the useful source of truth for recovery and `inspect`. A communication helper should be introduced only when a real workflow needs long-lived subscriptions, live fanout policy, or shared mutable room state beyond the current lock/debounce/compaction safeguards.
+Current backend decision: keep the file-backed adapter for now. The covered workload is append-heavy room coordination plus direct branch inbox queueing/claiming, where durable local files are still the useful source of truth for recovery and `inspect`. Live notification is a separate advisory wake layer: actors may subscribe to `wake.jsonl` changes through a cross-platform file notifier and still reconcile canonical mailbox files if a wake is missed. A communication helper should be introduced only when a real workflow needs long-lived subscriptions, live fanout policy, or shared mutable room state beyond the current lock/debounce/compaction safeguards.
 
 Package-specific endpoints may still exist, but the envelope stays the same.
 
@@ -106,7 +106,9 @@ Transport is not public API unless a recipe explicitly documents a custom endpoi
 
 The task room is the discovery and shared-context layer for actors whose spawn-tree positions do not give them each other's addresses. The spawn tree remains the lifecycle/provenance structure; the task room describes the group communication graph. Direct messages and room messages can share the same semantic `type` such as `chat.message`; the route (`to: branch:*` versus `to: room:*`) determines whether delivery is private or group-wide.
 
-Use direct branch messages only when the receiving branch is backed by a worker or recipe that reads the parent run mailbox or branch inbox and dispatches branch-targeted envelopes. Room roster contacts are discovery hints, not a guarantee that an independent prompt process is subscribed to its branch address. The current branch inbox records queued FIFO work; the intended next step is runner-side claiming/handling so direct messages become prompt work for the recipient branch, while room messages remain shared transcript entries. A direct message may ask the recipient to inspect room history when broader shared context is needed. For ad hoc or transcript-driven swarms without such a runner, prefer room-visible replies and mentions so every participant can inspect the shared timeline.
+Use direct branch messages only when the receiving branch is backed by a worker or recipe that reads the parent run mailbox or branch inbox and dispatches branch-targeted envelopes. Room roster contacts are discovery hints, not a guarantee that an independent prompt process is subscribed to its branch address. The current branch inbox records queued mailbox work; runner-side claiming/handling turns direct messages into prompt work for the recipient branch, while room messages remain shared transcript entries. A direct message may ask the recipient to inspect room history when broader shared context is needed. For ad hoc or transcript-driven swarms without such a runner, prefer room-visible replies and mentions so every participant can inspect the shared timeline.
+
+Direct branch delivery is prompt steering for worker-backed branches, not a coordinator follow-up. Packaged coordinator flows claim queued branch inbox records immediately before launching the branch's next prompt, append a bounded "direct messages for you" section to that prompt, and then mark the claimed records `handled` or `failed` based on the prompt result. Generic one-shot `pi -p` children do not receive this injection automatically; a recipe must own the runner loop or use the packaged coordinator path for direct messages to become next-prompt work.
 
 Selected-recipient multicast stays route-based: send one `to: room:<run>` envelope with `metadata.recipients` set to same-run branch addresses. The room timeline keeps the original room-visible envelope, and the runtime also forwards branch-targeted copies to each listed recipient. This is not a subroom; it is a shared transcript plus explicit direct delivery for actors whose worker protocol consumes branch envelopes.
 
@@ -197,7 +199,7 @@ Recipes can declare their conversational surface:
 }
 ```
 
-The implementation supports `status`, `tail`, `messages`, `artifacts`, `files`, `mailbox`, and `communication` for `run:<id>` actors, `status`, `messages`, `previews`, `roster`, and `contacts` for `room:<run>` actors, `status`/`runs` for `coordinator`, `session:<id>`, and `session:all` actors with optional status filtering, and `status`/`schema` for registered `tool:<name>` actors. Room `status` returns compact message/roster counts plus `last_message_at`, `last_message_from`, `last_message_type`, and `last_message_summary` when available, without parsing the full timeline into actor envelopes. Use `messages` for actor-envelope inspection. `inspect target=coordinator` requires a current coordinator session; use `session:<id>` or `session:all` when the session is intentionally explicit. Direct `run:<id>` and `room:<run>` inspection respects coordinator-session ownership when the current session is known. `inspect` is for decision points and diagnosis only; examples must not teach sleep-then-inspect polling.
+The implementation supports `status`, `tail`, `messages`, `artifacts`, `files`, `mailbox`, and `communication` for `run:<id>` actors, `status`, `messages`, `previews`, `roster`, and `contacts` for `room:<run>` actors, `status`/`runs` for `coordinator`, `session:<id>`, and `session:all` actors with optional status filtering, and `status`/`schema` for registered `tool:<name>` actors. Run mailbox inspection shows recipe-declared mailbox metadata plus recent durable run inbox entries; branch mailbox inspection shows branch-local queued/claimed/handled records. Room `status` returns compact message/roster counts plus `last_message_at`, `last_message_from`, `last_message_type`, and `last_message_summary` when available, without parsing the full timeline into actor envelopes. Use `messages` for actor-envelope inspection. `inspect target=coordinator` requires a current coordinator session; use `session:<id>` or `session:all` when the session is intentionally explicit. Direct `run:<id>` and `room:<run>` inspection respects coordinator-session ownership when the current session is known. `inspect` is for decision points and diagnosis only; examples must not teach sleep-then-inspect polling.
 
 ## Runtime Direction
 

package/docs/async-runs.md

@@ -156,7 +156,7 @@ The actor-level surface is:
 
 - `spawn`: start a detached `run:<id>` actor from `file`, `recipe`, or inline `template`.
 - `message`: send one typed envelope to `run:<id>`, `branch:<run>/<branch>`, `room:<run>`, `tool:<name>`, `coordinator`, or `session:<id>`.
-- `inspect`: intentionally read owned `run:<id>` status, tail, messages, artifacts, files, mailbox metadata, or communication snapshot; read `room:<run>` status, messages, previews, roster, or contacts; read current `coordinator` run inventory only when a coordinator session is known; read `session:<id>` or `session:all` run inventory with optional status filtering when the session is explicit; read `tool:<name>` status or schema for registered tool actors.
+- `inspect`: intentionally read owned `run:<id>` status, tail, messages, artifacts, files, mailbox metadata plus recent run inbox entries, or communication snapshot; read `room:<run>` status, messages, previews, roster, or contacts; read current `coordinator` run inventory only when a coordinator session is known; read `session:<id>` or `session:all` run inventory with optional status filtering when the session is explicit; read `tool:<name>` status or schema for registered tool actors.
 
 Opt-in supervisor retirement uses `retire_when: "children_terminal"` as lifecycle metadata. Run summaries discover nested child run state dirs under the visible state root so bounded supervisor trees are observable. Candidate detection is conservative: a supervisor is not retirement-ready while command-template progress, descendant `pi -p` worker processes, or nested child async runs under the supervisor state dir are still active. Candidate metadata includes observed child-run counts. When the session watcher observes a ready candidate, it sends a graceful `stop` control message once; if the run has no ready control endpoint, it falls back to owned-run cancellation and records the terminal action through normal run events. Persistent or non-opt-in runs are not retirement candidates.
 
@@ -183,10 +183,12 @@ Some recipes expose a run-local control channel. When present, a caller can send
 }
 ```
 
-For `run:<id>`, `message` adapts the body to the recipe's run-local control channel. For `branch:<run>/<branch>`, it sends the full envelope through the parent run mailbox and records a queued branch-local inbox entry at `branches/<branch>/inbox.jsonl` so the run can dispatch branch-local control. Current consumers are recipe-specific worker protocols that read the parent run mailbox or branch inbox; independent one-shot prompt processes do not automatically consume branch inbox entries. For `tool:<name>`, object bodies become the target tool parameters and primitive bodies are passed as `{ "input": body }`. The generic runtime records control messages but does not interpret arbitrary run mailbox content. For example, a music player may accept `play`, `pause`, `next`, and `stop`, while a collaborative agent recipe may accept `continue`, `revise:<note>`, `approve`, or `abort`. Recipes may treat terminal control messages such as `stop` as synchronously handled so the later process exit does not generate a duplicate async follow-up.
+For `run:<id>`, `message` adapts the body to the recipe's run-local control channel. For `branch:<run>/<branch>`, it sends the full envelope through the parent run mailbox and records a queued branch-local inbox entry at `branches/<branch>/inbox.jsonl` so the run can dispatch branch-local control. Current consumers are recipe-specific worker protocols that read the parent run mailbox or branch inbox; independent one-shot prompt processes do not automatically consume branch inbox entries. In packaged coordinator flows, queued branch inbox records are claimed immediately before the branch's next prompt is launched, appended as direct prompt-steering context, and then marked `handled` or `failed` from the prompt result. This path is not a follow-up notification; it is a runner-owned prompt queue. For `tool:<name>`, object bodies become the target tool parameters and primitive bodies are passed as `{ "input": body }`. The generic runtime records control messages but does not interpret arbitrary run mailbox content. For example, a music player may accept `play`, `pause`, `next`, and `stop`, while a collaborative agent recipe may accept `continue`, `revise:<note>`, `approve`, or `abort`. Recipes may treat terminal control messages such as `stop` as synchronously handled so the later process exit does not generate a duplicate async follow-up.
 
 Run-local control uses a platform adapter under the same `message` API. Unix recipes may keep the existing FIFO endpoint, and native Windows recipes can expose a named-pipe endpoint in run state. Recipe authors should document message vocabulary through `mailbox.accepts`, not through transport arguments. Packaged scripts that still create Unix-only endpoints remain WSL/Linux/macOS-only until migrated.
 
+Runtime wake notifications are now modeled separately from durable queues. Message handling records canonical state in file-backed mailbox/event files before attempting optional live endpoint delivery. Runs may expose a mailbox-only control endpoint when durable inbox plus wake notification is the intended delivery path; FIFO and named-pipe endpoints remain compatibility/fast-wake paths rather than the durable queue itself. Successful FIFO or named-pipe delivery marks the run inbox entry `sent`; mailbox-only delivery leaves the entry queued for the runtime to claim. `wake.jsonl` is an advisory doorbell that lets a live runtime subscribe through file-system notifications plus explicit initial, wake-triggered, and polling reconciliation callbacks. A missed wake must not lose work because actors can re-read the canonical mailbox state. Runtime loops that consume the file-backed mailbox should claim queued run inbox entries, then mark them `handled` or `failed`; the helper path uses a small lock so concurrent reconciliation callbacks do not process the same entry twice.
+
 ## Coordinator Notifications
 
 The launching coordinator should not busy-poll long-running async runs. The extension watches run state directories and delivers terminal `done`/`failed`/unhandled `killed`/`exited` transitions plus script-authored `notify`/`followup` actor messages back to the owning session. This gives the top-level async task a completion signal on the happy path while still letting recipe-local messages bubble up when scripts need finer-grained notifications. Terminal follow-ups include recipe-level named `artifacts` when declared. The generic runner also emits compact `command.done` actor messages for completed leaf commands; recipe authors declare that capability in `mailbox.emits` rather than configuring a separate delivery policy. Failures and in-flight parallel branch completions can bubble as follow-ups, while successful final leaf completions stay diagnostic to avoid flooding long sequential pipelines. Branch-level `command.done` follow-ups omit artifact manifests because the top-level terminal follow-up carries them once. Intentional `control.stop`, `control.kill`, and recipe-local stop commands stay out of follow-up context because the initiating message already returns synchronously. If a follow-up asks for direction, answer with `message` rather than starting a polling loop. Use explicit `inspect` only when a delivered follow-up requests inspection, a real decision depends on state, or a suspected stuck run needs diagnosis — never merely because a timeout elapsed.

package/docs/recipe-library.md

@@ -136,12 +136,12 @@ Files:
 
 Purpose: start a local or URL audio source as an async run so the agent can continue working while playback runs in the background. The running script exposes a run-local mailbox, so addressed `message` calls can control playback without a second recipe.
 
-Requirements: Linux, macOS, or WSL, Node.js, and one of `mpv`, `ffplay`, `cvlc`, or SoX `play`. Native Windows is not supported by the standard wrapper; use WSL or a platform-specific recipe transport.
+Requirements: Node.js and one playback backend. Supported backends are `mpv`, macOS `afplay`, `ffplay`, `cvlc`, SoX `play`, or `wmp` on native Windows through the legacy Windows Media Player COM control exposed by `powershell.exe`. The `wmp` backend validates `wmplayer.exe` under `Program Files/Windows Media Player` or `Program Files (x86)/Windows Media Player`; it does not target the newer UWP/Store Media Player. Playback format support depends on the selected player; the actor control path itself uses the portable mailbox/wake runtime layer.
 
 The required `source` arg accepts:
 
 - A single local file or URL.
-- A directory containing audio files; the wrapper scans `.mp3`, `.ogg`, `.wav`, `.flac`, and `.m4a` files.
+- A directory containing audio files; the wrapper scans `.aac`, `.aif`, `.aiff`, `.flac`, `.m4a`, `.mp3`, `.ogg`, and `.wav` files.
 - An `.m3u`, `.m3u8`, or `.txt` playlist file.
 - A `|`-separated inline list of local files or URLs.
 
@@ -158,7 +158,7 @@ Register playback:
 register_tool name=music_player \
   description="Start async music player playback through the Node.js wrapper" \
   template="music-player.json" \
-  args="source:string,loop:bool=true,volume:int=70,player:enum(auto,mpv,ffplay,cvlc,play)=auto"
+  args="source:string,loop:bool=true,volume:int=70,player:enum(auto,mpv,afplay,ffplay,cvlc,play,wmp)=auto"
 ```
 
 Start playback:
@@ -185,7 +185,14 @@ The wrapper also accepts control commands directly when a caller already has the
 scripts/music-player.mjs next ~/.pi/agent/tmp/pi-actors/runs/music
 ```
 
-Message body is adapted to the recipe's run-local control channel. The script writes `status.txt`, `player.json`, and track-change actor messages in the same state dir. Track-change messages stay diagnostic by default; interactive recipes should define a small command vocabulary for addressed messages, emit semantic actor messages for decision points, and let the coordinator react to messages rather than sleep-polling state.
+Message body is queued in the recipe's run-local mailbox and reconciled by the player loop. The loop treats `wake.jsonl` and `fs.watch` as advisory signals, then verifies the durable inbox signature before taking the inbox lock so unchanged mailboxes are not reread on every tick. On Unix-like hosts, child players run in their own process group so pause/resume/next/stop controls can signal the playback subtree directly. The script writes `status.txt`, `player.json`, and track-change actor messages in the same state dir. Track-change messages stay diagnostic by default; interactive recipes should define a small command vocabulary for addressed messages, emit semantic actor messages for decision points, and let the coordinator react to messages rather than sleep-polling state.
+
+Cross-platform smoke checklist:
+
+- Linux: install one backend such as `mpv` or `ffplay`; start `music_player source="~/Music" run_id=music`, send `pause`, `play`, `next`, and `stop`, then inspect `run:music` status/mailbox.
+- macOS: verify `player=auto` selects `afplay` when no preferred CLI backend is installed, then run the same addressed message controls.
+- Native Windows: verify `player=wmp` detects `wmplayer.exe`, starts playback through Windows Media Player COM, handles `pause`/`play`/`next`/`previous`/`stop`, and leaves handled mailbox records visible through `inspect target=run:music view=mailbox`.
+- All hosts: confirm missed wake resilience by checking that queued mailbox commands are eventually claimed without relying on a transport-specific endpoint.
 
 ## Safety Notes
 

package/lib/actor-rooms.ts

@@ -9,6 +9,7 @@ import { randomUUID } from "node:crypto";
 import * as path from "node:path";
 
 import type { ActorMessage } from "./actor-messages.ts";
+import { notifyRuntimeWake } from "./runtime-notifier.ts";
 
 const STATE_LOCK_MAX_AGE_MS = 5 * 60 * 1000;
 const STATE_LOCK_TIMEOUT_MS = 5000;
@@ -181,6 +182,19 @@ function writeJsonFile(file: string, value: unknown): void {
   fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
 }
 
+function notifyActorWake(
+  stateDir: string,
+  actor: string,
+  reason: string,
+  metadata: Record<string, unknown> = {},
+): void {
+  try {
+    notifyRuntimeWake(stateDir, { actor, metadata, reason });
+  } catch {
+    // Runtime wakes are advisory; durable room/inbox state remains canonical.
+  }
+}
+
 function positiveEnvInt(name: string, fallback: number): number {
   const value = Number(process.env[name] ?? fallback);
   return Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
@@ -422,6 +436,10 @@ export function appendBranchInboxMessage(
       `${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();
   }
@@ -451,6 +469,7 @@ export function updateBranchInboxMessageStatus(
     if (!changed) 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 {
     releaseLock();
@@ -472,6 +491,10 @@ export function appendRoomMessage(
     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/lib/async-runs.ts

@@ -4,6 +4,7 @@
  * 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,
@@ -33,14 +34,16 @@ import { writeJsonAtomic } from "./file-state.ts";
 import * as Paths from "./paths.ts";
 import * as RecipeReferences from "./recipe-references.ts";
 import * as RecipeUsage from "./recipe-usage.ts";
+import { notifyRuntimeWake } from "./runtime-notifier.ts";
 
 const START_LOCK_MAX_AGE_MS = 5 * 60 * 1000;
+const RUN_INBOX_LOCK_TIMEOUT_MS = 5000;
 
 export type AsyncRunLaunchSource = "spawn" | "tool";
 
 export interface AsyncRunControlEndpoint {
   path: string;
-  type: "fifo" | "named-pipe";
+  type: "fifo" | "mailbox" | "named-pipe";
 }
 
 export interface AsyncRunStartParams {
@@ -662,6 +665,193 @@ export function readRunEvents(runOrDir: string, lines = 40): RunOutboxEvent[] {
     .filter((event): event is RunOutboxEvent => Boolean(event));
 }
 
+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;
+}
+
+function runInboxFile(stateDir: string): string {
+  return join(stateDir, "inbox.jsonl");
+}
+
+function sleepSync(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function acquireRunInboxLock(stateDir: string): () => void {
+  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: string): RunInboxMessage | undefined {
+  try {
+    return JSON.parse(line) as RunInboxMessage;
+  } catch {
+    return undefined;
+  }
+}
+
+function readRunInboxMessagesFromStateDir(stateDir: string): RunInboxMessage[] {
+  const file = runInboxFile(stateDir);
+  if (!existsSync(file)) return [];
+  return readFileSync(file, "utf8")
+    .split("\n")
+    .filter((line) => line.trim())
+    .map(parseRunInboxLine)
+    .filter((message): message is RunInboxMessage => Boolean(message));
+}
+
+function writeRunInboxMessages(
+  stateDir: string,
+  messages: RunInboxMessage[],
+): void {
+  writeFileSync(
+    runInboxFile(stateDir),
+    messages.length
+      ? `${messages.map((message) => JSON.stringify(message)).join("\n")}\n`
+      : "",
+    "utf8",
+  );
+}
+
+export function readRunInboxMessages(
+  runOrDir: string,
+  lines = 40,
+): RunInboxMessage[] {
+  const status = getRunStatus(runOrDir);
+  const stateDir = String(status.state_dir);
+  return tailLines(runInboxFile(stateDir), lines)
+    .map(parseRunInboxLine)
+    .filter((message): message is RunInboxMessage => Boolean(message));
+}
+
+export function updateRunInboxMessageStatus(
+  runOrDir: string,
+  id: string,
+  nextStatus: RunInboxStatus,
+  metadata: Record<string, unknown> = {},
+): boolean {
+  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: string,
+  owner = "runtime",
+  statuses: string[] = ["queued"],
+): RunInboxMessage | undefined {
+  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",
+    } satisfies RunInboxMessage;
+    messages[index] = claimed;
+    writeRunInboxMessages(stateDir, messages);
+    return claimed;
+  } finally {
+    releaseLock();
+  }
+}
+
+export async function processRunInboxMessages(
+  runOrDir: string,
+  handler: (message: RunInboxMessage) => Promise<void> | void,
+  options: { limit?: number; owner?: string; statuses?: string[] } = {},
+): Promise<ProcessRunInboxResult> {
+  const result: ProcessRunInboxResult = { 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: string,
   event: {
@@ -725,7 +915,9 @@ function getRunControlEndpoint(
   if (control && typeof control === "object" && !Array.isArray(control)) {
     const record = control as Record<string, unknown>;
     if (
-      (record.type === "fifo" || record.type === "named-pipe") &&
+      (record.type === "fifo" ||
+        record.type === "mailbox" ||
+        record.type === "named-pipe") &&
       typeof record.path === "string" &&
       record.path.trim()
     ) {
@@ -735,10 +927,36 @@ function getRunControlEndpoint(
   return { path: join(stateDir, "control.fifo"), type: "fifo" };
 }
 
+function appendRunInboxMessage(stateDir: string, message: string): string {
+  const id = randomUUID();
+  const ts = new Date().toISOString();
+  let record: Record<string, unknown>;
+  try {
+    const parsed = JSON.parse(message) as unknown;
+    record = parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : { body: parsed, type: "run.message" };
+  } catch {
+    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: string,
   message: string,
   bytes: number,
+  inboxId: string,
 ): void {
   const trimmedMessage = message.trim().toLowerCase();
   const terminalMessage = ["stop", "cancel", "quit", "exit"].includes(
@@ -747,19 +965,10 @@ function writeRunMessageReceipt(
   const ts = new Date().toISOString();
   writeFileSync(
     join(stateDir, "events.jsonl"),
-    `${JSON.stringify({ bytes, event: "run.message", terminal: terminalMessage || undefined, ts })}\n`,
+    `${JSON.stringify({ bytes, event: "run.message", inbox_id: inboxId, terminal: terminalMessage || undefined, ts })}\n`,
     { flag: "a" },
   );
-  try {
-    const envelope = JSON.parse(message) as Record<string, unknown>;
-    writeFileSync(
-      join(stateDir, "inbox.jsonl"),
-      `${JSON.stringify({ ...envelope, received_at: ts })}\n`,
-      { flag: "a" },
-    );
-  } catch {
-    // Plain control lines are already represented in events.jsonl.
-  }
+  updateRunInboxMessageStatus(stateDir, inboxId, "sent", { bytes });
   if (terminalMessage) {
     markTerminalHandled(stateDir, {
       event: "run.message",
@@ -787,6 +996,25 @@ function sendRunMessageToFifo(
   }
 }
 
+function notifyRunMessageWake(
+  stateDir: string,
+  run: string,
+  bytes: number,
+  endpoint: AsyncRunControlEndpoint,
+  inboxId: string,
+): Record<string, unknown> | undefined {
+  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: AsyncRunControlEndpoint,
   payload: string,
@@ -832,7 +1060,23 @@ export async function sendRunMessage(
     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") {
@@ -841,8 +1085,9 @@ export async function sendRunMessage(
         );
       }
       const bytes = sendRunMessageToFifo(endpoint, payload);
-      writeRunMessageReceipt(stateDir, message, bytes);
+      writeRunMessageReceipt(stateDir, message, bytes, inboxId);
       return {
+        ...(wake ?? {}),
         bytes,
         control: "control.fifo",
         control_path: endpoint.path,
@@ -857,8 +1102,9 @@ export async function sendRunMessage(
       payload,
       options.namedPipeSend,
     );
-    writeRunMessageReceipt(stateDir, message, bytes);
+    writeRunMessageReceipt(stateDir, message, bytes, inboxId);
     return {
+      ...(wake ?? {}),
       bytes,
       control: endpoint.path,
       control_path: endpoint.path,