bloby-bot 0.70.9 → 0.70.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bloby-bot",
-  "version": "0.70.9",
+  "version": "0.70.11",
   "releaseNotes": [
     "1. Fix: agent self-update ",
     "1",

package/supervisor/channels/manager.ts

@@ -542,6 +542,16 @@ export class ChannelManager {
     eventData: any,
     botName: string,
   ): void {
+    // Synthetic turns (background-task continuation turns the harness injects
+    // with no matching user push — currently only the pi harness tags these)
+    // are INVISIBLE to channel routing: they enqueued no routing target, so
+    // consuming/flushing/draining here would steal a concurrently-queued
+    // channel message's route and cross-wire replies. They are dashboard-
+    // broadcast + DB-persist only. consumedThisTurn/chunkBuf are deliberately
+    // untouched — synthetic tokens never enter the chunk buffer, and the
+    // surrounding real turns' accounting stays intact.
+    if (eventData?.synthetic) return;
+
     const convId = eventData?.conversationId as string | undefined;
 
     if (type === 'bot:token' && eventData?.token) {

package/supervisor/harnesses/pi/index.ts

@@ -16,6 +16,8 @@ import { log } from '../../../shared/logger.js';
 import { WORKSPACE_DIR } from '../../../shared/paths.js';
 import type { SavedFile } from '../../file-saver.js';
 import { assembleSystemPrompt } from '../../../worker/prompts/prompt-assembler.js';
+import { buildAgents } from '../../agents/index.js';
+import crypto from 'crypto';
 import fs from 'fs';
 import path from 'path';
 import type {
@@ -34,6 +36,7 @@ import { readPiAuth } from './auth-storage.js';
 import { streamProvider } from './providers/stream.js';
 import type { PiMessage } from './providers/types.js';
 import { toolDefsForProvider } from './tools/registry.js';
+import type { PiTaskHost } from './tools/types.js';
 
 // ── Live conversation state ────────────────────────────────────────────────
 
@@ -49,9 +52,47 @@ interface LiveConversation {
   pendingCount: number;
   /** 60ms micro-batcher for bot:token — collapses per-delta WS frame floods. */
   batcher: TokenBatcher;
+  /** Running background sub-agent tasks (Phase B). While non-empty, the
+   *  conversation reports idle:false (recycling deferred) and counts as busy
+   *  (backend restarts / self-updates deferred) so a task is never killed
+   *  mid-flight by housekeeping. */
+  tasks: Map<string, RunningTask>;
+  /** Set when a completed background task used file tools — OR'd into the next
+   *  bot:turn-complete (the continuation turn) so the backend restarts right
+   *  after the user hears "Done!", mirroring claude's usedTools capture of
+   *  sub-agent tool_use blocks. */
+  taskUsedFileTools: boolean;
+  /** Origin of each queued message, FIFO-aligned with inputQueue: 'user' for
+   *  pushMessage, 'synthetic' for task-completion injections. Shifted on
+   *  turn_started so the turn's events can be tagged synthetic — the channel
+   *  routing FIFO must skip turns that never enqueued a routing target
+   *  (Phase B review PI-B-1: an untagged continuation turn would steal a
+   *  concurrently-queued channel message's route). */
+  turnOrigins: ('user' | 'synthetic')[];
+  /** True while the in-flight turn originated from pushSyntheticMessage. */
+  currentTurnSynthetic: boolean;
   loopDone: Promise<void> | null;
 }
 
+interface RunningTask {
+  id: string;
+  description: string;
+  subagentType: string;
+  abortController: AbortController;
+  /** True when stopped via user:stop-task or conversation teardown. */
+  stopped: boolean;
+  /** True when the wall-clock task watchdog aborted it. */
+  timedOut: boolean;
+  startedAt: number;
+}
+
+/** Hard wall-clock cap per background task. Bounds the housekeeping wedge
+ *  (idle:false defers recycling; anyConversationBusy defers restarts and
+ *  self-updates) if a child ever hangs in a way the stream timeouts and the
+ *  Bash exit-settle can't catch. Generous: a 50-round coder task fits well
+ *  inside it. */
+const TASK_WALL_CLOCK_MS = 30 * 60_000;
+
 const liveConversations = new Map<string, LiveConversation>();
 
 /**
@@ -227,6 +268,220 @@ function resolveAuth(): { ok: true; auth: PiSessionAuth } | { ok: false; error:
   };
 }
 
+// ── Background sub-agents (Phase B — audit D4-1) ───────────────────────────
+
+/** Inject a system-originated message into the parent's queue (task completion).
+ *  Mirrors the Claude SDK's self-prompted continuation turn, with one
+ *  improvement: the resulting turn's events are tagged `synthetic: true`
+ *  (origin tracked via conv.turnOrigins) so the channel routing FIFO ignores
+ *  them entirely — a continuation enqueues no routing target, and an untagged
+ *  bot:response would steal a concurrently-queued channel message's route
+ *  (review PI-B-1). Synthetic turns are dashboard-broadcast + DB-persist only.
+ *  pendingCount/busy are maintained so idle stays accurate and the recycler
+ *  can't fire mid-continuation. No bot:typing (claude parity). */
+function pushSyntheticMessage(conv: LiveConversation, text: string): void {
+  conv.busy = true;
+  conv.pendingCount += 1;
+  conv.turnOrigins.push('synthetic');
+  conv.inputQueue.push({ role: 'user', content: [{ type: 'text', text }] });
+}
+
+/** coder.txt advertises the claude toolset ("Read, Write, Edit, Bash, Glob,
+ *  Grep") — swap in the child's REAL pi toolset so the sub-agent never chases
+ *  tools it doesn't have (audit D4-4). claude keeps its richer line. */
+function rewriteToolAccessLine(prompt: string, toolNames: string[]): string {
+  return prompt.replace(/You have full tool access:[^\n]*/i, `You have full tool access: ${toolNames.join(', ')}.`);
+}
+
+/** Compact human-readable descriptor of a child tool call for bot:task-progress. */
+function toolCallSummary(name: string, input: any): string {
+  const tail = (p: any) => (typeof p === 'string' ? p.split('/').slice(-2).join('/') : '');
+  switch (name.toLowerCase()) {
+    case 'bash': return `Bash: ${String(input?.description || input?.command || '').slice(0, 80)}`;
+    case 'read': return `Reading ${tail(input?.file_path)}`;
+    case 'write': return `Writing ${tail(input?.file_path)}`;
+    case 'edit': return `Editing ${tail(input?.file_path)}`;
+    default: return name;
+  }
+}
+
+/**
+ * Per-conversation task host: spawns an in-process child `createPiSession`
+ * per Task call, translates child events into the `bot:task-*` vocabulary
+ * (payload fields exactly as claude.ts:443-484 emits them), and injects the
+ * completion back into the parent's queue for the "Done!" continuation turn.
+ */
+function createTaskHost(conv: LiveConversation, getAuth: () => PiSessionAuth): PiTaskHost {
+  return {
+    spawn(req) {
+      const agents = buildAgents();
+      const cfg = agents[req.subagentType];
+      if (!cfg) {
+        return {
+          ok: false,
+          error: `Unknown subagent_type "${req.subagentType}". Available: ${Object.keys(agents).join(', ') || 'none'}.`,
+        };
+      }
+
+      const taskId = crypto.randomUUID().slice(0, 8);
+      const abortController = new AbortController();
+      const task: RunningTask = {
+        id: taskId,
+        description: req.description,
+        subagentType: req.subagentType,
+        abortController,
+        stopped: false,
+        timedOut: false,
+        startedAt: Date.now(),
+      };
+      conv.tasks.set(taskId, task);
+
+      // Wall-clock backstop: a hung child would otherwise pin idle:false and
+      // anyConversationBusy forever, deferring recycling/restarts/self-updates
+      // indefinitely (review PI-B lifecycle finding). Cleared in the finally.
+      const watchdog = setTimeout(() => {
+        if (!conv.tasks.has(taskId)) return;
+        log.warn(`[pi/task] Task ${taskId} hit the ${TASK_WALL_CLOCK_MS / 60_000}-minute wall clock — aborting`);
+        task.timedOut = true;
+        abortController.abort();
+      }, TASK_WALL_CLOCK_MS);
+
+      // Honor the agent config's tool restrictions (claude applies these via
+      // the SDK's tools/disallowedTools options — e.g. a future researcher
+      // agent with disallowedTools: ['Write','Edit']).
+      let childTools = toolDefsForProvider({ forSubagent: true });
+      if (Array.isArray(cfg.tools) && cfg.tools.length > 0) {
+        childTools = childTools.filter((t) => cfg.tools.includes(t.name));
+      }
+      if (Array.isArray(cfg.disallowedTools) && cfg.disallowedTools.length > 0) {
+        childTools = childTools.filter((t) => !cfg.disallowedTools.includes(t.name));
+      }
+      const systemPrompt = rewriteToolAccessLine(String(cfg.prompt || ''), childTools.map((t) => t.name));
+
+      let summaryText = '';
+      let errorText = '';
+      let usedFileTools = false;
+      let toolUses = 0;
+      // Outcome from the session's turn_complete — the error EVENT is
+      // suppressed when partial text streamed (D6-2 precedence), so these are
+      // how the host learns a child that streamed text still failed
+      // (review PI-B-CHILD-1: such tasks must not be reported 'completed').
+      let childErrored = false;
+      let childErrorMsg = '';
+      let childCapHit = false;
+      let lastUsage: { inputTokens?: number; outputTokens?: number; cacheReadTokens?: number; cacheCreationTokens?: number } | undefined;
+
+      const session = createPiSession({
+        getAuth,
+        systemPrompt,
+        tools: childTools,
+        cwd: WORKSPACE_DIR,
+        abortController,
+        maxToolRounds: typeof cfg.maxTurns === 'number' ? cfg.maxTurns : 50,
+        onEvent: (evt: PiSessionEvent) => {
+          switch (evt.type) {
+            case 'tool_use':
+              toolUses += 1;
+              conv.batcher.flush();
+              conv.onMessage('bot:task-progress', {
+                conversationId: conv.id,
+                taskId,
+                summary: toolCallSummary(evt.name, evt.input),
+                lastTool: evt.name,
+                usage: { tool_uses: toolUses, duration_ms: Date.now() - task.startedAt },
+              });
+              break;
+            case 'text_end':
+              summaryText = evt.text;
+              break;
+            case 'error':
+              errorText = evt.error;
+              break;
+            case 'turn_complete':
+              usedFileTools = usedFileTools || evt.usedFileTools;
+              if (evt.usage) lastUsage = evt.usage;
+              if (evt.errored) {
+                childErrored = true;
+                childErrorMsg = evt.errorMsg || childErrorMsg;
+              }
+              if (evt.roundCapHit) childCapHit = true;
+              break;
+          }
+        },
+      });
+
+      const queue = createAsyncQueue<PiMessage>();
+      queue.push({ role: 'user', content: [{ type: 'text', text: req.prompt }] });
+      queue.end();
+
+      log.info(`[pi/task] ──── SUB-AGENT STARTED ──── id=${taskId} type=${req.subagentType} "${req.description}"`);
+      // Task events bypass translateAndEmit, so flush the token batcher first —
+      // bot:task-created COMMITS the dashboard stream buffer (useBlobyChat),
+      // and a batch flushed after it would mis-slice committedTextLength.
+      conv.batcher.flush();
+      conv.onMessage('bot:task-created', {
+        conversationId: conv.id,
+        taskId,
+        description: req.description,
+        type: req.subagentType,
+      });
+
+      void (async () => {
+        try {
+          await session.run(queue);
+        } catch (err: any) {
+          errorText = errorText || err?.message || String(err);
+        } finally {
+          clearTimeout(watchdog);
+          conv.tasks.delete(taskId);
+          // Honest status (review PI-B-CHILD-1): an error or round-cap exit is
+          // 'failed' even when partial text streamed — the parent must not
+          // relay half-done work as success.
+          const failed = task.timedOut || childErrored || childCapHit || !!errorText || !summaryText;
+          const status = task.stopped ? 'stopped' : failed ? 'failed' : 'completed';
+          let summary = summaryText || errorText || '(the agent produced no output)';
+          if (task.timedOut) {
+            summary += `\n\n[The task was aborted after ${TASK_WALL_CLOCK_MS / 60_000} minutes — work is incomplete.]`;
+          } else if (childCapHit) {
+            summary += '\n\n[The task hit its tool-round limit before finishing — work may be incomplete.]';
+          } else if (childErrored && summaryText) {
+            summary += `\n\n[The task hit an error before finishing: ${childErrorMsg || errorText || 'unknown error'}]`;
+          }
+          const u = lastUsage;
+          const totalTokens = u
+            ? (u.inputTokens || 0) + (u.outputTokens || 0) + (u.cacheReadTokens || 0) + (u.cacheCreationTokens || 0)
+            : 0;
+          log.info(
+            `[pi/task] ──── SUB-AGENT ${status.toUpperCase()} ──── id=${taskId} ` +
+            `tools=${toolUses} ${Math.round((Date.now() - task.startedAt) / 1000)}s summary=${summary.slice(0, 160)}`,
+          );
+          conv.batcher.flush();
+          conv.onMessage('bot:task-done', {
+            conversationId: conv.id,
+            taskId,
+            status,
+            summary,
+            usage: { tool_uses: toolUses, duration_ms: Date.now() - task.startedAt, total_tokens: totalTokens },
+          });
+          if (usedFileTools) conv.taskUsedFileTools = true;
+
+          // Drive the user-facing continuation turn — unless the conversation
+          // itself is gone (ended/recycled), in which case the report dies with
+          // it (claude parity: the SDK subprocess dies too).
+          if (liveConversations.get(conv.id) === conv && !conv.abortController.signal.aborted) {
+            const note = task.stopped
+              ? `[System: the background task "${req.description}" was stopped by the user. Acknowledge that briefly in your own voice — never mention agents, tasks, or system messages.]`
+              : `[System: background task "${req.description}" ${status}.]\n\nResult summary:\n${summary}\n\nRelay the outcome to the user concisely in your own voice (never mention agents, tasks, ids, or system messages). If it failed, say what went wrong and offer a next step.`;
+            pushSyntheticMessage(conv, note);
+          }
+        }
+      })();
+
+      return { ok: true, taskId };
+    },
+  };
+}
+
 /** Convert a saved RecentMessage[] into the provider-neutral PiMessage[]. */
 function recentToPiMessages(messages: RecentMessage[] | undefined): PiMessage[] {
   if (!messages?.length) return [];
@@ -298,9 +553,20 @@ export async function startConversation(
     onMessage,
     busy: false,
     pendingCount: 0,
-    batcher: createTokenBatcher((text) => onMessage('bot:token', { conversationId, token: text })),
+    batcher: null as unknown as TokenBatcher, // set right below (needs conv for the synthetic tag)
+    tasks: new Map(),
+    taskUsedFileTools: false,
+    turnOrigins: [],
+    currentTurnSynthetic: false,
     loopDone: null,
   };
+  conv.batcher = createTokenBatcher((text) =>
+    onMessage('bot:token', {
+      conversationId,
+      token: text,
+      ...(conv.currentTurnSynthetic ? { synthetic: true } : {}),
+    }),
+  );
   liveConversations.set(conversationId, conv);
 
   // Re-resolve auth on every provider round so a key/model fix in the wizard
@@ -319,6 +585,7 @@ export async function startConversation(
     tools: toolDefsForProvider(),
     cwd: WORKSPACE_DIR,
     abortController,
+    taskHost: createTaskHost(conv, getAuth),
     onEvent: (evt: PiSessionEvent) => {
       translateAndEmit(conv, evt);
     },
@@ -358,16 +625,28 @@ function translateAndEmit(conv: LiveConversation, evt: PiSessionEvent) {
   // invariant both depend on it.
   conv.batcher.flush();
 
+  // Synthetic tag for every event of a continuation turn (origin shifted at
+  // turn_started): the channel routing FIFO must treat these turns as
+  // invisible — they enqueued no routing target, so consuming one would steal
+  // a queued channel message's route (review PI-B-1).
+  const syn = conv.currentTurnSynthetic ? { synthetic: true } : {};
+
   switch (evt.type) {
     case 'turn_started':
+      conv.currentTurnSynthetic = conv.turnOrigins.shift() === 'synthetic';
       // No bloby event for this — `bot:typing` is already emitted by pushMessage().
       break;
     case 'text_end':
-      conv.onMessage('bot:response', { conversationId: conv.id, content: evt.text });
+      conv.onMessage('bot:response', { conversationId: conv.id, content: evt.text, ...syn });
       break;
-    case 'tool_use':
-      conv.onMessage('bot:tool', { conversationId: conv.id, name: evt.name, input: evt.input });
+    case 'tool_use': {
+      // House vocabulary: claude's delegation tool is named Task; the pi
+      // prompt's 'Agent' alias resolves to the same tool — normalize the
+      // event so consumers see one name.
+      const toolName = evt.name === 'Agent' || evt.name === 'agent' ? 'Task' : evt.name;
+      conv.onMessage('bot:tool', { conversationId: conv.id, name: toolName, input: evt.input, ...syn });
       break;
+    }
     case 'tool_result':
       // Not surfaced yet (Phase D: translate to a bot:tool progress pulse).
       break;
@@ -375,9 +654,16 @@ function translateAndEmit(conv: LiveConversation, evt: PiSessionEvent) {
       conv.busy = false;
       // One turn-complete per pushed message (D1-1 restored that invariant);
       // idle gates the supervisor's proactive recycling so it never fires with
-      // a message still queued — claude.ts pendingCount semantics exactly.
+      // a message still queued OR a background task still running — recycling
+      // mid-task would kill the task (claude has the same teardown semantics,
+      // but its idle flag doesn't guard tasks; this is strictly safer).
       conv.pendingCount = Math.max(0, conv.pendingCount - 1);
-      const idle = conv.pendingCount === 0;
+      const idle = conv.pendingCount === 0 && conv.tasks.size === 0;
+      // A finished background task's file edits restart the backend on the
+      // very next turn boundary (the continuation turn) — claude captures
+      // sub-agent tool_use blocks into the parent's usedTools the same way.
+      const usedFileTools = evt.usedFileTools || conv.taskUsedFileTools;
+      conv.taskUsedFileTools = false;
       // Prompt occupancy of the last provider round — input + cache reads +
       // cache writes, exactly claude.ts's contextTokens math. Output tokens
       // are NOT added (claude doesn't either; the recycler's 70% threshold
@@ -387,12 +673,13 @@ function translateAndEmit(conv: LiveConversation, evt: PiSessionEvent) {
         : 0;
       conv.onMessage('bot:turn-complete', {
         conversationId: conv.id,
-        usedFileTools: evt.usedFileTools,
+        usedFileTools,
         contextTokens,
         contextWindow: evt.contextWindow || 0,
         idle,
+        ...syn,
       });
-      log.info(`[pi/conversation] ──── TURN COMPLETE ────  busy=false ctx=${contextTokens}/${evt.contextWindow || 'n/a'} idle=${idle}`);
+      log.info(`[pi/conversation] ──── TURN COMPLETE ────  busy=false ctx=${contextTokens}/${evt.contextWindow || 'n/a'} idle=${idle} tasks=${conv.tasks.size}`);
       break;
     }
     case 'error': {
@@ -405,7 +692,7 @@ function translateAndEmit(conv: LiveConversation, evt: PiSessionEvent) {
         : evt.kind === 'auth'
           ? ' I\'ll reconnect with the new key as soon as it\'s saved.'
           : '';
-      conv.onMessage('bot:error', { conversationId: conv.id, error: `${evt.error}${remedy}` });
+      conv.onMessage('bot:error', { conversationId: conv.id, error: `${evt.error}${remedy}`, ...syn });
       if (fatal) {
         // Unrecoverable for this session (audit D6-4): an over-window history
         // would re-fail on every future turn, and a dead key has no business
@@ -435,6 +722,7 @@ export function pushMessage(
   log.info(`[pi/conversation] ──── PUSH MESSAGE ──── busy=${conv.busy} pending=${conv.pendingCount + 1}`);
   conv.busy = true;
   conv.pendingCount += 1;
+  conv.turnOrigins.push('user');
   conv.inputQueue.push(buildUserMessage(content, attachments, savedFiles));
   conv.onMessage('bot:typing', { conversationId });
   return true;
@@ -445,6 +733,14 @@ export function endConversation(conversationId: string): void {
   if (!conv) return;
 
   log.info(`[pi/conversation] ──── ENDING CONVERSATION ${conversationId} ────`);
+  // Background tasks die with the conversation (claude parity — the SDK
+  // subprocess takes its tasks down too). Their finallys still emit
+  // bot:task-done {status:'stopped'} so dashboard task cards don't spin
+  // forever; the completion injection is skipped (conv gone).
+  for (const task of conv.tasks.values()) {
+    task.stopped = true;
+    task.abortController.abort();
+  }
   conv.batcher.discard();
   conv.inputQueue.end();
   conv.abortController.abort();
@@ -455,16 +751,29 @@ export function isConversationBusy(conversationId: string): boolean {
   return liveConversations.get(conversationId)?.busy || false;
 }
 
-/** True if ANY live conversation in this harness is mid-turn. Used by the supervisor to defer
- *  backend restarts during channel/Alexa turns (which don't set the dashboard's agentQueryActive). */
+/** True if ANY live conversation in this harness is mid-turn OR has a background
+ *  sub-agent running. Used by the supervisor to defer backend restarts and
+ *  self-updates — a restart mid-task would kill the task's work in flight. */
 export function anyConversationBusy(): boolean {
-  for (const c of liveConversations.values()) if (c.busy) return true;
+  for (const c of liveConversations.values()) {
+    if (c.busy || c.tasks.size > 0) return true;
+  }
   return false;
 }
 
-/** Pi has no sub-agents yet; provided for interface compatibility. */
-export async function stopSubAgentTask(_conversationId: string, _taskId: string): Promise<void> {
-  // no-op for Phase 1
+/** Stop a specific background sub-agent task (dashboard user:stop-task). The
+ *  child's teardown emits bot:task-done {status:'stopped'} and injects a brief
+ *  acknowledgement turn into the parent. */
+export async function stopSubAgentTask(conversationId: string, taskId: string): Promise<void> {
+  const conv = liveConversations.get(conversationId);
+  const task = conv?.tasks.get(taskId);
+  if (!task) {
+    log.warn(`[pi/task] Cannot stop task ${taskId} — not running in conversation ${conversationId}`);
+    return;
+  }
+  log.info(`[pi/task] Stopping sub-agent task ${taskId}`);
+  task.stopped = true;
+  task.abortController.abort();
 }
 
 /** Pi has no pre-warm step (no subprocess), but the interface requires this. */

package/supervisor/harnesses/pi/session.ts

@@ -38,7 +38,7 @@ import type { PiMessage, PiStreamEvent, PiToolDef, PiContentBlock, PiUsage, PiEr
 import { sleep } from './providers/retry.js';
 import type { AsyncQueue } from './async-queue.js';
 import { findTool } from './tools/registry.js';
-import type { PiTool } from './tools/types.js';
+import type { PiTool, PiTaskHost } from './tools/types.js';
 
 export type PiSessionEvent =
   | { type: 'turn_started' }
@@ -46,7 +46,22 @@ export type PiSessionEvent =
   | { type: 'text_end'; text: string }
   | { type: 'tool_use'; id: string; name: string; input: any }
   | { type: 'tool_result'; toolUseId: string; name: string; isError?: boolean }
-  | { type: 'turn_complete'; usedFileTools: boolean; usage?: PiUsage; contextWindow?: number }
+  | {
+      type: 'turn_complete';
+      usedFileTools: boolean;
+      usage?: PiUsage;
+      contextWindow?: number;
+      /** True when the turn ended on a provider error. NOTE: the `error` EVENT
+       *  is suppressed when partial text streamed (D6-2 response-over-error
+       *  precedence, designed for the watched parent stream) — these fields
+       *  are how an UNwatched consumer (the task host) learns the turn failed,
+       *  so a child that streamed text then died isn't reported 'completed'. */
+      errored?: boolean;
+      errorKind?: PiErrorKind;
+      errorMsg?: string;
+      /** True when the turn was cut off by the tool-round budget mid-task. */
+      roundCapHit?: boolean;
+    }
   | { type: 'error'; error: string; kind?: PiErrorKind };
 
 /** Everything the providers need that can change while a session is alive. */
@@ -78,6 +93,17 @@ export interface PiSessionInit {
   tools?: PiToolDef[];
   /** Resolved every time a tool fires (registry → run). */
   cwd: string;
+  /**
+   * Background sub-agent host (Phase B). Set only on PARENT live sessions —
+   * threaded into PiToolContext so the Task tool can spawn; child sessions
+   * leave it unset (no grandchildren, Claude SDK parity).
+   */
+  taskHost?: PiTaskHost;
+  /**
+   * Per-turn tool-round budget. Parents keep the default; sub-agent children
+   * get their agent config's maxTurns (e.g. coder: 50).
+   */
+  maxToolRounds?: number;
   /** Used to interrupt in-flight provider calls when the session ends. */
   abortController: AbortController;
   /** Caller's event sink — translated to bloby's `bot:*` events one layer up. */
@@ -199,7 +225,7 @@ export function createPiSession(init: PiSessionInit): PiSession {
       };
     }
     try {
-      return await tool.run(call.input, { cwd: init.cwd, signal: init.abortController.signal });
+      return await tool.run(call.input, { cwd: init.cwd, signal: init.abortController.signal, tasks: init.taskHost });
     } catch (err: any) {
       return { output: `Tool ${call.name} threw: ${err?.message || err}`, isError: true };
     }
@@ -218,8 +244,12 @@ export function createPiSession(init: PiSessionInit): PiSession {
     let turnErrorMsg: string | undefined;
     let turnErrorKind: PiErrorKind | undefined;
 
-    for (let round = 0; round < MAX_TOOL_ROUNDS; round++) {
-      if (init.abortController.signal.aborted) break;
+    const maxRounds = Math.max(1, init.maxToolRounds ?? MAX_TOOL_ROUNDS);
+    // True only when the for-loop runs out of rounds with the model still
+    // mid-task — every intentional exit (done, errored, aborted) clears it.
+    let roundCapHit = true;
+    for (let round = 0; round < maxRounds; round++) {
+      if (init.abortController.signal.aborted) { roundCapHit = false; break; }
       // The separator condition is decided BEFORE the round so the round can
       // emit it ahead of its first token (claude.ts ordering — see runOneRound).
       const needsSeparator = accumulatedText.length > 0 && !accumulatedText.endsWith('\n');
@@ -277,6 +307,7 @@ export function createPiSession(init: PiSessionInit): PiSession {
         turnErrored = true;
         turnErrorMsg = res.errorMsg;
         turnErrorKind = res.errorKind;
+        roundCapHit = false;
         break;
       }
 
@@ -301,7 +332,7 @@ export function createPiSession(init: PiSessionInit): PiSession {
       }
 
       // No tool calls ⇒ the model is done with this turn.
-      if (toolUses.length === 0) break;
+      if (toolUses.length === 0) { roundCapHit = false; break; }
     }
 
     // Turn-end emission order (audit D6-2, mirrors claude.ts:394-401):
@@ -325,7 +356,16 @@ export function createPiSession(init: PiSessionInit): PiSession {
         init.onEvent({ type: 'error', error: turnErrorMsg || 'Provider turn failed', kind: turnErrorKind });
       }
       const usedFileTools = Array.from(usedTools).some((t) => FILE_TOOL_NAMES.has(t));
-      init.onEvent({ type: 'turn_complete', usedFileTools, usage: lastUsage, contextWindow: lastContextWindow });
+      init.onEvent({
+        type: 'turn_complete',
+        usedFileTools,
+        usage: lastUsage,
+        contextWindow: lastContextWindow,
+        errored: turnErrored || undefined,
+        errorKind: turnErrorKind,
+        errorMsg: turnErrorMsg,
+        roundCapHit: roundCapHit || undefined,
+      });
     }
   }
 
@@ -342,7 +382,14 @@ export function createPiSession(init: PiSessionInit): PiSession {
           // and chat aren't wedged. Skip when aborting (teardown emits conversation-ended).
           // usedFileTools=false is the safe default (it only governs whether to auto-restart now).
           if (!init.abortController.signal.aborted) {
-            init.onEvent({ type: 'turn_complete', usedFileTools: false, usage: lastUsage, contextWindow: lastContextWindow });
+            init.onEvent({
+              type: 'turn_complete',
+              usedFileTools: false,
+              usage: lastUsage,
+              contextWindow: lastContextWindow,
+              errored: true,
+              errorMsg: err?.message || String(err),
+            });
           }
         }
       }

package/supervisor/harnesses/pi/tools/bash.ts

@@ -38,12 +38,26 @@ export const bashTool: PiTool = {
       let timedOut = false;
       let settled = false;
 
+      // detached:true gives the child its own process group so kills reach
+      // grandchildren too — a SIGKILLed direct child can leave orphans holding
+      // the stdio pipes, and 'close' (which waits for the pipes) then never
+      // fires, hanging the tool promise and wedging the whole turn.
       const child = spawn('bash', ['-lc', command], {
         cwd: ctx.cwd,
         env: process.env,
         stdio: ['ignore', 'pipe', 'pipe'],
+        detached: true,
       });
 
+      const killTree = () => {
+        try {
+          if (child.pid) process.kill(-child.pid, 'SIGKILL');
+          else child.kill('SIGKILL');
+        } catch {
+          try { child.kill('SIGKILL'); } catch {}
+        }
+      };
+
       const append = (chunk: Buffer) => {
         if (truncated) return;
         const remaining = OUTPUT_CAP_BYTES - Buffer.byteLength(out, 'utf-8');
@@ -65,23 +79,15 @@ export const bashTool: PiTool = {
 
       const timer = setTimeout(() => {
         timedOut = true;
-        try { child.kill('SIGKILL'); } catch {}
+        killTree();
       }, timeout);
 
       const onAbort = () => {
-        try { child.kill('SIGKILL'); } catch {}
+        killTree();
       };
       ctx.signal?.addEventListener('abort', onAbort);
 
-      child.on('error', (err) => {
-        if (settled) return;
-        settled = true;
-        clearTimeout(timer);
-        ctx.signal?.removeEventListener('abort', onAbort);
-        resolve({ output: `Failed to spawn command: ${err.message}`, isError: true });
-      });
-
-      child.on('close', (code, signal) => {
+      const finish = (code: number | null, signal: NodeJS.Signals | null) => {
         if (settled) return;
         settled = true;
         clearTimeout(timer);
@@ -103,6 +109,23 @@ export const bashTool: PiTool = {
             isError: true,
           });
         }
+      };
+
+      child.on('error', (err) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        ctx.signal?.removeEventListener('abort', onAbort);
+        resolve({ output: `Failed to spawn command: ${err.message}`, isError: true });
+      });
+
+      // 'close' is the normal settle point (all output drained). But orphaned
+      // grandchildren can inherit the stdio pipes and keep them open after the
+      // direct child died — settle from 'exit' after a short drain grace so the
+      // tool promise can never hang the turn on a pipe that won't close.
+      child.on('close', (code, signal) => finish(code, signal));
+      child.on('exit', (code, signal) => {
+        setTimeout(() => finish(code, signal), 1500);
       });
     });
   },

package/supervisor/harnesses/pi/tools/registry.ts

@@ -1,8 +1,10 @@
 /**
  * Tool registry — the bag of tools the pi session passes to the model.
  *
- * Phase 2 ships the four core coding tools. Phase 3 or later will add Grep,
- * Glob, LS, NotebookEdit, etc. so the surface fully matches Claude SDK's.
+ * Read/Write/Edit/Bash mirror the Claude SDK tools; Task is the background
+ * sub-agent delegator (Phase B of the parity plan). Grep, Glob, LS,
+ * NotebookEdit etc. are still pending (Phase D) to fully match Claude SDK's
+ * surface.
  */
 import type { PiTool } from './types.js';
 import type { PiToolDef } from '../providers/types.js';
@@ -10,8 +12,9 @@ import { readTool } from './read.js';
 import { writeTool } from './write.js';
 import { editTool } from './edit.js';
 import { bashTool } from './bash.js';
+import { taskTool, taskToolDef } from './task.js';
 
-export const PI_TOOLS: PiTool[] = [readTool, writeTool, editTool, bashTool];
+export const PI_TOOLS: PiTool[] = [readTool, writeTool, editTool, bashTool, taskTool];
 
 const TOOL_BY_NAME = new Map<string, PiTool>();
 for (const t of PI_TOOLS) {
@@ -20,15 +23,28 @@ for (const t of PI_TOOLS) {
   // common aliases so we don't 404 a legitimate call over a casing nit.
   TOOL_BY_NAME.set(t.name.toLowerCase(), t);
 }
+// The pi system prompt calls background delegation "the Agent tool" (claude
+// heritage) — alias it so a model following the prompt verbatim still lands
+// on the Task implementation.
+TOOL_BY_NAME.set('Agent', taskTool);
+TOOL_BY_NAME.set('agent', taskTool);
 
 export function findTool(name: string): PiTool | undefined {
   return TOOL_BY_NAME.get(name) || TOOL_BY_NAME.get(name.toLowerCase());
 }
 
-export function toolDefsForProvider(): PiToolDef[] {
-  return PI_TOOLS.map((t) => ({
-    name: t.name,
-    description: t.description,
-    inputSchema: t.inputSchema,
-  }));
+export function toolDefsForProvider(opts?: { forSubagent?: boolean }): PiToolDef[] {
+  const defs: PiToolDef[] = [];
+  for (const t of PI_TOOLS) {
+    if (t.name === 'Task') {
+      // Children cannot spawn grandchildren (Claude SDK parity) — a child that
+      // hallucinates a Task call still fails gracefully (ctx.tasks is unset).
+      if (opts?.forSubagent) continue;
+      // Rebuilt fresh so agent-roster/prompt edits apply per session start.
+      defs.push(taskToolDef());
+      continue;
+    }
+    defs.push({ name: t.name, description: t.description, inputSchema: t.inputSchema });
+  }
+  return defs;
 }

package/supervisor/harnesses/pi/tools/task.ts

@@ -0,0 +1,108 @@
+/**
+ * Task tool — background sub-agent delegation (audit D4-1, Phase B).
+ *
+ * Mirrors the Claude Agent SDK's Task tool contract and feel:
+ *   - the model calls Task({description, prompt, subagent_type})
+ *   - the tool returns IMMEDIATELY with an acknowledgement, so the parent turn
+ *     ends in seconds and the chat stays fully conversational
+ *   - the child runs as an in-process `createPiSession` (Bloby owns the agent
+ *     loop, so no subprocess is needed — unlike upstream pi's subagent
+ *     extension, which must spawn the pi CLI)
+ *   - completion is injected back into the parent's input queue as a synthetic
+ *     message that drives the user-facing "Done!" continuation turn
+ *
+ * Also registered under the alias 'Agent' (registry.ts): the pi system prompt
+ * sells "the Agent tool" — with this tool live, those sections are true as
+ * written, closing the audit's D4-2 finding without a prompt edit.
+ *
+ * Agent definitions come from `supervisor/agents/index.ts:buildAgents()` —
+ * the same roster the Claude harness uses, so both harnesses stay in sync.
+ */
+import type { PiTool } from './types.js';
+import type { PiToolDef } from '../providers/types.js';
+import { buildAgents } from '../../../agents/index.js';
+
+/**
+ * Tool definition with a FRESH subagent enum — built per session start (not at
+ * module load) so prompt-file/roster edits apply without a supervisor restart,
+ * and so the workspace is guaranteed to exist when prompts are read.
+ */
+export function taskToolDef(): PiToolDef {
+  const agents = buildAgents();
+  const names = Object.keys(agents);
+  return {
+    name: 'Task',
+    description:
+      'Delegate heavy work to a background sub-agent and keep chatting while it runs. ' +
+      'Returns immediately — you will automatically receive the result when the agent finishes, ' +
+      'so acknowledge the user briefly and end your turn. ' +
+      'Available agents: ' +
+      (names.map((n) => `${n} (${agents[n].description})`).join('; ') || 'none configured'),
+    inputSchema: {
+      type: 'object',
+      properties: {
+        description: {
+          type: 'string',
+          description: 'Short (3-5 word) description of the task, shown to the user as a progress card.',
+        },
+        prompt: {
+          type: 'string',
+          description: 'Complete, self-contained instructions for the sub-agent. It cannot ask follow-up questions — include every detail it needs.',
+        },
+        subagent_type: {
+          type: 'string',
+          ...(names.length > 0 ? { enum: names } : {}),
+          description: 'Which sub-agent to delegate to.',
+        },
+      },
+      required: ['description', 'prompt', 'subagent_type'],
+    },
+  };
+}
+
+export const taskTool: PiTool = {
+  name: 'Task',
+  description: 'Delegate heavy work to a background sub-agent.',
+  // Static placeholder (no file I/O at module load) — providers receive the
+  // dynamic enum schema from taskToolDef() via registry.toolDefsForProvider.
+  inputSchema: {
+    type: 'object',
+    properties: {
+      description: { type: 'string' },
+      prompt: { type: 'string' },
+      subagent_type: { type: 'string' },
+    },
+    required: ['description', 'prompt', 'subagent_type'],
+  },
+
+  async run(input, ctx) {
+    if (!ctx.tasks) {
+      return {
+        output:
+          'The Task tool is not available in this context — do the work yourself with your other tools.',
+        isError: true,
+      };
+    }
+    const description = typeof input?.description === 'string' ? input.description.trim() : '';
+    const prompt = typeof input?.prompt === 'string' ? input.prompt.trim() : '';
+    const subagentType = typeof input?.subagent_type === 'string' ? input.subagent_type.trim() : '';
+    if (!prompt) {
+      return { output: 'Task requires `prompt` — complete instructions for the sub-agent.', isError: true };
+    }
+
+    const res = ctx.tasks.spawn({
+      description: description || prompt.slice(0, 60),
+      prompt,
+      subagentType: subagentType || 'coder',
+    });
+    if (!res.ok) return { output: res.error, isError: true };
+
+    return {
+      output:
+        `Background task started (id: ${res.taskId}). It is now running while you keep chatting. ` +
+        `Tell the user in ONE short sentence that you're on it (your usual voice — never mention ` +
+        `agents, tasks, or ids), then end your turn. You will automatically receive the result ` +
+        `when it finishes.`,
+    };
+  },
+};

package/supervisor/harnesses/pi/tools/types.ts

@@ -14,11 +14,26 @@ export interface PiToolResult {
   isError?: boolean;
 }
 
+/**
+ * Host interface a live conversation exposes to the Task tool so it can spawn
+ * background sub-agents (audit D4-1). Only PARENT sessions provide it — child
+ * sessions get `ctx.tasks` undefined, so a sub-agent cannot spawn
+ * grandchildren (Claude SDK parity).
+ */
+export interface PiTaskHost {
+  /** Spawn a background sub-agent. Returns synchronously; the child runs detached. */
+  spawn(req: { description: string; prompt: string; subagentType: string }):
+    | { ok: true; taskId: string }
+    | { ok: false; error: string };
+}
+
 export interface PiToolContext {
   /** Workspace root — every tool resolves paths against this. */
   cwd: string;
   /** Aborted when the session ends so long-running tools stop fast. */
   signal?: AbortSignal;
+  /** Present only in live parent sessions — lets the Task tool spawn sub-agents. */
+  tasks?: PiTaskHost;
 }
 
 export interface PiTool {

package/supervisor/index.ts

@@ -3236,8 +3236,12 @@ ${alreadyLinked ? '' : `
     return async (type: string, eventData: any) => {
       // Capture surface BEFORE routeWaStreamEvent consumes the routing target on bot:response.
       // Used below to suppress chat-bubble broadcasts for non-dashboard turns.
+      // Synthetic turns (background-task continuations — see routeWaStreamEvent's
+      // guard) never own a routing target; the FIFO head, if any, belongs to a
+      // QUEUED channel message, so peeking it would misclassify the turn.
+      // They are always dashboard turns.
       const triggerSurface = channelManager.peekCurrentSurface(convId);
-      const isDashboardTurn = !triggerSurface || triggerSurface === 'workspace' || triggerSurface === 'chat';
+      const isDashboardTurn = eventData?.synthetic === true || !triggerSurface || triggerSurface === 'workspace' || triggerSurface === 'chat';
 
       if (type === 'bot:typing') {
         currentStreamConvId = convId;

package/supervisor/shell.ts

@@ -170,7 +170,7 @@ export const SHELL_HTML = `<!DOCTYPE html>
             // preload=auto so the clip is fetched (and SW-cached) while the supervisor is
             // still up — by the time we show this, the origin is unreachable.
             '<video autoplay loop muted playsinline preload="auto" style="position:relative;width:100%;height:100%;object-fit:contain;border-radius:50%">' +
-              '<source src="/morphy_sad.mov" type=\'video/mp4; codecs="hvc1"\'><source src="/morphy_sad.webm" type="video/webm">' +
+              '<source src="/morphy_sad.webm" type="video/webm"><source src="/morphy_sad.mov" type="video/mp4">' +
             '</video>' +
           '</div>' +
           '<h1 style="font-size:1.5rem;font-weight:700;margin:0 0 .6rem;background:linear-gradient(135deg,#0166FF,#009AFE,#4AEEFF);-webkit-background-clip:text;-webkit-text-fill-color:transparent;background-clip:text">Workspace is restarting&hellip;</h1>' +

package/supervisor/workspace-guard.js

@@ -562,7 +562,7 @@
         '<div style="position:relative;width:160px;height:160px;margin:0 auto 1.2rem">' +
           '<div style="position:absolute;inset:-18px;background:radial-gradient(circle,rgba(1,102,255,.18) 0%,transparent 60%);filter:blur(18px)"></div>' +
           '<video autoplay loop muted playsinline style="position:relative;width:100%;height:100%;object-fit:contain;border-radius:50%">' +
-            '<source src="/morphy_sad.mov" type=\'video/mp4; codecs="hvc1"\'><source src="/morphy_sad.webm" type="video/webm">' +
+            '<source src="/morphy_sad.webm" type="video/webm"><source src="/morphy_sad.mov" type="video/mp4">' +
           '</video>' +
         '</div>' +
         '<h1 style="font-size:1.5rem;font-weight:700;margin:0 0 .6rem;background:linear-gradient(135deg,#0166FF,#009AFE,#4AEEFF);-webkit-background-clip:text;-webkit-text-fill-color:transparent;background-clip:text">Workspace error</h1>' +