@llblab/pi-actors 0.27.1 → 0.28.0

package/BACKLOG.md

@@ -247,18 +247,21 @@ The backlog is intentionally pruned to the 20% of work most likely to deliver 80
   - Coordinator/session status exposes other-session counts without leaking unrelated run details by default.
   - Tests cover version inspection, session mismatch shape, and other-session count summaries.
 
-### M-13 Shadowed Recipe Launch UX
+### M-13 Shadowed Recipe Launch Diagnostics
 
 - Priority: High.
-- Status: Planned.
-- Goal: Make broken user recipes that shadow packaged/ad hoc candidates obvious at launch time.
+- Status: Done.
+- Goal: Make broken user recipes that shadow packaged/ad hoc candidates obvious only at the moment a launch already fails.
 - Why now: 0.26 dogfood found a broken `~/.pi/agent/recipes/actor-worker.json` shadowing the packaged `actor-worker`; Recipe Doctor exposed the evidence, but the launch path did not provide a direct hint.
 - Direction:
+  - Treat shadowing as a normal, intentional override mechanism; do not warn on healthy shadowing.
   - When recipe resolution or launch fails because the active user recipe is invalid/disabled and a lower-priority candidate exists, surface `reason=shadowed_invalid` or `reason=shadowed_disabled` where practical.
-  - Include active path, blocked candidate path, and compact hint: `inspect target=recipes view=doctor`.
-  - Keep remediation advisory only; do not auto-disable, delete, or rewrite user recipes.
+  - Treat disabled template recipes as non-launchable so disabled shadowing fails consistently instead of silently executing.
+  - Include minimal compact tokens: active path, blocked candidate path, and `hint=inspect_recipes_doctor`.
+  - Keep remediation advisory only; do not auto-disable, delete, rewrite, or nag about user recipes.
 - Acceptance:
-  - Launch failures caused by shadowing include a compact actionable hint.
+  - Healthy user overrides remain silent.
+  - Launch failures caused by invalid/disabled shadowing include a compact actionable hint.
   - Verbose details expose the active broken recipe and blocked fallback candidate.
   - Tests cover invalid and disabled user recipes shadowing a packaged candidate.
 
@@ -306,5 +309,5 @@ These are valid ideas but not current focus. Reintroduce only with concrete evid
 ## Suggested Milestone Order
 
 ```text
-Next milestone: M-13 Shadowed Recipe Launch UX.
+Next milestone: M-14 Session Mismatch Follow-through.
 ```

package/CHANGELOG.md

@@ -2,10 +2,17 @@
 
 ## Unreleased
 
+## 0.28.0: Shadowed Recipe Launch Diagnostics
+
+- `[Spawn]` Added minimal shadowed-recipe diagnostics when a bare recipe launch already fails because an invalid or disabled higher-priority recipe blocks a lower-priority fallback; healthy recipe overrides remain silent.
+- `[Async Runs]` Treat disabled template recipes as non-launchable so disabled shadowing fails consistently instead of silently executing.
+- `[Docs]` Clarified the quiet shadowing contract, disabled recipe launch behavior, and recipe-doctor hint path.
+- `[Backlog]` Reframed shadowed recipe launch diagnostics as diagnostic-on-failure only, preserving shadowing as an intentional user override mechanism without startup warnings or automatic remediation.
+
 ## 0.27.1: Changelog and Backlog Hotfix
 
 - `[Changelog]` Moved the 0.27.0 runtime/session observability notes out of `Unreleased` into a proper release section so published package history matches the npm/tag release.
-- `[Backlog]` Marked M-12 complete and added the next evidence-backed candidates for shadowed recipe launch UX, session mismatch follow-through, and worker stale-claim dogfood.
+- `[Backlog]` Marked runtime/session observability complete and added the next evidence-backed candidates for shadowed recipe launch UX, session mismatch follow-through, and worker stale-claim dogfood.
 
 ## 0.27.0: Runtime and Session Observability UX
 

package/dist/lib/async-runs.js

