@llblab/pi-actors 0.51.0 → 0.52.1

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 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/dist/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/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,
   });

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

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

package/dist/skills/swarm/SKILL.md

@@ -9,13 +9,9 @@ Use multi-actor execution only when at least two scopes or evidence lenses are m
 
 Read `actors` first for generic Recipe, spawn, Run, Trace, Control, artifact, and lifecycle operation. This Skill owns only multi-actor methodology: decomposition, scope ownership, independence, synthesis, integration, and completion proof.
 
-## Coordinator topology
+## Coordinator and participants
 
-A swarm can be coordinated without an external gateway. In this model the current host agent is the declarative control plane, the actor kernel creates explicit participant Runs, and companion transports provide ingress or presence without owning hidden agent creation. The coordinator retains user authority, global context, decomposition, shared-surface ownership, integration, and final validation; participants own bounded concrete tasks and report evidence.
-
-This resembles gateway orchestration in dependency direction but not in ownership: the coordinator is itself an agent instance with inspectable Runs, not an infrastructure service that implicitly creates sessions. Preserve that distinction in prompts, docs, recovery, and target routing.
-
-Once work is delegated, keep the coordinator available for decisions and integration instead of duplicating participant implementation. Wait for 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/dist/skills/swarm/references/development-swarm.md

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

package/docs/README.md

@@ -7,6 +7,7 @@ Living index of all documentation in the `/docs` directory.
 - [command-templates.md](./command-templates.md) — Portable synchronous command execution standard
 - [template-recipes.md](./template-recipes.md) — Saved JSON/Markdown recipe standard, imports, and reusable command-template graph composition
 - [async-runs.md](./async-runs.md) — Run lifecycle, state, Control, Trace, cancellation, and terminal reconciliation
+- [coordinator-delivery.md](./coordinator-delivery.md) — Accepted next-minor design for durable terminal batching and explicit urgent Pi steering
 - [actor-inspector.md](./actor-inspector.md) — Owner-filtered actor-instance navigation through Recipe, Trace, and Control
 - [inspection.md](./inspection.md) — Complete `inspect` target/view matrix, authorization boundaries, and diagnostic routes
 - [tool-registry.md](./tool-registry.md) — Local `pi-actors` registry storage and `register_tool` adaptation

package/docs/async-runs.md

@@ -54,11 +54,12 @@ Trace records strict bounded events:
 ```json
 {"id":"…","ts":"…","kind":"command.done","summary":"Command completed","data":{"code":0},"level":"info"}
 {"id":"…","ts":"…","kind":"checkpoint.ready","summary":"Review needs a decision","level":"info","attention":"followup"}
+{"id":"…","ts":"…","kind":"checkpoint.blocked","summary":"Approval required before migration","level":"warning","attention":"steer"}
 ```
 
 Required fields: `id`, `ts`, `kind`. Optional fields: `summary`, `data`, `level`, `attention`. Trace rejects addressed-envelope fields and malformed or oversized data. It retains a recent suffix within 2,048 events and 4 MiB. When either bound would be exceeded, the canonical lock atomically keeps a newest suffix near the lower targets, the new event, and one cumulative warning-only `runtime.trace_compacted` marker. The marker means older history was discarded; it reports cumulative drop evidence and never requests attention.
 
