@llblab/pi-actors 0.37.1 → 0.38.0

package/scripts/async-runner.mjs

@@ -8,7 +8,7 @@
  * chasing a one-off lib entrypoint domain.
  */
 
-import { appendFileSync, existsSync, readFileSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
@@ -25,8 +25,10 @@ async function importRuntimeModule(name) {
   );
 }
 
-const { appendRecipeContextToPiArgs } =
+const { appendRecipeContextToPiArgs, materializePiPrintPromptArg } =
   await importRuntimeModule("recipes-context");
+const { buildReviewPreflightDiagnostic, formatReviewPreflightDiagnostic } =
+  await importRuntimeModule("preflight-diagnostics");
 const { execCommandTemplate } = await importRuntimeModule("command-templates");
 const { executeRegisteredTool } = await importRuntimeModule("execution");
 const { writeJsonAtomic } = await importRuntimeModule("file-state");
@@ -75,6 +77,7 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
 
   function progress(phase, extra = {}) {
     writeJsonAtomic(progressPath, {
+      ...(meta.model_policy ? { model_policy: meta.model_policy } : {}),
       phase,
       updatedAt: new Date().toISOString(),
       ...extra,
@@ -83,6 +86,7 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
 
   let activeSubagents = 0;
   let completedSubagents = 0;
+  let promptCounter = 0;
   const subagentFailures = [];
 
   function getCommandDoneDelivery(result) {
@@ -97,18 +101,65 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
     });
   }
 
+  function promptFilePath() {
+    promptCounter += 1;
+    const dir = join(stateDir, "prompts");
+    mkdirSync(dir, { recursive: true });
+    return join(dir, `command-${String(promptCounter).padStart(3, "0")}.md`);
+  }
+
+  function readPromptText(promptFile) {
+    if (!promptFile) return undefined;
+    try {
+      return readFileSync(promptFile, "utf8");
+    } catch {
+      return undefined;
+    }
+  }
+
   async function observedExec(command, args, options) {
-    const commandDetail = formatCommandDetail(command, args);
-    const execArgs = appendRecipeContextToPiArgs(
+    const contextArgs = appendRecipeContextToPiArgs(
       command,
       args,
       meta.recipe_context_records,
       options?.actorRecipeContext,
     );
+    const materialized = materializePiPrintPromptArg(
+      command,
+      contextArgs,
+      promptFilePath,
+    );
+    const execArgs = materialized.args;
+    const commandDetail = formatCommandDetail(command, execArgs);
     activeSubagents += 1;
-    event("command.start", { activeSubagents, command: commandDetail });
+    event("command.start", {
+      activeSubagents,
+      command: commandDetail,
+      ...(materialized.promptFile ? { prompt_file: materialized.promptFile } : {}),
+      ...(materialized.promptBytes ? { prompt_bytes: materialized.promptBytes } : {}),
+    });
     progressRunning();
-    const result = await execCommandTemplate(command, execArgs, options);
+    let result = await execCommandTemplate(command, execArgs, options);
+    const preflightDiagnostic = result.code !== 0
+      ? buildReviewPreflightDiagnostic({
+          args: execArgs,
+          code: result.code,
+          killed: result.killed,
+          ...(materialized.promptFile ? { promptFile: materialized.promptFile } : {}),
+          promptText: readPromptText(materialized.promptFile),
+          stderr: result.stderr,
+          stdout: result.stdout,
+        })
+      : undefined;
+    if (preflightDiagnostic) {
+      result = {
+        ...result,
+        stderr: [
+          result.stderr,
+          formatReviewPreflightDiagnostic(preflightDiagnostic),
+        ].filter(Boolean).join("\n"),
+      };
+    }
     activeSubagents = Math.max(0, activeSubagents - 1);
     completedSubagents += 1;
     if (result.code !== 0) {
@@ -116,6 +167,8 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
         code: result.code,
         command: commandDetail,
         killed: result.killed,
+        ...(materialized.promptFile ? { prompt_file: materialized.promptFile } : {}),
+        ...(preflightDiagnostic ? { preflight: preflightDiagnostic } : {}),
       });
     }
     event("command.done", {
@@ -123,6 +176,9 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       code: result.code,
       command: commandDetail,
       killed: result.killed,
+      ...(materialized.promptFile ? { prompt_file: materialized.promptFile } : {}),
+      ...(materialized.promptBytes ? { prompt_bytes: materialized.promptBytes } : {}),
+      ...(preflightDiagnostic ? { preflight: preflightDiagnostic } : {}),
     });
     outbox(
       "command.done",
@@ -134,6 +190,9 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
         code: result.code,
         command: commandDetail,
         killed: result.killed,
+        ...(materialized.promptFile ? { prompt_file: materialized.promptFile } : {}),
+        ...(materialized.promptBytes ? { prompt_bytes: materialized.promptBytes } : {}),
+        ...(preflightDiagnostic ? { preflight: preflightDiagnostic } : {}),
       },
       getCommandDoneDelivery(result),
       result.code === 0 ? "info" : "error",
@@ -163,6 +222,7 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       code: result.details.code,
       command: result.details.command,
       killed: result.details.killed,
+      ...(meta.model_policy ? { model_policy: meta.model_policy } : {}),
       truncated: result.details.truncated,
       completedAt: new Date().toISOString(),
     });
