@llblab/pi-actors 0.34.0 → 0.35.0

package/BACKLOG.md

@@ -53,55 +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.
-- Status: Planned.
-- Goal: Make successful ad hoc actor patterns easy to promote manually from draft memory into active user recipe memory.
-- Why now: Draft recipes under `~/.pi/agent/recipes/drafts` are replayable but intentionally not active tools, and the two-stage memory model needs an explicit operator-gated promotion path.
-- Direction:
-  - List draft recipes with source run, timestamp, fingerprint, description/template preview, and validation status.
-  - Promote a selected draft to `~/.pi/agent/recipes/<name>.json` only through an explicit action or explicit tool argument.
-  - Run recipe validation/doctor before writing and expose collision/shadowing diagnostics.
-  - Preserve draft files unless deletion is explicitly requested.
-  - Prefer extending existing registry/tool surfaces over adding a new public noun.
-- Acceptance:
-  - Draft recipes remain non-tools until promotion.
-  - Promotion writes atomically and never auto-promotes.
-  - Tests cover valid promotion, invalid draft, name collision, and packaged-recipe shadowing.
-  - Docs explain draft memory vs active tool memory in one compact section.
-
 ### M-19 Recipe Doctor Risk Labels v2
 
 - Priority: Medium.
@@ -185,7 +136,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-19 Recipe Doctor Risk Labels v2.
+Then: M-20 Runtime Recipe Triage.
 Small cleanup lane: continue opportunistic domain polish only when a real ownership boundary appears.
 ```

package/CHANGELOG.md

@@ -1,27 +1,24 @@
 # Changelog
 
+## Unreleased
+
+## 0.35.0: Draft Recipe Promotion UX
+
+- `[Recipes]` Completed M-18 Draft Recipe Promotion UX: `inspect target=recipes view=summary verbose=true` now exposes draft timestamps, fingerprints, validation state, source run when known, and template previews, while `register_tool name=<tool> draft=<path>` promotes a validated draft into active recipe memory without deleting the draft and rejects collisions unless `update=true` is explicit.
+
+## 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/README.md

@@ -207,7 +207,8 @@ Rules:
 - User recipes override same-name lower-priority recipes;
 - Same-id JSON recipes shadow Markdown recipes in the same priority layer;
 - Packaged recipes are standard-library components, not automatically installed operator policy;
-- `register_tool` creates, updates, lists, or deletes user recipe files through the normal agent interface.
+- Draft recipes in `~/.pi/agent/recipes/drafts/` are replayable memory, not active tools;
+- `register_tool` creates, updates, lists, deletes, or explicitly promotes draft recipe files through the normal agent interface.
 
 Example foreground tool:
 
@@ -226,6 +227,14 @@ register_tool name=docs_review \
   args="scope:path,model:string"
 ```
 
