@llblab/pi-actors 0.24.0 → 0.24.1

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,52 @@ 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`.
+
 ## Explicitly Deferred
 
 These are valid ideas but not current focus. Reintroduce only with concrete evidence from real actor workflows.
@@ -176,4 +222,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:
+  M-10
+```

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+## 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 +23,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/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.1
 ---
 
 # 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.1
 ---
 
 # Swarm

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.1",
   "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.1
 ---
 
 # 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.1
 ---
 
 # 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]);
-}