@timqi/pier 0.1.0 → 0.1.1

package/dist/channels/lark.js

@@ -1,25 +1,11 @@
 // Lark (Feishu) adapter: normalize long-connection events, render outbound
-// turns as cards.
-//
-// The anchor is threads, exactly as on Slack: Pier never posts into a chat's
-// main flow — a message in the chat is answered in *its own* topic
-// (`reply_in_thread`), a message inside a topic is answered there. So a
-// conversation is `<chatId>/<rootMessageId>`, the thread is the session, and
-// DMs follow the same rule (Feishu DMs thread; avibe verified it). Telegram's
-// `topicMode` toggle is meaningless here — there is no other behaviour.
-//
-// Four more things are Lark-specific and live only here:
-//  - Message bodies are JSON *strings* (`content` is double-encoded), and a
-//    mention is a `@_user_N` placeholder resolved through `mentions[]`.
-//  - Reactions are named keys: 👀 is `OnIt`, and removal is list-then-delete
-//    because the API deletes by reaction_id.
-//  - A card callback does not say which thread its message lives in, so every
-//    button's value carries the thread root (`LarkActionValue.root`).
-//  - Delivery is at-least-once and the transport acks only after the handler
-//    returns, so handlers queue work and return; `event_id` is deduplicated.
-//
-// Everything policy-shaped (mention/bind gates, per-chat overrides) is in
-// config.ts, platform-blind and shared with Telegram and Slack.
+// turns as cards. As on Slack, Pier never posts into a chat's main flow: a
+// conversation is `<chatId>/<rootMessageId>` (`reply_in_thread`; DMs thread
+// too). Lark-specific: `content` is a double-encoded JSON string and a mention
+// is a `@_user_N` placeholder resolved through `mentions[]`; 👀 is the reaction
+// key `OnIt`, removed by reaction_id; a card callback does not say which thread
+// its message lives in, so every button value carries the root; delivery is
+// at-least-once and acked when the handler returns, so handlers queue and return.
 import { saveInboundAll } from "../core/inbox.js";
 import { MAX_INBOUND_BYTES } from "../core/inbound-file.js";
 import { awaitsTurn } from "../core/reply.js";
@@ -35,21 +21,14 @@ import { CWD_SUBMIT_PREFIX, LarkPanel } from "./lark-panel.js";
 import { card, markdown, OFFER_PREFIX } from "./lark-render.js";
 import { PANEL_PREFIX } from "./panel.js";
 import { ReceiptLedger, Receipts } from "./receipts.js";
-/** Lark wants a named key here; 👀 has none, `OnIt` is its "being handled". */
 const WORKING = "OnIt";
-// Backpressure: bounds concurrency (downloads, API calls), not the backlog —
-// the event is already acked by the transport, so nothing slows the source.
+// The event is already acked, so this bounds concurrency, 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, against redelivery. */
 const DEDUP_TTL_MS = 5 * 60_000;
 const DEDUP_MAX = 2000;
