@pinet/slack-bridge 0.1.2 → 0.2.1

package/dist/helpers.d.ts

@@ -23,6 +23,8 @@ export interface SlackBridgeSettings {
     ralphSnoozeAfterEmptyCycles?: number;
     ralphSnoozeDurationMs?: number;
     skinTheme?: string;
+    slackCommandName?: string;
+    slackCommandNames?: string[];
     agentName?: string;
     agentEmoji?: string;
     meshSecret?: string;
@@ -173,6 +175,12 @@ export interface AgentDisplayInfo {
         launchSource?: string;
         tmuxSession?: string;
         brokerManagedAt?: string;
+        parentAgentId?: string;
+        rootAgentId?: string;
+        treeDepth?: number;
+        supervisionState?: string;
+        subtreeRole?: string;
+        laneId?: string;
         skinTheme?: string;
         personality?: string;
         skinStatusVocabulary?: PinetSkinStatusVocabulary;
@@ -212,6 +220,12 @@ export interface AgentVisibilityInput {
     lastActivity?: string | null;
     outboundCount?: number | null;
     pendingInboxCount?: number | null;
+    parentAgentId?: string | null;
+    rootAgentId?: string | null;
+    treeDepth?: number;
+    supervisionState?: string;
+    subtreeRole?: string | null;
+    laneId?: string | null;
 }
 export interface AgentVisibilityOptions {
     now?: number;

package/dist/helpers.js

@@ -837,8 +837,15 @@ export function buildAgentDisplayInfo(agent, options = {}) {
         health = "stale";
     }
     const metadata = asRecord(agent.metadata);
+    const hasHierarchyMetadata = Boolean(agent.parentAgentId ||
+        agent.rootAgentId ||
+        typeof agent.treeDepth === "number" ||
+        agent.supervisionState ||
+        agent.subtreeRole ||
+        agent.laneId);
     const capabilities = extractAgentCapabilities(metadata);
     const capabilityTags = buildAgentCapabilityTags(capabilities);
+    const displayMetadata = metadata ?? {};
     const idleSinceMs = parseIsoMs(agent.idleSince);
     const lastActivityMs = parseIsoMs(agent.lastActivity);
     const idleDurationMs = idleSinceMs == null ? null : Math.max(0, nowMs - idleSinceMs);
@@ -849,31 +856,37 @@ export function buildAgentDisplayInfo(agent, options = {}) {
         id: agent.id,
         ...(agent.pid != null ? { pid: agent.pid } : {}),
         status: agent.status,
-        metadata: metadata
+        metadata: metadata || hasHierarchyMetadata
             ? {
-                cwd: asString(metadata.cwd),
-                branch: asString(metadata.branch),
-                ...(metadata.workdirDirty === true ? { workdirDirty: true } : {}),
-                ...(typeof metadata.workdirDirtyFileCount === "number"
-                    ? { workdirDirtyFileCount: metadata.workdirDirtyFileCount }
+                cwd: asString(displayMetadata.cwd),
+                branch: asString(displayMetadata.branch),
+                ...(displayMetadata.workdirDirty === true ? { workdirDirty: true } : {}),
+                ...(typeof displayMetadata.workdirDirtyFileCount === "number"
+                    ? { workdirDirtyFileCount: displayMetadata.workdirDirtyFileCount }
                     : {}),
-                ...(metadata.gitProbeFailed === true ? { gitProbeFailed: true } : {}),
-                ...(asString(metadata.gitProbedAt)
-                    ? { gitProbedAt: asString(metadata.gitProbedAt) }
+                ...(displayMetadata.gitProbeFailed === true ? { gitProbeFailed: true } : {}),
+                ...(asString(displayMetadata.gitProbedAt)
+                    ? { gitProbedAt: asString(displayMetadata.gitProbedAt) }
                     : {}),
-                host: asString(metadata.host),
-                repo: asString(metadata.repo) ?? capabilities.repo,
-                role: asString(metadata.role) ?? capabilities.role,
-                brokerManaged: metadata.brokerManaged === true,
-                brokerManagedBy: asString(metadata.brokerManagedBy),
-                launchSource: asString(metadata.launchSource),
-                tmuxSession: asString(metadata.tmuxSession),
-                brokerManagedAt: asString(metadata.brokerManagedAt),
-                skinTheme: asString(metadata.skinTheme),
-                personality: asString(metadata.personality),
-                ...(extractPinetSkinStatusVocabulary(metadata.skinStatusVocabulary)
+                host: asString(displayMetadata.host),
+                repo: asString(displayMetadata.repo) ?? capabilities.repo,
+                role: asString(displayMetadata.role) ?? capabilities.role,
+                brokerManaged: displayMetadata.brokerManaged === true,
+                brokerManagedBy: asString(displayMetadata.brokerManagedBy),
+                launchSource: asString(displayMetadata.launchSource),
+                tmuxSession: asString(displayMetadata.tmuxSession),
+                brokerManagedAt: asString(displayMetadata.brokerManagedAt),
+                parentAgentId: agent.parentAgentId ?? asString(displayMetadata.parentAgentId),
+                rootAgentId: agent.rootAgentId ?? asString(displayMetadata.rootAgentId),
+                ...(typeof agent.treeDepth === "number" ? { treeDepth: agent.treeDepth } : {}),
+                supervisionState: agent.supervisionState,
+                subtreeRole: agent.subtreeRole ?? asString(displayMetadata.subtreeRole),
+                laneId: agent.laneId ?? asString(displayMetadata.laneId),
+                skinTheme: asString(displayMetadata.skinTheme),
+                personality: asString(displayMetadata.personality),
+                ...(extractPinetSkinStatusVocabulary(displayMetadata.skinStatusVocabulary)
                     ? {
-                        skinStatusVocabulary: extractPinetSkinStatusVocabulary(metadata.skinStatusVocabulary),
+                        skinStatusVocabulary: extractPinetSkinStatusVocabulary(displayMetadata.skinStatusVocabulary),
                     }
                     : {}),
                 ...(capabilities.scope ? { scope: capabilities.scope } : {}),
@@ -1729,6 +1742,17 @@ export function formatAgentList(agents, homedir) {
             const probe = meta.gitProbeFailed ? " [git probe failed]" : "";
             line += `\n   ${cwd}${branch}${host}${probe}`;
         }
+        if (meta?.parentAgentId || meta?.supervisionState === "orphaned") {
+            const hierarchy = [
+                meta.parentAgentId ? `parent=${meta.parentAgentId}` : null,
+                meta.rootAgentId ? `root=${meta.rootAgentId}` : null,
+                typeof meta.treeDepth === "number" ? `depth=${meta.treeDepth}` : null,
+                meta.supervisionState ? `state=${meta.supervisionState}` : null,
+                meta.subtreeRole ? `role=${meta.subtreeRole}` : null,
+                meta.laneId ? `lane=${meta.laneId}` : null,
+            ].filter((item) => Boolean(item));
+            line += `\n   subtree: ${hierarchy.join(" · ")}`;
+        }
         if (meta?.brokerManaged) {
             const managed = [
                 meta.launchSource ? `source=${meta.launchSource}` : "source=broker",

package/dist/index.js

@@ -37,9 +37,12 @@ import { createAgentPromptGuidance } from "./agent-prompt-guidance.js";
 import { createAgentEventRuntime } from "./agent-event-runtime.js";
 import { createSessionUiRuntime } from "./session-ui-runtime.js";
 import { createSlackRequestRuntime } from "./slack-request-runtime.js";
+import { getSlackMessageAgeMs, isStaleSlackMessage } from "./stale-slack-messages.js";
+import { formatSlackAgentsDashboard, formatSlackAgentsUsage, isSlackAgentCommand, isSlackAgentsListCommand, resolveSlackAgentCommandNames, shouldIncludeSlackAgentsGhosts, } from "./slack-agents-command.js";
 import { createPinetRegistrationGate } from "./pinet-registration-gate.js";
 import { createBrokerRuntimeAccess } from "./broker-runtime-access.js";
 import { createInboxDrainRuntime } from "./inbox-drain-runtime.js";
+import { createSubtreeBrokerRuntime } from "./subtree-broker-runtime.js";
 import { createAgentCompletionRuntime } from "./agent-completion-runtime.js";
 import { sendBrokerMessage } from "./broker/message-send.js";
 import { SlackThreadStatusManager } from "./slack-thread-status.js";
@@ -406,6 +409,23 @@ export default function (pi) {
         formatError: msg,
     });
     const { requestRemoteControl, runRemoteControl, resetRemoteControlState } = pinetRemoteControl;
+    const subtreeBrokerRuntime = createSubtreeBrokerRuntime({
+        cwd: process.cwd(),
+        getSettings: () => settings,
+        getAgentStableId: () => agentStableId,
+        getCentralAgentId: () => brokerClient?.client.getRegisteredIdentity()?.agentId ?? null,
+        getAgentIdentity: () => ({ name: agentName, emoji: agentEmoji }),
+        getAgentMetadata,
+        getMeshRoleFromMetadata: (metadata, fallbackRole) => getMeshRoleFromMetadata(metadata, fallbackRole),
+        pushInboxMessages: (messages) => {
+            inbox.push(...messages);
+        },
+        updateBadge,
+        maybeDrainInboxIfIdle,
+        requestRemoteControl,
+        runRemoteControl,
+        formatError: msg,
+    });
     const pinetActivityFormatting = createPinetActivityFormatting({
         getActiveBrokerDb,
     });
@@ -491,6 +511,20 @@ export default function (pi) {
     const handleBrokerAppHomeOpened = async (userId, ctx) => {
         await pinetHomeTabs.publishCurrentPinetHomeTabSafely(userId, ctx, new Date().toISOString());
     };
+    const handleBrokerSlackSlashCommand = async (event) => {
+        const commandNames = resolveSlackAgentCommandNames(settings, activeSkinTheme);
+        if (!isSlackAgentCommand(event.command, commandNames)) {
+            return null;
+        }
+        if (!isSlackAgentsListCommand(event.command, event.text, commandNames)) {
+            return formatSlackAgentsUsage(commandNames);
+        }
+        const snapshot = await buildCurrentBrokerControlPlaneDashboardSnapshot();
+        if (!snapshot) {
+            return "Pinet broker dashboard data is not available yet. Try again after the broker completes a maintenance cycle.";
+        }
+        return formatSlackAgentsDashboard(snapshot, shouldIncludeSlackAgentsGhosts(event.text));
+    };
     const slackPinetAdapterFactory = createSlackPinetRuntimeAdapterFactory({
         getSettings: () => settings,
         getBotToken: () => botToken,
@@ -498,6 +532,7 @@ export default function (pi) {
         getAllowedUsers: () => allowedUsers,
         shouldAllowAllWorkspaceUsers: () => resolveAllowAllWorkspaceUsers(settings, process.env.SLACK_ALLOW_ALL_WORKSPACE_USERS),
         onAppHomeOpened: handleBrokerAppHomeOpened,
+        onSlashCommand: handleBrokerSlackSlashCommand,
     });
     const brokerRuntime = createBrokerRuntime({
         getSettings: () => settings,
@@ -519,6 +554,11 @@ export default function (pi) {
         getMeshRoleFromMetadata: (metadata, fallbackRole) => getMeshRoleFromMetadata(metadata ?? undefined, fallbackRole),
         handleInboundMessage: async ({ message, broker, router, selfId, ctx }) => {
             try {
+                if (isStaleSlackMessage(message)) {
+                    const ageMs = getSlackMessageAgeMs(message);
+                    console.info(`[slack-bridge] skipped stale Slack inbound message older than 15m: channel=${message.channel} thread=${message.threadId} ts=${message.timestamp} age_ms=${ageMs ?? "unknown"}`);
+                    return;
+                }
                 const ownerHint = message.source === "slack" && message.threadId && message.channel
                     ? await resolveBrokerThreadOwnerHint(message.channel, message.threadId)
                     : null;
@@ -687,6 +727,7 @@ export default function (pi) {
         getActiveBrokerSelfId,
         getAgentName: () => agentName,
         getFollowerClient: () => brokerClient?.client ?? null,
+        sendSubtreeAgentMessage: (target, body, metadata) => subtreeBrokerRuntime.sendMessage(target, body, metadata),
         formatTrackedAgent,
         logActivity: (entry) => {
             brokerRuntime.logActivity(entry);
@@ -830,6 +871,10 @@ export default function (pi) {
             }, consumeConfirmationReply);
         }
         if (brokerRole === "follower" && brokerClient?.client) {
+            const subtreeResult = subtreeBrokerRuntime.readInbox(options);
+            if (subtreeResult && (subtreeResult.messages.length > 0 || Boolean(options.threadId))) {
+                return consumePinetReadConfirmationReplies(subtreeResult, consumeConfirmationReply);
+            }
             const result = await brokerClient.client.readInbox(options);
             return consumePinetReadConfirmationReplies(result, consumeConfirmationReply);
         }
@@ -872,6 +917,7 @@ export default function (pi) {
     }
     async function stopPinetRuntime(ctx, options) {
         flushPersist();
+        await subtreeBrokerRuntime.stop({ releaseIdentity: options.releaseIdentity });
         await brokerRuntime.disconnect({ releaseIdentity: options.releaseIdentity });
         if (brokerClient) {
             if (options.releaseIdentity) {
@@ -980,6 +1026,7 @@ export default function (pi) {
                             channel: input.channel,
                             content,
                             ...(input.blocks && input.blocks.length > 0 ? { blocks: input.blocks } : {}),
+                            ...(input.files && input.files.length > 0 ? { files: input.files } : {}),
                             agentName,
                             agentEmoji,
                             agentOwnerToken,
@@ -1003,6 +1050,7 @@ export default function (pi) {
                             channel: input.channel,
                             content,
                             ...(input.blocks && input.blocks.length > 0 ? { blocks: input.blocks } : {}),
+                            ...(input.files && input.files.length > 0 ? { files: input.files } : {}),
                             agentName,
                             agentEmoji,
                             agentOwnerToken,
@@ -1024,6 +1072,14 @@ export default function (pi) {
             readPinetInbox,
             listBrokerAgents,
             listFollowerAgents,
+            listSubtreeAgents: (includeGhosts) => subtreeBrokerRuntime.listAgents(includeGhosts),
+            getSubtreeSelfAgentId: () => subtreeBrokerRuntime.getStatus().selfAgentId,
+            spawnSubtreeWorker: async (input) => {
+                const activeCtx = sessionUiRuntime.getExtensionContext();
+                if (!activeCtx)
+                    throw new Error("No active Pi extension context for subtree spawn.");
+                return await subtreeBrokerRuntime.spawnWorker(activeCtx, input);
+            },
             listPinetLanes,
             upsertPinetLane,
             setPinetLaneParticipant,
@@ -1234,11 +1290,15 @@ export default function (pi) {
             getBrokerControlPlaneHomeTabViewerIds,
             lastBrokerControlPlaneHomeTabRefreshAt: () => brokerRuntime.getLastHomeTabRefreshAt(),
             lastBrokerControlPlaneHomeTabError: () => brokerRuntime.getLastHomeTabError(),
+            subtreeBrokerStatus: () => subtreeBrokerRuntime.getStatus(),
             getPinetRegistrationBlockReason: pinetRegistrationGate.getBlockReason,
             connectAsBroker: (ctx) => transitionToRuntimeMode(ctx, "broker"),
             connectAsFollower: (ctx) => transitionToRuntimeMode(ctx, "follower"),
             reloadPinetRuntime,
             disconnectFollower,
+            startSubtreeBroker: (ctx) => subtreeBrokerRuntime.start(ctx),
+            stopSubtreeBroker: () => subtreeBrokerRuntime.stop({ releaseIdentity: true }),
+            spawnSubtreeWorker: (ctx, input) => subtreeBrokerRuntime.spawnWorker(ctx, input),
             sendPinetAgentMessage,
             signalAgentFree,
             applyLocalAgentIdentity,

package/dist/pinet-commands.d.ts

@@ -4,6 +4,7 @@ import { type LoggedActivityLogEntry } from "./activity-log.js";
 import { type SlackScopeDiagnostics } from "./slack-scope-diagnostics.js";
 import type { SlackBridgeRuntimeMode } from "./runtime-mode.js";
 import type { RalphSnoozeStatus } from "./ralph-loop.js";
+import type { SubtreeBrokerStatus, SubtreeSpawnInput, SubtreeSpawnResult } from "./subtree-broker-runtime.js";
 export interface PinetCommandsDeps {
     pinetEnabled: () => boolean;
     pinetRegistrationBlocked: () => boolean;
@@ -43,6 +44,7 @@ export interface PinetCommandsDeps {
     getBrokerControlPlaneHomeTabViewerIds: () => string[];
     lastBrokerControlPlaneHomeTabRefreshAt: () => string | null;
     lastBrokerControlPlaneHomeTabError: () => string | null;
+    subtreeBrokerStatus: () => SubtreeBrokerStatus;
     getPinetRegistrationBlockReason: () => string;
     connectAsBroker: (ctx: ExtensionContext) => Promise<void>;
     connectAsFollower: (ctx: ExtensionContext) => Promise<void>;
@@ -50,6 +52,9 @@ export interface PinetCommandsDeps {
     disconnectFollower: (ctx: ExtensionContext) => Promise<{
         unregisterError: string | null;
     }>;
+    startSubtreeBroker: (ctx: ExtensionContext) => Promise<SubtreeBrokerStatus>;
+    stopSubtreeBroker: () => Promise<void>;
+    spawnSubtreeWorker: (ctx: ExtensionContext, input: SubtreeSpawnInput) => Promise<SubtreeSpawnResult>;
     sendPinetAgentMessage: (target: string, body: string) => Promise<{
         messageId: number;
         target: string;
@@ -64,7 +69,7 @@ export interface PinetCommandsDeps {
     setExtStatus: (ctx: ExtensionContext, state: "ok" | "reconnecting" | "error" | "off") => void;
     setExtCtx: (ctx: ExtensionContext) => void;
 }
-export type PinetCommandAction = "start" | "follow" | "unfollow" | "reload" | "exit" | "free" | "status" | "logs" | "rename" | "snooze";
+export type PinetCommandAction = "start" | "follow" | "unfollow" | "reload" | "exit" | "free" | "status" | "logs" | "rename" | "snooze" | "subtree";
 export declare function formatPinetCommandHelp(): string;
 export declare function runPinetCommandAction(deps: PinetCommandsDeps, action: PinetCommandAction, args: string, ctx: ExtensionContext, usageCommand?: string): Promise<void>;
 export declare function registerPinetCommands(pi: ExtensionAPI, deps: PinetCommandsDeps): void;

package/dist/pinet-commands.js

@@ -11,6 +11,11 @@ const PINET_PRIMARY_COMMANDS = [
     { action: "exit", args: "<agent>", description: "Ask another agent to exit" },
     { action: "free", args: "", description: "Mark this agent as idle" },
     { action: "snooze", args: "[duration|off|status]", description: "Quiet empty RALPH cycles" },
+    {
+        action: "subtree",
+        args: "[start|status|spawn|stop]",
+        description: "Run this worker as a subtree broker for child followers",
+    },
 ];
 const PINET_SECONDARY_COMMANDS = [
     { action: "status", args: "", description: "Show Pinet status" },
@@ -89,6 +94,9 @@ function normalizePinetCommandAction(rawAction) {
         case "snooze":
         case "quiet":
             return "snooze";
+        case "subtree":
+        case "subbroker":
+            return "subtree";
         case "help":
             return null;
         default:
@@ -127,11 +135,14 @@ export async function runPinetCommandAction(deps, action, args, ctx, usageComman
         case "snooze":
             runPinetSnooze(deps, args, ctx);
             return;
+        case "subtree":
+            await runPinetSubtree(deps, args, ctx);
+            return;
     }
 }
 export function registerPinetCommands(pi, deps) {
     pi.registerCommand("pinet", {
-        description: "Unified Pinet command surface: start, follow, unfollow, reload, exit, free, snooze, status, logs, rename",
+        description: "Unified Pinet command surface: start, follow, unfollow, reload, exit, free, snooze, subtree, status, logs, rename",
         handler: async (args, ctx) => {
             const parsed = parsePinetCommandAction(args);
             if (!parsed) {
@@ -318,6 +329,152 @@ function runPinetSnooze(deps, args, ctx) {
     });
     ctx.ui.notify(formatRalphSnoozeStatus(status), "info");
 }
+function formatSubtreeBrokerStatus(status) {
+    if (!status.active || !status.paths || !status.selfAgentId) {
+        return "Subtree broker: off\nUse /pinet subtree start from a worker that is already following the central broker.";
+    }
+    const envLines = Object.entries(status.childLaunchEnv).map(([key, value]) => `${key}=${value}`);
+    return [
+        "Subtree broker: running",
+        `Self agent: ${status.selfAgentId}`,
+        `Started: ${status.startedAt ?? "unknown"}`,
+        `Socket: ${status.paths.socketPath}`,
+        `Database: ${status.paths.dbPath}`,
+        `Lock: ${status.paths.lockPath}`,
+        `Children: ${status.childCount}`,
+        ...(status.spawnedWorkers.length > 0
+            ? [
+                "Spawned workers:",
+                ...status.spawnedWorkers.map((worker) => `- ${worker.sessionName} role=${worker.role} agent=${worker.agentId ?? "pending"} repo=${worker.repoPath}`),
+            ]
+            : []),
+        "Child follower environment:",
+        ...envLines,
+        ...(status.childLaunchHint ? ["Child launch hint:", status.childLaunchHint] : []),
+    ].join("\n");
+}
+function parseSubtreeSpawnArgs(args) {
+    const tokens = args
+        .trim()
+        .split(/\s+/)
+        .map((token) => token.trim())
+        .filter(Boolean);
+    let repo = null;
+    let role;
+    let laneId;
+    const taskParts = [];
+    for (let index = 0; index < tokens.length; index += 1) {
+        const token = tokens[index];
+        const next = tokens[index + 1];
+        if (token === "--") {
+            taskParts.push(...tokens.slice(index + 1));
+            break;
+        }
+        if (token === "--repo" || token === "repo") {
+            if (!next)
+                return null;
+            repo = next;
+            index += 1;
+            continue;
+        }
+        if (token === "--role" || token === "role") {
+            if (!next)
+                return null;
+            role = next;
+            index += 1;
+            continue;
+        }
+        if (token === "--lane" || token === "--lane-id" || token === "lane" || token === "lane_id") {
+            if (!next)
+                return null;
+            laneId = next;
+            index += 1;
+            continue;
+        }
+        if (token.startsWith("repo=")) {
+            repo = token.slice("repo=".length);
+            continue;
+        }
+        if (token.startsWith("role=")) {
+            role = token.slice("role=".length);
+            continue;
+        }
+        if (token.startsWith("lane=")) {
+            laneId = token.slice("lane=".length);
+            continue;
+        }
+        if (token.startsWith("lane_id=")) {
+            laneId = token.slice("lane_id=".length);
+            continue;
+        }
+        taskParts.push(token);
+    }
+    const task = taskParts.join(" ").trim();
+    if (!repo || !task)
+        return null;
+    return {
+        repo,
+        task,
+        ...(role ? { role } : {}),
+        ...(laneId ? { laneId } : {}),
+    };
+}
+function formatSubtreeSpawnResult(result) {
+    return [
+        "Subtree worker started",
+        `Agent: ${result.agentName} (${result.agentId})`,
+        `Session: ${result.sessionName}`,
+        `Repo: ${result.repoPath}`,
+        `Role: ${result.role}`,
+        ...(result.laneId ? [`Lane: ${result.laneId}`] : []),
+        `Task message: ${result.messageId}`,
+        `Thread: ${result.threadId}`,
+        `Monitor: ${result.monitorCommand}`,
+    ].join("\n");
+}
+async function runPinetSubtree(deps, args, ctx) {
+    const [rawSubcommand = "status"] = args.trim().split(/\s+/);
+    const subcommand = rawSubcommand.toLowerCase();
+    if (["status", "show", "info", ""].includes(subcommand)) {
+        ctx.ui.notify(formatSubtreeBrokerStatus(deps.subtreeBrokerStatus()), "info");
+        return;
+    }
+    if (["stop", "off", "down"].includes(subcommand)) {
+        await deps.stopSubtreeBroker();
+        ctx.ui.notify("Subtree broker stopped. Spawned child followers were asked to exit.", "info");
+        return;
+    }
+    if (deps.runtimeMode() !== "follower" || deps.brokerRole() !== "follower") {
+        ctx.ui.notify("Subtree broker operations require this session to be running as a Pinet worker/follower. Run /pinet follow first.", "warning");
+        return;
+    }
+    if (["spawn", "child", "worker"].includes(subcommand)) {
+        const spawnInput = parseSubtreeSpawnArgs(args.trim().slice(rawSubcommand.length));
+        if (!spawnInput) {
+            ctx.ui.notify("Usage: /pinet subtree spawn repo=<repo-or-path> [role=<role>] [lane=<lane>] <task>", "warning");
+            return;
+        }
+        try {
+            const result = await deps.spawnSubtreeWorker(ctx, spawnInput);
+            ctx.ui.notify(formatSubtreeSpawnResult(result), "info");
+        }
+        catch (err) {
+            ctx.ui.notify(`Subtree worker spawn failed: ${errorMsg(err)}`, "error");
+        }
+        return;
+    }
+    if (!["start", "on", "broker", "promote"].includes(subcommand)) {
+        ctx.ui.notify("Usage: /pinet subtree [start|status|spawn|stop]", "warning");
+        return;
+    }
+    try {
+        const status = await deps.startSubtreeBroker(ctx);
+        ctx.ui.notify(formatSubtreeBrokerStatus(status), "info");
+    }
+    catch (err) {
+        ctx.ui.notify(`Subtree broker start failed: ${errorMsg(err)}`, "error");
+    }
+}
 function runPinetStatus(deps, ctx) {
     const mode = deps.runtimeMode();
     const ownedCount = [...deps.threads().values()].filter((t) => agentOwnsThread(t.owner, deps.agentName(), deps.agentAliases(), deps.agentOwnerToken())).length;
@@ -357,6 +514,13 @@ function runPinetStatus(deps, ctx) {
                 : []),
         ]
         : [];
+    const subtreeStatus = deps.subtreeBrokerStatus();
+    const subtreeBrokerInfo = subtreeStatus.active
+        ? [
+            `Subtree broker: running (${subtreeStatus.selfAgentId ?? "unknown"})`,
+            ...(subtreeStatus.paths ? [`Subtree socket: ${subtreeStatus.paths.socketPath}`] : []),
+        ]
+        : [];
     ctx.ui.notify([
         `Mode: ${mode}`,
         `Agent: ${deps.agentEmoji()} ${deps.agentName()}`,
@@ -376,6 +540,7 @@ function runPinetStatus(deps, ctx) {
         ...brokerHealthInfo,
         ...ralphSnoozeInfo,
         ...brokerHomeTabInfo,
+        ...subtreeBrokerInfo,
     ].join("\n"), "info");
 }
 function runPinetLogs(deps, ctx) {

package/dist/pinet-mesh-ops.d.ts

@@ -14,6 +14,12 @@ export interface PinetMeshOpsAgentRecord {
     resumableUntil?: string | null;
     outboundCount?: number;
     pendingInboxCount?: number;
+    parentAgentId?: string | null;
+    rootAgentId?: string | null;
+    treeDepth?: number;
+    supervisionState?: string;
+    subtreeRole?: string | null;
+    laneId?: string | null;
 }
 export interface PinetMeshOpsRecordedAssignment {
     issueNumber: number;
@@ -64,6 +70,11 @@ export interface PinetMeshOpsDeps {
     getActiveBrokerSelfId: () => string | null;
     getAgentName: () => string;
     getFollowerClient: () => PinetMeshOpsFollowerClientPort | null;
+    sendSubtreeAgentMessage?: (target: string, body: string, metadata?: Record<string, unknown>) => Promise<{
+        messageId: number;
+        target: string;
+        threadId: string;
+    } | null>;
     formatTrackedAgent: (agentId: string) => string;
     logActivity: (entry: ActivityLogEntry) => void;
 }

package/dist/pinet-mesh-ops.js

@@ -109,6 +109,7 @@ export function createPinetMeshOps(deps) {
                 target: targetRef,
                 body: dispatchBody,
                 metadata: dispatchMetadata,
+                trustedBrokerAgentId: selfId,
             });
             if (transferThreadId) {
                 const transfer = db.transferThreadOwnership(transferThreadId, result.target.id);
@@ -171,6 +172,10 @@ export function createPinetMeshOps(deps) {
             };
         }
         if (deps.getBrokerRole() === "follower") {
+            const subtreeResult = await deps.sendSubtreeAgentMessage?.(targetRef, finalBody, finalMetadata);
+            if (subtreeResult) {
+                return { messageId: subtreeResult.messageId, target: subtreeResult.target };
+            }
             const client = deps.getFollowerClient();
             if (!client) {
                 throw new Error("Pinet is in an unexpected state.");
@@ -233,6 +238,12 @@ export function createPinetMeshOps(deps) {
             resumableUntil: agent.resumableUntil,
             outboundCount: agent.outboundCount,
             pendingInboxCount: db.getPendingInboxCount(agent.id),
+            parentAgentId: agent.parentAgentId,
+            rootAgentId: agent.rootAgentId,
+            treeDepth: agent.treeDepth,
+            supervisionState: agent.supervisionState,
+            subtreeRole: agent.subtreeRole,
+            laneId: agent.laneId,
         }));
     }
     async function listFollowerAgents(includeGhosts) {
@@ -253,6 +264,12 @@ export function createPinetMeshOps(deps) {
             resumableUntil: agent.resumableUntil,
             outboundCount: agent.outboundCount,
             pendingInboxCount: agent.pendingInboxCount,
+            parentAgentId: agent.parentAgentId,
+            rootAgentId: agent.rootAgentId,
+            treeDepth: agent.treeDepth,
+            supervisionState: agent.supervisionState,
+            subtreeRole: agent.subtreeRole,
+            laneId: agent.laneId,
         }));
     }
     return {

package/dist/pinet-tools.d.ts

@@ -15,6 +15,34 @@ export interface PinetToolsAgentRecord {
     resumableUntil?: string | null;
     outboundCount?: number;
     pendingInboxCount?: number;
+    parentAgentId?: string | null;
+    rootAgentId?: string | null;
+    treeDepth?: number;
+    supervisionState?: string;
+    subtreeRole?: string | null;
+    laneId?: string | null;
+}
+export interface PinetSubtreeSpawnInput {
+    task: string;
+    repo: string;
+    role?: string;
+    laneId?: string;
+}
+export interface PinetSubtreeSpawnResult {
+    status: "started";
+    launchId: string;
+    sessionName: string;
+    repoPath: string;
+    role: string;
+    laneId: string | null;
+    agentId: string;
+    agentName: string;
+    messageId: number;
+    threadId: string;
+    monitorCommand: string;
+    socketPath: string;
+    dbPath: string;
+    childLaunchEnv: Record<string, string>;
 }
 export interface RegisterPinetToolsDeps {
     pinetEnabled: () => boolean;
@@ -48,6 +76,9 @@ export interface RegisterPinetToolsDeps {
     readPinetInbox: (options: PinetReadOptions) => Promise<PinetReadResult>;
     listBrokerAgents: () => PinetToolsAgentRecord[];
     listFollowerAgents: (includeGhosts: boolean) => Promise<PinetToolsAgentRecord[]>;
+    listSubtreeAgents?: (includeGhosts: boolean) => PinetToolsAgentRecord[] | null;
+    getSubtreeSelfAgentId?: () => string | null;
+    spawnSubtreeWorker?: (input: PinetSubtreeSpawnInput) => Promise<PinetSubtreeSpawnResult>;
     listPinetLanes: (options: PinetLaneListOptions) => Promise<PinetLaneInfo[]>;
     upsertPinetLane: (input: PinetLaneUpsertInput) => Promise<PinetLaneInfo>;
     setPinetLaneParticipant: (input: PinetLaneParticipantUpsertInput) => Promise<PinetLaneParticipantInfo>;
@@ -64,4 +95,20 @@ export interface RegisterPinetToolsDeps {
     }) => RalphSnoozeStatus;
     clearRalphSnooze?: () => RalphSnoozeStatus;
 }
+type PinetDispatcherStatus = "succeeded" | "failed";
+interface PinetRenderContentBlock {
+    type: string;
+    text?: string;
+}
+interface PinetRenderResultInput {
+    content?: PinetRenderContentBlock[];
+    details?: unknown;
+    expandedText?: string;
+    displayText?: string;
+}
+export declare function formatPinetDispatcherResultForDisplay(result: PinetRenderResultInput, expanded: boolean): {
+    status: PinetDispatcherStatus | "unknown";
+    text: string;
+};
 export declare function registerPinetTools(pi: ExtensionAPI, deps: RegisterPinetToolsDeps): void;
+export {};