@timqi/pier 0.0.1 → 0.0.2

package/dist/core/reply.js

@@ -13,7 +13,7 @@
  * into the factory). Both halves of the feature live in this file: the syntax
  * the agent is told to emit, and the parser that reads it back.
  */
-export const REPLY_SURFACE_PROMPT = `## Pier chat surface
+const REPLY_SURFACE_PROMPT = `## Pier chat surface
 
 Your replies render in a chat UI (web and IM). Three optional markdown
 conventions:
@@ -25,15 +25,19 @@ conventions:
 - **Attachments** — link a file you produced by absolute \`file://\` URL:
   \`[report.md](file:///abs/path/report.md)\`. Images render as thumbnails,
   other files as a download card; only files inside the session's working
-  directory are readable.
+  directory or Pier's inbox are readable. The same convention runs inbound: a
+  user message ending in \`[name](file:///…)\` lines is carrying files the
+  sender attached, already saved to disk — read one only when it matters to
+  the task; every read puts its content in your context for good.
 - **Staying silent** — \`<silent>why</silent>\` is stripped, and if nothing else
   remains no message is sent. In a group chat you are handed every message,
   including humans talking to each other: stay silent rather than acknowledge
   what was not addressed to you.
 
 A message may start with \`[name<id> time]\` — the sender, added by Pier, not
-typed by them. It appears only when the speaker or the day changes, so the last
-one still applies. Use that \`id\` to mention someone; never ask for their own.
+typed by them. It appears only on a change — new speaker, a ~10-minute gap, a
+new day — so the last one still applies; a gap alone shows as time only, like
+\`[14:23]\`. Use that \`id\` to mention someone; never ask for their own.
 `;
 /**
  * The contract above plus the two facts about *this* deployment that an agent
@@ -124,6 +128,17 @@ export function cjkFriendly(markdown) {
     });
     return out.replace(/\uE010(\d+)\uE011/g, (_m, i) => stash[Number(i)] ?? "");
 }
+/**
+ * The one wording for a turn that said nothing, wherever it is shown — the
+ * chat surfaces and the task result path. The reason arrives pre-escaped
+ * because each surface escapes for its own markup; the label itself contains
+ * nothing any of them escape.
+ */
+export const quietLabel = (silence) => silence ? `stayed silent — ${silence}` : "no reply";
+/** One policy for "did this turn actually reply": options count as a reply —
+ *  the buttons are the answer, so a turn that is only its options is not
+ *  "nothing". Every surface decides through here. */
+export const isSilentReply = (reply) => !reply.text.trim() && reply.suggestions.length === 0;
 /** How a reasoning level is spelled wherever a human reads it. */
 export const thinkingLabel = (level) => level === "xhigh" ? "Extra high" : level[0].toUpperCase() + level.slice(1);
 /** 1200 → "1.2K", 12_000 → "12K" — absolute token counts read badly inline. */