-Runtime lifecycle, runner progress, command completion, cancellation, kill, parent teardown, and controlled-service observations use Trace. Generic command lifecycle is Trace-only: runner-owned `command.done` records preserve level, captures, session provenance, and execution evidence but never request or project attention. No Recipe field configures command-completion delivery. Semantic checkpoints opt in explicitly with `attention: "notify"` or `attention: "followup"`; they must not infer coordinator intent from a leaf exit code. Bounded reads preserve complete UTF-8 lines and disclose omitted legacy prefixes. `inspect view=trace` reports retained-history completeness and projects events with Controls, owned Pi turns, logs, results, artifacts, and diagnostics newest-first. Equal timestamps use same-source physical order, then fixed source rank and stable id without claiming cross-source causality. Terminal state, `result.json`, `execution.json`, and artifacts remain authoritative even when old Trace has compacted.
+Runtime lifecycle, runner progress, command completion, cancellation, kill, parent teardown, and controlled-service observations use Trace. Generic command lifecycle is Trace-only: runner-owned `command.done` records preserve level, captures, session provenance, and execution evidence but never request or project attention, even if malformed legacy evidence carries `steer`. No Recipe field configures command-completion delivery. Semantic checkpoints opt in explicitly: `attention: "notify"` is visible status, `attention: "followup"` supplies ordinary checkpoint context, and `attention: "steer"` requests urgent delivery at Pi's next safe assistant/tool boundary. Steer is never inferred from exit status; its exact Run generation and event id enter the bounded owner journal before Pi delivery, recover through owned session evidence, and require exact model-bound context acknowledgment. Presentation appends a generation-fenced non-attention `delivery.steer_presented` Trace marker so historical retained steer events cannot replay after bounded owner receipts rotate. The eventual root terminal remains independently eligible for its completion batch. Bounded reads preserve complete UTF-8 lines and disclose omitted legacy prefixes. `inspect view=trace` reports retained-history completeness and projects events with Controls, owned Pi turns, logs, results, artifacts, and diagnostics newest-first. Equal timestamps use same-source physical order, then fixed source rank and stable id without claiming cross-source causality. Terminal state, `result.json`, `execution.json`, and artifacts remain authoritative even when old Trace has compacted.
 
 ## Control
 
