@llblab/pi-actors 0.29.0 → 0.29.1

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+## 0.29.1: Subagent TTL Kill Hotfix
+
+- `[Coordinator]` Added `subagent_ttl_ms` / `--subagent-ttl-ms` to the room-swarm adapter so timed-out subagent `pi -p` processes are terminated instead of only awaited.
+
 ## 0.29.0: Candidate Recipe Memory
 
 - `[Spawn]` Capture inline spawn templates as non-registered candidate recipes under `~/.pi/agent/recipes/candidates`, making successful ad hoc actor patterns easy to replay by explicit path and promote manually.

package/dist/lib/coordinator.js

@@ -200,7 +200,25 @@ async function stopLocker(locker) {
             locker.child.kill("SIGTERM");
     }
 }
-function runPi(prompt, model, thinking) {
+function terminateProcessGroup(child, signal) {
+    if (!child.pid)
+        return;
+    try {
+        if (process.platform !== "win32")
+            process.kill(-child.pid, signal);
+        else
+            child.kill(signal);
+    }
+    catch {
+        try {
+            child.kill(signal);
+        }
+        catch {
+            // Process already exited.
+        }
+    }
+}
+function runPi(prompt, model, thinking, ttlMs = 0) {
     return new Promise((resolve) => {
         const args = [
             "--tools",
@@ -216,17 +234,57 @@ function runPi(prompt, model, thinking) {
             args.push("--thinking", thinking);
         }
         args.push("-p", prompt);
-        const child = spawn("pi", args, { stdio: ["ignore", "pipe", "pipe"] });
+        const child = spawn("pi", args, {
+            detached: process.platform !== "win32",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
         let stdout = "";
         let stderr = "";
+        let settled = false;
+        let timedOut = false;
+        let ttlTimer;
+        let forceTimer;
+        const clearTimers = () => {
+            if (ttlTimer)
+                clearTimeout(ttlTimer);
+            if (forceTimer)
+                clearTimeout(forceTimer);
+        };
+        if (ttlMs > 0) {
+            ttlTimer = setTimeout(() => {
+                timedOut = true;
+                stderr += `\nSubagent TTL expired after ${ttlMs}ms; terminating process group.\n`;
+                terminateProcessGroup(child, "SIGTERM");
+                forceTimer = setTimeout(() => terminateProcessGroup(child, "SIGKILL"), 1000);
+            }, ttlMs);
+        }
         child.stdout.on("data", (chunk) => {
             stdout += chunk;
         });
         child.stderr.on("data", (chunk) => {
             stderr += chunk;
         });
-        child.on("close", (code) => resolve({ code, stdout, stderr }));
-        child.on("error", (error) => resolve({ code: 1, stdout, stderr: String(error) }));
+        child.on("close", (code, signal) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimers();
+            resolve({
+                code: timedOut ? 124 : (code ?? (signal ? 1 : 0)),
+                killed: timedOut,
+                signal,
+                stderr,
+                stdout,
+                timed_out: timedOut,
+            });
+        });
+        child.on("error", (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimers();
+            resolve({ code: 1, stdout, stderr: String(error) });
+        });
     });
 }
 async function readRoomTranscript(config) {
@@ -268,7 +326,7 @@ 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 result = await runPi(prompt, config.model, config.thinking, config.subagentTtlMs);
     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`
@@ -371,7 +429,7 @@ async function executeParticipantPrompt(role, basePrompt, config) {
             "\nPlease acknowledge and address these direct messages in your response.\n";
         finalPrompt += inboxSection;
     }
-    const result = await runPi(finalPrompt, config.model, config.thinking);
+    const result = await runPi(finalPrompt, config.model, config.thinking, config.subagentTtlMs);
     if (claimedIds.length > 0) {
         const finalStatus = result.code === 0 ? "handled" : "failed";
         await updateInboxMessagesStatus(config.runId, branchName, claimedIds, finalStatus);
@@ -399,13 +457,13 @@ async function participantJoin(role, config) {
     const displayName = role.name;
     const address = `branch:${config.runId}/${role.name}`;
     const joinPrompt = `You are ${displayName}, ${role.persona}. Mission: ${config.mission}. Call tool message exactly once with to=${shellQuote(config.room)}, from=${shellQuote(address)}, type='actor.join', summary='${displayName} joined', body JSON {"role":${JSON.stringify(role.persona)},"display":${JSON.stringify(displayName)},"caps":["coordination","synthesis"],"claim":"coordinate on mission"}. Then print one short line.`;
-    await runPi(joinPrompt, config.model, config.thinking);
+    await runPi(joinPrompt, config.model, config.thinking, config.subagentTtlMs);
 }
 async function participantLeave(role, config) {
     const displayName = role.name;
     const address = `branch:${config.runId}/${role.name}`;
     const leavePrompt = `Call tool message exactly once with to=${shellQuote(config.room)}, from=${shellQuote(address)}, type='actor.leave', summary='${displayName} left', body='finished coordinated work'. Then print goodbye.`;
-    await runPi(leavePrompt, config.model, config.thinking);
+    await runPi(leavePrompt, config.model, config.thinking, config.subagentTtlMs);
 }
 // 1. consensus / swarm mode: iterative chat in a room
 async function runConsensus(config, locker) {
@@ -559,6 +617,7 @@ export async function runCoordinator(argv = process.argv.slice(2)) {
         artifactPath: arg("artifact-path", ""),
         locker: boolArg("locker", false),
         lockerLeaseMs: numberArg("locker-lease-ms", 600000),
+        subagentTtlMs: numberArg("subagent-ttl-ms", 0),
         stats: {
             participantAttempts: 0,
             participantSuccess: 0,

package/dist/recipes/pipeline-room-swarm.json

@@ -11,6 +11,7 @@
     "delay:int",
     "locker:bool",
     "locker_lease_ms:int",
+    "subagent_ttl_ms:int",
     "artifact_path:path",
     "repo:path"
   ],
@@ -23,6 +24,7 @@
     "delay": "10",
     "locker": "false",
     "locker_lease_ms": "600000",
+    "subagent_ttl_ms": "0",
     "artifact_path": "{state_dir}/room-swarm-artifact.md",
     "repo": "~/.pi/agent/extensions/pi-actors"
   },
@@ -44,5 +46,5 @@
       "run.failed"
     ]
   },
-  "template": "{repo}/scripts/coordinator.mjs --run-id={run_id} --mode={mode} --mission={mission} --model={model} --thinking={thinking} --roles={roles} --roles-path={roles_path} --rounds={rounds} --delay={delay} --locker={locker} --locker-lease-ms={locker_lease_ms} --artifact-path={artifact_path}"
+  "template": "{repo}/scripts/coordinator.mjs --run-id={run_id} --mode={mode} --mission={mission} --model={model} --thinking={thinking} --roles={roles} --roles-path={roles_path} --rounds={rounds} --delay={delay} --locker={locker} --locker-lease-ms={locker_lease_ms} --subagent-ttl-ms={subagent_ttl_ms} --artifact-path={artifact_path}"
 }

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.29.0
+  version: 0.29.1
 ---
 
 # Actors (pi-actors)
@@ -302,7 +302,7 @@ Use packaged recipes by name with `spawn file=<name>` for async actors, or regis
 - [`pipeline-docs-maintenance`](../../recipes/pipeline-docs-maintenance.json): docs index/review/planning → maintenance artifact.
 - Artifacts: [`pipeline-artifact-report`](../../recipes/pipeline-artifact-report.json), [`pipeline-artifact-write`](../../recipes/pipeline-artifact-write.json), [`pipeline-artifact-bundle`](../../recipes/pipeline-artifact-bundle.json).
 - Review gates: [`pipeline-quorum-review`](../../recipes/pipeline-quorum-review.json), [`pipeline-review-readiness`](../../recipes/pipeline-review-readiness.json).
-- Task-first workflows: [`pipeline-architect-coordinator`](../../recipes/pipeline-architect-coordinator.json), [`pipeline-research-synthesis`](../../recipes/pipeline-research-synthesis.json), [`pipeline-development-tasking`](../../recipes/pipeline-development-tasking.json), [`pipeline-checkpoint-continuation`](../../recipes/pipeline-checkpoint-continuation.json), [`pipeline-media-library`](../../recipes/pipeline-media-library.json), [`pipeline-room-swarm`](../../recipes/pipeline-room-swarm.json). For room swarms, choose `mode` from `consensus`, `pipeline`, `fanout`, or `pool`; prefer `roles_path` for custom role JSON and keep role `name` ASCII-safe for branch addresses. Use `locker=true` when the swarm needs a coordinator-locker-backed artifact lock and journal.
+- Task-first workflows: [`pipeline-architect-coordinator`](../../recipes/pipeline-architect-coordinator.json), [`pipeline-research-synthesis`](../../recipes/pipeline-research-synthesis.json), [`pipeline-development-tasking`](../../recipes/pipeline-development-tasking.json), [`pipeline-checkpoint-continuation`](../../recipes/pipeline-checkpoint-continuation.json), [`pipeline-media-library`](../../recipes/pipeline-media-library.json), [`pipeline-room-swarm`](../../recipes/pipeline-room-swarm.json). For room swarms, choose `mode` from `consensus`, `pipeline`, `fanout`, or `pool`; prefer `roles_path` for custom role JSON and keep role `name` ASCII-safe for branch addresses. Set `subagent_ttl_ms` when participant processes need a hard kill budget. Use `locker=true` when the swarm needs a coordinator-locker-backed artifact lock and journal.
 
 ### Utilities
 

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.29.0
+  version: 0.29.1
 ---
 
 # Swarm

package/docs/recipe-library.md

@@ -84,7 +84,7 @@ Pipeline recipes demonstrate second-order composition:
 - `recipes/pipeline-development-tasking.json`: Plan → task card → critique → integrator handoff.
 - `recipes/pipeline-docs-maintenance.json`: Docs index → documentation review → maintenance plan → artifact report.
 - `recipes/pipeline-media-library.json`: Playlist build → media-library artifact report.
-- `recipes/pipeline-room-swarm.json`: Room participants join `room:<run>`, coordinate over repeated room-visible rounds, leave cleanly, and synthesize the room transcript into a caller-provided artifact path. Supported coordinator modes are `consensus`, `pipeline`, `fanout`, and `pool`; unknown modes fail closed instead of silently running consensus. Keep model/thinking/mission policy caller-owned. Custom roles can be supplied with `roles_path` as a JSON array of `{ "name", "persona" }` objects; `name` stays ASCII-safe for `branch:<run>/<name>` addresses and debugger output remains plain and name-driven. The packaged swarm uses contacts for peer awareness but does not rely on direct branch delivery unless a caller-specific worker protocol consumes branch envelopes. Set `locker=true` to compose a local `coordinator-locker` cell under `{state_dir}/locker` for artifact ownership, resource lease locks, and a decision journal without merging locker policy into the room-participant script.
+- `recipes/pipeline-room-swarm.json`: Room participants join `room:<run>`, coordinate over repeated room-visible rounds, leave cleanly, and synthesize the room transcript into a caller-provided artifact path. Supported coordinator modes are `consensus`, `pipeline`, `fanout`, and `pool`; unknown modes fail closed instead of silently running consensus. Keep model/thinking/mission policy caller-owned. Custom roles can be supplied with `roles_path` as a JSON array of `{ "name", "persona" }` objects; `name` stays ASCII-safe for `branch:<run>/<name>` addresses and debugger output remains plain and name-driven. The packaged swarm uses contacts for peer awareness but does not rely on direct branch delivery unless a caller-specific worker protocol consumes branch envelopes. Set `subagent_ttl_ms` to a positive millisecond budget when participant `pi -p` processes must be killed instead of awaited indefinitely. Set `locker=true` to compose a local `coordinator-locker` cell under `{state_dir}/locker` for artifact ownership, resource lease locks, and a decision journal without merging locker policy into the room-participant script.
 - `recipes/pipeline-artifact-report.json`: Normalize → artifact-shaped output → actor-message-shaped record. This pipeline prepares a candidate artifact and emits `artifact.prepared`/`artifact.blocked`; the `artifact_path` is a target path, not a guarantee that the file was written.
 - `recipes/pipeline-artifact-write.json`: Normalize → artifact-shaped output → deterministic artifact write → actor-message-shaped record. Use only when the caller explicitly wants filesystem writes; `write_mode` is `create`, `overwrite`, or `append`.
 - `recipes/pipeline-artifact-bundle.json`: Optional validation → deterministic artifact write → machine-readable manifest generation → deterministic manifest write → actor-message-shaped record. Use when the caller explicitly wants a filesystem handoff bundle with both artifact and manifest paths.

package/lib/coordinator.ts

@@ -220,7 +220,21 @@ async function stopLocker(locker) {
   }
 }
 
-function runPi(prompt, model, thinking) {
+function terminateProcessGroup(child, signal) {
+  if (!child.pid) return;
+  try {
+    if (process.platform !== "win32") process.kill(-child.pid, signal);
+    else child.kill(signal);
+  } catch {
+    try {
+      child.kill(signal);
+    } catch {
+      // Process already exited.
+    }
+  }
+}
+
+function runPi(prompt, model, thinking, ttlMs = 0) {
   return new Promise((resolve) => {
     const args = [
       "--tools",
@@ -237,19 +251,53 @@ function runPi(prompt, model, thinking) {
     }
     args.push("-p", prompt);
 
-    const child = spawn("pi", args, { stdio: ["ignore", "pipe", "pipe"] });
+    const child = spawn("pi", args, {
+      detached: process.platform !== "win32",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
     let stdout = "";
     let stderr = "";
+    let settled = false;
+    let timedOut = false;
+    let ttlTimer;
+    let forceTimer;
+    const clearTimers = () => {
+      if (ttlTimer) clearTimeout(ttlTimer);
+      if (forceTimer) clearTimeout(forceTimer);
+    };
+    if (ttlMs > 0) {
+      ttlTimer = setTimeout(() => {
+        timedOut = true;
+        stderr += `\nSubagent TTL expired after ${ttlMs}ms; terminating process group.\n`;
+        terminateProcessGroup(child, "SIGTERM");
+        forceTimer = setTimeout(() => terminateProcessGroup(child, "SIGKILL"), 1000);
+      }, ttlMs);
+    }
     child.stdout.on("data", (chunk) => {
       stdout += chunk;
     });
     child.stderr.on("data", (chunk) => {
       stderr += chunk;
     });
-    child.on("close", (code) => resolve({ code, stdout, stderr }));
-    child.on("error", (error) =>
-      resolve({ code: 1, stdout, stderr: String(error) }),
-    );
+    child.on("close", (code, signal) => {
+      if (settled) return;
+      settled = true;
+      clearTimers();
+      resolve({
+        code: timedOut ? 124 : (code ?? (signal ? 1 : 0)),
+        killed: timedOut,
+        signal,
+        stderr,
+        stdout,
+        timed_out: timedOut,
+      });
+    });
+    child.on("error", (error) => {
+      if (settled) return;
+      settled = true;
+      clearTimers();
+      resolve({ code: 1, stdout, stderr: String(error) });
+    });
   });
 }
 
@@ -294,7 +342,7 @@ 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 result = await runPi(prompt, config.model, config.thinking, config.subagentTtlMs);
   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`
@@ -417,7 +465,7 @@ async function executeParticipantPrompt(role, basePrompt, config) {
     finalPrompt += inboxSection;
   }
 
-  const result = await runPi(finalPrompt, config.model, config.thinking);
+  const result = await runPi(finalPrompt, config.model, config.thinking, config.subagentTtlMs);
 
   if (claimedIds.length > 0) {
     const finalStatus = result.code === 0 ? "handled" : "failed";
@@ -454,14 +502,14 @@ async function participantJoin(role, config) {
   const displayName = role.name;
   const address = `branch:${config.runId}/${role.name}`;
   const joinPrompt = `You are ${displayName}, ${role.persona}. Mission: ${config.mission}. Call tool message exactly once with to=${shellQuote(config.room)}, from=${shellQuote(address)}, type='actor.join', summary='${displayName} joined', body JSON {"role":${JSON.stringify(role.persona)},"display":${JSON.stringify(displayName)},"caps":["coordination","synthesis"],"claim":"coordinate on mission"}. Then print one short line.`;
-  await runPi(joinPrompt, config.model, config.thinking);
+  await runPi(joinPrompt, config.model, config.thinking, config.subagentTtlMs);
 }
 
 async function participantLeave(role, config) {
   const displayName = role.name;
   const address = `branch:${config.runId}/${role.name}`;
   const leavePrompt = `Call tool message exactly once with to=${shellQuote(config.room)}, from=${shellQuote(address)}, type='actor.leave', summary='${displayName} left', body='finished coordinated work'. Then print goodbye.`;
-  await runPi(leavePrompt, config.model, config.thinking);
+  await runPi(leavePrompt, config.model, config.thinking, config.subagentTtlMs);
 }
 
 // 1. consensus / swarm mode: iterative chat in a room
@@ -646,6 +694,7 @@ const config = {
   artifactPath: arg("artifact-path", ""),
   locker: boolArg("locker", false),
   lockerLeaseMs: numberArg("locker-lease-ms", 600000),
+  subagentTtlMs: numberArg("subagent-ttl-ms", 0),
   stats: {
     participantAttempts: 0,
     participantSuccess: 0,

package/package.json

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

package/recipes/pipeline-room-swarm.json

@@ -11,6 +11,7 @@
     "delay:int",
     "locker:bool",
     "locker_lease_ms:int",
+    "subagent_ttl_ms:int",
     "artifact_path:path",
     "repo:path"
   ],
@@ -23,6 +24,7 @@
     "delay": "10",
     "locker": "false",
     "locker_lease_ms": "600000",
+    "subagent_ttl_ms": "0",
     "artifact_path": "{state_dir}/room-swarm-artifact.md",
     "repo": "~/.pi/agent/extensions/pi-actors"
   },
@@ -44,5 +46,5 @@
       "run.failed"
     ]
   },
-  "template": "{repo}/scripts/coordinator.mjs --run-id={run_id} --mode={mode} --mission={mission} --model={model} --thinking={thinking} --roles={roles} --roles-path={roles_path} --rounds={rounds} --delay={delay} --locker={locker} --locker-lease-ms={locker_lease_ms} --artifact-path={artifact_path}"
+  "template": "{repo}/scripts/coordinator.mjs --run-id={run_id} --mode={mode} --mission={mission} --model={model} --thinking={thinking} --roles={roles} --roles-path={roles_path} --rounds={rounds} --delay={delay} --locker={locker} --locker-lease-ms={locker_lease_ms} --subagent-ttl-ms={subagent_ttl_ms} --artifact-path={artifact_path}"
 }

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.29.0
+  version: 0.29.1
 ---
 
 # Actors (pi-actors)
@@ -302,7 +302,7 @@ Use packaged recipes by name with `spawn file=<name>` for async actors, or regis
 - [`pipeline-docs-maintenance`](../../recipes/pipeline-docs-maintenance.json): docs index/review/planning → maintenance artifact.
 - Artifacts: [`pipeline-artifact-report`](../../recipes/pipeline-artifact-report.json), [`pipeline-artifact-write`](../../recipes/pipeline-artifact-write.json), [`pipeline-artifact-bundle`](../../recipes/pipeline-artifact-bundle.json).
 - Review gates: [`pipeline-quorum-review`](../../recipes/pipeline-quorum-review.json), [`pipeline-review-readiness`](../../recipes/pipeline-review-readiness.json).
-- Task-first workflows: [`pipeline-architect-coordinator`](../../recipes/pipeline-architect-coordinator.json), [`pipeline-research-synthesis`](../../recipes/pipeline-research-synthesis.json), [`pipeline-development-tasking`](../../recipes/pipeline-development-tasking.json), [`pipeline-checkpoint-continuation`](../../recipes/pipeline-checkpoint-continuation.json), [`pipeline-media-library`](../../recipes/pipeline-media-library.json), [`pipeline-room-swarm`](../../recipes/pipeline-room-swarm.json). For room swarms, choose `mode` from `consensus`, `pipeline`, `fanout`, or `pool`; prefer `roles_path` for custom role JSON and keep role `name` ASCII-safe for branch addresses. Use `locker=true` when the swarm needs a coordinator-locker-backed artifact lock and journal.
+- Task-first workflows: [`pipeline-architect-coordinator`](../../recipes/pipeline-architect-coordinator.json), [`pipeline-research-synthesis`](../../recipes/pipeline-research-synthesis.json), [`pipeline-development-tasking`](../../recipes/pipeline-development-tasking.json), [`pipeline-checkpoint-continuation`](../../recipes/pipeline-checkpoint-continuation.json), [`pipeline-media-library`](../../recipes/pipeline-media-library.json), [`pipeline-room-swarm`](../../recipes/pipeline-room-swarm.json). For room swarms, choose `mode` from `consensus`, `pipeline`, `fanout`, or `pool`; prefer `roles_path` for custom role JSON and keep role `name` ASCII-safe for branch addresses. Set `subagent_ttl_ms` when participant processes need a hard kill budget. Use `locker=true` when the swarm needs a coordinator-locker-backed artifact lock and journal.
 
 ### Utilities
 

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.29.0
+  version: 0.29.1
 ---
 
 # Swarm