@timqi/pier 0.0.1 → 0.0.2

package/dist/channels/telegram.js

@@ -11,7 +11,9 @@
 //
 // Everything policy-shaped (mention/bind gates, per-chat overrides) is in
 // config.ts, platform-blind and shared with the adapters still to come.
-import { formatTurnMeta, originLabel } from "../core/reply.js";
+import { formatTurnMeta, isSilentReply, originLabel, quietLabel } from "../core/reply.js";
+import { saveInbound } from "../core/inbox.js";
+import { fileMarker, lostMarker, MAX_INBOUND_BYTES } from "../core/inbound-file.js";
 import { logger } from "../log.js";
 import { Chains } from "./chains.js";
 import { parseCommand } from "./commands.js";
@@ -158,14 +160,14 @@ export class TelegramChannel {
         if (!msg.from || msg.from.id === this.me?.id)
             return; // own echo, or malformed
         const raw = (msg.text ?? msg.caption ?? "").trim();
-        if (!raw && !msg.photo?.length)
+        if (!raw && !msg.photo?.length && !msg.document)
             return;
         const chatId = String(msg.chat.id);
         const isDm = msg.chat.type === "private";
         const kind = isDm ? "dm" : msg.chat.is_forum ? "forum" : "group";
         const name = msg.chat.title ?? [msg.from.first_name, msg.from.last_name].filter(Boolean).join(" ");
         this.deps.store.discoverChat("telegram", { id: chatId, name: name || chatId, kind });
-        const text = this.stripMention(raw, msg);
+        const text = this.stripMention(raw);
         const command = parseCommand(text);
         // A command aimed at another bot in the same group is not ours to answer.
         const mine = !command?.target || command.target.toLowerCase() === this.me?.username.toLowerCase();
@@ -194,12 +196,12 @@ export class TelegramChannel {
             return;
         // `@bot` on its own (text is empty once the mention is stripped) and
         // `/settings` are the same request: show me this conversation's settings.
-        if (this.panel && mine && (command?.name === "settings" || (!text && !msg.photo?.length))) {
+        if (this.panel && mine && (command?.name === "settings" || (!text && !msg.photo?.length && !msg.document))) {
             return this.panel.open(here, chatId, msg.message_thread_id);
         }
         // Downloading only past the gate: an unauthorized sender must not be able
         // to make the bot pull bytes on their behalf.
-        const images = await this.photos(msg);
+        const markers = await this.saveAttachments(msg);
         const topicId = await this.routeTopic(msg, text);
         const key = { channelId: this.id, conversationId: conversationId(chatId, topicId) };
         this.receipts.mark(key.conversationId, chatId, String(msg.message_id));
@@ -211,8 +213,7 @@ export class TelegramChannel {
             // A group is many people talking into one session; the update already
             // carries the name, so no lookup is needed here.
             sender: { id: String(msg.from.id), name: senderName(msg.from) },
-            text,
-            images,
+            text: [text, ...markers].filter(Boolean).join("\n"),
             mode: "steer",
         });
     }
@@ -354,17 +355,32 @@ export class TelegramChannel {
             return msg.message_thread_id;
         }
     }
