@llblab/pi-actors 0.52.0 → 0.53.0

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 the settled completion batch by default; use meaningful attention or evidence-based timers for overdue work rather than a tight inspection loop.
+The coordinator owns decomposition, shared contracts, integration order, and final validation. Participants own bounded tasks or evidence lenses. Keep the coordinator available for decisions instead of duplicating participant implementation; use `actors` for launch, observation, and lifecycle mechanics.
 
 ## Reasoning allocation
 

package/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/async-runs.md

@@ -110,7 +110,7 @@ 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.
 
-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.
+Ordinary finite Runs project terminal results through one root-coordinator completion scheduler. Every detached runner passes its delivery-root owner and exact parent Run generation to nested actor processes. A descendant terminal remains authoritative but ineligible until its containing top-level Run is terminal; descendant Pi sessions never schedule completion follow-ups. After `agent_settled`, session recovery, or an idle debounce, the root scheduler snapshots the ready trees plus concurrently completed top-level Runs into one owner-fenced immutable batch of at most 256 exact generations. One batch causes one automatic agent turn, renders one visible gray operator card, exposes at most 64 bounded parent-child rows with semantic outputs to the model, and marks member terminals handled after Pi durably accepts the exact batch. Pending send failures retain bounded retry evidence. The narrow crash boundary between acceptance and finalization remains recoverable from bounded active-session evidence, but normal hot delivery never waits on a later context callback and therefore cannot block subsequent epochs. Duplicate exact context envelopes collapse before presentation.
 
 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.
 

package/docs/coordinator-delivery.md

@@ -1,17 +1,17 @@
 # Coordinator Delivery Scheduler
 
-Status: Accepted next-minor design. Implementation is in progress; public delivery behavior remains unchanged until the complete acceptance boundary passes.
+Status: Implemented coordinator-delivery contract.
 
 ## 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
+one Run generation -> one terminal record with inherited tree lineage
+one ready completion forest per bounded epoch -> one root-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.
+Ordinary terminals accumulate across nested actor sessions while Pi is active. Descendants wait for their containing top-level Run, then all ready trees and concurrently completed top-level Runs reach only the root coordinator in one bounded batch after Pi settles. Only an explicitly actor-authored urgent semantic checkpoint may steer an active agent loop.
 
 ## Non-Goals
 
