@llblab/pi-actors 0.34.0 → 0.34.1

package/BACKLOG.md

@@ -53,37 +53,6 @@ No open hotfix items.
 
 The backlog is intentionally pruned to the 20% of work most likely to deliver 80% of value for `pi-actors` as a local actor kernel. Bias toward consolidation, smaller public surface area, and reliability over new feature breadth.
 
-### M-15 Worker Stale-Claim Dogfood
-
-- Priority: Medium.
-- Status: Planned.
-- Goal: Validate and harden actor-worker v2 stale-claim visibility under intentionally stale claimed branch messages.
-- Why now: M-09 exposed `stale_claims`; real dogfood should verify the operator can diagnose stuck claimed work before adding recovery policy.
-- Direction:
-  - Create deterministic stale claimed branch inbox fixtures or smoke tests.
-  - Verify `worker-status.json`, room events, and inspect surfaces make stale claims visible.
-  - Defer auto-recovery unless workflow evidence proves it is safe.
-- Acceptance:
-  - Stale claims are reproducible and visible in worker status.
-  - Tests cover stale-claim counting without adding scheduler/broker policy.
-
-### M-17 Message Delivery Outcome Contract
-
-- Priority: High.
-- Status: Planned.
-- Goal: Normalize `message` results so operators can distinguish delivered, queued, persisted, forwarded, unsupported, and ownership-denied outcomes.
-- Why now: Branch message UX already treats durable branch mailbox persistence as a successful queued outcome when a parent endpoint is unavailable; that local fix should become a consistent message-result membrane.
-- Direction:
-  - Define compact delivery fields: `queued`, `delivered`, `persisted`, `forwarded`, `consumer`, `reason`, and `hint`.
-  - Apply the shape to `run:<id>`, `branch:<run>/<branch>`, `room:<run>`, `coordinator`, `session:`, and `tool:<name>` where meaningful.
-  - Reuse M-14 session mismatch shape for ownership-denied outcomes.
-  - Do not claim guaranteed live consumption unless a known consumer exists.
-  - Do not add a broker, distributed delivery semantics, or a new public noun.
-- Acceptance:
-  - Branch messages clearly report queued/persisted state and known worker-consumer state where available.
-  - Room messages distinguish timeline append success from forwarded branch-targeted copies.
-  - Tests cover at least run, branch, room, coordinator, and ownership-denied outcomes.
-
 ### M-18 Draft Recipe Promotion UX
 
 - Priority: High.
@@ -185,7 +154,7 @@ These are valid ideas but not current focus. Reintroduce only with concrete evid
 ## Suggested Milestone Order
 
 ```text
-Next milestone: M-15 Worker Stale-Claim Dogfood.
-Then: M-17 Message Delivery Outcome Contract → M-18 Draft Recipe Promotion UX.
+Next milestone: M-18 Draft Recipe Promotion UX.
+Then: M-19 Recipe Doctor Risk Labels v2.
 Small cleanup lane: continue opportunistic domain polish only when a real ownership boundary appears.
 ```

package/CHANGELOG.md

@@ -1,27 +1,20 @@
 # Changelog
 
+## Unreleased
+
+## 0.34.1: Message Delivery Outcome Hotfix
+
+- `[Dogfood]` Added a deterministic actor-worker stale-claim smoke covering an intentionally claimed branch inbox record; the worker now reports stale claim counts in both `worker-status.json` and its awaiting-assignment room event without adding auto-recovery or scheduler policy.
+- `[Messages]` Completed the M-17 message delivery outcome contract by normalizing public message results with `delivered`, `persisted`, `queued`, `forwarded`, `consumer`, and `reason` fields across run, branch, room, coordinator, session, and tool destinations; room multicast now also exposes per-recipient branch delivery outcomes.
+- `[Backlog]` Closed M-15 Worker Stale-Claim Dogfood and M-17 Message Delivery Outcome Contract after adding delivery-result coverage for run, branch, room, coordinator, session, tool, and ownership-denied paths.
+
 ## 0.34.0: Actor Kernel Domain Compression
 