-/**
- * A Lark conversation is always `<chatId>/<rootMessageId>` — 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 = (chatId, root) => `${chatId}/${root}`;
 export const parseConversation = (id) => {
     const at = id.indexOf("/");
@@ -57,31 +36,20 @@ export const parseConversation = (id) => {
         ? { chatId: id, root: "" }
         : { chatId: id.slice(0, at), root: id.slice(at + 1) };
 };
-/**
- * The thread a message belongs to. A message already in a topic keeps its
- * root; one posted in the chat becomes the root of its own — which is what
- * makes every request its own session without asking Lark for anything.
- */
+/** A message posted in the chat becomes the root of its own topic. */
 const threadOf = (msg) => msg.rootId || msg.messageId;
 export class LarkChannel {
     deps;
     id = "lark";
     api;
     log;
-    /** 👀 lifecycle, durable; see receipts.ts for why it is not just a Map. */
     receipts;
-    /** Ordering per chat, concurrency across them; see chains.ts. */
     chains;
-    /** The inbound gate and the bind-hint throttle; see gatekeeper.ts. */
     gate;
-    /** Event ids already handled, against 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;
-    /** User names, cached for the process — one contact lookup per person. */
     names = new Map();
-    /** Chats already reported to the store this process; a rename waits for a
-     *  restart, which is soon enough for a Console display label. */
     discovered = new Set();
     me = "";
     out;
@@ -98,7 +66,7 @@ export class LarkChannel {
         this.api = deps.client ?? new LarkApi(config.token, config.appToken, this.log);
         this.out = new LarkOutbound(this.api, this.log);
         this.receipts = new Receipts(
-        // Reaction removal needs the emoji key back, and Pier only applies one.
+        // Removal needs the emoji key back.
         {
             setReaction: (_chatId, messageId, emoji) => emoji
                 ? this.api.addReaction(messageId, emoji)
@@ -116,12 +84,10 @@ export class LarkChannel {
     async start(onMessage) {
         this.me = await this.api.botOpenId();
         if (!this.me) {
-            // Without our own open_id, "was I mentioned?" can only answer no, so
-            // every chat with require-mention on goes silent. Loud, not a debug line.
+            // Every chat with require-mention on goes silent; loud, not a debug line.
             this.log("bot info returned no open_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({
             onMessage: (event) => this.onEvent(event, onMessage),
@@ -135,16 +101,12 @@ export class LarkChannel {
         await this.chains.drain(DRAIN_TIMEOUT_MS);
     }
     // --- inbound ---------------------------------------------------------------
-    /**
-     * Already (about to be) acked by the transport — the SDK answers the frame
-     * when this returns, so routing is synchronous and the work is queued.
-     */
+    /** The SDK acks the frame when this returns, so routing is synchronous and
+     *  the work is queued. */
     onEvent(event, onMessage) {
         if (!this.running)
             return;
-        // Asked on every event, throttled inside receipts.ts.
         void this.receipts.sweep();
-        // Our own echo or another app's message.
         if (event.senderType === "app")
             return;
         if (this.seen.duplicate(event.eventId))
@@ -157,8 +119,6 @@ export class LarkChannel {
     onCardEvent(action, onMessage) {
         if (!this.running)
             return;
-        // A card callback carries its own event id; the composed key is the
-        // fallback for a payload that arrives without one.
         const dedupId = action.eventId ??
             `card:${action.messageId}:${action.operatorId}:${action.value?.key ?? action.name ?? ""}`;
         if (this.seen.duplicate(dedupId))
@@ -178,12 +138,12 @@ export class LarkChannel {
         if (!raw && !attachments.length && !mentioned)
             return;
         const isDm = msg.chatType === "p2p";
-        if (!this.discovered.has(msg.chatId)) {
+        if (!this.discovered.has(msg.chatId) && this.gate.mayDiscover({ isDm, userId: senderId })) {
             this.discovered.add(msg.chatId);
             const name = isDm
                 ? `DM · ${await this.userName(senderId)}`
                 : (await this.api.chatName(msg.chatId).catch((err) => {
-                    // Named, not silent: this failing usually means a missing scope.
+                    // Usually a missing scope.
                     this.log(`chat lookup failed for ${msg.chatId}: ${String(err)}`);
                     return undefined;
                 })) ?? msg.chatId;
@@ -194,9 +154,8 @@ export class LarkChannel {
             });
         }
         const text = raw.trim();
-        // A command aimed at another bot (`/stop@other`) is not ours to answer
-        // and travels on as ordinary text — Lark gives Pier no @username a target
-        // could positively match, so any target means "not us".
+        // Lark gives Pier no @username a command target could match, so any target
+        // means "not us".
         const parsed = parseCommand(text);
         const command = parsed?.target ? undefined : parsed;
         const root = threadOf(msg);
@@ -204,8 +163,7 @@ export class LarkChannel {
         const bindRequest = command?.name === "bind" && isDm;
         const admitted = this.gate.admit("message", msg.chatId, {
             isDm,
-            // Mentioned, or continuing a topic Pier already owns — Lark's
-            // equivalent of Telegram's "replying to the bot", durable so it still
+            // Mentioned, or continuing a topic Pier already owns — durable, so it
             // holds after a restart.
             addressed: mentioned || (!!msg.rootId && !!this.deps.control?.knows(here)),
             userId: senderId,
@@ -220,22 +178,18 @@ export class LarkChannel {
             return this.bind(senderId, msg.messageId, command?.args ?? "");
         if (command?.name === "stop")
             return this.abortTurn(here, msg.messageId);
-        // `@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 && !attachments.length && mentioned))) {
             return this.panel.open(here, msg.chatId, root);
         }
-        // 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(msg.messageId, attachments);
-        // Every await between mark() and dispatch is a window in which a previous
-        // turn can end and settle — taking this receipt with it before its own
-        // turn even starts — so the name is resolved first and the mark→dispatch
-        // pair stays synchronous.
+        // 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: senderId, name: await this.userName(senderId) };
         this.receipts.mark(here.conversationId, msg.chatId, msg.messageId);
-        // 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 topic.
+        // Steer: a follow-up is the wrong default when the human is watching a 👀.
         onMessage({
             key: here,
             senderId,
@@ -244,11 +198,8 @@ export class LarkChannel {
             mode: "steer",
         });
     }
-    /**
-     * One message's readable content: text with mentions resolved, attachments
-     * to fetch, and whether the bot was addressed. `content` is a JSON string;
-     * malformed or unreadable types are logged and dropped at this boundary.
-     */
+    /** `content` is a JSON string; malformed or unreadable types are logged and
+     *  dropped at this boundary. */
     readContent(msg) {
         let content = {};
         try {
@@ -278,8 +229,7 @@ export class LarkChannel {
             case "media":
             case "audio":
                 if (content.file_key) {
-                    // `file_size` is optional and sometimes a numeric string; a missing
-                    // one is fine — download() enforces the cap mid-stream regardless.
+                    // `file_size` is optional and sometimes a numeric string.
                     const size = Number(content.file_size);
                     attachments.push({
                         key: String(content.file_key),
@@ -292,9 +242,8 @@ export class LarkChannel {
             default:
                 this.log(`ignored message type ${msg.messageType ?? "?"}`);
         }
-        // A mention arrives as a `@_user_N` placeholder: the bot's own is
-        // addressing, not content, and is removed; anyone else's becomes their
-        // name, so the agent sees who was meant.
+        // The bot's own placeholder is addressing and is removed; anyone else's
+        // becomes their name.
         let mentioned = false;
         for (const mention of msg.mentions ?? []) {
             const isMe = !!this.me && mention.id?.open_id === this.me;
@@ -303,11 +252,8 @@ export class LarkChannel {
         }
         return { text, attachments, mentioned };
     }
-    /** Rich text: the readable runs, and any images embedded in it. */
     readPost(raw) {
-        // A post body may arrive wrapped in a locale (`{zh_cn: {title, content}}`)
-        // rather than flat — both shapes are real. Take the flat body when it is
-        // one, else the first locale entry that is an object.
+        // A post body may arrive flat or wrapped in a locale (`{zh_cn: {title, content}}`).
         const content = Array.isArray(raw.content) || typeof raw.title === "string"
             ? raw
             : (Object.values(raw).find((v) => !!v && typeof v === "object" && !Array.isArray(v)) ??
@@ -326,9 +272,8 @@ export class LarkChannel {
                 if (run.tag === "text" || run.tag === "a")
                     parts.push(String(run.text ?? ""));
                 else if (run.tag === "at") {
-                    // Inline, not a `@_user_N` placeholder: rich text carries the at run
-                    // itself. The bot's own is addressing (detected via `mentions[]`),
-                    // not content; anyone else's becomes their name.
+                    // Rich text carries the at run inline, not as a placeholder; the
+                    // bot's own is detected via `mentions[]`.
                     if (run.user_id !== this.me)
                         parts.push(`@${run.user_name ?? run.user_id ?? "?"}`);
                 }
@@ -343,9 +288,8 @@ export class LarkChannel {
     }
     // --- card actions ------------------------------------------------------------
     async onAction(action, onMessage) {
-        // The thread root travels in the button payload (a callback does not say
-        // which topic its message lives in); a form submit carries it in the
-        // button's name. Absent both, the payload is not one Pier minted.
+        // A form submit carries the root in the button's name instead of the
+        // value. Absent both, the payload is not one Pier minted.
         const payload = action.value?.key ?? "";
         const formRoot = action.name?.startsWith(CWD_SUBMIT_PREFIX)
             ? action.name.slice(CWD_SUBMIT_PREFIX.length)
@@ -370,18 +314,15 @@ export class LarkChannel {
             await this.panel?.onCwdSubmit(key, action, root);
             return;
         }
-        // Panel clicks are namespaced `cfg:` and never reach the agent.
         if (payload.startsWith(PANEL_PREFIX)) {
             if (!(await this.panel?.onAction(action, key, payload, root))) {
                 this.log(`panel action ${payload} with no panel wired, dropped`);
             }
             return;
         }
-        // A next-step button. The label travels in the value the platform echoes
-        // back — the only durable place, since Lark cannot return a 2.0 card
-        // (LarkActionValue documents the probe) — so a click needs no adapter
-        // state and survives a restart. A value without one is a stale card from
-        // before this convention, and the user clicked expecting something.
+        // The label travels in the echoed value (Lark cannot return a 2.0 card;
+        // see LarkActionValue), so a click survives a restart. A value without
+        // one is a stale card, and the user clicked expecting something.
         const label = payload.startsWith(OFFER_PREFIX) && typeof action.value?.label === "string"
             ? action.value.label
             : undefined;
@@ -391,10 +332,8 @@ export class LarkChannel {
                 .catch((err) => this.log(`stale-option notice failed: ${String(err)}`));
             return;
         }
-        // The taken row comes off (best-effort; see LarkOutbound.retire), and the
-        // pick is echoed — a bot cannot post as the user, so without the echo the
-        // topic shows an answer to a request nobody can see being made, and there
-        // is nothing to carry the eyes.
+        // A bot cannot post as the user, so the pick is echoed: otherwise the
+        // topic shows an answer to a request nobody can see, with nothing to carry the eyes.
         const sender = { id: action.operatorId, name: await this.userName(action.operatorId) };
         await this.out.retire(action.messageId);
         const echo = await this.api.replyCard(root, card([markdown(picked(label))]))
@@ -413,20 +352,14 @@ export class LarkChannel {
             mode: "steer",
         });
     }
-    /**
-     * 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, messageId) {
         await this.deps.control?.abort(key);
         await this.api.replyCard(messageId, card([markdown(STOPPED)]));
     }
     // --- bind ------------------------------------------------------------------
-    /**
-     * Tell an unbound DM sender what to do. Groups stay silent (see gate()),
-     * but a DM that swallows every message looks broken rather than locked.
-     */
+    /** Groups stay silent, but a DM that swallows every message looks broken
+     *  rather than locked. */
     async hintBind(userId, messageId) {
         if (!this.gate.mayHint(userId))
             return;
@@ -435,8 +368,8 @@ export class LarkChannel {
     }
     async bind(userId, messageId, code) {
         const name = await this.userName(userId);
-        const ok = this.deps.store.redeemBindCode("lark", code, { id: userId, name });
-        await this.api.replyCard(messageId, card([markdown(bindResult(ok, name))]));
+        const outcome = this.deps.store.redeemBindCode("lark", code, { id: userId, name });
+        await this.api.replyCard(messageId, card([markdown(bindResult(outcome, name))]));
     }
     // --- lookups ---------------------------------------------------------------
     async userName(openId) {
@@ -444,17 +377,12 @@ export class LarkChannel {
         if (hit)
             return hit;
         const name = await this.api.userName(openId).catch((err) => {
-            // The id is the honest fallback label; the reason still gets said.
             this.log(`user lookup failed for ${openId}: ${String(err)}`);
             return openId;
         });
         this.names.set(openId, name);
         return name;
     }
-    /** The message's attachments as the shared save loop wants them (the loop
-     *  itself, size gate and lost markers included, is core/inbox.ts; the
-     *  mid-stream refusal in download() names "too large" so the loop's marker
-     *  stays honest when the metadata lied by omission). */
     saveAttachments(messageId, files) {
         return saveInboundAll(this.id, files.map((file) => ({
             label: file.name ?? "attachment",
@@ -465,34 +393,20 @@ export class LarkChannel {
         })), 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 { root } = parseConversation(conversation);
-        // Every id this adapter mints carries a thread root, so an empty one is a
-        // corrupted or foreign conversation id. Posting it would put an agent
-        // turn in the chat'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 root is a foreign id; posting it would put a turn in the chat's main
+        // flow. Refused loudly, receipts still cleared.
         if (!root) {
             this.log(`refusing to answer ${conversation}: no thread root 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(root, reply));
+        // The turn ended either way; a 👀 left up by a failed send looks like work.
+        await this.receipts.settleAfter(conversation, () => this.out.reply(root, 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 topic 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 { chatId, root } = parseConversation(conversation);
         if (!root) {
@@ -500,9 +414,6 @@ export class LarkChannel {
             return;
         }
         const messageId = await this.out.note(root, note);
-        // The last card of a long note, so the eyes sit at the foot of the topic,
-        // 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 (messageId && awaitsTurn(note.origin))
             this.receipts.mark(conversation, chatId, messageId);
     }

package/dist/channels/lines.js

@@ -1,19 +1,17 @@
-// What the shared control moments say — one spelling for three platforms.
-//
-// Bind, stop and the option echo behave identically everywhere by contract,
-// and their lines were copied per adapter until Lark made three of each; the
-// same wording drifting apart is how the panels went (see panel.ts). How a
-// line is *sent* stays with the adapter; the only legitimate variation is the
-// spelling of the bind command, so it is the parameter.
-/** DM-only, throttled by Gatekeeper.mayHint; groups stay silent by contract. */
+// What the shared control moments say — one spelling for three platforms. The
+// only legitimate variation is the spelling of the bind command, so it is the parameter.
 export const bindHint = (command) => `You are not bound yet. Ask the operator for a bind code, then send ${command}.`;
-/** The answer to a bind attempt. The name arrives escaped by the caller. */
-export const bindResult = (ok, name) => ok ? `Bound as ${name}.` : "That bind code is invalid or expired.";
-/** Acknowledges /stop; the turn's own end still arrives through send(). */
+/** The name arrives escaped by the caller. */
+export const bindResult = (outcome, name) => {
+    if (outcome === "bound")
+        return `Bound as ${name}.`;
+    return outcome === "voided"
+        ? "That bind code is invalid or expired — and too many wrong tries have now" +
+            " voided it. Ask the operator for a new one."
+        : "That bind code is invalid or expired.";
+};
 export const STOPPED = "\u23f9 Stopped.";
-/** A picked option, echoed because a bot cannot post as the user. */
+/** Echoed because a bot cannot post as the user. */
 export const picked = (label) => `\u25b8 ${label}`;
-/** A click on options that are gone — retired, or from before this process'
- *  conventions. Said in the chat: the person clicked and would otherwise see
- *  nothing happen, which reads as broken (5b). */
+/** Said in the chat: the person clicked and would otherwise see nothing happen (§5). */
 export const STALE_OPTION = "⚠ That option is no longer available — please type the choice instead.";

package/dist/channels/panel.js

@@ -1,21 +1,9 @@
-// The in-chat settings panel, minus the platform.
-//
-// One message edited in place — a new message per tap would bury the chat.
-// Every payload is namespaced `cfg:` and consumed here, so a panel tap can
-// never be mistaken for one of the agent's next-step buttons (whose payload is
-// the label itself) and never reaches the agent. Choices travel as an index
-// rather than a name: Telegram's callback data caps at 64 bytes, and an index
-// cannot be invalidated by a label someone rewrote.
-//
-// What is left to a platform is markup, how its one message is sent, edited
-// and deleted, and how it asks for a single typed answer — Slack has modals,
-// Telegram has a forced reply. Everything above that is the same panel, so it
-// is written once here.
+// The in-chat settings panel, minus the platform: one message edited in place,
+// every payload namespaced `cfg:` so a tap never reaches the agent. Choices
+// travel as an index: Telegram's callback data caps at 64 bytes.
 import { compact, thinkingLabel } from "../core/reply.js";
 export const PANEL_PREFIX = "cfg:";
 const MODELS_PER_PAGE = 8;
-/** The cwd prompt's one sentence and placeholder — each platform owns only
- *  its widget's lead-in ("Reply with…", a modal hint, a form label). */
 export const CWD_TAIL = "A new session starts there; the current one stays in its own directory.";
 export const CWD_PLACEHOLDER = "/path/to/project";
 const onOff = (v) => (v ? "on" : "off");
@@ -40,7 +28,6 @@ export class ChatPanel {
         return this.panels.get(key.conversationId);
     }
     // --- rendering ---------------------------------------------------------------
-    /** The panel proper: this session, this chat, and what can be done to them. */
     async view(key, chatId) {
         const status = await this.deps.control.status(key);
         return {
@@ -51,8 +38,6 @@ export class ChatPanel {
                         ? this.sessionLines(status)
                         : ["None yet — send a message to start one."],
                 },
-                // Slack calls it a channel, Telegram a chat; the panel says what the
-                // person reading it says.
                 {
                     title: this.platform === "slack" ? "Channel" : "Chat",
                     lines: this.chatLines(chatId),
@@ -90,7 +75,6 @@ export class ChatPanel {
             : `mention ${onOff(policy.requireMention)} · bind ${onOff(policy.requireBind)}${this.gateExtras(chat, policy)}`;
         return [`${this.esc(chat.name || chatId)} · ${chat.kind} · ${this.code(chatId)}`, gates];
     }
-    /** Redraw the panel this conversation owns. */
     async refresh(key, note) {
         const state = this.state(key);
         if (!state)
@@ -98,14 +82,8 @@ export class ChatPanel {
         await this.draw(state, await this.view(key, state.chatId), note);
     }
     // --- actions -----------------------------------------------------------------
-    /**
-     * Handle a `cfg:` payload. Returns false when it is not ours, so the caller
-     * can treat it as one of the agent's next-step labels instead.
-     *
-     * `reopen` is how a panel left behind by a previous process recovers: its
-     * state died with that process, and redrawing from the platform's own copy
-     * of the message is the only honest answer. It costs one tap.
-     */
+    /** Returns false when the payload is not ours. `reopen` recovers a panel
+     *  whose state died with a previous process; it costs one tap. */
     async dispatch(key, payload, ctx, reopen) {
         if (!payload.startsWith(PANEL_PREFIX))
             return false;
@@ -157,7 +135,14 @@ export class ChatPanel {
         const state = this.state(key);
         if (!state)
             return;
-        state.models = await this.deps.control.models().catch(() => []);
+        // An empty list and a catalog that could not be read are two different
+        // answers; the second must not draw as the first.
+        let unavailable;
+        state.models = await this.deps.control.models().catch((err) => {
+            unavailable = `Could not list models: ${String(err)}`;
+            this.deps.log(unavailable);
+            return [];
+        });
         const status = await this.deps.control.status(key);
         const pages = Math.max(1, Math.ceil(state.models.length / MODELS_PER_PAGE));
         const at = Math.min(Math.max(page, 0), pages - 1);
@@ -166,7 +151,7 @@ export class ChatPanel {
             groups: [{
                     title: "Model",
                     suffix: ` · page ${at + 1}/${pages}`,
-                    lines: state.models.length ? [] : ["No models with configured auth."],
+                    lines: state.models.length ? [] : [unavailable ?? "No models with configured auth."],
                 }],
             picks: slice.map((model, i) => {
                 const current = status?.model?.provider === model.provider && status.model.id === model.id;
@@ -210,15 +195,10 @@ export class ChatPanel {
         await this.deps.control.setThinking(key, level);
         await this.refresh(key, `Reasoning set to ${thinkingLabel(level)}.`);
     }
-    /**
-     * The one action that is not reversible in place: Pi fixes cwd at session
-     * creation, so "change the working directory" *is* "start a new session
-     * there". Shared because both platforms have to say so and handle the same
-     * two failures.
-     */
+    /** Pi fixes cwd at session creation, so "change the working directory" *is*
+     *  "start a new session there". */
     async startSessionIn(key, path) {
         if (!path.startsWith("/")) {
-            // A silent no-op here reads as "the button is broken".
             const error = "That is not an absolute path — nothing changed.";
             await this.refresh(key, error);
             return { error };