-    async photos(msg) {
-        const largest = msg.photo?.at(-1);
-        if (!largest)
-            return [];
-        try {
-            return [await this.api.downloadPhoto(largest.file_id)];
-        }
-        catch (err) {
-            this.log(`photo download failed: ${String(err)}`);
-            return [];
+    /** Save the message's attachments to the inbox; each becomes a prompt
+     *  line — a failed one becomes a lost-marker line, never silence (5b). */
+    async saveAttachments(msg) {
+        // Telegram sends a photo as a size ladder — the last entry is the largest.
+        const photo = msg.photo?.at(-1);
+        const doc = msg.document;
+        const wanted = [
+            ...(photo ? [{ id: photo.file_id, name: undefined, label: "photo", mime: "image/jpeg", size: photo.file_size }] : []),
+            ...(doc ? [{ id: doc.file_id, name: doc.file_name, label: doc.file_name ?? "file", mime: doc.mime_type ?? "application/octet-stream", size: doc.file_size }] : []),
+        ];
+        const markers = [];
+        for (const { id, name, label, mime, size } of wanted) {
+            if (size !== undefined && size > MAX_INBOUND_BYTES) {
+                markers.push(lostMarker(label, "too large"));
+                continue;
+            }
+            try {
+                const file = await this.api.downloadFile(id);
+                markers.push(fileMarker(await saveInbound(this.id, name ?? file.name, mime, file.bytes)));
+            }
+            catch (err) {
+                this.log(`attachment download failed: ${String(err)}`);
+                markers.push(lostMarker(label, "download failed"));
+            }
         }
+        return markers;
     }
     // --- addressing ------------------------------------------------------------
     /** Mentioned, replying to the bot, or a slash command aimed at this bot. */
@@ -379,14 +395,10 @@ export class TelegramChannel {
         return !!this.me?.username && text.toLowerCase().includes(handle);
     }
     /** A leading @bot is addressing, not content — the agent should not see it. */
-    stripMention(text, msg) {
+    stripMention(text) {
         const handle = `@${this.me?.username ?? ""}`;
         if (!this.me?.username)
             return text;
-        const mention = msg.entities?.find((e) => e.type === "mention" && e.offset === 0);
-        if (mention && text.slice(0, mention.length).toLowerCase() === handle.toLowerCase()) {
-            return text.slice(mention.length).replace(/^[\s,:-]+/, "");
-        }
         return text.toLowerCase().startsWith(handle.toLowerCase())
             ? text.slice(handle.length).replace(/^[\s,:-]+/, "")
             : text;
@@ -404,12 +416,9 @@ export class TelegramChannel {
         // the person waiting cannot tell. See AGENTS.md — an empty turn is still an
         // event, and an event nobody can see is not observable.
         const buttons = keyboard(reply.suggestions);
-        // Options count as a reply: the buttons are the answer.
-        const quiet = text || buttons
-            ? ""
-            : reply.silence
-                ? `<i>stayed silent \u2014 ${escapeHtml(reply.silence)}</i>`
-                : "<i>no reply</i>";
+        const quiet = isSilentReply(reply)
+            ? `<i>${quietLabel(reply.silence && escapeHtml(reply.silence))}</i>`
+            : "";
         const body = (text ? toTelegramHtml(text) : quiet) + turnFooter(reply.meta);
         try {
             if (body.trim()) {

package/dist/cli.js

@@ -3,13 +3,15 @@
 // server until a command that needs it: `pier service install` on a machine
 // with no database should not open one.
 //
-// Hand-rolled against node:util's parseArgs rather than a CLI framework: three
-// commands and four flags do not earn a dependency (AGENTS.md 8).
+// Hand-rolled against node:util's parseArgs rather than a CLI framework: this
+// small command set does not earn a dependency (AGENTS.md 8).
 import { execFileSync } from "node:child_process";
-import { createRequire } from "node:module";
+import { accessSync, constants, realpathSync } from "node:fs";
+import { delimiter, join, resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { fileURLToPath } from "node:url";
-const { version } = createRequire(import.meta.url)("../package.json");
+import { currentVersion, UpdateCheck } from "./update.js";
+const version = currentVersion();
 const HELP = `pier ${version} — a self-hosted workspace for coding agents
 
 Usage
@@ -17,6 +19,11 @@ Usage
   pier service install        write and start a systemd user unit (Linux)
   pier service uninstall      stop it and remove the unit
   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 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
   pier --version | --help
 
 Options for "service install"
@@ -28,19 +35,40 @@ Options for "service install"
 The workbench is behind a password generated on first run and printed once.
 Under systemd that print lands in the journal: journalctl --user -u pier -e
 `;
-const { values, positionals } = parseArgs({
-    allowPositionals: true,
-    strict: false,
-    options: {
-        help: { type: "boolean", short: "h" },
-        version: { type: "boolean", short: "v" },
-        force: { type: "boolean" },
-        port: { type: "string" },
-        host: { type: "string" },
-        "pier-home": { type: "string" },
-    },
-});
-const [command, subcommand] = positionals;
+const say = (message) => void process.stdout.write(`${message}\n`);
+const fail = (message) => {
+    process.stderr.write(`pier: ${message}\n`);
+    process.exit(2);
+};
+const parsed = (() => {
+    try {
+        return parseArgs({
+            allowPositionals: true,
+            strict: true,
+            options: {
+                help: { type: "boolean", short: "h" },
+                version: { type: "boolean", short: "v" },
+                check: { type: "boolean" },
+                force: { type: "boolean" },
+                port: { type: "string" },
+                host: { type: "string" },
+                "pier-home": { type: "string" },
+            },
+        });
+    }
+    catch (err) {
+        return fail(err instanceof Error ? err.message : String(err));
+    }
+})();
+const { values, positionals } = parsed;
+const [command, subcommand, ...extra] = positionals;
+if (extra.length)
+    fail(`unexpected argument "${extra[0]}"`);
+const allowOnly = (allowed, usage) => {
+    const invalid = Object.keys(values).find((key) => !allowed.includes(key));
+    if (invalid)
+        fail(`--${invalid} is not valid for ${usage}`);
+};
 if (values.help || command === "help") {
     process.stdout.write(HELP);
 }
@@ -48,49 +76,169 @@ else if (values.version || command === "version") {
     process.stdout.write(`${version}\n`);
 }
 else if (!command) {
+    allowOnly([], "pier");
     // The server starts on import; this file stays a dispatcher.
     await import("./main.js");
 }
 else if (command === "service") {
     await service(subcommand);
 }
+else if (command === "backup") {
+    if (subcommand)
+        fail(`unexpected argument "${subcommand}"`);
+    allowOnly([], "pier backup");
+    await backup();
+}
+else if (command === "update") {
+    if (subcommand)
+        fail(`unexpected argument "${subcommand}"`);
+    allowOnly(["check"], "pier update");
+    await update(values.check === true);
+}
+else if (command === "restart" || command === "reload") {
+    if (subcommand)
+        fail(`unexpected argument "${subcommand}"`);
+    allowOnly([], `pier ${command}`);
+    await signalService(command);
+}
 else {
     process.stderr.write(`pier: unknown command "${command}"\n\n${HELP}`);
     process.exit(2);
 }
+/**
+ * Checking is Pier's own code; applying it is npm's. Under systemd the work is
+ * handed to a second unit — this process is about to be restarted, and a child
+ * of the service being restarted dies with it.
+ */
+async function update(checkOnly) {
+    const check = new UpdateCheck(version);
+    await check.refresh();
+    const { current, latest, available } = check.status();
+    if (latest === null) {
+        process.stderr.write(`could not reach the registry — running ${current}.\n`);
+        process.exitCode = 1;
+        return;
+    }
+    if (!available) {
+        process.stdout.write(`${current} is the latest.\n`);
+        return;
+    }
+    process.stdout.write(`${latest} is out (running ${current}).\n`);
+    if (checkOnly)
+        return;
+    const { startUpdate } = await import("./service.js");
+    if (process.platform === "linux") {
+        const started = startUpdate({ say });
+        if (started === "started")
+            return;
+        if (started === "failed") {
+            process.exitCode = 1;
+            return;
+        }
+    }
+    // No service manager owns this process, so do not mutate its rollback point
+    // until the operator is ready to run all three steps.
+    say(`pier backup`);
+    say(`npm install -g @timqi/pier@${latest}`);
+    say(`then restart Pier.`);
+}
+/** Both are signals to the running unit: SIGUSR2 drains then exits (systemd
+ * starts the next process), SIGHUP reloads config in place (main.ts). */
+async function signalService(command) {
+    if (process.platform !== "linux") {
+        return fail(`only under the systemd service — send ${command === "restart" ? "SIGUSR2" : "SIGHUP"} to the pier process yourself`);
+    }
+    const { UNIT_NAME } = await import("./service.js");
+    const signal = command === "restart" ? "SIGUSR2" : "SIGHUP";
+    try {
+        // `--kill-who`, not the newer `--kill-whom`: the old spelling is the one
+        // every systemd still parses (systemd/systemd#29793).
+        execFileSync("systemctl", ["--user", "kill", "-s", signal, "--kill-who=main", UNIT_NAME], { stdio: "inherit" });
+    }
+    catch (err) {
+        // A failed kill already printed why on the inherited stderr; a missing
+        // systemctl printed nothing, so name it (same shape as `service status`).
+        if (err.code === "ENOENT") {
+            process.stderr.write(`pier: systemctl is not on PATH — no systemd here.\n`);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    say(command === "restart"
+        ? "draining — running turns finish first (up to 5 minutes), then Pier restarts."
+        : "reloading — adapters re-read their config; idle sessions re-open with the current one.");
+}
+async function backup() {
+    const [{ backupDb }, { PIER_DB }] = await Promise.all([import("./db.js"), import("./paths.js")]);
+    const path = backupDb(PIER_DB);
+    process.stdout.write(path ? `backed up ${path}\n` : `no database yet — nothing to back up.\n`);
+}
+function commandPath(name) {
+    for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+        const path = join(dir || ".", name);
+        try {
+            accessSync(path, constants.X_OK);
+            return realpathSync(path);
+        }
+        catch {
+            // Keep looking: version managers commonly put several prefixes on PATH.
+        }
+    }
+    return fail(`${name} is not executable on PATH`);
+}
 async function service(action = "status") {
     const { install, uninstall, UNIT_NAME } = await import("./service.js");
-    const say = (message) => void process.stdout.write(`${message}\n`);
-    if (action !== "status" && process.platform !== "linux") {
+    const systemdAction = action === "install" || action === "uninstall";
+    if (systemdAction && process.platform !== "linux") {
         process.stderr.write(`pier service is systemd, so Linux only — this is ${process.platform}.\n` +
             `Run "pier" in a terminal, or under whatever supervisor you already use;\n` +
             `it needs no arguments and keeps its state in $PIER_HOME (~/.pier).\n`);
         process.exit(2);
     }
     switch (action) {
-        case "install":
-            install({
-                // The node running this command, not whatever systemd would find on a
-                // minimal PATH — and the entry beside this file, not a checkout.
+        case "install": { // The installed unit owns this Node prefix until replaced.
+            allowOnly(["force", "port", "host", "pier-home"], "pier service install");
+            const port = typeof values.port === "string" ? Number(values.port) : 3141;
+            if (!Number.isInteger(port) || port < 1 || port > 65_535)
+                fail("--port must be an integer from 1 to 65535");
+            const host = typeof values.host === "string" ? values.host : "127.0.0.1";
+            if (!host || /\s|[\0\r\n]/.test(host))
+                fail("--host must be one address with no whitespace");
+            const rawHome = values["pier-home"];
+            if (rawHome === "")
+                fail("--pier-home must not be empty");
+            const pierHome = typeof rawHome === "string" ? resolve(rawHome) : undefined;
+            if (!install({
                 execPath: process.execPath,
+                npmPath: commandPath("npm"),
                 entry: fileURLToPath(new URL("./main.js", import.meta.url)),
-                host: typeof values.host === "string" ? values.host : "127.0.0.1",
-                port: typeof values.port === "string" ? Number(values.port) : 3141,
-                pierHome: typeof values["pier-home"] === "string" ? values["pier-home"] : undefined,
+                host,
+                port,
+                pierHome,
                 force: values.force === true,
                 say,
-            });
+            }))
+                process.exitCode = 1;
             return;
+        }
         case "uninstall":
-            uninstall(undefined, say);
+            allowOnly([], "pier service uninstall");
+            if (!uninstall(undefined, say))
+                process.exitCode = 1;
             return;
         case "status":
+            allowOnly([], "pier service status");
             try {
                 // Inherited, not captured: systemctl's own output is the answer, and
                 // its exit code is nonzero for a service that is merely stopped.
                 execFileSync("systemctl", ["--user", "status", UNIT_NAME], { stdio: "inherit" });
             }
-            catch {
+            catch (err) {
+                // A stopped service already printed its status; a missing systemctl
+                // printed nothing, so name it.
+                if (err.code === "ENOENT") {
+                    process.stderr.write(`pier: systemctl is not on PATH — no systemd here.\n`);
+                }
                 process.exitCode = 1;
             }
             return;

package/dist/core/hub.js

@@ -1,6 +1,20 @@
 // Per-session event fan-out with a replay ring buffer. The single stamping
 // point for seq/ts — nothing else in the system numbers events.
+import { logger } from "../log.js";
+const log = logger("core");
 const RING_SIZE = 1000;
+/** A throwing subscriber costs only itself — emit() runs on the emitter's
+ *  stack (Pi's dispatch path, for session events), which must not unwind. */
+function fanOut(subscribers, event) {
+    for (const fn of subscribers) {
+        try {
+            fn(event);
+        }
+        catch (err) {
+            log.warn(`event subscriber threw: ${String(err)}`);
+        }
+    }
+}
 export class EventHub {
     buses = new Map();
     // Workspace bus: no seq, no replay — a client that missed events just
@@ -25,9 +39,7 @@ export class EventHub {
         b.buffer.push(event);
         if (b.buffer.length > RING_SIZE)
             b.buffer.shift();
-        for (const fn of b.subscribers)
-            fn(event);
-        return event;
+        fanOut(b.subscribers, event);
     }
     subscribe(sessionId, fn) {
         const b = this.bus(sessionId);
@@ -39,8 +51,7 @@ export class EventHub {
         return this.bus(sessionId).buffer.filter((e) => e.seq > afterSeq);
     }
     emitWorkspace(event) {
-        for (const fn of this.workspace)
-            fn(event);
+        fanOut(this.workspace, event);
     }
     subscribeWorkspace(fn) {
         this.workspace.add(fn);
@@ -50,4 +61,24 @@ export class EventHub {
     lastSeq(sessionId) {
         return this.buses.get(sessionId)?.seq ?? 0;
     }
+    /** Whether anyone is still watching this session (an open SSE stream). */
+    hasSubscribers(sessionId) {
+        return (this.buses.get(sessionId)?.subscribers.size ?? 0) > 0;
+    }
+    /**
+     * Release the ring of a session nobody is watching — the memory an evicted
+     * session leaves behind (1000 events of text, per session, forever).
+     *
+     * The bus itself stays, holding its seq: a client that reconnects with a
+     * Last-Event-ID drops anything numbered at or below what it saw, so a
+     * counter restarting at 1 would make every later event invisible to it.
+     * What is left is a number and an empty set.
+     */
+    dropReplay(sessionId) {
+        if (this.hasSubscribers(sessionId))
+            return;
+        const b = this.buses.get(sessionId);
+        if (b)
+            b.buffer = [];
+    }
 }

package/dist/core/identity.js

@@ -61,6 +61,11 @@ export class SenderPrefix {
         const when = gap || newDay ? `${newDay ? `${day(now)} ` : ""}${hhmm(now)}` : "";
         return `[${[who, when].filter(Boolean).join(" ")}]`;
     }
+    /** Forget a session being evicted. Costs one redundant header if it comes
+     *  back, which is the same price a restart already pays. */
+    forget(sessionId) {
+        this.seen.delete(sessionId);
+    }
 }
 /** Put the prefix above the message, or hand the message back untouched. */
 export const withPrefix = (prefix, text) => prefix ? `${prefix}\n${text}` : text;

package/dist/core/inbound-file.js

@@ -0,0 +1,70 @@
+// The inbound-file convention, browser-safe: what a user's attachment may be
+// called, the marker line that tells the agent about it, the parser that
+// splits it back out of a message, and the size cap both ends enforce.
+// Producers are node code (channels/, web/server.ts) but the web composer
+// builds markers and the web chat parses them in the browser, so the grammar
+// lives in a module with no node imports that either side can load. The
+// filesystem half (saving the bytes) is core/inbox.ts.
+/** One cap for every inbound path: composer, upload route, Slack metadata. */
+export const MAX_INBOUND_BYTES = 32 * 1024 * 1024;
+/** Extension for a name-less upload (a pasted screenshot has no filename). */
+const MIME_EXT = {
+    "image/png": ".png",
+    "image/jpeg": ".jpg",
+    "image/gif": ".gif",
+    "image/webp": ".webp",
+    "application/pdf": ".pdf",
+    "text/plain": ".txt",
+};
+/**
+ * A filename that is safe as a path segment and inside a markdown link:
+ * basename only (no traversal), whitespace and link-breaking characters
+ * folded to `-`, length capped.
+ */
+export function safeName(name, mimeType) {
+    const base = (name ?? "").split("/").pop().replace(/[\s\\()[\]<>%#?]/g, "-");
+    if (!base || base === "." || base === "..")
+        return `file${MIME_EXT[mimeType] ?? ""}`;
+    if (base.length <= 64)
+        return base;
+    const dot = base.lastIndexOf(".");
+    const ext = dot > 0 ? base.slice(dot, dot + 16) : "";
+    return base.slice(0, 64 - ext.length) + ext;
+}
+/**
+ * The prompt line for a saved file — the attachment convention, inbound. The
+ * path is percent-encoded (parentheses included, which encodeURI leaves
+ * alone) so the link survives markdown and the marker regex even when
+ * `PIER_HOME` contains spaces or parens; splitInboundFiles decodes.
+ */
+export const fileMarker = (path) => `[${path.split("/").pop() ?? "file"}](file://${encodeURI(path).replace(/\(/g, "%28").replace(/\)/g, "%29")})`;
+/**
+ * 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.
+ */
+export const lostMarker = (name, reason) => `[attachment lost: ${name} — ${reason}]`;
+// A whole line that is one `[name](file:///…)` link — what fileMarker emits.
+const MARKER_RE = /^\[[^\]\n]*\]\(\s*<?file:\/\/(\/[^)>\s]*)>?\s*\)$/;
+/**
+ * Split a user message into its typed text and the attached files' paths.
+ * Only the contiguous *trailing* block of marker lines is an attachment —
+ * that is where every producer puts them — so a `file://` link the user
+ * wrote mid-message stays message text.
+ */
+export function splitInboundFiles(raw) {
+    const lines = raw.split("\n");
+    let start = lines.length;
+    while (start > 0 && MARKER_RE.test(lines[start - 1].trim()))
+        start--;
+    const paths = lines.slice(start).map((line) => {
+        const path = MARKER_RE.exec(line.trim())[1];
+        try {
+            return decodeURIComponent(path);
+        }
+        catch {
+            return path; // not percent-encoded — take the path as written
+        }
+    });
+    return { text: lines.slice(0, start).join("\n").trimEnd(), paths };
+}

package/dist/core/inbox.js

@@ -0,0 +1,32 @@
+// Inbound user files: bytes land on disk exactly once.
+//
+// A photo pasted on the web, dropped in Telegram or uploaded to Slack used to
+// travel as base64 through the seam into the transcript, where it was re-sent
+// with every provider request until compaction. Now the adapter (or the web
+// upload route) saves the bytes under `$PIER_HOME/inbox/<channel>/` and the
+// prompt carries only a marker line (core/inbound-file.ts owns that grammar),
+// so the agent reads a file only when it decides the file is worth looking at.
+import { mkdir, writeFile } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import { basename, join } from "node:path";
+import { pierPath } from "../paths.js";
+import { safeName } from "./inbound-file.js";
+/** Where every inbound file lives; web/files.ts allowlists this root. */
+export const INBOX_DIR = pierPath("inbox");
+/**
+ * Write one inbound file and return its absolute path. The timestamp-random
+ * prefix keeps concurrent saves collision-free (`wx` turns the impossible
+ * collision into an error instead of an overwrite) and makes `ls` read as a
+ * timeline. Owner-only modes: uploads are private conversation content on a
+ * possibly shared machine. Nothing is ever deleted here — pruning the inbox
+ * is the operator's call (docs/deploy.md).
+ */
+export async function saveInbound(channelId, name, mimeType, bytes) {
+    // The channel id is ours ("web" | "telegram" | "slack"), not user input,
+    // but basename() keeps a future id honest.
+    const dir = join(INBOX_DIR, basename(channelId));
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const path = join(dir, `${String(Date.now())}-${randomBytes(3).toString("hex")}-${safeName(name, mimeType)}`);
+    await writeFile(path, bytes, { mode: 0o600, flag: "wx" });
+    return path;
+}

package/dist/core/queue.js

@@ -1,11 +1,17 @@
 // The whole queue policy. Fixed by docs/architecture.md — do not add options.
 export function decide(msg, state) {
+    // An explicit mode takes the text verbatim: IM sends steer for every
+    // message, so a leading "!" there is content, not a control prefix —
+    // consuming it silently rewrote what the person typed.
+    if (msg.mode === "steer" || msg.mode === "followUp") {
+        return { action: state === "idle" ? "prompt" : msg.mode, text: msg.text };
+    }
+    // On auto the "!" is a control prefix and always consumed — whether the
+    // turn happened to end first must not decide if it was content. Idle just
+    // means there is nothing to steer, so it degenerates to a prompt.
     const steerPrefixed = msg.text.startsWith("!");
     const text = steerPrefixed ? msg.text.slice(1).trimStart() : msg.text;
     if (state === "idle")
         return { action: "prompt", text };
-    if (msg.mode === "steer" || msg.mode === "followUp") {
-        return { action: msg.mode, text };
-    }
     return { action: steerPrefixed ? "steer" : "followUp", text };
 }