@llblab/pi-actors 0.41.1 → 0.42.0

package/dist/lib/tools-inspect.js

@@ -11,6 +11,7 @@ import * as Limits from "./limits.js";
 import * as Messages from "./messages.js";
 import * as Paths from "./paths.js";
 import * as RecipesDiscovery from "./recipes-discovery.js";
+import * as ReviewDiagnostics from "./review-diagnostics.js";
 import * as Rooms from "./rooms.js";
 import * as Schema from "./schema.js";
 import * as ToolsAccess from "./tools-access.js";
@@ -18,6 +19,14 @@ import * as ToolsMailbox from "./tools-mailbox.js";
 import * as ToolsResponse from "./tools-response.js";
 const asRecord = ToolsResponse.asRecord;
 const maybeJsonText = ToolsResponse.maybeJsonText;
+function compactAutomaticReviewDiagnostics(diagnostics) {
+    const draft = asRecord(diagnostics.draft_review);
+    const tool = asRecord(diagnostics.tool_review);
+    return [
+        `automatic_reviews draft=${String(draft.phase ?? "idle")} tool=${String(tool.phase ?? "idle")}`,
+        `lineages=${String(diagnostics.lineage_count ?? 0)} revision_snapshots=${String(diagnostics.revision_snapshots ?? 0)}`,
+    ].join("\n");
+}
 function compactRunMessages(messages) {
     if (messages.length === 0)
         return "\n(no actor messages)";
@@ -222,6 +231,7 @@ function getPiActorsRuntimeStatus() {
     }
     const entrypoint = new URL(import.meta.url).pathname;
     return {
+        automatic_recipe_review: Paths.isAutomaticRecipeReviewEnabled(),
         entrypoint,
         git_commit,
         mode: entrypoint.includes("/dist/") ? "dist" : "source",
@@ -233,7 +243,7 @@ function getPiActorsRuntimeStatus() {
     };
 }
 function compactPiActorsRuntimeStatus(status) {
-    return `\npi-actors version=${String(status.version)} mode=${String(status.mode)} path=${String(status.package_root)} entrypoint=${String(status.entrypoint)}${status.git_commit ? ` git=${String(status.git_commit)}` : ""}`;
+    return `\npi-actors version=${String(status.version)} mode=${String(status.mode)} automatic_review=${String(status.automatic_recipe_review)} path=${String(status.package_root)} entrypoint=${String(status.entrypoint)}${status.git_commit ? ` git=${String(status.git_commit)}` : ""}`;
 }
 function isStaleClaim(message, now) {
     if (message.status !== "claimed")
@@ -436,8 +446,21 @@ export function createInspectToolDefinition(deps = {}) {
                 if (view !== "status" &&
                     view !== "summary" &&
                     view !== "doctor" &&
-                    view !== "imports") {
-                    throw new Error("inspect recipes supports view=status, view=summary, view=doctor, or view=imports.");
+                    view !== "imports" &&
+                    view !== "reviews") {
+                    throw new Error("inspect recipes supports view=status, view=summary, view=doctor, view=imports, or view=reviews.");
+                }
+                if (view === "reviews") {
+                    const diagnostics = ReviewDiagnostics.readAutomaticReviewDiagnostics({
+                        recipeRoot: deps.recipeRoot ?? Paths.getRecipeRoot(),
+                    });
+                    return {
+                        content: [{
+                                type: "text",
+                                text: maybeJsonText(diagnostics, input.verbose === true, compactAutomaticReviewDiagnostics(diagnostics)),
+                            }],
+                        details: diagnostics,
+                    };
                 }
                 const discovered = RecipesDiscovery.discoverRecipeSources([
                     {

package/dist/lib/tools-local.js

@@ -110,8 +110,10 @@ export function createRuntimeToolDefinition(cfg, exec) {
             : Prompts.formatRegisteredToolPromptSnippet(cfg.template),
         async execute(_toolCallId, params, signal, _onUpdate, ctx) {
             try {
-                if (cfg.sourcePath)
-                    RecipesUsage.recordRecipeLaunch(cfg.sourcePath, new Date(), "tool");
+                if (cfg.sourcePath &&
+                    !RecipesUsage.recordRecipeLaunch(cfg.sourcePath, new Date(), "tool")) {
+                    throw new Error(`Recipe launch rejected because its source changed during activation: ${cfg.sourcePath}. Reload recipe tools and retry.`);
+                }
                 if (isAsyncRecipe) {
                     const input = params;
                     const { run_id, ...values } = input;

package/dist/lib/tools-message.d.ts

@@ -5,5 +5,6 @@
  */
 export interface ActorMessageToolDeps<TContext = unknown> {
     getTool?: (name: string) => any | undefined;
+    handleRuntimeMessage?: (type: string, body: unknown) => Record<string, unknown>;
 }
 export declare function createActorMessageToolDefinition<TContext = unknown>(deps?: ActorMessageToolDeps<TContext>): any;

package/dist/lib/tools-message.js

@@ -274,7 +274,14 @@ export function createActorMessageToolDefinition(deps = {}) {
                     ]
                     : [];
                 if (message.type === "control.kill") {
-                    result = AsyncRuns.killRun(address.value);
+                    result = typeof status.run_instance_id === "string"
+                        ? AsyncRuns.killRun(address.value, {
+                            ...(typeof status.ownerId === "string"
+                                ? { ownerId: status.ownerId }
+                                : {}),
+                            runInstanceId: status.run_instance_id,
+                        })
+                        : { killed: false, reason: "run generation unavailable" };
                 }
                 else if (message.type === "control.archive") {
                     result = AsyncRuns.archiveRun(address.value);
@@ -344,24 +351,29 @@ export function createActorMessageToolDefinition(deps = {}) {
                 };
             }
             else if (address.kind === "tool" && address.value) {
-                const tool = deps.getTool?.(address.value);
-                if (!tool || typeof tool.execute !== "function") {
-                    throw new Error(`tool actor not found or not executable: ${address.value}`);
+                if (address.value === "pi-actors" && deps.handleRuntimeMessage) {
+                    result = deps.handleRuntimeMessage(message.type, message.body);
                 }
-                const toolParams = messageBodyToToolParams(message);
-                let toolResult;
-                try {
-                    toolResult = await tool.execute(`message:${message.type}`, toolParams, _signal, _onUpdate, ctx);
-                }
-                catch (error) {
-                    throw formatToolActorFailure(address.value, message, toolParams, error);
+                else {
+                    const tool = deps.getTool?.(address.value);
+                    if (!tool || typeof tool.execute !== "function") {
+                        throw new Error(`tool actor not found or not executable: ${address.value}`);
+                    }
+                    const toolParams = messageBodyToToolParams(message);
+                    let toolResult;
+                    try {
+                        toolResult = await tool.execute(`message:${message.type}`, toolParams, _signal, _onUpdate, ctx);
+                    }
+                    catch (error) {
+                        throw formatToolActorFailure(address.value, message, toolParams, error);
+                    }
+                    result = {
+                        invoked: true,
+                        sent: true,
+                        tool: address.value,
+                        tool_result: toolResult,
+                    };
                 }
-                result = {
-                    invoked: true,
-                    sent: true,
-                    tool: address.value,
-                    tool_result: toolResult,
-                };
             }
             else if (address.kind === "coordinator" || address.kind === "session") {
                 if (!message.from) {

package/dist/lib/tools-spawn.js

@@ -6,10 +6,12 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import * as AsyncRuns from "./async-runs.js";
+import { withFileMutationLock } from "./file-state.js";
 import * as Messages from "./messages.js";
 import * as ModelContext from "./model-context.js";
 import * as Paths from "./paths.js";
 import * as RecipesDiscovery from "./recipes-discovery.js";
+import * as RecipesUsage from "./recipes-usage.js";
 import * as Rooms from "./rooms.js";
 import * as Schema from "./schema.js";
 import * as ToolsResponse from "./tools-response.js";
@@ -62,7 +64,8 @@ function writeSpawnDraftRecipe(input, meta) {
         ...(defaults ? { defaults } : {}),
         template: input.template,
     };
-    writeFileSync(path, `${JSON.stringify(recipe, null, 2)}\n`, { flag: "wx" });
+    withFileMutationLock(root, () => withFileMutationLock(path, () => writeFileSync(path, `${JSON.stringify(recipe, null, 2)}\n`, { flag: "wx" })));
+    RecipesUsage.recordRecipeLaunch(path, new Date(), "spawn", Paths.getRecipeRoot());
     return path;
 }
 function enhanceSpawnRecipeError(error, recipe) {

package/dist/lib/tools.d.ts

@@ -15,6 +15,7 @@ export interface CoreActorToolDefinitionDeps<TContext extends RuntimeToolContext
     configPath: string;
     getActiveTools: () => string[];
     getRuntimeTool: (name: string) => unknown;
+    handleRuntimeMessage?: (type: string, body: unknown) => Record<string, unknown>;
     registryRuntime: Pick<RegisterToolRuntimeDeps<TContext>, "getToolNameBlocker" | "getTools" | "notify" | "registerRuntimeTool">;
     setActiveTools: (toolNames: string[]) => void;
 }

package/dist/lib/tools.js

@@ -38,6 +38,7 @@ export function createCoreActorToolDefinitions(deps) {
         ToolsSpawn.createSpawnToolDefinition(),
         ToolsMessage.createActorMessageToolDefinition({
             getTool: (name) => deps.getRuntimeTool(name),
+            handleRuntimeMessage: deps.handleRuntimeMessage,
         }),
         ToolsInspect.createInspectToolDefinition({
             getTool: (name) => deps.getRuntimeTool(name),

package/dist/recipes/draft-review.json

@@ -0,0 +1,24 @@
+{
+  "async": true,
+  "args": [
+    "input_path:path",
+    "model:string",
+    "thinking:string"
+  ],
+  "defaults": {
+    "model": "{current_model}",
+    "thinking": "{current_thinking}"
+  },
+  "description": "Read-only background reviewer for one immutable automatic draft-memory batch.",
+  "mailbox": {
+    "accepts": [
+      "control.kill"
+    ],
+    "emits": [
+      "command.done",
+      "run.done",
+      "run.failed"
+    ]
+  },
+  "template": "pi -p --model {model} --thinking {thinking} --no-tools @{input_path} Review the attached immutable pi-actors draft batch. Evaluate every draft independently using launch history, universality, flexibility, parameterization, duplication, safety, and likely future usefulness. Treat draft and sha256 fields as batch-local opaque occurrence/content-group identifiers and return them verbatim. Choose exactly one promote or discard decision per draft; there is no selection quota. Promotion requires a unique absent snake_case target and targetSha256 null. Never return recipe content: the executor derives the exact immutable captured source. Invalid or secret-touching drafts must be discarded. Include assessment with launches, universality, flexibility, futureUsefulness, and safety. Do not mutate, move, register, or delete recipes. End stdout with DRAFT_REVIEW_RESULT on its own line followed by exactly one JSON object with batchId, createdAt, and decisions."
+}

package/dist/recipes/tool-review.json

@@ -0,0 +1,24 @@
+{
+  "async": true,
+  "args": [
+    "input_path:path",
+    "model:string",
+    "thinking:string"
+  ],
+  "defaults": {
+    "model": "{current_model}",
+    "thinking": "{current_thinking}"
+  },
+  "description": "Read-only background reviewer for one immutable 36-tool evolution portfolio.",
+  "mailbox": {
+    "accepts": [
+      "control.kill"
+    ],
+    "emits": [
+      "command.done",
+      "run.done",
+      "run.failed"
+    ]
+  },
+  "template": "pi -p --model {model} --thinking {thinking} --no-tools @{input_path} Review the attached immutable pi-actors active-tool portfolio. Evaluate all 36 tools independently using lifetime and revision usage, adaptability, redundancy, safety, contract quality, and likely future usefulness. Treat source/name and sha256 fields as batch-local opaque occurrence/content-group identifiers, return them verbatim, and infer exact duplication only from a shared content group. Choose exactly one keep, evolve, demote, or merge decision per tool; there is no action quota. evolve may only rename one unchanged captured recipe, demote moves the unchanged recipe to draft memory, and merge may only deduplicate at least two canonically identical captured recipes. Never return recipe or outputs fields; replace and split require explicit operator-authored mutation and are unavailable to automatic review. Do not mutate, register, move, or delete recipes. End stdout with TOOL_REVIEW_RESULT on its own line followed by exactly one JSON object with reviewId, createdAt, and decisions."
+}

package/dist/scripts/release-gates.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+/** Reproducible exact-tree, Domain DAG, secret-hygiene, and ABCd release gates. */
+
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, extname, join, normalize, relative, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const temp = mkdtempSync(join(tmpdir(), "pi-actors-release-index-"));
+const indexPath = join(temp, "index");
+const gitEnv = { ...process.env, GIT_INDEX_FILE: indexPath };
+const failures = [];
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    cwd: root,
+    encoding: "utf8",
+    maxBuffer: 32 * 1024 * 1024,
+    ...options,
+  });
+  if (result.status !== 0) {
+    throw new Error(
+      `${command} ${args.join(" ")} failed (${result.status}): ${(result.stderr || result.stdout || "no output").trim()}`,
+    );
+  }
+  return result.stdout;
+}
+
+function check(condition, message) {
+  if (!condition) failures.push(message);
+}
+
+function stagedText(path) {
+  const result = spawnSync("git", ["show", `:${path}`], {
+    cwd: root,
+    env: gitEnv,
+    encoding: "buffer",
+    maxBuffer: 16 * 1024 * 1024,
+  });
+  if (result.status !== 0) {
+    failures.push(`could not read staged file: ${path}`);
+    return undefined;
+  }
+  const bytes = result.stdout;
+  if (bytes.includes(0)) return undefined;
+  return bytes.toString("utf8");
+}
+
+function sourceImports(source) {
+  return [...source.matchAll(/^import(?:\s+type)?\s+(?:[^"']+?\s+from\s+)?["']([^"']+)["'];?$/gmu)]
+    .map((match) => match[1]);
+}
+
+function resolveLocalImport(from, specifier, sourceSet) {
+  if (!specifier.startsWith(".")) return undefined;
+  const base = normalize(join(dirname(from), specifier)).replaceAll("\\", "/");
+  const candidates = extname(base)
+    ? [base.replace(/\.js$/u, ".ts")]
+    : [`${base}.ts`, `${base}/index.ts`];
+  return candidates.find((candidate) => sourceSet.has(candidate));
+}
+
+try {
+  run("git", ["read-tree", "HEAD"], { env: gitEnv });
+  run("git", ["add", "-A"], { env: gitEnv });
+  run("git", ["diff", "--cached", "--check"], { env: gitEnv });
+  const files = run("git", ["ls-files", "-z"], { env: gitEnv })
+    .split("\0")
+    .filter(Boolean);
+  const fileSet = new Set(files);
+  console.log(`[release] exact temporary index: ${files.length} files`);
+
+  const secretPatterns = [
+    [/-----BEGIN(?: [A-Z0-9]+)? PRIVATE KEY-----[\s\S]{80,}?-----END(?: [A-Z0-9]+)? PRIVATE KEY-----/u, "private-key block"],
+    [/\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/u, "AWS access key"],
+    [/\bgithub_pat_[A-Za-z0-9_]{20,}\b|\bgh[pousr]_[A-Za-z0-9]{20,}\b/u, "GitHub token"],
+    [/\bglpat-[A-Za-z0-9_-]{20,}\b|\bnpm_[A-Za-z0-9]{20,}\b|\bxox[baprs]-[A-Za-z0-9-]{10,}\b/u, "service token"],
+  ];
+  const publicPath = /^(?:README\.md|AGENTS\.md|BACKLOG\.md|CHANGELOG\.md|docs\/|skills\/|recipes\/)/u;
+  for (const path of files) {
+    const text = stagedText(path);
+    if (text === undefined) continue;
+    if (!path.startsWith("tests/") && !path.startsWith("fixtures/")) {
+      for (const [pattern, label] of secretPatterns) {
+        check(!pattern.test(text), `${label} detected in ${path}`);
+      }
+    }
+    if (publicPath.test(path)) {
+      check(!/(?:^|[\s"'`])\/home\/[A-Za-z0-9._-]+\//u.test(text), `machine-local path in ${path}`);
+    }
+  }
+  console.log("[release] bounded secret and public-path hygiene checked");
+
+  const sources = files.filter((path) => path === "index.ts" || (path.startsWith("lib/") && path.endsWith(".ts")));
+  const sourceSet = new Set(sources);
+  const graph = new Map();
+  for (const path of sources) {
+    const text = stagedText(path) ?? "";
+    const headerEnd = text.indexOf("*/");
+    const header = headerEnd >= 0 ? text.slice(0, headerEnd + 2) : "";
+    check(
+      header.startsWith("/**") && (header.includes("Zones:") || header.includes("Owns:")),
+      `missing domain header: ${path}`,
+    );
+    const edges = sourceImports(text)
+      .map((specifier) => resolveLocalImport(path, specifier, sourceSet))
+      .filter(Boolean);
+    graph.set(path, edges);
+    if (path.startsWith("lib/")) {
+      check(!edges.includes("index.ts"), `domain imports entrypoint: ${path}`);
+    }
+  }
+  const visiting = new Set();
+  const visited = new Set();
+  function visit(path, stack = []) {
+    if (visiting.has(path)) {
+      failures.push(`Domain DAG cycle: ${[...stack, path].join(" -> ")}`);
+      return;
+    }
+    if (visited.has(path)) return;
+    visiting.add(path);
+    for (const next of graph.get(path) ?? []) visit(next, [...stack, path]);
+    visiting.delete(path);
+    visited.add(path);
+  }
+  for (const path of sources) visit(path);
+  console.log(`[release] strict Domain DAG: ${sources.length} sources, acyclic`);
+
+  for (const path of ["README.md", "AGENTS.md", "BACKLOG.md", "CHANGELOG.md", "docs/README.md"]) {
+    check(fileSet.has(path), `missing ABCd root/context file: ${path}`);
+  }
+  const readStaged = (path) => stagedText(path) ?? "";
+  const readme = readStaged("README.md");
+  for (const path of ["AGENTS.md", "BACKLOG.md", "CHANGELOG.md", "docs/README.md"]) {
+    check(readme.includes(path), `README.md does not route to ${path}`);
+  }
+  for (const path of files.filter((candidate) => candidate.endsWith(".md"))) {
+    const text = readStaged(path);
+    for (const match of text.matchAll(/\[[^\]]*\]\(([^)]+)\)/gu)) {
+      const target = match[1].split("#", 1)[0];
+      if (!target || /^(?:https?:|mailto:)/u.test(target)) continue;
+      const resolved = normalize(join(dirname(path), decodeURIComponent(target))).replaceAll("\\", "/");
+      check(fileSet.has(resolved), `broken Markdown link: ${path} -> ${target}`);
+    }
+  }
+  const docsIndex = readStaged("docs/README.md");
+  for (const path of files.filter((candidate) => candidate.startsWith("docs/") && candidate.endsWith(".md") && candidate !== "docs/README.md")) {
+    check(docsIndex.includes(relative("docs", path).replaceAll("\\", "/")), `docs/README.md omits ${path}`);
+  }
+  console.log("[release] ABCd context roots, routing, and Markdown links checked");
+
+  if (failures.length > 0) {
+    for (const failure of failures) console.error(`[FAIL] ${failure}`);
+    process.exitCode = 1;
+  } else {
+    console.log("[release] all supplemental release gates passed");
+  }
+} catch (error) {
+  console.error(`[FAIL] ${error instanceof Error ? error.message : String(error)}`);
+  process.exitCode = 1;
+} finally {
+  rmSync(temp, { recursive: true, force: true });
+}

package/dist/skills/actors/SKILL.md

@@ -2,7 +2,7 @@
 name: actors
 description: Required practical guide for non-trivial pi-actors use, including parallel actor launches, subagent fanout, and autonomous coordinator workflows. Read before using or changing spawn, message, inspect, actor runs, tools, recipes, command templates, async lifecycle, mailboxes, artifacts, and local orchestration mechanics.
 metadata:
-  version: 0.41.1
+  version: 0.42.0
 ---
 
 # Actors (pi-actors)
@@ -40,7 +40,7 @@ Trusted local capability
 - **Command template**: portable execution graph. String leaf, sequence array, or object node with controls.
 - **Recipe**: saved JSON definition wrapping a template with args, defaults, imports, mailbox, artifacts, metadata, and optional `async: true`.
 - **Run actor**: one detached execution instance addressable as `run:<id>` with status, logs, messages, mailbox metadata, files, and artifacts.
-- **Tool actor**: registered persistent capability addressable as `tool:<name>` and callable through the generated tool or `message`. `tool:pi-actors` is reserved for runtime/status inspection.
+- **Tool actor**: registered persistent capability addressable as `tool:<name>` and callable through the generated tool or `message`. `tool:pi-actors` is reserved for runtime status and explicit automatic-review retry/reset control.
 - **Artifact**: named durable output path declared by a recipe/run.
 - **Mailbox**: interaction contract: message types the actor accepts/emits.
 - **Advanced group/coordination surfaces**: `branch:<run>/<branch>`, `room:<run>`, `coordinator`, `session:<id>`, and communication snapshots exist for multi-actor workflows and diagnostics; do not make them the default mental model.
@@ -94,7 +94,8 @@ Envelope fields:
 - Group posts to `room:<run>` require `from` from the same run (`run:<run>` or `branch:<run>/<branch>`).
 - Runtime termination message: `control.kill` is the only documented actor message that kills a run. `control.stop` and `control.cancel` are actor-local mailbox vocabulary only when a recipe declares and handles them. Terminal retention messages: `control.archive`, `control.prune`.
 - Long-lived child processes should remain in the run-owned process group unless the recipe implements an explicit daemon termination bridge; do not leave unowned detached services behind `control.kill`.
-- Run controls revalidate a persisted cross-platform process identity proof before delivery or signaling. Treat `dead pid`, `owner mismatch`, and `unsupported proof` as distinct fail-closed states; never bypass them with direct pid signals.
+- Run controls revalidate a persisted cross-platform process identity proof at authorization and again immediately before signaling. Treat `dead pid`, `owner mismatch`, and `unsupported proof` as distinct fail-closed states; on Unix, only process-group `ESRCH` plus one more matching identity check permits exact-pid fallback, while permission/authorization errors remain terminal. Node exposes no portable pidfd/process-group handle, so retain the documented residual exit/reuse window instead of claiming atomic signaling or bypassing control with direct pid signals.
+- Detached actors survive ordinary agent turns. On `session_shutdown` (quit, reload, or session replacement), pi-actors attempts canonical `control.kill` for each discovered readable still-running exact-owner run. Control compares immutable run generation inside the canonical boundary and serializes against same-directory restart; terminal, ambiguous, changed-generation, and other-session runs remain untouched. Teardown scans without the ordinary index depth cap, reports unreadable/corrupt state as failures, and persists a bounded summary under the run root. Descendant Pi sessions remain separate owners and rely on their own shutdown hooks; hard host termination can still leave an orphan requiring summary-guided OS/manual recovery, so never describe teardown as an absolute no-survivor guarantee.
 
 Check `inspect view=mailbox` before domain-specific messages.
 
@@ -216,15 +217,15 @@ Only matching filename ids compete. Higher priority shadows lower priority; with
 Muscle-memory lens: pi-actors has two durable executable-memory layers.
 
 1. `~/.pi/agent/recipes/*.json` and `*.md` are the agent's active capability memory. Every recipe in that directory becomes an easy-to-call tool automatically and survives into later sessions. Descriptions matter here because they become the tool's operator-facing title/context.
-2. `~/.pi/agent/recipes/drafts/*.json` is draft memory captured from successful inline `spawn template=...` runs. Drafts do not enter the injected tool surface. They remain reusable by explicit path, e.g. `spawn file="~/.pi/agent/recipes/drafts/<name>.json"`, and can be promoted by moving or copying one level up into `~/.pi/agent/recipes`.
+2. `~/.pi/agent/recipes/drafts/*.json` is draft memory captured from successful inline `spawn template=...` runs. Drafts do not enter the injected tool surface and remain reusable by explicit path, e.g. `spawn file="~/.pi/agent/recipes/drafts/<name>.json"`.
 
-Agents grow active memory by calling `register_tool` or by deliberate recipe-file edits. They grow draft memory by trying ad hoc actors successfully. Treat both as executable habits: drafts are the workbench/proving ground; root recipes are promoted muscle memory.
+Agents grow draft memory by trying ad hoc actors successfully. Active memory grows through explicit `register_tool`, deliberate operator recipe edits, or the bounded automatic review cycle. Treat drafts as the workbench and root recipes as active muscle memory.
 
-Usage lens: user recipe launches update extension-maintained `.usage/<recipe-filename>.json` sidecars with fields such as `usage.calls` and `usage.last_called`; authored recipe files are not rewritten for telemetry. Discovery merges the sidecar into inspection. Agents should not hand-edit counters as part of normal recipe maintenance. Treat usage as evidence for usefulness analysis: heavily used recipes are good candidates for promotion, documentation, or stronger tests; unused recipes are cleanup candidates. Do not use failure counts as a primary usefulness signal because failures may reflect bad caller judgment rather than bad recipes. Do not delete or demote solely from counters without operator approval.
+Usage lens: user recipe launches update an extension-maintained canonical name-and-priority lineage ledger under `.usage/recipes/<recipe-name>.json`; authored recipe files are not rewritten for telemetry. Accounting briefly shares the portfolio mutation fence so source quarantine cannot erase an authorized launch; if another session already changed the source, the stale invocation rejects and requests reload rather than executing without evidence. Lifetime calls survive rename, revision, promotion, and demotion, while revision-local calls restart when executable content changes. The bounded unversioned ledger retains former names/paths, revision ancestry, transition events, and review epochs. Discovery merges lineage usage into inspection. Agents should not hand-edit counters; usage remains evidence rather than a sufficient usefulness verdict.
 
-Promotion lens: successful transient/ad hoc actor runs are evidence, not commands. Inline spawns leave draft recipes as replayable evidence, not active tools. If a draft is repeatable, parameterized, safe enough, and likely useful later, the agent may promote it by moving/copying it into `~/.pi/agent/recipes` or by calling `register_tool` with a concise name, typed args/defaults, and a reviewed template or recipe path. Do not auto-register every success; do not promote temp paths, secrets, one-off prompts, or project-private assumptions without normalization and approval.
+Automatic review lens: successful transient/ad hoc actor runs leave replayable drafts rather than active tools. At twelve eligible drafts, pi-actors captures one exact trusted batch and attaches only its identity-opaque value-free structural projection to a silent no-tools reviewer after the foreground turn and active actors finish. Its complete quota-free `promote`/`discard` result contains no recipe content: the deterministic executor derives promotions from exact captured sources and revalidates source/target CAS, complete recipes, root identity, quarantine hashes, and recovery state before commit. Newer drafts remain for a later batch; malformed, stale, unsafe, or incomplete decisions fail closed. Unchanged automatic demotions remain in cooldown until their executable fingerprint changes. Prefer fenced `register_tool draft=...` for an explicit single-draft promotion. A deliberate move/copy into the recipe root also remains valid, but may invalidate and defer an already captured batch; do not reconstruct removed batch commands or ask the operator to drive an automatic batch.
 
-Cleanup rule: periodically inspect `~/.pi/agent/recipes` as the live muscle-memory set. For each stale, duplicate, too-specific, or low-value recipe, choose one explicit action: keep as a tool, move it out of the agent recipe root to retain recipe-only memory, merge into a better recipe, or delete/archive the file. Prefer moving over deletion when the recipe may still be useful as a component. Never silently remove tools during unrelated work.
+Portfolio lens: thirty-six eligible non-sensitive active revisions trigger a no-tools review of an attached value-free structural projection; canonical names, draft basenames, raw hashes, recipe bodies, template/default values, authored prose, and filesystem paths remain in the separate trusted capture; batch-local occurrence IDs and equality-only content groups preserve correlation and deduplication. Set `PI_ACTORS_AUTOMATIC_REVIEW=off` before Pi starts to disable both reviewer scheduling and safe-boundary portfolio activation; verify the effective value with `inspect target=tool:pi-actors view=status`. The reviewer may select keep, unchanged-source rename, unchanged-source demotion, or deduplication of canonically identical captured recipes; it cannot return recipe content. Replacement, split, and executable contract changes require explicit operator authoring. Approval remains immutable until the next safe session boundary, where journaled filesystem and lineage executors apply only the captured recipe bytes. Use `inspect target=recipes view=reviews` for bounded evidence including failed stage/error/next action. Recover a failed cycle through `message to=tool:pi-actors type=review.retry body={"scope":"draft"|"tool"}`. Draft retry resumes an existing authenticated transaction plan and original reviewer run rather than generating decisions after filesystem commit; `review.reset` clears only disposable terminal admission state and rejects tool recovery evidence that must roll forward.
 
 ## Registered Tools
 

package/dist/skills/swarm/SKILL.md

@@ -2,7 +2,7 @@
 name: swarm
 description: Subagent and actor orchestration with scoped locks, fanout, and quorum consensus. Use before launching multiple parallel actors or subagents for independent implementation, artifact generation, review, delegated audit, coordinated execution, or any workflow that needs autonomous coordinator decomposition and integration.
 metadata:
-  version: 0.41.1
+  version: 0.42.0
 ---
 
 # Swarm

package/docs/actor-inspector.md

@@ -1,12 +1,13 @@
 # Actor Inspector
 
-The actor inspector is a manually opened, read-only TUI navigator for owned actor runs. It keeps communication evidence and persisted subagent execution evidence in one hierarchy without merging their meanings.
+The actor inspector is a manually opened TUI navigator for owned actor runs. Evidence remains read-only; its one explicit lifecycle action can send canonical `control.kill` to the selected running run after confirmation. It keeps recipe/launch identity, communication evidence, and persisted subagent execution evidence in one hierarchy without merging their meanings.
 
 ```text
 owned run
+  → recipe
   → messages | turns
     → filtered timeline
-      → bounded detail
+      → one bounded detail level
 ```
 
 ## Navigation
@@ -16,18 +17,20 @@ owned run
 The overlay exposes an explicit focus hierarchy:
 
 ```text
-Run       ←/→ chooses the previous/next owned run, Enter opens runs, ↓ enters tabs
-Tabs      ←/→ chooses Messages or Turns, Enter opens filter parameters
-Filters   ↑/↓ chooses Channel/State or Subagent, Enter opens values to the right
+Run       ←/→ chooses the previous/next owned run, Enter opens runs, K asks to Kill a running run, ↓ enters tabs
+Tabs      ←/→ chooses Recipe, Messages, or Turns
+Recipe    ↑/↓ scroll; PageUp/PageDown jumps by viewport; ↑ at top, Escape, or ← returns to tabs
+Filters   Enter on Messages/Turns opens Channel/State or Subagent; Enter opens values
 Values    ↑/↓ hovers, Enter applies, Escape returns one menu level
-List      ↑/↓ chooses, Enter/→ opens detail
-Detail    ↑/↓ scroll, Enter/→ opens readable transcript, Escape/← returns
-Readable  ↑/↓ scroll, Escape/← returns to evidence detail
+List      ↑/↓ chooses, PageUp/PageDown jumps by viewport, Enter/→ opens detail, ← returns to tabs
+Detail    ↑/↓ scroll, PageUp/PageDown jumps by viewport, Escape/← returns to the list
 Escape    Close (or cancel the active options popup)
 ```
 
 Navigation stays bounded by available actions. `↑` on Run does nothing because no higher control exists. `↓` on Tabs enters the timeline only when it contains rows. Empty timelines therefore never receive focus.
 
+`K` appears only while Run is focused and the selected owned run reports `running`. It opens an in-overlay destructive confirmation; `Y`/Enter confirms and `N`/Escape cancels. Confirmation captures the immutable run generation and routes expected owner/generation through canonical `control.kill`; control compares both while serialized against same-directory restart, so terminal, ownership, or replacement-generation races reject without signaling. Success, cancellation, rejection, and failure remain bounded in the content area; terminal runs expose no Kill hint and reject a stale keypress.
+
 Selection and focus remain separate visual states. Accent-blue text marks the current tab, active filter popup, and applied option. The Run control uses `← … →` markers plus a light neutral background to show both focus and horizontal cycling; menus and timeline rows retain the single `▶` focus marker, while selected tabs retain brackets. Opening a popup keeps its parent filter blue so the relationship remains visible. The footer uses accent color only for key names and arrows; descriptions remain muted.
 
 The top Run control aligns vertically with the tab labels, names the selected owned run, and colors its textual lifecycle status semantically. ←/→ cycles owned runs directly with wraparound, while Enter opens the complete owned-run list immediately beneath the control. That run list starts one cell farther left than the filter menus so its border aligns with the Run control rather than the tab/filter grid. It still overlays the tab row rather than leaving a detached gap. The timeline no longer renders run metadata as a data row.
@@ -36,7 +39,13 @@ Filters live behind their tab rather than occupying a permanent row. Non-default
 
 Nested menus overlay rather than replace the timeline. Only rows and columns containing menu borders or values occlude underlying cells. When adjacent menus have different heights, the unused corner remains transparent and preserves the separator, striped background, and timeline data beneath it. Every run, filter, and nested value menu is viewport-bounded: ↑/↓ moves through the complete option set, the visible window follows focus, and `↑`/`↓` border markers disclose hidden options above or below without growing past the available inspector rows.
 
-The overlay uses most of the available terminal width and height and reduces its content/menu viewport on shorter terminals. The bordered header keeps both tabs visible, while the list body shows the selected run and its current status above the evidence rows. Run, Message, and Turn lists place the newest retained item directly below their control; a newly opened Inspector therefore selects the latest owned run, and ↓ moves backward in time toward older entries. Run options, Messages, and Turns all use compact descending `#N` labels, providing one timestamp-free time axis without repeating type words on every row. Evidence rows retain stable alternating backgrounds based on their absolute timeline position, including while scrolling: even rows keep the dark overlay background, while odd rows use the neutral `customMessageBg` stripe. Unused viewport padding stays on the plain overlay background instead of drawing fake striped rows beneath the last item. The footer exposes the active keys. Messages retain attention markers and unread filtering and open into bounded detail without leaving the overlay. The overlay refreshes while visible and distinguishes true empty timelines from filtered-empty results; filtered-empty copy points back to Enter on the active tab without moving focus.
+The overlay uses most of the available terminal width and height and reduces its content/menu viewport on shorter terminals. The bordered header keeps all three tabs visible, while the body shows the selected run and its current status above the active document or evidence rows. Run, Message, and Turn lists place the newest retained item directly below their control; a newly opened Inspector therefore selects the latest owned run, and ↓ moves backward in time toward older entries. Run options, Messages, and Turns all use compact descending `#N` labels, providing one timestamp-free time axis without repeating type words on every row. Evidence rows retain stable alternating backgrounds based on their absolute timeline position, including while scrolling: even rows keep the dark overlay background, while odd rows use the neutral `customMessageBg` stripe. Unused viewport padding stays on the plain overlay background instead of drawing fake striped rows beneath the last item. The footer exposes the active keys. Messages retain attention markers and unread filtering and open into bounded detail without leaving the overlay. The overlay refreshes while visible and distinguishes true empty timelines from filtered-empty results; filtered-empty copy points back to Enter on the active tab without moving focus.
+
+## Recipe Document
+
+`Recipe` is the first and initially selected tab. It reads only persisted owned-run evidence from `run.json`: recipe identity and source, the authored recipe context captured at launch, the resolved executable template and runtime values, composition records, model policy, mailbox, artifacts, notification/retirement policy, and bounded read diagnostics. It never follows a mutable external recipe path while the Inspector is open.
+
+The document renders as labeled, indented terminal text rather than raw JSON and scrolls as one level. Secret-bearing values receive the same redaction as turn evidence. Recipe context lives here rather than repeating inside every Turn.
 
 ## Communication Timeline
 
@@ -64,9 +73,9 @@ Each turn groups:
 - Tool calls in assistant source order;
 - Tool results correlated by `toolCallId`, regardless of completion order.
 
-Enter/→ opens the selected turn as structured evidence inside the overlay. A compact `Subagent N` heading with an optional meaningful role leads into meaning-first sections: User, persisted Thinking, Assistant, Tools, Execution, and Diagnostics. A final Provenance section retains session/prompt paths, truncation state, and recipe context without making transport metadata the first screen. Generic internal stages such as `command` and `subagent` stay hidden; technical `command-NNN` provenance remains available through the session and prompt paths without producing a redundant `Command / command-NNN (command)` block. Secondary qualifiers use parentheses rather than centered-dot separators. Long text, paths, and structured values wrap to subsequent terminal rows instead of receiving visual ellipsis; lines that already fit the available inner width remain intact, leading indentation is reserved before wrapping long unbroken paths so it cannot become a whitespace-only row, and every section plus all of its explicit or wrapped continuations keeps one background stripe. Blank-only source lines and trailing line breaks are omitted from both evidence and readable rendering. Section boundaries change the stripe without inserting separator rows, so the next heading follows the previous value immediately. ↑/↓ scrolls the resulting visual-row document while the footer remains visible. Source evidence remains bounded by the persisted session reader, but the detail view no longer truncates that retained evidence to one terminal row per field.
+Enter/→ opens the selected turn as one structured, scrollable detail document inside the overlay. A compact `Subagent N` heading with an optional meaningful role leads into meaning-first sections: User, persisted Thinking, Assistant, Tools, Execution, and Diagnostics. A final Provenance section retains session/prompt paths and truncation state without duplicating recipe context from the Recipe tab. Generic internal stages such as `command` and `subagent` stay hidden; technical `command-NNN` provenance remains available through the session and prompt paths without producing a redundant `Command / command-NNN (command)` block. Secondary qualifiers use parentheses rather than centered-dot separators. Long text, paths, and structured values wrap to subsequent terminal rows instead of receiving visual ellipsis; lines that already fit the available inner width remain intact, leading indentation is reserved before wrapping long unbroken paths so it cannot become a whitespace-only row, and every section plus all of its explicit or wrapped continuations keeps one background stripe. Blank-only source lines and trailing line breaks are omitted from both evidence and readable rendering. Section boundaries change the stripe without inserting separator rows, so the next heading follows the previous value immediately. ↑/↓ scrolls the resulting visual-row document while the footer remains visible. Source evidence remains bounded by the persisted session reader, but the detail view no longer truncates that retained evidence to one terminal row per field.
 
-Enter/→ once more opens a plain readable transcript of the same turn. This second level removes provenance, model, usage, ids, and other evidence metadata, retaining only User, Thinking when persisted, Assistant, Tool input/result, and Error content in execution order. When Pi persisted the user prompt as one `<file name="…">…</file>` transport wrapper, readable mode removes that wrapper and shows only its actual prompt text. Structured values render as indented key/value text rather than one-line JSON. Escape/← returns from transcript to evidence detail, then from evidence detail to the Turns list.
+The detail view removes a single enclosing `<file name="…">…</file>` prompt transport wrapper and renders structured values as indented key/value text rather than one-line JSON. It has no nested transcript mode: Escape/← returns directly to the Turns list.
 
 ## Evidence And Privacy Boundary
 

package/docs/async-runs.md

@@ -246,7 +246,7 @@ Use coordinator/session-bound messages for completion and decision points, not f
 
 An async run belongs to the current user, cwd, and launching agent session at start time. Send, cancellation, and force-kill target only the recorded runner pid when command line and cwd still match the recorded owner data. Stale pid reuse must fail closed.
 
-On Unix-like systems, `control.kill` signals the runner process group when available, then falls back to the runner pid. On native Windows, `control.kill` uses Windows process-tree termination through the platform adapter. The runner starts command-template children in the owned process tree, so long-running descendants such as audio players should stop with the run instead of becoming orphaned background processes. A recipe may manage a true detached daemon, but then daemon ownership is recipe-local: the script must persist and verify a pid or service handle, expose status/stop behavior, and bridge `control.kill` to daemon cleanup. The generic runner does not scan for or guess detached services. After the process exits, status reflects the operator action as `killed` instead of a generic `exited`. Programmatic `cancelRun()` remains an internal lifecycle helper for retirement and tests, but it is not a documented actor-message action.
+Immediately before signaling, control revalidates the persisted process identity a second time inside the state-directory lifecycle lock. On Unix-like systems, `control.kill` signals the runner process group when available and falls back to the exact runner pid only when group signaling returns `ESRCH` and one additional identity revalidation still matches; authorization and permission errors fail closed without fallback. On native Windows, `control.kill` uses Windows process-tree termination through the platform adapter. The runner starts command-template children in the owned process tree, so long-running descendants such as audio players should stop with the run instead of becoming orphaned background processes. A recipe may manage a true detached daemon, but then daemon ownership is recipe-local: the script must persist and verify a pid or service handle, expose status/stop behavior, and bridge `control.kill` to daemon cleanup. The generic runner does not scan for or guess detached services. After the process exits, status reflects the operator action as `killed` instead of a generic `exited`. Programmatic `cancelRun()` remains an internal lifecycle helper for retirement and tests, but it is not a documented actor-message action. Node does not expose one portable identity-stable process-group handle across Linux, macOS, and Windows, so a runner can theoretically exit and its PID/PGID can be reused after the final identity read but before the OS signal call. Generation fencing, lifecycle serialization, immediate revalidation, and error-specific fallback minimize this residual platform window; docs and evidence must not claim pidfd/handle-level atomic signaling where the host cannot provide it.
 
 State is append-only where practical. Final result writes should be atomic. Recipe-local control endpoints and actor-message logs may live in the state dir. pi-actors core owns the generic run-local message adapter and runtime attention policy; command and message vocabularies belong to the recipe/script.
 
@@ -270,6 +270,14 @@ Rules:
 - The `runs` state root is preserved by startup cleanup; run lifecycle cleanup must be explicit and run-aware.
 - State that must survive restarts belongs in the agent root, not in `tmp`.
 
+## Parent Session Teardown
+
+Async actors may outlive individual agent turns. Every Pi `session_shutdown` reason (`quit`, `reload`, `new`, `resume`, or `fork`) scans persisted run state and attempts teardown for discovered readable `running` runs whose exact `ownerId` matches the retiring coordinator session. Each new run persists immutable `run_instance_id`; teardown carries expected owner/generation into canonical `control.kill`, which compares both while holding the state-directory lifecycle lock shared with restart. Missing ownership or generation fails closed; terminal, ambiguous, changed-generation, and other-session runs remain untouched. Teardown never signals processes directly.
+
+Teardown remains idempotent and best-effort across discovered siblings: one signal, process-proof, or evidence-write failure does not block later candidates. A `run.parent_teardown` event is written only while the selected generation still owns that state directory; replacement generations cannot receive stale teardown evidence. Successful kills retain `run.kill`, terminal progress, process-identity fencing, and handled-marker evidence.
+
+This boundary intentionally does not run at ordinary `agent_end`. Teardown uses unbounded directory discovery rather than the ordinary index depth cap. Unreadable directories and corrupt run state become explicit failures, and every invocation persists a bounded summary under `<run-root>/teardown/`; shutdown warnings include that path when failures remain. Actors launched by descendant Pi sessions deliberately remain outside the exact-owner contract and rely on their own session shutdown hook. A hard OS/process kill can still prevent either hook; use the persisted summary plus OS-level/manual recovery for an orphan that a replacement session cannot control safely.
+
 ## Ambient Observability
 
 Interactive sessions expose compact activity with minimal screen cost: