@timqi/pier 0.0.1 → 0.0.2

package/dist/web/server.js

@@ -7,36 +7,17 @@ import { Hono } from "hono";
 import { streamSSE } from "hono/streaming";
 import { EventHub } from "../core/hub.js";
 import { Router } from "../core/router.js";
-import { logger } from "../log.js";
+import { registerExplorerRoutes } from "./explorer.js";
 import { guarded, registerFileRoutes } from "./files.js";
 import { isThinkingLevel } from "../core/types.js";
-import { normalizePublicUrl } from "../settings.js";
+import { saveInbound } from "../core/inbox.js";
+import { MAX_INBOUND_BYTES } from "../core/inbound-file.js";
+import { registerInstanceRoutes } from "./instance.js";
+import { registerProviderRoutes } from "./providers.js";
 const HEARTBEAT_MS = 15_000;
-/** Client reports per minute, for the whole server: a browser bug can fire in
- *  a loop, and the journal is shared with everything else Pier says. */
-const CLIENT_LOG_PER_MINUTE = 60;
-const MAX_IMAGES = 8;
-const MAX_IMAGE_BYTES = 8 * 1024 * 1024; // per image, base64 length ≈ bytes × 4/3
-/** Validate at the seam: malformed attachments are rejected, never half-sent. */
-function parseImages(raw) {
-    if (raw === undefined)
-        return [];
-    if (!Array.isArray(raw) || raw.length > MAX_IMAGES)
-        return { error: "invalid images" };
-    const images = [];
-    for (const i of raw) {
-        if (typeof i?.data !== "string" ||
-            !i.data ||
-            i.data.length > (MAX_IMAGE_BYTES * 4) / 3 ||
-            typeof i?.mimeType !== "string" ||
-            !i.mimeType.startsWith("image/")) {
-            return { error: "invalid images" };
-        }
-        images.push({ data: i.data, mimeType: i.mimeType });
-    }
-    return images;
-}
-export function createServer({ factory, router, hub, sessions: state, config, settings, secrets, onUnlocked, backgroundRuns }) {
+// Canonical base64 only: Buffer.from(.., "base64") happily "decodes" garbage.
+const BASE64_RE = /^[A-Za-z0-9+/]+={0,2}$/;
+export function createServer({ factory, router, hub, sessions: state, config, providers, settings, secrets, onUnlocked, updates, backgroundRuns, }) {
     const app = new Hono();
     // A finished turn marks its session unread until some client reports it was
     // seen (session selected + tab visible → POST read below). Server-side so
@@ -68,6 +49,10 @@ export function createServer({ factory, router, hub, sessions: state, config, se
         const sessions = await factory.list();
         for (const s of sessions)
             nascent.delete(s.id);
+        // A session created but never prompted would otherwise be listed forever.
+        for (const [id, n] of nascent)
+            if (Date.now() - n.createdAt > 86_400_000)
+                nascent.delete(id);
         return c.json([...[...nascent].map(([id, n]) => ({ id, ...n })), ...sessions].map((s) => ({
             ...s,
             state: router.stateOf(s.id) ?? "idle",
@@ -103,6 +88,8 @@ export function createServer({ factory, router, hub, sessions: state, config, se
         const body = await c.req.json().catch(() => null);
         if (typeof body?.pinned !== "boolean")
             return c.json({ error: "pinned required" }, 400);
+        // The id is trusted: checking existence costs a session list per click,
+        // and the surface is operator-authenticated. Worst case is a stray row.
         state.set("pinned", c.req.param("id"), body.pinned);
         hub.emitWorkspace({ type: "sessions-changed" });
         return c.json({ pinned: body.pinned });
@@ -123,20 +110,24 @@ export function createServer({ factory, router, hub, sessions: state, config, se
             backgroundRuns: backgroundRuns?.(id) ?? [],
         });
     });
-    // Transcript images by their history ordinal: the snapshot ships refs, the
-    // browser pulls (and caches) the bytes only for what it renders.
-    guarded(app, "GET", "/api/sessions/:id/images/:ordinal", 404, async (c) => {
-        const ordinal = Number(c.req.param("ordinal"));
-        if (!Number.isInteger(ordinal) || ordinal < 0)
-            return c.json({ error: "bad ordinal" }, 400);
-        const session = await ensure(c.req.param("id"));
-        const image = await session.image(ordinal);
-        if (!image)
-            return c.json({ error: "no such image" }, 404);
-        return c.body(Buffer.from(image.data, "base64"), 200, {
-            "content-type": image.mimeType,
-            "cache-control": "private, max-age=3600",
-        });
+    // Composer attachments: bytes land in the inbox, the message carries the
+    // path as a `[name](file:///…)` line the client builds itself — upload
+    // first, so the text it sends (and optimistically renders) is final.
+    guarded(app, "POST", "/api/inbox", 400, async (c) => {
+        const body = await c.req.json().catch(() => null);
+        if (typeof body?.data !== "string" ||
+            !body.data ||
+            // Cheap ceiling before decoding; the exact check is on the bytes.
+            body.data.length > Math.ceil(MAX_INBOUND_BYTES / 3) * 4 + 4 ||
+            !BASE64_RE.test(body.data) ||
+            typeof body?.mimeType !== "string") {
+            return c.json({ error: "invalid file" }, 400);
+        }
+        const name = typeof body.name === "string" ? body.name : undefined;
+        const bytes = Buffer.from(body.data, "base64");
+        if (bytes.length > MAX_INBOUND_BYTES)
+            return c.json({ error: "invalid file" }, 400);
+        return c.json({ path: await saveInbound("web", name, body.mimeType, bytes) });
     });
     // Backend model catalog, no session needed: surfaces that configure what a
     // *future* session launches with (IM chats) have none to ask.
@@ -180,21 +171,14 @@ export function createServer({ factory, router, hub, sessions: state, config, se
     app.post("/api/sessions/:id/messages", async (c) => {
         const id = c.req.param("id");
         const body = await c.req.json().catch(() => null);
-        if (!body || typeof body.text !== "string") {
+        if (!body || typeof body.text !== "string" || !body.text.trim()) {
             return c.json({ error: "text required" }, 400);
         }
-        const images = parseImages(body.images);
-        if ("error" in images)
-            return c.json({ error: images.error }, 400);
-        if (!body.text.trim() && images.length === 0) {
-            return c.json({ error: "text or images required" }, 400);
-        }
         const mode = body.mode === "steer" || body.mode === "followUp" ? body.mode : "auto";
         const { sessionId } = await router.dispatch({
             key: { channelId: "web", conversationId: id },
             senderId: "web",
             text: body.text,
-            images: images.length ? images : undefined,
             mode,
         });
         return c.json({ sessionId }, 202);
@@ -209,6 +193,10 @@ export function createServer({ factory, router, hub, sessions: state, config, se
         if (!Number.isInteger(index) || index < 0 || typeof body?.text !== "string" || !body.text.trim()) {
             return c.json({ error: "index and text required" }, 400);
         }
+        // Asked before touching anything: the dispatch below would be refused by
+        // the drain gate, and by then the transcript is already rewound.
+        if (router.isDraining())
+            return c.json({ error: "Pier is restarting — try again in a moment" }, 503);
         const session = await ensure(id);
         if (session.state === "streaming")
             return c.json({ error: "busy — stop the turn first" }, 409);
@@ -231,6 +219,9 @@ export function createServer({ factory, router, hub, sessions: state, config, se
         if (mode !== "steer" && mode !== "restart") {
             return c.json({ error: "mode must be steer or restart" }, 400);
         }
+        // Same reason as edit above: a refused dispatch must not cost the queue.
+        if (router.isDraining())
+            return c.json({ error: "Pier is restarting — try again in a moment" }, 503);
         const session = await ensure(id);
         const { steering, followUp } = await session.clearQueue();
         const text = [...steering, ...followUp].join("\n").trim();
@@ -252,30 +243,6 @@ export function createServer({ factory, router, hub, sessions: state, config, se
         const { steering, followUp } = await session.clearQueue();
         return c.json({ messages: [...steering, ...followUp] });
     });
-    // The browser's half of the log. A workbench that threw after the response
-    // left the server is otherwise invisible here (ui/report.ts) — this is the
-    // one route whose entire purpose is to make it visible.
-    const clientLog = logger("client");
-    let reports = [];
-    app.post("/api/client-log", async (c) => {
-        const body = (await c.req.json().catch(() => null));
-        if (typeof body?.message !== "string" || !body.message.trim()) {
-            return c.json({ error: "message required" }, 400);
-        }
-        const now = Date.now();
-        reports = reports.filter((at) => now - at < 60_000);
-        if (reports.length >= CLIENT_LOG_PER_MINUTE)
-            return c.body(null, 429);
-        reports.push(now);
-        const cap = (value, max) => typeof value === "string" ? value.slice(0, max) : "";
-        const where = cap(body.view, 120);
-        const stack = cap(body.stack, 2000);
-        // One line, ua included: "only on iOS" is the answer half these questions
-        // have, and the report is the only place it exists.
-        clientLog.warn(`${cap(body.message, 500)} [${where || "/"}] ${cap(c.req.header("user-agent"), 160)}` +
-            (stack ? `\n${stack}` : ""));
-        return c.body(null, 204);
-    });
     app.post("/api/sessions/:id/abort", async (c) => {
         const id = c.req.param("id");
         await router.abort(id);
@@ -284,7 +251,8 @@ export function createServer({ factory, router, hub, sessions: state, config, se
     // Workspace stream: one per client, keeps every session list in sync
     // (created/pinned → re-list, run state → patch) without polling.
     app.get("/api/events", (c) => streamSSE(c, async (stream) => {
-        const unsubscribe = hub.subscribeWorkspace((e) => void stream.writeSSE({ data: JSON.stringify(e) }));
+        // A write to a torn-down stream must not become an unhandled rejection.
+        const unsubscribe = hub.subscribeWorkspace((e) => void stream.writeSSE({ data: JSON.stringify(e) }).catch(() => { }));
         stream.onAbort(unsubscribe);
         while (!stream.aborted) {
             await stream.sleep(HEARTBEAT_MS);
@@ -300,7 +268,8 @@ export function createServer({ factory, router, hub, sessions: state, config, se
             const send = (e) => stream.writeSSE({ id: String(e.seq), data: JSON.stringify(e) });
             for (const e of hub.replay(id, lastId))
                 await send(e);
-            const unsubscribe = hub.subscribe(id, (e) => void send(e));
+            // Same as above: the client may be gone by the time an event fires.
+            const unsubscribe = hub.subscribe(id, (e) => void send(e).catch(() => { }));
             stream.onAbort(unsubscribe);
             // Heartbeat keeps proxies from closing the stream; loop ends on abort.
             while (!stream.aborted) {
@@ -309,52 +278,10 @@ export function createServer({ factory, router, hub, sessions: state, config, se
             }
         });
     });
-    // Instance settings. The password lives behind its own route (web/auth.ts):
-    // it is a credential, and changing it takes the old one.
-    app.get("/api/settings", (c) => c.json(settings.get()));
-    app.put("/api/settings", async (c) => {
-        const body = await c.req.json().catch(() => null);
-        if (typeof body?.publicUrl !== "string")
-            return c.json({ error: "publicUrl required" }, 400);
-        const publicUrl = normalizePublicUrl(body.publicUrl);
-        if (publicUrl === null) {
-            return c.json({ error: "not a URL: expected http(s)://host, no query or fragment" }, 400);
-        }
-        return c.json(settings.setPublicUrl(publicUrl));
-    });
-    // Layer-1 key status and control (Console → Settings → Security). The GET
-    // is what a locked instance shows; unlock is how it recovers without a
-    // restart, and rotate is the only way to change how the KEK is protected.
-    const secretsStatus = () => ({
-        state: secrets.state,
-        mode: secrets.mode ?? null,
-        ...(secrets.state === "locked" ? { reason: secrets.lockedReason } : {}),
-    });
-    app.get("/api/secrets", (c) => c.json(secretsStatus()));
-    app.post("/api/secrets/unlock", async (c) => {
-        try {
-            await secrets.unlock();
-        }
-        catch (err) {
-            return c.json({ error: String(err) }, 500);
-        }
-        onUnlocked?.();
-        return c.json(secretsStatus());
-    });
-    app.post("/api/secrets/rotate", async (c) => {
-        const body = (await c.req.json().catch(() => ({})));
-        if (body.mode !== undefined && body.mode !== "vt" && body.mode !== "file") {
-            return c.json({ error: "mode must be vt or file" }, 400);
-        }
-        try {
-            await secrets.rotateKek(body.mode);
-        }
-        catch (err) {
-            return c.json({ error: String(err) }, 500);
-        }
-        return c.json(secretsStatus());
-    });
+    registerInstanceRoutes(app, { settings, updates, secrets, onUnlocked });
+    registerProviderRoutes(app, providers);
     registerFileRoutes(app, { factory, config, nascentCwd: (id) => nascent.get(id)?.cwd });
+    registerExplorerRoutes(app, { factory, nascentCwds: () => [...nascent.values()].map((n) => n.cwd) });
     // serveStatic resolves `root` against the *working directory*, and an
     // installed Pier is started from wherever the operator happens to be. The
     // bundle sits beside this module in both trees — src/web/public when tsx

package/docs/deploy.md

@@ -24,17 +24,15 @@ you want the unit to say something different.
 ## Prerequisites
 
 - Node 24 or newer (`node:sqlite` is used unflagged).
-- The `sqlite3` CLI, for the off-machine backup and password steps below. Pier
-  itself does not need it.
-- A checkout, built once:
-
-```sh
-git clone git@github.com:timqi/pier.git ~/pier
-cd ~/pier && npm ci && npm run build
-```
-
-The unit below runs the build output, so a deploy is always "update the
-checkout, rebuild, restart" — never "run from source".
+- A user-writable global npm prefix. The updater runs as you, so an initial
+  install that needed `sudo npm install -g` cannot later update itself.
+- The `sqlite3` CLI is optional, for the off-machine backup and password steps
+  below. Pier itself and its automatic update backup do not need it.
+- Pier installed globally: `npm install -g @timqi/pier`. The unit runs that
+  installed entry point, so a deploy is `pier update`. A checkout
+  (`git clone` + `npm ci && npm run build`) is the *develop* path; point the
+  unit's `ExecStart` at its `dist/main.js` if you run one as the service, and
+  update it with the "From a checkout" steps under Updating.
 
 ## The unit
 
@@ -44,7 +42,7 @@ or as a dedicated system user means an agent that cannot touch the files you
 wanted it to work on.
 
 `~/.config/systemd/user/pier.service` — what `pier service install` generates,
-with your node and your entry point filled in:
+with your absolute Node and package paths filled in:
 
 ```ini
 [Unit]
@@ -55,29 +53,33 @@ Wants=network-online.target
 
 [Service]
 Type=simple
-WorkingDirectory=%h/pier
-# An absolute path on purpose: systemd starts with a minimal PATH, so a node
-# installed by nvm/fnm/asdf is not on it. `command -v node` gives you this.
-ExecStart=/usr/bin/node dist/main.js
-Environment=NODE_ENV=production
+WorkingDirectory=%h
+# Absolute paths on purpose: systemd starts with a minimal PATH, so a node
+# installed by nvm/fnm/asdf is not on it — the installer fills in the node
+# that installed Pier and the globally installed entry point.
+ExecStart="/absolute/path/to/node" "/absolute/npm/prefix/lib/node_modules/@timqi/pier/dist/main.js"
+Environment="NODE_ENV=production"
 # Loopback by default. Put a reverse proxy in front before widening this —
 # whoever reaches this port can drive an agent that runs a shell.
-Environment=HOST=127.0.0.1
-Environment=PORT=3141
-# Where the database, the boards and the generated password hash live.
-Environment=PIER_HOME=%h/.pier
+Environment="HOST=127.0.0.1"
+Environment="PORT=3141"
 Restart=always
 RestartSec=2
-# The journal is where the first-run password is printed, so keep it readable.
 StandardOutput=journal
 StandardError=journal
-# Otherwise every line is tagged "node"; this makes `journalctl -t pier` work.
 SyslogIdentifier=pier
 
 [Install]
 WantedBy=default.target
 ```
 
+`--pier-home` adds a quoted `PIER_HOME` environment line. Paths with spaces and
+literal systemd `%` specifiers are escaped. `pier service install` also writes an
+updater unit containing the exact npm executable currently on `PATH`. Re-run with
+`--force` after changing service settings or the Node/npm installation; it
+rewrites both units and restarts the running service. The limits drop-in remains
+operator-owned and is never overwritten.
+
 Enable it, and tell logind to keep your user manager alive after you log out —
 without lingering, every scheduled task stops when your SSH session ends:
 
@@ -167,7 +169,9 @@ journalctl --user -u pier --since -1h | grep 'tasks:'   # one area
 ```
 
 Every line is `area: message` — `core`, `agent`, `tasks`, `slack`, `telegram`,
-`channels`, `web`, `auth`, `boards`, `client`, `pier` — so an area is a grep
+`channels`, `slack.tool`, `auth`, `boards`, `client`, `db`, `drain`, `secrets`,
+`settings`, `credentials`, `update`, `web.providers`, `pier` — so an area is a
+grep
 and a level is a `-p`. The level reaches journald as a syslog priority prefix, which Pier
 emits only when systemd says the output is a journal (`$JOURNAL_STREAM`); run
 in a terminal, the same lines carry a timestamp and a level word instead.
@@ -214,42 +218,83 @@ new password is generated and printed:
 
 ```sh
 sqlite3 ~/.pier/db/pier.db 'DELETE FROM auth'
-systemctl --user restart pier
+pier restart
 ```
 
 Changing the password invalidates every session cookie: the cookies are signed
 with the stored hash.
 
+## Restarting and reloading
+
+```sh
+pier restart          # finish active work, then restart the service
+pier reload           # apply channel config and recycle idle sessions in place
+```
+
+Both commands signal the installed systemd service; they are not foreground
+process controls. `pier restart` refuses new messages and root Task runs, waits
+up to five minutes for active work, then exits for `Restart=always` to start the
+next process. At the deadline it records every aborted IM turn first, and the
+next process posts that note after its adapter starts. Cleanup after the deadline
+has one shared 10-second bound regardless of how many sessions are stuck.
+
+`pier reload` does not stop active work. It reloads Slack and Telegram adapters
+and immediately evicts idle sessions nobody is watching, so their next message
+opens with current agent files and configuration. Streaming sessions and
+sessions held by an open workbench stay attached until their normal eviction.
+
+An ordinary `systemctl --user restart pier` and `pier update` remain fast,
+hard-stop paths. Let active work finish first when using either one.
+
 ## Updating
 
-Manually, which is also exactly what an automated update has to do:
+```sh
+pier update           # installs the latest release; hard-stops/restarts Pier
+pier update --check   # only says whether one exists
+```
+
+The workbench footer says the same thing without being asked: the server checks
+`registry.npmjs.org` every six hours in the background, and the version turns
+into `v0.0.1 → 0.0.2` when there is something newer. A failed check is silent
+by design — an offline box is not a broken one.
+
+From a checkout instead, stop and back up before replacing the build:
 
 ```sh
+systemctl --user stop pier
+pier backup
 cd ~/pier
-git fetch --tags && git checkout v0.2.0   # a tag, not a branch
+git fetch --tags && git checkout v0.0.2   # a tag, not a branch
 npm ci && npm run build
-systemctl --user restart pier
+systemctl --user start pier
 ```
 
+For a service install, `pier update` stops Pier first; it does not use the
+graceful `pier restart` path. It snapshots the database to
+`~/.pier/db/pier.db.release.bak` before npm touches the package. This happens for
+every release, including releases with no schema change. If installation or
+backup fails, the updater unit still tries to start the previously installed
+service and reports the failure in its journal.
+
 A newer Pier brings its own schema up on the next start: the migrations run in
 one transaction before the port opens, and the version they leave behind is
-stamped in the database. Before touching an existing database it snapshots it
-to `~/.pier/db/pier.db.v<N>.bak` (`N` = the schema it was at), so the step you
-cannot forget is the one you never take. **Upgrades only.** Start an older Pier
-on a database a newer one has migrated and it refuses to run rather than write
-tables it does not understand — the way back down is that `.bak`:
+stamped in the database. It also snapshots the immediately preceding schema to
+`~/.pier/db/pier.db.v<N>.bak` (`N` = the schema it was at). **Upgrades only.**
+Start an older Pier on a database a newer one has migrated and it refuses to run
+rather than write tables it does not understand — the way back down is either
+the release backup or that schema snapshot:
 
 ```sh
 systemctl --user stop pier
-cd ~/.pier/db && rm -f pier.db pier.db-wal pier.db-shm && cp pier.db.v1.bak pier.db
-# then check out the Pier that speaks schema 1 again
+cd ~/.pier/db && rm -f pier.db pier.db-wal pier.db-shm && cp pier.db.release.bak pier.db
+# then reinstall the Pier release that created that backup
 ```
 
-The three newest snapshots are kept and older ones removed as later upgrades
-supersede them; each is a full copy of the database, so size grows with the
-database, not with the number of releases. They sit next to the database and
-therefore protect against a bad upgrade, not against a lost disk — an
-off-machine copy is still yours to take.
+The release backup is replaced atomically on each update. The three newest
+schema snapshots are also kept and older ones removed as later migrations
+supersede them. Each is a full copy of the database. They sit next to the
+database and therefore protect against a bad upgrade, not against a lost disk —
+an off-machine copy is still yours to take.
 
 ### Can it update itself?
 
@@ -259,32 +304,33 @@ in `pier.service`'s cgroup, so an update script spawned by Pier dies halfway
 through — sometimes after unpacking and before restarting, which is the one
 outcome worse than not updating.
 
-So the update runs as its own unit. `~/.config/systemd/user/pier-update.service`:
+So installation writes a second unit and `pier update` starts it after recording
+the running service's effective `PIER_HOME` in a runtime drop-in. That includes
+an operator environment override, so the updater cannot back up one database and
+migrate another. `~/.config/systemd/user/pier-update.service`:
 
 ```ini
 [Unit]
-Description=Update Pier to the latest tag
+Description=Update Pier to the latest published version
 
 [Service]
 Type=oneshot
-WorkingDirectory=%h/pier
-ExecStart=/bin/sh -lc 'git fetch --tags && git checkout "$(git describe --tags --abbrev=0 origin/main)" && npm ci && npm run build'
-ExecStartPost=/bin/sh -lc 'systemctl --user restart pier'
+ExecStart=systemctl --user stop pier.service
+ExecStart=/path/to/node /path/to/pier/dist/cli.js backup
+ExecStart=/path/to/node /recorded/path/to/npm install -g @timqi/pier@latest
+ExecStopPost=systemctl --user start pier.service
 ```
 
-Pier can then trigger an update with a single call that survives its own
-restart, because the work happens in a different cgroup:
-
-```sh
-systemctl --user start pier-update.service
-```
+`pier update` triggers that unit with a call that survives Pier's restart because
+the work happens in a different cgroup. Starting the unit directly is unsupported:
+the command first records the effective database home used by the running service.
 
 Deliberately **not** a `systemd.timer`. An unattended update is a machine that
-rewrites its own code from the network while holding your API keys, and it
-interrupts whatever session was mid-turn to do it. The intended shape is that
-Pier notices a newer release and says so (not built yet), while starting the
-update stays a decision someone makes. `Restart=always` above is what makes
-that decision cheap — the service comes back on its own.
+rewrites its own code from the network while holding your API keys, and its hard
+stop interrupts whatever session was mid-turn. Pier notices a newer release
+and says so in the workbench footer; starting the update stays a decision someone
+makes. The updater's `ExecStopPost` is what brings the service back after both
+success and failure.
 
 ## Remote access
 
@@ -294,14 +340,24 @@ elsewhere, pick a tunnel rather than a wider bind:
 - `ssh -L 3141:localhost:3141 server` — nothing to configure, nothing exposed.
 - Tailscale, or Cloudflare Tunnel — no open port, and TLS terminates outside.
 - A reverse proxy (Caddy, nginx) if you want a real hostname. Terminate TLS
-  there and pass `X-Forwarded-For`; Pier's login throttle counts per forwarded
-  client, and its session cookie is marked `Secure` when the proxy reports
-  `X-Forwarded-Proto: https`.
+  there, preserve the external `Host` (or pass `X-Forwarded-Host`), and pass
+  `X-Forwarded-For`; Pier uses the external host for write-origin checks and
+  counts login failures per forwarded client. Its session cookie is marked
+  `Secure` when the proxy reports `X-Forwarded-Proto: https`.
 
 ## Backups
 
-Two paths hold everything: `~/.pier/db/pier.db` (tasks, channels, the chat →
-session map, workbench state, settings, the password hash) and
-`~/.pier/boards/`. Copy the database with `sqlite3 ... "VACUUM INTO '…'"`
-rather than `cp`, which under WAL can miss the most recent commits. Pi's own session history lives under its
-config directory (`PI_CODING_AGENT_DIR`, `~/.pi/agent` by default).
+Three paths hold everything: `~/.pier/db/pier.db` (tasks, channels, the chat →
+session map, workbench state, settings, the password hash, and the sealed
+provider credentials and channel tokens), `~/.pier/master.key` (the key that
+seals them — without it the database's sealed values are unreadable), and
+`~/.pier/boards/`. `pier.db.release.bak` is the latest automatic pre-update copy.
+For off-machine backups, use `sqlite3 ... "VACUUM INTO '…'"` rather than `cp`,
+which under WAL can miss the most recent commits. Pi's own session history lives
+under `~/.pier/pi` (Pier sets `PI_CODING_AGENT_DIR` there unless the environment
+already names another directory).
+
+Inbound chat attachments (photos, uploads from any surface) accumulate under
+`~/.pier/inbox/<channel>/` and are never deleted by Pier — a transcript may
+reference them indefinitely. Prune old files by hand (or a cron) when disk
+matters; a pruned file degrades to a broken attachment link, nothing else.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timqi/pier",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "A self-hosted workspace for coding agents: web workbench and IM channels in front of Pi sessions",
   "license": "AGPL-3.0-only",
   "repository": "github:timqi/pier",

package/skills/pier-help/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: pier-help
+description: How Pier itself works — durable sessions and what survives a restart, how messages and files reach you from Slack and Telegram, in-chat commands (/stop, /settings, /bind), interrupting a running turn, and what only the operator's Console can change. Read before explaining Pier's behavior or advising a user on how to use it.
+---
+
+# How Pier works
+
+Pier is the workspace this session runs in: agent sessions behind chat
+surfaces — a web workbench and IM channels (Slack and Telegram today) — plus
+scheduled tasks, subagents and boards. Answer questions about it from the
+facts below. If the answer is not here, say you do not know how this instance
+is configured rather than guessing: the Console (Pier's admin web UI) is the
+operator's source of truth.
+
+## Sessions and persistence
+
+- One durable session per conversation: a web chat, a Slack thread, a
+  Telegram chat or topic. The mapping survives restarts — the next message
+  lands in the same transcript with its context intact.
+- Idle sessions leave memory but keep their transcript; they resume
+  transparently on the next message. Never promise that a restart or a pause
+  wipes context.
+- A fresh start is explicit: "New session" in the chat settings panel or the
+  web UI. The old transcript remains readable from the web workbench.
+- The web workbench can also rewind to an earlier user turn and re-prompt;
+  IM surfaces cannot.
+- A long session does not hit a wall: when the context fills, Pi compacts it
+  automatically — older turns become a summary. The transcript on disk keeps
+  everything, but detail can leave *your* context, so a very old turn is worth
+  re-reading rather than recalling. The web session header shows context used
+  and how much is left.
+
+## Files and images the user sends
+
+- A photo or file sent on any surface (web paste, Telegram photo/document,
+  Slack upload) is saved to `$PIER_HOME/inbox/` and reaches you as a trailing
+  `[name](file:///…)` line on the message — a path, not the content.
+- Read it with the read tool only when it matters to the task: every read
+  puts the content in your context for good. An image you never read costs
+  nothing.
+- The file stays on disk after the conversation moves on; link it back
+  (`[name](file:///…)`) whenever the user asks for it again.
+
+## Messages while you are working
+
+- On the web, a message sent mid-turn queues as a follow-up and lands after
+  the turn; a leading `!` interrupts instead — `!wrong file, stop` is injected
+  into the running turn as a steer.
+- From an IM chat, every mid-turn message steers the running turn directly —
+  no `!` needed, and a leading `!` is just content.
+- `/stop` aborts the current turn outright.
+
+## In-chat commands and the settings panel
+
+- `/settings` — or an addressed message with no text at all (a bare mention,
+  an empty DM) — opens a panel: model, reasoning level, new session
+  (optionally in a chosen directory), stop. Slack also accepts the bare words
+  `stop`, `settings`, `bind <code>`.
+- Panel taps never reach you. The next-step buttons under your own replies
+  do — a click arrives as an ordinary user message with that label.
+
+## What a turn looks like from outside
+
+- Telegram and Slack put a 👀 on the message that started a turn and take it
+  off when the turn settles; a restart and a periodic sweep clear stragglers.
+  A 👀 that never clears means the turn died, not that you are still thinking.
+- Every finished reply carries its cost: elapsed time and the context size at
+  completion (`1m14s · 32K tok`) — a running total, not this turn's spend. IM
+  shows it as a footer line, the web on hover.
+- A reply past the platform's message cap is split across several messages
+  (Telegram ~3.8k chars); the footer and the next-step buttons ride the last
+  one.
+
+## Who may talk (groups and binding)
+
+- Group messages pass a per-chat gate the operator sets: it can require a
+  mention, require the sender to be bound, or both. Dropped messages are
+  logged, never answered.
+- Binding: the operator issues a code in the Console; the user DMs the bot
+  `/bind <code>` (Slack: `bind <code>`). Codes expire after ~10 minutes.
+- An unbound DM sender is told how to bind at most once per 10 minutes;
+  their other messages are dropped. "The bot ignores my DMs" usually means
+  not bound.
+
+## Service restart, reload and update
+
+- `pier restart` is the graceful systemd path: it refuses new work, waits up to
+  five minutes for active turns and Task runs, then restarts. If the deadline
+  aborts an IM turn, the next process tells that conversation.
+- `pier reload` stays in-process: channel adapters re-read configuration and
+  idle, unwatched sessions reopen with current agent files on their next
+  message. Streaming or watched sessions are not interrupted.
+- `pier update` is deliberately different: the separate updater hard-stops the
+  service, backs up the database, replaces the package, and starts it again.
+  It can interrupt active work. All three are operator shell commands for an
+  installed Linux systemd service, not tools available to the agent.
+
+## Only the Console can change
+
+Channel tokens and connections, per-chat gate policies, bind codes, provider
+logins and credentials, the public address, security unlock. You have no tool
+for any of these: point the user at the Console instead of improvising.
+
+## The rest of the surface
+
+- Chat conventions — next-step buttons, `file://` attachments, staying
+  silent, `[name<id> time]` sender headers — are in `<pier>/AGENTS.md`,
+  already in your context.
+- Delegating and scheduling work: the pier-tasks skill. Reading and posting
+  Slack: pier-slack. Presenting a report as a page: pier-boards.