@timqi/pier 0.0.1 → 0.0.2

package/dist/main.js

@@ -18,6 +18,7 @@ import { handleSlackTool, slackToolSpec } from "./channels/slack-tool.js";
 import { parseConversation as parseSlackConversation } from "./channels/slack.js";
 import { EventHub } from "./core/hub.js";
 import { pierDb } from "./db.js";
+import { deliverLedger, drainForRestart, RestartLedger } from "./drain.js";
 import { surfacePrompt } from "./core/reply.js";
 import { Router } from "./core/router.js";
 import { logger } from "./log.js";
@@ -28,6 +29,7 @@ import { taskToolSpec } from "./tasks/tool.js";
 import { PIER_HOME, pierPath } from "./paths.js";
 import { Secrets } from "./secrets.js";
 import { SettingsStore } from "./settings.js";
+import { UpdateCheck } from "./update.js";
 import { AuthStore, registerAuthRoutes, requireAuth } from "./web/auth.js";
 import { SessionStateStore } from "./web/session-state.js";
 import { createServer } from "./web/server.js";
@@ -64,6 +66,7 @@ let channelStore;
 // Shared by the adapter and the tool: a display name is looked up once per
 // process, not once per message and again per transcript.
 const slackDirectory = new SlackDirectory((m) => logger("slack").warn(m));
