@llblab/pi-actors 0.18.0 → 0.19.0

package/AGENTS.md

@@ -52,6 +52,8 @@
 - `Release artifact hygiene`: PR/release summaries become stale during active branch work and do not belong in the repository documentation tree | Trigger: Preparing release notes or PR bodies | Action: Create temporary/operator-facing artifacts outside the repo only during explicit release finalization; keep durable release evidence in `CHANGELOG.md` and open gates in `BACKLOG.md`
 - `Graceful actor retirement`: Coordinator/helper actors that exist only to supervise a bounded worker tree should have explicit retirement semantics instead of relying on the operator or LLM to remember cleanup | Trigger: Designing coordinator recipes, helper actors, worker fanout, locker-backed swarms, or auto-stop behavior | Action: Make retirement opt-in through recipe/run metadata, retire only after observed child actors or descendant workers are terminal and outputs are flushed, prefer graceful control messages before process termination, record retirement events, and never infer retirement for persistent services or backlog implementers
 - `Persistent implementer workflows are recipe composition`: Backlog implementer scenarios should be launched through reusable component recipes, not one-off scripts or ad hoc shell orchestration | Trigger: Designing implementer swarms, backlog workers, coordinator-assigned task loops, or related recipes | Action: Compose cells such as `coordinator-locker`, subagent launchers, and actor-message utilities; preserve JSON envelope object shape across handoffs; add missing reusable component recipes only when needed; update the actors skill launcher map with supported scenarios
+- `Modular coordination and separate lock state`: The coordination of multi-agent workflows is split into two cleanly decoupled layers: the active coordinator and the stateful locker. The locker manages task queueing and resource lock leases over Unix FIFO/pipes without project policy. The coordinator script (`scripts/coordinator.mjs`) manages process pools, rooms, and lifecycles, and supports different pluggable mode strategies (`pipeline`, `fanout`, `pool`, `consensus`). | Trigger: Modifying coordination scripts, queues, locking, or parallel worker flows | Action: Keep the locker generic and thin, and implement all orchestration strategy rules inside the multi-mode coordinator.
+- `Active branch inbox queues`: Direct branch messages are active, work-triggering inbox queues rather than passive files. During subagent execution, the coordinator automatically claims (`claimed`), injects, and handles (`handled`/`failed`) queued branch-local direct messages to allow interactive/resumable worker workflows. | Trigger: Delivering branch messages, executing subagents, or updating branch queues | Action: Ensure direct messages can continue or wake long-lived branch runners, and keep the FIFO queue status transitions clean and fully tested.
 - `Recipe library growth is demand-driven`: Packaged recipes should grow from concrete repeated task patterns, not speculative scenario catalogs | Trigger: Adding packaged utilities, pipelines, or component recipes | Action: Prefer existing component composition, keep recipes policy-light with caller-owned prompts/models/paths/knobs, avoid scenario-specific scripts when existing components suffice, and document new reusable launch scenarios in the actors skill only after the recipe exists
 - `Context sync`: Meaningful implementation or docs changes must reconcile `BACKLOG.md`, `CHANGELOG.md`, README, and docs navigation | Trigger: Closing, narrowing, or discovering work | Action: Run the context validator before final status when practical
 - `Public path hygiene`: Published docs must not include machine-local absolute paths | Trigger: Adding validation commands, examples, or local instructions to README/AGENTS/docs/changelog | Action: Use `~/.pi/...`, `<repo>/...`, `${SKILL_DIR}/...`, or relative paths

package/BACKLOG.md

@@ -2,19 +2,6 @@
 
 ## Open Work
 
-### Direct Actor Inbox Queue Semantics
-
-- Priority: High.
-- Goal: Make direct actor-to-actor messages initiating work items, not passive files that the receiving actor may or may not inspect.
-- Direction:
-  - Deliver direct messages into the recipient actor's next prompt/context as soon as the branch runner can accept work.
-  - Keep the model simple: FIFO direct messages, no priority tiers unless real usage proves they are needed.
-  - Keep room messages as shared transcript only; a direct message may ask the recipient to inspect room history when broader context is needed.
-  - Wire branch runner protocols to claim/handle/fail messages from the current inspectable per-branch inbox files (`branches/<branch>/inbox.jsonl`, surfaced through `inspect branch:<run>/<branch> view=mailbox`); internal helpers can already transition queued messages to claimed/handled/failed for retries.
-- Exit:
-  - A direct branch message can wake or continue a long-lived branch runner without waiting for that runner to poll room files.
-  - Room transcript semantics remain unchanged and compatible with `room:<run>` inspection.
-
 ### Actor Rooms, Roster, and Cross-Branch Messaging
 
 - Priority: High.
@@ -78,7 +65,6 @@
   - A packaged workflow, if added, is described by recipes and existing helper cells; no one-off backlog-implementer scripts are required.
   - The actors skill documents the supported launch scenarios and the concrete packaged recipes for each.
 
-
 ### Branch-Local Checkpoint Semantics
 
 - Priority: Low.
@@ -114,4 +100,3 @@
 - Direction:
   - Consider sidecar stats sync/backup policy after inline user-owned `usage.calls` / `usage.last_called` proves useful.
   - Do not add failure counters as primary usefulness evidence unless there is a strong operator-facing need.
