@llblab/pi-actors 0.52.1 → 0.53.1

package/dist/lib/run-delivery.js

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

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

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

package/dist/lib/runtime.js

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

package/dist/scripts/build-dist.mjs

@@ -1,47 +1,40 @@
 #!/usr/bin/env node
 
 /**
- * Build the JavaScript-only distributive tree.
- *
- * This is intentionally standalone: it is package/build glue, not reusable
- * actor-domain behavior. It cleans dist, compiles TypeScript, mirrors runtime
- * assets, and syntax-checks packaged scripts.
+ * Builds or verifies the JavaScript-only distributive tree without exposing a
+ * partial tree to Pi or destroying the previous distributive on failure.
  */
 
 import { spawnSync } from "node:child_process";
 import {
   cpSync,
+  existsSync,
   mkdirSync,
+  mkdtempSync,
+  readFileSync,
   readdirSync,
+  renameSync,
   rmSync,
   writeFileSync,
 } from "node:fs";
-import { join } from "node:path";
+import { join, relative } from "node:path";
+
+const DIST_DIR = "dist";
+const checkOnly = process.argv.includes("--check");
 
 function run(command, args) {
   const result = spawnSync(command, args, { stdio: "inherit" });
   if (result.error) throw result.error;
-  if (result.status !== 0) process.exit(result.status ?? 1);
+  if (result.status !== 0) {
+    throw new Error(`${command} exited with status ${result.status ?? "unknown"}.`);
+  }
 }
 
-rmSync("dist", { recursive: true, force: true });
-mkdirSync("dist", { recursive: true });
-
-run(process.execPath, [
-  join("node_modules", "typescript", "bin", "tsc"),
-  "-p",
-  "tsconfig.build.json",
-]);
-
-mkdirSync(join("dist", "pi-actors"), { recursive: true });
-writeFileSync(
-  join("dist", "pi-actors", "index.js"),
-  'export { default } from "../index.js";\n',
-  "utf8",
-);
-
-for (const dir of ["scripts", "fixtures", "skills"]) {
-  cpSync(dir, join("dist", dir), { recursive: true });
+function listFiles(root, current = root) {
+  return readdirSync(current, { withFileTypes: true }).flatMap((entry) => {
+    const path = join(current, entry.name);
+    return entry.isDirectory() ? listFiles(root, path) : [relative(root, path)];
+  }).sort();
 }
 
 function listModuleScripts(root) {
@@ -52,9 +45,80 @@ function listModuleScripts(root) {
   });
 }
 
-const builtScripts = [
-  ...listModuleScripts(join("dist", "scripts")),
-  ...listModuleScripts(join("dist", "skills")),
-];
+function normalizeTextFiles(root) {
+  const textSuffixes = [".js", ".ts", ".mjs", ".json", ".md"];
+  for (const path of listFiles(root)) {
+    if (!textSuffixes.some((suffix) => path.endsWith(suffix))) continue;
+    const absolutePath = join(root, path);
+    const source = readFileSync(absolutePath, "utf8");
+    const normalized = source.replace(/\r\n?/g, "\n");
+    if (normalized !== source) writeFileSync(absolutePath, normalized, "utf8");
+  }
+}
+
+function assertTreesEqual(expectedRoot, actualRoot) {
+  if (!existsSync(expectedRoot)) {
+    throw new Error(`${expectedRoot} is missing; run npm run build.`);
+  }
+  const expectedFiles = listFiles(expectedRoot);
+  const actualFiles = listFiles(actualRoot);
+  if (JSON.stringify(expectedFiles) !== JSON.stringify(actualFiles)) {
+    throw new Error("dist file inventory is stale; run npm run build.");
+  }
+  for (const path of expectedFiles) {
+    if (!readFileSync(join(expectedRoot, path)).equals(readFileSync(join(actualRoot, path)))) {
+      throw new Error(`dist/${path} is stale; run npm run build.`);
+    }
+  }
+}
+
+function replaceDist(candidate) {
+  const backup = `.dist-backup-${process.pid}-${Date.now()}`;
+  const hadDist = existsSync(DIST_DIR);
+  if (hadDist) renameSync(DIST_DIR, backup);
+  try {
+    renameSync(candidate, DIST_DIR);
+    if (hadDist) rmSync(backup, { recursive: true, force: true });
+  } catch (error) {
+    if (hadDist && existsSync(backup) && !existsSync(DIST_DIR)) {
+      renameSync(backup, DIST_DIR);
+    }
+    throw error;
+  }
+}
 
-run(process.execPath, ["--check", ...builtScripts]);
+const candidate = mkdtempSync(join(process.cwd(), ".dist-build-"));
+try {
+  run(process.execPath, [
+    join("node_modules", "typescript", "bin", "tsc"),
+    "-p",
+    "tsconfig.build.json",
+    "--outDir",
+    candidate,
+  ]);
+
+  mkdirSync(join(candidate, "pi-actors"), { recursive: true });
+  writeFileSync(
+    join(candidate, "pi-actors", "index.js"),
+    'export { default } from "../index.js";\n',
+    "utf8",
+  );
+  normalizeTextFiles(candidate);
+  for (const dir of ["scripts", "fixtures", "skills"]) {
+    cpSync(dir, join(candidate, dir), { recursive: true });
+  }
+  const builtScripts = [
+    ...listModuleScripts(join(candidate, "scripts")),
+    ...listModuleScripts(join(candidate, "skills")),
+  ];
+  run(process.execPath, ["--check", ...builtScripts]);
+
+  if (checkOnly) {
+    assertTreesEqual(DIST_DIR, candidate);
+    console.log("pi-actors: dist is current");
+  } else {
+    replaceDist(candidate);
+  }
+} finally {
+  rmSync(candidate, { recursive: true, force: true });
+}

package/dist/skills/actors/SKILL.md

@@ -107,7 +107,7 @@ Run = Recipe + Trace + Control
 ```
 
 1. Spawn with the exact logical Recipe identity and caller-owned values.
-2. Retain the returned `run:<id>` and normally wait for its settled completion batch instead of polling.
+2. Retain the returned `run:<id>` and normally wait for the root coordinator's settled completion batch instead of polling. Nested actor completions accumulate under their containing top-level Run and arrive in that one tree-compressed batch; descendant sessions do not need notification options.
 3. Inspect `view=trace` when retained observations or attention matter.
 4. Inspect `view=control` before diagnosing service readiness, stale work, or saturation.
 5. Send `message` only for an action declared and consumed by that controlled Recipe.

package/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.