@llblab/pi-actors 0.24.0 → 0.24.2

package/AGENTS.md

@@ -33,7 +33,7 @@ Treat this extension as an experimental self-evolution membrane for the agent ha
 ## Repo Surfaces
 
 - `/scripts/*.mjs`: Stable executable shims for detached/helper processes.
-- `/lib/*.ts`: Compiled domain and script-entrypoint logic. Keep `scripts/*.mjs` lightweight and move substantive behavior into named domain modules so `dist/lib` is the JS-only runtime surface. This intentionally grows a standard library: script-born behavior should gain a clear domain name when reuse is plausible. Exception: self-contained application scripts with no expected second consumer, such as `music-player.mjs`, may remain standalone `.mjs` files.
+- `/lib/*.ts`: Compiled domain and script-entrypoint logic. Keep `scripts/*.mjs` lightweight and move substantive behavior into named domain modules so `dist/lib` is the JS-only runtime surface. This intentionally grows a standard library: script-born behavior should gain a clear domain name when reuse is plausible. Exception: self-contained application/build scripts with no expected second consumer, such as `music-player.mjs` or `build-dist.mjs`, may remain standalone `.mjs` files.
 - `/recipes/*.json`: Packaged standard recipe library. Keep recipes optional, composable, policy-light, and caller-configurable.
 - `/skills/actors/SKILL.md`: Dense practical reference for operating pi-actors itself.
 - `/skills/swarm/SKILL.md`: Bundled methodology skill for multi-agent standards, strategies, and portable examples.

package/BACKLOG.md

@@ -162,6 +162,71 @@ The backlog is intentionally pruned to the 20% of work most likely to deliver 80
   - `npm run pack:dry` includes expected compiled/script files.
   - Recipe paths remain stable or migrations are explicitly documented.
 
+### M-08 Recipe Doctor Remediation UX
+
+- Priority: High.
+- Status: Open.
+- Goal: Turn recipe doctor output into an operator action surface, not just a diagnostic listing.
+- Why now: Recipe registry warnings are intentionally actionable; the next value is helping operators decide whether to fix, disable, delete, or inspect a recipe without hiding the warning.
+- Direction:
+  - Summarize invalid, blocking, shadowed, disabled, and risky shell-boundary entries with compact recommended actions.
+  - Keep remediation advisory by default; no automatic mutation of user recipes.
+  - Preserve detailed diagnostics through verbose inspection.
+- Acceptance:
+  - `inspect target=recipes view=doctor` identifies the highest-priority actionable maintenance item.
+  - Blocking invalid recipes include the blocked lower-priority candidate when available.
+  - Tests cover at least invalid/blocking, disabled, shadowed, and risky shell diagnostics.
+
+### M-09 Actor Worker v2
+
+- Priority: High.
+- Status: Open.
+- Goal: Promote `actor-worker` from a minimal demo into the canonical standard-worker reference pattern.
+- Why now: Mailbox-loop semantics are now stable enough to show artifact production, compact status, and stale-claim recovery without adding a scheduler or broker.
+- Direction:
+  - Add optional task result artifact writing.
+  - Expose compact worker status for `inspect` and room events.
+  - Add stale-claim recovery or timeout semantics where they fit the mailbox-loop helper.
+  - Preserve policy-light behavior: no model choice, prompt design, or project task selection.
+- Acceptance:
+  - Worker can produce a durable artifact path for handled work.
+  - Stale claimed work can be surfaced or recovered deterministically.
+  - The actors skill documents the v2 worker pattern.
+
+### M-10 Dist Package Contract Hardening
+
+- Priority: Medium.
+- Status: Open.
+- Goal: Make the dist-first package contract difficult to regress after the 0.24 packaging shift.
+- Why now: `dist/` is now the default JS-only runtime surface and carries mirrored scripts, recipes, fixtures, and skills.
+- Direction:
+  - Add package-layout checks for default metadata, source metadata, mirrored assets, and compiled script-domain modules.
+  - Add negative checks for stale renamed dist files and source-only runtime imports from installed packages.
+  - Keep source files packaged for TypeScript-native runtimes unless a future package-size decision changes that explicitly.
+- Acceptance:
+  - `npm run validate` fails if default Pi metadata points outside `dist` unexpectedly.
+  - Installed-package tests cover every script shim that imports compiled domain logic.
+  - Pack dry assertions cover `dist/scripts`, `dist/recipes`, `dist/fixtures`, and `dist/skills`.
+
+### M-11 Actor Termination Semantics
+
+- Priority: Medium.
+- Status: Open.
+- Goal: Make `control.kill` the canonical parent-to-actor termination action while keeping `control.stop` and `control.cancel` as actor-domain messages whose meaning depends on the actor protocol.
+- Why now: Mailbox workers need a clearer lifecycle boundary before v2 patterns harden. Treating `stop`, `cancel`, and `kill` as equivalent stop messages blurs actor termination with domain-specific task or playback control.
+- Direction:
+  - Document `control.kill` as the universal lifecycle action for a parent/supervisor terminating an actor or run.
+  - Reframe `control.stop` as actor-defined domain control, such as stopping music playback or ending an actor-specific loop when that actor declares it.
+  - Reframe `control.cancel` as actor-defined domain control, such as cancelling the current subagent task while keeping the worker actor alive for later assignments.
+  - Split mailbox-loop helper semantics so lifecycle termination detection is distinct from general control-message detection.
+  - While the package is pre-1.0, allow a small intentional minor-version contract break: remove legacy treatment that aliases `control.stop` or `control.cancel` to actor termination.
+  - Do not preserve compatibility shims for the old stop/cancel-as-termination behavior before the first 1.0 major release unless a concrete safety issue appears during implementation.
+- Acceptance:
+  - Docs and actors skill advertise `control.kill` as canonical parent-to-actor termination.
+  - Mailbox-loop helpers/tests distinguish actor termination from actor-domain `stop`/`cancel` handling.
+  - Packaged recipes declare `stop`/`cancel` only when the actor-specific behavior is meaningful.
+  - Tests assert that generic mailbox-loop termination is not triggered by `control.stop` or `control.cancel`.
+
 ## Explicitly Deferred
 
 These are valid ideas but not current focus. Reintroduce only with concrete evidence from real actor workflows.
