@llblab/pi-kit 0.3.2 → 0.5.0

package/AGENTS.md

@@ -3,7 +3,7 @@
 ## Product Contract
 
 - `@llblab/pi-kit` is a Pi package distribution, not a Pi extension.
-- It bundles independently released LLBLAB extensions behind one installable package.
+- It bundles independently released LLBLAB extensions and Skill packages behind one installable package.
 - Every included package version is exact. Ranges, floating tags, local paths, and unpublished refs are forbidden in release state.
 - The kit owns composition and version selection only. Runtime behavior, Skills, documentation, and implementation remain owned by the included packages.
 - Loading order is explicit in `package.json`; do not rely on recursive package discovery.
@@ -24,7 +24,7 @@
 - Expose only resources declared by each included package. Prefer published distribution entrypoints over source entrypoints when both exist.
 - Do not copy extension source, Skills, or documentation into this repository.
 - Preserve package independence: a kit release may advance any subset of included extensions without forcing lockstep extension releases.
-- Derive the kit version bump from the highest dependency bump in the synchronized release cohort: dependency patch-only updates require a kit patch bump, while any dependency minor update requires a kit minor bump. Do not let lower-level dependency bumps force a larger kit bump.
+- Adding packages or newly exposed capabilities requires a kit minor bump. For updates to the existing composition, derive the kit version bump from the highest dependency bump in the synchronized release cohort: dependency patch-only updates require a kit patch bump, while any dependency minor update requires a kit minor bump. Do not let lower-level dependency bumps force a larger kit bump.
 - Use English for public and repository-facing text.
 - Do not commit, publish, tag, create a remote repository, or mutate Pi settings without explicit authorization.
 
@@ -32,5 +32,5 @@
 
 - Run `npm test` after manifest or inventory changes.
 - Run `npm run pack:check` before declaring package readiness.
-- Inspect the dry-run tarball inventory to confirm all four bundled packages and their declared resources are present.
+- Inspect the dry-run tarball inventory to confirm every package in `bundledDependencies` and its declared resources are present.
 - Run `npm run validate` at completion.

package/BACKLOG.md

@@ -1,3 +1,3 @@
 # Backlog
 
-No open work.
+No open items.

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to `@llblab/pi-kit` are documented here.
 
+## 0.5.0 - 2026-09-05
+
+- `Telegram Native Controls`: Advances the exact Telegram pin to `0.43.0`, bringing in-body button blocks, shared JSON/CML disabled controls, HTML footer fallback, and updated agent Skills while preserving package-owned implementations and the existing resource inventory.
+
+## 0.4.0 - 2026-09-05
+
+- `Expanded Composition`: Adds exact published pins for Clean Room and opt-in State Flow alongside the portable LLBLAB Skills collection, exposing each package's own declared resources without duplicating source or runtime ownership.
+- `Verified Hotfix Cohort`: Advances Actors to `0.52.1`, Grow Loop to `0.7.4`, and Telegram to `0.42.4`, including guarded thread recovery and cleanup, while retaining independent package release ownership.
+- `Independent Package Guide`: Links every included package to its owning repository, explains its purpose, and documents duplicate-resource configuration for users migrating from individual installations.
+
 ## 0.3.2 - 2026-09-01
 
 - `Telegram Comment Membrane`: Advances `@llblab/pi-telegram` to `0.42.2`, keeping assistant-authored HTML comments transport-private across Telegram previews and final replies while preserving top-level button and voice activation and skipping empty text sends after sanitization.

package/README.md

@@ -1,17 +1,24 @@
 # @llblab/pi-kit
 
