@llblab/pi-actors 0.49.0 → 0.49.2

package/BACKLOG.md

@@ -1,6 +1,16 @@
 # Project Backlog
 
-- [ ] `Linux MPRIS media integration`: Expose the active `music-player/playback` singleton as one optional generation-fenced MPRIS2 player so GNOME and compatible desktop shells can show current media and native controls without making D-Bus a second playback authority.
+- [ ] `0.50.0 hardening`: Close the confirmed authorization, bounded-inspection, and operator-truth gaps from the v0.49.1 production-readiness review.
+  - [ ] `Run boundary checkpoint`: Public Run operations remain owner-safe and bounded under missing identity and adversarial evidence sizes.
+    - [ ] Make Run-specific `inspect` and `message` operations fail closed when the caller session identity is unavailable, keep runtime inventory owner-filtered, and add missing-context plus cross-owner regressions.
+    - [ ] Bound session-evidence and artifact-manifest inspection before full-file materialization; use capped/streaming reads or hashing as appropriate and add adversarial-size regressions.
+  - [ ] `Operator truth checkpoint`: Public status and recovery guidance exactly match supported runtime behavior.
+    - [ ] Route automatic-review status through the canonical policy parser so `0`, `false`, and `off` are reported consistently without case sensitivity.
+    - [ ] Replace the removed `session:<id>` and `session:all` recovery hints with supported inspection guidance.
+    - [ ] Document exact `message target=run:<id>` examples for runtime-owned `kill`, `archive`, and `prune`, including their state and artifact-preservation constraints.
+  - [ ] Pass focused boundary and operator-contract regressions plus full package validation before release.
+
+- [ ] `Future minor — Linux MPRIS media integration`: Expose the active `music-player/playback` singleton as one optional generation-fenced MPRIS2 player so GNOME and compatible desktop shells can show current media and native controls without making D-Bus a second playback authority; keep this feature outside the 0.49.2 and 0.50.0 cohorts.
   - [ ] Publish `PlaybackStatus`, track metadata, duration, read-time position, volume, and supported capabilities under one stable session-scoped bus identity; disappear cleanly when the Run stops or its generation is replaced, and fail soft when the user D-Bus session is unavailable.
   - [ ] Map `Play`, `Pause`, `PlayPause`, `Next`, `Previous`, `Stop`, `Seek`, `SetPosition`, and `Volume` back into the existing generation-fenced music-player Control/helper contract rather than signaling the backend or editing Run state directly.
   - [ ] Validate deterministic D-Bus contract behavior plus a live GNOME smoke showing the media surface, metadata, progress, volume, and controls while preserving backend independence and exact Actor ownership.

package/CHANGELOG.md

@@ -4,6 +4,14 @@
 
 ## Unreleased
 
