@llblab/pi-actors 0.48.0 → 0.49.0

package/docs/async-runs.md

@@ -123,7 +123,7 @@ Archive and prune apply only to terminal Runs and enforce path containment. Rete
 
 Packaged controlled services demonstrate the endpoint protocol:
 
-- `media/player` consumes playback Controls and emits playback Trace;
+- `music-player/playback` consumes playback Controls and emits playback Trace;
 - `actors/resource-locker` consumes queue/lease actions, emits lock Trace, and atomically retains at most 512 valid journal records within 1 MiB.
 
 Shared archive/prune evidence similarly retains at most 256 valid records within 1 MiB under its canonical lock. The obsolete advisory `wake.jsonl` notifier was removed; filesystem watchers and bounded reconciliation observe authoritative state directly.

package/docs/recipe-library.md

@@ -34,12 +34,9 @@ Callers should own model, thinking, concurrency, quorum, and mission policy. Rev
 
 Artifact pipelines terminate in files/manifests and result evidence; they do not fabricate communication events.
 
-### Media and controlled services
+### Music playback and controlled services
 
-- `media/playlist-scan` — shallow unfiltered path inventory.
-- `media/playlist-build` — extension-filtered `paths`, `m3u`, or `inline` playlist output; it does not create a playlist file.
-- `media/library` — filtered playlist plus bounded library-report content; `artifact_path` alone is not durable-write proof.
-- `media/player` — playback service with declared playback actions, `controls.jsonl`, generation-fenced endpoint readiness, state artifact, and playback Trace. Player selection is `player:enum(auto,mpv,afplay,ffplay,cvlc,play,wmp)=auto`.
+- `music-player/playback` — singleton playback service that resolves files, directories, URLs, explicit lists, and playlist files into one persistent queue; it exposes declared playback Controls including arbitrary absolute `volume` percentages, generation-fenced endpoint readiness, structured status, a player-owned continuity checkpoint, and playback Trace. Player selection is `player:enum(auto,mpv,afplay,ffplay,cvlc,play,wmp)=auto`.
 - `actors/resource-locker` — optional queue/lease-lock service with explicit owner/resource input, lock Trace, and a 512-record/1 MiB atomically retained journal.
 
 These Recipes declare actor-local Control. Ordinary one-shot Recipes omit it. Helper-backed Skill Recipes self-locate through runtime-owned `{skill_dir}`; callers do not pass package installation roots.

package/docs/template-recipes.md

@@ -50,6 +50,7 @@ Common Recipe fields:
 - `imports` with optional binding defaults/values;
 - `template`;
 - `async`;
+- `singleton: true` for one explicit Skill-owned async service slot;
 - `artifacts`;
 - `control` for actual controlled services;
 - command-template flags such as `parallel`, `concurrency`, `min_successful`, `when`, `timeout`, `delay`, `retry`, `failure`, `recover`, `repeat`, `accept_output`, and `output`;
@@ -93,6 +94,12 @@ nested skill path    -> flatten filename or use explicit file path
 
 Removed `std:` and `skill:` forms fail with migration guidance; they are not aliases. Root packaged Recipes no longer exist. Flatten a maintained Skill component to a direct filename, or reference a nested/local file explicitly when it is intentionally outside the Skill component namespace.
 
+## Singleton Services
+
+`singleton: true` is valid only for an async Skill Recipe, and one Skill may declare at most one singleton Recipe. The runtime derives `run:<skill>` and the canonical `<skill>/<recipe>` identity, then rejects a conflicting caller-supplied Run id. A compatible repeated launch returns the healthy active generation; contradictory Recipe identity, ownership, startup values, or Control fails closed. A terminal result is never reused even during runner exit; retry after that process exits starts a fresh `run_instance_id` under the same logical Run id. Actor-owned workload continuity requires a validated state artifact that restart cleanup deliberately preserves; singleton identity alone never proves restored state.
+
+Direct Recipe delegation inherits the original singleton Run and Recipe identities, so registered tools and explicit wrappers cannot retarget the service or create parallel aliases.
+
 ## Control
 
 Only a process that consumes actor-local input declares actions:

