@llblab/pi-actors 0.24.8 → 0.26.0

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.24.8
+  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.24.8
+  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"]
   }

package/docs/template-recipes.md

@@ -80,7 +80,7 @@ defaults:
   scope: docs
 mailbox:
   accepts:
-    - control.stop
+    - control.kill
 ---
 
 Human notes can explain intent, examples, or review guidance.
@@ -155,7 +155,7 @@ Use recipe-level `mailbox` to document the semantic messages a recipe actor acce
       "control.continue",
       "control.revise",
       "control.approve",
-      "control.stop"
+      "control.kill"
     ],
     "emits": ["checkpoint.needs_scope", "branch.done", "run.done"]
   }

package/docs/tool-registry.md

@@ -23,10 +23,11 @@ Inspect the discovered registry with:
 
 ```text
 inspect target=recipes view=status
+inspect target=recipes view=doctor
 inspect target=recipes view=summary verbose=true
 ```
 
-The summary reports active, shadowed, invalid, disabled, and diagnostic entries so operators can answer why a tool is present, hidden, broken, or disabled.
+The summary reports active, shadowed, invalid, disabled, and diagnostic entries so operators can answer why a tool is present, hidden, broken, or disabled. The doctor view keeps the same registry evidence but promotes an advisory action surface: compact output includes the highest-priority `top` remediation plus ordered actions for invalid/blocking, disabled, risky shell-boundary, and shadowed recipes. Verbose inspection keeps the structured `remediations`, `top_action`, diagnostic details, and blocked lower-priority candidate paths when a broken or disabled higher-priority recipe masks a fallback.
 
 ## Registering Tools
 

package/lib/actor-worker.ts

@@ -3,17 +3,20 @@
  * 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.ts";
+import { appendRoomMessage, ensureRoomMember, readBranchInboxMessages } from "./actor-rooms.ts";
 import { handleMailboxLoopOnce, isMailboxLoopStopMessage } from "./mailbox-loop.ts";
 
 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 function parseActorWorkerArgs(argv: string[]): ActorWorkerArgs {
@@ -41,12 +44,23 @@ function text(value: unknown): string {
   return typeof value === "string" ? value : JSON.stringify(value);
 }
 
+function enabled(value: unknown): boolean {
+  return value !== false && value !== "false" && value !== "0";
+}
+
+function safeName(value: unknown): string {
+  return String(value ?? "unknown").replaceAll(/[^A-Za-z0-9_.-]+/g, "_");
+}
+
 export async function runActorWorker(argv = process.argv.slice(2)): Promise<void> {
   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]");
@@ -55,6 +69,8 @@ export async function runActorWorker(argv = process.argv.slice(2)): Promise<void
   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: string, data: Record<string, unknown> = {}): void {
     appendFileSync(
@@ -63,6 +79,30 @@ export async function runActorWorker(argv = process.argv.slice(2)): Promise<void
     );
   }
 
