@llblab/pi-actors 0.20.1 → 0.21.0

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
 

package/docs/template-recipes.md

@@ -1,10 +1,10 @@
 # Template Recipe Standard
 
-Template recipes are saved JSON definitions around the synchronous [Command Template Standard](./command-templates.md).
+Template recipes are saved definitions around the synchronous [Command Template Standard](./command-templates.md). JSON remains the canonical precise format; Markdown is a literate authoring format that compiles into the same recipe model.
 
 **Meta-contract:** a recipe stores a command-template graph plus defaults and run mode. It does not create a second execution language.
 
-**Scope:** reusable JSON shape, recipe naming, file-backed recipes, co-located recipes, recipe-layer imports/references, call-time values, foreground execution, and the `async: true` handoff to the [Async Run Standard](./async-runs.md).
+**Scope:** reusable JSON/Markdown shape, recipe naming, file-backed recipes, co-located recipes, recipe-layer imports/references, call-time values, foreground execution, and the `async: true` handoff to the [Async Run Standard](./async-runs.md).
 
 ---
 
@@ -27,7 +27,7 @@ Packaged recipes are the pi-actors recipe standard library: declarative actor co
 
 Template-recipe standard owns:
 
-- Saved JSON definitions around one command-template graph.
+- Saved JSON definitions around one command-template graph, plus Markdown-authored recipes that compile to that shape.
 - File-backed and co-located recipe shapes.
 - Recipe identity through file-backed filename or co-located tool id.
 - Recipe defaults, values, imports, import references, and import-node expansion.
@@ -67,6 +67,33 @@ Async recipe:
 
 A file-backed recipe's id comes from its filename, not a JSON `name` field. Legacy files may still contain `name`, but loaders ignore it for identity. `template` is the command-template tree. `async: true` selects detached run mode when the recipe is invoked through a registered tool.
 
+## Markdown Authoring
+
+Markdown recipes use `.md` files with YAML-like frontmatter for recipe metadata and one fenced executable block for the recipe/template body. Runtime behavior comes only from frontmatter plus the fenced block; surrounding prose is advisory for humans and future recipe-context use.
+
+````markdown
+---
+description: Literate docs check
+args:
+  - scope:path
+defaults:
+  scope: docs
+mailbox:
+  accepts:
+    - control.stop
+---
+
+Human notes can explain intent, examples, or review guidance.
+
+```template
+npm run check -- {scope}
+```
+````
+
+Fenced blocks marked `template`, `command-template`, `json`, or `recipe` are executable. A `template` fence stores its text as the command-template string. A JSON fence can contain either a full recipe object with `template` or a raw command-template value. Frontmatter supports the recipe metadata used by JSON recipes, including `args`, `defaults`, `imports`, `mailbox`, `artifacts`, `async`, and command-template flags.
+
+JSON remains the source-of-truth format for precise machine editing. If `<id>.json` and `<id>.md` exist in the same discovery priority layer, `<id>.json` wins and the Markdown recipe is reported as shadowed.
+
 ## Discovery Priority
 
 Recipe priority only matters when two discovered recipes have the same filename id. The conceptual ladder from lowest to highest priority is:
@@ -74,11 +101,11 @@ Recipe priority only matters when two discovered recipes have the same filename
 1. No recipe for that id.
 2. Packaged pi-actors recipe components, acting as the standard library.
 3. Explicitly referenced ad hoc user recipe files located outside `~/.pi/agent/recipes`.
-4. User recipe files under `~/.pi/agent/recipes/*.json`.
+4. User recipe files under `~/.pi/agent/recipes/*.json` or `*.md`.
 
 The high-priority user recipe directory is also the default tool set: recipes placed there are agent tools by location. This preserves the old advantage of a tool-only registry because listing `~/.pi/agent/recipes` shows the operator-managed tool surface. Packaged and ad hoc recipes are recipe components by default; they become tools only when copied or registered into the agent recipe root.
 
