toolroll 0.9.104 → 0.9.105

package/dist/desktop-update-recovery.js

@@ -1,5 +1,3 @@
-/** Supervision of one approved app update, independent of the app being swapped.
- * No task scheduling, credentials or provider calls belong in this process. */
 import { spawn } from "node:child_process";
 import { existsSync, lstatSync, readFileSync, unlinkSync } from "node:fs";
 import { homedir } from "node:os";
@@ -35,8 +33,6 @@ export function updateRecoveryDefinition(j, home = homedir()) {
     return { platform: "darwin", label, bin, entry, logPath, unitPath: join(home, "Library", "LaunchAgents", `${label}.plist`),
         unitContent: launchdPlist({ label, command: [bin, entry, "update-supervise", "--state", j.stateDir, "--update-id", j.id], workingDirectory: j.workDir, logPath,
             pathEnv: [dirname(bin), "/usr/bin", "/bin", "/usr/sbin", "/sbin"].join(":"), associatedBundleId: j.next.bundleId,
-            // A timer is a fallback even when macOS defers a non-demand KeepAlive
-            // restart. It is an updater wakeup, never a task execution time limit.
             keepAlive: false, startInterval: 15 }) };
 }
 export async function armUpdateRecovery(stateDir, retry = false, supervise = run, home = homedir()) {
@@ -51,7 +47,7 @@ export async function armUpdateRecovery(stateDir, retry = false, supervise = run
         throw Error("The staged updater changed. Nothing was launched.");
     const lock = sqliteLock(join(j.workDir, "guardian.sqlite"), 1000);
     if (!lock)
-        return; // An existing guardian owns the job; never restart it.
+        return;
     try {
         let record = readRecovery(j);
         if (record?.state === "attention" && !retry)
@@ -87,8 +83,6 @@ export async function runUpdateAttempt(j, signal, onPid, hooks = {}) {
     const child = spawn(join(resources, "runtime", "node"), [join(resources, "dist", "desktop-host.js"), "update-run", "--state", j.stateDir, "--update-id", j.id], { cwd: j.workDir, stdio: "inherit" });
     let ended = false, fault = null;
     const startedAt = Date.now();
-    // Only this ChildProcess handle may be signalled. A PID in a receipt is
-    // diagnostic, never authority to kill something after a restart.
     const stop = () => { if (!ended)
         child.kill("SIGKILL"); };
     signal.addEventListener("abort", stop, { once: true });
@@ -126,10 +120,7 @@ export async function runUpdateAttempt(j, signal, onPid, hooks = {}) {
         onPid(null);
     }
 }
-/** Remove only the immutable job definition for this completed operation.
- * Receipts/backups remain. A crash during cleanup gets another no-op wake. */
 async function cleanup(j) {
-    // Prevent a new update's registration racing this old job's bootout.
     const lock = installationLock(j);
     if (!lock)
         return;
@@ -152,9 +143,6 @@ export async function superviseDesktopUpdate(stateDir, id, signal, hooks = {}) {
         initial = readUpdateJournal(stateDir);
     }
     catch (error) {
-        // The OS job's pinned working directory has an independently validated
-        // receipt. Use it only to suspend this exact job, never to overwrite a
-        // damaged/newer main record or infer permission to continue the update.
         const retained = readUpdateJournal(stateDir, join(hooks.receiptDir ?? process.cwd(), "receipt.json"));
         if (!retained || retained.id !== id)
             throw error;
@@ -162,7 +150,6 @@ export async function superviseDesktopUpdate(stateDir, id, signal, hooks = {}) {
         await (hooks.cleanup ?? cleanup)(retained);
         return;
     }
-    // A retained old login job cannot act on a newer update in the same state.
     if (!initial || initial.id !== id)
         return;
     const lock = sqliteLock(join(initial.workDir, "guardian.sqlite"), 1000);
@@ -196,8 +183,6 @@ export async function superviseDesktopUpdate(stateDir, id, signal, hooks = {}) {
                 pause(j, "The staged updater changed. Automatic recovery stopped; keep the app and backups and open Update status.");
                 return;
             }
-            // launchd may be settling the previous process group. Do not consume a
-            // retry or spawn over an updater that still owns the database lock.
             if (desktopUpdateStatus(stateDir).running) {
                 await (hooks.sleep ?? sleep)(500);
                 continue;
@@ -229,8 +214,6 @@ export async function superviseDesktopUpdate(stateDir, id, signal, hooks = {}) {
         }
     }
     catch (error) {
-        // If the receipt itself cannot be trusted, do not invent state or launch
-        // anything. Preserve it and suspend this OS job instead of looping.
         if (record)
             writeRecovery(initial, record, "attention", `Automatic recovery stopped: ${error instanceof Error ? error.message : String(error)}. Open Update status; saved work was kept.`);
         finished = true;

package/dist/desktop-update.js

@@ -17,8 +17,6 @@ import { assertCodingUpdateStopped, backupCodingCatalog, codingCatalogExists, re
 import { processMayBeAlive } from "./process-liveness.js";
 import { readDesktopRecoveryView, readDesktopUpdateJournal, supervisorPidsOf, updateRequestIs } from "./contracts/update-journal.js";
 import { sleep as defaultSleep } from "./sleep.js";
-/** Loaded on first use (as backup.ts and store.ts do), so modules that only import this one (the console,
- * and tests that load it in a browser-like environment) never need `node:sqlite` itself. */
 function sqlite() {
     return createRequire(import.meta.url)("node:sqlite");
 }
@@ -31,7 +29,6 @@ const journalPath = (state) => join(state, "desktop-update.json");
 const payload = (j) => join(j.workDir, "Updater.app");
 const standby = (j) => join(j.workDir, "Standby.app");
 const atInstalled = (bundle, j) => ({ ...bundle, path: j.old.path });
-/** Durable receipts are private and independent of the app being replaced. */
 export function durableJson(file, value) {
     const temp = `${file}.${randomUUID()}.tmp`;
     const fd = openSync(temp, "wx", 0o600);
@@ -65,8 +62,6 @@ function privateFile(file) {
     if (!stat.isFile() || stat.isSymbolicLink() || (process.platform !== "win32" && ((stat.mode & 0o077) !== 0 || stat.uid !== process.getuid?.())))
         throw Error("The update record must be an owner-only regular file.");
 }
-/** The refusal the hand-written reader gave for the field a saved journal first gets wrong, so callers and people read
- * the same words; fields it never checked read as an invalid record. */
 function journalRefusal(issue) {
     const [field, inner] = issue.path.split(/[.[]/);
     switch (field) {
@@ -178,7 +173,6 @@ async function otherControllers(app, stateDir) {
     const command = `${join(resources(app), "runtime", "node")} ${join(resources(app), "dist", "desktop-host.js")} serve --state `;
     return result.stdout.split("\n").some(line => line.trim().startsWith(command) && line.trim() !== command + resolve(stateDir));
 }
-/** How long an update waits on a finished run it cannot show has ended before it stops waiting and says why. */
 export const LINGERING_LIMIT_MS = 120_000;
 export function lingeringRun(db) {
     const store = new Store(db);
@@ -194,9 +188,7 @@ export function lingeringWork(db) {
     return lingering && lingeringWords(lingering);
 }
 export const lingeringWords = (l) => l.action ? `${l.on}. To have Toolroll check again, run: ${l.action}` : `${l.on}.`;
-/** What an update says when it stops waiting on `l`: what is in the way, the command, and that new work resumed. */
 export const stoppedWaitingWords = (l) => `Stopped waiting after 2 minutes. ${l.on}. ${clearWords(l)} New work resumed; nothing was changed.`;
-/** The next step once an update has stopped on `l`. */
 export const clearWords = (l) => l.action ? `To have Toolroll check again, run ${l.action}, then update again.` : "Update again once it has stopped.";
 export function updateWaitingWords(o) {
     const { app, version, stopped, lingering: l } = o;
@@ -211,9 +203,6 @@ export function updateWaitingWords(o) {
         words: `${update} ${stopped ? "stopped waiting" : "is waiting"}: ${l.on}.${next}`,
         short: `${update} ${stopped ? `stopped: run #${l.run} is in the way` : `is waiting on run #${l.run}`}.${next}` };
 }
-/** An app updater that ended while letting work finish, with no automatic recovery coming to resume it, leaves new
- * work paused with nobody left to lift the pause. Nothing was stopped or swapped yet, so the pause is lifted here and
- * the update says it stopped. Returns what it said, or null. */
 export function releaseStalledDesktopUpdate(stateDir) {
     let j;
     try {
@@ -250,8 +239,6 @@ export function releaseStalledDesktopUpdate(stateDir) {
         lock.close();
     }
 }
-/** The desktop app's update, when it is waiting on work in `databaseFile`'s installation, or stopped on a run still in
- * the way. An app updater that ended mid-drain is released first, as `toolroll update`'s is. */
 export function desktopUpdateWaitingOf(databaseFile, inTheWay, stateDirs = [dirname(databaseFile), join(homedir(), "Library", "Application Support", "Standing Orders")]) {
     for (const stateDir of new Set(stateDirs.map(dir => resolve(dir)))) {
         let j;
@@ -263,13 +250,12 @@ export function desktopUpdateWaitingOf(databaseFile, inTheWay, stateDirs = [dirn
         }
         if (!j || resolve(j.databaseFile) !== resolve(databaseFile))
             continue;
-        // A page visit only reads (docs/plans/get-side-effects.md): the console's background pass releases it.
         if (!inReadOnlyRequest()) {
             try {
                 if (releaseStalledDesktopUpdate(stateDir))
                     j = readUpdateJournal(stateDir);
             }
-            catch { /* shown as last saved */ }
+            catch { }
         }
         const version = j.next.version;
         if (j.phase === "draining")
@@ -279,13 +265,9 @@ export function desktopUpdateWaitingOf(databaseFile, inTheWay, stateDirs = [dirn
     }
     return null;
 }
-/** The same settling reconcile the background worker runs: a finished run's leftover record of a process that never
- * started settles once the run's process groups are proven gone. A record nothing can prove either way stays. */
 export function settleLeftoverRecords(db, now) {
     return new Store(db).settleUnspawnedWitnesses(now);
 }
-/** Store.stopQuiescenceProblem's reasons, said for a person: no internal terms. Nobody vouches that a run stopped:
- * Toolroll proves it itself (stop-proof.ts), and `toolroll run settle` only has it look again now. */
 export function plainLingering(fallbackRun, problem) {
     const run = Number(/run #(\d+)/.exec(problem)?.[1] ?? fallbackRun);
     const settle = `toolroll run settle ${run}`;
@@ -358,14 +340,11 @@ export async function prepareDesktopUpdate(stateDir, installed, candidate, label
     mkdirSync(workDir, { recursive: true, mode: 0o700 });
     chmodSync(dirname(workDir), 0o700);
     chmodSync(workDir, 0o700);
-    // The staged updater stays put while Standby and the installation exchange.
     cpSync(plan.next.path, join(workDir, "Updater.app"), { recursive: true, errorOnExist: true, force: false });
     cpSync(plan.next.path, join(workDir, "Standby.app"), { recursive: true, errorOnExist: true, force: false });
     if (bundleHash(join(workDir, "Updater.app")) !== plan.next.hash || bundleHash(join(workDir, "Standby.app")) !== plan.next.hash)
         throw Error("The staged update changed during copying. The installed app is unchanged.");
     const journal = { version: 1, id, workDir, ...plan, phase: "prepared", intended: "install", startedAt: new Date().toISOString(), updatedAt: new Date().toISOString(), detail: "Update prepared; waiting to pause new work." };
-    // Two starts may finish copying together. Reserve the installation's one
-    // active journal atomically; never replace another pending update.
     const reservation = installationLock(journal);
     if (!reservation)
         throw Error("This app is already being updated. Open Update status in its controlling installation.");
@@ -403,8 +382,6 @@ export function sqliteLock(file, busyTimeoutMs = 0) {
         throw error;
     }
 }
-/** Whether another process holds the lock in `file`, without making the file or changing it: a status read (a page
- * shows it, docs/plans/get-side-effects.md). A file that isn't there yet is held by nobody. */
 export function lockHeld(file) {
     let st;
     try {
@@ -413,11 +390,9 @@ export function lockHeld(file) {
     catch {
         return false;
     }
-    // Not a plain file of ours (a link, or one someone else made): treated as held, so nothing goes ahead on it.
     if (!st.isFile() || (typeof process.getuid === "function" && st.uid !== process.getuid()))
         return true;
     let db;
-    // Read-only: it never makes the file. The holder's exclusive lock stops even a read.
     try {
         db = new (sqlite().DatabaseSync)(file, { readOnly: true });
     }
@@ -448,7 +423,7 @@ export function desktopUpdateStatus(stateDir) {
         privateFile(join(j.workDir, "recovery.json"));
         recovery = readDesktopRecoveryView(JSON.parse(readFileSync(join(j.workDir, "recovery.json"), "utf8")));
     }
-    catch { /* A legacy/manual update has no guardian. */ }
+    catch { }
     const wantsAutomatic = recovery?.id === j.id && ["armed", "running", "backoff"].includes(recovery.state ?? "") && !terminal(j.phase);
     const automatic = wantsAutomatic && (lockHeld(join(j.workDir, "guardian.sqlite")) || Date.now() - Date.parse(recovery?.updatedAt ?? "") < 45_000);
     const detail = wantsAutomatic && !automatic ? "Automatic recovery has not restarted. Work remains paused; use Retry safely in Update status." : recovery?.state === "attention" || (automatic && (!running || j.phase === "needs-attention")) ? recovery?.detail ?? j.detail : j.detail;
@@ -517,7 +492,6 @@ function assertConfig(j) {
 }
 function snapshot(db) {
     const result = {};
-    // The lead's messages were mate_message before v117 (D5); a desktop update never migrates, so read whichever is here.
     const messages = db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'lead_message'").get() === undefined ? "mate_message" : "lead_message";
     for (const table of ["task", "task_scope", "approver", "run", "artifact", messages, "project"]) {
         const rows = db.prepare(`SELECT * FROM "${table}" ORDER BY rowid`).all();
@@ -535,7 +509,6 @@ async function verifiedBackup(j) {
         save(j, "backing-up", "Private database backups verified; saved tasks and coding sessions are retained.");
         return;
     }
-    // A crashed partial attempt gets a fresh filename; no backup is overwritten.
     const backupPath = existsSync(file) ? join(j.workDir, `orders.backup.${randomUUID()}.db`) : file;
     const backupHash = await verifiedDatabaseBackup(j.databaseFile, backupPath, j.id, async () => {
         await verifiedCodingBackup(j);
@@ -555,16 +528,10 @@ async function verifiedBackup(j) {
     j.backupHash = backupHash;
     save(j, "backing-up", "Private database backups verified; saved tasks, evidence and coding sessions match.");
 }
-/** A private, verified copy of the task database, made under a write
- * reservation so no writer slips in between the snapshot and the copy. The
- * copy drops the update's own admission pause. `inside` runs before the
- * reservation is released, `after` once it is; returns the copy's hash. */
 export async function verifiedDatabaseBackup(databaseFile, backupPath, gateId, inside = async () => { }, after = () => { }, accepts = currentSchemaOnly) {
     const db = connect(databaseFile, false, accepts);
     try {
         db.exec("BEGIN IMMEDIATE");
-        // The write reservation prevents a concurrent writer; a separate read
-        // connection is required because SQLite cannot back up a write transaction.
         const source = connect(databaseFile, true, accepts);
         let before;
         try {
@@ -613,7 +580,6 @@ function assertDesktopCodingStopped(j, db) {
     assertCodingCatalogPresent(j);
     assertCodingUpdateStopped(db);
 }
-/** The service's own processes, from its supervisor's status file: read before the stop, never after. */
 function servicePids(stateDir) {
     try {
         return supervisorPidsOf(JSON.parse(readFileSync(join(stateDir, "controller-supervisor.json"), "utf8")));
@@ -622,8 +588,6 @@ function servicePids(stateDir) {
         return [];
     }
 }
-/** An older app killed before its close leaves the coding owner record behind. Once the stopped service's processes
- * are proved gone, it is released here (and recorded in the ledger); anything unproven keeps the ordinary refusal. */
 function releaseDesktopCodingOwner(j, db, alive) {
     assertCodingCatalogPresent(j);
     const released = releaseStaleCodingOwner(db, j.stoppedPids ?? [], (pid, group) => alive(pid) || processMayBeAlive(pid, group));
@@ -668,14 +632,10 @@ async function verifiedCodingBackup(j) {
     assertCodingBackup(j);
     save(j, j.phase, j.detail);
 }
-/** A SQLite OS lock releases on updater death. Each irreversible step has a
- * preceding durable intent; recovery determines the actual side by hashes. */
 export async function runDesktopUpdate(stateDir, hooks = {}) {
     let j = readUpdateJournal(stateDir);
     if (!j || terminal(j.phase))
         return;
-    // A status probe briefly tries this same lock. Give it time to finish;
-    // treating its millisecond lock as a live updater stranded resume/start.
     const lock = workerLock(j, 1000);
     if (!lock)
         return;
@@ -826,8 +786,6 @@ export async function runDesktopUpdate(stateDir, hooks = {}) {
         await release("restored", "Previous app restored. Your current tasks and evidence were preserved." + (j.error ? ` Update stopped because: ${j.error}` : ""));
     };
     const cancel = async () => {
-        // A resumed operation may already have swapped or stopped the service,
-        // even though its new drain pass is now showing "draining".
         if (bundleHash(j.old.path) === j.old.hash && !j.serviceInterrupted)
             await release("cancelled", "Update cancelled. The installed app and current work are unchanged; any verified backup was kept.");
         else
@@ -871,7 +829,6 @@ export async function runDesktopUpdate(stateDir, hooks = {}) {
             try {
                 const active = activeUpdateWork(checking);
                 const idle = Object.values(active).every(n => n === 0);
-                // A finished run's leftover record settles here first, as the background worker would settle it.
                 if (idle)
                     settleLeftoverRecords(checking, now());
                 const lingering = idle ? lingeringRun(checking) : null;
@@ -879,7 +836,6 @@ export async function runDesktopUpdate(stateDir, hooks = {}) {
                     delete j.waiting;
                     break;
                 }
-                // Saved, so a resumed updater keeps counting from when it began, and status can say what it waits on.
                 if (!lingering)
                     delete j.waiting;
                 else if (j.waiting?.run !== lingering.run || j.waiting.on !== lingering.on)
@@ -892,7 +848,6 @@ export async function runDesktopUpdate(stateDir, hooks = {}) {
             finally {
                 checking.close();
             }
-            // Waiting longer proves nothing more: new work resumes, and the one thing in the way is named.
             if (stuck) {
                 await release("cancelled", stoppedWaitingWords(stuck));
                 return;
@@ -918,7 +873,6 @@ export async function runDesktopUpdate(stateDir, hooks = {}) {
             throw Error("The installed app changed after preview. Nothing was replaced.");
         const current = actual === j.old.hash ? j.old : atInstalled(j.next, j);
         j.serviceInterrupted = true;
-        // Recorded once, before the first stop: a resumed update keeps the processes it first saw.
         if (j.stoppedPids === undefined)
             j.stoppedPids = servicePids(j.stateDir);
         checkpoint("stopping", "Current work is finished. Stopping the background service for the update.");

package/dist/digest-times.js

@@ -1,5 +1,3 @@
-/** The evening digest choices Settings offers: off, or an evening hour — plus a time set from the command line,
- * kept as chosen. Shared by the console page and its no-script fallback. */
 export function digestTimes(current) {
     const hours = ["17:00", "18:00", "19:00", "20:00", "21:00", "22:00"];
     const times = current === null || hours.includes(current) ? hours : [...hours, current].sort();

package/dist/disclosure.js

@@ -1,8 +1,3 @@
-/** One disclosure glyph everywhere: the chevron. It points right while a fold is shut and turns down when it opens,
- * on the server pages, the enhanced folds (workspace-motion.ts) and the React views (lucide's ChevronRight). Every
- * other marker (the native triangle, ▸/▾, +/−, ⌄ and the old arrows) is turned off here, last, so no page can bring
- * a second glyph back. A summary that carries its own icon keeps it. Drawn with two borders: the page's content
- * policy allows no image, not even a data: one. */
 export const DISCLOSURE_CSS = `details>summary{list-style:none}details>summary::-webkit-details-marker{display:none}` +
     `details>summary::after{content:none!important}` +
     `details>summary:not(:has(>svg))::before{content:""!important;display:inline-block;flex:none;box-sizing:border-box;width:7px!important;height:7px!important;` +

package/dist/discord-api.js

@@ -1,4 +1,3 @@
-/** Discord REST requests and private installation credentials. */
 import { chmodSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { join } from "node:path";
 import { randomBytes } from "node:crypto";
@@ -8,17 +7,12 @@ export { object };
 export const discordId = (v) => typeof v === "string" && /^[1-9][0-9]{16,19}$/.test(v);
 export class DiscordError extends ChatDeliveryError {
 }
-/** Discord's 403: the bot may not do this here (for a file, no Attach Files permission). */
 export const DISCORD_REFUSED = "Discord refused access. Check the app and direct-message permissions.";
-/** Discord's 404: the message (or the conversation) is gone. */
 export const DISCORD_GONE = "The Discord message or conversation is unavailable. Open the saved chat.";
 export function discordApi(token, fetcher = fetch) {
     return async (method, path, body, file) => {
-        // Only relative API routes; never send the bot credential to supplied URLs. Beyond messages: typing, and the bot's
-        // own 👀 on a message (put on, taken off).
         if (!/^\/(?:users\/@me|users\/[0-9]+|oauth2\/applications\/@me|channels\/[0-9]+(?:\/typing|\/messages\/[0-9]+\/reactions\/%F0%9F%91%80\/@me|\/messages(?:\/[0-9]+)?(?:\?limit=100)?)?|interactions\/[0-9]+\/[A-Za-z0-9._-]+\/callback)$/.test(path))
             throw new DiscordError("Invalid Discord request");
-        // DELETE takes off the bot's own 👀 and nothing else (never a message).
         if (method === "DELETE" && !/^\/channels\/[0-9]+\/messages\/[0-9]+\/reactions\/%F0%9F%91%80\/@me$/.test(path))
             throw new DiscordError("Invalid Discord request");
         let response;

package/dist/discord-chat.js

@@ -1,4 +1,3 @@
-/** Discord messages and buttons transport the shared assistant's saved actions. */
 import { chatQuestionButtons } from "./subagent-question.js";
 import { chatAskButtons } from "./chat-ask.js";
 import { discordCardEmbed } from "./card-render.js";
@@ -25,8 +24,6 @@ export const discordDelivery = (options) => {
         state,
         label: "Discord",
         member: (member, channel) => discordMember(options.api, member, channel),
-        // "typing…" while the lead works (the 👀 goes at arrival: discordAckHooks), under the shared cooldown; a missing
-        // permission is skipped silently.
         warm: (event) => ({
             typing: underCooldown(state, options.identity.installation, error => error instanceof DiscordError && error.code === "ratelimited" ? error.retryMs : null, () => options.clock?.() ?? new Date(), () => options.api("POST", `/channels/${event.channel}/typing`)),
         }),
@@ -38,13 +35,10 @@ export const discordDelivery = (options) => {
 export const processDiscordEvent = (options) => processChatEvent(discordDelivery(options));
 export const planDiscordRooms = (options) => planRoomMessages(discordDelivery(options));
 export const planDiscordNotifications = (options) => planChatNotifications(discordDelivery(options));
-/** Save only normalized input. Interaction credentials and pairing codes never enter SQLite. */
 export function receiveDiscord(state, identity, type, raw, now) {
     const body = object(raw);
     if (body.webhook_id !== undefined)
         return false;
-    // A guild channel is a room: accepted only while it follows a conversation,
-    // or for the `/team` words that make it follow one.
     const isRoom = body.guild_id !== undefined;
     let member, channel, id, ts, thread, kind, payload;
     if (type === "MESSAGE_CREATE") {
@@ -77,7 +71,6 @@ export function receiveDiscord(state, identity, type, raw, now) {
             };
     }
     else if (type === "INTERACTION_CREATE") {
-        // Only a tap on one of this bot's own messages, in a DM (or a followed guild text channel), from this app.
         const interaction = readDiscordComponentInteraction(body);
         if (!interaction.ok)
             return false;
@@ -93,7 +86,6 @@ export function receiveDiscord(state, identity, type, raw, now) {
         ts = tap.message.id;
         thread = tap.message.id;
         kind = "action";
-        // A button that isn't one Toolroll made is answered with why, once the tap is proved to be the paired person's below.
         const button = readDiscordButtonToken(tap);
         payload = button.ok ? { token: button.value } : { problem: button.issues.map(issue => issue.line).join("; ") };
     }
@@ -150,10 +142,8 @@ function link(origin, target) {
         return [];
     }
 }
-/** Escape Discord's presentation syntax; allowed_mentions also prevents actual pings. */
 export { discordPlain };
 export function discordCard(text, buttons = [], voice = false) {
-    // The lead's own reply: one description in Discord's Markdown (bold anchors, labelled links), no title line promoted to a header.
     if (voice)
         return discordVoicePayload(renderReply(text, "discord"), buttons);
     const lines = text.split("\n"), first = lines[0] ?? "Toolroll", title = discordPlain(first).length <= 256 &&
@@ -161,7 +151,6 @@ export function discordCard(text, buttons = [], voice = false) {
         lines.length > 1
         ? first
         : "Toolroll", detail = title === first ? lines.slice(1).join("\n").trim() : text;
-    // Long answers were split before this point; approval controls only appear when full terms fit.
     return {
         content: "",
         embeds: [
@@ -171,7 +160,6 @@ export function discordCard(text, buttons = [], voice = false) {
                 color: 0x297b70,
             },
         ],
-        // A row holds at most 5 buttons (a question's 4 options and "Answer in words", then the link, need two).
         components: Array.from({ length: Math.min(5, Math.ceil(buttons.length / 5)) }, (_, row) => ({ type: 1, components: buttons.slice(row * 5, row * 5 + 5) })),
         allowed_mentions: { parse: [], replied_user: false },
     };
@@ -208,7 +196,6 @@ export async function deliverDiscordPart(options) {
             state.dropPart(row.id, "Removed by retention");
             return true;
         }
-        // A screenshot sent with a result replies to that result's message once it is placed, and waits until then.
         const result = content.shot?.follows == null ? null : state.part(content.shot.follows);
         if (result !== null && !discordId(result.message) && result.state === "pending") {
             state.holdPart(row.id, shotWaitsUntil(result.next_at, now));
@@ -280,7 +267,6 @@ export async function deliverDiscordPart(options) {
         }
         else if (!content.image)
             buttons = [
-                // A flow decision (v88): Approve / Edit / Send back, then the link.
                 ...(content.flow || content.choose || content.note
                     ? chatFlowButtons(state, row.id, now).map((one) => ({
                         type: 2,
@@ -289,7 +275,6 @@ export async function deliverDiscordPart(options) {
                         custom_id: `so_${one.token}`,
                     }))
                     : []),
-                // A subagent's question (v93): its options, then "Answer in words".
                 ...(content.question
                     ? chatQuestionButtons(state, row.id, now).map((one) => ({
                         type: 2,
@@ -298,7 +283,6 @@ export async function deliverDiscordPart(options) {
                         custom_id: `so_${one.token}`,
                     }))
                     : []),
-                // The lead's question to its owner: its options, then "Something else".
                 ...(content.ask
                     ? chatAskButtons(state, row.id, now).map((one) => ({
                         type: 2,
@@ -307,7 +291,6 @@ export async function deliverDiscordPart(options) {
                         custom_id: `so_${one.token}`,
                     }))
                     : []),
-                // A result's, plan's, failure's or pull request's own buttons (chat-decide.ts): its acts, then its links.
                 ...(content.decide?.rows.flat() ?? []).flatMap((one, index) => "token" in one
                     ? [{ type: 2, style: index === 0 ? 1 : 2, label: one.label.slice(0, 80), custom_id: `so_${one.token}` }]
                     : link(options.origin(), one.link)),
@@ -322,7 +305,6 @@ export async function deliverDiscordPart(options) {
             file = undefined;
         }
         const nonce = chatHash(`discord:part:${row.id}:${event.id}`).slice(0, 24);
-        // Recent Discord nonce receipts reconcile uncertain sends, including attachments.
         if (row.uncertain && !target) {
             const recent = await options.api("GET", `/channels/${destination}/messages?limit=100`);
             const found = (Array.isArray(recent.items) ? recent.items : [])
@@ -332,8 +314,6 @@ export async function deliverDiscordPart(options) {
                 m.channel_id === destination &&
                 discordId(m.id));
             if (found) {
-                // Record the recovered placement, then repaint current terms/progress.
-                // A notification or proposal may have changed while delivery was uncertain.
                 target = String(found.id);
                 if (content.image) {
                     const attachments = Array.isArray(found.attachments)
@@ -346,7 +326,6 @@ export async function deliverDiscordPart(options) {
                     if (!file && attachments.length)
                         text =
                             "Screenshot delivered earlier. The saved evidence has since changed; open the result to review its current state.";
-                    // Preserve the original remote attachment; never upload it again on an edit.
                     file = undefined;
                 }
                 state.setPartFile(row.id, null, Boolean(content.image && Array.isArray(found.attachments) && found.attachments.length), target);
@@ -376,7 +355,6 @@ export async function deliverDiscordPart(options) {
                     fail_if_not_exists: false,
                 };
         }
-        // The watch, at the last moment before the network (cockpit §3).
         if (heldForWatch(state, store, row.id, event, binding.approver, content, now))
             return true;
         const answer = await options.api(target ? "PATCH" : "POST", `/channels/${destination}/messages${target ? `/${target}` : ""}`, args, file);
@@ -398,15 +376,12 @@ export async function deliverDiscordPart(options) {
             state.dropPart(row.id, error.message);
             return true;
         }
-        // No permission to attach files here: one plain line instead of the result's screenshots.
         const saved = readChatPart(row.payload), content = saved.ok ? saved.value : null;
-        // The live message the reply was to replace is gone: the reply goes out as a new message.
         if (content?.edit !== undefined && error instanceof DiscordError && error.code === DISCORD_GONE && isLiveMessage(state, row.event, content.edit)) {
             const { edit: _edit, ...asNew } = content;
             state.repaint(row.id, asNew);
             return true;
         }
-        // Discord refused the card's embed: the part's own plain text goes instead, so the message is never lost.
         if (content?.rich && error instanceof DiscordError && error.code === "Discord could not complete the request" && error.retryMs === 60_000) {
             state.repaint(row.id, withoutCard(content));
             return true;
@@ -426,9 +401,6 @@ export async function deliverDiscordPart(options) {
         return true;
     }
 }
-/** The lead's words as Discord carries them, already rendered: one embed description (cut to its 4 096), empty
- * content, its buttons (none on a live message) and never a ping. Every field is sent on every edit: Discord keeps
- * what an edit leaves out, and inherits no allowed_mentions. */
 export function discordVoicePayload(rendered, buttons = []) {
     return {
         content: "",
@@ -437,7 +409,6 @@ export function discordVoicePayload(rendered, buttons = []) {
         allowed_mentions: { parse: [], replied_user: false },
     };
 }
-/** The live message for one owner message: a reply to it, created under a nonce so a repeat returns the same one. */
 export function discordLive(options, event, spacingMs) {
     const nonce = chatHash(`discord:live:${event.id}`).slice(0, 24);
     const confirmed = (answer, id) => {
@@ -453,7 +424,6 @@ export function discordLive(options, event, spacingMs) {
             ...discordVoicePayload(text), nonce, enforce_nonce: true,
             ...(discordId(event.thread) ? { message_reference: { message_id: event.thread, channel_id: event.channel, fail_if_not_exists: false } } : {}),
         })),
-        // Discord checks an enforced nonce against "the past few minutes": a repeat within one minute is the same message.
         nonceMs: 60_000,
         recover: async () => {
             const recent = await options.api("GET", `/channels/${event.channel}/messages?limit=100`);
@@ -466,7 +436,6 @@ export function discordLive(options, event, spacingMs) {
         uncertain: error => !(error instanceof ChatDeliveryError) || error.uncertain,
     };
 }
-/** The 👀 on the owner's message, and taking it off. A missing permission is asked about at most once a minute, quietly. */
 export function discordAckHooks(options) {
     const path = (event) => `/channels/${event.channel}/messages/${event.ts}/reactions/${encodeURIComponent("👀")}/@me`;
     return {

package/dist/discord.js

@@ -1,4 +1,3 @@
-/** A single leased Discord Gateway connection, hosted by the ordinary worker. */
 import { randomBytes } from "node:crypto";
 import { abortablePause, workChatQueue } from "./chat-follow.js";
 import { loadDiscordCredentials, discordApi, object, discordId, } from "./discord-api.js";
@@ -32,11 +31,8 @@ export async function followDiscord(options) {
         };
         const problem = (message) => state.setProblem(credentials.installation, owner, message);
         const api = discordApi(credentials.botToken);
-        // The SDK loads once Discord is set up, not with every command that could host the follower.
         const { Client, GatewayIntentBits, Partials } = await import("discord.js");
         const client = new Client({
-            // Guild messages and their content are needed for rooms; the Message
-            // Content intent must be enabled for the app in Discord's developer portal.
             intents: [GatewayIntentBits.DirectMessages, GatewayIntentBits.GuildMessages, GatewayIntentBits.MessageContent],
             partials: [Partials.Channel],
             allowedMentions: { parse: [], repliedUser: false },
@@ -70,10 +66,8 @@ export async function followDiscord(options) {
         });
         client.on("error", () => problem("Discord connection failed. Check the bot token and reconnect."));
         client.on("shardError", () => problem("Discord connection failed. Saved replies will retry."));
-        // The 👀 on each owner message as it arrives, beside the queue (a turn there can take a minute).
         const acks = runChatAcks({ state, installation: credentials.installation, owner, current: () => same() && connected,
             hooks: discordAckHooks({ api }), same, signal: options.signal });
-        // Never subscribe a logger to raw payloads, SDK debug output or interaction tokens.
         client.on("raw", (packet) => {
             if (!same())
                 return;
@@ -101,7 +95,6 @@ export async function followDiscord(options) {
                     typeof body.token === "string" &&
                     /^[A-Za-z0-9._-]{1,300}$/.test(body.token)) {
                     const repeated = state.event(chatHash(`${credentials.installation}:interaction:${body.id}`)) !== null;
-                    // Immediate acknowledgement; model work and approvals are handled from the durable queue.
                     void api("POST", `/interactions/${body.id}/${body.token}/callback`, saved || repeated
                         ? { type: 6 }
                         : {