@llblab/pi-actors 0.51.0 → 0.52.1

package/package.json

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

package/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 terminal follow-up and durable Trace/artifacts; inspect on meaningful attention, operator request, or an evidence-based overdue timer rather than busy polling.
+## 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
 
@@ -97,7 +107,7 @@ Run = Recipe + Trace + Control
 ```
 
 1. Spawn with the exact logical Recipe identity and caller-owned values.
-2. Retain the returned `run:<id>` and normally wait for terminal follow-up instead of polling.
+2. Retain the returned `run:<id>` and normally wait for its settled completion batch instead of polling.
 3. Inspect `view=trace` when retained observations or attention matter.
 4. Inspect `view=control` before diagnosing service readiness, stale work, or saturation.
 5. Send `message` only for an action declared and consumed by that controlled Recipe.

package/skills/actors/references/runs.md

@@ -14,7 +14,7 @@ A rare Skill Recipe may declare `singleton: true`. Do not pass `as`: the runtime
 
 ## Observe
 
-Normally wait for terminal follow-up. Inspect only when requested, when meaningful attention arrives, or when the Run is overdue or blocked:
+Normally wait for the settled completion batch. Inspect only when requested, when meaningful attention arrives, or when the Run is overdue or blocked:
 
 ```text
 inspect target=run:<id> view=recipe

package/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/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/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/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 terminal follow-up 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/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/dist/skills/music-player/scripts/playback-client.mjs

@@ -1,143 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Actor-neutral client for the local Music Player playback protocol.
- *
- * Reads portable JSON status and sends bounded generation-fenced commands to
- * the playback service endpoint without reading pi-actors Run or Control state.
- */
-
-import { existsSync, readFileSync } from "node:fs";
-import { createConnection } from "node:net";
-import { homedir } from "node:os";
-import { join } from "node:path";
-
-const ACTIONS = new Set([
-  "play",
-  "resume",
-  "pause",
-  "toggle",
-  "next",
-  "previous",
-  "seek",
-  "volume",
-  "stop",
-  "status",
-]);
-
-function fail(message, code = 1) {
-  console.error(`music-player: ${message}`);
-  process.exit(code);
-}
-
-function expandPath(value) {
-  if (value === "~") return homedir();
-  if (value.startsWith("~/")) return join(homedir(), value.slice(2));
-  return value;
-}
-
-function readJson(path, fallback) {
-  try {
-    return JSON.parse(readFileSync(path, "utf8"));
-  } catch {
-    return fallback;
-  }
-}
-
-function parsePercent(value, label) {
-  if (!/^\d+$/.test(String(value))) {
-    fail(`${label} percent must be an integer 0..100`, 2);
-  }
-  const percent = Number(value);
-  if (percent < 0 || percent > 100) {
-    fail(`${label} percent must be an integer 0..100`, 2);
-  }
-  return percent;
-}
-
-function projectCurrentProgress(status, nowMs = Date.now()) {
-  const duration = Number(status.duration_seconds);
-  let position = Number(status.position_seconds);
-  const updatedAtMs = Number(status.position_updated_at_ms);
-  if (!Number.isFinite(position)) position = 0;
-  if (status.state === "playing" && Number.isFinite(updatedAtMs)) {
-    position += Math.max(0, nowMs - updatedAtMs) / 1000;
-  }
-  if (!Number.isFinite(duration) || duration <= 0) {
-    return { ...status, progress_percent: null };
-  }
-  position = Math.min(Math.max(position, 0), duration);
-  return {
-    ...status,
-    progress_percent: Math.round((position / duration) * 100),
-    position_seconds: position,
-    position_updated_at_ms: nowMs,
-  };
-}
-
-async function sendCommand(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();
-      rejectResponse(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("error", rejectResponse);
-    socket.on("end", () => {
-      clearTimeout(timeout);
-      try {
-        resolveResponse(JSON.parse(content.trim()));
-      } catch {
-        rejectResponse(new Error("playback service returned invalid JSON"));
-      }
-    });
-  });
-  if (!response?.ok) {
-    throw new Error(response?.error || "playback service rejected the command");
-  }
-}
-
-const [action = "status", rawStateDir, ...actionArgs] = process.argv.slice(2);
-if (!ACTIONS.has(action) || !rawStateDir) {
-  fail("usage: playback-client.mjs <status|play|resume|pause|toggle|next|previous|seek|volume|stop> <state-dir> [action args]", 2);
-}
-const stateDir = expandPath(rawStateDir);
-if (action === "status") {
-  const status = readJson(join(stateDir, "player.json"), { state: "unknown" });
-  process.stdout.write(`${JSON.stringify(projectCurrentProgress(status))}\n`);
-  process.exit(0);
-}
-const endpointPath = join(stateDir, "playback-endpoint.json");
-if (!existsSync(endpointPath)) fail(`playback service is not active: ${stateDir}`, 3);
-const endpoint = readJson(endpointPath, {});
-if (
-  typeof endpoint.path !== "string" ||
-  !endpoint.path ||
-  typeof endpoint.service_instance_id !== "string" ||
-  !endpoint.service_instance_id
-) fail(`playback service endpoint is invalid: ${stateDir}`, 3);
-let input;
-if (action === "seek" || action === "volume") {
-  input = { percent: parsePercent(actionArgs[0], action) };
-}
-try {
-  await sendCommand(endpoint, action === "resume" ? "play" : action, input);
-  console.log(`music-player: command=${action} handled state_dir=${stateDir}`);
-} catch (error) {
-  fail(error instanceof Error ? error.message : String(error), 3);
-}

