@llblab/pi-actors 0.20.1 → 0.21.0

package/lib/recipe-references.ts

@@ -6,7 +6,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 type {
   CommandTemplateConfig,
@@ -101,7 +101,9 @@ export function resolveRecipePath(
   if (expanded.includes("/")) return resolve(expanded);
   return resolve(
     recipeRoot,
-    expanded.endsWith(".json") ? expanded : `${expanded}.json`,
+    expanded.endsWith(".json") || expanded.endsWith(".md")
+      ? expanded
+      : `${expanded}.json`,
   );
 }
 
@@ -110,20 +112,26 @@ function isBareRecipeName(value: string): boolean {
   return Boolean(trimmed) && !trimmed.includes("/") && !trimmed.startsWith("~") && !trimmed.includes("{");
 }
 
-function recipeNameFile(value: string): string {
+function recipeNameFiles(value: string): string[] {
   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: string, currentRecipeRoot: string): string {
   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];
 }
 
@@ -134,14 +142,14 @@ export function getRecipePath(
   if (typeof value !== "string") return undefined;
   const trimmed = value.trim();
   if (!trimmed || hasWhitespace(trimmed)) return undefined;
-  if (trimmed.endsWith(".json")) return resolveRecipePath(trimmed, recipeRoot);
-  const path = resolveRecipePath(trimmed, recipeRoot);
+  if (trimmed.endsWith(".json") || trimmed.endsWith(".md"))
+    return 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")) as Record<
-      string,
-      unknown
-    >;
+    const raw = readRawRecipeConfig(path);
     return raw && typeof raw === "object" && Object.hasOwn(raw, "template")
       ? path
       : undefined;
@@ -232,6 +240,123 @@ function getRecipeCommandTemplate(
   return normalizeRecipeTemplate({ ...envelope, template });
 }
 
+function parseMarkdownScalar(value: string): unknown {
+  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: string[],
+): Record<string, unknown> | unknown[] {
+  if (lines.every((line) => /^\s*-\s+/.test(line))) {
+    return lines.map((line) => parseMarkdownScalar(line.replace(/^\s*-\s+/, "")));
+  }
+  const result: Record<string, unknown> = {};
+  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: string[] = [];
+    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: string): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  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: string[] = [];
+    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: string,
+): { info: string; body: string } | undefined {
+  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: string,
+): Record<string, unknown> | undefined {
+  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) as unknown;
+      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: string,
 ): Record<string, unknown> | undefined {
@@ -243,10 +368,9 @@ export function readRawRecipeConfig(
     );
   }
   try {
-    const raw = JSON.parse(readFileSync(path, "utf8")) as Record<
-      string,
-      unknown
-    >;
+    const content = readFileSync(path, "utf8");
+    if (path.endsWith(".md")) return parseMarkdownRecipeConfig(content);
+    const raw = JSON.parse(content) as Record<string, unknown>;
     return raw && typeof raw === "object" ? raw : undefined;
   } catch {
     return undefined;
@@ -254,7 +378,7 @@ export function readRawRecipeConfig(
 }
 
 export function getRecipeIdFromPath(file: string): string {
-  return basename(file, ".json");
+  return basename(file, extname(file));
 }
 
 function readRecipeConfig(value: unknown): TemplateRecipeConfig | undefined {

package/lib/tools.ts

@@ -1089,7 +1089,7 @@ export function createActorMessageToolDefinition<TContext = unknown>(
         } else if (message.type === "control.kill") {
           result = AsyncRuns.killRun(address.value);
         } else {
-          result = AsyncRuns.sendRunMessage(
+          result = await AsyncRuns.sendRunMessage(
             address.value,
             messageBodyToRunLine(message),
           );
@@ -1131,7 +1131,7 @@ export function createActorMessageToolDefinition<TContext = unknown>(
           ActorRooms.writeCommunicationSnapshot(stateDir, runId);
           ActorRooms.appendBranchInboxMessage(stateDir, runId, message.to, message);
         }
-        result = AsyncRuns.sendRunMessage(
+        result = await AsyncRuns.sendRunMessage(
           address.value,
           JSON.stringify(message),
         );
@@ -1143,16 +1143,18 @@ export function createActorMessageToolDefinition<TContext = unknown>(
         if (!stateDir) 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 }
             : {}),
         };
       } else if (address.kind === "tool" && address.value) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.20.1",
+  "version": "0.21.0",
   "private": false,
   "description": "Local Actor Kernel for Pi",
   "keywords": [
@@ -33,6 +33,7 @@
     "prepack": "npm run build"
   },
   "files": [
+    "index.js",
     "index.ts",
     "lib",
     "scripts",
@@ -48,7 +49,7 @@
   ],
   "pi": {
     "extensions": [
-      "./index.ts"
+      "./index.js"
     ],
     "skills": [
       "./skills/actors/SKILL.md",
@@ -57,7 +58,8 @@
     "image": "https://github.com/llblab/pi-actors/raw/main/banner.jpg"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*"
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
   },
   "devDependencies": {
     "@types/node": "latest",

package/recipes/pipeline-room-swarm.json

@@ -1,7 +1,7 @@
 {
   "async": true,
   "args": [
-    "mode:string",
+    "mode:enum(consensus,pipeline,fanout,pool)",
     "mission:string",
     "model:string",
     "thinking:string",

package/scripts/coordinator.mjs

@@ -2,6 +2,7 @@
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { createConnection } from "node:net";
 
 function arg(name, fallback = "") {
   const prefix = `--${name}=`;
@@ -102,10 +103,34 @@ async function acquireBranchInboxLock(runId, branchName) {
   return acquireStateLock(`${runStateDir(runId)}/branches/${branchName}`, ".inbox.lock", `Branch inbox ${branchName}`);
 }
 
+async function readLockerControl(locker) {
+  const controlJson = `${locker.stateDir}/control.json`;
+  await waitForPath(controlJson);
+  return JSON.parse(await readFile(controlJson, "utf8"));
+}
+
+function writeNamedPipeLine(path, line) {
+  return new Promise((resolve, reject) => {
+    const socket = createConnection(path);
+    let settled = false;
+    const finish = (error) => {
+      if (settled) return;
+      settled = true;
+      if (error) reject(error);
+      else resolve();
+    };
+    socket.on("error", finish);
+    socket.on("connect", () => socket.end(line, () => finish()));
+  });
+}
+
 async function writeLockerMessage(locker, message) {
   if (!locker) return;
-  await waitForPath(locker.controlPath);
-  await writeFile(locker.controlPath, `${JSON.stringify(message)}\n`, { flag: "a" });
+  const control = locker.control ?? await readLockerControl(locker);
+  locker.control = control;
+  const line = `${JSON.stringify(message)}\n`;
+  if (control.type === "named-pipe") await writeNamedPipeLine(control.path, line);
+  else await writeFile(control.path, line, { flag: "a" });
   await sleep(50);
 }
 
@@ -125,8 +150,8 @@ async function startLocker(config) {
   });
   child.stdout.on("data", (chunk) => process.stdout.write(`[locker] ${chunk}`));
   child.stderr.on("data", (chunk) => process.stderr.write(`[locker] ${chunk}`));
-  const locker = { child, controlPath: `${lockerStateDir}/control.fifo`, stateDir: lockerStateDir };
-  await waitForPath(locker.controlPath);
+  const locker = { child, stateDir: lockerStateDir };
+  locker.control = await readLockerControl(locker);
   await writeLockerMessage(locker, {
     type: "lock.enqueue",
     body: { id: "coordinator-artifact", task: "Own final artifact synthesis", resources: [config.artifactPath || "artifact"] },
@@ -230,11 +255,23 @@ async function writeInboxMessages(inboxPath, messages) {
   await writeFile(inboxPath, messages.map((message) => JSON.stringify(message)).join("\n") + "\n", "utf8");
 }
 
-async function claimQueuedInboxMessages(runId, branchName) {
+async function mutateBranchInbox(runId, branchName, mutate, fallback) {
   const inboxPath = `${runStateDir(runId)}/branches/${branchName}/inbox.jsonl`;
   const releaseLock = await acquireBranchInboxLock(runId, branchName);
   try {
     const messages = await readInboxLines(inboxPath);
+    const result = mutate(messages);
+    if (result.messages) await writeInboxMessages(inboxPath, result.messages);
+    return result.value;
+  } catch {
+    return fallback;
+  } finally {
+    await releaseLock();
+  }
+}
+
+async function claimQueuedInboxMessages(runId, branchName) {
+  return mutateBranchInbox(runId, branchName, (messages) => {
     const claimedAt = new Date().toISOString();
     const queuedMessages = [];
     const updated = messages.map((msg, index) => {
@@ -248,31 +285,22 @@ async function claimQueuedInboxMessages(runId, branchName) {
       queuedMessages.push(claimed);
       return claimed;
     });
-    if (queuedMessages.length > 0) await writeInboxMessages(inboxPath, updated);
-    return queuedMessages;
-  } catch {
-    return [];
-  } finally {
-    await releaseLock();
-  }
+    return {
+      messages: queuedMessages.length > 0 ? updated : undefined,
+      value: queuedMessages,
+    };
+  }, []);
 }
 
 async function updateInboxMessagesStatus(runId, branchName, ids, status) {
-  const inboxPath = `${runStateDir(runId)}/branches/${branchName}/inbox.jsonl`;
-  const releaseLock = await acquireBranchInboxLock(runId, branchName);
-  try {
-    const messages = await readInboxLines(inboxPath);
+  await mutateBranchInbox(runId, branchName, (messages) => {
     const idSet = new Set(ids);
     const updated = messages.map((msg) => {
       if (!msg.id || !idSet.has(msg.id)) return msg;
       return { ...msg, [`${status}_at`]: new Date().toISOString(), status };
     });
-    await writeInboxMessages(inboxPath, updated);
-  } catch {
-    // Best-effort write
-  } finally {
-    await releaseLock();
-  }
+    return { messages: updated, value: undefined };
+  });
 }
 
 async function executeParticipantPrompt(role, basePrompt, config) {
@@ -421,6 +449,13 @@ async function runPool(config, locker) {
   }));
 }
 
+const coordinatorModes = {
+  consensus: runConsensus,
+  fanout: runFanout,
+  pipeline: runPipeline,
+  pool: runPool,
+};
+
 async function readJsonFile(path) {
   try {
     return JSON.parse(await readFile(path, "utf8"));
@@ -464,16 +499,9 @@ const failures = [];
 const locker = await startLocker(config);
 
 try {
-  if (config.mode === "pipeline") {
-    await runPipeline(config, locker);
-  } else if (config.mode === "fanout") {
-    await runFanout(config, locker);
-  } else if (config.mode === "pool") {
-    await runPool(config, locker);
-  } else {
-    // default: consensus / swarm
-    await runConsensus(config, locker);
-  }
+  const runMode = coordinatorModes[config.mode];
+  if (!runMode) throw new Error(`Unknown coordinator mode: ${config.mode}`);
+  await runMode(config, locker);
   await synthesize(config, locker);
 } catch (globalError) {
   failures.push(`Global coordinator error: ${globalError.message}`);

package/scripts/locker.mjs

@@ -8,7 +8,9 @@ import {
   writeFileSync,
 } from "node:fs";
 import { dirname, join, resolve } from "node:path";
+import { createHash } from "node:crypto";
 import { spawnSync } from "node:child_process";
+import { createServer } from "node:net";
 import readline from "node:readline";
 
 function parseArgs(argv) {
@@ -49,6 +51,17 @@ function writeJson(path, value) {
   mkdirSync(dirname(path), { recursive: true });
   writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
 }
+function getControlEndpoint() {
+  if (process.platform !== "win32") return { path: controlPath, type: "fifo" };
+  const hash = createHash("sha256").update(resolve(stateDir)).digest("hex").slice(0, 20);
+  return { path: `\\\\.\\pipe\\pi-actors-locker-${hash}`, type: "named-pipe" };
+}
+function writeControlEndpoint(endpoint) {
+  writeJson(join(stateDir, "control.json"), endpoint);
+  const runPath = join(stateDir, "run.json");
+  const run = readJson(runPath, undefined);
+  if (run && typeof run === "object") writeJson(runPath, { ...run, control: endpoint });
+}
 function journal(event, data = {}) {
   appendFileSync(
     journalPath,
@@ -244,30 +257,55 @@ if (mode === "snapshot") {
   process.exit(0);
 }
 
-if (!existsSync(controlPath)) {
-  const result = spawnSync("mkfifo", [controlPath]);
-  if (result.status !== 0)
-    throw new Error(`mkfifo failed: ${result.stderr?.toString?.() ?? ""}`);
+function handleLine(line) {
+  const message = normalizeMessage(line);
+  if (!message) return;
+  try {
+    handle(message);
+  } catch (error) {
+    const text = error instanceof Error ? error.message : String(error);
+    journal("lock.error", { error: text });
+    outbox("lock.error", text, { error: text }, "error");
+  }
 }
-writeJson(queuePath, readJson(queuePath, { items: [] }));
-writeJson(locksPath, cleanExpiredLocks(readJson(locksPath, {})));
-journal("lock.started", { leaseMs });
-outbox("lock.started", "Locker ready", { leaseMs });
 
-while (true) {
-  const stream = await import("node:fs").then((fs) =>
-    fs.createReadStream(controlPath, { encoding: "utf8" }),
-  );
-  const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
-  for await (const line of rl) {
-    const message = normalizeMessage(line);
-    if (!message) continue;
-    try {
-      handle(message);
-    } catch (error) {
-      const text = error instanceof Error ? error.message : String(error);
-      journal("lock.error", { error: text });
-      outbox("lock.error", text, { error: text }, "error");
-    }
+async function serveFifo(endpoint) {
+  if (!existsSync(endpoint.path)) {
+    const result = spawnSync("mkfifo", [endpoint.path]);
+    if (result.status !== 0)
+      throw new Error(`mkfifo failed: ${result.stderr?.toString?.() ?? ""}`);
+  }
+  writeControlEndpoint(endpoint);
+  while (true) {
+    const stream = await import("node:fs").then((fs) =>
+      fs.createReadStream(endpoint.path, { encoding: "utf8" }),
+    );
+    const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    for await (const line of rl) handleLine(line);
   }
 }
+
+async function serveNamedPipe(endpoint) {
+  rmSync(endpoint.path, { force: true });
+  const server = createServer((socket) => {
+    const rl = readline.createInterface({ input: socket, crlfDelay: Infinity });
+    rl.on("line", handleLine);
+  });
+  await new Promise((resolveReady, rejectReady) => {
+    server.once("error", rejectReady);
+    server.listen(endpoint.path, () => {
+      server.off("error", rejectReady);
+      writeControlEndpoint(endpoint);
+      resolveReady();
+    });
+  });
+  await new Promise(() => {});
+}
+
+const endpoint = getControlEndpoint();
+writeJson(queuePath, readJson(queuePath, { items: [] }));
+writeJson(locksPath, cleanExpiredLocks(readJson(locksPath, {})));
+journal("lock.started", { leaseMs, control: endpoint.type });
+outbox("lock.started", "Locker ready", { leaseMs, control: endpoint.type });
+if (endpoint.type === "named-pipe") await serveNamedPipe(endpoint);
+else await serveFifo(endpoint);

package/scripts/validate-recipe.mjs

@@ -26,7 +26,7 @@ function usage() {
   console.error(`Usage:
   validate-recipe.mjs <recipe-file-or-dir> [--all]
 
-Validates one template recipe file, or all *.json files in a directory when --all is set.`);
+Validates one template recipe file, or all *.json/*.md files in a directory when --all is set.`);
 }
 
 function expandPath(value) {
@@ -56,7 +56,7 @@ function recipeFiles(target, all) {
     throw new Error(`Recipe path is not a file or directory: ${target}`);
   if (!all) throw new Error("Directory validation requires --all.");
   return readdirSync(target)
-    .filter((file) => file.endsWith(".json"))
+    .filter((file) => file.endsWith(".json") || file.endsWith(".md"))
     .sort((a, b) => a.localeCompare(b))
     .map((file) => resolve(target, file));
 }

package/skills/actors/SKILL.md

@@ -2,7 +2,7 @@
 name: actors
 description: Highest-density practical guide for pi-actors. Read this skill whenever prompt and tools are not enough for spawn, message, inspect, actor runs, tools, recipes, command templates, async lifecycle, mailboxes, artifacts, and local orchestration mechanics.
 metadata:
-  version: 0.20.1
+  version: 0.21.0
 ---
 
 # Actors (pi-actors)
@@ -228,11 +228,11 @@ Priority for same-id recipes:
 1. No recipe: no capability.
 2. Packaged pi-actors recipe: standard-library declarative actor component.
 3. Explicit ad hoc user recipe file outside `~/.pi/agent/recipes`.
-4. User recipe in `~/.pi/agent/recipes/*.json`: highest-priority operator tool surface.
+4. User recipe in `~/.pi/agent/recipes/*.json` or `*.md`: highest-priority operator tool surface.
 
-Only matching filename ids compete. Higher priority shadows lower priority. An invalid or `disabled: true` higher-priority recipe blocks fallback so the agent does not silently run standard-library behavior when a user override is broken or intentionally disabled.
+Only matching filename ids compete. Higher priority shadows lower priority; within one priority layer, same-id JSON shadows Markdown. An invalid or `disabled: true` higher-priority recipe blocks fallback so the agent does not silently run standard-library behavior when a user override is broken or intentionally disabled.
 
-Muscle-memory lens: `~/.pi/agent/recipes/*.json` is the agent's capability memory. Every recipe in that directory becomes an easy-to-call tool automatically and survives into later sessions. Agents grow this memory either by calling `register_tool`, which writes recipe files there under the hood, or by deliberately editing those recipe files. Treat this directory like `MEMORY.md` for executable habits: useful local patterns belong there; packaged recipes elsewhere are reusable components, not tools.
+Muscle-memory lens: `~/.pi/agent/recipes/*.json` and `*.md` are the agent's capability memory. Every recipe in that directory becomes an easy-to-call tool automatically and survives into later sessions. Agents grow this memory either by calling `register_tool`, which writes recipe files there under the hood, or by deliberately editing those recipe files. Treat this directory like `MEMORY.md` for executable habits: useful local patterns belong there; packaged recipes elsewhere are reusable components, not tools.
 
 Usage lens: user recipes may carry extension-maintained launch metadata such as `usage.calls` and `usage.last_called`. The extension increments the counter when it starts that concrete recipe; agents should not hand-edit counters as part of normal recipe maintenance. Treat usage as evidence for usefulness analysis: heavily used recipes are good candidates for promotion, documentation, or stronger tests; unused recipes are cleanup candidates. Do not use failure counts as a primary usefulness signal because failures may reflect bad caller judgment rather than bad recipes. Do not delete or demote solely from counters without operator approval.
 
@@ -240,7 +240,7 @@ Cleanup rule: periodically inspect `~/.pi/agent/recipes` as the live muscle-memo
 
 ## Registered Tools
 
-`register_tool` persists trusted local capabilities as recipe files in `~/.pi/agent/recipes/*.json`.
+`register_tool` persists trusted local capabilities as recipe files in `~/.pi/agent/recipes/*.json`; hand-authored Markdown recipes in the same directory are also discovered as tools.
 
 Use it when a command/template/recipe should become durable agent muscle memory. Prefer typed args or placeholder-derived args; use `update=true` for replacement and `template=null` or `template=""` for deletion. `register_tool` should create/update/delete recipe files in the user recipe root; direct file editing is allowed but is the lower-level path.
 
@@ -250,7 +250,7 @@ Tool templates may be:
 - A file-backed recipe name/path.
 - A complete recipe body, optionally `async: true`.
 
-The user recipe root is the default tool set by location; packaged recipes are lower-priority standard-library components and are not tools unless copied or registered into the agent recipe root. Ideal runtime behavior is reactive: create/edit/delete recipe files, validate them, then connect valid tools or surface diagnostics without requiring agents to hand-maintain a separate registry.
+The user recipe root is the default tool set by location. It accepts canonical JSON recipes and literate Markdown recipes with frontmatter plus fenced `template`/`json recipe` blocks; same-id JSON shadows Markdown in the same priority layer. Packaged recipes are lower-priority standard-library components and are not tools unless copied or registered into the agent recipe root. Ideal runtime behavior is reactive: create/edit/delete recipe files, validate them, then connect valid tools or surface diagnostics without requiring agents to hand-maintain a separate registry.
 
 ## Recipe Navigator
 
@@ -258,8 +258,8 @@ Use packaged recipes by name with `spawn file=<name>` for async actors, or regis
 
 ### Coordination and Services
 
-- [`coordinator-locker`](../../recipes/coordinator-locker.json): queue + acquire/renew/release lease locks + journaled coordinator messages.
-- [`locker`](../../recipes/locker.json): modular queue + acquire/renew/release lease locks + journaled locker messages.
+- [`coordinator-locker`](../../recipes/coordinator-locker.json): queue + acquire/renew/release lease locks + journaled coordinator messages + platform-adapted control metadata.
+- [`locker`](../../recipes/locker.json): modular queue + acquire/renew/release lease locks + journaled locker messages + platform-adapted control metadata.
 - [`utility-coordinator-lock-snapshot`](../../recipes/utility-coordinator-lock-snapshot.json): one-shot JSON snapshot of a coordinator-locker state directory.
 - [`music-player`](../../recipes/music-player.json): background local/URL/directory/playlist playback actor controlled by messages.
 
@@ -280,7 +280,7 @@ Use packaged recipes by name with `spawn file=<name>` for async actors, or regis
 - [`pipeline-docs-maintenance`](../../recipes/pipeline-docs-maintenance.json): docs index/review/planning → maintenance artifact.
 - Artifacts: [`pipeline-artifact-report`](../../recipes/pipeline-artifact-report.json), [`pipeline-artifact-write`](../../recipes/pipeline-artifact-write.json), [`pipeline-artifact-bundle`](../../recipes/pipeline-artifact-bundle.json).
 - Review gates: [`pipeline-quorum-review`](../../recipes/pipeline-quorum-review.json), [`pipeline-review-readiness`](../../recipes/pipeline-review-readiness.json).
-- Task-first workflows: [`pipeline-architect-coordinator`](../../recipes/pipeline-architect-coordinator.json), [`pipeline-research-synthesis`](../../recipes/pipeline-research-synthesis.json), [`pipeline-development-tasking`](../../recipes/pipeline-development-tasking.json), [`pipeline-checkpoint-continuation`](../../recipes/pipeline-checkpoint-continuation.json), [`pipeline-media-library`](../../recipes/pipeline-media-library.json), [`pipeline-room-swarm`](../../recipes/pipeline-room-swarm.json). For room swarms, prefer `roles_path` for custom role JSON and keep role `name` ASCII-safe for branch addresses. Use `locker=true` when the swarm needs a coordinator-locker-backed artifact lock and journal.
+- Task-first workflows: [`pipeline-architect-coordinator`](../../recipes/pipeline-architect-coordinator.json), [`pipeline-research-synthesis`](../../recipes/pipeline-research-synthesis.json), [`pipeline-development-tasking`](../../recipes/pipeline-development-tasking.json), [`pipeline-checkpoint-continuation`](../../recipes/pipeline-checkpoint-continuation.json), [`pipeline-media-library`](../../recipes/pipeline-media-library.json), [`pipeline-room-swarm`](../../recipes/pipeline-room-swarm.json). For room swarms, choose `mode` from `consensus`, `pipeline`, `fanout`, or `pool`; prefer `roles_path` for custom role JSON and keep role `name` ASCII-safe for branch addresses. Use `locker=true` when the swarm needs a coordinator-locker-backed artifact lock and journal.
 
 ### Utilities
 
@@ -339,6 +339,7 @@ Keep the split clean: methodology chooses coordination shape; pi-actors supplies
 - Sending domain messages without checking `mailbox`.
 - Expecting current room messages to wake prompt-only subagents; use direct branch messages or a runner protocol for initiating work.
 - Reading only stdout and missing actor messages/artifacts.
+- Assuming every packaged message-controlled script is native-Windows-ready; core run control is platform-adapted, but Unix-tool scripts must be migrated recipe by recipe.
 - Baking local absolute paths into published docs or reusable recipes.
 - Creating recipes that perform external side effects without explicit operator gates.
 - Letting project insights live only in chat instead of updating BACKLOG/CHANGELOG/docs and, when agent behavior changes, the packaged skill or prompt guidance.

package/skills/swarm/SKILL.md

@@ -2,7 +2,7 @@
 name: swarm
 description: Subagent orchestration with scoped locks and quorum consensus. Use for multi-model review, parallel scoped work, delegated audit, and coordinated subagent execution.
 metadata:
-  version: 0.20.1
+  version: 0.21.0
 ---
 
 # Swarm