@llblab/pi-actors 0.17.1 → 0.19.0

package/lib/actor-rooms.ts

@@ -5,16 +5,21 @@
  */
 
 import * as fs from "node:fs";
+import { randomUUID } from "node:crypto";
 import * as path from "node:path";
 
 import type { ActorMessage } from "./actor-messages.ts";
 
+const ROOM_LOCK_MAX_AGE_MS = 5 * 60 * 1000;
+const ROOM_LOCK_TIMEOUT_MS = 5000;
+const DEFAULT_ROOM_MAX_MESSAGES = 10000;
+const DEFAULT_SNAPSHOT_MIN_INTERVAL_MS = 250;
+
 export interface RoomMember {
   address: string;
   caps?: unknown;
   claim?: unknown;
   display?: unknown;
-  glyph?: unknown;
   joined_at: string;
   last_seen: string;
   parent?: unknown;
@@ -94,6 +99,10 @@ function branchSnapshotFile(stateDir: string, branch: string): string {
   return path.join(stateDir, "branches", branch, "communication.json");
 }
 
+function branchInboxFile(stateDir: string, branch: string): string {
+  return path.join(stateDir, "branches", branch, "inbox.jsonl");
+}
+
 function branchIdFromAddress(address: string | undefined, run: string): string | undefined {
   if (!address) return undefined;
   const match = new RegExp(`^branch:${run}/(.+)$`).exec(address);
@@ -104,6 +113,43 @@ function ensureRoomDir(stateDir: string, room: string): void {
   fs.mkdirSync(roomDir(stateDir, room), { recursive: true });
 }
 
+function sleepSync(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function acquireRoomLock(stateDir: string, room: string): () => void {
+  ensureRoomDir(stateDir, room);
+  const lockDir = path.join(roomDir(stateDir, room), ".append.lock");
+  const started = Date.now();
+  while (true) {
+    try {
+      fs.mkdirSync(lockDir);
+      fs.writeFileSync(
+        path.join(lockDir, "owner.json"),
+        `${JSON.stringify({ pid: process.pid, created_at: new Date().toISOString() })}\n`,
+      );
+      return () => fs.rmSync(lockDir, { recursive: true, force: true });
+    } catch (error) {
+      try {
+        const stat = fs.statSync(lockDir);
+        if (Date.now() - stat.mtimeMs > ROOM_LOCK_MAX_AGE_MS) {
+          fs.rmSync(lockDir, { recursive: true, force: true });
+          continue;
+        }
+      } catch {
+        continue;
+      }
+      if (Date.now() - started > ROOM_LOCK_TIMEOUT_MS) {
+        throw new Error(
+          `Room append lock timed out for ${room} in ${stateDir}.`,
+          { cause: error },
+        );
+      }
+      sleepSync(10);
+    }
+  }
+}
+
 function asRecord(value: unknown): Record<string, unknown> {
   return value && typeof value === "object" && !Array.isArray(value)
     ? (value as Record<string, unknown>)
@@ -129,6 +175,65 @@ function writeJsonFile(file: string, value: unknown): void {
   fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
 }
 
+function positiveEnvInt(name: string, fallback: number): number {
+  const value = Number(process.env[name] ?? fallback);
+  return Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
+}
+
+function roomMaxMessages(): number {
+  return positiveEnvInt("PI_ACTORS_ROOM_MAX_MESSAGES", DEFAULT_ROOM_MAX_MESSAGES);
+}
+
+function snapshotMinIntervalMs(): number {
+  return positiveEnvInt(
+    "PI_ACTORS_COMMUNICATION_SNAPSHOT_MIN_MS",
+    DEFAULT_SNAPSHOT_MIN_INTERVAL_MS,
+  );
+}
+
+function compactRoomMessages(stateDir: string, room: string): void {
+  const maxMessages = roomMaxMessages();
+  const file = messagesFile(stateDir, room);
+  const lines = readJsonlTailLines(file, maxMessages + 1);
+  if (lines.length <= maxMessages) return;
+  const kept = lines.slice(-maxMessages);
+  fs.writeFileSync(file, `${kept.join("\n")}\n`);
+  writeJsonFile(path.join(roomDir(stateDir, room), "compaction.json"), {
+    compacted_at: new Date().toISOString(),
+    max_messages: maxMessages,
+  });
+}
+
+function readJsonlTailLines(file: string, limit: number): string[] {
+  const lineLimit = Math.max(1, limit);
+  const stat = fs.statSync(file);
+  if (stat.size === 0) return [];
+  const fd = fs.openSync(file, "r");
+  try {
+    const chunkSize = 64 * 1024;
+    const chunks: Buffer[] = [];
+    let position = stat.size;
+    let newlines = 0;
+    while (position > 0 && newlines <= lineLimit) {
+      const size = Math.min(chunkSize, position);
+      position -= size;
+      const chunk = Buffer.allocUnsafe(size);
+      fs.readSync(fd, chunk, 0, size, position);
+      chunks.unshift(chunk);
+      for (let index = size - 1; index >= 0; index -= 1) {
+        if (chunk[index] === 10) newlines += 1;
+      }
+    }
+    return Buffer.concat(chunks)
+      .toString("utf8")
+      .split("\n")
+      .filter(Boolean)
+      .slice(-lineLimit);
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
 export function readRoomRoster(
   stateDir: string,
   room: string,
@@ -145,6 +250,15 @@ function writeRoomRoster(
   writeJsonFile(rosterFile(stateDir, room), roster);
 }
 
+function shouldDebounceSnapshot(file: string): boolean {
+  try {
+    return Date.now() - fs.statSync(file).mtimeMs < snapshotMinIntervalMs();
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+}
+
 function updateRosterForMessage(
   stateDir: string,
   room: string,
@@ -153,13 +267,23 @@ function updateRosterForMessage(
 ): Record<string, RoomMember> {
   const roster = readRoomRoster(stateDir, room);
   if (!message.from) return roster;
+  const body = asRecord(message.body);
+  const current = roster[message.from];
   if (message.type === "actor.leave") {
-    delete roster[message.from];
+    roster[message.from] = {
+      address: message.from,
+      joined_at: current?.joined_at ?? receivedAt,
+      last_seen: receivedAt,
+      ...(current?.caps !== undefined ? { caps: current.caps } : {}),
+      ...(current?.claim !== undefined ? { claim: current.claim } : {}),
+      ...(current?.display !== undefined ? { display: current.display } : {}),
+      ...(current?.parent !== undefined ? { parent: current.parent } : {}),
+      ...(current?.role !== undefined ? { role: current.role } : { role: "actor" }),
+      status: String(body.status ?? "left"),
+    };
     writeRoomRoster(stateDir, room, roster);
     return roster;
   }
-  const body = asRecord(message.body);
-  const current = roster[message.from];
   roster[message.from] = {
     address: message.from,
     joined_at: current?.joined_at ?? receivedAt,
@@ -167,7 +291,6 @@ function updateRosterForMessage(
     ...(body.caps !== undefined ? { caps: body.caps } : current?.caps !== undefined ? { caps: current.caps } : {}),
     ...(body.claim !== undefined ? { claim: body.claim } : current?.claim !== undefined ? { claim: current.claim } : {}),
     ...(body.display !== undefined ? { display: body.display } : current?.display !== undefined ? { display: current.display } : {}),
-    ...(body.glyph !== undefined ? { glyph: body.glyph } : current?.glyph !== undefined ? { glyph: current.glyph } : {}),
     ...(body.parent !== undefined ? { parent: body.parent } : current?.parent !== undefined ? { parent: current.parent } : {}),
     ...(body.role !== undefined ? { role: body.role } : current?.role !== undefined ? { role: current.role } : { role: "actor" }),
     status: String(body.status ?? current?.status ?? "present"),
@@ -176,29 +299,92 @@ function updateRosterForMessage(
   return roster;
 }
 
+export function readBranchInboxMessages(
+  stateDir: string,
+  run: string,
+  address: string,
+  limit = 40,
+): Array<ActorMessage & { id?: string; queued_at?: string; status?: string }> {
+  const branch = branchIdFromAddress(address, run);
+  if (!branch) throw new Error(`Expected branch:${run}/<branch>; got ${address}`);
+  try {
+    return readJsonlTailLines(branchInboxFile(stateDir, branch), limit).map(
+      (line) => JSON.parse(line),
+    );
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw error;
+  }
+}
+
+export function appendBranchInboxMessage(
+  stateDir: string,
+  run: string,
+  address: string,
+  message: ActorMessage,
+): void {
+  const branch = branchIdFromAddress(address, run);
+  if (!branch) throw new Error(`Expected branch:${run}/<branch>; got ${address}`);
+  fs.mkdirSync(path.dirname(branchInboxFile(stateDir, branch)), { recursive: true });
+  fs.writeFileSync(
+    branchInboxFile(stateDir, branch),
+    `${JSON.stringify({ ...message, id: randomUUID(), queued_at: new Date().toISOString(), status: "queued" })}\n`,
+    { flag: "a" },
+  );
+}
+
+export function updateBranchInboxMessageStatus(
+  stateDir: string,
+  run: string,
+  address: string,
+  id: string,
+  status: "claimed" | "handled" | "failed",
+  metadata: Record<string, unknown> = {},
+): boolean {
+  const branch = branchIdFromAddress(address, run);
+  if (!branch) throw new Error(`Expected branch:${run}/<branch>; got ${address}`);
+  const file = branchInboxFile(stateDir, branch);
+  const messages = readBranchInboxMessages(stateDir, run, address, Number.MAX_SAFE_INTEGER);
+  let changed = false;
+  const timestampKey = `${status}_at`;
+  const updated = messages.map((message) => {
+    if (message.id !== id) return message;
+    changed = true;
+    return { ...message, ...metadata, [timestampKey]: new Date().toISOString(), status };
+  });
+  if (!changed) return false;
+  fs.writeFileSync(file, `${updated.map((message) => JSON.stringify(message)).join("\n")}\n`);
+  return true;
+}
+
 export function appendRoomMessage(
   stateDir: string,
   room: string,
   message: ActorMessage,
 ): RoomAppendResult {
-  ensureRoomDir(stateDir, room);
-  const receivedAt = new Date().toISOString();
-  const entry: RoomTimelineEntry = { ...message, received_at: receivedAt };
-  fs.appendFileSync(messagesFile(stateDir, room), `${JSON.stringify(entry)}\n`);
-  const roster = updateRosterForMessage(stateDir, room, message, receivedAt);
-  const run = runFromRoomAddress(message.to);
-  if (run) {
-    writeCommunicationSnapshot(stateDir, run);
-    if (message.from && branchIdFromAddress(message.from, run)) {
-      writeBranchCommunicationSnapshot(stateDir, run, message.from);
+  const releaseLock = acquireRoomLock(stateDir, room);
+  try {
+    const receivedAt = new Date().toISOString();
+    const entry: RoomTimelineEntry = { ...message, received_at: receivedAt };
+    fs.appendFileSync(messagesFile(stateDir, room), `${JSON.stringify(entry)}\n`);
+    compactRoomMessages(stateDir, room);
+    const roster = updateRosterForMessage(stateDir, room, message, receivedAt);
+    const run = runFromRoomAddress(message.to);
+    if (run) {
+      writeCommunicationSnapshot(stateDir, run);
+      if (message.from && branchIdFromAddress(message.from, run)) {
+        writeBranchCommunicationSnapshotDebounced(stateDir, run, message.from);
+      }
     }
+    return {
+      message_count: readRoomMessages(stateDir, room).length,
+      room,
+      roster_count: Object.keys(roster).length,
+      sent: true,
+    };
+  } finally {
+    releaseLock();
   }
-  return {
-    message_count: readRoomMessages(stateDir, room).length,
-    room,
-    roster_count: Object.keys(roster).length,
-    sent: true,
-  };
 }
 
 export function readRoomMessages(
@@ -207,11 +393,8 @@ export function readRoomMessages(
   limit = 40,
 ): RoomTimelineEntry[] {
   try {
-    const lines = fs
-      .readFileSync(messagesFile(stateDir, room), "utf8")
-      .split("\n")
-      .filter(Boolean);
-    return lines.slice(-Math.max(1, limit)).map((line) => JSON.parse(line));
+    const lines = readJsonlTailLines(messagesFile(stateDir, room), limit);
+    return lines.map((line) => JSON.parse(line));
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
     throw error;
@@ -371,3 +554,14 @@ export function writeBranchCommunicationSnapshot(
   writeJsonFile(branchSnapshotFile(stateDir, branch), snapshot);
   return snapshot;
 }
+
+function writeBranchCommunicationSnapshotDebounced(
+  stateDir: string,
+  run: string,
+  self: string,
+): ActorCommunicationSnapshot | undefined {
+  const branch = branchIdFromAddress(self, run);
+  if (!branch) throw new Error(`Expected branch:${run}/<branch>; got ${self}`);
+  if (shouldDebounceSnapshot(branchSnapshotFile(stateDir, branch))) return undefined;
+  return writeBranchCommunicationSnapshot(stateDir, run, self);
+}

package/lib/async-runs.ts

@@ -32,6 +32,8 @@ import * as Paths from "./paths.ts";
 import * as RecipeReferences from "./recipe-references.ts";
 import * as RecipeUsage from "./recipe-usage.ts";
 
+const START_LOCK_MAX_AGE_MS = 5 * 60 * 1000;
+
 export interface AsyncRunStartParams {
   async?: boolean;
   file?: string;
@@ -51,6 +53,7 @@ export interface AsyncRunStartParams {
   output?: string;
   artifacts?: Record<string, string>;
   mailbox?: RecipeReferences.TemplateRecipeMailbox;
+  retire_when?: "children_terminal";
   retry?: number | string;
   failure?: CommandTemplateFailureScope;
   recover?: CommandTemplateValue;
@@ -104,6 +107,7 @@ export interface AsyncRunMeta {
   values: Record<string, unknown>;
   artifacts?: Record<string, string>;
   mailbox?: RecipeReferences.TemplateRecipeMailbox;
+  retire_when?: "children_terminal";
 }
 
 const DEFAULT_STATE_ROOT = Paths.getRunStateRoot();
@@ -169,6 +173,17 @@ function resolveStateDir(params: AsyncRunStartParams, run: string): string {
   return resolve(params.state_dir || join(DEFAULT_STATE_ROOT, run));
 }
 
+function assertNoActiveRunState(stateDir: string): void {
+  const meta = readJson(join(stateDir, "run.json"));
+  if (!meta) return;
+  const pid = Number(meta.pid || 0);
+  const cwd = String(meta.cwd ?? "");
+  if (!pid || !isAlive(pid) || !pidMatchesRun(pid, cwd, stateDir)) return;
+  throw new Error(
+    `Run state already has an active owned process: ${String(meta.run ?? stateDir)}. Stop it before reusing the same run_id or state_dir.`,
+  );
+}
+
 function resolveRecipeFile(file: string): string {
   return RecipeReferences.resolveRecipePath(file, DEFAULT_RECIPE_ROOT);
 }
@@ -277,6 +292,39 @@ function getInterruptedRunStatus(
   return undefined;
 }
 
+function acquireStateStartLock(stateDir: string): () => void {
+  const lockDir = join(stateDir, ".start.lock");
+  try {
+    mkdirSync(lockDir);
+    writeFileSync(
+      join(lockDir, "owner.json"),
+      `${JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() })}\n`,
+      "utf8",
+    );
+  } catch (error) {
+    try {
+      const stat = statSync(lockDir);
+      if (Date.now() - stat.mtimeMs > START_LOCK_MAX_AGE_MS) {
+        rmSync(lockDir, { recursive: true, force: true });
+        mkdirSync(lockDir);
+        writeFileSync(
+          join(lockDir, "owner.json"),
+          `${JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString(), recovered: true })}\n`,
+          "utf8",
+        );
+        return () => rmSync(lockDir, { recursive: true, force: true });
+      }
+    } catch {
+      // Keep the original lock acquisition error below.
+    }
+    throw new Error(
+      `Run state is already being started: ${stateDir}. Retry after the current start finishes.`,
+      { cause: error },
+    );
+  }
+  return () => rmSync(lockDir, { recursive: true, force: true });
+}
+
 function prepareStateDirForStart(stateDir: string): void {
   const existing = readJson(join(stateDir, "run.json"));
   const existingPid = Number(existing?.pid || 0);
@@ -316,8 +364,12 @@ export function startRun(
   const resolved = resolveRunTemplate(startParams);
   const run = safeRunId(startParams.run_id);
   const stateDir = resolveStateDir(startParams, run);
+  assertNoActiveRunState(stateDir);
   mkdirSync(stateDir, { recursive: true });
-  prepareStateDirForStart(stateDir);
+  const releaseStartLock = acquireStateStartLock(stateDir);
+  try {
+    assertNoActiveRunState(stateDir);
+    prepareStateDirForStart(stateDir);
   const stdout = join(stateDir, "stdout.log");
   const stderr = join(stateDir, "stderr.log");
   const recipeFile = startParams.file
@@ -359,6 +411,9 @@ export function startRun(
     values,
     ...(artifacts ? { artifacts } : {}),
     ...(startParams.mailbox ? { mailbox: startParams.mailbox } : {}),
+    ...(startParams.retire_when === "children_terminal"
+      ? { retire_when: "children_terminal" as const }
+      : {}),
   };
   writeJsonAtomic(join(stateDir, "run.json"), meta);
   const child = spawn(process.execPath, argv, {
@@ -383,6 +438,9 @@ export function startRun(
   );
   child.unref();
   return meta;
+  } finally {
+    releaseStartLock();
+  }
 }
 
 function normalizeRunOutboxDelivery(value: unknown): RunOutboxDelivery {

package/lib/execution.ts

@@ -70,6 +70,8 @@ export type RegisteredToolExec = (
   options?: ToolExecOptions,
 ) => Promise<ToolExecResult>;
 
+const DEFAULT_MAX_PARALLEL_BRANCHES = 64;
+
 type TemplateExecution = {
   branches: BranchReport[];
   commands: string[];
@@ -170,6 +172,19 @@ function createSoftQuorum(
   };
 }
 
+function getMaxParallelBranches(): number {
+  const raw = Number(process.env.PI_ACTORS_MAX_PARALLEL_BRANCHES ?? "");
+  return Number.isInteger(raw) && raw > 0 ? raw : DEFAULT_MAX_PARALLEL_BRANCHES;
+}
+
+function assertParallelBranchLimit(count: number): void {
+  const max = getMaxParallelBranches();
+  if (count <= max) return;
+  throw new Error(
+    `Command template parallel fanout ${count} exceeds limit ${max}; set PI_ACTORS_MAX_PARALLEL_BRANCHES to override intentionally.`,
+  );
+}
+
 function normalizeFailureScope(
   value: CommandTemplates.CommandTemplateFailureScope | undefined,
 ): CommandTemplates.CommandTemplateFailureScope {
@@ -428,6 +443,7 @@ async function executeTemplateConfig(
     );
     if (repeat === undefined)
       throw new Error("Command template repeat could not be resolved.");
+    if (normalized.parallel === true) assertParallelBranchLimit(repeat);
     const repeatedSteps = Array.from({ length: repeat }, (_unused, index0) => {
       const { repeat: _repeat, ...rest } = normalized;
       return {
@@ -521,6 +537,7 @@ async function executeTemplateConfig(
   if (steps.length === 0)
     throw new Error(formatToolText("Tool template produced no command steps."));
   if (normalized.parallel === true) {
+    assertParallelBranchLimit(steps.length);
     const branchResults = await Promise.all(
       steps.map((step) =>
         executeTemplateConfig(

package/lib/file-state.ts

@@ -4,12 +4,13 @@
  * Owns generic durable JSON file writes shared by registry config and async run state.
  */
 
+import { randomUUID } from "node:crypto";
 import { mkdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 
 export function writeJsonAtomic(path: string, value: unknown): void {
   mkdirSync(dirname(path), { recursive: true });
-  const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+  const tempPath = `${path}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`;
   try {
     writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
     renameSync(tempPath, path);

package/lib/observability.ts

@@ -27,6 +27,7 @@ export interface RunObservation {
   ownerId?: string;
   artifacts?: Record<string, string>;
   terminalHandled?: boolean;
+  retireWhen?: string;
   run: string;
   stateDir?: string;
   status: RunObservedStatus;
@@ -45,6 +46,12 @@ export interface RunSummary {
   total: number;
 }
 
+export interface RunRetirementCandidate {
+  activeSubagents: number;
+  run: string;
+  stateDir: string;
+}
+
 export interface RunTransition {
   from: RunObservedStatus;
   run: string;
@@ -77,6 +84,12 @@ const TERMINAL = new Set<RunObservedStatus>([
   "cancelled",
   "killed",
 ]);
+const PROC_DESCENDANT_SCAN_TTL_MS = 1000;
+
+const procDescendantScanCache = new Map<
+  string,
+  { count: number; expiresAt: number; signature: string }
+>();
 
 function toNumber(value: unknown): number | undefined {
   const number = Number(value);
@@ -120,6 +133,9 @@ function observeRun(stateDir: string): RunObservation | undefined {
         ? { artifacts: status.artifacts as Record<string, string> }
         : {}),
       ...(status.terminal_handled ? { terminalHandled: true } : {}),
+      ...(typeof status.retire_when === "string"
+        ? { retireWhen: status.retire_when }
+        : {}),
       run,
       stateDir,
       status: status.status as RunObservedStatus,
@@ -160,10 +176,12 @@ export function summarizeRuns(
   const failed = runs.filter((run) => run.status === "failed").length;
   const cancelled = runs.filter((run) => run.status === "cancelled").length;
   const killed = runs.filter((run) => run.status === "killed").length;
-  const runningSubagents = runningRuns.reduce(
+  const progressSubagents = runningRuns.reduce(
     (sum, run) => sum + Math.max(1, Math.floor(run.activeSubagents ?? 0)),
     0,
   );
+  const processSubagents = countRunningSubagents(stateRoot, ownerId);
+  const runningSubagents = Math.max(progressSubagents, running + processSubagents);
   return {
     cancelled,
     done,
@@ -253,9 +271,22 @@ export function countRunningSubagents(
 ): number {
   const runPids = getRunningRunPids(stateRoot, ownerId);
   if (runPids.size === 0 || !existsSync("/proc")) return 0;
+  const signature = [...runPids].sort().join(",");
+  const cacheKey = `${stateRoot}\0${ownerId ?? ""}`;
+  const cached = procDescendantScanCache.get(cacheKey);
+  const now = Date.now();
+  if (cached && cached.signature === signature && cached.expiresAt > now) {
+    return cached.count;
+  }
   const parentByPid = new Map<string, string>();
   const commandByPid = new Map<string, string>();
-  for (const entry of readdirSync("/proc", { withFileTypes: true })) {
+  let procEntries: import("node:fs").Dirent[];
+  try {
+    procEntries = readdirSync("/proc", { withFileTypes: true });
+  } catch {
+    return 0;
+  }
+  for (const entry of procEntries) {
     if (!entry.isDirectory() || !/^\d+$/.test(entry.name)) continue;
     const ppid = getProcPpid(entry.name);
     if (!ppid) continue;
@@ -277,6 +308,11 @@ export function countRunningSubagents(
     if (!command.includes("pi -p") && !command.includes("pi\0-p")) continue;
     if (descendantOfRun(pid)) count++;
   }
+  procDescendantScanCache.set(cacheKey, {
+    count,
+    expiresAt: now + PROC_DESCENDANT_SCAN_TTL_MS,
+    signature,
+  });
   return count;
 }
 
@@ -299,6 +335,23 @@ export function renderRunStatus(
   return renderSubagentStatus(summary.runningSubagents, frame);
 }
 
+export function findRunRetirementCandidates(
+  summary: RunSummary,
+): RunRetirementCandidate[] {
+  return summary.runs
+    .filter((run) =>
+      run.status === "running" &&
+      run.retireWhen === "children_terminal" &&
+      run.stateDir &&
+      Math.floor(run.activeSubagents ?? 0) <= 0,
+    )
+    .map((run) => ({
+      activeSubagents: Math.max(0, Math.floor(run.activeSubagents ?? 0)),
+      run: run.run,
+      stateDir: run.stateDir!,
+    }));
+}
+
 export function detectRunTransitions(
   previous: Map<string, RunObservedStatus>,
   summary: RunSummary,
@@ -384,6 +437,33 @@ function readOutboxLines(run: RunObservation): string[] {
   return content ? content.split("\n") : [];
 }
 
+export function pruneRunObservationState(
+  previousStatuses: Map<string, RunObservedStatus>,
+  previousLineCounts: Map<string, number>,
+  summary: RunSummary,
+  terminalRuns: Iterable<string> = [],
+): void {
+  const activeRuns = new Set(summary.runs.map((run) => run.run));
+  const terminalRunSet = new Set(terminalRuns);
+  const terminalLineKeys = new Set(
+    summary.runs
+      .filter((run) => terminalRunSet.has(run.run))
+      .map((run) => run.stateDir ?? run.run),
+  );
+  const activeLineKeys = new Set(
+    summary.runs.map((run) => run.stateDir ?? run.run),
+  );
+  for (const run of terminalRunSet) previousStatuses.delete(run);
+  for (const run of previousStatuses.keys()) {
+    if (!activeRuns.has(run)) previousStatuses.delete(run);
+  }
+  for (const key of previousLineCounts.keys()) {
+    if (terminalLineKeys.has(key) || !activeLineKeys.has(key)) {
+      previousLineCounts.delete(key);
+    }
+  }
+}
+
 export function detectRunOutboxEvents(
   previousLineCounts: Map<string, number>,
   summary: RunSummary,

package/lib/prompts.ts

@@ -25,13 +25,13 @@ export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
 - Command templates stay sync: string leaf, array sequence, object node; flags include args/defaults, parallel, when, timeout, delay, retry, failure, recover, repeat, output.
 - Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.
 - ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.
-- Recipes own template directly and may declare metadata/defaults/imports/mailbox/artifacts.
+- Recipes own template directly and may declare metadata/defaults/imports/mailbox/artifacts; files >1 MiB or import depth >32 fail closed.
 - Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.
 - Use spawn/message/inspect for actor-level start/send/observe; avoid runtime/FIFO/outbox vocabulary in public guidance.
 - Run state lives under ~/.pi/agent/tmp/pi-actors/runs; inspect status/tail/messages/mailbox/files/artifacts intentionally and avoid busy-polling.
 - Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones; packaged recipes are lower-priority components, not tools by location.
 - Foreground tools/templates fit short work; async recipes/runs fit subagents, services, fanout, media, and long pipelines.
-- Long fanout = parent async recipe wrapping template(parallel:true) and imports; packaged fanout recipes bubble branch completion messages.
+- Long fanout = parent async recipe wrapping template(parallel:true) and imports; packaged fanout recipes bubble branch completion messages; grow recurring multi-agent workflows as packaged recipes/pipelines, not ad hoc external scripts.
 - For deeper pi-actors guidance, inspect installed extension sources/docs/recipes; README and docs are not automatically in context.`;
 
 export const REGISTER_TOOL_PARAM_DESCRIPTIONS = {