@pinet/slack-bridge 0.2.1 → 0.2.4

package/dist/broker/adapters/slack.d.ts

@@ -1,4 +1,5 @@
 import { type ParsedAppHomeOpened, type ParsedSlashCommand, type ParsedThreadStarted } from "../../slack-access.js";
+import { type SlackIngressGuardSettings } from "../../helpers.js";
 import { type ReactionCommandSettings } from "../../reaction-triggers.js";
 import type { AdapterCapabilityRequest, AdapterCapabilityResult, InboundMessage, OutboundMessage, MessageAdapter } from "./types.js";
 export { classifyMessage, extractAppHomeOpened, extractThreadStarted, parseMemberJoinedChannel, parseSocketFrame, RECONNECT_DELAY_MS, } from "../../slack-access.js";
@@ -7,6 +8,7 @@ export interface SlackAdapterConfig {
     appToken: string;
     allowedUsers?: string[];
     allowAllWorkspaceUsers?: boolean;
+    ingressGuard?: SlackIngressGuardSettings;
     suggestedPrompts?: {
         title: string;
         message: string;
@@ -33,6 +35,8 @@ export interface SlackAdapterConfig {
      * Slack messages (#812).
      */
     isReactionThreadAuthorized?: (threadTs: string, channelId: string) => boolean;
+    /** Check whether a known Slack thread is Pinet-owned for mixed-participant mention gating. */
+    isPinetOwnedThread?: (threadTs: string, channelId: string) => boolean;
     /** Best-effort callback for Home tab opens. */
     onAppHomeOpened?: (event: ParsedAppHomeOpened) => Promise<void> | void;
     /** Best-effort callback for Slack slash commands handled by the broker process. */
@@ -43,6 +47,7 @@ export declare const SLACK_THREAD_CACHE_TTL_MS: number;
 export declare const SLACK_PENDING_ATTENTION_MAX_THREADS = 1000;
 export declare const SLACK_PENDING_ATTENTION_TTL_MS: number;
 export declare const SLACK_PENDING_ATTENTION_MAX_MESSAGES_PER_THREAD = 50;
+export declare const SLACK_INGRESS_GUARD_THREAD_PARTICIPANT_LIMIT = 200;
 export declare class SlackAdapter implements MessageAdapter {
     readonly name = "slack";
     private readonly config;
@@ -79,6 +84,12 @@ export declare class SlackAdapter implements MessageAdapter {
     private onReactionAdded;
     private getCachedThread;
     private isReactionThreadAuthorized;
+    private messageMentionsBot;
+    private requiresMentionInChannel;
+    private shouldRequireMentionForMixedParticipantThread;
+    private isPinetOwnedThreadForIngressGuard;
+    private fetchThreadParticipantUserIds;
+    private shouldRequireExplicitMention;
     private onMessage;
     private emitInteractiveInbound;
     private onMemberJoined;

package/dist/broker/adapters/slack.js

@@ -5,6 +5,7 @@ import { buildReactionTriggerMessage, normalizeReactionName, resolveReactionComm
 import { TtlCache, TtlSet } from "../../ttl-cache.js";
 import { SLACK_SOCKET_DELIVERY_DEDUP_MAX_SIZE, SLACK_SOCKET_DELIVERY_DEDUP_TTL_MS, } from "../../slack-access.js";
 import { DEFAULT_SLACK_THREAD_STATUS, SlackThreadStatusManager, } from "../../slack-thread-status.js";
+import { renderMarkdownForSlackMrkdwn } from "../../slack-markdown.js";
 import { performSlackUploads, prepareSlackUpload } from "../../slack-upload.js";
 export { classifyMessage, extractAppHomeOpened, extractThreadStarted, parseMemberJoinedChannel, parseSocketFrame, RECONNECT_DELAY_MS, } from "../../slack-access.js";
 export const SLACK_THREAD_CACHE_MAX_SIZE = 5000;
@@ -12,6 +13,7 @@ export const SLACK_THREAD_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
 export const SLACK_PENDING_ATTENTION_MAX_THREADS = 1000;
 export const SLACK_PENDING_ATTENTION_TTL_MS = 2 * 60 * 60 * 1000;
 export const SLACK_PENDING_ATTENTION_MAX_MESSAGES_PER_THREAD = 50;
+export const SLACK_INGRESS_GUARD_THREAD_PARTICIPANT_LIMIT = 200;
 export class SlackAdapter {
     name = "slack";
     config;
@@ -124,9 +126,10 @@ export class SlackAdapter {
             : msg.blocks && msg.blocks.length > 0
                 ? msg.blocks
                 : undefined;
+        const renderedText = renderMarkdownForSlackMrkdwn(msg.content?.markdown ?? msg.content?.text ?? msg.text);
         const body = {
             channel: msg.channel,
-            text: msg.content?.text ?? msg.text,
+            text: renderedText,
             thread_ts: msg.threadId,
             ...(slackBlocks ? { blocks: slackBlocks } : {}),
         };
@@ -157,7 +160,7 @@ export class SlackAdapter {
                 uploads,
                 channelId: msg.channel,
                 threadTs: msg.threadId,
-                initialComment: msg.content?.text ?? msg.text,
+                initialComment: renderedText,
                 slack: this.callSlack.bind(this),
                 token: this.config.botToken,
             });
@@ -464,6 +467,87 @@ export class SlackAdapter {
             return false;
         }
     }
+    messageMentionsBot(evt) {
+        if (!this.botUserId)
+            return false;
+        const text = typeof evt.text === "string" ? evt.text : "";
+        return text.includes(`<@${this.botUserId}>`) || text.includes(`<@${this.botUserId}|`);
+    }
+    requiresMentionInChannel(channelId) {
+        const channels = this.config.ingressGuard?.requireMention?.channels ?? [];
+        return channels.some((channel) => channel.trim() === channelId);
+    }
+    async shouldRequireMentionForMixedParticipantThread(input) {
+        const config = this.config.ingressGuard?.requireMention?.mixedParticipantThreads;
+        if (!config?.enabled || input.isDM || typeof input.evt.thread_ts !== "string") {
+            return false;
+        }
+        if (!this.isPinetOwnedThreadForIngressGuard(input.threadTs, input.channel)) {
+            return false;
+        }
+        const participants = await this.fetchThreadParticipantUserIds(input.channel, input.threadTs, input.userId);
+        if (!participants) {
+            // Fail closed for this guard: if we cannot inspect the thread makeup,
+            // require an explicit mention before Pinet acts in a configured mixed-thread posture.
+            return true;
+        }
+        const trustedUsers = new Set((config.trustedUsers ?? []).map((user) => user.trim()).filter(Boolean));
+        for (const participant of participants) {
+            if (this.botUserId && participant === this.botUserId)
+                continue;
+            if (trustedUsers.has(participant))
+                continue;
+            return true;
+        }
+        return false;
+    }
+    isPinetOwnedThreadForIngressGuard(threadTs, channelId) {
+        const isOwned = this.config.isPinetOwnedThread;
+        if (isOwned) {
+            try {
+                return isOwned(threadTs, channelId);
+            }
+            catch (error) {
+                console.error(`[slack-adapter] Pinet-owned thread check failed: ${errorMsg(error)}`);
+                return false;
+            }
+        }
+        const thread = this.getThread(threadTs);
+        return !!thread && thread.channelId === channelId;
+    }
+    async fetchThreadParticipantUserIds(channelId, threadTs, currentUserId) {
+        const participants = new Set();
+        if (currentUserId)
+            participants.add(currentUserId);
+        try {
+            const response = await this.callSlack("conversations.replies", this.config.botToken, {
+                channel: channelId,
+                ts: threadTs,
+                limit: SLACK_INGRESS_GUARD_THREAD_PARTICIPANT_LIMIT,
+            });
+            const messages = Array.isArray(response.messages) ? response.messages : [];
+            for (const message of messages) {
+                if (!message || typeof message !== "object" || Array.isArray(message))
+                    continue;
+                const userId = message.user;
+                if (typeof userId === "string" && userId.length > 0) {
+                    participants.add(userId);
+                }
+            }
+            return participants;
+        }
+        catch (error) {
+            console.error(`[slack-adapter] failed to inspect Slack thread participants: ${errorMsg(error)}`);
+            return null;
+        }
+    }
+    async shouldRequireExplicitMention(input) {
+        if (!this.config.ingressGuard?.requireMention)
+            return false;
+        if (this.requiresMentionInChannel(input.channel))
+            return true;
+        return this.shouldRequireMentionForMixedParticipantThread(input);
+    }
     async onMessage(evt) {
         if (this.shuttingDown)
             return;
@@ -480,6 +564,10 @@ export class SlackAdapter {
         // traffic can never mint known-thread/affinity side effects (#812).
         if (!isSlackUserAllowed(this.allowlist, userId))
             return;
+        if (!this.messageMentionsBot(evt) &&
+            (await this.shouldRequireExplicitMention({ evt, channel, threadTs, userId, isDM }))) {
+            return;
+        }
         if (!this.getThread(threadTs)) {
             this.threads.set(threadTs, {
                 channelId: channel,

package/dist/broker/client.d.ts

@@ -1,5 +1,5 @@
 import type { PinetReadOptions, PinetReadResult } from "@pinet/pinet-core/pinet-read-formatting";
-import type { ClientAgentInfo, NormalizedMessageContent, OutboundAttachmentFile, PortLeaseAcquireInput, PortLeaseInfo, PortLeaseListOptions, PortLeaseReleaseInput, PortLeaseRenewInput, PinetLaneInfo, PinetLaneListOptions, PinetLaneParticipantInfo, PinetLaneParticipantUpsertInput, PinetLaneUpsertInput } from "./types.js";
+import type { AgentSessionSearchInfo, AgentSessionSearchOptions, ClientAgentInfo, NormalizedMessageContent, OutboundAttachmentFile, PortLeaseAcquireInput, PortLeaseInfo, PortLeaseListOptions, PortLeaseReleaseInput, PortLeaseRenewInput, PinetLaneInfo, PinetLaneListOptions, PinetLaneParticipantInfo, PinetLaneParticipantUpsertInput, PinetLaneUpsertInput } from "./types.js";
 export interface InboxItem {
     inboxId: number;
     message: {
@@ -25,6 +25,7 @@ export interface ThreadInfo {
     updatedAt: string;
 }
 export type AgentInfo = ClientAgentInfo;
+export type { AgentSessionSearchInfo, AgentSessionSearchOptions };
 export interface ScheduledWakeupInfo {
     id: number;
     threadId: string;
@@ -136,6 +137,7 @@ export declare class BrokerClient {
     expirePortLeases(): Promise<PortLeaseInfo[]>;
     listThreads(): Promise<ThreadInfo[]>;
     listAgents(includeDisconnected?: boolean): Promise<AgentInfo[]>;
+    searchAgentSessions(options?: AgentSessionSearchOptions): Promise<AgentSessionSearchInfo[]>;
     invokeAdapterCapability(adapter: string, capability: string, params?: Record<string, unknown>): Promise<Record<string, unknown>>;
     /**
      * Compatibility wrapper for callers that still need direct Slack API access.

package/dist/broker/client.js

@@ -366,6 +366,17 @@ export class BrokerClient {
         const result = (await this.request("agents.list", includeDisconnected ? { includeDisconnected: true } : undefined));
         return result;
     }
+    async searchAgentSessions(options = {}) {
+        try {
+            return (await this.request("agent.sessions.search", options));
+        }
+        catch (err) {
+            if (isRpcMethodNotFoundError(err, "agent.sessions.search")) {
+                throw new Error("Broker does not support Pinet session search (`agent.sessions.search`). Upgrade the broker before using pinet action=sessions.");
+            }
+            throw err;
+        }
+    }
     // ─── Adapter capabilities ───────────────────────────
     async invokeAdapterCapability(adapter, capability, params = {}) {
         const result = (await this.request("adapter.capability", {

package/dist/broker/socket-server.d.ts

@@ -98,6 +98,7 @@ export declare class BrokerSocketServer {
     private handleMessageSend;
     private handleThreadsList;
     private handleAgentsList;
+    private handleAgentSessionsSearch;
     private handleThreadClaim;
     private handleResolveThread;
     private handleAgentMessage;
@@ -116,5 +117,6 @@ export declare class BrokerSocketServer {
     private handleAdapterCapability;
     private handleLegacySlackProxy;
     private dispatchAdapterCapability;
+    private checkAdapterCapabilityThreadOwnership;
     private applyAdapterCapabilityEffects;
 }

package/dist/broker/socket-server.js

@@ -7,14 +7,17 @@ import { MessageRouter } from "./router.js";
 import { dispatchDirectAgentMessage } from "./agent-messaging.js";
 import { sendBrokerMessage } from "./message-send.js";
 import { assertLoopbackTcpHost } from "./raw-tcp-loopback.js";
+import { summarizePinetStableId } from "../pinet-session-formatting.js";
 import { RPC_PARSE_ERROR, RPC_INVALID_REQUEST, RPC_METHOD_NOT_FOUND, RPC_INVALID_PARAMS, RPC_INTERNAL_ERROR, RPC_AUTH_REQUIRED, RPC_AGENT_NAME_CONFLICT, RPC_AGENT_STABLE_ID_CONFLICT, } from "./types.js";
 export const DEFAULT_HEARTBEAT_TIMEOUT_MS = 15_000;
 export const DEFAULT_PRUNE_INTERVAL_MS = 5_000;
 export const DEFAULT_AUTH_TIMEOUT_MS = 2_000;
 function toClientAgentInfo(agent) {
     const { stableId, ...clientAgent } = agent;
-    void stableId;
-    return clientAgent;
+    return {
+        ...clientAgent,
+        session: summarizePinetStableId(stableId),
+    };
 }
 // ─── RPC helpers ─────────────────────────────────────────
 function rpcOk(id, result) {
@@ -351,6 +354,8 @@ export class BrokerSocketServer {
                     return this.handleThreadsList(req, state);
                 case "agents.list":
                     return this.handleAgentsList(req);
+                case "agent.sessions.search":
+                    return this.handleAgentSessionsSearch(req, state);
                 case "thread.claim":
                     return this.handleThreadClaim(req, state);
                 case "resolveThread":
@@ -686,6 +691,35 @@ export class BrokerSocketServer {
         }));
         return rpcOk(req.id, agents);
     }
+    handleAgentSessionsSearch(req, state) {
+        if (!state.agentId) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "Not registered");
+        }
+        const caller = this.db.getAgentById(state.agentId);
+        const metadataRole = typeof caller?.metadata?.role === "string" ? caller.metadata.role.trim().toLowerCase() : "";
+        const capabilities = caller?.metadata?.capabilities &&
+            typeof caller.metadata.capabilities === "object" &&
+            !Array.isArray(caller.metadata.capabilities)
+            ? caller.metadata.capabilities
+            : null;
+        const capabilityRole = typeof capabilities?.role === "string" ? capabilities.role.trim().toLowerCase() : "";
+        if (metadataRole !== "broker" && capabilityRole !== "broker") {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "agent.sessions.search requires a broker agent");
+        }
+        const params = req.params ?? {};
+        const options = {
+            ...(typeof params.agentName === "string" ? { agentName: params.agentName } : {}),
+            ...(typeof params.agentId === "string" ? { agentId: params.agentId } : {}),
+            ...(typeof params.threadId === "string" ? { threadId: params.threadId } : {}),
+            ...(typeof params.repo === "string" ? { repo: params.repo } : {}),
+            ...(typeof params.worktreePath === "string" ? { worktreePath: params.worktreePath } : {}),
+            ...(typeof params.tmuxSession === "string" ? { tmuxSession: params.tmuxSession } : {}),
+            ...(typeof params.since === "string" ? { since: params.since } : {}),
+            ...(typeof params.until === "string" ? { until: params.until } : {}),
+            ...(typeof params.limit === "number" ? { limit: params.limit } : {}),
+        };
+        return rpcOk(req.id, this.db.searchAgentSessions(options));
+    }
     // ─── Thread claim handler ─────────────────────────────
     handleThreadClaim(req, state) {
         if (!state.agentId) {
@@ -1044,6 +1078,14 @@ export class BrokerSocketServer {
     }
     // ─── Adapter capability handler ───────────────────────
     async handleAdapterCapability(req, state) {
+        // #855: adapter.capability must be identity-bound so the broker can
+        // enforce thread ownership. Unregistered callers cannot own or claim
+        // threads, so they must not be able to invoke outbound-side capabilities
+        // (chat.postMessage in particular) that would race a first-responder
+        // claim or take over a thread already owned by another agent.
+        if (!state.agentId) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "Not registered");
+        }
         const params = req.params ?? {};
         const adapterName = typeof params.adapter === "string"
             ? params.adapter.trim()
@@ -1063,6 +1105,12 @@ export class BrokerSocketServer {
         return await this.dispatchAdapterCapability(req.id, adapterName, capability, capabilityParams, state);
     }
     async handleLegacySlackProxy(req, state) {
+        // #855: legacy slack.proxy is a compatibility wrapper over
+        // adapter.capability and must enforce the same registration bar so
+        // unregistered callers cannot bypass thread ownership via chat.postMessage.
+        if (!state.agentId) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "Not registered");
+        }
         const params = req.params ?? {};
         const method = typeof params.method === "string" ? params.method.trim() : "";
         if (!method) {
@@ -1078,6 +1126,15 @@ export class BrokerSocketServer {
         if (!adapter?.invokeCapability) {
             return rpcError(id, RPC_METHOD_NOT_FOUND, `Adapter ${adapterName} does not implement capability ${capability}`);
         }
+        // #855: refuse cross-owner Slack chat.postMessage before hitting Slack.
+        // Without this pre-check the adapter posts first and the broker races a
+        // first-responder-wins claim via effects.claimThread — letting an
+        // unauthorized follower take over a thread already owned by another
+        // agent simply by winning the send.
+        const ownershipError = this.checkAdapterCapabilityThreadOwnership(adapterName, capability, capabilityParams, state.agentId);
+        if (ownershipError) {
+            return rpcError(id, RPC_INVALID_PARAMS, `${errorPrefix}: ${ownershipError}`);
+        }
         try {
             const response = await adapter.invokeCapability({ capability, params: capabilityParams });
             this.applyAdapterCapabilityEffects(adapterName, response, state);
@@ -1088,6 +1145,36 @@ export class BrokerSocketServer {
             return rpcError(id, RPC_INTERNAL_ERROR, `${errorPrefix}: ${message}`);
         }
     }
+    checkAdapterCapabilityThreadOwnership(adapterName, capability, capabilityParams, callerAgentId) {
+        if (adapterName !== "slack")
+            return null;
+        if (capability !== "api.call")
+            return null;
+        const method = typeof capabilityParams.method === "string" ? capabilityParams.method.trim() : "";
+        if (method !== "chat.postMessage")
+            return null;
+        const inner = capabilityParams.params &&
+            typeof capabilityParams.params === "object" &&
+            !Array.isArray(capabilityParams.params)
+            ? capabilityParams.params
+            : {};
+        const threadTs = typeof inner.thread_ts === "string" ? inner.thread_ts.trim() : "";
+        if (!threadTs)
+            return null;
+        // Defense in depth (#855): even if a future call path forgot the
+        // registration guard on the handler, refuse threaded chat.postMessage
+        // for unregistered callers here — they cannot own a Slack thread and
+        // must not be able to post into one.
+        if (!callerAgentId) {
+            return `Slack thread ${threadTs}: refusing threaded chat.postMessage from an unregistered caller`;
+        }
+        const thread = this.db.getThread(threadTs);
+        if (!thread?.ownerAgent)
+            return null;
+        if (thread.ownerAgent === callerAgentId)
+            return null;
+        return `Slack thread ${threadTs} is already owned by another agent; refusing cross-owner chat.postMessage`;
+    }
     applyAdapterCapabilityEffects(adapterName, response, state) {
         if (!state.agentId)
             return;

package/dist/helpers.d.ts

@@ -1,5 +1,17 @@
 import { type RuntimeScopeCarrier } from "@pinet/transport-core";
 import type { ReactionCommandSettings } from "./reaction-triggers.js";
+import type { AgentSessionSummary } from "./broker/types.js";
+export interface SlackIngressGuardSettings {
+    requireMention?: {
+        /** Slack channel IDs where every actionable message must explicitly mention the bot. */
+        channels?: string[];
+        /** Require mention in Pinet-owned threads once anyone outside trustedUsers + the bot participates. */
+        mixedParticipantThreads?: {
+            enabled?: boolean;
+            trustedUsers?: string[];
+        };
+    };
+}
 export interface SlackBridgeSettings {
     botToken?: string;
     appToken?: string;
@@ -7,6 +19,7 @@ export interface SlackBridgeSettings {
     appConfigToken?: string;
     allowedUsers?: string[];
     allowAllWorkspaceUsers?: boolean;
+    ingressGuard?: SlackIngressGuardSettings;
     defaultChannel?: string;
     logChannel?: string;
     logLevel?: "errors" | "actions" | "verbose";
@@ -157,6 +170,8 @@ export interface AgentDisplayInfo {
     name: string;
     id: string;
     pid?: number;
+    stableId?: string | null;
+    session?: AgentSessionSummary | null;
     status: "working" | "idle";
     metadata?: {
         cwd?: string;
@@ -210,6 +225,8 @@ export interface AgentVisibilityInput {
     name: string;
     id: string;
     pid?: number;
+    stableId?: string | null;
+    session?: AgentSessionSummary | null;
     status: "working" | "idle";
     metadata?: Record<string, unknown> | null;
     lastHeartbeat?: string;

package/dist/helpers.js

@@ -5,6 +5,7 @@ import { classifyPinetMail, formatPinetMailClassLabel, } from "@pinet/broker-cor
 import { buildCompatibilityInstanceScope, buildCompatibilityWorkspaceScope, buildRuntimeScopeCarrier, } from "@pinet/transport-core";
 import { buildPinetReadPointer } from "./broker-inbound-persistence.js";
 import { matchesToolPattern } from "./guardrails.js";
+import { getPinetSessionPath, summarizePinetStableId } from "./pinet-session-formatting.js";
 function normalizeOptionalSetting(value) {
     const trimmed = value?.trim();
     return trimmed && trimmed.length > 0 ? trimmed : null;
@@ -855,6 +856,8 @@ export function buildAgentDisplayInfo(agent, options = {}) {
         name: agent.name,
         id: agent.id,
         ...(agent.pid != null ? { pid: agent.pid } : {}),
+        ...(agent.stableId !== undefined ? { stableId: agent.stableId } : {}),
+        session: agent.session ?? summarizePinetStableId(agent.stableId),
         status: agent.status,
         metadata: metadata || hasHierarchyMetadata
             ? {
@@ -1733,7 +1736,15 @@ export function formatAgentList(agents, homedir) {
             : "";
         const stuckTag = a.stuck ? " [stuck]" : "";
         const pid = a.pid != null ? ` pid:${a.pid}` : "";
-        let line = `${a.emoji} ${a.name} (${a.id}) \u2014 ${a.status}${statusFlavor}${health}${stuckTag}${pid}`;
+        const sessionRef = a.session?.ref ? ` session:${a.session.ref}` : "";
+        let line = `${a.emoji} ${a.name} (${a.id}) \u2014 ${a.status}${statusFlavor}${health}${stuckTag}${pid}${sessionRef}`;
+        if (a.stableId) {
+            const sessionPath = getPinetSessionPath(a.stableId);
+            line += `\n   stable: ${a.stableId}`;
+            if (sessionPath) {
+                line += `\n   jsonl: ${sessionPath}`;
+            }
+        }
         const meta = a.metadata;
         if (meta && (meta.cwd || meta.branch || meta.host || meta.gitProbeFailed)) {
             const cwd = meta.cwd ? shortenPath(meta.cwd, homedir) : "";

package/dist/index.js

@@ -733,7 +733,7 @@ export default function (pi) {
             brokerRuntime.logActivity(entry);
         },
     });
-    const { sendPinetAgentMessage, sendPinetBroadcastMessage, scheduleBrokerWakeup, scheduleFollowerWakeup, listBrokerAgents, listFollowerAgents, } = pinetMeshOps;
+    const { sendPinetAgentMessage, sendPinetBroadcastMessage, scheduleBrokerWakeup, scheduleFollowerWakeup, listBrokerAgents, listFollowerAgents, searchPinetSessions, } = pinetMeshOps;
     async function listPinetLanes(options) {
         if (brokerRole === "broker") {
             const db = getActiveBrokerDb();
@@ -1002,6 +1002,7 @@ export default function (pi) {
             getBotUserId: () => botUserId,
             registerConfirmationRequest,
             pinetDelivery: {
+                isEnabled: () => pinetEnabled,
                 isAvailable: () => pinetEnabled && brokerRole !== null,
                 sendSlackMessage: async (input) => {
                     const content = {
@@ -1072,6 +1073,7 @@ export default function (pi) {
             readPinetInbox,
             listBrokerAgents,
             listFollowerAgents,
+            searchPinetSessions,
             listSubtreeAgents: (includeGhosts) => subtreeBrokerRuntime.listAgents(includeGhosts),
             getSubtreeSelfAgentId: () => subtreeBrokerRuntime.getStatus().selfAgentId,
             spawnSubtreeWorker: async (input) => {

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

@@ -1,11 +1,13 @@
 import { type AgentMessageStorage } from "./broker/agent-messaging.js";
-import type { AgentInfo, TaskAssignmentInfo, TaskAssignmentKind } from "./broker/types.js";
+import type { AgentInfo, AgentSessionSearchInfo, AgentSessionSearchOptions, AgentSessionSummary, TaskAssignmentInfo, TaskAssignmentKind } from "./broker/types.js";
 import type { ActivityLogEntry } from "./activity-log.js";
 export interface PinetMeshOpsAgentRecord {
     emoji: string;
     name: string;
     id: string;
     pid?: number;
+    stableId?: string | null;
+    session?: AgentSessionSummary | null;
     status: "working" | "idle";
     metadata: Record<string, unknown> | null;
     lastHeartbeat: string;
@@ -32,6 +34,7 @@ export interface PinetMeshOpsTransferableThread {
 }
 export interface PinetMeshOpsBrokerDbPort extends AgentMessageStorage {
     getAllAgents: () => AgentInfo[];
+    searchAgentSessions: (options?: AgentSessionSearchOptions) => AgentSessionSearchInfo[];
     getPendingInboxCount: (agentId: string) => number;
     getThread: (threadId: string) => PinetMeshOpsTransferableThread | null;
     transferThreadOwnership: (threadId: string, ownerAgent: string) => {
@@ -62,6 +65,7 @@ export interface PinetMeshOpsFollowerClientPort {
         fireAt: string;
     }>;
     listAgents: (includeGhosts: boolean) => Promise<PinetMeshOpsFollowerAgentRecord[]>;
+    searchAgentSessions: (options: AgentSessionSearchOptions) => Promise<AgentSessionSearchInfo[]>;
 }
 export interface PinetMeshOpsDeps {
     getPinetEnabled: () => boolean;
@@ -100,6 +104,7 @@ export interface PinetMeshOps {
     }>;
     listBrokerAgents: () => PinetMeshOpsAgentRecord[];
     listFollowerAgents: (includeGhosts: boolean) => Promise<PinetMeshOpsAgentRecord[]>;
+    searchPinetSessions: (options: AgentSessionSearchOptions) => Promise<AgentSessionSearchInfo[]>;
 }
 export declare function parseGitHubRemoteRepo(remoteUrl: string): {
     repoOwner: string;

package/dist/pinet-mesh-ops.js

@@ -2,6 +2,7 @@ import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { normalizeOutgoingPinetControlMessage } from "./helpers.js";
 import { dispatchBroadcastAgentMessage, dispatchDirectAgentMessage, isBroadcastChannelTarget, } from "./broker/agent-messaging.js";
+import { summarizePinetStableId } from "./pinet-session-formatting.js";
 import { extractTaskAssignmentsFromMessage } from "./task-assignments.js";
 const execFileAsync = promisify(execFile);
 function prepareOutgoingPinetAgentMessage(body, metadata) {
@@ -33,6 +34,7 @@ function appendSlackThreadTransferNotice(body, threadId, channel) {
         `- channel: ${channel}`,
         `- To report directly in the transferred Slack thread, use slack_send with thread_ts ${threadId}; the channel is already recorded in Pinet.`,
         "- If slack_send says the thread is already owned by another agent, ask the broker to inspect ownership and transfer it again.",
+        "- If slack_send says the Pinet broker is unavailable, wait for the broker to reconnect \u2014 do NOT retry via post_channel; direct posting would bypass thread ownership (#855).",
     ].join("\n");
 }
 export function parseGitHubRemoteRepo(remoteUrl) {
@@ -230,6 +232,8 @@ export function createPinetMeshOps(deps) {
             name: agent.name,
             id: agent.id,
             pid: agent.pid,
+            stableId: agent.stableId ?? null,
+            session: summarizePinetStableId(agent.stableId),
             status: agent.status,
             metadata: agent.metadata,
             lastHeartbeat: agent.lastHeartbeat,
@@ -256,6 +260,7 @@ export function createPinetMeshOps(deps) {
             name: agent.name,
             id: agent.id,
             pid: agent.pid,
+            session: agent.session ?? null,
             status: agent.status ?? "idle",
             metadata: agent.metadata,
             lastHeartbeat: agent.lastHeartbeat,
@@ -272,6 +277,20 @@ export function createPinetMeshOps(deps) {
             laneId: agent.laneId,
         }));
     }
+    async function searchPinetSessions(options) {
+        if (deps.getBrokerRole() === "broker") {
+            const db = deps.getActiveBrokerDb();
+            if (!db) {
+                throw new Error("Broker agent identity is unavailable.");
+            }
+            return db.searchAgentSessions(options);
+        }
+        const client = deps.getFollowerClient();
+        if (!client) {
+            throw new Error("Pinet is in an unexpected state.");
+        }
+        return await client.searchAgentSessions(options);
+    }
     return {
         sendPinetAgentMessage,
         sendPinetBroadcastMessage,
@@ -279,5 +298,6 @@ export function createPinetMeshOps(deps) {
         scheduleFollowerWakeup,
         listBrokerAgents,
         listFollowerAgents,
+        searchPinetSessions,
     };
 }

package/dist/pinet-session-formatting.d.ts

@@ -0,0 +1,13 @@
+import type { AgentSessionKind, AgentSessionSearchInfo, AgentSessionSummary } from "./broker/types.js";
+export interface ParsedPinetStableId {
+    host: string | null;
+    kind: AgentSessionKind;
+    locator: string;
+    hasPath: boolean;
+}
+export declare function parsePinetStableId(stableId: string | null | undefined): ParsedPinetStableId | null;
+export declare function summarizePinetStableId(stableId: string | null | undefined): AgentSessionSummary | null;
+export declare function getPinetSessionPath(stableId: string | null | undefined): string | null;
+export declare function getPinetSessionFilename(stableId: string | null | undefined): string | null;
+export declare function buildPinetSessionFullDetails(session: AgentSessionSearchInfo): Record<string, unknown>;
+export declare function buildPinetSessionCompactDetails(session: AgentSessionSearchInfo): Record<string, unknown>;