@llblab/pi-actors 0.25.0 → 0.26.0

package/BACKLOG.md

@@ -180,7 +180,7 @@ The backlog is intentionally pruned to the 20% of work most likely to deliver 80
 ### M-09 Actor Worker v2
 
 - Priority: High.
-- Status: Open.
+- Status: Done.
 - 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:
@@ -196,7 +196,7 @@ The backlog is intentionally pruned to the 20% of work most likely to deliver 80
 ### M-10 Dist Package Contract Hardening
 
 - Priority: Medium.
-- Status: Open.
+- Status: Done.
 - 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:
@@ -211,7 +211,7 @@ The backlog is intentionally pruned to the 20% of work most likely to deliver 80
 ### M-11 Actor Termination Semantics
 
 - Priority: Medium.
-- Status: Open; core mailbox-loop hotfix landed in 0.24.8.
+- Status: Done.
 - 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.
 - Remaining direction:
@@ -240,9 +240,5 @@ These are valid ideas but not current focus. Reintroduce only with concrete evid
 ## Suggested Milestone Order
 
 ```text
-0.25 — Worker maturity:
-  M-09
-
-0.26 — Package contract hardening and lifecycle semantics:
-  M-10, M-11
+Next milestone: choose from deferred items only after concrete actor workflow evidence appears.
 ```

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.26.0: Actor Worker v2 and Package Contract Hardening
+
+- `[Actor Worker]` Promoted the packaged `actor-worker` into a v2 reference pattern with compact `worker-status.json`, optional per-task result artifacts under `worker-artifacts/`, stale-claim surfacing through status, and artifact metadata on `task.result` room messages.
+- `[Recipes]` Audited packaged async recipe mailbox contracts so `control.stop` and `control.cancel` remain declared only for actor-domain handlers such as locker/coordinator/music control, while generic async recipes expose `control.kill` for runtime termination.
+- `[Packaging]` Hardened dist package regressions with mirrored asset checks for `dist/scripts`, `dist/recipes`, `dist/fixtures`, and `dist/skills`, plus negative checks for stale dist files and source-only runtime imports in built script shims.
+- `[Skills]` Updated the actors skill recipe navigator to document the v2 worker pattern and its `control.kill` termination contract.
+
 ## 0.25.0: Recipe Doctor Remediation UX
 
 - `[Recipe Doctor]` Added prioritized advisory remediations to recipe doctor output, including a compact top action, structured verbose remediation entries, blocked lower-priority candidates for invalid/disabled overrides, and ordered coverage for invalid, disabled, shadowed, and risky shell-boundary recipes.

package/README.md

@@ -89,7 +89,7 @@ cat > ~/.pi/agent/recipes/docs_review.json <<'JSON'
   "async": true,
   "args": ["scope:path", "model:string"],
   "mailbox": {
-    "accepts": ["control.stop", "control.continue"],
+    "accepts": ["control.kill", "control.continue"],
     "emits": ["review.completed", "run.failed"]
   },
   "template": "pi -p --model {model} --no-tools \"Review {scope} for unclear actor-runtime onboarding. Return concise findings.\""

package/dist/lib/actor-worker.d.ts

@@ -3,10 +3,13 @@
  * Zones: worker demo, mailbox loop recipe runtime
  */
 interface ActorWorkerArgs {
+    artifact_dir?: string;
     branch?: string;
     poll_ms?: string | number;
     run?: string;
+    stale_claim_ms?: string | number;
     state_dir?: string;
+    write_artifacts?: string | boolean;
 }
 export declare function parseActorWorkerArgs(argv: string[]): ActorWorkerArgs;
 export declare function runActorWorker(argv?: string[]): Promise<void>;

package/dist/lib/actor-worker.js

@@ -2,9 +2,9 @@
  * Canonical mailbox-backed actor worker entrypoint logic.
  * Zones: worker demo, mailbox loop recipe runtime
  */