@@ -109,9 +110,9 @@ Statuses include `running`, `done`, `failed`, `exited`, `cancelled`, and `killed
 
 Ambient observation detects root terminal transitions and explicit retained Trace attention. Terminal transitions reconcile before semantic attention. Canonical attention is an in-memory wake hint, not a durable queue: observers prime retained ids at startup, deliver each later retained unseen id once, and bound memory to the current retained set across compaction. Persist durable recovery state or an artifact before emitting attention; compaction may discard older hints and its marker makes that history loss explicit. Terminal follow-up delivery persists handled/failure evidence so reloads retry unhandled transitions without duplicating completed notifications.
 
-By default, one normal finite Run produces exactly one automatic agent turn from its root terminal result. Sequence, parallel, repeat, and imported branches are internal execution topology and never own branch-level turns. Each separately launched Run owns its own generation and terminal lifecycle; compatible singleton reuse is not a new launch. Explicit semantic attention may intentionally add a checkpoint turn; Runs marked silent suppress automatic projection.
+Ordinary finite Runs project root terminal results through one completion scheduler. Eligible terminals remain authoritative in Run state while Pi is active; after `agent_settled`, session recovery, or an idle debounce, the scheduler snapshots at most 256 exact generations into one owner-fenced immutable batch. One batch causes one automatic agent turn, exposes at most 64 bounded model-facing rows, and marks member terminals handled only after the exact batch id and content appear in model-bound Pi context. Pending send failures retain bounded retry evidence. On restart, queued recovery inspects only a bounded active Pi session parent chain: exact message evidence waits for presentation without resend, proven absence returns the same batch to pending, and incomplete or conflicting evidence stays queued with a diagnostic. Duplicate exact context envelopes collapse before presentation.
 
-Large semantic results stay outside compact visible follow-up text and remain available in structured details, execution captures, or artifacts.
+Sequence, parallel, repeat, and imported branches are internal execution topology and never own branch-level turns. Each separately launched Run owns its own generation and terminal lifecycle; compatible singleton reuse is not a new launch. Explicit semantic attention may intentionally add a checkpoint turn; Runs marked silent and synchronously acknowledged stop outcomes suppress automatic projection. Large semantic results stay outside compact completion rows and remain available in structured details, execution captures, or artifacts.
 
 ## Cancellation and Kill
 

package/docs/coordinator-delivery.md

@@ -0,0 +1,207 @@
+# Coordinator Delivery Scheduler
+
+Status: Accepted next-minor design. Implementation is in progress; public delivery behavior remains unchanged until the complete acceptance boundary passes.
+
+## Goal
+
+Separate durable Run completion truth from the scheduling of model turns:
+
+```text
+one Run generation -> one root terminal record
+one bounded completion epoch -> one coordinator turn
+```
+
+Ordinary root terminals accumulate while Pi is active and reach the coordinator in one bounded batch after Pi settles. Only an explicitly actor-authored urgent semantic checkpoint may steer an active agent loop.
+
+## Non-Goals
+
+- Do not interrupt generation mid-token.
+- Do not stream generic progress or Command lifecycle into model context.
+- Do not infer urgency from exit codes, failure status, artifacts, branch position, or active subagent counts.
+- Do not change Run, Recipe, Trace, Control, artifact, generation, ownership, or Inspect authority.
+- Do not add transport-specific behavior or restore Recipe-level Command delivery grammar.
+
+## Delivery Classes
+
+- Generic Trace and runner-owned `command.done` remain Trace-only.
+- `attention: "notify"` remains visible UI status without a model turn.
+- `attention: "followup"` retains its existing explicit semantic follow-up behavior.
+- New `attention: "steer"` requests urgent semantic delivery at Pi's next safe assistant/tool boundary.
+- Root terminal transitions enter durable completion batching instead of sending one follow-up per Run.
+
+`command.done` remains non-projectable even if malformed or legacy Trace attaches any attention value.
+
+## Ownership
+
+- Run terminal state remains completion truth; the absence of `terminal-handled.json` makes that generation eligible for projection.
+- `runs-trace.ts` owns admission of the new `steer` attention value.
+- `observability.ts` discovers terminal candidates and explicit semantic attention without deciding Pi delivery timing.
+- A new `run-delivery.ts` domain owns the owner-scoped delivery journal, batch construction, bounds, phases, formatting, recovery, and acknowledgments.
+- `run-ui-runtime.ts` owns idle detection, debounce, reconciliation, flushing, and stale-context containment.
+- `extension-runtime.ts` orders completion flushes before automatic Recipe review.
+- `index.ts` remains a thin registration root and adds only the required Pi lifecycle adapter.
+- `pi.ts` exposes narrow ports for batched follow-up and urgent steer delivery.
+
+The local TypeScript dependency graph must remain acyclic. No public tool, target, view, Recipe field, or transport contract is added by default.
+
+## Durable Delivery State
+
+Store one journal per exact coordinator owner under an internal path derived from a safe owner hash:
+
+```text
+<extension-temp>/delivery/<owner-hash>/projection.json
+```
+
+The journal records the exact internal owner and contains at most one active completion batch plus a bounded set of unpresented urgent steer envelopes.
+
+Completion batch shape:
+
+```json
+{
+  "batch_id": "uuid",
+  "owner_id": "exact internal owner",
+  "phase": "pending",
+  "members": [
+    {
+      "run": "review-a",
+      "run_instance_id": "generation-id",
+      "status": "done",
+      "state_dir": "internal path"
+    }
+  ],
+  "created_at": "timestamp"
+}
+```
+
+Phases are monotonic:
+
+1. `pending`: The exact member snapshot is durable but no Pi message has been accepted.
+2. `queued`: Pi accepted a custom message carrying the exact batch or steer ID.
+3. `presented`: A Pi `context` event observed that ID in messages being supplied to an LLM call.
+
+Every journal mutation uses the canonical token-owned lock, expected-phase fencing, owner and generation validation, and atomic replacement. Repeated transitions are idempotent. Corrupt, oversized, foreign-owner, or stale-generation state fails closed with bounded diagnostics.
+
+A queued envelope is not treated as presented merely because `sendMessage()` returned. Only presentation marks completion members through their existing terminal-handled authority. If a member was synchronously archived or pruned after queueing, the bounded delivery snapshot remains sufficient and the missing state write becomes a diagnostic rather than invalidating the batch.
+
+## Completion Collection
+
+Reconciliation admits unhandled root terminal generations with status `done`, `failed`, `killed`, or `exited`.
+
+It excludes:
+
+- Runs with silent notification policy;
+- synchronous stop or cancel outcomes already acknowledged by their caller;
+- handled terminal generations;
+- internal composition branches;
+- every Command lifecycle event.
+
+Candidates sort by terminal timestamp, then stable Run identity, then `run_instance_id`. Replacement generations with the same logical Run id remain distinct internal members.
+
+While `ctx.isIdle()` is false, candidates remain durable in their Run state and no terminal follow-up is sent. A flush snapshots eligible candidates into one immutable batch. While that batch remains unpresented, newer terminals stay unhandled for the next bounded completion epoch.
+
+## Batch Flush
+
+Flush one batch when:
+
+1. `agent_settled` fires for the still-active context and `ctx.isIdle()` remains true;
+2. terminals arrive while Pi is already idle and survive one short debounce window;
+3. session restoration discovers unhandled terminal generations or recoverable queued delivery state.
+
+The model-facing custom message uses `customType: "pi-actors-run-batch"`, `deliverAs: "followUp"`, and `triggerTurn: true`. It includes:
+
+- batch ID and completion window;
+- counts by terminal status;
+- stable Run, status, compact semantic summary, and bounded artifact rows;
+- explicit overflow evidence and the canonical runtime Inspect route.
+
+The journal may retain at most 256 members and 1 MiB. Model-facing content lists at most 64 exact rows within the centralized model-output bound. Additional members remain represented by exact status counts and supported Inspect guidance. More than 256 unhandled generations form a later batch rather than being discarded.
+
+Completion member details remain redacted through existing terminal projection rules: no raw model policy, secrets, private Recipe paths, or machine-local source paths enter the message.
+
+## Presentation Acknowledgment And Recovery
+
+Register a `context` lifecycle adapter that scans model-bound messages for exact pi-actors batch and steer IDs. On a matching active-owner envelope it atomically:
+
+1. moves the envelope to `presented`;
+2. marks every still-present member generation terminal-handled;
+3. records a non-attention `delivery.steer_presented` marker in the exact Run generation for a presented steer;
+4. retains a bounded owner receipt sufficient for near-term deduplication and diagnostics.
+
+The generation-fenced Trace marker prevents a retained historical steer from replaying after bounded owner receipts rotate: suffix compaction cannot retain the older steer while discarding its newer presentation marker. Missing, archived, pruned, or replaced Run state needs no marker because it can no longer replay that original generation.
+
+Recovery rules:
+
+- Send failure: keep `pending`, record failure evidence, and retry.
+- Crash after queueing: inspect existing owned Pi session evidence for the exact custom message ID.
+- Queued message exists: do not resend; wait for `context` presentation.
+- Queued message is absent: return the envelope to `pending`.
+- Presented envelope: never resend.
+- Session or context replacement: close timers and callbacks; never deliver through stale context.
+- Owner mismatch: do not inspect, acknowledge, or deliver the envelope.
+
+Session evidence inspection must reuse the existing bounded owned-session readers rather than adding raw unbounded session parsing.
+
+## Explicit Urgent Steer
+
+Extend canonical Trace attention with `"steer"`:
+
+```json
+{
+  "kind": "checkpoint.blocked",
+  "summary": "Approval required before destructive migration",
+  "attention": "steer"
+}
+```
+
+A steer event is:
+
+- explicit and actor-authored;
+- admitted to the durable owner delivery journal before Pi delivery;
+- sent through `deliverAs: "steer"` with `triggerTurn: true`;
+- presented only when its exact event ID appears in model-bound `context`;
+- retried after delivery failure without duplicate presentation;
+- independent from the eventual root-terminal batch.
+
+Pi steering is a safe-boundary continuation, not token-level interruption: while streaming, Pi delivers it after the current assistant turn finishes its tool calls and before the next LLM call. If Pi is idle, it triggers a new turn immediately.
+
+Urgent steer capacity is bounded to 64 unpresented envelopes within the same 1 MiB owner journal. Capacity pressure remains visible and retryable; it never degrades into generic follow-up or drops an admitted envelope silently.
+
+## Settled Lifecycle Ordering
+
+`onAgentSettled` must use this order:
+
+```text
+active-context and exact-owner check
+-> completion flush
+-> if a batch was sent, defer automatic Recipe review
+-> batch-triggered model run settles
+-> schedule automatic review only when no batch remains
+```
+
+Another extension may start work during `agent_settled`; recheck `ctx.isIdle()` immediately before sending. A completion/settled race places each generation in either the current immutable batch or the next batch, never both.
+
+## Validation Contract
+
+Implementation is complete only when source and packed-extension tests prove:
+
+1. Multiple Runs finishing during one agent run cause no immediate terminal turns and one settled batch.
+2. Idle completions inside the debounce window form one batch.
+3. Completion/settled races project every generation exactly once.
+4. Send failure and restart before queueing retry without a handled marker.
+5. Restart after queueing but before presentation neither loses nor duplicates the batch.
+6. Exact `context` presentation acknowledges members atomically and idempotently.
+7. Replacement generations sharing a Run id remain distinct.
+8. Silent, stopped, cancelled, handled, and foreign-owner Runs remain excluded.
+9. Legacy or malformed `command.done` attention, including `steer`, remains non-projectable.
+10. Explicit steer reaches the next safe Pi boundary once and root terminal still batches later.
+11. Overflow, corruption, journal backpressure, archive/prune races, and stale contexts fail safely.
+12. Completion flushing precedes automatic Recipe review.
+13. Pi 0.84.4 remains the exact minimum source and packed lifecycle baseline.
+
+Focused observability and delivery tests precede TypeScript/build/import checks. The acceptance checkpoint then runs full product validation, dependency audit, package dry-run, and ABCd context validation.
+
+## Rollout
+
+This is one minor release because durable batching, presentation acknowledgment, lifecycle ordering, and explicit steer share one model-delivery invariant. Do not ship partial batching that marks terminals handled at `sendMessage()` acceptance, and do not ship steer before its durable deduplication path exists.
+
+Update README and Run documentation only when implementation establishes the new public behavior. Move the accepted outcome from BACKLOG to CHANGELOG only after complete validation.

package/docs/recipe-library.md

@@ -36,7 +36,7 @@ Artifact pipelines terminate in files/manifests and result evidence; they do not
 
 ### Music playback and controlled services
 
-- `music-player/playback` — singleton playback service that resolves files, directories, URLs, explicit lists, and playlist files into one persistent queue; it exposes declared playback Controls including arbitrary absolute `volume` percentages, generation-fenced endpoint readiness, structured status, a player-owned continuity checkpoint, and playback Trace. Player selection is `player:enum(auto,mpv,afplay,ffplay,cvlc,play,wmp)=auto`.
+- `music-player/playback` — singleton playback service that resolves files, directories, URLs, explicit lists, and playlist files into one persistent queue; it exposes declared playback Controls including arbitrary absolute `volume` percentages, generation-fenced endpoint readiness, structured status, a player-owned continuity checkpoint, and playback Trace. Player selection is `player:enum(auto,mpv,afplay,ffplay,cvlc,play,wmp)=auto`. The single `skills/music-player/scripts/playback.mjs` executable also supports standalone foreground `serve` and `control <state-dir> <action> [percent]`; control observes the existing owner, using canonical Control records for Actors and generation-fenced RPC for standalone playback. The maintained Generative App uses that same control entrypoint for Actor-owned playback.
 - `actors/resource-locker` — optional queue/lease-lock service with explicit owner/resource input, lock Trace, and a 512-record/1 MiB atomically retained journal.
 
 These Recipes declare actor-local Control. Ordinary one-shot Recipes omit it. Helper-backed Skill Recipes self-locate through runtime-owned `{skill_dir}`; callers do not pass package installation roots.