package/docs/tool-registry.md

@@ -19,7 +19,7 @@ register_tool name=repo_check template="make check" description="Run repository
 Specialize a maintained Recipe without copying its contract:
 
 ```text
-register_tool name=music_player from=media/player defaults={"source":"~/Music/1MIX"}
+register_tool name=music_player from=music-player/playback defaults={"source":"~/Music/1MIX"}
 ```
 
 `from`, `template`, and `draft` are distinct source modes. `from` accepts exact `<skill>/<recipe>` identity or an explicit `.json` / `.md` path and inherits async behavior, args/types, source defaults, artifacts, Control, and runtime-owned origins. `defaults` may set only effective caller-owned args and must satisfy their types. `template` is only for trusted command definitions; public `values` authoring has been removed in favor of caller defaults or an authored Recipe file.
@@ -73,7 +73,7 @@ Usage and lineage live in locked metadata ledgers rather than authored Recipe fi
 
 ## Specializing Existing Recipes
 
-Use `register_tool from=<skill>/<recipe> defaults={...}` for one maintained capability under a persistent name or narrower defaults. The stored user Recipe remains compact direct delegation; it does not copy async, args/types, Control, artifacts, helpers, or runtime-owned `{recipe_dir}`/`{skill_dir}`. Named imports remain for multi-node Recipe composition, not one-source specialization. Skill Recipes remain components and are never exposed merely because their Skill is active. Install only specific capabilities; internal automatic-review Recipes must not become user-callable tools.
+Use `register_tool from=<skill>/<recipe> defaults={...}` for one maintained capability under a persistent name or narrower defaults. Pi supplies one authoritative active-session Skill snapshot across global, project, package, settings, CLI, and extension-contributed locations. Registration resolves the source from that snapshot, stores only the logical direct-delegation reference plus caller specialization, and activates the tool from the already-resolved effective contract without ambient re-resolution. It does not copy async, args/types, Control, artifacts, helpers, or runtime-owned `{recipe_dir}`/`{skill_dir}`; symlinks and absolute helper paths are not substitutes. Named imports remain for multi-node Recipe composition, not one-source specialization. Skill Recipes remain components and are never exposed merely because their Skill is active. Install only specific capabilities; internal automatic-review Recipes must not become user-callable tools.
 
 ## Safety
 

package/lib/async-runs.ts

