@timqi/pier 0.1.0 → 0.1.1

package/dist/channels/receipts.js

@@ -1,26 +1,13 @@
-// Reaction receipts: the whole lifecycle, storage included.
-//
-// A 👀 goes on an inbound message and comes off when its turn settles. Both
-// halves live in Telegram, not in Pier, so anything ending the process between
-// them leaves the emoji on a user's message with nobody left to clear it —
-// and so does a message whose session never started a turn at all. Making the
-// pending set durable is what closes the loop: an adapter clears every receipt
-// it finds at startup (nothing in memory can be its own yet), and sweeps its
-// own stragglers on a timer.
+// Reaction receipts: a 👀 goes on an inbound message and comes off when its
+// turn settles. Durable, because the emoji lives on the platform: a process
+// ending between the two halves would leave it with nobody to clear it.
 import { pierDb } from "../db.js";
-/**
- * How often the straggler sweep may really run. Adapters ask on the inbound
- * path — per envelope, or per `getUpdates` round trip — and the books only
- * change on the scale of `staleMs`, so a busy chat would otherwise run this
- * query hundreds of times a minute. Throttled here rather than in each
- * adapter, which is where the same timestamp had been copied twice already.
- */
+/** Adapters ask on every inbound envelope; the books change on the scale of `staleMs`. */
 const SWEEP_EVERY_MS = 60_000;
 const toReceipt = (row) => ({
     conversationId: row.conversation_id,
     chatId: row.chat_id,
-    // SQLite hands back whatever affinity it stored; the column is TEXT, but
-    // coercing keeps a numeric-looking id from arriving as a number.
+    // The column is TEXT, but a numeric-looking id could still arrive as a number.
     messageId: String(row.message_id),
 });
 export class ReceiptLedger {
@@ -30,7 +17,6 @@ export class ReceiptLedger {
         this.platform = platform;
         this.db = db;
     }
-    /** Re-marking the same message replaces the row rather than duplicating it. */
     add(receipt) {
         this.db.prepare(`
       INSERT INTO receipts(platform, conversation_id, chat_id, message_id, created_at)
@@ -39,14 +25,17 @@ export class ReceiptLedger {
         conversation_id = excluded.conversation_id, created_at = excluded.created_at
     `).run(this.platform, receipt.conversationId, receipt.chatId, receipt.messageId, Date.now());
     }
-    /** Claim a conversation's receipts: returned once, then gone. */
-    take(conversationId) {
+    /** Returned once, then gone. `bookedBy` claims only what was on the books by
+     *  then — see `Receipts.settle`. */
+    take(conversationId, bookedBy) {
+        const scope = bookedBy === undefined ? "" : " AND created_at <= ?";
+        const args = bookedBy === undefined ? [] : [bookedBy];
         const rows = this.db.prepare(`
       SELECT conversation_id, chat_id, message_id FROM receipts
-      WHERE platform = ? AND conversation_id = ?
-    `).all(this.platform, conversationId);
-        this.db.prepare("DELETE FROM receipts WHERE platform = ? AND conversation_id = ?")
-            .run(this.platform, conversationId);
+      WHERE platform = ? AND conversation_id = ?${scope}
+    `).all(this.platform, conversationId, ...args);
+        this.db.prepare(`DELETE FROM receipts WHERE platform = ? AND conversation_id = ?${scope}`)
+            .run(this.platform, conversationId, ...args);
         return rows.map(toReceipt);
     }
     /** Claim receipts older than `ageMs`; `0` claims everything (startup sweep). */
@@ -61,20 +50,15 @@ export class ReceiptLedger {
         return rows.map(toReceipt);
     }
 }
-/**
- * Marks messages as being worked on and unmarks them when their turn settles.
- * Lives next to the ledger because the ordering rule spans both: a receipt is
- * booked synchronously (so an instant turn cannot clear an unbooked one) while
- * the platform call is in flight, and the clear must wait for that call to land
- * or the reaction stays up forever.
- */
+/** A receipt is booked synchronously (an instant turn must not clear an
+ *  unbooked one) while the platform call is in flight, and the clear waits for
+ *  that call to land or the reaction stays up forever. */
 export class Receipts {
     api;
     ledger;
     log;
     emoji;
     staleMs;
-    /** In-flight `setReaction` per marked message. Only this process's own. */
     applying = new Map();
     sweptAt = 0;
     constructor(api, ledger, log, emoji, 
@@ -91,40 +75,33 @@ export class Receipts {
             .catch((err) => this.log(`reaction failed: ${String(err)}`)));
         this.ledger.add({ conversationId, chatId, messageId });
     }
-    /** The turn this conversation was running has ended. */
-    settle(conversationId) {
-        return this.clear(this.ledger.take(conversationId));
+    /** Only the messages *this* turn was working on: a message queued mid-turn
+     *  is still owed an answer. `meta` says when the turn began; no meta clears
+     *  everything (the refusal paths have no turn to scope by). */
+    settle(conversationId, meta) {
+        const began = meta && meta.completedAt - meta.durationMs;
+        return this.clear(this.ledger.take(conversationId, began));
     }
-    /**
-     * Deliver a turn and settle its receipts *whatever happens* — a 👀 left on
-     * a message because the reply failed to send sits there looking like work
-     * until the stale sweep. The try/finally was copied into all three
-     * adapters' send() before landing here; the error still propagates, because
-     * a failed delivery is the router's to report.
-     */
-    async settleAfter(conversationId, deliver) {
+    /** Settles whatever happens; the error still propagates, because a failed
+     *  delivery is the router's to report. */
+    async settleAfter(conversationId, deliver, meta) {
         try {
             await deliver();
         }
         finally {
-            await this.settle(conversationId);
+            await this.settle(conversationId, meta);
         }
     }
-    /**
-     * Everything on the books at startup is orphaned — nothing in memory can be
-     * ours yet — and past `staleMs` a receipt's turn is never going to settle.
-     */
+    /** `all` is the startup sweep: everything on the books is orphaned then. */
     sweep(all = false) {
         const now = Date.now();
-        // `all` is the startup sweep: it takes everything, so it is never skipped.
         if (!all && now - this.sweptAt < SWEEP_EVERY_MS)
             return Promise.resolve();
         this.sweptAt = now;
         return this.clear(this.ledger.takeStale(all ? 0 : this.staleMs));
     }
     async clear(receipts) {
-        // Wait together, then launch clears in booking order: if one apply is slow,
-        // it must not let a later receipt clear first.
+        // A slow apply must not let a later receipt clear first.
         await Promise.all(receipts.map(({ chatId, messageId }) => this.applying.get(`${chatId}:${messageId}`)));
         for (const { chatId, messageId } of receipts)
             this.applying.delete(`${chatId}:${messageId}`);

package/dist/channels/routes.js

@@ -1,6 +1,4 @@
-// Settings → Channels HTTP surface. One document per platform: credentials,
-// global defaults, bound users and discovered chats travel together, so the
-// UI never has to stitch two half-configs.
+// Settings → Channels HTTP surface: one document per platform.
 import { isThinkingLevel } from "../core/types.js";
 import { defaultChannelConfig, isChannelPlatform, } from "./types.js";
 /** Stable mask: recomputable at write time, so "unchanged" is detectable. */
@@ -17,12 +15,8 @@ function asModel(v) {
     const id = asString(ref.id);
     return provider && id ? { provider, id } : null;
 }
-/**
- * Apply the client's edits on top of what the store knows. Iterating the
- * stored list, not the payload, is what makes the save non-destructive: chats
- * are discovered, so one that appeared while the operator had the page open
- * must survive their save instead of being deleted by a stale client list.
- */
+/** Iterates the stored list, not the payload: a chat discovered while the
+ *  operator had the page open must survive their save. */
 function parseChats(raw, known) {
     if (!Array.isArray(raw))
         return known;

package/dist/channels/runtime.js

@@ -1,20 +1,16 @@
-// Channel lifecycle: which adapters are running, and where their sessions
-// live. Keeps main.ts wiring-only and gives the Console one call to apply a
-// config change.
+// Channel lifecycle: which adapters are running; one call for the Console to
+// apply a config change.
 import { logger } from "../log.js";
 import { LarkChannel } from "./lark.js";
 import { SlackChannel } from "./slack.js";
 import { TelegramChannel } from "./telegram.js";
-/** Platforms with an adapter, and what each needs before it can start. */
 const ADAPTERS = [
     { platform: "telegram", needsAppToken: false, build: (deps) => new TelegramChannel(deps) },
     { platform: "slack", needsAppToken: true, build: (deps) => new SlackChannel(deps) },
-    // Lark's "token" is the App ID and "appToken" the App Secret; the adapter
-    // needs both before it can start, same gate as Slack's two credentials.
+    // Lark's "token" is the App ID and "appToken" the App Secret.
     { platform: "lark", needsAppToken: true, build: (deps) => new LarkChannel(deps) },
 ];
-// Lifecycle news, which is not what the injected sink below is for: that one
-// is a warning sink the adapters share, and "slack started" is not a warning.
+// The injected sink is for warnings; "slack started" is not one.
 const log = logger("channels");
 // The parameter below shadows `log` inside its own default expression.
 const warn = (m) => log.warn(m);
@@ -32,10 +28,8 @@ export class ChannelRuntime {
         this.control = control;
         this.log = log;
     }
-    /** (Re)start every platform whose config says it should run. Idempotent.
-     *  Serialized — two concurrent Console saves raced into duplicate live
-     *  adapters; platforms restart in parallel so a hung start on one cannot
-     *  stall the other, and a failure is logged, never swallowed. */
+    /** Serialized: two concurrent Console saves would race into duplicate live
+     *  adapters. Platforms restart in parallel so a hung start cannot stall another. */
     reload() {
         const run = this.reloading.catch(() => { }).then(async () => {
             if (this.stopped)
@@ -55,24 +49,20 @@ export class ChannelRuntime {
         const existing = this.live.get(platform);
         if (existing) {
             this.live.delete(platform);
-            // Never fatal — the config still has to be applied — but a socket that
-            // refuses to close is exactly what makes the next start behave oddly.
+            // Never fatal: the config still has to be applied.
             await existing.stop().catch((err) => this.log(`${platform} did not stop cleanly: ${String(err)}`));
         }
         const config = this.store.get(platform);
         if (!config.enabled || !config.token)
             return;
         if (needsAppToken && !config.appToken) {
-            // Named, not silent: "enabled but nothing happens" is otherwise
-            // indistinguishable from a broken adapter.
+            // "Enabled but nothing happens" is indistinguishable from a broken adapter.
             this.log(`${platform}: enabled but no app token, not starting`);
             return;
         }
         const channel = build({
             store: this.store,
             log: (m) => this.log(`${platform}: ${m}`),
-            // The runtime owns the router, so channel control (stop, the settings
-            // panel) is wired here instead of widening the Channel seam.
             control: this.control,
         });
         try {
@@ -88,9 +78,8 @@ export class ChannelRuntime {
         this.live.set(platform, channel);
         log.info(`${platform} started`);
     }
-    /** Post a note into a conversation on a live adapter. Boot-time restart-note
-     *  delivery (src/drain.ts) has no session to report through; false means the
-     *  platform is not running, so the caller can say so instead of dropping it. */
+    /** For restart-note delivery (src/drain.ts), which has no session to report
+     *  through; false means the platform is not running. */
     async notify(platform, conversationId, text) {
         const channel = this.live.get(platform);
         if (!channel)
@@ -99,8 +88,8 @@ export class ChannelRuntime {
         return true;
     }
     async stop() {
-        // Join the reload queue first: an in-flight restart could otherwise
-        // register an adapter after `live` was cleared — running, unstoppable.
+        // An in-flight restart could otherwise register an adapter after `live`
+        // was cleared — running, unstoppable.
         this.stopped = true;
         await this.reloading.catch(() => { });
         for (const channel of this.live.values()) {

package/dist/channels/slack-api.js

@@ -1,37 +1,18 @@
-// Thin Slack client: HTTP shapes and the Socket Mode transport, no policy.
-// The one file in channels/ that talks to slack.com, so the adapter stays
-// testable against `SlackClient`.
-//
-// Socket Mode, not the Events API over HTTP: Pier is one local process and must
-// not require a public inbound URL. It needs two credentials — an app-level
-// token (`xapp-`) opens the socket, the bot token (`xoxb-`) signs every Web API
-// call — which is why ChannelConfig carries `appToken` beside `token`.
-//
-// No SDK: `apps.connections.open` plus Node's built-in WebSocket is the whole
-// protocol, and @slack/socket-mode would pull a dependency tree to wrap it.
+// Thin Slack client: HTTP shapes and the Socket Mode transport, no policy; the
+// one file that talks to slack.com. Socket Mode so Pier needs no public inbound
+// URL: the app-level token (`xapp-`) opens the socket, the bot token (`xoxb-`)
+// signs every Web API call. No SDK: `apps.connections.open` plus Node's
+// WebSocket is the whole protocol.
 import { readCapped } from "../core/inbox.js";
 const BASE = "https://slack.com/api";
-/**
- * Did Slack refuse the payload because of the *block* itself? The `markdown`
- * block is recent, so a workspace that predates it answers with one of these —
- * the signal to re-render the turn as legacy mrkdwn rather than to lose it.
- *
- * Slack has no capability API to ask up front, so the only detection is a
- * failed send. That makes the test's *narrowness* the whole safety property:
- * the caller latches the answer for the process, so anything matched here
- * degrades every later message too. `invalid_arguments` is deliberately NOT
- * matched even though avibe lists it — avibe retries per message, where a
- * broad match costs one fallback; latching turns the same breadth into a
- * permanent downgrade triggered by an unrelated bad argument (a malformed
- * `thread_ts` would silently cost the whole process its rendering). A wrong
- * call should surface as an error, not as a quieter renderer.
- */
+/** A workspace that predates the `markdown` block answers with one of these;
+ *  there is no capability API, so a failed send is the only detection. The
+ *  caller latches the answer for the process, so the match must stay narrow:
+ *  `invalid_arguments` is deliberately not matched — a malformed `thread_ts`
+ *  would otherwise permanently downgrade the renderer. */
 export const isBlockRejection = (err) => /invalid_blocks|unsupported_block_type/.test(String(err));
-/**
- * A connection that dies younger than this was a failed attempt, however it
- * ended: Slack answers "too many connections" by accepting the socket and
- * closing it straight away, which is not an error the loop would otherwise see.
- */
+/** Younger than this was a failed attempt: Slack answers "too many
+ *  connections" by accepting the socket and closing it straight away. */
 const MIN_CONNECTION_MS = 5000;
 const RECONNECT_FLOOR_MS = 1000;
 const RECONNECT_MAX_MS = 30_000;
@@ -42,20 +23,16 @@ export class SlackApi {
     openSocket;
     socketRunning = false;
     constructor(token, appToken, log = () => { }, 
-    /** Injected in tests; production opens a real WebSocket. */
+    /** Injected in tests. */
     openSocket = (url) => new WebSocket(url)) {
         this.token = token;
         this.appToken = appToken;
         this.log = log;
         this.openSocket = openSocket;
     }
-    /**
-     * Slack accepts a JSON body only on *write* methods. A read method
-     * (`users.info`, `conversations.info|history|replies`) silently ignores it and
-     * then reports the missing parameter — `users.info` answers `user_not_found`,
-     * which reads like "no such person" rather than "you sent the id in a place I
-     * do not look". So reads go form-encoded. This was worth four broken calls.
-     */
+    /** Slack accepts a JSON body only on write methods; a read method silently
+     *  ignores it and reports the parameter missing (`users.info` answers
+     *  `user_not_found`). So reads go form-encoded. */
     async read(method, params) {
         const form = new URLSearchParams();
         for (const [key, value] of Object.entries(params)) {
@@ -77,9 +54,8 @@ export class SlackApi {
             body: form ? payload.toString() : JSON.stringify(payload),
             signal: AbortSignal.timeout(30_000),
         });
-        // Slack answers a flood (a long turn split into chunks hits ~1 msg/s per
-        // channel) with the exact wait in a header. Obeying it once turns a dropped
-        // reply into a late one; a second 429 is a real problem and throws.
+        // A long turn split into chunks hits ~1 msg/s per channel; the header
+        // carries the exact wait. Obeyed once; a second 429 throws.
         if (res.status === 429 && retry) {
             const after = Number(res.headers.get("retry-after") ?? "1");
             if (Number.isFinite(after) && after <= 60) {
@@ -99,32 +75,26 @@ export class SlackApi {
         return { userId: body.user_id ?? "" };
     }
     // --- Socket Mode -----------------------------------------------------------
-    /**
-     * Reconnecting is part of the protocol, not the adapter's problem: Slack
-     * cycles a connection every few hours with `disconnect: refresh_requested`,
-     * so the loop reopens until `close()` clears the flag.
-     */
+    /** Slack cycles a connection every few hours with `disconnect:
+     *  refresh_requested`, so the loop reopens until `close()` clears the flag. */
     async connect(onEnvelope) {
         this.socketRunning = true;
         let socket;
         const run = async () => {
             let backoff = RECONNECT_FLOOR_MS;
             while (this.socketRunning) {
-                // Set once the socket exists, so a slow `apps.connections.open` cannot
-                // make a connection that died instantly look like a healthy one.
+                // Set once the socket exists, not before `apps.connections.open`.
                 let connectedAt = 0;
                 try {
                     const open = await this.call("apps.connections.open", {}, this.appToken);
                     if (!open.url)
                         throw new Error("apps.connections.open returned no url");
-                    // stop() may have landed while that call was in flight. Opening now
-                    // would leave a live socket nobody holds a reference to.
+                    // stop() may have landed while that call was in flight.
                     if (!this.socketRunning)
                         return;
                     socket = this.openSocket(open.url);
                     connectedAt = Date.now();
-                    // Resolves on close, never rejects: a dropped socket is normal and
-                    // the loop's job is to reopen it, not to treat it as an error.
+                    // Resolves on close, never rejects: a dropped socket is normal.
                     await new Promise((resolve) => {
                         const ws = socket;
                         ws.onmessage = (ev) => {
@@ -133,13 +103,11 @@ export class SlackApi {
                                 env = JSON.parse(String(ev.data));
                             }
                             catch {
-                                // Validate at the boundary: log and drop, never half-handle.
                                 this.log(`unparseable socket frame dropped`);
                                 return;
                             }
-                            // Ack first and always. Handling happens after, because a turn
-                            // outlives the deadline and Slack redelivers what it never saw
-                            // acknowledged.
+                            // Ack first: a turn outlives the deadline, and an unacked
+                            // envelope is redelivered.
                             if (env.envelope_id) {
                                 try {
                                     ws.send(JSON.stringify({ envelope_id: env.envelope_id }));
@@ -151,8 +119,6 @@ export class SlackApi {
                             if (env.type === "hello")
                                 return;
                             if (env.type === "disconnect") {
-                                // Expected: Slack recycles connections. Closing resolves the
-                                // promise below and the loop reopens.
                                 this.log(`socket disconnect (${env.reason ?? "no reason"}), reconnecting`);
                                 ws.close();
                                 return;
@@ -170,10 +136,7 @@ export class SlackApi {
                 }
                 if (!this.socketRunning)
                     return;
-                // The anti-spin floor. A socket that lived a while was healthy, so the
-                // next attempt starts from the floor again; one that died young — or
-                // threw — backs off, because reopening instantly would hammer
-                // apps.connections.open in a tight loop.
+                // A socket that lived a while was healthy; one that died young backs off.
                 if (connectedAt && Date.now() - connectedAt >= MIN_CONNECTION_MS) {
                     backoff = RECONNECT_FLOOR_MS;
                 }
@@ -219,7 +182,6 @@ export class SlackApi {
             await this.call("reactions.add", { channel, timestamp: ts, name });
         }
         catch (err) {
-            // The reaction is already where we want it; that is a success.
             if (!String(err).includes("already_reacted"))
                 throw err;
         }
@@ -249,7 +211,7 @@ export class SlackApi {
     }
     async page(method, params) {
         const body = await this.read(method, params);
-        // An empty cursor means "no more"; Slack sends `""` rather than omitting it.
+        // Slack sends `""` for "no more" rather than omitting it.
         const next = body.response_metadata?.next_cursor;
         return { messages: body.messages ?? [], nextCursor: next || undefined };
     }
@@ -267,26 +229,21 @@ export class SlackApi {
         return this.page("conversations.replies", {
             channel,
             ts,
-            // Slack drops the boundary message unless asked; the caller wants it and
-            // filters for itself, the same as `history` above.
+            // Slack drops the boundary message unless asked; the caller filters for itself.
             oldest: query.oldest,
             inclusive: true,
             limit: query.limit ?? 200,
             cursor: query.cursor,
         });
     }
-    /**
-     * Slack file URLs are private: they need the bot token as a bearer header and
-     * answer HTML (a login page) rather than an error when it is missing.
-     */
-    /** A read method, so form-encoded (see read()); `id` is the `F…` id. */
     async filesInfo(id) {
         const body = await this.read("files.info", { file: id });
-        // `ok` without a file would leave the caller downloading `undefined`.
         if (!body.file)
             throw new Error("slack files.info: no file in the response");
         return body.file;
     }
+    /** File URLs need the bot token as a bearer header, and answer HTML (a login
+     *  page) rather than an error without it. */
     async downloadFile(file, maxBytes) {
         const url = file.url_private_download ?? file.url_private;
         if (!url)
@@ -298,21 +255,13 @@ export class SlackApi {
         if (!res.ok)
             throw new Error(`slack file download: ${res.status}`);
         const mimeType = res.headers.get("content-type")?.split(";")[0] ?? file.mimetype ?? "application/octet-stream";
-        // Bounded mid-stream: the event's size metadata is the platform's word.
         return { bytes: await readCapped(res.body, maxBytes), mimeType };
     }
-    /**
-     * Three calls, because that is what Slack's current upload is: ask for a
-     * one-shot URL, POST the bytes to it (that host is not the Web API and
-     * answers with plain text, not JSON), then tell Slack where the file goes.
-     * `files.upload` did it in one, and is retired.
-     */
+    /** Three calls is Slack's current upload (`files.upload` is retired); the
+     *  upload host is not the Web API and answers plain text. */
     async uploadFile(channel, threadTs, file) {
-        // A read method: form-encoded, or Slack ignores the body (see read()).
         const slot = await this.read("files.getUploadURLExternal", { filename: file.name, length: file.bytes.length }).catch((err) => {
-            // An app installed before Pier could upload has every other scope, so
-            // this reads as a mysterious refusal in the chat. Name the fix instead:
-            // the manifest is only applied when an app is *created*.
+            // The manifest is only applied when an app is created; name the fix.
             if (!/missing_scope/.test(String(err)))
                 throw err;
             throw new Error("the Slack app is missing the files:write scope — add it under " +
@@ -324,8 +273,7 @@ export class SlackApi {
         const put = await fetch(slot.upload_url, {
             method: "POST",
             headers: { "content-type": "application/octet-stream" },
-            // Copied into a fresh view: a request body must be backed by an
-            // ArrayBuffer, and a Buffer read off disk is the wider ArrayBufferLike.
+            // A request body must be backed by an ArrayBuffer, not a Buffer's ArrayBufferLike.
             body: new Uint8Array(file.bytes),
             signal: AbortSignal.timeout(120_000),
         });

package/dist/channels/slack-directory.js

@@ -1,15 +1,7 @@
-// Who and where, cached: user display names and channel kind/name.
-//
-// Every inbound message needs the sender's name, and every transcript the tool
-// returns needs one per speaker — so without a cache this is one `users.info`
-// per message and per read. Neither answer changes in practice, so the cache is
-// process-lifetime and shared: the adapter and the agent-facing tool ask the
-// same instance, which is why a repeated `read_thread` costs no lookups at all.
-//
-// Failures are logged and fall back to the id, never swallowed: without
-// `users:read` this fails for every message, and the only symptom used to be an
-// agent telling the human "Slack does not expose your display name" — a scope
-// problem wearing a product problem's clothes.
+// User display names and channel kind/name, cached for the process and shared
+// by the adapter and the agent-facing tool. Failures fall back to the id and
+// are logged: without `users:read` every lookup fails, and the symptom is
+// otherwise a scope problem wearing a product problem's clothes.
 export class SlackDirectory {
     log;
     channels = new Map();
@@ -17,11 +9,8 @@ export class SlackDirectory {
     constructor(log) {
         this.log = log;
     }
-    /**
-     * Kind and display name together, because one `conversations.info` answers
-     * both. The event usually settles the kind for free (`channel_type`), and a
-     * `D`-prefixed id is always a DM — but only the lookup knows the name.
-     */
+    /** The event usually settles the kind for free (`channel_type`, or a
+     *  `D`-prefixed id); only the lookup knows the name. */
     async channel(api, channel, event) {
         const cached = this.channels.get(channel);
         if (cached)
@@ -31,8 +20,6 @@ export class SlackDirectory {
             : channel.startsWith("D")
                 ? "dm"
                 : undefined;
-        // A DM's name comes from its member, not from the channel, so a DM settled
-        // by the event needs no lookup at all.
         if (fromEvent === "dm") {
             const facts = { kind: fromEvent };
             this.channels.set(channel, facts);
@@ -42,8 +29,7 @@ export class SlackDirectory {
             this.log(`conversations.info failed for ${channel}: ${String(err)}`);
             return undefined;
         });
-        // Uncached on failure, so the next message retries rather than pinning a
-        // guess for the life of the process.
+        // Uncached on failure, so the next message retries.
         if (!info)
             return { kind: fromEvent ?? "group" };
         const facts = {
@@ -53,7 +39,6 @@ export class SlackDirectory {
         this.channels.set(channel, facts);
         return facts;
     }
-    /** Display name for a user id; the id itself when Slack will not say. */
     async user(api, userId) {
         const hit = this.users.get(userId);
         if (hit !== undefined)
@@ -65,7 +50,6 @@ export class SlackDirectory {
         this.users.set(userId, name);
         return name;
     }
-    /** Names for every speaker in a transcript, in one pass. */
     async names(api, userIds) {
         const out = new Map();
         for (const id of userIds) {