@pinet/slack-bridge 0.1.2 → 0.2.1

package/dist/prompts/broker/tmux.md

@@ -24,7 +24,7 @@ FRESH TMUX WORKERS: On the Mac mini, launch a fresh tmux-backed Pinet follower w
 
 WORKER GRACE PERIOD: After a worker reports completion, keep the same Pi instance available for a one-hour grace period before spinning it down. During that window, route follow-up, review-fix, or clarification work back to the same instance whenever possible so context and thread ownership remain stable. Do not assign unrelated new work to a grace-reserved worker unless the maintainer explicitly prioritizes reuse over follow-up stability. After the grace period, ask an idle, healthy, broker-managed worker to confirm it is free, then ask it to `/pinet exit` or use `pinet action=exit` only when available Pinet agent/lane/status signals and/or the worker response show no pending inbox/thread ownership and no active lane assignment. If any required signal is unavailable or ambiguous, fail closed: report the worker as a cleanup candidate instead of exiting or closing tmux. After the worker exits, close only the broker-managed tmux session recorded for that lane when it is still present. If it does not exit cleanly, let conservative broker-managed ghost reaping handle the verified process rather than killing unmarked local PIDs.
 
-WORKER CAP AND TMUX HYGIENE: Keep broker-managed tmux capacity bounded by pruning, not by recycling old context into new lanes. Start at most one fresh worker per new lane unless the maintainer asks for fan-out, and flag multiple idle broker-managed workers past their grace windows as cleanup candidates. Broker-created tmux session names must be lane/repo-scoped and recorded in lane metadata; do not leave anonymous private-socket sessions that operators cannot map back to a lane.
+WORKER CAP AND TMUX HYGIENE: Keep broker-managed tmux capacity bounded by pruning, not by recycling old context into new lanes. Start at most one fresh worker per new lane unless the maintainer asks for fan-out, and flag multiple idle broker-managed workers past their grace windows as cleanup candidates. If multiple worker identities report the same broker-managed tmux session, repo/worktree, or lane, treat it as an immediate duplicate-owner anomaly: stop routing new work to the duplicates, choose the canonical live worker from the tmux pane/current PID and lane metadata, ask non-canonical idle workers to `/pinet exit` once they have no pending inbox/thread ownership/active lane, and report ambiguous or private-socket cases instead of guessing. Broker-created tmux session names must be lane/repo-scoped and recorded in lane metadata; do not leave anonymous private-socket sessions that operators cannot map back to a lane.
 
 THREAD OWNERSHIP AND REPORTING: Slack thread ownership is first-responder-wins. If direct Slack posting is blocked because another agent owns the thread, report through the Pinet/broker channel for relay instead of trying alternate Slack channel posts. When delegating, tell workers exactly where to report progress and final outcomes; if a worker cannot post to Slack, require it to report back to the broker for relay.
 
@@ -46,4 +46,4 @@ Clean up worktrees after PRs merge: `git worktree remove .worktrees/<name>`. Fla
 
 GITHUB AND SECRET HANDLING: Use the repo's documented GitHub authentication path when filing issues, creating PRs, or merging. Never echo tokens, mesh secrets, private prompt contents, local absolute secret paths, or credential material into Slack, Pinet, issues, PRs, logs, or diagnostics. Prefer high-level auth/secret status such as "auth unavailable" or "secret configured" without revealing values.
 
