@llblab/pi-actors 0.26.0 → 0.26.1

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+## 0.26.1: Coordinator Empty-Synthesis Hotfix
+
+- `[Coordinator]` Treat all-failed participant rounds and empty synthesis as a failed coordinator run instead of a clean success, preserving operator trust when swarm branches all exit non-zero.
+- `[Artifacts]` Write compact diagnostics into empty synthesis artifacts, including participant attempt/success/failure counts and transcript size, so failed swarms leave actionable evidence instead of only `No synthesis output`.
+
 ## 0.26.0: Actor Worker v2 and Package Contract Hardening
 
 - `[Actor Worker]` Promoted the packaged `actor-worker` into a v2 reference pattern with compact `worker-status.json`, optional per-task result artifacts under `worker-artifacts/`, stale-claim surfacing through status, and artifact metadata on `task.result` room messages.

package/dist/lib/coordinator.js

@@ -259,7 +259,7 @@ async function readRoomTranscript(config) {
 }
 async function synthesize(config, locker) {
     if (!config.artifactPath)
-        return;
+        return { code: 0, empty: false };
     if (locker) {
         await writeLockerMessage(locker, {
             type: "lock.claim",
@@ -269,9 +269,13 @@ async function synthesize(config, locker) {
     const transcript = await readRoomTranscript(config);
     const prompt = `Synthesize this transcript into a concise Markdown artifact. Mission: ${config.mission}. Include: Title, Consensus, Roles, Protocol, Final Artifact Shape, Next Actions, Open Questions. Use only the transcript evidence below.\n\nTRANSCRIPT:\n${transcript.slice(-24000)}`;
     const result = await runPi(prompt, config.model, config.thinking);
-    await writeFile(config.artifactPath, result.stdout.trim()
+    const output = result.stdout.trim();
+    const diagnostics = config.stats
+        ? `\n\n## Diagnostics\n\nparticipant_attempts=${config.stats.participantAttempts}\nparticipant_success=${config.stats.participantSuccess}\nparticipant_failures=${config.stats.participantFailures}\nsynthesis_code=${result.code}\ntranscript_messages=${transcript.trim() ? transcript.split("\n").length : 0}\n`
+        : "";
+    await writeFile(config.artifactPath, output
         ? result.stdout
-        : "# Synthesis Artifact\n\nNo synthesis output.\n", "utf8");
+        : `# Synthesis Artifact\n\nNo synthesis output.${diagnostics}\n`, "utf8");
     if (locker) {
         await writeLockerMessage(locker, {
             type: "lock.complete",
@@ -284,6 +288,7 @@ async function synthesize(config, locker) {
         });
     }
     process.stdout.write(`artifact=${config.artifactPath}\n`);
+    return { code: result.code, empty: !output };
 }
 async function readInboxLines(inboxPath) {
     if (!existsSync(inboxPath))
@@ -378,9 +383,17 @@ async function participantRound(role, round, config) {
     const address = `branch:${config.runId}/${role.name}`;
     const prompt = `You are ${displayName} (${address}), ${role.persona}. Mission: ${config.mission}. Round ${round}/${config.rounds}. First call inspect target=${config.room} view=previews lines=30 and inspect target=${config.room} view=contacts. Then call message once to ${config.room} from ${address} type=chat.message. Body: 2-4 sentences that react to a named participant, propose the next coordination step, and refine the shared artifact. Use contacts for peer names and addresses. End stdout with summary <=160 chars.`;
     const result = await executeParticipantPrompt(role, prompt, config);
+    if (config.stats) {
+        config.stats.participantAttempts += 1;
+        if (result.code === 0)
+            config.stats.participantSuccess += 1;
+        else
+            config.stats.participantFailures += 1;
+    }
     process.stdout.write(`[${role.name} round ${round}] code=${result.code}\n${result.stdout}\n`);
     if (result.stderr.trim())
         process.stderr.write(`[${role.name} round ${round}] ${result.stderr}\n`);
+    return result;
 }
 async function participantJoin(role, config) {
     const displayName = role.name;
@@ -546,6 +559,11 @@ export async function runCoordinator(argv = process.argv.slice(2)) {
         artifactPath: arg("artifact-path", ""),
         locker: boolArg("locker", false),
         lockerLeaseMs: numberArg("locker-lease-ms", 600000),
+        stats: {
+            participantAttempts: 0,
+            participantSuccess: 0,
+            participantFailures: 0,
+        },
     };
     if (!config.model) {
         console.error("--model is required");
@@ -559,7 +577,16 @@ export async function runCoordinator(argv = process.argv.slice(2)) {
         if (!runMode)
             throw new Error(`Unknown coordinator mode: ${config.mode}`);
         await runMode(config, locker);
-        await synthesize(config, locker);
+        const synthesis = await synthesize(config, locker);
+        if (config.stats.participantAttempts > 0 && config.stats.participantSuccess === 0) {
+            failures.push(`All participant rounds failed: attempts=${config.stats.participantAttempts}`);
+        }
+        if (synthesis?.empty && config.stats.participantFailures > 0) {
+            failures.push(`Synthesis output was empty after participant failures: failures=${config.stats.participantFailures}`);
+        }
+        if (synthesis && synthesis.code !== 0) {
+            failures.push(`Synthesis command failed: code=${synthesis.code}`);
+        }
     }
     catch (globalError) {
         failures.push(`Global coordinator error: ${globalError.message}`);

package/dist/skills/actors/SKILL.md

@@ -2,7 +2,7 @@
 name: actors
 description: Highest-density practical guide for pi-actors. Read this skill whenever prompt and tools are not enough for spawn, message, inspect, actor runs, tools, recipes, command templates, async lifecycle, mailboxes, artifacts, and local orchestration mechanics.
 metadata:
-  version: 0.26.0
+  version: 0.26.1
 ---
 
 # Actors (pi-actors)

package/dist/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.26.0
+  version: 0.26.1
 ---
 
 # Swarm

package/lib/coordinator.ts

@@ -285,7 +285,7 @@ async function readRoomTranscript(config) {
 }
 
 async function synthesize(config, locker) {
-  if (!config.artifactPath) return;
+  if (!config.artifactPath) return { code: 0, empty: false };
   if (locker) {
     await writeLockerMessage(locker, {
       type: "lock.claim",
@@ -295,11 +295,15 @@ async function synthesize(config, locker) {
   const transcript = await readRoomTranscript(config);
   const prompt = `Synthesize this transcript into a concise Markdown artifact. Mission: ${config.mission}. Include: Title, Consensus, Roles, Protocol, Final Artifact Shape, Next Actions, Open Questions. Use only the transcript evidence below.\n\nTRANSCRIPT:\n${transcript.slice(-24000)}`;
   const result = await runPi(prompt, config.model, config.thinking);
+  const output = result.stdout.trim();
+  const diagnostics = config.stats
+    ? `\n\n## Diagnostics\n\nparticipant_attempts=${config.stats.participantAttempts}\nparticipant_success=${config.stats.participantSuccess}\nparticipant_failures=${config.stats.participantFailures}\nsynthesis_code=${result.code}\ntranscript_messages=${transcript.trim() ? transcript.split("\n").length : 0}\n`
+    : "";
   await writeFile(
     config.artifactPath,
-    result.stdout.trim()
+    output
       ? result.stdout
-      : "# Synthesis Artifact\n\nNo synthesis output.\n",
+      : `# Synthesis Artifact\n\nNo synthesis output.${diagnostics}\n`,
     "utf8",
   );
   if (locker) {
@@ -314,6 +318,7 @@ async function synthesize(config, locker) {
     });
   }
   process.stdout.write(`artifact=${config.artifactPath}\n`);
+  return { code: result.code, empty: !output };
 }
 
 async function readInboxLines(inboxPath) {
@@ -432,11 +437,17 @@ async function participantRound(role, round, config) {
   const address = `branch:${config.runId}/${role.name}`;
   const prompt = `You are ${displayName} (${address}), ${role.persona}. Mission: ${config.mission}. Round ${round}/${config.rounds}. First call inspect target=${config.room} view=previews lines=30 and inspect target=${config.room} view=contacts. Then call message once to ${config.room} from ${address} type=chat.message. Body: 2-4 sentences that react to a named participant, propose the next coordination step, and refine the shared artifact. Use contacts for peer names and addresses. End stdout with summary <=160 chars.`;
   const result = await executeParticipantPrompt(role, prompt, config);
+  if (config.stats) {
+    config.stats.participantAttempts += 1;
+    if (result.code === 0) config.stats.participantSuccess += 1;
+    else config.stats.participantFailures += 1;
+  }
   process.stdout.write(
     `[${role.name} round ${round}] code=${result.code}\n${result.stdout}\n`,
   );
   if (result.stderr.trim())
     process.stderr.write(`[${role.name} round ${round}] ${result.stderr}\n`);
+  return result;
 }
 
 async function participantJoin(role, config) {
@@ -635,6 +646,11 @@ const config = {
   artifactPath: arg("artifact-path", ""),
   locker: boolArg("locker", false),
   lockerLeaseMs: numberArg("locker-lease-ms", 600000),
+  stats: {
+    participantAttempts: 0,
+    participantSuccess: 0,
+    participantFailures: 0,
+  },
 };
 
 if (!config.model) {
@@ -650,7 +666,20 @@ try {
   const runMode = coordinatorModes[config.mode];
   if (!runMode) throw new Error(`Unknown coordinator mode: ${config.mode}`);
   await runMode(config, locker);
-  await synthesize(config, locker);
+  const synthesis = await synthesize(config, locker);
+  if (config.stats.participantAttempts > 0 && config.stats.participantSuccess === 0) {
+    failures.push(
+      `All participant rounds failed: attempts=${config.stats.participantAttempts}`,
+    );
+  }
+  if (synthesis?.empty && config.stats.participantFailures > 0) {
+    failures.push(
+      `Synthesis output was empty after participant failures: failures=${config.stats.participantFailures}`,
+    );
+  }
+  if (synthesis && synthesis.code !== 0) {
+    failures.push(`Synthesis command failed: code=${synthesis.code}`);
+  }
 } catch (globalError) {
   failures.push(`Global coordinator error: ${globalError.message}`);
 } finally {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.26.0",
+  "version": "0.26.1",
   "private": false,
   "description": "Local Actor Kernel for Pi",
   "keywords": [

package/skills/actors/SKILL.md

@@ -2,7 +2,7 @@
 name: actors
 description: Highest-density practical guide for pi-actors. Read this skill whenever prompt and tools are not enough for spawn, message, inspect, actor runs, tools, recipes, command templates, async lifecycle, mailboxes, artifacts, and local orchestration mechanics.
 metadata:
-  version: 0.26.0
+  version: 0.26.1
 ---
 
 # Actors (pi-actors)

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.26.0
+  version: 0.26.1
 ---
 
 # Swarm