@llblab/pi-actors 0.48.1 → 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,18 @@
 
 > 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.

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/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/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

@@ -96,6 +96,7 @@ export function createRuntimeToolDefinition(cfg, exec) {
     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)
@@ -123,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.");
@@ -146,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",
@@ -181,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/skills/actors/SKILL.md

@@ -58,12 +58,12 @@ A Skill Recipe is a maintained component addressed by `<skill>/<recipe>`. `spawn
 
 ## 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,7 +22,7 @@ Do not mix source modes.
 ```text
 register_tool
   name=music_player
-  from=media/player
+  from=music-player/playback
   defaults={"source":"~/Music/1MIX"}
 ```
 

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:

package/dist/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"

package/dist/skills/music-player/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: music-player
+description: Use for starting, resuming, inspecting, and controlling one persistent local music playback actor from caller-approved files, directories, URLs, or playlists.
+---
+
+# Music Player
+
+Use this Skill for one local music playback service. For generic Recipe execution, singleton Run lifecycle, persistent-tool setup, or diagnosis, follow `actors`; this Skill owns only playback-specific selection and controls.
+
+## Playback
+
+`music-player/playback` is a singleton async controlled service with the canonical address `run:music-player`. The Recipe is the sole lifecycle owner: it starts the service, supervises it, and stops playback when the Run closes. The service owns queue, backend, checkpoint, and playback state. `playback-client.mjs` is a pure actor-neutral RPC client; it never starts, adopts, supervises, or signals a service. The executable also supports explicit foreground `serve` for development or a caller-owned standalone host, but Actor and standalone ownership of one state directory are mutually exclusive.
+
+```text
+spawn recipe=music-player/playback values={"source":"~/Music","player":"auto"}
+message target=run:music-player action=pause
+message target=run:music-player action=next
+inspect target=run:music-player view=control
+```
+
+A repeated compatible spawn returns the healthy active singleton instead of launching a second player. A terminal or dead singleton restarts under the same Run id with a fresh fenced generation and restores its validated playback checkpoint when the source and configuration still match.
+
+## Controls
+
+Use only declared actions: `play`, `pause`, `resume`, `toggle`, `next`, `previous`, `seek`, `volume`, `stop`, and `status`.
+
+- `play` and `resume` continue the current checkpointed track selection.
+- `next` and `previous` update the checkpoint before the next backend launch.
+- `seek` accepts Control input `{ "percent": 0..100 }`, resolves the current track duration, and restarts a supported backend at that percentage while preserving track identity and paused/playing intent. It fails when duration or backend seeking is unavailable.
+- `volume` accepts Control input `{ "percent": 0..100 }` and sets any integer percentage. On Linux with WirePlumber, the helper resolves the exact current playback stream by process identity and changes its volume in place so the track continues; when no safe in-place control exists, it restarts the current track under the new volume while preserving paused/playing intent. UI adapters may expose coarse relative steps but must send the resolved absolute percentage.
+- `status` is read-only and exposes bounded machine-readable player state, including the current absolute volume and a duration-derived progress percentage projected at read time.
+- `stop` ends the live process without silently deleting the saved queue.
+
+External local views use the actor-neutral playback client against the canonical service state directory. They must not read or edit Run files, signal playback processes, construct Actor Control records, or import pi-actors internals. The client validates bounded commands, exact service generation, structured responses, and active endpoint ownership before returning success.
+
+## Optional Telegram View
+
+> [!NOTE]
+> If a Generative App runtime is installed, this Skill includes a ready Music Player app at `genapps/music-player.mjs`. Use `telegram_bind` to copy and install it as app `music-player`; hot replacement keeps the same app name with `replace: true`.
+
+Bind with absolute `control`, `stateDir`, and `node` arguments. The adapter reports whether the Actor control surface is actually available. Every mutating button queues a canonical Actor Control through `playback.mjs` and waits for that exact record to become handled or failed, so terminal evidence remains visible in the Run inspector and failures reach Telegram; bounded status projection is read-only. The adapter neither imports extension internals nor starts playback. Its stopped-state Start button returns to Pi so the composition root can spawn `music-player/playback`, while active controls remain deterministic Generative App actions that bypass the model. `pi-telegram` owns only the generic Generative App runtime.
+
+## Sources And Backends
+
+- `source` must name caller-approved local music, a readable directory, a playlist file, a URL, or an explicit `|`-separated list. Do not broaden it to unrelated directories.
+- Directory and playlist resolution is owned by the playback helper; there is no separate public playlist Recipe.
+- `player=auto` selects an available supported backend. Do not install or substitute a player silently.
+- The checkpoint preserves source, resolved queue, current index/track, loop, volume, backend, and playback state. It does not promise within-track position restoration unless the selected backend can prove it.
+- A changed source rebuilds the queue. Missing or corrupt checkpoint data fails visibly or rebuilds only under the helper's explicit recovery contract; never claim continuity without evidence.
+
+## Stop Rules
+
+Stop if the source is missing, unreadable, contains no playable audio, or no supported backend is available. Do not claim playback from process start alone; confirm through Run evidence or `status`. Prefer the declared `stop` action for a responsive player. If the service is unresponsive, return to `actors` for bounded Run recovery rather than shell process control.