+Promote a successful captured draft only after an explicit operator decision:
+
+```text
+register_tool name=docs_review draft=~/.pi/agent/recipes/drafts/spawned-run.json
+```
+
+Promotion validates the draft, writes `~/.pi/agent/recipes/<name>.json`, preserves the draft, and rejects collisions unless `update=true` is supplied.
+
 Inspect the discovered registry:
 
 ```text

package/dist/lib/prompts.d.ts

@@ -10,6 +10,7 @@ export declare const ONBOARDING_SYSTEM_PROMPT = "pi-actors quick model:\n- Local
 export declare const REGISTER_TOOL_PARAM_DESCRIPTIONS: {
     readonly name: "Tool name in snake_case (e.g., 'transcribe')";
     readonly description: "Describe what the tool does for the LLM. Required unless deleting; omitted updates keep the old description.";
+    readonly draft: "Promote a draft recipe path from ~/.pi/agent/recipes/drafts into an active named recipe under ~/.pi/agent/recipes. Requires name; use update=true to overwrite.";
     readonly async: "Set true for a co-located async template recipe. Omit for ordinary command templates or file-backed recipe references.";
     readonly state_dir: "Optional async run state directory for a co-located template recipe.";
     readonly template: "Command template with {arg} or {arg=default} placeholders, or a template recipe JSON path/name. With async, this is the co-located recipe body. Bare recipe names resolve under ~/.pi/agent/recipes. Omitted updates keep the old template. Empty string deletes the tool.";

package/dist/lib/prompts.js

@@ -30,6 +30,7 @@ export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
 export const REGISTER_TOOL_PARAM_DESCRIPTIONS = {
     name: "Tool name in snake_case (e.g., 'transcribe')",
     description: "Describe what the tool does for the LLM. Required unless deleting; omitted updates keep the old description.",
+    draft: "Promote a draft recipe path from ~/.pi/agent/recipes/drafts into an active named recipe under ~/.pi/agent/recipes. Requires name; use update=true to overwrite.",
     async: "Set true for a co-located async template recipe. Omit for ordinary command templates or file-backed recipe references.",
     state_dir: "Optional async run state directory for a co-located template recipe.",
     template: "Command template with {arg} or {arg=default} placeholders, or a template recipe JSON path/name. With async, this is the co-located recipe body. Bare recipe names resolve under ~/.pi/agent/recipes. Omitted updates keep the old template. Empty string deletes the tool.",

package/dist/lib/recipes-discovery.js

@@ -425,14 +425,39 @@ export function getShadowedLaunchDiagnostic(result, id) {
         reason: active.invalid ? "shadowed_invalid" : "shadowed_disabled",
     };
 }
+function templatePreview(value) {
+    const rendered = typeof value === "string"
+        ? value
+        : value === undefined
+            ? undefined
+            : JSON.stringify(value);
+    return rendered && rendered.length > 120
+        ? `${rendered.slice(0, 117)}...`
+        : rendered;
+}
 export function listDraftRecipes(root) {
     return listRecipeFiles(root).map((path) => {
         const id = RecipesReferences.getRecipeIdFromPath(path);
+        const bytes = readFileSync(path);
+        const stat = statSync(path);
         const config = RecipesReferences.readRawRecipeConfig(path);
+        const resolved = RecipesReferences.readResolvedRecipeConfig(path);
+        const diagnostics = getRecipeConfigDiagnostics(path, resolved);
+        const sourceRun = String(config?.description ?? "").match(/spawn run ([^\s]+)/)?.[1];
+        const preview = templatePreview(config?.template);
         return {
             id,
             path,
+            sha256: createHash("sha256").update(bytes).digest("hex"),
+            size: bytes.byteLength,
+            created_at: stat.birthtime.toISOString(),
+            modified_at: stat.mtime.toISOString(),
+            valid: Boolean(resolved),
+            diagnostics,
             ...(config?.description ? { description: config.description } : {}),
+            ...(sourceRun ? { source_run: sourceRun } : {}),
+            ...(config?.async !== undefined ? { async: config.async } : {}),
+            ...(preview ? { template_preview: preview } : {}),
         };
     });
 }

package/dist/lib/registry.d.ts

@@ -11,6 +11,7 @@ export interface RegisterToolInput {
     async?: boolean;
     state_dir?: string;
     template?: CommandTemplates.CommandTemplateValue | null;
+    draft?: string;
     args?: string;
     update?: boolean;
     values?: Record<string, unknown>;
@@ -20,6 +21,8 @@ export interface RegisterToolResultDetails {
     async?: boolean;
     config?: string;
     defaults?: Record<string, string>;
+    draft?: string;
+    promoted?: boolean;
     recipeName?: string;
     state_dir?: string;
     template?: CommandTemplates.CommandTemplateValue;

package/dist/lib/registry.js

@@ -4,7 +4,7 @@
  * Owns register/update/delete validation, persistence, runtime side effects, and result payloads
  */
 import { existsSync, mkdirSync, unlinkSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join, relative, resolve } from "node:path";
 import * as CommandTemplates from "./command-templates.js";
 import * as ExecutionOutput from "./execution-output.js";
 import { writeJsonAtomic } from "./file-state.js";
@@ -32,6 +32,62 @@ function getRecipeRoot(deps) {
 function getToolRecipePath(deps, name) {
     return join(getRecipeRoot(deps), `${name}.json`);
 }
+function assertDraftPath(deps, draft) {
+    const draftRoot = resolve(getRecipeRoot(deps), "drafts");
+    const path = resolve(draft);
+    const relation = relative(draftRoot, path);
+    if (relation === "" ||
+        relation.startsWith("..") ||
+        resolve(relation) === relation) {
+        throw new Error(ExecutionOutput.formatToolText(`Draft must be under ${draftRoot}. Use inspect target=recipes view=summary to list drafts.`));
+    }
+    if (!existsSync(path)) {
+        throw new Error(ExecutionOutput.formatToolText(`Draft not found: ${path}`));
+    }
+    return path;
+}
+function promoteDraftRecipe(name, input, ctx, deps) {
+    const draftPath = assertDraftPath(deps, String(input.draft ?? ""));
+    const targetPath = getToolRecipePath(deps, name);
+    const tools = deps.getTools();
+    const existing = tools.get(name);
+    const conflict = deps.getExternalToolConflict(name);
+    if (conflict)
+        throw new Error(ExecutionOutput.formatToolText(conflict));
+    if ((existing || existsSync(targetPath)) && !input.update) {
+        throw new Error(ExecutionOutput.formatToolText(`Tool "${name}" already registered. Use update=true to overwrite.`));
+    }
+    const config = RecipesReferences.readResolvedRecipeConfig(draftPath);
+    if (!config) {
+        const reason = RecipesReferences.diagnoseRawRecipeConfigFailure(draftPath);
+        throw new Error(ExecutionOutput.formatToolText(`Draft recipe is invalid${reason ? `: ${reason}` : "."}`));
+    }
+    const promoted = buildConfig(name, {
+        ...input,
+        description: input.description ?? config.description,
+        template: draftPath,
+    }, existing);
+    const raw = RecipesReferences.readRawRecipeConfig(draftPath);
+    mkdirSync(dirname(targetPath), { recursive: true });
+    writeJsonAtomic(targetPath, raw);
+    promoted.template = targetPath;
+    promoted.sourcePath = targetPath;
+    tools.set(name, promoted);
+    deps.registerRuntimeTool(promoted);
+    deps.notify(ctx, `Promoted draft recipe: ${name}`, "info");
+    return {
+        content: [
+            textContent(ExecutionOutput.formatToolText(`${existing ? "Updated" : "Registered"} tool "${name}" from draft recipe.`)),
+        ],
+        details: {
+            args: promoted.args,
+            config: targetPath,
+            draft: draftPath,
+            promoted: true,
+            tool: name,
+        },
+    };
+}
 function persistToolRecipe(deps, cfg) {
     const path = getToolRecipePath(deps, cfg.name);
     mkdirSync(dirname(path), { recursive: true });
@@ -173,6 +229,9 @@ export async function executeRegisterTool(params, ctx, deps) {
     if (deps.reservedToolNames.has(name)) {
         throw new Error(ExecutionOutput.formatToolText(`Reserved tool name: ${name}`));
     }
+    if (typeof input.draft === "string" && input.draft.trim()) {
+        return promoteDraftRecipe(name, input, ctx, deps);
+    }
     const templateProvided = Object.hasOwn(input, "template");
     const template = getInputTemplate(input.template);
     if (templateProvided && (template === null || template === ""))

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/lib/tools-register.js

@@ -24,6 +24,7 @@ export function createRegisterToolDefinition(deps) {
             args: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.args),
             async: booleanSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.async),
             description: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.description),
+            draft: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.draft),
             name: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.name),
             state_dir: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.state_dir),
             template: unionSchema([

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.35.0
 ---
 
 # 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.35.0
 ---
 
 # Swarm

package/docs/tool-registry.md

@@ -10,7 +10,7 @@ The registry source is location-discovered recipes, not a live tool-only JSON fi
 
 - `~/.pi/agent/recipes/*.json` and `*.md` are the highest-priority user recipe root and the operator-managed tool set.
 - Recipes in that root are tools by location.
-- `~/.pi/agent/recipes/drafts/*.json` stores captured inline-spawn draft recipes, not registered tools. Promote one by moving or copying it up one level into `~/.pi/agent/recipes`. `inspect target=recipes view=summary` reports their count, and verbose output lists their paths/descriptions for explicit replay by file path.
+- `~/.pi/agent/recipes/drafts/*.json` stores captured inline-spawn draft recipes, not registered tools. Promote one with `register_tool name=<tool_name> draft=<draft_path>` or by manually moving/copying it up one level into `~/.pi/agent/recipes`. `inspect target=recipes view=summary` reports their count, and verbose output lists their paths, timestamps, fingerprints, validation state, source run when known, descriptions, and template previews for explicit replay or promotion.
 - Packaged pi-actors recipes are the lower-priority standard library of declarative actor config components, not automatically registered tools.
 - Ad hoc recipe files outside the user recipe root are components unless explicitly registered/copied into `~/.pi/agent/recipes`.
 - Recipe identity is the filename basename; `~/.pi/agent/recipes/docs_review.json` and `docs_review.md` both have id/tool name `docs_review`.
@@ -51,7 +51,7 @@ register_tool name=call_subagent \
   template="pi -p --model {model} --no-tools {prompt}" args="prompt:string,model:string"
 ```
 
-Use `update=true` to overwrite an existing tool. Omit `template` and co-located recipe fields during update to keep the previous execution binding.
+Use `update=true` to overwrite an existing tool. Omit `template` and co-located recipe fields during update to keep the previous execution binding. To promote a captured draft, pass `name` plus `draft` with a path under `~/.pi/agent/recipes/drafts`; promotion validates the draft before writing `~/.pi/agent/recipes/<name>.json`, preserves the draft file, rejects name collisions unless `update=true`, and leaves shadowing evidence visible through `inspect target=recipes view=summary` or `view=doctor`.
 
 `template` may also be a standard command-template sequence for multi-step tools. Timeout is disabled by default; add explicit positive `timeout` values when individual steps should fail closed:
 

package/lib/prompts.ts

@@ -38,6 +38,8 @@ export const REGISTER_TOOL_PARAM_DESCRIPTIONS = {
   name: "Tool name in snake_case (e.g., 'transcribe')",
   description:
     "Describe what the tool does for the LLM. Required unless deleting; omitted updates keep the old description.",
+  draft:
+    "Promote a draft recipe path from ~/.pi/agent/recipes/drafts into an active named recipe under ~/.pi/agent/recipes. Requires name; use update=true to overwrite.",
   async:
     "Set true for a co-located async template recipe. Omit for ordinary command templates or file-backed recipe references.",
   state_dir:

package/lib/recipes-discovery.ts

@@ -574,14 +574,43 @@ export function getShadowedLaunchDiagnostic(
   };
 }
 
+function templatePreview(value: unknown): string | undefined {
+  const rendered =
+    typeof value === "string"
+      ? value
+      : value === undefined
+        ? undefined
+        : JSON.stringify(value);
+  return rendered && rendered.length > 120
+    ? `${rendered.slice(0, 117)}...`
+    : rendered;
+}
+
 export function listDraftRecipes(root: string): Array<Record<string, unknown>> {
   return listRecipeFiles(root).map((path) => {
     const id = RecipesReferences.getRecipeIdFromPath(path);
+    const bytes = readFileSync(path);
+    const stat = statSync(path);
     const config = RecipesReferences.readRawRecipeConfig(path);
+    const resolved = RecipesReferences.readResolvedRecipeConfig(path);
+    const diagnostics = getRecipeConfigDiagnostics(path, resolved);
+    const sourceRun = String(config?.description ?? "").match(
+      /spawn run ([^\s]+)/,
+    )?.[1];
+    const preview = templatePreview(config?.template);
     return {
       id,
       path,
+      sha256: createHash("sha256").update(bytes).digest("hex"),
+      size: bytes.byteLength,
+      created_at: stat.birthtime.toISOString(),
+      modified_at: stat.mtime.toISOString(),
+      valid: Boolean(resolved),
+      diagnostics,
       ...(config?.description ? { description: config.description } : {}),
+      ...(sourceRun ? { source_run: sourceRun } : {}),
+      ...(config?.async !== undefined ? { async: config.async } : {}),
+      ...(preview ? { template_preview: preview } : {}),
     };
   });
 }

package/lib/registry.ts

@@ -5,7 +5,7 @@
  */
 
 import { existsSync, mkdirSync, unlinkSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join, relative, resolve } from "node:path";
 
 import * as CommandTemplates from "./command-templates.ts";
 import * as Config from "./config.ts";