+## 0.49.2: Stale-Context Lifecycle Hotfix
+
+- `Stale-Context Lifecycle Hotfix`: Contains Run UI animation, delayed watcher, reconciliation, error-handler, retirement, and Recipe-reload callbacks so invalidated Pi contexts cannot escape into the host event loop. Session owners are captured while live, stale shutdown cannot close a replacement session, and parent teardown plus shutdown notification remain identity-fenced and no-throw (GitHub issue #125).
+
+## 0.49.1: Maintained Telegram View Routing
+
+- `Maintained Telegram View Routing`: Music Player now treats Telegram-originated control intent as a breadcrumb to its ready capability-owned Generative App, preferring bind/invoke over one-shot prompt buttons while preserving Actor playback authority and an explicit model-mediated fallback when the app runtime is unavailable.
+
 ## 0.49.0: Skill-Scoped Music Player
 
 - `Skill-Scoped Singletons`: Added one optional async singleton Recipe per active Skill with canonical `run:<skill>` and `<skill>/<recipe>` identities, idempotent compatible reuse, lifecycle/process fencing, terminal-generation replacement, delegation-safe identity inheritance, persistent actor-owned state directories, focused inspection, and fail-closed conflicts across Recipe, owner, startup values, and Control.

package/dist/lib/extension-runtime.js

@@ -17,6 +17,8 @@ import * as Tools from "./tools.js";
 import * as ToolsResponse from "./tools-response.js";
 export function createActorExtensionRuntime(pi) {
     let activeRunContext;
+    let activeRunOwnerId;
+    const runOwnerIdsByContext = new WeakMap();
     const recipeResolutionContextsBySession = new Map();
     const getRunOwnerId = Pi.getSessionId;
     const getRecipeResolutionContext = (ctx) => {
@@ -32,9 +34,21 @@ export function createActorExtensionRuntime(pi) {
         getRunOwnerId,
         getThinkingLevel: () => pi.getThinkingLevel(),
     });
-    const runUiRuntime = RunUiRuntime.createRunUiRuntime({
+    let recipeReload;
+    let runUiRuntime;
+    const closeActiveSessionRuntimes = () => {
+        const ownerId = activeRunOwnerId;
+        activeRunContext = undefined;
+        activeRunOwnerId = undefined;
+        runUiRuntime?.close();
+        automaticReview.close();
+        recipeReload?.close();
+        if (ownerId)
+            recipeResolutionContextsBySession.delete(ownerId);
+    };
+    runUiRuntime = RunUiRuntime.createRunUiRuntime({
         getActiveContext: () => activeRunContext,
-        getRunOwnerId,
+        onCallbackError: closeActiveSessionRuntimes,
         onRunEvent: automaticReview.schedule,
         pi,
     });
@@ -77,10 +91,11 @@ export function createActorExtensionRuntime(pi) {
         reservedToolNames: Tools.RESERVED_TOOL_NAMES,
         setActiveTools: (toolNames) => pi.setActiveTools(toolNames),
     });
-    const recipeReload = Runtime.createRecipeToolReloadWatcher(runtime, {
+    recipeReload = Runtime.createRecipeToolReloadWatcher(runtime, {
         getResolutionContext: () => activeRunContext
             ? getRecipeResolutionContext(activeRunContext)
             : undefined,
+        onCallbackError: closeActiveSessionRuntimes,
     });
     return {
         beforeAgentStart(systemPrompt, skills, ctx) {
@@ -102,25 +117,29 @@ export function createActorExtensionRuntime(pi) {
                 automaticReview.schedule();
         },
         onSessionShutdown(reason, ctx) {
-            recipeResolutionContextsBySession.delete(getRunOwnerId(ctx));
-            activeRunContext = undefined;
-            automaticReview.close();
-            recipeReload.close();
-            runUiRuntime.shutdown(reason, ctx);
+            const ownerId = runOwnerIdsByContext.get(ctx);
+            runOwnerIdsByContext.delete(ctx);
+            if (activeRunContext === ctx)
+                closeActiveSessionRuntimes();
+            if (ownerId)
+                recipeResolutionContextsBySession.delete(ownerId);
+            runUiRuntime.shutdown(reason, ownerId, ctx);
         },
         async onSessionStart(ctx) {
             const sessionId = getRunOwnerId(ctx);
             recipeResolutionContextsBySession.set(sessionId, RecipeResolution.createEmptyRecipeResolutionContext(sessionId, ctx.cwd));
             ctx.ui.setWidget("zz-pi-actors-comms", undefined);
             activeRunContext = ctx;
+            activeRunOwnerId = sessionId;
+            runOwnerIdsByContext.set(ctx, sessionId);
             runUiRuntime.close();
             automaticReview.close();
             recipeReload.close();
             await Temp.prepareExtensionTempDir(Paths.EXTENSION_RUNTIME_PATHS.tempDir);
-            if (activeRunContext !== ctx)
+            if (activeRunContext !== ctx || activeRunOwnerId !== sessionId)
                 return;
             automaticReview.start(ctx);
-            runUiRuntime.start(ctx);
+            runUiRuntime.start(ctx, sessionId);
             recipeReload.watch(ctx);
         },
         registerCoreTools() {

package/dist/lib/observability.js

@@ -229,7 +229,12 @@ export function createRunTerminalReconciliationLoop(input) {
             input.reconcile();
         }
         catch (error) {
-            input.onError?.(error);
+            try {
+                input.onError?.(error);
+            }
+            catch {
+                /* reconciliation callbacks must never escape into the host event loop */
+            }
         }
     };
     const close = () => {

package/dist/lib/run-ui-runtime.d.ts

@@ -3,16 +3,23 @@
  * Zones: run watcher lifecycle, terminal reconciliation, status animation, shutdown teardown
  * Owns event-driven run UI coordination without owning actor execution semantics.
  */
+import * as AsyncRuns from "./async-runs.ts";
+import * as Observability from "./observability.ts";
 import * as Pi from "./pi.ts";
 export interface RunUiRuntime {
     close(): void;
-    shutdown(eventReason: string, ctx: Pi.ExtensionContext): void;
-    start(ctx: Pi.ExtensionContext): void;
+    shutdown(eventReason: string, ownerId: string | undefined, ctx?: Pi.ExtensionContext): void;
+    start(ctx: Pi.ExtensionContext, ownerId: string): void;
 }
 export interface RunUiRuntimeDeps {
+    animationIntervalMs?: number;
+    createRunStateWatcher?: typeof Observability.createRunStateWatcher;
+    createRunTerminalReconciliationLoop?: typeof Observability.createRunTerminalReconciliationLoop;
     getActiveContext(): Pi.ExtensionContext | undefined;
-    getRunOwnerId(ctx: Pi.ExtensionContext): string;
+    notificationDelayMs?: number;
+    onCallbackError?: (error: unknown) => void;
     onRunEvent(): void;
     pi: Pi.ExtensionAPI;
+    teardownRunsOwnedByParent?: typeof AsyncRuns.teardownRunsOwnedByParent;
 }
 export declare function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime;

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

@@ -8,22 +8,78 @@ import * as Observability from "./observability.js";
 import * as Paths from "./paths.js";
 import * as Pi from "./pi.js";
 export function createRunUiRuntime(deps) {
+    let activeContext;
+    let activeOwnerId;
     let animationInterval;
     let notifyTimeout;
+    let running = false;
     let lastWatcherDiagnosticId = 0;
     const observation = Observability.createRunUiObservationState();
     const retirementAttempts = new Set();
     const terminalNotificationsInFlight = new Set();
+    const close = () => {
+        running = false;
+        activeContext = undefined;
+        activeOwnerId = undefined;
+        try {
+            watcher.close();
+        }
+        catch {
+            /* cleanup must not escape a host callback */
+        }
+        try {
+            reconciliation.close();
+        }
+        catch {
+            /* cleanup must not escape a host callback */
+        }
+        if (notifyTimeout)
+            clearTimeout(notifyTimeout);
+        notifyTimeout = undefined;
+        if (animationInterval)
+            clearInterval(animationInterval);
+        animationInterval = undefined;
+    };
+    const stopAfterCallbackFailure = (label, error, expectedContext) => {
+        if (activeContext !== expectedContext)
+            return;
+        close();
+        try {
+            deps.onCallbackError?.(error);
+        }
+        catch {
+            /* host callback containment must remain no-throw */
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        try {
+            expectedContext.ui.notify(`Actor ${label} failed: ${message}`, "error");
+        }
+        catch {
+            /* stale context or unavailable UI */
+        }
+    };
+    const runActiveCallback = (label, callback) => {
+        if (!running || !activeContext || !activeOwnerId)
+            return;
+        const ctx = activeContext;
+        try {
+            if (deps.getActiveContext() !== ctx)
+                return;
+            callback(ctx, activeOwnerId);
+        }
+        catch (error) {
+            stopAfterCallbackFailure(label, error, ctx);
+        }
+    };
     const retireCandidateRuns = (ctx, summary) => {
         void Observability.executeRunRetirements(summary, {
             attempted: retirementAttempts,
             cancelRun: (candidate) => AsyncRuns.cancelRun(candidate.stateDir),
             notify: (message, level) => ctx.ui.notify(message, level),
             sendStop: async (candidate) => AsyncRuns.cancelRun(candidate.stateDir),
-        });
+        }).catch((error) => stopAfterCallbackFailure("Run retirement callback", error, ctx));
     };
-    const update = (ctx, notify = false, terminalOnly = false) => {
-        const ownerId = deps.getRunOwnerId(ctx);
+    const update = (ctx, ownerId, notify = false, terminalOnly = false) => {
         const snapshot = Observability.readRunUiSnapshot(observation, ownerId);
         ctx.ui.setStatus("zz-pi-actors-runs", snapshot.status ? ctx.ui.theme.fg("dim", snapshot.status) : undefined);
         if (!notify)
@@ -45,62 +101,55 @@ export function createRunUiRuntime(deps) {
         }
     };
     const scheduleUpdate = () => {
+        if (!running)
+            return;
         if (notifyTimeout)
             clearTimeout(notifyTimeout);
         notifyTimeout = setTimeout(() => {
-            const ctx = deps.getActiveContext();
-            if (!ctx)
-                return;
-            watcher.refresh();
-            update(ctx, true);
-            deps.onRunEvent();
-            reportDiagnostics(ctx);
-        }, 50);
+            runActiveCallback("Run watcher callback", (ctx, ownerId) => {
+                watcher.refresh();
+                update(ctx, ownerId, true);
+                deps.onRunEvent();
+                reportDiagnostics(ctx);
+            });
+        }, deps.notificationDelayMs ?? 50);
         notifyTimeout.unref?.();
     };
-    const watcher = Observability.createRunStateWatcher({
+    const watcher = (deps.createRunStateWatcher ?? Observability.createRunStateWatcher)({
         stateRoot: Paths.EXTENSION_RUNTIME_PATHS.runStateRoot,
         onChange: scheduleUpdate,
     });
-    const reconciliation = Observability.createRunTerminalReconciliationLoop({
+    const reconciliation = (deps.createRunTerminalReconciliationLoop ??
+        Observability.createRunTerminalReconciliationLoop)({
         onError: (error) => {
-            const ctx = deps.getActiveContext();
-            if (!ctx)
+            if (!running || !activeContext)
                 return;
-            const message = error instanceof Error ? error.message : String(error);
-            ctx.ui.notify(`Actor terminal reconciliation failed: ${message}`, "error");
+            stopAfterCallbackFailure("terminal reconciliation callback", error, activeContext);
         },
         reconcile: () => {
-            const ctx = deps.getActiveContext();
-            if (!ctx)
-                return;
-            Observability.reconcileRunTerminalNotifications({
-                inFlight: terminalNotificationsInFlight,
-                ownerId: deps.getRunOwnerId(ctx),
-                sink: Pi.createNotificationSink(deps.pi, ctx),
-                state: observation,
-                includeAttention: true,
+            runActiveCallback("terminal reconciliation callback", (ctx, ownerId) => {
+                Observability.reconcileRunTerminalNotifications({
+                    inFlight: terminalNotificationsInFlight,
+                    ownerId,
+                    sink: Pi.createNotificationSink(deps.pi, ctx),
+                    state: observation,
+                    includeAttention: true,
+                });
+                reportDiagnostics(ctx);
             });
-            reportDiagnostics(ctx);
         },
-        refreshWatcher: () => watcher.refresh(),
+        refreshWatcher: () => {
+            if (running)
+                watcher.refresh();
+        },
     });
-    const close = () => {
-        watcher.close();
-        reconciliation.close();
-        if (notifyTimeout)
-            clearTimeout(notifyTimeout);
-        notifyTimeout = undefined;
-        if (animationInterval)
-            clearInterval(animationInterval);
-        animationInterval = undefined;
-    };
     return {
         close,
-        shutdown(eventReason, ctx) {
-            close();
-            const teardown = AsyncRuns.teardownRunsOwnedByParent(deps.getRunOwnerId(ctx), Paths.EXTENSION_RUNTIME_PATHS.runStateRoot, { trigger: `session_shutdown:${eventReason}` });
-            if (teardown.failed === 0)
+        shutdown(eventReason, ownerId, ctx) {
+            if (!ownerId)
+                return;
+            const teardown = (deps.teardownRunsOwnedByParent ?? AsyncRuns.teardownRunsOwnedByParent)(ownerId, Paths.EXTENSION_RUNTIME_PATHS.runStateRoot, { trigger: `session_shutdown:${eventReason}` });
+            if (teardown.failed === 0 || !ctx)
                 return;
             try {
                 ctx.ui.notify(`Actor shutdown teardown: killed=${teardown.killed} failed=${teardown.failed} skipped=${teardown.skipped} discovery_failed=${teardown.discoveryFailed}. Summary: ${teardown.summaryPath ?? "unavailable"}.`, "warning");
@@ -109,17 +158,25 @@ export function createRunUiRuntime(deps) {
                 /* stale shutdown context */
             }
         },
-        start(ctx) {
+        start(ctx, ownerId) {
             close();
-            Observability.primeRunAttentionState(observation, deps.getRunOwnerId(ctx));
-            update(ctx, true, true);
-            watcher.refresh();
-            reconciliation.start();
-            animationInterval = setInterval(() => {
-                if (deps.getActiveContext() === ctx)
-                    update(ctx);
-            }, 1000);
-            animationInterval.unref?.();
+            activeContext = ctx;
+            activeOwnerId = ownerId;
+            running = true;
+            try {
+                Observability.primeRunAttentionState(observation, ownerId);
+                update(ctx, ownerId, true, true);
+                watcher.refresh();
+                reconciliation.start();
+                animationInterval = setInterval(() => {
+                    runActiveCallback("status animation callback", (current, currentOwnerId) => update(current, currentOwnerId));
+                }, deps.animationIntervalMs ?? 1000);
+                animationInterval.unref?.();
+            }
+            catch (error) {
+                close();
+                throw error;
+            }
         },
     };
 }

package/dist/lib/runtime.d.ts

@@ -63,7 +63,9 @@ export declare function createAutoToolsRuntime(deps: ToolRegistryRuntimeDeps): T
 export interface RecipeToolReloadWatcherDeps {
     exists?: (path: string) => boolean;
     getResolutionContext?: () => RecipeResolutionContext | undefined;
+    onCallbackError?: (error: unknown) => void;
     recipeRoot?: string;
+    reloadDelayMs?: number;
     watchPath?: typeof watch;
 }
 export declare function createRecipeToolReloadWatcher(runtime: Pick<ToolRegistryRuntime, "loadTools"> & Partial<Pick<ToolRegistryRuntime, "setWatchStatus">>, deps?: RecipeToolReloadWatcherDeps): RecipeToolReloadWatcher;

package/dist/lib/runtime.js

@@ -236,21 +236,41 @@ export function createRecipeToolReloadWatcher(runtime, deps = {}) {
         reloadTimeout = undefined;
         setWatchStatus("closed");
     };
+    const reportCallbackError = (error) => {
+        try {
+            deps.onCallbackError?.(error);
+        }
+        catch {
+            /* host callback containment must remain no-throw */
+        }
+    };
     const notifyFailure = (ctx) => {
         if (failureNotified)
             return;
         failureNotified = true;
         setWatchStatus("failed");
-        ctx.ui.notify("Recipe live reload watcher failed; restart the session or use register_tool again to refresh recipe tools.", "warning");
+        try {
+            ctx.ui.notify("Recipe live reload watcher failed; restart the session or use register_tool again to refresh recipe tools.", "warning");
+        }
+        catch (error) {
+            reportCallbackError(error);
+        }
     };
     const scheduleReload = (ctx) => {
         failureNotified = false;
         if (reloadTimeout)
             clearTimeout(reloadTimeout);
         reloadTimeout = setTimeout(() => {
-            runtime.loadTools(ctx, deps.getResolutionContext?.());
-            ctx.ui.notify("Recipe tools refreshed from ~/.pi/agent/recipes", "info");
-        }, 150);
+            reloadTimeout = undefined;
+            try {
+                runtime.loadTools(ctx, deps.getResolutionContext?.());
+                ctx.ui.notify("Recipe tools refreshed from ~/.pi/agent/recipes", "info");
+            }
+            catch (error) {
+                notifyFailure(ctx);
+                reportCallbackError(error);
+            }
+        }, deps.reloadDelayMs ?? 150);
         reloadTimeout.unref?.();
     };
     const watchParent = (ctx, recipeRoot) => {

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

@@ -7,6 +7,10 @@ description: Use for starting, resuming, inspecting, and controlling one persist
 
 Use this Skill for one local music playback service. For generic Recipe execution, singleton Run lifecycle, persistent-tool setup, or diagnosis, follow `actors`; this Skill owns only playback-specific selection and controls.
 
+## Interaction Routing
+
+When a Telegram-originated turn or explicit Telegram-control question makes repeated player controls relevant, prefer the maintained Telegram view described below over synthesizing one-shot prompt buttons. If `telegram_bind` is available, load and follow the active operating guidance that owns Generative Apps, then bind or invoke the capability-owned adapter; do not re-author it or move playback authority into the view. If the runtime is unavailable or binding fails, report that boundary and fall back to ordinary model-mediated controls.
+
 ## Playback
 
 `music-player/playback` is a singleton async controlled service with the canonical address `run:music-player`. The Recipe is the sole lifecycle owner: it starts the service, supervises it, and stops playback when the Run closes. The service owns queue, backend, checkpoint, and playback state. `playback-client.mjs` is a pure actor-neutral RPC client; it never starts, adopts, supervises, or signals a service. The executable also supports explicit foreground `serve` for development or a caller-owned standalone host, but Actor and standalone ownership of one state directory are mutually exclusive.
@@ -33,10 +37,10 @@ Use only declared actions: `play`, `pause`, `resume`, `toggle`, `next`, `previou
 
 External local views use the actor-neutral playback client against the canonical service state directory. They must not read or edit Run files, signal playback processes, construct Actor Control records, or import pi-actors internals. The client validates bounded commands, exact service generation, structured responses, and active endpoint ownership before returning success.
 
-## Optional Telegram View
+## Maintained Telegram View
 
 > [!NOTE]
-> If a Generative App runtime is installed, this Skill includes a ready Music Player app at `genapps/music-player.mjs`. Use `telegram_bind` to copy and install it as app `music-player`; hot replacement keeps the same app name with `replace: true`.
+> 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.
 

package/lib/extension-runtime.ts

@@ -35,6 +35,8 @@ export function createActorExtensionRuntime(
   pi: Pi.ExtensionAPI,
 ): ActorExtensionRuntime {
   let activeRunContext: Pi.ExtensionContext | undefined;
+  let activeRunOwnerId: string | undefined;
+  const runOwnerIdsByContext = new WeakMap<Pi.ExtensionContext, string>();
   const recipeResolutionContextsBySession = new Map<
     string,
     RecipeResolution.RecipeResolutionContext
@@ -55,9 +57,20 @@ export function createActorExtensionRuntime(
     getRunOwnerId,
     getThinkingLevel: () => pi.getThinkingLevel(),
   });
-  const runUiRuntime = RunUiRuntime.createRunUiRuntime({
+  let recipeReload: Runtime.RecipeToolReloadWatcher | undefined;
+  let runUiRuntime: RunUiRuntime.RunUiRuntime;
+  const closeActiveSessionRuntimes = (): void => {
+    const ownerId = activeRunOwnerId;
+    activeRunContext = undefined;
+    activeRunOwnerId = undefined;
+    runUiRuntime?.close();
+    automaticReview.close();
+    recipeReload?.close();
+    if (ownerId) recipeResolutionContextsBySession.delete(ownerId);
+  };
+  runUiRuntime = RunUiRuntime.createRunUiRuntime({
     getActiveContext: () => activeRunContext,
-    getRunOwnerId,
+    onCallbackError: closeActiveSessionRuntimes,
     onRunEvent: automaticReview.schedule,
     pi,
   });
@@ -102,11 +115,12 @@ export function createActorExtensionRuntime(
     reservedToolNames: Tools.RESERVED_TOOL_NAMES,
     setActiveTools: (toolNames) => pi.setActiveTools(toolNames),
   });
-  const recipeReload = Runtime.createRecipeToolReloadWatcher(runtime, {
+  recipeReload = Runtime.createRecipeToolReloadWatcher(runtime, {
     getResolutionContext: () =>
       activeRunContext
         ? getRecipeResolutionContext(activeRunContext)
         : undefined,
+    onCallbackError: closeActiveSessionRuntimes,
   });
   return {
     beforeAgentStart(systemPrompt, skills, ctx) {
@@ -131,11 +145,11 @@ export function createActorExtensionRuntime(
       if (activeRunContext === ctx) automaticReview.schedule();
     },
     onSessionShutdown(reason, ctx) {
-      recipeResolutionContextsBySession.delete(getRunOwnerId(ctx));
-      activeRunContext = undefined;
-      automaticReview.close();
-      recipeReload.close();
-      runUiRuntime.shutdown(reason, ctx);
+      const ownerId = runOwnerIdsByContext.get(ctx);
+      runOwnerIdsByContext.delete(ctx);
+      if (activeRunContext === ctx) closeActiveSessionRuntimes();
+      if (ownerId) recipeResolutionContextsBySession.delete(ownerId);
+      runUiRuntime.shutdown(reason, ownerId, ctx);
     },
     async onSessionStart(ctx) {
       const sessionId = getRunOwnerId(ctx);
@@ -145,13 +159,15 @@ export function createActorExtensionRuntime(
       );
       ctx.ui.setWidget("zz-pi-actors-comms", undefined);
       activeRunContext = ctx;
+      activeRunOwnerId = sessionId;
+      runOwnerIdsByContext.set(ctx, sessionId);
       runUiRuntime.close();
       automaticReview.close();
       recipeReload.close();
       await Temp.prepareExtensionTempDir(Paths.EXTENSION_RUNTIME_PATHS.tempDir);
-      if (activeRunContext !== ctx) return;
+      if (activeRunContext !== ctx || activeRunOwnerId !== sessionId) return;
       automaticReview.start(ctx);
-      runUiRuntime.start(ctx);
+      runUiRuntime.start(ctx, sessionId);
       recipeReload.watch(ctx);
     },
     registerCoreTools() {

package/lib/observability.ts

@@ -418,7 +418,11 @@ export function createRunTerminalReconciliationLoop(input: {
       input.refreshWatcher();
       input.reconcile();
     } catch (error) {
-      input.onError?.(error);
+      try {
+        input.onError?.(error);
+      } catch {
+        /* reconciliation callbacks must never escape into the host event loop */
+      }
     }
   };
   const close = (): void => {

package/lib/run-ui-runtime.ts

@@ -11,25 +11,89 @@ import * as Pi from "./pi.ts";
 
 export interface RunUiRuntime {
   close(): void;
-  shutdown(eventReason: string, ctx: Pi.ExtensionContext): void;
-  start(ctx: Pi.ExtensionContext): void;
+  shutdown(
+    eventReason: string,
+    ownerId: string | undefined,
+    ctx?: Pi.ExtensionContext,
+  ): void;
+  start(ctx: Pi.ExtensionContext, ownerId: string): void;
 }
 
 export interface RunUiRuntimeDeps {
+  animationIntervalMs?: number;
+  createRunStateWatcher?: typeof Observability.createRunStateWatcher;
+  createRunTerminalReconciliationLoop?:
+    typeof Observability.createRunTerminalReconciliationLoop;
   getActiveContext(): Pi.ExtensionContext | undefined;
-  getRunOwnerId(ctx: Pi.ExtensionContext): string;
+  notificationDelayMs?: number;
+  onCallbackError?: (error: unknown) => void;
   onRunEvent(): void;
   pi: Pi.ExtensionAPI;
+  teardownRunsOwnedByParent?: typeof AsyncRuns.teardownRunsOwnedByParent;
 }
 
 export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
+  let activeContext: Pi.ExtensionContext | undefined;
+  let activeOwnerId: string | undefined;
   let animationInterval: NodeJS.Timeout | undefined;
   let notifyTimeout: NodeJS.Timeout | undefined;
+  let running = false;
   let lastWatcherDiagnosticId = 0;
   const observation = Observability.createRunUiObservationState();
   const retirementAttempts = new Set<string>();
   const terminalNotificationsInFlight = new Set<string>();
 
+  const close = (): void => {
+    running = false;
+    activeContext = undefined;
+    activeOwnerId = undefined;
+    try {
+      watcher.close();
+    } catch {
+      /* cleanup must not escape a host callback */
+    }
+    try {
+      reconciliation.close();
+    } catch {
+      /* cleanup must not escape a host callback */
+    }
+    if (notifyTimeout) clearTimeout(notifyTimeout);
+    notifyTimeout = undefined;
+    if (animationInterval) clearInterval(animationInterval);
+    animationInterval = undefined;
+  };
+  const stopAfterCallbackFailure = (
+    label: string,
+    error: unknown,
+    expectedContext: Pi.ExtensionContext,
+  ): void => {
+    if (activeContext !== expectedContext) return;
+    close();
+    try {
+      deps.onCallbackError?.(error);
+    } catch {
+      /* host callback containment must remain no-throw */
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    try {
+      expectedContext.ui.notify(`Actor ${label} failed: ${message}`, "error");
+    } catch {
+      /* stale context or unavailable UI */
+    }
+  };
+  const runActiveCallback = (
+    label: string,
+    callback: (ctx: Pi.ExtensionContext, ownerId: string) => void,
+  ): void => {
+    if (!running || !activeContext || !activeOwnerId) return;
+    const ctx = activeContext;
+    try {
+      if (deps.getActiveContext() !== ctx) return;
+      callback(ctx, activeOwnerId);
+    } catch (error) {
+      stopAfterCallbackFailure(label, error, ctx);
+    }
+  };
   const retireCandidateRuns = (
     ctx: Pi.ExtensionContext,
     summary: Observability.RunSummary,
@@ -39,14 +103,16 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
       cancelRun: (candidate) => AsyncRuns.cancelRun(candidate.stateDir),
       notify: (message, level) => ctx.ui.notify(message, level),
       sendStop: async (candidate) => AsyncRuns.cancelRun(candidate.stateDir),
-    });
+    }).catch((error) =>
+      stopAfterCallbackFailure("Run retirement callback", error, ctx),
+    );
   };
   const update = (
     ctx: Pi.ExtensionContext,
+    ownerId: string,
     notify = false,
     terminalOnly = false,
   ): void => {
-    const ownerId = deps.getRunOwnerId(ctx);
     const snapshot = Observability.readRunUiSnapshot(observation, ownerId);
     ctx.ui.setStatus(
       "zz-pi-actors-runs",
@@ -76,61 +142,63 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
     }
   };
   const scheduleUpdate = (): void => {
+    if (!running) return;
     if (notifyTimeout) clearTimeout(notifyTimeout);
     notifyTimeout = setTimeout(() => {
-      const ctx = deps.getActiveContext();
-      if (!ctx) return;
-      watcher.refresh();
-      update(ctx, true);
-      deps.onRunEvent();
-      reportDiagnostics(ctx);
-    }, 50);
+      runActiveCallback("Run watcher callback", (ctx, ownerId) => {
+        watcher.refresh();
+        update(ctx, ownerId, true);
+        deps.onRunEvent();
+        reportDiagnostics(ctx);
+      });
+    }, deps.notificationDelayMs ?? 50);
     notifyTimeout.unref?.();
   };
-  const watcher = Observability.createRunStateWatcher({
+  const watcher = (deps.createRunStateWatcher ?? Observability.createRunStateWatcher)({
     stateRoot: Paths.EXTENSION_RUNTIME_PATHS.runStateRoot,
     onChange: scheduleUpdate,
   });
-  const reconciliation = Observability.createRunTerminalReconciliationLoop({
+  const reconciliation = (
+    deps.createRunTerminalReconciliationLoop ??
+    Observability.createRunTerminalReconciliationLoop
+  )({
     onError: (error) => {
-      const ctx = deps.getActiveContext();
-      if (!ctx) return;
-      const message = error instanceof Error ? error.message : String(error);
-      ctx.ui.notify(`Actor terminal reconciliation failed: ${message}`, "error");
+      if (!running || !activeContext) return;
+      stopAfterCallbackFailure(
+        "terminal reconciliation callback",
+        error,
+        activeContext,
+      );
     },
     reconcile: () => {
-      const ctx = deps.getActiveContext();
-      if (!ctx) return;
-      Observability.reconcileRunTerminalNotifications({
-        inFlight: terminalNotificationsInFlight,
-        ownerId: deps.getRunOwnerId(ctx),
-        sink: Pi.createNotificationSink(deps.pi, ctx),
-        state: observation,
-        includeAttention: true,
+      runActiveCallback("terminal reconciliation callback", (ctx, ownerId) => {
+        Observability.reconcileRunTerminalNotifications({
+          inFlight: terminalNotificationsInFlight,
+          ownerId,
+          sink: Pi.createNotificationSink(deps.pi, ctx),
+          state: observation,
+          includeAttention: true,
+        });
+        reportDiagnostics(ctx);
       });
-      reportDiagnostics(ctx);
     },
-    refreshWatcher: () => watcher.refresh(),
+    refreshWatcher: () => {
+      if (running) watcher.refresh();
+    },
   });
-  const close = (): void => {
-    watcher.close();
-    reconciliation.close();
-    if (notifyTimeout) clearTimeout(notifyTimeout);
-    notifyTimeout = undefined;
-    if (animationInterval) clearInterval(animationInterval);
-    animationInterval = undefined;
-  };
 
   return {
     close,
-    shutdown(eventReason, ctx) {
-      close();
-      const teardown = AsyncRuns.teardownRunsOwnedByParent(
-        deps.getRunOwnerId(ctx),
+    shutdown(eventReason, ownerId, ctx) {
+      if (!ownerId) return;
+      const teardown = (
+        deps.teardownRunsOwnedByParent ?? AsyncRuns.teardownRunsOwnedByParent
+      )(
+        ownerId,
         Paths.EXTENSION_RUNTIME_PATHS.runStateRoot,
         { trigger: `session_shutdown:${eventReason}` },
       );
-      if (teardown.failed === 0) return;
+      if (teardown.failed === 0 || !ctx) return;
       try {
         ctx.ui.notify(
           `Actor shutdown teardown: killed=${teardown.killed} failed=${teardown.failed} skipped=${teardown.skipped} discovery_failed=${teardown.discoveryFailed}. Summary: ${teardown.summaryPath ?? "unavailable"}.`,
@@ -140,16 +208,26 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
         /* stale shutdown context */
       }
     },
-    start(ctx) {
+    start(ctx, ownerId) {
       close();
-      Observability.primeRunAttentionState(observation, deps.getRunOwnerId(ctx));
-      update(ctx, true, true);
-      watcher.refresh();
-      reconciliation.start();
-      animationInterval = setInterval(() => {
-        if (deps.getActiveContext() === ctx) update(ctx);
-      }, 1000);
-      animationInterval.unref?.();
+      activeContext = ctx;
+      activeOwnerId = ownerId;
+      running = true;
+      try {
+        Observability.primeRunAttentionState(observation, ownerId);
+        update(ctx, ownerId, true, true);
+        watcher.refresh();
+        reconciliation.start();
+        animationInterval = setInterval(() => {
+          runActiveCallback("status animation callback", (current, currentOwnerId) =>
+            update(current, currentOwnerId),
+          );
+        }, deps.animationIntervalMs ?? 1000);
+        animationInterval.unref?.();
+      } catch (error) {
+        close();
+        throw error;
+      }
     },
   };
 }

package/lib/runtime.ts

@@ -308,7 +308,9 @@ export function createAutoToolsRuntime(
 export interface RecipeToolReloadWatcherDeps {
   exists?: (path: string) => boolean;
   getResolutionContext?: () => RecipeResolutionContext | undefined;
+  onCallbackError?: (error: unknown) => void;
   recipeRoot?: string;
+  reloadDelayMs?: number;
   watchPath?: typeof watch;
 }
 
@@ -336,22 +338,39 @@ export function createRecipeToolReloadWatcher(
     reloadTimeout = undefined;
     setWatchStatus("closed");
   };
+  const reportCallbackError = (error: unknown): void => {
+    try {
+      deps.onCallbackError?.(error);
+    } catch {
+      /* host callback containment must remain no-throw */
+    }
+  };
   const notifyFailure = (ctx: RuntimeContext): void => {
     if (failureNotified) return;
     failureNotified = true;
     setWatchStatus("failed");
-    ctx.ui.notify(
-      "Recipe live reload watcher failed; restart the session or use register_tool again to refresh recipe tools.",
-      "warning",
-    );
+    try {
+      ctx.ui.notify(
+        "Recipe live reload watcher failed; restart the session or use register_tool again to refresh recipe tools.",
+        "warning",
+      );
+    } catch (error) {
+      reportCallbackError(error);
+    }
   };
   const scheduleReload = (ctx: RuntimeContext): void => {
     failureNotified = false;
     if (reloadTimeout) clearTimeout(reloadTimeout);
     reloadTimeout = setTimeout(() => {
-      runtime.loadTools(ctx, deps.getResolutionContext?.());
-      ctx.ui.notify("Recipe tools refreshed from ~/.pi/agent/recipes", "info");
-    }, 150);
+      reloadTimeout = undefined;
+      try {
+        runtime.loadTools(ctx, deps.getResolutionContext?.());
+        ctx.ui.notify("Recipe tools refreshed from ~/.pi/agent/recipes", "info");
+      } catch (error) {
+        notifyFailure(ctx);
+        reportCallbackError(error);
+      }
+    }, deps.reloadDelayMs ?? 150);
     reloadTimeout.unref?.();
   };
   const watchParent = (ctx: RuntimeContext, recipeRoot: string): void => {

package/package.json

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

package/skills/music-player/SKILL.md

@@ -7,6 +7,10 @@ description: Use for starting, resuming, inspecting, and controlling one persist
 
 Use this Skill for one local music playback service. For generic Recipe execution, singleton Run lifecycle, persistent-tool setup, or diagnosis, follow `actors`; this Skill owns only playback-specific selection and controls.
 
+## Interaction Routing
+
+When a Telegram-originated turn or explicit Telegram-control question makes repeated player controls relevant, prefer the maintained Telegram view described below over synthesizing one-shot prompt buttons. If `telegram_bind` is available, load and follow the active operating guidance that owns Generative Apps, then bind or invoke the capability-owned adapter; do not re-author it or move playback authority into the view. If the runtime is unavailable or binding fails, report that boundary and fall back to ordinary model-mediated controls.
+
 ## Playback
 
 `music-player/playback` is a singleton async controlled service with the canonical address `run:music-player`. The Recipe is the sole lifecycle owner: it starts the service, supervises it, and stops playback when the Run closes. The service owns queue, backend, checkpoint, and playback state. `playback-client.mjs` is a pure actor-neutral RPC client; it never starts, adopts, supervises, or signals a service. The executable also supports explicit foreground `serve` for development or a caller-owned standalone host, but Actor and standalone ownership of one state directory are mutually exclusive.
@@ -33,10 +37,10 @@ Use only declared actions: `play`, `pause`, `resume`, `toggle`, `next`, `previou
 
 External local views use the actor-neutral playback client against the canonical service state directory. They must not read or edit Run files, signal playback processes, construct Actor Control records, or import pi-actors internals. The client validates bounded commands, exact service generation, structured responses, and active endpoint ownership before returning success.
 
-## Optional Telegram View
+## Maintained Telegram View
 
 > [!NOTE]
-> If a Generative App runtime is installed, this Skill includes a ready Music Player app at `genapps/music-player.mjs`. Use `telegram_bind` to copy and install it as app `music-player`; hot replacement keeps the same app name with `replace: true`.
+> 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.