@llblab/pi-kit 0.6.0 → 0.7.0

package/node_modules/@llblab/pi-actors/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/node_modules/@llblab/pi-actors/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/node_modules/@llblab/pi-actors/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/node_modules/@llblab/pi-actors/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/node_modules/@llblab/pi-actors/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/node_modules/@llblab/pi-actors/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/node_modules/@llblab/pi-actors/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);