@timqi/pier 0.1.0 → 0.1.1

package/dist/channels/slack.js

@@ -1,27 +1,9 @@
 // Slack adapter: normalize inbound Socket Mode envelopes, render outbound turns.
-//
-// The anchor is threads. Pier never posts into a channel's main flow: a message
-// in the channel is answered in *its own* thread, a message in a thread is
-// answered in that thread. So a conversation is `<channel>/<threadTs>` and the
-// thread is the session — which makes Telegram's `topicMode` toggle meaningless
-// here, because there is no other behaviour to switch to. Threads cost no admin
-// right and no group conversion on Slack, so the feature Telegram has to
-// negotiate for is simply how this adapter always works.
-//
-// Three more things are Slack-specific and live only here:
-//  - Commands cannot start with `/`. The Slack client intercepts an
-//    unregistered slash command and never sends it to an app, so `stop` and
-//    `settings` are bare words instead. Registering real slash commands is
-//    deliberately not a feature: it needs manifest setup to add a second way to
-//    do what a word in the thread already does, and Slack only sends `thread_ts`
-//    for a command typed *inside* a thread, so it would be the weaker path too.
-//  - Reactions are short names (`eyes`), not codepoints; `reactions.add`
-//    rejects 👀 with `invalid_name`.
-//  - Slack redelivers anything it did not see acknowledged, so `event_id` is
-//    deduplicated.
-//
-// Everything policy-shaped (mention/bind gates, per-chat overrides) is in
-// config.ts, platform-blind and shared with Telegram.
+// Pier never posts into a channel's main flow: a conversation is
+// `<channel>/<threadTs>` and the thread is the session. Slack-specific: the
+// client intercepts unregistered slash commands, so `stop` and `settings` are
+// bare words; reactions are short names (`reactions.add` rejects 👀 with
+// `invalid_name`); unacked envelopes are redelivered, so `event_id` is deduplicated.
 import { saveInboundAll } from "../core/inbox.js";
 import { MAX_INBOUND_BYTES } from "../core/inbound-file.js";
 import { awaitsTurn } from "../core/reply.js";
@@ -38,36 +20,19 @@ import { SlackOutbound } from "./slack-outbound.js";
 import { readThread, slackToolAvailable } from "./slack-tool.js";
 import { SlackPanel } from "./slack-panel.js";
 import { context, escapeMrkdwn, offeredLabel } from "./slack-render.js";
-/** Slack wants a short name here; the raw codepoint is an `invalid_name`. */
 const WORKING = "eyes";
-// Backpressure: how many channels may be handled at once before a new one
-// queues behind an existing chain. Unlike Telegram's poll loop this cannot
-// slow the source down — the envelope is already acked — so it bounds
-// concurrency (open sockets, downloads) rather than the backlog itself.
+// The envelope is already acked, so this bounds concurrency (sockets,
+// downloads), not the backlog.
 const MAX_ACTIVE_CHATS = 16;
 const RECEIPT_STALE_MS = 30 * 60_000;
 const DRAIN_TIMEOUT_MS = 5000;
-/**
- * How long a delivered `event_id` is remembered. Slack retries an unacked
- * envelope for a few minutes; we ack immediately, so this only has to cover
- * a redelivery that crossed our ack.
- */
+/** Only has to cover a redelivery that crossed our immediate ack. */
 const DEDUP_TTL_MS = 5 * 60_000;
 const DEDUP_MAX = 2000;
-/**
- * Commands that may appear as a bare word, and exactly how many arguments each
- * takes. Both halves are load-bearing, because Slack gives us no leading `/` to
- * key on: a closed set keeps ordinary prose from being a command, and the
- * exact arity keeps "settings are broken, please help" from opening the panel
- * (or worse, "stop the deploy and tell me why" from aborting the turn that was
- * about to explain). Anything longer is a sentence, and goes to the agent.
- */
+/** Bare words with exact arity, since there is no leading `/` to key on: "stop
+ *  the deploy and tell me why" is a sentence for the agent, not an abort. */
 const BARE_COMMANDS = new Map([["stop", 0], ["settings", 0], ["bind", 1]]);
