@llblab/pi-actors 0.48.1 → 0.49.1

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.

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

@@ -150,6 +150,7 @@ export function createRuntimeToolDefinition(
   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!;
@@ -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/package.json

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

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

package/skills/music-player/SKILL.md

@@ -0,0 +1,57 @@
+---
+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.
+
+## Interaction Routing
+
+When a Telegram-originated turn or explicit Telegram-control question makes repeated player controls relevant, prefer the maintained Telegram view described below over synthesizing one-shot prompt buttons. If `telegram_bind` is available, load and follow the active operating guidance that owns Generative Apps, then bind or invoke the capability-owned adapter; do not re-author it or move playback authority into the view. If the runtime is unavailable or binding fails, report that boundary and fall back to ordinary model-mediated 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.
+
+## Maintained Telegram View
+
+> [!NOTE]
+> This Skill includes a ready Music Player Generative App at `genapps/music-player.mjs`. When `telegram_bind` is available and Telegram interaction is relevant, use it to copy and install the app as `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.