@llblab/pi-actors 0.39.0 → 0.40.1

package/dist/scripts/async-runner.mjs

@@ -8,8 +8,14 @@
  * chasing a one-off lib entrypoint domain.
  */
 
-import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  statSync,
+} from "node:fs";
+import { dirname, join, relative } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 function packageRoot() {
@@ -30,7 +36,8 @@ const { appendRecipeContextToPiArgs, materializePiPrintPromptArg } =
 const { buildReviewPreflightDiagnostic, formatReviewPreflightDiagnostic } =
   await importRuntimeModule("preflight-diagnostics");
 const { execCommandTemplate } = await importRuntimeModule("command-templates");
-const { executeRegisteredTool } = await importRuntimeModule("execution");
+const { applyOutputAcceptancePolicy, executeRegisteredTool } =
+  await importRuntimeModule("execution");
 const { writeJsonAtomic } = await importRuntimeModule("file-state");
 
 function quoteCommandDetailPart(value) {
@@ -43,6 +50,17 @@ function formatCommandDetail(command, args) {
   return [command, ...args].map(quoteCommandDetailPart).join(" ");
 }
 
+function captureDetails(result) {
+  return {
+    ...(typeof result.stdoutBytes === "number" ? { stdout_bytes: result.stdoutBytes } : {}),
+    ...(typeof result.stderrBytes === "number" ? { stderr_bytes: result.stderrBytes } : {}),
+    ...(result.stdoutFile ? { stdout_file: result.stdoutFile } : {}),
+    ...(result.stderrFile ? { stderr_file: result.stderrFile } : {}),
+    ...(result.stdoutTruncated ? { stdout_truncated: true } : {}),
+    ...(result.stderrTruncated ? { stderr_truncated: true } : {}),
+  };
+}
+
 function summarizeCommandDetail(commandDetail) {
   return commandDetail.length > 160
     ? `${commandDetail.slice(0, 157)}...`
@@ -59,6 +77,7 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
   const outboxPath = join(stateDir, "outbox.jsonl");
   const stdoutPath = join(stateDir, "stdout.log");
   const stderrPath = join(stateDir, "stderr.log");
+  const evidencePath = join(stateDir, "review-evidence.json");
   const meta = JSON.parse(readFileSync(runPath, "utf8"));
 
   function event(name, data = {}) {
@@ -87,7 +106,171 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
   let activeSubagents = 0;
   let completedSubagents = 0;
   let promptCounter = 0;
+  let captureCounter = 0;
   const subagentFailures = [];
+  const evidenceRecords = [];
+  const stageOccurrences = new Map();
+  let reportEvidence;
+
+  function writeEvidenceManifest(status) {
+    writeJsonAtomic(evidencePath, {
+      version: 1,
+      run: meta.run,
+      status,
+      ...(meta.model_policy ? { model_policy: meta.model_policy } : {}),
+      commands: [...evidenceRecords].sort((left, right) =>
+        left.id.localeCompare(right.id)
+      ),
+      ...(reportEvidence ? { report_evidence: reportEvidence } : {}),
+      updated_at: new Date().toISOString(),
+    });
+  }
+
+  function commandEvidenceStartRecord({
+    commandDetail,
+    commandId,
+    materialized,
+    options,
+    stage,
+    occurrence,
+  }) {
+    const recipeContext = options?.actorRecipeContext;
+    return {
+      id: commandId,
+      stage,
+      occurrence,
+      status: "running",
+      started_at: new Date().toISOString(),
+      ...(options?.evidenceContext?.label
+        ? { label: options.evidenceContext.label }
+        : {}),
+      ...(options?.evidenceContext?.repeatIndex !== undefined
+        ? { branch_index: options.evidenceContext.repeatIndex }
+        : {}),
+      ...(recipeContext ? { recipe_context: recipeContext } : {}),
+      command: commandDetail,
+      ...(materialized.promptFile
+        ? { prompt_file: relative(stateDir, materialized.promptFile) }
+        : {}),
+      ...(materialized.promptBytes
+        ? { prompt_bytes: materialized.promptBytes }
+        : {}),
+      attempts: [],
+      semantic_acceptance:
+        options?.evidenceContext?.acceptOutput === "review_evidence" ||
+        stage === "preflight"
+          ? "pending"
+          : "not_required",
+    };
+  }
+
+  function commandEvidenceRecord({
+    captureDir,
+    commandDetail,
+    commandId,
+    materialized,
+    options,
+    result,
+    rawExitCode,
+    stage,
+    occurrence,
+    startedAt,
+  }) {
+    const recipeContext = options?.actorRecipeContext;
+    const attempts = [];
+    const maxAttempts = Math.max(1, options?.retry || 1);
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+      const attemptDir = join(
+        captureDir,
+        `attempt-${String(attempt).padStart(3, "0")}`,
+      );
+      const stdoutFile = join(attemptDir, "stdout.log");
+      const stderrFile = join(attemptDir, "stderr.log");
+      if (!existsSync(stdoutFile) && !existsSync(stderrFile)) continue;
+      attempts.push({
+        attempt,
+        stdout: {
+          path: relative(stateDir, stdoutFile),
+          bytes: existsSync(stdoutFile) ? statSync(stdoutFile).size : 0,
+        },
+        stderr: {
+          path: relative(stateDir, stderrFile),
+          bytes: existsSync(stderrFile) ? statSync(stderrFile).size : 0,
+        },
+      });
+    }
+    const expectedReviewMarker =
+      options?.evidenceContext?.acceptOutput === "review_evidence";
+    const expectedPreflightMarker = stage === "preflight";
+    const semanticStdout = result.stdoutTruncated && result.stdoutFile && existsSync(result.stdoutFile)
+      ? readFileSync(result.stdoutFile, "utf8")
+      : result.stdout;
+    const firstNonWhitespaceLine = semanticStdout
+      .split(/\r?\n/)
+      .find((line) => line.trim().length > 0);
+    const markerAccepted = expectedReviewMarker
+      ? firstNonWhitespaceLine?.trim() === "ACTOR_REVIEW_RESULT"
+      : expectedPreflightMarker
+        ? result.stdout.trimStart().startsWith("ACTOR_PREFLIGHT_OK")
+        : undefined;
+    return {
+      id: commandId,
+      stage,
+      occurrence,
+      status: result.code === 0 ? "done" : "failed",
+      started_at: startedAt,
+      completed_at: new Date().toISOString(),
+      ...(options?.evidenceContext?.label
+        ? { label: options.evidenceContext.label }
+        : {}),
+      ...(options?.evidenceContext?.repeatIndex !== undefined
+        ? { branch_index: options.evidenceContext.repeatIndex }
+        : {}),
+      ...(recipeContext ? { recipe_context: recipeContext } : {}),
+      command: commandDetail,
+      ...(materialized.promptFile
+        ? { prompt_file: relative(stateDir, materialized.promptFile) }
+        : {}),
+      ...(materialized.promptBytes
+        ? { prompt_bytes: materialized.promptBytes }
+        : {}),
+      attempts,
+      exit_code: rawExitCode ?? result.code,
+      effective_exit_code: result.code,
+      killed: result.killed,
+      stdout_bytes: result.stdoutBytes ?? Buffer.byteLength(result.stdout),
+      stderr_bytes: result.stderrBytes ?? Buffer.byteLength(result.stderr),
+      stdout_truncated: result.stdoutTruncated === true,
+      stderr_truncated: result.stderrTruncated === true,
+      semantic_acceptance:
+        markerAccepted === undefined
+          ? "not_required"
+          : markerAccepted && result.code === 0
+            ? "accepted"
+            : "rejected",
+    };
+  }
+
+  function auditReviewReport(text) {
+    const required = evidenceRecords
+      .filter((record) =>
+        ["reviewer", "verifier", "merger", "judge"].includes(record.stage)
+      )
+      .map((record) => `review-evidence.json#${record.id}`);
+    if (required.length === 0) return undefined;
+    const cited = [...new Set(
+      text.match(/review-evidence\.json#command-\d{3}/g) || [],
+    )].sort();
+    const missing = required.filter((reference) => !cited.includes(reference));
+    const claimsComplete = /\bStatus\b[\s:*#_-]{0,40}\bcomplete\b/i.test(text);
+    return {
+      required,
+      cited,
+      missing,
+      claims_complete: claimsComplete,
+      complete_allowed: missing.length === 0,
+    };
+  }
 
   function getCommandDoneDelivery(result) {
     return result.code !== 0 || activeSubagents > 0 ? "followup" : "log";
@@ -131,15 +314,64 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
     );
     const execArgs = materialized.args;
     const commandDetail = formatCommandDetail(command, execArgs);
+    captureCounter += 1;
+    const commandId = `command-${String(captureCounter).padStart(3, "0")}`;
+    const stage =
+      options?.actorRecipeContext?.alias ||
+      options?.actorRecipeContext?.name ||
+      "command";
+    const occurrence = (stageOccurrences.get(stage) || 0) + 1;
+    stageOccurrences.set(stage, occurrence);
+    if (
+      materialized.promptFile &&
+      ["verifier", "merger", "judge", "normalizer"].includes(stage)
+    ) {
+      const references = evidenceRecords
+        .filter((record) =>
+          ["reviewer", "verifier", "merger", "judge"].includes(record.stage)
+        )
+        .map((record) => `ACTOR_EVIDENCE_REF: review-evidence.json#${record.id}`);
+      if (references.length > 0) {
+        appendFileSync(
+          materialized.promptFile,
+          `\n\nRetained actor evidence references available for citation:\n${references.join("\n")}\n`,
+        );
+        materialized.promptBytes = statSync(materialized.promptFile).size;
+      }
+    }
     activeSubagents += 1;
+    const evidenceIndex = evidenceRecords.length;
+    const startedEvidence = commandEvidenceStartRecord({
+      commandDetail,
+      commandId,
+      materialized,
+      options,
+      stage,
+      occurrence,
+    });
+    evidenceRecords.push(startedEvidence);
+    writeEvidenceManifest("running");
     event("command.start", {
       activeSubagents,
+      command_id: commandId,
       command: commandDetail,
       ...(materialized.promptFile ? { prompt_file: materialized.promptFile } : {}),
       ...(materialized.promptBytes ? { prompt_bytes: materialized.promptBytes } : {}),
     });
     progressRunning();
-    let result = await execCommandTemplate(command, execArgs, options);
+    const captureDir = join(stateDir, "captures", commandId);
+    const rawResult = await execCommandTemplate(command, execArgs, {
+      ...options,
+      captureDir,
+    });
+    let result = await applyOutputAcceptancePolicy(
+      rawResult,
+      options?.evidenceContext?.acceptOutput,
+    );
+    result = {
+      ...result,
+      evidenceRef: `review-evidence.json#${commandId}`,
+    };
     const preflightDiagnostic = result.code !== 0
       ? buildReviewPreflightDiagnostic({
           args: execArgs,
@@ -160,6 +392,19 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
         ].filter(Boolean).join("\n"),
       };
     }
+    evidenceRecords[evidenceIndex] = commandEvidenceRecord({
+      captureDir,
+      commandDetail,
+      commandId,
+      materialized,
+      options,
+      result,
+      rawExitCode: rawResult.code,
+      stage,
+      occurrence,
+      startedAt: startedEvidence.started_at,
+    });
+    writeEvidenceManifest("running");
     activeSubagents = Math.max(0, activeSubagents - 1);
     completedSubagents += 1;
     if (result.code !== 0) {
@@ -167,15 +412,18 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
         code: result.code,
         command: commandDetail,
         killed: result.killed,
+        ...captureDetails(result),
         ...(materialized.promptFile ? { prompt_file: materialized.promptFile } : {}),
         ...(preflightDiagnostic ? { preflight: preflightDiagnostic } : {}),
       });
     }
     event("command.done", {
       activeSubagents,
+      command_id: commandId,
       code: result.code,
       command: commandDetail,
       killed: result.killed,
+      ...captureDetails(result),
       ...(materialized.promptFile ? { prompt_file: materialized.promptFile } : {}),
       ...(materialized.promptBytes ? { prompt_bytes: materialized.promptBytes } : {}),
       ...(preflightDiagnostic ? { preflight: preflightDiagnostic } : {}),
@@ -186,10 +434,12 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       {
         activeSubagents,
         ...(meta.artifacts ? { artifacts: meta.artifacts } : {}),
-        run_files: [stdoutPath, stderrPath, resultPath, eventsPath, outboxPath],
+        run_files: [stdoutPath, stderrPath, resultPath, eventsPath, outboxPath, evidencePath],
+        command_id: commandId,
         code: result.code,
         command: commandDetail,
         killed: result.killed,
+        ...captureDetails(result),
         ...(materialized.promptFile ? { prompt_file: materialized.promptFile } : {}),
         ...(materialized.promptBytes ? { prompt_bytes: materialized.promptBytes } : {}),
         ...(preflightDiagnostic ? { preflight: preflightDiagnostic } : {}),
@@ -218,6 +468,20 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
     );
     const text = result.content?.[0]?.text || "";
     appendFileSync(stdoutPath, text);
+    reportEvidence = auditReviewReport(text);
+    if (
+      reportEvidence?.claims_complete &&
+      reportEvidence.complete_allowed !== true
+    ) {
+      const error = new Error(
+        `review report evidence incomplete: missing ${reportEvidence.missing.join(", ")}`,
+      );
+      error.details = {
+        code: 65,
+        failureReason: "incomplete review report evidence",
+      };
+      throw error;
+    }
     writeJsonAtomic(resultPath, {
       code: result.details.code,
       command: result.details.command,
@@ -226,6 +490,7 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       truncated: result.details.truncated,
       completedAt: new Date().toISOString(),
     });
+    writeEvidenceManifest("done");
     progress("done", {
       completed: 1,
       failures: result.details.nonCriticalFailures || [],
@@ -245,11 +510,14 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       ...(details?.softQuorum ? { soft_quorum: details.softQuorum } : {}),
       completedAt: new Date().toISOString(),
     });
+    writeEvidenceManifest("failed");
     progress("failed", {
       completed: 0,
       failures: Array.isArray(details?.branches) && details.branches.length > 0
         ? details.branches
-        : [{ message }],
+        : subagentFailures.length > 0
+          ? subagentFailures
+          : [{ message }],
       ...(details?.failureReason ? { failureReason: details.failureReason } : {}),
     });
     event("run.failed", {

package/dist/scripts/build-dist.mjs

@@ -9,7 +9,13 @@
  */
 
 import { spawnSync } from "node:child_process";
-import { cpSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import {
+  cpSync,
+  mkdirSync,
+  readdirSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { join } from "node:path";
 
 function run(command, args) {
@@ -22,6 +28,13 @@ mkdirSync("dist", { recursive: true });
 
 run("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", "recipes", "fixtures", "skills"]) {
   cpSync(dir, join("dist", dir), { recursive: true });
 }

package/dist/skills/actors/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: actors
-description: Required practical guide for non-trivial pi-actors use. Read before using or changing spawn, message, inspect, actor runs, tools, recipes, command templates, async lifecycle, mailboxes, artifacts, and local orchestration mechanics.
+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.39.0
+  version: 0.40.1
 ---
 
 # Actors (pi-actors)
@@ -53,6 +53,8 @@ Actor-mode trigger: if work may outlive this turn, needs steering/follow-up/arti
 
 Use for long work, background services, subagents, fanout, pipelines, and reusable recipes.
 
+Before a parallel launch, the coordinator should verify five things once: each actor owns a disjoint mutation scope, every run has a stable id, each durable result has an artifact path, every command template respects shell-free argv execution, and completion can return through follow-up delivery without polling. For multiple delegated implementation or review actors, also load the bundled Swarm skill before choosing decomposition, locks, or quorum shape.
+
 ```json
 {
   "as": "run:repo-health",
@@ -64,10 +66,12 @@ Use for long work, background services, subagents, fanout, pipelines, and reusab
 
 Rules:
 
+- Command-template strings execute directly without a shell. Operators such as `&&`, `||`, pipes, redirects, and `cd` remain literal argv unless an explicit trusted shell is the executable. Prefer absolute paths or template arrays for sequencing; put non-trivial shell behavior in a reviewed script.
 - Use `file`/`recipe` for saved recipes; bare names resolve under `~/.pi/agent/recipes`.
 - Use inline `template` for one-off experiments; promote useful repeats to recipes.
 - When a successful actor follow-up suggests persistence, decide whether the pattern deserves durable tool memory; call `register_tool` yourself only when the evidence is strong, and ask before writing the user recipe root.
 - Use stable `as` names when you will inspect or message the actor later.
+- Public run state is runtime-owned; do not pass custom `state_dir` paths. This keeps `run:<id>` addressability and retention on one boundary.
 - `async: true` on the recipe is the detached run switch.
 
 ### `message` — send a typed envelope
@@ -90,6 +94,7 @@ 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.
 
 Check `inspect view=mailbox` before domain-specific messages.
 
@@ -116,8 +121,8 @@ Views:
 - Advanced `contacts`: roster-derived direct-message targets without full roster metadata.
 - Advanced `previews`: TUI-ready bounded group-message previews with timestamp/from/to/type/summary/body_preview.
 - `mailbox`: declared accepts/emits contract for runs; queued direct branch inbox messages for `branch:<run>/<branch>` with `id`, status, route/type, and queue/handling timestamps.
-- `files`: run state directory file list.
-- `artifacts`: declared artifact paths/status.
+- `files`: run state file summary plus a `lines`-bounded `review-evidence.json` manifest when present, including total/truncated command counts and stage capture paths.
+- `artifacts`: declared artifact paths/status plus the same bounded owned review-evidence manifest when present.
 - `recipes` target: registry summary for active, shadowed, invalid, disabled, and diagnostic recipe entries.
 
 Actor inspector commands:
@@ -128,7 +133,7 @@ Actor inspector commands:
 
 The table is compact and optimistic by default: bounded body previews, capped noisy room rows, branch-local inbox previews, stable event ids in selected-message details, and an inline roster summary in the form `name/role` that wraps only when needed. Use `unread` for queued branch inbox work and `branch <name>` / `current-branch <name>` for one branch's room/direct/inbox traffic. Rows with `metadata.requires_response=true` show a `!` attention marker. `/actors-inspect <number>` marks that row read for the current session filter. Active roster members use the target color; members that sent `actor.leave` stay visible as inactive/muted participants from the current run. Actor display names come from `actor.join` bodies (`display`) or branch addresses, keeping debugger output plain and name-driven.
 
-Let terminal notifications arrive; avoid sleep-poll loops except during diagnosis.
+Let terminal notifications arrive. They queue through Pi's follow-up delivery mode, so a busy coordinator finishes its current work before receiving concurrently completed actor results; the host's `followUpMode` controls whether queued results arrive together or one at a time. When a deferred actor result gates the next step, wait for that terminal follow-up instead of scheduling continuation loops, repeatedly inspecting, or mutating the actor's reviewed scope. Idle coordinators still start a normal turn through `triggerTurn: true`. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue or stuck run.
 
 ## Runtime Communication Rules
 
@@ -154,11 +159,13 @@ Controls:
 - `args`, `defaults`: public placeholder declarations and defaults.
 - `parallel: true`: fanout child nodes.
 - `when`: conditional execution.
+- `accept_output: review_evidence`: fail closed unless the exact first non-whitespace stdout line is `ACTOR_REVIEW_RESULT`; marker prefixes are rejected and rejected stdout remains diagnostic evidence.
 - `timeout`, `delay`, `retry`: timing and retry controls; string placeholders are allowed where supported.
 - `failure`: `continue`, `branch`, or `root` propagation.
 - `recover`: cleanup between retry attempts.
 - `repeat`: repeated node expansion.
 - `output`: output behavior selection.
+- Command stdout/stderr use bounded tails plus complete spill files; tool/run diagnostics expose byte counts, truncation, and spill paths, while pipelines fail with `incomplete pipeline stdin` rather than consuming a partial tail.
 
 Placeholders:
 
@@ -199,7 +206,7 @@ Rules:
 7. Declare `mailbox` for actors that accept or emit meaningful messages.
 8. Declare `artifacts` for durable outputs the coordinator should inspect.
 9. File-backed recipe identity comes from the filename basename; legacy top-level `name` fields are ignored by loaders.
-10. File-backed async recipes pass child `pi -p` actors a bounded JSONL recipe context bundle by default: raw entry/import recipe records, derived `name`, import path/alias, and `"you_are_here": true` on the launching recipe node. The runner materializes child prompts under `prompts/command-NNN.md` and invokes Pi with `@file` args so large prompts and recipe context stay inspectable and argv-safe. Set `"actor_context": false` or `"off"` to suppress recipe context for minimal prompts.
+10. File-backed async recipes pass child `pi -p` actors a bounded JSONL recipe context bundle by default: raw entry/import recipe records, derived `name`, import path/alias, and `"you_are_here": true` on the launching recipe node. The runner collapses all natural-language positional fragments into one prompt under `prompts/command-NNN.md`, keeps intentional `@file` attachments separate, and invokes Pi with one authoritative prompt-file arg so large prompts and recipe context stay inspectable and argv-safe. Set `"actor_context": false` or `"off"` to suppress recipe context for minimal prompts.
 11. Keep packaged recipes generic: no machine-local paths, no private companion identities, no project-specific defaults unless the recipe is explicitly project-specific.
 12. Do not ship concrete model-version defaults in packaged recipes. For review-oriented subagent/lens recipes, default model/thinking args through `{current_model}` and `{current_thinking}` so they inherit the selected Pi session policy; keep `model`, `models`, `thinking`, and stage-specific model args explicit so callers can override policy at launch.
 
@@ -219,7 +226,7 @@ Muscle-memory lens: pi-actors has two durable executable-memory layers.
 
 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.
 
-Usage lens: user recipes may carry extension-maintained launch metadata such as `usage.calls` and `usage.last_called`. The extension increments the counter when it starts that concrete recipe; 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 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.
 
 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.
 
@@ -284,7 +291,7 @@ The user recipe root is the default tool set by location. It accepts canonical J
 
 Use packaged recipes by name with `spawn file=<name>` for async actors, or register/call them as tools when repeated use deserves a stable shortcut.
 
-Packaged review recipes are directly spawnable. Use `spawn file="pipeline-review-readiness" values={...}` for readiness review or `spawn file="subagent-review" values={...}` for one reviewer; pass model/thinking/tool policy through values, then inspect the run. Review coordinators preflight stage models before fanout; `ACTOR_PREFLIGHT_FAILED` diagnostics identify the failed stage, selected policy, provider error class, prompt file, and override args. Quorum-aware review fanout exposes `subagent_ttl_ms`, `reviewer_concurrency`, `min_successful_reviewers`, and `merge_policy`; partial reviewer evidence is preserved and marked `complete`, `degraded`, or `insufficient_data`. Run status/progress exposes `model_policy` so inherited vs explicit model/thinking choices remain visible. Do not recreate their script commands, call packaged scripts directly, or create wrapper recipes just to launch the maintained recipe.
+Packaged review recipes are directly spawnable. Use `spawn file="pipeline-review-readiness" values={...}` for readiness review or `spawn file="subagent-review" values={...}` for one reviewer; pass model/thinking/tool policy through values, then inspect the run. Review coordinators preflight stage models before fanout; `ACTOR_PREFLIGHT_FAILED` diagnostics identify the failed stage, selected policy, provider error class, prompt file, and override args. Review stages require the `ACTOR_REVIEW_RESULT` evidence marker, so format acknowledgements and input requests fail closed before satisfying quorum or flowing downstream; rejected stdout remains in branch diagnostics. Quorum-aware review fanout exposes `subagent_ttl_ms`, `reviewer_concurrency`, `min_successful_reviewers`, and `merge_policy`; partial reviewer evidence is preserved and marked `complete`, `degraded`, or `insufficient_data`. Run status/progress exposes `model_policy` so inherited vs explicit model/thinking choices remain visible. Do not recreate their script commands, call packaged scripts directly, or create wrapper recipes just to launch the maintained recipe.
 
 - [`pipeline-room-swarm`](../../recipes/pipeline-room-swarm.json): room-visible swarm coordination with roles, rounds, optional locker, artifact synthesis, and `subagent_ttl_ms` for hard participant budgets.
 - [`pipeline-repo-health`](../../recipes/pipeline-repo-health.json): git/doc/validation evidence → normalized repository health report.

package/dist/skills/swarm/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: swarm
-description: Subagent orchestration with scoped locks and quorum consensus. Use for multi-model review, parallel scoped work, delegated audit, and coordinated subagent execution.
+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.39.0
+  version: 0.40.1
 ---
 
 # Swarm
@@ -13,6 +13,8 @@ Subagent orchestration: delegated review, quorum consensus, scoped locks, clean-
 
 Run subagents safely and predictably through reusable orchestration contracts.
 
+Activation rule: load this skill before launching multiple independent actors or subagents, even when the work is creative artifact generation rather than code review. The coordinator owns decomposition, disjoint scopes, launch correctness, result integration, and final validation; participants may choose local content or implementation details independently inside their assigned boundaries.
+
 Swarm is independent. It must not require concrete sibling skill names, private repositories, local model aliases, or a specific tool registry layout. Local agents may bind the contracts to their own tools, command templates, model names, and review protocols.
 
 Maintain this skill as a living orchestration standard. When real swarm work exposes better decomposition shapes, lock etiquette, quorum rules, checkpoint semantics, failure modes, or trade-offs, fold those lessons back here as durable guidance instead of leaving them only in one-off transcripts or backlog notes.

package/docs/actor-messages.md

@@ -186,7 +186,7 @@ Recipes can declare their conversational surface:
 }
 ```
 
-`spawn` creates detached `run:<id>` actors from a recipe file/name or inline command template. Spawn metadata may include explicit `state_dir` and named `artifacts` for terminal follow-ups and inspection. Room rosters are durable but burst-safe: repeated messages that only update `last_seen` may be coalesced briefly, while semantic roster changes such as role/status/display still write immediately.
+`spawn` creates detached `run:<id>` actors from a recipe file/name or inline command template. Public spawn state directories are runtime-owned so every actor remains addressable and retention cannot target a caller-selected directory; spawn metadata may include named `artifacts` for terminal follow-ups and inspection. Room rosters are durable but burst-safe: repeated messages that only update `last_seen` may be coalesced briefly, while semantic roster changes such as role/status/display still write immediately.
 
 ## Inspect
 

package/docs/async-runs.md

@@ -81,19 +81,26 @@ Use `run_id` on async recipe tools or `as: "run:<id>"` on `spawn` when the calle
 - `{default_room}`: default room address, e.g. `room:review`.
 - `{communication_file}`: compact communication snapshot path.
 
+Review commands that require semantic evidence apply marker acceptance before command completion accounting. Rejected code-zero output is reported consistently as a failed command in events, progress, evidence, and outbox delivery; it cannot emit a success-level completion notification. Evidence records are written before command launch and lifecycle cancellation or kill finalizes any running record with its interrupted state, effective exit code, and attempt capture paths. Async attempt stdout/stderr files exist from attempt start, so even small partial streams remain auditable when a command never returns.
+
 ## State Files
 
 Use ordinary files under the extension temp directory so status tools stay simple and inspectable:
 
-- `run.json`: pid, optional source metadata (`launch_source`, `tool`, `recipe`, `recipe_file`), command-template config, cwd, coordinator owner id, values, named `artifacts`, mailbox metadata, created time, and state dir.
+- `.pi-actors-run-state.json`: runtime ownership marker binding the run id to the canonical state directory; launch reuse and destructive retention fail closed when it is absent, invalid, mismatched, or reached through a symlink alias. State reuse also fails closed whenever the persisted process identity mismatches a still-live pid, preventing corrupted metadata from admitting overlapping runners.
+- `run.json`: pid, cross-platform `process_identity` proof (start time, command, and canonical cwd where available), optional source metadata (`launch_source`, `tool`, `recipe`, `recipe_file`), command-template config, cwd, coordinator owner id, values, named `artifacts`, mailbox metadata, created time, and state dir. Existing launch cwd aliases are resolved through native `realpath` before proof matching, so symlinked working directories do not degrade control to `unsupported_proof`.
 - `communication.json`: compact actor communication snapshot with self/root/parent, default-room, member, and contact hints for room-aware scripts and agents.
 - `progress.json`: phase, active command count, completed count, failures, updated time, and optional `model_policy` provenance for inherited/explicit model and thinking values.
 - `events.jsonl`: append-only implementation lifecycle log.
 - `outbox.jsonl`: implementation storage for actor-message envelopes used by `inspect view=messages`, coordinator notifications, or follow-up context. Coordinator follow-ups preserve bounded `body` previews plus message metadata for decision points.
 - `stdout.log` and `stderr.log`: detached process output.
-- `prompts/command-NNN.md`: state-owned prompt files materialized for child `pi -p` commands so long prompts and appended recipe context travel as `@file` arguments instead of fragile inline argv text.
+- `prompts/command-NNN.md`: state-owned prompt files that collapse child `pi -p` natural-language positional fragments and appended recipe context into one authoritative `@file` prompt while preserving intentional file/image arguments.
+- `captures/command-NNN/attempt-NNN/{stdout,stderr}.log`: complete byte-exact command streams, retained even below the bounded in-memory capture limit and separated across retries.
+- `review-evidence.json`: stable command/stage manifest linking prompts, repeated branches, capture attempts, byte counts, exit state, semantic marker acceptance, recipe context, and model/thinking policy; terminal status aligns with the run. Review pipelines inject prior-stage `ACTOR_EVIDENCE_REF` values into downstream prompts, record cited/missing report sources, and fail closed if a normalized report claims `complete` without every required reviewer, verifier, merger, and judge reference.
 - `result.json`: final code, killed flag, output selector, and optional full-output path.
 
+Public `spawn` always uses the runtime-owned run root; caller-selected state directories are rejected so `run:<id>` addressing and retention share one boundary. Internal adapters may still supply isolated state directories for deterministic fixtures, but those are not part of the public actor contract. Every launched runner also persists a process identity proof and revalidates it for status, state reuse, message delivery, cancellation, kill, and retirement; dead pids, reused-pid owner mismatches, and unavailable platform proofs remain distinct diagnostics and destructive controls fail closed.
+
 For pi-actors, actor run state defaults to:
 
 ```text
@@ -110,6 +117,8 @@ State files use this shape:
 ~/.pi/agent/tmp/pi-actors/runs/<run>/outbox.jsonl
 ~/.pi/agent/tmp/pi-actors/runs/<run>/stdout.log
 ~/.pi/agent/tmp/pi-actors/runs/<run>/stderr.log
+~/.pi/agent/tmp/pi-actors/runs/<run>/review-evidence.json
+~/.pi/agent/tmp/pi-actors/runs/<run>/captures/command-NNN/attempt-NNN/stdout.log
 ~/.pi/agent/tmp/pi-actors/runs/<run>/prompts/command-001.md
 ~/.pi/agent/tmp/pi-actors/runs/<run>/result.json
 ```
@@ -170,7 +179,7 @@ Low-level async actions map into the actor surface instead of forming a second p
 - Send/control → `message`
 - Status/tail/messages/list → `inspect`
 - Force kill → `message` with `control.kill`, with synchronous results
-- Archive/prune terminal state → `message` with `control.archive` or `control.prune`, with active runs rejected fail-closed
+- Archive/prune terminal state → `message` with `control.archive` or `control.prune`, with active runs rejected fail-closed; retained artifacts use collision-safe identity-derived filenames, preserve timestamps, skip missing optional files, and abort prune before source deletion on any copy failure
 
 Compact text is returned by default so async management does not flood agent context; use verbose inspection when the full state object is needed. List output intentionally shares one state root across music, subagents, timers, and other async work; source fields such as `tool` and `recipe` distinguish run purpose when the launcher recorded them. The run root may contain a rebuildable `index.json` with run id, state directory, owner, status, update time, and recipe/tool hints; corrupt indexes fall back to recursive scan. Registered tools are the preferred user-facing surface for reusable recipes. `control.prune` accepts `body.preserve_artifacts=true` to copy existing named artifacts beside the run root before deleting terminal state.
 
@@ -207,9 +216,9 @@ Runtime wake notifications are now modeled separately from durable queues. Messa
 
 ## Coordinator Notifications
 
-The launching coordinator should not busy-poll long-running async runs. The extension watches run state directories and delivers terminal `done`/`failed`/unhandled `killed`/`exited` transitions plus script-authored `notify`/`followup` actor messages back to the owning session. This gives the top-level async task a completion signal on the happy path while still letting recipe-local messages bubble up when scripts need finer-grained notifications. Terminal follow-ups include recipe-level named `artifacts` when declared. The generic runner also emits compact `command.done` actor messages for completed leaf commands; recipe authors declare that capability in `mailbox.emits` rather than configuring a separate delivery policy. Failures and in-flight parallel branch completions can bubble as follow-ups, while successful final leaf completions stay diagnostic to avoid flooding long sequential pipelines. Branch-level `command.done` follow-ups omit artifact manifests because the top-level terminal follow-up carries them once. Intentional `control.kill` and recipe-local stop commands stay out of follow-up context because the initiating message already returns synchronously or is handled by actor-local policy. If a follow-up asks for direction, answer with `message` rather than starting a polling loop. Use explicit `inspect` only when a delivered follow-up requests inspection, a real decision depends on state, or a suspected stuck run needs diagnosis — never merely because a timeout elapsed.
+The launching coordinator should not busy-poll long-running async runs. The extension watches run state directories and queues terminal `done`/`failed`/unhandled `killed`/`exited` transitions back to the owning session through Pi's `followUp` delivery mode with `triggerTurn: true`; a busy coordinator finishes its current work before queued actor results arrive, while an idle coordinator starts a normal turn without a racy manual idle check. Pi's configured `followUpMode` determines whether concurrently queued results arrive together or one at a time. Script-authored `notify`/`followup` actor messages still follow their declared outbox delivery policy. Terminal notifications include recipe-level named `artifacts` when declared. The generic runner also emits compact `command.done` actor messages for completed leaf commands; recipe authors declare that capability in `mailbox.emits` rather than configuring a separate delivery policy. Failures and in-flight parallel branch completions can bubble according to outbox policy, while successful final leaf completions stay diagnostic to avoid flooding long sequential pipelines. Intentional `control.kill` and recipe-local stop commands stay out of coordinator context because the initiating message already returns synchronously or is handled by actor-local policy. If a notification asks for direction, answer with `message` rather than starting a polling loop. Use explicit `inspect` only when a delivered notification requests inspection, a real decision depends on state, or a suspected stuck run needs diagnosis — never merely because a timeout elapsed.
 
-Ambient status indicators may refresh while work is active, but coordinator attention is driven from run-state changes rather than a coordinator agent loop. This lets the coordinator continue other work after `spawn`; the run signals back through lifecycle state, results, and actor messages. The ambient triangle count represents active async work units: each running async run contributes at least one triangle, and a run with multiple active parallel command/subagent branches contributes the reported active branch count. If a coordinator starts one parent run with four active parallel branches, four triangles are shown; if the same coordinator starts five independent single-branch runs, five triangles are shown.
+Ambient status indicators may refresh while work is active, but coordinator attention is driven from run-state changes rather than a coordinator agent loop. This lets the coordinator continue other work after `spawn`; the run signals back through lifecycle state, results, and actor messages. An owned terminal run without `terminal-handled.json` remains retry-eligible during same-runtime and extension/session replacement reconciliation; the marker is written only after successful follow-up delivery, and initial reconciliation does not replay historical outbox traffic. This is an at-least-once contract: a process crash after send but before marker persistence can produce a duplicate notification, while a failed send remains durably retryable. The ambient triangle count represents active async work units: each running async run contributes at least one triangle, and a run with multiple active parallel command/subagent branches contributes the reported active branch count. If a coordinator starts one parent run with four active parallel branches, four triangles are shown; if the same coordinator starts five independent single-branch runs, five triangles are shown.
 
 ## Run Actor Messages