@timqi/pier 0.0.29 → 0.1.1

package/dist/channels/telegram.js

@@ -1,16 +1,7 @@
 // Telegram adapter: normalize inbound updates, render outbound turns.
-//
-// Three behaviours are Telegram-specific and live only here:
-//  - Topic mode. A message that lands in a forum group's General opens a fresh
-//    topic named after its first line, and the conversation (hence the Pi
-//    session) is that topic. One group therefore hosts many parallel sessions.
-//  - Reaction receipts. Intermediate reasoning is never posted to IM; instead
-//    every message that entered a turn wears 👀 until the turn settles, so a
-//    steered message gets feedback without a line in the chat.
-//  - Bind. `/bind <code>` in a DM redeems a Console-issued code.
-//
-// Everything policy-shaped (mention/bind gates, per-chat overrides) is in
-// config.ts, platform-blind and shared with the adapters still to come.
+// Telegram-specific: topic mode, where a message in a forum group's General
+// opens a topic that becomes the session; 👀 receipts on every message that
+// entered a turn; `/bind <code>` in a DM.
 import { awaitsTurn, formatTurnMeta, isSilentReply, originLabel, quietLabel } from "../core/reply.js";
 import { saveInboundAll } from "../core/inbox.js";
 import { MAX_INBOUND_BYTES } from "../core/inbound-file.js";
@@ -26,20 +17,13 @@ import { chunk, escapeHtml, keyboard, offeredLabel, toTelegramHtml } from "./tel
 import { TelegramApi, } from "./telegram-api.js";
 const WORKING = "👀";
 const POLL_SECONDS = 30;
-// Backpressure: how many chats may be mid-handling before the poll loop waits.
-// Bounds memory without ever advancing the offset past what we accepted.
+// The poll loop waits here without advancing the offset past what it accepted.
 const MAX_ACTIVE_CHATS = 16;
-// Longest a 👀 may sit before we assume its turn will never settle (a dispatch
-// that failed, a session that died). Generous: a real coding turn can be long.
+// Generous: a real coding turn can be long.
 const RECEIPT_STALE_MS = 30 * 60_000;
-// Longest stop() waits for in-flight handlers before letting reload() proceed.
 const DRAIN_TIMEOUT_MS = 5000;
 const TOPIC_TITLE_MAX = 60;