-Higher-priority files shadow lower-priority files with the same basename. A highest-priority invalid recipe is still visible and blocks fallback so operators do not accidentally run packaged behavior when a user override is broken. A highest-priority recipe with `disabled: true` also blocks fallback and intentionally disables that id.
+Higher-priority files shadow lower-priority files with the same basename. Within one priority layer, same-id JSON shadows Markdown because JSON is the canonical precise format. A highest-priority invalid recipe is still visible and blocks fallback so operators do not accidentally run packaged behavior when a user override is broken. A highest-priority recipe with `disabled: true` also blocks fallback and intentionally disables that id.
 
 ## Usage Metadata
 
@@ -203,19 +230,22 @@ Reusable local recipes live in:
 
 ```text
 ~/.pi/agent/recipes/*.json
+~/.pi/agent/recipes/*.md
 ```
 
 Bare recipe names resolve under that directory, so `file: "review-docs"` loads:
 
 ```text
 ~/.pi/agent/recipes/review-docs.json
+# or, when no same-id JSON file exists:
+~/.pi/agent/recipes/review-docs.md
 ```
 
 Call-time params override file params. `values` are merged with file values; call-time values win. If a run id is omitted for an explicit async start, the file basename becomes the default run id.
 
 ## Registered Recipe Tools
 
-A registered tool is a recipe file exposed as an agent tool. User recipes under `~/.pi/agent/recipes/*.json` are tools by location; packaged/ad hoc recipes are components unless copied or registered into that user recipe root:
+A registered tool is a recipe file exposed as an agent tool. User recipes under `~/.pi/agent/recipes/*.json` or `*.md` are tools by location; packaged/ad hoc recipes are components unless copied or registered into that user recipe root:
 
 ```json
 {
@@ -312,6 +342,6 @@ Nested object keys are dot-separated. Import references are resolved before norm
 
 ## Recipe Shape
 
-Use the filename for file-backed recipe ids, and use `async: true` for detached runs. Use `parallel: true` for fanout, `when` for node guards, and semantic public args such as `tools`, `all`, or `timeout_ms` instead of leaking CLI fragments or reusing node-control names. Local files belong under `~/.pi/agent/recipes/*.json` before relying on recipe launchers.
+Use the filename for file-backed recipe ids, and use `async: true` for detached runs. Use `parallel: true` for fanout, `when` for node guards, and semantic public args such as `tools`, `all`, or `timeout_ms` instead of leaking CLI fragments or reusing node-control names. Local files belong under `~/.pi/agent/recipes/*.json` or `*.md` before relying on recipe launchers.
 
 If a proposed recipe needs a scheduler, queue daemon, `goto`, or custom workflow syntax, stop. Keep the recipe as saved command-template JSON and put policy in the registered tool, script, or caller.

package/docs/tool-registry.md

@@ -1,6 +1,6 @@
 # Tool Registry
 
-`pi-actors` stores persistent agent tools as recipe files under `~/.pi/agent/recipes/*.json` and registers the active tool set automatically on session start.
+`pi-actors` stores persistent agent tools as recipe files under `~/.pi/agent/recipes/*.json` or `*.md` and registers the active tool set automatically on session start.
 
 This document is the local adaptation of the portable [Command Template Standard](./command-templates.md) and the recipe-file runtime described in [Template Recipe Standard](./template-recipes.md).
 
@@ -8,11 +8,12 @@ This document is the local adaptation of the portable [Command Template Standard
 
 The registry source is location-discovered recipes, not a live tool-only JSON file and not a recipe-owned boolean:
 
-- `~/.pi/agent/recipes/*.json` is the highest-priority user recipe root and the operator-managed tool set.
+- `~/.pi/agent/recipes/*.json` and `*.md` are the highest-priority user recipe root and the operator-managed tool set.
 - Recipes in that root are tools by location.
 - Packaged pi-actors recipes are the lower-priority standard library of declarative actor config components, not automatically registered tools.
 - Ad hoc recipe files outside the user recipe root are components unless explicitly registered/copied into `~/.pi/agent/recipes`.
-- Recipe identity is the filename basename; `~/.pi/agent/recipes/docs_review.json` has id/tool name `docs_review`.
+- Recipe identity is the filename basename; `~/.pi/agent/recipes/docs_review.json` and `docs_review.md` both have id/tool name `docs_review`.
+- Same-id JSON shadows Markdown in the same priority layer.
 
 
 Because the user recipe directory is sticky agent muscle memory, runtime launches update `usage.calls`, `usage.last_called`, and a content `usage.fingerprint` on user-owned recipe files. If authored recipe content changes, the next launch resets `usage.calls` and records `usage.reset_at` before counting the launch, so usage evidence follows the current recipe meaning rather than an older file history. `inspect target=recipes view=summary verbose=true` includes usage metadata and operator-gated cleanup recommendations for invalid, shadowed, disabled, component-only, unused, or overriding recipes. Recommended actions stay explicit: keep as a tool/component, enable, merge, fix, delete, or archive. The extension does not maintain a failure counter and agents should not silently clean tools during unrelated work.

package/index.js

@@ -0,0 +1,19 @@
+/**
+ * Runtime extension entrypoint wrapper.
+ *
+ * Installed npm packages load compiled JS from dist so Node does not try to strip
+ * TypeScript under node_modules. Source checkouts fall back to index.ts for local
+ * development before dist has been built.
+ */
+
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const compiledEntry = resolve(here, "dist", "index.js");
+const sourceEntry = resolve(here, "index.ts");
+const entry = existsSync(compiledEntry) ? compiledEntry : sourceEntry;
+const entryModule = await import(pathToFileURL(entry).href);
+
+export default entryModule.default;

