@llblab/pi-actors 0.20.2 → 0.21.0

package/dist/lib/observability.js

@@ -4,7 +4,7 @@
  * Owns ambient summaries, terminal events, and run outbox delivery for detached command-template runs
  */
 import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { basename, dirname, join, relative, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import * as AsyncRuns from "./async-runs.js";
 import * as Paths from "./paths.js";
 const TERMINAL = new Set([
@@ -15,6 +15,7 @@ const TERMINAL = new Set([
     "killed",
 ]);
 const PROC_DESCENDANT_SCAN_TTL_MS = 1000;
+const RUN_STATE_DISCOVERY_MAX_DEPTH = 8;
 const procDescendantScanCache = new Map();
 function toNumber(value) {
     const number = Number(value);
@@ -34,6 +35,29 @@ function getUpdatedAt(status) {
             ? status.createdAt
             : undefined;
 }
+function listRunStateDirs(stateRoot, depth = 0, seen = new Set()) {
+    if (!existsSync(stateRoot) || seen.has(stateRoot))
+        return [];
+    seen.add(stateRoot);
+    let entries;
+    try {
+        entries = readdirSync(stateRoot, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const result = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const child = join(stateRoot, entry.name);
+        if (existsSync(join(child, "run.json")))
+            result.push(child);
+        if (depth + 1 < RUN_STATE_DISCOVERY_MAX_DEPTH)
+            result.push(...listRunStateDirs(child, depth + 1, seen));
+    }
+    return result;
+}
 function observeRun(stateDir) {
     try {
         const status = AsyncRuns.getRunStatus(stateDir);
@@ -90,9 +114,8 @@ export function summarizeRuns(stateRoot = Paths.getRunStateRoot(), ownerId) {
             total: 0,
         };
     }
-    const runs = readdirSync(stateRoot, { withFileTypes: true })
-        .filter((entry) => entry.isDirectory())
-        .map((entry) => observeRun(join(stateRoot, entry.name)))
+    const runs = listRunStateDirs(stateRoot)
+        .map((stateDir) => observeRun(stateDir))
         .filter((run) => Boolean(run))
         .filter((run) => ownerId === undefined || run.ownerId === ownerId)
         .sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""));
@@ -148,7 +171,7 @@ function getRunningRunPidMap(stateRoot, ownerId) {
     for (const run of summarizeRunsWithoutSubagents(stateRoot, ownerId).runs) {
         if (run.status !== "running")
             continue;
-        const status = AsyncRuns.getRunStatus(join(stateRoot, run.run));
+        const status = AsyncRuns.getRunStatus(run.stateDir ?? join(stateRoot, run.run));
         const pid = Number(status.pid || 0);
         if (pid > 0)
             pids.set(String(pid), run.run);
@@ -167,9 +190,8 @@ function summarizeRunsWithoutSubagents(stateRoot, ownerId) {
             runs: [],
             total: 0,
         };
-    const runs = readdirSync(stateRoot, { withFileTypes: true })
-        .filter((entry) => entry.isDirectory())
-        .map((entry) => observeRun(join(stateRoot, entry.name)))
+    const runs = listRunStateDirs(stateRoot)
+        .map((stateDir) => observeRun(stateDir))
         .filter((run) => Boolean(run))
         .filter((run) => ownerId === undefined || run.ownerId === ownerId)
         .sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""));
@@ -260,23 +282,86 @@ export function renderSubagentStatus(count, frame = 0) {
 export function renderRunStatus(summary, frame = 0) {
     return renderSubagentStatus(summary.runningSubagents, frame);
 }
+function isNestedStateDir(parent, child) {
+    const path = relative(parent, child);
+    return Boolean(path) && !path.startsWith("..") && !isAbsolute(path);
+}
 export function findRunRetirementCandidates(summary) {
     return summary.runs
-        .filter((run) => {
+        .map((run) => {
         const activeSubagents = Math.max(0, Math.floor(run.activeSubagents ?? 0));
         const descendantSubagents = Math.max(0, Math.floor(run.descendantSubagents ?? 0));
-        return (run.status === "running" &&
-            run.retireWhen === "children_terminal" &&
-            run.stateDir &&
-            activeSubagents + descendantSubagents <= 0);
+        const childRuns = run.stateDir
+            ? summary.runs.filter((child) => child.stateDir !== undefined &&
+                child.stateDir !== run.stateDir &&
+                isNestedStateDir(run.stateDir, child.stateDir))
+            : [];
+        const runningChildRuns = childRuns.filter((child) => child.status === "running").length;
+        return {
+            activeSubagents,
+            childRuns: childRuns.length,
+            descendantSubagents,
+            ready: run.status === "running" &&
+                run.retireWhen === "children_terminal" &&
+                run.stateDir !== undefined &&
+                !run.terminalHandled &&
+                activeSubagents + descendantSubagents + runningChildRuns <= 0,
+            run,
+            terminalChildRuns: childRuns.filter((child) => TERMINAL.has(child.status)).length,
+        };
     })
-        .map((run) => ({
-        activeSubagents: Math.max(0, Math.floor(run.activeSubagents ?? 0)),
-        descendantSubagents: Math.max(0, Math.floor(run.descendantSubagents ?? 0)),
-        run: run.run,
-        stateDir: run.stateDir,
+        .filter((item) => item.ready)
+        .map((item) => ({
+        activeSubagents: item.activeSubagents,
+        childRuns: item.childRuns,
+        descendantSubagents: item.descendantSubagents,
+        run: item.run.run,
+        stateDir: item.run.stateDir,
+        terminalChildRuns: item.terminalChildRuns,
     }));
 }
+export async function executeRunRetirements(summary, options) {
+    const results = [];
+    for (const candidate of findRunRetirementCandidates(summary)) {
+        if (options.attempted?.has(candidate.stateDir)) {
+            results.push({ action: "skip", run: candidate.run, stateDir: candidate.stateDir });
+            continue;
+        }
+        options.attempted?.add(candidate.stateDir);
+        try {
+            await options.sendStop(candidate);
+            options.notify?.(`Retiring actor ${candidate.run} after child runs reached terminal state`, "info");
+            results.push({ action: "stop", run: candidate.run, stateDir: candidate.stateDir });
+            continue;
+        }
+        catch (error) {
+            try {
+                const cancelResult = options.cancelRun(candidate);
+                const cancelled = Boolean(cancelResult.cancelled);
+                options.notify?.(cancelled
+                    ? `Retiring actor ${candidate.run} by cancellation after graceful stop failed`
+                    : `Actor retirement skipped for ${candidate.run}: ${error instanceof Error ? error.message : String(error)}`, cancelled ? "warning" : "error");
+                results.push({
+                    action: cancelled ? "cancel" : "skip",
+                    ...(cancelled ? {} : { error: error instanceof Error ? error.message : String(error) }),
+                    run: candidate.run,
+                    stateDir: candidate.stateDir,
+                });
+            }
+            catch (cancelError) {
+                const message = cancelError instanceof Error ? cancelError.message : String(cancelError);
+                options.notify?.(`Actor retirement failed for ${candidate.run}: ${message}`, "error");
+                results.push({
+                    action: "failed",
+                    error: message,
+                    run: candidate.run,
+                    stateDir: candidate.stateDir,
+                });
+            }
+        }
+    }
+    return results;
+}
 export function detectRunTransitions(previous, summary) {
     const transitions = [];
     for (const run of summary.runs) {

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/tools.js

@@ -790,7 +790,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 +820,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 +831,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`. 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 }`.
 
@@ -205,6 +207,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

@@ -158,7 +158,7 @@ The actor-level surface is:
 - `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.
 
-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:
 
@@ -185,7 +185,7 @@ 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.
 
-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.
 
 ## Coordinator Notifications
 
@@ -219,7 +219,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.
 

package/docs/recipe-library.md

@@ -70,7 +70,7 @@ inspect target=run:docs_review view=tail
 
 Pipeline recipes demonstrate second-order composition:
 
-- `recipes/coordinator-locker.json`: Long-lived coordinator cell with queue, acquire/renew/release lease locks, journal, and actor messages for worker coordination.
+- `recipes/coordinator-locker.json`: Long-lived coordinator cell with queue, acquire/renew/release lease locks, journal, actor messages for worker coordination, and platform-adapted control metadata.
 - `recipes/subagent-review-coordinator.json`: Lens reviewers → verifier → merger → judge → normalizer.
 - `recipes/pipeline-release-readiness.json`: Task-first release cell: changelog section → package summary → packaged skill summary → validation → release review → artifact report.
 - `recipes/pipeline-release-summary.json`: Evidence-only release summary cell: changelog section → package summary → packaged skill summary → validation → release summary / risks / PR body draft artifact. It does not commit, open a PR, merge, tag, publish, or perform external release side effects.
@@ -84,7 +84,7 @@ Pipeline recipes demonstrate second-order composition:
 - `recipes/pipeline-development-tasking.json`: Plan → task card → critique → integrator handoff.
 - `recipes/pipeline-docs-maintenance.json`: Docs index → documentation review → maintenance plan → artifact report.
 - `recipes/pipeline-media-library.json`: Playlist build → media-library artifact report.
-- `recipes/pipeline-room-swarm.json`: Room participants join `room:<run>`, coordinate over repeated room-visible rounds, leave cleanly, and synthesize the room transcript into a caller-provided artifact path. Keep model/thinking/mission policy caller-owned. Custom roles can be supplied with `roles_path` as a JSON array of `{ "name", "persona" }` objects; `name` stays ASCII-safe for `branch:<run>/<name>` addresses and debugger output remains plain and name-driven. The packaged swarm uses contacts for peer awareness but does not rely on direct branch delivery unless a caller-specific worker protocol consumes branch envelopes. Set `locker=true` to compose a local `coordinator-locker` cell under `{state_dir}/locker` for artifact ownership, resource lease locks, and a decision journal without merging locker policy into the room-participant script.
+- `recipes/pipeline-room-swarm.json`: Room participants join `room:<run>`, coordinate over repeated room-visible rounds, leave cleanly, and synthesize the room transcript into a caller-provided artifact path. Supported coordinator modes are `consensus`, `pipeline`, `fanout`, and `pool`; unknown modes fail closed instead of silently running consensus. Keep model/thinking/mission policy caller-owned. Custom roles can be supplied with `roles_path` as a JSON array of `{ "name", "persona" }` objects; `name` stays ASCII-safe for `branch:<run>/<name>` addresses and debugger output remains plain and name-driven. The packaged swarm uses contacts for peer awareness but does not rely on direct branch delivery unless a caller-specific worker protocol consumes branch envelopes. Set `locker=true` to compose a local `coordinator-locker` cell under `{state_dir}/locker` for artifact ownership, resource lease locks, and a decision journal without merging locker policy into the room-participant script.
 - `recipes/pipeline-artifact-report.json`: Normalize → artifact-shaped output → actor-message-shaped record. This pipeline prepares a candidate artifact and emits `artifact.prepared`/`artifact.blocked`; the `artifact_path` is a target path, not a guarantee that the file was written.
 - `recipes/pipeline-artifact-write.json`: Normalize → artifact-shaped output → deterministic artifact write → actor-message-shaped record. Use only when the caller explicitly wants filesystem writes; `write_mode` is `create`, `overwrite`, or `append`.
 - `recipes/pipeline-artifact-bundle.json`: Optional validation → deterministic artifact write → machine-readable manifest generation → deterministic manifest write → actor-message-shaped record. Use when the caller explicitly wants a filesystem handoff bundle with both artifact and manifest paths.
@@ -97,7 +97,7 @@ Utility recipes cover local operator workflows that do not need subagents:
 
 - `recipes/utility-markdown-index.json`: List Markdown files in a directory as input for README/docs index maintenance.
 - `recipes/utility-jsonl-tail.json`: Tail a JSONL message/log file with a configurable line count.
-- `recipes/utility-validation-wrapper.json`: Run a caller-supplied validation command in a scoped directory with a bounded timeout.
+- `recipes/utility-validation-wrapper.json`: Run a caller-supplied validation command in a scoped directory with a bounded timeout. This intentionally crosses a trusted shell boundary; discovery surfaces it as a diagnostic, and callers should pass explicit validation commands only.
 - `recipes/utility-git-status.json`: Read concise branch/worktree state for a repo.
 - `recipes/utility-git-log.json`: Read recent decorated commit history for a repo.
 - `recipes/utility-run-state-files.json`: List run-state files such as `run.json` under an async run state root.
@@ -115,7 +115,17 @@ Utility recipes cover local operator workflows that do not need subagents:
 - `recipes/utility-skill-summary.json`: Use `scripts/recipe-utils.mjs` to summarize packaged skill frontmatter, body shape, formatter-safe scalar lines, and package-version alignment.
 - `recipes/utility-validate-recipe.json`: Use `scripts/validate-recipe.mjs` to validate one template recipe file, or all packaged recipes in a directory with `all: true`.
 
-These recipes are intentionally small. Register them only for trusted local commands and prefer narrow scopes. The helper-backed utilities share `scripts/recipe-utils.mjs` so repeated parsing/listing logic stays out of recipe strings.
+These recipes are intentionally small. Register them only for trusted local commands and prefer narrow scopes. Discovery diagnostics flag obvious trust-boundary shapes such as shell/eval/destructive commands; those warnings are operator review aids, not a sandbox. The helper-backed utilities share `scripts/recipe-utils.mjs` so repeated parsing/listing logic stays out of recipe strings.
+
+## Actor OS Smoke Matrix
+
+The repeatable smoke surface is the normal validation suite:
+
+```text
+npm test
+```
+
+The scenario coverage is intentionally local-first and bounded: shared room coordination and roster snapshots (`actor-rooms` / `tools` tests), direct branch delivery and claim/handle transitions (`tools` and coordinator tests), inspector navigation (`actor-inspector-tui` tests), recipe context injection (`actor-recipe-context` / async-run tests), recipe persistence suggestions (`observability` tests), and opt-in retirement candidate/execution smoke (`observability` / async-run tests). These scenarios exercise public `spawn` / `message` / `inspect` behavior or the packaged script surfaces rather than relying on manual swarm demos.
 
 ## Music Player