@@ -159,7 +174,6 @@ export const formatTurnMeta = (meta) => `${formatDuration(meta.durationMs)} · $
 const BLOCK = /(?:^|\n)[ \t]*-{3,}[ \t]*\r?\n((?:[ \t]*\[[^\]\r\n]+\][ \t]*(?:[|｜][ \t]*)?)+)\s*$/;
 const TOKEN = /\[([^\]\r\n]+)\]/g;
 const MAX_SUGGESTIONS = 5;
-/** Split an assistant turn's markdown into renderable text + next-step labels. */
 /**
  * A deliberate non-answer. In a group thread the agent is handed every message,
  * and most of them are two humans talking; a bot that replies to each one is
@@ -183,6 +197,7 @@ export function silentReason(markdown) {
         .filter(Boolean);
     return reasons.length ? reasons.join(" · ") : undefined;
 }
+/** Split an assistant turn's markdown into renderable text + next-step labels. */
 export function splitReply(rawMarkdown, meta) {
     // Every surface that renders this goes through here, and every CommonMark
     // parser has some version of the CJK emphasis hole — so the repair belongs

package/dist/core/router.js

@@ -1,11 +1,17 @@
-// Conversation → session routing plus event wiring. In-memory for v1;
-// persistence arrives with task storage (docs/plans/bootstrap.md step 4).
+// Conversation → session routing plus event wiring. In-memory on purpose:
+// the durable chat → session map lives in channels/conversations.ts.
 import { logger } from "../log.js";
 import { EventHub } from "./hub.js";
 import { SenderPrefix, withPrefix } from "./identity.js";
 import { decide } from "./queue.js";
 import { splitReply } from "./reply.js";
 const log = logger("core");
+/** How long a session may sit idle in memory before it is let go. Generous on
+ *  purpose: eviction is a memory measure, and re-opening one costs a Pi
+ *  resume plus the transcript being read back. */
+const IDLE_TTL_MS = 30 * 60_000;
+/** Sweep interval. Nothing here is urgent, so it is coarse. */
+const SWEEP_MS = 5 * 60_000;
 /** An error goes into a chat window, so it is trimmed to something readable. */
 const truncate = (message) => message.length > 600 ? `${message.slice(0, 600)}…` : message;
 function keyOf(key) {
@@ -16,9 +22,16 @@ export class Router {
     resolve;
     byKey = new Map();
     bySession = new Map();
+    /** Resolves in flight, so two surfaces asking at once share one session
+     *  object instead of opening a second Pi runtime on the same transcript.
+     *  Web and task keys collapse to the session id they both name. */
+    opening = new Map();
     channels = new Map();
     /** Who each session last heard from, so a header costs tokens only on news. */
     senders = new SenderPrefix();
+    /** Set once by a graceful restart (src/drain.ts); never unset — the process
+     *  exits when the drain ends. */
+    draining = false;
     constructor(hub, 
     /** Create or resume the session owning a conversation (wired in main.ts). */
     resolve) {
@@ -55,6 +68,61 @@ export class Router {
             });
         });
     }
+    /**
+     * Report something that happened *to* a session rather than in it: a task
+     * result that could not be delivered, say. Its conversation is told when one
+     * is attached — an agent that was promised an answer and a human watching the
+     * same thread learn it is not coming from the same place they were waiting.
+     * Otherwise the hub carries it for the web timeline.
+     */
+    reportTo(sessionId, message) {
+        const key = this.conversationOf(sessionId);
+        if (key)
+            this.report(sessionId, key, message);
+        else
+            this.hub.emit(sessionId, { type: "error", message });
+    }
+    /**
+     * Let go of every session that has been idle too long, so a process serving
+     * IM threads and task runs for weeks does not hold one live Pi runtime per
+     * conversation it ever saw. Only the in-memory attachment goes: the durable
+     * conversation → session mapping stays, so the next message resumes the very
+     * same transcript (channels/conversations.ts).
+     *
+     * Skipped for anything that would notice: a streaming turn, and a session
+     * someone is still watching over SSE.
+     */
+    async evictIdle(ttlMs = IDLE_TTL_MS, now = Date.now()) {
+        let evicted = 0;
+        for (const [id, attached] of [...this.bySession]) {
+            if (attached.session.state === "streaming")
+                continue;
+            if (this.hub.hasSubscribers(id))
+                continue;
+            if (now - attached.activeAt < ttlMs)
+                continue;
+            this.bySession.delete(id);
+            this.forgetKeys(attached.session);
+            attached.unsubscribe();
+            this.senders.forget(id);
+            this.hub.dropReplay(id);
+            evicted += 1;
+            log.info(`evicted idle session ${id} (${keyOf(attached.key)})`);
+            // Best-effort: a runtime that will not shut down must not keep the
+            // sweeper from releasing the rest.
+            await attached.session.dispose().catch((err) => log.error(`disposing session ${id} failed`, err));
+        }
+        return evicted;
+    }
+    /** Run evictIdle on a timer. Returns the stop function (main.ts owns it). */
+    startIdleEviction() {
+        // Unref'd: a sweep pending is never a reason for the process to stay up.
+        const timer = setInterval(() => {
+            void this.evictIdle().catch((err) => log.error("idle sweep failed", err));
+        }, SWEEP_MS);
+        timer.unref();
+        return () => clearInterval(timer);
+    }
     stateOf(sessionId) {
         return this.bySession.get(sessionId)?.session.state;
     }
@@ -74,21 +142,43 @@ export class Router {
     conversationOf(sessionId) {
         return this.bySession.get(sessionId)?.key;
     }
+    /** Every key that points at this session object. One session can be reached
+     *  under more than one — `web:<id>` and `task:<id>` name the same session —
+     *  and a key left behind hands out a session that is no longer live. */
+    forgetKeys(session) {
+        for (const [key, held] of this.byKey)
+            if (held === session)
+                this.byKey.delete(key);
+    }
     /** Attach an existing session to a conversation and wire its events. */
     attach(key, session) {
-        this.byKey.set(keyOf(key), session);
         const existing = this.bySession.get(session.id);
-        if (existing?.session === session)
+        if (existing?.session === session) {
+            this.byKey.set(keyOf(key), session);
+            existing.activeAt = Date.now();
             return;
-        this.bySession.set(session.id, { session, key, stateSince: Date.now() });
+        }
+        if (existing) {
+            // Two live objects on one transcript: both would write it and both would
+            // answer the chat. Single-flight `ensure` closes the race that makes
+            // this, so reaching here is a bug worth seeing — the replaced one is
+            // silenced and unreachable, rather than left answering under aliases
+            // nobody knows are stale.
+            log.warn(`session ${session.id} replaced while attached to ${keyOf(existing.key)}`);
+            existing.unsubscribe();
+            this.forgetKeys(existing.session);
+        }
+        this.byKey.set(keyOf(key), session);
         log.info(`attached ${keyOf(key)} → session ${session.id}`);
-        session.subscribe((payload) => {
+        const unsubscribe = session.subscribe((payload) => {
             this.hub.emit(session.id, payload);
             // Run state is workspace-visible: every client's session list shows it.
             if (payload.type === "state") {
                 const attached = this.bySession.get(session.id);
+                // Every turn passes through here, so this is also where a session
+                // proves to the sweeper that it is still in use.
                 if (attached)
-                    attached.stateSince = Date.now();
+                    attached.stateSince = attached.activeAt = Date.now();
                 this.hub.emitWorkspace({
                     type: "session-state",
                     sessionId: session.id,
@@ -132,10 +222,43 @@ export class Router {
                 }
             }
         });
+        this.bySession.set(session.id, {
+            session,
+            key,
+            stateSince: Date.now(),
+            activeAt: Date.now(),
+            unsubscribe,
+        });
     }
     async abort(sessionId) {
         await this.bySession.get(sessionId)?.session.abort();
     }
+    /** Refuse new work from every surface; in-flight turns keep running. */
+    beginDrain() {
+        this.draining = true;
+    }
+    /** For surfaces that mutate state before dispatching (the web's edit and
+     *  queue-deliver routes): ask first, so a refused dispatch cannot cost a
+     *  rewound transcript or a cleared queue. */
+    isDraining() {
+        return this.draining;
+    }
+    /** The drain gate, throwing. Told to the chat directly (5b): an adapter's
+     *  dispatch catch only logs, and the web caller gets the throw. */
+    refuseDraining(key) {
+        const message = "Pier is restarting — this message was not taken; send it again in a moment.";
+        this.channels.get(key.channelId)
+            ?.notify(key.conversationId, { text: message, origin: { kind: "error" } })
+            .catch((err) => log.error(`could not report the drain to ${key.channelId}`, err));
+        throw new Error(message);
+    }
+    /** Attached sessions still mid-turn — what the drain waits on, and what its
+     *  deadline snapshots into the ledger. */
+    busy() {
+        return [...this.bySession.values()]
+            .filter((attached) => attached.session.state === "streaming")
+            .map((attached) => ({ session: attached.session, key: attached.key }));
+    }
     /**
      * The session already attached to a conversation, if any. Never creates one:
      * a channel's stop or settings command must not be what opens a session.
@@ -157,31 +280,80 @@ export class Router {
                 this.byKey.set(keyOf(key), session);
         }
         if (!session) {
+            // Aliases share one lock: web:<id> and task:<id> must not each open one.
+            const lock = key.channelId === "web" || key.channelId === "task"
+                ? `session:${key.conversationId}`
+                : keyOf(key);
+            const inflight = this.opening.get(lock);
+            // A second caller rides the first one's resolve — which attaches before
+            // this continuation runs, having awaited it first — and registers its own
+            // key against the session that came back.
+            if (inflight) {
+                session = await inflight;
+                this.byKey.set(keyOf(key), session);
+                return this.reached(session);
+            }
             try {
-                session = await this.resolve(key);
+                // Inside the try: a resolver that throws synchronously is the same
+                // failure as one that rejects, and reports the same way.
+                const opening = this.resolve(key);
+                this.opening.set(lock, opening);
+                session = await opening;
             }
             catch (err) {
-                // The one failure with nowhere to report itself: there is no session id
-                // to emit under yet, and every caller only sees a rejected promise.
-                log.error(`could not open a session for ${keyOf(key)}`, err);
+                this.unopened(key, err);
                 throw err;
             }
+            finally {
+                this.opening.delete(lock);
+            }
             this.attach(key, session);
         }
+        return this.reached(session);
+    }
+    /** A session that would not open has no event stream of its own to report on
+     *  — unless its id is what we were asked for, which is what a web or task key
+     *  is. Otherwise the chat that is waiting is told directly. Callers still get
+     *  the rejection; this is only so the waiting side is not left with nothing. */
+    unopened(key, err) {
+        log.error(`could not open a session for ${keyOf(key)}`, err);
+        const message = truncate(`could not open a session: ${String(err)}`);
+        // A web or task key names the session that would not open, so its own
+        // stream is where the waiting surface is looking; an IM key names a chat.
+        if (key.channelId === "web" || key.channelId === "task") {
+            this.reportTo(key.conversationId, message);
+            return;
+        }
+        this.channels.get(key.channelId)
+            ?.notify(key.conversationId, { text: message, origin: { kind: "error" } })
+            .catch((e) => log.error(`could not report it to ${key.channelId}`, e));
+    }
+    /** Reached for, so not idle — every surface that uses a session comes
+     *  through `ensure`, including the ones that only read it. */
+    reached(session) {
+        const attached = this.bySession.get(session.id);
+        if (attached)
+            attached.activeAt = Date.now();
         return session;
     }
     async dispatch(msg) {
+        // Before ensure — a drain must not be what opens a session …
+        if (this.draining)
+            this.refuseDraining(msg.key);
         const session = await this.ensure(msg.key);
+        // … and after — a dispatch that was inside a slow ensure when the gate
+        // closed must not start the turn the drain just declared finished with.
+        if (this.draining)
+            this.refuseDraining(msg.key);
         const { action, text } = decide(msg, session.state);
         // A group chat is many people talking into one session; without a speaker
         // line the agent cannot tell them apart or mention anyone back. Emitted
         // only when the speaker or the clock says something new.
         const prompt = withPrefix(this.senders.next(session.id, msg.sender), text);
-        log.debug(`${action} ${keyOf(msg.key)} → session ${session.id}` +
-            ` (${String(prompt.length)} chars, ${String(msg.images?.length ?? 0)} images)`);
+        log.debug(`${action} ${keyOf(msg.key)} → session ${session.id} (${String(prompt.length)} chars)`);
         // Turn outcomes flow through the event stream; a rejected call surfaces
         // there too, never as a thrown exception across the seam.
-        session[action](prompt, msg.images).catch((err) => {
+        session[action](prompt).catch((err) => {
             this.report(session.id, msg.key, String(err));
         });
         return { sessionId: session.id };

package/dist/core/types.js

@@ -5,3 +5,56 @@
  *  drift, and boundary validators use isThinkingLevel instead of their own copy. */
 export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
 export const isThinkingLevel = (v) => typeof v === "string" && THINKING_LEVELS.includes(v);
+// Wire-protocol names, not SDK types — but they are pi-ai's spellings, and a
+// non-Pi backend is bound to them by this seam.
+export const PROVIDER_APIS = [
+    "openai-completions",
+    "openai-responses",
+    "anthropic-messages",
+    "google-generative-ai",
+];
+export const isProviderApi = (value) => typeof value === "string" && PROVIDER_APIS.includes(value);
+/** The rules of the ProviderSetup seam, in one place: agent/ enforces them on
+ *  write and web/ pre-checks them at its HTTP boundary, and neither may import
+ *  the other. Throws the message the surface shows. */
+export function validateProviderSetup(input) {
+    if (input.id.length > 100 || !/^[a-z0-9][a-z0-9._-]*$/.test(input.id)) {
+        throw new Error("invalid provider id");
+    }
+    if (input.endpoint) {
+        if (input.endpoint.length > 2048 || input.endpoint !== input.endpoint.trim()) {
+            throw new Error("invalid endpoint");
+        }
+        validateEndpoint(input.endpoint);
+    }
+    if (input.kind === "builtin")
+        return;
+    if (!input.endpoint)
+        throw new Error("custom provider endpoint required");
+    if (input.name && (input.name.length > 200 || input.name !== input.name.trim())) {
+        throw new Error("invalid provider name");
+    }
+    if (!isProviderApi(input.api))
+        throw new Error("unsupported provider API");
+    if (!input.models.length || input.models.length > 100)
+        throw new Error("1-100 models required");
+    const ids = input.models.map((model) => model.id);
+    if (ids.some((id) => !id || id.length > 200 || id !== id.trim()) || new Set(ids).size !== ids.length) {
+        throw new Error("model ids must be non-empty, trimmed and unique");
+    }
+}
+export function validateEndpoint(endpoint) {
+    let url;
+    try {
+        url = new URL(endpoint);
+    }
+    catch {
+        throw new Error("endpoint must be an http(s) URL");
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new Error("endpoint must be an http(s) URL");
+    }
+    if (url.username || url.password || url.search || url.hash) {
+        throw new Error("endpoint must not contain credentials, query or fragment");
+    }
+}

package/dist/db.js

@@ -126,6 +126,18 @@ const MIGRATIONS = [
     key TEXT PRIMARY KEY,
     value TEXT NOT NULL
   );
+  `,
+    // 3 — what a restart's drain deadline cut off, told to the chat at next boot.
+    `
+  -- Written only when a graceful restart aborts a still-running turn; the next
+  -- boot delivers each row and clears it once delivered. Owned by drain.ts.
+  CREATE TABLE restart_ledger (
+    id INTEGER PRIMARY KEY,
+    channel_id TEXT NOT NULL,
+    conversation_id TEXT NOT NULL,
+    note TEXT NOT NULL,
+    created_at INTEGER NOT NULL
+  );
   `,
 ];
 let shared;
