@pinet/slack-bridge 0.1.2 → 0.2.1

package/dist/pinet-tools.js

@@ -2,6 +2,7 @@ import os from "node:os";
 import { buildCompactPinetReadDetails, formatPinetReadResultCompact, formatPinetReadResultFull, } from "@pinet/pinet-core/pinet-read-formatting";
 import { normalizePinetOutputOptions, } from "@pinet/pinet-core/output-options";
 import { parseScheduledWakeupDelay, resolveScheduledWakeupFireAt, } from "@pinet/pinet-core/scheduled-wakeups";
+import { Text } from "@earendil-works/pi-tui";
 import { Type } from "@sinclair/typebox";
 import { buildAgentDisplayInfo, filterAgentsForMeshVisibility, formatAgentList, rankAgentsForRouting, } from "./helpers.js";
 import { isBroadcastChannelTarget } from "./broker/agent-messaging.js";
@@ -10,8 +11,16 @@ import { HEARTBEAT_INTERVAL_MS } from "./broker/client.js";
 const PINET_DISPATCHER_EXAMPLES = {
     send: [{ action: "send", args: { to: "@worker", message: "Please review PR #123" } }],
     read: [
+        // Routine inbox drain: defaults are `unread_only: true` + `mark_read: true`,
+        // so this returns and consumes only this agent's unread rows. The compact
+        // output already includes capped per-message previews; no `full=true` needed.
+        { action: "read", args: { limit: 20 } },
+        // Same defaults, scoped to one thread.
         { action: "read", args: { thread_id: "a2a:<broker>:<worker>", limit: 20 } },
-        { action: "read", args: { unread_only: false, mark_read: false, full: true } },
+        // Non-destructive latest-history peek (does NOT mark anything read or
+        // change unread state). Use only when you need to revisit recently-read
+        // context, not as a routine inbox read.
+        { action: "read", args: { unread_only: false, mark_read: false, limit: 5 } },
     ],
     free: [{ action: "free", args: { note: "Wrapped up <issue>" } }],
     snooze: [
@@ -19,14 +28,20 @@ const PINET_DISPATCHER_EXAMPLES = {
         { action: "snooze", args: { op: "clear" } },
     ],
     schedule: [{ action: "schedule", args: { delay: "30m", message: "Check queue state" } }],
-    agents: [{ action: "agents", args: { repo: "<repo>", role: "worker", full: true } }],
+    agents: [{ action: "agents", args: { repo: "<repo>", role: "worker" } }],
+    spawn: [
+        {
+            action: "spawn",
+            args: { task: "Review PR #123", repo: "extensions", role: "reviewer", lane_id: "issue-123" },
+        },
+    ],
     ports: [
         { action: "ports", args: { op: "acquire", purpose: "preview", ttl_ms: 600000 } },
         { action: "ports", args: { op: "renew", lease_id: "<lease-id>", ttl_ms: 600000 } },
         { action: "ports", args: { op: "list", include_inactive: true } },
     ],
     lanes: [
-        { action: "lanes", args: { op: "list", full: true } },
+        { action: "lanes", args: { op: "list" } },
         {
             action: "lanes",
             args: {
@@ -44,9 +59,10 @@ const PINET_DISPATCHER_EXAMPLES = {
 const PINET_OUTPUT_OPTION_PARAMETERS = {
     format: Type.Optional(Type.String({ description: 'Response presentation format: "cli" (default) or "json".' })),
     full: Type.Optional(Type.Boolean({
-        description: "Include full verbose text/details; default cli output keeps data.details compact.",
+        description: "Include full verbose text/details. JSON format alone keeps data.details compact.",
     })),
 };
+const PINET_COMPACT_LIST_LIMIT = 10;
 function getRecordString(record, key) {
     const value = record?.[key];
     return typeof value === "string" && value.trim() ? value : undefined;
@@ -75,6 +91,7 @@ function normalizeDispatcherAction(value) {
         "agents",
         "lanes",
         "ports",
+        "spawn",
         "reload",
         "exit",
     ];
@@ -119,7 +136,8 @@ function classifyPinetError(message) {
         message.includes("lease_id") ||
         message.includes("ttl_ms") ||
         message.includes("purpose") ||
-        message.includes("port")) {
+        message.includes("port") ||
+        message.includes("spawn")) {
         return {
             class: "input",
             message,
@@ -159,7 +177,7 @@ function formatPinetHelpCliText(data) {
         const description = typeof data.description === "string" && data.description.trim()
             ? ` — ${data.description.trim()}`
             : "";
-        return `Pinet ${data.action}${description}. Use args.format="json" or args.full=true for schema/details; JSON/full output can fill context quickly.`;
+        return `Pinet ${data.action}${description}. Use args.format="json" for the compact envelope, or args.full=true for verbose schema/debug details.`;
     }
     return null;
 }
@@ -172,14 +190,14 @@ function getPinetEnvelopeCliText(envelope) {
         if (helpText)
             return helpText;
         const action = typeof envelope.data.action === "string" ? ` ${envelope.data.action}` : "";
-        return `Pinet${action} succeeded. Use args.format="json" or args.full=true for details; JSON/full output can fill context quickly.`;
+        return `Pinet${action} succeeded. Use args.format="json" for the compact envelope, or args.full=true for verbose details.`;
     }
     const errors = envelope.errors.map((error) => error.message).filter(Boolean);
     const hints = Array.from(new Set(envelope.errors.map((error) => error.hint).filter((hint) => hint.length > 0)));
     if (errors.length > 0) {
         return `Pinet ${envelope.status}: ${errors.join("; ")}${hints.length > 0 ? ` Hint: ${hints.join(" ")}` : ""}`;
     }
-    return `Pinet ${envelope.status}. Use args.format="json" or args.full=true for details; JSON/full output can fill context quickly.`;
+    return `Pinet ${envelope.status}. Use args.format="json" for the compact envelope, or args.full=true for verbose details.`;
 }
 function getTolerantPinetOutputOptions(value) {
     if (!isRecord(value))
@@ -212,29 +230,165 @@ function shouldRenderStructuredPinetEnvelope(envelope, output) {
     const text = envelope.data.text;
     return typeof text !== "string" || text.length === 0;
 }
-function wrapDispatcherEnvelope(envelope, output = { format: "cli", full: false }) {
+function wrapDispatcherEnvelope(envelope, output = { format: "cli", full: false }, expandedText, displayText) {
     return {
         content: [
             {
                 type: "text",
                 text: shouldRenderStructuredPinetEnvelope(envelope, output)
-                    ? JSON.stringify(envelope, null, 2)
+                    ? JSON.stringify(envelope, null, output.full ? 2 : 0)
                     : getPinetEnvelopeCliText(envelope),
             },
         ],
         details: envelope,
+        ...(expandedText ? { expandedText } : {}),
+        ...(displayText ? { displayText } : {}),
+    };
+}
+function isPinetDispatcherEnvelope(value) {
+    if (!isRecord(value))
+        return false;
+    if (value.status !== "succeeded" && value.status !== "failed")
+        return false;
+    return Array.isArray(value.errors) && Array.isArray(value.warnings);
+}
+function getFirstTextContent(result) {
+    return (result.content?.find((block) => block.type === "text" && typeof block.text === "string")
+        ?.text ?? "");
+}
+function parsePinetDispatcherEnvelopeFromText(text) {
+    if (!text.trim().startsWith("{"))
+        return null;
+    try {
+        const parsed = JSON.parse(text);
+        return isPinetDispatcherEnvelope(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function summarizeDetailValue(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value)) {
+        return `${value.length} item${value.length === 1 ? "" : "s"}`;
+    }
+    if (typeof value === "object") {
+        const entries = Object.entries(value);
+        if (entries.length === 0)
+            return "{}";
+        const inline = entries
+            .slice(0, 6)
+            .map(([key, nested]) => {
+            if (nested === null || ["string", "number", "boolean"].includes(typeof nested)) {
+                return `${key}=${String(nested)}`;
+            }
+            return `${key}=…`;
+        })
+            .join(", ");
+        return `{ ${inline}${entries.length > 6 ? ", …" : ""} }`;
+    }
+    return String(value);
+}
+// Renders `data.details` as compact key lines. Arrays and nested objects are
+// summarized (count / inlined keys) so the expanded view never JSON-dumps a
+// wall of structured data into the operator's TUI.
+function formatPrimitiveDetails(details) {
+    return Object.entries(details).map(([key, value]) => `${key}: ${summarizeDetailValue(value)}`);
+}
+const PINET_SEND_PREVIEW_MAX = 80;
+const PINET_SEND_BODY_MAX = 600;
+// Single-line, whitespace-collapsed, length-capped preview of a sent message.
+// Operator-facing only; kept short so model/CLI text stays compact.
+function formatMessagePreview(message, maxLength = PINET_SEND_PREVIEW_MAX) {
+    const collapsed = message.replace(/\s+/g, " ").trim();
+    if (collapsed.length <= maxLength)
+        return collapsed;
+    return `${collapsed.slice(0, Math.max(0, maxLength - 1))}…`;
+}
+function countMessageLines(message) {
+    if (message.length === 0)
+        return 0;
+    return message.split(/\r?\n/).length;
+}
+// Capped multi-line body for the expanded TUI card. Preserves line breaks so the
+// operator can see structure, but truncates very long bodies.
+function capMessageBody(message, maxLength = PINET_SEND_BODY_MAX) {
+    if (message.length <= maxLength)
+        return message;
+    return `${message.slice(0, Math.max(0, maxLength - 1))}…`;
+}
+function formatSentMessageSuffix(message) {
+    const preview = formatMessagePreview(message);
+    if (!preview)
+        return "";
+    const lines = countMessageLines(message);
+    return ` · “${preview}”${lines > 1 ? ` (${lines} lines)` : ""}`;
+}
+function buildSentMessageExpandedText(fields, message) {
+    const lines = fields
+        .filter((entry) => entry[1] !== undefined)
+        .map(([label, value]) => `${label}: ${value}`);
+    const chars = message.length;
+    const lineCount = countMessageLines(message);
+    lines.push(`message (${lineCount} line${lineCount === 1 ? "" : "s"}, ${chars} chars):`);
+    lines.push(capMessageBody(message));
+    return lines.join("\n");
+}
+function formatPinetEnvelopeExpandedText(envelope, expandedText) {
+    const lines = [getPinetEnvelopeCliText(envelope)];
+    if (envelope.status === "failed") {
+        lines.push(`status: ${envelope.status}`);
+        for (const error of envelope.errors) {
+            lines.push(`error[${error.class}]: ${error.message}`);
+            if (error.hint)
+                lines.push(`hint: ${error.hint}`);
+        }
+    }
+    else if (expandedText && expandedText.trim().length > 0) {
+        lines.push(...expandedText.split("\n"));
+    }
+    else if (isRecord(envelope.data)) {
+        lines.push(`status: ${envelope.status}`);
+        const action = typeof envelope.data.action === "string" ? envelope.data.action : undefined;
+        if (action)
+            lines.push(`action: ${action}`);
+        const details = envelope.data.details;
+        if (isRecord(details)) {
+            lines.push("details:");
+            lines.push(...formatPrimitiveDetails(details).map((line) => `  ${line}`));
+        }
+    }
+    for (const warning of envelope.warnings) {
+        lines.push(`warning: ${warning}`);
+    }
+    return lines.join("\n");
+}
+export function formatPinetDispatcherResultForDisplay(result, expanded) {
+    const firstText = getFirstTextContent(result);
+    const envelope = isPinetDispatcherEnvelope(result.details)
+        ? result.details
+        : parsePinetDispatcherEnvelopeFromText(firstText);
+    if (!envelope) {
+        return { status: "unknown", text: firstText || "Pinet result." };
+    }
+    return {
+        status: envelope.status,
+        text: expanded
+            ? formatPinetEnvelopeExpandedText(envelope, result.expandedText)
+            : (result.displayText ?? getPinetEnvelopeCliText(envelope)),
     };
 }
 function selectPinetResultDetails(result, output) {
-    if (output.format === "json" || output.full) {
-        return result.details ?? null;
+    if (output.full) {
+        return result.fullDetails ?? result.details ?? null;
     }
     if (result.compactDetails !== undefined) {
         return result.compactDetails;
     }
     return result.details ?? null;
 }
-function buildPinetDispatcherHelpEnvelope(args, actions) {
+function buildPinetDispatcherHelpEnvelope(args, actions, output) {
     const topic = typeof args.topic === "string" && args.topic.trim()
         ? args.topic.trim().toLowerCase()
         : undefined;
@@ -245,13 +399,19 @@ function buildPinetDispatcherHelpEnvelope(args, actions) {
             action: definition.name,
             description: definition.description,
             guardrail_tool: `pinet:${definition.name}`,
-            args_schema: definition.parameters,
-            examples: PINET_DISPATCHER_EXAMPLES[definition.name] ?? [],
+            ...(output.full
+                ? {
+                    args_schema: definition.parameters,
+                    examples: PINET_DISPATCHER_EXAMPLES[definition.name] ?? [],
+                }
+                : {}),
         }))
             .sort((a, b) => a.action.localeCompare(b.action));
         return buildPinetDispatcherEnvelope("succeeded", {
             actions: catalog,
-            note: "Use args.topic to inspect a single action schema.",
+            note: output.full
+                ? "Use args.topic to inspect a single action schema."
+                : "Use args.topic to inspect a single action schema; add args.full=true for the full catalog schemas/examples.",
         });
     }
     const definition = actions.get(topic);
@@ -306,17 +466,19 @@ function runPinetSendAction(params, deps, toolName, output) {
         if (transferThreadId && isBroadcastChannelTarget(to)) {
             throw new Error("transfer_thread_id requires a direct agent target, not a broadcast channel.");
         }
+        const previewSuffix = formatSentMessageSuffix(message);
         if (deps.brokerRole() === "broker" && isBroadcastChannelTarget(to)) {
             const result = deps.sendPinetBroadcastMessage(to, message);
             const preview = result.recipients.slice(0, 5).join(", ");
             const suffix = result.recipients.length > 5 ? ", …" : "";
+            const recipientList = result.recipients.join(", ");
             return {
                 content: [
                     {
                         type: "text",
                         text: output.full
                             ? `Broadcast sent to ${result.channel} (${result.recipients.length} agents: ${preview}${suffix}).`
-                            : `Pinet broadcast sent to ${result.channel} (${result.recipients.length} recipients).`,
+                            : `Pinet broadcast sent to ${result.channel} (${result.recipients.length} recipients)${previewSuffix}.`,
                     },
                 ],
                 details: {
@@ -324,6 +486,26 @@ function runPinetSendAction(params, deps, toolName, output) {
                     messageIds: result.messageIds,
                     recipients: result.recipients,
                 },
+                compactDetails: {
+                    channel: result.channel,
+                    messageCount: result.messageIds.length,
+                    recipientCount: result.recipients.length,
+                    recipients: result.recipients.slice(0, PINET_COMPACT_LIST_LIMIT),
+                    recipientsTruncated: Math.max(0, result.recipients.length - PINET_COMPACT_LIST_LIMIT),
+                },
+                fullDetails: {
+                    channel: result.channel,
+                    messageIds: result.messageIds,
+                    recipients: result.recipients,
+                },
+                machineText: output.full
+                    ? `Broadcast sent to ${result.channel} (${result.recipients.length} agents: ${preview}${suffix}).`
+                    : `Pinet broadcast sent to ${result.channel} (${result.recipients.length} recipients).`,
+                expandedText: buildSentMessageExpandedText([
+                    ["to", result.channel],
+                    ["recipients", `${result.recipients.length} (${recipientList})`],
+                    ["message ids", result.messageIds.join(", ")],
+                ], message),
             };
         }
         const result = transferThreadId
@@ -331,13 +513,16 @@ function runPinetSendAction(params, deps, toolName, output) {
                 threadOwnershipTransfer: { mode: "transfer", threadId: transferThreadId },
             })
             : await deps.sendPinetAgentMessage(to, message);
+        const transferSuffix = result.transferredThreadId
+            ? ` (${result.transferredThreadChannel})`
+            : "";
         return {
             content: [
                 {
                     type: "text",
                     text: output.full
                         ? `Message sent to ${result.target} (id: ${result.messageId})${result.transferredThreadId ? ` and transferred Slack thread ${result.transferredThreadId}${result.transferredThreadChannel ? ` (${result.transferredThreadChannel})` : ""}` : ""}.`
-                        : `Pinet message sent to ${result.target}${result.transferredThreadId ? `; transferred Slack thread ${result.transferredThreadId}` : ""}.`,
+                        : `Pinet message sent to ${result.target}${result.transferredThreadId ? `; transferred Slack thread ${result.transferredThreadId}` : ""}${previewSuffix}.`,
                 },
             ],
             details: {
@@ -348,6 +533,16 @@ function runPinetSendAction(params, deps, toolName, output) {
                     ? { transferredThreadChannel: result.transferredThreadChannel }
                     : {}),
             },
+            machineText: output.full
+                ? `Message sent to ${result.target} (id: ${result.messageId})${result.transferredThreadId ? ` and transferred Slack thread ${result.transferredThreadId}${result.transferredThreadChannel ? ` (${result.transferredThreadChannel})` : ""}` : ""}.`
+                : `Pinet message sent to ${result.target}${result.transferredThreadId ? `; transferred Slack thread ${result.transferredThreadId}` : ""}.`,
+            expandedText: buildSentMessageExpandedText([
+                ["to", result.target],
+                ["message id", result.messageId],
+                result.transferredThreadId
+                    ? ["transferred thread", `${result.transferredThreadId}${transferSuffix}`]
+                    : ["transferred thread", undefined],
+            ], message),
         };
     })();
 }
@@ -367,11 +562,12 @@ function runPinetReadAction(params, deps, toolName, output) {
             throw new Error("thread_id must be a non-empty string when provided.");
         }
         const result = await deps.readPinetInbox(options);
+        const shouldRenderFull = output.full;
         return {
             content: [
                 {
                     type: "text",
-                    text: output.full
+                    text: shouldRenderFull
                         ? formatPinetReadResultFull(result, options)
                         : formatPinetReadResultCompact(result, options),
                 },
@@ -379,6 +575,10 @@ function runPinetReadAction(params, deps, toolName, output) {
             details: result,
             compactDetails: buildCompactPinetReadDetails(result),
             fullDetails: result,
+            // When the model/CLI text is the compact one-liner, give the operator the
+            // full per-message rows on expand. In full/thread mode `text` already
+            // carries the rich view, so no separate expanded body is needed.
+            ...(shouldRenderFull ? {} : { expandedText: formatPinetReadResultFull(result, options) }),
         };
     })();
 }
@@ -455,6 +655,53 @@ function runPinetSnoozeAction(params, deps, toolName) {
         return { content: [{ type: "text", text: formatRalphSnoozeResult(status) }], details: status };
     })();
 }
+function runPinetSpawnAction(params, deps, toolName, output) {
+    return (async () => {
+        const task = getMaybeString(params, "task");
+        const repo = getMaybeString(params, "repo");
+        const role = getMaybeString(params, "role") ?? "subworker";
+        const laneId = getMaybeString(params, "lane_id");
+        deps.requireToolPolicy(toolName, undefined, `task=${task ?? ""} | repo=${repo ?? ""} | role=${role} | lane_id=${laneId ?? ""}`);
+        if (!deps.pinetEnabled()) {
+            throw new Error("Pinet is not running. Use /pinet start or /pinet follow first.");
+        }
+        if (deps.brokerRole() !== "follower") {
+            throw new Error("spawn is worker-only; the broker should launch top-level followers, not own subtrees.");
+        }
+        if (!task)
+            throw new Error("spawn requires task");
+        if (!repo)
+            throw new Error("spawn requires repo");
+        if (!deps.spawnSubtreeWorker) {
+            throw new Error("subtree worker launcher is unavailable in this runtime. Start a worker subtree with /pinet subtree start and retry.");
+        }
+        const result = await deps.spawnSubtreeWorker({
+            task,
+            repo,
+            role,
+            ...(laneId ? { laneId } : {}),
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: output.full
+                        ? `Pinet subtree worker started: ${result.agentName} (${result.agentId}) in tmux session ${result.sessionName}. Task message ${result.messageId} delivered. Monitor: ${result.monitorCommand}`
+                        : `Pinet subtree worker started: ${result.agentName} (${result.agentId}). Task message ${result.messageId} delivered.`,
+                },
+            ],
+            details: result,
+            compactDetails: {
+                status: result.status,
+                agentId: result.agentId,
+                agentName: result.agentName,
+                messageId: result.messageId,
+                threadId: result.threadId,
+            },
+            fullDetails: result,
+        };
+    })();
+}
 function runPinetRemoteControlAction(params, deps, toolName, command) {
     return (async () => {
         const target = typeof params.target === "string" ? params.target.trim() : "";
@@ -495,7 +742,7 @@ function runPinetScheduleAction(params, deps, toolName, output) {
                         type: "text",
                         text: output.full
                             ? `Wake-up scheduled for ${wakeup.fireAt} (id: ${wakeup.id}).`
-                            : `Pinet wake-up scheduled for ${wakeup.fireAt}.`,
+                            : `Pinet wake-up scheduled for ${wakeup.fireAt} (id ${wakeup.id}).`,
                     },
                 ],
                 details: wakeup,
@@ -509,7 +756,7 @@ function runPinetScheduleAction(params, deps, toolName, output) {
                         type: "text",
                         text: output.full
                             ? `Wake-up scheduled for ${wakeup.fireAt} (id: ${wakeup.id}).`
-                            : `Pinet wake-up scheduled for ${wakeup.fireAt}.`,
+                            : `Pinet wake-up scheduled for ${wakeup.fireAt} (id ${wakeup.id}).`,
                     },
                 ],
                 details: wakeup,
@@ -527,11 +774,25 @@ function getAgentBranch(agent) {
 function getAgentRole(agent) {
     return getRecordString(agent.metadata, "role");
 }
+function truncatePinetDetailText(value, maxLength = 160) {
+    if (!value)
+        return null;
+    const collapsed = value.replace(/\s+/g, " ").trim();
+    if (!collapsed)
+        return null;
+    if (collapsed.length <= maxLength)
+        return collapsed;
+    return `${collapsed.slice(0, Math.max(0, maxLength - 1))}…`;
+}
 function buildCompactAgentDetails(agents, hint) {
+    const shownAgents = agents.slice(0, PINET_COMPACT_LIST_LIMIT);
     return {
         count: agents.length,
+        total: agents.length,
+        shown: shownAgents.length,
+        truncated: Math.max(0, agents.length - shownAgents.length),
         hint,
-        agents: agents.map((agent) => {
+        agents: shownAgents.map((agent) => {
             const capabilityTags = agent.capabilityTags ?? [];
             return {
                 id: agent.id,
@@ -543,8 +804,11 @@ function buildCompactAgentDetails(agents, hint) {
                 branch: getAgentBranch(agent) ?? null,
                 role: getAgentRole(agent) ?? null,
                 brokerManaged: agent.metadata?.brokerManaged === true,
-                launchSource: agent.metadata?.launchSource ?? null,
-                tmuxSession: agent.metadata?.tmuxSession ?? null,
+                parentAgentId: agent.metadata?.parentAgentId ?? null,
+                treeDepth: agent.metadata?.treeDepth ?? 0,
+                supervisionState: agent.metadata?.supervisionState ?? "root",
+                subtreeRole: agent.metadata?.subtreeRole ?? null,
+                laneId: agent.metadata?.laneId ?? null,
                 routingScore: agent.routingScore ?? null,
                 ...(agent.pendingInboxCount != null && agent.pendingInboxCount > 0
                     ? { pendingInboxCount: agent.pendingInboxCount }
@@ -555,6 +819,42 @@ function buildCompactAgentDetails(agents, hint) {
         }),
     };
 }
+function filterAgentsForHierarchyScope(agents, scope, parentAgentId) {
+    if (scope === "all" || scope === "visible")
+        return agents;
+    if (!parentAgentId)
+        return [];
+    if (scope === "children") {
+        return agents.filter((agent) => agent.parentAgentId === parentAgentId);
+    }
+    const descendants = [];
+    const seen = new Set();
+    const queue = agents.filter((agent) => agent.parentAgentId === parentAgentId);
+    while (queue.length > 0) {
+        const child = queue.shift();
+        if (!child || seen.has(child.id))
+            continue;
+        seen.add(child.id);
+        descendants.push(child);
+        queue.push(...agents.filter((agent) => agent.parentAgentId === child.id));
+    }
+    return descendants;
+}
+function formatAgentStatusBreakdown(agents) {
+    if (agents.length === 0)
+        return "";
+    const working = agents.filter((agent) => agent.status === "working").length;
+    const idle = agents.length - working;
+    const ghost = agents.filter((agent) => agent.health === "ghost").length;
+    const stale = agents.filter((agent) => agent.health === "stale").length;
+    const parts = [
+        `${working} working`,
+        `${idle} idle`,
+        ghost > 0 ? `${ghost} ghost` : null,
+        stale > 0 ? `${stale} stale` : null,
+    ].filter((item) => Boolean(item));
+    return ` (${parts.join(", ")})`;
+}
 function formatCompactAgentList(agents, hint) {
     const hintParts = [
         hint.repo ? `repo=${hint.repo}` : null,
@@ -565,7 +865,56 @@ function formatCompactAgentList(agents, hint) {
             : null,
     ].filter((item) => Boolean(item));
     const hintSuffix = hintParts.length > 0 ? `; hints ${hintParts.join(" · ")}` : "";
-    return `Pinet agents: ${agents.length} visible${hintSuffix}.`;
+    const scopeSuffix = hint.scope && hint.scope !== "visible" ? `; scope=${hint.scope}` : "";
+    const breakdown = formatAgentStatusBreakdown(agents);
+    return `Pinet agents: ${agents.length} visible${breakdown}${hintSuffix}${scopeSuffix}.`;
+}
+const PINET_AGENTS_EXPANDED_MAX_ROWS = 30;
+// Compact, aligned per-agent rows for the expanded TUI card. Avoids JSON dumps;
+// shows name/id/status-health/repo-branch/lane-or-role/pending-inbox + flags.
+function formatPinetAgentsExpanded(agents) {
+    if (agents.length === 0)
+        return "(no agents connected)";
+    const shown = agents.slice(0, PINET_AGENTS_EXPANDED_MAX_ROWS);
+    const rows = shown.map((agent) => {
+        const name = `${agent.emoji} ${agent.name}`;
+        const id = agent.id.length > 8 ? agent.id.slice(0, 8) : agent.id;
+        const healthSuffix = agent.health && agent.health !== "healthy" ? `/${agent.health}` : "";
+        const stuckSuffix = agent.stuck ? " stuck" : "";
+        const state = `${agent.status}${healthSuffix}${stuckSuffix}`;
+        const repo = getAgentRepo(agent);
+        const branch = getAgentBranch(agent);
+        const where = repo ? `${repo}${branch ? `/${branch}` : ""}` : (branch ?? "—");
+        const laneId = typeof agent.metadata?.laneId === "string" ? agent.metadata.laneId : undefined;
+        const role = getAgentRole(agent);
+        const laneOrRole = laneId ? `lane:${laneId}` : (role ?? "");
+        const inbox = agent.pendingInboxCount != null && agent.pendingInboxCount > 0
+            ? `inbox:${agent.pendingInboxCount}`
+            : "";
+        return { name, id, state, where, laneOrRole, inbox };
+    });
+    const clip = (value, width) => value.length <= width ? value : `${value.slice(0, Math.max(0, width - 1))}…`;
+    const pad = (value, width) => value.length >= width ? value : `${value}${" ".repeat(width - value.length)}`;
+    const colWidth = (pick, cap) => Math.min(cap, rows.reduce((max, row) => Math.max(max, pick(row).length), 0));
+    const nameW = colWidth((row) => row.name, 28);
+    const idW = colWidth((row) => row.id, 8);
+    const stateW = colWidth((row) => row.state, 20);
+    const whereW = colWidth((row) => row.where, 30);
+    const laneW = colWidth((row) => row.laneOrRole, 18);
+    const lines = rows.map((row) => [
+        pad(clip(row.name, nameW), nameW),
+        pad(row.id, idW),
+        pad(clip(row.state, stateW), stateW),
+        pad(clip(row.where, whereW), whereW),
+        pad(clip(row.laneOrRole, laneW), laneW),
+        row.inbox,
+    ]
+        .join("  ")
+        .trimEnd());
+    if (agents.length > shown.length) {
+        lines.push(`… +${agents.length - shown.length} more`);
+    }
+    return lines.join("\n");
 }
 function formatPinetLaneSummary(lane) {
     const refs = [
@@ -639,6 +988,46 @@ function getMaybeMetadata(params) {
         return null;
     return isRecord(value) ? value : undefined;
 }
+function buildCompactPortLeaseDetails(leases) {
+    const shownLeases = leases.slice(0, PINET_COMPACT_LIST_LIMIT);
+    return {
+        leaseCount: leases.length,
+        total: leases.length,
+        shown: shownLeases.length,
+        truncated: Math.max(0, leases.length - shownLeases.length),
+        leases: shownLeases.map((lease) => ({
+            leaseId: lease.id,
+            host: lease.host,
+            port: lease.port,
+            status: lease.status,
+            purpose: lease.purpose,
+            ownerAgentId: lease.ownerAgentId ?? null,
+            expiresAt: lease.expiresAt,
+        })),
+    };
+}
+function buildCompactLaneDetails(lanes) {
+    const shownLanes = lanes.slice(0, PINET_COMPACT_LIST_LIMIT);
+    return {
+        laneCount: lanes.length,
+        total: lanes.length,
+        shown: shownLanes.length,
+        truncated: Math.max(0, lanes.length - shownLanes.length),
+        lanes: shownLanes.map((lane) => ({
+            laneId: lane.laneId,
+            state: lane.state,
+            name: truncatePinetDetailText(lane.name),
+            issueNumber: lane.issueNumber,
+            prNumber: lane.prNumber,
+            ownerAgentId: lane.ownerAgentId,
+            implementationLeadAgentId: lane.implementationLeadAgentId,
+            pmMode: lane.pmMode,
+            participantCount: lane.participants.length,
+            summary: truncatePinetDetailText(lane.summary),
+            lastActivityAt: lane.lastActivityAt,
+        })),
+    };
+}
 function formatPortLeaseSummary(lease) {
     return `${lease.host}:${lease.port} ${lease.status} lease=${lease.id} purpose=${lease.purpose} owner=${lease.ownerAgentId ?? "none"} expires=${lease.expiresAt}`;
 }
@@ -753,7 +1142,7 @@ function runPinetPortsAction(params, deps, toolName, output) {
             return {
                 content: [{ type: "text", text: `Pinet port leases expired: ${leases.length}.` }],
                 details: { leases },
-                compactDetails: { leaseCount: leases.length, leases: leases.slice(0, 10) },
+                compactDetails: buildCompactPortLeaseDetails(leases),
                 fullDetails: { leases },
             };
         }
@@ -773,8 +1162,12 @@ function runPinetPortsAction(params, deps, toolName, output) {
             return {
                 content: [{ type: "text", text: formatPortLeases(leases, output.full) }],
                 details: { leases },
-                compactDetails: { leaseCount: leases.length, leases: leases.slice(0, 10) },
+                compactDetails: buildCompactPortLeaseDetails(leases),
                 fullDetails: { leases },
+                // Compact text is a count; show the per-lease rows on expand.
+                ...(output.full || leases.length === 0
+                    ? {}
+                    : { expandedText: formatPortLeases(leases, true) }),
             };
         }
         throw new Error("ports op must be acquire, renew, release, status, list, or expire");
@@ -803,8 +1196,12 @@ function runPinetLanesAction(params, deps, toolName, output) {
             return {
                 content: [{ type: "text", text: formatPinetLanes(lanes, output.full) }],
                 details: { lanes },
-                compactDetails: { laneCount: lanes.length, lanes: lanes.slice(0, 10) },
+                compactDetails: buildCompactLaneDetails(lanes),
                 fullDetails: { lanes },
+                // Compact text is a count; show the per-lane rows on expand.
+                ...(output.full || lanes.length === 0
+                    ? {}
+                    : { expandedText: formatPinetLanes(lanes, true) }),
             };
         }
         if (op === "upsert") {
@@ -893,10 +1290,20 @@ function runPinetLanesAction(params, deps, toolName, output) {
 }
 function runPinetAgentsAction(params, deps, toolName, output) {
     return (async () => {
+        const scope = params.scope === "children" || params.scope === "subtree" || params.scope === "all"
+            ? params.scope
+            : "visible";
+        const requestedParentAgentId = typeof params.parent_agent === "string" ? params.parent_agent : undefined;
+        const subtreeSelfAgentId = deps.getSubtreeSelfAgentId?.() ?? undefined;
+        const parentAgentId = requestedParentAgentId ??
+            (deps.brokerRole() === "follower" && (scope === "children" || scope === "subtree")
+                ? subtreeSelfAgentId
+                : undefined);
         const hint = {
             repo: typeof params.repo === "string" ? params.repo : undefined,
             branch: typeof params.branch === "string" ? params.branch : undefined,
             role: typeof params.role === "string" ? params.role : undefined,
+            ...(scope !== "visible" ? { scope } : {}),
             requiredTools: typeof params.required_tools === "string"
                 ? params.required_tools
                     .split(",")
@@ -905,7 +1312,7 @@ function runPinetAgentsAction(params, deps, toolName, output) {
                 : undefined,
             task: typeof params.task === "string" ? params.task : undefined,
         };
-        deps.requireToolPolicy(toolName, undefined, `repo=${hint.repo ?? ""} | branch=${hint.branch ?? ""} | role=${hint.role ?? ""} | required_tools=${params.required_tools ?? ""} | task=${hint.task ?? ""} | format=${output.format} | full=${output.full}`);
+        deps.requireToolPolicy(toolName, undefined, `repo=${hint.repo ?? ""} | branch=${hint.branch ?? ""} | role=${hint.role ?? ""} | scope=${scope} | parent_agent=${parentAgentId ?? ""} | required_tools=${params.required_tools ?? ""} | task=${hint.task ?? ""} | format=${output.format} | full=${output.full}`);
         if (!deps.pinetEnabled()) {
             throw new Error("Pinet is not running. Use /pinet start or /pinet follow first.");
         }
@@ -923,12 +1330,23 @@ function runPinetAgentsAction(params, deps, toolName, output) {
             rawAgents = deps.listBrokerAgents();
         }
         else if (deps.brokerRole() === "follower") {
-            rawAgents = await deps.listFollowerAgents(includeGhosts);
+            const wantsLocalSubtree = scope === "children" || scope === "subtree";
+            const subtreeAgents = wantsLocalSubtree ? deps.listSubtreeAgents?.(includeGhosts) : null;
+            if (wantsLocalSubtree && subtreeAgents) {
+                rawAgents = subtreeAgents;
+            }
+            else if (wantsLocalSubtree && deps.listSubtreeAgents && !subtreeAgents) {
+                throw new Error("No active worker-owned subtree broker. Run /pinet subtree start first.");
+            }
+            else {
+                rawAgents = await deps.listFollowerAgents(includeGhosts);
+            }
         }
         else {
             throw new Error("Pinet is in an unexpected state.");
         }
-        const visibleAgents = filterAgentsForMeshVisibility(rawAgents, {
+        const scopedRawAgents = filterAgentsForHierarchyScope(rawAgents, scope, parentAgentId);
+        const visibleAgents = filterAgentsForMeshVisibility(scopedRawAgents, {
             now: nowMs,
             includeGhosts,
             recentDisconnectWindowMs: recentGhostWindowMs,
@@ -941,6 +1359,7 @@ function runPinetAgentsAction(params, deps, toolName, output) {
             details: { agents, hint },
             compactDetails: buildCompactAgentDetails(agents, hint),
             fullDetails: { agents, hint },
+            expandedText: formatPinetAgentsExpanded(agents),
         };
     })();
 }
@@ -966,7 +1385,7 @@ export function registerPinetTools(pi, deps) {
     });
     registerAction({
         name: "read",
-        description: "Read this agent's durable SQLite-backed Pinet inbox context with unread/read semantics. Ordinary workers only see rows addressed to their own agent identity; broker coordination visibility is limited to broker-addressed inbox rows.",
+        description: "Read this agent's durable SQLite-backed Pinet inbox context with unread/read semantics. Defaults to draining unread rows (`unread_only: true`, `mark_read: true`) with compact per-message previews — no `full=true` required for routine reads. Override `unread_only`/`mark_read` only for a non-destructive latest-history peek. Ordinary workers only see rows addressed to their own agent identity; broker coordination visibility is limited to broker-addressed inbox rows.",
         parameters: Type.Object({
             thread_id: Type.Optional(Type.String({
                 description: "Optional Pinet/Slack broker thread ID to filter this agent's own inbox rows; it does not grant cross-agent thread access.",
@@ -998,6 +1417,18 @@ export function registerPinetTools(pi, deps) {
         }),
         execute: (_id, params, _output) => runPinetSnoozeAction(params, deps, "pinet:snooze"),
     });
+    registerAction({
+        name: "spawn",
+        description: "Worker-only: launch a tmux-backed child worker into this worker's active subtree broker and deliver the task over Pinet.",
+        parameters: Type.Object({
+            task: Type.String({ description: "Scoped task prompt for the child worker" }),
+            repo: Type.String({ description: "Repo/workspace scope for the child worker" }),
+            role: Type.Optional(Type.String({ description: "Child subtree role, e.g. reviewer" })),
+            lane_id: Type.Optional(Type.String({ description: "Optional durable Pinet lane id" })),
+            ...PINET_OUTPUT_OPTION_PARAMETERS,
+        }),
+        execute: (_id, params, output) => runPinetSpawnAction(params, deps, "pinet:spawn", output),
+    });
     registerAction({
         name: "reload",
         description: "Ask another connected Pinet agent to reload itself.",
@@ -1039,6 +1470,10 @@ export function registerPinetTools(pi, deps) {
             include_ghosts: Type.Optional(Type.Boolean({
                 description: "Include recently disconnected/resumable agents. Defaults false so graceful exits do not look like actionable ghosts.",
             })),
+            scope: Type.Optional(Type.String({
+                description: "Hierarchy filter: visible (default), children, subtree, or all. children/subtree require parent_agent for explicit inspection.",
+            })),
+            parent_agent: Type.Optional(Type.String({ description: "Parent agent id for scope=children or scope=subtree" })),
             ...PINET_OUTPUT_OPTION_PARAMETERS,
         }),
         execute: (_id, params, output) => runPinetAgentsAction(params, deps, "pinet:agents", output),
@@ -1114,15 +1549,44 @@ export function registerPinetTools(pi, deps) {
         name: "pinet",
         label: "Pinet Dispatcher",
         description: "Dispatch Pinet operations by action with compact help and schema discovery.",
-        promptSnippet: 'Use this compact dispatcher for Pinet actions: send, read, free, snooze, schedule, agents, lanes, ports, reload, exit, and help. Use /pinet start, /pinet follow, and /pinet unfollow for TUI lifecycle changes. Defaults to terse CLI text; pass args.format="json" or args.full=true for explicit detail, but avoid JSON/full unless needed because it can fill context quickly.',
+        promptSnippet: 'Use this compact dispatcher for Pinet actions: send, read, free, snooze, schedule, agents, lanes, ports, reload, exit, spawn, and help. Use /pinet start, /pinet follow, /pinet unfollow, and /pinet subtree start for TUI lifecycle changes. Defaults to terse CLI text; pass args.format="json" for the compact envelope or args.full=true for verbose/debug detail.',
         parameters: Type.Object({
             action: Type.String({
-                description: "Action name: help, send, read, free, snooze, schedule, agents, lanes, ports, reload, or exit.",
+                description: "Action name: help, send, read, free, snooze, schedule, agents, lanes, ports, reload, or exit. Also supports spawn for launching worker-owned subtree children.",
             }),
             args: Type.Optional(Type.Record(Type.String(), Type.Unknown(), {
-                description: 'Action arguments. Add format="cli"|"json" (or f/"-f") and full=true (or "--full": true) for explicit presentation control. Default cli keeps data.details compact; format="json" or full=true exposes full structured details and can fill context quickly, so use it only when needed.',
+                description: 'Action arguments. Add format="cli"|"json" (or f/"-f") for presentation, and full=true (or "--full": true) only for verbose/debug details. Default cli and non-full json keep data.details compact.',
             })),
         }),
+        renderCall(args, theme) {
+            const action = typeof args.action === "string" && args.action.trim() ? args.action.trim() : "?";
+            let suffix = "";
+            if (isRecord(args.args)) {
+                const topic = typeof args.args.topic === "string" ? args.args.topic.trim() : "";
+                const op = typeof args.args.op === "string" ? args.args.op.trim() : "";
+                if (topic)
+                    suffix = ` ${theme.fg("dim", `topic=${topic}`)}`;
+                else if (op)
+                    suffix = ` ${theme.fg("dim", `op=${op}`)}`;
+            }
+            return new Text(`${theme.fg("toolTitle", theme.bold("pinet"))} ${theme.fg("muted", action)}${suffix}`, 0, 0);
+        },
+        renderResult(result, { expanded, isPartial }, theme) {
+            if (isPartial) {
+                return new Text(theme.fg("warning", "Pinet running…"), 0, 0);
+            }
+            const display = formatPinetDispatcherResultForDisplay(result, expanded);
+            const color = display.status === "failed"
+                ? "error"
+                : display.status === "succeeded"
+                    ? "success"
+                    : "muted";
+            const icon = display.status === "failed" ? "✗" : display.status === "succeeded" ? "✓" : "•";
+            const lines = display.text.split("\n");
+            const first = lines[0] ?? "Pinet result.";
+            const rest = lines.slice(1).map((line) => theme.fg("dim", line));
+            return new Text([`${theme.fg(color, icon)} ${theme.fg(color, first)}`, ...rest].join("\n"), 0, 0);
+        },
         async execute(toolCallId, params) {
             let normalizedAction;
             try {
@@ -1154,7 +1618,7 @@ export function registerPinetTools(pi, deps) {
                         },
                     ]), getTolerantPinetOutputOptions(args));
                 }
-                return wrapDispatcherEnvelope(buildPinetDispatcherHelpEnvelope(args, actionDefinitions), output);
+                return wrapDispatcherEnvelope(buildPinetDispatcherHelpEnvelope(args, actionDefinitions, output), output);
             }
             const definition = actionDefinitions.get(normalizedAction);
             if (!definition) {
@@ -1193,11 +1657,15 @@ export function registerPinetTools(pi, deps) {
             }
             try {
                 const result = await definition.execute(toolCallId, params.args, output);
+                const expandedText = typeof result.expandedText === "string" && result.expandedText.trim().length > 0
+                    ? result.expandedText
+                    : undefined;
+                const displayText = result.content[0]?.text ?? "";
                 return wrapDispatcherEnvelope(buildPinetDispatcherEnvelope("succeeded", {
                     action: definition.name,
-                    text: result.content[0]?.text ?? "",
+                    text: output.format === "json" ? (result.machineText ?? displayText) : displayText,
                     details: selectPinetResultDetails(result, output),
-                }), output);
+                }), output, expandedText, displayText);
             }
             catch (error) {
                 if (error instanceof Error && error.name === "AbortError") {