@@ -176,4 +241,10 @@ These are valid ideas but not current focus. Reintroduce only with concrete evid
 
 ## Suggested Milestone Order
 
-All milestone tasks in this backlog are currently complete. Reopen this section only with concrete follow-up work from real actor workflows, release preflight, or operator diagnostics.
+```text
+0.25 — Operator remediation and worker maturity:
+  M-08, M-09
+
+0.26 — Package contract hardening and lifecycle semantics:
+  M-10, M-11
+```

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+## 0.24.2: Actor Inspector Item View Hotfix
+
+- `[Inspector]` Removed the roster panel from selected actor-message item inspection, kept the compact route header styling, added the same left/right gutter used by inspector rows, and renamed the selected-item `body_preview` label to `body`.
+
+## 0.24.1: Build Script Package Hygiene Hotfix
+
+- `[Backlog]` Added the next focused backlog set for recipe doctor remediation UX, actor worker v2, and dist package contract hardening.
+- `[Skills]` Clarified agent-governed promotion of successful transient actor patterns into durable local tools via `register_tool`, without UI buttons or automatic registration.
+
 ## 0.24.0: Reliability, Mailbox Workers, and Dist-First Packaging
 
 - `[Prompts]` Clarified that recipe registry warnings are actionable maintenance: invalid or blocking recipes should be fixed, removed, or disabled rather than ignored.
@@ -18,7 +27,7 @@
 - `[Packaging]` Build output now mirrors packaged `skills/` into `dist/` alongside scripts, recipes, and fixtures so the JS-only distributive tree carries the project skills; package skill metadata now points at `dist/skills` with `pi.sourceSkills` preserving root TypeScript/source-tree paths, and README now documents the dist-first/source-optional package shape. The dist build pipeline now lives in `scripts/build-dist.mjs` instead of an inline package script, completing the compiled script entrypoint backlog slice.
 - `[Docs]` Added a platform support matrix for mailbox-only, FIFO, named-pipe, and process-control behavior across Linux/macOS/WSL and native Windows, with regressions proving native Windows FIFO limits remain visible and the canonical worker recipe stays mailbox-only.
 - `[Backlog]` Marked the reliability, mailbox loop, protocol fixture, portability, and compiled-entrypoint milestone set complete; future backlog additions should come from concrete actor workflow evidence.
