@stratusagent/channel-slack 0.11.0 → 0.11.1

package/dist/index.js

@@ -7,6 +7,35 @@ import { channelSessionKey, } from '@stratusagent/channels';
 const SLACK_MAX_MESSAGE_CHARS = 4000;
 const DEFAULT_EDIT_INTERVAL_MS = 1000;
 const DEDUPE_CAPACITY = 2000;
+/**
+ * How many threads' addressees are remembered in receipt order. Past this
+ * the least recently addressed is dropped, which costs its next follow-up
+ * one session lookup — the durable answer, which is what a restart falls
+ * back to anyway.
+ */
+const THREAD_ADDRESSEE_CAPACITY = 2000;
+/**
+ * How many cold verdicts are remembered. Far smaller than the addressee
+ * map: one is wanted only while the agents sharing a thread resolve the
+ * same message, and the addressee record answers for every message after.
+ */
+const COLD_VERDICT_CAPACITY = 256;
+/**
+ * How many changes of hands one thread remembers.
+ *
+ * A message older than all of them asks the sessions instead, which answer
+ * for the thread as it stands rather than as it stood — so a reply that old
+ * can be resolved to the agent holding the thread now. That is the cost of
+ * bounding this, and something has to bound it: the alternative is a list
+ * that grows with a conversation for the life of the daemon.
+ *
+ * Eight is chosen to sit far past the case it covers. This only has to
+ * span the lag between two sockets, which is messages inside one delivery
+ * window; crossing it needs a single thread to change hands eight times —
+ * eight mentions, alternating between agents — while one socket stays
+ * behind for all of them.
+ */
+const THREAD_HANDOVER_DEPTH = 8;
 /**
  * How many files an unrendered turn may queue for its outcome. Nothing
  * drains that queue until the outcome arrives, so a session whose outcome
@@ -438,9 +467,9 @@ const truncateForSlack = (text) => text.length <= SLACK_MAX_MESSAGE_CHARS
  * point of writing a span as ``code with a ` in it`` and a fence as ````
  * when the block itself contains ```.
  */