-- `[Context]` Added a critical tools-domain split track and durable naming guidance: split broad buckets proactively, use `tool-<verb>.ts` for independent public agent-tool domains when deleting `tools.ts`, reserve `tools-<part>.ts` only for a retained `tools.ts` aggregate-root architecture, keep non-tool domains unprefixed, and avoid new `utils` or compatibility barrels when direct owned-domain imports work.
-- `[Domains]` Started the `tools.ts` split by moving JSON schema builders into `schema.ts` and compact response helpers into the tool-family response path, reducing the remaining tool bucket to public tool composition rather than generic schema ownership.
-- `[Domains]` Moved the public `message` actor tool behavior into `tools-message.ts`, including run controls, branch/room delivery, tool actor invocation, and compact delivery next actions.
-- `[Domains]` Moved shared session ownership guards and normalized mismatch diagnostics into `tools-access.ts` so public tools can share one access contract without copying ownership checks.
-- `[Domains]` Moved mailbox contract normalization and accepted/emitted type extraction into `tools-mailbox.ts`, removing duplicated mailbox metadata handling from message and inspect tool paths.
-- `[Domains]` Added `tools-response.ts` for compact public tool responses and next-action rendering shared by spawn, inspect, and registered tool paths; moved recipe registry compact summaries and doctor/import next-action rendering into it.
-- `[Domains]` Moved the public `inspect` actor tool behavior into `tools-inspect.ts`, including recipe registry inspection, room/session/tool/run views, and inspect-specific compact observation formatting.
-- `[Domains]` Moved the public `spawn` actor tool behavior into `tools-spawn.ts`, including actor launch, draft recipe capture, shadowed recipe launch diagnostics, and spawn next-action feedback.
-- `[Domains]` Removed the over-thin `tool-context.ts` extraction and kept tool execution context types local to the domains that use them.
-- `[Domains]` Moved saved local capability execution into `tools-local.ts`, including generated schemas, argument usage hints, runtime value normalization, and async recipe launch behavior.
-- `[Domains]` Moved public `register_tool` behavior into `tools-register.ts`, including the register schema and registry mutation bridge for persisted local capabilities.
-- `[Domains]` Kept `tools.ts` as the public tool-family composition owner, moved decomposed behavior into `tools-*` subdomains, removed the redundant `actor-tools.ts` prefix because this package is already actor-scoped, and documented that any `tools-*` helper reused by non-tools domains must drop the prefix in the same slice.
-- `[Domains]` Removed redundant internal `actor-` prefixes from core library domains: `inspector.ts`, `messages.ts`, `recipes-context.ts`, and `rooms.ts`; public recipe/script/docs names that intentionally expose actor terminology stay unchanged.
-- `[Scripts]` Collapsed the one-off `run-executor.ts`, `worker.ts`, `validate-recipe.ts`, `recipe-utils.ts`, `locker.ts`, and `coordinator.ts` domains into their owning scripts; reusable lifecycle, room, mailbox, and recipe-reference primitives stay in `lib/`, while public scripts own their executable control loops directly.
-- `[Domains]` Started decomposing the oversized `async-runs.ts` lifecycle aggregate into `runs-*` subdomains, moving artifact manifest handling to `runs-artifacts.ts`, durable run inbox locking/claim handling to `runs-mailbox.ts`, process-control signal helpers to `runs-control.ts`, outbox event parsing/payload formatting to `runs-outbox.ts`, run-state index discovery/rebuild logic to `runs-index.ts`, id normalization to `runs-identity.ts`, archive/prune retention behavior to `runs-retention.ts`, process identity/liveness checks to `runs-process.ts`, run message delivery to `runs-messages.ts`, status/log derivation to `runs-status.ts`, and start lock/reuse guards to `runs-start.ts` while preserving the `async-runs.ts` facade.
-- `[Context]` Reversed the thin-script default: `scripts/*.mjs` should own script-only executable behavior, and behavior should move into `lib/` only for real non-script reuse or existing reusable domain ownership; packaging/tests/shim neatness alone no longer justify a lib domain.
-- `[Context]` Polished domain ownership headers after the file moves so command templates, actor messages, rooms, recipe context, inspector previews, and mailbox loops describe their actual reasons to change without generic helper wording.
-- `[Domains]` Renamed generic `output.ts` to `execution-output.ts` so registered-tool stdout/stderr truncation and temp artifact formatting are tied to the execution domain instead of a broad output bucket.
-- `[Domains]` Renamed the recipe domain family from singular `recipe-*` to plural `recipes-*` (`recipes-references.ts`, `recipes-discovery.ts`, `recipes-usage.ts`, `recipes-context.ts`) to match the `tools-*` and `runs-*` family convention.
-- `[Tests]` Extended installed-package contract coverage to assert stale renamed lib domains are absent from `dist/lib`, keeping packaged JS output aligned with the current domain names.
+- `[Domains]` Compressed the actor kernel into explicit domain families: `tools.ts` remains the public tool-family owner while `tools-*` owns message, inspect, spawn, register, local execution, response, access, and mailbox-contract behavior; `async-runs.ts` remains the lifecycle facade while `runs-*` owns artifacts, mailbox, process control, delivery, outbox, index, retention, status, start guards, and identity internals.
+- `[Domains]` Removed redundant internal `actor-` prefixes and renamed the recipe family to plural `recipes-*`, leaving public actor-named recipe/script/docs surfaces intact while making core library ownership match the `tools-*` and `runs-*` convention.
+- `[Scripts]` Collapsed script-only runner, worker, validator, recipe-utils, locker, and coordinator library shims back into their owning `scripts/*.mjs` entrypoints; reusable lifecycle, room, mailbox-loop, command-template, and recipe-reference primitives remain in `lib/`.
+- `[Context]` Reversed the thin-script default, polished ownership headers, and kept completed script-autonomy/domain-compression work in the changelog instead of the backlog.
+- `[Tests]` Mirrored renamed domains in test filenames and extended installed-package contract coverage to ensure stale renamed lib domains are absent from `dist/lib` while packaged JS-only script execution still works.
 
 ## 0.33.0: Signal-First Compatibility Pruning
 

