@llblab/pi-actors 0.48.0 → 0.49.0

package/AGENTS.md

@@ -60,7 +60,7 @@ Pi host
 - `observability.ts`, `run-ui-runtime.ts`: Trace attention, terminal reconciliation, and Pi follow-up delivery.
 - automatic draft/tool review domains: structurally redacted model review, journaled mutation, lineage, recovery, and explicit retry/reset safety.
 
-The bundled Skill Recipe dependency DAG is `artifacts → actors, swarm`, `media → artifacts`, and `project-work → actors, artifacts, swarm`; `actors`, `swarm`, and `recipe-memory` have no cross-Skill Recipe dependencies.
+The bundled Skill Recipe dependency DAG is `artifacts → actors, swarm` and `project-work → actors, artifacts, swarm`; `actors`, `music-player`, `swarm`, and `recipe-memory` have no cross-Skill Recipe dependencies.
 
 Scripts remain self-contained when no non-script consumer justifies a TypeScript domain. Command-template script leaves infer `.js`/`.mjs` in order through Node, Bun, or `deno run` and `.sh` through Bash without shell evaluation. Helper-backed Skill Recipes self-locate through runtime-owned `{skill_dir}`. Recipes stay optional, composable, policy-light, and caller-configurable.
 

package/BACKLOG.md

@@ -1,3 +1,6 @@
 # Project Backlog
 
-No open items.
+- [ ] `Linux MPRIS media integration`: Expose the active `music-player/playback` singleton as one optional generation-fenced MPRIS2 player so GNOME and compatible desktop shells can show current media and native controls without making D-Bus a second playback authority.
+  - [ ] Publish `PlaybackStatus`, track metadata, duration, read-time position, volume, and supported capabilities under one stable session-scoped bus identity; disappear cleanly when the Run stops or its generation is replaced, and fail soft when the user D-Bus session is unavailable.
+  - [ ] Map `Play`, `Pause`, `PlayPause`, `Next`, `Previous`, `Stop`, `Seek`, `SetPosition`, and `Volume` back into the existing generation-fenced music-player Control/helper contract rather than signaling the backend or editing Run state directly.
+  - [ ] Validate deterministic D-Bus contract behavior plus a live GNOME smoke showing the media surface, metadata, progress, volume, and controls while preserving backend independence and exact Actor ownership.

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
+## Unreleased
+
+## 0.49.0: Skill-Scoped Music Player
+
+- `Skill-Scoped Singletons`: Added one optional async singleton Recipe per active Skill with canonical `run:<skill>` and `<skill>/<recipe>` identities, idempotent compatible reuse, lifecycle/process fencing, terminal-generation replacement, delegation-safe identity inheritance, persistent actor-owned state directories, focused inspection, and fail-closed conflicts across Recipe, owner, startup values, and Control.
+- `Terminal Attention Dedupe`: Retains seen Trace-attention identities while terminal Runs remain observable, preventing periodic reconciliation from replaying the same command follow-ups after the terminal transition.
+- `Focused Music Player`: Replaces broad Media with one `music-player/playback` singleton for files, directories, URLs, and playlists. It checkpoints queue and paused intent, reports structured status/Trace, rejects Actor/standalone ownership collisions, and recovers malformed checkpoints explicitly. Live Generative App validation confirmed fresh status and exact terminal Controls across the complete action set.
+- `Absolute Volume Control`: Adds generation-fenced `volume` with `{ "percent": 0..100 }`, direct helper parity, structured status/checkpoint/Trace evidence, and fail-before-admission invalid-input handling. Linux WirePlumber resolves the exact playback stream by process identity and changes it in place; unsupported environments retain the restart fallback. UIs resolve relative steps to one absolute percentage.
+- `Percentage Seeking`: Adds generation-fenced `seek` with `{ "percent": 0..100 }`, bounded duration probing, read-time progress percentage, structured status/checkpoint/Trace evidence, and supported-backend restart at the resolved offset while preserving track and paused/playing intent; unavailable duration or backend support fails explicitly.
+- `Portable Playback Protocol`: Adds actor-neutral foreground `serve` and a pure generation-fenced `playback-client.mjs` for structured status and bounded controls. The Recipe remains the sole managed lifecycle owner; standalone foreground ownership is explicit and mutually exclusive, with no hidden daemon start, adoption, or supervisor handoff.
+- `Optional Generative App`: Ships a ready `genapps/music-player.mjs` adapter for a co-installed generic Generative App runtime. It reports Actor availability and waits for the exact terminal canonical Actor Control for every mutation, including failed-action propagation; Pi remains the lifecycle composition root. Progress and volume use symmetric seven-button `0..90` scales in steps of 15.
+
+## 0.48.1: Persistent Skill Composition
+
+- `Persistent Skill Composition`: Made `register_tool from=<skill>/<recipe>` use Pi's authoritative active-session Skill snapshot across every admitted Skill location and activate synchronous or asynchronous tools from the resolved effective contract. Compact user Recipes retain logical delegation without copied contracts, absolute helper paths, symlinks, or ambient runtime re-resolution.
+
 ## 0.48.0: Host-Coordinated Swarms
 
 - `Coordinator And Swarm Methodology`: Defined gatewayless host coordination with companion transports as presence only; the coordinator accepts declarative outcomes, creates explicit Runs, stays available, and owns integration/final validation. Reasoning is role-allocated: bounded authors default off, independent reviewers/integrators use medium, and the coordinator selects evidence-worthy fanout. Swarm retains overhead admission, disjoint ownership, isolation, mutation freeze, and event/timer observation.