@@ -22,6 +22,7 @@ export interface RegisterToolInput {
   async?: boolean;
   state_dir?: string;
   template?: CommandTemplates.CommandTemplateValue | null;
+  draft?: string;
   args?: string;
   update?: boolean;
   values?: Record<string, unknown>;
@@ -32,6 +33,8 @@ export interface RegisterToolResultDetails {
   async?: boolean;
   config?: string;
   defaults?: Record<string, string>;
+  draft?: string;
+  promoted?: boolean;
   recipeName?: string;
   state_dir?: string;
   template?: CommandTemplates.CommandTemplateValue;
@@ -95,6 +98,93 @@ function getToolRecipePath<TContext>(
   return join(getRecipeRoot(deps), `${name}.json`);
 }
 
+function assertDraftPath<TContext>(
+  deps: RegisterToolRuntimeDeps<TContext>,
+  draft: string,
+): string {
+  const draftRoot = resolve(getRecipeRoot(deps), "drafts");
+  const path = resolve(draft);
+  const relation = relative(draftRoot, path);
+  if (
+    relation === "" ||
+    relation.startsWith("..") ||
+    resolve(relation) === relation
+  ) {
+    throw new Error(
+      ExecutionOutput.formatToolText(
+        `Draft must be under ${draftRoot}. Use inspect target=recipes view=summary to list drafts.`,
+      ),
+    );
+  }
+  if (!existsSync(path)) {
+    throw new Error(ExecutionOutput.formatToolText(`Draft not found: ${path}`));
+  }
+  return path;
+}
+
+function promoteDraftRecipe<TContext>(
+  name: string,
+  input: RegisterToolInput,
+  ctx: TContext,
+  deps: RegisterToolRuntimeDeps<TContext>,
+): RegisterToolResult {
+  const draftPath = assertDraftPath(deps, String(input.draft ?? ""));
+  const targetPath = getToolRecipePath(deps, name);
+  const tools = deps.getTools();
+  const existing = tools.get(name);
+  const conflict = deps.getExternalToolConflict(name);
+  if (conflict) throw new Error(ExecutionOutput.formatToolText(conflict));
+  if ((existing || existsSync(targetPath)) && !input.update) {
+    throw new Error(
+      ExecutionOutput.formatToolText(
+        `Tool "${name}" already registered. Use update=true to overwrite.`,
+      ),
+    );
+  }
+  const config = RecipesReferences.readResolvedRecipeConfig(draftPath);
+  if (!config) {
+    const reason = RecipesReferences.diagnoseRawRecipeConfigFailure(draftPath);
+    throw new Error(
+      ExecutionOutput.formatToolText(
+        `Draft recipe is invalid${reason ? `: ${reason}` : "."}`,
+      ),
+    );
+  }
+  const promoted = buildConfig(
+    name,
+    {
+      ...input,
+      description: input.description ?? config.description,
+      template: draftPath,
+    },
+    existing,
+  );
+  const raw = RecipesReferences.readRawRecipeConfig(draftPath)!;
+  mkdirSync(dirname(targetPath), { recursive: true });
+  writeJsonAtomic(targetPath, raw);
+  promoted.template = targetPath;
+  promoted.sourcePath = targetPath;
+  tools.set(name, promoted);
+  deps.registerRuntimeTool(promoted);
+  deps.notify(ctx, `Promoted draft recipe: ${name}`, "info");
+  return {
+    content: [
+      textContent(
+        ExecutionOutput.formatToolText(
+          `${existing ? "Updated" : "Registered"} tool "${name}" from draft recipe.`,
+        ),
+      ),
+    ],
+    details: {
+      args: promoted.args,
+      config: targetPath,
+      draft: draftPath,
+      promoted: true,
+      tool: name,
+    } as RegisterToolResultDetails & Record<string, unknown>,
+  };
+}
+
 function persistToolRecipe<TContext>(
   deps: RegisterToolRuntimeDeps<TContext>,
   cfg: Config.RegisteredTool,
@@ -284,6 +374,9 @@ export async function executeRegisterTool<TContext>(
       ExecutionOutput.formatToolText(`Reserved tool name: ${name}`),
     );
   }
+  if (typeof input.draft === "string" && input.draft.trim()) {
+    return promoteDraftRecipe(name, input, ctx, deps);
+  }
   const templateProvided = Object.hasOwn(input, "template");
   const template = getInputTemplate(input.template);
   if (templateProvided && (template === null || template === ""))

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/lib/tools-register.ts

@@ -36,6 +36,7 @@ export function createRegisterToolDefinition<TContext>(
         description: stringSchema(
           Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.description,
         ),
+        draft: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.draft),
         name: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.name),
         state_dir: stringSchema(
           Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.state_dir,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "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.35.0
 ---
 
 # 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.35.0
 ---
 
 # Swarm