-`@llblab/pi-kit` is the version-pinned LLB Lab extension distribution for [Pi](https://github.com/badlogic/pi-mono). It provides one installable package while each included extension keeps its own repository, release line, and development lifecycle.
+One install for the LLB Lab extension and Skill collection for [Pi](https://github.com/earendil-works/pi).
+
+`@llblab/pi-kit` is a version-pinned package distribution, not another runtime extension. It brings together independently maintained packages; each keeps its own repository, releases, documentation, and development lifecycle.
 
 ## Included packages
 
-| Package | Version | Resources |
+Package links lead to the owning repositories for usage, documentation, issues, and contributions.
+
+| Package | Version | Purpose |
 | --- | ---: | --- |
-| `@llblab/pi-actors` | `0.52.0` | Extension and Skills |
-| `@llblab/pi-codex-usage` | `0.9.4` | Extension |
-| `@llblab/pi-grow-loop` | `0.7.3` | Extension and Skills |
-| `@llblab/pi-telegram` | `0.42.2` | Extension and Skills |
+| [`@llblab/pi-actors`](https://github.com/llblab/pi-actors) | `0.52.1` | Inspectable local Runs, reusable Recipes, persistent tools, and delegation Skills |
+| [`@llblab/pi-clean-room`](https://github.com/llblab/pi-clean-room) | `0.1.1` | Isolated nested Pi TUI with explicitly selected extensions |
+| [`@llblab/pi-codex-usage`](https://github.com/llblab/pi-codex-usage) | `0.9.4` | Compact Codex/Spark subscription-limit status |
+| [`@llblab/pi-grow-loop`](https://github.com/llblab/pi-grow-loop) | `0.7.4` | Visible continuation scheduling and bounded worker Skills |
+| [`@llblab/pi-state-flow`](https://github.com/llblab/pi-state-flow) | `0.3.0` | Opt-in validated state handoffs between agent runs |
+| [`@llblab/pi-telegram`](https://github.com/llblab/pi-telegram) | `0.43.0` | Telegram companion, queues, files, voice, controls, and Generative Apps guidance |
+| [`@llblab/skills`](https://github.com/llblab/skills) | `1.14.0` | Portable workflows for engineering, review, design, context maintenance, and other focused tasks |
 
-Versions are exact by design. Updating an extension does not change an installed kit until this repository explicitly advances that dependency and publishes a new kit version.
+Versions are exact by design. An upstream release does not change an installed kit until this repository explicitly advances the dependency and publishes a new kit version. Runtime defects and package-specific feature requests belong in the linked repository; package selection and kit installation issues belong here.
 
 ## Install
 
@@ -27,7 +34,9 @@ From GitHub:
 pi install git:github.com/llblab/pi-kit
 ```
 
-Pi loads the bundled extension entrypoints and Skills declared by this package. The kit itself does not register an extension or introduce runtime behavior.
+Pi loads the six extension entrypoints and the Skill resources explicitly declared by the kit. The kit adds no runtime behavior and does not copy the packages' source or instructions into a new owner. State Flow remains opt-in; bundling it does not enable its state handoff mode.
+
+Prefer the kit instead of separately loading the same packages. If you already use individual installations or local Skill copies, use `pi config` to disable duplicate resources. Installing the kit does not remove or rewrite those installations.
 
 ## Development
 
@@ -36,8 +45,8 @@ npm install
 npm run validate
 ```
 
-To advance one included package, update its exact version in `dependencies`, run `npm install`, update the package table and changelog, then validate the packed artifact. Do not use version ranges.
+To advance an included package, update its exact version in `dependencies`, run `npm install`, synchronize bundled dependencies, declared resource paths, tests, the table above, and the changelog, then validate the packed artifact. Expose only resources declared by the published owning package; do not use version ranges or unpublished local paths.
 
 ## Security
 
-Pi extensions execute with the user's system permissions. Review every included package and its release before advancing the pinned version.
+Pi extensions execute with the user's system permissions, and Skills can guide executable actions. Review each included package and release before advancing its pin. Private Knowledge, credentials, and personal Pi configuration are not bundled.

package/node_modules/@llblab/pi-actors/AGENTS.md

@@ -144,6 +144,7 @@ When deferred Run results gate the next step, wait for their completion batch. I
 
 - Keep published text portable: use `~`, `<repo>`, or relative paths.
 - Update `skills/actors/SKILL.md` when durable operating mechanics change.
+- For registration or agent-instruction changes, use `tests/registration-truth.test.ts` for resolution/admission/activation truth and `tests/agent-journeys.test.ts` for public agent journeys, then check installed-package parity at the affected boundary. Fresh-agent operating evidence must use the active Skills and public tools rather than repository source or copied helper contracts.
 - Keep `skills/swarm/SKILL.md` focused on multi-agent methodology rather than kernel internals.
 - Recipe `description` is optional. Skill Recipe QA recursively validates direct filesystem-owned components and capability semantics with zero diagnostics or warnings; it does not enforce aesthetics or architecture policy.
 - Before release run the normal product validation and dependency audit. Use the project-local Domain DAG Skill during architecture-affecting development, not as publication automation.

package/node_modules/@llblab/pi-actors/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
+## 0.52.1: Unified Playback Control Hotfix
+
+- `Unified Playback CLI`: Consolidates standalone playback and external control into `playback.mjs`; standalone commands remain runtime-independent, while Actor-owned commands retain exact terminal Control evidence. The maintained Music Player Generative App uses the same explicit control entrypoint. Post-stop status remains readable despite leftover Run metadata; inactive controls fail before journal admission. External callers of the removed `playback-client.mjs` use `playback.mjs control` instead.
+- `Skill Ownership`: Keeps extension operation and the capability/Recipe map in Actors, multi-participant coordination and quorum in Swarm, and development detail in focused references. Preserves registration/agent-journey evidence routing in AGENTS while removing obsolete delivery Skills, historical evidence reports, and tests coupled only to that retired prose.
+- `Local Architecture Tooling`: Restores the project-local Domain DAG Skill's portable, configurable graph validator and focused maintenance contract, replacing repository-specific defaults and removing its obsolete Recipe/config wrappers. Architecture tooling remains agent-owned and outside npm publication and CI gates.
+
 ## 0.52.0: Durable Coordinator Delivery
 
 - `Completion Epochs`: Replaces per-Run terminal turns with one immutable owner-fenced completion batch per idle/settled epoch. Batches retain exact Run generations and terminal timestamps, bound durable and model-facing members, preserve silent and synchronous-stop semantics, and remain eligible after urgent steering.

package/node_modules/@llblab/pi-actors/dist/skills/actors/SKILL.md

@@ -76,16 +76,26 @@ Then:
 
 Use direct delegation for the same maintained capability under a persistent name or narrower defaults. Use named imports only when one Recipe graph contains reusable child nodes. See [persistent tools](./references/persistent-tools.md) and [Recipes](./references/recipes.md).
 
-## Local coordinator topology
+## Capability map
 
-There are two distinct multi-instance shapes:
+Recipes remain with the Skill that owns their behavior. Load that Skill for selection and caller inputs; this map is routing, not a copied Recipe contract.
 
-- A gateway-centric system owns ingress, agent-instance creation, routing, and lifecycle outside the agents.
-- A host-coordinator system keeps the current Pi instance as the control plane; companion extensions such as Telegram provide presence, while pi-actors creates explicit local Runs for delegated work.
+| Owner | Recipe families |
+| --- | --- |
+| `actors` | `command-validate`, `recipe-validate`, `jsonl-tail`, `run-summary`, `run-state-files`, `run-ops-snapshot`, `resource-locker`, `resource-locker-snapshot` |
+| `swarm` | Lens and quorum reviews, research synthesis, architecture, development tasking, readiness, and supporting `subagent-*` components |
+| `artifacts` | Report, write, manifest, bundle, and supporting file-write |
+| `project-work` | Repository health, docs maintenance, release readiness/summary, Run reports, and supporting deterministic snapshots |
+| `music-player` | The controlled `playback` singleton |
+| `recipe-memory` | Internal automatic reviewers; use its Skill only for diagnosis/recovery |
 
-In host-coordinator mode, the top-level agent receives declarative outcomes, preserves user authority and global context, delegates bounded concrete execution, and owns integration plus final validation. It is not merely another worker after delegation begins. One bounded implementation worker normally runs with reasoning off; consequential output receives a separate reasoning-enabled review. Several independent participants or reviewers additionally use `swarm`.
+Use the `actors/*` helpers only for their narrow requested result or intentional composition. Prefer public `inspect` for ordinary runtime diagnosis and the capability's primary workflow for a complete outcome.
 
-Delegation is not mandatory for every prompt. Work inline when one short bounded act has one natural validation boundary and spawning would add more coordination than isolation, latency hiding, clean context, or continued coordinator availability can repay. For admitted delegation, prefer the settled completion batch and durable Trace/artifacts; inspect on meaningful attention, operator request, or an evidence-based overdue timer rather than busy polling. Treat `attention: "steer"` as an actor-authored urgent semantic checkpoint at Pi's next safe boundary, never as a status-derived completion signal; the later root terminal still arrives through its ordinary completion batch.
+## Delegation boundary
+
+The current Pi instance owns user authority and the final result; pi-actors creates explicit local Runs, while companion transports provide presence rather than hidden instance creation. Keep short single-boundary work inline when delegation adds no value. For several participants, reasoning allocation, quorum, or integration methodology, read `swarm`.
+
+Treat `attention: "steer"` as an actor-authored urgent semantic checkpoint at Pi's next safe boundary, never as a status-derived completion signal; the later root terminal still arrives through its ordinary completion batch.
 
 ## Run workflow
 

package/node_modules/@llblab/pi-actors/dist/skills/music-player/SKILL.md

@@ -13,7 +13,7 @@ When a Telegram-originated turn or explicit Telegram-control question makes repe
 
 ## 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.
+`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. `scripts/playback.mjs` owns both foreground playback and the bounded control CLI. Its `control <state-dir> <action> [percent]` entrypoint observes or controls an existing owner without starting, adopting, or supervising it. Explicit foreground `serve` supports a caller-owned standalone host without importing the Actor runtime; Actor and standalone ownership of one state directory are mutually exclusive.
 
 ```text
 spawn recipe=music-player/playback values={"source":"~/Music","player":"auto"}
@@ -35,14 +35,14 @@ Use only declared actions: `play`, `pause`, `resume`, `toggle`, `next`, `previou
 - `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.
+External local views use `playback.mjs control <state-dir> <action> [percent]`. For Actor-owned playback, the script validates Run availability, queues canonical Control, and waits for that exact record to become handled or failed. For standalone playback, it sends a bounded generation-fenced command to the service endpoint without creating Run, Control, or Trace state. Views themselves never read or edit Run files, signal processes, construct Control records, or import pi-actors internals. `status` is read-only and reports `actor_available` separately from playback state.
 
 ## 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.
+Bind with absolute `control` (the `scripts/playback.mjs` path), `stateDir`, and `node` arguments. This maintained adapter targets Actor-owned playback and uses the unified `control` entrypoint above for status and mutation; it displays controls only when `actor_available` is true. Exact terminal Control evidence remains visible in the Run inspector and failures reach Telegram. 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
 

package/node_modules/@llblab/pi-actors/dist/skills/music-player/genapps/music-player.mjs

@@ -70,7 +70,7 @@ function normalizePlayback(status) {
 async function readPlayback(adapter, run) {
   const result = await run({
     command: adapter.node,
-    args: [adapter.control, "status", adapter.stateDir],
+    args: [adapter.control, "control", adapter.stateDir, "status"],
     cwd: dirname(adapter.control),
     timeoutMs: 5_000,
   });
@@ -188,8 +188,9 @@ async function applyVolume(percent, context) {
     command: context.state.adapter.node,
     args: [
       context.state.adapter.control,
-      "volume",
+      "control",
       context.state.adapter.stateDir,
+      "volume",
       String(percent),
     ],
     cwd: dirname(context.state.adapter.control),
@@ -224,8 +225,9 @@ async function applySeek(percent, context) {
     command: context.state.adapter.node,
     args: [
       context.state.adapter.control,
-      "seek",
+      "control",
       context.state.adapter.stateDir,
+      "seek",
       String(percent),
     ],
     cwd: dirname(context.state.adapter.control),
@@ -253,7 +255,7 @@ async function apply(action, context) {
   const before = await readPlayback(context.state.adapter, context.run);
   const result = await context.run({
     command: context.state.adapter.node,
-    args: [context.state.adapter.control, action, context.state.adapter.stateDir],
+    args: [context.state.adapter.control, "control", context.state.adapter.stateDir, action],
     cwd: dirname(context.state.adapter.control),
     timeoutMs: 5_000,
   });

package/node_modules/@llblab/pi-actors/dist/skills/music-player/scripts/playback.mjs

@@ -27,7 +27,7 @@ import {
   watch,
   writeFileSync,
 } from "node:fs";
-import { createServer } from "node:net";
+import { createConnection, createServer } from "node:net";
 import { homedir } from "node:os";
 import {
   basename,
@@ -66,7 +66,7 @@ let updateRunControlStatusInStateDir;
 let isAlive;
 let verifyRunProcessIdentity;
 let appendRunTraceEvent = () => {};
-if (actorAdapterEnabled) {
+async function loadActorAdapter() {
   ({
     appendRunControlInStateDir,
     claimRunControlByIdInStateDir,
@@ -110,8 +110,9 @@ function usage() {
   playback.mjs control <state-dir> <play|pause|toggle|next|previous|seek|volume|stop|status> [percent]
 
 Runs a foreground music player so pi-actors can own it as a controlled Run.
-Controls use canonical records in <state-dir>/controls.jsonl.
-Prefer message target=run:<run> action=<command>, or use direct control commands below.
+Actor-owned controls use canonical records in <state-dir>/controls.jsonl.
+Standalone controls use the generation-fenced playback service endpoint.
+Prefer message target=run:<run> action=<command> for Actors; external adapters use control <state-dir> <action>.
 Supported players: auto, mpv, afplay, ffplay, cvlc, play, wmp.
 `);
 }
@@ -1134,6 +1135,7 @@ function readAndClearCommand(ctx) {
 }
 
 async function playMain(args) {
+  if (actorAdapterEnabled) await loadActorAdapter();
   const [
     sourceArg,
     loopArg = "true",
@@ -1333,30 +1335,74 @@ function projectCurrentProgress(status, nowMs = Date.now()) {
   };
 }
 
-function actorControlAvailability(stateDir) {
+async function actorControlAvailability(stateDir) {
   const run = readJsonFile(join(stateDir, "run.json"), {});
   const result = readJsonFile(join(stateDir, "result.json"), {});
   const endpoint = readJsonFile(join(stateDir, "control-endpoint.json"), {});
   const playerStatus = readJsonFile(join(stateDir, "player.json"), {});
+  const runInstanceId = typeof run.run_instance_id === "string"
+    ? run.run_instance_id
+    : undefined;
+  // Inactive status must remain readable without an installed Actor runtime,
+  // including standalone state beside metadata from a rejected Actor launch.
+  if (!runInstanceId || typeof result.completedAt === "string" ||
+      endpoint.run_instance_id !== runInstanceId ||
+      !["playing", "paused"].includes(playerStatus.state)) {
+    return { available: false, runInstanceId };
+  }
+  if (!verifyRunProcessIdentity) {
+    await loadActorAdapter();
+    // Re-read authority after the asynchronous import before admitting control.
+    return actorControlAvailability(stateDir);
+  }
   const pid = Number(run.pid || 0);
   const hasProcessIdentity = pid > 0 || run.process_identity !== undefined;
   const processIdentity = pid > 0
     ? verifyRunProcessIdentity(pid, run.process_identity)
     : { valid: false };
-  const available =
-    typeof run.run_instance_id === "string" &&
-    typeof result.completedAt !== "string" &&
-    (!hasProcessIdentity || (pid > 0 && isAlive(pid) && processIdentity.valid === true)) &&
-    endpoint.run_instance_id === run.run_instance_id &&
-    ["playing", "paused"].includes(playerStatus.state);
   return {
-    available,
-    runInstanceId: typeof run.run_instance_id === "string"
-      ? run.run_instance_id
-      : undefined,
+    available: !hasProcessIdentity ||
+      (pid > 0 && isAlive(pid) && processIdentity.valid === true),
+    runInstanceId,
   };
 }
 
+async function sendPlaybackCommand(endpoint, action, input) {
+  const payload = `${JSON.stringify({
+    action,
+    ...(input !== undefined ? { input } : {}),
+    service_instance_id: endpoint.service_instance_id,
+  })}\n`;
+  const response = await new Promise((resolveResponse, rejectResponse) => {
+    const socket = createConnection(endpoint.path);
+    let content = "";
+    const timeout = setTimeout(() => {
+      socket.destroy(new Error("playback service command timed out"));
+    }, 5_000);
+    timeout.unref?.();
+    socket.setEncoding("utf8");
+    socket.on("connect", () => socket.write(payload));
+    socket.on("data", (chunk) => {
+      content += chunk;
+      if (Buffer.byteLength(content, "utf8") > 4096) {
+        socket.destroy(new Error("playback service response is too large"));
+      }
+    });
+    socket.on("close", () => clearTimeout(timeout));
+    socket.on("error", rejectResponse);
+    socket.on("end", () => {
+      try {
+        resolveResponse(JSON.parse(content.trim()));
+      } catch {
+        rejectResponse(new Error("playback service returned invalid JSON"));
+      }
+    });
+  });
+  if (response?.ok !== true) {
+    throw new Error(response?.error || "playback service rejected the command");
+  }
+}
+
 async function controlMain(args) {
   const stateDir = expandPath(args[0] || "");
   const command = args[1] || "status";
@@ -1365,13 +1411,20 @@ async function controlMain(args) {
     usage();
     process.exit(2);
   }
-  mkdirSync(stateDir, { recursive: true });
+  if (!CONTROL_COMMANDS.has(command)) fail(`unsupported command: ${command}`, 2);
+  const endpoint = readJsonFile(join(stateDir, "playback-endpoint.json"), {});
+  // A standalone service retains authority even if an unsuccessful Actor launch
+  // left Run metadata beside its endpoint. Clients never start or adopt it.
+  const actorOwned = endpoint.owner_mode !== "standalone" &&
+    existsSync(join(stateDir, "run.json"));
   if (command === "status") {
     const statusFile = join(stateDir, "player.json");
     const status = exists(statusFile)
       ? readJsonFile(statusFile, { state: "unknown" })
       : { state: "unknown" };
-    const actor = actorControlAvailability(stateDir);
+    const actor = actorOwned
+      ? await actorControlAvailability(stateDir)
+      : { available: false };
     process.stdout.write(`${JSON.stringify({
       ...projectCurrentProgress(status),
       actor_available: actor.available,
@@ -1381,7 +1434,7 @@ async function controlMain(args) {
     })}\n`);
     return;
   }
-  if (!actorControlAvailability(stateDir).available) {
+  if (actorOwned && !(await actorControlAvailability(stateDir)).available) {
     fail(`Run playback is not active: ${stateDir}`, 3);
   }
   let input;
@@ -1396,6 +1449,20 @@ async function controlMain(args) {
       fail(error instanceof Error ? error.message : String(error), 2);
     }
   }
+  if (!actorOwned) {
+    if (endpoint.owner_mode !== "standalone" ||
+        typeof endpoint.path !== "string" || !endpoint.path ||
+        typeof endpoint.service_instance_id !== "string" || !endpoint.service_instance_id) {
+      fail(`standalone playback service is not active: ${stateDir}`, 3);
+    }
+    try {
+      await sendPlaybackCommand(endpoint, command === "resume" ? "play" : command, input);
+      console.log(`music-player: command=${command} handled state_dir=${stateDir}`);
+      return;
+    } catch (error) {
+      fail(error instanceof Error ? error.message : String(error), 3);
+    }
+  }
   const queued = appendControl(
     { controlsFile: join(stateDir, "controls.jsonl"), stateDir },
     command,

package/node_modules/@llblab/pi-actors/dist/skills/swarm/SKILL.md

@@ -9,13 +9,9 @@ Use multi-actor execution only when at least two scopes or evidence lenses are m
 
 Read `actors` first for generic Recipe, spawn, Run, Trace, Control, artifact, and lifecycle operation. This Skill owns only multi-actor methodology: decomposition, scope ownership, independence, synthesis, integration, and completion proof.
 
-## Coordinator topology
+## Coordinator and participants
 
-A swarm can be coordinated without an external gateway. In this model the current host agent is the declarative control plane, the actor kernel creates explicit participant Runs, and companion transports provide ingress or presence without owning hidden agent creation. The coordinator retains user authority, global context, decomposition, shared-surface ownership, integration, and final validation; participants own bounded concrete tasks and report evidence.
-
-This resembles gateway orchestration in dependency direction but not in ownership: the coordinator is itself an agent instance with inspectable Runs, not an infrastructure service that implicitly creates sessions. Preserve that distinction in prompts, docs, recovery, and target routing.
-
-Once work is delegated, keep the coordinator available for decisions and integration instead of duplicating participant implementation. Wait for the settled completion batch by default; use meaningful attention or evidence-based timers for overdue work rather than a tight inspection loop.
+The coordinator owns decomposition, shared contracts, integration order, and final validation. Participants own bounded tasks or evidence lenses. Keep the coordinator available for decisions instead of duplicating participant implementation; use `actors` for launch, observation, and lifecycle mechanics.
 
 ## Reasoning allocation
 

package/node_modules/@llblab/pi-actors/dist/skills/swarm/references/development-swarm.md

@@ -14,38 +14,9 @@ Use a development swarm only when all are true:
 
 Do not parallelize implementation when tasks need the same central files, semantic ordering dominates wall-clock time, or the likely conflicts would invalidate the decomposition. Use planning or review first.
 
-## Coordinator role separation
+## Roles and reasoning
 
-In a host-coordinator topology, the current Pi instance owns the declarative outcome and participant graph rather than acting as the default implementation worker. It may receive intent through Telegram or another companion extension, but transport does not become a gateway or gain hidden instance-creation authority; participant creation remains an explicit actor-kernel Run.
-
-The coordinator should:
-
-- Translate high-level intent into bounded task cards and dependency edges.
-- Keep user authority, shared contracts, integration order, and final validation local.
-- Remain available for checkpoints, permissions, conflicts, and changing evidence.
-- Consume terminal handoffs, durable artifacts, and Trace attention instead of mirroring participant work.
-- Check overdue work on an evidence-based timer; never replace event-driven completion with a rapid polling loop.
-
-A participant should:
-
-- Own one concrete execution or evidence boundary.
-- Avoid global orchestration and undeclared participant creation.
-- Return a bounded handoff that lets the coordinator decide without replaying the entire task.
-
-Use one ordinary Run under `actors` when only one worker is delegated. Activate this development-swarm protocol when two or more participants, parallel ownership, or explicit integration edges exist. Keep trivial single-boundary work inline when delegation overhead has no compensating value.
-
-## Reasoning profiles
-
-| Role | Default | Raise or fan out when |
-| --- | --- | --- |
-| Bounded implementation author | Reasoning off | The card explicitly owns unresolved diagnosis or design judgement |
-| Reviewer | Medium reasoning, clean context | Stakes require independent lenses or repeated judges |
-| Synthesizer / integrator | Medium reasoning | Evidence conflicts, shared contracts move, or merge order is semantic |
-| Coordinator | Sufficient for decomposition and decisions | Scope, authority, or architecture remains unresolved |
-
-Prefer independent review after implementation over asking one author thread to implement, retain all local assumptions, and then certify itself. When risk justifies the cost, use multiple independent reviewers: different lenses increase breadth, while repeated judges increase confidence. Preserve minority high-impact findings and merge only evidence-backed conclusions.
-
-More reviewers are not automatically better. Do not fan out when they would inspect unstable code, share contaminated context, repeat one unsupported claim, or exceed the value of the decision. Never change an already-running participant solely to enforce a newer profile; add a fresh review boundary if evidence remains open.
+Apply [Swarm's coordinator and reasoning contract](../SKILL.md#reasoning-allocation). Task cards record those profiles and the owned execution boundary; participants return evidence without undeclared orchestration. Do not fan out review over unstable code or contaminated context. The sections below specify development-only task cards, ownership transfers, conflict reports, and integration.
 
 ## Decompose by ownership
 

package/node_modules/@llblab/pi-actors/docs/recipe-library.md

@@ -36,7 +36,7 @@ Artifact pipelines terminate in files/manifests and result evidence; they do not
 
 ### Music playback and controlled services
 
-- `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`.
+- `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`. The single `skills/music-player/scripts/playback.mjs` executable also supports standalone foreground `serve` and `control <state-dir> <action> [percent]`; control observes the existing owner, using canonical Control records for Actors and generation-fenced RPC for standalone playback. The maintained Generative App uses that same control entrypoint for Actor-owned playback.
 - `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/node_modules/@llblab/pi-actors/package.json

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

package/node_modules/@llblab/pi-actors/skills/actors/SKILL.md

@@ -76,16 +76,26 @@ Then:
 
 Use direct delegation for the same maintained capability under a persistent name or narrower defaults. Use named imports only when one Recipe graph contains reusable child nodes. See [persistent tools](./references/persistent-tools.md) and [Recipes](./references/recipes.md).
 
-## Local coordinator topology
+## Capability map
 
-There are two distinct multi-instance shapes:
+Recipes remain with the Skill that owns their behavior. Load that Skill for selection and caller inputs; this map is routing, not a copied Recipe contract.
 
-- A gateway-centric system owns ingress, agent-instance creation, routing, and lifecycle outside the agents.
-- A host-coordinator system keeps the current Pi instance as the control plane; companion extensions such as Telegram provide presence, while pi-actors creates explicit local Runs for delegated work.
+| Owner | Recipe families |
+| --- | --- |
+| `actors` | `command-validate`, `recipe-validate`, `jsonl-tail`, `run-summary`, `run-state-files`, `run-ops-snapshot`, `resource-locker`, `resource-locker-snapshot` |
+| `swarm` | Lens and quorum reviews, research synthesis, architecture, development tasking, readiness, and supporting `subagent-*` components |
+| `artifacts` | Report, write, manifest, bundle, and supporting file-write |
+| `project-work` | Repository health, docs maintenance, release readiness/summary, Run reports, and supporting deterministic snapshots |
+| `music-player` | The controlled `playback` singleton |
+| `recipe-memory` | Internal automatic reviewers; use its Skill only for diagnosis/recovery |
 
-In host-coordinator mode, the top-level agent receives declarative outcomes, preserves user authority and global context, delegates bounded concrete execution, and owns integration plus final validation. It is not merely another worker after delegation begins. One bounded implementation worker normally runs with reasoning off; consequential output receives a separate reasoning-enabled review. Several independent participants or reviewers additionally use `swarm`.
+Use the `actors/*` helpers only for their narrow requested result or intentional composition. Prefer public `inspect` for ordinary runtime diagnosis and the capability's primary workflow for a complete outcome.
 
-Delegation is not mandatory for every prompt. Work inline when one short bounded act has one natural validation boundary and spawning would add more coordination than isolation, latency hiding, clean context, or continued coordinator availability can repay. For admitted delegation, prefer the settled completion batch and durable Trace/artifacts; inspect on meaningful attention, operator request, or an evidence-based overdue timer rather than busy polling. Treat `attention: "steer"` as an actor-authored urgent semantic checkpoint at Pi's next safe boundary, never as a status-derived completion signal; the later root terminal still arrives through its ordinary completion batch.
+## Delegation boundary
+
+The current Pi instance owns user authority and the final result; pi-actors creates explicit local Runs, while companion transports provide presence rather than hidden instance creation. Keep short single-boundary work inline when delegation adds no value. For several participants, reasoning allocation, quorum, or integration methodology, read `swarm`.
+
+Treat `attention: "steer"` as an actor-authored urgent semantic checkpoint at Pi's next safe boundary, never as a status-derived completion signal; the later root terminal still arrives through its ordinary completion batch.
 
 ## Run workflow
 

package/node_modules/@llblab/pi-actors/skills/music-player/SKILL.md

@@ -13,7 +13,7 @@ When a Telegram-originated turn or explicit Telegram-control question makes repe
 
 ## 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.
+`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. `scripts/playback.mjs` owns both foreground playback and the bounded control CLI. Its `control <state-dir> <action> [percent]` entrypoint observes or controls an existing owner without starting, adopting, or supervising it. Explicit foreground `serve` supports a caller-owned standalone host without importing the Actor runtime; Actor and standalone ownership of one state directory are mutually exclusive.
 
 ```text
 spawn recipe=music-player/playback values={"source":"~/Music","player":"auto"}
@@ -35,14 +35,14 @@ Use only declared actions: `play`, `pause`, `resume`, `toggle`, `next`, `previou
 - `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.
+External local views use `playback.mjs control <state-dir> <action> [percent]`. For Actor-owned playback, the script validates Run availability, queues canonical Control, and waits for that exact record to become handled or failed. For standalone playback, it sends a bounded generation-fenced command to the service endpoint without creating Run, Control, or Trace state. Views themselves never read or edit Run files, signal processes, construct Control records, or import pi-actors internals. `status` is read-only and reports `actor_available` separately from playback state.
 
 ## 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.
+Bind with absolute `control` (the `scripts/playback.mjs` path), `stateDir`, and `node` arguments. This maintained adapter targets Actor-owned playback and uses the unified `control` entrypoint above for status and mutation; it displays controls only when `actor_available` is true. Exact terminal Control evidence remains visible in the Run inspector and failures reach Telegram. 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
 

package/node_modules/@llblab/pi-actors/skills/music-player/genapps/music-player.mjs

@@ -70,7 +70,7 @@ function normalizePlayback(status) {
 async function readPlayback(adapter, run) {
   const result = await run({
     command: adapter.node,
-    args: [adapter.control, "status", adapter.stateDir],
+    args: [adapter.control, "control", adapter.stateDir, "status"],
     cwd: dirname(adapter.control),
     timeoutMs: 5_000,
   });
@@ -188,8 +188,9 @@ async function applyVolume(percent, context) {
     command: context.state.adapter.node,
     args: [
       context.state.adapter.control,
-      "volume",
+      "control",
       context.state.adapter.stateDir,
+      "volume",
       String(percent),
     ],
     cwd: dirname(context.state.adapter.control),
@@ -224,8 +225,9 @@ async function applySeek(percent, context) {
     command: context.state.adapter.node,
     args: [
       context.state.adapter.control,
-      "seek",
+      "control",
       context.state.adapter.stateDir,
+      "seek",
       String(percent),
     ],
     cwd: dirname(context.state.adapter.control),
@@ -253,7 +255,7 @@ async function apply(action, context) {
   const before = await readPlayback(context.state.adapter, context.run);
   const result = await context.run({
     command: context.state.adapter.node,
-    args: [context.state.adapter.control, action, context.state.adapter.stateDir],
+    args: [context.state.adapter.control, "control", context.state.adapter.stateDir, action],
     cwd: dirname(context.state.adapter.control),
     timeoutMs: 5_000,
   });