@heyhuynhgiabuu/pi-task 0.1.5 → 0.2.0

package/dist/index.js

@@ -1,458 +1,74 @@
 /**
  * Task Tool — Delegate complex work to specialist agents.
  *
- * Spawns pi CLI in a tmux split pane (so you can watch it live) and
- * detects completion via RESULT.md polling. On completion, tool call
- * count and duration are reported as a notification.
+ * Spawns pi CLI in a tmux split pane (foreground) or background.
+ * Completion is detected from the subagent's final assistant message
+ * in the persistent session JSONL (stopReason gating). The final message
+ * is the authoritative result; no RESULT.md is used.
  *
  * Three agent sources:
  *   - .pi/agents/*.md        project-local agents
  *   - ~/.pi/agent/agents/*.md user-global agents (fallback)
  *
  * P0: Persistent task registry (appendEntry + JSON), --session resume,
- *     sendMessage completion notification.
- * P1: Foreground mode (background:false, inline subprocess), pane death
- *     detection, 30-minute timeout.
+ *     sendMessage completion notification, Ctrl+O expand/collapse.
+ * P1: Foreground mode (background:false), pane death detection, timeout.
  */
-import { mkdir, writeFile } from "node:fs/promises";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { execFileSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { Type } from "@sinclair/typebox";
-import { getArtifactsDir, normalizeConversationId, readConversationMetadata, readConversationRegistry, renderConversationSessions, taskArtifactName, taskIdFromArtifactName, writeConversationArtifacts, writeConversationRegistry, } from "./conversation.js";
-import { Text, truncateToWidth } from "@earendil-works/pi-tui";
-import { TASK_BACKGROUND_DEFAULT, TASK_RESULT_XML_INSTRUCTIONS, TASK_TOOL_DESCRIPTION, buildTmuxSplitWindowArgs, chooseTmuxSplitDirection, formatBackgroundReceipt, buildPiArgs, parseResultXml, formatMs, shellQuote, discoverAgents, formatAgentList, countToolUses, readRecentToolCalls, } from "./helpers.js";
+import { buildAgentToolSelection } from "./agent-tools.js";
+import { BACKGROUND_CHECK_MS, COUNT_POLL_MS, MAX_POLL_ERRORS, TASK_TIMEOUT_MS, } from "./constants.js";
+import { findJsonlSessionByName, normalizeConversationId, parseMetadataFromBody, readTaskBlock, findTaskSessionHistory, readRegistry, readTaskSessionsRegistry, renderConversationSessions, upsertTaskSessionHistory, writeConversationArtifacts, writeRegistry, writeTaskSessionsRegistry, } from "./conversation.js";
+import { TASK_BACKGROUND_DEFAULT, TASK_TOOL_DESCRIPTION, buildPiArgs, countToolUses, discoverAgents, formatAgentList, formatBackgroundReceipt, parseResultXml, shellQuote, } from "./helpers.js";
+import { completeTask, createTaskWidgetController, restoreActiveBackgroundTasks, startBackgroundPolling, startToolStatsPolling, } from "./lifecycle/index.js";
 import { runSdkSubagent } from "./subagent/runSdk.js";
 import { checkTaskCompletion, waitForTaskCompletion as waitForSessionTaskCompletion, } from "./subagent/waitCompletion.js";
-import { buildAgentToolSelection } from "./agent-tools.js";
+import { hasTmux, killAgentPane, paneExists, setPaneRemainOnExit, splitWindowPane, wrapWithPaneExitWatcher, } from "./subagent/tmux.js";
+import { buildTaskPrompt, createTaskCompleteRenderer, renderCall, renderResult, taskParametersSchema, } from "./tool/index.js";
 // ─── Constants ───────────────────────────────────────────────────────────────
 const BUNDLED_AGENT_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "agents");
-const BACKGROUND_CHECK_MS = 10_000; // poll every 10 sec
-const COUNT_POLL_MS = 3_000; // update toolcall counts every 3 sec
-const TASK_TIMEOUT_MS = 30 * 60 * 1_000; // 30 minutes
 // Conversation helpers live in ./conversation.js.