+  function staleClaims(): number {
+    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: string, data: Record<string, unknown> = {}): void {
+    writeFileSync(
+      statusPath,
+      `${JSON.stringify({ artifact_dir: artifactDir, branch, run, stale_claims: staleClaims(), state, ts: new Date().toISOString(), ...data }, null, 2)}\n`,
+    );
+  }
+
+  function writeResultArtifact(id: unknown, result: string): string | undefined {
+    if (!writeArtifacts) return undefined;
+    const path = join(artifactDir, `${safeName(id)}.txt`);
+    writeFileSync(path, `${result}\n`);
+    return path;
+  }
+
   function room(type: string, summary: string, body: Record<string, unknown> = {}): void {
     appendRoomMessage(stateDir, "main", {
       body,
@@ -82,7 +122,10 @@ export async function runActorWorker(argv = process.argv.slice(2)): Promise<void
     `${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) {
@@ -93,6 +136,7 @@ export async function runActorWorker(argv = process.argv.slice(2)): Promise<void
           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}`, {
@@ -100,19 +144,31 @@ export async function runActorWorker(argv = process.argv.slice(2)): Promise<void
           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/lib/recipe-discovery.ts

@@ -403,6 +403,10 @@ function diagnosticSeverity(message: string): "info" | "warning" | "error" {
 }
 
 function diagnosticSuggestedAction(message: string): string {
+  if (/world-writable|group-writable/i.test(message))
+    return "tighten recipe root permissions";
+  if (/invokes bash/i.test(message))
+    return "audit the trusted shell boundary and keep only if intentional";
   if (/must define template/i.test(message))
     return "add a template field or remove the recipe";
   if (/JSON|Expected|parse/i.test(message))
@@ -414,10 +418,6 @@ function diagnosticSuggestedAction(message: string): string {
     return "split large prompt or data into separate files";
   if (/repeat must/i.test(message))
     return "use a positive repeat count or an array-typed repeat source";
-  if (/world-writable|group-writable/i.test(message))
-    return "tighten recipe root permissions";
-  if (/invokes bash/i.test(message))
-    return "audit the trusted shell boundary or move details to recipe doctor";
   if (/shadows/i.test(message))
     return "confirm the active override or rename one recipe";
   if (/disabled/i.test(message))
@@ -455,6 +455,93 @@ function diagnosticDetails(
   });
 }
 
+function remediationForEntry(
+  entry: DiscoveredRecipe,
+  activePath: string | undefined,
+): Record<string, unknown> | undefined {
+  const riskyDiagnostics = entry.diagnostics.filter(
+    (message) => diagnosticSeverity(message) === "warning",
+  );
+  const blockedCandidate = entry.shadows[0];
+  if (entry.invalid) {
+    return {
+      id: entry.id,
+      kind: blockedCandidate ? "blocking_invalid" : "invalid",
+      severity: "error",
+      path: entry.path,
+      ...(blockedCandidate ? { blocked_candidate: blockedCandidate } : {}),
+      reason: blockedCandidate
+        ? "invalid higher-priority recipe blocks a lower-priority candidate"
+        : "recipe is invalid and cannot be exposed as a tool",
+      action: "fix recipe syntax/config, or disable/delete/archive it to restore fallback",
+    };
+  }
+  if (entry.disabled && entry.active) {
+    return {
+      id: entry.id,
+      kind: blockedCandidate ? "blocking_disabled" : "disabled",
+      severity: "warning",
+      path: entry.path,
+      ...(blockedCandidate ? { blocked_candidate: blockedCandidate } : {}),
+      reason: blockedCandidate
+        ? "disabled higher-priority recipe intentionally blocks a lower-priority candidate"
+        : "recipe is disabled and not exposed as a tool",
+      action: "keep disabled intentionally, re-enable, or delete/archive the file",
+    };
+  }
+  if (riskyDiagnostics.length > 0) {
+    return {
+      id: entry.id,
+      kind: "risky_shell_boundary",
+      severity: "warning",
+      path: entry.path,
+      reason: riskyDiagnostics[0],
+      action: "audit trusted command boundary; keep only if the recipe is local and intentional",
+    };
+  }
+  if (entry.shadowed) {
+    return {
+      id: entry.id,
+      kind: "shadowed",
+      severity: "info",
+      path: entry.path,
+      ...(activePath ? { active_path: activePath } : {}),
+      reason: activePath
+        ? `shadowed by ${activePath}`
+        : "shadowed by a higher-priority recipe",
+      action: "keep as fallback/component, merge, rename, delete, or archive",
+    };
+  }
+  return undefined;
+}
+
+function remediationRank(item: Record<string, unknown>): number {
+  const kind = String(item.kind ?? "");
+  if (kind === "blocking_invalid") return 0;
+  if (kind === "invalid") return 1;
+  if (kind === "blocking_disabled") return 2;
+  if (kind === "risky_shell_boundary") return 3;
+  if (kind === "disabled") return 4;
+  if (kind === "shadowed") return 5;
+  return 6;
+}
+
+function discoveryRemediations(
+  result: RecipeDiscoveryResult,
+): Array<Record<string, unknown>> {
+  return result.entries
+    .map((entry) =>
+      remediationForEntry(entry, result.active.get(entry.id)?.path),
+    )
+    .filter((entry): entry is Record<string, unknown> => Boolean(entry))
+    .sort(
+      (a, b) =>
+        remediationRank(a) - remediationRank(b) ||
+        String(a.id).localeCompare(String(b.id)) ||
+        String(a.path).localeCompare(String(b.path)),
+    );
+}
+
 function recommendationForEntry(
   entry: DiscoveredRecipe,
   activePath: string | undefined,
@@ -483,6 +570,7 @@ export function summarizeDiscovery(
         String(a.id).localeCompare(String(b.id)) ||
         String(a.path).localeCompare(String(b.path)),
     );
+  const remediations = discoveryRemediations(result);
   return {
     active: [...result.active.values()]
       .map((entry) => ({
@@ -520,6 +608,8 @@ export function summarizeDiscovery(
       .map((entry) => ({ id: entry.id, path: entry.path }))
       .sort((a, b) => a.id.localeCompare(b.id)),
     recommendations,
+    remediations,
+    top_action: remediations[0],
     diagnostics: result.diagnostics,
     diagnostic_details: diagnosticDetails(result),
     integrity_manifest: createRecipeIntegrityManifest(result),

package/lib/tools.ts

@@ -470,6 +470,9 @@ function compactRecipeDoctor(summary: Record<string, unknown>): string {
   const details = Array.isArray(summary.diagnostic_details)
     ? (summary.diagnostic_details as Array<Record<string, unknown>>)
     : [];
+  const remediations = Array.isArray(summary.remediations)
+    ? (summary.remediations as Array<Record<string, unknown>>)
+    : [];
   const recommendations = Array.isArray(summary.recommendations)
     ? (summary.recommendations as Array<Record<string, unknown>>)
     : [];
@@ -479,12 +482,26 @@ function compactRecipeDoctor(summary: Record<string, unknown>): string {
     if (severity === "error" || severity === "warning" || severity === "info")
       counts[severity] += 1;
   }
+  const topAction = asRecord(summary.top_action);
   const lines = [
-    `recipes doctor errors=${counts.error} warnings=${counts.warning} info=${counts.info} recommendations=${recommendations.length}`,
+    `recipes doctor errors=${counts.error} warnings=${counts.warning} info=${counts.info} actions=${remediations.length} recommendations=${recommendations.length}`,
   ];
-  for (const detail of details.slice(0, 8)) {
+  if (Object.keys(topAction).length > 0) {
+    const action = compactPreview(
+      topAction.action,
+      Limits.DOCTOR_ACTION_PREVIEW_CHARS,
+    );
+    lines.push(
+      `top severity=${String(topAction.severity ?? "info")} kind=${String(topAction.kind ?? "inspect")} id=${String(topAction.id ?? "root")} action=${action ?? "inspect"}`,
+    );
+  }
+  for (const item of remediations.slice(0, 8)) {
+    const action = compactPreview(item.action, Limits.DOCTOR_ACTION_PREVIEW_CHARS);
+    const blocked = item.blocked_candidate
+      ? ` blocked=${compactPreview(item.blocked_candidate, Limits.DOCTOR_ACTION_PREVIEW_CHARS)}`
+      : "";
     lines.push(
-      `${String(detail.severity ?? "info")} id=${String(detail.id ?? "root")} action=${compactPreview(detail.action, Limits.DOCTOR_ACTION_PREVIEW_CHARS) ?? "inspect"}`,
+      `${String(item.severity ?? "info")} kind=${String(item.kind ?? "inspect")} id=${String(item.id ?? "root")}${blocked} action=${action ?? "inspect"}`,
     );
   }
   return `\n${lines.join("\n")}`;

package/package.json

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

package/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/recipes/lens-swarm.json

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

package/recipes/pipeline-architect-coordinator.json

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

package/recipes/pipeline-artifact-bundle.json

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

package/recipes/pipeline-artifact-report.json

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

package/recipes/pipeline-artifact-write.json

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

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

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

package/recipes/pipeline-checkpoint-continuation.json

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

package/recipes/pipeline-development-tasking.json

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

package/recipes/pipeline-docs-maintenance.json

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

package/recipes/pipeline-media-library.json

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

package/recipes/pipeline-quorum-review.json

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