@llblab/pi-actors 0.52.1 → 0.53.1

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/index.ts

@@ -6,13 +6,16 @@
 
 import * as ExtensionRuntime from "./lib/extension-runtime.ts";
 import * as InspectorCommand from "./lib/inspector-command.ts";
+import * as Paths from "./lib/paths.ts";
 import * as Pi from "./lib/pi.ts";
 
 export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
   const runtime = ExtensionRuntime.createActorExtensionRuntime(pi);
-  pi.on("resources_discover", async () =>
-    runtime.discoverResources(import.meta.url),
-  );
+  if (Paths.isRawExtensionCheckout(import.meta.url)) {
+    pi.on("resources_discover", async () =>
+      runtime.discoverResources(import.meta.url),
+    );
+  }
   pi.on("session_start", async (_event, ctx) => runtime.onSessionStart(ctx));
   pi.on("agent_settled", async (_event, ctx) => runtime.onAgentSettled(ctx));
   pi.on("context", async (event, ctx) => ({

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) {

package/lib/observability.ts

@@ -43,6 +43,12 @@ export interface RunObservation {
   activeSubagents?: number;
   completed?: number;
   descendantSubagents?: number;
+  deliveryOwnerId?: string;
+  deliveryParent?: {
+    run: string;
+    run_instance_id: string;
+    state_dir: string;
+  };
   failures?: number;
   ownerId?: string;
   artifacts?: Record<string, string>;
@@ -136,6 +142,21 @@ export function readRunUiSnapshot(
   };
 }
 
+/** Observe every Run generation routed to one root coordinator. */
+export function readRunDeliverySnapshot(
+  state: RunUiObservationState,
+  deliveryOwnerId: string,
+  stateRoot?: string,
+): RunUiSnapshot {
+  const summary = summarizeRuns(stateRoot, undefined, deliveryOwnerId);
+  return {
+    attentionEvents: [],
+    status: undefined,
+    summary,
+    transitions: detectRunTransitions(state.observed, summary),
+  };
+}
+
 export function pruneRunUiObservationState(
   state: RunUiObservationState,
   snapshot: Pick<RunUiSnapshot, "summary" | "transitions">,
@@ -383,6 +404,11 @@ export interface RunRetirementExecutorOptions {
 }
 
 export interface RunTransition {
+  deliveryParent?: {
+    run: string;
+    run_instance_id: string;
+    state_dir: string;
+  };
   from: RunObservedStatus;
   run: string;
   runInstanceId?: string;
@@ -584,6 +610,23 @@ function observeRun(stateDir: string): RunObservation | undefined {
       failures: Array.isArray(progress.failures)
         ? progress.failures.length
         : undefined,
+      ...(typeof status.delivery_owner_id === "string"
+        ? { deliveryOwnerId: status.delivery_owner_id }
+        : {}),
+      ...(status.delivery_parent &&
+      typeof status.delivery_parent === "object" &&
+      !Array.isArray(status.delivery_parent) &&
+      typeof (status.delivery_parent as Record<string, unknown>).run === "string" &&
+      typeof (status.delivery_parent as Record<string, unknown>).run_instance_id === "string" &&
+      typeof (status.delivery_parent as Record<string, unknown>).state_dir === "string"
+        ? {
+            deliveryParent: status.delivery_parent as {
+              run: string;
+              run_instance_id: string;
+              state_dir: string;
+            },
+          }
+        : {}),
       ...(typeof status.ownerId === "string"
         ? { ownerId: status.ownerId }
         : {}),
@@ -630,6 +673,7 @@ function observeRun(stateDir: string): RunObservation | undefined {
 export function summarizeRuns(
   stateRoot = Paths.getRunStateRoot(),
   ownerId?: string,
+  deliveryOwnerId?: string,
 ): RunSummary {
   if (!existsSync(stateRoot)) {
     return {
@@ -650,7 +694,10 @@ export function summarizeRuns(
   )
     .map((stateDir) => observeRun(stateDir))
     .filter((run): run is RunObservation => Boolean(run))
-    .filter((run) => ownerId === undefined || run.ownerId === ownerId)
+    .filter((run) => deliveryOwnerId !== undefined
+      ? run.deliveryOwnerId === deliveryOwnerId ||
+        (run.deliveryOwnerId === undefined && run.ownerId === deliveryOwnerId)
+      : ownerId === undefined || run.ownerId === ownerId)
     .sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""));
   const processSubagentsByRun = countRunningSubagentsByRun(stateRoot, ownerId);
   const runsWithDescendants = runs.map((run) => {
@@ -1005,6 +1052,7 @@ export function detectRunTransitions(
       transitions.push({
         from: old ?? "running",
         run: run.run,
+        ...(run.deliveryParent ? { deliveryParent: run.deliveryParent } : {}),
         ...(run.stateDir ? { stateDir: run.stateDir } : {}),
         ...(run.artifacts ? { artifacts: run.artifacts } : {}),
         ...(run.launchCorrelation ? { launchCorrelation: run.launchCorrelation } : {}),
@@ -1282,11 +1330,57 @@ export function shouldNotifyRunTransition(transition: RunTransition): boolean {
   );
 }
 
-/** Build exact immutable generation members for owner-journal admission. */
+function deliveryGenerationIdentity(input: {
+  runInstanceId?: string;
+  stateDir?: string;
+}): string | undefined {
+  return input.stateDir && input.runInstanceId
+    ? `${input.stateDir}\0${input.runInstanceId}`
+    : undefined;
+}
+
+function deliveryTreePosition(
+  input: {
+    deliveryParent?: RunObservation["deliveryParent"];
+    runInstanceId?: string;
+    stateDir?: string;
+  },
+  runsByIdentity: Map<string, RunObservation>,
+): { depth: number; rootIdentity: string } | undefined {
+  const ownIdentity = deliveryGenerationIdentity(input);
+  if (!ownIdentity) return undefined;
+  let parent = input.deliveryParent;
+  let depth = 0;
+  let rootIdentity = ownIdentity;
+  const visited = new Set([ownIdentity]);
+  while (parent) {
+    const identity = `${parent.state_dir}\0${parent.run_instance_id}`;
+    if (visited.has(identity)) return undefined;
+    visited.add(identity);
+    const ancestor = runsByIdentity.get(identity);
+    if (!ancestor || ancestor.notificationPolicy === "silent") return undefined;
+    depth += 1;
+    rootIdentity = identity;
+    parent = ancestor.deliveryParent;
+  }
+  return { depth, rootIdentity };
+}
+
+/** Build exact immutable members only after each containing root Run is terminal. */
 export function collectRunCompletionBatchMembers(
   transitions: RunTransition[],
+  deliveryRuns: RunObservation[] = [],
 ): RunCompletionBatchMember[] {
-  return transitions.flatMap((transition) => {
+  const runsByIdentity = new Map(deliveryRuns.flatMap((run) => {
+    const identity = deliveryGenerationIdentity(run);
+    return identity ? [[identity, run] as const] : [];
+  }));
+  const incompleteRoots = new Set(deliveryRuns.flatMap((run) => {
+    if (TERMINAL.has(run.status)) return [];
+    const position = deliveryTreePosition(run, runsByIdentity);
+    return position ? [position.rootIdentity] : [];
+  }));
+  const admitted = transitions.flatMap((transition) => {
     if (
       !shouldNotifyRunTransition(transition) ||
       !transition.stateDir ||
@@ -1294,6 +1388,9 @@ export function collectRunCompletionBatchMembers(
       !transition.terminalAt ||
       Number.isNaN(Date.parse(transition.terminalAt))
     ) return [];
+    const position = deliveryTreePosition(transition, runsByIdentity);
+    if (!position || incompleteRoots.has(position.rootIdentity)) return [];
+    const { depth } = position;
     const artifactEntries = Object.entries(transition.artifacts ?? {})
       .filter((entry): entry is [string, string] =>
         typeof entry[1] === "string" && Boolean(entry[1]))
@@ -1304,6 +1401,20 @@ export function collectRunCompletionBatchMembers(
       ...(artifactEntries.length > 0
         ? { artifacts: Object.fromEntries(artifactEntries) }
         : {}),
+      ...(transition.semanticResult?.body?.trim()
+        ? {
+            output: transition.semanticResult.body.trim().length > 4_000
+              ? `${transition.semanticResult.body.trim().slice(0, 3_999)}…`
+              : transition.semanticResult.body.trim(),
+          }
+        : {}),
+      ...(transition.deliveryParent
+        ? {
+            parent_run: transition.deliveryParent.run,
+            parent_run_instance_id: transition.deliveryParent.run_instance_id,
+            parent_state_dir: transition.deliveryParent.state_dir,
+          }
+        : {}),
       run: transition.run,
       run_instance_id: transition.runInstanceId,
       state_dir: transition.stateDir,
@@ -1312,13 +1423,16 @@ export function collectRunCompletionBatchMembers(
         ? `${rawSummary.slice(0, 999)}…`
         : rawSummary,
       terminal_at: transition.terminalAt,
+      tree_depth: depth,
     }];
-  }).sort((left, right) =>
+  });
+  return admitted.sort((left, right) =>
+    left.tree_depth - right.tree_depth ||
     left.terminal_at.localeCompare(right.terminal_at) ||
     left.run.localeCompare(right.run) ||
     left.run_instance_id.localeCompare(right.run_instance_id) ||
     left.state_dir.localeCompare(right.state_dir)
-  );
+  ).map(({ tree_depth: _depth, ...member }) => member);
 }
 
 const TERMINAL_FOLLOW_UP_ARTIFACT_LIMIT = 4;

package/lib/paths.ts

@@ -93,8 +93,34 @@ export function getExtensionRuntimePaths(
 
 export const EXTENSION_RUNTIME_PATHS = getExtensionRuntimePaths();
 
+export function getExtensionPackageRoot(extensionUrl: string): string {
+  let current = dirname(fileURLToPath(extensionUrl));
+  while (true) {
+    if (existsSync(join(current, "package.json"))) return current;
+    const parent = dirname(current);
+    if (parent === current) return dirname(fileURLToPath(extensionUrl));
+    current = parent;
+  }
+}
+
+export interface RawExtensionCheckoutOptions {
+  agentDir?: string;
+  cwd?: string;
+}
+
+export function isRawExtensionCheckout(
+  extensionUrl: string,
+  options: RawExtensionCheckoutOptions = {},
+): boolean {
+  const packageRoot = resolve(getExtensionPackageRoot(extensionUrl));
+  const agentDir = resolve(options.agentDir ?? getAgentDir());
+  const cwd = resolve(options.cwd ?? process.cwd());
+  return dirname(packageRoot) === join(agentDir, "extensions") ||
+    dirname(packageRoot) === join(cwd, ".pi", "extensions");
+}
+
 export function getExtensionSkillsDir(extensionUrl: string): string {
-  return join(dirname(fileURLToPath(extensionUrl)), "skills");
+  return join(getExtensionPackageRoot(extensionUrl), "skills");
 }
 
 export function getExistingExtensionSkillPaths(extensionUrl: string): string[] {

package/lib/pi.ts

@@ -52,7 +52,7 @@ export function sendRunCompletionBatch(
   pi.sendMessage({
     customType: RUN_COMPLETION_BATCH_CUSTOM_TYPE,
     content,
-    display: false,
+    display: true,
     details: {
       pi_actors_delivery: {
         batch_id: batchId,
@@ -96,17 +96,20 @@ function completionBatchMessage(
     typeof record.content !== "string"
   ) return undefined;
   const details = record.details;
-  if (!details || typeof details !== "object" || Array.isArray(details)) return undefined;
-  const delivery = (details as Record<string, unknown>).pi_actors_delivery;
-  if (!delivery || typeof delivery !== "object" || Array.isArray(delivery)) return undefined;
-  const envelope = delivery as Record<string, unknown>;
-  if (
-    envelope.kind !== "completion_batch" ||
-    typeof envelope.batch_id !== "string" ||
-    !envelope.batch_id ||
-    envelope.batch_id.length > 128
-  ) return undefined;
-  return { batchId: envelope.batch_id, content: record.content };
+  const delivery = details && typeof details === "object" && !Array.isArray(details)
+    ? (details as Record<string, unknown>).pi_actors_delivery
+    : undefined;
+  const envelope = delivery && typeof delivery === "object" && !Array.isArray(delivery)
+    ? delivery as Record<string, unknown>
+    : undefined;
+  const detailedId = envelope?.kind === "completion_batch" &&
+    typeof envelope.batch_id === "string"
+    ? envelope.batch_id
+    : undefined;
+  const contentId = /^Batch: `([^`]{1,128})`$/mu.exec(record.content)?.[1];
+  const batchId = detailedId ?? contentId;
+  if (!batchId || batchId.length > 128) return undefined;
+  return { batchId, content: record.content };
 }
 
 /** Collapse exact retry duplicates and remove conflicting delivery envelopes. */
@@ -233,22 +236,6 @@ export function inspectRunSteerSessionEvidence(
   });
 }
 
-export function inspectRunCompletionBatchSessionEvidence(
-  ctx: ExtensionContext,
-  batchId: string,
-  content: string,
-): SessionEvidence.ActiveSessionEntryEvidence {
-  return SessionEvidence.inspectBoundedActiveSessionEntries({
-    getEntry: (id) => ctx.sessionManager.getEntry(id),
-    leaf: ctx.sessionManager.getLeafEntry(),
-    match: (entry) => {
-      const batch = completionBatchMessage(entry);
-      if (!batch || batch.batchId !== batchId) return undefined;
-      return batch.content === content ? "present" : "conflict";
-    },
-  });
-}
-
 export function registerToolDefinitions(
   pi: ExtensionAPI,
   definitions: Iterable<unknown>,

package/lib/run-delivery-lineage.ts

@@ -0,0 +1,68 @@
+/**
+ * Run delivery lineage.
+ * Zones: inherited coordinator root, parent Run generation, delivery-tree filtering
+ * Owns durable completion ancestry; excludes delivery persistence and Pi scheduling.
+ */
+
+export interface RunDeliveryParent {
+  run: string;
+  run_instance_id: string;
+  state_dir: string;
+}
+
+export interface RunDeliveryLineage {
+  delivery_owner_id: string;
+  delivery_parent?: RunDeliveryParent;
+}
+
+const DELIVERY_OWNER_ENV = "PI_ACTORS_DELIVERY_OWNER_ID";
+const PARENT_RUN_ENV = "PI_ACTORS_DELIVERY_PARENT_RUN";
+const PARENT_INSTANCE_ENV = "PI_ACTORS_DELIVERY_PARENT_INSTANCE";
+const PARENT_STATE_DIR_ENV = "PI_ACTORS_DELIVERY_PARENT_STATE_DIR";
+
+function nonEmpty(value: string | undefined): string | undefined {
+  const text = value?.trim();
+  return text || undefined;
+}
+
+export function inheritedRunDeliveryLineage(
+  ownerId: string | undefined,
+  env: NodeJS.ProcessEnv = process.env,
+): RunDeliveryLineage | undefined {
+  const localOwner = nonEmpty(ownerId);
+  if (!localOwner) return undefined;
+  const deliveryOwner = nonEmpty(env[DELIVERY_OWNER_ENV]) ?? localOwner;
+  const run = nonEmpty(env[PARENT_RUN_ENV]);
+  const runInstanceId = nonEmpty(env[PARENT_INSTANCE_ENV]);
+  const stateDir = nonEmpty(env[PARENT_STATE_DIR_ENV]);
+  const completeParent = run && runInstanceId && stateDir
+    ? { run, run_instance_id: runInstanceId, state_dir: stateDir }
+    : undefined;
+  if ((run || runInstanceId || stateDir) && !completeParent) {
+    throw new Error("Inherited Run delivery parent lineage is incomplete");
+  }
+  return {
+    delivery_owner_id: deliveryOwner,
+    ...(completeParent ? { delivery_parent: completeParent } : {}),
+  };
+}
+
+export function runDeliveryChildEnv(
+  lineage: RunDeliveryLineage,
+  parent: RunDeliveryParent,
+  env: NodeJS.ProcessEnv = process.env,
+): NodeJS.ProcessEnv {
+  return {
+    ...env,
+    [DELIVERY_OWNER_ENV]: lineage.delivery_owner_id,
+    [PARENT_RUN_ENV]: parent.run,
+    [PARENT_INSTANCE_ENV]: parent.run_instance_id,
+    [PARENT_STATE_DIR_ENV]: parent.state_dir,
+  };
+}
+
+export function getProcessDeliveryOwnerId(
+  env: NodeJS.ProcessEnv = process.env,
+): string | undefined {
+  return nonEmpty(env[DELIVERY_OWNER_ENV]);
+}