@@ -18,6 +18,7 @@ import {
 } from "node:fs";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { isDeepStrictEqual } from "node:util";
 
 import type {
   CommandTemplateFailureScope,
@@ -124,6 +125,9 @@ export interface AsyncRunStartParams {
   name?: string;
   ownerId?: string;
   run_id?: string;
+  singleton?: boolean;
+  singleton_run_id?: string;
+  singleton_recipe_id?: string;
   state_dir?: string;
   tool?: string;
   template?: CommandTemplateValue;
@@ -187,6 +191,10 @@ export interface AsyncRunMeta {
   process_identity?: RunProcessIdentity;
   recipe_context_records?: RecipesReferences.TemplateRecipeContextRecord[];
   retire_when?: "children_terminal";
+  reused?: boolean;
+  singleton?: boolean;
+  singleton_recipe_id?: string;
+  singleton_values?: Record<string, unknown>;
   transport_context?: Record<string, unknown>;
 }
 
@@ -260,6 +268,43 @@ function assertNoActiveRunState(stateDir: string): void {
   RunsStart.assertNoActiveRunState(stateDir, readJson, RUNNER_PATH);
 }
 
+function reuseCompatibleSingletonRun(
+  stateDir: string,
+  startParams: AsyncRunStartParams,
+  singletonValues: Record<string, unknown>,
+): AsyncRunMeta | undefined {
+  const existing = RunsStart.readActiveOwnedRunState(
+    stateDir,
+    readJson,
+    RUNNER_PATH,
+  );
+  if (!existing) return undefined;
+  const compatible =
+    existing.singleton === true &&
+    existing.singleton_recipe_id === startParams.singleton_recipe_id &&
+    existing.ownerId === startParams.ownerId &&
+    isDeepStrictEqual(existing.singleton_values ?? {}, singletonValues) &&
+    isDeepStrictEqual(existing.control ?? [], startParams.control ?? []);
+  if (!compatible) {
+    throw new Error(
+      `Active singleton Run ${String(existing.run ?? stateDir)} has incompatible Recipe identity, owner, startup values, or Control contract. Stop it before changing singleton configuration.`,
+    );
+  }
+  return {
+    ...(existing as unknown as AsyncRunMeta),
+    ...(startParams.launch_source
+      ? {
+          launch_kind: startParams.launch_source,
+          launch_source: startParams.launch_source,
+        }
+      : {}),
+    ...(startParams.launch_correlation
+      ? { launch_correlation: startParams.launch_correlation }
+      : {}),
+    reused: true,
+  };
+}
+
 export interface AsyncRunStartOptions {
   skillContext?: RecipesReferences.ActiveSkillRecipeContext;
 }
@@ -326,10 +371,25 @@ function resolveStartParams(
 ): AsyncRunStartParams {
   if (!params.file) return params;
   const fileParams = readRecipeFile(params.file, cwd, options);
+  const singleton = fileParams.singleton === true;
+  if (singleton && fileParams.async !== true) {
+    throw new Error("singleton Recipes must declare async: true");
+  }
+  if (singleton && (!fileParams.singleton_run_id || !fileParams.singleton_recipe_id)) {
+    throw new Error("singleton Recipes must resolve one active Skill-owned singleton identity");
+  }
+  const singletonRun = singleton ? fileParams.singleton_run_id : undefined;
+  if (singletonRun && params.run_id && params.run_id !== singletonRun) {
+    throw new Error(
+      `singleton Recipe run identity is run:${singletonRun}; received run:${params.run_id}`,
+    );
+  }
   return {
     ...fileParams,
     ...params,
+    ...(singleton ? { singleton: true } : {}),
     run_id:
+      singletonRun ||
       params.run_id ||
       fileParams.run_id ||
       fileParams.name ||
@@ -540,14 +600,37 @@ export function startRun(
     values,
     modelPolicy,
   );
-  assertNoActiveRunState(stateDir);
+  const singletonValues = Object.fromEntries(
+    [...declaredArgs].map((key) => [key, values[key]]),
+  );
+  if (startParams.singleton !== true) assertNoActiveRunState(stateDir);
   mkdirSync(stateDir, { recursive: true });
   const releaseStartLock = acquireStateStartLock(stateDir, {
     onContention: startParams.lifecycleHooks?.onLockContention,
   });
   try {
     claimRunStateDirectory(stateDir, run);
-    assertNoActiveRunState(stateDir);
+    if (
+      recipeFile &&
+      isMutableUsageRecipeFile(recipeFile) &&
+      !RecipesUsage.recordRecipeLaunch(
+        recipeFile,
+        new Date(),
+        startParams.launch_source === "tool" ? "tool" : "spawn",
+      )
+    ) {
+      throw new Error(
+        `Recipe launch rejected because its source changed during activation: ${recipeFile}. Reload recipe tools and retry.`,
+      );
+    }
+    if (startParams.singleton === true) {
+      const existing = reuseCompatibleSingletonRun(
+        stateDir,
+        startParams,
+        singletonValues,
+      );
+      if (existing) return existing;
+    } else assertNoActiveRunState(stateDir);
     prepareStateDirForStart(stateDir);
     const stdout = join(stateDir, "stdout.log");
     const stderr = join(stateDir, "stderr.log");
@@ -572,19 +655,6 @@ export function startRun(
               : record,
           )
         : undefined;
-    if (
-      recipeFile &&
-      isMutableUsageRecipeFile(recipeFile) &&
-      !RecipesUsage.recordRecipeLaunch(
-        recipeFile,
-        new Date(),
-        startParams.launch_source === "tool" ? "tool" : "spawn",
-      )
-    ) {
-      throw new Error(
-        `Recipe launch rejected because its source changed during activation: ${recipeFile}. Reload recipe tools and retry.`,
-      );
-    }
     const outFd = openSync(stdout, "a");
     const errFd = openSync(stderr, "a");
     const argv = asyncRunnerArgv(stateDir);
@@ -635,6 +705,13 @@ export function startRun(
       ...(startParams.retire_when === "children_terminal"
         ? { retire_when: "children_terminal" as const }
         : {}),
+      ...(startParams.singleton === true
+        ? {
+            singleton: true,
+            singleton_recipe_id: startParams.singleton_recipe_id,
+            singleton_values: singletonValues,
+          }
+        : {}),
       ...(transportContext
         ? { transport_context: transportContext } : {}),
     };

package/lib/extension-runtime.ts

@@ -160,6 +160,10 @@ export function createActorExtensionRuntime(
         Tools.createCoreActorToolDefinitions<Pi.ExtensionContext>({
           configPath: Paths.EXTENSION_RUNTIME_PATHS.configPath,
           getActiveTools: () => pi.getActiveTools(),
+          getRecipeResolutionContext: () =>
+            activeRunContext
+              ? getRecipeResolutionContext(activeRunContext)
+              : undefined,
           getRuntimeTool: (name) =>
             Tools.resolveActiveRuntimeTool(
               name,

package/lib/file-state.ts

@@ -267,6 +267,19 @@ export function withFileMutationLock<T>(
   }
 }
 
+function replaceFileWithRetry(source: string, target: string): void {
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      renameSync(source, target);
+      return;
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if ((code !== "EPERM" && code !== "EBUSY") || attempt >= 19) throw error;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50);
+    }
+  }
+}
+
 export function writeTextAtomic(
   path: string,
   content: string,
@@ -277,7 +290,7 @@ export function writeTextAtomic(
   try {
     writeFileSync(tempPath, content, "utf8");
     options.onBeforeReplace?.();
-    renameSync(tempPath, path);
+    replaceFileWithRetry(tempPath, path);
   } catch (error) {
     try {
       unlinkSync(tempPath);

package/lib/inspector.ts

@@ -185,6 +185,9 @@ export function readActorInspectorRecipe(
       source_kind: primarySourceKind,
       launch_kind: meta.launch_kind ?? meta.launch_source,
       launch_source: meta.launch_source,
+      ...(meta.singleton === true
+        ? { singleton: true, singleton_recipe_id: meta.singleton_recipe_id }
+        : {}),
     }),
     launch: redactedRecord({
       cwd: meta.cwd,
@@ -195,6 +198,7 @@ export function readActorInspectorRecipe(
       artifacts: meta.artifacts,
       notification_policy: meta.notification_policy,
       retire_when: meta.retire_when,
+      singleton_values: meta.singleton_values,
     }),
   };
 }

package/lib/observability.ts

@@ -1143,17 +1143,14 @@ export function pruneRunObservationState(
 ): void {
   const activeRuns = new Set(summary.runs.map((run) => runObservationKey(run)));
   const terminalRunSet = new Set(terminalRuns);
-  const terminalLineKeys = new Set(summary.runs
-    .filter((run) => terminalRunSet.has(runObservationKey(run)))
-    .map((run) => runObservationKey(run)));
   const activeLineKeys = new Set(summary.runs.map((run) => run.stateDir ?? run.run));
   for (const run of terminalRunSet) previousStatuses.delete(run);
   for (const run of previousStatuses.keys())
     if (!activeRuns.has(run)) previousStatuses.delete(run);
   for (const key of previousLineCounts.keys())
-    if (terminalLineKeys.has(key) || !activeLineKeys.has(key)) previousLineCounts.delete(key);
+    if (!activeLineKeys.has(key)) previousLineCounts.delete(key);
   for (const key of seenEventIds.keys())
-    if (terminalLineKeys.has(key) || !activeLineKeys.has(key)) seenEventIds.delete(key);
+    if (!activeLineKeys.has(key)) seenEventIds.delete(key);
 }
 
 export function detectRunAttentionEvents(

package/lib/recipes-discovery.ts

@@ -957,7 +957,8 @@ export function summarizeRegisteredToolArgs(tool: RegisteredTool): {
   const requiredSet = new Set(required);
   const optional = publicArgs.filter((arg) => !requiredSet.has(arg));
   if (tool.recipe?.async === true) {
-    optional.push("run_id", "transport_context");
+    if (tool.recipe.singleton !== true) optional.push("run_id");
+    optional.push("transport_context");
   }
   return { optional, required };
 }

package/lib/recipes-references.ts

@@ -30,6 +30,7 @@ export type TemplateRecipeImport = string | TemplateRecipeImportBinding;
 export interface TemplateRecipeDefinition {
   description?: string;
   disabled?: boolean;
+  singleton?: boolean;
   imports?: Record<string, TemplateRecipeImport>;
   template: CommandTemplateValue;
   args?: string[];
@@ -59,6 +60,8 @@ export interface TemplateRecipeConfig extends TemplateRecipeDefinition {
   async?: boolean;
   recipe_dir?: string;
   skill_dir?: string;
+  singleton_run_id?: string;
+  singleton_recipe_id?: string;
 }
 
 interface ImportedRecipe {
@@ -1416,6 +1419,23 @@ export function readResolvedRecipeConfig(
           : delegated?.async === false
             ? { async: false }
             : {}),
+    ...(substituted.singleton === true || delegated?.singleton === true
+      ? {
+          singleton: true,
+          singleton_run_id:
+            delegated?.singleton === true
+              ? delegated.singleton_run_id
+              : skillDir
+                ? basename(skillDir)
+                : undefined,
+          singleton_recipe_id:
+            delegated?.singleton === true
+              ? delegated.singleton_recipe_id
+              : skillDir
+                ? `${basename(skillDir)}/${recipeName}`
+                : undefined,
+        }
+      : {}),
     ...(Object.keys(imports).length > 0
       ? { imports: getRecipeImports(raw) }
       : {}),

package/lib/registry.ts

@@ -73,6 +73,7 @@ export interface RegisterToolRuntimeDeps<TContext> {
   recipeRoot?: string;
   getToolNameBlocker: (name: string) => string | undefined;
   getTools: () => Map<string, Config.RegisteredTool>;
+  getRecipeResolutionContext?: () => RecipesContext.RecipeResolutionContext | undefined;
   getActiveTools: () => string[];
   notify: (
     ctx: TContext,
@@ -422,11 +423,9 @@ function getRegistrationResolutionContext<TContext>(
   ctx: TContext,
   deps: RegisterToolRuntimeDeps<TContext>,
 ): RecipesContext.RecipeResolutionContext {
-  if (
-    ctx &&
-    typeof ctx === "object" &&
-    "recipeResolutionContext" in ctx
-  ) {
+  const runtimeContext = deps.getRecipeResolutionContext?.();
+  if (runtimeContext) return runtimeContext;
+  if (ctx && typeof ctx === "object" && "recipeResolutionContext" in ctx) {
     const resolutionContext = (ctx as {
       recipeResolutionContext?: RecipesContext.RecipeResolutionContext;
     }).recipeResolutionContext;
@@ -697,9 +696,11 @@ function executeRegisterToolUnlocked<TContext>(
   let persisted = false;
   let activation: RuntimeActivation | undefined;
   let cfg: Config.RegisteredTool;
+  let transactionStage = "persist";
   try {
     persistToolRecipe(deps, name, authoredRecipe);
     persisted = true;
+    transactionStage = "persisted_admission";
     const admitted = RecipesDiscovery.admitUserRecipe(
       recipePath,
       resolutionContext,
@@ -711,6 +712,7 @@ function executeRegisterToolUnlocked<TContext>(
     }
     cfg = admitted.tool;
     tools.set(name, cfg);
+    transactionStage = "runtime_activation";
     activation = deps.registerRuntimeTool(cfg) ?? undefined;
     if (
       activation &&
@@ -737,7 +739,7 @@ function executeRegisterToolUnlocked<TContext>(
     deps.setActiveTools(activeBefore);
     throw new Error(
       ExecutionOutput.formatToolText(
-        `Tool registration transaction failed: ${error instanceof Error ? error.message : String(error)}`,
+        `Tool registration transaction failed at ${transactionStage} (${resolutionContext.generation}; active Skills: ${activeSkillSummary(resolutionContext)}): ${error instanceof Error ? error.message : String(error)}`,
       ),
     );
   }

package/lib/runs-start.ts

@@ -19,16 +19,17 @@ import {
 
 type RunJsonReader = (path: string) => Record<string, unknown> | undefined;
 
-export function assertNoActiveRunState(
+export function readActiveOwnedRunState(
   stateDir: string,
   readJson: RunJsonReader,
   _runnerPath: string,
-): void {
+): Record<string, unknown> | undefined {
   const meta = readJson(join(stateDir, "run.json"));
-  if (!meta) return;
+  if (!meta) return undefined;
+  const result = readJson(join(stateDir, "result.json"));
+  if (typeof result?.completedAt === "string") return undefined;
   const pid = Number(meta.pid || 0);
-  const cwd = String(meta.cwd ?? "");
-  if (!pid || !isAlive(pid)) return;
+  if (!pid || !isAlive(pid)) return undefined;
   const identity = verifyRunProcessIdentity(
     pid,
     meta.process_identity as RunProcessIdentity | undefined,
@@ -43,7 +44,16 @@ export function assertNoActiveRunState(
       `Run state process identity proof is unavailable: ${String(meta.run ?? stateDir)}. Refusing to reuse the state directory while pid ${pid} is alive.`,
     );
   }
-  if (identity.valid) {
+  return identity.valid ? meta : undefined;
+}
+
+export function assertNoActiveRunState(
+  stateDir: string,
+  readJson: RunJsonReader,
+  runnerPath: string,
+): void {
+  const meta = readActiveOwnedRunState(stateDir, readJson, runnerPath);
+  if (meta) {
     throw new Error(
       `Run state already has an active owned process: ${String(meta.run ?? stateDir)}. Stop it before reusing the same run_id or state_dir.`,
     );

package/lib/tools-local.ts

@@ -147,9 +147,10 @@ export function createRuntimeToolDefinition(
   const paramSchema: Record<string, JsonSchema> = {};
   const required: string[] = [];
   const isRecipe = RecipesReferences.isRecipeTool(cfg.template, cfg.recipe);
-  const isAsyncRecipe =
-    cfg.recipe?.async === true ||
-    RecipesReferences.isAsyncRecipeReference(cfg.template);
+  const isAsyncRecipe = cfg.recipe
+    ? cfg.recipe.async === true
+    : RecipesReferences.isAsyncRecipeReference(cfg.template);
+  const isSingletonRecipe = cfg.recipe?.singleton === true;
   const recipeTemplate =
     cfg.recipe?.template ?? RecipesReferences.getRecipeTemplate(cfg.template);
   const requiredTemplate = recipeTemplate ?? cfg.template!;
@@ -177,7 +178,7 @@ export function createRuntimeToolDefinition(
               !Object.hasOwn(recipeInlineDefaults, arg),
           ),
         )
-      : RecipesReferences.isRecipeReference(cfg.template) && !recipeTemplate
+      : !cfg.recipe && RecipesReferences.isRecipeReference(cfg.template) && !recipeTemplate
         ? new Set(cfg.args.filter((arg) => !Object.hasOwn(cfg.defaults, arg)))
         : Schema.getRequiredToolArgNames(requiredTemplateConfig);
   for (const arg of cfg.args) {
@@ -185,7 +186,7 @@ export function createRuntimeToolDefinition(
     paramSchema[arg] = typedArgSchema(arg, cfg.argTypes?.[arg]);
     if (requiredArgs.has(arg)) required.push(arg);
   }
-  if (isAsyncRecipe)
+  if (isAsyncRecipe && !isSingletonRecipe)
     paramSchema.run_id = Schema.stringSchema(
       "Optional run id override for this async template recipe invocation.",
     );
@@ -225,8 +226,9 @@ export function createRuntimeToolDefinition(
           const input = params as Record<string, unknown>;
           const { run_id, transport_context, ...values } = input;
           const base = cfg.recipe ? cfg.recipe : { file: String(cfg.template) };
-          const runId =
-            typeof run_id === "string" && run_id.trim()
+          const runId = isSingletonRecipe
+            ? undefined
+            : typeof run_id === "string" && run_id.trim()
               ? run_id.trim()
               : `${cfg.name}-${Date.now()}`;
           const meta = AsyncRuns.startRun(
@@ -293,7 +295,7 @@ export function createRuntimeToolDefinition(
           cfg,
           error,
           required,
-          isAsyncRecipe,
+          isAsyncRecipe && !isSingletonRecipe,
         );
       }
     },

package/lib/tools.ts

@@ -24,6 +24,7 @@ export interface CoreActorToolDefinitionDeps<
 > {
   configPath: string;
   getActiveTools: () => string[];
+  getRecipeResolutionContext: () => import("./recipes-context.ts").RecipeResolutionContext | undefined;
   getRuntimeTool: (name: string) => unknown;
   getRuntimeToolStatus: (name: string) => Record<string, unknown> | undefined;
   handleRuntimeControl?: (
@@ -68,6 +69,7 @@ export function createCoreActorToolDefinitions<
       getActiveTools: deps.getActiveTools,
       getToolNameBlocker: deps.registryRuntime.getToolNameBlocker,
       getTools: deps.registryRuntime.getTools,
+      getRecipeResolutionContext: deps.getRecipeResolutionContext,
       notify: deps.registryRuntime.notify,
       registerRuntimeTool: deps.registryRuntime.registerRuntimeTool,
       reservedToolNames: RESERVED_TOOL_NAMES,

package/package.json

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

package/skills/actors/SKILL.md

@@ -52,18 +52,18 @@ direct delegation ≠ named import composition
 Run Control ≠ actor chat
 ```
 
-A Skill Recipe is a maintained component addressed by `<skill>/<recipe>`. `spawn` creates a Run from a Recipe. `register_tool` creates or updates a persistent user tool. A tool is callable in the current session only when activation evidence says `callable_now: true`.
+A Skill Recipe is a maintained component addressed by `<skill>/<recipe>`. `spawn` creates a Run from a Recipe. `register_tool from=<skill>/<recipe>` persists compact logical delegation and activates from the resolved effective contract without copying, symlinking, or ambient re-resolution. A tool is callable in the current session only when activation evidence says `callable_now: true`.
 
 `actors` owns generic Recipe/tool/Run mechanics. The owning capability Skill owns capability-specific selection and constraints. `swarm` owns multi-actor decomposition and integration methodology.
 
 ## Persistent capability workflow
 
-To make `media/player` callable as `music_player` with a default source:
+To make `music-player/playback` callable as `music_player` with a default source:
 
 ```text
 register_tool
   name=music_player
-  from=media/player
+  from=music-player/playback
   defaults={"source":"~/Music/1MIX"}
 ```
 

package/skills/actors/references/persistent-tools.md

@@ -22,12 +22,14 @@ Do not mix source modes.
 ```text
 register_tool
   name=music_player
-  from=media/player
+  from=music-player/playback
   defaults={"source":"~/Music/1MIX"}
 ```
 
 `from` means logical direct delegation. The source remains authoritative for async behavior, caller args and types, source defaults, artifacts, Control, and runtime-owned origins. The persistent user Recipe stores only the compact specialization; do not copy inherited fields.
 
+Resolution uses Pi's authoritative active-session Skill snapshot across every Skill location Pi admits. Registration resolves and validates the maintained source, persists only its logical `<skill>/<recipe>` reference plus caller specialization, and projects the already-resolved effective contract into the runtime tool. Never replace this composition with a copied Recipe, absolute helper path, symlink, or ambient runtime re-resolution.
+
 Use `description` to narrow agent-facing intent when useful. Every supplied default must name a caller-owned source arg and satisfy its type or enum. Never default runtime-owned origins.
 
 ## Prove registration

package/skills/actors/references/recipes.md

@@ -7,14 +7,14 @@ A Recipe is a reusable executable definition. Address a maintained component as
 Use direct delegation when the root remains fundamentally the same capability under a different persistent name, description, or caller default:
 
 ```text
-media/player
+music-player/playback
 → music_player with a default source
 ```
 
 For agent-facing persistent specialization, use:
 
 ```text
-register_tool from=media/player defaults={"source":"~/Music/1MIX"}
+register_tool from=music-player/playback defaults={"source":"~/Music/1MIX"}
 ```
 
 The delegated root inherits async behavior, args and types, defaults, artifacts, Control, and runtime-owned origins. Do not copy those fields into the wrapper.

package/skills/actors/references/runs.md

@@ -10,6 +10,8 @@ spawn recipe=<skill>/<recipe> values={...} as=run:<id>
 
 Use the owning capability Skill to choose the Recipe and capability-specific values. Retain the returned Run id. A spawn result reports `launch_kind: "spawn"`; it is never evidence of registered-tool invocation.
 
+A rare Skill Recipe may declare `singleton: true`. Do not pass `as`: the runtime derives `run:<skill>` plus the canonical `<skill>/<recipe>` identity, allows at most one singleton Recipe per Skill, and returns the same compatible healthy active Run instead of launching a duplicate. Contradictory Recipe identity, startup values, Control, or ownership fails closed. Delegation inherits both singleton identities instead of retargeting them. A terminal result is never reused; after its runner exits, restart keeps the logical Run id but creates a new fenced generation. Continuity still depends on actor-owned validated state, not the Run id alone.
+
 ## Observe
 
 Normally wait for terminal follow-up. Inspect only when requested, when meaningful attention arrives, or when the Run is overdue or blocked:

package/skills/actors/scripts/validate-recipe.mjs

@@ -106,6 +106,7 @@ function scanSkillRecipes(target) {
     if (!existsSync(recipeDir)) continue;
     const direct = readdirSync(recipeDir, { withFileTypes: true });
     const byStem = new Map();
+    const singletonFiles = [];
     for (const entry of direct) {
       const path = join(recipeDir, entry.name);
       if (entry.isDirectory()) {
@@ -120,6 +121,7 @@ function scanSkillRecipes(target) {
       }
       if (!entry.isFile() || !/\.(?:json|md)$/.test(entry.name)) continue;
       files.push(path);
+      if (readRawRecipeConfig(path)?.singleton === true) singletonFiles.push(path);
       const stem = basename(entry.name, extname(entry.name));
       const previous = byStem.get(stem);
       if (previous) {
@@ -130,6 +132,13 @@ function scanSkillRecipes(target) {
         });
       } else byStem.set(stem, path);
     }
+    if (singletonFiles.length > 1) {
+      failures.push({
+        file: recipeDir,
+        ok: false,
+        error: `Skill ${skill.name} declares more than one singleton Recipe: ${singletonFiles.map((file) => basename(file)).join(", ")}`,
+      });
+    }
   }
   let skillContext = packageSkillContext;
   try {
@@ -227,6 +236,8 @@ function qaDiagnostics(file, config) {
   const warnings = [];
   if (config.mailbox !== undefined)
     diagnostics.push("recipe.mailbox was removed; use control actions and Trace events");
+  if (config.singleton === true && config.async !== true)
+    diagnostics.push("singleton: requires async: true");
   diagnostics.push(...validateArtifactDeclarations(config));
   diagnostics.push(...validatePortablePaths(config));
   diagnostics.push(...validateHelperPaths(file, config));
@@ -260,6 +271,7 @@ function validateFile(file, qa = false, skillContext = packageSkillContext) {
       ok: qaOk(qaReport),
       name: config.name ?? "",
       async: Boolean(config.async),
+      singleton: Boolean(config.singleton),
       args: Array.isArray(config.args) ? config.args : [],
       defaults:
         config.defaults && typeof config.defaults === "object"