@llblab/pi-actors 0.20.2 → 0.22.0

package/dist/lib/recipe-discovery.js

@@ -36,15 +36,18 @@ function listRecipeFiles(root) {
         return [];
     return readdirSync(root, { withFileTypes: true })
         .filter((entry) => entry.isFile() &&
-        entry.name.endsWith(".json") &&
+        (entry.name.endsWith(".json") || entry.name.endsWith(".md")) &&
         entry.name !== "legacy-tool-registry-migration-report.json")
         .map((entry) => join(root, entry.name))
-        .sort();
+        .sort((a, b) => a.replace(/\.md$/, ".json").localeCompare(b.replace(/\.md$/, ".json")) || (a.endsWith(".json") ? -1 : 1));
 }
 function getRecipeConfigDiagnostics(file, config) {
     if (!config)
         return [`Invalid recipe: ${file}`];
-    return CommandTemplates.getCommandTemplateWarnings(typeof config.template === "string" ? config.template : { template: config.template }).map((warning) => `Recipe ${file}: ${warning}`);
+    const commandTemplateConfig = typeof config.template === "object" && config.template !== null
+        ? config.template
+        : config;
+    return CommandTemplates.getCommandTemplateWarnings(commandTemplateConfig).map((warning) => `Recipe ${file}: ${warning}`);
 }
 function readDiscoveredRecipe(root, file, priority, defaultTool = false, mutableUsage = false) {
     const id = RecipeReferences.getRecipeIdFromPath(file);
@@ -135,13 +138,18 @@ export function discoverRecipeSources(sources) {
     const active = new Map();
     const diagnostics = getRecipeRootDiagnostics(sources);
     for (const [id, bucket] of byId) {
-        bucket.sort((a, b) => a.priority - b.priority || a.path.localeCompare(b.path));
+        bucket.sort((a, b) => a.priority - b.priority ||
+            a.path.replace(/\.md$/, ".json").localeCompare(b.path.replace(/\.md$/, ".json")) ||
+            (a.path.endsWith(".json") ? -1 : 1));
         const winner = bucket[0];
         winner.active = true;
         winner.shadows = bucket.slice(1).map((entry) => entry.path);
         active.set(id, winner);
-        for (const shadow of bucket.slice(1))
+        for (const shadow of bucket.slice(1)) {
             shadow.shadowed = true;
+            if (winner.path.endsWith(".json") && shadow.path.endsWith(".md"))
+                shadow.diagnostics.push(`Markdown recipe ${shadow.path} is shadowed by JSON recipe ${winner.path}`);
+        }
         if (winner.invalid)
             diagnostics.push(`Recipe ${id} is invalid and blocks lower-priority recipes`);
         if (winner.disabled)

package/dist/lib/recipe-references.js

@@ -5,7 +5,7 @@
  */
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, dirname, resolve } from "node:path";
+import { basename, dirname, extname, resolve } from "node:path";
 import * as CommandTemplates from "./command-templates.js";
 import * as Paths from "./paths.js";
 const MAX_RECIPE_FILE_BYTES = 1024 * 1024;
@@ -23,26 +23,31 @@ export function resolveRecipePath(value, recipeRoot = Paths.getRecipeRoot()) {
         return resolve(homedir(), expanded.slice(2));
     if (expanded.includes("/"))
         return resolve(expanded);
-    return resolve(recipeRoot, expanded.endsWith(".json") ? expanded : `${expanded}.json`);
+    return resolve(recipeRoot, expanded.endsWith(".json") || expanded.endsWith(".md")
+        ? expanded
+        : `${expanded}.json`);
 }
 function isBareRecipeName(value) {
     const trimmed = value.trim();
     return Boolean(trimmed) && !trimmed.includes("/") && !trimmed.startsWith("~") && !trimmed.includes("{");
 }
-function recipeNameFile(value) {
+function recipeNameFiles(value) {
     const trimmed = value.trim();
-    return trimmed.endsWith(".json") ? trimmed : `${trimmed}.json`;
+    if (trimmed.endsWith(".json") || trimmed.endsWith(".md"))
+        return [trimmed];
+    return [`${trimmed}.json`, `${trimmed}.md`];
 }
 function resolveRecipeImportPath(value, currentRecipeRoot) {
     if (!isBareRecipeName(value))
         return resolveRecipePath(value, currentRecipeRoot);
-    const file = recipeNameFile(value);
     const roots = [
         Paths.getRecipeRoot(),
         currentRecipeRoot,
         Paths.getPackagedRecipeRoot(),
     ];
-    const candidates = [...new Set(roots.map((root) => resolve(root, file)))];
+    const candidates = [
+        ...new Set(roots.flatMap((root) => recipeNameFiles(value).map((file) => resolve(root, file)))),
+    ];
     return candidates.find((candidate) => existsSync(candidate)) ?? candidates[0];
 }
 export function getRecipePath(value, recipeRoot = Paths.getRecipeRoot()) {
@@ -51,13 +56,15 @@ export function getRecipePath(value, recipeRoot = Paths.getRecipeRoot()) {
     const trimmed = value.trim();
     if (!trimmed || hasWhitespace(trimmed))
         return undefined;
-    if (trimmed.endsWith(".json"))
+    if (trimmed.endsWith(".json") || trimmed.endsWith(".md"))
         return resolveRecipePath(trimmed, recipeRoot);
-    const path = resolveRecipePath(trimmed, recipeRoot);
+    const jsonPath = resolveRecipePath(trimmed, recipeRoot);
+    const mdPath = resolveRecipePath(`${trimmed}.md`, recipeRoot);
+    const path = existsSync(jsonPath) ? jsonPath : mdPath;
     if (!existsSync(path))
         return undefined;
     try {
-        const raw = JSON.parse(readFileSync(path, "utf8"));
+        const raw = readRawRecipeConfig(path);
         return raw && typeof raw === "object" && Object.hasOwn(raw, "template")
             ? path
             : undefined;
@@ -137,6 +144,122 @@ function getRecipeCommandTemplate(raw) {
     }
     return normalizeRecipeTemplate({ ...envelope, template });
 }
+function parseMarkdownScalar(value) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        return "";
+    if ((trimmed.startsWith("{") && trimmed.endsWith("}")) ||
+        (trimmed.startsWith("[") && trimmed.endsWith("]"))) {
+        try {
+            return JSON.parse(trimmed);
+        }
+        catch {
+            return trimmed;
+        }
+    }
+    const quoted = trimmed.match(/^(?:"([^"]*)"|'([^']*)')$/);
+    if (quoted)
+        return quoted[1] ?? quoted[2] ?? "";
+    if (trimmed === "true")
+        return true;
+    if (trimmed === "false")
+        return false;
+    if (trimmed === "null")
+        return null;
+    if (/^-?\d+(?:\.\d+)?$/.test(trimmed))
+        return Number(trimmed);
+    return trimmed;
+}
+function parseMarkdownFrontmatterObject(lines) {
+    if (lines.every((line) => /^\s*-\s+/.test(line))) {
+        return lines.map((line) => parseMarkdownScalar(line.replace(/^\s*-\s+/, "")));
+    }
+    const result = {};
+    for (let index = 0; index < lines.length; index += 1) {
+        const match = lines[index].match(/^\s{2}([A-Za-z_][A-Za-z0-9_.-]*):\s*(.*)$/);
+        if (!match)
+            continue;
+        if (match[2]) {
+            result[match[1]] = parseMarkdownScalar(match[2]);
+            continue;
+        }
+        const nested = [];
+        while (index + 1 < lines.length && /^\s{4}/.test(lines[index + 1])) {
+            index += 1;
+            nested.push(lines[index].slice(2));
+        }
+        result[match[1]] = parseMarkdownFrontmatterObject(nested);
+    }
+    return result;
+}
+function parseMarkdownFrontmatter(value) {
+    const result = {};
+    const lines = value.split(/\r?\n/);
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index];
+        if (!line.trim() || line.trim().startsWith("#"))
+            continue;
+        const match = line.match(/^([A-Za-z_][A-Za-z0-9_.-]*):\s*(.*)$/);
+        if (!match)
+            continue;
+        if (match[2]) {
+            result[match[1]] = parseMarkdownScalar(match[2]);
+            continue;
+        }
+        const nested = [];
+        while (index + 1 < lines.length && /^\s+/.test(lines[index + 1])) {
+            index += 1;
+            nested.push(lines[index]);
+        }
+        result[match[1]] = parseMarkdownFrontmatterObject(nested);
+    }
+    return result;
+}
+function findMarkdownRecipeFence(body) {
+    const pattern = /```([^\n`]*)\n([\s\S]*?)```/g;
+    for (const match of body.matchAll(pattern)) {
+        const info = match[1].trim().toLowerCase();
+        if (info.includes("recipe") ||
+            info.includes("template") ||
+            info.includes("command") ||
+            info.includes("json")) {
+            return { info, body: match[2].trim() };
+        }
+    }
+    return undefined;
+}
+function parseMarkdownRecipeConfig(content) {
+    const lines = content.split(/\r?\n/);
+    if (lines[0]?.trim() !== "---")
+        return undefined;
+    const end = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
+    if (end === -1)
+        return undefined;
+    const frontmatter = parseMarkdownFrontmatter(lines.slice(1, end).join("\n"));
+    const fence = findMarkdownRecipeFence(lines.slice(end + 1).join("\n"));
+    if (!fence)
+        return Object.hasOwn(frontmatter, "template") ? frontmatter : undefined;
+    const text = fence.body.trim();
+    if (!text)
+        return undefined;
+    if (fence.info.includes("json") ||
+        fence.info.includes("recipe") ||
+        text.startsWith("{") ||
+        text.startsWith("[") ||
+        text.startsWith('"')) {
+        try {
+            const parsed = JSON.parse(text);
+            if (isRecord(parsed) && Object.hasOwn(parsed, "template"))
+                return { ...frontmatter, ...parsed };
+            return { ...frontmatter, template: parsed };
+        }
+        catch {
+            if (fence.info.includes("json") || fence.info.includes("recipe"))
+                return undefined;
+        }
+    }
+    return { ...frontmatter, template: text };
+}
 export function readRawRecipeConfig(path) {
     if (!existsSync(path))
         return undefined;
@@ -145,7 +268,10 @@ export function readRawRecipeConfig(path) {
         throw new Error(`Recipe file exceeds size limit ${MAX_RECIPE_FILE_BYTES} bytes: ${path}`);
     }
     try {
-        const raw = JSON.parse(readFileSync(path, "utf8"));
+        const content = readFileSync(path, "utf8");
+        if (path.endsWith(".md"))
+            return parseMarkdownRecipeConfig(content);
+        const raw = JSON.parse(content);
         return raw && typeof raw === "object" ? raw : undefined;
     }
     catch {
@@ -153,7 +279,7 @@ export function readRawRecipeConfig(path) {
     }
 }
 export function getRecipeIdFromPath(file) {
-    return basename(file, ".json");
+    return basename(file, extname(file));
 }
 function readRecipeConfig(value) {
     const path = getRecipePath(value);

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();
+                },
+            };
+        },
+    };
+}

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": {
@@ -790,7 +799,7 @@ export function createActorMessageToolDefinition(deps = {}) {
                     result = AsyncRuns.killRun(address.value);
                 }
                 else {
-                    result = AsyncRuns.sendRunMessage(address.value, messageBodyToRunLine(message));
+                    result = await AsyncRuns.sendRunMessage(address.value, messageBodyToRunLine(message));
                 }
             }
             else if (address.kind === "branch" && address.value) {
@@ -820,7 +829,7 @@ export function createActorMessageToolDefinition(deps = {}) {
                     ActorRooms.writeCommunicationSnapshot(stateDir, runId);
                     ActorRooms.appendBranchInboxMessage(stateDir, runId, message.to, message);
                 }
-                result = AsyncRuns.sendRunMessage(address.value, JSON.stringify(message));
+                result = await AsyncRuns.sendRunMessage(address.value, JSON.stringify(message));
             }
             else if (address.kind === "room" && address.value && address.room) {
                 const runId = address.value;
@@ -831,11 +840,11 @@ export function createActorMessageToolDefinition(deps = {}) {
                     throw new Error(`${message.to} has no run state directory.`);
                 const recipients = getRoomMulticastRecipients(message, runId);
                 const roomResult = ActorRooms.appendRoomMessage(stateDir, address.room, message);
-                const multicast = recipients.map((recipient) => AsyncRuns.sendRunMessage(runId, JSON.stringify({ ...message, to: recipient })));
+                await Promise.all(recipients.map((recipient) => AsyncRuns.sendRunMessage(runId, JSON.stringify({ ...message, to: recipient }))));
                 result = {
                     ...roomResult,
-                    ...(multicast.length > 0
-                        ? { multicast: recipients, multicast_count: multicast.length }
+                    ...(recipients.length > 0
+                        ? { multicast: recipients, multicast_count: recipients.length }
                         : {}),
                 };
             }

package/docs/README.md

@@ -5,7 +5,7 @@ Living index of all documentation in the `/docs` directory.
 ## Documents
 
 - [command-templates.md](./command-templates.md) — Portable synchronous command execution standard
-- [template-recipes.md](./template-recipes.md) — Saved JSON recipe standard, imports, and reusable command-template graph composition
+- [template-recipes.md](./template-recipes.md) — Saved JSON/Markdown recipe standard, imports, and reusable command-template graph composition
 - [async-runs.md](./async-runs.md) — Detached run lifecycle, state files, actor messages, cancellation, and ambient indicators
 - [actor-messages.md](./actor-messages.md) — Actor/message protocol for symmetric communication primitives
 - [tool-registry.md](./tool-registry.md) — Local `pi-actors` registry storage and `register_tool` adaptation

package/docs/actor-messages.md

@@ -44,6 +44,8 @@ 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`. 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.
 
 ## Message Envelope
@@ -94,7 +96,7 @@ Transports differ, but the public contract does not:
 
 - `to: run:<id>` routes through the run-local control channel selected by that recipe or runtime adapter.
 - `to: coordinator` routes to the runtime attention path when `from` names a run actor. `to: session:<id>` uses the same actor-message path only when the sender run is owned by that session, making explicit session-directed checkpoints possible without exposing runtime delivery knobs. Generic async-runner `command.done` messages and explicit coordinator/session-bound messages include the actor envelope fields alongside runtime metadata.
-- `to: branch:<run>/<branch>` currently routes through the parent run mailbox with the full envelope preserved so the run or recipe-specific worker protocol can dispatch branch-local control. It also persists a queued branch-local copy under `branches/<branch>/inbox.jsonl`, inspectable with `inspect branch:<run>/<branch> view=mailbox`; compact inspection includes the inbox message `id`, status, route, type, and timestamps so worker protocols can correlate claims/retries. Branch-local inbox append and status rewrites are guarded by a small lock so direct delivery and coordinator claims do not overwrite each other during bursts. Coordinator claim handling also assigns an ID to older/manual queued records that do not have one so they can still transition to `handled` or `failed` instead of repeating forever. It is not a broadcast room and it does not make an arbitrary prompt process consume the message automatically. Target direction: direct branch messages should become initiating inbox work for long-lived branch runners, delivered into the recipient's next prompt/context as soon as the runner can accept work.
+- `to: branch:<run>/<branch>` currently routes through the parent run mailbox with the full envelope preserved so the run or recipe-specific worker protocol can dispatch branch-local control. It also persists a queued branch-local copy under `branches/<branch>/inbox.jsonl`, inspectable with `inspect branch:<run>/<branch> view=mailbox`; compact inspection includes the inbox message `id`, status, route, type, and timestamps so worker protocols can correlate claims/retries. Branch-local inbox append and status rewrites are guarded by a small lock so direct delivery and coordinator claims do not overwrite each other during bursts. Status transitions preserve active queued/claimed records and compact older handled/failed terminal records with bounded retention, so persistent runners do not accumulate unbounded completed inbox history. Coordinator claim handling also assigns an ID to older/manual queued records that do not have one so they can still transition to `handled` or `failed` instead of repeating forever. It is not a broadcast room and it does not make an arbitrary prompt process consume the message automatically. Target direction: direct branch messages should become initiating inbox work for long-lived branch runners, delivered into the recipient's next prompt/context as soon as the runner can accept work.
 - `to: room:<run>` appends the full envelope to the room timeline, updates room state for room-control types such as `actor.join` and `actor.leave`, and can route selected-recipient multicast when `metadata.recipients` contains same-run `branch:<run>/<branch>` addresses.
 - `to: tool:<name>` invokes an executable pi tool by name. Object bodies become tool parameters; primitive bodies are passed as `{ "input": body }`.
 
@@ -104,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.
 
@@ -195,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
 
@@ -205,6 +209,7 @@ Runtime operations use the actor/message vocabulary:
 create detached work -> spawn
 run-local control    -> message to run:<id>
 run stop/kill        -> message type control.stop/control.kill
+platform control     -> internal adapter selected from run state
 coordinator signal   -> message to coordinator/session
 tool execution       -> message to tool:<name>
 intentional observe  -> inspect

package/docs/async-runs.md

@@ -156,9 +156,9 @@ 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. Candidate detection is conservative: a supervisor is not retirement-ready while command-template progress or descendant `pi -p` worker processes are still active; future retirement execution must also verify child async-run state and flushed outputs before stopping the supervisor.
+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.
 
 Low-level async actions map into the actor surface instead of forming a second public model:
 
@@ -183,9 +183,11 @@ 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.
 
-The standard run-local transport is Unix-oriented. Use WSL/Linux/macOS for packaged message-controlled recipes, or let a Windows-specific recipe expose its own transport such as a Windows named pipe or localhost socket.
+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
 
@@ -219,7 +221,7 @@ Use coordinator/session-bound messages for completion and decision points, not f
 
 An async run belongs to the current user, cwd, and launching agent session at start time. Send, cancellation, and force-kill target only the recorded runner pid when command line and cwd still match the recorded owner data. Stale pid reuse must fail closed.
 
-On Unix-like systems, cancel and kill signal the runner process group when available, then fall back to the runner pid. The runner starts command-template children in that process group, so long-running descendants such as audio players stop with the run instead of becoming orphaned background processes. After the process exits, status reflects the operator action as `cancelled` or `killed` instead of a generic `exited`.
+On Unix-like systems, cancel and kill signal the runner process group when available, then fall back to the runner pid. On native Windows, cancel and kill use Windows process-tree termination through the platform adapter. The runner starts command-template children in the owned process tree, so long-running descendants such as audio players should stop with the run instead of becoming orphaned background processes. After the process exits, status reflects the operator action as `cancelled` or `killed` instead of a generic `exited`.
 
 State is append-only where practical. Final result writes should be atomic. Recipe-local control endpoints and actor-message logs may live in the state dir. pi-actors core owns the generic run-local message adapter and runtime attention policy; command and message vocabularies belong to the recipe/script.