@timqi/pier 0.1.0 → 0.1.1

package/dist/boards/boards.js

@@ -1,13 +1,7 @@
-// Boards: a folder of static files an agent writes to present something at a
-// stable URL. The filesystem is the source of truth — boards are derived by
-// scanning $PIER_HOME/boards, never registered. See docs/design/05-boards.md.
-//
-// Only <board>/site is reachable over HTTP: sources, README and the manifest
-// itself stay off the wire, so a public board leaks nothing about how it was
-// made. `/boards/*` is authenticated; `/p/*` additionally requires the
-// manifest's `public` flag and runs as sandboxed active content — and is the
-// only password-free prefix, stylesheet included, so one firewall rule covers
-// everything a logged-out reader may fetch.
+// Boards: static pages an agent writes, derived by scanning $PIER_HOME/boards,
+// never registered (docs/design/05-boards.md). Only <board>/site is reachable
+// over HTTP, so a public board leaks nothing about how it was made. `/p/*` is
+// the only password-free prefix, stylesheet included, and runs sandboxed.
 import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
 import { readdir, readFile, realpath, rename, stat, writeFile } from "node:fs/promises";
 import { extname, join, resolve, sep } from "node:path";
@@ -17,11 +11,8 @@ export const defaultBoardsDir = () => pierPath("boards");
 /** Deleted boards keep their bytes under `<slug>.deleted-<ts>`, which this
  *  pattern excludes from every scan — one rename is the whole delete path. */
 const SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/;
-/** A published board is addressed by `<slug>-<token>`: the slug alone is a
- *  guessable word, so without the 32 bits after it `/p/` could be walked with
- *  a dictionary. Minted the first time a manifest is seen public, by whichever
- *  path published it — the Console's toggle or an agent editing board.json —
- *  so a board cannot be public and enumerable at the same time. */
+/** Without the 32 bits after the slug, `/p/` could be walked with a dictionary.
+ *  Minted the first time a manifest is seen public, by whichever path did it. */
 const TOKEN = /^[a-f0-9]{8}$/;
 const mintToken = () => randomBytes(4).toString("hex");
 // A board ships fonts and images, so the list is wider than the attachment
@@ -43,10 +34,11 @@ const TYPES = {
     ".txt": "text/plain; charset=utf-8",
     ".csv": "text/plain; charset=utf-8",
 };
-// Board HTML is active content on the workbench origin. Scripts stay available
-// for self-contained pages, but the response sandbox removes forms, frames,
-// popups and network access. Public pages omit same-origin too, so their scripts
-// receive an opaque origin and cannot inherit an operator's authority.
+// Active content on the workbench origin: the sandbox removes forms, frames,
+// popups and subresource requests. A private board keeps `allow-same-origin`
+// for the session cookie, so its script reads this origin's storage and
+// top-level navigation remains a way out (docs/design/05-boards.md). Public
+// pages omit same-origin, so their scripts inherit no authority at all.
 const CSP = "default-src 'self'; img-src 'self' data:; style-src 'self' 'unsafe-inline'; " +
     "script-src 'self' 'unsafe-inline'; connect-src 'none'; frame-src 'none'; " +
     "worker-src 'none'; object-src 'none'; base-uri 'none'; form-action 'none'; " +
@@ -55,14 +47,9 @@ const PRIVATE_CSP = `sandbox allow-scripts allow-same-origin; ${CSP}`;
 const PUBLIC_CSP = `sandbox allow-scripts; ${CSP}`;
 /** Malformed boards are reported once, not on every scan. */
 const warned = new Set();
