@pinet/slack-bridge 0.2.0 → 0.2.2

package/README.md

@@ -160,6 +160,15 @@ Behavior and precedence:
     "appToken": "xapp-...",
     "runtimeMode": "single",
     "allowedUsers": ["U_EXAMPLE_MEMBER_ID"],
+    "ingressGuard": {
+      "requireMention": {
+        "channels": ["C_EXTERNAL_CHANNEL_ID"],
+        "mixedParticipantThreads": {
+          "enabled": true,
+          "trustedUsers": ["U_EXAMPLE_MEMBER_ID"]
+        }
+      }
+    },
     "defaultChannel": "C_EXAMPLE_CHANNEL_ID",
     "logChannel": "#pinet-logs",
     "logLevel": "actions",
@@ -183,30 +192,33 @@ Slack access is now **default-deny** unless you configure one of these explicitl
 - `allowedUsers` / `SLACK_ALLOWED_USERS` — allow only specific Slack user IDs
 - `allowAllWorkspaceUsers: true` / `SLACK_ALLOW_ALL_WORKSPACE_USERS=true` — explicit workspace-wide opt-in
 
-| Key                            | Required | Description                                                                                                           |
-| ------------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------- |
-| `botToken`                     | **yes**  | Bot User OAuth Token (`xoxb-...`)                                                                                     |
-| `appToken`                     | **yes**  | App-Level Token for Socket Mode (`xapp-...`)                                                                          |
-| `allowedUsers`                 | no       | Slack user IDs that can interact; when unset, access is denied unless `allowAllWorkspaceUsers` is true                |
-| `allowAllWorkspaceUsers`       | no       | Explicit opt-in for workspace-wide Slack access when you do not want a user allowlist                                 |
-| `defaultChannel`               | no       | Default channel for the `slack` dispatcher `post_channel` action                                                      |
-| `logChannel`                   | no       | Channel for broker activity logs                                                                                      |
-| `logLevel`                     | no       | `"errors"`, `"actions"` (default), or `"verbose"`                                                                     |
-| `runtimeMode`                  | no       | Explicit startup mode: `"off"`, `"single"`, `"broker"`, or `"follower"`                                               |
-| `autoConnect`                  | no       | Legacy compatibility alias for `runtimeMode: "single"`                                                                |
-| `autoFollow`                   | no       | Legacy compatibility alias for follower startup when a broker socket exists                                           |
-| `ralphLoopIntervalMs`          | no       | Broker RALPH maintenance cadence in milliseconds; defaults to `300000` (5 minutes), valid range `1000`-`2147483647`   |
-| `ralphSnoozeAfterEmptyCycles`  | no       | Broker RALPH auto-snooze trigger after N empty cycles; defaults to `0` (disabled), valid range `0`-`100`              |
-| `ralphSnoozeDurationMs`        | no       | Broker RALPH auto-snooze duration in milliseconds; defaults to `1800000` (30 minutes), valid range `60000`-`86400000` |
-| `skinTheme`                    | no       | Pinet presentation skin selected at broker startup/reload (`default`, `foundation`, `cosmere`, or free-form)          |
-| `slackCommandName`             | no       | Slack web app slash command name for `agents list`; defaults to `/pinet`, or `/oathgate` for Oathgate/Cosmere skins   |
-| `slackCommandNames`            | no       | Optional list of accepted/deployed Slack slash command aliases when one app needs multiple command names              |
-| `meshSecret`                   | no       | Optional inline Pinet shared secret; overrides `meshSecretPath` and env fallbacks                                     |
-| `meshSecretPath`               | no       | Optional path to a shared-secret file; broker creates it if missing, followers require an existing file               |
-| `suggestedPrompts`             | no       | Prompts shown when a user opens a new conversation                                                                    |
-| `security.readOnly`            | no       | Runtime-block write-capable tools for Slack-triggered turns, including core tools like `bash`, `edit`, and `write`    |
-| `security.requireConfirmation` | no       | Runtime-require Slack approval before matching tools execute; core tools need a specific Slack thread context         |
-| `security.blockedTools`        | no       | Runtime-block matching tools for Slack-triggered turns, including core tools                                          |
+Optional explicit invocation guard: `ingressGuard.requireMention` is off by default. Set `channels` to Slack channel IDs where otherwise-actionable messages must mention the bot (`@pinet` / `<@bot>`), and set `mixedParticipantThreads.enabled: true` with `trustedUsers` to require a mention in Pinet-owned Slack threads once anyone outside `trustedUsers` plus the bot has participated. This guard is orthogonal to `allowedUsers`: sender authorization still decides who may invoke Pinet; the guard only decides when an explicit mention is required.
+
+| Key                            | Required | Description                                                                                                            |
+| ------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `botToken`                     | **yes**  | Bot User OAuth Token (`xoxb-...`)                                                                                      |
+| `appToken`                     | **yes**  | App-Level Token for Socket Mode (`xapp-...`)                                                                           |
+| `allowedUsers`                 | no       | Slack user IDs that can interact; when unset, access is denied unless `allowAllWorkspaceUsers` is true                 |
+| `allowAllWorkspaceUsers`       | no       | Explicit opt-in for workspace-wide Slack access when you do not want a user allowlist                                  |
+| `ingressGuard.requireMention`  | no       | Optional Slack ingress guard requiring `@pinet` in configured channel IDs and/or mixed-participant Pinet-owned threads |
+| `defaultChannel`               | no       | Default channel for the `slack` dispatcher `post_channel` action                                                       |
+| `logChannel`                   | no       | Channel for broker activity logs                                                                                       |
+| `logLevel`                     | no       | `"errors"`, `"actions"` (default), or `"verbose"`                                                                      |
+| `runtimeMode`                  | no       | Explicit startup mode: `"off"`, `"single"`, `"broker"`, or `"follower"`                                                |
+| `autoConnect`                  | no       | Legacy compatibility alias for `runtimeMode: "single"`                                                                 |
+| `autoFollow`                   | no       | Legacy compatibility alias for follower startup when a broker socket exists                                            |
+| `ralphLoopIntervalMs`          | no       | Broker RALPH maintenance cadence in milliseconds; defaults to `300000` (5 minutes), valid range `1000`-`2147483647`    |
+| `ralphSnoozeAfterEmptyCycles`  | no       | Broker RALPH auto-snooze trigger after N empty cycles; defaults to `0` (disabled), valid range `0`-`100`               |
+| `ralphSnoozeDurationMs`        | no       | Broker RALPH auto-snooze duration in milliseconds; defaults to `1800000` (30 minutes), valid range `60000`-`86400000`  |
+| `skinTheme`                    | no       | Pinet presentation skin selected at broker startup/reload (`default`, `foundation`, `cosmere`, or free-form)           |
+| `slackCommandName`             | no       | Slack web app slash command name for `agents list`; defaults to `/pinet`, or `/oathgate` for Oathgate/Cosmere skins    |
+| `slackCommandNames`            | no       | Optional list of accepted/deployed Slack slash command aliases when one app needs multiple command names               |
+| `meshSecret`                   | no       | Optional inline Pinet shared secret; overrides `meshSecretPath` and env fallbacks                                      |
+| `meshSecretPath`               | no       | Optional path to a shared-secret file; broker creates it if missing, followers require an existing file                |
+| `suggestedPrompts`             | no       | Prompts shown when a user opens a new conversation                                                                     |
+| `security.readOnly`            | no       | Runtime-block write-capable tools for Slack-triggered turns, including core tools like `bash`, `edit`, and `write`     |
+| `security.requireConfirmation` | no       | Runtime-require Slack approval before matching tools execute; core tools need a specific Slack thread context          |
+| `security.blockedTools`        | no       | Runtime-block matching tools for Slack-triggered turns, including core tools                                           |
 
 ## Scope carrier model (compatibility-first)
 