-const closingBacktickRun = (text, from, length) => {
+const closingBacktickRun = (text, from, length, limit) => {
     const run = '`'.repeat(length);
-    for (let at = text.indexOf(run, from); at !== -1; at = text.indexOf(run, at + 1)) {
+    for (let at = text.indexOf(run, from); at !== -1 && at + length <= limit; at = text.indexOf(run, at + 1)) {
         if (text[at - 1] !== '`' && text[at + length] !== '`') {
             return at;
         }
@@ -456,12 +485,22 @@ const closingBacktickRun = (text, from, length) => {
  * the same rule for a span and for a fence and is why a longer delimiter
  * can carry a shorter one inside it.
  *
+ * A span may close on a later line, and is protected the whole way. That
+ * looks wasteful — two stray backticks paragraphs apart become one long
+ * "span" whose contents are left unconverted — and it was briefly changed
+ * to end a span at its line for exactly that reason. That was wrong, and
+ * the reason is the rule this whole file answers to: what Slack does with
+ * the message decides, not what Markdown says. Slack pairs those backticks
+ * too, so the text between them is what it renders as code, and rewriting
+ * a `**bold**` in there would alter the contents of somebody's snippet.
+ * Leaving prose unconverted is a cosmetic loss; changing what a reader is
+ * told is code is not, so the doubt resolves toward protecting more.
+ *
  * A fence with no closer runs to the end on purpose: a model that forgets
  * to close one, and every partially streamed block on its way to being
  * closed, would otherwise have its contents rewritten as prose. One or two
- * unmatched backticks are the opposite case — literal text, as they are in
- * Markdown, since "use the ` character" must not swallow the rest of the
- * message.
+ * unmatched backticks are the opposite case — literal text, since "use the
+ * ` character" must not swallow what follows.
  */
 const proseAndCode = (text) => {
     const segments = [];
@@ -476,7 +515,7 @@ const proseAndCode = (text) => {
         while (text[open + length] === '`') {
             length += 1;
         }
-        const close = closingBacktickRun(text, open + length, length);
+        const close = closingBacktickRun(text, open + length, length, text.length);
         if (close === -1) {
             if (length < 3) {
                 cursor = open + length;
@@ -522,26 +561,131 @@ const MRKDWN_REWRITES = [
  * The optional closing hashes have to be spaced off the text, as Markdown
  * requires: without that, `# C#` is a heading whose name loses its last
  * character.
+ *
+ * What they and any trailing spaces cover is captured rather than dropped,
+ * because dropping is only right when they are the heading's own syntax. A
+ * heading that opens a code span reaches its end inside one, and there the
+ * same characters are the snippet: `` # show `value # `` has a hash that
+ * belongs to whoever wrote the code.
  */
-const MARKDOWN_HEADING = /^ {0,3}#{1,6}[ \t]+(.+?)(?:[ \t]+#+)?[ \t]*$/gm;
-/** One emphasis run and nothing else — `*Title*`, not `Some *word* here`. */
-const WHOLLY_BOLD = /^\*[^*]+\*$/;
-const convertProse = (segment) => {
+const MARKDOWN_HEADING = /^ {0,3}#{1,6}[ \t]+(.+?)((?:[ \t]+#+)?[ \t]*)$/gm;
+const convertInline = (segment) => {
     let converted = segment;
     for (const [pattern, replacement] of MRKDWN_REWRITES) {
         converted = converted.replace(pattern, replacement);
     }
-    // Last, so the heading's own text is already converted. A heading a model
-    // wrote as `## **Title**` is bold by then, and wrapping it again would
-    // print the asterisks rather than render them. Nothing is stripped to get
-    // there: an asterisk in a heading may be the text itself (`# glob *.ts`),
-    // and a reply that reads oddly beats a reply that says something else.
-    return converted.replace(MARKDOWN_HEADING, (line, body) => {
-        const text = body.trim();
-        if (text.length === 0) {
+    return converted;
+};
+/**
+ * Headings, found on the text's own lines rather than inside each prose
+ * fragment.
+ *
+ * A fragment is not a line: inline code cuts one in two, and the halves
+ * begin wherever the code ended. Matched per fragment, `^` then lied in
+ * both directions — the tail of `` `status` # not a heading `` looked like a
+ * line of its own and lost its hash, and ``## Run `npm test` now`` was only
+ * ever half a line, so only the half before the code was wrapped.
+ *
+ * So the whole text is matched instead, with the code spans it now contains
+ * passed in: a `#` whose line begins inside one is a comment in somebody's
+ * snippet, not a heading. A heading that merely *contains* code is a
+ * heading, and its code goes along untouched.
+ *
+ * Emphasis inside is already converted by here, so the line is only wrapped
+ * when nothing in it can pair with the wrapper. Slack has one bold
+ * delimiter and no way to nest it: wrapping `*Run* the thing` again yields
+ * `**Run* the thing*`, which it renders as literal asterisks rather than as
+ * anything bold. A heading that already carries emphasis therefore keeps
+ * exactly the emphasis it has — `## **Title**` is bold by now and needs
+ * nothing more, and `# glob *.ts` keeps an asterisk that was never a marker
+ * at all. An unbolded heading reads fine; a heading full of stray asterisks
+ * does not, and one with characters removed to make room is worse than both.
+ *
+ * An asterisk inside a code span is not one of those: Slack does not read
+ * markup there, so it cannot pair with anything, and ``## Match `*.ts` files``
+ * is bolded like any other heading.
+ *
+ * Both walks are cursors rather than searches: `replace` reports matches in
+ * increasing offset, and the spans were collected in that order too, so
+ * neither has to be looked at twice. The same work as a scan per heading,
+ * without its quadratic on a reply that is mostly headings and snippets.
+ */
+/** What could pair with a heading's wrapper, or with something out of sight. */
+const PAIRABLE_MARKER = /[*`]/g;
+const convertHeadings = (text, code) => {
+    let span = 0;
+    const startsInside = (position, from) => position >= (code[from]?.[0] ?? Number.POSITIVE_INFINITY);
+    return text.replace(MARKDOWN_HEADING, (line, body, tail, offset) => {
+        while (span < code.length && (code[span]?.[1] ?? 0) <= offset) {
+            span += 1;
+        }
+        // A `#` whose line begins inside a span is a comment in somebody's code.
+        if (startsInside(offset, span)) {
+            return line;
+        }
+        const heading = body.trim();
+        if (heading.length === 0) {
             return line;
         }
-        return WHOLLY_BOLD.test(text) ? text : `*${text}*`;
+        // Where everything this would drop from the line's end begins: the
+        // closing hashes and spaces the pattern captured, and whatever else
+        // `trimEnd` would take with them. The two are not the same set — the
+        // pattern knows only spaces and tabs, while trimming also takes a
+        // no-break space, an ideographic space, and the rest of what
+        // ECMAScript counts as whitespace — and the difference is exactly
+        // where a character goes missing.
+        //
+        // Dropping any of it is the heading's own syntax being removed, but
+        // only while it is the heading's: a line that opens a span reaches its
+        // end inside one, and there the same characters are somebody's
+        // snippet. Nothing on this line is safe to strip then, so it is left
+        // exactly as written. (The front needs no such care: the body starts
+        // where the hashes stop, which this line has already been shown to
+        // reach in prose.)
+        const dropped = tail.length + (body.length - body.trimEnd().length);
+        if (dropped > 0) {
+            const droppedAt = offset + line.length - dropped;
+            let over = span;
+            while (over < code.length && (code[over]?.[1] ?? 0) <= droppedAt) {
+                over += 1;
+            }
+            if (startsInside(droppedAt, over)) {
+                return line;
+            }
+        }
+        // Anything left on the line that a delimiter could pair with, walked
+        // from where the heading cursor already stands rather than from the
+        // beginning. An asterisk is the obvious one — it would pair with the
+        // wrapper. A backtick counts too: one this side found no partner for is
+        // a literal character here, but Slack parses the message itself and may
+        // pair it with a backtick further down, and the wrapper's closing `*`
+        // would then be written inside what Slack reads as code, where it is
+        // ignored — leaving the opening one with nothing to close it. Both are
+        // spent characters inside a span, which is why the ranges are consulted
+        // rather than the text alone.
+        let within = span;
+        for (const marker of line.matchAll(PAIRABLE_MARKER)) {
+            const position = offset + (marker.index ?? 0);
+            while (within < code.length && (code[within]?.[1] ?? 0) <= position) {
+                within += 1;
+            }
+            if (!startsInside(position, within)) {
+                return heading;
+            }
+        }
+        // Both markers have to land in prose, not just the opening one. A fence
+        // opened on this line — by a model mid-answer, or by a block still being
+        // streamed — runs past its end, so the closing `*` would be written
+        // inside the code and ignored there, leaving the opening one unpaired.
+        // The line began in prose or this never ran, so it is the end that is
+        // in question: where the marker would go, one past the line's last
+        // character, and not that character itself — a span that closes exactly
+        // at the line's end leaves the marker just outside it, which is fine.
+        const closer = offset + line.length;
+        while (within < code.length && (code[within]?.[1] ?? 0) <= closer) {
+            within += 1;
+        }
+        return startsInside(closer, within) ? heading : `*${heading}*`;
     });
 };
 /**
@@ -558,9 +702,30 @@ const convertProse = (segment) => {
  * already mean in mrkdwn what they mean in Markdown; rewriting them would
  * add ways to be wrong and fix nothing.
  */
-const toSlackMrkdwn = (text) => proseAndCode(text)
-    .map((segment, index) => (index % 2 === 1 ? segment : convertProse(segment)))
-    .join('');
+const toSlackMrkdwn = (text) => {
+    // Where each code span ends up in the converted text, which is not where
+    // it started: the prose before it changes length as it is rewritten.
+    const code = [];
+    const segments = proseAndCode(text);
+    let converted = '';
+    segments.forEach((segment, index) => {
+        if (index % 2 === 1) {
+            // A code segment that ends the text is the unterminated fence: every
+            // closed run is followed by a prose slice, even an empty one. It has
+            // no end to be past, so nothing may be appended after it either —
+            // recording the end as it looks would say a marker placed at the
+            // text's end was safely outside.
+            const ends = index === segments.length - 1
+                ? Number.POSITIVE_INFINITY
+                : converted.length + segment.length;
+            code.push([converted.length, ends]);
+            converted += segment;
+            return;
+        }
+        converted += convertInline(segment);
+    });
+    return convertHeadings(converted, code);
+};
 const splitForSlack = (text) => {
     if (text.length <= SLACK_MAX_MESSAGE_CHARS) {
         return [text];
@@ -638,6 +803,45 @@ const OUTCOME_TEXT = {
 const APPROVAL_INPUT_LIMIT = 1400;
 /** One line in a notification; the blocks carry the readable version. */
 const APPROVAL_SUMMARY_LIMIT = 160;
+/**
+ * Subtypes that are still a person saying something, rather than Slack
+ * narrating the channel. Everything else a `subtype` marks — an edit, a
+ * deletion, a join, a pinned file — is bookkeeping, and an agent following
+ * a thread must not answer bookkeeping.
+ *
+ * These three are here because each is an ordinary thing a person does:
+ * `file_share` is a message that happens to carry an attachment (asking a
+ * question with the log attached is the normal way to ask it),
+ * `thread_broadcast` is a thread reply the author also sent to the channel,
+ * and `me_message` is what `/me` produces — typed by a person, in their own
+ * words, and marked only by how it is rendered.
+ */
+const HUMAN_MESSAGE_SUBTYPES = new Set(['file_share', 'me_message', 'thread_broadcast']);
+const isPersonSpeaking = (event) => event.subtype === undefined || HUMAN_MESSAGE_SUBTYPES.has(event.subtype);
+/** At most this many attachment names are listed; the rest are counted. */
+const MAX_LISTED_ATTACHMENTS = 5;
+/**
+ * What a message's attachments are called, for a turn that cannot open
+ * them. Without this the agent is handed "here's the log" and no log, and
+ * answers as though it had read something — the note is what lets it say
+ * the true thing instead.
+ */
+const attachmentNote = (files) => {
+    if (!files || files.length === 0) {
+        return '';
+    }
+    const names = files.slice(0, MAX_LISTED_ATTACHMENTS).map((file) => file.name ?? file.title ?? 'an unnamed file');
+    const rest = files.length - names.length;
+    const listed = rest > 0 ? `${names.join(', ')}, and ${rest} more` : names.join(', ');
+    return `\n[Attached: ${listed}. Attachment contents cannot be read here — say so rather than guessing at them.]`;
+};
+/**
+ * Whether `text` addresses a bot user by name. Slack writes a mention as
+ * `<@U123>` markup whoever typed it, so this is the same question for an
+ * `app_mention` event and for a plain channel message the app now also
+ * sees.
+ */
+const mentions = (text, botUserId) => botUserId.length > 0 && text.includes(`<@${botUserId}>`);
 /**
  * Slack's three markup characters. Tool input is written by a model, so it
  * reaches this message as untrusted text: unescaped, `<@U123>` becomes a
@@ -743,6 +947,14 @@ const approvalBlocks = (agentName, toolName, risk, requestId, input, origin, one
  * (DMs: the DM channel id alone), so threads are resumable conversations
  * and two agents sharing a thread keep fully separate sessions. Replies
  * stream via placeholder-then-edit, throttled for chat.update limits.
+ *
+ * A mention starts a thread conversation; inside one, the agent keeps
+ * listening without being tagged again — see `couldBeFollowUp` and
+ * `answersFollowUp` for exactly whose reply an untagged message is. That
+ * needs the app to be subscribed to `message.channels` / `message.groups`
+ * / `message.mpim` (the shipped manifest is); an app installed before
+ * those were in it receives only `app_mention` and behaves as it always
+ * did, which makes the workspace's own grant the switch.
  */
 export const createSlackChannelAdapter = (options) => {
     const log = options.log ?? (() => { });
@@ -776,6 +988,75 @@ export const createSlackChannelAdapter = (options) => {
     // Socket Mode redelivers on missed acks; a slow turn must not run twice.
     const seenEvents = new Set();
     const seenOrder = [];
+    /**
+     * Who each thread was last handed to, in SLACK RECEIPT ORDER — written
+     * the moment a message is accepted for an agent, before any of the work
+     * that message causes.
+     *
+     * The durable answer (`answersFollowUp`) is the agents' own sessions,
+     * and it lags: a session row is written when its turn starts, which is a
+     * display-name lookup and a placeholder post after the message that
+     * asked for it. Inside that window the persisted order still names the
+     * agent that spoke *before* the handover, so a mention of Bea followed
+     * straight away by an untagged addendum would send the addendum to Ava —
+     * and a follow-up typed on the heels of the mention that opened the
+     * thread would find no session at all and be dropped for good.
+     *
+     * Keyed by thread rather than by (agent, thread): one agent has it at a
+     * time, so there is nothing to reconcile. The value is that thread's
+     * HANDOVERS in order, not just its latest one, because the question an
+     * untagged message asks is not "who holds this thread now" but "who held
+     * it when I was sent". Those differ whenever a socket runs behind
+     * another: Bea's connection can reject a pre-handover reply, then take
+     * the mention that moves the thread to her, and Ava's connection reach
+     * that same earlier reply afterwards — which the latest holder alone
+     * would reject for a second time, dropping a message that was plainly
+     * Ava's when it was written.
+     *
+     * Keeping the handovers also makes out-of-order writes ordinary rather
+     * than dangerous. A connection several messages behind, or a redelivered
+     * envelope carrying an old mention, inserts into the past where it
+     * belongs instead of overwriting the present.
+     *
+     * Bounded and lossy on purpose — evicting an entry costs one lookup,
+     * since the sessions still hold the answer for every thread this map has
+     * forgotten, and for every thread a restart forgot.
+     *
+     * One thing they cannot reconstruct: a handover made in the seconds
+     * before the daemon went down. The mention that moved the thread is
+     * recorded only here, and the newly named agent has not replied yet, so
+     * after a restart the sessions still name the previous speaker and the
+     * next untagged reply goes to them. Surviving that needs durable
+     * adapter-owned state, which the channel contract deliberately does not
+     * have — an adapter reads routing and translates events, and inventing a
+     * private store here is the wrong place to answer it. The next mention
+     * corrects it.
+     */
+    const threadAddressee = new Map();
+    /**
+     * One cold verdict per message — see `followUpWinner`. Bounded, because
+     * an entry outlives its own resolution on purpose; an entry that has not
+     * yet resolved is never the one evicted, since the agent still waiting on
+     * it would otherwise start a second one.
+     */
+    const coldVerdicts = new Map();
+    /**
+     * `agentId` → bot user id, for every app whose token this adapter has
+     * authenticated — whether or not its socket then came up, and kept for as
+     * long as the adapter runs.
+     *
+     * Separate from `connections` because recognizing that somebody was named
+     * and being able to answer are different questions. An agent whose app is
+     * down cannot answer anything; a message that names it is still not the
+     * other agent's to take, and treating it as untagged would have the wrong
+     * agent answer a question a person deliberately handed elsewhere. Silence
+     * is the correct outcome there, and it is also the visible one — the same
+     * thing a mention has always done when an app is down.
+     *
+     * Insertion order is `options.agents` order, which is what makes
+     * `agentNamedIn` deterministic across every connection.
+     */
+    const botIdentities = new Map();
     // Rendered approval requests, keyed by the gateway's request id — the
     // same id the buttons carry back.
     const approvalPosts = new Map();
@@ -1348,47 +1629,432 @@ export const createSlackChannelAdapter = (options) => {
             warn(`slack: could not send an ephemeral notice: ${error instanceof Error ? error.message : String(error)}`);
         }
     };
-    const handleInbound = async (connection, args) => {
-        // Ack immediately: Slack redelivers unacked envelopes, and a turn can
-        // outlive the ack window many times over.
-        await args.ack();
+    /** One thread, whichever agent is talking in it. */
+    const threadKeyFor = (parts) => `${parts.team}:${parts.conversation}:${parts.thread}`;
+    /**
+     * Records that `agentId` holds the thread from the message at `ts`
+     * onwards, wherever in the thread's history that message falls.
+     *
+     * Only actual handovers are kept: a write naming the agent that already
+     * held the thread at that point adds nothing, so the list stays as short
+     * as the conversation's changes of hands rather than growing per message.
+     * The oldest handovers are dropped past `THREAD_HANDOVER_DEPTH`, and the
+     * least recently written thread past `THREAD_ADDRESSEE_CAPACITY`; both
+     * losses cost a lookup, never an answer, since the sessions still hold
+     * the durable version.
+     *
+     * Slack timestamps compare as strings: `seconds.microseconds`, both
+     * parts fixed width, so lexicographic order is chronological order.
+     */
+    const rememberAddressee = (key, agentId, ts) => {
+        const handovers = threadAddressee.get(key) ?? [];
+        let at = handovers.length;
+        while (at > 0 && handovers[at - 1].ts > ts) {
+            at -= 1;
+        }
+        const before = handovers[at - 1];
+        if (before && before.agentId === agentId) {
+            // Already this agent's from earlier in the thread; the same message
+            // reaching a second connection lands here too.
+            return;
+        }
+        handovers.splice(at, 0, { agentId, ts });
+        // Re-inserted rather than mutated in place: a Map iterates in insertion
+        // order, which is what makes the first key the one to evict.
+        threadAddressee.delete(key);
+        threadAddressee.set(key, handovers.slice(-THREAD_HANDOVER_DEPTH));
+        if (threadAddressee.size > THREAD_ADDRESSEE_CAPACITY) {
+            const oldest = threadAddressee.keys().next();
+            if (!oldest.done) {
+                threadAddressee.delete(oldest.value);
+            }
+        }
+    };
+    /**
+     * Who held the thread when the message at `ts` was sent — the last
+     * handover at or before it. Undefined when this process has no handover
+     * that old, which sends the question to the sessions.
+     */
+    const holderAt = (key, ts) => {
+        const handovers = threadAddressee.get(key);
+        if (!handovers) {
+            return undefined;
+        }
+        for (let index = handovers.length - 1; index >= 0; index -= 1) {
+            const handover = handovers[index];
+            if (handover && handover.ts <= ts) {
+                return handover.agentId;
+            }
+        }
+        return undefined;
+    };
+    /**
+     * Which of this process's agents a message names, or undefined if it
+     * names none of them.
+     *
+     * When it names several, the first that is actually serving — and any
+     * of them otherwise. That determinism is the point: every connection sees every message and runs
+     * this over the same text and the same array, so all of them agree on who
+     * a message handed the thread to — including the connections that will go
+     * on to ignore it. Which is what makes the handover record converge
+     * without the sockets having to agree on anything, since each agent is
+     * its own Socket Mode connection and one can run minutes behind another.
+     *
+     * Scoped to the message's own workspace, because a bot user id is only
+     * unique within one — the same reason the display-name cache is keyed by
+     * team. Two agents in two workspaces can hold the same id, and resolving
+     * a mention to the wrong one would hand the thread to an agent that
+     * cannot see it, leaving the agent that was actually named refusing every
+     * reply after.
+     *
+     * Only agents this adapter has authenticated can be recognized at all.
+     * One served by another daemon is invisible here, and both would answer;
+     * so is one whose `auth.test` itself failed, since its bot id was never
+     * learned.
+     */
+    const agentNamedIn = (text, team) => {
+        let offline;
+        for (const [agentId, identity] of botIdentities) {
+            if (identity.teamId !== team || !mentions(text, identity.botUserId)) {
+                continue;
+            }
+            if (connections.some((live) => live.config.agentId === agentId)) {
+                return agentId;
+            }
+            // Named, recognized, and not serving. Remembered only as the answer
+            // of last resort: a message that names an agent whose app is down and
+            // nobody else still gets silence, which is the deliberate behavior —
+            // but a message that also names one that IS serving must leave the
+            // thread with the agent that can actually answer it, or the reply it
+            // just posted would be the last anyone gets.
+            offline ??= agentId;
+        }
+        return offline;
+    };
+    /**
+     * Who an untagged reply belongs to, asked of the SESSIONS — the durable
+     * answer, for a thread this process has no record of: one it has not seen
+     * a message in since it started, or one evicted from `threadAddressee`.
+     * Everything else is settled synchronously in `admit`, before this is
+     * ever reached.
+     *
+     * Being in the thread is the first half: a session under a thread's key
+     * exists only because someone mentioned that agent here, so an agent
+     * follows up only in conversations it was invited into, and stops when
+     * the thread is gone. `sessionRouting` is the durable record of that — a
+     * restart forgets nothing.
+     *
+     * Whose turn it is, is the second. In a thread with several agents an
+     * unaddressed reply belongs to **whoever spoke last**, the way it does
+     * between people: answer the voice that just answered you, and tag
+     * someone by name to change that. `lastSpokeAt` orders them — when each
+     * agent last *replied*, not when its session last changed, because a turn
+     * saves on tool results and approval checkpoints without having said
+     * anything, and a recovery resuming after a restart lands in exactly this
+     * window.
+     *
+     * Nobody is the answer only when the agents cannot be *ordered* — nothing
+     * in the thread has spoken (a host whose routing carries no `lastSpokeAt`
+     * at all reads this way, and so does a thread where every agent is still
+     * on its first turn), or the newest two tie — because guessing there
+     * would put two answers under one message. An agent that simply has not
+     * spoken is a different thing and is skipped rather than fatal: it cannot
+     * have spoken last, and letting it silence the agent that did would leave
+     * a reply nobody answers. The agent alone in its thread, which is nearly
+     * every thread, is answered without the question arising.
+     */
+    const resolveFollowUpWinner = async (parts) => {
         const gateway = gatewayRef;
+        if (!gateway?.sessionRouting || !parts.thread) {
+            return undefined;
+        }
+        const engaged = [];
+        // Live connections in this message's OWN workspace. Live, because an
+        // agent whose app failed to connect cannot answer anything, and leaving
+        // a thread silent because its last speaker is offline is the bug this
+        // whole change exists to remove. In-workspace, because a session key
+        // carries a team: an agent whose app has moved workspaces still has its
+        // old sessions there, and letting those contend for a thread it can no
+        // longer receive a message in would leave nobody to answer.
+        for (const candidate of connections) {
+            if (candidate.teamId !== parts.team) {
+                continue;
+            }
+            const routing = await gateway.sessionRouting(channelSessionKey({
+                channel: 'slack',
+                agentId: candidate.config.agentId,
+                team: parts.team,
+                conversation: parts.conversation,
+                thread: parts.thread,
+            }));
+            if (!routing) {
+                continue;
+            }
+            engaged.push({
+                agentId: candidate.config.agentId,
+                ...(routing.lastSpokeAt !== undefined ? { lastSpokeAt: routing.lastSpokeAt } : {}),
+            });
+        }
+        const first = engaged[0];
+        if (!first) {
+            return undefined;
+        }
+        if (engaged.length === 1) {
+            return first.agentId;
+        }
+        let latest;
+        let tied = false;
+        for (const entry of engaged) {
+            if (entry.lastSpokeAt === undefined) {
+                // In the thread, but has never said anything in it — mentioned and
+                // still on its first turn, or a turn that produced no text. It
+                // cannot be the one who spoke last, and it must not stop the agent
+                // that did from answering.
+                continue;
+            }
+            if (!latest || entry.lastSpokeAt > latest.lastSpokeAt) {
+                latest = { agentId: entry.agentId, lastSpokeAt: entry.lastSpokeAt };
+                tied = false;
+            }
+            else if (entry.lastSpokeAt === latest.lastSpokeAt) {
+                tied = true;
+            }
+        }
+        return tied ? undefined : latest?.agentId;
+    };
+    /**
+     * `resolveFollowUpWinner`, resolved ONCE PER MESSAGE and shared by every
+     * agent asking about that message.
+     *
+     * The sharing is the point. Each agent's own copy of the question is
+     * several independent session reads, and turns finishing in between can
+     * make two agents' reads disagree: both concluding they are the most
+     * recent speaker, so one message is answered twice, or both concluding
+     * they are not, so it is answered by nobody. One resolution cannot
+     * disagree with itself, which is a stronger guarantee than arbitrating
+     * between two that already have.
+     *
+     * Keyed on the message, so a later reply in the same thread asks again.
+     * Bounded, and deliberately not deleted when it settles: an entry has to
+     * outlive its own resolution, because an agent it beats may only reach
+     * this after the winner has finished, and recomputing for that agent is
+     * precisely the disagreement the memo exists to prevent.
+     */
+    const followUpWinner = (parts, ts) => {
+        const key = `${threadKeyFor(parts)}:${ts}`;
+        const existing = coldVerdicts.get(key);
+        if (existing) {
+            return existing.verdict;
+        }
+        const entry = { verdict: resolveFollowUpWinner(parts), settled: false };
+        coldVerdicts.set(key, entry);
+        void entry.verdict.then(() => {
+            entry.settled = true;
+        }, () => {
+            entry.settled = true;
+        });
+        if (coldVerdicts.size > COLD_VERDICT_CAPACITY) {
+            // The oldest SETTLED entry, never simply the oldest. Evicting one
+            // still resolving is the one eviction that costs an answer rather
+            // than a lookup: the agent it has not reached yet would start its own
+            // resolution, which is the disagreement this memo exists to prevent.
+            // With none settled there is nothing safe to drop, and the map runs
+            // over its cap by however many resolutions are genuinely in flight.
+            for (const [candidate, held] of coldVerdicts) {
+                if (held.settled) {
+                    coldVerdicts.delete(candidate);
+                    break;
+                }
+            }
+        }
+        return entry.verdict;
+    };
+    /**
+     * Everything about who a message is for that can be decided WITHOUT
+     * AWAITING, run straight off the socket's own event emission — so for the
+     * whole of it, this process is exactly as far through the conversation as
+     * Slack is.
+     *
+     * That is the point of it being one synchronous block. The Socket Mode
+     * client emits envelopes in order, but `ack()` resolves from a WebSocket
+     * send callback, so two handlers that ack before deciding anything can
+     * come back in either order: a follow-up could then overtake the mention
+     * that opened its thread, find neither a record nor a session, and be
+     * dropped for good. Nothing here awaits, so nothing can be overtaken —
+     * the dedupe and the handover record included, which are the two pieces a
+     * later message reads.
+     *
+     * `undefined` means the message is not this agent's. `settled: false`
+     * means only the sessions can still decide it, which is the one case that
+     * has to wait — and it is the cold case, where by definition no message
+     * of this thread has been seen in this process.
+     */
+    const admit = (connection, args) => {
         const event = args.event;
-        if (!gateway || !event || !event.user || event.bot_id || event.subtype) {
-            return;
+        if (!gatewayRef || !event || !event.user || event.bot_id || !isPersonSpeaking(event)) {
+            return undefined;
         }
-        const isDm = event.channel_type === 'im';
-        if (event.type !== 'app_mention' && !(event.type === 'message' && isDm)) {
-            // Mention-only outside DMs.
-            return;
+        if (event.type !== 'app_mention' && event.type !== 'message') {
+            return undefined;
         }
         if (event.user === connection.botUserId) {
-            return;
-        }
-        const eventKey = `${connection.config.agentId}:${args.body?.event_id ?? args.envelope_id ?? `${event.channel}:${event.ts}`}`;
-        if (alreadySeen(eventKey)) {
-            return;
+            return undefined;
         }
+        const isDm = event.channel_type === 'im';
         const team = args.body?.team_id ?? connection.teamId;
-        const userId = event.user;
         // A top-level mention has no thread_ts; its own ts roots the reply
         // thread that becomes the conversation. DMs are one conversation per
         // peer, unkeyed by thread.
         const thread = isDm ? undefined : event.thread_ts ?? event.ts;
-        const sessionId = channelSessionKey({
-            channel: 'slack',
-            agentId: connection.config.agentId,
+        // Threads only: a DM has one agent by construction.
+        const threadKey = thread !== undefined && !isDm
+            ? threadKeyFor({ team, conversation: event.channel, thread })
+            : undefined;
+        const text = event.text ?? '';
+        const addressed = isDm || mentions(text, connection.botUserId);
+        // Who this message hands the thread to — worked out by EVERY connection
+        // that sees it, not only by the one being named, and recorded before any
+        // of the rejections below. Each agent is its own Socket Mode connection,
+        // so the message naming Bea reaches Ava's socket and Bea's socket
+        // independently and in no fixed order; if only Bea recorded the
+        // handover, Ava could take the next untagged reply while Bea's socket
+        // was still behind, and answer a question that had just been handed
+        // away. The message Ava must record is exactly the one Ava ignores.
+        const named = agentNamedIn(text, team);
+        if (threadKey && named) {
+            rememberAddressee(threadKey, named, event.ts);
+        }
+        if (!addressed) {
+            if (event.thread_ts === undefined) {
+                // The room is not a conversation: a message that starts a thread,
+                // or stands alone, is a follow-up to nothing.
+                return undefined;
+            }
+            if (named) {
+                // Somebody else was asked. Tagging an agent hands it the question,
+                // and the agent that had it is no longer being asked — two answers
+                // to one message is what a thread with a roster in it must never
+                // produce.
+                return undefined;
+            }
+        }
+        // One Slack MESSAGE, not one delivery. An app subscribed to both
+        // `app_mention` and `message.channels` is told about a mention twice —
+        // two envelopes carrying two event ids — so keying this on the event
+        // id would run the turn twice the moment thread follow-through was
+        // switched on. `(channel, ts)` names the message itself, and a
+        // redelivery (what the event id was here for) repeats both.
+        //
+        // After the handover record and not before it: a redelivery re-records
+        // the same agent, which costs nothing, while deduping first would drop
+        // the record whenever the other copy of a doubly-delivered mention is
+        // the one a connection sees second.
+        const eventKey = `${connection.config.agentId}:${event.channel}:${event.ts}`;
+        if (alreadySeen(eventKey)) {
+            return undefined;
+        }
+        const admission = {
+            event,
+            isDm,
             team,
-            conversation: event.channel,
+            userId: event.user,
+            sessionId: channelSessionKey({
+                channel: 'slack',
+                agentId: connection.config.agentId,
+                team,
+                conversation: event.channel,
+                ...(thread ? { thread } : {}),
+            }),
             ...(thread ? { thread } : {}),
+            ...(threadKey ? { threadKey } : {}),
+            settled: true,
+        };
+        if (addressed) {
+            // A message that named this agent and others is recorded above under
+            // whichever of them comes first in connection order — every agent
+            // named answers it, and the thread it leaves behind has one holder
+            // that all the sockets agree on, which is the only self-consistent
+            // reading of a message that asked several.
+            return admission;
+        }
+        // An untagged reply. The record is what this process has actually seen,
+        // in the order it saw it — right even inside the window before a
+        // handover reaches the store.
+        const holder = threadKey === undefined ? undefined : holderAt(threadKey, event.ts);
+        if (holder !== undefined && threadKey !== undefined) {
+            if (holder !== connection.config.agentId) {
+                // Standing down for the holder, whether or not the holder can still
+                // hear it. An app removed from this channel stops receiving the
+                // thread, and its untagged replies then reach nobody until somebody
+                // names an agent — which is the same answer this adapter gives
+                // whenever the agent being addressed cannot answer, and one mention
+                // reopens the conversation. Doing better means per-channel
+                // membership the adapter does not track, and would have to be
+                // tracked in the durable path too, since a removed app is still a
+                // live connection with the newest session there.
+                return undefined;
+            }
+            rememberAddressee(threadKey, connection.config.agentId, event.ts);
+            return admission;
+        }
+        // Nothing seen for this thread since startup: only the sessions can
+        // answer, and that answer has to be awaited.
+        return { ...admission, settled: false };
+    };
+    const handleInbound = async (connection, args) => {
+        // Decided before the ack, never after it — see `admit`. That block is
+        // map and string work measured in microseconds, against an ack window
+        // Slack measures in seconds, and the envelope is acked below whatever
+        // the decision was.
+        const admitted = admit(connection, args);
+        // Acked without awaiting it. The ack still leaves as promptly as it ever
+        // did — Slack redelivers unacked envelopes, and a turn outlives the ack
+        // window many times over — but nothing here needs its send callback, and
+        // awaiting one was the single await between receiving a message and
+        // taking its place in the queue below. Two handlers waiting on their
+        // acks can come back in either order; two handlers that never wait
+        // cannot. A failed ack costs a redelivery, which the dedupe absorbs.
+        void Promise.resolve(args.ack()).catch((error) => {
+            warn(`slack: could not ack an envelope: ${error instanceof Error ? error.message : String(error)}`);
         });
+        if (!admitted) {
+            return;
+        }
+        // Re-read rather than carried through the admission: `stop()` can clear
+        // it while the ack above is in flight, and a dispatch into a gateway
+        // this adapter has let go of is not one to start.
+        const gateway = gatewayRef;
+        if (!gateway) {
+            return;
+        }
+        const { event, isDm, team, userId, thread, sessionId, threadKey } = admitted;
         // Everything up to (and including) the dispatch call is serialized per
         // session in Slack receipt order: the user lookups and placeholder
         // post below await network I/O, and without this chain a later message
         // could reach gateway.dispatch first — processing the conversation in
-        // reverse order in durable history.
+        // reverse order in durable history. The chain is claimed here,
+        // synchronously, so a message's place in it is fixed by when Slack
+        // delivered it and not by how long anything it does takes.
         const previousIntake = intakeChains.get(sessionId) ?? Promise.resolve();
         const intake = previousIntake.then(async () => {
+            // The durable half of addressing runs INSIDE the chain, for the same
+            // reason: it awaits, and a message that had to ask the sessions must
+            // not lose its place to one that did not. A message that turns out
+            // not to be this agent's leaves an empty link behind, which is all it
+            // should cost.
+            if (!admitted.settled) {
+                // One verdict for this message, shared with whichever other agents
+                // are asking about it — see `followUpWinner`.
+                const winner = await followUpWinner({ team, conversation: event.channel, thread: event.thread_ts ?? '' }, event.ts);
+                if (winner !== connection.config.agentId) {
+                    return undefined;
+                }
+                // Answered from the store rather than from memory: hold it, so the
+                // rest of the thread is ordered by receipt like any other.
+                if (threadKey) {
+                    rememberAddressee(threadKey, connection.config.agentId, event.ts);
+                }
+            }
             const cleaned = await humanizeMentions(connection, event.text ?? '');
             if (cleaned.length === 0) {
                 return undefined;
@@ -1396,7 +2062,8 @@ export const createSlackChannelAdapter = (options) => {
             const author = await displayNameFor(connection, userId);
             // In shared channels the model should know who is speaking; a DM is
             // unambiguous.
-            const userMessage = isDm ? cleaned : `${author}: ${cleaned}`;
+            const spoken = isDm ? cleaned : `${author}: ${cleaned}`;
+            const userMessage = `${spoken}${attachmentNote(event.files)}`;
             const renderer = new ReplyRenderer(connection.web, event.channel, thread, editIntervalMs, warn);
             try {
                 await renderer.open();
@@ -1569,6 +2236,14 @@ export const createSlackChannelAdapter = (options) => {
                 }
             });
             const known = new Set(gateway.agents().map((agent) => agent.id));
+            // Two passes, because who a message names has to be answerable from
+            // the first event onwards. Identities are learned for every app
+            // FIRST; only then does any socket start delivering. One pass would
+            // leave the agents at the front of the roster taking messages while
+            // the ones behind them were still authenticating, and a mention of an
+            // agent not yet known reads as an untagged reply — which the agent
+            // holding that thread would then answer.
+            const authenticated = [];
             for (const config of options.agents) {
                 if (!known.has(config.agentId)) {
                     warn(`slack: no roster agent with id ${config.agentId}; skipping its Slack app`);
@@ -1577,14 +2252,27 @@ export const createSlackChannelAdapter = (options) => {
                 try {
                     const web = createWeb(config.botToken);
                     const auth = await web.auth.test();
-                    const socket = createSocket(config.appToken);
-                    const connection = {
+                    const botUserId = auth.user_id ?? '';
+                    const teamId = auth.team_id ?? '';
+                    // Recorded before the socket is even built: an app that never
+                    // comes up must still be recognizable when somebody names it.
+                    botIdentities.set(config.agentId, { botUserId, teamId });
+                    authenticated.push({
                         config,
                         web,
-                        socket,
-                        botUserId: auth.user_id ?? '',
-                        teamId: auth.team_id ?? '',
-                    };
+                        socket: createSocket(config.appToken),
+                        botUserId,
+                        teamId,
+                    });
+                }
+                catch (error) {
+                    // One broken app must not take the rest of the fleet down.
+                    warn(`slack: could not connect ${config.agentId}: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            for (const connection of authenticated) {
+                const { config, socket } = connection;
+                try {
                     const onEvent = (args) => {
                         const handled = handleInbound(connection, args).catch((error) => {
                             warn(`slack event handling failed: ${error instanceof Error ? error.message : String(error)}`);
@@ -1604,7 +2292,8 @@ export const createSlackChannelAdapter = (options) => {
                     log(`slack: ${config.agentId} connected (bot ${connection.botUserId} in team ${connection.teamId})`);
                 }
                 catch (error) {
-                    // One broken app must not take the rest of the fleet down.
+                    // Authenticated but not serving: it answers nothing, and stays
+                    // recognizable so nobody answers in its place.
                     warn(`slack: could not connect ${config.agentId}: ${error instanceof Error ? error.message : String(error)}`);
                 }
             }
@@ -1636,6 +2325,9 @@ export const createSlackChannelAdapter = (options) => {
             gatewayRef = undefined;
             connections.length = 0;
             approvalPosts.clear();
+            threadAddressee.clear();
+            coldVerdicts.clear();
+            botIdentities.clear();
             rendering.clear();
             resolvedWhileRendering.clear();
         },