@timqi/pier 0.0.8 → 0.0.15

package/dist/web/server.js

@@ -14,8 +14,11 @@ import { Router } from "../core/router.js";
 import { registerExplorerRoutes } from "./explorer.js";
 import { guarded, registerFileRoutes } from "./files.js";
 import { isThinkingLevel } from "../core/types.js";
+import { SESSION_TITLE_MAX } from "../limits.js";
 import { saveInbound } from "../core/inbox.js";
 import { MAX_INBOUND_BYTES } from "../core/inbound-file.js";
+import { RepoIndex } from "./repos.js";
+import {} from "./session-state.js";
 import { registerInstanceRoutes } from "./instance.js";
 import { registerProviderRoutes } from "./providers.js";
 const log = logger("web");
@@ -37,7 +40,7 @@ export const withTabPrefix = (html, prefix) => prefix
 const HEARTBEAT_MS = 15_000;
 // 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, reload, updates, updater, backgroundRuns, }) {
+export function createServer({ factory, router, hub, sessions: state, config, providers, settings, catalog, names, onToolsChanged, validateCustomTools, secrets, onUnlocked, reload, updates, updater, backgroundRuns, channelOf, }) {
     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
@@ -57,6 +60,8 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
         state.setUnread(e.sessionId, true);
         hub.emitWorkspace({ type: "sessions-changed" });
     });
+    // Repository identity per project directory, refreshed off the request path.
+    const repos = new RepoIndex(() => hub.emitWorkspace({ type: "sessions-changed" }));
     /** Background runs this session launched that are still in flight. */
     const activeRuns = (id) => backgroundRuns?.(id).filter((r) => r.state === "queued" || r.state === "running").length ?? 0;
     /** The web channel's session for `id` — every session route resolves here. */
@@ -65,37 +70,38 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
     // only once the first assistant message lands. Merged into the list below
     // so every client sees a new session immediately; dropped once Pi lists it.
     const nascent = new Map();
-    // listAll parses every transcript. Concurrent consumers share that work,
-    // but the result is not retained: an explicit All-sessions open stays fresh.
+    /** `ensure`, plus ghost cleanup. A session created and never messaged does
+     *  not survive a restart or an eviction (Pi persisted nothing), but while
+     *  this process lives it is in `nascent` and therefore in the rail — left
+     *  alone, clicking it 404s forever. The load path is where a ghost is
+     *  discovered, so it is where the entry and its pin are dropped and every
+     *  rail told; the 404 then says what happened instead of looking like a
+     *  crash (§5b). */
+    const ensureLoadable = async (id) => {
+        try {
+            return await ensure(id);
+        }
+        catch (err) {
+            if (String(err).includes("unknown session")) {
+                nascent.delete(id);
+                state.forget(id);
+                hub.emitWorkspace({ type: "sessions-changed" });
+                throw new Error(`session ${id} no longer exists — it never got a first reply, so nothing was persisted; its rail entry was removed`);
+            }
+            throw err;
+        }
+    };
+    // A listing stats every session file and parses whatever grew — milliseconds
+    // warm, one scan cold. Concurrent consumers share it, whatever the factory
+    // behind the seam retains of its own; nothing here is cached past the last
+    // of them.
     let listing;