-RALPH LOOP: Run autonomous maintenance every cycle unless RALPH snooze is active for empty/no-work cycles. Don't wait to be asked when work, anomalies, blockers, or human-triggered messages appear; snooze must not hide active work. Proactively: (1) REAP — ping idle agents, keep completed workers in their one-hour grace window, then ask grace-expired healthy broker-managed workers to exit only after inspectable Pinet signals or the worker's own response confirm they have no pending inbox/thread ownership or active lane assignment; report ambiguous cases as cleanup candidates instead of guessing. (2) NUDGE — check assigned work, poll branches for commits, escalate stalled agents. (3) REASSIGN — if an assigned lane worker is dead, start a fresh repo-scoped tmux worker for that lane unless the maintainer explicitly asked to reuse another worker. (4) DRAIN — assign queued tasks to fresh lane-scoped tmux workers; do not recycle unrelated idle workers as a shortcut. (5) TMUX HYGIENE — inspect lane metadata for broker-managed tmux sessions, close sessions whose worker exited after grace, and report orphaned/private sessions that cannot be mapped safely instead of killing blindly. (6) SNOOZE — after repeated empty cycles, use `/pinet snooze` or `pinet action=snooze` only for non-urgent quiet time; wake/route normally when new work or anomalies appear. (7) SELF-REPAIR — verify main is on `main`, check mesh health, report anomalies.
+RALPH LOOP: Run autonomous maintenance every cycle unless RALPH snooze is active for empty/no-work cycles. Don't wait to be asked when work, anomalies, blockers, or human-triggered messages appear; snooze must not hide active work. Proactively: (1) REAP — ping idle agents, keep completed workers in their one-hour grace window, then ask grace-expired healthy broker-managed workers to exit only after inspectable Pinet signals or the worker's own response confirm they have no pending inbox/thread ownership or active lane assignment; report ambiguous cases as cleanup candidates instead of guessing. (2) NUDGE — check assigned work, poll branches for commits, escalate stalled agents. (3) REASSIGN — if an assigned lane worker is dead, start a fresh repo-scoped tmux worker for that lane unless the maintainer explicitly asked to reuse another worker. (4) DRAIN — assign queued tasks to fresh lane-scoped tmux workers; do not recycle unrelated idle workers as a shortcut. (5) TMUX HYGIENE — inspect lane metadata for broker-managed tmux sessions every cycle; resolve duplicate owners immediately, close sessions whose worker exited after grace, and report orphaned/private sessions that cannot be mapped safely instead of killing blindly. (6) SNOOZE — after repeated empty cycles, use `/pinet snooze` or `pinet action=snooze` only for non-urgent quiet time; wake/route normally when new work or anomalies appear. (7) SELF-REPAIR — verify main is on `main`, check mesh health, report anomalies.

package/dist/reaction-triggers.d.ts

@@ -7,6 +7,7 @@ export type ReactionCommandSetting = string | {
     prompt?: string;
 };
 export type ReactionCommandSettings = Record<string, ReactionCommandSetting>;
+export declare const REACTION_COMMAND_PRESETS: Record<string, ReactionCommandTemplate>;
 export declare const DEFAULT_REACTION_COMMANDS: Record<string, ReactionCommandTemplate>;
 export declare function normalizeReactionName(input: string): string;
 export declare function resolveReactionCommands(settings: ReactionCommandSettings | undefined): Map<string, ReactionCommandTemplate>;

package/dist/reaction-triggers.js

@@ -35,7 +35,7 @@ const REACTION_DISPLAY = {
     arrow_up: "⬆️",
     octagonal_sign: "🛑",
 };
