@llblab/pi-actors 0.26.0 → 0.26.2

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 0.26.2: Terminal Progress Hotfix
+
+- `[Async Runs]` Keep `progress.json` aligned with terminal kill/cancel handling by writing `phase=killed` or `phase=cancelled` and clearing active subagent counts when a run is stopped by runtime control.
+- `[Inspector]` Prevent killed runs from showing contradictory `status=killed` with `progress.phase=running`, preserving compact operator status trust after `control.kill`.
+
+## 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/async-runs.js

@@ -565,6 +565,10 @@ export function readRunStateIndex(stateRoot = DEFAULT_STATE_ROOT) {
     });
     if (valid.some((entry) => !existsSync(join(entry.state_dir, "run.json"))))
         return undefined;
+    const indexedDirs = new Set(valid.map((entry) => resolve(entry.state_dir)));
+    const stateDirs = listRunStateDirs(stateRoot).map((stateDir) => resolve(stateDir));
+    if (stateDirs.some((stateDir) => !indexedDirs.has(stateDir)))
+        return undefined;
     return valid;
 }
 export function listRuns(stateRoot = DEFAULT_STATE_ROOT, statusFilter) {
@@ -1010,6 +1014,20 @@ function markTerminalHandled(stateDir, details) {
         ts: new Date().toISOString(),
     });
 }
+function markTerminalProgress(stateDir, phase) {
+    const existing = readJson(join(stateDir, "progress.json"));
+    const progress = existing && typeof existing === "object" && !Array.isArray(existing)
+        ? existing
+        : {};
+    const { activeSubagents: _activeSubagents, ...rest } = progress;
+    writeJsonAtomic(join(stateDir, "progress.json"), {
+        ...rest,
+        completed: typeof progress.completed === "number" ? progress.completed : 0,
+        failures: Array.isArray(progress.failures) ? progress.failures : [],
+        phase,
+        updatedAt: new Date().toISOString(),
+    });
+}
 function stopRun(runOrDir, signal, event) {
     const status = getRunStatus(runOrDir);
     const pid = Number(status.pid || 0);
@@ -1024,6 +1042,10 @@ function stopRun(runOrDir, signal, event) {
     const signalResult = signalOwnedRunProcess(pid, signal);
     writeFileSync(join(stateDir, "events.jsonl"), `${JSON.stringify({ event, pid, signal, ...signalResult, ts: new Date().toISOString() })}\n`, { flag: "a" });
     markTerminalHandled(stateDir, { event, signal });
+    if (event === "run.kill")
+        markTerminalProgress(stateDir, "killed");
+    if (event === "run.cancel")
+        markTerminalProgress(stateDir, "cancelled");
     return { stopped: true, pid, signal, ...signalResult, state_dir: stateDir };
 }
 export function cancelRun(runOrDir) {

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.2
 ---
 
 # 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.2
 ---
 
 # Swarm

package/lib/async-runs.ts

@@ -805,6 +805,9 @@ export function readRunStateIndex(
   });
   if (valid.some((entry) => !existsSync(join(entry.state_dir, "run.json"))))
     return undefined;
+  const indexedDirs = new Set(valid.map((entry) => resolve(entry.state_dir)));
+  const stateDirs = listRunStateDirs(stateRoot).map((stateDir) => resolve(stateDir));
+  if (stateDirs.some((stateDir) => !indexedDirs.has(stateDir))) return undefined;
   return valid;
 }
 
@@ -1403,6 +1406,25 @@ function markTerminalHandled(
   });
 }
 
+function markTerminalProgress(
+  stateDir: string,
+  phase: "cancelled" | "killed",
+): void {
+  const existing = readJson(join(stateDir, "progress.json"));
+  const progress =
+    existing && typeof existing === "object" && !Array.isArray(existing)
+      ? (existing as Record<string, unknown>)
+      : {};
+  const { activeSubagents: _activeSubagents, ...rest } = progress;
+  writeJsonAtomic(join(stateDir, "progress.json"), {
+    ...rest,
+    completed: typeof progress.completed === "number" ? progress.completed : 0,
+    failures: Array.isArray(progress.failures) ? progress.failures : [],
+    phase,
+    updatedAt: new Date().toISOString(),
+  });
+}
+
 function stopRun(
   runOrDir: string,
   signal: NodeJS.Signals,
@@ -1425,6 +1447,8 @@ function stopRun(
     { flag: "a" },
   );
   markTerminalHandled(stateDir, { event, signal });
+  if (event === "run.kill") markTerminalProgress(stateDir, "killed");
+  if (event === "run.cancel") markTerminalProgress(stateDir, "cancelled");
   return { stopped: true, pid, signal, ...signalResult, state_dir: stateDir };
 }
 

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.2",
   "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.2
 ---
 
 # 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.2
 ---
 
 # Swarm