@llblab/pi-actors 0.37.1 → 0.38.1

package/recipes/subagent-review-coordinator.json

@@ -1,6 +1,7 @@
 {
   "async": true,
   "imports": {
+    "preflight": "subagent-preflight.json",
     "reviewer": "subagent-review.json",
     "verifier": "subagent-verify.json",
     "merger": "subagent-merge.json",
@@ -17,6 +18,10 @@
     "judge_model:string",
     "thinking:string",
     "tools:string",
+    "subagent_ttl_ms:int",
+    "reviewer_concurrency:string",
+    "min_successful_reviewers:int",
+    "merge_policy:string",
     "evidence_policy:string",
     "risk_policy:string",
     "output_format:string"
@@ -28,11 +33,19 @@
       "operator UX"
     ],
     "claim": "The reviewed scope is ready for the next implementation or release step.",
-    "thinking": "off",
+    "thinking": "{current_thinking}",
     "tools": "",
+    "subagent_ttl_ms": 600000,
+    "reviewer_concurrency": "",
+    "min_successful_reviewers": 1,
+    "merge_policy": "Preserve partial reviewer reports, branch status, and degraded confidence markers. If reviewer evidence is below threshold, do not invent consensus.",
     "evidence_policy": "Cite inspected files, command output, or explicit uncertainty for every material claim.",
     "risk_policy": "Preserve minority high-impact risks and separate confirmed issues from hypotheses.",
-    "output_format": "Markdown sections: Summary, Consensus Findings, Minority Findings, Verification, Judge Notes, Risks, Next Actions."
+    "output_format": "Markdown sections: Status (complete/degraded/insufficient_data), Summary, Consensus Findings, Minority Findings, Verification, Judge Notes, Risks, Next Actions.",
+    "reviewer_model": "{current_model}",
+    "verifier_model": "{current_model}",
+    "merger_model": "{current_model}",
+    "judge_model": "{current_model}"
   },
   "mailbox": {
     "accepts": [
@@ -49,12 +62,65 @@
     ]
   },
   "template": [
+    {
+      "parallel": true,
+      "failure": "root",
+      "template": [
+        {
+          "label": "preflight:reviewer",
+          "name": "preflight",
+          "timeout": "{subagent_ttl_ms}",
+          "values": {
+            "stage": "reviewer",
+            "model": "{reviewer_model}",
+            "thinking": "{thinking}",
+            "tools": "{tools}"
+          }
+        },
+        {
+          "label": "preflight:verifier",
+          "name": "preflight",
+          "timeout": "{subagent_ttl_ms}",
+          "values": {
+            "stage": "verifier",
+            "model": "{verifier_model}",
+            "thinking": "{thinking}",
+            "tools": "{tools}"
+          }
+        },
+        {
+          "label": "preflight:merger",
+          "name": "preflight",
+          "timeout": "{subagent_ttl_ms}",
+          "values": {
+            "stage": "merger",
+            "model": "{merger_model}",
+            "thinking": "{thinking}",
+            "tools": "{tools}"
+          }
+        },
+        {
+          "label": "preflight:judge",
+          "name": "preflight",
+          "timeout": "{subagent_ttl_ms}",
+          "values": {
+            "stage": "judge",
+            "model": "{judge_model}",
+            "thinking": "{thinking}",
+            "tools": "{tools}"
+          }
+        }
+      ]
+    },
     {
       "parallel": true,
       "repeat": "{lenses.length}",
+      "concurrency": "{reviewer_concurrency}",
+      "min_successful": "{min_successful_reviewers}",
       "failure": "branch",
       "template": {
         "name": "reviewer",
+        "timeout": "{subagent_ttl_ms}",
         "values": {
           "scope": "{scope}",
           "lens": "{lenses[index]}",
@@ -68,9 +134,10 @@
     },
     {
       "name": "verifier",
+      "timeout": "{subagent_ttl_ms}",
       "values": {
         "claim": "{claim}",
-        "evidence": "Use previous reviewer outputs from stdin and named scope: {scope}.",
+        "evidence": "Use previous reviewer outputs from stdin and named scope: {scope}. Respect the parallel_status header and verify only against usable reviewer evidence.",
         "model": "{verifier_model}",
         "thinking": "{thinking}",
         "tools": "{tools}",
@@ -79,32 +146,37 @@
     },
     {
       "name": "merger",
+      "timeout": "{subagent_ttl_ms}",
       "values": {
         "inputs": "Use previous reviewer and verifier outputs from stdin.",
         "mode": "consensus-first",
+        "merge_policy": "{merge_policy}",
         "model": "{merger_model}",
-        "thinking": "medium",
+        "thinking": "{thinking}",
         "tools": "{tools}",
         "risk_policy": "{risk_policy}"
       }
     },
     {
       "name": "judge",
+      "timeout": "{subagent_ttl_ms}",
       "values": {
         "report": "Use merged output from stdin.",
-        "evidence": "Use previous reviewer, verifier, and merger outputs from stdin.",
+        "evidence": "Use previous reviewer, verifier, and merger outputs from stdin. Preserve complete/degraded/insufficient_data status.",
         "model": "{judge_model}",
-        "thinking": "medium",
+        "thinking": "{thinking}",
         "tools": "{tools}"
       }
     },
     {
       "name": "normalizer",
+      "timeout": "{subagent_ttl_ms}",
       "values": {
         "input": "Use merged and judged output from stdin.",
         "format": "{output_format}",
+        "preservation_policy": "Preserve branch status and explicitly mark Status as complete, degraded, or insufficient_data.",
         "model": "{merger_model}",
-        "thinking": "off",
+        "thinking": "{thinking}",
         "tools": "{tools}"
       }
     }

package/recipes/subagent-review.json

@@ -17,7 +17,8 @@
     "evidence_policy": "Cite inspected files, command output, or explicit uncertainty for every material claim.",
     "risk_policy": "Preserve minority high-impact risks and separate confirmed issues from hypotheses.",
     "output_format": "Markdown sections: Findings, Evidence, Risks, Next Actions.",
-    "thinking": "off",
+    "model": "{current_model}",
+    "thinking": "{current_thinking}",
     "tools": ""
   },
   "mailbox": {

package/recipes/subagent-verify.json

@@ -14,7 +14,8 @@
     "acceptance": "Separate proven, disproven, unknown, and missing evidence.",
     "evidence_policy": "Do not infer beyond provided evidence or inspected artifacts.",
     "output_format": "Markdown sections: Verdict, Evidence, Gaps, Confidence.",
-    "thinking": "off",
+    "model": "{current_model}",
+    "thinking": "{current_thinking}",
     "tools": ""
   },
   "mailbox": {

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.1
 ---
 
 # 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.1
 ---
 
 # 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.