-export const DEFAULT_REACTION_COMMANDS = {
+export const REACTION_COMMAND_PRESETS = {
     memo: {
         action: "summarize",
         prompt: "Summarize the reacted-to message and the surrounding thread. Focus on key decisions, action items, and open questions.",
@@ -77,6 +77,10 @@ export const DEFAULT_REACTION_COMMANDS = {
         prompt: "If the reacted message contains a URL, fetch the linked page and summarize the important information for the user.",
     },
 };
+// Slack emoji reactions are deliberately no-op by default. Operators must opt in
+// per reaction through settings.reactionCommands before any reaction can enqueue
+// Pinet work, steering, reviews, or interrupt controls.
+export const DEFAULT_REACTION_COMMANDS = {};
 function normalizeReactionNameOrNull(input) {
     const trimmed = input.trim();
     if (!trimmed)
@@ -96,25 +100,25 @@ export function normalizeReactionName(input) {
 function buildDefaultPromptForAction(action) {
     switch (action) {
         case "summarize":
-            return DEFAULT_REACTION_COMMANDS.memo.prompt;
+            return REACTION_COMMAND_PRESETS.memo.prompt;
         case "file-issue":
-            return DEFAULT_REACTION_COMMANDS.bug.prompt;
+            return REACTION_COMMAND_PRESETS.bug.prompt;
         case "review":
-            return DEFAULT_REACTION_COMMANDS.eyes.prompt;
+            return REACTION_COMMAND_PRESETS.eyes.prompt;
         case "approve":
-            return DEFAULT_REACTION_COMMANDS.white_check_mark.prompt;
+            return REACTION_COMMAND_PRESETS.white_check_mark.prompt;
         case "retry":
-            return DEFAULT_REACTION_COMMANDS.repeat.prompt;
+            return REACTION_COMMAND_PRESETS.repeat.prompt;
         case "steer":
-            return DEFAULT_REACTION_COMMANDS.arrow_up.prompt;
+            return REACTION_COMMAND_PRESETS.arrow_up.prompt;
         case "interrupt":
-            return DEFAULT_REACTION_COMMANDS.octagonal_sign.prompt;
+            return REACTION_COMMAND_PRESETS.octagonal_sign.prompt;
         case "search":
-            return DEFAULT_REACTION_COMMANDS.mag.prompt;
+            return REACTION_COMMAND_PRESETS.mag.prompt;
         case "track":
-            return DEFAULT_REACTION_COMMANDS.pushpin.prompt;
+            return REACTION_COMMAND_PRESETS.pushpin.prompt;
         case "fetch-url":
-            return DEFAULT_REACTION_COMMANDS.globe_with_meridians.prompt;
+            return REACTION_COMMAND_PRESETS.globe_with_meridians.prompt;
         default:
             return `Carry out the "${action}" action for the reacted Slack message or thread, using the included context before you decide what to do.`;
     }
@@ -137,8 +141,15 @@ export function resolveReactionCommands(settings) {
         }
         if (!config || typeof config !== "object")
             continue;
-        const action = config.action?.trim() || resolved.get(normalizedReaction)?.action || normalizedReaction;
-        const prompt = config.prompt?.trim() || buildDefaultPromptForAction(action);
+        const preset = REACTION_COMMAND_PRESETS[normalizedReaction];
+        const configuredAction = config.action?.trim();
+        const action = configuredAction ||
+            resolved.get(normalizedReaction)?.action ||
+            preset?.action ||
+            normalizedReaction;
+        const prompt = config.prompt?.trim() ||
+            (configuredAction ? buildDefaultPromptForAction(action) : preset?.prompt) ||
+            buildDefaultPromptForAction(action);
         resolved.set(normalizedReaction, { action, prompt });
     }
     return resolved;
@@ -165,7 +176,7 @@ export function buildReactionTriggerMessage(input) {
 }
 export function buildReactionPromptGuidelines() {
     return [
-        "Reaction-triggered requests may appear in your Slack inbox as structured 'Reaction trigger from Slack:' messages.",
-        "Treat them as explicit user requests keyed off emoji reactions. Use the included action, reacted message text, and thread context to decide what to do.",
+        "Slack emoji reactions are ignored by default and should not be treated as work unless the extension has already delivered an explicit structured 'Reaction trigger from Slack:' inbox message from an authorized Pinet thread.",
+        "If such an opt-in reaction-triggered request appears, treat it as an explicit user instruction tied to the referenced Slack message or thread; never infer work from a plain emoji reaction alone or from reactions in ordinary uninvoked Slack threads.",
     ];
 }

package/dist/runtime-agent-context.js

@@ -214,6 +214,7 @@ export function createRuntimeAgentContext(deps) {
         ];
         const skinAssignment = resolveSkinAssignment(role, getIdentitySeedForRole(role));
         const brokerManaged = role === "worker" && process.env.PINET_BROKER_MANAGED === "1";
+        const parentAgentId = process.env.PINET_PARENT_AGENT_ID?.trim() || undefined;
         const brokerManagedMetadata = brokerManaged
             ? {
                 brokerManaged: true,
@@ -221,6 +222,24 @@ export function createRuntimeAgentContext(deps) {
                 launchSource: process.env.PINET_LAUNCH_SOURCE?.trim() || "broker-tmux",
                 tmuxSession: process.env.PINET_TMUX_SESSION?.trim() || undefined,
                 brokerManagedAt: new Date().toISOString(),
+                ...(parentAgentId ? { parentAgentId, pinetParentAgentId: parentAgentId } : {}),
+                ...(process.env.PINET_ROOT_AGENT_ID?.trim()
+                    ? { rootAgentId: process.env.PINET_ROOT_AGENT_ID.trim() }
+                    : {}),
+                ...(process.env.PINET_SPAWNED_BY_AGENT_ID?.trim()
+                    ? { spawnedByAgentId: process.env.PINET_SPAWNED_BY_AGENT_ID.trim() }
+                    : parentAgentId
+                        ? { spawnedByAgentId: parentAgentId }
+                        : {}),
+                ...(process.env.PINET_LAUNCH_ID?.trim()
+                    ? { launchId: process.env.PINET_LAUNCH_ID.trim() }
+                    : {}),
+                ...(process.env.PINET_SUBTREE_ROLE?.trim()
+                    ? { subtreeRole: process.env.PINET_SUBTREE_ROLE.trim() }
+                    : {}),
+                ...(process.env.PINET_LANE_ID?.trim()
+                    ? { laneId: process.env.PINET_LANE_ID.trim() }
+                    : {}),
             }
             : {};
         return {

package/dist/runtime-mode.js

@@ -12,7 +12,13 @@ export function isPinetRuntimeMode(mode) {
     return mode === "broker" || mode === "follower";
 }
 export function isBrokerManagedFollowerLaunch(env = process.env) {
-    return env.PINET_BROKER_MANAGED === "1" && env.PINET_LAUNCH_SOURCE === "broker-tmux";
+    if (env.PINET_BROKER_MANAGED !== "1")
+        return false;
+    if (env.PINET_LAUNCH_SOURCE === "broker-tmux")
+        return true;
+    if (env.PINET_LAUNCH_SOURCE === "subtree-broker-tmux")
+        return true;
+    return Boolean(env.PINET_SOCKET_PATH?.trim());
 }
 export function resolveSlackBridgeStartupRuntimeMode(settings, options = {}) {
     const explicitMode = normalizeSlackBridgeRuntimeMode(settings.runtimeMode);

package/dist/single-player-runtime.js

@@ -166,23 +166,13 @@ export function createSinglePlayerRuntime(deps) {
         try {
             const isInterruptReaction = command.action === "interrupt";
             const reactedMessage = await deps.fetchSlackMessageByTs(item.channel, item.ts);
-            if (!reactedMessage) {
-                const reason = isInterruptReaction
-                    ? "identify Slack thread for interrupt reaction"
-                    : "fetch reacted message";
-                throw new Error(`Unable to ${reason} ${item.ts} in channel ${item.channel}`);
-            }
             const threadTs = reactedMessage?.thread_ts ??
                 reactedMessage?.ts ??
                 item.ts;
             const threads = deps.getThreads();
-            if (!threads.has(threadTs)) {
-                threads.set(threadTs, {
-                    channelId: item.channel,
-                    threadTs,
-                    userId: reactedMessage?.user ?? user,
-                    source: "slack",
-                });
+            const threadInfo = threads.get(threadTs);
+            if (!threadInfo || threadInfo.channelId !== item.channel) {
+                return;
             }
             const ownership = await ensureLocalThreadOwnership(item.channel, threadTs);
             if (ownership !== "continue") {
@@ -209,7 +199,9 @@ export function createSinglePlayerRuntime(deps) {
                 return;
             const reactedMessageText = typeof reactedMessage?.text === "string" && reactedMessage.text.trim().length > 0
                 ? reactedMessage.text
-                : "(no text)";
+                : reactedMessage
+                    ? "(no text)"
+                    : "(message text unavailable; Slack did not return the reacted message, so use the channel/thread/message ids for context)";
             const reactionMessage = buildReactionTriggerMessage({
                 reactionName,
                 command,
@@ -221,7 +213,6 @@ export function createSinglePlayerRuntime(deps) {
                 reactedMessageAuthor,
             });
             ctx.ui.notify(`${reactorName} reacted with :${reactionName}:`, "info");
-            const threadInfo = threads.get(threadTs);
             deps.pushInboxMessage({
                 channel: item.channel,
                 threadTs,
@@ -251,9 +242,6 @@ export function createSinglePlayerRuntime(deps) {
         if (!classified.relevant)
             return;
         const { threadTs, channel, userId, text, isDM, isChannelMention, messageTs, metadata } = classified;
-        if (!threads.has(threadTs)) {
-            threads.set(threadTs, { channelId: channel, threadTs, userId, source: "slack" });
-        }
         const ownership = await ensureLocalThreadOwnership(channel, threadTs);
         if (ownership !== "continue") {
             return;
@@ -266,6 +254,12 @@ export function createSinglePlayerRuntime(deps) {
             });
             return;
         }
+        // Track the thread only after the allowlist gate so unauthorized traffic
+        // cannot mint known-thread state that later admits replies or opt-in
+        // reaction commands (#812).
+        if (!threads.has(threadTs)) {
+            threads.set(threadTs, { channelId: channel, threadTs, userId, source: "slack" });
+        }
         if (isDM) {
             deps.setLastDmChannel(channel);
         }
@@ -304,14 +298,6 @@ export function createSinglePlayerRuntime(deps) {
     }
     async function queueInteractiveInboxEvent(normalized, ctx) {
         const threads = deps.getThreads();
-        if (!threads.has(normalized.threadTs)) {
-            threads.set(normalized.threadTs, {
-                channelId: normalized.channel,
-                threadTs: normalized.threadTs,
-                userId: normalized.userId,
-                source: "slack",
-            });
-        }
         const ownership = await ensureLocalThreadOwnership(normalized.channel, normalized.threadTs);
         if (ownership !== "continue") {
             return;
@@ -324,6 +310,16 @@ export function createSinglePlayerRuntime(deps) {
             });
             return;
         }
+        // Track the thread only after the allowlist gate so unauthorized
+        // interactive events cannot mint known-thread state (#812).
+        if (!threads.has(normalized.threadTs)) {
+            threads.set(normalized.threadTs, {
+                channelId: normalized.channel,
+                threadTs: normalized.threadTs,
+                userId: normalized.userId,
+                source: "slack",
+            });
+        }
         if (normalized.channel.startsWith("D")) {
             deps.setLastDmChannel(normalized.channel);
         }

package/dist/slack-access.d.ts

@@ -22,12 +22,22 @@ export declare function buildSlackThreadRuntimeScope(input: {
     channelId?: string | null;
     context?: SlackThreadContext | null;
 }): RuntimeScopeCarrier;
+export interface ParsedSlashCommand {
+    command: string;
+    text: string;
+    channelId: string;
+    userId: string;
+    responseUrl?: string;
+    triggerId?: string;
+    teamId?: string;
+}
 export interface ParsedEnvelope {
     envelopeId?: string;
     type: string;
     dedupKey?: string;
     event?: Record<string, unknown>;
     interactivePayload?: Record<string, unknown>;
+    slashCommand?: ParsedSlashCommand;
 }
 export declare function isSlackUserAllowed(allowlist: Set<string> | null, userId: string): boolean;
 /**
@@ -168,6 +178,7 @@ export interface SlackSocketModeClientConfig {
     }) => Promise<void> | void;
     onAppHomeOpened?: (event: ParsedAppHomeOpened) => Promise<void> | void;
     onInteractive?: (event: SlackInteractiveInboxEvent) => Promise<void> | void;
+    onSlashCommand?: (event: ParsedSlashCommand) => Promise<void> | void;
 }
 export declare class SlackSocketModeClient {
     private readonly config;

package/dist/slack-access.js

@@ -50,12 +50,38 @@ export function parseSocketFrame(raw) {
         if (interactivePayload) {
             result.interactivePayload = interactivePayload;
         }
+        if (data.type === "slash_commands") {
+            const slashCommand = extractSlackSlashCommandPayload(data.payload);
+            if (slashCommand) {
+                result.slashCommand = slashCommand;
+            }
+        }
         return result;
     }
     catch {
         return null;
     }
 }
+function extractSlackSlashCommandPayload(payload) {
+    if (typeof payload !== "object" || payload === null || Array.isArray(payload))
+        return null;
+    const record = payload;
+    const command = typeof record.command === "string" ? record.command.trim() : "";
+    const text = typeof record.text === "string" ? record.text : "";
+    const channelId = typeof record.channel_id === "string" ? record.channel_id : "";
+    const userId = typeof record.user_id === "string" ? record.user_id : "";
+    if (!command || !channelId || !userId)
+        return null;
+    return {
+        command,
+        text,
+        channelId,
+        userId,
+        ...(typeof record.response_url === "string" ? { responseUrl: record.response_url } : {}),
+        ...(typeof record.trigger_id === "string" ? { triggerId: record.trigger_id } : {}),
+        ...(typeof record.team_id === "string" ? { teamId: record.team_id } : {}),
+    };
+}
 /**
  * Extract thread info from an assistant_thread_started event.
  */
@@ -402,6 +428,10 @@ export class SlackSocketModeClient {
                 }
                 return;
             }
+            if (envelope.slashCommand) {
+                await this.config.onSlashCommand?.(envelope.slashCommand);
+                return;
+            }
             if (!envelope.event)
                 return;
             const evt = envelope.event;

package/dist/slack-agents-command.d.ts

@@ -0,0 +1,19 @@
+import type { BrokerControlPlaneDashboardSnapshot } from "./broker/control-plane-dashboard.js";
+export interface SlackAgentCommandSettings {
+    skinTheme?: string | null;
+    slackCommandName?: string | null;
+    slackCommandNames?: string[] | null;
+}
+export interface SlackAgentsCommandInput {
+    command: string;
+    text: string;
+    channelId: string;
+    userId: string;
+}
+export declare function normalizeSlackCommandName(value: string | null | undefined): string | null;
+export declare function resolveSlackAgentCommandNames(settings: SlackAgentCommandSettings, activeSkinTheme?: string | null): string[];
+export declare function formatSlackAgentsUsage(commandNames: string[]): string;
+export declare function isSlackAgentCommand(command: string, commandNames: string[]): boolean;
+export declare function isSlackAgentsListCommand(command: string, text: string, commandNames: string[]): boolean;
+export declare function shouldIncludeSlackAgentsGhosts(text: string): boolean;
+export declare function formatSlackAgentsDashboard(snapshot: BrokerControlPlaneDashboardSnapshot, includeGhosts: boolean): string;

package/dist/slack-agents-command.js

@@ -0,0 +1,90 @@
+const DEFAULT_SLACK_COMMAND_NAME = "/pinet";
+const OATHGATE_SLACK_COMMAND_NAME = "/oathgate";
+export function normalizeSlackCommandName(value) {
+    const trimmed = value?.trim().toLowerCase();
+    if (!trimmed)
+        return null;
+    const command = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+    return /^\/[a-z0-9_-]+$/.test(command) ? command : null;
+}
+function defaultSlackCommandNameForSkin(skinTheme) {
+    const normalized = skinTheme?.trim().toLowerCase();
+    if (normalized === "oathgate" || normalized === "cosmere" || normalized === "cosmere-inspired") {
+        return OATHGATE_SLACK_COMMAND_NAME;
+    }
+    return DEFAULT_SLACK_COMMAND_NAME;
+}
+export function resolveSlackAgentCommandNames(settings, activeSkinTheme) {
+    const configured = [
+        ...(settings.slackCommandName ? [settings.slackCommandName] : []),
+        ...(Array.isArray(settings.slackCommandNames) ? settings.slackCommandNames : []),
+    ]
+        .map(normalizeSlackCommandName)
+        .filter((command) => command !== null);
+    const names = configured.length > 0
+        ? configured
+        : [defaultSlackCommandNameForSkin(activeSkinTheme ?? settings.skinTheme)];
+    return [...new Set(names)];
+}
+export function formatSlackAgentsUsage(commandNames) {
+    return `Usage: ${commandNames[0] ?? DEFAULT_SLACK_COMMAND_NAME} agents list [all]`;
+}
+function parseSlackCommandTokens(text) {
+    return text.trim().toLowerCase().split(/\s+/).filter(Boolean);
+}
+export function isSlackAgentCommand(command, commandNames) {
+    const normalized = normalizeSlackCommandName(command);
+    return normalized !== null && commandNames.includes(normalized);
+}
+export function isSlackAgentsListCommand(command, text, commandNames) {
+    if (!isSlackAgentCommand(command, commandNames))
+        return false;
+    const [subject, action] = parseSlackCommandTokens(text);
+    return subject === "agents" && action === "list";
+}
+export function shouldIncludeSlackAgentsGhosts(text) {
+    return parseSlackCommandTokens(text).some((token) => token === "all" || token === "ghosts" || token === "--all" || token === "--ghosts");
+}
+export function formatSlackAgentsDashboard(snapshot, includeGhosts) {
+    const rows = includeGhosts
+        ? snapshot.roster
+        : snapshot.roster.filter((row) => !row.health.includes("ghost") && !row.health.includes("resumable"));
+    const visibleRows = rows.slice(0, 20);
+    const headerParts = [
+        `Pinet agents: ${visibleRows.length}${rows.length !== visibleRows.length ? ` of ${rows.length}` : ""} shown`,
+        `${snapshot.liveAgents} live`,
+        `${snapshot.workerCount} workers`,
+        `${snapshot.workingWorkers} working`,
+        `${snapshot.idleWorkers} idle`,
+        `backlog ${snapshot.pendingBacklogCount}`,
+    ];
+    if (snapshot.ghostAgents > 0) {
+        headerParts.push(`${snapshot.ghostAgents} ghost${snapshot.ghostAgents === 1 ? "" : "s"}`);
+    }
+    if (snapshot.stuckAgents > 0) {
+        headerParts.push(`${snapshot.stuckAgents} stuck`);
+    }
+    const rosterLines = visibleRows.length
+        ? visibleRows.flatMap((row) => [
+            `${row.label} · ${row.role} · ${row.status} · ${row.health}`,
+            `  Workload: ${row.workload}`,
+            `  Task: ${row.taskSummary}`,
+            `  Heartbeat: ${row.heartbeat}`,
+            `  Branch: ${row.branch} · Worktree: ${row.worktree}`,
+        ])
+        : ["No agents are currently registered."];
+    const activeLanes = snapshot.activeLanes.slice(0, 8);
+    const detachedLanes = snapshot.detachedLanes.slice(0, 4);
+    return [
+        headerParts.join(" · "),
+        rosterLines.join("\n"),
+        activeLanes.length > 0
+            ? ["Active lanes:", ...activeLanes.map((lane) => `• ${lane}`)].join("\n")
+            : null,
+        detachedLanes.length > 0
+            ? ["Detached lanes:", ...detachedLanes.map((lane) => `• ${lane}`)].join("\n")
+            : null,
+    ]
+        .filter((section) => Boolean(section))
+        .join("\n\n");
+}

package/dist/slack-export.d.ts

@@ -1,11 +1,11 @@
 export type SlackExportFormat = "markdown" | "json" | "plain";
 export interface SlackExportFileInput {
+    id?: string;
     name?: string;
     title?: string;
     mimetype?: string;
     filetype?: string;
     permalink?: string;
-    urlPrivate?: string;
     preview?: string;
 }
 export interface SlackExportMessageInput {

package/dist/slack-export.js

@@ -93,14 +93,16 @@ export function formatSlackExportTimestamp(ts) {
 }
 function buildSlackFileSummary(file) {
     const label = file.title ?? file.name ?? "attachment";
-    const url = file.permalink ?? file.urlPrivate;
     const type = file.filetype ?? file.mimetype;
     const parts = [`- ${label}`];
     if (type) {
         parts.push(`(${type})`);
     }
-    if (url) {
-        parts.push(`— ${url}`);
+    if (file.id) {
+        parts.push(`id=${file.id}`);
+    }
+    if (file.permalink) {
+        parts.push(`— ${file.permalink}`);
     }
     let line = parts.join(" ");
     const preview = file.preview?.trim();
@@ -183,11 +185,11 @@ function buildJsonExport(options) {
                 : {}),
             text: convertSlackMrkdwnToMarkdown(message.text ?? "", mentionNames),
             files: (message.files ?? []).map((file) => ({
+                id: file.id,
                 title: file.title,
                 name: file.name,
                 type: file.filetype ?? file.mimetype,
                 permalink: file.permalink,
-                url_private: file.urlPrivate,
                 preview: file.preview,
             })),
         })),

package/dist/slack-file-access.d.ts

@@ -0,0 +1,34 @@
+import type { SlackResult } from "./slack-api.js";
+export declare const DEFAULT_SLACK_FILE_CACHE_TTL_MS: number;
+export declare const DEFAULT_SLACK_FILE_MAX_DOWNLOAD_BYTES: number;
+export interface SlackFileDescriptor {
+    fileId: string;
+    path: string;
+    filename: string;
+    mimetype?: string;
+    filetype?: string;
+    prettyType?: string;
+    size: number;
+    sha256: string;
+    cacheDir: string;
+    expiresAt: string;
+    residualRisks: string[];
+}
+export interface SlackFileLookupContext {
+    channelId?: string;
+    threadTs?: string;
+    messageTs?: string;
+}
+export interface SlackFileDownloadDeps {
+    slack: (method: string, token: string, body?: Record<string, unknown>) => Promise<SlackResult>;
+    token: string;
+    fetchImpl?: (url: string, init: RequestInit) => Promise<Pick<Response, "ok" | "status" | "statusText" | "arrayBuffer" | "text"> & {
+        body?: Response["body"];
+    }>;
+    now?: () => Date;
+    cacheDir?: string;
+    ttlMs?: number;
+    maxBytes?: number;
+}
+export declare function fetchSlackFileToCache(fileId: string, context: SlackFileLookupContext, deps: SlackFileDownloadDeps): Promise<SlackFileDescriptor>;
+export declare function readCachedSlackFile(pathname: string): Promise<Buffer>;