-

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.19.0: Modular Coordination And Active Mailboxes
+
+- `[Coordination]` Decoupled the overloaded `coordinator-locker.mjs` script into two completely independent, single-purpose components: a dedicated stateful `locker.mjs` (recipes `locker.json` and `coordinator-locker.json`) that manages resource locking, task queueing, and lease expirations; and a powerful, modular `coordinator.mjs` orchestrator. The coordinator manages execution lifecycles and process pools, supporting four distinct pluggable strategies via `--mode`: `consensus` (chat-swarm), `pipeline` (sequential), `fanout` (parallel review), and `pool` (worker pool pulling from locker).
+- `[Actor Messages]` Implemented active direct actor inbox queue semantics. The modular coordinator now automatically inspects, claims (`claimed`), injects into prompt context, and finalizes (`handled` or `failed`) any queued direct branch messages (`branches/<branch>/inbox.jsonl`) during subagent executions, making direct messages active initiating work items. Backed by complete regression test coverage.
+
 ## 0.18.0: Actor Runtime Hardening And Recipe Guardrails
 
 - `[Async Runs]` Made actor starts safer under concurrency and stale state. Duplicate active `run_id` / `state_dir` launches now fail before state is cleared, concurrent starts are serialized by a start lock, stale terminal run directories are cleaned automatically, and atomic JSON writes use collision-resistant temp names. Impact: restarts and concurrent launches no longer orphan active processes or overwrite logs, messages, progress, and control metadata.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "private": false,
   "description": "Actor runtime and orchestrator for agent-managed local processes",
   "keywords": [

package/recipes/coordinator-locker.json

@@ -41,5 +41,5 @@
     "locks": "{state_dir}/locks.json",
     "journal": "{state_dir}/journal.jsonl"
   },
-  "template": "{repo}/scripts/coordinator-locker.mjs serve --state-dir {state_dir} --lease-ms {lease_ms}"
+  "template": "{repo}/scripts/locker.mjs serve --state-dir {state_dir} --lease-ms {lease_ms}"
 }

package/recipes/locker.json

@@ -0,0 +1,45 @@
+{
+  "async": true,
+  "args": [
+    "repo:path",
+    "lease_ms:int"
+  ],
+  "defaults": {
+    "repo": "~/.pi/agent/extensions/pi-actors",
+    "lease_ms": "600000"
+  },
+  "mailbox": {
+    "accepts": [
+      "lock.enqueue",
+      "lock.claim",
+      "lock.complete",
+      "lock.fail",
+      "lock.acquire",
+      "lock.renew",
+      "lock.release",
+      "control.stop",
+      "control.cancel",
+      "control.kill"
+    ],
+    "emits": [
+      "lock.started",
+      "lock.enqueued",
+      "lock.assigned",
+      "lock.empty",
+      "lock.completed",
+      "lock.failed",
+      "lock.granted",
+      "lock.denied",
+      "lock.renewed",
+      "lock.released",
+      "run.done",
+      "run.failed"
+    ]
+  },
+  "artifacts": {
+    "queue": "{state_dir}/queue.json",
+    "locks": "{state_dir}/locks.json",
+    "journal": "{state_dir}/journal.jsonl"
+  },
+  "template": "{repo}/scripts/locker.mjs serve --state-dir {state_dir} --lease-ms {lease_ms}"
+}

package/recipes/pipeline-room-swarm.json

@@ -1,6 +1,7 @@
 {
   "async": true,
   "args": [
+    "mode:string",
     "mission:string",
     "model:string",
     "thinking:string",
@@ -14,6 +15,7 @@
     "repo:path"
   ],
   "defaults": {
+    "mode": "consensus",
     "thinking": "off",
     "roles": "",
     "roles_path": "",
@@ -44,5 +46,5 @@
       "run.failed"
     ]
   },
-  "template": "{repo}/scripts/room-swarm.mjs --run-id={run_id} --mission={mission} --model={model} --thinking={thinking} --roles={roles} --roles-path={roles_path} --rounds={rounds} --delay={delay} --locker={locker} --locker-lease-ms={locker_lease_ms} --artifact-path={artifact_path}"
+  "template": "{repo}/scripts/coordinator.mjs --run-id={run_id} --mode={mode} --mission={mission} --model={model} --thinking={thinking} --roles={roles} --roles-path={roles_path} --rounds={rounds} --delay={delay} --locker={locker} --locker-lease-ms={locker_lease_ms} --artifact-path={artifact_path}"
 }

package/scripts/coordinator.mjs

@@ -0,0 +1,434 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+
+function arg(name, fallback = "") {
+  const prefix = `--${name}=`;
+  const value = process.argv.find((item) => item.startsWith(prefix));
+  return value ? value.slice(prefix.length) : fallback;
+}
+
+function numberArg(name, fallback) {
+  const value = Number(arg(name, String(fallback)));
+  return Number.isFinite(value) && value >= 0 ? value : fallback;
+}
+
+function boolArg(name, fallback = false) {
+  const value = arg(name, String(fallback)).trim().toLowerCase();
+  return ["1", "true", "yes", "on"].includes(value);
+}
+
+function normalizeRoles(value) {
+  if (!Array.isArray(value)) throw new Error("roles must be an array");
+  return value.map((role, index) => ({
+    name: String(role.name ?? `actor-${index + 1}`),
+    persona: String(role.persona ?? role.role ?? "room participant"),
+  }));
+}
+
+function parseRoles(raw) {
+  if (!raw.trim()) return defaultRoles;
+  try {
+    return normalizeRoles(JSON.parse(raw));
+  } catch {
+    return raw.split(",").map((item, index) => ({
+      name: item.trim() || `actor-${index + 1}`,
+      persona: "room participant",
+    }));
+  }
+}
+
+async function loadRoles(raw, path) {
+  if (path.trim()) return normalizeRoles(JSON.parse(await readFile(path, "utf8")));
+  return parseRoles(raw);
+}
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+
+function agentDir() {
+  return process.env.PI_CODING_AGENT_DIR || `${process.env.HOME}/.pi/agent`;
+}
+
+function runStateDir(runId) {
+  return `${agentDir()}/tmp/pi-actors/runs/${runId}`;
+}
+
+async function sleep(ms) {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function waitForPath(path, timeoutMs = 5000) {
+  const started = Date.now();
+  while (!existsSync(path)) {
+    if (Date.now() - started > timeoutMs) throw new Error(`timed out waiting for ${path}`);
+    await sleep(50);
+  }
+}
+
+async function writeLockerMessage(locker, message) {
+  if (!locker) return;
+  await waitForPath(locker.controlPath);
+  await writeFile(locker.controlPath, `${JSON.stringify(message)}\n`, { flag: "a" });
+  await sleep(50);
+}
+
+async function startLocker(config) {
+  if (!config.locker) return undefined;
+  const lockerStateDir = `${runStateDir(config.runId)}/locker`;
+  await mkdir(lockerStateDir, { recursive: true });
+  const child = spawn(new URL("./locker.mjs", import.meta.url).pathname, [
+    "serve",
+    "--state-dir",
+    lockerStateDir,
+    "--lease-ms",
+    String(config.lockerLeaseMs),
+  ], {
+    env: { ...process.env, run_id: config.runId },
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  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);
+  await writeLockerMessage(locker, {
+    type: "lock.enqueue",
+    body: { id: "coordinator-artifact", task: "Own final artifact synthesis", resources: [config.artifactPath || "artifact"] },
+  });
+  return locker;
+}
+
+async function stopLocker(locker) {
+  if (!locker) return;
+  try {
+    await writeLockerMessage(locker, { type: "control.stop", body: {} });
+    await sleep(100);
+  } finally {
+    if (!locker.child.killed) locker.child.kill("SIGTERM");
+  }
+}
+
+function runPi(prompt, model, thinking) {
+  return new Promise((resolve) => {
+    const child = spawn("pi", [
+      "--model", model,
+      "--thinking", thinking,
+      "--tools", "inspect,message",
+      "--no-context-files",
+      "--no-skills",
+      "--no-session",
+      "-p",
+      prompt,
+    ], { stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => { stdout += chunk; });
+    child.stderr.on("data", (chunk) => { stderr += chunk; });
+    child.on("close", (code) => resolve({ code, stdout, stderr }));
+    child.on("error", (error) => resolve({ code: 1, stdout, stderr: String(error) }));
+  });
+}
+
+async function readRoomTranscript(config) {
+  const messagesPath = `${runStateDir(config.runId)}/rooms/main/messages.jsonl`;
+  try {
+    const raw = await readFile(messagesPath, "utf8");
+    return raw
+      .split("\n")
+      .filter(Boolean)
+      .slice(-160)
+      .map((line) => {
+        try {
+          const message = JSON.parse(line);
+          const from = String(message.from || "unknown").replace(/^branch:[^/]+\//, "");
+          const type = String(message.type || "message");
+          const body = typeof message.body === "string" ? message.body : JSON.stringify(message.body ?? "");
+          return `${from} [${type}]: ${body}`;
+        } catch {
+          return line;
+        }
+      })
+      .join("\n");
+  } catch {
+    return "";
+  }
+}
+
+async function synthesize(config, locker) {
+  if (!config.artifactPath) return;
+  if (locker) {
+    await writeLockerMessage(locker, {
+      type: "lock.claim",
+      body: { owner: "coordinator:synthesizer" },
+    });
+  }
+  const transcript = await readRoomTranscript(config);
+  const prompt = `Synthesize this transcript into a concise Markdown artifact. Mission: ${config.mission}. Include: Title, Consensus, Roles, Protocol, Final Artifact Shape, Next Actions, Open Questions. Use only the transcript evidence below.\n\nTRANSCRIPT:\n${transcript.slice(-24000)}`;
+  const result = await runPi(prompt, config.model, config.thinking);
+  await writeFile(config.artifactPath, result.stdout.trim() ? result.stdout : "# Synthesis Artifact\n\nNo synthesis output.\n", "utf8");
+  if (locker) {
+    await writeLockerMessage(locker, {
+      type: "lock.complete",
+      body: { id: "coordinator-artifact", artifact: config.artifactPath },
+    });
+    await writeLockerMessage(locker, {
+      type: "lock.release",
+      body: { resource: config.artifactPath },
+    });
+  }
+  process.stdout.write(`artifact=${config.artifactPath}\n`);
+}
+
+async function updateInboxMessagesStatus(runId, branchName, ids, status) {
+  const inboxPath = `${runStateDir(runId)}/branches/${branchName}/inbox.jsonl`;
+  try {
+    if (!existsSync(inboxPath)) return;
+    const content = await readFile(inboxPath, "utf8");
+    const lines = content.split("\n").filter(Boolean);
+    const updatedLines = [];
+    for (const line of lines) {
+      const msg = JSON.parse(line);
+      if (msg.id && ids.includes(msg.id)) {
+        msg.status = status;
+        msg[`${status}_at`] = new Date().toISOString();
+      }
+      updatedLines.push(JSON.stringify(msg));
+    }
+    await writeFile(inboxPath, updatedLines.join("\n") + "\n", "utf8");
+  } catch (err) {
+    // Best-effort write
+  }
+}
+
+async function executeParticipantPrompt(role, basePrompt, config) {
+  const branchName = role.name;
+  const inboxPath = `${runStateDir(config.runId)}/branches/${branchName}/inbox.jsonl`;
+  const queuedMessages = [];
+  
+  try {
+    if (existsSync(inboxPath)) {
+      const content = await readFile(inboxPath, "utf8");
+      const lines = content.split("\n").filter(Boolean);
+      for (const line of lines) {
+        const msg = JSON.parse(line);
+        if (msg.status === "queued" || !msg.status) {
+          queuedMessages.push(msg);
+        }
+      }
+    }
+  } catch (err) {
+    // Best-effort read
+  }
+
+  let finalPrompt = basePrompt;
+  const claimedIds = [];
+
+  if (queuedMessages.length > 0) {
+    let inboxSection = "\n\nDIRECT INBOX MESSAGES FOR YOU (FIFO queue):\n";
+    for (const msg of queuedMessages) {
+      const bodyText = typeof msg.body === "string" ? msg.body : JSON.stringify(msg.body ?? "");
+      inboxSection += `- From: ${msg.from || "unknown"} (Type: ${msg.type || "message"})\n  Body: ${bodyText}\n`;
+      if (msg.id) claimedIds.push(msg.id);
+    }
+    inboxSection += "\nPlease acknowledge and address these direct messages in your response.\n";
+    finalPrompt += inboxSection;
+
+    if (claimedIds.length > 0) {
+      await updateInboxMessagesStatus(config.runId, branchName, claimedIds, "claimed");
+    }
+  }
+
+  const result = await runPi(finalPrompt, config.model, config.thinking);
+
+  if (claimedIds.length > 0) {
+    const finalStatus = result.code === 0 ? "handled" : "failed";
+    await updateInboxMessagesStatus(config.runId, branchName, claimedIds, finalStatus);
+  }
+
+  return result;
+}
+
+async function participantRound(role, round, config) {
+  const displayName = role.name;
+  const address = `branch:${config.runId}/${role.name}`;
+  const prompt = `You are ${displayName} (${address}), ${role.persona}. Mission: ${config.mission}. Round ${round}/${config.rounds}. First call inspect target=${config.room} view=previews lines=30 and inspect target=${config.room} view=contacts. Then call message once to ${config.room} from ${address} type=chat.message. Body: 2-4 sentences that react to a named participant, propose the next coordination step, and refine the shared artifact. Use contacts for peer names and addresses. End stdout with summary <=160 chars.`;
+  const result = await executeParticipantPrompt(role, prompt, config);
+  process.stdout.write(`[${role.name} round ${round}] code=${result.code}\n${result.stdout}\n`);
+  if (result.stderr.trim()) process.stderr.write(`[${role.name} round ${round}] ${result.stderr}\n`);
+}
+
+async function participantJoin(role, config) {
+  const displayName = role.name;
+  const address = `branch:${config.runId}/${role.name}`;
+  const joinPrompt = `You are ${displayName}, ${role.persona}. Mission: ${config.mission}. Call tool message exactly once with to=${shellQuote(config.room)}, from=${shellQuote(address)}, type='actor.join', summary='${displayName} joined', body JSON {"role":${JSON.stringify(role.persona)},"display":${JSON.stringify(displayName)},"caps":["coordination","synthesis"],"claim":"coordinate on mission"}. Then print one short line.`;
+  await runPi(joinPrompt, config.model, config.thinking);
+}
+
+async function participantLeave(role, config) {
+  const displayName = role.name;
+  const address = `branch:${config.runId}/${role.name}`;
+  const leavePrompt = `Call tool message exactly once with to=${shellQuote(config.room)}, from=${shellQuote(address)}, type='actor.leave', summary='${displayName} left', body='finished coordinated work'. Then print goodbye.`;
+  await runPi(leavePrompt, config.model, config.thinking);
+}
+
+// 1. consensus / swarm mode: iterative chat in a room
+async function runConsensus(config, locker) {
+  await Promise.all(config.roles.map((role) => participantJoin(role, config)));
+  for (let round = 1; round <= config.rounds; round += 1) {
+    await Promise.all(config.roles.map((role) => participantRound(role, round, config)));
+    if (round < config.rounds && config.delay > 0) await sleep(config.delay * 1000);
+  }
+  await Promise.all(config.roles.map((role) => participantLeave(role, config)));
+}
+
+// 2. pipeline mode: sequential step-by-step
+async function runPipeline(config, locker) {
+  for (const role of config.roles) {
+    await participantJoin(role, config);
+    for (let round = 1; round <= config.rounds; round += 1) {
+      await participantRound(role, round, config);
+      if (round < config.rounds && config.delay > 0) await sleep(config.delay * 1000);
+    }
+    await participantLeave(role, config);
+  }
+}
+
+// 3. fanout mode: run completely parallel independent processes
+async function runFanout(config, locker) {
+  await Promise.all(config.roles.map(async (role) => {
+    await participantJoin(role, config);
+    for (let round = 1; round <= config.rounds; round += 1) {
+      await participantRound(role, round, config);
+      if (round < config.rounds && config.delay > 0) await sleep(config.delay * 1000);
+    }
+    await participantLeave(role, config);
+  }));
+}
+
+// 4. pool mode: dynamic task pulling from the locker queue
+async function runPool(config, locker) {
+  if (!locker) {
+    throw new Error("Pool mode requires locker enabled (--locker=true)");
+  }
+  // Enqueue a set of sub-tasks based on the mission splits (for demo/simulation, we enqueue 3 sub-tasks)
+  for (let index = 1; index <= 3; index += 1) {
+    await writeLockerMessage(locker, {
+      type: "lock.enqueue",
+      body: { id: `subtask-${index}`, task: `Execute subtask ${index} under mission: ${config.mission}`, resources: [`resource-${index}`] },
+    });
+  }
+
+  // Workers concurrently poll task queue
+  await Promise.all(config.roles.map(async (role) => {
+    const address = `branch:${config.runId}/${role.name}`;
+    await participantJoin(role, config);
+    
+    while (true) {
+      // Dequeue/Claim a task from the locker
+      await writeLockerMessage(locker, {
+        type: "lock.claim",
+        body: { owner: role.name },
+      });
+      await sleep(100);
+
+      // Check locks and queue state from locker snapshot
+      const lockerData = await readJsonFile(`${locker.stateDir}/locks.json`);
+      const assignedTask = Object.values(lockerData).find(lock => lock.owner === role.name);
+      
+      if (!assignedTask) {
+        // No task assigned or queue is empty
+        break;
+      }
+
+      const taskId = assignedTask.task;
+      const prompt = `You are ${role.name}, ${role.persona}. You have been assigned task ${taskId}: "${assignedTask.task}". Solve it as part of the overall mission: ${config.mission}. End your response with a clear summary.`;
+      const result = await executeParticipantPrompt(role, prompt, config);
+      
+      process.stdout.write(`[${role.name} completed ${taskId}] code=${result.code}\n${result.stdout}\n`);
+
+      // Report task completion back to locker and release resource locks
+      await writeLockerMessage(locker, {
+        type: "lock.complete",
+        body: { id: taskId, result: result.stdout },
+      });
+      // Release any locks associated with this resource
+      for (const [res, lock] of Object.entries(lockerData)) {
+        if (lock.owner === role.name) {
+          await writeLockerMessage(locker, {
+            type: "lock.release",
+            body: { resource: res },
+          });
+        }
+      }
+    }
+
+    await participantLeave(role, config);
+  }));
+}
+
+async function readJsonFile(path) {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+const defaultRoles = [
+  { name: "mapper", persona: "systems mapper; tracks shared structure and dependencies" },
+  { name: "memory", persona: "memory keeper; preserves decisions and unresolved questions" },
+  { name: "risk", persona: "risk scout; challenges weak coordination and missing owners" },
+  { name: "flow", persona: "flow designer; turns scattered ideas into process rhythm" },
+  { name: "operator", persona: "operator; converts ideas into concrete next actions" },
+  { name: "narrative", persona: "narrative synthesizer; keeps the artifact coherent" },
+  { name: "interface", persona: "interface designer; makes outputs visible and usable" },
+  { name: "facilitator", persona: "facilitator; asks for consensus and convergence" },
+];
+
+const config = {
+  runId: arg("run-id", process.env.run_id || process.env.RUN_ID || "coordinator-run"),
+  mode: arg("mode", "consensus"), // "consensus" (default/swarm), "pipeline", "fanout", "pool"
+  mission: arg("mission", "Coordinate a shared artifact and converge on next actions"),
+  model: arg("model", ""),
+  thinking: arg("thinking", "off"),
+  roles: await loadRoles(arg("roles", ""), arg("roles-path", "")),
+  rounds: numberArg("rounds", 4),
+  delay: numberArg("delay", 10),
+  artifactPath: arg("artifact-path", ""),
+  locker: boolArg("locker", false),
+  lockerLeaseMs: numberArg("locker-lease-ms", 600000),
+};
+
+if (!config.model) {
+  console.error("--model is required");
+  process.exit(2);
+}
+config.room = `room:${config.runId}`;
+
+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);
+  }
+  await synthesize(config, locker);
+} catch (globalError) {
+  failures.push(`Global coordinator error: ${globalError.message}`);
+} finally {
+  await stopLocker(locker);
+}
+
+if (failures.length > 0) {
+  console.error(failures.join("\n"));
+  process.exit(1);
+}

package/scripts/{coordinator-locker.mjs → locker.mjs}

@@ -58,7 +58,7 @@ function journal(event, data = {}) {
 function outbox(type, summary, body = {}, level = "info") {
   appendFileSync(
     outboxPath,
-    `${JSON.stringify({ to: "coordinator", from: `run:${process.env.run_id ?? "coordinator-locker"}`, type, event: type, summary, body, data: body, delivery: "followup", level, ts: new Date().toISOString() })}\n`,
+    `${JSON.stringify({ to: "coordinator", from: `run:${process.env.run_id ?? "locker"}`, type, event: type, summary, body, data: body, delivery: "followup", level, ts: new Date().toISOString() })}\n`,
   );
 }
 function now() {
@@ -82,7 +82,7 @@ function normalizeMessage(line) {
   try {
     return JSON.parse(trimmed);
   } catch {
-    return { type: "coord.enqueue", body: { task: trimmed } };
+    return { type: "lock.enqueue", body: { task: trimmed } };
   }
 }
 function tailJournal(count) {
@@ -127,7 +127,7 @@ function nextTask(queue, locks) {
   return items.splice(index, 1)[0];
 }
 function handle(message) {
-  const type = message.type || message.event || "coord.enqueue";
+  const type = message.type || message.event || "lock.enqueue";
   const body =
     message.body && typeof message.body === "object" ? message.body : message;
   let queue = readJson(queuePath, { items: [] });
@@ -135,12 +135,12 @@ function handle(message) {
   if (type === "control.stop" || type === "control.cancel") {
     writeJson(locksPath, locks);
     journal("control.stop", {});
-    outbox("coord.stopped", "Coordinator locker stopped", {
+    outbox("lock.stopped", "Locker stopped", {
       queueDepth: queue.items?.length ?? 0,
     });
     process.exit(0);
   }
-  if (type === "coord.enqueue") {
+  if (type === "lock.enqueue" || type === "coord.enqueue") {
     const item = {
       id: body.id || `task-${Date.now()}`,
       task: body.task ?? body,
@@ -150,20 +150,20 @@ function handle(message) {
     queue.items = [...(queue.items ?? []), item];
     writeJson(queuePath, queue);
     writeJson(locksPath, locks);
-    journal("coord.enqueued", { id: item.id, resources: item.resources });
-    outbox("coord.enqueued", `Queued ${item.id}`, {
+    journal("lock.enqueued", { id: item.id, resources: item.resources });
+    outbox("lock.enqueued", `Queued task ${item.id}`, {
       id: item.id,
       queueDepth: queue.items.length,
     });
     return;
   }
-  if (type === "coord.claim") {
+  if (type === "lock.claim" || type === "coord.claim") {
     const owner = body.owner || message.from || "worker";
     const item = nextTask(queue, locks);
     if (!item) {
       writeJson(queuePath, queue);
       writeJson(locksPath, locks);
-      outbox("coord.empty", "No claimable task", {
+      outbox("lock.empty", "No claimable task", {
         owner,
         queueDepth: queue.items?.length ?? 0,
       });
@@ -173,12 +173,12 @@ function handle(message) {
       locks[resource] = { owner, task: item.id, expiresAt: now() + leaseMs };
     writeJson(queuePath, queue);
     writeJson(locksPath, locks);
-    journal("coord.assigned", {
+    journal("lock.assigned", {
       id: item.id,
       owner,
       resources: item.resources,
     });
-    outbox("coord.assigned", `Assigned ${item.id}`, { owner, task: item });
+    outbox("lock.assigned", `Assigned task ${item.id}`, { owner, task: item });
     return;
   }
   if (type === "lock.acquire") {
@@ -222,20 +222,21 @@ function handle(message) {
     outbox("lock.released", `Lock released ${resource}`, { resource });
     return;
   }
-  if (type === "coord.complete" || type === "coord.fail") {
-    journal(type, body);
+  if (type === "lock.complete" || type === "lock.fail" || type === "coord.complete" || type === "coord.fail") {
+    const eventType = type.startsWith("coord.") ? type.replace("coord.", "lock.") : type;
+    journal(eventType, body);
     outbox(
-      type,
-      `${type} ${body.id ?? ""}`.trim(),
+      eventType,
+      `${eventType} ${body.id ?? ""}`.trim(),
       body,
-      type === "coord.fail" ? "error" : "info",
+      eventType === "lock.fail" ? "error" : "info",
     );
     writeJson(locksPath, locks);
     writeJson(queuePath, queue);
     return;
   }
-  journal("coord.unknown", { type, body });
-  outbox("coord.unknown", `Unknown message ${type}`, { type, body }, "warning");
+  journal("lock.unknown", { type, body });
+  outbox("lock.unknown", `Unknown message ${type}`, { type, body }, "warning");
 }
 
 if (mode === "snapshot") {
@@ -250,8 +251,8 @@ if (!existsSync(controlPath)) {
 }
 writeJson(queuePath, readJson(queuePath, { items: [] }));
 writeJson(locksPath, cleanExpiredLocks(readJson(locksPath, {})));
-journal("coord.started", { leaseMs });
-outbox("coord.started", "Coordinator locker ready", { leaseMs });
+journal("lock.started", { leaseMs });
+outbox("lock.started", "Locker ready", { leaseMs });
 
 while (true) {
   const stream = await import("node:fs").then((fs) =>
@@ -265,8 +266,8 @@ while (true) {
       handle(message);
     } catch (error) {
       const text = error instanceof Error ? error.message : String(error);
-      journal("coord.error", { error: text });
-      outbox("coord.error", text, { error: text }, "error");
+      journal("lock.error", { error: text });
+      outbox("lock.error", text, { error: text }, "error");
     }
   }
 }

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.18.0
+  version: 0.19.0
 ---
 
 # Actors (pi-actors)
@@ -257,6 +257,7 @@ 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.
 - [`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.
 

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.18.0
+  version: 0.19.0
 ---
 
 # Swarm

package/scripts/room-swarm.mjs

@@ -1,243 +0,0 @@
-#!/usr/bin/env node
-import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-
-function arg(name, fallback = "") {
-  const prefix = `--${name}=`;
-  const value = process.argv.find((item) => item.startsWith(prefix));
-  return value ? value.slice(prefix.length) : fallback;
-}
-
-function numberArg(name, fallback) {
-  const value = Number(arg(name, String(fallback)));
-  return Number.isFinite(value) && value >= 0 ? value : fallback;
-}
-
-function boolArg(name, fallback = false) {
-  const value = arg(name, String(fallback)).trim().toLowerCase();
-  return ["1", "true", "yes", "on"].includes(value);
-}
-
-function normalizeRoles(value) {
-  if (!Array.isArray(value)) throw new Error("roles must be an array");
-  return value.map((role, index) => ({
-    name: String(role.name ?? `actor-${index + 1}`),
-    persona: String(role.persona ?? role.role ?? "room participant"),
-  }));
-}
-
-function parseRoles(raw) {
-  if (!raw.trim()) return defaultRoles;
-  try {
-    return normalizeRoles(JSON.parse(raw));
-  } catch {
-    return raw.split(",").map((item, index) => ({
-      name: item.trim() || `actor-${index + 1}`,
-      persona: "room participant",
-    }));
-  }
-}
-
-async function loadRoles(raw, path) {
-  if (path.trim()) return normalizeRoles(JSON.parse(await readFile(path, "utf8")));
-  return parseRoles(raw);
-}
-
-function shellQuote(value) {
-  return `'${String(value).replaceAll("'", "'\\''")}'`;
-}
-
-function agentDir() {
-  return process.env.PI_CODING_AGENT_DIR || `${process.env.HOME}/.pi/agent`;
-}
-
-function runStateDir(runId) {
-  return `${agentDir()}/tmp/pi-actors/runs/${runId}`;
-}
-
-async function sleep(ms) {
-  await new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-async function waitForPath(path, timeoutMs = 5000) {
-  const started = Date.now();
-  while (!existsSync(path)) {
-    if (Date.now() - started > timeoutMs) throw new Error(`timed out waiting for ${path}`);
-    await sleep(50);
-  }
-}
-
-async function writeLockerMessage(locker, message) {
-  if (!locker) return;
-  await waitForPath(locker.controlPath);
-  await writeFile(locker.controlPath, `${JSON.stringify(message)}\n`, { flag: "a" });
-  await sleep(50);
-}
-
-async function startLocker(config) {
-  if (!config.locker) return undefined;
-  const lockerStateDir = `${runStateDir(config.runId)}/locker`;
-  await mkdir(lockerStateDir, { recursive: true });
-  const child = spawn(new URL("./coordinator-locker.mjs", import.meta.url).pathname, [
-    "serve",
-    "--state-dir",
-    lockerStateDir,
-    "--lease-ms",
-    String(config.lockerLeaseMs),
-  ], {
-    env: { ...process.env, run_id: config.runId },
-    stdio: ["ignore", "pipe", "pipe"],
-  });
-  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);
-  await writeLockerMessage(locker, {
-    type: "coord.enqueue",
-    body: { id: "room-swarm-artifact", task: "Own final room-swarm artifact synthesis", resources: [config.artifactPath || "artifact"] },
-  });
-  return locker;
-}
-
-async function stopLocker(locker) {
-  if (!locker) return;
-  try {
-    await writeLockerMessage(locker, { type: "control.stop", body: {} });
-    await sleep(100);
-  } finally {
-    if (!locker.child.killed) locker.child.kill("SIGTERM");
-  }
-}
-
-function runPi(prompt, model, thinking) {
-  return new Promise((resolve) => {
-    const child = spawn("pi", [
-      "--model", model,
-      "--thinking", thinking,
-      "--tools", "inspect,message",
-      "--no-context-files",
-      "--no-skills",
-      "--no-session",
-      "-p",
-      prompt,
-    ], { stdio: ["ignore", "pipe", "pipe"] });
-    let stdout = "";
-    let stderr = "";
-    child.stdout.on("data", (chunk) => { stdout += chunk; });
-    child.stderr.on("data", (chunk) => { stderr += chunk; });
-    child.on("close", (code) => resolve({ code, stdout, stderr }));
-    child.on("error", (error) => resolve({ code: 1, stdout, stderr: String(error) }));
-  });
-}
-
-async function participant(role, config) {
-  const displayName = role.name;
-  const address = `branch:${config.runId}/${role.name}`;
-  const joinPrompt = `You are ${displayName}, ${role.persona}. Mission: ${config.mission}. Call tool message exactly once with to=${shellQuote(config.room)}, from=${shellQuote(address)}, type='actor.join', summary='${displayName} joined', body JSON {"role":${JSON.stringify(role.persona)},"display":${JSON.stringify(displayName)},"caps":["coordination","synthesis"],"claim":"coordinate on mission"}. Then print one short line.`;
-  await runPi(joinPrompt, config.model, config.thinking);
-  for (let round = 1; round <= config.rounds; round += 1) {
-    const prompt = `You are ${displayName} (${address}), ${role.persona}. Mission: ${config.mission}. Round ${round}/${config.rounds}. First call inspect target=${config.room} view=previews lines=30 and inspect target=${config.room} view=contacts. Then call message once to ${config.room} from ${address} type=chat.message. Body: 2-4 sentences that react to a named participant, propose the next coordination step, and refine the shared artifact. Use contacts for peer names and addresses, but keep this packaged swarm's coordination room-visible; do not send direct branch messages unless a caller-specific worker protocol says recipients consume them. End stdout with summary <=160 chars.`;
-    const result = await runPi(prompt, config.model, config.thinking);
-    process.stdout.write(`[${role.name} round ${round}] code=${result.code}\n${result.stdout}\n`);
-    if (result.stderr.trim()) process.stderr.write(`[${role.name} round ${round}] ${result.stderr}\n`);
-    if (round < config.rounds && config.delay > 0) await new Promise((resolve) => setTimeout(resolve, config.delay * 1000));
-  }
-  const leavePrompt = `Call tool message exactly once with to=${shellQuote(config.room)}, from=${shellQuote(address)}, type='actor.leave', summary='${displayName} left', body='finished coordinated work'. Then print goodbye.`;
-  await runPi(leavePrompt, config.model, config.thinking);
-}
-
-async function readRoomTranscript(config) {
-  const messagesPath = `${agentDir()}/tmp/pi-actors/runs/${config.runId}/rooms/main/messages.jsonl`;
-  try {
-    const raw = await readFile(messagesPath, "utf8");
-    return raw
-      .split("\n")
-      .filter(Boolean)
-      .slice(-160)
-      .map((line) => {
-        try {
-          const message = JSON.parse(line);
-          const from = String(message.from || "unknown").replace(/^branch:[^/]+\//, "");
-          const type = String(message.type || "message");
-          const body = typeof message.body === "string" ? message.body : JSON.stringify(message.body ?? "");
-          return `${from} [${type}]: ${body}`;
-        } catch {
-          return line;
-        }
-      })
-      .join("\n");
-  } catch {
-    return "";
-  }
-}
-
-async function synthesize(config, locker) {
-  if (!config.artifactPath) return;
-  await writeLockerMessage(locker, {
-    type: "coord.claim",
-    body: { owner: "room-swarm:synthesizer" },
-  });
-  const transcript = await readRoomTranscript(config);
-  const prompt = `Synthesize this room-swarm transcript into a concise Markdown artifact. Mission: ${config.mission}. Include: Title, Consensus, Roles, Protocol, Final Artifact Shape, Next Actions, Open Questions. Use only the transcript evidence below.\n\nTRANSCRIPT:\n${transcript.slice(-24000)}`;
-  const result = await runPi(prompt, config.model, config.thinking);
-  await writeFile(config.artifactPath, result.stdout.trim() ? result.stdout : "# Room Swarm Artifact\n\nNo synthesis output.\n", "utf8");
-  await writeLockerMessage(locker, {
-    type: "coord.complete",
-    body: { id: "room-swarm-artifact", artifact: config.artifactPath },
-  });
-  await writeLockerMessage(locker, {
-    type: "lock.release",
-    body: { resource: config.artifactPath },
-  });
-  process.stdout.write(`artifact=${config.artifactPath}\n`);
-}
-
-const defaultRoles = [
-  { name: "mapper", persona: "systems mapper; tracks shared structure and dependencies" },
-  { name: "memory", persona: "memory keeper; preserves decisions and unresolved questions" },
-  { name: "risk", persona: "risk scout; challenges weak coordination and missing owners" },
-  { name: "flow", persona: "flow designer; turns scattered ideas into process rhythm" },
-  { name: "operator", persona: "operator; converts ideas into concrete next actions" },
-  { name: "narrative", persona: "narrative synthesizer; keeps the artifact coherent" },
-  { name: "interface", persona: "interface designer; makes outputs visible and usable" },
-  { name: "facilitator", persona: "facilitator; asks for consensus and convergence" },
-];
-
-const config = {
-  runId: arg("run-id", process.env.run_id || process.env.RUN_ID || "room-swarm"),
-  mission: arg("mission", "Coordinate a shared artifact and converge on next actions"),
-  model: arg("model", ""),
-  thinking: arg("thinking", "off"),
-  roles: await loadRoles(arg("roles", ""), arg("roles-path", "")),
-  rounds: numberArg("rounds", 4),
-  delay: numberArg("delay", 10),
-  artifactPath: arg("artifact-path", ""),
-  locker: boolArg("locker", false),
-  lockerLeaseMs: numberArg("locker-lease-ms", 600000),
-};
-
-if (!config.model) {
-  console.error("--model is required");
-  process.exit(2);
-}
-config.room = `room:${config.runId}`;
-
-const failures = [];
-const locker = await startLocker(config);
-try {
-  await Promise.all(config.roles.map(async (role) => {
-    try {
-      await participant(role, config);
-    } catch (error) {
-      failures.push(`${role.name}: ${error instanceof Error ? error.message : String(error)}`);
-    }
-  }));
-  await synthesize(config, locker);
-} finally {
-  await stopLocker(locker);
-}
-if (failures.length > 0) {
-  console.error(failures.join("\n"));
-  process.exit(1);
-}