@pi-unipi/unipi 3.0.0-alpha.2 → 3.0.0-alpha.21

package/packages/subagents/src/index.ts

@@ -1,1153 +1,678 @@
 /**
- * @pi-unipi/subagents — Extension entry
+ * @pi-unipi/subagents — Devin-model subagents for unipi.
  *
- * Tools: spawn_helper, get_helper_result
- * Features: renderCall/renderResult, message renderer, conversation viewer
- * ESC propagation: all children abort on parent ESC
+ * Tools: `run_subagent` (foreground wait / background notify / resume) and a
+ * reader registration for the shared core `read_subagent` tool.
+ * Profiles: built-ins `subagent_explore` / `subagent_general` plus custom
+ * markdown agents from ~/.unipi/config/agents and <workspace>/.unipi/config/agents.
+ * Config `subagents`: enabled, defaultModel, defaultThinking, maxConcurrent —
+ * re-read every turn, so settings and agent files apply without a restart.
+ *
+ * TUI (Devin parity): spawn card with a live tail, `Subagent "…" completed`
+ * lines, the `N subagents (k running) · ↓ select` strip, the dock (↵ view,
+ * f foreground, x cancel), Ctrl+B to background a foreground subagent.
  */
 
-import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Text } from "@earendil-works/pi-tui";
+import { type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { existsSync, readdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { homedir } from "node:os";
-import { MODULES, UNIPI_EVENTS, emitEvent, type UnipiBadgeGenerateRequestEvent } from "@pi-unipi/core";
-import { boundHelperOutput, withHerdrBlocked } from "./core-compat.js";
-import { AgentManager } from "./agent-manager.js";
-import { initConfig, loadRawGlobalConfig, loadRawWorkspaceConfig } from "./config.js";
-import { type AgentActivity, type NotificationDetails, BUILTIN_TYPES } from "./types.js";
-import { loadBuiltinFileAgents } from "./custom-agents.js";
-import { ConversationViewer } from "./conversation-viewer.js";
-import { AgentWidget, SPINNER, TOOL_DISPLAY, formatMs, formatTurns, describeActivity } from "./widget.js";
-import { handleSpawnHelper, type HandlerDeps } from "./tool-handler.js";
-import { SpawnHelperParams, GetHelperResultParams } from "./schemas.js";
-import { runAsyncSubagent, createAsyncRunDir, writeStatus, readStatus } from "./async-runner.js";
-import { createResultWatcher, cleanupAsyncRetention } from "./result-watcher.js";
-import { writeAsyncResultFile, readAsyncResultFile } from "./result-files.js";
-import { writePendingSubscription } from "./result-watcher.js";
-import { RESULTS_DIR, ASYNC_DIR, ensureDirs } from "./parity-types.js";
-import { createForkContextResolver } from "./fork-context.js";
-import { createWorktrees, cleanupWorktrees, diffWorktrees, type WorktreeSetup } from "./worktree.js";
-import { FleetView } from "./fleet-view.js";
-import { registerSlashCommands } from "./slash-commands.js";
+import { Key, matchesKey, truncateToWidth, type TUI } from "@earendil-works/pi-tui";
+import { renderDelegatedStep, type DelegatedStep } from "@pi-unipi/utility/src/render/delegated.js";
 import {
-  parseDetachShortcut,
-  formatDetachHint,
-  matchesDetachInput,
-} from "./foreground-detach.js";
-import { coerceThinkingLevel } from "./agent-runner.js";
-import { childExtensionsArg } from "./pi-args.js";
-
-/** Get info registry from global */
-function getInfoRegistry() {
-  return globalThis.__unipi_info_registry;
+  UNIPI_EVENTS, emitEvent, getSettings, isChildProcess, registerSettings, registerWaitSource, getSharedFusionStatus, SPINNER_MS,
+} from "@pi-unipi/core";
+import {
+  ensureReadSubagentTool, registerSubagentReader, setReadSubagentDemand,
+  createCompletionDelivery, type HandoffReport, type SidekickStep,
+} from "@pi-unipi/core/child-agent.js";
+import {
+  SubagentManager, backgroundRunningReason, canSpawn, getSharedSubagents, subscribeSubagents, recordStatusFor,
+  MAX_CONCURRENT, type SubagentRecord, type SubagentRun, type SubagentStatus,
+} from "./manager.js";
+import { loadProfiles, type AgentProfile } from "./profiles.js";
+import { buildTranscript, itemsFromEvents } from "./transcript.js";
+import {
+  SubagentDock, SubagentStrip, elapsed, plural, profileLabel, statusColor, statusGlyph, statLine, tailLines, STATUS_LABEL, type ThemeLike,
+} from "./ui.js";
+import { AGENTS_COMMAND, registerAgentsCommand } from "./agents.js";
+import {
+  cardOutcome, renderCompletion, renderRunCall, renderRunResult, type CardContext, type CardDetails, type RunArgs,
+} from "./cards.js";
+
+export interface SubagentsConfig {
+  enabled: boolean;
+  defaultModel?: string;
+  defaultThinking?: string;
+  maxConcurrent?: number;
 }
 
-// ---- Formatting helpers (shared between renderers and inline text) ----
+const DEFAULT_CONFIG: SubagentsConfig = { enabled: true, defaultThinking: "inherit", maxConcurrent: MAX_CONCURRENT };
+const AUTO_MODEL = "auto (Fusion sidekick → your model)";
 
+registerSettings({
+  namespace: "subagents",
+  label: "Subagents",
+  defaults: DEFAULT_CONFIG as unknown as Record<string, unknown>,
+  schema: [
+    {
+      title: "Subagents",
+      fields: [
+        { key: "enabled", type: "boolean", label: "Enabled", description: "Offer run_subagent / read_subagent to the agent. Applies from the next turn." },
+        {
+          key: "defaultModel", type: "model", label: "Default subagent model", capability: "text",
+          description: "Model for subagent_explore and custom agents without a model: line. subagent_general always runs on your model.",
+          emptyLabel: AUTO_MODEL, emptyOption: AUTO_MODEL,
+        },
+        {
+          key: "defaultThinking", type: "enum", label: "Default thinking level",
+          description: "For subagent_explore and custom agents without thinking:. subagent_general uses yours.",
+          options: [{ value: "inherit", label: "inherit (your level)" }, "off", "minimal", "low", "medium", "high", "xhigh"],
+        },
+        { key: "maxConcurrent", type: "number", label: "Max running at once", min: 1, max: 16, description: "Further run_subagent calls are refused until one finishes." },
+      ],
+    },
+    {
+      title: "Agents",
+      fields: [
+        { key: "manageAgents", type: "action", label: "Manage agents…", description: "List, create, edit, copy or delete custom agents (global or this project).", command: AGENTS_COMMAND },
+      ],
+    },
+  ],
+});
 
-/** Tool name → human-readable action. */
-
-function formatTokens(count: number): string {
-  if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M token`;
-  if (count >= 1_000) return `${(count / 1_000).toFixed(1)}k token`;
-  return `${count} token`;
-}
-
-/** Format tokens safely from session. */
-function safeFormatTokens(session: any): string {
-  if (!session) return "";
-  try {
-    const stats = session.getSessionStats();
-    const total = stats.tokens?.total ?? 0;
-    return formatTokens(total);
-  } catch {
-    return "";
-  }
-}
-
-/** Get raw token count from session. */
-function safeTokenCount(session: any): number {
-  if (!session) return 0;
+export function loadConfig(cwd: string): SubagentsConfig {
   try {
-    return session.getSessionStats().tokens?.total ?? 0;
+    const m = getSettings("subagents", cwd) as unknown as SubagentsConfig;
+    const n = Number(m.maxConcurrent);
+    return {
+      enabled: m.enabled !== false,
+      defaultModel: typeof m.defaultModel === "string" && m.defaultModel.trim() ? m.defaultModel.trim() : undefined,
+      defaultThinking: typeof m.defaultThinking === "string" && m.defaultThinking !== "inherit" && m.defaultThinking ? m.defaultThinking : undefined,
+      maxConcurrent: Number.isFinite(n) && n >= 1 ? Math.floor(n) : MAX_CONCURRENT,
+    };
   } catch {
-    return 0;
+    return { enabled: true, maxConcurrent: MAX_CONCURRENT };
   }
 }
 
-/** Build result text */
-function textResult(msg: string, details?: any) {
-  return { content: [{ type: "text" as const, text: msg }], details };
-}
-
-/** Escape XML for structured notifications. */
-function escapeXml(s: string): string {
-  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
-}
+const RunSubagentParams = Type.Object({
+  title: Type.String({ description: "Short 3-8 word title shown to the user" }),
+  task: Type.String({
+    description: "Complete, self-contained instructions. The subagent does not see this conversation: include the goal, relevant paths, constraints, and what to report back.",
+  }),
+  profile: Type.String({ description: "" }), // rebuilt at load: profile list
+  is_background: Type.Optional(Type.Boolean({ description: "Run without waiting; report arrives via notification (default false)" })),
+  resume: Type.Optional(Type.String({ description: "agent_id of an earlier subagent to continue (keeps its context); always runs in the foreground" })),
+});
 
-/** Human-readable status label. */
-function getStatusLabel(status: string, error?: string): string {
-  switch (status) {
-    case "error": return `Error: ${error ?? "unknown"}`;
-    case "aborted": return "Aborted (max turns exceeded)";
-    case "stopped": return "Stopped";
-    default: return "Done";
-  }
-}
+const RUN_DESCRIPTION =
+  "Launch an independent subagent for a self-contained task. It has its own context and does not see this conversation, so put everything it needs in `task`. Foreground (default) waits and returns the subagent's report. With is_background:true it returns immediately and you receive a <subagent_completion_notification> when it finishes; use read_subagent to wait for it — never poll in a loop. Background subagents cannot ask for approval: tool calls that would need approval are denied. Use resume:<agent_id> to continue an earlier subagent with a follow-up task.";
 
-export default function (pi: ExtensionAPI) {
-  // Initialize config
-  const config = initConfig(process.cwd());
-  if (!config.enabled) return;
+const STRIP_KEY = "subagents-strip";
+const FG_KEY = "subagents-foreground";
+const WORKING = "Subagent running · Ctrl+B to run in background";
 
-  // Compute paths at factory time
-  const homeDir = homedir();
-  const cwd = process.cwd();
-  const globalAgentsDir = join(homeDir, ".unipi", "config", "agents");
-  const workspaceAgentsDir = join(cwd, ".unipi", "config", "agents");
 
-  // Activity tracking for widget
-  const agentActivity = new Map<string, AgentActivity>();
+function leadSessionId(ctx: ExtensionContext): string {
+  const m = ctx.sessionManager as { getSessionId?: () => string | undefined } | undefined;
+  return m?.getSessionId?.() ?? "default";
+}
 
-  /**
-   * Set once `session_shutdown` fires — after which `pi` must not be touched.
-   *
-   * Pi disposes the session as soon as the shutdown handlers resolve, and
-   * `AgentSession.dispose()` invalidates the extension runtime. Every
-   * `assertActive`-gated method (`sendMessage`, `setSessionName`,
-   * `appendEntry`, `setModel`, …) then throws "This extension ctx is stale
-   * after session replacement or reload".
-   *
-   * Background agents outlive that moment: `abortAll()` only signals their
-   * AbortController, so the in-flight promise settles a microtask *later* and
-   * fires this completion callback against a dead runtime — an unhandled
-   * throw that crashed the process on exit.
-   *
-   * Scoped to the extension factory rather than module scope on purpose:
-   * `session_shutdown` also fires for `/new`, `/fork` and `/resume` (reasons
-   * "new" / "fork" / "resume"), and pi re-invokes the extension factory for
-   * the replacement session. A fresh closure therefore starts with
-   * `sessionEnded = false`, so the guard can never latch permanently.
-   * Verified: `/new` emits `shutdown reason=new` then re-runs the factory.
-   *
-   * `pi.events` is NOT gated, so cross-module events still fire.
-   */
-  let sessionEnded = false;
+/** Model order: profile.model → (general: parent) → config.defaultModel →
+ * Fusion sidekickKey → parent. Exported for tests. */
+export function resolveSubagentModel(
+  profile: AgentProfile,
+  ctx: Pick<ExtensionContext, "model">,
+  config: SubagentsConfig,
+): string {
+  if (profile.model !== undefined) return profile.model;
+  const cur = ctx.model as { provider?: string; id?: string } | undefined;
+  const parent = cur ? `${String(cur.provider)}/${String(cur.id)}` : "";
+  if (profile.id === "subagent_general") return parent;
+  if (config.defaultModel !== undefined) return config.defaultModel;
+  const sidekickKey = getSharedFusionStatus()?.sidekickKey;
+  if (sidekickKey !== undefined) return sidekickKey;
+  return parent;
+}
 
-  // Create manager with completion callback
-  const manager = new AgentManager(
-    (record) => {
-      agentActivity.delete(record.id);
+/** subagent_general rides the parent's level; defaultThinking covers
+ * explore/custom agents without their own `thinking`. Exported for tests. */
+export function resolveSubagentThinking(
+  profile: AgentProfile,
+  ctx: Pick<ExtensionContext, "thinkingLevel">,
+  config: SubagentsConfig,
+): string {
+  const own = profile.id === "subagent_general" ? undefined : config.defaultThinking;
+  return profile.thinking ?? own ?? ctx.thinkingLevel ?? "medium";
+}
 
-      // After shutdown the UI is gone and the runtime is stale — nothing here
-      // is deliverable, and touching `pi` would throw.
-      if (sessionEnded) return;
+export { cardOutcome };
 
-      widget.markFinished(record.id);
-      widget.update();
+/**
+ * UI-only completed-step entry: payload + guarded append, identical for
+ * foreground and background runs. The final report is intentionally never
+ * streamed here — the lead reports it itself. Exported for tests.
+ */
+export function appendSubagentStep(
+  appendEntry: (type: string, data: Record<string, unknown>) => void,
+  record: Pick<SubagentRecord, "id" | "title" | "profile" | "startedAt">,
+  step: SidekickStep,
+): void {
+  try {
+    appendEntry("subagent-step", {
+      ...step,
+      agentId: record.id,
+      id: record.id,
+      title: record.title,
+      profile: record.profile,
+      group: `subagent:${record.id}:${record.startedAt}`,
+      label: `${profileLabel(record.profile)} subagent · ${record.title}`,
+    });
+  } catch {
+    /* entry rendering never affects the run */
+  }
+}
 
-      // Build notification details
-      const details = buildNotificationDetails(record, agentActivity.get(record.id));
+export default function subagents(pi: ExtensionAPI, deps?: { manager?: SubagentManager }): void {
+  const manager = deps?.manager ?? new SubagentManager();
+  const delivery = createCompletionDelivery<HandoffReport>((report) => deliverCompletion(report));
 
-      // Badge generation: extract name from agent result and set directly.
-      // Mark resultConsumed BEFORE the notification check so the main agent
-      // never sees this subagent.
-      if (record.description === "Generate session name" && record.result && record.status === "completed") {
-        const name = record.result.split("\n")[0]?.trim().slice(0, 50) ?? "";
-        if (name && !name.startsWith("Error") && !name.includes("error")) {
-          try {
-            pi.setSessionName(name);
-          } catch { /* best effort */ }
-        }
-        record.resultConsumed = true;
-      }
+  // Turn-arbiter wait source (lead only): a background subagent is still
+  // working while the lead settles — its completion will arrive as an event
+  // turn, so a nudge now would race it.
+  if (!isChildProcess()) {
+    try {
+      registerWaitSource("subagents", () => backgroundRunningReason(getSharedSubagents()));
+    } catch {
+      // Registration must never block module load.
+    }
+  }
 
+  let profiles: AgentProfile[] = [];
+  let config: SubagentsConfig = { ...DEFAULT_CONFIG };
+  let enabled = false;
+  let uiCtx: ExtensionContext | undefined;
+  const warned = new Set<string>();
+
+  // UI state
+  let stripTui: TUI | undefined;
+  let stripInstalled = false;
+  let fgInstalled = false;
+  let dockOpen = false;
+  let workingShown = false;
+  let unsubInput: (() => void) | undefined;
+  /** Foreground waiters (run_subagent / read_subagent block) → move to bg. */
+  const fgWaits = new Map<string, () => void>();
+  /** Background agents the user foregrounded from the dock (f). */
+  const watched = new Set<string>();
+
+  function deliverCompletion(report: HandoffReport): void {
+    const rec = manager.record(report.id);
+    if (rec?.cancelledBy === "session") return; // the session is gone
+    const status = rec?.status ?? recordStatusFor(report);
+    const head = status === "cancelled"
+      ? rec?.cancelledBy === "user" ? "Cancelled by the user." : "Cancelled."
+      : status === "failed" ? `Failed${report.error ? `: ${report.error}` : "."}` : "";
+    const body = [head, report.text].filter((s) => s && s.trim()).join("\n\n");
+    try {
+      pi.sendMessage(
+        {
+          customType: "subagent-completion",
+          content: `<subagent_completion_notification agent_id="${report.id}" status="${status}">\n${body}\n</subagent_completion_notification>`,
+          display: true,
+          details: {
+            owner: "subagents", id: report.id, title: rec?.title ?? report.id, profile: rec?.profile, model: rec?.model, status,
+            cancelledBy: rec?.cancelledBy, toolCalls: report.toolCalls, durationMs: report.durationMs, usage: report.usage, report: report.text.slice(0, 20_000),
+          },
+        } as never,
+        { deliverAs: "followUp", triggerTurn: true } as never,
+      );
+    } catch {
+      /* session replaced while it finished */
+    }
+  }
 
-      // Send styled notification via message renderer
-      const status = getStatusLabel(record.status, record.error);
-      const durationMs = record.completedAt ? record.completedAt - record.startedAt : 0;
-      const resultPreview = record.result
-        ? record.result.length > 500
-          ? record.result.slice(0, 500) + "…"
-          : record.result
-        : "No output.";
+  /** Re-read config + agent files; returns the load warnings. Safe at load. */
+  function reload(cwd: string): string[] {
+    config = loadConfig(cwd);
+    enabled = config.enabled;
+    const loaded = loadProfiles(cwd);
+    profiles = loaded.profiles;
+    return loaded.warnings;
+  }
 
-      const notificationXml = [
-        `<task-notification>`,
-        `<task-id>${record.id}</task-id>`,
-        `<status>${escapeXml(status)}</status>`,
-        `<summary>Agent "${escapeXml(record.description)}" ${record.status}</summary>`,
-        `<result>${escapeXml(resultPreview)}</result>`,
-        `<usage><total_tokens>${details.totalTokens}</total_tokens><tool_uses>${record.toolUses}</tool_uses><duration_ms>${durationMs}</duration_ms></usage>`,
-        `</task-notification>`,
-      ].join("\n");
+  /** reload + tool sync + warnings (runtime only — not during loading). */
+  function refresh(cwd: string, ctx?: ExtensionContext): void {
+    // Warnings surface once per distinct message per process.
+    for (const w of reload(cwd)) {
+      if (warned.has(w)) continue;
+      warned.add(w);
+      (ctx ?? uiCtx)?.ui?.notify?.(`subagents: ${w}`, "warning");
+    }
+    setReadSubagentDemand(pi, "subagents", enabled);
+    syncRunSubagent();
+  }
 
-      if (!record.resultConsumed) {
-        // Defence in depth: `sessionEnded` covers the ordinary shutdown path,
-        // but a session can also be replaced mid-flight. Delivering a
-        // notification is best-effort — it must never take the process down.
-        try {
-          pi.sendMessage<NotificationDetails>(
-            {
-              customType: "subagent-notification",
-              content: notificationXml,
-              display: true,
-              details,
-            },
-            { deliverAs: "followUp", triggerTurn: true },
-          );
-        } catch {
-          // Runtime went stale between the guard and here — nothing to notify.
-        }
-      }
+  function syncRunSubagent(): void {
+    const want = enabled && canSpawn();
+    const current = pi.getActiveTools();
+    const has = current.includes("run_subagent");
+    if (has !== want) pi.setActiveTools(want ? [...current, "run_subagent"] : current.filter((t) => t !== "run_subagent"));
+  }
 
-      pi.events.emit("subagents:completed", {
-        id: record.id,
-        type: record.type,
-        description: record.description,
-        status: record.status,
-        result: record.result,
-        error: record.error,
-      });
-    },
-    config.maxConcurrent,
-    (record) => {
-      pi.events.emit("subagents:started", {
-        id: record.id,
-        type: record.type,
-        description: record.description,
-      });
-    },
-    config.types,
-    process.cwd(),
-    {
-      user: loadRawGlobalConfig()?.subagents,
-      project: loadRawWorkspaceConfig(process.cwd())?.subagents,
-    },
-  );
+  // Profiles load before registration so the tool schema's profile list is
+  // complete; later additions reach the model through the prompt section.
+  reload(process.cwd());
 
-  // ---- Async process runner (Phase 3) ----
-  ensureDirs();
-  const activeAsyncRuns = new Map<string, AbortController>();
-  const asyncSessionId = `unipi-${process.pid}`;
+  const transcriptOf = (rec: SubagentRecord) =>
+    buildTranscript({ sessionFile: rec.sessionFile, task: rec.task, running: rec.status === "running", events: manager.events(rec.id) });
+  const liveItems = (id: string) => itemsFromEvents(manager.events(id) ?? []);
 
-  const runAsyncDep: NonNullable<HandlerDeps["runAsync"]> = async (launch) => {
-    const agent = manager.getAgentConfig(manager.resolveAlias(launch.agentName));
-    if (!agent) throw new Error(`Unknown agent "${launch.agentName}".`);
-    if (launch.resumeSessionFile && !existsSync(launch.resumeSessionFile)) {
-      throw new Error(`Resume session file is missing: ${launch.resumeSessionFile}`);
-    }
+  // ── UI sync ───────────────────────────────────────────────────────────────
 
-    // Worktree isolation: managed worktree per child; cleaned up after the run
-    // (diffs preserved to the run dir as handoff artifacts).
-    let worktreeSetup: WorktreeSetup | undefined;
-    let childCwd = process.cwd();
-    if (launch.worktree === true) {
-      try {
-        worktreeSetup = createWorktrees(process.cwd(), `async-${Date.now().toString(36)}`, 1);
-        childCwd = worktreeSetup.worktrees[0]!.agentCwd;
-      } catch (worktreeError) {
-        throw new Error(
-          `Worktree isolation failed: ${worktreeError instanceof Error ? worktreeError.message : String(worktreeError)}`,
-        );
+  function syncUi(): void {
+    const ctx = uiCtx;
+    if (!ctx?.hasUI) return;
+    try {
+      for (const id of watched) {
+        if (manager.run(id) === undefined) watched.delete(id);
       }
-    }
-    const runDir = createAsyncRunDir(launch.agentName, asyncSessionId);
-    const runId = runDir.split("/").pop()!;
-    const controller = new AbortController();
-    activeAsyncRuns.set(runId, controller);
-
-    // Fork context: branch a child session from the parent conversation
-    // (sanitized thinking blocks, thinking forced off when sanitized).
-    let forkSessionFile: string | undefined;
-    let forceThinkingOff: boolean | undefined;
-    if (launch.context === "fork") {
-      try {
-        const sessionManager = (sessionCtx as unknown as {
-          sessionManager?: {
-            getSessionFile(): string | undefined;
-            getLeafId(): string | null;
-            openSession?: Parameters<typeof createForkContextResolver>[0]["openSession"];
-          };
-        })?.sessionManager;
-        if (!sessionManager) {
-          throw new Error("Forked context requires a persisted parent session (session manager unavailable).");
-        }
-        const resolver = createForkContextResolver(sessionManager, "fork");
-        forkSessionFile = resolver.sessionFileForIndex(0);
-        forceThinkingOff = resolver.thinkingOverrideForIndex(0) === "off";
-        if (!forkSessionFile) {
-          throw new Error("Forked context failed to produce a branched session file.");
-        }
-        writeStatus(runDir, { context: "fork", forkSessionFile });
-      } catch (forkError) {
-        // Reference rule: explicit fork never silently downgrades.
-        activeAsyncRuns.delete(runId);
-        throw forkError;
+      const wantStrip = getSharedSubagents().length > 0;
+      if (wantStrip && !stripInstalled) {
+        stripInstalled = true;
+        ctx.ui.setWidget(STRIP_KEY, (tui, theme) => {
+          stripTui = tui;
+          return new SubagentStrip(tui, theme, getSharedSubagents, (rec) => ({ toolCalls: manager.toolCalls(rec.id), usage: manager.usage(rec.id) }));
+        }, { placement: "belowEditor" });
+      } else if (!wantStrip && stripInstalled) {
+        stripInstalled = false;
+        stripTui = undefined;
+        ctx.ui.setWidget(STRIP_KEY, undefined);
+      } else {
+        stripTui?.requestRender();
       }
-    }
-
-    // Fire-and-track: the promise writes the durable result file + notifies on
-    // completion; the tool call returns immediately with the run id.
-    void (async () => {
-      try {
-        const result = await runAsyncSubagent(
-          {
-            agent,
-            task: launch.task,
-            cwd: childCwd,
-            model: launch.model,
-            thinking: launch.thinking,
-            tools: agent.builtinToolNames,
-            extensions: childExtensionsArg(agent.extensions),
-            timeoutMs: launch.timeoutMs,
-            parentSessionId: asyncSessionId,
-            config,
-            ...(launch.resumeSessionFile ? { sessionFile: launch.resumeSessionFile } : {}),
-            ...(forkSessionFile ? { forkSessionFile } : {}),
-            ...(forceThinkingOff ? { forceThinkingOff } : {}),
-          },
-          runDir,
-          controller.signal,
-        );
-        writeAsyncResultFile(RESULTS_DIR, {
-          runId,
-          sessionId: asyncSessionId,
-          ...(result.output !== undefined ? { output: result.output } : {}),
-          ...(result.error ? { error: result.error } : {}),
-          success: result.status === "completed",
-          state: result.status,
-          timedOut: result.status === "timedOut",
-          durationMs: result.durationMs,
-        }, { asyncDir: runDir });
-      } catch (error) {
-        writeStatus(runDir, {
-          status: "failed",
-          error: error instanceof Error ? error.message : String(error),
-        });
-        writeAsyncResultFile(RESULTS_DIR, {
-          runId,
-          sessionId: asyncSessionId,
-          error: error instanceof Error ? error.message : String(error),
-          success: false,
-          state: "failed",
-        }, { asyncDir: runDir });
-      } finally {
-        activeAsyncRuns.delete(runId);
-        if (worktreeSetup) {
-          try {
-            const diffs = diffWorktrees(worktreeSetup, [launch.agentName], runDir);
-            writeFileSync(
-              join(runDir, "handoff.json"),
-              JSON.stringify({ patches: diffs.map((d) => d.patchPath) }),
-              { mode: 0o600 },
-            );
-            cleanupWorktrees(worktreeSetup, {
-              kind: "preserve",
-              capturedDiffs: diffs,
-              handoffManifestPath: join(runDir, "handoff.json"),
-            });
-          } catch {
-            // Worktree cleanup is best-effort; preserved trees surface in the report.
-          }
-        }
+      const wantFg = watched.size > 0;
+      if (wantFg && !fgInstalled) {
+        fgInstalled = true;
+        ctx.ui.setWidget(FG_KEY, (tui, theme) => {
+          const timer = setInterval(() => tui.requestRender(), SPINNER_MS);
+          timer.unref?.();
+          return { invalidate() {}, render: (w: number) => renderWatched(w, theme), dispose: () => clearInterval(timer) };
+        }, { placement: "aboveEditor" });
+      } else if (!wantFg && fgInstalled) {
+        fgInstalled = false;
+        ctx.ui.setWidget(FG_KEY, undefined);
       }
-    })();
-
-    return { runId, status: "running" };
-  };
-
-  // Result watcher: deliver async completions as follow-up notifications.
-  const watcher = createResultWatcher({
-    resultsDir: RESULTS_DIR,
-    sessionId: asyncSessionId,
-    resultScanLogging: config.resultScanLogging ?? "activity",
-    notifier: (notification) => {
-      if (sessionEnded) return;
-      try {
-        pi.sendMessage(
-          {
-            customType: "unipi-response",
-            content:
-              `<task-notification>\n` +
-              `<task-id>${notification.runId}</task-id>\n` +
-              `<status>${notification.success ? "completed" : notification.state ?? "failed"}</status>\n` +
-              `<summary>Background agent "${notification.agent ?? "agent"}" ${notification.state ?? (notification.success ? "completed" : "failed")}</summary>\n` +
-              (notification.error
-                ? `<error>${notification.error}</error>\n`
-                : `<result>${(notification.output ?? "").slice(0, 2000)}</result>\n`) +
-              `</task-notification>`,
-            display: false,
-          },
-          { deliverAs: "followUp", triggerTurn: true },
-        );
-      } catch {
-        // Runtime went stale — nothing to notify.
+      const wantWorking = fgWaits.size > 0 || watched.size > 0;
+      if (wantWorking !== workingShown) {
+        workingShown = wantWorking;
+        ctx.ui.setWorkingMessage(wantWorking ? WORKING : undefined);
       }
-    },
-  });
+    } catch {
+      /* UI is best-effort; the runs are unaffected */
+    }
+  }
+  const unsubRegistry = subscribeSubagents(syncUi);
+
+  function renderWatched(width: number, theme: ThemeLike): string[] {
+    const out: string[] = [];
+    for (const id of watched) {
+      const rec = manager.record(id);
+      if (rec === undefined) continue;
+      // Same Devin card as a foreground run_subagent.
+      const head = `${statusGlyph(rec.status, theme)} ${theme.bold(`${profileLabel(rec.profile)} subagent`)} ${rec.title}`;
+      const foot = theme.fg("dim", `└ ${statLine(rec, manager.toolCalls(id), manager.usage(id))} · ctrl+b background`);
+      out.push(truncateToWidth(head, width), ...tailLines(liveItems(id), width, theme, 4), truncateToWidth(`  ${foot}`, width));
+    }
+    return out;
+  }
 
-  // Periodic retention cleanup (hourly, unref'd).
-  const retentionTimer = setInterval(() => {
-    cleanupAsyncRetention(ASYNC_DIR, RESULTS_DIR);
-  }, 60 * 60 * 1000);
-  retentionTimer.unref?.();
+  function foregroundAgent(id: string): string | undefined {
+    const run = manager.run(id);
+    if (run === undefined) return "Already finished — ask the agent to resume it.";
+    if (fgWaits.has(id) || watched.has(id)) return undefined;
+    if (uiCtx) run.runtime.attachUi(uiCtx.ui as never);
+    manager.setBackground(id, false);
+    watched.add(id);
+    syncUi();
+    return undefined;
+  }
 
-  // Scheduled runs: poll for due schedules every minute when enabled.
-  let schedulePoller: { stopPolling(): void } | undefined;
-  if (config.scheduledRuns?.enabled !== false && deps_runAsyncAvailable()) {
-    import("./scheduled-runs.js").then(({ ScheduledRunManager }) => {
-      const manager = new ScheduledRunManager(process.cwd(), {
-        storeRoot: config.scheduledRuns?.storeRoot,
-        maxPending: config.scheduledRuns?.maxPending,
-        launch: async (record) => {
-          const result = await runAsyncDep({
-            agentName: record.agent,
-            task: record.task,
-            description: `schedule: ${record.name}`,
-            context: "fresh",
-            timeoutMs: record.timeoutMs,
-          });
-          return result.runId;
-        },
-      });
-      manager.startPolling();
-      schedulePoller = manager;
-    }).catch(() => {});
+  /** Ctrl+B: every foreground subagent goes to the background. */
+  function backgroundAll(): boolean {
+    let any = false;
+    for (const move of [...fgWaits.values()]) {
+      move();
+      any = true;
+    }
+    for (const id of watched) {
+      manager.run(id)?.runtime.detachUi();
+      manager.setBackground(id, true);
+      any = true;
+    }
+    watched.clear();
+    syncUi();
+    return any;
   }
-  function deps_runAsyncAvailable(): boolean {
-    return true; // runAsyncDep is defined below in the closure
+
+  function cancelAgent(id: string): string | undefined {
+    return manager.cancel(id, "user") ? undefined : "Not running.";
   }
 
-  // ---- Parity handler wiring (spawn_helper surface) ----
-  // Session-wide cumulative spawn accounting (maxSubagentSpawnsPerSession)
-  let sessionSpawnsUsed = 0;
-  const sessionSpawnCap = config.maxSubagentSpawnsPerSession && config.maxSubagentSpawnsPerSession > 0
-    ? config.maxSubagentSpawnsPerSession
-    : undefined;
+  async function openDock(ctx: ExtensionContext, initialId?: string): Promise<void> {
+    if (dockOpen || !ctx.hasUI) return;
+    dockOpen = true;
+    try {
+      await ctx.ui.custom<void>((tui, theme, _kb, done) => new SubagentDock(tui, theme, {
+        records: getSharedSubagents,
+        transcript: transcriptOf,
+        toolCalls: (rec) => manager.toolCalls(rec.id),
+        usage: (rec) => manager.usage(rec.id),
+        subscribe: subscribeSubagents,
+        foreground: foregroundAgent,
+        cancel: cancelAgent,
+      }, () => done(), initialId));
+    } finally {
+      dockOpen = false;
+    }
+  }
 
-  const handlerDeps: HandlerDeps = {
-    pi,
-    manager,
-    config,
-    spawnAccounting: {
-      used: () => sessionSpawnsUsed,
-      cap: () => sessionSpawnCap,
-      consume: (count) => { sessionSpawnsUsed += count; },
-    },
-    runAsync: runAsyncDep,
-    spawnBackground: (spawnCtx, agentName, childPrompt, options) => {
-      const { state: bgState, callbacks: bgCallbacks } = createActivityTracker(options.maxTurns);
-      const origOnSession = bgCallbacks.onSessionCreated;
-      bgCallbacks.onSessionCreated = (session: any) => {
-        origOnSession(session);
-        bgState.tokens = safeFormatTokens(session);
-        widget.update();
-      };
-      const id = manager.spawn(pi, spawnCtx, agentName, childPrompt, {
-        description: options.description ?? `${agentName} task`,
-        maxTurns: options.maxTurns,
-        modelInput: options.modelInput,
-        modelRegistry: spawnCtx.modelRegistry,
-        thinkingLevel: coerceThinkingLevel(options.thinkingLevel as never),
-        isBackground: true,
-        ...bgCallbacks,
-      });
-      agentActivity.set(id, bgState);
-      widget.ensureTimer();
-      widget.update();
-      return id;
-    },
-    spawnForeground: async (spawnCtx, agentName, childPrompt, options) => {
-      // Stream progress via the widget — reuse the activity tracker.
-      let spinnerFrame = 0;
-      const startedAt = Date.now();
-      let fgId: string | undefined;
-      const { state: fgState, callbacks: fgCallbacks } = createActivityTracker(options.maxTurns);
+  /** The editor is focused, empty and not autocompleting (↓ may open the dock). */
+  function editorIdle(): boolean {
+    const tui = stripTui as { getFocusedComponent?: () => unknown } | undefined;
+    const f = tui?.getFocusedComponent?.() as { getText?: () => string; isShowingAutocomplete?: () => boolean } | null | undefined;
+    if (!f || typeof f.getText !== "function" || typeof f.isShowingAutocomplete !== "function") return false;
+    return f.getText() === "" && !f.isShowingAutocomplete();
+  }
 
-      const streamUpdate = () => {
-        onUpdateForForeground({
-          status: "running",
-          toolUses: fgState.toolUses,
-          tokens: fgState.tokens,
-          turnCount: fgState.turnCount,
-          maxTurns: fgState.maxTurns,
-          durationMs: Date.now() - startedAt,
-          activity: describeActivity(fgState.activeTools, fgState.responseText),
-          spinnerFrame: spinnerFrame % SPINNER.length,
-        });
-      };
-      const origOnSession = fgCallbacks.onSessionCreated;
-      fgCallbacks.onSessionCreated = (session: any) => {
-        origOnSession(session);
-        fgState.tokens = safeFormatTokens(session);
-        for (const a of manager.listAgents()) {
-          if (a.session === session) {
-            fgId = a.id;
-            agentActivity.set(a.id, fgState);
-            widget.ensureTimer();
-            break;
-          }
-        }
-      };
-      const spinnerInterval = setInterval(() => { spinnerFrame++; streamUpdate(); }, 80);
-      // Detach: stop waiting without killing the child. The completion
-      // notification arrives later via the normal onComplete path.
-      activeForegroundDetach = () => {
-        if (!fgId) return false;
-        const record = manager.getRecord(fgId);
-        if (!record || record.status !== "running") return false;
-        record.resultConsumed = true; // suppress the duplicate notification
-        return true;
-      };
-      try {
-        const record = await manager.spawnAndWait(pi, spawnCtx, agentName, childPrompt, {
-          description: options.description ?? `${agentName} task`,
-          maxTurns: options.maxTurns,
-          modelInput: options.modelInput,
-          modelRegistry: spawnCtx.modelRegistry,
-          thinkingLevel: coerceThinkingLevel(options.thinkingLevel as never),
-          ...fgCallbacks,
-        });
-        const durationMs = (record.completedAt ?? Date.now()) - record.startedAt;
-        const tokenText = safeFormatTokens(fgState.session);
-        if (record.status === "error") {
-          return { ok: false, output: record.error ?? "failed", error: record.error, toolUses: record.toolUses, durationMs };
-        }
-        const output = boundHelperOutput(record.result?.trim() || "No output.");
-        record.resultArtifactPath = output.artifactPath;
-        return { ok: true, output: output.text, toolUses: record.toolUses, durationMs };
-      } finally {
-        clearInterval(spinnerInterval);
-        activeForegroundDetach = undefined;
-        if (fgId) {
-          agentActivity.delete(fgId);
-          widget.markFinished(fgId);
-          widget.update();
-        }
-      }
-    },
-  };
-  // onUpdate stream for the current foreground execution (set per execute() call)
-  let onUpdateForForeground: (details: Record<string, unknown>) => void = () => {};
+  function onTerminalInput(data: string): { consume?: boolean } | undefined {
+    if (matchesKey(data, "ctrl+b")) return backgroundAll() ? { consume: true } : undefined;
+    if (matchesKey(data, Key.down) && !dockOpen && stripInstalled && uiCtx && editorIdle()) {
+      void openDock(uiCtx);
+      return { consume: true };
+    }
+    return undefined;
+  }
 
-  // ---- Foreground detach (foregroundDetachShortcut) ----
-  const detachParts = parseDetachShortcut(config.foregroundDetachShortcut);
-  let activeForegroundDetach: (() => boolean) | undefined;
+  // ── run_subagent ──────────────────────────────────────────────────────────
+
+  if (canSpawn()) {
+    const profileParam = profiles.map((p) => `${p.id} — ${p.description}`).join("; ");
+    pi.registerTool({
+      name: "run_subagent",
+      label: "Run Subagent",
+      description: RUN_DESCRIPTION,
+      parameters: Type.Object({
+        ...RunSubagentParams.properties,
+        profile: Type.String({ description: `Profile name. Available: ${profileParam}. Custom agents added later are listed in the Subagents section of the system prompt.` }),
+      }),
+      renderShell: "self",
+      renderCall: (args: RunArgs, theme, context) => renderRunCall(args, theme, context as unknown as CardContext),
+      renderResult: (result, opts, theme, context) =>
+        renderRunResult(result as never, opts, theme, context as unknown as CardContext, (context as { args?: RunArgs }).args ?? {}, {
+          tail: (id, w) => tailLines(liveItems(id), w, theme, 4),
+          toolCalls: (id) => manager.toolCalls(id),
+          startedAt: (id) => manager.record(id)?.startedAt,
+          usage: (id) => manager.usage(id),
+          record: (id) => manager.record(id),
+        }),
+      execute: runSubagent as never,
+      // Simple render style: live stats in the row meta, `└ Completed …` under it.
+      ...( {
+        simpleMeta: (details: CardDetails | undefined) => {
+          const rec = details?.id !== undefined ? manager.record(details.id) : undefined;
+          return rec === undefined ? undefined : ` · ${statLine(rec, manager.toolCalls(rec.id), manager.usage(rec.id))}`;
+        },
+        simpleResult: (result: { details?: CardDetails }, theme: ThemeLike) => [`  ${cardOutcome(result.details, theme)}`],
+      } as object),
+    });
+  }
 
+  function textResult(text: string, details: CardDetails, isError = false) {
+    return { content: [{ type: "text" as const, text }], details, isError };
+  }
 
-  // Build notification details for the message renderer
-  function buildNotificationDetails(record: any, activity?: AgentActivity): NotificationDetails {
+  function doneDetails(rec: SubagentRecord, report: HandoffReport): CardDetails {
     return {
-      id: record.id,
-      description: record.description,
-      status: record.status,
-      toolUses: record.toolUses,
-      turnCount: activity?.turnCount ?? 0,
-      maxTurns: activity?.maxTurns,
-      totalTokens: safeTokenCount(record.session),
-      durationMs: record.completedAt ? record.completedAt - record.startedAt : 0,
-      error: record.error,
-      resultPreview: record.result
-        ? record.result.length > 200
-          ? record.result.slice(0, 200) + "…"
-          : record.result
-        : "No output.",
+      owner: "subagents", id: rec.id, title: rec.title, profile: rec.profile, model: rec.model, phase: "done",
+      status: rec.status === "running" ? recordStatusFor(report, rec.cancelledBy) : rec.status,
+      toolCalls: report.toolCalls, durationMs: report.durationMs, usage: report.usage, error: report.error, cancelledBy: rec.cancelledBy,
     };
   }
 
-  // ---- Register custom notification renderer ----
-  pi.registerMessageRenderer<NotificationDetails>(
-    "subagent-notification",
-    (message, { expanded }, theme) => {
-      const d = message.details;
-      if (!d) return undefined;
-
-      function renderOne(d: NotificationDetails): string {
-        const isError = d.status === "error" || d.status === "stopped" || d.status === "aborted";
-        const icon = isError ? theme.fg("error", "✗") : theme.fg("success", "✓");
-        const statusText = isError
-          ? d.status
-          : d.status === "steered"
-            ? "completed (steered)"
-            : "completed";
-
-        // Line 1: icon + agent description + status
-        let line = `${icon} ${theme.bold(d.description)} ${theme.fg("dim", statusText)}`;
-
-        // Line 2: stats
-        const parts: string[] = [];
-        if (d.turnCount > 0) parts.push(formatTurns(d.turnCount, d.maxTurns));
-        if (d.toolUses > 0) parts.push(`${d.toolUses} tool use${d.toolUses === 1 ? "" : "s"}`);
-        if (d.totalTokens > 0) parts.push(formatTokens(d.totalTokens));
-        if (d.durationMs > 0) parts.push(formatMs(d.durationMs));
-        if (parts.length) {
-          line += "\n  " + parts.map((p) => theme.fg("dim", p)).join(" " + theme.fg("dim", "·") + " ");
-        }
-
-        // Line 3: result preview (collapsed) or full (expanded)
-        if (expanded) {
-          const lines = d.resultPreview.split("\n").slice(0, 30);
-          for (const l of lines) line += "\n" + theme.fg("dim", `  ${l}`);
-        } else {
-          const preview = d.resultPreview.split("\n")[0]?.slice(0, 80) ?? "";
-          line += "\n  " + theme.fg("dim", `⎿  ${preview}`);
-        }
-
-        return line;
-      }
-
-      const all = [d, ...(d.others ?? [])];
-      return new Text(all.map(renderOne).join("\n"), 0, 0);
-    },
-  );
-
-  // Create widget
-  const widget = new AgentWidget(manager, agentActivity);
-
-  // ---- FleetView (persistent fleet panel; our AgentWidget slot system) ----
-  const fleetView = new FleetView(manager, agentActivity, ASYNC_DIR, {
-    placement: config.fleetView === false ? undefined : (config.fleetViewPlacement ?? "belowEditor"),
-    sessionId: asyncSessionId,
-    openInspector: async (entry) => {
-      if (!sessionCtx?.ui) return;
-      if (entry.source === "inprocess") {
-        const record = manager.getRecord(entry.key.replace("inprocess:", ""));
-        if (record?.session) {
-          await withHerdrBlocked(
-            pi,
-            "fleet inspector",
-            () => sessionCtx!.ui.custom<undefined>(
-              (tui, theme, _keybindings, done) =>
-                new ConversationViewer(tui, record.session!, {
-                  type: record.type,
-                  description: record.description,
-                  status: record.status,
-                  toolUses: record.toolUses,
-                  startedAt: record.startedAt,
-                  completedAt: record.completedAt,
-                }, agentActivity.get(record.id), theme, done),
-              { overlay: true, overlayOptions: { anchor: "center", width: "90%" } },
-            ),
-          );
-        }
-        return;
-      }
-      // Async run: show the transcript tail from the result payload / output.txt.
-      const runId = entry.key.replace("async:", "");
-      const payload = readAsyncResultFile(RESULTS_DIR, runId);
-      const text = payload
-        ? `${payload.success ? "completed" : payload.state ?? "failed"}\n\n${payload.output ?? payload.error ?? "(no output)"}`
-        : "(run still active — transcript available after completion)";
-      await withHerdrBlocked(
-        pi,
-        "fleet inspector",
-        () => sessionCtx!.ui.custom<undefined>(
-          (_tui, theme, _keybindings, done) => ({
-            render: (width: number): string[] => [
-              ...text.split("\n").slice(-30).map((line) => `  ${line}`),
-              "",
-              `  ${theme.fg("dim", "esc/q close")}`,
-            ],
-            handleInput: (data: string): void => {
-              if (data === "\x1b" || data === "q") done(undefined);
-            },
-            invalidate: (): void => {},
-          }),
-          { overlay: true, overlayOptions: { anchor: "center", width: "90%" } },
-        ),
-      );
-    },
-  });
-
-
-  // ---- Slash commands (/unipi:subagents-*) ----
-  registerSlashCommands(pi, () => sessionCtx ?? undefined, {
-    manager,
-    config,
-    asyncDirRoot: ASYNC_DIR,
-    sessionId: asyncSessionId,
-  });
-
-  // Register info group at factory time (not session_start)
-  const registry = getInfoRegistry();
-  if (registry) {
-    registry.registerGroup({
-      id: "subagents",
-      name: "Subagents",
-      icon: "🤖",
-      priority: 80,
-      config: {
-        showByDefault: true,
-        stats: [
-          { id: "maxConcurrent", label: "Max Concurrent", show: true },
-          { id: "activeCount", label: "Active Agents", show: true },
-          { id: "enabled", label: "Enabled", show: true },
-          { id: "types", label: "Available Types", show: true },
-        ],
-      },
-      dataProvider: async () => {
-        const types = config.types || {};
-        const codeBuiltins: string[] = [...BUILTIN_TYPES];
-        const fileBuiltins = [...loadBuiltinFileAgents().keys()];
-
-        const customTypes: string[] = [];
-        for (const dir of [globalAgentsDir, workspaceAgentsDir]) {
-          try {
-            if (existsSync(dir)) {
-              for (const file of readdirSync(dir)) {
-                if (file.endsWith(".md") && !customTypes.includes(file.replace(".md", ""))) {
-                  customTypes.push(file.replace(".md", ""));
-                }
-              }
-            }
-          } catch { /* ignore */ }
-        }
-
-        const allTypes = manager.getKnownTypes();
-        const typeList = allTypes.map((t) => {
-          const isEnabled = manager.isTypeEnabled(t);
-          const scope = codeBuiltins.includes(t) || fileBuiltins.includes(t)
-            ? "builtin"
-            : customTypes.includes(t)
-              ? "custom"
-              : "config";
-          return `${t}(${scope})${isEnabled ? "" : " [disabled]"}`;
-        }).join(", ");
-
-        const activeAgents = manager.listAgents().filter((a) => a.status === "running").length;
-
-        return {
-          maxConcurrent: { value: String(manager.getMaxConcurrent()) },
-          activeCount: { value: String(activeAgents) },
-          enabled: { value: config.enabled ? "yes" : "no" },
-          types: {
-            value: allTypes.length > 0 ? allTypes[0] : "none",
-            detail: allTypes.length > 1 ? typeList : undefined,
-          },
-        };
-      },
-    });
+  function reportText(rec: SubagentRecord, report: HandoffReport, status: SubagentStatus): string {
+    const head = status === "cancelled" ? `Subagent ${rec.id} was cancelled${rec.cancelledBy === "user" ? " by the user" : ""}. Partial output:\n\n` : "";
+    return `${head}${report.text}\n\n--- subagent ${rec.id} · ${status} · ${plural(report.toolCalls, "tool call")} · ${(report.durationMs / 1000).toFixed(1)}s`;
   }
 
-  // Store session context for badge generation
-  let sessionCtx: import("@earendil-works/pi-coding-agent").ExtensionContext | null = null;
-
-  // Session start: emit MODULE_READY + capture context
-  pi.on("session_start", async (_event, ctx) => {
-    sessionCtx = ctx;
-    // FleetView keyboard activation (↓/← to inspect active work).
+  /**
+   * Wait for a run while the lead's UI can answer its approvals. Ends on the
+   * report, Esc (aborted), Ctrl+B (moved), a pending user message
+   * (interrupted) or the timeout.
+   */
+  async function waitForeground(
+    run: SubagentRun,
+    signal: AbortSignal | undefined,
+    ctx: ExtensionContext,
+    onUpdate: ((u: unknown) => void) | undefined,
+    timeoutMs: number,
+  ): Promise<{ report?: HandoffReport; interrupted?: boolean; aborted?: boolean; moved?: boolean; error?: string }> {
+    const id = run.record.id;
+    let move!: () => void;
+    const moved = new Promise<"moved">((r) => {
+      move = () => r("moved");
+    });
+    run.runtime.attachUi(ctx.ui as never);
+    delivery.attach(id);
+    fgWaits.set(id, move);
+    manager.setBackground(id, false);
+    syncUi();
+    const started = Date.now();
     try {
-      if (typeof (ctx.ui as unknown as { onTerminalInput?: unknown }).onTerminalInput === "function") {
-        (ctx.ui as unknown as {
-          onTerminalInput(handler: (data: string) => { consume?: boolean } | undefined): () => void;
-        }).onTerminalInput((data) => {
-          // Detach shortcut: detach the active foreground run.
-          if (detachParts && matchesDetachInput(data, detachParts) && activeForegroundDetach) {
-            if (activeForegroundDetach()) {
-              try {
-                ctx.ui.notify("Foreground run detached — it continues in the background.", "info");
-              } catch { /* best effort */ }
-              return { consume: true };
-            }
-          }
-          return fleetView.handleKey(data, () => {
-            try {
-              return ctx.ui.getEditorText() !== "";
-            } catch {
-              return false;
-            }
-          });
+      while (true) {
+        if (signal?.aborted) return { aborted: true };
+        if (ctx.hasPendingMessages?.()) return { interrupted: true };
+        const remaining = timeoutMs - (Date.now() - started);
+        if (remaining <= 0) return {};
+        const tick = new Promise<undefined>((r) => setTimeout(() => r(undefined), Math.min(400, remaining)));
+        const outcome = await Promise.race([run.done.then((r) => ({ report: r }), (e) => ({ error: String(e) })), moved, tick]);
+        if (outcome === "moved") return { moved: true };
+        if (outcome !== undefined) return outcome;
+        onUpdate?.({
+          content: [{ type: "text" as const, text: `Subagent "${run.record.title}" working · ${plural(manager.toolCalls(id), "tool call")}` }],
+          details: { owner: "subagents", id, title: run.record.title, profile: run.record.profile, model: run.record.model, status: "running", startedAt: run.record.startedAt } satisfies CardDetails,
         });
       }
-    } catch {
-      // Terminal input hooking is optional.
+    } finally {
+      fgWaits.delete(id);
+      run.runtime.detachUi();
+      syncUi();
+    }
+  }
+  async function runSubagent(
+    _toolCallId: string,
+    params: { title: string; task: string; profile: string; is_background?: boolean; resume?: string },
+    signal: AbortSignal | undefined,
+    onUpdate: ((u: unknown) => void) | undefined,
+    ctx: ExtensionContext,
+  ) {
+    const cwd = ctx.cwd ?? process.cwd();
+    const resumeId = params.resume?.trim() || undefined;
+    const profileName = resumeId !== undefined ? (manager.record(resumeId)?.profile ?? params.profile) : params.profile;
+    const profile = profiles.find((p) => p.id === profileName);
+    if (!profile) {
+      return textResult(`Unknown profile "${params.profile}". Available: ${profiles.map((p) => p.id).join(", ")}`, { owner: "subagents", status: "failed", title: params.title }, true);
     }
-    fleetView.setUICtx(ctx.ui);
-    emitEvent(pi, UNIPI_EVENTS.MODULE_READY, {
-      name: MODULES.SUBAGENTS || "subagents",
-      version: "0.2.0",
-      commands: [],
-      tools: ["spawn_helper", "get_helper_result"],
-    });
-  });
 
-  // Listen for badge generation requests — spawn background agent
-  pi.events.on(UNIPI_EVENTS.BADGE_GENERATE_REQUEST, async (data) => {
-    const event = data as UnipiBadgeGenerateRequestEvent;
-    if (!sessionCtx) return;
+    const start = manager.start({
+      title: params.title,
+      task: params.task,
+      profile,
+      model: resolveSubagentModel(profile, ctx, config),
+      thinking: resolveSubagentThinking(profile, ctx, config),
+      cwd,
+      leadSessionId: leadSessionId(ctx),
+      background: resumeId === undefined && params.is_background === true,
+      resume: resumeId,
+      maxConcurrent: config.maxConcurrent,
+      onStep: (record, step) => appendSubagentStep((type, data) => pi.appendEntry(type, data), record, step),
+    });
+    if ("error" in start) return textResult(start.error, { owner: "subagents", status: "failed", title: params.title, error: start.error }, true);
+    const { run } = start;
+    const rec = run.record;
+    const id = rec.id;
+    const base: CardDetails = { owner: "subagents", id, title: rec.title, profile: rec.profile, model: rec.model };
+
+    if (rec.background) {
+      delivery.detach(id, run.done);
+      return textResult(
+        `Subagent ${id} started in the background. You will receive a <subagent_completion_notification agent_id="${id}"> when it finishes; use read_subagent to wait.`,
+        { ...base, status: "running", phase: "started" },
+      );
+    }
 
-    const summary = event?.conversationSummary ?? "";
-    const prompt = summary
-      ? `Based on this conversation, generate a concise session title (MAX 5 WORDS). Reply with ONLY the title. No quotes, no explanation, no punctuation.\n\nConversation:\n${summary}`
-      : `Generate a concise session title (MAX 5 WORDS) for this session. Reply with ONLY the title. No quotes, no explanation, no punctuation.`;
+    const waited = await waitForeground(run, signal, ctx, onUpdate, 2_700_000);
+    if (waited.report) {
+      delivery.consume(id);
+      const details = doneDetails(rec, waited.report);
+      return textResult(reportText(rec, waited.report, details.status!), details, details.status !== "completed");
+    }
+    if (waited.aborted) {
+      // Esc stopped the turn: the tool result reports the cancel; a completion
+      // notice would wake the lead right after the user stopped it.
+      delivery.consume(id);
+      manager.cancel(id, "user");
+      return textResult(`The user cancelled subagent "${rec.title}" (${id}). Don't restart it unless asked; it can be resumed with resume:${id}.`, { ...base, status: "cancelled", phase: "done", cancelledBy: "user", toolCalls: manager.toolCalls(id), durationMs: Date.now() - rec.startedAt }, true);
+    }
+    delivery.detach(id, run.done);
+    manager.setBackground(id, true);
+    if (waited.moved) {
+      return textResult(
+        `The user moved subagent "${rec.title}" (${id}) to the background so you don't wait for it. It keeps working; you will receive a <subagent_completion_notification agent_id="${id}"> when it finishes. Do not wait for it with read_subagent — continue with other work, or end your turn and let the notification wake you.`,
+        { ...base, status: "running", phase: "moved" },
+      );
+    }
+    if (waited.interrupted) {
+      return textResult(
+        `A user message arrived while subagent "${rec.title}" (${id}) was working. It continues in the background. Act on the user's message first; its completion notification will arrive when it finishes (or call read_subagent({agent_id:"${id}", block:true})).`,
+        { ...base, status: "running", phase: "moved" },
+      );
+    }
+    if (waited.error) return textResult(`Subagent ${id} failed: ${waited.error}`, { ...base, status: "failed", phase: "done", error: waited.error }, true);
+    return textResult(`Subagent ${id} is still running in the background; its completion notification will arrive when it finishes.`, { ...base, status: "running", phase: "moved" });
+  }
 
-    // Try with configured model, fallback to inherit
-    let modelInput: string | undefined = undefined;
-    try {
-      const fs = await import("node:fs");
-      const path = await import("node:path");
-      const configPath = path.resolve(process.cwd(), ".unipi/config/badge.json");
-      if (fs.existsSync(configPath)) {
-        const parsed = JSON.parse(fs.readFileSync(configPath, "utf-8"));
-        if (typeof parsed.generationModel === "string" && parsed.generationModel !== "inherit") {
-          modelInput = parsed.generationModel;
-        }
+  // ── Reader registration for the shared read_subagent tool ────────────────
+  registerSubagentReader("subagents", {
+    owns: (id) => manager.record(id) !== undefined || manager.run(id) !== undefined,
+    latest: () => manager.latest(),
+    read: async (params, signal, onUpdate, ctx) => {
+      const id = params.agent_id ?? manager.latest()?.id;
+      const record = id !== undefined ? manager.record(id) : undefined;
+      if (id === undefined || record === undefined) {
+        return textResult(params.agent_id !== undefined ? `No subagent found for ${params.agent_id}.` : "No subagent has run yet.", { owner: "subagents" }, true);
       }
-    } catch { /* ignore — inherit parent model */ }
-    let resolvedModel: any = undefined;
-
-    // Check if model is available
-    if (modelInput && sessionCtx.modelRegistry) {
-      const { resolveModel } = await import("./model-resolver.js");
-      const result = resolveModel(modelInput, sessionCtx.modelRegistry);
-      if (typeof result !== "string") {
-        resolvedModel = result;
+      const base: CardDetails = { owner: "subagents", id, title: record.title, profile: record.profile, model: record.model };
+      const run = manager.run(id);
+      if (record.status !== "running" || run === undefined) {
+        const text = record.report !== undefined
+          ? `${record.status === "cancelled" ? `Cancelled${record.cancelledBy === "user" ? " by the user" : ""}. Partial output:\n\n` : ""}${record.report}\n\n--- subagent ${id} · ${record.status} · ${plural(record.toolCalls, "tool call")}`
+          : `Subagent ${id} ${record.status}${record.error !== undefined ? `: ${record.error}` : ""}`;
+        return textResult(text, { ...base, status: record.status, phase: "done", toolCalls: record.toolCalls, cancelledBy: record.cancelledBy }, record.status !== "completed");
+      }
+      if (params.block !== true) {
+        return textResult(`Subagent "${record.title}" (${id}) is running — ${plural(manager.toolCalls(id), "tool call")} so far.`, { ...base, status: "running" });
       }
-      // If result is a string (error), resolvedModel stays undefined → inherit parent
+      const wasBackground = record.background;
+      const waited = await waitForeground(run, signal, ctx, onUpdate, Math.min(600, params.timeout ?? 30) * 1000);
+      if (waited.report) {
+        delivery.consume(id);
+        const details = doneDetails(record, waited.report);
+        return textResult(reportText(record, waited.report, details.status!), details, details.status !== "completed");
+      }
+      delivery.detach(id, run.done);
+      if (wasBackground) manager.setBackground(id, true);
+      if (waited.error) return textResult(`Subagent ${id} failed: ${waited.error}`, { ...base, status: "failed", error: waited.error }, true);
+      if (waited.aborted) return textResult(`Stopped waiting for subagent ${id}; it keeps running in the background.`, { ...base, status: "running" });
+      if (waited.moved) return textResult(`The user moved subagent ${id} to the background; stop waiting and continue — its completion notification will arrive.`, { ...base, status: "running" });
+      if (waited.interrupted) return textResult(`A user message arrived while waiting for subagent "${record.title}" (${id}); it keeps running. Act on the message first.`, { ...base, status: "running" });
+      return textResult(`Subagent ${id} is still running.`, { ...base, status: "running" });
+    },
+  });
+  ensureReadSubagentTool(pi);
+
+  // Background completion notice — badge: `DONE Explore title ···· 7s · 1 tool call`.
+  pi.registerMessageRenderer("subagent-completion", (message: { details?: CardDetails & { report?: string } }, opts: { expanded?: boolean }, theme) =>
+    renderCompletion(message.details, opts.expanded === true, theme));
+
+  // Completed subagent steps as a delegated panel (shared UNI-2 renderer;
+  // historical entries keep their cards, new ones stream below them).
+  pi.registerEntryRenderer("subagent-step", (entry: { data?: DelegatedStep & { group?: string; label?: string } }, opts: { expanded?: boolean }, theme) =>
+    renderDelegatedStep(
+      entry.data as DelegatedStep,
+      opts.expanded === true,
+      theme as never,
+      { group: entry.data?.group ?? "subagent", label: entry.data?.label },
+    ));
+
+  // ── Prompt section (only while enabled) ───────────────────────────────────
+  pi.on("before_agent_start", (event, ctx) => {
+    refresh(ctx.cwd ?? process.cwd(), ctx);
+    if (!enabled) {
+      delete event.systemPromptOptions.sections["subagents"];
+      return undefined;
     }
-
-    manager.spawn(pi, sessionCtx, "name-gen", prompt, {
-      description: "Generate session name",
-      model: resolvedModel,
-      isBackground: true,
-      isolated: true,
-      maxTurns: 1,
-    });
+    const fusionActive = getSharedFusionStatus() !== undefined;
+    const out = [
+      "You can delegate self-contained subtasks to subagents with `run_subagent`. A subagent is an independent agent with its own context: it does not see this conversation, so put everything it needs in `task` — the goal, relevant paths, constraints, and exactly what to report back.",
+      "",
+      "Profiles:",
+      ...profiles.map((p) => `- ${p.id}: ${p.description}`),
+      "subagent_explore is read-only and runs on a cheaper model; subagent_general can make changes and runs on your own model, so it costs like a full extra session.",
+      "",
+      "- Use subagents for broad or parallelizable work: independent searches, investigations across several areas, or implementation slices that don't touch the same files. Skip them when a direct read or search answers the question.",
+      "- Launch independent subagents in the same response so they run in parallel, and keep their work disjoint.",
+      "- Foreground (the default) waits and returns the report. Set is_background:true only when you have other work to do meanwhile; you will receive a <subagent_completion_notification> when it finishes. Don't poll read_subagent in a loop.",
+      "- Background subagents cannot ask for approval: tool calls that would need approval are denied. Run approval-needing work in the foreground.",
+      "- The user can move a foreground subagent to the background (Ctrl+B) or cancel any subagent. When that happens, continue accordingly; don't restart a cancelled subagent unless asked.",
+      "- Resume a finished, failed, or cancelled subagent with resume:<agent_id> and a follow-up task; it keeps its context.",
+      "- The user does not see subagent output directly: summarize what matters from the report, and verify anything critical before relying on it.",
+    ];
+    if (fusionActive) out.push("While Fusion is active, do not use subagents other than the sidekick unless the user explicitly asks you to.");
+    event.systemPromptOptions.sections["subagents"] = out.join("\n");
+    return undefined;
   });
 
-  // ESC propagation: abort all agents on session shutdown.
-  // Set the guard FIRST: abortAll() settles in-flight promises, whose
-  // completion callbacks would otherwise reach a runtime that pi is about to
-  // invalidate.
-  pi.on("session_shutdown", async () => {
-    watcher.stop();
-    schedulePoller?.stopPolling();
-    sessionEnded = true;
-    manager.abortAll();
-    manager.dispose();
+  // ── Commands ──────────────────────────────────────────────────────────────
+  pi.registerCommand("unipi:subagents", {
+    description: "Open the subagent panel (also ↓ from an empty input)",
+    handler: async (_args, ctx) => {
+      if (getSharedSubagents().length === 0) {
+        ctx.ui.notify("No subagents in this session yet.", "info");
+        return;
+      }
+      await openDock(ctx);
+    },
   });
-
-  // Wire UI context for widget + age finished agents on new turn
-  pi.on("tool_execution_start", async (_event, ctx) => {
-    widget.setUICtx(ctx.ui);
-    widget.onTurnStart();
+  registerAgentsCommand(pi, { onChange: (cwd) => refresh(cwd) });
+
+  pi.on("session_start", (_event, ctx) => {
+    uiCtx = ctx;
+    stripInstalled = false;
+    fgInstalled = false;
+    workingShown = false;
+    manager.restore(ctx.cwd ?? process.cwd(), leadSessionId(ctx));
+    refresh(ctx.cwd ?? process.cwd(), ctx);
+    unsubInput?.();
+    unsubInput = ctx.hasUI ? ctx.ui.onTerminalInput(onTerminalInput) : undefined;
+    syncUi();
+  });
+  pi.on("session_shutdown", () => {
+    manager.shutdown();
+    unsubInput?.();
+    unsubInput = undefined;
+    unsubRegistry();
+    uiCtx = undefined;
   });
 
-  // Create activity tracker
-  function createActivityTracker(maxTurns?: number, onStreamUpdate?: () => void) {
-    const state: AgentActivity = {
-      activeTools: new Map(),
-      toolUses: 0,
-      turnCount: 1,
-      maxTurns,
-      tokens: "",
-      responseText: "",
-    };
-
-    const callbacks = {
-      onToolActivity: (activity: { type: "start" | "end"; toolName: string }) => {
-        if (activity.type === "start") {
-          state.activeTools.set(activity.toolName + "_" + Date.now(), activity.toolName);
-        } else {
-          for (const [key, name] of state.activeTools) {
-            if (name === activity.toolName) {
-              state.activeTools.delete(key);
-              break;
-            }
-          }
-          state.toolUses++;
-        }
-        state.tokens = safeFormatTokens(state.session);
-        onStreamUpdate?.();
-      },
-      onTextDelta: (_delta: string, fullText: string) => {
-        state.responseText = fullText;
-        onStreamUpdate?.();
-      },
-      onTurnEnd: (turnCount: number) => {
-        state.turnCount = turnCount;
-        onStreamUpdate?.();
-      },
-      onSessionCreated: (session: any) => {
-        state.session = session;
-      },
-    };
-
-    return { state, callbacks };
-  }
-
-  // ---- Agent tool ----
-
-  const builtinTypes = BUILTIN_TYPES.join(", ");
-  const enabledTypes = manager.getKnownTypes().filter((type) => manager.isTypeEnabled(type));
-  const availableTypes = enabledTypes.join(", ") || "none";
-
-  pi.registerTool(
-    defineTool({
-      name: "spawn_helper",
-      label: "Spawn Helper",
-      description: `Launch a sub-agent for parallel work.
-
-Available agent types: ${availableTypes}
-Custom types can be defined in:
-- ~/.unipi/config/agents/<name>.md (global)
-- <workspace>/.unipi/config/agents/<name>.md (project)
-
-Guidelines:
-- Use "explore" or "scout" for parallel file reads / fast codebase recon
-- Use "work" or "worker" for parallel file writes (transparent locking)
-- Use "reviewer" for code review of diffs, plans, or solutions
-- Use "researcher" for web research (needs web-api tools)
-- Use "oracle" for a second opinion on decisions before acting
-- Use "delegate" for a lightweight general delegate
-- Use run_in_background for work you don't need immediately
-- ESC kills all running agents immediately
-- Agents inherit the parent model by default`,
-      parameters: SpawnHelperParams,
-
-      // ---- Rich inline rendering ----
-
-      renderCall(args, theme) {
-        const displayName = args.type ? args.type : "Agent";
-        const desc = args.description ?? "";
-        return new Text(
-          "▸ " + theme.fg("toolTitle", theme.bold(displayName)) + (desc ? "  " + theme.fg("muted", desc) : ""),
-          0,
-          0,
-        );
-      },
-
-      renderResult(result, { expanded, isPartial }, theme) {
-        const details = result.details as any;
-        if (!details) {
-          const text = result.content[0]?.type === "text" ? result.content[0].text : "";
-          return new Text(text, 0, 0);
-        }
-
-        // inlineToolDisplay: "summary" keeps one stable row per state.
-        if (config.inlineToolDisplay === "summary") {
-          const glyph = isPartial || details.status === "running"
-            ? theme.fg("accent", SPINNER[details.spinnerFrame ?? 0])
-            : details.status === "completed"
-              ? theme.fg("success", "✓")
-              : details.status === "background"
-                ? theme.fg("dim", "■")
-                : theme.fg("error", "✗");
-          const label = details.status === "completed"
-            ? "completed"
-            : details.status === "background"
-              ? "background"
-              : details.status === "running"
-                ? "running"
-                : details.status;
-          return new Text(theme.fg("muted", `${glyph} ${label}`), 0, 0);
-        }
-
-        // Stats helper
-        const stats = (d: any) => {
-          const parts: string[] = [];
-          if (d.turnCount != null && d.turnCount > 0) parts.push(formatTurns(d.turnCount, d.maxTurns));
-          if (d.toolUses > 0) parts.push(`${d.toolUses} tool use${d.toolUses === 1 ? "" : "s"}`);
-          if (d.tokens) parts.push(d.tokens);
-          return parts.map((p) => theme.fg("dim", p)).join(" " + theme.fg("dim", "·") + " ");
-        };
-
-        // Running
-        if (isPartial || details.status === "running") {
-          const frame = SPINNER[details.spinnerFrame ?? 0];
-          const s = stats(details);
-          let line = theme.fg("accent", frame) + (s ? " " + s : "");
-          line += "\n" + theme.fg("dim", `  ⎿  ${details.activity ?? "thinking…"}`);
-          return new Text(line, 0, 0);
-        }
-
-        // Background launched
-        if (details.status === "background") {
-          return new Text(theme.fg("dim", `  ⎿  Running in background (ID: ${details.agentId})`), 0, 0);
-        }
-
-        // Completed
-        if (details.status === "completed") {
-          const duration = formatMs(details.durationMs);
-          const s = stats(details);
-          let line = theme.fg("success", "✓") + (s ? " " + s : "");
-          line += " " + theme.fg("dim", "·") + " " + theme.fg("dim", duration);
-
-          if (expanded) {
-            const resultText = result.content[0]?.type === "text" ? result.content[0].text : "";
-            if (resultText) {
-              const rlines = resultText.split("\n").slice(0, 50);
-              for (const l of rlines) {
-                line += "\n" + theme.fg("dim", `  ${l}`);
-              }
-            }
-          } else {
-            line += "\n" + theme.fg("dim", "  ⎿  Done");
-          }
-          return new Text(line, 0, 0);
-        }
-
-        // Error / Aborted / Stopped
-        const isError = details.status === "error";
-        const isStopped = details.status === "stopped";
-        const s = stats(details);
-        let line = (isStopped ? theme.fg("dim", "■") : theme.fg("error", "✗")) + (s ? " " + s : "");
-
-        if (isError) {
-          line += "\n" + theme.fg("error", `  ⎿  Error: ${details.error ?? "unknown"}`);
-        } else if (isStopped) {
-          line += "\n" + theme.fg("dim", "  ⎿  Stopped");
-        } else {
-          line += "\n" + theme.fg("warning", "  ⎿  Aborted (max turns exceeded)");
-        }
-        return new Text(line, 0, 0);
-      },
-
-      // ---- Execute ----
-
-      execute: async (toolCallId, params, signal, onUpdate, ctx) => {
-        widget.setUICtx(ctx.ui);
-        fleetView.setUICtx(ctx.ui);
-
-        // Route through the parity handler (actions, workflowScript, legacy
-        // single-child) — widget/notify plumbing lives in the deps adapters.
-        onUpdateForForeground = (details) => {
-          onUpdate?.({
-            content: [{ type: "text", text: `${details.toolUses ?? 0} tool uses...` }],
-            details,
-          });
-        };
-        try {
-          return (await handleSpawnHelper(handlerDeps, ctx, params as Record<string, unknown>, signal)) as never;
-        } finally {
-          onUpdateForForeground = () => {};
-        }
-      },
-    }),
-  );
-
-  // ---- get_helper_result tool ----
-
-  pi.registerTool(
-    defineTool({
-      name: "get_helper_result",
-      label: "Get Helper Result",
-      description: "Check status and retrieve results from a background agent or async run. Use view: true to open a live conversation overlay; nonBlocking: true to subscribe and be woken on completion.",
-      parameters: GetHelperResultParams,
-      execute: async (_toolCallId, rawParams, _signal, _onUpdate, ctx) => {
-        const params = rawParams as Record<string, unknown>;
-        const id = (params.id ?? params.agent_id) as string | undefined;
-        const nonBlocking = params.nonBlocking === true;
-        const waitAll = params.all === true;
-        const timeoutMs = typeof params.timeoutMs === "number" ? params.timeoutMs : undefined;
-
-        // ---- Async process runs ----
-        const asyncPayload = id ? readAsyncResultFile(RESULTS_DIR, id) : undefined;
-        if (asyncPayload && !nonBlocking) {
-          const duration = asyncPayload.durationMs ? `${(asyncPayload.durationMs / 1000).toFixed(1)}s` : "";
-          return textResult(
-            `Run: ${asyncPayload.runId}\nAgent: ${asyncPayload.agent ?? "unknown"} | Status: ${asyncPayload.state ?? (asyncPayload.success ? "completed" : "failed")}\n\n${asyncPayload.output ?? asyncPayload.error ?? "(no output)"}`,
-            { status: asyncPayload.success ? "completed" : "error", runId: asyncPayload.runId },
-          );
-        }
-        if (nonBlocking && id) {
-          // Persist a wake subscription: when the result file appears, the
-          // watcher delivers a followUp notification that wakes this session.
-          if (readAsyncResultFile(RESULTS_DIR, id)) {
-            return textResult(`Run ${id} already completed.`, { status: "completed", runId: id });
-          }
-          writePendingSubscription(RESULTS_DIR, asyncSessionId, id);
-          return textResult(
-            `Subscribed to run ${id}. This session will be woken on completion or failure.`,
-            { status: "subscribed", runId: id },
-          );
-        }
-
-        // ---- In-process records ----
-        const record = manager.getRecord(id as string);
-        if (!record) {
-          if (waitAll) {
-            // Wait for ALL active in-process agents.
-            const active = manager.listAgents().filter((a) => a.status === "running" || a.status === "queued");
-            if (active.length === 0) return textResult("No active agents.");
-            await Promise.race([
-              Promise.allSettled(active.map((a) => a.promise).filter(Boolean)),
-              new Promise((resolve) => setTimeout(resolve, timeoutMs ?? 1_800_000)),
-            ]);
-            return textResult(`All ${active.length} agent(s) settled (or wait timed out).`);
-          }
-          return textResult(`Helper not found: "${id}". It may have been cleaned up.`);
-        }
-
-        // Open conversation viewer overlay if requested
-        if (params.view && record.session) {
-          const activity = agentActivity.get(record.id);
-          await withHerdrBlocked(
-            pi,
-            "helper viewer",
-            () => ctx.ui.custom<undefined>(
-              (tui, theme, _keybindings, done) => {
-                return new ConversationViewer(
-                  tui,
-                  record.session!,
-                  {
-                    type: record.type,
-                    description: record.description,
-                    status: record.status,
-                    toolUses: record.toolUses,
-                    startedAt: record.startedAt,
-                    completedAt: record.completedAt,
-                  },
-                  activity,
-                  theme,
-                  done,
-                );
-              },
-              {
-                overlay: true,
-                overlayOptions: { anchor: "center", width: "90%" },
-              },
-            ),
-          );
-        }
-
-        if (params.wait && record.status === "running" && record.promise) {
-          record.resultConsumed = true;
-          await record.promise;
-        }
-
-        const duration = record.completedAt
-          ? `${((record.completedAt - record.startedAt) / 1000).toFixed(1)}s`
-          : "running";
-
-        let output =
-          `Agent: ${record.id}\n` +
-          `Type: ${record.type} | Status: ${record.status} | Tool uses: ${record.toolUses} | Duration: ${duration}\n` +
-          `Description: ${record.description}\n\n`;
-
-        if (record.status === "running") {
-          output += "Agent is still running. Use wait: true or check back later.";
-        } else if (record.status === "error") {
-          output += `Error: ${record.error}`;
-        } else {
-          const bounded = boundHelperOutput(
-            record.result?.trim() || "No output.",
-            64 * 1024,
-            record.resultArtifactPath,
-          );
-          record.resultArtifactPath = bounded.artifactPath;
-          output += bounded.text;
-        }
-
-        if (record.status !== "running" && record.status !== "queued") {
-          record.resultConsumed = true;
-        }
-
-        return textResult(output);
-      },
-    }),
-  );
+  emitEvent(pi, UNIPI_EVENTS.MODULE_READY, { module: "subagents" });
 }