@fradser/pi-agent-teams 0.5.2 → 0.6.0

package/src/spawner.ts

@@ -1,75 +1,30 @@
 /**
- * Teammate spawner — spawns real child Pi processes as workers.
+ * Teammate spawner — spawns named resident child Pi processes in RPC mode.
  *
- * A teammate becomes "real" by running its assigned task in a fresh,
- * non-interactive Pi CLI process (`--print`), with its own model and tool
- * scope. stdout/stderr are captured and reported back through the callback
- * so the board can record the outcome on the task.
+ * A teammate is a long-lived worker: it receives prompts on its control
+ * stream (stdin), streams JSON events on stdout, and suspends between wake
+ * ups without consuming tokens. The harness delivers new prompts via
+ * deliverPrompt (idle wake-up) and steering lines via sendWorkerSteer
+ * (mid-turn delivery). Wake-up sequences are uncapped: no turn-count or
+ * wall-clock limit terminates a working teammate; anomalies surface as
+ * leader notifications instead.
  */
 
-import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
-import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-import { extractTextContent } from "@fradser/pi-kit";
-import type { WorkerUsage } from "./types";
+import {
+  DEFAULT_TERMINATION_GRACE_MS,
+  extractTextContent,
+  resolvePiCli,
+  spawnPiChild,
+  terminateChildProcess,
+} from "@fradser/pi-kit";
+import type { ChildProcess } from "node:child_process";
+import type { WorkerUsage } from "./types.ts";
 