package/README.md

@@ -29,7 +29,7 @@ For local development:
 pi install /path/to/pi-actors
 ```
 
-The package contributes the extension and six capability-owning Skills for actors, artifacts, media, project work, Recipe memory, and swarm orchestration.
+The package contributes the extension and six capability-owning Skills for actors, artifacts, music playback, project work, Recipe memory, and swarm orchestration.
 
 ## Public Tools
 
@@ -40,7 +40,7 @@ Create a Run from an active-Skill Recipe, an explicit Recipe file, or an inline
 ```text
 spawn template="sleep 30" as=run:demo
 spawn recipe=project-work/repo-health values={"repo":"/work/project","model":"provider/model"}
-spawn recipe=media/player values={"source":"/music"} as=run:player
+spawn recipe=music-player/playback values={"source":"/music"}
 spawn template="make test" as=run:test
 ```
 
@@ -80,7 +80,7 @@ inspect target=run:test view=trace source=lifecycle lines=40
 inspect target=run:test view=control
 inspect target=runtime view=status
 inspect target=recipes view=status
-inspect target=recipes view=doctor identity=media/player
+inspect target=recipes view=doctor identity=music-player/playback
 inspect target=tool:my_tool view=status
 ```
 
@@ -203,7 +203,7 @@ Useful entry points include:
 - `project-work/release-readiness`
 - `swarm/quorum-review`
 - `artifacts/bundle`
-- `media/player` — controlled playback service
+- `music-player/playback` — singleton controlled playback service
 - `actors/resource-locker` — optional controlled resource-lock service
 
 Validate Recipes with:

package/dist/lib/async-runs.d.ts

@@ -33,6 +33,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;
@@ -94,6 +97,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>;
 }
 export { safeRunId } from "./runs-identity.ts";

package/dist/lib/async-runs.js

@@ -7,6 +7,7 @@ import { randomUUID } from "node:crypto";
 import { closeSync, existsSync, mkdirSync, openSync, readdirSync, statSync, } 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 { writeJsonAtomic } from "./file-state.js";
 import { CURRENT_MODEL_VALUE_KEY, CURRENT_THINKING_VALUE_KEY, describeCurrentPolicyProvenance, } from "./model-context.js";
 import * as Paths from "./paths.js";
