@timqi/pier 0.0.8 → 0.0.15

package/dist/channels/attach.js

@@ -0,0 +1,87 @@
+// 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.
+import { readFile, stat } from "node:fs/promises";
+import { basename, extname } from "node:path";
+import { lostMarker } 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.
+ */
+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. */
+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. */
+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.
+ */
+export function splitAttachments(markdown) {
+    const paths = [];
+    const text = markdown.replace(LINK, (_m, label, raw) => {
+        let path = raw;
+        try {
+            path = decodeURIComponent(raw);
+        }
+        catch {
+            /* not percent-encoded — take the path as written */
+        }
+        if (!paths.includes(path))
+            paths.push(path);
+        return label || nameOf(path);
+    });
+    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.
+ */
+export async function sendAttachments(paths, upload, log) {
+    const lost = [];
+    const fail = (path, reason) => {
+        log(`attachment ${path} not sent: ${reason}`);
+        lost.push(lostMarker(nameOf(path), reason));
+    };
+    for (const path of paths.slice(0, MAX_ATTACHMENTS)) {
+        try {
+            const info = await stat(path);
+            if (!info.isFile())
+                throw new Error("not a file");
+            if (info.size > MAX_ATTACH_BYTES)
+                throw new Error(`too large (>${MAX_ATTACH_BYTES} bytes)`);
+            const name = nameOf(path);
+            const ext = extname(name).slice(1).toLowerCase();
+            await upload({ name, bytes: await readFile(path), image: IMAGE_EXT.has(ext) });
+        }
+        catch (err) {
+            fail(path, err instanceof Error ? err.message : String(err));
+        }
+    }
+    for (const path of paths.slice(MAX_ATTACHMENTS)) {
+        fail(path, `more than ${MAX_ATTACHMENTS} files in one turn`);
+    }
+    return lost.join("\n");
+}

package/dist/channels/control.js

@@ -29,11 +29,11 @@ export function createControl({ router, factory, conversations, store }) {
             if (!session)
                 return null;
             // AgentSession has no cwd; the factory's listing is where it lives.
-            const listed = await factory.list();
+            const summary = await factory.find(session.id);
             const usage = session.contextUsage;
             return {
                 sessionId: session.id,
-                cwd: listed.find((s) => s.id === session.id)?.cwd ?? "",
+                cwd: summary?.cwd ?? "",
                 state: session.state,
                 model: session.model,
                 thinking: session.thinkingLevel,

package/dist/channels/conversations.js

@@ -29,6 +29,16 @@ 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. */
+    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) {

package/dist/channels/lark-api.js

@@ -136,6 +136,44 @@ export class LarkApi {
         });
         return { messageId: ok("message.reply", res).data?.message_id ?? "" };
     }
+    /**
+     * Two calls: the bytes go to the platform first and come back as a key,
+     * then the key is posted as a message. Images take the image endpoint so
+     * they render inline; everything else is a `stream` file, which is Lark's
+     * name for "a file whose type I am not claiming to know".
+     *
+     * The SDK unwraps an upload response to its `data`, so a business failure
+     * arrives as a missing key rather than as a code — hence the explicit throw
+     * instead of `ok()`.
+     */
+    async uploadFile(rootId, file) {
+        const bytes = Buffer.from(file.bytes);
+        let content;
+        if (file.image) {
+            const res = await this.client.im.v1.image.create({
+                data: { image_type: "message", image: bytes },
+            });
+            if (!res?.image_key)
+                throw new Error(`lark image.create: no image_key for ${file.name}`);
+            content = { image_key: res.image_key };
+        }
+        else {
+            const res = await this.client.im.v1.file.create({
+                data: { file_type: "stream", file_name: file.name, file: bytes },
+            });
+            if (!res?.file_key)
+                throw new Error(`lark file.create: no file_key for ${file.name}`);
+            content = { file_key: res.file_key };
+        }
+        ok("message.reply", await this.client.im.v1.message.reply({
+            path: { message_id: rootId },
+            data: {
+                msg_type: file.image ? "image" : "file",
+                content: JSON.stringify(content),
+                reply_in_thread: true,
+            },
+        }));
+    }
     async patchCard(messageId, card) {
         ok("message.patch", await this.client.im.v1.message.patch({
             path: { message_id: messageId },

package/dist/channels/lark-outbound.js

@@ -6,6 +6,7 @@
 // adapter keeps the 👀 receipts, because those are about the turn ending, not
 // about what was said.
 import { formatTurnMeta, isSilentReply, originLabel, quietLabel } from "../core/reply.js";
+import { sendAttachments, splitAttachments } from "./attach.js";
 import { button, buttonRow, card, chunk, footer, LARK_MAX, markdown, OFFER_PREFIX, withFooter, withoutButtons, } from "./lark-render.js";
 /** How many sent cards the retire cache remembers (avibe keeps 200). */
 const SENT_CACHE = 200;
@@ -37,11 +38,14 @@ export class LarkOutbound {
      * platform — the card is remembered so retire() can rebuild it without them.
      */
     async reply(root, reply) {
-        const text = reply.text.trim();
+        // A file the agent linked lives on Pier's machine, so the link is dead in
+        // Lark: the bytes are uploaded instead and the label stays in the text.
+        const { text: spoken, paths } = splitAttachments(reply.text);
+        const text = spoken.trim();
         const meta = reply.meta ? formatTurnMeta(reply.meta) : "";
         const quiet = isSilentReply(reply) ? quietLabel(reply.silence) : "";
         const note = [quiet, meta].filter(Boolean).join(" · ");
-        if (!(text || reply.suggestions.length || note))
+        if (!(text || reply.suggestions.length || note || paths.length))
             return;
         const row = reply.suggestions.length
             ? buttonRow(reply.suggestions.map((label, index) => button(label, { key: `${OFFER_PREFIX}${index}`, root, label })))
@@ -62,6 +66,11 @@ export class LarkOutbound {
             if (last && row && messageId)
                 this.remember(messageId, card(elements));
         }
+        // Attachments follow the words, so the card introducing them is above
+        // them; anything that could not be sent says so in the thread.
+        const lost = await sendAttachments(paths, (file) => this.api.uploadFile(root, file), this.log);
+        if (lost)
+            await this.api.replyCard(root, card([markdown(lost)]));
     }
     /**
      * Take the buttons off a card one option was just taken from — the rest

package/dist/channels/slack-api.js

@@ -293,4 +293,40 @@ export class SlackApi {
         // Bounded mid-stream: the event's size metadata is the platform's word.
         return { bytes: await readCapped(res.body, maxBytes), mimeType };
     }
+    /**
+     * Three calls, because that is what Slack's current upload is: ask for a
+     * one-shot URL, POST the bytes to it (that host is not the Web API and
+     * answers with plain text, not JSON), then tell Slack where the file goes.
+     * `files.upload` did it in one, and is retired.
+     */
+    async uploadFile(channel, threadTs, file) {
+        // A read method: form-encoded, or Slack ignores the body (see read()).
+        const slot = await this.read("files.getUploadURLExternal", { filename: file.name, length: file.bytes.length }).catch((err) => {
+            // An app installed before Pier could upload has every other scope, so
+            // this reads as a mysterious refusal in the chat. Name the fix instead:
+            // the manifest is only applied when an app is *created*.
+            if (!/missing_scope/.test(String(err)))
+                throw err;
+            throw new Error("the Slack app is missing the files:write scope — add it under " +
+                "OAuth & Permissions and reinstall the app");
+        });
+        if (!slot.upload_url || !slot.file_id) {
+            throw new Error("slack files.getUploadURLExternal: no upload url");
+        }
+        const put = await fetch(slot.upload_url, {
+            method: "POST",
+            headers: { "content-type": "application/octet-stream" },
+            // Copied into a fresh view: a request body must be backed by an
+            // ArrayBuffer, and a Buffer read off disk is the wider ArrayBufferLike.
+            body: new Uint8Array(file.bytes),
+            signal: AbortSignal.timeout(120_000),
+        });
+        if (!put.ok)
+            throw new Error(`slack file upload: ${put.status}`);
+        await this.call("files.completeUploadExternal", {
+            files: [{ id: slot.file_id, title: file.name }],
+            channel_id: channel,
+            thread_ts: threadTs,
+        });
+    }
 }

package/dist/channels/slack-outbound.js

@@ -5,6 +5,7 @@
 // limit, and what an empty turn still has to say. The adapter keeps the 👀
 // receipts, because those are about the turn ending, not about what was said.
 import { formatTurnMeta, isSilentReply, originLabel, quietLabel } from "../core/reply.js";
+import { sendAttachments, splitAttachments } from "./attach.js";
 import { isBlockRejection } from "./slack-api.js";
 import { actions, chunk, context, escapeMrkdwn, markdown, MARKDOWN_MAX, MRKDWN_MAX, sections, toMrkdwn, } from "./slack-render.js";
 /**
@@ -30,7 +31,10 @@ export class SlackOutbound {
      * and that is still something to show.
      */
     async reply(channel, threadTs, reply) {
-        const text = reply.text.trim();
+        // A file the agent linked lives on Pier's machine, so the link is dead in
+        // Slack: the bytes are uploaded instead and the label stays in the text.
+        const { text: spoken, paths } = splitAttachments(reply.text);
+        const text = spoken.trim();
         const footer = reply.meta ? footerText(reply.meta) : "";
         const row = actions(reply.suggestions);
         // A turn that produced no text still posts its footer, and says which kind
@@ -41,7 +45,7 @@ export class SlackOutbound {
         const quiet = isSilentReply(reply)
             ? `_${quietLabel(reply.silence && escapeMrkdwn(reply.silence))}_`
             : "";
-        if (!(text || row || footer || quiet))
+        if (!(text || row || footer || quiet || paths.length))
             return;
         const parts = text ? chunk(text, this.budget()) : [""];
         for (const [i, part] of parts.entries()) {
@@ -55,6 +59,12 @@ export class SlackOutbound {
                 ...(last && row ? [row] : []),
             ]);
         }
+        // Attachments follow the words, so the message introducing them is above
+        // them; anything that could not be sent says so in the thread.
+        const lost = await sendAttachments(paths, (file) => this.api.uploadFile(channel, threadTs, file), this.log);
+        // Unescaped, like every other body: post() escapes on the path that needs it.
+        if (lost)
+            await this.post(channel, threadTs, lost, []);
     }
     /**
      * A system note: quoted, labelled with where it came from, and deliberately

package/dist/channels/slack-tool.js

@@ -41,11 +41,25 @@ export function toTs(value) {
         throw new Error(`not a time: ${value}`);
     return String(parsed / 1000);
 }
-export function slackToolSpec(execute) {
+/**
+ * Whether a session opened now is given the tool at all: the same two switches
+ * `handleSlackTool` checks, asked before the description is paid for. The call
+ * keeps its own checks and its own two messages — a session opened while Slack
+ * was configured outlives the operator switching it off, and that turn has to
+ * say so rather than find the tool quietly gone.
+ */
+export function slackToolAvailable(store) {
+    const config = store.get("slack");
+    return config.enabled && !!config.token && config.agentTool;
+}
+export function slackToolSpec(execute, available) {
     return {
         name: "slack",
         label: "Slack",
-        description: "Read and write Slack through Pier, which holds the bot token. State what you want; Pier does the paging and hands back a finished transcript. context says which Slack conversation you are in; read_channel returns a channel's transcript for a time range; read_thread returns one thread, or only what is new in it since a given message via after; read_message returns the single message at a ts (pass thread_ts when it is a reply inside a thread); post sends a message; delete removes the message at a ts, which Slack allows only for messages Pier itself posted; channels lists what Pier can reach. When you were reached through Slack, omit channel (and thread_ts) to act on the conversation you are already in. since/until/after accept ISO 8601, epoch seconds or a ts from an earlier read. Every read fetches live from Slack, so nothing is kept between calls — write down what you need to keep. Message text is standard markdown, but @mentions, #channels and links need Slack's own syntax — read the pier-slack skill before posting.",
+        // One screen of contract; the paragraph this once was lives in the
+        // pier-slack skill, which the description sends the model to before it
+        // posts — the part that goes wrong without instructions.
+        description: "Read and write Slack through Pier, which holds the bot token. Operations: context (which Slack conversation this session is in), read_channel (transcript for a time range), read_thread (one thread; only what is new since a message via after), read_message (the one at ts), post, edit/delete (Pier's own messages only), channels (what Pier can reach). Omit channel and thread_ts to act on the conversation you are in. since/until/after accept ISO 8601, epoch seconds or a ts. Every read fetches live; nothing is kept between calls. @mentions, #channels and links need Slack's own syntax — read the pier-slack skill before posting.",
         parameters: Type.Object({
             // A JSON-Schema enum emits far fewer tokens than typebox's anyOf-of-consts.
             operation: Type.Unsafe({
@@ -56,6 +70,7 @@ export function slackToolSpec(execute) {
                     "read_thread",
                     "read_message",
                     "post",
+                    "edit",
                     "delete",
                     "channels",
                 ],
@@ -69,12 +84,13 @@ export function slackToolSpec(execute) {
             until: Type.Optional(Type.String()),
             /** Strictly newer than this — "what changed since I last looked". */
             after: Type.Optional(Type.String()),
-            /** The one message `read_message` or `delete` is about. */
+            /** The one message `read_message`, `edit` or `delete` is about. */
             ts: Type.Optional(Type.String()),
             limit: Type.Optional(Type.Number()),
             thread_ts: Type.Optional(Type.String()),
             text: Type.Optional(Type.String()),
         }),
+        available,
         execute,
     };
 }
@@ -83,6 +99,17 @@ const required = (value, field) => {
         throw new Error(`${field} is required`);
     return value.trim();
 };
+/**
+ * Slack rejects an oversized message outright, so the length is checked here:
+ * a refusal the agent can act on beats a post that silently never happened.
+ */
+const messageText = (raw) => {
+    const text = required(raw, "text");
+    if (text.length > MARKDOWN_MAX) {
+        throw new Error(`text is ${text.length} chars; Slack accepts ${MARKDOWN_MAX} per message`);
+    }
+    return text;
+};
 const record = (raw) => raw && typeof raw === "object" && !Array.isArray(raw) ? raw : undefined;
 export async function handleSlackTool(deps, raw, callerSessionId = "") {
     const input = record(raw);
@@ -157,10 +184,7 @@ export async function handleSlackTool(deps, raw, callerSessionId = "") {
         return readMessage(deps, client, channel, required(input.ts, "ts"), asked || undefined);
     }
     if (input.operation === "post") {
-        const text = required(input.text, "text");
-        if (text.length > MARKDOWN_MAX) {
-            throw new Error(`text is ${text.length} chars; Slack accepts ${MARKDOWN_MAX} per message`);
-        }
+        const text = messageText(input.text);
         // Defaults to the thread we are in; `thread_ts: "none"` is the explicit
         // way to start a new top-level message instead.
         const asked = typeof input.thread_ts === "string" ? input.thread_ts.trim() : "";
@@ -182,6 +206,20 @@ export async function handleSlackTool(deps, raw, callerSessionId = "") {
             threadTs: threadTs ?? sent.ts,
         };
     }
+    if (input.operation === "edit") {
+        // Explicit `ts`, for delete's reason: an edit replaces the text outright,
+        // and Slack keeps no visible record of what it said before.
+        const ts = required(input.ts, "ts");
+        const text = messageText(input.text);
+        try {
+            await client.updateMessage({ channel, ts, text, blocks: [{ type: "markdown", text }] });
+        }
+        catch (err) {
+            throw new Error(explain(err));
+        }
+        deps.log(`slack tool edited ${ts} in ${channel}`);
+        return { channel, ts, edited: true };
+    }
     if (input.operation === "delete") {
         // Never defaulted from `here`: the thread's ts is the parent message, and
         // "delete" with an implied target is the one mistake with no undo.
@@ -305,10 +343,12 @@ function explain(err) {
     return {
         channel_not_found: "no such channel, or Pier's bot cannot see it — check the channels operation",
         not_in_channel: "Pier's bot is not in that channel; someone has to invite it before it can read",
-        missing_scope: "Pier's Slack app lacks the scope for this read; the operator must reinstall it",
-        ratelimited: "Slack rate-limited this read; wait a minute or ask for a narrower range",
+        missing_scope: "Pier's Slack app lacks the scope for this call; the operator must reinstall it",
+        ratelimited: "Slack rate-limited Pier; wait a minute, and narrow the range if this was a read",
         thread_not_found: "no thread with that ts in this channel",
         cant_delete_message: "Slack only lets Pier delete what its own bot posted; a person's message has to be deleted by them",
+        cant_update_message: "Slack only lets Pier edit what its own bot posted; anyone else's message can only be replied to",
+        edit_window_closed: "Slack's edit window for that message has closed; post a correction instead of rewriting it",
         message_not_found: "no message with that ts in this channel — a ts only means anything in the conversation it came from",
     }[code] ?? String(err);
 }

package/dist/channels/telegram-api.js

@@ -13,10 +13,14 @@ export class TelegramApi {
         this.token = token;
     }
     async call(method, payload, timeoutMs = 30_000, retry = true) {
+        // An upload is the one call that is not JSON: FormData carries the bytes,
+        // and fetch sets its own multipart boundary. It is re-sendable, so the
+        // flood retry below still works on it.
+        const multipart = payload instanceof FormData;
         const res = await fetch(`${BASE}/bot${this.token}/${method}`, {
             method: "POST",
-            headers: { "content-type": "application/json" },
-            body: JSON.stringify(payload),
+            headers: multipart ? undefined : { "content-type": "application/json" },
+            body: multipart ? payload : JSON.stringify(payload),
             signal: AbortSignal.timeout(timeoutMs),
         });
         const body = (await res.json());
@@ -41,6 +45,21 @@ export class TelegramApi {
     sendMessage(payload) {
         return this.call("sendMessage", payload);
     }
+    /** Bytes, not a file_id or a URL: the file is local to this machine, which
+     *  is the whole reason the agent could not just link it. */
+    async sendFile({ chat_id, message_thread_id, file }) {
+        const form = new FormData();
+        form.set("chat_id", String(chat_id));
+        if (message_thread_id !== undefined)
+            form.set("message_thread_id", String(message_thread_id));
+        const field = file.image ? "photo" : "document";
+        // Copied into a fresh view: a Blob part must be backed by an ArrayBuffer,
+        // and a Buffer read off disk carries the wider ArrayBufferLike type.
+        form.set(field, new Blob([new Uint8Array(file.bytes)]), file.name);
+        // A long upload on a slow link is not a hung request; 30s is the budget
+        // for a JSON call, not for megabytes.
+        await this.call(file.image ? "sendPhoto" : "sendDocument", form, 120_000);
+    }
     async editMessage(payload) {
         await this.call("editMessageText", payload);
     }

package/dist/channels/telegram.js

@@ -14,6 +14,7 @@
 import { formatTurnMeta, isSilentReply, originLabel, quietLabel } from "../core/reply.js";
 import { saveInboundAll } from "../core/inbox.js";
 import { MAX_INBOUND_BYTES } from "../core/inbound-file.js";
+import { sendAttachments, splitAttachments } from "./attach.js";
 import { bindHint, bindResult, picked, STALE_OPTION, STOPPED } from "./lines.js";
 import { logger } from "../log.js";
 import { Chains } from "./chains.js";
@@ -413,7 +414,10 @@ export class TelegramChannel {
      */
     async send(conversation, reply) {
         const { chatId, topicId } = parseConversation(conversation);
-        const text = reply.text.trim();
+        // 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.
+        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
@@ -430,17 +434,28 @@ export class TelegramChannel {
         // settleAfter: a 👀 left up because the reply failed would sit there until
         // the stale sweep, looking like the agent is still working.
         await this.receipts.settleAfter(conversation, async () => {
-            if (!body.trim())
-                return;
-            const parts = chunk(body);
-            for (const [i, part] of parts.entries()) {
+            if (body.trim()) {
+                const parts = chunk(body);
+                for (const [i, part] of parts.entries()) {
+                    await this.api.sendMessage({
+                        chat_id: chatId,
+                        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({
                     chat_id: chatId,
                     message_thread_id: topicId,
-                    text: part,
+                    text: escapeHtml(lost),
                     parse_mode: "HTML",
-                    // Next-step buttons ride the last chunk; a click sends the label.
-                    reply_markup: i === parts.length - 1 ? buttons : undefined,
                 });
             }
         });

package/dist/cli.js

@@ -21,6 +21,7 @@ Usage
   pier service status         what systemd thinks of it
   pier update                 install the latest release and restart the service
   pier update --check         only say whether one exists
+  pier tools sync             install/update the managed CLI tools (rtk, …)
   pier restart                finish running turns first, then restart the service
   pier reload                 re-read channel config and recycle idle sessions
   pier backup                 snapshot pier.db before a manual update
@@ -103,6 +104,9 @@ else if (command === "update") {
     allowOnly(["check"], "pier update");
     await update(values.check === true);
 }
+else if (command === "tools") {
+    await tools(subcommand);
+}
 else if (command === "restart" || command === "reload") {
     if (subcommand)
         fail(`unexpected argument "${subcommand}"`);
@@ -150,6 +154,36 @@ async function update(checkOnly) {
     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.
+ */
+async function tools(action = "") {
+    if (action !== "sync") {
+        process.stderr.write(`pier tools: unknown action "${action}"\n\n${HELP}`);
+        process.exit(2);
+    }
+    allowOnly([], "pier tools sync");
+    const [{ ManagedTools }, { SettingsStore }] = await Promise.all([
+        import("./tools.js"),
+        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.
+        const settings = new SettingsStore();
+        const report = await new ManagedTools().sync(() => settings.get());
+        say(report.summary);
+        if (report.failed)
+            process.exitCode = 1;
+    }
+    catch (err) {
+        process.stderr.write(`pier: tools sync failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        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) {

package/dist/core/identity.js

@@ -90,3 +90,21 @@ export function splitSpeaker(text) {
         text: text.slice(m[0].length),
     };
 }
+/**
+ * A session titled by its first prompt inherits that prompt's header, and the
+ * header is for the model: anything a person reads — a list row, a session
+ * header, a notification on a phone — would say "operator: …" on every session
+ * the workbench ever opened. So the speaker comes off and what they said is
+ * the title. Here rather than in a UI module because the push notification
+ * needs the same answer and a second copy of this would drift (AGENTS.md §3).
+ */
+export function readableTitle(title) {
+    if (!title)
+        return title;
+    const { text } = splitSpeaker(title);
+    // No header — the title is what the person typed, and reflowing it would
+    // change what the sidebar's search is matching against for nothing.
+    if (text === title)
+        return title;
+    return text.replace(/\s+/g, " ").trim() || title;
+}

package/dist/core/inbound-file.js

@@ -41,7 +41,9 @@ export const fileMarker = (path) => `[${path.split("/").pop() ?? "file"}](file:/
 /**
  * The conversation-visible line for an attachment that never made it (5b: a
  * failed download must not look like no attachment). Plain text on purpose —
- * not a link — so every surface renders it as the words it is.
+ * not a link — so every surface renders it as the words it is. Both
+ * directions: an inbound file Pier could not fetch and an outbound one it
+ * could not upload (channels/attach.ts) are the same fact to the reader.
  */
 export const lostMarker = (name, reason) => `[attachment lost: ${name} — ${reason}]`;
 // A whole line that is one `[name](file:///…)` link — what fileMarker emits.

package/dist/core/reply.js

@@ -52,7 +52,8 @@ new day — so the last one still applies; a gap alone shows as time only, like
 export function surfacePrompt(instance) {
     const reach = instance.publicUrl
         ? `Address: ${instance.publicUrl} — a board's link is that plus ` +
-            "`/boards/<slug>/`, or `/p/<slug>/` once published."
+            "`/boards/<slug>/`, or `/p/<slug>-<token>/` once published, where `token` " +
+            "is the random field the manifest carries beside `public`."
         : "No public address is configured (the user sets one in Console → Settings), " +
             "so give paths and never guess a host.";
     return `${REPLY_SURFACE_PROMPT}