-import { appendFileSync } from "node:fs";
+import { appendFileSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { appendRoomMessage, ensureRoomMember } from "./actor-rooms.js";
+import { appendRoomMessage, ensureRoomMember, readBranchInboxMessages } from "./actor-rooms.js";
 import { handleMailboxLoopOnce, isMailboxLoopStopMessage } from "./mailbox-loop.js";
 export function parseActorWorkerArgs(argv) {
     const args = {};
@@ -29,21 +29,54 @@ function sleep(ms) {
 function text(value) {
     return typeof value === "string" ? value : JSON.stringify(value);
 }
+function enabled(value) {
+    return value !== false && value !== "false" && value !== "0";
+}
+function safeName(value) {
+    return String(value ?? "unknown").replaceAll(/[^A-Za-z0-9_.-]+/g, "_");
+}
 export async function runActorWorker(argv = process.argv.slice(2)) {
     const args = parseActorWorkerArgs(argv);
     const stateDir = String(args.state_dir ?? "");
     const run = String(args.run ?? "");
     const branch = String(args.branch ?? "worker");
     const pollMs = Math.max(50, Number(args.poll_ms ?? 1000));
+    const staleClaimMs = Math.max(0, Number(args.stale_claim_ms ?? 0));
+    const artifactDir = String(args.artifact_dir ?? join(stateDir, "worker-artifacts"));
+    const writeArtifacts = enabled(args.write_artifacts ?? true);
     if (!stateDir || !run) {
         throw new Error("usage: actor-worker.mjs --state-dir <dir> --run <id> [--branch worker] [--poll-ms 1000]");
     }
     const branchAddress = `branch:${run}/${branch}`;
     const roomAddress = `room:${run}`;
     const journalPath = join(stateDir, "worker-events.jsonl");
+    const statusPath = join(stateDir, "worker-status.json");
+    if (writeArtifacts)
+        mkdirSync(artifactDir, { recursive: true });
     function journal(event, data = {}) {
         appendFileSync(journalPath, `${JSON.stringify({ event, ts: new Date().toISOString(), ...data })}\n`);
     }
+    function staleClaims() {
+        if (staleClaimMs <= 0)
+            return 0;
+        const cutoff = Date.now() - staleClaimMs;
+        return readBranchInboxMessages(stateDir, run, branchAddress).filter((record) => {
+            if (record.status !== "claimed" || !record.claimed_at)
+                return false;
+            const claimedAt = Date.parse(record.claimed_at);
+            return Number.isFinite(claimedAt) && claimedAt < cutoff;
+        }).length;
+    }
+    function status(state, data = {}) {
+        writeFileSync(statusPath, `${JSON.stringify({ artifact_dir: artifactDir, branch, run, stale_claims: staleClaims(), state, ts: new Date().toISOString(), ...data }, null, 2)}\n`);
+    }
+    function writeResultArtifact(id, result) {
+        if (!writeArtifacts)
+            return undefined;
+        const path = join(artifactDir, `${safeName(id)}.txt`);
+        writeFileSync(path, `${result}\n`);
+        return path;
+    }
     function room(type, summary, body = {}) {
         appendRoomMessage(stateDir, "main", {
             body,
@@ -55,7 +88,9 @@ export async function runActorWorker(argv = process.argv.slice(2)) {
     }
     ensureRoomMember(stateDir, run, "main", branchAddress, { display: branch, role: "worker", status: "present" }, `${branch} joined as mailbox worker`);
     room("awaiting_assignment", `${branch} awaiting assignment`, { branch });
-    journal("worker.started", { branch, run });
+    journal("worker.started", { artifact_dir: artifactDir, branch, run, stale_claim_ms: staleClaimMs });
+    status("awaiting_assignment", { handled: 0, stale_claim_ms: staleClaimMs });
+    let handled = 0;
     let stopping = false;
     while (!stopping) {
         const result = await handleMailboxLoopOnce({ address: branchAddress, kind: "branch", run, stateDir }, (message) => {
@@ -63,6 +98,7 @@ export async function runActorWorker(argv = process.argv.slice(2)) {
                 stopping = true;
                 room("actor.leave", `${branch} stopping`, { branch, reason: message.type });
                 journal("worker.stopping", { id: message.id, type: message.type });
+                status("stopping", { handled, reason: message.type });
                 return;
             }
             room("task.claim", `${branch} claimed ${message.type}`, {
@@ -70,17 +106,29 @@ export async function runActorWorker(argv = process.argv.slice(2)) {
                 id: message.id,
                 type: message.type,
             });
+            const result = text(message.body);
+            const artifact = writeResultArtifact(message.id, result);
+            handled += 1;
             room("task.result", `${branch} handled ${message.type}`, {
+                artifact,
                 branch,
                 id: message.id,
-                result: text(message.body),
+                result,
                 type: message.type,
             });
             room("awaiting_assignment", `${branch} awaiting assignment`, { branch });
-            journal("task.handled", { id: message.id, type: message.type });
+            journal("task.handled", { artifact, id: message.id, type: message.type });
+            status("awaiting_assignment", {
+                handled,
+                last_artifact: artifact,
+                last_id: message.id,
+                last_type: message.type,
+                stale_claim_ms: staleClaimMs,
+            });
         }, { owner: branchAddress });
         if (!result.handled)
             await sleep(pollMs);
     }
-    journal("worker.done", { branch, run });
+    journal("worker.done", { branch, handled, run });
+    status("done", { handled });
 }

package/dist/recipes/actor-worker.json

@@ -4,18 +4,20 @@
   "args": [
     "repo:path",
     "branch:string",
-    "poll_ms:int"
+    "poll_ms:int",
+    "stale_claim_ms:int",
+    "write_artifacts:bool"
   ],
   "defaults": {
     "repo": "~/.pi/agent/extensions/pi-actors",
     "branch": "worker",
-    "poll_ms": "1000"
+    "poll_ms": "1000",
+    "stale_claim_ms": "0",
+    "write_artifacts": "true"
   },
   "mailbox": {
     "accepts": [
       "task.assign",
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [
@@ -29,7 +31,9 @@
     ]
   },
   "artifacts": {
-    "journal": "{state_dir}/worker-events.jsonl"
+    "journal": "{state_dir}/worker-events.jsonl",
+    "status": "{state_dir}/worker-status.json",
+    "results": "{state_dir}/worker-artifacts"
   },
-  "template": "{repo}/scripts/actor-worker.mjs --state-dir {state_dir} --run {run_id} --branch {branch} --poll-ms {poll_ms}"
+  "template": "{repo}/scripts/actor-worker.mjs --state-dir {state_dir} --run {run_id} --branch {branch} --poll-ms {poll_ms} --stale-claim-ms {stale_claim_ms} --write-artifacts {write_artifacts}"
 }

package/dist/recipes/lens-swarm.json

@@ -30,8 +30,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/dist/recipes/pipeline-architect-coordinator.json

@@ -26,8 +26,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/dist/recipes/pipeline-artifact-bundle.json

@@ -35,8 +35,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/dist/recipes/pipeline-artifact-report.json

@@ -18,8 +18,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/dist/recipes/pipeline-artifact-write.json

@@ -21,8 +21,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/dist/recipes/pipeline-async-run-ops.json

@@ -24,8 +24,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/dist/recipes/pipeline-checkpoint-continuation.json

@@ -22,8 +22,6 @@
     "accepts": [
       "control.reply",
       "control.revise",
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/dist/recipes/pipeline-development-tasking.json

@@ -24,8 +24,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/dist/recipes/pipeline-docs-maintenance.json

@@ -23,8 +23,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/dist/recipes/pipeline-media-library.json

@@ -23,8 +23,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/dist/recipes/pipeline-quorum-review.json

@@ -20,8 +20,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/dist/recipes/pipeline-release-readiness.json

@@ -40,8 +40,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/dist/recipes/pipeline-release-summary.json

@@ -29,8 +29,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/dist/recipes/pipeline-repo-health.json

@@ -25,8 +25,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/dist/recipes/pipeline-research-synthesis.json

@@ -22,8 +22,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/dist/recipes/pipeline-review-readiness.json

@@ -25,8 +25,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/dist/recipes/pipeline-room-swarm.json

@@ -34,8 +34,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/dist/recipes/subagent-artifact.json

@@ -19,8 +19,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/dist/recipes/subagent-checkpoint.json

@@ -21,8 +21,6 @@
     "accepts": [
       "control.continue",
       "control.revise",
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/dist/recipes/subagent-conflict-report.json

@@ -17,8 +17,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/dist/recipes/subagent-contradiction-map.json

@@ -18,8 +18,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/dist/recipes/subagent-critic.json

@@ -20,8 +20,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/dist/recipes/subagent-evidence-map.json

@@ -18,8 +18,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/dist/recipes/subagent-followup.json

@@ -21,8 +21,6 @@
     "accepts": [
       "control.reply",
       "control.revise",
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/dist/recipes/subagent-judge.json

@@ -18,8 +18,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/dist/recipes/subagent-merge.json

@@ -18,8 +18,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/dist/recipes/subagent-message.json

@@ -22,8 +22,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/dist/recipes/subagent-normalize.json

@@ -16,8 +16,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/dist/recipes/subagent-plan.json

@@ -18,8 +18,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/dist/recipes/subagent-prompt.json

@@ -14,8 +14,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/dist/recipes/subagent-quorum.json

@@ -17,8 +17,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/dist/recipes/subagent-review-coordinator.json

@@ -36,8 +36,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/dist/recipes/subagent-review.json

@@ -22,8 +22,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/dist/recipes/subagent-task-card.json

@@ -20,8 +20,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/dist/recipes/subagent-tools.json

@@ -13,8 +13,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/dist/recipes/subagent-verify.json

@@ -19,8 +19,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

package/dist/recipes/subagents-prompts.json

@@ -25,8 +25,6 @@
   },
   "mailbox": {
     "accepts": [
-      "control.stop",
-      "control.cancel",
       "control.kill"
     ],
     "emits": [

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.25.0
+  version: 0.26.0
 ---
 
 # Actors (pi-actors)
@@ -277,7 +277,7 @@ Use packaged recipes by name with `spawn file=<name>` for async actors, or regis
 - [`locker`](../../recipes/locker.json): modular queue + acquire/renew/release lease locks + journaled locker messages + platform-adapted control metadata.
 - [`utility-coordinator-lock-snapshot`](../../recipes/utility-coordinator-lock-snapshot.json): one-shot JSON snapshot of a coordinator-locker state directory.
 - [`music-player`](../../recipes/music-player.json): background local/URL/directory/playlist playback actor controlled by messages.
-- [`actor-worker`](../../recipes/actor-worker.json): canonical mailbox-backed branch worker demo that claims branch inbox work, emits room-visible task lifecycle messages, and stops on standard control messages.
+- [`actor-worker`](../../recipes/actor-worker.json): canonical mailbox-backed branch worker reference that claims branch inbox work, emits room-visible task lifecycle messages, writes compact `worker-status.json`, optionally writes per-task result artifacts under `worker-artifacts/`, surfaces stale-claim counts when `stale_claim_ms` is set, and terminates on `control.kill`.
 
 ### Subagent Atoms
 

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.25.0
+  version: 0.26.0
 ---
 
 # Swarm

package/docs/actor-messages.md

@@ -164,7 +164,7 @@ Recipes can declare their conversational surface:
       "control.continue",
       "control.revise",
       "control.approve",
-      "control.stop"
+      "control.kill"
     ],
     "emits": ["checkpoint.needs_scope", "branch.done", "run.done"]
   }