@pinet/slack-bridge 0.2.2 → 0.2.6

package/dist/slack-pinet-runtime-adapter.js

@@ -79,6 +79,16 @@ export function createSlackPinetRuntimeAdapterFactory(deps) {
             onAppHomeOpened: async ({ userId }) => {
                 await deps.onAppHomeOpened(userId, ctx);
             },
+            onSocketOpen: () => deps.setExtStatus(ctx, "ok"),
+            onSocketReconnectScheduled: () => deps.setExtStatus(ctx, "reconnecting"),
+            onSocketError: (message, source) => {
+                if (source === "connection") {
+                    deps.setExtStatus(ctx, "error");
+                }
+                else {
+                    ctx.ui.notify(`Slack event failed: ${message}`, "error");
+                }
+            },
             onSlashCommand: deps.onSlashCommand
                 ? (event) => deps.onSlashCommand?.(event, ctx) ?? null
                 : undefined,

package/dist/slack-presence.d.ts

@@ -21,11 +21,12 @@ export interface SlackPresenceSnapshot {
     lastActivity?: number;
     online?: boolean;
 }
+export type SlackPresenceTimestampValue = string | number | null | undefined;
 export interface SlackDndInfoLike {
-    dnd_enabled?: unknown;
-    next_dnd_end_ts?: unknown;
-    snooze_enabled?: unknown;
-    snooze_endtime?: unknown;
+    dnd_enabled?: boolean | null;
+    next_dnd_end_ts?: SlackPresenceTimestampValue;
+    snooze_enabled?: boolean | null;
+    snooze_endtime?: SlackPresenceTimestampValue;
 }
 export declare function stripSlackUserReference(value: string): string;
 export declare function isSlackUserId(value: string): boolean;

package/dist/slack-request-runtime.d.ts

@@ -1,5 +1,6 @@
-import { type SlackResult } from "./slack-api.js";
-export type SlackRequestCall = (method: string, token: string, body?: Record<string, unknown>) => Promise<SlackResult>;
+import { callSlackApi, type SlackResult } from "./slack-api.js";
+export type SlackRequestBody = NonNullable<Parameters<typeof callSlackApi>[2]>;
+export type SlackRequestCall = (method: string, token: string, body?: SlackRequestBody) => Promise<SlackResult>;
 export interface SlackRequestRuntime {
     slack: SlackRequestCall;
     reset: () => void;

package/dist/slack-scope-diagnostics.d.ts

@@ -1,7 +1,31 @@
+export type SlackScopeDiagnosticsSurface = "files" | "bookmarks" | "pins";
+export type SlackScopeProbeBody = Record<string, unknown>;
+interface SlackFileInfoScopeProbeBody extends SlackScopeProbeBody {
+    file: string;
+}
+interface SlackCompleteUploadScopeProbeFile {
+    id: string;
+    title: string;
+}
+interface SlackCompleteUploadScopeProbeBody extends SlackScopeProbeBody {
+    files: SlackCompleteUploadScopeProbeFile[];
+    channel_id: string;
+}
+interface SlackChannelScopeProbeBody extends SlackScopeProbeBody {
+    channel_id: string;
+}
+interface SlackBookmarkRemoveScopeProbeBody extends SlackChannelScopeProbeBody {
+    bookmark_id: string;
+}
+interface SlackPinnedItemScopeProbeBody extends SlackScopeProbeBody {
+    channel: string;
+    timestamp?: string;
+}
+export type SlackScopeProbeRequestBody = SlackFileInfoScopeProbeBody | SlackCompleteUploadScopeProbeBody | SlackChannelScopeProbeBody | SlackBookmarkRemoveScopeProbeBody | SlackPinnedItemScopeProbeBody;
 export type SlackScopeDiagnosticsStatus = "not_checked" | "pending" | "healthy" | "drift" | "unavailable";
 export interface SlackScopeProbeResult {
     key: string;
-    surface: "files" | "bookmarks" | "pins";
+    surface: SlackScopeDiagnosticsSurface;
     method: string;
     expectedScopes: string[];
     status: "ok" | "missing" | "unavailable";
@@ -14,7 +38,7 @@ export interface SlackScopeDiagnostics {
     status: SlackScopeDiagnosticsStatus;
     checkedAt: string | null;
     summary: string;
-    surfaces: Array<"files" | "bookmarks" | "pins">;
+    surfaces: SlackScopeDiagnosticsSurface[];
     missingScopes: string[];
     results: SlackScopeProbeResult[];
     error?: string;
@@ -29,3 +53,4 @@ export declare function createPendingSlackScopeDiagnostics(): SlackScopeDiagnost
 export declare function detectSlackScopeDiagnostics(options: DetectSlackScopeDiagnosticsOptions): Promise<SlackScopeDiagnostics>;
 export declare function formatSlackScopeDiagnosticsStatus(diagnostics: SlackScopeDiagnostics): string;
 export declare function buildSlackScopeDriftWarning(diagnostics: SlackScopeDiagnostics): string | null;
+export {};

package/dist/slack-socket-dedup.d.ts

@@ -1,7 +1,10 @@
 export declare const SLACK_SOCKET_DELIVERY_DEDUP_TTL_MS: number;
 export declare const SLACK_SOCKET_DELIVERY_DEDUP_MAX_SIZE = 10000;
-export declare function extractSlackEventDedupKey(evt: Record<string, unknown>): string | null;
-export declare function extractSlackBlockActionDedupKey(payload: Record<string, unknown>): string | null;
-export declare function extractSlackViewSubmissionDedupKey(payload: Record<string, unknown>): string | null;
-export declare function extractSlackInteractiveDedupKey(payload: Record<string, unknown>): string | null;
-export declare function extractSlackSocketDedupKey(frame: Record<string, unknown>): string | null;
+export type SlackDedupEventPayload = Record<string, unknown>;
+export type SlackInteractiveDedupPayload = Record<string, unknown>;
+export type SlackSocketDedupFrame = Record<string, unknown>;
+export declare function extractSlackEventDedupKey(evt: SlackDedupEventPayload): string | null;
+export declare function extractSlackBlockActionDedupKey(payload: SlackInteractiveDedupPayload): string | null;
+export declare function extractSlackViewSubmissionDedupKey(payload: SlackInteractiveDedupPayload): string | null;
+export declare function extractSlackInteractiveDedupKey(payload: SlackInteractiveDedupPayload): string | null;
+export declare function extractSlackSocketDedupKey(frame: SlackSocketDedupFrame): string | null;

package/dist/slack-tools.d.ts

@@ -26,10 +26,19 @@ export interface SlackPinetDeliveryResult {
     source: string;
 }
 export interface SlackPinetDeliveryPort {
+    /**
+     * True when Pinet is configured/enabled for this session, regardless of
+     * live broker connectivity. When true, threaded Slack replies MUST route
+     * through the broker; direct Slack fallback is refused even if the broker
+     * is momentarily unavailable, to preserve broker-enforced thread
+     * ownership (see gugu91/pinet#855).
+     */
+    isEnabled: () => boolean;
     isAvailable: () => boolean;
     sendSlackMessage: (input: SlackPinetDeliveryInput) => Promise<SlackPinetDeliveryResult>;
 }
 export interface RegisterSlackToolsDeps {
+    additionalSendPromptGuidelines?: string[];
     getBotToken: () => string;
     getDefaultChannel: () => string | undefined;
     getSecurityPrompt: () => string;
@@ -40,6 +49,7 @@ export interface RegisterSlackToolsDeps {
     getAgentOwnerToken: () => string;
     getLastDmChannel: () => string | null;
     updateBadge: () => void;
+    markSubtreeInboxIdsDelivered: (inboxIds: number[]) => void;
     resolveUser: (userId: string) => Promise<string>;
     threadContext: SlackToolsThreadContextPort;
     resolveChannel: (nameOrId: string) => Promise<string>;

package/dist/slack-tools.js

@@ -1,5 +1,6 @@
 import os from "node:os";
 import { Type } from "@sinclair/typebox";
+import { getSubtreeInboxIds } from "./broker-delivery.js";
 import { buildSlackCanvasCreateRequest, buildSlackCanvasEditRequest, buildSlackCanvasSectionsLookupRequest, extractSlackCanvasCommentsPage, extractSlackChannelCanvasId, normalizeSlackCanvasCommentsLimit, normalizeSlackCanvasCreateKind, normalizeSlackCanvasUpdateMode, pickSlackCanvasSectionId, } from "./canvases.js";
 import { normalizeSlackBlocksInput, summarizeSlackBlocksForPolicy } from "./slack-block-kit.js";
 import { encodeSlackModalPrivateMetadata, normalizeSlackModalViewInput } from "./slack-modals.js";
@@ -146,7 +147,7 @@ const SLACK_DISPATCHER_EXAMPLES = {
         },
     ],
 };
-function isRecord(value) {
+function isSlackToolObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function normalizeSlackDispatcherActionName(value) {
@@ -180,25 +181,6 @@ function isAbortError(error) {
 function getErrorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
-function isPinetDeliveryFallbackError(error) {
-    const lower = getErrorMessage(error).toLowerCase();
-    if (lower.includes("already owned"))
-        return false;
-    return (lower.includes("not running") ||
-        lower.includes("unexpected state") ||
-        lower.includes("unavailable") ||
-        lower.includes("not connected") ||
-        lower.includes("disconnected") ||
-        lower.includes("timeout") ||
-        lower.includes("timed out") ||
-        lower.includes("econn") ||
-        lower.includes("socket") ||
-        lower.includes("no transport source") ||
-        lower.includes("no transport channel") ||
-        lower.includes("only allows local file paths") ||
-        lower.includes("no adapter") ||
-        lower.includes("identity is unavailable"));
-}
 function classifySlackDispatcherError(error) {
     const message = getErrorMessage(error);
     const lower = message.toLowerCase();
@@ -311,11 +293,11 @@ function classifySlackDispatcherError(error) {
     };
 }
 function extractToolResponseText(response) {
-    if (!isRecord(response) || !Array.isArray(response.content))
+    if (!isSlackToolObject(response) || !Array.isArray(response.content))
         return undefined;
     const lines = response.content
         .map((item) => {
-        if (!isRecord(item))
+        if (!isSlackToolObject(item))
             return undefined;
         return typeof item.text === "string" ? item.text : undefined;
     })
@@ -323,18 +305,20 @@ function extractToolResponseText(response) {
     return lines.length > 0 ? lines.join("\n") : undefined;
 }
 function extractToolResponseDetails(response) {
-    return isRecord(response) && "details" in response ? response.details : undefined;
+    return isSlackToolObject(response) && "details" in response ? response.details : undefined;
 }
 function extractToolResponseFullDetails(response) {
-    return isRecord(response) && "fullDetails" in response ? response.fullDetails : undefined;
+    return isSlackToolObject(response) && "fullDetails" in response
+        ? response.fullDetails
+        : undefined;
 }
 function normalizeSlackOutputOptions(action, args) {
-    if (args != null && !isRecord(args)) {
+    if (args != null && !isSlackToolObject(args)) {
         throw new Error("slack args must be an object.");
     }
     const ownsFormatArg = SLACK_ACTIONS_WITH_FORMAT_ARG.has(action);
-    const rawResponseFormat = isRecord(args) ? args.response_format : undefined;
-    const rawFormat = rawResponseFormat ?? (isRecord(args) && !ownsFormatArg ? args.format : undefined);
+    const rawResponseFormat = isSlackToolObject(args) ? args.response_format : undefined;
+    const rawFormat = rawResponseFormat ?? (isSlackToolObject(args) && !ownsFormatArg ? args.format : undefined);
     const normalizedFormat = rawFormat == null ? "cli" : String(rawFormat).trim().toLowerCase();
     if (normalizedFormat !== "cli" && normalizedFormat !== "json") {
         throw new Error(ownsFormatArg
@@ -342,14 +326,14 @@ function normalizeSlackOutputOptions(action, args) {
             : 'format must be "cli" or "json" when provided.');
     }
     const format = normalizedFormat;
-    const rawFull = isRecord(args) ? args.full : undefined;
+    const rawFull = isSlackToolObject(args) ? args.full : undefined;
     if (rawFull != null && typeof rawFull !== "boolean") {
         throw new Error("full must be a boolean when provided.");
     }
     return { format, full: rawFull === true };
 }
 function getSlackEnvelopeCliText(envelope) {
-    if (envelope.status === "succeeded" && isRecord(envelope.data)) {
+    if (envelope.status === "succeeded" && isSlackToolObject(envelope.data)) {
         const text = envelope.data.text;
         if (typeof text === "string" && text.length > 0)
             return text;
@@ -423,6 +407,7 @@ function buildSlackSendPromptGuidelines() {
     return [
         "Use slack_send for replies in the current Slack assistant thread; always reply where the task came from.",
         "For rich Block Kit JSON examples or modal/canvas patterns, load the slack-bridge skill instead of relying on tool schemas.",
+        "If slack_send fails with 'broker is unavailable' or 'already owned by another agent', do NOT retry via post_channel or a different tool \u2014 report the blocker in the same thread (or to the broker) and wait for ownership to be transferred; direct posting would bypass thread ownership (#855).",
     ];
 }
 function getSlackCanvasSummary(markdown) {
@@ -624,32 +609,31 @@ export function registerSlackTools(pi, deps) {
     }
     async function deliverSlackMessage(input) {
         const blocks = input.blocks ? normalizeSlackBlocksInput(input.blocks) : undefined;
-        let fallbackReason;
-        if (input.threadTs && pinetDelivery) {
-            try {
-                if (pinetDelivery.isAvailable()) {
-                    const result = await pinetDelivery.sendSlackMessage({
-                        threadId: input.threadTs,
-                        channel: input.channel,
-                        text: input.text,
-                        ...(blocks ? { blocks } : {}),
-                        ...(input.files ? { files: input.files } : {}),
-                    });
-                    return {
-                        threadTs: input.threadTs,
-                        channel: result.channel,
-                        blocksCount: blocks?.length ?? 0,
-                        delivery: "pinet",
-                        adapter: result.adapter,
-                        messageId: result.messageId,
-                    };
-                }
-            }
-            catch (error) {
-                if (!isPinetDeliveryFallbackError(error))
-                    throw error;
-                fallbackReason = getErrorMessage(error);
-            }
+        // Threaded Slack replies routed through Pinet MUST NOT fall back to direct
+        // Slack when the broker is unavailable or the delivery errors: direct
+        // Slack posting bypasses broker thread-ownership enforcement and lets any
+        // worker with a valid bot token take over a Slack thread it does not own.
+        // See gugu91/pinet#855. Single-player mode (isEnabled === false) and
+        // top-level channel posts (no threadTs) remain unaffected.
+        if (input.threadTs && pinetDelivery?.isEnabled()) {
+            if (!pinetDelivery.isAvailable()) {
+                throw new Error("Cannot post to Slack thread: Pinet broker is unavailable and direct Slack fallback would bypass thread-ownership enforcement. Wait for the broker to reconnect, or ask the broker to transfer this thread.");
+            }
+            const result = await pinetDelivery.sendSlackMessage({
+                threadId: input.threadTs,
+                channel: input.channel,
+                text: input.text,
+                ...(blocks ? { blocks } : {}),
+                ...(input.files ? { files: input.files } : {}),
+            });
+            return {
+                threadTs: input.threadTs,
+                channel: result.channel,
+                blocksCount: blocks?.length ?? 0,
+                delivery: "pinet",
+                adapter: result.adapter,
+                messageId: result.messageId,
+            };
         }
         if (input.files && input.files.length > 0) {
             if (blocks && blocks.length > 0) {
@@ -676,7 +660,6 @@ export function registerSlackTools(pi, deps) {
                 channel: input.channel,
                 blocksCount: blocks?.length ?? 0,
                 delivery: "slack",
-                ...(fallbackReason ? { fallbackReason } : {}),
             };
         }
         const body = {
@@ -693,14 +676,13 @@ export function registerSlackTools(pi, deps) {
         if (input.threadTs)
             body.thread_ts = input.threadTs;
         const response = await slack("chat.postMessage", getBotToken(), body);
-        const message = isRecord(response.message) ? response.message : null;
+        const message = isSlackToolObject(response.message) ? response.message : null;
         const ts = typeof message?.ts === "string" ? message.ts : undefined;
         return {
             ...(ts ? { ts } : {}),
             channel: input.channel,
             blocksCount: blocks?.length ?? 0,
             delivery: "slack",
-            ...(fallbackReason ? { fallbackReason } : {}),
         };
     }
     const slackActionRegistry = new Map();
@@ -712,10 +694,10 @@ export function registerSlackTools(pi, deps) {
         slackActionRegistry.set(action, definition);
     }
     function buildSlackDispatcherHelpEnvelope(args) {
-        if (args != null && !isRecord(args)) {
+        if (args != null && !isSlackToolObject(args)) {
             return buildSlackActionFailureEnvelope(new Error("slack help args must be an object."));
         }
-        const topic = isRecord(args) && typeof args.topic === "string" ? args.topic : undefined;
+        const topic = isSlackToolObject(args) && typeof args.topic === "string" ? args.topic : undefined;
         if (topic) {
             const action = normalizeSlackDispatcherActionName(topic);
             const definition = slackActionRegistry.get(action);
@@ -790,7 +772,7 @@ export function registerSlackTools(pi, deps) {
                 if (action === "help") {
                     return buildSlackDispatcherResponse(buildSlackDispatcherHelpEnvelope(args), output);
                 }
-                if (!isRecord(args)) {
+                if (!isSlackToolObject(args)) {
                     return buildSlackDispatcherResponse(buildSlackActionFailureEnvelope(new Error("slack args must be an object.")), output);
                 }
                 const definition = slackActionRegistry.get(action);
@@ -1268,6 +1250,10 @@ export function registerSlackTools(pi, deps) {
                             : "";
                 lines.push(`${prefix} (${message.timestamp}): ${message.text}${metadataSuffix}`);
             }
+            const subtreeInboxIds = getSubtreeInboxIds(pending);
+            if (subtreeInboxIds.length > 0) {
+                deps.markSubtreeInboxIdsDelivered(subtreeInboxIds);
+            }
             return {
                 content: [
                     {
@@ -1425,7 +1411,10 @@ export function registerSlackTools(pi, deps) {
         label: "Slack Send",
         description: "Send a message in a Slack assistant thread.",
         promptSnippet: "Reply in a Slack assistant thread. When you receive a task: ACK briefly, do the work, report blockers immediately, report the outcome when done. Always reply where the task came from.",
-        promptGuidelines: buildSlackSendPromptGuidelines(),
+        promptGuidelines: [
+            ...buildSlackSendPromptGuidelines(),
+            ...(deps.additionalSendPromptGuidelines ?? []),
+        ],
         parameters: Type.Object({
             text: Type.String({ description: "Message text (Slack markdown)" }),
             thread_ts: Type.Optional(Type.String({
@@ -1479,7 +1468,6 @@ export function registerSlackTools(pi, deps) {
                     filesCount: Array.isArray(params.files) ? params.files.length : 0,
                     ...(delivery.adapter ? { adapter: delivery.adapter } : {}),
                     ...(delivery.messageId ? { messageId: delivery.messageId } : {}),
-                    ...(delivery.fallbackReason ? { fallbackReason: delivery.fallbackReason } : {}),
                 },
             };
         },
@@ -2194,7 +2182,6 @@ export function registerSlackTools(pi, deps) {
                     filesCount: Array.isArray(params.files) ? params.files.length : 0,
                     ...(delivery.adapter ? { adapter: delivery.adapter } : {}),
                     ...(delivery.messageId ? { messageId: delivery.messageId } : {}),
-                    ...(delivery.fallbackReason ? { fallbackReason: delivery.fallbackReason } : {}),
                 },
             };
         },

package/dist/slack-upload.d.ts

@@ -17,8 +17,24 @@ export interface PreparedSlackUpload {
     source: "content" | "path";
     resolvedPath?: string;
 }
+export interface SlackUploadMetadataPayload extends Record<string, unknown> {
+    filename: string;
+    length: number;
+    snippet_type?: string;
+}
+export interface SlackCompleteUploadFilePayload {
+    id: string;
+    title: string;
+}
+export interface SlackCompleteUploadPayload extends Record<string, unknown> {
+    files: SlackCompleteUploadFilePayload[];
+    channel_id: string;
+    thread_ts?: string;
+    initial_comment?: string;
+}
+export type SlackUploadApiBody = SlackUploadMetadataPayload | SlackCompleteUploadPayload;
 export interface SlackUploadDeps {
-    slack: (method: string, token: string, body?: Record<string, unknown>) => Promise<SlackResult>;
+    slack: (method: string, token: string, body?: SlackUploadApiBody) => Promise<SlackResult>;
     token: string;
     fetchImpl?: (url: string, init: RequestInit) => Promise<Pick<Response, "ok" | "status" | "statusText" | "text">>;
 }

package/dist/subtree-broker-runtime.d.ts

@@ -2,21 +2,51 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { AgentSessionSummary } from "./broker/types.js";
 import type { PinetReadOptions, PinetReadResult } from "@pinet/pinet-core/pinet-read-formatting";
 import { type InboxMessage, type PinetControlCommand, type PinetRemoteControlRequestResult, type SlackBridgeSettings } from "./helpers.js";
+import type { BrokerDB } from "./broker/schema.js";
 export interface SubtreeBrokerPaths {
     rootDir: string;
     socketPath: string;
     dbPath: string;
     lockPath: string;
 }
-export interface SubtreeWorkerRecord {
-    launchId: string;
+export type WorkerRuntimeSpec = {
+    runtimeKind: "tmux";
+    sessionName: string;
+    tmuxSocketPath: string | null;
+} | {
+    runtimeKind: "herdr";
     sessionName: string;
+    herdrSession: string;
+    herdrConfigDir: string;
+    herdrPaneId: string | null;
+    herdrShellPid: number | null;
+};
+type HerdrWorkerRuntimeSpec = Extract<WorkerRuntimeSpec, {
+    runtimeKind: "herdr";
+}>;
+export type SubtreeWorkerRecord = WorkerRuntimeSpec & {
+    launchId: string;
     repoPath: string;
     role: string;
     laneId: string | null;
     agentId: string | null;
     startedAt: string;
     monitorCommand: string;
+};
+interface WorkerRuntimeController<T extends WorkerRuntimeSpec> {
+    createLaunchSpec: (sessionName: string) => T;
+    monitorCommand: (spec: T) => string;
+    launch: (spec: T, launcherPath: string, launchEnv: Record<string, string>, onRuntimeOwned?: (spec: T) => void) => Promise<void>;
+    cleanup: (spec: T) => Promise<void>;
+}
+export interface HerdrCommandOptions {
+    env: NodeJS.ProcessEnv;
+    detached?: boolean;
+}
+export type HerdrCommandRunner = (args: string[], options: HerdrCommandOptions) => Promise<string>;
+export interface HerdrWorkerRuntimeControllerOptions {
+    herdrSession: string;
+    herdrConfigDir: string;
 }
 export interface SubtreeBrokerStatus {
     active: boolean;
@@ -50,16 +80,34 @@ export interface SubtreeAgentRecord {
     subtreeRole?: string | null;
     laneId?: string | null;
 }
+export interface SubtreeSpawnLaunchHandle {
+    launchId: string;
+    tmuxSessionName: string;
+    socketPath: string;
+    state: "launched_unregistered";
+    runtimeKind?: WorkerRuntimeSpec["runtimeKind"];
+    monitorCommand?: string;
+}
+export declare class SubtreeSpawnRegistrationTimeoutError extends Error {
+    readonly handle: SubtreeSpawnLaunchHandle;
+    constructor(timeoutMs: number, handle: SubtreeSpawnLaunchHandle);
+}
+export declare class SubtreeSpawnLaunchError extends Error {
+    readonly handle: SubtreeSpawnLaunchHandle;
+    constructor(error: Error, handle: SubtreeSpawnLaunchHandle, runtimeKind?: WorkerRuntimeSpec["runtimeKind"]);
+}
 export interface SubtreeSpawnInput {
     task: string;
     repo: string;
     role?: string;
     laneId?: string;
     waitForRegistrationMs?: number;
+    cleanupHandle?: SubtreeSpawnLaunchHandle;
 }
 export interface SubtreeSpawnResult {
     status: "started";
     launchId: string;
+    runtimeKind: WorkerRuntimeSpec["runtimeKind"];
     sessionName: string;
     repoPath: string;
     role: string;
@@ -85,19 +133,43 @@ export interface SubtreeBrokerRuntimeDeps {
     getAgentMetadata: (role: "broker" | "worker") => Promise<Record<string, unknown>>;
     getMeshRoleFromMetadata: (metadata: Record<string, unknown> | undefined, fallback?: "broker" | "worker") => "broker" | "worker";
     pushInboxMessages: (messages: InboxMessage[]) => void;
+    discardQueuedInboxMessages: () => void;
     updateBadge: () => void;
     maybeDrainInboxIfIdle: (ctx: ExtensionContext) => boolean;
+    deliverSteeringMessage: (text: string, ctx: ExtensionContext) => boolean;
     requestRemoteControl: (command: PinetControlCommand, ctx: ExtensionContext) => PinetRemoteControlRequestResult;
     runRemoteControl: (command: PinetControlCommand, ctx: ExtensionContext) => void;
     formatError: (error: unknown) => string;
+    runTmuxCommand?: (args: string[]) => Promise<void>;
+    runHerdrCommand?: HerdrCommandRunner;
+}
+/**
+ * The authoritative hibernation runtime surface for this process's subtree
+ * broker. The subtree broker is the authority that spawns and OWNS its workers
+ * and authors their durable runtime specs, so hibernate/wake must resolve the
+ * target, read its authz spec, and drive the orchestrator against THIS same
+ * authoritative DB end to end. The explicit trust boundary: the operator command
+ * may only address workers this subtree broker owns. Null when no subtree broker
+ * is running (nothing is command-addressable).
+ */
+export interface SubtreeHibernationRuntimeControl {
+    /** The single authoritative DB that owns the spawned workers + their specs. */
+    db: BrokerDB;
+    /** Broker instance id recorded on lifecycle leases; matches startup recovery. */
+    brokerInstanceId: string;
+    /** Base PINET_* env re-establishing the mesh connection for a woken worker. */
+    baseLaunchEnv: Record<string, string>;
 }
 export interface SubtreeBrokerRuntime {
     start: (ctx: ExtensionContext) => Promise<SubtreeBrokerStatus>;
+    getHibernationRuntimeControl: () => SubtreeHibernationRuntimeControl | null;
     stop: (options?: {
         releaseIdentity?: boolean;
         stopChildren?: boolean;
     }) => Promise<void>;
     getStatus: () => SubtreeBrokerStatus;
+    drainInbox: (ctx: ExtensionContext) => void;
+    markDelivered: (inboxIds: number[]) => void;
     readInbox: (options?: PinetReadOptions) => PinetReadResult | null;
     sendMessage: (target: string, body: string, metadata?: Record<string, unknown>) => Promise<{
         messageId: number;
@@ -109,4 +181,13 @@ export interface SubtreeBrokerRuntime {
     isActive: () => boolean;
 }
 export declare function buildSubtreeBrokerPaths(stableId: string): SubtreeBrokerPaths;
+export declare function createHerdrWorkerRuntimeController(runHerdrCommand: HerdrCommandRunner, options: HerdrWorkerRuntimeControllerOptions): WorkerRuntimeController<HerdrWorkerRuntimeSpec>;
+export declare function getExtensionEntryPath(): string;
+/**
+ * Broker env var NAMES (never values) a spawned — or later WOKEN — worker
+ * re-exports to re-establish itself. Single source of truth shared by the
+ * ordinary spawn launcher and the Phase B wake path so both stay in lockstep.
+ */
+export declare const SUBTREE_INHERITED_ENV_KEYS: string[];
 export declare function createSubtreeBrokerRuntime(deps: SubtreeBrokerRuntimeDeps): SubtreeBrokerRuntime;
+export {};