package/dist/lib/tools-message.js

@@ -101,6 +101,73 @@ function getRoomMulticastRecipients(message, run) {
         return Messages.formatActorAddress(parsed);
     });
 }
+function normalizeDeliveryOutcome(address, result) {
+    if (result.reason)
+        return result;
+    if (address.kind === "run") {
+        if (result.stopped === true) {
+            return {
+                ...result,
+                consumer: "run-control",
+                delivered: true,
+                persisted: true,
+                reason: "control_applied",
+            };
+        }
+        return {
+            ...result,
+            consumer: result.control_type ?? result.control ?? "run-control",
+            delivered: result.sent === true && result.queued !== true,
+            persisted: true,
+            reason: result.delivery_error
+                ? "delivery_failed_persisted"
+                : result.queued === true
+                    ? "queued_mailbox"
+                    : "delivered",
+        };
+    }
+    if (address.kind === "branch") {
+        return {
+            ...result,
+            consumer: "branch-mailbox",
+            delivered: result.sent === true,
+            persisted: true,
+            reason: result.delivery_error
+                ? "branch_persisted_parent_unavailable"
+                : "branch_persisted_forwarded",
+        };
+    }
+    if (address.kind === "room") {
+        return {
+            ...result,
+            consumer: "room-timeline",
+            delivered: true,
+            forwarded: Number(result.multicast_count ?? 0) > 0,
+            persisted: true,
+            reason: "room_persisted",
+        };
+    }
+    if (address.kind === "tool") {
+        return {
+            ...result,
+            consumer: "tool",
+            delivered: true,
+            persisted: false,
+            reason: "tool_invoked",
+        };
+    }
+    if (address.kind === "coordinator" || address.kind === "session") {
+        return {
+            ...result,
+            consumer: "run-outbox",
+            delivered: false,
+            persisted: true,
+            queued: true,
+            reason: `${address.kind}_outbox_persisted`,
+        };
+    }
+    return result;
+}
 function actorMessageNextActions(message, result) {
     const actions = [];
     const address = Messages.parseActorAddress(message.to);
@@ -132,8 +199,18 @@ function compactActorMessageResult(message, result) {
     ];
     if (result.bytes !== undefined)
         tokens.push(`bytes=${String(result.bytes)}`);
+    if (result.delivered !== undefined)
+        tokens.push(`delivered=${String(result.delivered)}`);
     if (result.queued === true)
         tokens.push("queued=true");
+    if (result.persisted !== undefined)
+        tokens.push(`persisted=${String(result.persisted)}`);
+    if (result.forwarded !== undefined)
+        tokens.push(`forwarded=${String(result.forwarded)}`);
+    if (result.consumer)
+        tokens.push(`consumer=${String(result.consumer)}`);
+    if (result.reason)
+        tokens.push(`reason=${String(result.reason)}`);
     if (result.control)
         tokens.push(`control=${String(result.control)}`);
     if (result.outbox)
@@ -252,13 +329,17 @@ export function createActorMessageToolDefinition(deps = {}) {
                     throw new Error(`${message.to} has no run state directory.`);
                 const recipients = getRoomMulticastRecipients(message, runId);
                 const roomResult = Rooms.appendRoomMessage(stateDir, address.room, message);
-                await Promise.all(recipients.map((recipient) => routeBranchEnvelope(stateDir, runId, recipient, message, {
+                const multicastResults = await Promise.all(recipients.map(async (recipient) => normalizeDeliveryOutcome({ kind: "branch", branch: recipient.split("/").at(-1), value: runId }, await routeBranchEnvelope(stateDir, runId, recipient, message, {
                     source: "room-multicast",
-                })));
+                }))));
                 result = {
                     ...roomResult,
                     ...(recipients.length > 0
-                        ? { multicast: recipients, multicast_count: recipients.length }
+                        ? {
+                            multicast: recipients,
+                            multicast_count: recipients.length,
+                            multicast_results: multicastResults,
+                        }
                         : {}),
                 };
             }
@@ -328,6 +409,7 @@ export function createActorMessageToolDefinition(deps = {}) {
             else {
                 throw new Error(`message currently supports run:<id>, branch:<run>/<branch>, room:<run>, tool:<name>, coordinator, and session:<id> destinations; unsupported destination: ${message.to}`);
             }
+            result = normalizeDeliveryOutcome(address, result);
             const nextActions = actorMessageNextActions(message, result);
             const resultWithNext = nextActions.length
                 ? { ...result, next_actions: nextActions }

package/dist/scripts/actor-worker.mjs

@@ -137,7 +137,11 @@ export async function runActorWorker(argv = process.argv.slice(2)) {
     { display: branch, role: "worker", status: "present" },
     `${branch} joined as mailbox worker`,
   );
-  room("awaiting_assignment", `${branch} awaiting assignment`, { branch });
+  room("awaiting_assignment", `${branch} awaiting assignment`, {
+    branch,
+    stale_claim_ms: staleClaimMs,
+    stale_claims: staleClaims(),
+  });
   journal("worker.started", {
     artifact_dir: artifactDir,
     branch,

package/dist/skills/actors/SKILL.md

@@ -2,7 +2,7 @@
 name: actors
 description: Required practical guide for non-trivial pi-actors use. Read before using or changing spawn, message, inspect, actor runs, tools, recipes, command templates, async lifecycle, mailboxes, artifacts, and local orchestration mechanics.
 metadata:
-  version: 0.34.0
+  version: 0.34.1
 ---
 
 # Actors (pi-actors)

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.34.0
+  version: 0.34.1
 ---
 
 # Swarm

package/lib/tools-message.ts

@@ -144,6 +144,76 @@ function getRoomMulticastRecipients(
   });
 }
 
+function normalizeDeliveryOutcome(
+  address: Messages.ActorAddress,
+  result: Record<string, unknown>,
+): Record<string, unknown> {
+  if (result.reason) return result;
+  if (address.kind === "run") {
+    if (result.stopped === true) {
+      return {
+        ...result,
+        consumer: "run-control",
+        delivered: true,
+        persisted: true,
+        reason: "control_applied",
+      };
+    }
+    return {
+      ...result,
+      consumer: result.control_type ?? result.control ?? "run-control",
+      delivered: result.sent === true && result.queued !== true,
+      persisted: true,
+      reason: result.delivery_error
+        ? "delivery_failed_persisted"
+        : result.queued === true
+          ? "queued_mailbox"
+          : "delivered",
+    };
+  }
+  if (address.kind === "branch") {
+    return {
+      ...result,
+      consumer: "branch-mailbox",
+      delivered: result.sent === true,
+      persisted: true,
+      reason: result.delivery_error
+        ? "branch_persisted_parent_unavailable"
+        : "branch_persisted_forwarded",
+    };
+  }
+  if (address.kind === "room") {
+    return {
+      ...result,
+      consumer: "room-timeline",
+      delivered: true,
+      forwarded: Number(result.multicast_count ?? 0) > 0,
+      persisted: true,
+      reason: "room_persisted",
+    };
+  }
+  if (address.kind === "tool") {
+    return {
+      ...result,
+      consumer: "tool",
+      delivered: true,
+      persisted: false,
+      reason: "tool_invoked",
+    };
+  }
+  if (address.kind === "coordinator" || address.kind === "session") {
+    return {
+      ...result,
+      consumer: "run-outbox",
+      delivered: false,
+      persisted: true,
+      queued: true,
+      reason: `${address.kind}_outbox_persisted`,
+    };
+  }
+  return result;
+}
+
 function actorMessageNextActions(
   message: Messages.ActorMessage,
   result: Record<string, unknown>,
@@ -183,7 +253,15 @@ function compactActorMessageResult(
     `message=${result.sent === true || result.stopped === true ? "sent" : "not_sent"}`,
   ];
   if (result.bytes !== undefined) tokens.push(`bytes=${String(result.bytes)}`);
+  if (result.delivered !== undefined)
+    tokens.push(`delivered=${String(result.delivered)}`);
   if (result.queued === true) tokens.push("queued=true");
+  if (result.persisted !== undefined)
+    tokens.push(`persisted=${String(result.persisted)}`);
+  if (result.forwarded !== undefined)
+    tokens.push(`forwarded=${String(result.forwarded)}`);
+  if (result.consumer) tokens.push(`consumer=${String(result.consumer)}`);
+  if (result.reason) tokens.push(`reason=${String(result.reason)}`);
   if (result.control) tokens.push(`control=${String(result.control)}`);
   if (result.outbox) tokens.push(`messages=${String(result.outbox)}`);
   if (result.message_count !== undefined)
@@ -364,17 +442,24 @@ export function createActorMessageToolDefinition<TContext = unknown>(
           address.room,
           message,
         );
-        await Promise.all(
-          recipients.map((recipient) =>
-            routeBranchEnvelope(stateDir, runId, recipient, message, {
-              source: "room-multicast",
-            }),
+        const multicastResults = await Promise.all(
+          recipients.map(async (recipient) =>
+            normalizeDeliveryOutcome(
+              { kind: "branch", branch: recipient.split("/").at(-1), value: runId },
+              await routeBranchEnvelope(stateDir, runId, recipient, message, {
+                source: "room-multicast",
+              }),
+            ),
           ),
         );
         result = {
           ...roomResult,
           ...(recipients.length > 0
-            ? { multicast: recipients, multicast_count: recipients.length }
+            ? {
+                multicast: recipients,
+                multicast_count: recipients.length,
+                multicast_results: multicastResults,
+              }
             : {}),
         };
       } else if (address.kind === "tool" && address.value) {
@@ -461,6 +546,7 @@ export function createActorMessageToolDefinition<TContext = unknown>(
           `message currently supports run:<id>, branch:<run>/<branch>, room:<run>, tool:<name>, coordinator, and session:<id> destinations; unsupported destination: ${message.to}`,
         );
       }
+      result = normalizeDeliveryOutcome(address, result);
       const nextActions = actorMessageNextActions(message, result);
       const resultWithNext = nextActions.length
         ? { ...result, next_actions: nextActions }

package/package.json

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

package/scripts/actor-worker.mjs

@@ -137,7 +137,11 @@ export async function runActorWorker(argv = process.argv.slice(2)) {
     { display: branch, role: "worker", status: "present" },
     `${branch} joined as mailbox worker`,
   );
-  room("awaiting_assignment", `${branch} awaiting assignment`, { branch });
+  room("awaiting_assignment", `${branch} awaiting assignment`, {
+    branch,
+    stale_claim_ms: staleClaimMs,
+    stale_claims: staleClaims(),
+  });
   journal("worker.started", {
     artifact_dir: artifactDir,
     branch,

package/skills/actors/SKILL.md

@@ -2,7 +2,7 @@
 name: actors
 description: Required practical guide for non-trivial pi-actors use. Read before using or changing spawn, message, inspect, actor runs, tools, recipes, command templates, async lifecycle, mailboxes, artifacts, and local orchestration mechanics.
 metadata:
-  version: 0.34.0
+  version: 0.34.1
 ---
 
 # Actors (pi-actors)

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.34.0
+  version: 0.34.1
 ---
 
 # Swarm