-/**
- * Build the one-task execution prompt for a spawned worker.
- *
- * A worker executes one bounded task run. It reports to the leader throughout
- * the run and then exits. The parent independently drains the worker outbox.
- */
-export function buildAutonomousPrompt(opts: {
-  name: string;
-  role: string;
-  prompt: string;
-  taskId?: string;
-  timeoutSec: number;
-}): string {
-  const taskLine = `\nAssigned task: [${opts.taskId}].\nWhen finished, you MUST call teammate_message with status="completed" to submit your FULL final deliverable.`;
-
-  return `You are a FULLY AUTONOMOUS teammate named "${opts.name}" (agent: ${opts.role}) in a pi multi-agent team run.
-
-=== ROLE PROMPT ===
-${opts.prompt}
-${taskLine}
-
-YOUR ROLE IN THIS RUN:
-1. Work directly on your assigned scope and declared paths. DAG upstream results are ALREADY injected into this prompt below; do not poll for them.
-2. Report plans, progress, and blockers with teammate_message. When finished, call teammate_message with status="completed" and put your FULL deliverable in the body. If blocked or failed, use status="failed" and explain the error.
-3. There is no peer or leader-to-worker message channel. Make decisions within the assigned task and report blockers instead of waiting for a reply.
-4. The hard wall-clock cap is ${opts.timeoutSec}s — manage your time budget, avoid unnecessary exploration, and deliver your final message before the deadline.
-
-BOUND CAPABILITIES:
-- teammate_message reports progress or a final deliverable to the team leader.`;
-}
-
-export interface SpawnPiWorkerOptions {
-  /** Worker identity — used to register the child so the panel can interrupt/stop it. */
-  workerName?: string;
-  /** Task description — the actual work the worker executes. */
-  description: string;
-  /** Optional model pattern for the child (e.g. "anthropic/claude-sonnet-4"). */
-  model?: string;
-  /** Optional execution-tool allowlist for the child. Capability tools are always appended. */
-  tools?: string[];
-  /** Environment additions bound to this worker process. */
-  env?: Record<string, string | undefined>;
-  /** Working directory for the child (defaults to the parent's cwd). */
-  cwd?: string;
-  /** Kill the worker after this many milliseconds (undefined = no timeout). */
-  timeoutMs?: number;
-  /** Output parsing mode. "json" (default) parses usage from JSONL output. */
-  mode?: "json" | "text";
-  /** Called whenever JSON-mode worker output reveals live model or tool activity. */
-  onUpdate?: (update: WorkerProgressUpdate) => void;
-  /** Called once with the captured output when the child exits. */
-  onExit: (result: WorkerProcessResult) => void;
-  /** Called when the child could not be spawned at all. */
-  onError?: (error: Error) => void;
-}
+const OUTPUT_CAP = 16_000;
 
 export interface WorkerProcessResult {
   pid: number;
@@ -78,220 +33,109 @@ export interface WorkerProcessResult {
   stdout: string;
   stderr: string;
   usage?: WorkerUsage;
-  timedOut: boolean;
 }
 
-/** Live state extracted from a spawned worker's JSON-mode output. */
+/** Live state extracted from a teammate's RPC output stream. */
 export interface WorkerProgressUpdate {
   text: string;
   activeTool?: string;
   liveThinking?: string;
+  /** Assistant turns observed in the current wake-up sequence. */
   turns: number;
+  /** True after the current sequence's final response. */
   finalResponse?: boolean;
 }
 
-/** A worker only succeeds after a normal zero exit; signals are failures. */
-export function isSuccessfulWorkerExit(result: Pick<WorkerProcessResult, "exitCode" | "signal" | "timedOut">): boolean {
-  return result.exitCode === 0 && result.signal === null && !result.timedOut;
-}
-
-/** A reported completion remains successful when the harness closes it or teardown observes a signal/timeout. */
-export function isCompletedWorkerExit(
-  result: Pick<WorkerProcessResult, "exitCode" | "signal" | "timedOut">,
-  reportedCompleted = false,
-): boolean {
-  return isSuccessfulWorkerExit(result) || reportedCompleted;
+/** A crashed teammate is one that closed without a normal zero exit. */
+export function isCleanExit(result: Pick<WorkerProcessResult, "exitCode" | "signal">): boolean {
+  return result.exitCode === 0 && result.signal === null;
 }
 
-export interface SpawnedWorker {
-  pid: number;
-}
-
-/** Bounded grace period before a cancellation escalates from SIGTERM to SIGKILL. */
-const CANCEL_GRACE_MS = 5_000;
-/** Give a terminally reported worker a short chance to exit cleanly. */
-export const POST_REPORT_GRACE_MS = 10_000;
-
-/**
- * Defers a close finalizer while the leader confirms a cancellation request.
- * A run ID is unique to one child process, so an old close event cannot affect
- * a later task run.
- */
-export class CancellationIntents {
-  private readonly finalizers = new Map<string, Array<(cancelled: boolean) => void>>();
-
-  begin(spawnId: string): boolean {
-    if (this.finalizers.has(spawnId)) return false;
-    this.finalizers.set(spawnId, []);
-    return true;
-  }
-
-  has(spawnId: string): boolean {
-    return this.finalizers.has(spawnId);
-  }
-
-  defer(spawnId: string, finalize: (cancelled: boolean) => void): boolean {
-    const pending = this.finalizers.get(spawnId);
-    if (!pending) return false;
-    pending.push(finalize);
-    return true;
-  }
-
-  resolve(spawnId: string, cancelled: boolean): boolean {
-    const pending = this.finalizers.get(spawnId);
-    if (!pending) return false;
-    try {
-      for (const finalize of pending) finalize(cancelled);
-    } finally {
-      this.finalizers.delete(spawnId);
-    }
-    return true;
-  }
-}
+// ── Process registry ──────────────────────────────────────────────
 
-/** Live workers by teammate name — lets the panel interrupt/stop a running worker. */
-const workers = new Map<string, ReturnType<typeof spawn>>();
+/** Live children by teammate name — powers steering, prompting, and shutdown. */
+const workers = new Map<string, ChildProcess>();
+const closedWorkers = new WeakSet<ChildProcess>();
 
-export interface WorkerTimeoutHandle {
-  cancel(): void;
-  dispose(): void;
-  wasCancelled(): boolean;
-  didTimeout(): boolean;
+function observeWorkerClose(name: string, child: ChildProcess): void {
+  child.once("close", () => {
+    closedWorkers.add(child);
+    if (workers.get(name) === child) workers.delete(name);
+  });
 }
 
-const workerTimeouts = new WeakMap<ReturnType<typeof spawn>, WorkerTimeoutHandle>();
-
-function isChildRunning(child: ReturnType<typeof spawn>): boolean {
-  return child.exitCode === null && child.signalCode === null;
+/** True only after Node has emitted the child process close event. */
+export function isWorkerCloseObserved(name: string): boolean {
+  const child = workers.get(name);
+  if (child) return closedWorkers.has(child);
+  // Not registered anymore: either never spawned or already unregistered by close.
+  return true;
 }
 
-export function registerWorkerTimeout(
-  child: ReturnType<typeof spawn>,
-  timeoutMs: number,
-): WorkerTimeoutHandle {
-  let cancelled = false;
-  let disposed = false;
-  let timedOut = false;
-  let timer: ReturnType<typeof setTimeout> | undefined;
-
-  const handle: WorkerTimeoutHandle = {
-    cancel() {
-      if (disposed) return;
-      cancelled = true;
-      if (timer) clearTimeout(timer);
-      disposed = true;
-      workerTimeouts.delete(child);
-    },
-    dispose() {
-      if (disposed) return;
-      if (timer) clearTimeout(timer);
-      disposed = true;
-      workerTimeouts.delete(child);
-    },
-    wasCancelled: () => cancelled,
-    didTimeout: () => timedOut,
-  };
+export { terminateChildProcess };
 
-  timer = setTimeout(() => {
-    if (disposed || cancelled) return;
-    if (!isChildRunning(child)) {
-      handle.dispose();
-      return;
-    }
-    try {
-      if (child.kill("SIGKILL")) timedOut = true;
-    } catch {
-      // A failed kill is not a timeout outcome; close/error will report the
-      // actual child result.
-    }
-  }, timeoutMs);
-  timer.unref?.();
-  workerTimeouts.set(child, handle);
-  return handle;
+/** Terminate a living teammate and wait until its child process has closed. */
+export async function terminateTeammate(name: string, graceMs = DEFAULT_TERMINATION_GRACE_MS): Promise<boolean> {
+  const child = workers.get(name);
+  if (!child) return false;
+  return terminateChildProcess(child, graceMs);
 }
 
-export function cancelWorkerTimeout(child: ReturnType<typeof spawn>): void {
-  workerTimeouts.get(child)?.cancel();
+export async function terminateAllTeammates(graceMs = DEFAULT_TERMINATION_GRACE_MS): Promise<Array<{ name: string; confirmedClosed: boolean }>> {
+  const entries = [...workers.entries()];
+  return Promise.all(entries.map(async ([name, child]) => ({
+    name,
+    confirmedClosed: closedWorkers.has(child) || await terminateChildProcess(child, graceMs),
+  })));
 }
 
-function waitForClose(child: ReturnType<typeof spawn>, timeoutMs: number): Promise<boolean> {
-  return new Promise((resolve) => {
-    let settled = false;
-    const onClose = () => finish(true);
-    const timer = setTimeout(() => finish(false), timeoutMs);
-    timer.unref?.();
-
-    function finish(closed: boolean): void {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      child.off("close", onClose);
-      resolve(closed);
-    }
+// ── Control stream ────────────────────────────────────────────────
 
-    child.once("close", onClose);
-  });
+function writeToControlStream(child: ChildProcess, line: unknown): boolean {
+  if (!child.stdin || child.stdin.destroyed || !child.stdin.writable) return false;
+  child.stdin.write(`${JSON.stringify(line)}\n`);
+  return true;
 }
 
 /**
- * Request a graceful child shutdown, escalate to SIGKILL when it resists, and
- * resolve only after a bounded wait observes the child `close` event.
+ * Deliver a new wake-up prompt to an idle teammate's control stream.
+ * This starts a fresh assistant sequence in the child process.
  */
-export async function terminateChildProcess(child: ReturnType<typeof spawn>, graceMs = CANCEL_GRACE_MS): Promise<boolean> {
-  cancelWorkerTimeout(child);
-  if (!isChildRunning(child)) return false;
-
-  const closedAfterTerm = waitForClose(child, graceMs);
-  try {
-    if (!child.kill("SIGTERM")) {
-      void closedAfterTerm;
-      return false;
-    }
-  } catch {
-    void closedAfterTerm;
-    return false;
-  }
-  if (await closedAfterTerm) return true;
-  if (!isChildRunning(child)) return false;
-
-  const closedAfterKill = waitForClose(child, graceMs);
-  try {
-    if (!child.kill("SIGKILL")) {
-      void closedAfterKill;
-      return false;
-    }
-  } catch {
-    void closedAfterKill;
-    return false;
-  }
-  return closedAfterKill;
-}
-
-/** Terminate a live worker and wait until its child process has closed. */
-export async function terminateWorker(name: string, graceMs = CANCEL_GRACE_MS): Promise<boolean> {
+export function deliverPrompt(name: string, message: string): boolean {
   const child = workers.get(name);
   if (!child) return false;
-  return terminateChildProcess(child, graceMs);
+  const sent = writeToControlStream(child, { type: "prompt", id: randomUUID(), message });
+  if (sent) beginSequence(name);
+  return sent;
 }
 
-/** Gracefully end a worker that has already reported a terminal task result. */
-export async function finishReportedWorker(name: string, graceMs = POST_REPORT_GRACE_MS): Promise<boolean> {
-  return terminateWorker(name, graceMs);
+/** Per-name stream states so prompt delivery can reset sequence boundaries. */
+const streamStates = new Map<string, StreamState>();
+
+function beginSequence(name: string): void {
+  const state = streamStates.get(name);
+  if (state) {
+    state.finalResponse = false;
+    state.text = "";
+    state.thinking = "";
+    clearActiveTools(state);
+  }
+  baselines.set(name, streamTurns.get(name) ?? 0);
 }
 
-/** Stop every live child before the leader discards the current session board. */
-export async function terminateAllWorkers(graceMs = CANCEL_GRACE_MS): Promise<void> {
-  const children = [...workers.values()];
-  await Promise.all(children.map((child) => (isChildRunning(child) ? terminateChildProcess(child, graceMs) : undefined)));
-  workers.clear();
+/** Send a mid-turn steer to a working teammate; no peer mailbox is involved. */
+export function sendWorkerSteer(name: string, message: string): boolean {
+  const child = workers.get(name);
+  return child ? writeToControlStream(child, { type: "steer", message }) : false;
 }
 
-const TASK_ARG_LIMIT = 8000;
-const OUTPUT_CAP = 16_000;
+// ── Stream parsing ────────────────────────────────────────────────
 
 type JsonEvent = {
   type?: string;
+  toolCallId?: string;
   toolName?: string;
+  args?: unknown;
   assistantMessageEvent?: {
     type?: string;
     delta?: string;
@@ -311,28 +155,31 @@ type JsonEvent = {
   };
 };
 
-/**
- * Parse the JSONL output of a `pi --print --mode json` worker run.
- * Returns the final assistant text and the last reported usage.
- */
-export function parseWorkerOutput(stdout: string): { text: string; usage?: WorkerUsage } {
-  const state = createWorkerStreamState();
-  for (const line of stdout.split("\n")) applyWorkerJsonLine(state, line);
-  return { text: state.text.trim(), usage: state.usage };
-}
-
-interface WorkerStreamState {
+interface StreamState {
   text: string;
   thinking: string;
   toolcallArgs: string;
   activeTool?: string;
+  activeTools: Map<string, string>;
+  /** Lifetime count of completed assistant messages. */
   turns: number;
   finalResponse?: boolean;
   usage?: WorkerUsage;
 }
 
-function createWorkerStreamState(): WorkerStreamState {
-  return { text: "", thinking: "", toolcallArgs: "", turns: 0 };
+function createStreamState(): StreamState {
+  return { text: "", thinking: "", toolcallArgs: "", activeTools: new Map(), turns: 0 };
+}
+
+function clearActiveTools(state: StreamState): void {
+  state.toolcallArgs = "";
+  state.activeTool = undefined;
+  state.activeTools.clear();
+}
+
+function toolExecutionLabel(toolName: string | undefined, args: unknown): string {
+  const serialized = typeof args === "string" ? args : JSON.stringify(args ?? {});
+  return toolcallLabel(serialized) ?? toolName ?? "tool";
 }
 
 /** Human-readable label from a partially streamed tool-call argument JSON. */
@@ -342,20 +189,26 @@ function toolcallLabel(rawArgs: string): string | undefined {
   try {
     const args = JSON.parse(trimmed) as Record<string, unknown>;
     const command = args.command;
-    if (typeof command === "string" && command.trim()) return `bash: ${truncateInline(command, 40)}`;
+    if (typeof command === "string" && command.trim()) return `bash: ${normalizeInline(command)}`;
     const filePath = args.path;
-    if (typeof filePath === "string" && filePath.trim()) return `file: ${path.basename(filePath.trim())}`;
+    if (typeof filePath === "string" && filePath.trim()) return `file: ${normalizeInline(path.basename(filePath.trim()))}`;
     const subject = args.subject;
-    if (typeof subject === "string" && subject.trim()) return `message: ${truncateInline(subject, 40)}`;
+    if (typeof subject === "string" && subject.trim()) return `message: ${normalizeInline(subject)}`;
     const query = args.query;
-    if (typeof query === "string" && query.trim()) return `search: ${truncateInline(query, 40)}`;
+    if (typeof query === "string" && query.trim()) return `search: ${normalizeInline(query)}`;
+    const to = args.to;
+    if (typeof to === "string" && to.trim() && typeof args.subject === "string") return `send: ${normalizeInline(args.subject)}`;
   } catch {
     // Incomplete JSON mid-stream — retry on the next delta.
   }
   return undefined;
 }
 
-function applyWorkerJsonLine(state: WorkerStreamState, line: string): boolean {
+function normalizeInline(text: string): string {
+  return text.replace(/\s+/g, " ").trim();
+}
+
+function applyStreamLine(state: StreamState, line: string): boolean {
   if (!line.trim()) return false;
   let event: JsonEvent;
   try {
@@ -363,21 +216,34 @@ function applyWorkerJsonLine(state: WorkerStreamState, line: string): boolean {
   } catch {
     return false;
   }
+  if (event.type === "tool_execution_start") {
+    state.activeTools.set(event.toolCallId ?? `tool-${state.activeTools.size}`, toolExecutionLabel(event.toolName, event.args));
+    state.activeTool = [...state.activeTools.values()].at(-1);
+    return true;
+  }
+  if (event.type === "tool_execution_end") {
+    if (event.toolCallId) state.activeTools.delete(event.toolCallId);
+    else state.activeTools.clear();
+    state.activeTool = [...state.activeTools.values()].at(-1);
+    return true;
+  }
   if (event.type !== "message_update") {
     if (event.type !== "message_end" || event.message?.role !== "assistant") return false;
     state.turns++;
+    clearActiveTools(state);
+    state.thinking = "";
     if (event.message.stopReason === "stop") state.finalResponse = true;
     const parts = extractTextContent(event.message.content, "");
     if (parts.trim()) state.text = parts;
     const u = event.message.usage;
     if (u) {
       state.usage = {
-        input: u.input ?? 0,
-        output: u.output ?? 0,
-        cacheRead: u.cacheRead ?? 0,
-        cacheWrite: u.cacheWrite ?? 0,
-        totalTokens: u.totalTokens ?? 0,
-        cost: u.cost?.total ?? 0,
+        input: (state.usage?.input ?? 0) + (u.input ?? 0),
+        output: (state.usage?.output ?? 0) + (u.output ?? 0),
+        cacheRead: (state.usage?.cacheRead ?? 0) + (u.cacheRead ?? 0),
+        cacheWrite: (state.usage?.cacheWrite ?? 0) + (u.cacheWrite ?? 0),
+        totalTokens: (state.usage?.totalTokens ?? 0) + (u.totalTokens ?? 0),
+        cost: (state.usage?.cost ?? 0) + (u.cost?.total ?? 0),
       };
     }
     return true;
@@ -386,14 +252,15 @@ function applyWorkerJsonLine(state: WorkerStreamState, line: string): boolean {
   if (!sub) return false;
   switch (sub.type) {
     case "text_delta":
+      state.activeTool = undefined;
       state.text += sub.delta ?? "";
       return true;
     case "thinking_delta":
+      state.activeTool = undefined;
       state.thinking += sub.delta ?? "";
       return true;
     case "toolcall_start":
-      state.toolcallArgs = "";
-      state.activeTool = undefined;
+      clearActiveTools(state);
       return true;
     case "toolcall_delta": {
       state.toolcallArgs += sub.delta ?? "";
@@ -401,23 +268,20 @@ function applyWorkerJsonLine(state: WorkerStreamState, line: string): boolean {
       if (label) state.activeTool = label;
       return true;
     }
-    case "toolcall_end": {
-      const tc = (sub as { toolCall?: { name?: string } }).toolCall;
-      // Prefer the richer delta-derived label (e.g. "bash: echo hello");
-      // fall back to the bare tool name only when no label could be parsed.
-      if (tc?.name && !state.activeTool) state.activeTool = tc.name;
-      state.toolcallArgs = "";
+    case "toolcall_end":
+      // Execution events own the activity label until the result arrives.
+      clearActiveTools(state);
       return true;
-    }
     default:
       return false;
   }
 }
 
-function truncateInline(text: string, cap: number): string {
-  const oneLine = text.replace(/\s+/g, " ").trim();
-  if (oneLine.length <= cap) return oneLine;
-  return `${oneLine.slice(0, cap).trimEnd()} ...`;
+/** Parse the final assistant text and accumulated usage from captured stdout. */
+export function parseTeammateOutput(stdout: string): { text: string; usage?: WorkerUsage } {
+  const state = createStreamState();
+  for (const line of stdout.split("\n")) applyStreamLine(state, line);
+  return { text: state.text.trim(), usage: state.usage };
 }
 
 function truncate(text: string, cap: number): string {
@@ -425,89 +289,51 @@ function truncate(text: string, cap: number): string {
   return `${text.slice(0, cap)}\n... [truncated ${text.length - cap} chars]`;
 }
 
-export interface PiCliResolution {
-  /** Command to execute — either a runtime (node/bun) or a `pi` binary. */
-  command: string;
-  /** Leading args: the CLI script path when running via a runtime, else empty. */
-  args: string[];
-}
-
-/** Whether a file is the pi coding-agent CLI script (verified against its package manifest). */
-function isPiPackageScript(filePath: string): boolean {
-  try {
-    const resolved = fs.realpathSync(filePath);
-    if (!/\.(mjs|cjs|js)$/.test(resolved)) return false;
-    let dir = path.dirname(resolved);
-    while (dir !== path.dirname(dir)) {
-      const pkgPath = path.join(dir, "package.json");
-      if (fs.existsSync(pkgPath)) {
-        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8")) as { name?: unknown };
-        return pkg.name === "@earendil-works/pi-coding-agent";
-      }
-      dir = path.dirname(dir);
-    }
-  } catch {
-    // Unreadable paths are simply not candidates.
-  }
-  return false;
-}
+// ── Resident spawn ────────────────────────────────────────────────
 
-/**
- * Resolve how to launch a worker Pi process.
- *
- * Resolution order:
- *   1. `process.argv[1]` — the current Pi process entry, verified against the
- *      package manifest (avoids mistaking unrelated scripts for the CLI).
- *   2. The installed `@earendil-works/pi-coding-agent` package's `dist/cli.js`.
- *   3. A `pi` binary on PATH (best effort).
- */
-export function resolvePiCli(): PiCliResolution {
-  const argv1 = process.argv[1];
-  if (argv1 && isPiPackageScript(argv1)) {
-    return { command: process.execPath, args: [path.resolve(argv1)] };
-  }
+/** Turn-count baseline per teammate at its most recent delivered prompt. */
+const baselines = new Map<string, number>();
+const streamTurns = new Map<string, number>();
 
-  try {
-    const entry = fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent"));
-    const packageRoot = path.dirname(path.dirname(entry));
-    const cliPath = path.join(packageRoot, "dist", "cli.js");
-    if (fs.existsSync(cliPath)) {
-      return { command: process.execPath, args: [cliPath] };
-    }
-  } catch {
-    // Package resolution is best-effort; fall through to PATH.
-  }
+export interface ResidentSpawnOptions {
+  /** Teammate name — the registry key for steering, prompting, and shutdown. */
+  workerName: string;
+  /** Optional kickoff prompt; omit to let the teammate idle immediately. */
+  description?: string;
+  model?: string;
+  /** Execution-tool allowlist; capability tools are always appended. */
+  tools?: string[];
+  env?: Record<string, string | undefined>;
+  cwd?: string;
+  onUpdate?: (update: WorkerProgressUpdate) => void;
+  onExit: (result: WorkerProcessResult) => void;
+  onError?: (error: Error) => void;
+}
 
-  return { command: "pi", args: [] };
+export interface SpawnedResident {
+  pid: number;
 }
 
+const WORKER_EXTENSION = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "index.ts");
+
 /**
- * Spawn a child Pi process that executes the task description in
- * non-interactive mode. Returns immediately with the child pid; the outcome
- * is delivered via `onExit` / `onError`.
+ * Spawn one resident child Pi process in RPC mode. Returns immediately with
+ * the child pid; outcomes arrive via onExit / onError. An empty description
+ * spawns an idle teammate that waits for its first delivered prompt.
  */
-export function spawnPiWorker(options: SpawnPiWorkerOptions): SpawnedWorker | { error: string } {
-  // resolvePiCli always resolves (worst case a "pi" binary on PATH); a missing
-  // binary surfaces later as a child "error" event through onError.
+export function spawnResident(options: ResidentSpawnOptions): SpawnedResident | { error: string } {
   const cli = resolvePiCli();
-  const workerExtension = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "index.ts");
   const args: string[] = [
     ...cli.args,
-    "--print",
-    "--mode",
-    "json",
+    "--mode", "rpc",
     "--no-session",
     "--no-extensions",
-    "--extension",
-    workerExtension,
+    "--extension", WORKER_EXTENSION,
   ];
   if (options.model) args.push("--model", options.model);
-  // Capability tools cannot be removed; execution tools are selected by the
-  // leader from the teammate's explicit configuration or role default.
-  const capabilityTools = ["teammate_message"];
-  const requestedTools = (options.tools ?? []).filter((tool) => !tool.startsWith("teammate_"));
-  const tools = [...new Set([...requestedTools, ...capabilityTools])];
-  args.push("--tools", tools.join(","));
+  const capabilityTools = ["send_message", "task_list", "task_claim", "task_submit"];
+  const requestedTools = (options.tools ?? []).filter((tool) => !capabilityTools.includes(tool));
+  args.push("--tools", [...new Set([...requestedTools, ...capabilityTools])].join(","));
 
   let tempDir: string | undefined;
   const cleanupTempDir = () => {
@@ -520,93 +346,91 @@ export function spawnPiWorker(options: SpawnPiWorkerOptions): SpawnedWorker | {
       tempDir = undefined;
     }
   };
-  const setupError = (error: unknown): { error: string } => ({
-    error: error instanceof Error ? error.message : String(error),
-  });
-
-  try {
-    const taskText = `Task: ${options.description}`;
-    if (taskText.length > TASK_ARG_LIMIT) {
-      tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "teammate-"));
-      const taskFile = path.join(tempDir, "task.md");
-      fs.writeFileSync(taskFile, taskText, { mode: 0o600 });
-      args.push(`@${taskFile}`);
-    } else {
-      args.push(taskText);
-    }
-  } catch (error) {
-    cleanupTempDir();
-    return setupError(error);
-  }
 
-  let child;
+  let child: ChildProcess;
   try {
-    child = spawn(cli.command, args, {
+    child = spawnPiChild(cli.command, args, {
       cwd: options.cwd,
       env: { ...process.env, ...options.env },
-      stdio: ["ignore", "pipe", "pipe"],
+      stdio: ["pipe", "pipe", "pipe"],
     });
   } catch (error) {
     cleanupTempDir();
-    return setupError(error);
+    return { error: error instanceof Error ? error.message : String(error) };
+  }
+  if (options.description && options.description.trim()) {
+    writeToControlStream(child, { type: "prompt", id: randomUUID(), message: options.description });
+    baselines.set(options.workerName, 0);
   }
-  if (options.workerName) workers.set(options.workerName, child);
+  observeWorkerClose(options.workerName, child);
+  workers.set(options.workerName, child);
 
   const stdoutChunks: string[] = [];
   const stderrChunks: string[] = [];
-  const streamState = createWorkerStreamState();
+  const streamState = createStreamState();
+  streamStates.set(options.workerName, streamState);
   let stdoutBuffer = "";
-  let timeoutHandle: WorkerTimeoutHandle | undefined;
   let settled = false;
+
   const emitProgress = () => options.onUpdate?.({
     text: truncate(streamState.text, OUTPUT_CAP),
     activeTool: streamState.activeTool,
     liveThinking: truncate(streamState.thinking, OUTPUT_CAP),
-    turns: streamState.turns,
+    turns: Math.max(0, streamState.turns - (baselines.get(options.workerName) ?? 0)),
     finalResponse: streamState.finalResponse,
   });
-  child.stdout.on("data", (chunk: Buffer) => {
+
+  child.stdout?.on("data", (chunk: Buffer) => {
     const text = chunk.toString();
-    stdoutChunks.push(text);
+    appendCapped(stdoutChunks, text, OUTPUT_CAP * 4);
     stdoutBuffer += text;
     const lines = stdoutBuffer.split("\n");
     stdoutBuffer = lines.pop() ?? "";
     let changed = false;
-    for (const line of lines) changed = applyWorkerJsonLine(streamState, line) || changed;
+    for (const line of lines) {
+      changed = applyStreamLine(streamState, line) || changed;
+    }
+    streamTurns.set(options.workerName, streamState.turns);
     if (changed) emitProgress();
   });
-  child.stderr.on("data", (chunk: Buffer) => stderrChunks.push(chunk.toString()));
-
-  if (options.timeoutMs) {
-    timeoutHandle = registerWorkerTimeout(child, options.timeoutMs);
-  }
+  child.stderr?.on("data", (chunk: Buffer) => appendCapped(stderrChunks, chunk.toString(), OUTPUT_CAP * 2));
 
   child.on("error", (error) => {
-    timeoutHandle?.dispose();
     cleanupTempDir();
     settled = true;
-    if (options.workerName && workers.get(options.workerName) === child) workers.delete(options.workerName);
+    // Keep the registry entry until close is observed so shutdown diagnostics
+    // can distinguish an error/exit code from a confirmed close event.
     options.onError?.(error);
   });
 
   child.on("close", (code, signal) => {
-    const timedOut = timeoutHandle?.didTimeout() ?? false;
-    timeoutHandle?.dispose();
     cleanupTempDir();
-    // A spawn failure already reported via onError (Node fires error then
-    // close) — do not double-report through onExit, which would let a failed
-    // spawn look like a successful 0-exit run.
+    if (workers.get(options.workerName) === child) workers.delete(options.workerName);
+    streamStates.delete(options.workerName);
+    baselines.delete(options.workerName);
+    streamTurns.delete(options.workerName);
+    // A spawn failure was already reported via onError (Node fires error then
+    // close) — do not double-report through onExit.
     if (settled) return;
-    if (options.workerName && workers.get(options.workerName) === child) workers.delete(options.workerName);
-    const rawStdout = stdoutChunks.join("");
-    const parsed = (options.mode ?? "json") === "json"
-      ? parseWorkerOutput(rawStdout)
-      : { text: rawStdout.trim(), usage: undefined };
-    const stdout = truncate(parsed.text, OUTPUT_CAP);
-    const stderr = truncate(stderrChunks.join("").trim(), OUTPUT_CAP);
-    options.onExit({ pid: child.pid ?? 0, exitCode: code, signal, stdout, stderr, usage: parsed.usage, timedOut });
+    const parsed = parseTeammateOutput(stdoutChunks.join(""));
+    options.onExit({
+      pid: child.pid ?? 0,
+      exitCode: code,
+      signal,
+      stdout: truncate(parsed.text, OUTPUT_CAP),
+      stderr: truncate(stderrChunks.join("").trim(), OUTPUT_CAP),
+      usage: parsed.usage,
+    });
   });
 
   return { pid: child.pid ?? 0 };
 }
 
+function appendCapped(chunks: string[], chunk: string, cap: number): void {
+  chunks.push(chunk);
+  let total = chunks.reduce((sum, value) => sum + value.length, 0);
+  while (total > cap && chunks.length > 1) {
+    total -= chunks.shift()?.length ?? 0;
+  }
+  if (total > cap && chunks.length === 1) chunks[0] = chunks[0].slice(-cap);
+}