@@ -516,17 +528,19 @@ Only broker prompt content is replaceable. Broker runtime/tool restrictions rema
 
 ### Multi-agent tools
 
-| Tool    | Description                                                                                                                                                                |
-| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `pinet` | Pinet dispatcher with token-efficient `action`-based routing (`help`, `send`, `read`, `free`, `snooze`, `schedule`, `agents`, `lanes`, `ports`, `spawn`, `reload`, `exit`) |
+| Tool    | Description                                                                                                                                                                            |
+| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pinet` | Pinet dispatcher with token-efficient `action`-based routing (`help`, `send`, `read`, `free`, `snooze`, `schedule`, `agents`, `sessions`, `lanes`, `ports`, `spawn`, `reload`, `exit`) |
 
-Use the dispatcher for Pinet tool actions: `pinet action=send`, `pinet action=read`, `pinet action=free`, `pinet action=snooze`, `pinet action=schedule`, `pinet action=agents`, `pinet action=lanes`, `pinet action=ports`, `pinet action=spawn`, `pinet action=reload`, and `pinet action=exit`. Use slash commands for UI lifecycle transitions: `/pinet start`, `/pinet follow`, `/pinet unfollow`, and `/pinet subtree start`. Dedicated direct Pinet tools (`pinet_message`, `pinet_read`, `pinet_agents`, `pinet_free`, `pinet_schedule`) are no longer registered. Legacy `pinet_*` guardrail patterns still match dispatcher action names, and legacy send policies such as `pinet_send` or `pinet_message` also cover `pinet action=send`, so existing security configs fail closed during migration.
+Use the dispatcher for Pinet tool actions: `pinet action=send`, `pinet action=read`, `pinet action=free`, `pinet action=snooze`, `pinet action=schedule`, `pinet action=agents`, `pinet action=sessions`, `pinet action=lanes`, `pinet action=ports`, `pinet action=spawn`, `pinet action=reload`, and `pinet action=exit`. Use slash commands for UI lifecycle transitions: `/pinet start`, `/pinet follow`, `/pinet unfollow`, and `/pinet subtree start`. Dedicated direct Pinet tools (`pinet_message`, `pinet_read`, `pinet_agents`, `pinet_free`, `pinet_schedule`) are no longer registered. Legacy `pinet_*` guardrail patterns still match dispatcher action names, and legacy send policies such as `pinet_send` or `pinet_message` also cover `pinet action=send`, so existing security configs fail closed during migration.
 
 Worker-owned subtree brokers let a follower worker supervise its own child mesh without registering those children in the central broker. Run `/pinet subtree start` (alias: `/pinet subbroker start`) from a follower worker. The worker remains connected to the central broker as a normal worker, and it also starts a separate broker socket/database under `~/.pi/pinet-subtrees/<worker>/`. Child workers launched by this worker receive `PINET_SOCKET_PATH`, `PINET_PARENT_AGENT_ID`, `PINET_ROOT_AGENT_ID`, `PINET_LAUNCH_ID`, `PINET_SUBTREE_ROLE`, and related metadata, so they follow the worker's subtree broker instead of the central Pinet broker.
 
 Use `pinet action=spawn args.repo=<repo> args.task=<task> [args.role=<role>] [args.lane_id=<lane>]` or `/pinet subtree spawn repo=<repo> [role=<role>] [lane=<lane>] <task>` to launch a tmux-backed child worker, wait for it to register in the subtree broker, and deliver the task over private Pinet A2A. Use `pinet action=agents args.scope=subtree args.full=true` from the supervising worker to list subtree children, `pinet action=send args.to=<child> args.message=<message>` to reply/control them, `pinet action=read` to read child reports, and `pinet action=exit args.target=<child>` or `/pinet subtree stop` to clean them up. The central broker sees only the supervising worker; the subtree DB contains the child roster and messages.
 
-Dispatcher content defaults to terse CLI-style confirmations/summaries for noisy reads, sends, and agent lists. Bulky read/agent payloads are compacted in `data.details` by default, including when `args.format="json"` (or `args.f` / `args["-f"]`) renders the dispatcher envelope in content. Use `args.full=true` / `args["--full"]=true` only when you need verbose text and full structured debug details such as exact message bodies or agent metadata.
+Dispatcher content defaults to terse CLI-style confirmations/summaries for noisy reads, sends, agent lists, and session lookups. Bulky read/agent/session payloads are compacted in `data.details` by default, including when `args.format="json"` (or `args.f` / `args["-f"]`) renders the dispatcher envelope in content. Use `args.full=true` / `args["--full"]=true` only when you need verbose text and full structured debug details such as exact message bodies, agent metadata, stable session IDs, or local session JSONL paths.
+
+`pinet action=agents` shows a broker-safe session reference (`session:<digest>`) alongside pid in verbose roster output without exposing raw local paths by default. Use `pinet action=sessions args.agent_name="Frozen Hazel Whale"` to search live and historical worker sessions by display name; the search also accepts `agent_id`, `thread_id`, `repo`, `worktree_path`, `tmux_session`, `since`, `until`, and `limit`. Default output redacts path-bearing stable IDs; add `args.full=true` (or JSON plus `full`) only in local/debug contexts when the broker needs the exact stable ID or Pi session JSONL path for inspection/resume.
 
 Durable Pinet inbox notifications are classified as `steering`, `fwup`, or `maintenance/context` from explicit metadata or message cues. Follower prompts receive compact pointers such as `pinet action=read args.thread_id=...` instead of the full durable message body; agents use `pinet action=read` to retrieve the actual context. Delivery, read/ack state, and mail classification remain separate.
 

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;

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) {

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();
@@ -1072,6 +1072,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) {
@@ -230,6 +231,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 +259,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 +276,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 +297,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>;

package/dist/pinet-session-formatting.js

@@ -0,0 +1,80 @@
+import * as crypto from "node:crypto";
+import * as path from "node:path";
+function stableIdDigest(stableId) {
+    return crypto.createHash("sha256").update(stableId).digest("hex").slice(0, 12);
+}
+export function parsePinetStableId(stableId) {
+    const value = stableId?.trim();
+    if (!value)
+        return null;
+    const firstColon = value.indexOf(":");
+    const secondColon = firstColon >= 0 ? value.indexOf(":", firstColon + 1) : -1;
+    if (firstColon < 0 || secondColon < 0) {
+        return { host: null, kind: "unknown", locator: value, hasPath: false };
+    }
+    const host = value.slice(0, firstColon) || null;
+    const rawKind = value.slice(firstColon + 1, secondColon);
+    const locator = value.slice(secondColon + 1);
+    const kind = rawKind === "session" || rawKind === "leaf" || rawKind === "cwd" || rawKind === "broker"
+        ? rawKind
+        : "unknown";
+    return {
+        host,
+        kind,
+        locator,
+        hasPath: locator.startsWith("/") && (kind === "session" || kind === "cwd" || kind === "broker"),
+    };
+}
+export function summarizePinetStableId(stableId) {
+    const value = stableId?.trim();
+    if (!value)
+        return null;
+    const parsed = parsePinetStableId(value);
+    const kind = parsed?.kind ?? "unknown";
+    return {
+        kind,
+        ref: `${kind}:${stableIdDigest(value)}`,
+        host: parsed?.host ?? null,
+        hasPath: parsed?.hasPath ?? false,
+    };
+}
+export function getPinetSessionPath(stableId) {
+    const parsed = parsePinetStableId(stableId);
+    if (!parsed?.hasPath)
+        return null;
+    return parsed.locator;
+}
+export function getPinetSessionFilename(stableId) {
+    const sessionPath = getPinetSessionPath(stableId);
+    return sessionPath ? path.basename(sessionPath) : null;
+}
+export function buildPinetSessionFullDetails(session) {
+    const summary = summarizePinetStableId(session.stableId);
+    const sessionPath = getPinetSessionPath(session.stableId);
+    return {
+        ...session,
+        session: summary,
+        ...(sessionPath ? { jsonlPath: sessionPath } : {}),
+    };
+}
+export function buildPinetSessionCompactDetails(session) {
+    const summary = summarizePinetStableId(session.stableId);
+    return {
+        agentId: session.agentId,
+        agentName: session.agentName,
+        emoji: session.emoji,
+        pid: session.pid,
+        status: session.status,
+        health: session.disconnectedAt ? "disconnected" : "live",
+        session: summary?.ref ?? null,
+        sessionKind: summary?.kind ?? null,
+        host: summary?.host ?? null,
+        repo: session.repo,
+        branch: session.branch,
+        tmuxSession: session.tmuxSession,
+        lastSeen: session.lastSeen,
+        disconnectedAt: session.disconnectedAt,
+        relatedThreadIds: session.relatedThreadIds.slice(0, 5),
+        matchedBy: session.matchedBy,
+    };
+}

package/dist/pinet-tools.d.ts

@@ -1,12 +1,14 @@
 import { type PinetReadOptions, type PinetReadResult } from "@pinet/pinet-core/pinet-read-formatting";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { RalphSnoozeStatus } from "./ralph-loop.js";
-import type { PortLeaseAcquireInput, PortLeaseInfo, PortLeaseListOptions, PortLeaseReleaseInput, PortLeaseRenewInput, PinetLaneInfo, PinetLaneListOptions, PinetLaneParticipantInfo, PinetLaneParticipantUpsertInput, PinetLaneUpsertInput } from "./broker/types.js";
+import type { AgentSessionSearchInfo, AgentSessionSearchOptions, AgentSessionSummary, PortLeaseAcquireInput, PortLeaseInfo, PortLeaseListOptions, PortLeaseReleaseInput, PortLeaseRenewInput, PinetLaneInfo, PinetLaneListOptions, PinetLaneParticipantInfo, PinetLaneParticipantUpsertInput, PinetLaneUpsertInput } from "./broker/types.js";
 export interface PinetToolsAgentRecord {
     emoji: string;
     name: string;
     id: string;
     pid?: number;
+    stableId?: string | null;
+    session?: AgentSessionSummary | null;
     status: "working" | "idle";
     metadata: Record<string, unknown> | null;
     lastHeartbeat: string;
@@ -76,6 +78,7 @@ export interface RegisterPinetToolsDeps {
     readPinetInbox: (options: PinetReadOptions) => Promise<PinetReadResult>;
     listBrokerAgents: () => PinetToolsAgentRecord[];
     listFollowerAgents: (includeGhosts: boolean) => Promise<PinetToolsAgentRecord[]>;
+    searchPinetSessions: (options: AgentSessionSearchOptions) => Promise<AgentSessionSearchInfo[]>;
     listSubtreeAgents?: (includeGhosts: boolean) => PinetToolsAgentRecord[] | null;
     getSubtreeSelfAgentId?: () => string | null;
     spawnSubtreeWorker?: (input: PinetSubtreeSpawnInput) => Promise<PinetSubtreeSpawnResult>;

package/dist/pinet-tools.js

@@ -8,11 +8,20 @@ import { buildAgentDisplayInfo, filterAgentsForMeshVisibility, formatAgentList,
 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 { 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" } }],
     read: [
+        // Routine inbox drain: defaults are `unread_only: true` + `mark_read: true`,
+        // so this returns and consumes only this agent's unread rows. The compact
+        // output already includes capped per-message previews; no `full=true` needed.
+        { action: "read", args: { limit: 20 } },
+        // Same defaults, scoped to one thread.
         { action: "read", args: { thread_id: "a2a:<broker>:<worker>", limit: 20 } },
-        { action: "read", args: { unread_only: false, mark_read: false, full: true } },
+        // Non-destructive latest-history peek (does NOT mark anything read or
+        // change unread state). Use only when you need to revisit recently-read
+        // context, not as a routine inbox read.
+        { action: "read", args: { unread_only: false, mark_read: false, limit: 5 } },
     ],
     free: [{ action: "free", args: { note: "Wrapped up <issue>" } }],
     snooze: [
@@ -21,6 +30,10 @@ const PINET_DISPATCHER_EXAMPLES = {
     ],
     schedule: [{ action: "schedule", args: { delay: "30m", message: "Check queue state" } }],
     agents: [{ action: "agents", args: { repo: "<repo>", role: "worker" } }],
+    sessions: [
+        { action: "sessions", args: { agent_name: "Frozen Hazel Whale" } },
+        { action: "sessions", args: { thread_id: "a2a:<broker>:<worker>", full: true } },
+    ],
     spawn: [
         {
             action: "spawn",
@@ -81,6 +94,7 @@ function normalizeDispatcherAction(value) {
         "snooze",
         "schedule",
         "agents",
+        "sessions",
         "lanes",
         "ports",
         "spawn",
@@ -129,7 +143,8 @@ function classifyPinetError(message) {
         message.includes("ttl_ms") ||
         message.includes("purpose") ||
         message.includes("port") ||
-        message.includes("spawn")) {
+        message.includes("spawn") ||
+        message.includes("sessions op")) {
         return {
             class: "input",
             message,
@@ -795,6 +810,8 @@ function buildCompactAgentDetails(agents, hint) {
                 repo: getAgentRepo(agent) ?? null,
                 branch: getAgentBranch(agent) ?? null,
                 role: getAgentRole(agent) ?? null,
+                session: agent.session?.ref ?? null,
+                sessionKind: agent.session?.kind ?? null,
                 brokerManaged: agent.metadata?.brokerManaged === true,
                 parentAgentId: agent.metadata?.parentAgentId ?? null,
                 treeDepth: agent.metadata?.treeDepth ?? 0,
@@ -1355,6 +1372,123 @@ function runPinetAgentsAction(params, deps, toolName, output) {
         };
     })();
 }
+function buildPinetSessionSearchOptions(params) {
+    return {
+        ...((getMaybeString(params, "agent_name") ?? getMaybeString(params, "name"))
+            ? { agentName: getMaybeString(params, "agent_name") ?? getMaybeString(params, "name") }
+            : {}),
+        ...(getMaybeString(params, "agent_id") ? { agentId: getMaybeString(params, "agent_id") } : {}),
+        ...(getMaybeString(params, "thread_id")
+            ? { threadId: getMaybeString(params, "thread_id") }
+            : {}),
+        ...(getMaybeString(params, "repo") ? { repo: getMaybeString(params, "repo") } : {}),
+        ...(getMaybeString(params, "worktree_path")
+            ? { worktreePath: getMaybeString(params, "worktree_path") }
+            : {}),
+        ...(getMaybeString(params, "tmux_session")
+            ? { tmuxSession: getMaybeString(params, "tmux_session") }
+            : {}),
+        ...(getMaybeString(params, "since") ? { since: getMaybeString(params, "since") } : {}),
+        ...(getMaybeString(params, "until") ? { until: getMaybeString(params, "until") } : {}),
+        ...(getMaybeNumber(params, "limit") ? { limit: getMaybeNumber(params, "limit") } : {}),
+    };
+}
+function formatPinetSessionSearchHeader(sessions, options) {
+    const filters = [
+        options.agentName ? `agent_name=${options.agentName}` : null,
+        options.agentId ? `agent_id=${options.agentId}` : null,
+        options.threadId ? `thread_id=${options.threadId}` : null,
+        options.repo ? `repo=${options.repo}` : null,
+        options.worktreePath ? `worktree=${options.worktreePath}` : null,
+        options.tmuxSession ? `tmux=${options.tmuxSession}` : null,
+        options.since ? `since=${options.since}` : null,
+        options.until ? `until=${options.until}` : null,
+    ].filter((item) => Boolean(item));
+    const filterText = filters.length > 0 ? ` for ${filters.join(" · ")}` : "";
+    return `Pinet sessions: ${sessions.length} match${sessions.length === 1 ? "" : "es"}${filterText}.`;
+}
+function formatPinetSessionLine(session, full) {
+    const summary = summarizePinetStableId(session.stableId);
+    const health = session.disconnectedAt ? "disconnected" : "live";
+    const where = [
+        session.repo ?? null,
+        session.branch ? `branch=${session.branch}` : null,
+        session.tmuxSession ? `tmux=${session.tmuxSession}` : null,
+    ].filter((item) => Boolean(item));
+    const threads = session.relatedThreadIds.slice(0, full ? 10 : 3).join(", ");
+    const suffix = session.relatedThreadIds.length > (full ? 10 : 3) ? " …" : "";
+    const base = [
+        `- ${session.emoji} ${session.agentName} (${session.agentId})`,
+        `${health}`,
+        `pid:${session.pid}`,
+        summary?.ref ? `session:${summary.ref}` : "session:none",
+        `lastSeen:${session.lastSeen}`,
+        where.length > 0 ? where.join(" · ") : null,
+    ].filter((item) => Boolean(item));
+    const lines = [base.join(" — ")];
+    if (threads) {
+        lines.push(`  threads: ${threads}${suffix}`);
+    }
+    if (full) {
+        const sessionPath = getPinetSessionPath(session.stableId);
+        const sessionFilename = getPinetSessionFilename(session.stableId);
+        if (session.stableId)
+            lines.push(`  stableId: ${session.stableId}`);
+        if (sessionPath)
+            lines.push(`  jsonl: ${sessionPath}`);
+        if (sessionFilename)
+            lines.push(`  jsonlFile: ${sessionFilename}`);
+        if (session.cwd)
+            lines.push(`  cwd: ${session.cwd}`);
+        if (session.repoRoot)
+            lines.push(`  repoRoot: ${session.repoRoot}`);
+        if (session.worktreePath)
+            lines.push(`  worktreePath: ${session.worktreePath}`);
+        if (session.brokerManaged) {
+            lines.push(`  managed: source=${session.launchSource ?? "broker"}${session.brokerManagedBy ? ` by=${session.brokerManagedBy}` : ""}`);
+        }
+        lines.push(`  matchedBy: ${session.matchedBy.join(", ")}`);
+    }
+    return lines.join("\n");
+}
+function formatPinetSessionSearch(sessions, options, full) {
+    const header = formatPinetSessionSearchHeader(sessions, options);
+    if (sessions.length === 0)
+        return `${header} Try a broader agent_name, thread_id, or repo filter.`;
+    const body = sessions.map((session) => formatPinetSessionLine(session, full)).join("\n");
+    const fullHint = full ? "" : "\nUse args.full=true for exact stableId/jsonl paths.";
+    return `${header}\n${body}${fullHint}`;
+}
+function runPinetSessionsAction(params, deps, toolName, output) {
+    return (async () => {
+        const op = getMaybeString(params, "op") ?? "search";
+        if (op !== "search") {
+            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}`);
+        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);
+        return {
+            content: [{ type: "text", text }],
+            details: { count: sessions.length, sessions, options },
+            compactDetails: {
+                count: sessions.length,
+                options,
+                sessions: sessions.map(buildPinetSessionCompactDetails),
+            },
+            fullDetails: {
+                count: sessions.length,
+                options,
+                sessions: sessions.map(buildPinetSessionFullDetails),
+            },
+            expandedText: text,
+        };
+    })();
+}
 export function registerPinetTools(pi, deps) {
     const actionDefinitions = new Map();
     function registerAction(definition) {
@@ -1377,7 +1511,7 @@ export function registerPinetTools(pi, deps) {
     });
     registerAction({
         name: "read",
-        description: "Read this agent's durable SQLite-backed Pinet inbox context with unread/read semantics. Ordinary workers only see rows addressed to their own agent identity; broker coordination visibility is limited to broker-addressed inbox rows.",
+        description: "Read this agent's durable SQLite-backed Pinet inbox context with unread/read semantics. Defaults to draining unread rows (`unread_only: true`, `mark_read: true`) with compact per-message previews — no `full=true` required for routine reads. Override `unread_only`/`mark_read` only for a non-destructive latest-history peek. Ordinary workers only see rows addressed to their own agent identity; broker coordination visibility is limited to broker-addressed inbox rows.",
         parameters: Type.Object({
             thread_id: Type.Optional(Type.String({
                 description: "Optional Pinet/Slack broker thread ID to filter this agent's own inbox rows; it does not grant cross-agent thread access.",
@@ -1470,6 +1604,25 @@ export function registerPinetTools(pi, deps) {
         }),
         execute: (_id, params, output) => runPinetAgentsAction(params, deps, "pinet:agents", output),
     });
+    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.",
+        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" })),
+            name: Type.Optional(Type.String({ description: "Alias for agent_name" })),
+            agent_id: Type.Optional(Type.String({ description: "Pinet agent id or id prefix" })),
+            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" })),
+            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" })),
+            limit: Type.Optional(Type.Number({ description: "Maximum matches (default 20, max 100)" })),
+            ...PINET_OUTPUT_OPTION_PARAMETERS,
+        }),
+        execute: (_id, params, output) => runPinetSessionsAction(params, deps, "pinet:sessions", output),
+    });
     registerAction({
         name: "ports",
         description: "Acquire, renew, release, inspect, list, or expire durable Pinet local port leases.",
@@ -1541,10 +1694,10 @@ export function registerPinetTools(pi, deps) {
         name: "pinet",
         label: "Pinet Dispatcher",
         description: "Dispatch Pinet operations by action with compact help and schema discovery.",
-        promptSnippet: 'Use this compact dispatcher for Pinet actions: send, read, free, snooze, schedule, agents, lanes, ports, reload, exit, 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, spawn, and help. Use /pinet start, /pinet follow, /pinet unfollow, and /pinet subtree start for TUI lifecycle changes. Defaults to terse CLI text; pass args.format="json" for the compact envelope or args.full=true for verbose/debug detail.',
         parameters: Type.Object({
             action: Type.String({
-                description: "Action name: help, send, read, free, snooze, schedule, agents, lanes, ports, reload, or exit. Also supports spawn for launching worker-owned subtree children.",
+                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.",
             }),
             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.',

package/dist/slack-markdown.d.ts

@@ -0,0 +1 @@
+export declare function renderMarkdownForSlackMrkdwn(text: string): string;

package/dist/slack-markdown.js

@@ -0,0 +1,128 @@
+export function renderMarkdownForSlackMrkdwn(text) {
+    if (!text.includes("**")) {
+        return text;
+    }
+    return transformOutsideBacktickCode(text, convertMarkdownStrongToSlackBold);
+}
+function transformOutsideBacktickCode(text, transform) {
+    let output = "";
+    let segmentStart = 0;
+    let index = 0;
+    while (index < text.length) {
+        if (text[index] !== "`") {
+            index += 1;
+            continue;
+        }
+        const runLength = countRepeated(text, index, "`");
+        const closingIndex = findClosingBacktickRun(text, index + runLength, runLength);
+        if (closingIndex === -1) {
+            index += runLength;
+            continue;
+        }
+        output += transform(text.slice(segmentStart, index));
+        output += text.slice(index, closingIndex + runLength);
+        index = closingIndex + runLength;
+        segmentStart = index;
+    }
+    output += transform(text.slice(segmentStart));
+    return output;
+}
+function convertMarkdownStrongToSlackBold(segment) {
+    let output = "";
+    let index = 0;
+    while (index < segment.length) {
+        if (segment.startsWith("**", index) && isStrongOpeningDelimiter(segment, index)) {
+            const closingIndex = findStrongClosingDelimiter(segment, index + 2);
+            if (closingIndex !== -1) {
+                output += `*${segment.slice(index + 2, closingIndex)}*`;
+                index = closingIndex + 2;
+                continue;
+            }
+        }
+        output += segment[index];
+        index += 1;
+    }
+    return output;
+}
+function findStrongClosingDelimiter(segment, fromIndex) {
+    let index = fromIndex;
+    while (index < segment.length) {
+        const next = segment.indexOf("**", index);
+        if (next === -1) {
+            return -1;
+        }
+        if (isStrongClosingDelimiter(segment, next)) {
+            return next;
+        }
+        index = next + 2;
+    }
+    return -1;
+}
+function isStrongOpeningDelimiter(text, index) {
+    if (isEscaped(text, index)) {
+        return false;
+    }
+    const previous = text[index - 1];
+    const next = text[index + 2];
+    return isSafeOpeningBoundary(previous, next);
+}
+function isStrongClosingDelimiter(text, index) {
+    if (isEscaped(text, index)) {
+        return false;
+    }
+    const previous = text[index - 1];
+    const next = text[index + 2];
+    return isSafeClosingBoundary(previous, next);
+}
+function isSafeOpeningBoundary(previous, next) {
+    if (!next || isWhitespace(next) || next === "*" || next === "/") {
+        return false;
+    }
+    if (previous === "*" || previous === "/") {
+        return false;
+    }
+    return true;
+}
+function isSafeClosingBoundary(previous, next) {
+    if (!previous || isWhitespace(previous) || previous === "*" || previous === "/") {
+        return false;
+    }
+    if (next === "*" || next === "/") {
+        return false;
+    }
+    return true;
+}
+function isWhitespace(value) {
+    return /\s/u.test(value);
+}
+function countRepeated(text, index, char) {
+    let count = 0;
+    while (text[index + count] === char) {
+        count += 1;
+    }
+    return count;
+}
+function findClosingBacktickRun(text, fromIndex, runLength) {
+    let index = fromIndex;
+    while (index < text.length) {
+        const next = text.indexOf("`", index);
+        if (next === -1) {
+            return -1;
+        }
+        const nextRunLength = countRepeated(text, next, "`");
+        if (nextRunLength === runLength) {
+            return next;
+        }
+        index = next + nextRunLength;
+    }
+    return -1;
+}
+function isEscaped(text, index) {
+    let slashCount = 0;
+    let cursor = index - 1;
+    while (cursor >= 0 && text[cursor] === "\\") {
+        slashCount += 1;
+        cursor -= 1;
+    }
+    return slashCount % 2 === 1;
+}

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

@@ -61,6 +61,7 @@ export function createSlackPinetRuntimeAdapterFactory(deps) {
             appToken: deps.getAppToken(),
             allowedUsers: allowedUsers ? [...allowedUsers] : undefined,
             allowAllWorkspaceUsers: deps.shouldAllowAllWorkspaceUsers(),
+            ingressGuard: settings.ingressGuard,
             suggestedPrompts: settings.suggestedPrompts,
             reactionCommands: settings.reactionCommands,
             isKnownThread: (threadTs) => shouldRouteKnownSlackThread(broker.db.getThread(threadTs)),
@@ -69,6 +70,12 @@ export function createSlackPinetRuntimeAdapterFactory(deps) {
                 rememberKnownSlackThread(broker, threadTs, channelId, context);
             },
             isReactionThreadAuthorized: (threadTs, channelId) => isAuthorizedReactionThread(broker, threadTs, channelId),
+            isPinetOwnedThread: (threadTs, channelId) => {
+                const thread = broker.db.getThread(threadTs);
+                if (!thread || thread.source !== "slack" || thread.channel !== channelId)
+                    return false;
+                return !!thread.ownerAgent || readStoredSlackThreadContext(thread.metadata) !== null;
+            },
             onAppHomeOpened: async ({ userId }) => {
                 await deps.onAppHomeOpened(userId, ctx);
             },

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

@@ -1,4 +1,5 @@
 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";
 export interface SubtreeBrokerPaths {
@@ -32,6 +33,8 @@ export interface SubtreeAgentRecord {
     name: string;
     id: string;
     pid?: number;
+    stableId?: string | null;
+    session?: AgentSessionSummary | null;
     status: "working" | "idle";
     metadata: Record<string, unknown> | null;
     lastHeartbeat: string;

package/dist/subtree-broker-runtime.js

@@ -4,6 +4,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
+import { summarizePinetStableId } from "./pinet-session-formatting.js";
 import { dispatchDirectAgentMessage, resolveDirectAgentTarget } from "./broker/agent-messaging.js";
 import { startBroker } from "./broker/index.js";
 import { HEARTBEAT_INTERVAL_MS } from "./broker/client.js";
@@ -174,6 +175,8 @@ function toSubtreeAgentRecord(db, agent) {
         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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pinet/slack-bridge",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "type": "module",
   "description": "Pi package for Pinet Slack assistant integration — multi-agent broker, thread routing, and inbox tools",
   "author": "Will Porcellini <5994936+gugu91@users.noreply.github.com>",
@@ -49,10 +49,10 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@pinet/broker-core": "0.2.0",
-    "@pinet/imessage-bridge": "0.2.0",
-    "@pinet/pinet-core": "0.2.0",
-    "@pinet/transport-core": "0.2.0",
+    "@pinet/broker-core": "0.2.2",
+    "@pinet/imessage-bridge": "0.2.2",
+    "@pinet/pinet-core": "0.2.2",
+    "@pinet/transport-core": "0.2.2",
     "@sinclair/typebox": "^0.34.49"
   },
   "types": "./dist/index.d.ts",