@llblab/pi-actors 0.52.1 → 0.53.1

package/lib/run-delivery.ts

@@ -16,6 +16,10 @@ export type RunDeliveryPhase = "pending" | "queued" | "presented";
 
 export interface RunCompletionBatchMember {
   artifacts?: Record<string, string>;
+  parent_run?: string;
+  parent_run_instance_id?: string;
+  parent_state_dir?: string;
+  output?: string;
   run: string;
   run_instance_id: string;
   state_dir: string;
@@ -109,6 +113,10 @@ export interface RunSteerTransitionInput {
 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",
@@ -216,8 +224,40 @@ function parseMember(value: unknown): RunCompletionBatchMember {
   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,
@@ -740,7 +780,75 @@ function compactModelText(value: string, limit: number): string {
   return compact.length > limit ? `${compact.slice(0, limit - 1)}…` : compact;
 }
 
-function formatCompletionMember(member: RunCompletionBatchMember): string {
+function memberIdentity(member: RunCompletionBatchMember): string {
+  return `${member.state_dir}\0${member.run_instance_id}`;
+}
+
+function completionDepth(
+  member: RunCompletionBatchMember,
+  byIdentity: Map<string, RunCompletionBatchMember>,
+): number {
+  const visited = new Set<string>();
+  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: RunCompletionBatchMember[],
+): RunCompletionBatchMember[] {
+  const byIdentity = new Map(members.map((member) => [memberIdentity(member), member]));
+  const children = new Map<string, RunCompletionBatchMember[]>();
+  const roots: RunCompletionBatchMember[] = [];
+  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: RunCompletionBatchMember[] = [];
+  const visited = new Set<string>();
+  const visit = (member: RunCompletionBatchMember): void => {
+    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: string, indent: string): string {
+  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: RunCompletionBatchMember,
+  byIdentity: Map<string, RunCompletionBatchMember>,
+): string {
   const summary = compactModelText(member.summary, 200);
   const artifactEntries = Object.entries(member.artifacts ?? {}).slice(0, 4);
   const artifactText = artifactEntries.length === 0
@@ -748,7 +856,11 @@ function formatCompletionMember(member: RunCompletionBatchMember): string {
     : `; 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: RunCompletionBatchMember[]): string {
@@ -772,9 +884,13 @@ export function formatRunCompletionBatchMessage(batch: RunCompletionBatch): stri
     `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: string[] = [];
   for (const row of candidateRows) {
     const omitted = safe.members.length - rows.length - 1;

package/lib/run-ui-runtime.ts

@@ -10,6 +10,7 @@ import * as Observability from "./observability.ts";
 import * as Paths from "./paths.ts";
 import * as Pi from "./pi.ts";
 import * as RunDelivery from "./run-delivery.ts";
+import * as RunDeliveryLineage from "./run-delivery-lineage.ts";
 
 export interface RunUiRuntime {
   close(): void;
@@ -43,12 +44,11 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
   let animationInterval: NodeJS.Timeout | undefined;
   let deliveryTimeout: NodeJS.Timeout | undefined;
   let notifyTimeout: NodeJS.Timeout | undefined;
-  let recoverQueuedBatch = false;
   let recoverQueuedSteers = false;
   let running = false;
   let lastWatcherDiagnosticId = 0;
   const observation = Observability.createRunUiObservationState();
-  const deliveryRecoveryDiagnostics = new Set<string>();
+  const deliveryObservation = Observability.createRunUiObservationState();
   const retirementAttempts = new Set<string>();
   const steerDiagnostics = new Set<string>();
 
@@ -70,9 +70,7 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
     notifyTimeout = undefined;
     if (deliveryTimeout) clearTimeout(deliveryTimeout);
     deliveryTimeout = undefined;
-    recoverQueuedBatch = false;
     recoverQueuedSteers = false;
-    deliveryRecoveryDiagnostics.clear();
     steerDiagnostics.clear();
     if (animationInterval) clearInterval(animationInterval);
     animationInterval = undefined;
@@ -228,12 +226,14 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
   };
   const admitCompletionTransitions = (
     ownerId: string,
-    transitions: Observability.RunTransition[],
+    snapshot: Observability.RunUiSnapshot,
   ): boolean => {
     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({
       members,
@@ -244,6 +244,10 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
   };
   const isIdle = (ctx: Pi.ExtensionContext): boolean =>
     typeof ctx.isIdle !== "function" || ctx.isIdle();
+  const isDeliveryRoot = (ownerId: string): boolean => {
+    const inheritedOwner = RunDeliveryLineage.getProcessDeliveryOwnerId();
+    return inheritedOwner === undefined || inheritedOwner === ownerId;
+  };
   let flushCompletionBatch = (_ctx: Pi.ExtensionContext): boolean => false;
   const flushSteers = (ctx: Pi.ExtensionContext, ownerId: string): boolean => {
     const recovering = recoverQueuedSteers;
@@ -334,11 +338,25 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
     if (!notify) 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) =>
@@ -403,54 +421,48 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
   });
 
   flushCompletionBatch = (ctx: Pi.ExtensionContext): boolean => {
-    if (!running || activeContext !== ctx || deps.getActiveContext() !== ctx) return false;
     const ownerId = activeOwnerId;
-    if (!ownerId) return false;
+    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;
     }
     if (!isIdle(ctx)) 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;
     try {
@@ -471,7 +483,19 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
     })) {
       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;
   };
 
@@ -479,11 +503,13 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
     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;
+      } catch {
         return messages;
       }
-      const ownerId = activeOwnerId;
-      if (!ownerId) return messages;
       const steerContext = Pi.dedupeRunSteerContext(messages);
       let contextMessages = steerContext.messages;
       for (const steer of journal(ownerId).steers) {
@@ -560,7 +586,6 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
       close();
       activeContext = ctx;
       activeOwnerId = ownerId;
-      recoverQueuedBatch = true;
       recoverQueuedSteers = true;
       running = true;
       try {

package/lib/runtime.ts

@@ -325,6 +325,7 @@ export function createRecipeToolReloadWatcher(
   let rootWatcher: FSWatcher | undefined;
   let parentWatcher: FSWatcher | undefined;
   let failureNotified = false;
+  let notifyAfterReload = false;
   const setWatchStatus = (watchStatus: RecipeRegistryStatus["watch_status"]): void =>
     runtime.setWatchStatus?.(watchStatus);
   const close = (): void => {
@@ -336,6 +337,7 @@ export function createRecipeToolReloadWatcher(
     closingParent?.close();
     if (reloadTimeout) clearTimeout(reloadTimeout);
     reloadTimeout = undefined;
+    notifyAfterReload = false;
     setWatchStatus("closed");
   };
   const reportCallbackError = (error: unknown): void => {
@@ -358,14 +360,21 @@ export function createRecipeToolReloadWatcher(
       reportCallbackError(error);
     }
   };
-  const scheduleReload = (ctx: RuntimeContext): void => {
+  const scheduleReload = (
+    ctx: RuntimeContext,
+    notifyActiveChange = false,
+  ): void => {
     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);
         reportCallbackError(error);
@@ -394,7 +403,7 @@ export function createRecipeToolReloadWatcher(
         parentWatcher = undefined;
         watcher.close();
         watchRoot(ctx, recipeRoot);
-        scheduleReload(ctx);
+        scheduleReload(ctx, true);
       });
       parentWatcher = watcher;
       setWatchStatus("watching_parent");
@@ -415,16 +424,18 @@ export function createRecipeToolReloadWatcher(
       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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.52.1",
+  "version": "0.53.1",
   "private": false,
   "description": "Local Actor Kernel for Pi",
   "keywords": [
@@ -31,9 +31,10 @@
     "test:preservation": "node --experimental-strip-types --test --test-concurrency=1 tests/async-runs.test.ts tests/observability.test.ts tests/session-evidence.test.ts tests/inspector-security.test.ts tests/inspector-overlay.test.ts tests/review-control.test.ts",
     "pack:dry": "npm pack --dry-run",
     "recipes:qa": "node skills/actors/scripts/validate-recipe.mjs skills --skills --qa --summary",
-    "validate": "npx tsc --noEmit && npm run recipes:qa && npm run build && npm run check && npm test && npm run conformance && npm run pack:dry",
+    "validate": "npx tsc --noEmit && npm run recipes:qa && npm run build:check && npm run check && npm test && npm run conformance && npm run pack:dry",
     "audit:dependencies": "npm audit --audit-level=high --omit=peer",
     "build": "node scripts/build-dist.mjs",
+    "build:check": "node scripts/build-dist.mjs --check",
     "prepack": "npm run build"
   },
   "files": [
@@ -54,15 +55,9 @@
     "extensions": [
       "./dist/pi-actors/index.js"
     ],
-    "sourceExtensions": [
-      "./index.ts"
-    ],
     "skills": [
       "./dist/skills"
     ],
-    "sourceSkills": [
-      "./skills"
-    ],
     "image": "https://raw.githubusercontent.com/llblab/pi-actors/main/banner.jpg"
   },
   "peerDependencies": {

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