@@ -105,6 +106,32 @@ function resolveStateDir(params, run) {
 function assertNoActiveRunState(stateDir) {
     RunsStart.assertNoActiveRunState(stateDir, readJson, RUNNER_PATH);
 }
+function reuseCompatibleSingletonRun(stateDir, startParams, singletonValues) {
+    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,
+        ...(startParams.launch_source
+            ? {
+                launch_kind: startParams.launch_source,
+                launch_source: startParams.launch_source,
+            }
+            : {}),
+        ...(startParams.launch_correlation
+            ? { launch_correlation: startParams.launch_correlation }
+            : {}),
+        reused: true,
+    };
+}
 function resolveRecipeFile(file, cwd, options) {
     const path = RecipesReferences.resolveRecipeReferencePath(file, cwd, options.skillContext);
     if (path)
@@ -147,10 +174,23 @@ function resolveStartParams(params, cwd, options) {
     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,
-        run_id: params.run_id ||
+        ...(singleton ? { singleton: true } : {}),
+        run_id: singletonRun ||
+            params.run_id ||
             fileParams.run_id ||
             fileParams.name ||
             getRunIdFromFile(fileParams.file),
@@ -282,14 +322,27 @@ export function startRun(params, cwd, options = {}) {
         values: startParams.policy_values ?? startParams.values ?? {},
     });
     assertCurrentPlaceholderReferencesResolved(resolved.template, startParams.defaults, 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");
@@ -307,11 +360,6 @@ export function startRun(params, cwd, options = {}) {
                 }
                 : 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);
@@ -360,6 +408,13 @@ export function startRun(params, cwd, options = {}) {
             ...(startParams.retire_when === "children_terminal"
                 ? { retire_when: "children_terminal" }
                 : {}),
+            ...(startParams.singleton === true
+                ? {
+                    singleton: true,
+                    singleton_recipe_id: startParams.singleton_recipe_id,
+                    singleton_values: singletonValues,
+                }
+                : {}),
             ...(transportContext
                 ? { transport_context: transportContext } : {}),
         };

package/dist/lib/extension-runtime.js

@@ -127,6 +127,9 @@ export function createActorExtensionRuntime(pi) {
             Pi.registerToolDefinitions(pi, Tools.createCoreActorToolDefinitions({
                 configPath: Paths.EXTENSION_RUNTIME_PATHS.configPath,
                 getActiveTools: () => pi.getActiveTools(),
+                getRecipeResolutionContext: () => activeRunContext
+                    ? getRecipeResolutionContext(activeRunContext)
+                    : undefined,
                 getRuntimeTool: (name) => Tools.resolveActiveRuntimeTool(name, runtime.getTools(), (activeName) => actorToolDefinitions.get(activeName)),
                 getRuntimeToolStatus: runtime.getToolStatus,
                 handleRuntimeControl: automaticReview.handleControl,

package/dist/lib/file-state.js

@@ -273,13 +273,27 @@ export function withFileMutationLock(path, mutate, options = {}) {
         release();
     }
 }
+function replaceFileWithRetry(source, target) {
+    for (let attempt = 0;; attempt += 1) {
+        try {
+            renameSync(source, target);
+            return;
+        }
+        catch (error) {
+            const code = error.code;
+            if ((code !== "EPERM" && code !== "EBUSY") || attempt >= 19)
+                throw error;
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50);
+        }
+    }
+}
 export function writeTextAtomic(path, content, options = {}) {
     mkdirSync(dirname(path), { recursive: true });
     const tempPath = `${path}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`;
     try {
         writeFileSync(tempPath, content, "utf8");
         options.onBeforeReplace?.();
-        renameSync(tempPath, path);
+        replaceFileWithRetry(tempPath, path);
     }
     catch (error) {
         try {

package/dist/lib/inspector.js

@@ -117,6 +117,9 @@ export function readActorInspectorRecipe(stateDir) {
             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,
@@ -127,6 +130,7 @@ export function readActorInspectorRecipe(stateDir) {
             artifacts: meta.artifacts,
             notification_policy: meta.notification_policy,
             retire_when: meta.retire_when,
+            singleton_values: meta.singleton_values,
         }),
     };
 }

package/dist/lib/observability.js

@@ -786,9 +786,6 @@ function readTraceAttentionRecords(run) {
 export function pruneRunObservationState(previousStatuses, previousLineCounts, summary, terminalRuns = [], seenEventIds = new Map()) {
     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);
@@ -796,10 +793,10 @@ export function pruneRunObservationState(previousStatuses, previousLineCounts, s
         if (!activeRuns.has(run))
             previousStatuses.delete(run);
     for (const key of previousLineCounts.keys())
-        if (terminalLineKeys.has(key) || !activeLineKeys.has(key))
+        if (!activeLineKeys.has(key))
             previousLineCounts.delete(key);
     for (const key of seenEventIds.keys())
-        if (terminalLineKeys.has(key) || !activeLineKeys.has(key))
+        if (!activeLineKeys.has(key))
             seenEventIds.delete(key);
 }
 export function detectRunAttentionEvents(legacyLineCounts, summary, seenEventIds = new Map(), prime = false) {

package/dist/lib/recipes-discovery.js

@@ -707,7 +707,9 @@ export function summarizeRegisteredToolArgs(tool) {
     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/dist/lib/recipes-references.d.ts

@@ -14,6 +14,7 @@ export type TemplateRecipeImport = string | TemplateRecipeImportBinding;
 export interface TemplateRecipeDefinition {
     description?: string;
     disabled?: boolean;
+    singleton?: boolean;
     imports?: Record<string, TemplateRecipeImport>;
     template: CommandTemplateValue;
     args?: string[];
@@ -42,6 +43,8 @@ export interface TemplateRecipeConfig extends TemplateRecipeDefinition {
     async?: boolean;
     recipe_dir?: string;
     skill_dir?: string;
+    singleton_run_id?: string;
+    singleton_recipe_id?: string;
 }
 export interface TemplateRecipeContextRecord {
     alias?: string;

package/dist/lib/recipes-references.js

@@ -970,6 +970,21 @@ export function readResolvedRecipeConfig(file, stack = [], options = {}) {
                     : 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/dist/lib/registry.d.ts

@@ -5,6 +5,7 @@
  */
 import * as CommandTemplates from "./command-templates.ts";
 import * as Config from "./config.ts";
+import * as RecipesContext from "./recipes-context.ts";
 export interface RegisterToolInput {
     name?: string;
     description?: string;
@@ -55,6 +56,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, message: string, type: "info" | "warning" | "error") => void;
     registerRuntimeTool: (cfg: Config.RegisteredTool) => RuntimeActivation | void;

package/dist/lib/registry.js

@@ -233,9 +233,10 @@ function getInputTemplate(value) {
     throw new Error(ExecutionOutput.formatToolText("Tool template must be a string, object, or sequence."));
 }
 function getRegistrationResolutionContext(ctx, deps) {
-    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.recipeResolutionContext;
         if (resolutionContext)
             return resolutionContext;
@@ -415,15 +416,18 @@ function executeRegisterToolUnlocked(params, ctx, deps) {
     let persisted = false;
     let activation;
     let cfg;
+    let transactionStage = "persist";
     try {
         persistToolRecipe(deps, name, authoredRecipe);
         persisted = true;
+        transactionStage = "persisted_admission";
         const admitted = RecipesDiscovery.admitUserRecipe(recipePath, resolutionContext);
         if (!admitted.validated || !admitted.tool) {
             throw new Error(`Persisted tool recipe admission failed: ${admitted.diagnostics.join("; ")}`);
         }
         cfg = admitted.tool;
         tools.set(name, cfg);
+        transactionStage = "runtime_activation";
         activation = deps.registerRuntimeTool(cfg) ?? undefined;
         if (activation &&
             (!activation.host_registered ||
@@ -447,7 +451,7 @@ function executeRegisterToolUnlocked(params, ctx, deps) {
             tools.delete(name);
         }
         deps.setActiveTools(activeBefore);
-        throw new Error(ExecutionOutput.formatToolText(`Tool registration transaction failed: ${error instanceof Error ? error.message : String(error)}`));
+        throw new Error(ExecutionOutput.formatToolText(`Tool registration transaction failed at ${transactionStage} (${resolutionContext.generation}; active Skills: ${activeSkillSummary(resolutionContext)}): ${error instanceof Error ? error.message : String(error)}`));
     }
     deps.notify(ctx, `Tool activated: ${name}`, "info");
     const templateWarnings = CommandTemplates.getCommandTemplateWarnings(typeof cfg.recipe?.template === "object" && !Array.isArray(cfg.recipe.template)

package/dist/lib/runs-start.d.ts

@@ -5,7 +5,8 @@
  */
 import { type FileMutationLockOptions } from "./file-state.ts";
 type RunJsonReader = (path: string) => Record<string, unknown> | undefined;
-export declare function assertNoActiveRunState(stateDir: string, readJson: RunJsonReader, _runnerPath: string): void;
+export declare function readActiveOwnedRunState(stateDir: string, readJson: RunJsonReader, _runnerPath: string): Record<string, unknown> | undefined;
+export declare function assertNoActiveRunState(stateDir: string, readJson: RunJsonReader, runnerPath: string): void;
 export declare function acquireStateStartLock(stateDir: string, options?: FileMutationLockOptions): () => void;
 export declare function prepareStateDirForStart(stateDir: string, readJson: RunJsonReader, _runnerPath: string): void;
 export {};

package/dist/lib/runs-start.js

@@ -7,14 +7,16 @@ import { rmSync } from "node:fs";
 import { join } from "node:path";
 import { acquireFileMutationLock, } from "./file-state.js";
 import { isAlive, verifyRunProcessIdentity, } from "./runs-process.js";
-export function assertNoActiveRunState(stateDir, readJson, _runnerPath) {
+export function readActiveOwnedRunState(stateDir, readJson, _runnerPath) {
     const meta = readJson(join(stateDir, "run.json"));
     if (!meta)
-        return;
+        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;
+        return undefined;
     const identity = verifyRunProcessIdentity(pid, meta.process_identity);
     if (identity.status === "owner_mismatch") {
         throw new Error(`Run state process identity does not match the live pid: ${String(meta.run ?? stateDir)}. Refusing to reuse the state directory while pid ${pid} is alive.`);
@@ -22,7 +24,11 @@ export function assertNoActiveRunState(stateDir, readJson, _runnerPath) {
     if (identity.status === "unsupported_proof") {
         throw new Error(`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, readJson, runnerPath) {
+    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/dist/lib/tools-local.js

@@ -93,8 +93,10 @@ export function createRuntimeToolDefinition(cfg, exec) {
     const paramSchema = {};
     const required = [];
     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;
     const requiredTemplateConfig = typeof requiredTemplate === "object" && !Array.isArray(requiredTemplate)
@@ -112,7 +114,7 @@ export function createRuntimeToolDefinition(cfg, exec) {
     const requiredArgs = isRecipe && cfg.storedArgs !== undefined
         ? new Set(cfg.args.filter((arg) => !Object.hasOwn(cfg.defaults, arg) &&
             !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) {
@@ -122,7 +124,7 @@ export function createRuntimeToolDefinition(cfg, exec) {
         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.");
     if (isAsyncRecipe) {
         paramSchema.transport_context = Schema.looseObjectSchema("Optional originating transport route preserved for detached terminal follow-up.");
@@ -145,9 +147,11 @@ export function createRuntimeToolDefinition(cfg, exec) {
                     const input = params;
                     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()
-                        ? run_id.trim()
-                        : `${cfg.name}-${Date.now()}`;
+                    const runId = isSingletonRecipe
+                        ? undefined
+                        : typeof run_id === "string" && run_id.trim()
+                            ? run_id.trim()
+                            : `${cfg.name}-${Date.now()}`;
                     const meta = AsyncRuns.startRun({
                         ...base,
                         launch_source: "tool",
@@ -180,7 +184,7 @@ export function createRuntimeToolDefinition(cfg, exec) {
                 return await Execution.executeRegisteredTool(cfg, Schema.normalizeRuntimeValues(ModelContext.withCurrentModelValues(params, ctx), cfg.argTypes), exec, ctx.cwd, signal);
             }
             catch (error) {
-                throw formatRuntimeToolArgumentError(cfg, error, required, isAsyncRecipe);
+                throw formatRuntimeToolArgumentError(cfg, error, required, isAsyncRecipe && !isSingletonRecipe);
             }
         },
     };

package/dist/lib/tools.d.ts

@@ -14,6 +14,7 @@ export interface ActorToolDefinition {
 export interface CoreActorToolDefinitionDeps<TContext extends RuntimeToolContext> {
     configPath: string;
     getActiveTools: () => string[];
+    getRecipeResolutionContext: () => import("./recipes-context.ts").RecipeResolutionContext | undefined;
     getRuntimeTool: (name: string) => unknown;
     getRuntimeToolStatus: (name: string) => Record<string, unknown> | undefined;
     handleRuntimeControl?: (action: string, input: unknown) => Record<string, unknown>;

package/dist/lib/tools.js

@@ -30,6 +30,7 @@ export function createCoreActorToolDefinitions(deps) {
             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/dist/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/dist/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/dist/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/dist/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: