@llblab/pi-actors 0.16.3 → 0.17.0

package/lib/tools.ts

@@ -5,6 +5,7 @@
  */
 
 import * as ActorMessages from "./actor-messages.ts";
+import * as ActorRooms from "./actor-rooms.ts";
 import * as AsyncRuns from "./async-runs.ts";
 import * as CommandTemplates from "./command-templates.ts";
 import type { RegisteredTool } from "./config.ts";
@@ -192,6 +193,99 @@ function compactRunMessages(messages: AsyncRuns.RunOutboxEvent[]): string {
     .join("\n")}`;
 }
 
+function compactPreview(value: unknown, maxLength = 80): string | undefined {
+  if (value === undefined) return undefined;
+  const text =
+    typeof value === "string" ? value : JSON.stringify(value, undefined, 0);
+  const compact = text.replaceAll(/\s+/g, "_");
+  return compact.length > maxLength
+    ? `${compact.slice(0, Math.max(0, maxLength - 1))}…`
+    : compact;
+}
+
+function compactRoomPreviews(previews: ActorRooms.RoomMessagePreview[]): string {
+  if (previews.length === 0) return "\n(no room message previews)";
+  return `\n${previews
+    .map((preview) =>
+      [
+        `ts=${preview.timestamp}`,
+        preview.from ? `from=${preview.from}` : "",
+        `to=${preview.to}`,
+        `type=${preview.type}`,
+        preview.summary ? `summary=${compactPreview(preview.summary)}` : "",
+        preview.body_preview ? `body=${compactPreview(preview.body_preview)}` : "",
+      ]
+        .filter(Boolean)
+        .join(" "),
+    )
+    .join("\n")}`;
+}
+
+function compactRoomMessages(messages: ActorRooms.RoomTimelineEntry[]): string {
+  if (messages.length === 0) return "\n(no room messages)";
+  return `\n${messages
+    .map((message) =>
+      [
+        `ts=${message.received_at}`,
+        `from=${String(message.from ?? "<unknown>")}`,
+        `to=${message.to}`,
+        `type=${message.type}`,
+        `summary=${String(message.summary ?? "").replaceAll(/\s+/g, "_")}`,
+        compactPreview(message.body) ? `body=${compactPreview(message.body)}` : "",
+      ]
+        .filter(Boolean)
+        .join(" "),
+    )
+    .join("\n")}`;
+}
+
+function compactRoomContacts(contacts: ActorRooms.RoomContact[]): string {
+  if (contacts.length === 0) return "\n(no room contacts)";
+  return `\n${contacts
+    .map((contact) =>
+      [
+        `address=${contact.address}`,
+        contact.role !== undefined ? `role=${String(contact.role)}` : "",
+        contact.parent !== undefined ? `parent=${String(contact.parent)}` : "",
+        contact.caps !== undefined ? `caps=${Array.isArray(contact.caps) ? contact.caps.join(",") : String(contact.caps)}` : "",
+        contact.claim !== undefined ? `claim=${String(contact.claim).replaceAll(/\s+/g, "_")}` : "",
+        contact.status !== undefined ? `status=${String(contact.status)}` : "",
+      ]
+        .filter(Boolean)
+        .join(" "),
+    )
+    .join("\n")}`;
+}
+
+function compactRoomRoster(roster: Record<string, ActorRooms.RoomMember>): string {
+  const members = Object.values(roster);
+  if (members.length === 0) return "\n(no room members)";
+  return `\n${members
+    .map((member) =>
+      [
+        `address=${member.address}`,
+        `role=${String(member.role ?? "")}`,
+        member.parent !== undefined ? `parent=${String(member.parent)}` : "",
+        member.caps !== undefined ? `caps=${Array.isArray(member.caps) ? member.caps.join(",") : String(member.caps)}` : "",
+        member.claim !== undefined ? `claim=${String(member.claim).replaceAll(/\s+/g, "_")}` : "",
+        `status=${String(member.status ?? "")}`,
+        `last_seen=${member.last_seen}`,
+      ].join(" "),
+    )
+    .join("\n")}`;
+}
+
+function compactRoomStatus(status: ActorRooms.RoomStatus): string {
+  return `\nroom=${status.room} messages=${status.message_count} roster=${status.roster_count}${status.last_message_at ? ` last_message_at=${status.last_message_at}` : ""}${status.last_message_from ? ` last_from=${status.last_message_from}` : ""}${status.last_message_type ? ` last_type=${status.last_message_type}` : ""}${status.last_message_summary ? ` last_summary=${compactPreview(status.last_message_summary)}` : ""}`;
+}
+
+function compactCommunicationSnapshot(
+  snapshot: ActorRooms.ActorCommunicationSnapshot | undefined,
+): string {
+  if (!snapshot) return "\n(no communication snapshot)";
+  return `\nself=${snapshot.self} root=${snapshot.root} rooms=${snapshot.rooms.length} updated_at=${snapshot.updated_at}`;
+}
+
 function compactActorFiles(status: Record<string, unknown>): string {
   const run = String(status.run ?? "<unknown>");
   const artifacts = asRecord(status.artifacts);
@@ -200,6 +294,7 @@ function compactActorFiles(status: Record<string, unknown>): string {
     status.stderrLog,
     status.eventsFile,
     status.outboxFile,
+    status.state_dir ? `${String(status.state_dir)}/communication.json` : undefined,
     status.state_dir ? `${String(status.state_dir)}/result.json` : undefined,
   ].filter((file): file is string => typeof file === "string");
   const artifactText = Object.keys(artifacts).length
@@ -240,7 +335,10 @@ function compactRecipeRegistry(summary: Record<string, unknown>): string {
   const diagnostics = Array.isArray(summary.diagnostics)
     ? summary.diagnostics.length
     : 0;
-  return `\nrecipes active=${active} shadowed=${shadowed} invalid=${invalid} disabled=${disabled} diagnostics=${diagnostics}`;
+  const recommendations = Array.isArray(summary.recommendations)
+    ? summary.recommendations.length
+    : 0;
+  return `\nrecipes active=${active} shadowed=${shadowed} invalid=${invalid} disabled=${disabled} recommendations=${recommendations} diagnostics=${diagnostics}`;
 }
 
 function compactActorMessageResult(
@@ -255,6 +353,11 @@ function compactActorMessageResult(
   if (result.bytes !== undefined) tokens.push(`bytes=${String(result.bytes)}`);
   if (result.control) tokens.push(`control=${String(result.control)}`);
   if (result.outbox) tokens.push(`messages=${String(result.outbox)}`);
+  if (result.message_count !== undefined)
+    tokens.push(`messages=${String(result.message_count)}`);
+  if (result.roster_count !== undefined)
+    tokens.push(`roster=${String(result.roster_count)}`);
+  if (result.room) tokens.push(`room=${String(result.room)}`);
   if (result.tool) tokens.push(`tool=${String(result.tool)}`);
   if (result.stopped === true) tokens.push("stopped=true");
   if (result.signal) tokens.push(`signal=${String(result.signal)}`);
@@ -352,6 +455,25 @@ function runIdFromActorAddress(
   return parsed.value;
 }
 
+function assertMessageSenderBelongsToRun(
+  message: ActorMessages.ActorMessage,
+  run: string,
+  routeLabel: string,
+): void {
+  if (!message.from) {
+    throw new Error(`message to ${message.to} requires from=<actor address>.`);
+  }
+  const sender = ActorMessages.parseActorAddress(message.from);
+  if (
+    (sender.kind !== "run" && sender.kind !== "branch") ||
+    sender.value !== run
+  ) {
+    throw new Error(
+      `message to ${routeLabel} requires from=run:${run} or branch:${run}/<branch>; got ${message.from}.`,
+    );
+  }
+}
+
 export function createSpawnToolDefinition<
   TContext extends AsyncRunToolContext,
 >(): any {
@@ -422,6 +544,8 @@ export function createSpawnToolDefinition<
         },
         ctx.cwd,
       );
+      ActorRooms.ensureDefaultRoom(meta.state_dir, String(meta.run));
+      ActorRooms.writeCommunicationSnapshot(meta.state_dir, String(meta.run));
       return {
         content: [
           {
@@ -475,6 +599,10 @@ function assertRunAccessibleToContext(
   return status;
 }
 
+function assertRunExistsForActorMessage(runId: string): Record<string, unknown> {
+  return AsyncRuns.getRunStatus(runId);
+}
+
 export function createInspectToolDefinition<TContext = unknown>(
   deps: InspectToolDeps<TContext> = {},
 ): any {
@@ -482,7 +610,7 @@ export function createInspectToolDefinition<TContext = unknown>(
     name: "inspect",
     label: "Inspect",
     description:
-      "Intentionally inspect an actor. Supports run:<id> views: status, tail, messages, artifacts, files, mailbox; coordinator/session status; and tool:<name> status/schema.",
+      "Intentionally inspect an actor. Supports run:<id> views: status, tail, messages, artifacts, files, mailbox, communication; room:<run> status/messages/previews/roster/contacts; coordinator/session status; and tool:<name> status/schema.",
     parameters: objectSchema(
       {
         lines: stringSchema("Line count for tail/messages views. Default 40."),
@@ -490,13 +618,13 @@ export function createInspectToolDefinition<TContext = unknown>(
           "Optional session run filter: all, running, active, terminal, done, failed, cancelled, killed, or exited.",
         ),
         target: stringSchema(
-          "Actor address to inspect, e.g. run:<id>, coordinator, session:<id>, session:all, or tool:<name>.",
+          "Actor address to inspect, e.g. run:<id>, room:<run>, coordinator, session:<id>, session:all, or tool:<name>.",
         ),
         verbose: booleanSchema(
           "Return full JSON instead of compact text where available.",
         ),
         view: stringSchema(
-          "Inspection view: status, tail, messages, artifacts, files, or mailbox.",
+          "Inspection view: status, tail, messages, artifacts, files, mailbox, communication, roster, or contacts.",
         ),
       },
       ["target", "view"],
@@ -618,6 +746,100 @@ export function createInspectToolDefinition<TContext = unknown>(
           details,
         };
       }
+      if (address.kind === "room" && address.value && address.room) {
+        const status = assertRunAccessibleToContext(address.value, ctx);
+        const stateDir = String(status.state_dir ?? "");
+        if (!stateDir) throw new Error(`room:${address.value} has no run state directory.`);
+        if (view === "status") {
+          const status = ActorRooms.getRoomStatus(stateDir, address.room);
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: maybeJsonText(
+                  status,
+                  input.verbose === true,
+                  compactRoomStatus(status),
+                ),
+              },
+            ],
+            details: status,
+          };
+        }
+        if (view === "previews") {
+          const previews = ActorRooms.readRoomMessagePreviews(
+            stateDir,
+            address.room,
+            Number(input.lines || 40),
+          );
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: maybeJsonText(
+                  previews,
+                  input.verbose === true,
+                  compactRoomPreviews(previews),
+                ),
+              },
+            ],
+            details: { previews },
+          };
+        }
+        if (view === "messages") {
+          const messages = ActorRooms.readRoomMessages(
+            stateDir,
+            address.room,
+            Number(input.lines || 40),
+          );
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: maybeJsonText(
+                  messages,
+                  input.verbose === true,
+                  compactRoomMessages(messages),
+                ),
+              },
+            ],
+            details: { messages },
+          };
+        }
+        if (view === "contacts") {
+          const contacts = ActorRooms.readRoomContacts(stateDir, address.room);
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: maybeJsonText(
+                  contacts,
+                  input.verbose === true,
+                  compactRoomContacts(contacts),
+                ),
+              },
+            ],
+            details: { contacts },
+          };
+        }
+        if (view === "roster") {
+          const roster = ActorRooms.readRoomRoster(stateDir, address.room);
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: maybeJsonText(
+                  roster,
+                  input.verbose === true,
+                  compactRoomRoster(roster),
+                ),
+              },
+            ],
+            details: { roster },
+          };
+        }
+        throw new Error("inspect room:<run> supports view=status, view=messages, view=previews, view=roster, or view=contacts.");
+      }
       const runId = address.kind === "run" ? address.value : undefined;
       if (!runId)
         throw new Error(
@@ -702,9 +924,28 @@ export function createInspectToolDefinition<TContext = unknown>(
             details: { mailbox },
           };
         }
+        case "communication": {
+          const status = assertRunAccessibleToContext(runId, ctx);
+          const snapshot = ActorRooms.readCommunicationSnapshot(
+            String(status.state_dir ?? ""),
+          );
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: maybeJsonText(
+                  snapshot ?? {},
+                  input.verbose === true,
+                  compactCommunicationSnapshot(snapshot),
+                ),
+              },
+            ],
+            details: { communication: snapshot },
+          };
+        }
         default:
           throw new Error(
-            "inspect view must be one of: status, tail, messages, artifacts, files, mailbox.",
+            "inspect view must be one of: status, tail, messages, artifacts, files, mailbox, communication.",
           );
       }
     },
@@ -722,7 +963,7 @@ export function createActorMessageToolDefinition<TContext = unknown>(
     name: "message",
     label: "Message",
     description:
-      "Send one typed addressed message. Routes to run:<id> mailboxes, branch:<run>/<branch> mailboxes, tool:<name> calls, and coordinator/session-bound run messages.",
+      "Send one typed addressed message. Routes to run:<id> mailboxes, branch:<run>/<branch> mailboxes, room:<run> timelines/rosters, tool:<name> calls, and coordinator/session-bound run messages.",
     parameters: objectSchema(
       {
         body: unionSchema([
@@ -744,7 +985,7 @@ export function createActorMessageToolDefinition<TContext = unknown>(
         reply_to: stringSchema("Optional message id this message replies to."),
         summary: stringSchema("Optional short human-facing summary."),
         to: stringSchema(
-          "Destination actor address, e.g. run:<id>, branch:<run>/<branch>, coordinator, session:<id>, or tool:<name>.",
+          "Destination actor address, e.g. run:<id>, branch:<run>/<branch>, room:<run>, coordinator, session:<id>, or tool:<name>.",
         ),
         type: stringSchema(
           "Semantic message type, e.g. control.approve or checkpoint.needs_scope.",
@@ -780,11 +1021,51 @@ export function createActorMessageToolDefinition<TContext = unknown>(
           );
         }
       } else if (address.kind === "branch" && address.value) {
-        assertRunAccessibleToContext(address.value, ctx);
+        const runId = address.value;
+        if (message.from) assertMessageSenderBelongsToRun(message, runId, `branch:${runId}/<branch>`);
+        const status = message.from
+          ? assertRunExistsForActorMessage(runId)
+          : assertRunAccessibleToContext(runId, ctx);
+        const stateDir = String(status.state_dir ?? "");
+        if (stateDir && address.branch) {
+          const ensureBranchMember = (actorAddress: string) => {
+            ActorRooms.ensureRoomMember(
+              stateDir,
+              runId,
+              "main",
+              actorAddress,
+              {
+                parent: `run:${runId}`,
+                role: "branch",
+                status: "present",
+              },
+              "Branch joined default room",
+            );
+            ActorRooms.writeBranchCommunicationSnapshot(
+              stateDir,
+              runId,
+              actorAddress,
+            );
+          };
+          ensureBranchMember(message.to);
+          if (message.from) {
+            const sender = ActorMessages.parseActorAddress(message.from);
+            if (sender.kind === "branch" && sender.value === runId) {
+              ensureBranchMember(message.from);
+            }
+          }
+          ActorRooms.writeCommunicationSnapshot(stateDir, runId);
+        }
         result = AsyncRuns.sendRunMessage(
           address.value,
           JSON.stringify(message),
         );
+      } else if (address.kind === "room" && address.value && address.room) {
+        assertMessageSenderBelongsToRun(message, address.value, `room:${address.value}`);
+        const status = assertRunExistsForActorMessage(address.value);
+        const stateDir = String(status.state_dir ?? "");
+        if (!stateDir) throw new Error(`${message.to} has no run state directory.`);
+        result = { ...ActorRooms.appendRoomMessage(stateDir, address.room, message) };
       } else if (address.kind === "tool" && address.value) {
         const tool = deps.getTool?.(address.value);
         if (!tool || typeof tool.execute !== "function") {
@@ -842,7 +1123,7 @@ export function createActorMessageToolDefinition<TContext = unknown>(
         });
       } else {
         throw new Error(
-          `message currently supports run:<id>, branch:<run>/<branch>, tool:<name>, coordinator, and session:<id> destinations; unsupported destination: ${message.to}`,
+          `message currently supports run:<id>, branch:<run>/<branch>, room:<run>, tool:<name>, coordinator, and session:<id> destinations; unsupported destination: ${message.to}`,
         );
       }
       return {
@@ -942,6 +1223,8 @@ export function createRuntimeToolDefinition(
             },
             ctx.cwd,
           );
+          ActorRooms.ensureDefaultRoom(meta.state_dir, String(meta.run));
+          ActorRooms.writeCommunicationSnapshot(meta.state_dir, String(meta.run));
           return {
             content: [
               { type: "text" as const, text: compactAsyncRunStatus(meta) },

package/package.json

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

package/recipes/lens-swarm.json

@@ -1,7 +1,6 @@
 {
   "name": "lens-swarm",
   "description": "General-purpose multi-lens review swarm. Launches independent reviewers by lens, then verifies, merges, judges, and normalizes the result.",
-  "tool": true,
   "async": true,
   "imports": {
     "coordinator": "subagent-review-coordinator.json"

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.16.3
+  version: 0.17.0
 ---
 
 # Actors (pi-actors)
@@ -37,7 +37,8 @@ Trusted local capability
 
 - **Command template**: portable execution graph. String leaf, sequence array, or object node with controls.
 - **Recipe**: saved JSON definition wrapping a template with args, defaults, imports, mailbox, artifacts, metadata, and optional `async: true`.
-- **Run actor**: one detached execution instance addressable as `run:<id>` with status, logs, messages, mailbox metadata, files, and artifacts.
+- **Run actor**: one detached execution instance addressable as `run:<id>` with status, logs, messages, mailbox metadata, files, communication snapshot, and artifacts.
+- **Room actor**: shared timeline + roster endpoint addressable as `room:<run>`; every spawned run gets `room:<run>`.
 - **Tool actor**: registered persistent capability addressable as `tool:<name>` and callable through the generated tool or `message`.
 - **Coordinator/session**: the current pi session endpoint that receives bounded actor follow-ups.
 - **Mailbox**: public interaction contract: message types the actor accepts/emits.
@@ -80,7 +81,8 @@ Envelope fields:
 
 - Required: `to`, `type`.
 - Useful: `summary`, `body`, `from`, `reply_to`, `correlation_id`, `metadata`.
-- Addresses: `run:<id>`, `branch:<run>/<branch>`, `tool:<name>`, `coordinator`, `session:<id>`.
+- Addresses: `run:<id>`, `branch:<run>/<branch>`, `room:<run>`, `tool:<name>`, `coordinator`, `session:<id>`.
+- Room posts require `from` from the same run (`run:<run>` or `branch:<run>/<branch>`).
 - Standard termination messages: `control.stop`, `control.cancel`, `control.kill`.
 
 Check `inspect view=mailbox` before domain-specific messages.
@@ -91,7 +93,12 @@ Check `inspect view=mailbox` before domain-specific messages.
 { "target": "run:repo-health", "view": "status" }
 { "target": "run:repo-health", "view": "tail", "lines": "80" }
 { "target": "run:repo-health", "view": "messages" }
+{ "target": "run:repo-health", "view": "communication" }
 { "target": "run:repo-health", "view": "artifacts" }
+{ "target": "room:repo-health", "view": "status" }
+{ "target": "room:repo-health", "view": "roster" }
+{ "target": "room:repo-health", "view": "contacts" }
+{ "target": "room:repo-health", "view": "previews" }
 { "target": "tool:music_player", "view": "status" }
 { "target": "recipes", "view": "status" }
 { "target": "coordinator", "view": "status" }
@@ -101,7 +108,11 @@ Views:
 
 - `status`: lifecycle, pid, values, progress, result, compact summary.
 - `tail`: recent stdout/stderr/log tail.
-- `messages`: actor messages emitted by the run.
+- `messages`: actor messages emitted by the run, or room timeline entries for `room:*`.
+- `communication`: run/branch communication snapshot with self/root/default-room/member/contact hints.
+- `roster`: room member list with address, role, parent, caps, claim, status, and last seen.
+- `contacts`: roster-derived direct-message targets without full roster metadata.
+- `previews`: TUI-ready bounded room message previews with timestamp/from/to/type/summary/body_preview.
 - `mailbox`: declared accepts/emits contract.
 - `files`: run state directory file list.
 - `artifacts`: declared artifact paths/status.
@@ -109,6 +120,38 @@ Views:
 
 Let terminal notifications arrive; avoid sleep-poll loops except during diagnosis.
 
+## Stable Multi-Actor Review Rules
+
+- Prefer independent read-only reviewers for review swarms. Use shared room messages for coordination signals and observability, not for letting reviewers converge early, unless the task explicitly asks for collaborative discussion.
+- Treat inspector-visible communication logs as recipe-quality evidence. Verbose room/direct timelines show whether recipes coordinate clearly, emit useful summaries, over-chat, miss handoffs, choose poor message types, or need better mailbox/artifact conventions. Use `inspect room:<run> view=messages|previews`, `inspect run:<id> view=communication`, and the actor inspector compact/verbose modes to improve recipes after real runs.
+- Smoke-test provider/model availability before launching expensive fanout, or choose a provider known to be configured in this environment. A failed provider fanout creates noisy run transitions without useful review signal.
+- Keep one public communication model: `spawn` creates actors, `message` sends typed envelopes, and `inspect` observes. Avoid adding public side channels or storage nouns when a normal actor address/view can express the operation.
+- Keep route and semantic type separate. Direct, room, coordinator, and session messages may share `type`; delivery behavior comes from `to`.
+- Any UI, summary, or aggregate view that scans run directories must apply coordinator/session ownership filters before exposing summaries or body previews.
+- Treat `communication.json` as visible actor context, not a global mutable truth table. Run-level snapshots should identify the run actor; branch-local snapshots should identify the branch actor.
+- Prefer same-run provenance checks on lateral actor routes. If `from` is accepted for room or branch routes, validate that it belongs to the addressed run.
+
+## Persistent Backlog Implementers
+
+When using actors as backlog implementers, avoid one-shot subagents that exit after one task. Use long-lived branch actors and keep task selection with the coordinator:
+
+1. Coordinator assigns a concrete backlog slice with `task.assign`.
+2. Actor posts `task.claim` to `room:<run>` before editing.
+3. Actor executes and validates the slice.
+4. Actor posts `task.result` and `awaiting_assignment`.
+5. Actor stays alive until the coordinator sends another `task.assign` or an explicit `control.stop`.
+
+Use `front`/`back` actors for opposite backlog ends when reducing overlap. Implementer workflows should be packaged as reusable recipe composition, not bespoke scripts: use `coordinator-locker` for queue/assignment/locking, subagent launcher recipes for execution cells, and actor-message utility recipes for structured handoffs. If the existing recipe library cannot express the scenario, add missing reusable component recipes first, then compose the higher-level workflow from them. Supervisors should route coordinator assignments by `body.actor`, preserve the assignment as an object rather than a JSON string, and keep stopped-worker summaries tied to the original actor list.
+
+Current packaged building blocks:
+
+- `coordinator-locker`: long-lived queue/lock coordinator for assignment and resource ownership.
+- `subagent-prompt`, `subagent-tools`, `subagents-prompts`: execution launchers for one or many agent prompts.
+- `utility-actor-message`: deterministic actor-message envelope construction for handoffs/results.
+- `utility-run-ops-snapshot` and `pipeline-async-run-ops`: inspect live runs/messages before deciding the next assignment.
+
+The missing higher-level persistent backlog-implementer workflow is intentionally future work until it can be expressed from reusable recipe cells.
+
 ## Command Template Standard
 
 Forms:
@@ -180,11 +223,11 @@ Priority for same-name recipes:
 
 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.
 
-Muscle-memory lens: every recipe in `~/.pi/agent/recipes/*.json` becomes an easy-to-call tool by default. This is intentionally sticky: successful local patterns can quickly become durable agent muscle memory. The tradeoff is tool-surface clutter; accidental or one-off tools behave like persistent intrusive thoughts until an agent/operator focuses on cleanup.
+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.
 
-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 or `tool: false` 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.
+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.
 
-Cleanup rule: periodically inspect `~/.pi/agent/recipes` as the live muscle-memory set. For each stale, duplicate, too-specific, or low-value recipe, choose one explicit action: keep as a tool, set `tool: false` to retain recipe-only memory, merge into a better recipe, or delete/archive the file. Prefer demotion over deletion when the recipe may still be useful as a component. Never silently remove tools during unrelated work.
+Cleanup rule: periodically inspect `~/.pi/agent/recipes` as the live muscle-memory set. For each stale, duplicate, too-specific, or low-value recipe, choose one explicit action: keep as a tool, move it out of the agent recipe root to retain recipe-only memory, merge into a better recipe, or delete/archive the file. Prefer moving over deletion when the recipe may still be useful as a component. Never silently remove tools during unrelated work.
 
 ## Registered Tools
 
@@ -198,7 +241,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; packaged recipes are the lower-priority standard library and opt into tool exposure with `tool: true`. 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; 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
 

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.16.3
+  version: 0.17.0
 ---
 
 # Swarm