-function readRegistry(piDir) {
-    const path = join(piDir, "task-registry.json");
-    try {
-        return JSON.parse(readFileSync(path, "utf-8"));
-    }
-    catch {
-        return [];
-    }
-}
-function writeRegistry(piDir, entries) {
-    const path = join(piDir, "task-registry.json");
-    writeFileSync(path, JSON.stringify(entries, null, 2), "utf-8");
-}
-// ─── Tmux Helpers ────────────────────────────────────────────────────────────
-function tmuxCmd(args) {
-    return execFileSync("tmux", args, {
-        encoding: "utf-8",
-        stdio: ["ignore", "pipe", "pipe"],
-    }).trim();
-}
-function hasTmux() {
-    try {
-        execFileSync("tmux", ["-V"], { stdio: "ignore" });
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-function paneExists(paneId) {
-    try {
-        return tmuxCmd(["list-panes", "-a", "-F", "#{pane_id}"])
-            .split("\n")
-            .includes(paneId);
-    }
-    catch {
-        return false;
-    }
-}
-function getCurrentPaneId() {
-    try {
-        return tmuxCmd(["display-message", "-p", "#{pane_id}"]);
-    }
-    catch {
-        return null;
-    }
-}
-function getCurrentPaneSize(targetPane) {
-    try {
-        const args = ["display-message", "-p", "#{pane_width} #{pane_height}"];
-        if (targetPane)
-            args.splice(1, 0, "-t", targetPane);
-        const raw = tmuxCmd(args);
-        const [widthRaw, heightRaw] = raw.trim().split(/\s+/, 2);
-        const width = Number(widthRaw);
-        const height = Number(heightRaw);
-        if (!Number.isFinite(width) || !Number.isFinite(height))
-            return null;
-        return { width, height };
-    }
-    catch {
-        return null;
-    }
-}
-function splitWindowPane(cwd, command) {
-    const originalPane = getCurrentPaneId();
-    const paneSize = getCurrentPaneSize(originalPane);
-    const direction = chooseTmuxSplitDirection(paneSize?.width ?? 0, paneSize?.height ?? 0);
-    const paneId = tmuxCmd(buildTmuxSplitWindowArgs(cwd, command, direction, originalPane));
-    return { paneId, originalPane };
-}
-function killAgentPane(paneId, originalPane) {
-    if (paneId) {
-        try {
-            if (paneExists(paneId))
-                tmuxCmd(["kill-pane", "-t", paneId]);
-        }
-        catch {
-            /* ignore */
-        }
-    }
-    if (originalPane) {
-        try {
-            tmuxCmd(["select-pane", "-t", originalPane]);
-        }
-        catch {
-            /* ignore */
-        }
-    }
-}
-// ─── Process a completed task (sendMessage + registry cleanup) ──────────────
-function completeTask(pi, id, task, content, phase, piDir) {
-    // Kill the tmux pane if still alive
-    killAgentPane(task.paneId, task.originalPane);
-    const parsed = parseResultXml(content);
-    const durationMs = Date.now() - task.startedAt;
-    // Send completion notification
-    pi.sendMessage({
-        customType: "task-complete",
-        content: `Background task ${id} (${task.agentType}) ${phase}.\n\nResult:\n${content}`,
-        display: true,
-        details: {
-            task_id: id,
-            agent_type: task.agentType,
-            description: task.description,
-            phase,
-            status: phase,
-            result: content,
-            summary: parsed.summary,
-            findings: parsed.findings,
-            confidence: parsed.confidence,
-            duration_ms: durationMs,
-            tool_uses: task.toolUses,
-            turn_count: task.turns,
-        },
-    }, {
-        triggerTurn: true,
-        deliverAs: "followUp",
-    });
-    // Remove from registry
-    const entries = readRegistry(piDir).filter((e) => e.id !== id);
-    writeRegistry(piDir, entries);
-}
 // ─── Extension Entry Point ──────────────────────────────────────────────────
 export default function (pi) {
     // Prevent recursive loading
     if (process.env.PI_TASK_TOOL_DISABLED === "1")
         return;
     // ── Background task tracker ────────────────────────────────────────────
+    const { piDir } = discoverAgents(process.cwd(), BUNDLED_AGENT_DIR);
     const backgroundTasks = new Map();
     const foregroundTasks = new Map();
-    let widgetCtx = null;
+    const taskWidget = createTaskWidgetController(foregroundTasks, backgroundTasks);
+    const { ensureTaskWidget, clearTaskWidgetIfIdle } = taskWidget;
     // ── Restore active tasks from registry on load ──────────────────────────
-    const { piDir } = discoverAgents(process.cwd());
-    const registry = readRegistry(piDir);
-    const staleIds = [];
-    for (const entry of registry) {
-        // Only restore if artifact dir still exists
-        if (!existsSync(entry.dir)) {
-            staleIds.push(entry.id);
-            continue;
-        }
-        // Check if tmux pane is still alive
-        const paneAlive = entry.paneId ? paneExists(entry.paneId) : false;
-        if (!paneAlive) {
-            staleIds.push(entry.id);
-            continue;
-        }
-        const bgtask = {
-            dir: entry.dir,
-            agentType: entry.agentType,
-            sessionName: entry.sessionName,
-            paneId: entry.paneId,
-            originalPane: null,
-            description: entry.description,
-            startedAt: entry.startedAt,
-            toolUses: 0,
-            turns: 0,
-            conversationId: entry.conversationId,
-            recentCalls: [],
-        };
-        backgroundTasks.set(entry.id, bgtask);
-    }
-    if (staleIds.length) {
-        writeRegistry(piDir, registry.filter((e) => !staleIds.includes(e.id)));
-    }
+    restoreActiveBackgroundTasks(piDir, backgroundTasks);
     // ── Widget / timer setup ───────────────────────────────────────────────
-    let widgetTimer = null;
-    function stopWidget() {
-        if (widgetTimer) {
-            clearInterval(widgetTimer);
-            widgetTimer = null;
-        }
-    }
-    const countInterval = setInterval(() => {
-        for (const task of [
-            ...foregroundTasks.values(),
-            ...backgroundTasks.values(),
-        ]) {
-            const sessionDir = join(task.dir, "sessions");
-            // Single walk: counts + recent tool-call history with status
-            const { toolUses, turns, recent } = readRecentToolCalls(sessionDir, 12);
-            task.toolUses = toolUses;
-            task.turns = turns;
-            task.recentCalls = recent;
-        }
-    }, COUNT_POLL_MS);
-    /**
-     * Render a streaming view of one active subagent. Layout per task:
-     *
-     *   ⠋ Scout — SDK docs  • 1m 0s  11 toolcalls       (themed: accent + dim)
-     *     ├─ ✓ websearch  Model Context Protocol 2026    (green/success)
-     *     ├─ ✓ codesearch MCP reference server typescript
-     *     ├─ ✗ bash  curl -sL "https://api.github.com..."  (red/error)
-     *     └─ ⠹ read  /Users/.../scout.md                 (yellow/warning, animates)
-     *
-     * The header caret and in-progress tool marks share the same spinner
-     * frame set (rotates every WIDGET_RENDER_MS based on wall-clock time,
-     * so the animation cadence is stable regardless of TUI render rate).
-     */
-    // Theme reference is captured at setWidget time so renderWidget can use it.
-    // We don't import the Theme type because it's not exported; structural typing
-    // via `any` here is safe — the c() helper only calls `theme(color, text)`.
-    let widgetTheme = null;
-    // 8-frame Braille spinner. 80ms cadence = 12.5 FPS, which is the human
-    // perception threshold for "smooth motion" (below ~10 FPS the brain
-    // sees discrete steps; above ~12 FPS it reads as continuous rotation).
-    // Full rotation: 8 × 80ms = 640ms. Used for both per-tool in-progress
-    // marks AND the header caret (the "agent is active" indicator).
-    const WIDGET_SPINNER_FRAMES = [
-        "\u280B",
-        "\u2819",
-        "\u2838",
-        "\u2834",
-        "\u2826",
-        "\u2827",
-        "\u2807",
-        "\u280F",
-    ];
-    const WIDGET_CARET_FRAMES = WIDGET_SPINNER_FRAMES;
-    const WIDGET_RENDER_MS = 80;
-    const WIDGET_MAX_TOOL_LINES = 12;
-    const WIDGET_MAX_WIDTH = 120;
-    const TREE_MIDDLE = "\u251C\u2500"; // ├─
-    const TREE_LAST = "\u2514\u2500"; // └─
-    function c(color, text) {
-        // widgetTheme is a Theme object with a .fg(color, text) method,
-        // not a callable. Calling it as a function throws "widgetTheme is not
-        // a function" which the outer try/catch in renderWidget swallows.
-        return widgetTheme ? widgetTheme.fg(color, text) : text;
-    }
-    function renderWidget(width) {
-        // Defensive: never let a render exception kill the TUI. If anything
-        // throws (theme lookup miss, malformed session JSONL, etc.), fall
-        // back to a minimal single-line summary so the TUI stays alive.
-        try {
-            return renderWidgetInner(width);
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            const active = [
-                ...Array.from(foregroundTasks.entries()),
-                ...Array.from(backgroundTasks.entries()),
-            ];
-            if (active.length === 0)
-                return [];
-            const [, task] = active[0];
-            return [
-                truncateToWidth(`${task.agentType}  \u2022 ${formatMs(Date.now() - task.startedAt)}  (render error: ${msg})`, Math.min(width, WIDGET_MAX_WIDTH)),
-            ];
-        }
-    }
-    function ensureTaskWidget(targetCtx) {
-        if (widgetCtx || targetCtx.mode !== "tui")
-            return;
-        widgetCtx = targetCtx;
-        targetCtx.ui.setWidget("task", (tui, theme) => {
-            widgetTheme = theme ?? null;
-            widgetTimer = setInterval(() => tui.requestRender(), WIDGET_RENDER_MS);
-            // Don't keep the process alive just for the widget refresh.
-            widgetTimer.unref?.();
-            return {
-                render: (width) => renderWidget(width),
-                invalidate: () => { },
-                dispose: () => {
-                    widgetTheme = null;
-                    stopWidget();
-                },
-            };
-        });
-    }
-    function clearTaskWidgetIfIdle() {
-        if (foregroundTasks.size > 0 || backgroundTasks.size > 0)
-            return;
-        stopWidget();
-        if (widgetCtx) {
-            widgetCtx.ui.setWidget("task", undefined);
-            widgetCtx = null;
-        }
-    }
-    function renderWidgetInner(width) {
-        const active = [
-            ...Array.from(foregroundTasks.entries()),
-            ...Array.from(backgroundTasks.entries()),
-        ];
-        if (active.length === 0)
-            return [];
-        const now = Date.now();
-        const maxWidth = Math.min(width, WIDGET_MAX_WIDTH);
-        const tick = Math.floor(now / WIDGET_RENDER_MS);
-        const spinner = WIDGET_SPINNER_FRAMES[tick % WIDGET_SPINNER_FRAMES.length];
-        const caret = WIDGET_CARET_FRAMES[tick % WIDGET_CARET_FRAMES.length];
-        const lines = [];
-        for (const [, task] of active) {
-            const agentName = task.agentType.charAt(0).toUpperCase() + task.agentType.slice(1);
-            const elapsed = formatMs(now - task.startedAt);
-            const total = task.toolUses > 0 ? `  ${task.turns || task.toolUses} toolcalls` : "";
-            const description = task.description ? ` — ${task.description}` : "";
-            // Header: ▼ <Agent> — <description>  • 1m 0s  11 toolcalls
-            const header = c("accent", caret) +
-                " " +
-                c("toolTitle", agentName) +
-                c("dim", `${description}  \u2022 ${elapsed}${total}`);
-            lines.push(truncateToWidth(header, maxWidth));
-            const recent = task.recentCalls ?? [];
-            if (recent.length > 0) {
-                const slice = recent.slice(-WIDGET_MAX_TOOL_LINES);
-                slice.forEach((tc, idx) => {
-                    const isLast = idx === slice.length - 1;
-                    const connector = isLast ? TREE_LAST : TREE_MIDDLE;
-                    const isInProgress = tc.status === "in_progress";
-                    const markChar = isInProgress
-                        ? spinner
-                        : tc.status === "error"
-                            ? "\u2717"
-                            : "\u2713";
-                    const markColor = isInProgress
-                        ? "warning"
-                        : tc.status === "error"
-                            ? "error"
-                            : "success";
-                    const detailStr = tc.detail ? `  ${tc.detail}` : "";
-                    const line = "  " +
-                        c("dim", connector) +
-                        " " +
-                        c(markColor, markChar) +
-                        " " +
-                        c("text", tc.name) +
-                        c("dim", detailStr);
-                    lines.push(truncateToWidth(line, maxWidth));
-                });
-            }
-            lines.push("");
-        }
-        return lines;
-    }
+    const countInterval = startToolStatsPolling(foregroundTasks, backgroundTasks, COUNT_POLL_MS);
     // ── Polling loop (background task completion, pane death, timeout) ──────
-    const checkInterval = setInterval(async () => {
-        if (backgroundTasks.size === 0) {
-            clearTaskWidgetIfIdle();
-            return;
-        }
-        const now = Date.now();
-        const ids = Array.from(backgroundTasks.keys());
-        for (const id of ids) {
-            const task = backgroundTasks.get(id);
-            if (!task)
-                continue;
-            backgroundTasks.delete(id); // Remove atomically
-            // ── Check timeout ────────────────────────────────────────────
-            if (now - task.startedAt > TASK_TIMEOUT_MS) {
-                killAgentPane(task.paneId, task.originalPane);
-                completeTask(pi, id, task, "Task timed out after 30 minutes", "timeout", piDir);
-                continue;
-            }
-            const snapshot = await checkTaskCompletion({
-                resultPath: join(task.dir, "RESULT.md"),
-                sessionDir: task.dir,
-                sessionName: task.sessionName,
-                paneId: task.paneId,
-            });
-            if (snapshot.status === "running") {
-                backgroundTasks.set(id, task);
-                continue;
-            }
-            const phase = snapshot.status === "completed" ? "done" : "failed";
-            completeTask(pi, id, task, snapshot.content, phase, piDir);
-        }
+    const checkInterval = startBackgroundPolling({
+        backgroundTasks,
+        checkTaskCompletion,
+        killAgentPane: (paneId, originalPane) => {
+            if (paneId)
+                killAgentPane(paneId, originalPane);
+        },
+        clearTaskWidgetIfIdle,
+        completeTask,
+        TASK_TIMEOUT_MS,
+        MAX_POLL_ERRORS,
+        piDir,
+        pi,
     }, BACKGROUND_CHECK_MS);
     // ── Cleanup on shutdown ────────────────────────────────────────────────
     pi.on("session_shutdown", () => {
         clearInterval(checkInterval);
         clearInterval(countInterval);
-        stopWidget();
-        if (widgetCtx) {
-            widgetCtx.ui.setWidget("task", undefined);
-            widgetCtx = null;
-        }
+        taskWidget.dispose();
     });
     // ── Custom notification renderer ───────────────────────────────────────
-    pi.registerMessageRenderer?.("task-complete", (message, { expanded }, theme) => {
-        const d = message.details;
-        if (!d)
-            return undefined;
-        const agentType = d.agent_type || "";
-        const desc = d.description || "";
-        const summary = d.summary || "";
-        const findings = d.findings || "";
-        const confidence = d.confidence || "";
-        const durationMs = d.duration_ms || 0;
-        const toolUses = d.tool_uses || 0;
-        const turns = d.turn_count || 0;
-        let line = theme.fg("accent", agentType);
-        if (desc)
-            line += theme.fg("dim", ` - ${desc}`);
-        const useStr = toolUses > 0 ? `${turns || toolUses} toolcalls` : "";
-        const durStr = durationMs >= 1000 ? formatMs(durationMs) : "";
-        const statsParts = [useStr, durStr].filter(Boolean);
-        if (statsParts.length) {
-            line += "\n" + theme.fg("dim", statsParts.join(" • "));
-        }
-        const confStr = confidence ? confidence.toUpperCase() : "";
-        if (confStr && (statsParts.length || expanded)) {
-            const confColor = confidence === "high"
-                ? "success"
-                : confidence === "low"
-                    ? "error"
-                    : "accent";
-            line += "\n" + theme.fg(confColor, `[${confStr}]`);
-        }
-        if (expanded) {
-            if (summary)
-                line += "\n" + theme.fg("muted", summary);
-            if (findings)
-                line += "\n" + theme.fg("dim", findings);
-        }
-        if (!line.trim())
-            return undefined;
-        return new Text(line, 0, 0);
-    });
+    pi.registerMessageRenderer?.("task-complete", createTaskCompleteRenderer());
     // ── Tool Registration ──────────────────────────────────────────────────
     pi.registerTool({
         name: "task",
@@ -469,27 +85,7 @@ export default function (pi) {
             "After delegated work completes, read changed files, review diff, verify scope, and run relevant checks",
             "Send the user a concise summary of the result since the agent's output is not user-visible",
         ],
-        parameters: Type.Object({
-            agent_type: Type.String({
-                description: "The type of specialist agent to use for this task",
-            }),
-            prompt: Type.String({
-                description: "The complete task for the agent to perform. Be detailed and self-contained.",
-            }),
-            description: Type.String({
-                description: "A short (3-5 word) summary of the task",
-            }),
-            task_id: Type.Optional(Type.String({
-                description: "Resume an existing background task by id instead of starting a new task.",
-            })),
-            conversation_id: Type.Optional(Type.String({
-                description: "Durable specialist conversation id. Reuses .pi/artifacts/task-<id>/sessions when called again.",
-            })),
-            background: Type.Optional(Type.Boolean({
-                description: "Run in background (async). You will be notified when it completes. DO NOT sleep, poll, ask the task for status, or duplicate its work while it runs in background.",
-                default: true,
-            })),
-        }),
+        parameters: taskParametersSchema(),
         async execute(_toolCallId, params, signal, _onUpdate, ctx) {
             const { agents, piDir } = discoverAgents(ctx.cwd, BUNDLED_AGENT_DIR);
             const parentToolNames = pi
@@ -515,14 +111,11 @@ export default function (pi) {
             }
             // ── Resolve task identity: new, task resume, or conversation resume ──
             const conversationId = normalizeConversationId(params.conversation_id);
-            const conversationRegistry = conversationId
-                ? readConversationRegistry(piDir)
+            const taskSessionsRegistry = conversationId
+                ? readTaskSessionsRegistry(piDir)
                 : {};
-            const registeredArtifact = conversationId
-                ? conversationRegistry[conversationId]
-                : undefined;
-            const registeredTaskId = registeredArtifact
-                ? taskIdFromArtifactName(registeredArtifact)
+            const registeredTaskId = conversationId
+                ? taskSessionsRegistry[conversationId]?.task_id
                 : undefined;
             if (params.task_id &&
                 registeredTaskId &&
@@ -531,7 +124,7 @@ export default function (pi) {
                     content: [
                         {
                             type: "text",
-                            text: `conversation_id "${conversationId}" maps to ${taskArtifactName(registeredTaskId)}, not ${taskArtifactName(params.task_id)}. Omit task_id or use the mapped task id.`,
+                            text: `conversation_id "${conversationId}" maps to ${registeredTaskId}, not ${params.task_id}. Omit task_id or use the mapped task id.`,
                         },
                     ],
                     details: {
@@ -543,37 +136,21 @@ export default function (pi) {
             }
             let id;
             let sessionName;
-            let artifactDir;
-            let resultPath;
             let resume = false;
+            let resumeSessionRef;
+            const artifactsDir = join(piDir, "artifacts");
             if (registeredTaskId) {
                 id = registeredTaskId;
-                sessionName = taskArtifactName(id);
-                artifactDir = join(getArtifactsDir(piDir), sessionName);
-                resultPath = join(artifactDir, "RESULT.md");
-                if (!existsSync(artifactDir)) {
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: `conversation_id "${conversationId}" points to missing artifact directory: ${artifactDir}`,
-                            },
-                        ],
-                        details: {
-                            phase: "failed",
-                            error: "Conversation artifact dir missing",
-                            conversation_id: conversationId,
-                        },
-                        isError: true,
-                    };
-                }
-                const metadata = readConversationMetadata(join(artifactDir, "metadata.json"));
-                if (metadata?.agent_type && metadata.agent_type !== agent.name) {
+                sessionName = conversationId ?? `task-${id}`;
+                const block = readTaskBlock(piDir, id);
+                const previousMetadata = parseMetadataFromBody(block?.body);
+                const metadataAgent = previousMetadata?.agent_type;
+                if (metadataAgent && metadataAgent !== agent.name) {
                     return {
                         content: [
                             {
                                 type: "text",
-                                text: `conversation_id "${conversationId}" belongs to agent "${metadata.agent_type}", not "${agent.name}". Use the original agent_type or start a different conversation_id.`,
+                                text: `conversation_id "${conversationId}" belongs to agent "${metadataAgent}", not "${agent.name}". Use the original agent_type or start a different conversation_id.`,
                             },
                         ],
                         details: {
@@ -590,7 +167,7 @@ export default function (pi) {
                     entry?.paneId &&
                     paneExists(entry.paneId)) {
                     const bgtask = {
-                        dir: artifactDir,
+                        dir: artifactsDir,
                         agentType: entry.agentType,
                         sessionName,
                         paneId: entry.paneId,
@@ -607,7 +184,7 @@ export default function (pi) {
                         content: [
                             {
                                 type: "text",
-                                text: `Resumed conversation "${conversationId}" via ${taskArtifactName(id)}. The subagent is running in background and will notify on completion.`,
+                                text: `Resumed conversation "${conversationId}" via ${sessionName}. The subagent is running in background and will notify on completion.`,
                             },
                         ],
                         details: {
@@ -622,15 +199,31 @@ export default function (pi) {
                 }
             }
             else if (params.task_id) {
-                // Look up the task in the persistent registry
+                // Look up active tasks first, then durable completed-session history.
                 const entries = readRegistry(piDir);
-                const entry = entries.find((e) => e.id === params.task_id);
+                let entry = entries.find((e) => e.id === params.task_id || e.sessionName === params.task_id) ??
+                    findTaskSessionHistory(piDir, params.task_id) ??
+                    findJsonlSessionByName(piDir, params.task_id, agent.name);
+                // Older history entries were written before we stored the
+                // actual JSONL path needed by `pi --session`. Repair them by
+                // resolving the display session name to a session file.
+                if (entry && !entry.sessionRef) {
+                    const discovered = findJsonlSessionByName(piDir, entry.sessionName, entry.agentType);
+                    if (discovered?.sessionRef) {
+                        entry = { ...entry, sessionRef: discovered.sessionRef };
+                        upsertTaskSessionHistory(piDir, {
+                            ...entry,
+                            status: "done",
+                            background: false,
+                        });
+                    }
+                }
                 if (!entry) {
                     return {
                         content: [
                             {
                                 type: "text",
-                                text: `Unknown task_id: "${params.task_id}". No task with that ID found in the registry.`,
+                                text: `Unknown task_id: "${params.task_id}". No active or completed task session with that ID/session name was found.`,
                             },
                         ],
                         details: {
@@ -655,23 +248,23 @@ export default function (pi) {
                         isError: true,
                     };
                 }
-                // Resume: reuse existing artifact dir and session name
+                // Resume: reuse the existing session name; runtime files are
+                // flat in artifactsDir, no per-task subdir.
                 id = entry.id;
                 sessionName = entry.sessionName;
-                artifactDir = entry.dir;
-                resultPath = join(artifactDir, "RESULT.md");
                 resume = true;
+                resumeSessionRef = entry.sessionRef;
                 // If background and pane still alive, reattach to tracker
                 if (params.background !== false &&
                     entry.paneId &&
                     paneExists(entry.paneId)) {
                     const bgtask = {
-                        dir: artifactDir,
-                        agentType: agent.name,
+                        dir: artifactsDir,
+                        agentType: entry.agentType,
                         sessionName,
                         paneId: entry.paneId,
                         originalPane: null,
-                        description: params.description || entry.agentType,
+                        description: params.description || entry.description,
                         startedAt: entry.startedAt,
                         toolUses: 0,
                         turns: 0,
@@ -688,21 +281,33 @@ export default function (pi) {
                         ],
                         details: {
                             task_id: id,
-                            agent_type: agent.name,
-                            description: params.description,
+                            agent_type: entry.agentType,
+                            description: params.description || entry.description,
                             conversation_id: entry.conversationId ?? conversationId,
                             tmux_session: sessionName,
                             background: true,
                         },
                     };
                 }
+                if (!resumeSessionRef) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Task "${params.task_id}" was found, but its session JSONL file could not be resolved. Cannot resume without a --session file path.`,
+                            },
+                        ],
+                        details: {
+                            phase: "failed",
+                            error: "Task session file missing",
+                        },
+                        isError: true,
+                    };
+                }
             }
             else {
                 id = `${Date.now().toString(36)}-${randomUUID().slice(0, 4)}`;
-                sessionName = taskArtifactName(id);
-                artifactDir = join(getArtifactsDir(piDir), sessionName);
-                await mkdir(artifactDir, { recursive: true });
-                resultPath = join(artifactDir, "RESULT.md");
+                sessionName = conversationId ?? `task-${id}`;
             }
             if (conversationId && !hasTmux()) {
                 return {
@@ -721,58 +326,36 @@ export default function (pi) {
                 };
             }
             if (conversationId) {
-                await mkdir(artifactDir, { recursive: true });
-                conversationRegistry[conversationId] = taskArtifactName(id);
-                writeConversationRegistry(piDir, conversationRegistry);
-                writeConversationArtifacts({
-                    taskDir: artifactDir,
-                    taskId: id,
-                    conversationId,
-                    agentType: agent.name,
-                    sessionDir: join(artifactDir, "sessions"),
-                    sessionName,
-                    prompt: params.prompt,
-                });
+                await mkdir(artifactsDir, { recursive: true });
+                const taskSessionsRegistry = readTaskSessionsRegistry(piDir);
+                taskSessionsRegistry[conversationId] = {
+                    task_id: id,
+                    session_file: `${artifactsDir}/${id}`,
+                };
+                writeTaskSessionsRegistry(piDir, taskSessionsRegistry);
             }
             const descText = params.description || "";
             const isBackground = params.background ?? TASK_BACKGROUND_DEFAULT;
             // default true
-            // ── Write durable task context ──────────────────────────────────────
-            const contextPath = join(artifactDir, "CONTEXT.md");
-            const contextContent = [
-                `# Task: ${descText}`,
-                "",
-                `## Agent`,
-                `${agent.name} (${agent.source})`,
-                "",
-                `## Instructions`,
-                params.prompt,
-                "",
-                `## Working Directory`,
-                ctx.cwd,
-                "",
-                `## Output`,
-                `Write your result to ${resultPath}`,
-                "",
-                "Use this format:",
-                "",
-                "```",
-                TASK_RESULT_XML_INSTRUCTIONS,
-                "```",
-            ].join("\n");
-            await writeFile(contextPath, contextContent, "utf-8");
-            const promptContent = [
-                `Read ${contextPath} for your task.`,
-                `Write your findings/output to ${resultPath}`,
-                "",
-                "Format:",
-                TASK_RESULT_XML_INSTRUCTIONS,
-            ].join("\n");
-            const sessionDir = join(artifactDir, "sessions");
+            // ── Build the prompt (instructions are inlined; no CONTEXT.md file) ─
+            const promptContent = buildTaskPrompt({
+                description: descText,
+                agentName: agent.name,
+                agentSource: agent.source,
+                prompt: params.prompt,
+                cwd: ctx.cwd,
+            });
+            const sessionDir = join(artifactsDir, "sessions", id);
             await mkdir(sessionDir, { recursive: true });
             // ─── Build and run the sub-agent pi process ──────────────────────────
-            const piArgs = buildPiArgs(agent, sessionName, sessionDir, promptContent, resume, parentToolNames);
+            const piArgs = buildPiArgs(agent, sessionName, sessionDir, promptContent, resume, parentToolNames, resumeSessionRef);
             const envPrefix = `PI_TASK_TOOL_DISABLED=1`;
+            const forceTmuxBackend = process.env.PI_TASK_BACKEND === "tmux" ||
+                process.env.PI_TASK_USE_TMUX_BACKEND === "1";
+            const forceSdkBackend = process.env.PI_TASK_BACKEND === "sdk" ||
+                process.env.PI_TASK_USE_SDK_BACKEND === "1";
+            const tmuxAvailable = hasTmux();
+            const useSdkBackend = forceSdkBackend || (!forceTmuxBackend && !tmuxAvailable);
             const toolSelection = buildAgentToolSelection({
                 tools: agent.tools,
                 disallowedTools: agent.disallowedTools,
@@ -792,7 +375,7 @@ export default function (pi) {
             const foregroundTask = isBackground
                 ? undefined
                 : {
-                    dir: artifactDir,
+                    dir: artifactsDir,
                     agentType: agent.name,
                     sessionName,
                     originalPane: null,
@@ -807,11 +390,13 @@ export default function (pi) {
                 foregroundTasks.set(id, foregroundTask);
                 ensureTaskWidget(ctx);
             }
-            // Prefer tmux for observability, but fall back to the SDK in headless/CI/RPC.
-            if (!hasTmux()) {
+            // Prefer tmux when the parent Pi is running inside tmux so users can watch
+            // the subagent's interactive Pi TUI. Fall back to the SDK only when tmux is
+            // unavailable, or when explicitly forced with PI_TASK_BACKEND=sdk.
+            if (useSdkBackend) {
                 if (isBackground) {
                     const bgtask = {
-                        dir: artifactDir,
+                        dir: artifactsDir,
                         agentType: agent.name,
                         sessionName,
                         originalPane: null,
@@ -830,18 +415,22 @@ export default function (pi) {
                         sessionName,
                         startedAt: bgtask.startedAt,
                         piDir,
-                        dir: artifactDir,
+                        dir: artifactsDir,
                         conversationId,
                     };
                     const entries = readRegistry(piDir);
                     entries.push(entry);
                     writeRegistry(piDir, entries);
+                    upsertTaskSessionHistory(piDir, {
+                        ...entry,
+                        status: "running",
+                        background: true,
+                    });
                     pi.appendEntry("task-registry", entry);
                     ensureTaskWidget(ctx);
                     void runSdkFallback()
                         .then(async ({ output }) => {
                         const finalOutput = output || "SDK subagent completed without assistant text.";
-                        await writeFile(resultPath, finalOutput, "utf-8");
                         backgroundTasks.delete(id);
                         clearTaskWidgetIfIdle();
                         completeTask(pi, id, bgtask, finalOutput, "done", piDir);
@@ -856,14 +445,12 @@ export default function (pi) {
                         content: [
                             {
                                 type: "text",
-                                text: `Task ${id} started with SDK backend (tmux unavailable).`,
+                                text: `Task ${id} started with SDK backend.`,
                             },
                         ],
                         details: {
                             task_id: id,
                             background: true,
-                            backend: "sdk",
-                            result_path: resultPath,
                             conversation_id: conversationId,
                         },
                     };
@@ -871,14 +458,23 @@ export default function (pi) {
                 try {
                     const { output, sessionPath } = await runSdkFallback();
                     const finalOutput = output || "SDK subagent completed without assistant text.";
-                    await writeFile(resultPath, finalOutput, "utf-8");
+                    if (conversationId) {
+                        writeConversationArtifacts({
+                            piDir,
+                            taskId: id,
+                            conversationId,
+                            agentType: agent.name,
+                            sessionFile: sessionPath ?? "unknown",
+                            prompt: params.prompt,
+                            result: finalOutput,
+                        });
+                    }
                     return {
                         content: [{ type: "text", text: finalOutput }],
                         details: {
                             phase: "done",
                             backend: "sdk",
                             session_path: sessionPath,
-                            result_path: resultPath,
                             conversation_id: conversationId,
                         },
                     };
@@ -903,12 +499,15 @@ export default function (pi) {
                 }
             }
             const shellCommand = `${envPrefix} pi ${piArgs.map((a) => shellQuote(a)).join(" ")}`;
+            const sessionFile = join(sessionDir, sessionName + ".jsonl");
+            const tmuxCommand = wrapWithPaneExitWatcher(sessionFile, `cd ${shellQuote(ctx.cwd)} && ${shellCommand}`);
             let paneId;
             let originalPane;
             try {
-                const splitResult = splitWindowPane(ctx.cwd, `cd ${shellQuote(ctx.cwd)} && ${shellCommand}`);
+                const splitResult = splitWindowPane(ctx.cwd, tmuxCommand);
                 paneId = splitResult.paneId;
                 originalPane = splitResult.originalPane;
+                setPaneRemainOnExit(paneId, true);
                 if (foregroundTask) {
                     foregroundTask.paneId = paneId;
                     foregroundTask.originalPane = originalPane;
@@ -930,38 +529,101 @@ export default function (pi) {
             }
             // ── FOREGROUND MODE: block until result, return directly ────────────
             if (!isBackground) {
-                const startedAt = Date.now();
+                const startedAt = foregroundTask?.startedAt ?? Date.now();
+                upsertTaskSessionHistory(piDir, {
+                    id,
+                    agentType: agent.name,
+                    description: descText,
+                    sessionName,
+                    startedAt,
+                    paneId,
+                    piDir,
+                    dir: artifactsDir,
+                    conversationId,
+                    status: "running",
+                    background: false,
+                });
+                // Poll tool-call progress while waiting for completion
+                let lastToolCalls = -1;
+                const onAbort = () => clearInterval(toolProgressInterval);
+                const toolProgressInterval = setInterval(() => {
+                    try {
+                        const stats = countToolUses(sessionDir, sessionName);
+                        if (stats.toolUses > 0 && stats.toolUses !== lastToolCalls) {
+                            lastToolCalls = stats.toolUses;
+                            _onUpdate?.({
+                                content: [
+                                    {
+                                        type: "text",
+                                        text: `${stats.toolUses} tool call${stats.toolUses !== 1 ? "s" : ""}`,
+                                    },
+                                ],
+                                details: { toolCalls: stats.toolUses },
+                            });
+                        }
+                    }
+                    catch {
+                        // session file may not exist yet
+                    }
+                }, COUNT_POLL_MS);
+                signal?.addEventListener("abort", onAbort, { once: true });
                 const completion = await waitForSessionTaskCompletion({
-                    resultPath,
                     sessionDir,
                     sessionName,
                     paneId,
                     signal,
-                    timeoutMs: 30 * 60 * 1000,
+                    timeoutMs: TASK_TIMEOUT_MS,
+                    pollMs: 1000,
+                    sinceMs: startedAt,
                 });
+                clearInterval(toolProgressInterval);
+                signal?.removeEventListener("abort", onAbort);
                 const content = completion.content;
                 const phase = completion.status === "completed"
                     ? "done"
                     : completion.status === "cancelled"
                         ? "cancelled"
                         : "failed";
-                killAgentPane(paneId, originalPane);
+                const completedSessionRef = findJsonlSessionByName(piDir, sessionName, agent.name)?.sessionRef;
+                upsertTaskSessionHistory(piDir, {
+                    id,
+                    agentType: agent.name,
+                    description: descText,
+                    sessionName,
+                    startedAt,
+                    paneId,
+                    piDir,
+                    dir: artifactsDir,
+                    conversationId,
+                    sessionRef: completedSessionRef,
+                    status: phase,
+                    completedAt: Date.now(),
+                    background: false,
+                });
+                if (phase === "done") {
+                    killAgentPane(paneId, originalPane);
+                }
                 foregroundTasks.delete(id);
                 clearTaskWidgetIfIdle();
+                if (conversationId) {
+                    writeConversationArtifacts({
+                        piDir,
+                        taskId: id,
+                        conversationId,
+                        agentType: agent.name,
+                        sessionFile: `${sessionDir}/${sessionName}`,
+                        prompt: params.prompt,
+                        result: content,
+                    });
+                }
                 const parsed = parseResultXml(content);
                 const durationMs = Date.now() - startedAt;
-                const { toolUses, turns } = countToolUses(sessionDir);
+                const { toolUses, turns } = countToolUses(sessionDir, sessionName);
                 return {
                     content: [
                         {
                             type: "text",
-                            text: [
-                                `${parsed.status || "done"}: ${parsed.summary || content.slice(0, 300)}`,
-                                toolUses > 0 ? `\n${turns || toolUses} toolcalls` : "",
-                                durationMs >= 1000 ? `\n${formatMs(durationMs)}` : "",
-                            ]
-                                .filter(Boolean)
-                                .join(""),
+                            text: parsed.summary || content.trim(),
                         },
                     ],
                     details: {
@@ -969,7 +631,7 @@ export default function (pi) {
                         agent_type: agent.name,
                         description: descText,
                         phase,
-                        status: phase === "done" ? parsed.status || "done" : phase,
+                        status: "done",
                         summary: parsed.summary || "",
                         findings: parsed.findings || "",
                         evidence: parsed.evidence || "",
@@ -984,7 +646,7 @@ export default function (pi) {
             }
             // ── BACKGROUND MODE (default): add to tracker, return immediately ─────
             const bgtask = {
-                dir: artifactDir,
+                dir: artifactsDir,
                 agentType: agent.name,
                 sessionName,
                 paneId,
@@ -1003,16 +665,21 @@ export default function (pi) {
                 agentType: agent.name,
                 description: descText,
                 sessionName,
-                startedAt: Date.now(),
+                startedAt: bgtask.startedAt,
                 paneId,
                 piDir,
-                dir: artifactDir,
+                dir: artifactsDir,
                 conversationId,
             };
             // Write to JSON registry for on-load restore
             const entries = readRegistry(piDir);
             entries.push(entry);
             writeRegistry(piDir, entries);
+            upsertTaskSessionHistory(piDir, {
+                ...entry,
+                status: "running",
+                background: true,
+            });
             // Also persist to session store via appendEntry (audit trail)
             pi.appendEntry("task-registry", entry);
             // ── Abort signal handling ──────────────────────────────────────────
@@ -1024,13 +691,7 @@ export default function (pi) {
                     // Clean registry
                     const remaining = readRegistry(piDir).filter((e) => e.id !== id);
                     writeRegistry(piDir, remaining);
-                    if (backgroundTasks.size === 0) {
-                        stopWidget();
-                        if (widgetCtx) {
-                            widgetCtx.ui.setWidget("task", undefined);
-                            widgetCtx = null;
-                        }
-                    }
+                    clearTaskWidgetIfIdle();
                 }, { once: true });
             }
             // ── Sticky widget ──────────────────────────────────────────────────
@@ -1043,7 +704,7 @@ export default function (pi) {
                             taskId: id,
                             agentType: agent.name,
                             tmuxSession: sessionName,
-                            artifactDir,
+                            artifactDir: artifactsDir,
                         }),
                     },
                 ],
@@ -1056,70 +717,8 @@ export default function (pi) {
                 },
             };
         },
-        renderCall(args, theme, _context) {
-            const agentName = args.agent_type || "...";
-            const desc = args.description || "";
-            let text = theme.fg("toolTitle", "");
-            text += theme.fg("accent", agentName);
-            if (desc)
-                text += theme.fg("dim", ` - ${desc}`);
-            return new Text(text, 0, 0);
-        },
-        renderResult(result, { expanded }, theme, _context) {
-            const d = result.details;
-            if (!d)
-                return new Text("", 0, 0);
-            if (d.background) {
-                return new Text("", 0, 0);
-            }
-            if (d.phase === "timeout" ||
-                d.phase === "aborted" ||
-                d.phase === "failed") {
-                const line = theme.fg("error", "x") + " " + theme.fg("dim", `[${d.phase}]`);
-                return new Text(line, 0, 0);
-            }
-            const isError = d.status === "failure" ||
-                d.status === "blocked" ||
-                d.status === "unknown" ||
-                d.status === "timeout" ||
-                d.status === "failed";
-            const durationMs = d.duration_ms || 0;
-            const toolUses = d.tool_uses || 0;
-            const turns = d.turn_count || 0;
-            const useStr = toolUses > 0 ? `${turns || toolUses} toolcalls` : "";
-            const durStr = durationMs >= 1000 ? formatMs(durationMs) : "";
-            const statsParts = [useStr, durStr].filter(Boolean);
-            const statsStr = statsParts.length
-                ? " " + theme.fg("dim", statsParts.join(" • "))
-                : "";
-            const icon = isError ? theme.fg("error", "x") : theme.fg("success", "✓");
-            const statusLabel = d.status && d.status !== "done" ? d.status : "done";
-            let line = icon +
-                " " +
-                theme.fg(isError ? "error" : "success", statusLabel) +
-                statsStr;
-            if (expanded) {
-                const s = d.summary || "";
-                const f = d.findings || "";
-                const e = d.evidence || "";
-                if (s)
-                    line += "\n" + theme.fg("muted", s);
-                if (f)
-                    line += "\n" + theme.fg("dim", f);
-                if (e)
-                    line += "\n" + theme.fg("muted", "Evidence: ") + theme.fg("dim", e);
-            }
-            else {
-                const preview = (d.summary || "").slice(0, 80);
-                if (preview)
-                    line += "\n" + theme.fg("dim", `  ⎿  ${preview}`);
-                else
-                    line +=
-                        "\n" +
-                            theme.fg("dim", `  ⎿  ${isError ? d.status || "error" : "Done"}`);
-            }
-            return new Text(line, 0, 0);
-        },
+        renderCall,
+        renderResult,
     });
     pi.registerCommand("task-sessions", {
         description: "List durable pi-task conversations",