package/skills/music-player/scripts/playback-client.mjs

@@ -1,143 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Actor-neutral client for the local Music Player playback protocol.
- *
- * Reads portable JSON status and sends bounded generation-fenced commands to
- * the playback service endpoint without reading pi-actors Run or Control state.
- */
-
-import { existsSync, readFileSync } from "node:fs";
-import { createConnection } from "node:net";
-import { homedir } from "node:os";
-import { join } from "node:path";
-
-const ACTIONS = new Set([
-  "play",
-  "resume",
-  "pause",
-  "toggle",
-  "next",
-  "previous",
-  "seek",
-  "volume",
-  "stop",
-  "status",
-]);
-
-function fail(message, code = 1) {
-  console.error(`music-player: ${message}`);
-  process.exit(code);
-}
-
-function expandPath(value) {
-  if (value === "~") return homedir();
-  if (value.startsWith("~/")) return join(homedir(), value.slice(2));
-  return value;
-}
-
-function readJson(path, fallback) {
-  try {
-    return JSON.parse(readFileSync(path, "utf8"));
-  } catch {
-    return fallback;
-  }
-}
-
-function parsePercent(value, label) {
-  if (!/^\d+$/.test(String(value))) {
-    fail(`${label} percent must be an integer 0..100`, 2);
-  }
-  const percent = Number(value);
-  if (percent < 0 || percent > 100) {
-    fail(`${label} percent must be an integer 0..100`, 2);
-  }
-  return percent;
-}
-
-function projectCurrentProgress(status, nowMs = Date.now()) {
-  const duration = Number(status.duration_seconds);
-  let position = Number(status.position_seconds);
-  const updatedAtMs = Number(status.position_updated_at_ms);
-  if (!Number.isFinite(position)) position = 0;
-  if (status.state === "playing" && Number.isFinite(updatedAtMs)) {
-    position += Math.max(0, nowMs - updatedAtMs) / 1000;
-  }
-  if (!Number.isFinite(duration) || duration <= 0) {
-    return { ...status, progress_percent: null };
-  }
-  position = Math.min(Math.max(position, 0), duration);
-  return {
-    ...status,
-    progress_percent: Math.round((position / duration) * 100),
-    position_seconds: position,
-    position_updated_at_ms: nowMs,
-  };
-}
-
-async function sendCommand(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();
-      rejectResponse(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("error", rejectResponse);
-    socket.on("end", () => {
-      clearTimeout(timeout);
-      try {
-        resolveResponse(JSON.parse(content.trim()));
-      } catch {
-        rejectResponse(new Error("playback service returned invalid JSON"));
-      }
-    });
-  });
-  if (!response?.ok) {
-    throw new Error(response?.error || "playback service rejected the command");
-  }
-}
-
-const [action = "status", rawStateDir, ...actionArgs] = process.argv.slice(2);
-if (!ACTIONS.has(action) || !rawStateDir) {
-  fail("usage: playback-client.mjs <status|play|resume|pause|toggle|next|previous|seek|volume|stop> <state-dir> [action args]", 2);
-}
-const stateDir = expandPath(rawStateDir);
-if (action === "status") {
-  const status = readJson(join(stateDir, "player.json"), { state: "unknown" });
-  process.stdout.write(`${JSON.stringify(projectCurrentProgress(status))}\n`);
-  process.exit(0);
-}
-const endpointPath = join(stateDir, "playback-endpoint.json");
-if (!existsSync(endpointPath)) fail(`playback service is not active: ${stateDir}`, 3);
-const endpoint = readJson(endpointPath, {});
-if (
-  typeof endpoint.path !== "string" ||
-  !endpoint.path ||
-  typeof endpoint.service_instance_id !== "string" ||
-  !endpoint.service_instance_id
-) fail(`playback service endpoint is invalid: ${stateDir}`, 3);
-let input;
-if (action === "seek" || action === "volume") {
-  input = { percent: parsePercent(actionArgs[0], action) };
-}
-try {
-  await sendCommand(endpoint, action === "resume" ? "play" : action, input);
-  console.log(`music-player: command=${action} handled state_dir=${stateDir}`);
-} catch (error) {
-  fail(error instanceof Error ? error.message : String(error), 3);
-}