package/index.ts

@@ -13,6 +13,7 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 
 import * as ActorInspectorTui from "./lib/actor-inspector-tui.ts";
+import * as AsyncRuns from "./lib/async-runs.ts";
 import * as CommandTemplates from "./lib/command-templates.ts";
 import * as Observability from "./lib/observability.ts";
 import * as Paths from "./lib/paths.ts";
@@ -47,6 +48,7 @@ export default function toolRegistryExtension(pi: ExtensionAPI) {
   const runDirWatchers = new Map<string, FSWatcher>();
   const observedRuns = new Map<string, Observability.RunObservedStatus>();
   const observedRunEventLines = new Map<string, number>();
+  const retirementAttempts = new Set<string>();
   let runStatusFrame = 0;
   let communicationWidgetVisible = false;
   let actorInspectorRows = 12;
@@ -61,6 +63,17 @@ export default function toolRegistryExtension(pi: ExtensionAPI) {
   let recipeWatcherFailureNotified = false;
   const getRunOwnerId = (ctx: ExtensionContext): string =>
     ctx.sessionManager.getSessionId();
+  const retireCandidateRuns = (
+    ctx: ExtensionContext,
+    summary: Observability.RunSummary,
+  ): void => {
+    void Observability.executeRunRetirements(summary, {
+      attempted: retirementAttempts,
+      cancelRun: (candidate) => AsyncRuns.cancelRun(candidate.stateDir),
+      notify: (message, level) => ctx.ui.notify(message, level),
+      sendStop: (candidate) => AsyncRuns.sendRunMessage(candidate.stateDir, "stop"),
+    });
+  };
   const updateRunUi = (ctx: ExtensionContext, notify = false): void => {
     const ownerId = getRunOwnerId(ctx);
     const summary = Observability.summarizeRuns(undefined, ownerId);
@@ -139,6 +152,7 @@ export default function toolRegistryExtension(pi: ExtensionAPI) {
       summary,
     );
     if (!notify) return;
+    retireCandidateRuns(ctx, summary);
     for (const transition of transitions) {
       if (!Observability.shouldNotifyRunTransition(transition)) continue;
       const text = Observability.formatRunTransitionMessage(transition);

package/lib/actor-rooms.ts

@@ -13,6 +13,7 @@ import type { ActorMessage } from "./actor-messages.ts";
 const STATE_LOCK_MAX_AGE_MS = 5 * 60 * 1000;
 const STATE_LOCK_TIMEOUT_MS = 5000;
 const DEFAULT_ROOM_MAX_MESSAGES = 10000;
+const DEFAULT_BRANCH_INBOX_TERMINAL_RETAINED = 2000;
 const DEFAULT_SNAPSHOT_MIN_INTERVAL_MS = 250;
 
 export interface RoomMember {
@@ -241,6 +242,15 @@ function readJsonlLineCount(file: string): number {
   }
 }
 
+function readRoomMessageCount(stateDir: string, room: string): number {
+  try {
+    return readJsonlLineCount(messagesFile(stateDir, room));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return 0;
+    throw error;
+  }
+}
+
 function readJsonlTailLines(file: string, limit: number): string[] {
   const lineLimit = Math.max(1, limit);
   const stat = fs.statSync(file);
@@ -377,6 +387,26 @@ export function readBranchInboxMessages(
   }
 }
 
+export function getBranchInboxTerminalRetainLimit(): number {
+  const value = Number(process.env.PI_ACTORS_BRANCH_INBOX_TERMINAL_RETAINED ?? "");
+  return Number.isInteger(value) && value >= 0
+    ? value
+    : DEFAULT_BRANCH_INBOX_TERMINAL_RETAINED;
+}
+
+function compactBranchInboxMessages<T extends { status?: string }>(
+  messages: T[],
+): T[] {
+  const retainTerminal = getBranchInboxTerminalRetainLimit();
+  const active = messages.filter(
+    (message) => message.status !== "handled" && message.status !== "failed",
+  );
+  const terminal = messages.filter(
+    (message) => message.status === "handled" || message.status === "failed",
+  );
+  return [...terminal.slice(-retainTerminal), ...active];
+}
+
 export function appendBranchInboxMessage(
   stateDir: string,
   run: string,
@@ -419,7 +449,8 @@ export function updateBranchInboxMessageStatus(
       return { ...message, ...metadata, [timestampKey]: new Date().toISOString(), status };
     });
     if (!changed) return false;
-    fs.writeFileSync(file, `${updated.map((message) => JSON.stringify(message)).join("\n")}\n`);
+    const compacted = compactBranchInboxMessages(updated);
+    fs.writeFileSync(file, `${compacted.map((message) => JSON.stringify(message)).join("\n")}\n`);
     return true;
   } finally {
     releaseLock();
@@ -446,7 +477,7 @@ export function appendRoomMessage(
       }
     }
     return {
-      message_count: readRoomMessages(stateDir, room).length,
+      message_count: readRoomMessageCount(stateDir, room),
       room,
       roster_count: Object.keys(roster).length,
       sent: true,
@@ -496,12 +527,7 @@ export function readRoomMessagePreviews(
 }
 
 export function getRoomStatus(stateDir: string, room: string): RoomStatus {
-  let messageCount = 0;
-  try {
-    messageCount = readJsonlLineCount(messagesFile(stateDir, room));
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
-  }
+  const messageCount = readRoomMessageCount(stateDir, room);
   const [last] = readRoomMessages(stateDir, room, 1);
   return {
     ...(last
@@ -529,7 +555,7 @@ export function ensureRoomMember(
   const roster = readRoomRoster(stateDir, room);
   if (roster[address]) {
     return {
-      message_count: readRoomMessages(stateDir, room).length,
+      message_count: readRoomMessageCount(stateDir, room),
       room,
       roster_count: Object.keys(roster).length,
       sent: true,