-/**
- * A Slack conversation is always `<channel>/<threadTs>` — the thread is the
- * session. This pair is the only definition of the format; control.ts decodes
- * with it rather than splitting on "/" itself.
- */
+/** The only definition of the conversation id format; control.ts decodes with it. */
 const conversationId = (channel, threadTs) => `${channel}/${threadTs}`;
 export const parseConversation = (id) => {
     const at = id.indexOf("/");
@@ -75,43 +40,20 @@ export const parseConversation = (id) => {
         ? { channel: id, threadTs: "" }
         : { channel: id.slice(0, at), threadTs: id.slice(at + 1) };
 };
-/**
- * The thread a message belongs to. A message already in a thread keeps it; one
- * posted in the channel becomes the root of its own — which is what makes
- * every request its own session without asking Slack for anything.
- */
+/** A message posted in the channel becomes the root of its own thread. */
 const threadOf = (event) => event.thread_ts ?? event.ts ?? "";
-/**
- * Subtypes worth reading. Everything else (joins, edits, deletions, topic
- * changes) is noise, and `bot_message` is either our own echo or another app's.
- * `message_share` is in because a forward is a person handing the agent
- * something to look at; dropping it delivered the sharer's comment alone, or
- * nothing at all when they forwarded without one.
- */
+/** Everything else (joins, edits, topic changes, `bot_message`) is noise; a
+ *  forward is a person handing the agent something to look at. */
 const READABLE_SUBTYPES = new Set(["file_share", "thread_broadcast", "message_share"]);
-/**
- * The forwarded messages an event carries. `is_share` is the flag proper, and
- * a `message_share` may arrive without it. An `is_msg_unfurl` on its own is
- * Slack previewing a permalink somebody pasted — the sender did not choose to
- * forward that message, so quoting it as if they had puts words in their mouth.
- * A real share carries *both* flags, which is why the unfurl flag can only
- * rule one out.
- */
+/** `is_share` is the flag proper, and a `message_share` may arrive without it.
+ *  `is_msg_unfurl` alone is Slack previewing a pasted permalink, which the
+ *  sender did not choose to forward; a real share carries both flags. */
 const sharesOf = (event) => (event.attachments ?? []).filter((a) => a.is_share === true || (event.subtype === "message_share" && !a.is_msg_unfurl));
-/** A share's own uploads, which Slack hangs off the attachment. */
 const sharedFiles = (share) => share.files ?? share.original_message?.files ?? [];
-/**
- * How many replies a shared thread may have before Pier stops reading it
- * eagerly. A token budget, not a Slack limit: a handful of lines is worth
- * spending on something a human deliberately forwarded, a few hundred is not,
- * and past this the agent gets the coordinates and decides for itself.
- */
+/** A token budget, not a Slack limit: past this the agent gets the
+ *  coordinates and decides for itself. */
 const INLINE_REPLY_MAX = 30;
-/**
- * What the user asked for, from text a mention has already been stripped from.
- * `/stop` is accepted for muscle memory even though Slack rarely lets one
- * through; a bare `stop` is the form that actually arrives.
- */
+/** `/stop` is accepted for muscle memory; a bare `stop` is what actually arrives. */
 function slackCommand(text) {
     const slash = parseCommand(text);
     if (slash)
@@ -128,27 +70,17 @@ export class SlackChannel {
     id = "slack";
     api;
     log;
-    /** 👀 lifecycle, durable; see receipts.ts for why it is not just a Map. */
     receipts;
-    /** Ordering per channel, concurrency across them; see chains.ts. */
     chains;
-    /** The inbound gate and the bind-hint throttle; see gatekeeper.ts. */
     gate;
-    /** `event_id`s already handled, against Slack's at-least-once delivery. */
     seen;
-    /** The in-chat settings panel; absent when no control was wired (tests). */
+    /** Absent when no control was wired (tests). */
     panel;
-    /** Channel kinds/names and user names, cached; see slack-directory.ts. */
     directory;
-    /**
-     * Channels already reported to the store this process. Slack's message event
-     * carries no channel name, so discovery costs an API call — once per channel
-     * per process rather than once per message. A rename is picked up on restart,
-     * which is soon enough for a Console display label.
-     */
+    /** The message event carries no channel name, so discovery costs an API call
+     *  — once per channel per process. */
     discovered = new Set();
     me = "";
-    /** Precompiled from `me`: a leading mention, and any mention. */
     mention;
     out;
     socket;
@@ -164,8 +96,7 @@ export class SlackChannel {
         this.api = deps.client ?? new SlackApi(config.token, config.appToken, this.log);
         this.out = new SlackOutbound(this.api, this.log);
         this.receipts = new Receipts(
-        // Slack names its reactions; the clear needs that name back, and Pier
-        // only ever applies the one.
+        // The clear needs the reaction's name back.
         {
             setReaction: (channel, ts, emoji) => emoji
                 ? this.api.addReaction(channel, ts, emoji)
@@ -184,20 +115,17 @@ export class SlackChannel {
         const auth = await this.api.authTest();
         this.me = auth.userId;
         if (this.me) {
-            // A Slack user id is `[A-Z0-9]+`, so it needs no escaping — but building
-            // these once keeps two regex compiles off the per-message path.
+            // A Slack user id is `[A-Z0-9]+`, so it needs no escaping.
             this.mention = {
                 leading: new RegExp(`^\\s*<@${this.me}>[\\s,:-]*`),
                 any: new RegExp(`<@${this.me}>`, "g"),
             };
         }
         else {
-            // Without our own user id, "was I mentioned?" can only answer no, so
-            // every channel with require-mention on goes silent. Loud, not a debug line.
+            // Every channel with require-mention on goes silent; loud, not a debug line.
             this.log("auth.test returned no user id: mention detection is disabled");
         }
         this.running = true;
-        // Best-effort and off the critical path.
         void this.receipts.sweep(true);
         this.socket = await this.api.connect((env) => this.onEnvelope(env, onMessage));
     }
@@ -208,22 +136,17 @@ export class SlackChannel {
         await this.chains.drain(DRAIN_TIMEOUT_MS);
     }
     // --- inbound ---------------------------------------------------------------
-    /**
-     * Already acknowledged by the transport. Routing is synchronous so ordering
-     * is decided here, before any await.
-     */
+    /** Routing is synchronous so ordering is decided before any await. */
     onEnvelope(env, onMessage) {
         if (!this.running)
             return;
-        // Asked on every envelope, throttled inside receipts.ts.
         void this.receipts.sweep();
         if (env.type === "events_api") {
             const payload = env.payload;
             const event = payload?.event;
             if (!event)
                 return;
-            // `app_mention` duplicates a `message.channels` we already get, and has
-            // its own event_id, so dedup cannot save us — it has to be ignored here.
+            // `app_mention` duplicates a `message.channels` under its own event_id.
             if (event.type !== "message") {
                 this.log(`ignored event type ${event.type}`);
                 return;
@@ -240,8 +163,7 @@ export class SlackChannel {
             const interaction = env.payload;
             if (!interaction)
                 return;
-            // A modal submission carries its conversation in private_metadata, so it
-            // is not tied to a channel chain.
+            // A modal submission carries its conversation in private_metadata.
             const channel = interaction.channel?.id ?? "modal";
             this.chains.run(channel, () => this.onInteraction(interaction, onMessage));
             return;
@@ -249,7 +171,6 @@ export class SlackChannel {
         this.log(`ignored envelope type ${env.type}`);
     }
     async onMessage(event, onMessage) {
-        // Our own echo, another app, or a subtype that is not a person talking.
         if (event.bot_id || !event.user || event.user === this.me)
             return;
         if (event.subtype && !READABLE_SUBTYPES.has(event.subtype)) {
@@ -262,22 +183,17 @@ export class SlackChannel {
             return this.log("message event without a ts, dropped");
         const raw = (event.text ?? "").trim();
         const shares = sharesOf(event);
-        // A share's files are in the attachment, so they join the event's own and
-        // ride the one save loop below — size gate and lost markers included.
         const files = [...(event.files ?? []), ...shares.flatMap(sharedFiles)];
-        // A forward with no comment of its own is still content, and the whole
-        // point of the message.
         if (!raw && !files.length && !shares.length) {
-            // A subtype we opted into that carried nothing readable is a shape this
-            // adapter did not recognize, not an empty message — most likely a share
-            // whose attachment `sharesOf` ruled out. Saying so beats vanishing (5b).
+            // An opted-in subtype with nothing readable is a shape this adapter did
+            // not recognize, not an empty message (§5).
             if (event.subtype)
                 this.log(`${event.subtype} with nothing readable in it, dropped`);
             return;
         }
         const { kind } = await this.directory.channel(this.api, channel, event);
         const isDm = kind === "dm";
-        if (!this.discovered.has(channel)) {
+        if (!this.discovered.has(channel) && this.gate.mayDiscover({ isDm, userId: event.user })) {
             this.discovered.add(channel);
             const name = await this.nameOf(channel, event);
             this.deps.store.discoverChat("slack", { id: channel, name, kind });
@@ -302,37 +218,30 @@ export class SlackChannel {
             return this.bind(channel, event.user, threadTs, command?.args ?? "");
         if (command?.name === "stop")
             return this.abortTurn(here, channel, threadTs);
-        // `@bot` on its own (the text is empty once the mention is stripped) and
-        // `settings` are the same request: show me this conversation's settings.
+        // A bare `@bot` and `settings` are the same request.
         if (this.panel && (command?.name === "settings" || (!text && !files.length && !shares.length))) {
             return this.panel.open(here, channel, threadTs);
         }
-        // Downloading only past the gate: an unauthorized sender must not be able
-        // to make the bot pull bytes on their behalf.
+        // Downloading only past the gate: an unauthorized sender must not make the
+        // bot pull bytes on their behalf.
         const markers = await this.saveAttachments(files);
         const shared = await Promise.all(shares.map((share) => this.sharedBlock(share)));
-        // A Slack thread is many people talking into one session, so the agent is
-        // told who spoke — and the id, which is what a mention needs. Resolved
-        // *before* the mark: every await between mark() and dispatch is a window
-        // in which a previous turn can end and settle, taking this receipt with it
-        // (paid for on Lark first).
+        // Resolved before the mark: any await between mark() and dispatch is a
+        // window in which a previous turn can settle and take this receipt with it.
         const sender = { id: event.user, name: await this.directory.user(this.api, event.user) };
         this.receipts.mark(here.conversationId, channel, ts);
-        // IM messages steer by default: a follow-up that waits for the turn to end
-        // is the wrong default when the human is watching a 👀 in a thread.
+        // Steer: a follow-up is the wrong default when the human is watching a 👀.
         onMessage({
             key: here,
             senderId: event.user,
             sender,
-            // Markers stay last: the inbound-file convention is a *trailing* block.
+            // Markers last: the inbound-file convention is a trailing block.
             text: [text, ...shared, ...markers].filter(Boolean).join("\n"),
             mode: "steer",
         });
     }
     // --- interactions ----------------------------------------------------------
     async onInteraction(interaction, onMessage) {
-        // A modal submission carries the conversation in private_metadata and is
-        // answered entirely by the panel.
         if (interaction.type === "view_submission") {
             if (!(await this.panel?.onViewSubmission(interaction))) {
                 this.log(`unhandled view submission ${interaction.view?.callback_id ?? "?"}`);
@@ -363,24 +272,19 @@ export class SlackChannel {
         });
         if (!admitted)
             return;
-        // Panel clicks are namespaced `cfg:` and never reach the agent.
         if (await this.panel?.onAction(interaction, key, actionId))
             return;
         const text = offeredLabel(message.blocks, actionId);
         if (text === undefined) {
-            // The person clicked and would otherwise see nothing happen (5b).
+            // The person clicked and would otherwise see nothing happen (§5).
             this.log(`unknown action ${actionId} in channel ${channel}`);
             await this.api.postMessage({ channel, thread_ts: threadTs, text: STALE_OPTION })
                 .catch((err) => this.log(`stale-option notice failed: ${String(err)}`));
             return;
         }
-        // The options belonged to the turn that just ended; once one is taken the
-        // rest answer a question the conversation has moved past (the web drops
-        // them for the same reason).
         await this.retireOptions(channel, message.ts, message.blocks);
-        // A bot cannot post as the user, so the pick is echoed and marked as one.
-        // Without it the thread shows an answer to a request nobody can see being
-        // made, and there is no message of the user's to carry the eyes.
+        // A bot cannot post as the user, so the pick is echoed: otherwise the
+        // thread shows an answer to a request nobody can see, with nothing to carry the eyes.
         const sender = { id: user, name: await this.directory.user(this.api, user) };
         const echo = await this.api.postMessage({
             channel,
@@ -390,38 +294,26 @@ export class SlackChannel {
             this.log(`option echo failed: ${String(err)}`);
             return undefined;
         });
-        // The receipt goes on the echo, not on the bot message that held the
-        // buttons: the eyes mean "this input is being worked on". No await
-        // between mark and dispatch — see onMessage.
+        // No await between mark and dispatch — see onMessage.
         if (echo?.ts)
             this.receipts.mark(key.conversationId, channel, echo.ts);
         onMessage({ key, senderId: user, sender, text, mode: "steer" });
     }
-    /**
-     * Drop the actions row, keeping the reply itself exactly as it was. A turn
-     * that was *nothing but* its options leaves nothing to keep, and Slack will
-     * not accept a message with neither text nor blocks — so it becomes a muted
-     * line rather than staying clickable forever.
-     */
+    /** Slack will not accept a message with neither text nor blocks, so a turn
+     *  that was nothing but its options becomes a muted line. */
     async retireOptions(channel, ts, blocks) {
         const kept = (blocks ?? []).filter((b) => b.type !== "actions");
         const fallback = kept.find((b) => b.type === "section")?.text.text;
         await this.api.setBlocks(channel, ts, fallback ?? "Option taken.", kept.length ? kept : [context("_Option taken._")]).catch((err) => this.log(`retiring options failed: ${String(err)}`));
     }
-    /**
-     * Stop the turn this conversation is running. The abort makes Pi end the
-     * turn, which reaches send() through the normal turn-end path and clears the
-     * 👀 receipts — so nothing here touches them.
-     */
+    /** The abort ends the turn, which reaches send() and clears the receipts. */
     async abortTurn(key, channel, threadTs) {
         await this.deps.control?.abort(key);
         await this.api.postMessage({ channel, thread_ts: threadTs, text: STOPPED });
     }
     // --- bind ------------------------------------------------------------------
-    /**
-     * Tell an unbound DM sender what to do. Channels stay silent (see gate()),
-     * but a DM that swallows every message looks broken rather than locked.
-     */
+    /** Channels stay silent, but a DM that swallows every message looks broken
+     *  rather than locked. */
     async hintBind(channel, userId, threadTs) {
         if (!this.gate.mayHint(userId))
             return;
@@ -433,36 +325,28 @@ export class SlackChannel {
     }
     async bind(channel, userId, threadTs, code) {
         const name = await this.directory.user(this.api, userId);
-        const ok = this.deps.store.redeemBindCode("slack", code, { id: userId, name });
+        const outcome = this.deps.store.redeemBindCode("slack", code, { id: userId, name });
         await this.api.postMessage({
             channel,
             thread_ts: threadTs,
-            text: bindResult(ok, escapeMrkdwn(name)),
+            text: bindResult(outcome, escapeMrkdwn(name)),
         });
     }
     // --- addressing ------------------------------------------------------------
-    /**
-     * Mentioned, or continuing a thread Pier already owns — Slack's equivalent
-     * of Telegram's "replying to the bot". The thread check is what lets a
-     * conversation flow without an `@` on every line, and it is durable so it
-     * still holds after a restart.
-     */
+    /** Mentioned, or continuing a thread Pier already owns — durable, so it
+     *  holds after a restart. */
     addressed(raw, event, key) {
         if (this.me && raw.includes(`<@${this.me}>`))
             return true;
         return !!event.thread_ts && !!this.deps.control?.knows(key);
     }
-    /**
-     * A leading `<@BOT>` is addressing, not content — the agent should not see
-     * it. Slack does not strip it for us, and puts it wherever the user typed it.
-     */
+    /** Slack does not strip the mention for us. */
     stripMention(text) {
         if (!this.mention)
             return text;
         return text.replace(this.mention.leading, "").replace(this.mention.any, "").trim();
     }
     // --- lookups ---------------------------------------------------------------
-    /** A readable label for the Console's channel list; the id is the fallback. */
     async nameOf(channel, event) {
         const { kind, name } = await this.directory.channel(this.api, channel, event);
         if (kind === "dm") {
@@ -470,32 +354,20 @@ export class SlackChannel {
         }
         return name ?? channel;
     }
-    /**
-     * What a forwarded message contributes to the prompt: who wrote it, where it
-     * lives, its text, and — when it is a thread parent — either the thread
-     * itself or the coordinates for `read_thread`. Nothing is invented: a name, a
-     * channel or a ts the event does not carry is simply left out of the line.
-     *
-     * The eager read runs whether or not `agentTool` is on, because this is
-     * inbound normalization of a message a human deliberately handed the agent —
-     * the same act as an upload, which nothing gates either. `agentTool` governs
-     * the agent reaching *out*, and the only thing it changes here is the hint,
-     * which would otherwise name a tool this session does not have.
-     */
+    /** The eager thread read runs whether or not `agentTool` is on: a human
+     *  handing the agent a message is the same act as an upload, which nothing
+     *  gates. `agentTool` only changes the hint, which must not name a tool this
+     *  session does not have. */
     async sharedBlock(share) {
         const source = share.original_message;
         const ts = share.ts ?? source?.ts;
         const threadTs = share.thread_ts ?? source?.thread_ts ?? ts;
         const replies = share.reply_count ?? source?.reply_count;
-        // A share of a *reply* is one message; only a parent has a thread — and
-        // the three fields a thread needs travel together so neither branch below
-        // has to assert they are there.
+        // A share of a reply is one message; only a parent has a thread.
         const parent = share.channel_id && ts && threadTs === ts && replies
             ? { channel: share.channel_id, ts, replies }
             : null;
-        // `name<id>` is the sender prefix's grammar (core/identity.ts), and the id
-        // is the only thing a mention can be built from. Resolved through the same
-        // cache the senders use, so a shared author already seen costs nothing.
+        // `name<id>` is the sender prefix's grammar (core/identity.ts).
         const author = share.author_id
             ? `${await this.directory.user(this.api, share.author_id)}<${share.author_id}>`
             : share.author_name || share.author_subname;
@@ -508,42 +380,28 @@ export class SlackChannel {
             where && `in ${where}`,
             ts && `at ${ts}`,
         ].filter(Boolean).join(" ");
-        // `fallback` is the plain-text rendering Slack sends when a share's `text`
-        // is empty (a file-only forward, or one whose body is all blocks).
-        // Empty rather than absent is the normal case for a file-only forward, so
-        // these fall through on "" as well.
+        // `fallback` is Slack's plain-text rendering when a share's `text` is
+        // empty (a file-only forward, or a body that is all blocks); "" is normal.
         const body = (share.text || share.fallback || source?.text || "").trim();
         const thread = parent && parent.replies <= INLINE_REPLY_MAX
             ? await this.sharedThread(parent.channel, parent.ts, parent.replies)
             : { transcript: false, lines: [] };
-        // Past the budget, or read and failed: the coordinates are what is left,
-        // and they carry the tool's own parameter names so nothing has to be
-        // guessed from a permalink. Naming the tool is a lie when the Console has
-        // switched agent access off, so only that half goes — the coordinates are
-        // true either way.
+        // The coordinates carry the tool's own parameter names; naming the tool is
+        // a lie when the Console has switched agent access off.
         const how = slackToolAvailable(this.deps.store) ? "read with the slack tool: " : "";
         const hint = parent && !thread.transcript
             ? `[thread: ${parent.replies} replies — ${how}channel ${parent.channel}, thread_ts ${parent.ts}]`
             : "";
-        // The transcript opens with the shared message itself, so repeating its
-        // text above it would only cost tokens.
+        // The transcript opens with the shared message itself.
         return [`[${head}]`, thread.transcript ? "" : body, ...thread.lines, hint]
             .filter(Boolean).join("\n");
     }
-    /**
-     * A small shared thread, read eagerly and inlined as the slack tool's own
-     * lines — through the tool's own read, so the paging, the seam dedup, the
-     * ordering and the error-to-action translation exist once (slack-tool.ts).
-     *
-     * A read that fails or comes back cut says so in the prompt (5b): a thread
-     * the agent silently never saw is indistinguishable from one with nothing in
-     * it, and the turn is dispatched either way.
-     */
+    /** Through the slack tool's own read, so paging and dedup exist once. A read
+     *  that fails or comes back cut says so in the prompt (§5). */
     async sharedThread(channel, ts, replies) {
         const deps = { directory: this.directory, log: this.log };
         try {
-            // The parent plus its replies, and one over the budget so a reply_count
-            // that undercounts still reports itself as cut rather than as complete.
+            // One over the budget, so an undercounting reply_count still reports as cut.
             const read = await readThread(deps, this.api, channel, ts, undefined, INLINE_REPLY_MAX + 2);
             if (!read.messages.length)
                 return { transcript: false, lines: [] };
@@ -552,9 +410,6 @@ export class SlackChannel {
                 lines: [
                     `[thread: ${replies} replies, oldest first — ${read.format}]`,
                     ...read.messages,
-                    // Cut either because a page failed or because the thread turned out
-                    // longer than `reply_count` promised; a transcript that answers as
-                    // if it were complete is the one nobody double-checks.
                     ...(read.incomplete || read.truncated
                         ? [`[thread partly read: ${read.incomplete ?? `cut at ${read.count} lines`}]`]
                         : []),
@@ -563,16 +418,12 @@ export class SlackChannel {
         }
         catch (err) {
             this.log(`shared thread ${channel}/${ts} not read: ${String(err)}`);
-            // Said in the prompt in the same shape as an attachment that never made
-            // it, because it is the same fact to the reader.
             return {
                 transcript: false,
                 lines: [`[thread not read: ${err instanceof Error ? err.message : String(err)}]`],
             };
         }
     }
-    /** The upload list as the shared save loop wants it (the loop itself, size
-     *  gate and lost markers included, is core/inbox.ts). */
     saveAttachments(files) {
         return saveInboundAll(this.id, files.map((file) => ({
             label: file.name ?? "attachment",
@@ -584,34 +435,20 @@ export class SlackChannel {
         })), this.log);
     }
     // --- outbound --------------------------------------------------------------
-    /**
-     * Called on every turn-end, empty text included: the turn settled with
-     * nothing to say, and the 👀 receipts still have to come off.
-     */
     async send(conversation, reply) {
         const { channel, threadTs } = parseConversation(conversation);
-        // Every id this adapter mints carries a thread, so an empty one is a
-        // corrupted or foreign conversation id. Posting it would put an agent turn
-        // in the channel's main flow — the one thing this adapter promises never to
-        // do — so it is refused loudly instead, and the receipts still come off so
-        // no 👀 is stranded.
+        // No thread is a foreign id; posting it would put a turn in the channel's
+        // main flow. Refused loudly, receipts still cleared.
         if (!threadTs) {
             this.log(`refusing to answer ${conversation}: no thread in the conversation id`);
             await this.receipts.settle(conversation);
             return;
         }
-        // settleAfter: the turn ended either way, and a 👀 left up because the
-        // reply failed to send looks like work until the stale sweep.
-        await this.receipts.settleAfter(conversation, () => this.out.reply(channel, threadTs, reply));
+        // The turn ended either way; a 👀 left up by a failed send looks like work.
+        await this.receipts.settleAfter(conversation, () => this.out.reply(channel, threadTs, reply), reply.meta);
     }
-    /**
-     * A system note, and the 👀 goes on the note itself: the turn it triggers has
-     * no message of the user's to carry them — nobody typed one — so without this
-     * the thread shows nothing at all while the agent works. The turn-end `send`
-     * clears it like any other receipt; an error note is not marked, because no
-     * turn follows it (`awaitsTurn`) and the eyes would sit there until the stale
-     * sweep.
-     */
+    /** The 👀 goes on the note itself: the turn it triggers has no message of
+     *  the user's to carry them. */
     async notify(conversation, note) {
         const { channel, threadTs } = parseConversation(conversation);
         if (!threadTs) {
@@ -619,9 +456,6 @@ export class SlackChannel {
             return;
         }
         const ts = await this.out.note(channel, threadTs, note);
-        // The last chunk of a long note, so the eyes sit at the foot of the thread,
-        // where the reply will land. A reaction that fails is swallowed and logged
-        // by receipts.ts, so the note itself is never lost to one.
         if (ts && awaitsTurn(note.origin))
             this.receipts.mark(conversation, channel, ts);
     }