@llblab/pi-actors 0.25.0 → 0.26.1

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,18 @@
 
 ## Unreleased
 
+## 0.26.1: Coordinator Empty-Synthesis Hotfix
+
+- `[Coordinator]` Treat all-failed participant rounds and empty synthesis as a failed coordinator run instead of a clean success, preserving operator trust when swarm branches all exit non-zero.
+- `[Artifacts]` Write compact diagnostics into empty synthesis artifacts, including participant attempt/success/failure counts and transcript size, so failed swarms leave actionable evidence instead of only `No synthesis output`.
+
+## 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/lib/coordinator.js

@@ -259,7 +259,7 @@ async function readRoomTranscript(config) {
 }
 async function synthesize(config, locker) {
     if (!config.artifactPath)
-        return;
+        return { code: 0, empty: false };
     if (locker) {
         await writeLockerMessage(locker, {
             type: "lock.claim",
@@ -269,9 +269,13 @@ async function synthesize(config, locker) {
     const transcript = await readRoomTranscript(config);
     const prompt = `Synthesize this transcript into a concise Markdown artifact. Mission: ${config.mission}. Include: Title, Consensus, Roles, Protocol, Final Artifact Shape, Next Actions, Open Questions. Use only the transcript evidence below.\n\nTRANSCRIPT:\n${transcript.slice(-24000)}`;
     const result = await runPi(prompt, config.model, config.thinking);
-    await writeFile(config.artifactPath, result.stdout.trim()
+    const output = result.stdout.trim();
+    const diagnostics = config.stats
+        ? `\n\n## Diagnostics\n\nparticipant_attempts=${config.stats.participantAttempts}\nparticipant_success=${config.stats.participantSuccess}\nparticipant_failures=${config.stats.participantFailures}\nsynthesis_code=${result.code}\ntranscript_messages=${transcript.trim() ? transcript.split("\n").length : 0}\n`
+        : "";
+    await writeFile(config.artifactPath, output
         ? result.stdout
-        : "# Synthesis Artifact\n\nNo synthesis output.\n", "utf8");
+        : `# Synthesis Artifact\n\nNo synthesis output.${diagnostics}\n`, "utf8");
     if (locker) {
         await writeLockerMessage(locker, {
             type: "lock.complete",
@@ -284,6 +288,7 @@ async function synthesize(config, locker) {
         });
     }
     process.stdout.write(`artifact=${config.artifactPath}\n`);
+    return { code: result.code, empty: !output };
 }
 async function readInboxLines(inboxPath) {
     if (!existsSync(inboxPath))
@@ -378,9 +383,17 @@ async function participantRound(role, round, config) {
     const address = `branch:${config.runId}/${role.name}`;
     const prompt = `You are ${displayName} (${address}), ${role.persona}. Mission: ${config.mission}. Round ${round}/${config.rounds}. First call inspect target=${config.room} view=previews lines=30 and inspect target=${config.room} view=contacts. Then call message once to ${config.room} from ${address} type=chat.message. Body: 2-4 sentences that react to a named participant, propose the next coordination step, and refine the shared artifact. Use contacts for peer names and addresses. End stdout with summary <=160 chars.`;
     const result = await executeParticipantPrompt(role, prompt, config);
+    if (config.stats) {
+        config.stats.participantAttempts += 1;
+        if (result.code === 0)
+            config.stats.participantSuccess += 1;
+        else
+            config.stats.participantFailures += 1;
+    }
     process.stdout.write(`[${role.name} round ${round}] code=${result.code}\n${result.stdout}\n`);
     if (result.stderr.trim())
         process.stderr.write(`[${role.name} round ${round}] ${result.stderr}\n`);
+    return result;
 }
 async function participantJoin(role, config) {
     const displayName = role.name;
@@ -546,6 +559,11 @@ export async function runCoordinator(argv = process.argv.slice(2)) {
         artifactPath: arg("artifact-path", ""),
         locker: boolArg("locker", false),
         lockerLeaseMs: numberArg("locker-lease-ms", 600000),
+        stats: {
+            participantAttempts: 0,
+            participantSuccess: 0,
+            participantFailures: 0,
+        },
     };
     if (!config.model) {
         console.error("--model is required");
@@ -559,7 +577,16 @@ export async function runCoordinator(argv = process.argv.slice(2)) {
         if (!runMode)
             throw new Error(`Unknown coordinator mode: ${config.mode}`);
         await runMode(config, locker);
-        await synthesize(config, locker);
+        const synthesis = await synthesize(config, locker);
+        if (config.stats.participantAttempts > 0 && config.stats.participantSuccess === 0) {
+            failures.push(`All participant rounds failed: attempts=${config.stats.participantAttempts}`);
+        }
+        if (synthesis?.empty && config.stats.participantFailures > 0) {
+            failures.push(`Synthesis output was empty after participant failures: failures=${config.stats.participantFailures}`);
+        }
+        if (synthesis && synthesis.code !== 0) {
+            failures.push(`Synthesis command failed: code=${synthesis.code}`);
+        }
     }
     catch (globalError) {
         failures.push(`Global coordinator error: ${globalError.message}`);

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": [