-/**
- * A forum conversation is `<chatId>/<topicId>`; anything else is `<chatId>`.
- * This pair is the only definition of the format — control.ts and the panel
- * decode with it rather than splitting on "/" themselves.
- */
+/** `<chatId>/<topicId>` or `<chatId>`; the only definition of the format. */
 const conversationId = (chatId, topicId) => topicId ? `${chatId}/${topicId}` : String(chatId);
 export const parseConversation = (id) => {
     const [chatId = "", topic] = id.split("/");
@@ -59,13 +43,10 @@ export class TelegramChannel {
     id = "telegram";
     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;
-    /** The in-chat settings panel; absent when no control was wired (tests). */
+    /** Absent when no control was wired (tests). */
     panel;
     me;
     offset;
@@ -74,14 +55,11 @@ export class TelegramChannel {
         this.deps = deps;
         this.api = deps.client ?? new TelegramApi(deps.store.get("telegram").token);
         this.log = deps.log ?? ((m) => logger("telegram").warn(m));
-        // No cap here: the poll loop applies backpressure itself, before advancing
-        // the ack cursor past an update it has not accepted.
+        // No cap: the poll loop applies backpressure itself.
         this.chains = new Chains(this.log);
         this.gate = new Gatekeeper(deps.store, "telegram", this.log);
         this.receipts = new Receipts(
-        // The ledger keeps message ids as opaque strings (a Slack ts is not a
-        // number); Telegram's own are numeric, so the cast happens right here at
-        // the API boundary rather than leaking a platform's id type into shared code.
+        // The ledger keeps message ids as opaque strings (a Slack ts is not a number).
         { setReaction: (chatId, messageId, emoji) => this.api.setReaction(chatId, Number(messageId), emoji) }, deps.receipts ?? new ReceiptLedger("telegram"), this.log, WORKING, RECEIPT_STALE_MS);
         if (deps.control) {
             this.panel = new TelegramPanel({
@@ -96,35 +74,30 @@ export class TelegramChannel {
         const me = await this.api.getMe();
         this.me = { id: me.id, username: me.username ?? "" };
         if (!this.me.username) {
-            // Without a handle, "was I mentioned?" can only ever answer no, so every
-            // group with require-mention on goes silent. Loud, not a debug line.
+            // Every group with require-mention on goes silent; loud, not a debug line.
             this.log("bot has no username: mention detection is disabled");
         }
         this.running = true;
-        // Best-effort and off the critical path.
         void this.receipts.sweep(true);
         void this.poll(onMessage);
     }
     async stop() {
         this.running = false;
-        // Let in-flight updates finish: reload() starts a replacement right after,
-        // and two adapters handling one message would prompt the session twice.
-        // Bounded, because reload() runs on the Console's save request — a stuck
-        // handler must not hold that open.
+        // reload() starts a replacement right after; two adapters handling one
+        // message would prompt the session twice. Bounded: a stuck handler must not
+        // hold the Console's save request open.
         await this.chains.drain(DRAIN_TIMEOUT_MS);
     }
     // --- inbound ---------------------------------------------------------------
     async poll(onMessage) {
         while (this.running) {
             try {
-                // Floor on an empty round trip: getUpdates is supposed to block for
-                // POLL_SECONDS, and a proxy that answers instantly would otherwise
-                // turn this into a hot loop.
+                // Floor on an empty round trip: a proxy that answers instantly would
+                // otherwise turn the long poll into a hot loop.
                 const startedAt = Date.now();
                 const updates = await this.api.getUpdates(this.offset, POLL_SECONDS);
                 if (!this.running)
                     return;
-                // Asked on every round trip, throttled inside receipts.ts.
                 void this.receipts.sweep();
                 if (!updates.length && Date.now() - startedAt < 1000) {
                     await new Promise((r) => setTimeout(r, 1000));
@@ -169,10 +142,11 @@ export class TelegramChannel {
         const isDm = msg.chat.type === "private";
         const kind = isDm ? "dm" : msg.chat.is_forum ? "forum" : "group";
         const name = msg.chat.title ?? [msg.from.first_name, msg.from.last_name].filter(Boolean).join(" ");
-        this.deps.store.discoverChat("telegram", { id: chatId, name: name || chatId, kind });
+        if (this.gate.mayDiscover({ isDm, userId: String(msg.from.id) })) {
+            this.deps.store.discoverChat("telegram", { id: chatId, name: name || chatId, kind });
+        }
         const text = this.stripMention(raw);
         const command = parseCommand(text);
-        // A command aimed at another bot in the same group is not ours to answer.
         const mine = !command?.target || command.target.toLowerCase() === this.me?.username.toLowerCase();
         const bindRequest = mine && command?.name === "bind" && isDm;
         const admitted = this.gate.admit("message", chatId, {
@@ -194,35 +168,31 @@ export class TelegramChannel {
             channelId: this.id,
             conversationId: conversationId(chatId, msg.message_thread_id),
         };
-        // A typed answer to the panel's directory prompt, not a prompt for the agent.
         if (await this.panel?.consumeCwdReply(msg, here))
             return;
-        // `@bot` on its own (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 && mine && (command?.name === "settings" || (!text && !msg.photo?.length && !msg.document))) {
             return this.panel.open(here, chatId, msg.message_thread_id);
         }
-        // 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);
         const topicId = await this.routeTopic(msg, text);
         const key = { channelId: this.id, conversationId: conversationId(chatId, topicId) };
         this.receipts.mark(key.conversationId, chatId, String(msg.message_id));
-        // 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 chat window.
+        // Steer: a follow-up is the wrong default when the human is watching a 👀.
         onMessage({
             key,
             senderId: String(msg.from.id),
-            // A group is many people talking into one session; the update already
-            // carries the name, so no lookup is needed here.
             sender: { id: String(msg.from.id), name: senderName(msg.from) },
             text: [text, ...markers].filter(Boolean).join("\n"),
             mode: "steer",
         });
     }
-    /** Quick-reply buttons send their own label back as an ordinary message. */
     async onCallback(query, onMessage) {
-        await this.api.answerCallbackQuery(query.id).catch(() => { });
+        // Unanswered, the tapped button keeps its spinner until Telegram gives up.
+        await this.api.answerCallbackQuery(query.id)
+            .catch((err) => this.log(`callback ack failed: ${String(err)}`));
         const msg = query.message;
         if (!msg || !query.data)
             return;
@@ -238,14 +208,12 @@ export class TelegramChannel {
             channelId: this.id,
             conversationId: conversationId(chatId, msg.message_thread_id),
         };
-        // Panel taps are namespaced `cfg:` and never reach the agent.
         if (await this.panel?.onCallback(query, key))
             return;
         const text = offeredLabel(msg, query.data);
         if (text === undefined) {
-            // Said in the chat, not as a second answerCallbackQuery: a query may be
-            // answered exactly once, and the toast already went to the ack above —
-            // against the real API the second answer is silently dropped.
+            // A callback query may be answered exactly once, and the ack above was
+            // it; a second answer is silently dropped.
             await this.api.sendMessage({
                 chat_id: chatId,
                 message_thread_id: msg.message_thread_id,
@@ -253,17 +221,10 @@ export class TelegramChannel {
             }).catch((err) => this.log(`stale-option notice failed: ${String(err)}`));
             return;
         }
-        // The options belonged to the turn that just ended; once one is taken the
-        // rest answer a question the conversation has moved past (the web drops
-        // them for the same reason).
-        await this.api.clearKeyboard(chatId, msg.message_id).catch(() => { });
-        // A bot cannot post as the user, so the pick is echoed and marked as one.
-        // Without it the chat shows an answer to a request nobody can see being
-        // made, and there is no message of the user's to carry the eyes.
-        //
-        // No reply quote: the marker already says what this is, and quoting a long
-        // answer to show which of its buttons was tapped costs more space than it
-        // explains.
+        await this.api.clearKeyboard(chatId, msg.message_id)
+            .catch((err) => this.log(`retiring options failed: ${String(err)}`));
+        // A bot cannot post as the user, so the pick is echoed: otherwise the chat
+        // shows an answer to a request nobody can see, with nothing to carry the eyes.
         const echo = await this.api.sendMessage({
             chat_id: chatId,
             message_thread_id: msg.message_thread_id,
@@ -273,17 +234,11 @@ export class TelegramChannel {
             this.log(`option echo failed: ${String(err)}`);
             return undefined;
         });
-        // The receipt goes on the echo, not on the bot message that held the
-        // buttons: the eyes mean "this input is being worked on".
         if (echo)
             this.receipts.mark(key.conversationId, chatId, String(echo.message_id));
         onMessage({ key, senderId: String(query.from.id), text, 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(msg) {
         const key = {
             channelId: this.id,
@@ -296,10 +251,8 @@ export class TelegramChannel {
             text: STOPPED,
         });
     }
-    /**
-     * 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(msg) {
         if (!this.gate.mayHint(String(msg.from?.id ?? "")))
             return;
@@ -311,23 +264,16 @@ export class TelegramChannel {
     async bind(msg, code) {
         const user = msg.from;
         const name = senderName(user);
-        const ok = this.deps.store.redeemBindCode("telegram", code, { id: String(user.id), name });
+        const outcome = this.deps.store.redeemBindCode("telegram", code, { id: String(user.id), name });
         await this.api.sendMessage({
             chat_id: msg.chat.id,
-            text: bindResult(ok, name),
+            text: bindResult(outcome, name),
         });
     }
-    /**
-     * Topic mode: a message arriving in a forum group's General starts a new
-     * topic, so every request gets its own thread and its own Pi session. A
-     * reply or a slash command stays put — it is continuing something, not
-     * starting it. Failure falls back to the current thread rather than losing
-     * the message.
-     */
+    /** A reply or a command stays put; failure falls back to the current thread. */
     async routeTopic(msg, text) {
-        // Every reason to decline is named and logged: "why did it not open a
-        // topic" is the question this feature will be asked forever, and silence
-        // makes six invisible conditions indistinguishable from a bug.
+        // Every reason to decline is logged: six invisible conditions are
+        // indistinguishable from a bug.
         const decline = !this.deps.store.policy("telegram", String(msg.chat.id)).topicMode
             ? "topic mode off for this chat"
             : msg.chat.type !== "supergroup"
@@ -348,15 +294,14 @@ export class TelegramChannel {
         const title = topicTitle(text);
         try {
             const topic = await this.api.createForumTopic(msg.chat.id, title);
-            // The whole point of the notice is to get out of General, so the title is
-            // the link into the new topic rather than decoration.
             await this.api.sendMessage({
                 chat_id: msg.chat.id,
                 text: `→ <a href="${topicLink(msg.chat, topic.message_thread_id)}">${escapeHtml(title)}</a>`,
                 parse_mode: "HTML",
                 message_thread_id: msg.message_thread_id,
                 reply_to_message_id: msg.message_id,
-            }).catch(() => { });
+                // Without the pointer, General shows a question whose answer went elsewhere.
+            }).catch((err) => this.log(`topic pointer failed: ${String(err)}`));
             return topic.message_thread_id;
         }
         catch (err) {
@@ -364,10 +309,8 @@ export class TelegramChannel {
             return msg.message_thread_id;
         }
     }
-    /** The message's attachments as the shared save loop wants them (the loop
-     *  itself, size gate and lost markers included, is core/inbox.ts). */
     saveAttachments(msg) {
-        // Telegram sends a photo as a size ladder — the last entry is the largest.
+        // A photo is a size ladder; the last entry is the largest.
         const photo = msg.photo?.at(-1);
         const doc = msg.document;
         return saveInboundAll(this.id, [
@@ -375,7 +318,7 @@ export class TelegramChannel {
                     label: "photo",
                     mimeType: "image/jpeg",
                     size: photo.file_size,
-                    // Telegram only learns a filename from getFile, so the fetch's wins.
+                    // A filename comes only from getFile, so the fetch's wins.
                     fetch: async () => this.api.downloadFile(photo.file_id, MAX_INBOUND_BYTES),
                 }] : []),
             ...(doc ? [{
@@ -388,7 +331,6 @@ export class TelegramChannel {
         ], this.log);
     }
     // --- addressing ------------------------------------------------------------
-    /** Mentioned, replying to the bot, or a slash command aimed at this bot. */
     addressed(text, msg) {
         if (msg.reply_to_message?.from?.id === this.me?.id)
             return true;
@@ -399,7 +341,6 @@ export class TelegramChannel {
         const handle = `@${this.me?.username.toLowerCase()}`;
         return !!this.me?.username && text.toLowerCase().includes(handle);
     }
-    /** A leading @bot is addressing, not content — the agent should not see it. */
     stripMention(text) {
         const handle = `@${this.me?.username ?? ""}`;
         if (!this.me?.username)
@@ -409,31 +350,20 @@ export class TelegramChannel {
             : text;
     }
     // --- 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 { chatId, topicId } = parseConversation(conversation);
-        // A file the agent linked is local to this machine, so the link is dead in
-        // Telegram: the bytes are uploaded instead and the label stays in the text.
+        // A local file link is dead in Telegram: the bytes are uploaded instead.
         const { text: spoken, paths } = splitAttachments(reply.text);
         const text = spoken.trim();
-        // A turn that produced no text still posts its footer, and says which kind
-        // of nothing it was: total silence is indistinguishable from a crash, and
-        // the person waiting cannot tell. See AGENTS.md — an empty turn is still an
-        // event, and an event nobody can see is not observable.
+        // An empty turn still posts its footer and says which kind of nothing (§5).
         const buttons = keyboard(reply.suggestions);
         const quiet = isSilentReply(reply)
             ? `<i>${quietLabel(reply.silence && escapeHtml(reply.silence))}</i>`
             : "";
-        // A turn that is only its options still has to carry them: with no text,
-        // no silence marker and no meta the body is empty, and a keyboard cannot
-        // ride a message that was never sent — so it gets the smallest one.
+        // A keyboard cannot ride a message that was never sent.
         const body = ((text ? toTelegramHtml(text) : quiet) + turnFooter(reply.meta)) ||
             (buttons ? "…" : "");
-        // settleAfter: a 👀 left up because the reply failed would sit there until
-        // the stale sweep, looking like the agent is still working.
+        // A 👀 left up by a failed send looks like work until the stale sweep.
         await this.receipts.settleAfter(conversation, async () => {
             if (body.trim()) {
                 const parts = chunk(body);
@@ -443,13 +373,10 @@ export class TelegramChannel {
                         message_thread_id: topicId,
                         text: part,
                         parse_mode: "HTML",
-                        // Next-step buttons ride the last chunk; a click sends the label.
                         reply_markup: i === parts.length - 1 ? buttons : undefined,
                     });
                 }
             }
-            // Attachments follow the words, so the message that introduces them is
-            // above them; anything that could not be sent says so in the chat.
             const lost = await sendAttachments(paths, (file) => this.api.sendFile({ chat_id: chatId, message_thread_id: topicId, file }), this.log);
             if (lost) {
                 await this.api.sendMessage({
@@ -459,18 +386,10 @@ export class TelegramChannel {
                     parse_mode: "HTML",
                 });
             }
-        });
+        }, reply.meta);
     }
-    /**
-     * A system note: quoted, labelled with where it came from, and deliberately
-     * plain — no buttons and no turn footer, because the turn this input triggers
-     * has not ended yet.
-     *
-     * That turn has no message of the user's to carry the 👀 — nobody typed one —
-     * so the note wears them, on its last chunk, until the turn-end `send`
-     * clears it. An error note is not marked: no turn follows it (`awaitsTurn`),
-     * and the eyes would sit there until the stale sweep.
-     */
+    /** No footer: the turn this input triggers has not ended. The 👀 goes on the
+     *  note itself, since that turn has no message of the user's to carry them. */
     async notify(conversation, note) {
         const { chatId, topicId } = parseConversation(conversation);
         const label = originLabel(note.origin);
@@ -483,31 +402,20 @@ export class TelegramChannel {
                 parse_mode: "HTML",
             });
         }
-        // A failed reaction is swallowed and logged by receipts.ts, so the note
-        // itself is never lost to one.
         if (posted && awaitsTurn(note.origin)) {
             this.receipts.mark(conversation, chatId, String(posted.message_id));
         }
     }
 }
-/** Display name from an update, which always carries enough to build one. */
 const senderName = (user) => [user.first_name, user.last_name].filter(Boolean).join(" ") || user.username || String(user.id);
-/**
- * Deep link to a forum topic. A public supergroup links by username; a private
- * one uses the `/c/<internal id>` form, which is the chat id with its `-100`
- * supergroup prefix removed. Both only resolve for members — exactly the
- * audience standing in General.
- */
+/** A private supergroup links as `/c/<internal id>`: the chat id with its
+ *  `-100` prefix removed. */
 function topicLink(chat, topicId) {
     if (chat.username)
         return `https://t.me/${chat.username}/${topicId}`;
     const internal = String(chat.id).replace(/^-100(?=\d)/, "").replace(/^-/, "");
     return `https://t.me/c/${internal}/${topicId}`;
 }
-/**
- * The web shows a turn's cost on hover; IM has none, so it becomes a footer.
- * One newline, not a blank line: Telegram has no small or muted text, so the
- * only way to make it read as a footnote instead of its own paragraph is to
- * keep it tucked against the reply.
- */
+/** One newline, not a blank line: Telegram has no muted text, so tucking it
+ *  against the reply is the only way it reads as a footnote. */
 const turnFooter = (meta) => meta ? `\n<i>${formatTurnMeta(meta)}</i>` : "";

package/dist/channels/types.js

@@ -1,23 +1,12 @@
 // IM channel configuration types — the wire contract shared by the store, the
-// adapters and the Console view (which type-only imports it, so this file must
-// stay free of node builtins, exactly like core/types.ts).
-//
-// Defaults are least-privilege: mention AND bind are required. The platform
-// values are *seeds*, copied into a chat when the bot first sees it — not a
-// fallback consulted at runtime. So every chat carries its own answer and a
-// switch means what it says, instead of a three-state "inherit" nobody can
-// read off the screen.
+// adapters and the Console view (type-only, so no node builtins here). Defaults
+// are least-privilege, and platform values are seeds copied into a chat on
+// discovery, not a runtime fallback: a switch means what it says.
 const PLATFORMS = ["telegram", "slack", "lark"];
 /** Validate at the boundary: an unknown platform is a 404, not a new row. */
 export const isChannelPlatform = (v) => typeof v === "string" && PLATFORMS.includes(v);
-/**
- * The chat a conversation id belongs to. Every adapter spells its ids
- * `<chatId>` or `<chatId>/<thread>` — Telegram's topic, Slack's thread_ts,
- * Lark's root message — so the chat half has one decoder instead of one per
- * platform (control.ts used to import all three adapters for exactly this).
- * The *thread* half stays with each adapter: its type and meaning genuinely
- * differ per platform.
- */
+/** Every adapter spells its ids `<chatId>` or `<chatId>/<thread>`, so the chat
+ *  half has one decoder; the thread half genuinely differs per platform. */
 export const chatOf = (conversationId) => conversationId.split("/", 1)[0] ?? "";
 export const defaultChannelConfig = () => ({
     enabled: false,

package/dist/cli.js

@@ -1,10 +1,6 @@
 #!/usr/bin/env node
-// What `pier` does when typed. Dispatch only — no logic, and no imports of the
-// server until a command that needs it: `pier service install` on a machine
-// with no database should not open one.
-//
-// Hand-rolled against node:util's parseArgs rather than a CLI framework: this
-// small command set does not earn a dependency (AGENTS.md 8).
+// What `pier` does when typed. Dispatch only, and no server imports until a
+// command needs them: `pier service install` must not open a database.
 import { execFileSync } from "node:child_process";
 import { accessSync, constants, realpathSync } from "node:fs";
 import { delimiter, join, resolve } from "node:path";
@@ -77,16 +73,13 @@ else if (values.version || command === "version") {
     process.stdout.write(`${version}\n`);
 }
 else if (!command) {
-    // Typing the bare name is how someone finds out what this is, so it answers
-    // that and nothing else: it used to start a server, which is a surprising
-    // amount to have done by accident.
+    // The bare name must not start a server by accident.
     process.stdout.write(HELP);
 }
 else if (command === "serve") {
     if (subcommand)
         fail(`unexpected argument "${subcommand}"`);
     allowOnly([], "pier serve");
-    // The server starts on import; this file stays a dispatcher.
     await import("./main.js");
 }
 else if (command === "service") {
@@ -117,11 +110,8 @@ else {
     process.stderr.write(`pier: unknown command "${command}"\n\n${HELP}`);
     process.exit(2);
 }
-/**
- * Checking is Pier's own code; applying it is npm's. Under systemd the work is
- * handed to a second unit — this process is about to be restarted, and a child
- * of the service being restarted dies with it.
- */
+/** Under systemd the install is handed to a second unit: a child of the
+ *  service being restarted dies with it. */
 async function update(checkOnly) {
     const check = new UpdateCheck(version);
     await check.refresh();
@@ -148,18 +138,13 @@ async function update(checkOnly) {
             return;
         }
     }
-    // No service manager owns this process, so do not mutate its rollback point
-    // until the operator is ready to run all three steps.
+    // No service manager: leave the rollback point to the operator's own sequence.
     say(`pier backup`);
     say(`npm install -g @timqi/pier@${latest}`);
     say(`then restart Pier.`);
 }
-/**
- * What the daily task runs, and what an operator can type. The setting is the
- * instruction; this converges on it and prints what happened, one line per
- * tool. Non-zero when anything failed — the task run is then a failed run with
- * this text in it, which is the whole tools status surface.
- */
+/** Non-zero when anything failed: the task run is then a failed run with this
+ *  text in it, which is the whole tools status surface. */
 async function tools(action = "") {
     if (action !== "sync") {
         process.stderr.write(`pier tools: unknown action "${action}"\n\n${HELP}`);
@@ -171,8 +156,7 @@ async function tools(action = "") {
         import("./settings.js"),
     ]);
     try {
-        // Read inside the sync's lock, not here: a sync that queued behind another
-        // one must converge on the set as it is when its turn comes.
+        // Read inside the sync's lock: a queued sync converges on the set as it is then.
         const settings = new SettingsStore();
         const report = await new ManagedTools().sync(() => settings.get());
         say(report.summary);
@@ -184,8 +168,6 @@ async function tools(action = "") {
         process.exitCode = 1;
     }
 }
-/** Both are signals to the running unit: SIGUSR2 drains then exits (systemd
- * starts the next process), SIGHUP reloads config in place (main.ts). */
 async function signalService(command) {
     if (process.platform !== "linux") {
         return fail(`only under the systemd service — send ${command === "restart" ? "SIGUSR2" : "SIGHUP"} to the pier process yourself`);
@@ -193,13 +175,11 @@ async function signalService(command) {
     const { UNIT_NAME } = await import("./service.js");
     const signal = command === "restart" ? "SIGUSR2" : "SIGHUP";
     try {
-        // `--kill-who`, not the newer `--kill-whom`: the old spelling is the one
-        // every systemd still parses (systemd/systemd#29793).
+        // `--kill-who`, not `--kill-whom`: the spelling every systemd parses (systemd/systemd#29793).
         execFileSync("systemctl", ["--user", "kill", "-s", signal, "--kill-who=main", UNIT_NAME], { stdio: "inherit" });
     }
     catch (err) {
-        // A failed kill already printed why on the inherited stderr; a missing
-        // systemctl printed nothing, so name it (same shape as `service status`).
+        // A failed kill already printed why; a missing systemctl printed nothing.
         if (err.code === "ENOENT") {
             process.stderr.write(`pier: systemctl is not on PATH — no systemd here.\n`);
         }
@@ -212,8 +192,7 @@ async function signalService(command) {
 }
 async function backup() {
     const [{ backupDb }, { PIER_DB }] = await Promise.all([import("./db.js"), import("./paths.js")]);
-    // This tree's version: the updater runs `backup` before npm replaces it, so
-    // it is the release the copy pairs with.
+    // This tree's version: the updater runs `backup` before npm replaces it.
     const path = backupDb(version, PIER_DB);
     process.stdout.write(path ? `backed up ${path}\n` : `no database yet — nothing to back up.\n`);
 }
@@ -225,7 +204,7 @@ function commandPath(name) {
             return realpathSync(path);
         }
         catch {
-            // Keep looking: version managers commonly put several prefixes on PATH.
+            // Keep looking: version managers put several prefixes on PATH.
         }
     }
     return fail(`${name} is not executable on PATH`);
@@ -240,7 +219,7 @@ async function service(action = "status") {
         process.exit(2);
     }
     switch (action) {
-        case "install": { // The installed unit owns this Node prefix until replaced.
+        case "install": {
             allowOnly(["force", "port", "host", "pier-home"], "pier service install");
             const port = typeof values.port === "string" ? Number(values.port) : 3141;
             if (!Number.isInteger(port) || port < 1 || port > 65_535)
@@ -255,8 +234,7 @@ async function service(action = "status") {
             if (!install({
                 execPath: process.execPath,
                 npmPath: commandPath("npm"),
-                // This command is typed in the operator's shell, so its PATH is the one
-                // they expect a turn's commands to see; the unit records it.
+                // Typed in the operator's shell, so this PATH is the one a turn should see.
                 shellPath: process.env.PATH,
                 entry: fileURLToPath(new URL("./main.js", import.meta.url)),
                 host,
@@ -276,13 +254,11 @@ async function service(action = "status") {
         case "status":
             allowOnly([], "pier service status");
             try {
-                // Inherited, not captured: systemctl's own output is the answer, and
-                // its exit code is nonzero for a service that is merely stopped.
+                // Exit code is nonzero for a service that is merely stopped.
                 execFileSync("systemctl", ["--user", "status", UNIT_NAME], { stdio: "inherit" });
             }
             catch (err) {
-                // A stopped service already printed its status; a missing systemctl
-                // printed nothing, so name it.
+                // A stopped service already printed its status; a missing systemctl printed nothing.
                 if (err.code === "ENOENT") {
                     process.stderr.write(`pier: systemctl is not on PATH — no systemd here.\n`);
                 }