@@ -173,15 +233,29 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
     event("run.done", { code: result.details.code });
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
+    const details = error && typeof error === "object" ? error.details : undefined;
     appendFileSync(stderrPath, `${message}\n`);
     writeJsonAtomic(resultPath, {
-      code: 1,
+      code: typeof details?.code === "number" ? details.code : 1,
       error: message,
-      killed: false,
+      killed: Boolean(details?.killed),
+      ...(Array.isArray(details?.branches) ? { branches: details.branches } : {}),
+      ...(details?.failureReason ? { failure_reason: details.failureReason } : {}),
+      ...(meta.model_policy ? { model_policy: meta.model_policy } : {}),
+      ...(details?.softQuorum ? { soft_quorum: details.softQuorum } : {}),
       completedAt: new Date().toISOString(),
     });
-    progress("failed", { completed: 0, failures: [{ message }] });
-    event("run.failed", { error: message });
+    progress("failed", {
+      completed: 0,
+      failures: Array.isArray(details?.branches) && details.branches.length > 0
+        ? details.branches
+        : [{ message }],
+      ...(details?.failureReason ? { failureReason: details.failureReason } : {}),
+    });
+    event("run.failed", {
+      error: message,
+      ...(details?.failureReason ? { failure_reason: details.failureReason } : {}),
+    });
     throw error;
   }
 }

package/scripts/conformance.mjs

@@ -14,6 +14,7 @@ import { fileURLToPath } from "node:url";
 const conformanceSuites = [
   "tests/protocol-examples.test.ts",
   "tests/recipes-discovery.test.ts",
+  "tests/review-swarm-dogfood.test.ts",
   "tests/registry.test.ts",
   "tests/runtime.test.ts",
   "tests/async-runs.test.ts",

package/skills/actors/SKILL.md

@@ -2,7 +2,7 @@
 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.
 metadata:
-  version: 0.37.1
+  version: 0.38.0
 ---
 
 # Actors (pi-actors)
@@ -199,9 +199,9 @@ 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. Set `"actor_context": false` or `"off"` to suppress it 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 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.
 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; expose `model`, `models`, and stage-specific model args so the caller must choose current policy at launch.
+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.
 
 Priority for same-id recipes:
 
@@ -284,7 +284,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. 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. 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/skills/swarm/SKILL.md

@@ -2,7 +2,7 @@
 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.
 metadata:
-  version: 0.37.1
+  version: 0.38.0
 ---
 
 # Swarm
@@ -162,7 +162,7 @@ Use [`references/development-swarm.md`](./references/development-swarm.md) for c
 
 Purpose: turn one result into many risk lenses and a decision-grade verdict.
 
-Use lens swarm for broad coverage, quorum for confidence on one critical judgement, or both for high-stakes releases. The final report should separate consensus findings, minority findings, merger findings, risks, and recommended next actions.
+Use lens swarm for broad coverage, quorum for confidence on one critical judgement, or both for high-stakes releases. In adapters that expose current session model/thinking policy, default ordinary same-policy review swarms to that current policy and require explicit args only when intentionally varying models or thinking levels. Run a cheap model/tool preflight before launching expensive reviewer fanout; if it fails, use the `ACTOR_PREFLIGHT_FAILED` stage/model/error-class/prompt-file diagnostic to choose explicit override args instead of rerunning blindly. For packaged review swarms, tune `min_successful_reviewers`, `reviewer_concurrency`, `subagent_ttl_ms`, and `merge_policy` instead of manual reruns; preserve partial reports and label the outcome `complete`, `degraded`, or `insufficient_data`. The final report should separate consensus findings, minority findings, merger findings, risks, and recommended next actions.
 
 A review swarm synthesis must not fabricate claims. Every final finding should trace to a reviewer note, checked artifact, command output, source, or explicit merger rationale. Devil's Advocate critical findings must be preserved or explicitly disproved with evidence.