@@ -134,6 +146,17 @@ let shared;
  * defaults to it; a test passes `openDb(":memory:")` instead.
  */
 export const pierDb = () => (shared ??= openDb(PIER_DB));
+/** A release-level restore point, taken while the service is stopped even when
+ * the release has no schema migration. The previous complete copy stays put if
+ * writing its replacement fails. */
+export function backupDb(path = PIER_DB) {
+    if (!existsSync(path))
+        return undefined;
+    const bak = `${path}.release.bak`;
+    copyDatabase(path, bak);
+    log.info(`pre-update backup: ${bak}`);
+    return bak;
+}
 /** Open a database, bring it to the current schema, and lock down its files.
  *  `migrations` is injectable only so tests can exercise an upgrade — there is
  *  exactly one real list. */
@@ -141,10 +164,11 @@ export function openDb(path, migrations = MIGRATIONS) {
     if (path !== ":memory:")
         mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
     const db = new DatabaseSync(path);
-    // Outside the transaction below: journal_mode is a property of the file, and
-    // SQLite refuses to change it inside one.
-    db.exec("PRAGMA journal_mode = WAL");
+    // Timeout first: two processes booting together contend on the WAL switch
+    // itself. Outside the transaction below: journal_mode is a property of the
+    // file, and SQLite refuses to change it inside one.
     db.exec(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`);
+    db.exec("PRAGMA journal_mode = WAL");
     migrate(db, path, migrations);
     if (path !== ":memory:")
         restrict(path);
@@ -175,8 +199,6 @@ function migrate(db, path, migrations) {
     }
     if (at === target)
         return;
-    if (at > 0 && path !== ":memory:")
-        snapshot(db, path, at);
     // One transaction for the statements *and* the version number: a crash
     // between them would leave a database whose version describes a schema it
     // does not have, which is worse than a crash.
@@ -188,9 +210,24 @@ function migrate(db, path, migrations) {
     const { user_version: locked } = db.prepare("PRAGMA user_version").get();
     if (locked >= target) {
         db.exec("ROLLBACK");
+        if (locked > target) {
+            throw new Error(`${path} advanced to schema ${locked} while this Pier was waiting; it speaks ${target}`);
+        }
         log.info(`schema already at ${locked}, migrated by another process`);
         return;
     }
+    // Keep the write lock while a second, read-only connection copies the last
+    // committed state. That connection may VACUUM while this one holds a RESERVED
+    // lock; other Pier starts wait here instead of racing on the shared .tmp.
+    if (locked > 0 && path !== ":memory:") {
+        try {
+            snapshot(path, locked);
+        }
+        catch (err) {
+            db.exec("ROLLBACK");
+            throw err;
+        }
+    }
     let step = locked;
     try {
         for (; step < target; step++)
@@ -221,14 +258,23 @@ function migrate(db, path, migrations) {
  * old snapshot nor a complete new one. A rename is atomic: the `.bak` name only
  * ever refers to a finished copy.
  */
-function snapshot(db, path, at) {
+function snapshot(path, at) {
     const bak = `${path}.v${at}.bak`;
+    copyDatabase(path, bak);
+    log.info(`pre-migration backup: ${bak}`);
+}
+function copyDatabase(path, bak) {
     const tmp = `${bak}.tmp`;
     rmSync(tmp, { force: true }); // a previous crash may have left one
-    db.exec(`VACUUM INTO '${tmp.replaceAll("'", "''")}'`);
+    const source = new DatabaseSync(path, { readOnly: true });
+    try {
+        source.exec(`VACUUM INTO '${tmp.replaceAll("'", "''")}'`);
+    }
+    finally {
+        source.close();
+    }
     chmodSync(tmp, 0o600); // it holds everything the 0600 database holds
     renameSync(tmp, bak);
-    log.info(`pre-migration backup: ${bak}`);
 }
 /** Snapshots beside the database, newest schema first. */
 function backups(path) {

package/dist/drain.js

@@ -0,0 +1,145 @@
+// A graceful restart: refuse new work, let running turns finish, and write
+// down what the deadline had to cut off so the next boot can tell the chats.
+//
+// The trigger is SIGUSR2 (main.ts); systemd's `Restart=always` is the "start
+// again" half. SIGTERM stays the fast path systemd expects — this file is only
+// the slow one. Nothing here is persisted for its own sake: everything durable
+// (transcripts, the chat → session map, task runs) already survives a restart,
+// so the ledger below holds only the one thing that would otherwise vanish
+// silently — turns and queued messages the deadline aborted (§5b).
+import { logger } from "./log.js";
+const log = logger("drain");
+/** How long running turns may take before they are aborted. Generous: a turn
+ *  can be a subagent fan-out, and an abort still persists the partial work. */
+export const DRAIN_DEADLINE_MS = 5 * 60_000;
+const POLL_MS = 1_000;
+/** Shared cleanup window after the deadline. All sessions use the same clock,
+ *  so N hung seams still cost at most this long rather than N times as long. */
+const CLEANUP_BOUND_MS = 10_000;
+/** What the dying process owes the chats, held for the next one to deliver. */
+export class RestartLedger {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    record(entry) {
+        this.db.prepare("INSERT INTO restart_ledger (channel_id, conversation_id, note, created_at) VALUES (?, ?, ?, ?)").run(entry.channelId, entry.conversationId, entry.note, Date.now());
+    }
+    list() {
+        const rows = this.db.prepare("SELECT id, channel_id, conversation_id, note FROM restart_ledger ORDER BY id").all();
+        return rows.map((row) => ({
+            id: row.id,
+            channelId: row.channel_id,
+            conversationId: row.conversation_id,
+            note: row.note,
+        }));
+    }
+    remove(id) {
+        this.db.prepare("DELETE FROM restart_ledger WHERE id = ?").run(id);
+    }
+}
+/**
+ * Resolve when the process may exit: every turn settled and every task run
+ * terminal, or the deadline reached and the stragglers aborted into the
+ * ledger. The caller (main.ts) owns what happens next — the ordinary shutdown,
+ * minus aborting task runs: the boot-time interrupted marking is the recovery
+ * path (tasks/service.ts start()), not a teardown race against dying channels.
+ */
+export async function drainForRestart(deps, deadlineMs = DRAIN_DEADLINE_MS, pollMs = POLL_MS, cleanupBoundMs = CLEANUP_BOUND_MS) {
+    const { router, tasks, ledger } = deps;
+    router.beginDrain();
+    tasks.pause();
+    const deadline = Date.now() + deadlineMs;
+    let lastReport = "";
+    for (;;) {
+        // Sleep first: a prompt accepted just before the gate closed may not have
+        // flipped its session to streaming yet, and exiting on that blink would
+        // cut off the very turn the drain exists to protect.
+        await new Promise((resolve) => setTimeout(resolve, pollMs));
+        const busy = router.busy();
+        const runs = tasks.activeRunCount();
+        if (busy.length === 0 && runs === 0) {
+            log.info("drained — nothing running");
+            return;
+        }
+        if (Date.now() >= deadline) {
+            log.warn(`drain deadline after ${String(Math.round(deadlineMs / 1000))}s — aborting ${String(busy.length)} turn(s); ` +
+                `${String(runs)} task run(s) will be marked interrupted at boot`);
+            const cleanupDeadline = Date.now() + cleanupBoundMs;
+            await Promise.all(busy.map(({ session, key }) => abortToLedger(session, key, ledger, cleanupDeadline)));
+            return;
+        }
+        const report = `draining: ${String(busy.length)} turn(s), ${String(runs)} active task run(s)`;
+        if (report !== lastReport)
+            log.info((lastReport = report));
+    }
+}
+/** A seam call the deadline cannot wait on forever: a hang or a rejection is
+ *  logged and answered with the fallback, and cleanup moves on. */
+async function bounded(work, ms, what, fallback) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            log.error(`${what} did not answer within ${String(ms)}ms`);
+            resolve(fallback);
+        }, ms);
+        timer.unref();
+    });
+    try {
+        return await Promise.race([
+            work.catch((err) => {
+                log.error(`${what} failed`, err);
+                return fallback;
+            }),
+            timeout,
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/** Write the chat's entry, then abort the turn. The ledger comes first so a
+ *  hung abort cannot cost the note; the abort persists the partial transcript;
+ *  the pending queue would just vanish, so its texts ride along. */
+async function abortToLedger(session, key, ledger, cleanupDeadline) {
+    const remaining = () => Math.max(0, cleanupDeadline - Date.now());
+    const queued = await bounded(session.pendingQueue(), remaining(), `queue snapshot of session ${session.id}`, { steering: [], followUp: [] });
+    const pending = [...queued.steering, ...queued.followUp];
+    // A web or task key has no chat to write to: the transcript shows the
+    // aborted turn, and a task run's interruption is reported by its callback
+    // recovery. Only a dropped queue would be invisible there, so it is at
+    // least logged.
+    if (key.channelId === "web" || key.channelId === "task") {
+        if (pending.length) {
+            log.warn(`session ${session.id}: ${String(pending.length)} queued message(s) dropped by the restart`);
+        }
+    }
+    else {
+        const note = [
+            "Pier restarted before this turn finished — the last message may be unanswered.",
+            ...(pending.length ? ["Queued and not delivered:", ...pending.map((text) => `> ${text}`)] : []),
+        ].join("\n");
+        ledger.record({ channelId: key.channelId, conversationId: key.conversationId, note });
+    }
+    await bounded(session.abort(), remaining(), `abort of session ${session.id}`, undefined);
+}
+/**
+ * Deliver what a previous process wrote on its way out. Runs at boot once the
+ * adapters are up, and again on a Console unlock. Each entry is removed only
+ * after confirmed delivery. A missing adapter or a thrown notification keeps
+ * the debt for the next start: a duplicate apology is preferable to silence.
+ */
+export async function deliverLedger(ledger, notify) {
+    for (const entry of ledger.list()) {
+        const target = `${entry.channelId}:${entry.conversationId}`;
+        const delivered = await notify(entry).catch((err) => {
+            log.error(`restart note to ${target} failed`, err);
+            return null;
+        });
+        if (delivered === true)
+            ledger.remove(entry.id);
+        else if (delivered === false)
+            log.warn(`restart note waiting — ${target} is not running: ${entry.note}`);
+    }
+}