-/** The one choke point where a slug becomes a path, so the slug is validated
- *  here and nowhere else: an unvalidated `../../etc` would read outside the
- *  boards dir, and a NUL byte would throw instead of 404. Unknown fields get
- *  defaults, a broken file is skipped whole, and extra keys are the agent's
- *  business — they survive a write. The one manifest this writes back is a
- *  public board that arrived without a token: minting is the same decision as
- *  reading `public`, and doing it anywhere else leaves the agent's own publish
- *  path — editing `board.json` — with no URL. */
+/** The one place a slug becomes a path, so it is validated here (`../../etc`,
+ *  NUL). Extra keys survive a write. The one write-back is minting a token for
+ *  a public board that arrived without one, so the agent's own publish path has a URL. */
 async function readManifest(dir, slug) {
     if (!SLUG.test(slug))
         return null;
@@ -119,8 +106,11 @@ export async function listBoards(dir) {
             .filter((e) => e.isDirectory() && SLUG.test(e.name))
             .map((e) => e.name);
     }
-    catch {
-        return []; // no boards yet
+    catch (err) {
+        // No directory is no boards yet; anything else hides every board at once.
+        if (err.code !== "ENOENT")
+            logger("boards").warn(`cannot scan ${dir}`, err);
+        return [];
     }
     // One board's manifest says nothing about the next one's, so the scan waits
     // once for all of them rather than once per board.

package/dist/channels/attach.js

@@ -1,43 +1,21 @@
-// Outbound attachments: which links in a turn are files the platform has to
-// carry, and the bytes behind them.
-//
-// The agent links a file it produced by absolute `file://` URL — the
-// convention core/reply.ts hands it, spelled the same way inbound
-// (core/inbound-file.ts). The web chat renders that link as a card because the
-// browser can fetch the bytes back over an authenticated route; an IM client
-// cannot, and a `file:///…` link in Slack is a dead path on someone else's
-// machine. So an adapter uploads the file to the platform instead, and the
-// link's label stays behind as the words around it.
-//
-// The upload itself is per-platform and stays in each `*-api.ts`; what is
-// shared — the grammar, the caps, and the line a failed attachment still owes
-// the conversation — lives here so three adapters do not each have a copy.
+// Outbound attachments: a `file://` link in a turn is a dead path on someone
+// else's machine, so an IM adapter uploads the bytes and keeps the label. The
+// upload is per-platform; the grammar, the caps and the line a failed
+// attachment still owes the conversation are shared here.
 import { readFile, stat } from "node:fs/promises";
 import { basename, extname } from "node:path";
 import { lostMarker, replaceOutsideCode } from "../core/inbound-file.js";
-/**
- * One cap for every platform: Telegram refuses a photo past 10 MB, which is
- * the smallest of the three, and a turn that lands on one chat and not on
- * another is worse than a turn that is honest everywhere.
- */
+/** Telegram refuses a photo past 10 MB, the smallest of the three; one cap so
+ *  a turn does not land on one chat and not another. */
 export const MAX_ATTACH_BYTES = 10 * 1024 * 1024;
-/** Per turn. Linking a directory's worth of files is a mistake, not a plan. */
 const MAX_ATTACHMENTS = 5;
-/** Extensions the platforms show inline. Everything else goes as a document —
- *  svg included, deliberately: it is markup, and it renders as a file. */
+/** svg excluded deliberately: it is markup, and renders as a file. */
 const IMAGE_EXT = new Set(["png", "jpg", "jpeg", "gif", "webp", "bmp"]);
-/** `[label](file:///abs/path)`, inline or on a line of its own. The optional
- *  `!` is an image embed, which is the same request with a different sigil. */
+/** `[label](file:///abs/path)`; a leading `!` is the same request as an image embed. */
 const LINK = /!?\[([^\]\n]*)\]\(\s*<?file:\/\/(\/[^)>\s]*)>?\s*\)/g;
-/** A trailing slash or a bare root would otherwise leave an unnamed file. */
 const nameOf = (path) => basename(path) || "file";
