@llblab/pi-actors 0.26.1 → 0.26.3

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 0.26.3: Branch Message Delivery UX Hotfix
+
+- `[Actor Messages]` Treat branch mailbox persistence as a successful queued outcome even when the parent run control endpoint is unavailable, returning compact `queued=true` delivery diagnostics instead of throwing an unframed tool error.
+- `[UX]` Preserve the compact action-output contract for branch `message` calls by keeping delivery diagnostics in the normal result formatter, including the leading blank-line separation used by other tool actions.
+
+## 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.

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/tools.js

@@ -441,6 +441,8 @@ function compactActorMessageResult(message, result) {
     ];
     if (result.bytes !== undefined)
         tokens.push(`bytes=${String(result.bytes)}`);
+    if (result.queued === true)
+        tokens.push("queued=true");
     if (result.control)
         tokens.push(`control=${String(result.control)}`);
     if (result.outbox)
@@ -459,6 +461,9 @@ function compactActorMessageResult(message, result) {
         tokens.push(`signal=${String(result.signal)}`);
     if (result.invoked === true)
         tokens.push("invoked=true");
+    if (result.delivery_error) {
+        tokens.push(`delivery_error=${compactPreview(result.delivery_error, 96)}`);
+    }
     return `\n${tokens.join(" ")}`;
 }
 function maybeJsonText(value, verbose, compact) {
@@ -543,7 +548,25 @@ function assertMessageSenderBelongsToRun(message, run, routeLabel) {
 async function routeBranchEnvelope(stateDir, runId, recipient, message, _options) {
     const branchMessage = { ...message, to: recipient };
     ActorRooms.appendBranchInboxMessage(stateDir, runId, recipient, branchMessage);
-    return AsyncRuns.sendRunMessage(runId, JSON.stringify(branchMessage));
+    try {
+        return await AsyncRuns.sendRunMessage(runId, JSON.stringify(branchMessage));
+    }
+    catch (error) {
+        const record = error && typeof error === "object" ? error : {};
+        if (record.queued === true) {
+            return {
+                control_path: record.control_path,
+                control_type: record.control_type,
+                delivery_error: record.delivery_error ?? (error instanceof Error ? error.message : String(error)),
+                inbox_id: record.inbox_id,
+                queued: true,
+                run: runId,
+                sent: false,
+                state_dir: stateDir,
+            };
+        }
+        throw error;
+    }
 }
 function getRoomMulticastRecipients(message, run) {
     const raw = message.metadata?.recipients;

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.1
+  version: 0.26.3
 ---
 
 # 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.1
+  version: 0.26.3
 ---
 
 # 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/tools.ts

@@ -535,6 +535,7 @@ function compactActorMessageResult(
     `message=${result.sent === true || result.stopped === true ? "sent" : "not_sent"}`,
   ];
   if (result.bytes !== undefined) tokens.push(`bytes=${String(result.bytes)}`);
+  if (result.queued === true) tokens.push("queued=true");
   if (result.control) tokens.push(`control=${String(result.control)}`);
   if (result.outbox) tokens.push(`messages=${String(result.outbox)}`);
   if (result.message_count !== undefined)
@@ -546,6 +547,9 @@ function compactActorMessageResult(
   if (result.stopped === true) tokens.push("stopped=true");
   if (result.signal) tokens.push(`signal=${String(result.signal)}`);
   if (result.invoked === true) tokens.push("invoked=true");
+  if (result.delivery_error) {
+    tokens.push(`delivery_error=${compactPreview(result.delivery_error, 96)}`);
+  }
   return `\n${tokens.join(" ")}`;
 }
 
@@ -695,7 +699,24 @@ async function routeBranchEnvelope(
     recipient,
     branchMessage,
   );
-  return AsyncRuns.sendRunMessage(runId, JSON.stringify(branchMessage));
+  try {
+    return await AsyncRuns.sendRunMessage(runId, JSON.stringify(branchMessage));
+  } catch (error) {
+    const record = error && typeof error === "object" ? (error as Record<string, unknown>) : {};
+    if (record.queued === true) {
+      return {
+        control_path: record.control_path,
+        control_type: record.control_type,
+        delivery_error: record.delivery_error ?? (error instanceof Error ? error.message : String(error)),
+        inbox_id: record.inbox_id,
+        queued: true,
+        run: runId,
+        sent: false,
+        state_dir: stateDir,
+      };
+    }
+    throw error;
+  }
 }
 
 function getRoomMulticastRecipients(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.26.1",
+  "version": "0.26.3",
   "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.1
+  version: 0.26.3
 ---
 
 # 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.1
+  version: 0.26.3
 ---
 
 # Swarm