@@ -164,6 +164,9 @@ function readRecipeFile(file) {
     if (!config) {
         throw new Error(`Template recipe must define template: ${path}`);
     }
+    if (config.disabled === true) {
+        throw new Error(`Template recipe is disabled: ${path}`);
+    }
     return {
         ...config,
         file: path,

package/dist/lib/recipe-discovery.d.ts

@@ -46,5 +46,6 @@ export interface RecipeDiscoverySource {
 export declare function discoverRecipeSources(sources: RecipeDiscoverySource[]): RecipeDiscoveryResult;
 export declare function discoverRecipes(roots: string[]): RecipeDiscoveryResult;
 export declare function createRecipeIntegrityManifest(result: RecipeDiscoveryResult): RecipeIntegrityManifestEntry[];
+export declare function getShadowedLaunchDiagnostic(result: RecipeDiscoveryResult, id: string): Record<string, unknown> | undefined;
 export declare function summarizeDiscovery(result: RecipeDiscoveryResult): Record<string, unknown>;
 export declare function toRegisteredTool(entry: DiscoveredRecipe): RegisteredTool | undefined;

package/dist/lib/recipe-discovery.js

@@ -413,6 +413,19 @@ function recommendationForEntry(entry, activePath) {
     }
     return recommendation;
 }
+export function getShadowedLaunchDiagnostic(result, id) {
+    const active = result.active.get(id.trim());
+    if (!active || active.shadows.length === 0)
+        return undefined;
+    if (!active.invalid && !active.disabled)
+        return undefined;
+    return {
+        active_path: active.path,
+        blocked_candidate: active.shadows[0],
+        hint: "inspect_recipes_doctor",
+        reason: active.invalid ? "shadowed_invalid" : "shadowed_disabled",
+    };
+}
 export function summarizeDiscovery(result) {
     const recommendations = result.entries
         .map((entry) => recommendationForEntry(entry, result.active.get(entry.id)?.path))

package/dist/lib/tools.js

@@ -572,6 +572,25 @@ function formatToolActorFailure(tool, message, params, error) {
         tool,
     });
 }
+function shadowedRecipeLaunchDiagnostic(recipe) {
+    if (typeof recipe !== "string" || recipe.includes("/") || recipe.includes("~"))
+        return undefined;
+    const discovery = RecipeDiscovery.discoverRecipeSources([
+        { root: Paths.getRecipeRoot(), defaultTool: true, mutableUsage: true },
+        { root: Paths.getPackagedRecipeRoot(), defaultTool: false },
+    ]);
+    return RecipeDiscovery.getShadowedLaunchDiagnostic(discovery, recipe);
+}
+function enhanceSpawnRecipeError(error, recipe) {
+    const diagnostic = shadowedRecipeLaunchDiagnostic(recipe);
+    if (!diagnostic)
+        return error instanceof Error ? error : new Error(String(error));
+    const original = error instanceof Error ? error.message : String(error);
+    return Object.assign(new Error(`${original} reason=${diagnostic.reason} active_path=${diagnostic.active_path} blocked_candidate=${diagnostic.blocked_candidate} hint=${diagnostic.hint}`), {
+        ...diagnostic,
+        original_error: original,
+    });
+}
 function runIdFromActorAddress(address) {
     if (!address)
         return undefined;
@@ -654,30 +673,37 @@ export function createSpawnToolDefinition() {
         async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
             const input = asRecord(params);
             const runId = runIdFromActorAddress(typeof input.as === "string" ? input.as : undefined);
-            const meta = AsyncRuns.startRun({
-                file: typeof input.file === "string"
-                    ? input.file
-                    : typeof input.recipe === "string"
-                        ? input.recipe
-                        : undefined,
-                launch_source: "spawn",
-                ownerId: getRunOwnerId(ctx),
-                run_id: runId,
-                state_dir: typeof input.state_dir === "string" ? input.state_dir : undefined,
-                ...(input.template !== undefined
-                    ? {
-                        template: input.template,
-                    }
-                    : {}),
-                values: asRecord(input.values),
-                ...(input.artifacts &&
-                    typeof input.artifacts === "object" &&
-                    !Array.isArray(input.artifacts)
-                    ? {
-                        artifacts: input.artifacts,
-                    }
-                    : {}),
-            }, ctx.cwd);
+            const recipe = typeof input.file === "string"
+                ? input.file
+                : typeof input.recipe === "string"
+                    ? input.recipe
+                    : undefined;
+            let meta;
+            try {
+                meta = AsyncRuns.startRun({
+                    file: recipe,
+                    launch_source: "spawn",
+                    ownerId: getRunOwnerId(ctx),
+                    run_id: runId,
+                    state_dir: typeof input.state_dir === "string" ? input.state_dir : undefined,
+                    ...(input.template !== undefined
+                        ? {
+                            template: input.template,
+                        }
+                        : {}),
+                    values: asRecord(input.values),
+                    ...(input.artifacts &&
+                        typeof input.artifacts === "object" &&
+                        !Array.isArray(input.artifacts)
+                        ? {
+                            artifacts: input.artifacts,
+                        }
+                        : {}),
+                }, ctx.cwd);
+            }
+            catch (error) {
+                throw enhanceSpawnRecipeError(error, recipe);
+            }
             ActorRooms.ensureDefaultRoom(meta.state_dir, String(meta.run));
             ActorRooms.writeCommunicationSnapshot(meta.state_dir, String(meta.run));
             return {

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.27.1
+  version: 0.28.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.27.1
+  version: 0.28.0
 ---
 
 # Swarm

package/docs/template-recipes.md

@@ -105,7 +105,7 @@ Recipe priority only matters when two discovered recipes have the same filename
 
 The high-priority user recipe directory is also the default tool set: recipes placed there are agent tools by location. This preserves the old advantage of a tool-only registry because listing `~/.pi/agent/recipes` shows the operator-managed tool surface. Packaged and ad hoc recipes are recipe components by default; they become tools only when copied or registered into the agent recipe root.
 
-Higher-priority files shadow lower-priority files with the same basename. Within one priority layer, same-id JSON shadows Markdown because JSON is the canonical precise format. A highest-priority invalid recipe is still visible and blocks fallback so operators do not accidentally run packaged behavior when a user override is broken. A highest-priority recipe with `disabled: true` also blocks fallback and intentionally disables that id.
+Higher-priority files shadow lower-priority files with the same basename. Within one priority layer, same-id JSON shadows Markdown because JSON is the canonical precise format. A highest-priority invalid recipe is still visible and blocks fallback so operators do not accidentally run packaged behavior when a user override is broken. A highest-priority recipe with `disabled: true` also blocks fallback, is not launchable, and intentionally disables that id. Healthy overrides are silent; failed bare-name launches caused by invalid or disabled shadowing include compact `reason=shadowed_invalid` or `reason=shadowed_disabled` diagnostics with the active path, blocked candidate, and recipe-doctor hint.
 
 ## Usage Metadata
 

package/docs/tool-registry.md

@@ -32,6 +32,8 @@ inspect target=recipes view=summary verbose=true
 
 The recipe 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.
 
+Routine shadowing is quiet. If a bare `spawn` recipe launch already fails because an invalid or `disabled: true` user recipe blocks a lower-priority candidate, the launch error adds compact tokens such as `reason=shadowed_invalid` or `reason=shadowed_disabled`, `active_path`, `blocked_candidate`, and `hint=inspect_recipes_doctor`.
+
 ## Registering Tools
 
 `register_tool` is the interactive API for listing, creating, updating, or deleting persistent tools. Call it without arguments to list registered tools.

package/lib/async-runs.ts

@@ -318,6 +318,9 @@ function readRecipeFile(file: string): AsyncRunStartParams {
   if (!config) {
     throw new Error(`Template recipe must define template: ${path}`);
   }
+  if (config.disabled === true) {
+    throw new Error(`Template recipe is disabled: ${path}`);
+  }
   return {
     ...(config as AsyncRunStartParams),
     file: path,

package/lib/recipe-discovery.ts

@@ -473,7 +473,8 @@ function remediationForEntry(
       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",
+      action:
+        "fix recipe syntax/config, or disable/delete/archive it to restore fallback",
     };
   }
   if (entry.disabled && entry.active) {
@@ -486,7 +487,8 @@ function remediationForEntry(
       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",
+      action:
+        "keep disabled intentionally, re-enable, or delete/archive the file",
     };
   }
   if (riskyDiagnostics.length > 0) {
@@ -496,7 +498,8 @@ function remediationForEntry(
       severity: "warning",
       path: entry.path,
       reason: riskyDiagnostics[0],
-      action: "audit trusted command boundary; keep only if the recipe is local and intentional",
+      action:
+        "audit trusted command boundary; keep only if the recipe is local and intentional",
     };
   }
   if (entry.shadowed) {
@@ -557,6 +560,21 @@ function recommendationForEntry(
   return recommendation;
 }
 
+export function getShadowedLaunchDiagnostic(
+  result: RecipeDiscoveryResult,
+  id: string,
+): Record<string, unknown> | undefined {
+  const active = result.active.get(id.trim());
+  if (!active || active.shadows.length === 0) return undefined;
+  if (!active.invalid && !active.disabled) return undefined;
+  return {
+    active_path: active.path,
+    blocked_candidate: active.shadows[0],
+    hint: "inspect_recipes_doctor",
+    reason: active.invalid ? "shadowed_invalid" : "shadowed_disabled",
+  };
+}
+
 export function summarizeDiscovery(
   result: RecipeDiscoveryResult,
 ): Record<string, unknown> {

package/lib/tools.ts

@@ -710,6 +710,33 @@ function formatToolActorFailure(
   );
 }
 
+function shadowedRecipeLaunchDiagnostic(
+  recipe: unknown,
+): Record<string, unknown> | undefined {
+  if (typeof recipe !== "string" || recipe.includes("/") || recipe.includes("~"))
+    return undefined;
+  const discovery = RecipeDiscovery.discoverRecipeSources([
+    { root: Paths.getRecipeRoot(), defaultTool: true, mutableUsage: true },
+    { root: Paths.getPackagedRecipeRoot(), defaultTool: false },
+  ]);
+  return RecipeDiscovery.getShadowedLaunchDiagnostic(discovery, recipe);
+}
+
+function enhanceSpawnRecipeError(error: unknown, recipe: unknown): Error {
+  const diagnostic = shadowedRecipeLaunchDiagnostic(recipe);
+  if (!diagnostic) return error instanceof Error ? error : new Error(String(error));
+  const original = error instanceof Error ? error.message : String(error);
+  return Object.assign(
+    new Error(
+      `${original} reason=${diagnostic.reason} active_path=${diagnostic.active_path} blocked_candidate=${diagnostic.blocked_candidate} hint=${diagnostic.hint}`,
+    ),
+    {
+      ...diagnostic,
+      original_error: original,
+    },
+  );
+}
+
 function runIdFromActorAddress(
   address: string | undefined,
 ): string | undefined {
@@ -845,39 +872,45 @@ export function createSpawnToolDefinition<
       const runId = runIdFromActorAddress(
         typeof input.as === "string" ? input.as : undefined,
       );
-      const meta = AsyncRuns.startRun(
-        {
-          file:
-            typeof input.file === "string"
-              ? input.file
-              : typeof input.recipe === "string"
-                ? input.recipe
-                : undefined,
-          launch_source: "spawn",
-          ownerId: getRunOwnerId(ctx),
-          run_id: runId,
-          state_dir:
-            typeof input.state_dir === "string" ? input.state_dir : undefined,
-          ...(input.template !== undefined
-            ? {
-                template:
-                  input.template as AsyncRuns.AsyncRunStartParams["template"],
-              }
-            : {}),
-          values: asRecord(input.values),
-          ...(input.artifacts &&
-          typeof input.artifacts === "object" &&
-          !Array.isArray(input.artifacts)
-            ? {
-                artifacts: input.artifacts as Record<
-                  string,
-                  AsyncRuns.RunArtifactDeclaration
-                >,
-              }
-            : {}),
-        },
-        ctx.cwd,
-      );
+      const recipe =
+        typeof input.file === "string"
+          ? input.file
+          : typeof input.recipe === "string"
+            ? input.recipe
+            : undefined;
+      let meta: AsyncRuns.AsyncRunMeta;
+      try {
+        meta = AsyncRuns.startRun(
+          {
+            file: recipe,
+            launch_source: "spawn",
+            ownerId: getRunOwnerId(ctx),
+            run_id: runId,
+            state_dir:
+              typeof input.state_dir === "string" ? input.state_dir : undefined,
+            ...(input.template !== undefined
+              ? {
+                  template:
+                    input.template as AsyncRuns.AsyncRunStartParams["template"],
+                }
+              : {}),
+            values: asRecord(input.values),
+            ...(input.artifacts &&
+            typeof input.artifacts === "object" &&
+            !Array.isArray(input.artifacts)
+              ? {
+                  artifacts: input.artifacts as Record<
+                    string,
+                    AsyncRuns.RunArtifactDeclaration
+                  >,
+                }
+              : {}),
+          },
+          ctx.cwd,
+        );
+      } catch (error) {
+        throw enhanceSpawnRecipeError(error, recipe);
+      }
       ActorRooms.ensureDefaultRoom(meta.state_dir, String(meta.run));
       ActorRooms.writeCommunicationSnapshot(meta.state_dir, String(meta.run));
       return {

package/package.json

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

package/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.27.1
+  version: 0.28.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.27.1
+  version: 0.28.0
 ---
 
 # Swarm