-/**
- * Split a turn's markdown into the text an IM chat should show and the files
- * it linked. Each link collapses to its label — or to the file's name when the
- * agent wrote none — so the sentence it sat in still reads, and the turn never
- * becomes empty just because its only content was an attachment. A link inside
- * code is an example of the convention, not a use of it: it is left alone.
- */
+/** Each link collapses to its label (or the file's name), so the sentence it
+ *  sat in still reads. A link inside code is an example, left alone. */
 export function splitAttachments(markdown) {
     const paths = [];
     const text = replaceOutsideCode(markdown, LINK, (match) => {
@@ -56,12 +34,8 @@ export function splitAttachments(markdown) {
     });
     return { text, paths };
 }
-/**
- * Upload every file a turn linked, and return the line the conversation still
- * owes: an attachment that never arrived must not look like an attachment that
- * was never mentioned (AGENTS.md 5b), so each failure is named in the chat as
- * well as in the log. Empty string when everything landed.
- */
+/** Returns the line the conversation still owes: an attachment that never
+ *  arrived must not look like one never mentioned (§5). "" when all landed. */
 export async function sendAttachments(paths, upload, log) {
     const lost = [];
     const fail = (path, reason) => {
@@ -69,10 +43,8 @@ export async function sendAttachments(paths, upload, log) {
         lost.push(lostMarker(nameOf(path), reason));
     };
     const taken = paths.slice(0, MAX_ATTACHMENTS);
-    // Five files that know nothing about each other cost one round trip, not
-    // five. Two phases so the platform still receives them in the order the
-    // turn linked them, and each failure is kept in its own slot — `lost` reads
-    // in link order whichever upload finished first.
+    // Two phases: reads in parallel, then uploads, so the platform receives
+    // files in link order and `lost` reads in link order too.
     const reasons = [];
     const reasonOf = (err) => (err instanceof Error ? err.message : String(err));
     const files = await Promise.all(taken.map(async (path, i) => {

package/dist/channels/chains.js

@@ -1,28 +1,13 @@
-// Ordering: one promise chain per conversation.
-//
-// Messages from different chats are handled concurrently — a slow download must
-// not stall another group — but messages within one chat strictly in arrival
-// order, because a steer overtaking the message it interrupts reorders the
-// conversation.
-//
-// Two rules live here because both adapters got to write them once and neither
-// should write them twice:
-//
-//  - Every link needs its own `catch`. One rejected handler otherwise poisons
-//    the chain and silences that chat for the life of the process — an ordering
-//    mechanism that fails closed, permanently.
-//  - `drain()` is bounded. `runtime.reload()` runs on the Console's save, so a
-//    stuck handler must not hold that request open.
+// One promise chain per conversation: chats run concurrently, but within one
+// chat strictly in arrival order, or a steer overtakes the message it interrupts.
 export class Chains {
     log;
     maxActive;
     active = new Map();
+    held = 0;
+    waiting = [];
     constructor(log, 
-    /**
-     * How many conversations may be in flight before a new one queues behind an
-     * existing chain. Bounds concurrency (open sockets, downloads); a transport
-     * that can also slow its source down should do that separately.
-     */
+    /** Bounds concurrency (sockets, downloads), not the source's backlog. */
     maxActive = Infinity) {
         this.log = log;
         this.maxActive = maxActive;
@@ -30,34 +15,45 @@ export class Chains {
     get size() {
         return this.active.size;
     }
-    /** Append to a conversation's chain, dropping the entry once it drains. */
     run(key, task) {
+        // A conversation owns one slot for the life of its chain, so a follow-up
+        // message queues behind its own handler instead of claiming a second.
         const mine = this.active.get(key);
-        // A conversation with a chain already waits on itself; only a new one has
-        // to wait for a slot. `active` is non-empty whenever the cap is hit, so the
-        // race always settles.
-        const start = mine ??
-            (this.active.size >= this.maxActive
-                ? Promise.race(this.active.values()).catch(() => { })
-                : Promise.resolve());
-        const next = start
+        const next = (mine ?? this.acquire())
             .then(task)
+            // Every link catches: one rejection would otherwise silence the chat for good.
             .catch((err) => this.log(`handler failed in ${key}: ${String(err)}`));
         this.active.set(key, next);
         void next.then(() => {
-            if (this.active.get(key) === next)
-                this.active.delete(key);
+            if (this.active.get(key) !== next)
+                return;
+            this.active.delete(key);
+            this.release();
         });
     }
-    /** Wait for the oldest in-flight chain — the backpressure primitive. */
+    /** Reserved synchronously, so a burst of `run` calls cannot all pass the cap. */
+    acquire() {
+        if (this.held < this.maxActive) {
+            this.held += 1;
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => this.waiting.push(resolve));
+    }
+    release() {
+        // The slot moves to one waiter rather than being counted back, which is
+        // what keeps a release from waking the whole queue.
+        const next = this.waiting.shift();
+        if (next)
+            next();
+        else
+            this.held -= 1;
+    }
+    /** The backpressure primitive. */
     oldest() {
         return Promise.race(this.active.values()).catch(() => { });
     }
-    /**
-     * Let in-flight work finish before a replacement adapter starts, but never
-     * wait forever: two adapters handling one message would prompt twice, and a
-     * hung handler holding up a config save is worse than either.
-     */
+    /** Two adapters handling one message would prompt twice; a hung handler
+     *  holding up the Console's save is worse than either, hence the bound. */
     async drain(timeoutMs) {
         await Promise.race([
             Promise.allSettled(this.active.values()),

package/dist/channels/chunk.js

@@ -1,15 +1,7 @@
-// Splitting a long turn into sendable messages.
-//
-// Every platform caps a message, and the index arithmetic for "cut at the last
-// blank line that fits, else the last newline, else mid-text" is fiddly enough
-// that having it twice is having it wrong once. The cap and any per-platform
-// repair (Slack re-balances code fences across the cut) stay with the renderer.
-/**
- * Cut `text` into pieces of at most `max` characters, preferring a blank line,
- * then a newline, then the hard limit. A cut lands mid-text only when there is
- * no break in the second half of the window — better a blunt split than a
- * dropped turn.
- */
+// Splitting a long turn into sendable messages; the cap and any per-platform
+// repair stay with the renderer.
+/** Prefers a blank line, then a newline, then the hard limit; a cut lands
+ *  mid-text only when there is no break in the second half of the window. */
 export function chunkText(text, max) {
     if (text.length <= max)
         return [text];
@@ -26,27 +18,15 @@ export function chunkText(text, max) {
         parts.push(rest);
     return parts;
 }
-/**
- * Close a fence a chunk left open, and reopen it on the next one. Telegram can
- * be cut mid-`<pre>` and shrug — its parser closes the tag itself — but Slack
- * and Lark both swallow the rest of a message after an unterminated ```, and
- * the next chunk starts *outside* a fence, so the tail of a long code block
- * renders as prose.
- *
- * Fences are tracked by line-leading runs with their *length*, per CommonMark:
- * a ```` fence (used to quote a ``` block) only closes on a run at least as
- * long, so counting bare ``` occurrences would see the inner block close the
- * outer one and mangle both halves of the cut.
- */
+/** Slack and Lark swallow the rest of a message after an unterminated ```, so a
+ *  fence left open is closed and reopened on the next chunk. Runs are tracked
+ *  by length, per CommonMark: a ```` fence only closes on a run at least as long. */
 export function balanceFences(parts) {
-    /** Backticks of the fence currently open across the boundary; 0 = closed. */
     let open = 0;
     const fence = (n) => "`".repeat(n);
     return parts.map((part) => {
         const reopened = open ? `${fence(open)}\n${part}` : part;
-        // The prepended fence counts too — the scan restarts from "closed" and
-        // reads it as the opener, so a chunk that closes the block it inherited
-        // comes out even.
+        // The scan restarts from "closed" and reads the prepended fence as the opener.
         open = 0;
         for (const line of reopened.split("\n")) {
             const run = /^\s*(`{3,})/.exec(line)?.[1]?.length ?? 0;

package/dist/channels/commands.js

@@ -1,21 +1,10 @@
-// Slash commands in IM text, parsed once for every platform.
-//
-// Every chat platform types commands the same way and mangles them slightly
-// differently: Telegram appends `@botname` when several bots share a group,
-// clients add stray whitespace, and users capitalise. One parser so an adapter
-// never re-derives "is this a command" and the answer never drifts between
-// platforms.
-/**
- * Parse a command out of one inbound message. Whitespace on both ends is
- * dropped first, then a leading `/` is required: anything else is ordinary
- * text and must reach the agent untouched.
- */
+// Slash commands in IM text, parsed once for every platform: Telegram appends
+// `@botname` when several bots share a group, clients add whitespace, users capitalise.
 export function parseCommand(text) {
     const trimmed = text.trim();
     if (!trimmed.startsWith("/"))
         return null;
-    // Args are taken verbatim, not re-joined from split words: a path or a
-    // sentence must survive with its own spacing intact.
+    // Args verbatim: a path or a sentence must keep its own spacing.
     const match = /^\/(\S+)[ \t]*([\s\S]*)$/.exec(trimmed);
     const [name = "", target] = (match?.[1] ?? "").split("@");
     if (!name)

package/dist/channels/config.js

@@ -1,31 +1,25 @@
-// Channel config persistence and the permission gate every adapter shares.
-// One JSON document per platform holds credentials, defaults, bound users and
-// the discovered chats — token, groups and permissions in one place, so a
-// surface configuring a platform reads and writes exactly one row.
-// The shapes live in types.ts; this file is the store and the policy.
+// Channel config persistence and the permission gate every adapter shares: one
+// JSON document per platform, so a surface configuring one reads and writes one row.
+import { randomInt } from "node:crypto";
 import { pierDb } from "../db.js";
+import { isSealed } from "../secrets.js";
 import { defaultChannelConfig, } from "./types.js";
 const BIND_CODE_TTL_MS = 10 * 60_000;
-/** Envelope from secrets.ts. A token that matches was sealed by us; anything
- *  else is legacy plaintext, still honored and re-sealed on the next save. */
-const SEALED = /^v1:[0-9a-f]{8}:/;
+/** Six symbols out of 36 is 2 billion, but a caller who may retry forever only
+ *  needs the TTL; five wrong tries void the code instead. */
+const BIND_CODE_TRIES = 5;
+const BIND_CODE_ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ";
 export class ChannelStore {
     secrets;
     db;
     cache = new Map();
-    /** Without `secrets`, tokens persist as given — tests and one-off tools.
-     *  With it, tokens are sealed at rest; a locked store throws on both paths
+    /** Without `secrets` (tests), tokens persist as given. A locked store throws
      *  rather than serving a token it cannot read. */
     constructor(db = pierDb(), secrets) {
         this.secrets = secrets;
         this.db = db;
     }
-    /**
-     * The live cached document. Private on purpose: handing it out let a caller
-     * mutate config without saving, so memory and disk could disagree with no
-     * way to tell which was right. Internal readers use this; everyone outside
-     * gets a copy from get().
-     */
+    /** Private: handed out, a caller could mutate config without saving. */
     cached(platform) {
         const hit = this.cache.get(platform);
         if (hit)
@@ -36,23 +30,20 @@ export class ChannelStore {
             : defaultChannelConfig();
         if (this.secrets) {
             for (const key of ["token", "appToken"]) {
-                if (SEALED.test(config[key]))
+                if (isSealed(config[key]))
                     config[key] = this.secrets.decrypt(config[key]);
             }
         }
         this.cache.set(platform, config);
         return config;
     }
-    /** A detached copy: edit it freely, then hand it back to save(). */
     get(platform) {
         return structuredClone(this.cached(platform));
     }
     save(platform, config) {
-        // Clone on the way in too, so the caller keeping its object and mutating
-        // it later cannot reach into the cache behind save()'s back.
+        // Cloned, so the caller's object cannot reach into the cache later.
         this.cache.set(platform, structuredClone(config));
-        // The cache holds plaintext (it is what adapters connect with); only the
-        // row is sealed.
+        // The cache holds plaintext; only the row is sealed.
         const stored = this.secrets ? structuredClone(config) : config;
         if (this.secrets) {
             for (const key of ["token", "appToken"]) {
@@ -68,16 +59,9 @@ export class ChannelStore {
     chat(platform, chatId) {
         return this.get(platform).chats.find((c) => c.id === chatId);
     }
-    /**
-     * Record a chat the bot just met. Telegram has no "list my chats" API, so
-     * discovery is passive. A new chat copies the platform defaults and owns
-     * them from then on — the mention and bind gates are what keep it harmless
-     * until an operator configures it.
-     *
-     * Telegram gets a chat's name free with every update, so it discovers on
-     * every message: the "already known, unchanged" answer is read off the
-     * cached document and costs no clone. Only a real change pays for one.
-     */
+    /** Telegram has no "list my chats" API, so discovery is passive and happens
+     *  on every message: the unchanged case must cost no clone. A new chat copies
+     *  the platform defaults and owns them from then on. */
     discoverChat(platform, chat) {
         const cached = this.cached(platform).chats.find((c) => c.id === chat.id);
         if (cached && cached.name === chat.name && cached.kind === chat.kind)
@@ -98,9 +82,7 @@ export class ChannelStore {
         }
         this.save(platform, config);
     }
-    // Read-only and on the per-message path: no clone, nothing here escapes.
-    // An undiscovered chat falls back to the platform seed; in practice the
-    // adapter discovers before it asks.
+    // On the per-message path: no clone, nothing here escapes.
     policy(platform, chatId) {
         const config = this.cached(platform);
         const chat = config.chats.find((c) => c.id === chatId);
@@ -119,10 +101,11 @@ export class ChannelStore {
     isBound(platform, userId) {
         return this.cached(platform).users.some((u) => u.id === userId);
     }
-    /** Single-use, short-lived code an operator reads off the Console. */
+    /** `randomInt` rejection-samples, and this code is the whole distance
+     *  between a stranger and an agent with a shell. */
     issueBindCode(platform) {
         const config = this.get(platform);
-        const code = Math.random().toString(36).slice(2, 8).toUpperCase();
+        const code = Array.from({ length: 6 }, () => BIND_CODE_ALPHABET[randomInt(BIND_CODE_ALPHABET.length)]).join("");
         config.bindCode = { code, expiresAt: Date.now() + BIND_CODE_TTL_MS };
         this.save(platform, config);
         return config.bindCode;
@@ -131,15 +114,20 @@ export class ChannelStore {
         const config = this.get(platform);
         const pending = config.bindCode;
         if (!pending || pending.expiresAt < Date.now())
-            return false;
-        if (pending.code !== code.trim().toUpperCase())
-            return false;
+            return "invalid";
+        if (pending.code !== code.trim().toUpperCase()) {
+            const tries = (pending.tries ?? 0) + 1;
+            const voided = tries >= BIND_CODE_TRIES;
+            config.bindCode = voided ? null : { ...pending, tries };
+            this.save(platform, config);
+            return voided ? "voided" : "invalid";
+        }
         config.bindCode = null;
         if (!config.users.some((u) => u.id === user.id)) {
             config.users.push({ id: user.id, name: user.name, boundAt: Date.now() });
         }
         this.save(platform, config);
-        return true;
+        return "bound";
     }
     unbind(platform, userId) {
         const config = this.get(platform);
@@ -147,20 +135,13 @@ export class ChannelStore {
         this.save(platform, config);
     }
 }
-/**
- * The whole inbound permission policy, platform-blind and total.
- *
- * A group denial is silent by contract: a group where the bot answers "you are
- * not allowed" to every passing message is worse than one that stays quiet.
- * A DM is the exception — two parties, so silence is just confusing — and the
- * adapter answers `not-bound` there.
- */
+/** The whole inbound permission policy. A group denial is silent by contract;
+ *  a DM is the exception, and the adapter answers `not-bound` there. */
 export function gate({ policy, isDm, addressed, bound, bindRequest }) {
     if (!policy.enabled)
         return "chat-disabled";
-    // A DM has exactly two parties: mention is meaningless, and bind is not
-    // optional there — it is the only thing between a stranger and an agent with
-    // a shell. `requireMention`/`requireBind` are group settings by construction.
+    // In a DM bind is not optional: it is the only thing between a stranger and
+    // an agent with a shell. `requireMention`/`requireBind` are group settings.
     if (isDm)
         return bound || bindRequest ? "allow" : "not-bound";
     if (policy.requireMention && !addressed)

package/dist/channels/control.js

@@ -1,16 +1,9 @@
-// What an adapter is allowed to do to a session, beyond handing it a prompt.
-//
-// `Channel` has exactly one inbound path (`onMessage`) and keeps it: an in-chat
-// settings panel needs to read a session's model and change it, which is not a
-// prompt and must not become a second seam. So the channel layer — which owns
-// the router already — hands adapters this narrow, platform-blind interface.
-// Everything here is a thin wrapper over core; no policy lives in it.
+// What an adapter may do to a session beyond handing it a prompt. Not part of
+// the `Channel` seam: the channel layer owns the router and hands adapters this
+// narrow interface instead. Thin wrappers over core; no policy.
 import { chatOf, isChannelPlatform } from "./types.js";
 export function createControl({ router, factory, conversations, store }) {
     const launchFor = (key) => {
-        // Decoding a conversation id back to a chat id is the channel layer's
-        // business, never core's; the chat half of every platform's id has one
-        // decoder (chatOf), so no adapter import is needed here.
         if (!isChannelPlatform(key.channelId))
             return {};
         const policy = store.policy(key.channelId, chatOf(key.conversationId));
@@ -28,7 +21,6 @@ export function createControl({ router, factory, conversations, store }) {
             const session = router.sessionOf(key);
             if (!session)
                 return null;
-            // AgentSession has no cwd; the factory's listing is where it lives.
             const summary = await factory.find(session.id);
             const usage = session.contextUsage;
             return {
@@ -55,8 +47,7 @@ export function createControl({ router, factory, conversations, store }) {
                 ...launch,
                 cwd: cwd || launch.cwd || process.cwd(),
             });
-            // Persist before attaching: a crash in between must not leave the chat
-            // pointing at a session nobody recorded.
+            // Persist before attaching: a crash between must not leave an unrecorded session.
             conversations.set(key, session.id);
             router.attach(key, session);
             return session.id;

package/dist/channels/conversations.js

@@ -1,14 +1,6 @@
-// Durable conversation → session routing for IM channels.
-//
-// core/router.ts keeps its map in memory, which is enough for the surfaces
-// whose conversation id already IS a session id (web) or that persist their
-// target themselves (tasks). An IM conversation id is a chat or a topic, so
-// without this table a restart would silently hand every group a brand-new
-// session: the chat history stays on screen while the agent forgets all of
-// it, and the old transcript becomes unreachable.
-//
-// Owned by channels/ rather than core/ so core stays storage-agnostic — the
-// same split tasks/ already uses for its target session ids.
+// Durable conversation → session routing for IM channels: an IM conversation id
+// is a chat, not a session id, so without this table a restart would hand every
+// group a brand-new session. In channels/ so core stays storage-agnostic.
 import { pierDb } from "../db.js";
 export class ConversationStore {
     db;
@@ -29,30 +21,22 @@ export class ConversationStore {
         session_id = excluded.session_id, updated_at = excluded.updated_at
     `).run(key.channelId, key.conversationId, sessionId, Date.now());
     }
-    /** Which channel owns this session, durably — the router's own answer is
-     * in-memory and becomes undefined the moment an idle session is evicted, so
-     * a surface asking "was this turn already delivered to a chat?" long after
-     * the turn cannot use it. Sessions with no row are nobody's conversation. */
+    /** Durable, unlike the router's answer, which is gone once an idle session
+     *  is evicted. No row: nobody's conversation. */
     channelOf(sessionId) {
         const row = this.db.prepare(`
       SELECT channel_id FROM conversations WHERE session_id = ? LIMIT 1
     `).get(sessionId);
         return row?.channel_id;
     }
-    /** Drop a mapping whose session Pi no longer has, so the next message
-     * starts a fresh one instead of failing forever. */
     forget(key) {
         this.db.prepare(`
       DELETE FROM conversations WHERE channel_id = ? AND conversation_id = ?
     `).run(key.channelId, key.conversationId);
     }
 }
-/**
- * The IM half of the router's session factory: reuse this conversation's
- * session across restarts, and only create when there is nothing to resume.
- * Wired in main.ts, so neither core nor an adapter learns where the mapping
- * lives.
- */
+/** The IM half of the router's session factory, wired in main.ts so neither
+ *  core nor an adapter learns where the mapping lives. */
 export function resolveConversation(store, factory, launchFor, onStale) {
     return async (key) => {
         const known = store.get(key);
@@ -61,8 +45,7 @@ export function resolveConversation(store, factory, launchFor, onStale) {
                 return await factory.resume(known);
             }
             catch (err) {
-                // Pi never persisted it (a first turn that never landed) or the
-                // transcript was deleted. Re-route rather than fail every message.
+                // Never persisted, or deleted: re-route rather than fail every message.
                 onStale?.(`${key.channelId}:${key.conversationId} lost session ${known}: ${String(err)}`);
                 store.forget(key);
             }