@@ -27,7 +27,7 @@ Ordinary root terminals accumulate while Pi is active and reach the coordinator
 - `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.
+- Terminal transitions inherit exact parent-generation and root-owner lineage; only the root session batches ready completion trees instead of sending one follow-up per Run or descendant session.
 
 `command.done` remains non-projectable even if malformed or legacy Trace attaches any attention value.
 
@@ -81,11 +81,11 @@ Phases are monotonic:
 
 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 and steer acknowledgments intentionally differ. Successful `sendMessage()` acceptance finalizes an ordinary completion batch immediately and marks its members through the existing terminal-handled authority; this prevents a missed context callback from blocking every later epoch. Urgent steer still requires exact model-context presentation. If a completion 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 acceptance.
 
 ## Completion Collection
 
-Reconciliation admits unhandled root terminal generations with status `done`, `failed`, `killed`, or `exited`.
+Reconciliation admits unhandled terminal generations with status `done`, `failed`, `killed`, or `exited` that belong to the active root delivery owner. A descendant becomes eligible only when its exact parent chain reaches a terminal top-level Run.
 
 It excludes:
 
@@ -97,7 +97,7 @@ It excludes:
 
 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.
+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 transport acceptance is pending, newer terminals stay unhandled for the next bounded completion epoch.
 
 ## Batch Flush
 
@@ -107,25 +107,20 @@ Flush one batch when:
 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:
+The custom message uses `customType: "pi-actors-run-batch"`, `display: true`, `deliverAs: "followUp"`, and `triggerTurn: true`. It restores the visible gray completion card for the operator while supplying the same single tree-compressed prompt to the model. The bounded content retains the exact batch identity for session evidence and deduplication even though Pi omits private message details from model context. It includes:
 
 - batch ID and completion window;
 - counts by terminal status;
-- stable Run, status, compact semantic summary, and bounded artifact rows;
+- stable parent-child Run rows with status, compact semantic output, and bounded artifacts;
 - 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
+## Acceptance, Presentation, 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.
+Ordinary completion delivery atomically advances through queued acceptance to finalization immediately after `sendMessage()` returns, marks every still-present member generation terminal-handled, and retains a bounded owner receipt. A `context` lifecycle adapter remains for exact urgent-steer presentation and harmless completion deduplication; presented steer writes `delivery.steer_presented` in the exact Run generation.
 
 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.
 
@@ -133,9 +128,9 @@ 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.
+- Completion send accepted: finalize immediately and release the next epoch.
+- Crash leaves a queued completion: queued itself proves `sendMessage()` acceptance, so finalize without resend or content reformatting.
+- Presented urgent steer: 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.
 
@@ -188,8 +183,8 @@ Implementation is complete only when source and packed-extension tests prove:
 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.
+5. Restart in the narrow queue-acceptance/finalization boundary neither loses nor duplicates the batch.
+6. Successful completion acceptance acknowledges members atomically and idempotently; urgent steer still requires exact `context` presentation.
 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.
@@ -202,6 +197,6 @@ Focused observability and delivery tests precede TypeScript/build/import checks.
 
 ## 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.
+This is one minor release because durable batching, acceptance acknowledgment, lifecycle ordering, and explicit steer share one model-delivery invariant. Completion acceptance must release later epochs without depending on a context callback; steer must not ship before its durable presentation-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.

package/lib/async-runs.ts

@@ -32,6 +32,7 @@ import {
   type CurrentPolicyProvenance,
 } from "./model-context.ts";
 import * as Paths from "./paths.ts";
+import * as RunDeliveryLineage from "./run-delivery-lineage.ts";
 import * as RecipesReferences from "./recipes-references.ts";
 import * as RecipesUsage from "./recipes-usage.ts";
 import * as Schema from "./schema.ts";
@@ -186,6 +187,8 @@ export interface AsyncRunMeta {
   artifacts?: Record<string, RunArtifactDeclaration>;
   control?: string[];
   control_endpoint?: AsyncRunControlEndpoint;
+  delivery_owner_id?: string;
+  delivery_parent?: RunDeliveryLineage.RunDeliveryParent;
   model_policy?: CurrentPolicyProvenance;
   notification_policy?: "normal" | "silent";
   process_identity?: RunProcessIdentity;
@@ -666,6 +669,10 @@ export function startRun(
       startParams.transport_context,
     );
     const artifacts = resolveArtifactPaths(startParams.artifacts, outputValues);
+    const runInstanceId = randomUUID();
+    const deliveryLineage = RunDeliveryLineage.inheritedRunDeliveryLineage(
+      startParams.ownerId,
+    );
     const meta: AsyncRunMeta = {
       argv: [process.execPath, ...argv],
       createdAt: new Date().toISOString(),
@@ -683,7 +690,7 @@ export function startRun(
       ...(recipe ? { recipe } : {}),
       ...(recipeFile ? { recipe_file: recipeFile } : {}),
       run,
-      run_instance_id: randomUUID(),
+      run_instance_id: runInstanceId,
       state_dir: stateDir,
       state_schema: RuntimeIdentity.RUN_STATE_SCHEMA,
       status: "running",
@@ -696,6 +703,7 @@ export function startRun(
       ...(startParams.control_endpoint
         ? { control_endpoint: startParams.control_endpoint }
         : {}),
+      ...(deliveryLineage ?? {}),
       ...(startParams.notification_policy === "silent"
         ? { notification_policy: "silent" as const }
         : {}),
@@ -726,6 +734,15 @@ export function startRun(
     const child = spawn(process.execPath, argv, {
       cwd,
       detached: true,
+      ...(deliveryLineage
+        ? {
+            env: RunDeliveryLineage.runDeliveryChildEnv(deliveryLineage, {
+              run,
+              run_instance_id: runInstanceId,
+              state_dir: stateDir,
+            }),
+          }
+        : {}),
       stdio: ["ignore", outFd, errFd],
     });
     closeSync(outFd);

package/lib/command-templates.ts

@@ -4,7 +4,7 @@
  * Owns portable command-template parsing, expansion, risk checks, retries, timeouts, and direct execution.
  */
 
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { accessSync, appendFileSync, constants, mkdirSync, mkdtempSync, statSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { basename, delimiter, extname, isAbsolute, join, resolve as resolvePath } from "node:path";
@@ -1010,12 +1010,50 @@ function execCommandTemplateOnce(
     let settled = false;
     let timeoutId: NodeJS.Timeout | undefined;
     let killTimeoutId: NodeJS.Timeout | undefined;
+    const signalProcessTree = (signal: NodeJS.Signals): void => {
+      if (proc.pid === undefined) return;
+      if (process.platform === "win32") {
+        spawnSync("taskkill", [
+          "/PID",
+          String(proc.pid),
+          "/T",
+          ...(signal === "SIGKILL" ? ["/F"] : []),
+        ]);
+        return;
+      }
+      const snapshot = spawnSync("ps", ["-eo", "pid=,ppid="], { encoding: "utf8" });
+      const children = new Map<number, number[]>();
+      for (const line of snapshot.stdout?.split(/\r?\n/u) ?? []) {
+        const [pidText, parentText] = line.trim().split(/\s+/u);
+        const pid = Number(pidText);
+        const parent = Number(parentText);
+        if (!Number.isSafeInteger(pid) || !Number.isSafeInteger(parent)) continue;
+        const siblings = children.get(parent) ?? [];
+        siblings.push(pid);
+        children.set(parent, siblings);
+      }
+      const descendants: number[] = [];
+      const collect = (parent: number): void => {
+        for (const child of children.get(parent) ?? []) {
+          collect(child);
+          descendants.push(child);
+        }
+      };
+      collect(proc.pid);
+      for (const pid of [...descendants, proc.pid]) {
+        try {
+          process.kill(pid, signal);
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error;
+        }
+      }
+    };
     const killProcess = (): void => {
       if (killed) return;
       killed = true;
-      proc.kill("SIGTERM");
+      signalProcessTree("SIGTERM");
       killTimeoutId = setTimeout(() => {
-        if (!settled) proc.kill("SIGKILL");
+        if (!settled) signalProcessTree("SIGKILL");
       }, options.killGrace ?? 5000);
     };
     const settle = (code: number): void => {

package/lib/extension-runtime.ts

@@ -143,7 +143,7 @@ export function createActorExtensionRuntime(
     },
     getRunOwnerId,
     onAgentSettled(ctx) {
-      if (activeRunContext !== ctx) return;
+      if (!activeRunOwnerId || getRunOwnerId(ctx) !== activeRunOwnerId) return;
       if (!runUiRuntime.flushCompletionBatch(ctx)) automaticReview.schedule();
     },
     onContext(messages, ctx) {