@llblab/pi-actors 0.52.0 → 0.53.0

package/dist/lib/run-delivery.js

@@ -11,6 +11,10 @@ import * as Limits from "./limits.js";
 const RUN_DELIVERY_SCHEMA = "run-delivery-v1";
 const MEMBER_FIELDS = new Set([
     "artifacts",
+    "parent_run",
+    "parent_run_instance_id",
+    "parent_state_dir",
+    "output",
     "run",
     "run_instance_id",
     "state_dir",
@@ -107,8 +111,32 @@ function parseMember(value) {
     const record = asRecord(value, "Completion batch member");
     assertExactFields(record, MEMBER_FIELDS, "Completion batch member");
     const parsedArtifacts = artifacts(record.artifacts);
+    const parentRun = record.parent_run === undefined
+        ? undefined
+        : boundedString(record.parent_run, "Completion batch member parent_run", 120);
+    const parentRunInstanceId = record.parent_run_instance_id === undefined
+        ? undefined
+        : boundedString(record.parent_run_instance_id, "Completion batch member parent_run_instance_id", 256);
+    const parentStateDir = record.parent_state_dir === undefined
+        ? undefined
+        : boundedString(record.parent_state_dir, "Completion batch member parent_state_dir", 4_096);
+    if (Boolean(parentRun) !== Boolean(parentRunInstanceId) ||
+        Boolean(parentRun) !== Boolean(parentStateDir)) {
+        throw new Error("Completion batch member parent lineage is incomplete");
+    }
+    const output = record.output === undefined
+        ? undefined
+        : boundedString(record.output, "Completion batch member output", 4_000);
     return {
         ...(parsedArtifacts ? { artifacts: parsedArtifacts } : {}),
+        ...(output ? { output } : {}),
+        ...(parentRun
+            ? {
+                parent_run: parentRun,
+                parent_run_instance_id: parentRunInstanceId,
+                parent_state_dir: parentStateDir,
+            }
+            : {}),
         run: boundedString(record.run, "Completion batch member run", 120),
         run_instance_id: boundedString(record.run_instance_id, "Completion batch member run_instance_id", 256),
         state_dir: boundedString(record.state_dir, "Completion batch member state_dir", 4_096),
@@ -566,13 +594,79 @@ function compactModelText(value, limit) {
     const compact = value.replaceAll(/\s+/g, " ").replaceAll("`", "'").trim();
     return compact.length > limit ? `${compact.slice(0, limit - 1)}…` : compact;
 }
-function formatCompletionMember(member) {
+function memberIdentity(member) {
+    return `${member.state_dir}\0${member.run_instance_id}`;
+}
+function completionDepth(member, byIdentity) {
+    const visited = new Set();
+    let current = member;
+    let depth = 0;
+    while (current.parent_state_dir && current.parent_run_instance_id) {
+        const identity = `${current.parent_state_dir}\0${current.parent_run_instance_id}`;
+        if (visited.has(identity))
+            break;
+        visited.add(identity);
+        const parent = byIdentity.get(identity);
+        if (!parent)
+            break;
+        depth += 1;
+        current = parent;
+    }
+    return depth;
+}
+function orderCompletionForest(members) {
+    const byIdentity = new Map(members.map((member) => [memberIdentity(member), member]));
+    const children = new Map();
+    const roots = [];
+    for (const member of members) {
+        const parentIdentity = member.parent_state_dir && member.parent_run_instance_id
+            ? `${member.parent_state_dir}\0${member.parent_run_instance_id}`
+            : undefined;
+        if (!parentIdentity || !byIdentity.has(parentIdentity)) {
+            roots.push(member);
+            continue;
+        }
+        const siblings = children.get(parentIdentity) ?? [];
+        siblings.push(member);
+        children.set(parentIdentity, siblings);
+    }
+    const ordered = [];
+    const visited = new Set();
+    const visit = (member) => {
+        const identity = memberIdentity(member);
+        if (visited.has(identity))
+            return;
+        visited.add(identity);
+        ordered.push(member);
+        for (const child of children.get(identity) ?? [])
+            visit(child);
+    };
+    for (const root of roots)
+        visit(root);
+    for (const member of members)
+        visit(member);
+    return ordered;
+}
+function formatModelOutput(value, indent) {
+    return value
+        .replaceAll("`", "'")
+        .split(/\r?\n/u)
+        .map((line) => line.trimEnd())
+        .filter((line, index, lines) => line || (index > 0 && index < lines.length - 1))
+        .map((line) => `${indent}  ${line}`)
+        .join("\n");
+}
+function formatCompletionMember(member, byIdentity) {
     const summary = compactModelText(member.summary, 200);
     const artifactEntries = Object.entries(member.artifacts ?? {}).slice(0, 4);
     const artifactText = artifactEntries.length === 0
         ? ""
         : `; artifacts: ${artifactEntries.map(([name, path]) => `${compactModelText(name, 120)}=\`${compactModelText(path, 320)}\``).join(", ")}`;
-    return `- \`${compactModelText(member.run, 120)}\` — \`${member.status}\`: ${summary}${artifactText}`;
+    const indent = "  ".repeat(Math.min(completionDepth(member, byIdentity), 8));
+    const output = member.output
+        ? `\n${indent}  Output:\n${formatModelOutput(member.output, indent)}`
+        : "";
+    return `${indent}- \`${compactModelText(member.run, 120)}\` — \`${member.status}\`: ${summary}${artifactText}${output}`;
 }
 function formatStatusCounts(members) {
     const counts = new Map();
@@ -594,9 +688,13 @@ export function formatRunCompletionBatchMessage(batch) {
         `Window: \`${terminalTimes[0]}\` → \`${terminalTimes.at(-1)}\``,
         `Statuses: \`${formatStatusCounts(safe.members)}\``,
     ];
-    const candidateRows = safe.members
+    const byIdentity = new Map(safe.members.map((member) => [
+        memberIdentity(member),
+        member,
+    ]));
+    const candidateRows = orderCompletionForest(safe.members)
         .slice(0, Limits.RUN_DELIVERY_MODEL_MAX_MEMBERS)
-        .map(formatCompletionMember);
+        .map((member) => formatCompletionMember(member, byIdentity));
     const rows = [];
     for (const row of candidateRows) {
         const omitted = safe.members.length - rows.length - 1;

package/dist/lib/run-ui-runtime.js

@@ -9,18 +9,18 @@ import * as Observability from "./observability.js";
 import * as Paths from "./paths.js";
 import * as Pi from "./pi.js";
 import * as RunDelivery from "./run-delivery.js";
+import * as RunDeliveryLineage from "./run-delivery-lineage.js";
 export function createRunUiRuntime(deps) {
     let activeContext;
     let activeOwnerId;
     let animationInterval;
     let deliveryTimeout;
     let notifyTimeout;
-    let recoverQueuedBatch = false;
     let recoverQueuedSteers = false;
     let running = false;
     let lastWatcherDiagnosticId = 0;
     const observation = Observability.createRunUiObservationState();
-    const deliveryRecoveryDiagnostics = new Set();
+    const deliveryObservation = Observability.createRunUiObservationState();
     const retirementAttempts = new Set();
     const steerDiagnostics = new Set();
     const close = () => {
@@ -45,9 +45,7 @@ export function createRunUiRuntime(deps) {
         if (deliveryTimeout)
             clearTimeout(deliveryTimeout);
         deliveryTimeout = undefined;
-        recoverQueuedBatch = false;
         recoverQueuedSteers = false;
-        deliveryRecoveryDiagnostics.clear();
         steerDiagnostics.clear();
         if (animationInterval)
             clearInterval(animationInterval);
@@ -173,12 +171,11 @@ export function createRunUiRuntime(deps) {
             }
         }
     };
-    const admitCompletionTransitions = (ownerId, transitions) => {
+    const admitCompletionTransitions = (ownerId, snapshot) => {
         const existing = journal(ownerId).completion_batch;
         if (existing)
             return true;
-        const members = Observability.collectRunCompletionBatchMembers(transitions)
-            .slice(0, Limits.RUN_DELIVERY_BATCH_MAX_MEMBERS);
+        const members = Observability.collectRunCompletionBatchMembers(snapshot.transitions, snapshot.summary.runs).slice(0, Limits.RUN_DELIVERY_BATCH_MAX_MEMBERS);
         if (members.length === 0)
             return false;
         RunDelivery.admitRunCompletionBatch({
@@ -189,6 +186,10 @@ export function createRunUiRuntime(deps) {
         return true;
     };
     const isIdle = (ctx) => typeof ctx.isIdle !== "function" || ctx.isIdle();
+    const isDeliveryRoot = (ownerId) => {
+        const inheritedOwner = RunDeliveryLineage.getProcessDeliveryOwnerId();
+        return inheritedOwner === undefined || inheritedOwner === ownerId;
+    };
     let flushCompletionBatch = (_ctx) => false;
     const flushSteers = (ctx, ownerId) => {
         const recovering = recoverQueuedSteers;
@@ -273,10 +274,19 @@ export function createRunUiRuntime(deps) {
             return false;
         const sink = Pi.createNotificationSink(deps.pi, ctx);
         retireCandidateRuns(ctx, snapshot.summary);
-        const hasCompletionCandidates = Observability.collectRunCompletionBatchMembers(snapshot.transitions).length > 0;
-        const hasCompletionBatch = Boolean(journal(ownerId).completion_batch);
+        const deliverySnapshot = isDeliveryRoot(ownerId)
+            ? Observability.readRunDeliverySnapshot(deliveryObservation, ownerId)
+            : undefined;
+        const hasCompletionCandidates = deliverySnapshot
+            ? Observability.collectRunCompletionBatchMembers(deliverySnapshot.transitions, deliverySnapshot.summary.runs).length > 0
+            : false;
+        const hasCompletionBatch = isDeliveryRoot(ownerId) &&
+            Boolean(journal(ownerId).completion_batch);
         admitSteerEvents(ctx, ownerId, snapshot.attentionEvents);
         Observability.pruneRunUiObservationState(observation, snapshot);
+        if (deliverySnapshot) {
+            Observability.pruneRunUiObservationState(deliveryObservation, deliverySnapshot);
+        }
         if (!terminalOnly) {
             Observability.deliverRunAttentionNotifications(snapshot.attentionEvents.filter((event) => !Observability.isRunSteerAttentionEvent(event)), sink);
         }
@@ -333,27 +343,34 @@ export function createRunUiRuntime(deps) {
         },
     });
     flushCompletionBatch = (ctx) => {
-        if (!running || activeContext !== ctx || deps.getActiveContext() !== ctx)
-            return false;
         const ownerId = activeOwnerId;
-        if (!ownerId)
+        if (!running || !ownerId)
+            return false;
+        try {
+            if (Pi.getSessionId(ctx) !== ownerId)
+                return false;
+        }
+        catch {
             return false;
+        }
         if (flushSteers(ctx, ownerId))
             return true;
+        if (!isDeliveryRoot(ownerId))
+            return false;
         let batch = journal(ownerId).completion_batch;
         if (!batch) {
-            const snapshot = Observability.readRunUiSnapshot(observation, ownerId);
-            admitCompletionTransitions(ownerId, snapshot.transitions);
-            Observability.pruneRunUiObservationState(observation, snapshot);
+            const snapshot = Observability.readRunDeliverySnapshot(deliveryObservation, ownerId);
+            admitCompletionTransitions(ownerId, snapshot);
+            Observability.pruneRunUiObservationState(deliveryObservation, snapshot);
             batch = journal(ownerId).completion_batch;
         }
         if (!batch)
             return false;
         if (batch.phase === "presented") {
             finishPresentedBatch(ownerId, batch);
-            const snapshot = Observability.readRunUiSnapshot(observation, ownerId);
-            admitCompletionTransitions(ownerId, snapshot.transitions);
-            Observability.pruneRunUiObservationState(observation, snapshot);
+            const snapshot = Observability.readRunDeliverySnapshot(deliveryObservation, ownerId);
+            admitCompletionTransitions(ownerId, snapshot);
+            Observability.pruneRunUiObservationState(deliveryObservation, snapshot);
             batch = journal(ownerId).completion_batch;
             if (!batch)
                 return false;
@@ -362,27 +379,16 @@ export function createRunUiRuntime(deps) {
             return true;
         const content = RunDelivery.formatRunCompletionBatchMessage(batch);
         if (batch.phase === "queued") {
-            if (!recoverQueuedBatch)
-                return true;
-            recoverQueuedBatch = false;
-            const evidence = Pi.inspectRunCompletionBatchSessionEvidence(ctx, batch.batch_id, content);
-            if (evidence.status === "present")
-                return true;
-            if (evidence.status !== "absent") {
-                const diagnosticKey = `${batch.batch_id}:${evidence.status}:${evidence.reason ?? ""}`;
-                if (!deliveryRecoveryDiagnostics.has(diagnosticKey)) {
-                    deliveryRecoveryDiagnostics.add(diagnosticKey);
-                    ctx.ui.notify(`Actor completion recovery is ${evidence.status}: ${evidence.reason ?? "conflicting session evidence"}. Batch ${batch.batch_id} remains queued.`, "warning");
-                }
-                return true;
-            }
-            if (!RunDelivery.resetRunCompletionBatchPending({
+            if (!RunDelivery.markRunCompletionBatchPresented({
                 batchId: batch.batch_id,
                 ownerId,
                 tempDir: Paths.EXTENSION_RUNTIME_PATHS.tempDir,
             }))
                 return true;
-            batch = journal(ownerId).completion_batch;
+            const accepted = journal(ownerId).completion_batch;
+            if (accepted)
+                finishPresentedBatch(ownerId, accepted);
+            return flushCompletionBatch(ctx);
         }
         if (!isIdle(ctx))
             return true;
@@ -405,19 +411,33 @@ export function createRunUiRuntime(deps) {
         })) {
             throw new Error("Completion batch changed before queue acknowledgment");
         }
-        recoverQueuedBatch = false;
+        if (!RunDelivery.markRunCompletionBatchPresented({
+            batchId: batch.batch_id,
+            ownerId,
+            tempDir: Paths.EXTENSION_RUNTIME_PATHS.tempDir,
+        })) {
+            throw new Error("Completion batch changed before durable acceptance");
+        }
+        const accepted = journal(ownerId).completion_batch;
+        if (accepted)
+            finishPresentedBatch(ownerId, accepted);
+        ctx.ui.notify(`Actor completions ready: ${batch.members.length}`, "info");
         return true;
     };
     return {
         close,
         flushCompletionBatch,
         projectContext(messages, ctx) {
-            if (!running || activeContext !== ctx || deps.getActiveContext() !== ctx) {
+            const ownerId = activeOwnerId;
+            if (!running || !ownerId)
                 return messages;
+            try {
+                if (Pi.getSessionId(ctx) !== ownerId)
+                    return messages;
             }
-            const ownerId = activeOwnerId;
-            if (!ownerId)
+            catch {
                 return messages;
+            }
             const steerContext = Pi.dedupeRunSteerContext(messages);
             let contextMessages = steerContext.messages;
             for (const steer of journal(ownerId).steers) {
@@ -486,7 +506,6 @@ export function createRunUiRuntime(deps) {
             close();
             activeContext = ctx;
             activeOwnerId = ownerId;
-            recoverQueuedBatch = true;
             recoverQueuedSteers = true;
             running = true;
             try {

package/dist/lib/runtime.js

@@ -223,6 +223,7 @@ export function createRecipeToolReloadWatcher(runtime, deps = {}) {
     let rootWatcher;
     let parentWatcher;
     let failureNotified = false;
+    let notifyAfterReload = false;
     const setWatchStatus = (watchStatus) => runtime.setWatchStatus?.(watchStatus);
     const close = () => {
         const closingRoot = rootWatcher;
@@ -234,6 +235,7 @@ export function createRecipeToolReloadWatcher(runtime, deps = {}) {
         if (reloadTimeout)
             clearTimeout(reloadTimeout);
         reloadTimeout = undefined;
+        notifyAfterReload = false;
         setWatchStatus("closed");
     };
     const reportCallbackError = (error) => {
@@ -256,15 +258,19 @@ export function createRecipeToolReloadWatcher(runtime, deps = {}) {
             reportCallbackError(error);
         }
     };
-    const scheduleReload = (ctx) => {
+    const scheduleReload = (ctx, notifyActiveChange = false) => {
         failureNotified = false;
+        notifyAfterReload ||= notifyActiveChange;
         if (reloadTimeout)
             clearTimeout(reloadTimeout);
         reloadTimeout = setTimeout(() => {
             reloadTimeout = undefined;
             try {
                 runtime.loadTools(ctx, deps.getResolutionContext?.());
-                ctx.ui.notify("Recipe tools refreshed from ~/.pi/agent/recipes", "info");
+                if (notifyAfterReload) {
+                    ctx.ui.notify("Recipe tools refreshed from ~/.pi/agent/recipes", "info");
+                }
+                notifyAfterReload = false;
             }
             catch (error) {
                 notifyFailure(ctx);
@@ -295,7 +301,7 @@ export function createRecipeToolReloadWatcher(runtime, deps = {}) {
                 parentWatcher = undefined;
                 watcher.close();
                 watchRoot(ctx, recipeRoot);
-                scheduleReload(ctx);
+                scheduleReload(ctx, true);
             });
             parentWatcher = watcher;
             setWatchStatus("watching_parent");
@@ -319,17 +325,19 @@ export function createRecipeToolReloadWatcher(runtime, deps = {}) {
             return;
         }
         try {
-            const watcher = watchPath(recipeRoot, () => {
+            const watcher = watchPath(recipeRoot, (_event, changedFile) => {
                 if (rootWatcher !== watcher)
                     return;
                 if (!pathExists(recipeRoot)) {
                     rootWatcher = undefined;
                     watcher.close();
-                    scheduleReload(ctx);
+                    scheduleReload(ctx, true);
                     watchParent(ctx, recipeRoot);
                     return;
                 }
-                scheduleReload(ctx);
+                const relativeChange = changedFile ? String(changedFile) : "";
+                const firstSegment = relativeChange.split(/[\\/]/u)[0];
+                scheduleReload(ctx, Boolean(relativeChange) && firstSegment !== "drafts");
             });
             rootWatcher = watcher;
             setWatchStatus("watching_root");

package/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
 
@@ -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 its settled completion batch instead of polling.
+2. Retain the returned `run:<id>` and normally wait for the root coordinator's settled completion batch instead of polling. Nested actor completions accumulate under their containing top-level Run and arrive in that one tree-compressed batch; descendant sessions do not need notification options.
 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/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/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,
   });