@pinet/slack-bridge 0.2.2 → 0.2.6

package/dist/pinet-tools.js

@@ -1,16 +1,24 @@
+import { mkdtempSync, writeFileSync } from "node:fs";
 import os from "node:os";
+import path from "node:path";
 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 { formatAgentLifecycleStatus, formatAgentLifecycleTag, formatHibernationCommandResult, sanitizeOperatorReason, sanitizeOperatorTarget, } from "@pinet/broker-core";
 import { buildAgentDisplayInfo, filterAgentsForMeshVisibility, formatAgentList, rankAgentsForRouting, } from "./helpers.js";
 import { isBroadcastChannelTarget } from "./broker/agent-messaging.js";
 import { DEFAULT_HEARTBEAT_TIMEOUT_MS } from "./broker/socket-server.js";
 import { HEARTBEAT_INTERVAL_MS } from "./broker/client.js";
+import { SubtreeSpawnLaunchError, SubtreeSpawnRegistrationTimeoutError, } from "./subtree-broker-runtime.js";
+import { DEFAULT_MAX_OUTPUT_BYTES, DEFAULT_MAX_OUTPUT_LINES, formatOutputSize, measureOutputLimits, } from "./tool-output-limits.js";
 import { buildPinetSessionCompactDetails, buildPinetSessionFullDetails, getPinetSessionFilename, getPinetSessionPath, summarizePinetStableId, } from "./pinet-session-formatting.js";
 const PINET_DISPATCHER_EXAMPLES = {
-    send: [{ action: "send", args: { to: "@worker", message: "Please review PR #123" } }],
+    send: [
+        { action: "send", args: { to: "@worker", message: "Please review PR #123" } },
+        { action: "send", args: { to: "@worker", message: "/steer stop polling" } },
+    ],
     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
@@ -60,6 +68,8 @@ const PINET_DISPATCHER_EXAMPLES = {
     ],
     reload: [{ action: "reload", args: { target: "@worker" } }],
     exit: [{ action: "exit", args: { target: "@worker" } }],
+    hibernate: [{ action: "hibernate", args: { target: "@worker", reason: "idle overnight" } }],
+    wake: [{ action: "wake", args: { target: "@worker" } }],
 };
 const PINET_OUTPUT_OPTION_PARAMETERS = {
     format: Type.Optional(Type.String({ description: 'Response presentation format: "cli" (default) or "json".' })),
@@ -72,7 +82,7 @@ function getRecordString(record, key) {
     const value = record?.[key];
     return typeof value === "string" && value.trim() ? value : undefined;
 }
-function isRecord(value) {
+function isPinetToolObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function normalizeDispatcherAction(value) {
@@ -100,6 +110,8 @@ function normalizeDispatcherAction(value) {
         "spawn",
         "reload",
         "exit",
+        "hibernate",
+        "wake",
     ];
     if (!allowed.includes(normalized)) {
         throw new Error(`Unknown Pinet action: ${normalized}`);
@@ -118,6 +130,14 @@ function getErrorMessage(error) {
     }
 }
 function classifyPinetError(message) {
+    if (message.includes("state=launched_unregistered")) {
+        return {
+            class: "runtime",
+            message,
+            retryable: true,
+            hint: "Retry spawn with retry_handle to clean up the exact recorded worker runtime before relaunching.",
+        };
+    }
     if (message.includes("requires confirmation for action")) {
         return {
             class: "state",
@@ -126,7 +146,9 @@ function classifyPinetError(message) {
             hint: 'Call slack with action "confirm_action" first in the original thread.',
         };
     }
-    if (message.includes("is not running") || message.includes("unexpected state")) {
+    if (message.includes("is not running") ||
+        message.includes("not initialized") ||
+        message.includes("unexpected state")) {
         return {
             class: "state",
             message,
@@ -173,7 +195,7 @@ function buildPinetDispatcherEnvelope(status, data, errors = [], warnings = [])
 function formatPinetHelpCliText(data) {
     const actions = Array.isArray(data.actions)
         ? data.actions
-            .map((action) => isRecord(action) && typeof action.action === "string" ? action.action : null)
+            .map((action) => isPinetToolObject(action) && typeof action.action === "string" ? action.action : null)
             .filter((action) => Boolean(action))
         : [];
     if (actions.length > 0) {
@@ -189,7 +211,7 @@ function formatPinetHelpCliText(data) {
     return null;
 }
 function getPinetEnvelopeCliText(envelope) {
-    if (envelope.status === "succeeded" && isRecord(envelope.data)) {
+    if (envelope.status === "succeeded" && isPinetToolObject(envelope.data)) {
         const text = envelope.data.text;
         if (typeof text === "string" && text.length > 0)
             return text;
@@ -207,7 +229,7 @@ function getPinetEnvelopeCliText(envelope) {
     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))
+    if (!isPinetToolObject(value))
         return { format: "cli", full: false };
     const rawFormat = value.format ?? value.f ?? value["-f"];
     const normalizedFormat = rawFormat == null ? "cli" : String(rawFormat).trim().toLowerCase();
@@ -216,7 +238,7 @@ function getTolerantPinetOutputOptions(value) {
     return { format, full: rawFull === true };
 }
 function getOptionalPinetOutputOptions(value) {
-    if (!isRecord(value))
+    if (!isPinetToolObject(value))
         return { format: "cli", full: false };
     try {
         return normalizePinetOutputOptions(value);
@@ -232,28 +254,134 @@ function shouldRenderStructuredPinetEnvelope(envelope, output) {
         return false;
     if (envelope.status === "failed")
         return true;
-    if (!isRecord(envelope.data))
+    if (!isPinetToolObject(envelope.data))
         return true;
     const text = envelope.data.text;
     return typeof text !== "string" || text.length === 0;
 }
-function wrapDispatcherEnvelope(envelope, output = { format: "cli", full: false }, expandedText, displayText) {
+function wrapDispatcherEnvelope(envelope, output = { format: "cli", full: false }, expandedText, displayText, compactDetailsForSpill) {
+    const structuredEnvelopeText = JSON.stringify(envelope, null, output.full ? 2 : 0);
+    const renderStructured = shouldRenderStructuredPinetEnvelope(envelope, output);
+    const renderedText = renderStructured
+        ? structuredEnvelopeText
+        : getPinetEnvelopeCliText(envelope);
+    const data = typeof envelope.data === "object" && envelope.data !== null && !Array.isArray(envelope.data)
+        ? envelope.data
+        : null;
+    const action = typeof data?.action === "string" ? data.action : undefined;
+    const fullOutputText = output.format === "json"
+        ? renderedText
+        : `${renderedText}\n\n--- Pinet dispatcher envelope (JSON) ---\n${JSON.stringify(envelope, null, 2)}`;
+    const outputMeasurement = measureOutputLimits(fullOutputText);
+    let returnedEnvelope = envelope;
+    let returnedText = renderedText;
+    let returnedDisplayText = displayText;
+    if (outputMeasurement.exceedsLimit) {
+        const fileToken = (action ?? "result")
+            .trim()
+            .toLowerCase()
+            .replace(/[^a-z0-9_-]+/g, "-")
+            .replace(/^-+|-+$/g, "") || "result";
+        const dir = mkdtempSync(path.join(os.tmpdir(), "pinet-output-"));
+        const extension = output.format === "json" ? "json" : "txt";
+        const fullOutputPath = path.join(dir, `${Date.now()}-${fileToken}.${extension}`);
+        writeFileSync(fullOutputPath, fullOutputText, "utf8");
+        const originalDetails = data?.details;
+        let compactDetailRecord = {};
+        if (typeof compactDetailsForSpill === "object" &&
+            compactDetailsForSpill !== null &&
+            !Array.isArray(compactDetailsForSpill)) {
+            compactDetailRecord = compactDetailsForSpill;
+        }
+        else if (compactDetailsForSpill != null) {
+            const compactDetailValue = Array.isArray(compactDetailsForSpill)
+                ? { count: compactDetailsForSpill.length }
+                : typeof compactDetailsForSpill === "string" ||
+                    typeof compactDetailsForSpill === "number" ||
+                    typeof compactDetailsForSpill === "boolean"
+                    ? compactDetailsForSpill
+                    : String(compactDetailsForSpill);
+            compactDetailRecord = { compactDetails: compactDetailValue };
+        }
+        else if (typeof originalDetails === "object" &&
+            originalDetails !== null &&
+            !Array.isArray(originalDetails)) {
+            compactDetailRecord = Object.fromEntries(Object.entries(originalDetails)
+                .slice(0, PINET_COMPACT_LIST_LIMIT)
+                .map(([key, value]) => {
+                if (value == null ||
+                    typeof value === "string" ||
+                    typeof value === "number" ||
+                    typeof value === "boolean") {
+                    return [key, value];
+                }
+                if (Array.isArray(value))
+                    return [key, { count: value.length }];
+                return [key, typeof value === "object" ? "{...}" : String(value)];
+            }));
+        }
+        const count = compactDetailRecord.laneCount ??
+            compactDetailRecord.count ??
+            compactDetailRecord.total ??
+            compactDetailRecord.messageCount ??
+            compactDetailRecord.sessionCount;
+        const subject = action ? `Pinet ${action}` : `Pinet ${envelope.status}`;
+        let summary;
+        if (typeof count === "number" && action === "lanes") {
+            summary = `Pinet lanes: ${count} tracked.`;
+        }
+        else if (typeof count === "number" && action === "agents") {
+            summary = `Pinet agents: ${count} visible.`;
+        }
+        else if (typeof count === "number" && action === "sessions") {
+            summary = `Pinet sessions: ${count} found.`;
+        }
+        else if (typeof count === "number" && action === "ports") {
+            summary = `Pinet port leases: ${count}.`;
+        }
+        else if (typeof count === "number" && action === "read") {
+            summary = `Pinet read: ${count} message${count === 1 ? "" : "s"}.`;
+        }
+        else {
+            summary = `${subject} output exceeded the inline limit.`;
+        }
+        const spillNotice = `[Output truncated: original was ${outputMeasurement.totalLines} line${outputMeasurement.totalLines === 1 ? "" : "s"} (${formatOutputSize(outputMeasurement.totalBytes)}), exceeding the inline limit of ${DEFAULT_MAX_OUTPUT_LINES} lines or ${formatOutputSize(DEFAULT_MAX_OUTPUT_BYTES)}. Full output saved to: ${fullOutputPath}]`;
+        const warning = `Pinet output exceeded ${formatOutputSize(DEFAULT_MAX_OUTPUT_BYTES)} / ${DEFAULT_MAX_OUTPUT_LINES} lines; full output saved to ${fullOutputPath}.`;
+        returnedEnvelope = buildPinetDispatcherEnvelope(envelope.status, {
+            ...(action ? { action } : {}),
+            text: `${summary}\n\n${spillNotice}`,
+            details: {
+                ...compactDetailRecord,
+                fullOutputPath,
+                truncation: {
+                    truncated: true,
+                    totalLines: outputMeasurement.totalLines,
+                    totalBytes: outputMeasurement.totalBytes,
+                    maxLines: DEFAULT_MAX_OUTPUT_LINES,
+                    maxBytes: DEFAULT_MAX_OUTPUT_BYTES,
+                },
+                outputFormat: output.format,
+            },
+        }, envelope.errors, [...envelope.warnings, warning]);
+        returnedText = renderStructured
+            ? JSON.stringify(returnedEnvelope, null, output.full ? 2 : 0)
+            : getPinetEnvelopeCliText(returnedEnvelope);
+        returnedDisplayText = getPinetEnvelopeCliText(returnedEnvelope);
+    }
     return {
         content: [
             {
                 type: "text",
-                text: shouldRenderStructuredPinetEnvelope(envelope, output)
-                    ? JSON.stringify(envelope, null, output.full ? 2 : 0)
-                    : getPinetEnvelopeCliText(envelope),
+                text: returnedText,
             },
         ],
-        details: envelope,
-        ...(expandedText ? { expandedText } : {}),
-        ...(displayText ? { displayText } : {}),
+        details: returnedEnvelope,
+        ...(outputMeasurement.exceedsLimit ? {} : expandedText ? { expandedText } : {}),
+        ...(returnedDisplayText ? { displayText: returnedDisplayText } : {}),
     };
 }
 function isPinetDispatcherEnvelope(value) {
-    if (!isRecord(value))
+    if (!isPinetToolObject(value))
         return false;
     if (value.status !== "succeeded" && value.status !== "failed")
         return false;
@@ -355,13 +483,13 @@ function formatPinetEnvelopeExpandedText(envelope, expandedText) {
     else if (expandedText && expandedText.trim().length > 0) {
         lines.push(...expandedText.split("\n"));
     }
-    else if (isRecord(envelope.data)) {
+    else if (isPinetToolObject(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)) {
+        if (isPinetToolObject(details)) {
             lines.push("details:");
             lines.push(...formatPrimitiveDetails(details).map((line) => `  ${line}`));
         }
@@ -664,36 +792,59 @@ function runPinetSnoozeAction(params, deps, toolName) {
 }
 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 (!deps.spawnSubtreeWorker) {
+            throw new Error("subtree worker launcher is unavailable in this runtime. Start a worker subtree with /pinet subtree start and retry.");
+        }
+        const task = getMaybeString(params, "task");
+        const repo = getMaybeString(params, "repo");
+        const role = getMaybeString(params, "role") ?? "subworker";
+        const laneId = getMaybeString(params, "lane_id");
+        const retryHandleValue = params.retry_handle;
+        let cleanupHandle;
+        if (retryHandleValue !== undefined) {
+            if (!isPinetToolObject(retryHandleValue)) {
+                throw new Error("retry_handle must be a subtree spawn launch handle");
+            }
+            const launchId = getRecordString(retryHandleValue, "launchId");
+            const tmuxSessionName = getRecordString(retryHandleValue, "tmuxSessionName");
+            const socketPath = getRecordString(retryHandleValue, "socketPath");
+            if (!launchId ||
+                !tmuxSessionName ||
+                !socketPath ||
+                retryHandleValue.state !== "launched_unregistered") {
+                throw new Error('retry_handle requires launchId, tmuxSessionName, socketPath, and state="launched_unregistered"');
+            }
+            cleanupHandle = {
+                launchId,
+                tmuxSessionName,
+                socketPath,
+                state: "launched_unregistered",
+            };
+        }
+        deps.requireToolPolicy(toolName, undefined, `task=${task ?? ""} | repo=${repo ?? ""} | role=${role} | lane_id=${laneId ?? ""}`);
         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 } : {}),
+            ...(cleanupHandle ? { cleanupHandle } : {}),
         });
         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}) using ${result.runtimeKind} runtime ${result.sessionName}. Task message ${result.messageId} delivered. Monitor: ${result.monitorCommand}`
                         : `Pinet subtree worker started: ${result.agentName} (${result.agentId}). Task message ${result.messageId} delivered.`,
                 },
             ],
@@ -728,6 +879,49 @@ function runPinetRemoteControlAction(params, deps, toolName, command) {
         };
     })();
 }
+function runPinetHibernationCommandAction(target, reason, deps, toolName, command) {
+    return (async () => {
+        if (!target) {
+            throw new Error("target is required");
+        }
+        // Sanitize the operator-authored target/reason before they enter the policy
+        // context, which can surface verbatim in confirmation prompts and error
+        // text. `sanitizeOperatorTarget` fingerprints anything that is not a plain
+        // broker-safe identifier slug — a stable-id/session/cwd target such as
+        // `host:session:<ref>` (which embeds the session-resume identity), a private
+        // worktree path, or a `KEY=secret` shape — to an opaque `target:#<hash>`
+        // rather than echoing it. The reason is path/secret-redacted. The raw
+        // `target` still flows to the broker runner, which resolves it server-side
+        // and redacts any unknown-target echo.
+        const safeTarget = sanitizeOperatorTarget(target);
+        const safeReason = sanitizeOperatorReason(reason) ?? "";
+        deps.requireToolPolicy(toolName, undefined, `command=${command} | target=${safeTarget} | reason=${safeReason}`);
+        if (!deps.pinetEnabled()) {
+            throw new Error("Pinet is not running. Use /pinet start or /pinet follow first.");
+        }
+        const runner = command === "hibernate" ? deps.runHibernateCommand : deps.runWakeCommand;
+        if (!runner) {
+            throw new Error(`pinet ${command} is broker-managed. Connect this session as the broker (/pinet start) to hibernate or wake workers.`);
+        }
+        const result = await runner({ target, reason });
+        const text = formatHibernationCommandResult(result);
+        return {
+            content: [{ type: "text", text }],
+            details: result,
+            compactDetails: {
+                command: result.command,
+                agentId: result.agentId,
+                outcome: result.outcome,
+                reason: result.reason,
+                state: result.state,
+                ...(result.runtimeGeneration != null
+                    ? { runtimeGeneration: result.runtimeGeneration }
+                    : {}),
+            },
+            fullDetails: result,
+        };
+    })();
+}
 function runPinetScheduleAction(params, deps, toolName, output) {
     return (async () => {
         const delay = typeof params.delay === "string" ? params.delay : undefined;
@@ -995,7 +1189,7 @@ function getMaybeMetadata(params) {
     const value = params.metadata;
     if (value === null)
         return null;
-    return isRecord(value) ? value : undefined;
+    return isPinetToolObject(value) ? value : undefined;
 }
 function buildCompactPortLeaseDetails(leases) {
     const shownLeases = leases.slice(0, PINET_COMPACT_LIST_LIMIT);
@@ -1185,7 +1379,12 @@ function runPinetPortsAction(params, deps, toolName, output) {
 function runPinetLanesAction(params, deps, toolName, output) {
     return (async () => {
         const op = getMaybeString(params, "op")?.toLowerCase() ?? "list";
-        deps.requireToolPolicy(toolName, undefined, `op=${op} | format=${output.format}`);
+        const policyContext = `op=${op} | format=${output.format}`;
+        const threadTs = getMaybeString(params, "thread_ts");
+        deps.requireToolPolicy(toolName, threadTs, policyContext);
+        if (op === "upsert" || op === "participant") {
+            deps.requireToolPolicy(`${toolName}:write`, threadTs, policyContext);
+        }
         if (!deps.pinetEnabled()) {
             throw new Error("Pinet is not running. Use /pinet start or /pinet follow first.");
         }
@@ -1297,6 +1496,32 @@ function runPinetLanesAction(params, deps, toolName, output) {
         throw new Error("lanes op must be list, upsert, or participant");
     })();
 }
+/**
+ * Render the operator-safe hibernation lifecycle section appended to the
+ * existing `agents`/`sessions` read output. Compact output uses a scannable
+ * per-agent tag (state · gen · queue · checkpoint · refusal/quarantine); full
+ * output uses the complete redacted status block. Returns "" when there is
+ * nothing hibernation-relevant to show, so ordinary output is unchanged.
+ */
+function formatHibernationLifecycleSection(statuses, full) {
+    if (statuses.length === 0)
+        return "";
+    const body = full
+        ? statuses.map(formatAgentLifecycleStatus).join("\n\n")
+        : statuses
+            .map((status) => `  ${status.agentId}: ${formatAgentLifecycleTag(status)}`)
+            .join("\n");
+    return `\n\nHibernation lifecycle:\n${body}`;
+}
+function buildCompactLifecycleDetails(statuses) {
+    return statuses.map((status) => ({
+        agentId: status.agentId,
+        state: status.state,
+        quarantined: status.quarantined,
+        tag: formatAgentLifecycleTag(status),
+        ...(status.wake.queued ? { wakeQueuePosition: status.wake.position } : {}),
+    }));
+}
 function runPinetAgentsAction(params, deps, toolName, output) {
     return (async () => {
         const scope = params.scope === "children" || params.scope === "subtree" || params.scope === "all"
@@ -1361,14 +1586,26 @@ function runPinetAgentsAction(params, deps, toolName, output) {
             recentDisconnectWindowMs: recentGhostWindowMs,
         }).map(toDisplay);
         const agents = rankAgentsForRouting(visibleAgents, hint);
+        // Read-only hibernation lifecycle projection wired into the existing agents
+        // read path. Compact output shows a scannable per-agent tag; full/JSON
+        // exposes the complete redacted lifecycle structure. Broker-only (the dep
+        // is undefined on followers) and sanitized by construction. Called with NO
+        // id filter so durable hibernated/quarantined runtimes — which are
+        // disconnected and therefore absent from the visible roster — are still
+        // surfaced (this is exactly when operators need lifecycle visibility).
+        const lifecycle = deps.getAgentLifecycleProjection ? deps.getAgentLifecycleProjection() : [];
         const header = hasHint && output.full ? `${buildPinetAgentsHintText(hint)}\n\n` : "";
-        const text = `${header}${output.full ? formatAgentList(agents, os.homedir()) : formatCompactAgentList(agents, hint)}`;
+        const text = `${header}${output.full ? formatAgentList(agents, os.homedir()) : formatCompactAgentList(agents, hint)}${formatHibernationLifecycleSection(lifecycle, output.full)}`;
+        const expandedText = `${formatPinetAgentsExpanded(agents)}${formatHibernationLifecycleSection(lifecycle, true)}`;
         return {
             content: [{ type: "text", text }],
-            details: { agents, hint },
-            compactDetails: buildCompactAgentDetails(agents, hint),
-            fullDetails: { agents, hint },
-            expandedText: formatPinetAgentsExpanded(agents),
+            details: { agents, hint, ...(lifecycle.length > 0 ? { lifecycle } : {}) },
+            compactDetails: {
+                ...buildCompactAgentDetails(agents, hint),
+                ...(lifecycle.length > 0 ? { lifecycle: buildCompactLifecycleDetails(lifecycle) } : {}),
+            },
+            fullDetails: { agents, hint, ...(lifecycle.length > 0 ? { lifecycle } : {}) },
+            expandedText,
         };
     })();
 }
@@ -1385,6 +1622,9 @@ function buildPinetSessionSearchOptions(params) {
         ...(getMaybeString(params, "worktree_path")
             ? { worktreePath: getMaybeString(params, "worktree_path") }
             : {}),
+        ...(getMaybeString(params, "runtime_locator")
+            ? { runtimeLocator: getMaybeString(params, "runtime_locator") }
+            : {}),
         ...(getMaybeString(params, "tmux_session")
             ? { tmuxSession: getMaybeString(params, "tmux_session") }
             : {}),
@@ -1400,6 +1640,7 @@ function formatPinetSessionSearchHeader(sessions, options) {
         options.threadId ? `thread_id=${options.threadId}` : null,
         options.repo ? `repo=${options.repo}` : null,
         options.worktreePath ? `worktree=${options.worktreePath}` : null,
+        options.runtimeLocator ? `runtime=${options.runtimeLocator}` : null,
         options.tmuxSession ? `tmux=${options.tmuxSession}` : null,
         options.since ? `since=${options.since}` : null,
         options.until ? `until=${options.until}` : null,
@@ -1413,7 +1654,7 @@ function formatPinetSessionLine(session, full) {
     const where = [
         session.repo ?? null,
         session.branch ? `branch=${session.branch}` : null,
-        session.tmuxSession ? `tmux=${session.tmuxSession}` : null,
+        session.runtimeLocator ? `${session.runtimeKind ?? "runtime"}=${session.runtimeLocator}` : null,
     ].filter((item) => Boolean(item));
     const threads = session.relatedThreadIds.slice(0, full ? 10 : 3).join(", ");
     const suffix = session.relatedThreadIds.length > (full ? 10 : 3) ? " …" : "";
@@ -1466,24 +1707,37 @@ function runPinetSessionsAction(params, deps, toolName, output) {
             throw new Error("sessions op must be search");
         }
         const options = buildPinetSessionSearchOptions(params);
-        deps.requireToolPolicy(toolName, undefined, `agent_name=${options.agentName ?? ""} | agent_id=${options.agentId ?? ""} | thread_id=${options.threadId ?? ""} | repo=${options.repo ?? ""} | worktree_path=${options.worktreePath ?? ""} | tmux_session=${options.tmuxSession ?? ""} | since=${options.since ?? ""} | until=${options.until ?? ""} | limit=${options.limit ?? ""} | format=${output.format} | full=${output.full}`);
+        deps.requireToolPolicy(toolName, undefined, `agent_name=${options.agentName ?? ""} | agent_id=${options.agentId ?? ""} | thread_id=${options.threadId ?? ""} | repo=${options.repo ?? ""} | worktree_path=${options.worktreePath ?? ""} | runtime_locator=${options.runtimeLocator ?? ""} | tmux_session=${options.tmuxSession ?? ""} | since=${options.since ?? ""} | until=${options.until ?? ""} | limit=${options.limit ?? ""} | format=${output.format} | full=${output.full}`);
         if (!deps.pinetEnabled()) {
             throw new Error("Pinet is not running. Use /pinet start or /pinet follow first.");
         }
         const sessions = await deps.searchPinetSessions(options);
-        const text = formatPinetSessionSearch(sessions, options, output.full);
+        // Read-only lifecycle projection for the session's live agents, wired into
+        // the existing sessions read path. Broker-only and sanitized by
+        // construction; empty for historical/disconnected agents.
+        const lifecycle = deps.getAgentLifecycleProjection && sessions.length > 0
+            ? deps.getAgentLifecycleProjection(sessions.map((session) => session.agentId))
+            : [];
+        const text = `${formatPinetSessionSearch(sessions, options, output.full)}${formatHibernationLifecycleSection(lifecycle, output.full)}`;
         return {
             content: [{ type: "text", text }],
-            details: { count: sessions.length, sessions, options },
+            details: {
+                count: sessions.length,
+                sessions,
+                options,
+                ...(lifecycle.length > 0 ? { lifecycle } : {}),
+            },
             compactDetails: {
                 count: sessions.length,
                 options,
                 sessions: sessions.map(buildPinetSessionCompactDetails),
+                ...(lifecycle.length > 0 ? { lifecycle: buildCompactLifecycleDetails(lifecycle) } : {}),
             },
             fullDetails: {
                 count: sessions.length,
                 options,
                 sessions: sessions.map(buildPinetSessionFullDetails),
+                ...(lifecycle.length > 0 ? { lifecycle } : {}),
             },
             expandedText: text,
         };
@@ -1496,12 +1750,14 @@ export function registerPinetTools(pi, deps) {
     }
     registerAction({
         name: "send",
-        description: "Send a message to a connected Pinet agent or broker-only broadcast channel.",
+        description: "Send a queued message to a connected Pinet agent or broker-only broadcast channel. Prefix the body with /steer to interrupt a busy recipient with explicit steering.",
         parameters: Type.Object({
             to: Type.String({
                 description: "Target agent name/ID, or a broker-only broadcast channel like #extensions. Avoid #all for repo-specific issue/policy announcements.",
             }),
-            message: Type.String({ description: "Message body" }),
+            message: Type.String({
+                description: "Message body. Use /steer <instruction> only when you explicitly need to steer a busy recipient immediately; otherwise messages remain queued.",
+            }),
             transfer_thread_id: Type.Optional(Type.String({
                 description: "Broker-only: transfer ownership of this existing Slack thread to the direct recipient after delivery (for example a Slack thread_ts).",
             })),
@@ -1545,12 +1801,18 @@ export function registerPinetTools(pi, deps) {
     });
     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.",
+        description: "Worker-only: launch a child worker with the configured runtime 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" })),
+            retry_handle: Type.Optional(Type.Object({
+                launchId: Type.String(),
+                tmuxSessionName: Type.String(),
+                socketPath: Type.String(),
+                state: Type.Literal("launched_unregistered"),
+            })),
             ...PINET_OUTPUT_OPTION_PARAMETERS,
         }),
         execute: (_id, params, output) => runPinetSpawnAction(params, deps, "pinet:spawn", output),
@@ -1573,6 +1835,42 @@ export function registerPinetTools(pi, deps) {
         }),
         execute: (_id, params, _output) => runPinetRemoteControlAction(params, deps, "pinet:exit", "/exit"),
     });
+    registerAction({
+        name: "hibernate",
+        description: "Broker-managed: checkpoint and hibernate an idle broker-managed worker. Default-off; returns a safe refusal when hibernation is disabled or observe-only.",
+        parameters: Type.Object({
+            target: Type.String({
+                description: "Target worker: display name, agent id, or stable id",
+            }),
+            reason: Type.Optional(Type.String({ description: "Optional operator reason recorded in lifecycle telemetry" })),
+            ...PINET_OUTPUT_OPTION_PARAMETERS,
+        }),
+        execute: (_id, params, _output) => {
+            const target = typeof params.target === "string" ? params.target.trim() : "";
+            const reason = typeof params.reason === "string" && params.reason.trim().length > 0
+                ? params.reason.trim()
+                : undefined;
+            return runPinetHibernationCommandAction(target, reason, deps, "pinet:hibernate", "hibernate");
+        },
+    });
+    registerAction({
+        name: "wake",
+        description: "Broker-managed: wake a hibernated worker under a fresh fenced runtime and drain its queued messages in order.",
+        parameters: Type.Object({
+            target: Type.String({
+                description: "Target worker: display name, agent id, or stable id",
+            }),
+            reason: Type.Optional(Type.String({ description: "Optional operator reason recorded in lifecycle telemetry" })),
+            ...PINET_OUTPUT_OPTION_PARAMETERS,
+        }),
+        execute: (_id, params, _output) => {
+            const target = typeof params.target === "string" ? params.target.trim() : "";
+            const reason = typeof params.reason === "string" && params.reason.trim().length > 0
+                ? params.reason.trim()
+                : undefined;
+            return runPinetHibernationCommandAction(target, reason, deps, "pinet:wake", "wake");
+        },
+    });
     registerAction({
         name: "schedule",
         description: "Schedule a future wake-up for this Pinet agent.",
@@ -1606,7 +1904,7 @@ export function registerPinetTools(pi, deps) {
     });
     registerAction({
         name: "sessions",
-        description: "Search live and historical Pinet worker Pi sessions by display name, agent id, thread, repo/worktree, tmux session, or time range.",
+        description: "Search live and historical Pinet worker Pi sessions by display name, agent id, thread, repo/worktree, runtime locator (tmux session or herdr pane), or time range.",
         parameters: Type.Object({
             op: Type.Optional(Type.String({ description: "Operation: search (default)" })),
             agent_name: Type.Optional(Type.String({ description: "Worker display name, e.g. Frozen Hazel Whale" })),
@@ -1615,6 +1913,7 @@ export function registerPinetTools(pi, deps) {
             thread_id: Type.Optional(Type.String({ description: "Related Pinet/Slack/A2A thread id" })),
             repo: Type.Optional(Type.String({ description: "Repo name or path fragment" })),
             worktree_path: Type.Optional(Type.String({ description: "Worktree/cwd path fragment" })),
+            runtime_locator: Type.Optional(Type.String({ description: "Broker-managed runtime locator (tmux session or herdr pane)" })),
             tmux_session: Type.Optional(Type.String({ description: "Broker-managed tmux session name" })),
             since: Type.Optional(Type.String({ description: "Only sessions active after this ISO time" })),
             until: Type.Optional(Type.String({ description: "Only sessions started before this ISO time" })),
@@ -1645,9 +1944,10 @@ export function registerPinetTools(pi, deps) {
     });
     registerAction({
         name: "lanes",
-        description: "List or update durable Pinet lane metadata for PM-mode and complex coordination visibility.",
+        description: "List or update durable Pinet lane metadata for PM-mode and complex coordination visibility. Upsert and participant operations additionally require guardrail policy pinet:lanes:write.",
         parameters: Type.Object({
             op: Type.Optional(Type.String({ description: "Operation: list, upsert, or participant" })),
+            thread_ts: Type.Optional(Type.String({ description: "Slack thread timestamp for confirmation-required mutations" })),
             lane_id: Type.Optional(Type.String({ description: "Stable lane id, e.g. issue-688" })),
             name: Type.Optional(Type.Union([Type.String(), Type.Null()], { description: "Human-readable lane name" })),
             task: Type.Optional(Type.Union([Type.String(), Type.Null()], { description: "Short lane task description" })),
@@ -1694,10 +1994,11 @@ 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, sessions, 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.',
+        promptSnippet: 'Use this compact dispatcher for Pinet actions: send, read, free, snooze, schedule, agents, sessions, lanes, ports, reload, exit, hibernate, wake, 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.',
+        promptGuidelines: deps.promptGuidelines,
         parameters: Type.Object({
             action: Type.String({
-                description: "Action name: help, send, read, free, snooze, schedule, agents, sessions, lanes, ports, reload, or exit. Also supports spawn for launching worker-owned subtree children.",
+                description: "Action name: help, send, read, free, snooze, schedule, agents, sessions, lanes, ports, reload, exit, hibernate (broker-managed checkpoint+hibernate), or wake (broker-managed fenced wake). 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") for presentation, and full=true (or "--full": true) only for verbose/debug details. Default cli and non-full json keep data.details compact.',
@@ -1706,7 +2007,7 @@ export function registerPinetTools(pi, deps) {
         renderCall(args, theme) {
             const action = typeof args.action === "string" && args.action.trim() ? args.action.trim() : "?";
             let suffix = "";
-            if (isRecord(args.args)) {
+            if (isPinetToolObject(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)
@@ -1748,7 +2049,7 @@ export function registerPinetTools(pi, deps) {
                 ]), getOptionalPinetOutputOptions(params.args));
             }
             if (normalizedAction === "help") {
-                const args = isRecord(params.args) ? params.args : {};
+                const args = isPinetToolObject(params.args) ? params.args : {};
                 let output;
                 try {
                     output = normalizePinetOutputOptions(args);
@@ -1776,7 +2077,7 @@ export function registerPinetTools(pi, deps) {
                     },
                 ]), getOptionalPinetOutputOptions(params.args));
             }
-            if (!isRecord(params.args)) {
+            if (!isPinetToolObject(params.args)) {
                 return wrapDispatcherEnvelope(buildPinetDispatcherEnvelope("failed", null, [
                     {
                         class: "input",
@@ -1810,14 +2111,18 @@ export function registerPinetTools(pi, deps) {
                     action: definition.name,
                     text: output.format === "json" ? (result.machineText ?? displayText) : displayText,
                     details: selectPinetResultDetails(result, output),
-                }), output, expandedText, displayText);
+                }), output, expandedText, displayText, result.compactDetails);
             }
             catch (error) {
                 if (error instanceof Error && error.name === "AbortError") {
                     throw error;
                 }
                 const message = getErrorMessage(error);
-                return wrapDispatcherEnvelope(buildPinetDispatcherEnvelope("failed", null, [classifyPinetError(message)]), output);
+                const launchHandle = error instanceof SubtreeSpawnRegistrationTimeoutError ||
+                    error instanceof SubtreeSpawnLaunchError
+                    ? error.handle
+                    : null;
+                return wrapDispatcherEnvelope(buildPinetDispatcherEnvelope("failed", launchHandle ? { action: definition.name, details: { launchHandle } } : null, [classifyPinetError(message)]), output);
             }
         },
     });