+const piConfig = new PiConfigStore();
 const factory = new PiAgentFactory([
     taskToolSpec((params, callerSessionId) => tasks.tool(params, callerSessionId)),
     slackToolSpec((params, callerSessionId) => handleSlackTool({
@@ -95,7 +98,9 @@ const factory = new PiAgentFactory([
 [fileURLToPath(new URL("../skills", import.meta.url))], 
 // Provider credentials live sealed in pier.db; a leftover auth.json is
 // imported on first use and renamed to auth.json.imported.
-new CredentialStore(db, secrets));
+new CredentialStore(db, secrets), piConfig, 
+// Operator pins ride ahead of the curated catalog in every model picker.
+() => settings.get().modelMenu);
 const hub = new EventHub();
 const router = new Router(hub, (key) => {
     // Web conversation ids ARE session ids; an IM conversation id is a chat or a
@@ -106,7 +111,12 @@ const router = new Router(hub, (key) => {
     }
     return resolveIm(key);
 });
-tasks = new TaskService(new TaskStore(db), factory, router, hub);
+// An attached session holds a live Pi runtime and its transcript, and nothing
+// else ever lets one go: without this, one per conversation ever answered.
+const stopEviction = router.startIdleEviction();
+tasks = new TaskService(new TaskStore(db), factory, router, hub, {
+    modelMenu: () => settings.get().modelMenu,
+});
 tasks.start();
 channelStore = new ChannelStore(db, secrets);
 const control = createControl({ router, factory, conversations, store: channelStore });
@@ -115,7 +125,16 @@ resolveIm = resolveConversation(conversations, factory, control.launchFor, (mess
 // Channels connect only once tokens are readable. A refused unlock (vt denial,
 // corrupt master.key) must not take the web surface down — it is where the
 // operator goes to repair — but it is named loudly, not served as silence.
-void secrets.unlock().then(() => channels.reload(), (err) => log.error("secrets locked — channels not started; unlock from Console → Settings → Security, or repair master.key", err));
+// Once they are up, the chats a previous restart cut off are told (drain.ts) —
+// on this path and on a later Console unlock alike, because a note held back
+// by locked secrets must not wait for yet another restart.
+const restartLedger = new RestartLedger(db);
+const startChannels = async () => {
+    await channels.reload();
+    await deliverLedger(restartLedger, (entry) => channels.notify(entry.channelId, entry.conversationId, entry.note))
+        .catch((err) => log.error("restart-note delivery failed", err));
+};
+void secrets.unlock().then(startChannels, (err) => log.error("secrets locked — channels not started; unlock from Console → Settings → Security, or repair master.key", err));
 // Composition happens here so web/ and tasks/ never import each other.
 const app = new Hono();
 // A route that threw would otherwise answer 500 and leave no trace anywhere:
@@ -129,8 +148,8 @@ app.onError((err, c) => {
 // so a surface added later is covered without knowing this exists. Built
 // before the listener: a first run generates and prints its password here.
 const auth = new AuthStore(db);
-registerAuthRoutes(app, auth);
 app.use("*", requireAuth(auth));
+registerAuthRoutes(app, auth);
 registerTaskRoutes(app, tasks, { factory, router });
 registerChannelRoutes(app, channelStore, channels);
 registerBoardRoutes(app);
@@ -139,11 +158,13 @@ app.route("/", createServer({
     router,
     hub,
     sessions: new SessionStateStore(db),
-    config: new PiConfigStore(),
+    config: piConfig,
+    providers: factory,
     settings,
     secrets,
+    updates: new UpdateCheck(),
     // Unlocked from the Console: start the channels boot held back.
-    onUnlocked: () => void channels.reload(),
+    onUnlocked: () => void startChannels(),
     backgroundRuns: (id) => tasks.backgroundRuns(id),
 }));
 const port = Number(process.env.PORT ?? 3141);
@@ -164,20 +185,67 @@ process.on("uncaughtException", (err) => {
 process.on("unhandledRejection", (reason) => {
     log.error("unhandled rejection", reason);
 });
+let shuttingDown = false;
+const shutdown = (stopTasks = true) => {
+    // Once: SIGTERM can land while a drain is finishing, and two teardowns
+    // racing each other close the same sockets twice.
+    if (shuttingDown)
+        return;
+    shuttingDown = true;
+    // Best-effort, and bounded: a socket an adapter cannot close must not turn
+    // `systemctl restart` into a 90-second wait for SIGKILL.
+    setTimeout(() => process.exit(0), 3000).unref();
+    stopEviction();
+    // The drain path leaves task runs alone: aborting them here would record
+    // them cancelled and race their callbacks against dying channels, when the
+    // boot-time interrupted marking is the recovery that was promised.
+    if (stopTasks)
+        tasks.stop();
+    void channels.stop().finally(() => {
+        server.close(() => process.exit(0));
+        // Every workbench tab holds an SSE stream open, so `close()` alone would
+        // always wait out the timer above. (`in` because the served type is a
+        // union with HTTP/2, which has no such method — and no such problem.)
+        if ("closeAllConnections" in server)
+            server.closeAllConnections();
+    });
+};
 for (const signal of ["SIGTERM", "SIGINT"]) {
     process.once(signal, () => {
         log.info(`${signal} received, shutting down`);
-        // Best-effort, and bounded: a socket an adapter cannot close must not turn
-        // `systemctl restart` into a 90-second wait for SIGKILL.
-        setTimeout(() => process.exit(0), 3000).unref();
-        tasks.stop();
-        void channels.stop().finally(() => {
-            server.close(() => process.exit(0));
-            // Every workbench tab holds an SSE stream open, so `close()` alone would
-            // always wait out the timer above. (`in` because the served type is a
-            // union with HTTP/2, which has no such method — and no such problem.)
-            if ("closeAllConnections" in server)
-                server.closeAllConnections();
-        });
+        shutdown();
+    });
+}
+// The slow restart (`pier restart`): refuse new work, let running turns finish
+// — bounded by the drain deadline — then exit for `Restart=always` to bring the
+// next process up. SIGTERM above stays the fast path systemd expects. `on`,
+// not `once`: a second SIGUSR2 with no handler would fall back to Node's
+// default and kill the drain it meant to hurry.
+let draining = false;
+process.on("SIGUSR2", () => {
+    if (draining) {
+        log.info("SIGUSR2 received again — already draining");
+        return;
+    }
+    draining = true;
+    log.info("SIGUSR2 received, draining for restart");
+    void drainForRestart({ router, tasks, ledger: restartLedger })
+        .catch((err) => log.error("drain failed — shutting down anyway", err))
+        .then(() => shutdown(false));
+});
+// Reload without a restart (`pier reload`): adapters re-read their config, and
+// idle sessions are let go so the next message re-opens them with the current
+// skills, extensions and prompts — all applied at attach, none stored in a
+// transcript. Streaming or watched sessions pick the change up at their next
+// natural eviction. Only under systemd (the CLI signals through systemctl):
+// a foreground `pier` keeps SIGHUP's default, dying with its terminal instead
+// of surviving as an orphan that holds the port.
+if (process.env.INVOCATION_ID) {
+    process.on("SIGHUP", () => {
+        log.info("SIGHUP received, reloading channels and recycling idle sessions");
+        void channels.reload();
+        void router.evictIdle(0)
+            .then((n) => log.info(`recycled ${String(n)} idle session(s)`))
+            .catch((err) => log.error("session recycle failed", err));
     });
 }

package/dist/secrets.js

@@ -26,7 +26,6 @@ export class Secrets {
     path;
     vt;
     #dek;
-    #kek;
     #file;
     /** Why decrypt is refused right now — "" once unlocked. */
     #lockedReason = "unlock() has not run";
@@ -58,7 +57,12 @@ export class Secrets {
             try {
                 raw = readFileSync(this.path, "utf8");
             }
-            catch {
+            catch (err) {
+                // Only a missing file means first boot. Any other read error (EACCES,
+                // EISDIR…) must not fall through to #create(), which would rename a
+                // fresh key over the existing one and destroy every sealed credential.
+                if (err.code !== "ENOENT")
+                    throw err;
                 this.#file = this.#create();
                 log.info(`created ${this.path} (file mode)`);
                 raw = readFileSync(this.path, "utf8");
@@ -66,12 +70,12 @@ export class Secrets {
             const file = JSON.parse(raw);
             if (!file.kek || !file.dek || !file.dekId)
                 throw new Error(`${this.path} is malformed`);
-            this.#kek = file.kek.startsWith("vt://")
+            const kek = file.kek.startsWith("vt://")
                 ? Buffer.from(await this.vt.read(file.kek), "base64")
                 : Buffer.from(file.kek, "base64");
-            if (this.#kek.length !== KEY_BYTES)
+            if (kek.length !== KEY_BYTES)
                 throw new Error(`${this.path} KEK is not ${KEY_BYTES} bytes`);
-            this.#dek = open(this.#kek, file.dek, `kek:${file.dekId}`);
+            this.#dek = open(kek, file.dek, `kek:${file.dekId}`);
             this.#file = file;
             this.#lockedReason = "";
             log.info(`secrets unlocked (${this.mode} mode, dek ${file.dekId})`);
@@ -112,7 +116,6 @@ export class Secrets {
             throw new Error("vt create did not return a vt:// record");
         }
         this.#write(next);
-        this.#kek = kek;
         this.#file = next;
         log.info(`KEK rotated (${mode} mode, dek ${file.dekId} unchanged)`);
     }
@@ -184,6 +187,7 @@ function run(cmd, args, stdin) {
             else
                 reject(new Error(`${cmd} ${args[0]} exited ${code}: ${err.trim() || out.trim()}`));
         });
+        child.stdin.on("error", reject); // EPIPE if vt exits before reading
         if (stdin !== undefined)
             child.stdin.write(stdin);
         child.stdin.end();

package/dist/service.js

@@ -11,16 +11,33 @@
 // installed by fnm/nvm/asdf is not on it) and the absolute path of the
 // installed entry point.
 import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, rmdirSync, rmSync, writeFileSync } from "node:fs";
 import { homedir, userInfo } from "node:os";
 import { dirname, join } from "node:path";
 export const UNIT_NAME = "pier.service";
+export const UPDATE_UNIT_NAME = "pier-update.service";
 /** `~/.config/systemd/user/pier.service` — where a user unit belongs. */
 export const unitPath = (home = homedir()) => join(home, ".config", "systemd", "user", UNIT_NAME);
 /** The drop-in Pier writes once and never touches again: what the unit may
  *  consume is the operator's call, not ours. */
 export const limitsPath = (home = homedir()) => join(dirname(unitPath(home)), `${UNIT_NAME}.d`, "limits.conf");
-export function renderUnit({ execPath, entry, host, port, pierHome }) {
+/** The oneshot that installs a new version, beside the unit it restarts. */
+export const updateUnitPath = (home = homedir()) => join(dirname(unitPath(home)), UPDATE_UNIT_NAME);
+/** Runtime-only effective state for the updater, regenerated before each run. */
+export const updateRuntimePath = (home = homedir()) => join(dirname(unitPath(home)), `${UPDATE_UNIT_NAME}.d`, "runtime.conf");
+/** Quote one systemd word. Percent is doubled because specifier expansion runs
+ * after parsing; dollar is doubled only for command lines. */
+function quote(value, command = false) {
+    if (/[\0\r\n]/.test(value))
+        throw new Error("systemd values cannot contain control characters");
+    let escaped = value.replaceAll("\\", "\\\\").replaceAll('"', '\\"').replaceAll("%", "%%");
+    if (command)
+        escaped = escaped.replaceAll("$", () => "$$");
+    return `"${escaped}"`;
+}
+const environment = (key, value) => `Environment=${quote(`${key}=${value}`)}`;
+export function renderUnit(options) {
+    const { execPath, entry, host, port, pierHome } = options;
     return `[Unit]
 Description=Pier — agent workspace
 Documentation=https://github.com/timqi/pier
@@ -32,13 +49,13 @@ Type=simple
 WorkingDirectory=%h
 # Absolute paths on purpose: systemd starts with a minimal PATH, and the node
 # that installed Pier is usually not on it.
-ExecStart=${execPath} ${entry}
-Environment=NODE_ENV=production
+ExecStart=${quote(execPath, true)} ${quote(entry, true)}
+${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=${host}
-Environment=PORT=${port}
-${pierHome ? `# Where the database, the boards and the password hash live.\nEnvironment=PIER_HOME=${pierHome}\n` : ""}Restart=always
+${environment("HOST", host)}
+${environment("PORT", String(port))}
+${pierHome ? `# Where the database, the boards and the password hash live.\n${environment("PIER_HOME", pierHome)}\n` : ""}Restart=always
 RestartSec=2
 # The journal is where the first-run password is printed, so keep it readable.
 StandardOutput=journal
@@ -50,6 +67,46 @@ SyslogIdentifier=pier
 WantedBy=default.target
 `;
 }
+/** The 0.0.1 unit did not record npm. This one-time bridge can only use npm
+ * beside its recorded Node; a forced reinstall writes the exact executable. */
+function legacyOptions(home) {
+    const text = readFileSync(unitPath(home), "utf8");
+    const start = text.match(/^ExecStart=(\S+) (\S+)$/m);
+    const host = text.match(/^Environment=HOST=(\S+)$/m)?.[1];
+    const rawPort = text.match(/^Environment=PORT=(\d+)$/m)?.[1];
+    const pierHome = text.match(/^Environment=PIER_HOME=(\S+)$/m)?.[1];
+    if (!start?.[1] || !start[2] || !host || !rawPort)
+        throw new Error("unit is not the 0.0.1 Pier shape");
+    return {
+        execPath: start[1],
+        npmPath: join(dirname(start[1]), "npm"),
+        entry: start[2],
+        host,
+        port: Number(rawPort),
+        ...(pierHome ? { pierHome } : {}),
+    };
+}
+/** A separate cgroup stops Pier, takes a consistent backup, updates the exact
+ * npm installation recorded at install time, and always starts Pier again. */
+export function renderUpdateUnit(options) {
+    const { execPath, npmPath, entry, pierHome } = options;
+    const cli = join(dirname(entry), "cli.js");
+    return `[Unit]
+Description=Update Pier to the latest published version
+Documentation=https://github.com/timqi/pier
+
+[Service]
+Type=oneshot
+${pierHome ? `${environment("PIER_HOME", pierHome)}\n` : ""}ExecStart=systemctl --user stop ${UNIT_NAME}
+ExecStart=${quote(execPath, true)} ${quote(cli, true)} backup
+# npm runs under the recorded node: its shebang needs a node on PATH, and
+# systemd's minimal PATH has none for fnm/nvm installs.
+ExecStart=${quote(execPath, true)} ${quote(npmPath, true)} install -g @timqi/pier@latest
+# ExecStopPost runs on success and failure, so a failed backup or npm install
+# does not leave the previously working service stopped.
+ExecStopPost=systemctl --user start ${UNIT_NAME}
+`;
+}
 /**
  * Sized as a share of the machine, not as "how much should Pier need": the
  * limit covers node, every subagent and every command a turn ran, and it
@@ -74,8 +131,8 @@ OOMScoreAdjust=200
 OOMPolicy=continue
 `;
 }
-/** Best-effort: a step that fails says so and the rest still runs, because a
- *  half-installed service the operator knows about beats a stack trace. */
+/** A command failure is printed here and propagated by its caller. Linger is
+ * the only deliberately best-effort step. */
 const runner = (say) => (argv) => {
     try {
         execFileSync(argv[0], argv.slice(1), { stdio: "pipe" });
@@ -91,13 +148,16 @@ export function install(options) {
     const { force, home = homedir(), say, exec, ...unit } = options;
     const run = exec ?? runner(say);
     const path = unitPath(home);
-    if (existsSync(path) && !force) {
+    const replacing = existsSync(path);
+    if (replacing && !force) {
         say(`${path} already exists — nothing written. Re-run with --force to replace it.`);
-        return;
+        return true;
     }
     mkdirSync(dirname(path), { recursive: true });
     writeFileSync(path, renderUnit(unit), { mode: 0o644 });
+    writeFileSync(updateUnitPath(home), renderUpdateUnit(unit), { mode: 0o644 });
     say(`wrote ${path}`);
+    say(`wrote ${updateUnitPath(home)}`);
     const limits = limitsPath(home);
     if (existsSync(limits)) {
         say(`kept ${limits}`); // tuned by hand, by definition
@@ -107,28 +167,92 @@ export function install(options) {
         writeFileSync(limits, renderLimits(), { mode: 0o644 });
         say(`wrote ${limits}`);
     }
-    run(["systemctl", "--user", "daemon-reload"]);
+    if (!run(["systemctl", "--user", "daemon-reload"]))
+        return false;
     // Without lingering, the user manager stops at logout and takes every
     // scheduled task with it. It can need a polkit prompt, hence best-effort.
     if (!run(["loginctl", "enable-linger", userInfo().username])) {
         say(`  run it yourself so Pier survives logout: loginctl enable-linger ${userInfo().username}`);
     }
-    if (run(["systemctl", "--user", "enable", "--now", UNIT_NAME])) {
-        say(`started. The first run prints a password once: journalctl --user -u pier -e`);
+    if (replacing) {
+        if (!run(["systemctl", "--user", "enable", UNIT_NAME]))
+            return false;
+        if (!run(["systemctl", "--user", "restart", UNIT_NAME]))
+            return false;
     }
+    else if (!run(["systemctl", "--user", "enable", "--now", UNIT_NAME]))
+        return false;
+    say(`started. The first run prints a password once: journalctl --user -u pier -e`);
+    return true;
+}
+function runningPierHome(home) {
+    const pid = Number(execFileSync("systemctl", ["--user", "show", UNIT_NAME, "--property=MainPID", "--value"], { encoding: "utf8" }).trim());
+    if (Number.isInteger(pid) && pid >= 1) {
+        const value = readFileSync(`/proc/${pid}/environ`)
+            .toString()
+            .split("\0")
+            .find((item) => item.startsWith("PIER_HOME="))
+            ?.slice("PIER_HOME=".length);
+        return value || join(home, ".pier");
+    }
+    // Installed but stopped: the unit file records any override (quoted and
+    // escaped since 0.0.2, bare in the 0.0.1 shape) — undo quote()'s escaping
+    // or the drop-in would carry `%%`/`\\"` into a real path.
+    const raw = readFileSync(unitPath(home), "utf8")
+        .match(/^Environment="?PIER_HOME=((?:\\.|[^"\r\n])+)"?$/m)?.[1];
+    const fromUnit = raw?.replaceAll("%%", "%").replace(/\\(.)/g, "$1");
+    return fromUnit || join(home, ".pier");
+}
+/** Start the updater recorded at install time. Its tiny drop-in captures the
+ * running service's effective home, including an operator override. */
+export function startUpdate(options) {
+    const { home = homedir(), say } = options;
+    const run = options.exec ?? runner(say);
+    if (!existsSync(unitPath(home)))
+        return "not-installed";
+    try {
+        if (!existsSync(updateUnitPath(home))) {
+            writeFileSync(updateUnitPath(home), renderUpdateUnit(legacyOptions(home)), { mode: 0o644 });
+            say(`generated a legacy updater; run "pier service install --force" after this update to record the exact npm path.`);
+        }
+        const runtime = updateRuntimePath(home);
+        mkdirSync(dirname(runtime), { recursive: true });
+        writeFileSync(runtime, `[Service]\n${environment("PIER_HOME", (options.effectiveHome ?? (() => runningPierHome(home)))())}\n`, { mode: 0o644 });
+    }
+    catch (err) {
+        say(`! cannot prepare update — ${String(err)}`);
+        return "failed";
+    }
+    if (!run(["systemctl", "--user", "daemon-reload"]))
+        return "failed";
+    if (!run(["systemctl", "--user", "start", "--no-block", UPDATE_UNIT_NAME]))
+        return "failed";
+    say(`updating in the background — follow it with: journalctl --user -u ${UPDATE_UNIT_NAME} -f`);
+    say(`Pier stops, snapshots pier.db.release.bak, installs, then starts again.`);
+    return "started";
 }
 export function uninstall(home = homedir(), say = console.log, exec) {
     const run = exec ?? runner(say);
-    run(["systemctl", "--user", "disable", "--now", UNIT_NAME]);
-    for (const path of [unitPath(home), limitsPath(home)]) {
+    if (!run(["systemctl", "--user", "disable", "--now", UNIT_NAME]))
+        return false;
+    for (const path of [unitPath(home), limitsPath(home), updateUnitPath(home), updateRuntimePath(home)]) {
         if (!existsSync(path))
             continue;
         rmSync(path, { force: true });
         say(`removed ${path}`);
     }
-    rmSync(dirname(limitsPath(home)), { force: true, recursive: true });
-    run(["systemctl", "--user", "daemon-reload"]);
+    for (const dir of [dirname(limitsPath(home)), dirname(updateRuntimePath(home))]) {
+        try {
+            rmdirSync(dir); // non-recursive: drop-ins the operator added are not ours to delete
+        }
+        catch {
+            if (existsSync(dir))
+                say(`kept ${dir} — it has files Pier did not write`);
+        }
+    }
+    const ok = run(["systemctl", "--user", "daemon-reload"]);
     // Left alone on purpose: the database, the boards, and linger — none of them
     // are this command's to decide about.
     say(`$PIER_HOME is untouched; linger is still enabled.`);
+    return ok;
 }

package/dist/settings.js

@@ -1,14 +1,15 @@
 // Instance settings: the facts about *this* Pier that are neither a credential
-// nor per-session. Today there is one — the URL it is reached at from outside,
-// which nothing in the process can discover for itself: a request's Host header
-// is whatever a proxy chose to pass on, and an agent writing a board has no
-// request at all.
+// nor per-session — the public URL (nothing in the process can discover it:
+// a Host header is whatever a proxy passed on) and the operator's model menu.
 //
 // A key-value table, so the next setting is not the next table and not a third
 // kind of storage. It used to be a JSON file, justified by "the agent reads it
 // too" — the agent is told the URL in its system prompt (core/reply.ts), and
 // nothing outside this process ever opened that file.
+import { isThinkingLevel } from "./core/types.js";
 import { pierDb } from "./db.js";
+import { logger } from "./log.js";
+const log = logger("settings");
 /**
  * `""` clears it, `null` rejects it. Rejecting rather than repairing: a
  * mistyped host quietly turned into a URL produces board links that 404 for
@@ -33,22 +34,82 @@ export function normalizePublicUrl(raw) {
         return null;
     return `${url.origin}${url.pathname}`.replace(/\/+$/, "");
 }
+/**
+ * Boundary check for a menu, rejecting rather than repairing (same contract as
+ * `normalizePublicUrl`): a silently "fixed" entry would advertise a model the
+ * operator never picked. Notes are capped — they are one line of intent, and
+ * every session that asks for the menu pays for their tokens.
+ */
+export function normalizeModelMenu(raw) {
+    if (!Array.isArray(raw) || raw.length > 32)
+        return null;
+    const menu = [];
+    for (const item of raw) {
+        if (typeof item !== "object" || item === null)
+            return null;
+        const { provider, id, thinking, note } = item;
+        if (typeof provider !== "string" || !provider.trim())
+            return null;
+        if (typeof id !== "string" || !id.trim())
+            return null;
+        if (thinking !== undefined && !isThinkingLevel(thinking))
+            return null;
+        if (note !== undefined && typeof note !== "string")
+            return null;
+        const cleaned = note?.trim().slice(0, 200);
+        menu.push({
+            provider: provider.trim(),
+            id: id.trim(),
+            ...(thinking !== undefined ? { thinking } : {}),
+            ...(cleaned ? { note: cleaned } : {}),
+        });
+    }
+    return menu;
+}
 export class SettingsStore {
     #db;
     constructor(db = pierDb()) {
         this.#db = db;
     }
     get() {
-        return { publicUrl: this.#value("publicUrl") ?? "" };
+        return { publicUrl: this.#value("publicUrl") ?? "", modelMenu: this.#menu() };
+    }
+    #menu() {
+        const raw = this.#value("modelMenu");
+        if (!raw)
+            return [];
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            // Only a hand-edited row can get here; named, not silently served as [].
+            log.warn("settings.modelMenu is not JSON — ignoring it");
+            return [];
+        }
+        const menu = normalizeModelMenu(parsed);
+        if (!menu) {
+            log.warn("settings.modelMenu is not a valid menu — ignoring it");
+            return [];
+        }
+        return menu;
     }
     /** Store an already-normalized value — validation belongs at the boundary
      *  that received it, so this never has to guess what the caller meant. */
     setPublicUrl(publicUrl) {
+        this.#set("publicUrl", publicUrl);
+        return this.get();
+    }
+    /** Same contract: hand this `normalizeModelMenu`'s output, not raw input. */
+    setModelMenu(menu) {
+        this.#set("modelMenu", JSON.stringify(menu));
+        return this.get();
+    }
+    #set(key, value) {
         this.#db.prepare(`
-      INSERT INTO settings(key, value) VALUES ('publicUrl', ?)
+      INSERT INTO settings(key, value) VALUES (?, ?)
       ON CONFLICT(key) DO UPDATE SET value = excluded.value
-    `).run(publicUrl);
-        return this.get();
+    `).run(key, value);
     }
     #value(key) {
         const row = this.#db.prepare("SELECT value FROM settings WHERE key = ?").get(key);

package/dist/tasks/agent.js

@@ -1,8 +1,27 @@
+import { quietLabel, splitReply } from "../core/reply.js";
 import { Router } from "../core/router.js";
 import { TaskMessenger } from "./messages.js";
 import { TaskStore } from "./store.js";
 const MAX_ACTIVE_AGENTS = 4;
 const MAX_ACTIVE_PER_ROOT = 4;
+/** What a child cannot know unless told. Every session gets the chat-surface
+ * contract (<pier>/AGENTS.md), task runs included — so the delegation prompt
+ * says which of it does not apply here, and a supervised run how to reach the
+ * agent that is waiting on it. Skipped on resume: the session already saw it. */
+const preamble = (run) => {
+    // A cron/watch task with a session callback is read by an agent too.
+    const audience = run.invokedBySessionId
+        ? "read by the agent that delegated this run"
+        : run.callbackSessionId
+            ? "read by the agent session it is delivered to"
+            : "read by the operator";
+    const contact = run.invokedBySessionId
+        ? ' Mid-run, the task tool\'s contact operation reaches that agent: reason "progress" is fire-and-forget, "decision" waits for a reply — state what you await and end your turn.'
+        : "";
+    return `[Pier task run ${run.id} — "${run.context.definition.name}"] ` +
+        `Your final reply is recorded verbatim as the run result, ${audience}; ` +
+        `next-step buttons and file:// attachments do not render there.${contact}\n\n`;
+};
 export class AgentTaskRunner {
     factory;
     router;
@@ -28,10 +47,12 @@ export class AgentTaskRunner {
                 start();
                 // No input is no block: `<task_input>\nnull\n</task_input>` is four
                 // lines telling the agent nothing, on every run that has no input.
+                // Compact for the same reason tool results are (agent/pi.ts), and
+                // `<\/` is the same JSON — a value cannot close the fence early.
                 const input = run.input === undefined || run.input === null
                     ? ""
-                    : `\n\n<task_input>\n${JSON.stringify(run.input, null, 2)}\n</task_input>`;
-                const prompt = run.context.resumePrompt ?? `${action.prompt}${input}`;
+                    : `\n\n<task_input>\n${JSON.stringify(run.input).replaceAll("</task_input>", "<\\/task_input>")}\n</task_input>`;
+                const prompt = run.context.resumePrompt ?? `${preamble(run)}${action.prompt}${input}`;
                 run.context.sessionId = session.id;
                 run.context.model = session.model;
                 run.context.renderedPrompt = prompt;
@@ -41,7 +62,16 @@ export class AgentTaskRunner {
                     if (event.type === "turn-end")
                         text = event.text;
                 });
-                const abort = () => void session.abort();
+                // The race below also settles this attempt if Pi ignores the abort:
+                // a hung turn must not hold one of the 4 slots (and its waiters)
+                // forever — the same guard execution.ts gives task-type children.
+                let rejectAborted = () => { };
+                const abortedTurn = new Promise((_, reject) => { rejectAborted = reject; });
+                abortedTurn.catch(() => { }); // handled via the race; never unhandled
+                const abort = () => {
+                    void session.abort();
+                    rejectAborted(new Error("cancelled"));
+                };
                 signal.addEventListener("abort", abort, { once: true });
                 // A pre-aborted signal never fires the listener: check before the
                 // prompt starts or a cancelled run would hang until its timeout.
@@ -56,14 +86,20 @@ export class AgentTaskRunner {
                     }, "prompt");
                     await Promise.resolve();
                     this.messages.deliverPendingControls(run);
-                    await turn;
+                    await Promise.race([turn, abortedTurn]);
                     if (signal.aborted)
                         throw new Error("cancelled");
                     if (!text) {
                         const history = await session.history();
                         text = [...history].reverse().find((turn) => turn.role === "assistant")?.text ?? "";
                     }
-                    return { type: "agent", text, sessionId: session.id };
+                    // The chat contract is injected into task sessions too, so a child's
+                    // reply may carry chat-only markup. The result is read by a
+                    // supervisor or the Console, never a chat renderer: buttons are
+                    // dropped, and a turn that said nothing names which kind of nothing
+                    // it was (principle 5b) instead of storing an empty result.
+                    const reply = splitReply(text);
+                    return { type: "agent", text: reply.text || quietLabel(reply.silence), sessionId: session.id };
                 }
                 finally {
                     signal.removeEventListener("abort", abort);