-- `[Scripts]` Migrated `recipe-utils`, `build-dist`, `locker`, `coordinator`, and `validate-recipe` command logic behind compiled TypeScript domain modules while preserving the stable `scripts/*.mjs` shim paths; project guidance frames this as deliberate standard-library growth with clear domain boundaries while keeping self-contained application scripts such as `music-player.mjs` standalone.
+- `[Scripts]` Migrated `recipe-utils`, `locker`, `coordinator`, and `validate-recipe` command logic behind compiled TypeScript domain modules while preserving the stable `scripts/*.mjs` shim paths; project guidance frames this as deliberate standard-library growth with clear domain boundaries while keeping self-contained application/build scripts such as `music-player.mjs` and `build-dist.mjs` standalone.
 - `[Protocol]` Added compact protocol fixtures for actor messages, mailbox contracts, run inbox/outbox records, room messages/rosters, run state, recipe summaries, and artifact manifests with regression coverage.
 - `[Skills]` Documented the passive-active skill evolution discipline: `actors` tracks extension mechanics while `swarm` tracks orchestration standards and lessons.
 

package/dist/index.js

@@ -94,7 +94,7 @@ export default function toolRegistryExtension(pi) {
                             ? ActorInspectorTui.renderInspectorItemView(previews, width, style, { sequence: selectedInspectorSequence })
                             : ActorInspectorTui.renderInspectorWidget(previews, width, style)) ?? [];
                         const run = previews[0]?.run;
-                        const roster = run
+                        const roster = selectedInspectorSequence === undefined && run
                             ? ActorInspectorTui.renderInspectorRosterPanel(ActorInspectorTui.readActorInspectorRoster(RUN_STATE_ROOT, run), width, style)
                             : undefined;
                         return roster ? [...roster, ...rows] : rows;

package/dist/lib/actor-inspector-tui.js

@@ -318,6 +318,11 @@ function propertyValue(value) {
         return String(value);
     return JSON.stringify(value);
 }
+function itemViewKeyLabel(key) {
+    if (key === "body_preview")
+        return "body";
+    return key;
+}
 function displayWidth(value) {
     return visibleWidth(value);
 }