-    let projectBackfillNeeded = state.needsProjectBackfill();
-    const listSessions = () => listing ??= factory.list()
-        .then((rows) => {
-        state.remember(rows);
-        return rows;
-    })
-        .finally(() => {
+    const listSessions = () => listing ??= factory.list().finally(() => {
         listing = undefined;
     });
-    const present = (s, pinned, unread) => ({
-        ...s,
-        state: router.stateOf(s.id) ?? "idle",
-        pinned,
-        unread,
-        activeRuns: activeRuns(s.id),
-    });
-    app.get("/api/projects", async (c) => {
-        // Existing databases have pin booleans but no summaries. Pay one legacy
-        // scan, fill those rows, then every later Projects read is SQLite-only.
-        if (projectBackfillNeeded) {
-            await listSessions();
-            // Do not retry on every request, and do not clear a pin whose transcript
-            // happened to be unreadable. A later explicit full listing can repair it.
-            projectBackfillNeeded = false;
-        }
-        return c.json(state.projects().map((s) => present(s, true, s.unread)));
-    });
-    app.get("/api/sessions", async (c) => {
+    /** Every session a surface may show: what Pi has written, plus the ones
+     *  created here that it has not persisted yet. */
+    const allSessions = async () => {
         const sessions = await listSessions();
         for (const s of sessions)
             nascent.delete(s.id);
@@ -103,11 +109,65 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
         for (const [id, n] of nascent)
             if (Date.now() - n.createdAt > 86_400_000)
                 nascent.delete(id);
+        return [
+            ...[...nascent].map(([id, n]) => ({ id, ...n })),
+            ...sessions,
+        ];
+    };
+    // One session as every list renders it: the summary, what the workbench
+    // decided about it, and what is true of it right now.
+    // The listing's `modified` is dropped rather than forwarded: it dates a
+    // transcript, and no surface renders it.
+    const present = ({ modified: _drop, ...s }, own) => {
+        return {
+            ...s,
+            ...(own?.sort === undefined ? {} : { sort: own.sort }),
+            ...(own?.projectSort === undefined ? {} : { projectSort: own.projectSort }),
+            // Which repository the directory belongs to, on every list and not only
+            // on the rail's: All sessions replaces the client's whole list, so a row
+            // without it there un-groups the worktrees the rail had just grouped.
+            // Whatever is known now — the probe is never waited on, and its answer
+            // arrives as a `sessions-changed`.
+            ...repos.get(s.cwd),
+            state: router.stateOf(s.id) ?? "idle",
+            listed: own?.pinned ?? false,
+            unread: own?.unread ?? false,
+            channel: channelOf?.(s.id) ?? "web",
+            activeRuns: activeRuns(s.id),
+        };
+    };
+    // The rail: the same rows as the full list, minus everything Projects is not
+    // showing. One source, one shape — the rail used to read a second copy of
+    // the summaries out of SQLite, which is what had to be kept in step.
+    app.get("/api/projects", async (c) => {
         const flags = state.flags();
-        return c.json([...[...nascent].map(([id, n]) => ({ id, ...n })), ...sessions].map((s) => {
-            const row = flags.get(s.id);
-            return present(s, row?.pinned ?? false, row?.unread ?? false);
-        }));
+        return c.json((await allSessions())
+            .map((s) => present(s, flags.get(s.id)))
+            .filter((row) => row.listed));
+    });
+    // One drag, one write of the list that changed: the projects, or one
+    // project's sessions. Whole lists rather than a move — the client has just
+    // rendered the result, and replaying a move on top of a stale list would put
+    // the row somewhere nobody dropped it.
+    app.post("/api/projects/order", async (c) => {
+        const body = await c.req.json().catch(() => null);
+        const list = (raw) => raw === undefined
+            ? undefined
+            : Array.isArray(raw) && raw.every((x) => typeof x === "string" && x)
+                ? raw
+                : null;
+        const sessions = list(body?.sessions);
+        const projects = list(body?.projects);
+        if (sessions === null || projects === null || (!sessions && !projects)) {
+            return c.json({ error: "sessions and/or projects must be lists of ids" }, 400);
+        }
+        state.reorder({ sessions, projects });
+        hub.emitWorkspace({ type: "sessions-changed" });
+        return c.json({ ok: true });
+    });
+    app.get("/api/sessions", async (c) => {
+        const flags = state.flags();
+        return c.json((await allSessions()).map((s) => present(s, flags.get(s.id))));
     });
     app.post("/api/sessions", async (c) => {
         const body = await c.req.json().catch(() => ({}));
@@ -119,7 +179,7 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
         nascent.set(session.id, { cwd: body.cwd, createdAt });
         router.attach({ channelId: "web", conversationId: session.id }, session);
         // Created here = part of the workspace; pinning is what Projects lists.
-        state.pin({ id: session.id, cwd: body.cwd, createdAt }, true);
+        state.pin(session.id, body.cwd, true);
         hub.emitWorkspace({ type: "sessions-changed" });
         return c.json({ id: session.id }, 201);
     });
@@ -135,20 +195,17 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
     });
     app.post("/api/sessions/:id/pin", async (c) => {
         const body = await c.req.json().catch(() => null);
-        if (typeof body?.pinned !== "boolean" ||
-            typeof body.cwd !== "string" || !body.cwd ||
-            typeof body.createdAt !== "number" || !Number.isFinite(body.createdAt) ||
-            (body.title !== undefined && typeof body.title !== "string")) {
-            return c.json({ error: "pinned and session summary required" }, 400);
-        }
-        // The summary came from this authenticated surface's own list. Persisting
-        // it here makes the next Projects read independent of Pi's transcript scan.
-        state.pin({
-            id: c.req.param("id"),
-            cwd: body.cwd,
-            createdAt: body.createdAt,
-            ...(body.title ? { title: body.title.slice(0, 80) } : {}),
-        }, body.pinned);
+        if (typeof body?.pinned !== "boolean")
+            return c.json({ error: "pinned required" }, 400);
+        const id = c.req.param("id");
+        // The directory comes from the listing, not from the client that clicked:
+        // it is the one fact this row keeps about the session, it is the key a
+        // project's manual place is stamped on, and the browser is not where a
+        // path should come from when the server already knows it.
+        const cwd = (await factory.find(id))?.cwd ?? nascent.get(id)?.cwd;
+        if (!cwd)
+            return c.json({ error: `session ${id} has no directory Pier can find` }, 404);
+        state.pin(id, cwd, body.pinned);
         hub.emitWorkspace({ type: "sessions-changed" });
         return c.json({ pinned: body.pinned });
     });
@@ -161,7 +218,7 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
     // deltas from SSE — transcript, live state, pending queue, model.
     guarded(app, "GET", "/api/sessions/:id/history", 404, async (c) => {
         const id = c.req.param("id");
-        const session = await ensure(id);
+        const session = await ensureLoadable(id);
         return c.json({
             turns: (await session.history()).map(slim),
             lastSeq: hub.lastSeq(id),
@@ -256,11 +313,14 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
         const { sessionId } = await router.dispatch({
             key: { channelId: "web", conversationId: id },
             senderId: "web",
+            // Named, not anonymous: a session reached from a group chat as well as
+            // from here attributes an unheaded message to whoever spoke last
+            // (core/identity.ts), which is the operator's own words in someone
+            // else's mouth.
+            sender: { id: "web", name: "operator" },
             text: body.text,
             mode,
         });
-        if (state.title(id, body.text))
-            hub.emitWorkspace({ type: "sessions-changed" });
         return c.json({ sessionId }, 202);
     });
     // Edit a user turn: rewind the transcript to just before it, then re-send
@@ -281,9 +341,13 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
         if (session.state === "streaming")
             return c.json({ error: "busy — stop the turn first" }, 409);
         await session.rewindToUserTurn(index);
+        // The rewind took the turns after this one out of the context, headers and
+        // all; what the model was told about who is speaking went with them.
+        router.forgetSender(id);
         await router.dispatch({
             key: { channelId: "web", conversationId: id },
             senderId: "web",
+            sender: { id: "web", name: "operator" },
             text: body.text,
             mode: "auto",
         });
@@ -309,6 +373,9 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
             return c.json({ error: "queue is empty" }, 409);
         if (mode === "restart")
             await router.abort(id); // resolves once idle
+        // No sender here, unlike the other dispatches: the queued texts were
+        // headed when they were first dispatched — and in a shared session they
+        // are other speakers' words, which an operator header would claim.
         await router.dispatch({
             key: { channelId: "web", conversationId: id },
             senderId: "web",
@@ -319,10 +386,48 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
     });
     // Recall: drop all pending queued messages and hand them back (composer restore).
     guarded(app, "POST", "/api/sessions/:id/queue/recall", 404, async (c) => {
-        const session = await ensure(c.req.param("id"));
+        const id = c.req.param("id");
+        const session = await ensure(id);
         const { steering, followUp } = await session.clearQueue();
+        // Those messages carried the header that told the session who is speaking,
+        // and they are going back to the composer instead of to the model.
+        if (steering.length || followUp.length)
+            router.forgetSender(id);
         return c.json({ messages: [...steering, ...followUp] });
     });
+    // Shrink the context on demand: Pi summarizes the older transcript away and
+    // the session continues from the summary. Refused while streaming, like the
+    // edit route above and for the same reason — Pi's own compaction aborts a
+    // running turn to do it, and losing a turn is not what the button offered.
+    // The result is not in this response: it arrives on the session's stream as
+    // `context-compacted` (agent/events.ts), which is also the only place the
+    // automatic compaction can be seen.
+    guarded(app, "POST", "/api/sessions/:id/compact", 404, async (c) => {
+        const session = await ensure(c.req.param("id"));
+        if (session.state === "streaming")
+            return c.json({ error: "busy — stop the turn first" }, 409);
+        // The check above is a courtesy, not the lock: two clicks pass it on the
+        // same tick, so the seam refuses the second one (agent/pi.ts) and its
+        // refusal keeps the status this route already uses for "not now" — a 404
+        // from `guarded` would have read as "no such session".
+        return await session.compact().then(() => c.json({ ok: true }, 202), (err) => c.json({ error: String(err) }, 409));
+    });
+    // A name, so a title is what you called it instead of the first 80
+    // characters you happened to type. Not refused while streaming: a rename has
+    // nothing to do with the turn running, and the transcript takes an append.
+    guarded(app, "POST", "/api/sessions/:id/rename", 404, async (c) => {
+        const body = await c.req.json().catch(() => null);
+        if (typeof body?.name !== "string")
+            return c.json({ error: "name required" }, 400);
+        const id = c.req.param("id");
+        await (await ensure(id)).rename(body.name.trim().slice(0, SESSION_TITLE_MAX));
+        // Nothing to write and nothing to report: the name went into the
+        // transcript, which is what every list reads. The event is how the
+        // surfaces learn to re-read it, and the seam dropped its retained scan on
+        // the way out so the re-read sees the new name.
+        hub.emitWorkspace({ type: "sessions-changed" });
+        return c.json({ ok: true });
+    });
     app.post("/api/sessions/:id/abort", async (c) => {
         const id = c.req.param("id");
         await router.abort(id);
@@ -396,6 +501,10 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
         updates,
         updater,
         secrets,
+        catalog,
+        names,
+        onToolsChanged,
+        validateCustomTools,
         onUnlocked,
         onSettingsChanged: () => recycle("instance settings"),
     });
@@ -445,6 +554,15 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
         c.header("cache-control", "private, no-cache");
         await next();
     });
+    // Hashed bundles never change under their name — a release writes new names,
+    // and the shell above is what re-points at them. Without this they carry only
+    // the auth layer's bare `private`, so a browser revalidates each one before it
+    // may reuse it: three round trips on a remote instance, one of them in front
+    // of the 636KB terminal emulator, every time the workbench is opened.
+    app.get("/assets/*", async (c, next) => {
+        c.header("cache-control", "private, max-age=31536000, immutable");
+        await next();
+    });
     app.use("/*", serveStatic({ root: relative(process.cwd(), bundle) || "." }));
     return app;
 }

package/dist/web/session-state.js

@@ -1,6 +1,20 @@
-// Workbench organization state: which sessions show up under Projects, the
-// summaries needed to render them without scanning Pi, and which have a
-// finished turn no client has looked at yet.
+// What the workbench decided about a session, and nothing a transcript already
+// knows. Ownership of a row in Projects (`pinned`), a finished turn nobody has
+// looked at (`unread`), and the two places a hand put it in (`sort`,
+// `project_sort`).
+//
+// It used to mirror the summary too — cwd, title, created_at, last_active —
+// because listing sessions meant parsing every transcript on disk (~237ms) and
+// the rail could not pay that on every read. agent/listing.ts made a listing
+// cheap, so the mirror bought nothing and cost two stores kept in step: a
+// backfill gate, a repair pass on every full listing, a touch at the end of
+// every turn, a title write on the first prompt, a second write on rename.
+// Deriving beats syncing; all of it is gone.
+//
+// `cwd` stayed, and is not a mirror: it is the key a project's manual place is
+// stamped on (`reorder`, and the sibling lookup in `pin`), and a session's
+// working directory is fixed when its transcript is created — an immutable key
+// needs no synchronising.
 //
 // One row per session rather than two JSON files: the unread flag is written at
 // the end of every turn, and rewriting a whole file on each of those writes
@@ -20,48 +34,44 @@ export class SessionStateStore {
         this.#db.prepare(`INSERT INTO session_state(session_id, unread) VALUES (?, ?)
        ON CONFLICT(session_id) DO UPDATE SET unread = excluded.unread`).run(sessionId, unread ? 1 : 0);
     }
-    /** Pin plus the summary Projects needs, atomically in one row. */
-    pin(summary, pinned) {
-        this.#db.prepare(`INSERT INTO session_state(session_id, pinned, cwd, title, created_at)
-       VALUES (?, ?, ?, ?, ?)
+    /** Projects takes the session, or gives it up. Membership lasts until a hand
+     *  ends it: nothing expires, so what is pinned is what the rail draws until
+     *  the ✓ on the row says otherwise. */
+    pin(sessionId, cwd, pinned) {
+        // A new session joins a project that already has a place in the list.
+        // Unranked it would sort on top — lifting the whole project with it, which
+        // is the jump manual order exists to stop.
+        const sibling = this.#db.prepare("SELECT project_sort AS rank FROM session_state WHERE cwd = ? AND project_sort IS NOT NULL LIMIT 1").get(cwd);
+        this.#db.prepare(`INSERT INTO session_state(session_id, pinned, cwd, project_sort)
+       VALUES (?, ?, ?, ?)
        ON CONFLICT(session_id) DO UPDATE SET
          pinned = excluded.pinned,
          cwd = excluded.cwd,
-         title = COALESCE(excluded.title, session_state.title),
-         created_at = excluded.created_at`).run(summary.id, pinned ? 1 : 0, summary.cwd, summary.title ?? null, summary.createdAt);
+         project_sort = COALESCE(session_state.project_sort, excluded.project_sort)`).run(sessionId, pinned ? 1 : 0, cwd, sibling?.rank ?? null);
     }
-    /** Project rows only; unlike AgentFactory.list(), this never touches disk. */
-    projects() {
-        const rows = this.#db.prepare(`SELECT session_id AS id, cwd, title, created_at AS createdAt, unread
-       FROM session_state
-       WHERE pinned = 1 AND cwd IS NOT NULL AND created_at IS NOT NULL
-       ORDER BY created_at DESC`).all();
-        return rows.map(({ title, unread, ...row }) => ({
-            ...row,
-            ...(title ? { title } : {}),
-            unread: unread === 1,
-        }));
+    /** One drag = one write of the whole list it reordered: index is the place.
+     *  `sessions` are ids (a session's place inside its project), `projects` are
+     *  cwds, whose place is stamped on every session that has that cwd. */
+    reorder(order) {
+        const bySession = this.#db.prepare("UPDATE session_state SET sort = ? WHERE session_id = ?");
+        const byCwd = this.#db.prepare("UPDATE session_state SET project_sort = ? WHERE cwd = ?");
+        this.#tx(() => {
+            order.sessions?.forEach((id, i) => bySession.run(i, id));
+            order.projects?.forEach((cwd, i) => byCwd.run(i, cwd));
+        });
     }
-    /** What to call a session where there is room for one line — a push
-     *  notification's title. Falls back to the project directory, then to the
-     *  fact that it is a session at all: a notification with no title reads as a
-     *  browser bug rather than as an unnamed session. */
-    name(sessionId) {
-        const row = this.#db.prepare("SELECT title, cwd FROM session_state WHERE session_id = ?").get(sessionId);
-        return row?.title || row?.cwd?.split("/").filter(Boolean).at(-1) || "Pier session";
+    /** Drop a session's organization row entirely — pin, order, unread. For
+     *  ghosts: Pi persists a session only once its first assistant reply lands,
+     *  so a created-and-never-messaged one cannot be resumed, and its remembered
+     *  row would otherwise sit in the rail 404ing forever. */
+    forget(sessionId) {
+        this.#db.prepare("DELETE FROM session_state WHERE session_id = ?").run(sessionId);
     }
-    needsProjectBackfill() {
-        return this.#db.prepare("SELECT 1 FROM session_state WHERE pinned = 1 AND (cwd IS NULL OR created_at IS NULL) LIMIT 1").get() !== undefined;
-    }
-    /** A full listing is rare; use it to repair metadata for rows we already own. */
-    remember(summaries) {
-        const update = this.#db.prepare(`UPDATE session_state SET
-         cwd = ?, title = COALESCE(?, title), created_at = ?
-       WHERE session_id = ?`);
+    /** All-or-nothing: a half-written order is a list nobody arranged. */
+    #tx(run) {
         this.#db.exec("BEGIN");
         try {
-            for (const s of summaries)
-                update.run(s.cwd, s.title ?? null, s.createdAt, s.id);
+            run();
             this.#db.exec("COMMIT");
         }
         catch (err) {
@@ -69,13 +79,16 @@ export class SessionStateStore {
             throw err;
         }
     }
+    /** What this store knows about the sessions it knows anything about, for a
+     *  caller holding the listing. */
     flags() {
-        const rows = this.#db.prepare("SELECT session_id AS id, pinned, unread FROM session_state WHERE pinned = 1 OR unread = 1").all();
-        return new Map(rows.map((r) => [r.id, { pinned: r.pinned === 1, unread: r.unread === 1 }]));
-    }
-    /** The first prompt supplies the title of a newly-created pinned session. */
-    title(sessionId, text) {
-        const result = this.#db.prepare("UPDATE session_state SET title = ? WHERE session_id = ? AND pinned = 1 AND title IS NULL").run(text.trim().slice(0, 80), sessionId);
-        return result.changes > 0;
+        const rows = this.#db.prepare(`SELECT session_id AS id, pinned, unread, sort, project_sort AS projectSort
+       FROM session_state WHERE pinned = 1 OR unread = 1`).all();
+        return new Map(rows.map((r) => [r.id, {
+                pinned: r.pinned === 1,
+                unread: r.unread === 1,
+                ...(r.sort === null ? {} : { sort: r.sort }),
+                ...(r.projectSort === null ? {} : { projectSort: r.projectSort }),
+            }]));
     }
 }

package/dist/web/terminal.js

@@ -28,6 +28,15 @@ const MAX_FRAME_BYTES = 1024 * 1024;
 // start under. Inheriting these can attach the shell back into Pier's parent
 // tmux session; SSH_AUTH_SOCK deliberately stays so git/ssh keep working.
 const PARENT_TERMINAL_ENV = ["TMUX", "TMUX_PANE", "SSH_TTY", "SSH_CLIENT", "SSH_CONNECTION"];
+// Pier's own configuration is Pier's, not this shell's. `NODE_ENV=production`
+// alone turns an `npm i` typed here into an install with no dev dependencies,
+// and every `PI_*`/`PIER_*` would point a `pi` started here at Pier's own
+// instance rather than the person's. Everything else is inherited on purpose:
+// PATH, LANG, SSH_AUTH_SOCK and the session's XDG/DBUS handles are what make
+// the shell usable, and on a service-managed instance nothing else supplies
+// them.
+const PIER_OWN_ENV = ["NODE_ENV", "PORT", "HOST"];
+const PIER_OWN_PREFIX = /^PI(ER)?_/;
 const send = (sock, data) => {
     try {
         sock.send(data);
@@ -44,6 +53,7 @@ export class TerminalHub {
     #shell;
     #idleMs;
     #maxTerms;
+    #initCommand;
     #sweeper;
     #closeListeners = new Set();
     #closed = false;
@@ -51,6 +61,7 @@ export class TerminalHub {
         this.#shell = opts.shell ?? process.env.SHELL ?? "/bin/bash";
         this.#idleMs = opts.idleMs ?? IDLE_MS;
         this.#maxTerms = opts.maxTerms ?? MAX_TERMS;
+        this.#initCommand = opts.initCommand ?? (() => "");
         this.#sweeper = setInterval(() => this.sweep(Date.now()), SWEEP_MS);
         this.#sweeper.unref();
     }
@@ -117,8 +128,11 @@ export class TerminalHub {
     }
     #spawn(cwd) {
         const env = { ...process.env };
-        for (const key of PARENT_TERMINAL_ENV)
-            delete env[key];
+        for (const key of Object.keys(env)) {
+            if (PARENT_TERMINAL_ENV.includes(key) || PIER_OWN_ENV.includes(key) || PIER_OWN_PREFIX.test(key)) {
+                delete env[key];
+            }
+        }
         const pty = spawn(this.#shell, [], {
             name: "xterm-256color",
             cols: 120,
@@ -129,6 +143,14 @@ export class TerminalHub {
         const term = { pty, ring: [], ringBytes: 0, clients: new Set(), idleSince: Infinity };
         this.#terms.set(cwd, term);
         log.info(`shell ${pty.pid} for ${cwd}`);
+        // Typed in, not exec'd: the shell stays the parent, so quitting whatever
+        // this starts leaves a usable prompt, and the echo plus any error is in
+        // the ring where the person can see what ran. The tty buffers it until the
+        // shell's first read, so no wait is needed. A reattach never repeats it —
+        // this runs once per pty, which is once per cwd.
+        const init = this.#initCommand().trim();
+        if (init)
+            pty.write(`${init}\r`);
         pty.onData((data) => {
             const chunk = Buffer.from(data);
             term.ring.push(chunk);
@@ -179,6 +201,13 @@ export class TerminalHub {
             term.pty.write(msg.d);
             return;
         }
+        // The only way a page can end a shell: everything attached to it is told by
+        // the exit path below, exactly as if the shell had exited on its own.
+        if (msg.t === "restart") {
+            log.info(`shell ${term.pty.pid} for ${cwd} killed on request`);
+            term.pty.kill();
+            return;
+        }
         if (msg.t === "resize" &&
             typeof msg.cols === "number" && typeof msg.rows === "number" &&
             Number.isInteger(msg.cols) && Number.isInteger(msg.rows) &&
@@ -225,8 +254,9 @@ export class TerminalHub {
 /** The upgrade seam: `/api/terminal?cwd=…` behind the same password boundary
  *  as every route. SameSite=Lax already withholds the cookie cross-site; the
  *  Origin check is the explicit copy of that fact. */
-export function attachTerminal(server, auth, heartbeatMs = HEARTBEAT_MS) {
-    const hub = new TerminalHub();
+export function attachTerminal(server, auth, opts = {}) {
+    const heartbeatMs = opts.heartbeatMs ?? HEARTBEAT_MS;
+    const hub = new TerminalHub(opts);
     const wss = new WebSocketServer({ noServer: true, maxPayload: MAX_FRAME_BYTES });
     const alive = new WeakSet();
     const heartbeat = setInterval(() => {

package/dist/web/types.js

@@ -0,0 +1,5 @@
+// The shapes web's HTTP answers carry beyond the stores they come from — the
+// area's own wire vocabulary, and the one file in web/ the browser may import
+// type-only (docs/architecture.md, same rule as tasks/types.ts). Nothing here
+// runs: no imports, no values, so a page pays nothing for reading it.
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timqi/pier",
-  "version": "0.0.8",
+  "version": "0.0.15",
   "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-boards/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pier-boards
-description: Publish a Board — a folder of static HTML Pier serves at a stable URL — to present a report, digest, dashboard or handover note to the user. Read before building any page-shaped deliverable, or before editing an existing board.
+description: Publish a Board — a folder of static HTML Pier serves at a stable URL. Read before building any page-shaped deliverable (report, digest, dashboard) or editing an existing board.
 ---
 
 # Building a Pier board
@@ -27,23 +27,33 @@ session may read or rewrite any board, and closing this one changes nothing.
 }
 ```
 
-Those four fields are the whole manifest.
+Those four fields are the whole manifest (publishing adds a fifth — below).
 
-- `slug`: `[a-z0-9][a-z0-9-]{0,63}`, and it is the URL — short and stable.
+- `slug`: `[a-z0-9][a-z0-9-]{0,63}`, and it is the URL — short and stable. Do
+  not add random characters of your own; publishing adds them (see below).
 - `description` is the Console list entry: write it for someone who has
   forgotten this conversation.
 - `sessions`: append your own id, never replace — other ids are provenance too.
 
 ## Publish, then hand over the link
 
-`"public": true` serves the board at `/p/<slug>/` **with no password**. Set it
-only if the user asked for a public or shareable board *in this request*;
-otherwise leave it `false` and say the board is private. Never publish personal
-data or anything the user has not seen.
+`"public": true` serves the board **with no password**. Set it only if the user
+asked for a public or shareable board *in this request*; otherwise leave it
+`false` and say the board is private. Never publish personal data or anything
+the user has not seen.
 
-Asked to make an existing board public? Flip `"public"` to `true` in
-`board.json` and reply with the `/p/<slug>/` link — that is the whole answer.
-No verification step, no narrating the edit, no restating what the page holds.
+The published address is `/p/<slug>-<token>/`, not `/p/<slug>/`, so a public
+board's URL cannot be guessed from its name. `token` is a fifth manifest field
+you write next to `"public": true` — eight hex characters from
+`openssl rand -hex 4`, never invented in your head, never reused between
+boards. Leave it out and Pier mints one on the first request, but then the link
+is only visible in the Console, so write it yourself and you can hand it over
+in the same message.
+
+Asked to make an existing board public? Set `"public": true` and a fresh
+`token` in `board.json`, then reply with the `/p/<slug>-<token>/` link — that is
+the whole answer. Already has a token? Keep it: the link may be out there. No
+verification step, no narrating the edit, no restating what the page holds.
 
 The message announcing the board carries **one bare URL** — paste the address
 itself, never `[title](url)`: link labels get mangled or truncated on some chat
@@ -54,10 +64,10 @@ surfaces, and the title is already on the page. No filesystem paths either —
 | The user asked for | Send |
 | --- | --- |
 | a board, nothing about sharing | `https://pier.example.com/boards/weekly-digest/` — behind the Pier password; Console → Boards makes it public |
-| a **public** board | `https://pier.example.com/p/weekly-digest/` — no password |
+| a **public** board | `https://pier.example.com/p/weekly-digest-3f9ac128/` — no password; the suffix is the manifest's `token`, copied verbatim |
 
 Never both: the pair invites pasting the password-free URL of a board that was
-never meant to leave the workspace, and `/p/<slug>/` 404s unless the manifest
+never meant to leave the workspace, and `/p/<slug>-<token>/` 404s unless the manifest
 says `"public": true`. No address configured? Give the path, say Console →
 Settings turns it into a link, and never guess a host.
 
@@ -74,7 +84,7 @@ build, no npm, no framework:
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>Weekly digest — infra</title>
-<link rel="stylesheet" href="/boards/_assets/pier.css">
+<link rel="stylesheet" href="/p/_assets/pier.css">
 </head>
 <body>
 <div class="hero">