@@ -499,6 +504,9 @@ export function renderInspectorItemView(previews, width = 80, styles = {}, optio
     if (!preview)
         return undefined;
     const safeWidth = Math.max(1, width);
+    const prefix = " ";
+    const suffix = " ";
+    const contentWidth = Math.max(8, safeWidth - prefix.length - suffix.length);
     const orderedKeys = [
         "channel",
         "run",
@@ -522,20 +530,21 @@ export function renderInspectorItemView(previews, width = 80, styles = {}, optio
     const sequencePadding = " ".repeat(Math.max(0, keyWidth - displayWidth(sequenceText)));
     const headerSeparator = "  ";
     const route = routeText(preview);
-    const visibleRoute = boundedLine(route, Math.max(0, safeWidth - keyWidth - headerSeparator.length));
+    const visibleRoute = boundedLine(route, Math.max(0, contentWidth - keyWidth - headerSeparator.length));
     const headerPlain = `${sequenceText}${sequencePadding}${headerSeparator}${visibleRoute}`;
     const header = `${style(styles.muted, sequenceText)}${sequencePadding}${headerSeparator}${style(styles.target, visibleRoute)}`;
-    const headerPadding = Math.max(0, safeWidth - visibleWidth(headerPlain));
-    const lines = [`${header}${" ".repeat(headerPadding)}`, ""];
+    const headerPadding = Math.max(0, contentWidth - visibleWidth(headerPlain));
+    const lines = [`${prefix}${header}${" ".repeat(headerPadding)}${suffix}`, ""];
     for (const [key, value] of entries) {
-        const keyPadding = " ".repeat(Math.max(0, keyWidth - displayWidth(key)));
+        const label = itemViewKeyLabel(key);
+        const keyPadding = " ".repeat(Math.max(0, keyWidth - displayWidth(label)));
         const separator = "  ";
-        const valueWidth = Math.max(0, safeWidth - keyWidth - separator.length);
+        const valueWidth = Math.max(0, contentWidth - keyWidth - separator.length);
         const visibleValue = boundedLine(value, valueWidth);
-        const plain = `${key}${keyPadding}${separator}${visibleValue}`;
-        const rendered = `${style(styles.muted, key)}${keyPadding}${separator}${style(styles.preview, visibleValue)}`;
-        const padding = Math.max(0, safeWidth - visibleWidth(plain));
-        lines.push(`${rendered}${" ".repeat(padding)}`);
+        const plain = `${label}${keyPadding}${separator}${visibleValue}`;
+        const rendered = `${style(styles.muted, label)}${keyPadding}${separator}${style(styles.preview, visibleValue)}`;
+        const padding = Math.max(0, contentWidth - visibleWidth(plain));
+        lines.push(`${prefix}${rendered}${" ".repeat(padding)}${suffix}`);
     }
     return lines;
 }

package/dist/lib/coordinator.js

@@ -136,6 +136,22 @@ async function writeLockerMessage(locker, message) {
         await writeFile(control.path, line, { flag: "a" });
     await sleep(50);
 }
+async function waitForLockerJournal(locker, pattern, timeoutMs = 2000) {
+    if (!locker)
+        return;
+    const journalPath = `${locker.stateDir}/journal.jsonl`;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            if (pattern.test(await readFile(journalPath, "utf8")))
+                return;
+        }
+        catch {
+            // Journal may not exist yet.
+        }
+        await sleep(25);
+    }
+}
 function scriptPath(name) {
     const here = dirname(fileURLToPath(import.meta.url));
     const root = here.endsWith(`${join("dist", "lib")}`)
@@ -261,6 +277,7 @@ async function synthesize(config, locker) {
             type: "lock.complete",
             body: { id: "coordinator-artifact", artifact: config.artifactPath },
         });
+        await waitForLockerJournal(locker, /lock\.complete/);
         await writeLockerMessage(locker, {
             type: "lock.release",
             body: { resource: config.artifactPath },

package/dist/scripts/build-dist.mjs

@@ -1,25 +1,33 @@
 #!/usr/bin/env node
 
 /**
- * Build the JavaScript-only distributive tree shim.
+ * Build the JavaScript-only distributive tree.
  *
- * Runtime logic lives in lib/build-dist.ts and is compiled to
- * dist/lib/build-dist.js when the package is built.
+ * This is intentionally standalone: it is package/build glue, not reusable
+ * actor-domain behavior. It cleans dist, compiles TypeScript, mirrors runtime
+ * assets, and syntax-checks packaged script shims.
  */
 
-import { existsSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { spawnSync } from "node:child_process";
+import { cpSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
 
-function packageRoot() {
-  return dirname(dirname(fileURLToPath(import.meta.url)));
+function run(command, args) {
+  const result = spawnSync(command, args, { stdio: "inherit" });
+  if (result.status !== 0) process.exit(result.status ?? 1);
 }
 
-function mainModulePath() {
-  const root = packageRoot();
-  const compiled = join(root, "dist", "lib", "build-dist.js");
-  return existsSync(compiled) ? compiled : join(root, "lib", "build-dist.ts");
+rmSync("dist", { recursive: true, force: true });
+mkdirSync("dist", { recursive: true });
+
+run("tsc", ["-p", "tsconfig.build.json"]);
+
+for (const dir of ["scripts", "recipes", "fixtures", "skills"]) {
+  cpSync(dir, join("dist", dir), { recursive: true });
 }
 
-const { buildDist } = await import(pathToFileURL(mainModulePath()).href);
-buildDist();
+const builtScripts = readdirSync(join("dist", "scripts"))
+  .filter((name) => name.endsWith(".mjs"))
+  .map((name) => join("dist", "scripts", name));
+
+run(process.execPath, ["--check", ...builtScripts]);

package/dist/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.24.0
+  version: 0.24.2
 ---
 
 # Actors (pi-actors)
@@ -65,7 +65,7 @@ Rules:
 
 - Use `file`/`recipe` for saved recipes; bare names resolve under `~/.pi/agent/recipes`.
 - Use inline `template` for one-off experiments; promote useful repeats to recipes.
-- When a successful actor follow-up suggests persistence, offer to save or register the pattern under `~/.pi/agent/recipes`; ask before writing the user recipe root.
+- When a successful actor follow-up suggests persistence, decide whether the pattern deserves durable tool memory; call `register_tool` yourself only when the evidence is strong, and ask before writing the user recipe root.
 - Use stable `as` names when you will inspect or message the actor later.
 - `async: true` on the recipe is the detached run switch.
 
@@ -238,6 +238,8 @@ Muscle-memory lens: `~/.pi/agent/recipes/*.json` and `*.md` are the agent's capa
 
 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.
 
+Promotion lens: successful transient/ad hoc actor runs are evidence, not commands. If the run was repeatable, parameterized, safe enough, and likely useful later, the agent may promote it by calling `register_tool` with a concise name, typed args/defaults, and a reviewed template or recipe path. Do not wait for UI buttons; do not auto-register every success; do not persist temp paths, secrets, one-off prompts, or project-private assumptions without normalization and 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, 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

package/dist/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.24.0
+  version: 0.24.2
 ---
 
 # Swarm

package/index.ts

@@ -129,16 +129,17 @@ export default function toolRegistryExtension(pi: ExtensionAPI) {
                         style,
                       )) ?? [];
                 const run = previews[0]?.run;
-                const roster = run
-                  ? ActorInspectorTui.renderInspectorRosterPanel(
-                      ActorInspectorTui.readActorInspectorRoster(
-                        RUN_STATE_ROOT,
-                        run,
-                      ),
-                      width,
-                      style,
-                    )
-                  : undefined;
+                const roster =
+                  selectedInspectorSequence === undefined && run
+                    ? ActorInspectorTui.renderInspectorRosterPanel(
+                        ActorInspectorTui.readActorInspectorRoster(
+                          RUN_STATE_ROOT,
+                          run,
+                        ),
+                        width,
+                        style,
+                      )
+                    : undefined;
                 return roster ? [...roster, ...rows] : rows;
               },
             };

package/lib/actor-inspector-tui.ts

@@ -478,6 +478,11 @@ function propertyValue(value: unknown): string {
   return JSON.stringify(value);
 }
 
+function itemViewKeyLabel(key: string): string {
+  if (key === "body_preview") return "body";
+  return key;
+}
+
 function displayWidth(value: string): number {
   return visibleWidth(value);
 }
@@ -727,6 +732,9 @@ export function renderInspectorItemView(
   const preview = previews.find((item) => item.sequence === options.sequence);
   if (!preview) return undefined;
   const safeWidth = Math.max(1, width);
+  const prefix = " ";
+  const suffix = " ";
+  const contentWidth = Math.max(8, safeWidth - prefix.length - suffix.length);
   const orderedKeys = [
     "channel",
     "run",
@@ -754,21 +762,22 @@ export function renderInspectorItemView(
   const route = routeText(preview);
   const visibleRoute = boundedLine(
     route,
-    Math.max(0, safeWidth - keyWidth - headerSeparator.length),
+    Math.max(0, contentWidth - keyWidth - headerSeparator.length),
   );
   const headerPlain = `${sequenceText}${sequencePadding}${headerSeparator}${visibleRoute}`;
   const header = `${style(styles.muted, sequenceText)}${sequencePadding}${headerSeparator}${style(styles.target, visibleRoute)}`;
-  const headerPadding = Math.max(0, safeWidth - visibleWidth(headerPlain));
-  const lines = [`${header}${" ".repeat(headerPadding)}`, ""];
+  const headerPadding = Math.max(0, contentWidth - visibleWidth(headerPlain));
+  const lines = [`${prefix}${header}${" ".repeat(headerPadding)}${suffix}`, ""];
   for (const [key, value] of entries) {
-    const keyPadding = " ".repeat(Math.max(0, keyWidth - displayWidth(key)));
+    const label = itemViewKeyLabel(key);
+    const keyPadding = " ".repeat(Math.max(0, keyWidth - displayWidth(label)));
     const separator = "  ";
-    const valueWidth = Math.max(0, safeWidth - keyWidth - separator.length);
+    const valueWidth = Math.max(0, contentWidth - keyWidth - separator.length);
     const visibleValue = boundedLine(value, valueWidth);
-    const plain = `${key}${keyPadding}${separator}${visibleValue}`;
-    const rendered = `${style(styles.muted, key)}${keyPadding}${separator}${style(styles.preview, visibleValue)}`;
-    const padding = Math.max(0, safeWidth - visibleWidth(plain));
-    lines.push(`${rendered}${" ".repeat(padding)}`);
+    const plain = `${label}${keyPadding}${separator}${visibleValue}`;
+    const rendered = `${style(styles.muted, label)}${keyPadding}${separator}${style(styles.preview, visibleValue)}`;
+    const padding = Math.max(0, contentWidth - visibleWidth(plain));
+    lines.push(`${prefix}${rendered}${" ".repeat(padding)}${suffix}`);
   }
   return lines;
 }

package/lib/coordinator.ts

@@ -155,6 +155,20 @@ async function writeLockerMessage(locker, message) {
   await sleep(50);
 }
 
+async function waitForLockerJournal(locker, pattern, timeoutMs = 2000) {
+  if (!locker) return;
+  const journalPath = `${locker.stateDir}/journal.jsonl`;
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      if (pattern.test(await readFile(journalPath, "utf8"))) return;
+    } catch {
+      // Journal may not exist yet.
+    }
+    await sleep(25);
+  }
+}
+
 function scriptPath(name) {
   const here = dirname(fileURLToPath(import.meta.url));
   const root = here.endsWith(`${join("dist", "lib")}`)
@@ -293,6 +307,7 @@ async function synthesize(config, locker) {
       type: "lock.complete",
       body: { id: "coordinator-artifact", artifact: config.artifactPath },
     });
+    await waitForLockerJournal(locker, /lock\.complete/);
     await writeLockerMessage(locker, {
       type: "lock.release",
       body: { resource: config.artifactPath },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.24.0",
+  "version": "0.24.2",
   "private": false,
   "description": "Local Actor Kernel for Pi",
   "keywords": [

package/scripts/build-dist.mjs

@@ -1,25 +1,33 @@
 #!/usr/bin/env node
 
 /**
- * Build the JavaScript-only distributive tree shim.
+ * Build the JavaScript-only distributive tree.
  *
- * Runtime logic lives in lib/build-dist.ts and is compiled to
- * dist/lib/build-dist.js when the package is built.
+ * This is intentionally standalone: it is package/build glue, not reusable
+ * actor-domain behavior. It cleans dist, compiles TypeScript, mirrors runtime
+ * assets, and syntax-checks packaged script shims.
  */
 
-import { existsSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { spawnSync } from "node:child_process";
+import { cpSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
 
-function packageRoot() {
-  return dirname(dirname(fileURLToPath(import.meta.url)));
+function run(command, args) {
+  const result = spawnSync(command, args, { stdio: "inherit" });
+  if (result.status !== 0) process.exit(result.status ?? 1);
 }
 
-function mainModulePath() {
-  const root = packageRoot();
-  const compiled = join(root, "dist", "lib", "build-dist.js");
-  return existsSync(compiled) ? compiled : join(root, "lib", "build-dist.ts");
+rmSync("dist", { recursive: true, force: true });
+mkdirSync("dist", { recursive: true });
+
+run("tsc", ["-p", "tsconfig.build.json"]);
+
+for (const dir of ["scripts", "recipes", "fixtures", "skills"]) {
+  cpSync(dir, join("dist", dir), { recursive: true });
 }
 
-const { buildDist } = await import(pathToFileURL(mainModulePath()).href);
-buildDist();
+const builtScripts = readdirSync(join("dist", "scripts"))
+  .filter((name) => name.endsWith(".mjs"))
+  .map((name) => join("dist", "scripts", name));
+
+run(process.execPath, ["--check", ...builtScripts]);

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.24.0
+  version: 0.24.2
 ---
 
 # Actors (pi-actors)
@@ -65,7 +65,7 @@ Rules:
 
 - Use `file`/`recipe` for saved recipes; bare names resolve under `~/.pi/agent/recipes`.
 - Use inline `template` for one-off experiments; promote useful repeats to recipes.
-- When a successful actor follow-up suggests persistence, offer to save or register the pattern under `~/.pi/agent/recipes`; ask before writing the user recipe root.
+- When a successful actor follow-up suggests persistence, decide whether the pattern deserves durable tool memory; call `register_tool` yourself only when the evidence is strong, and ask before writing the user recipe root.
 - Use stable `as` names when you will inspect or message the actor later.
 - `async: true` on the recipe is the detached run switch.
 
@@ -238,6 +238,8 @@ Muscle-memory lens: `~/.pi/agent/recipes/*.json` and `*.md` are the agent's capa
 
 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.
 
+Promotion lens: successful transient/ad hoc actor runs are evidence, not commands. If the run was repeatable, parameterized, safe enough, and likely useful later, the agent may promote it by calling `register_tool` with a concise name, typed args/defaults, and a reviewed template or recipe path. Do not wait for UI buttons; do not auto-register every success; do not persist temp paths, secrets, one-off prompts, or project-private assumptions without normalization and 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, 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

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.24.0
+  version: 0.24.2
 ---
 
 # Swarm

package/dist/lib/build-dist.d.ts

@@ -1,5 +0,0 @@
-/**
- * Dist build pipeline entrypoint logic.
- * Zones: packaging, JavaScript-only distributive tree
- */
-export declare function buildDist(): void;

package/dist/lib/build-dist.js

@@ -1,24 +0,0 @@
-/**
- * Dist build pipeline entrypoint logic.
- * Zones: packaging, JavaScript-only distributive tree
- */
-import { spawnSync } from "node:child_process";
-import { cpSync, mkdirSync, readdirSync, rmSync } from "node:fs";
-import { join } from "node:path";
-function run(command, args) {
-    const result = spawnSync(command, args, { stdio: "inherit" });
-    if (result.status !== 0)
-        process.exit(result.status ?? 1);
-}
-export function buildDist() {
-    rmSync("dist", { recursive: true, force: true });
-    mkdirSync("dist", { recursive: true });
-    run("tsc", ["-p", "tsconfig.build.json"]);
-    for (const dir of ["scripts", "recipes", "fixtures", "skills"]) {
-        cpSync(dir, join("dist", dir), { recursive: true });
-    }
-    const builtScripts = readdirSync(join("dist", "scripts"))
-        .filter((name) => name.endsWith(".mjs"))
-        .map((name) => join("dist", "scripts", name));
-    run(process.execPath, ["--check", ...builtScripts]);
-}

package/lib/build-dist.ts

@@ -1,30 +0,0 @@
-/**
- * Dist build pipeline entrypoint logic.
- * Zones: packaging, JavaScript-only distributive tree
- */
-
-import { spawnSync } from "node:child_process";
-import { cpSync, mkdirSync, readdirSync, rmSync } from "node:fs";
-import { join } from "node:path";
-
-function run(command: string, args: string[]): void {
-  const result = spawnSync(command, args, { stdio: "inherit" });
-  if (result.status !== 0) process.exit(result.status ?? 1);
-}
-
-export function buildDist(): void {
-  rmSync("dist", { recursive: true, force: true });
-  mkdirSync("dist", { recursive: true });
-
-  run("tsc", ["-p", "tsconfig.build.json"]);
-
-  for (const dir of ["scripts", "recipes", "fixtures", "skills"]) {
-    cpSync(dir, join("dist", dir), { recursive: true });
-  }
-
-  const builtScripts = readdirSync(join("dist", "scripts"))
-    .filter((name) => name.endsWith(".mjs"))
-    .map((name) => join("dist", "scripts", name));
-
-  run(process.execPath, ["--check", ...builtScripts]);
-}