@timqi/pier 0.0.1 → 0.0.3

package/dist/tasks/service.js

@@ -14,7 +14,10 @@ import { isTerminal } from "./types.js";
 const log = logger("tasks");
 export class TaskService {
     store;
+    factory;
+    router;
     hub;
+    instance;
     timer = null;
     ticking = false;
     waiters = new Map();
@@ -24,12 +27,19 @@ export class TaskService {
     groups;
     runs;
     execution;
-    constructor(store, factory, router, hub) {
+    constructor(store, factory, router, hub, 
+    /** Structural on purpose: tasks/ must not import settings.ts — main.ts
+     *  hands in a closure over the store instead. Absent in bare test rigs. */
+    instance) {
         this.store = store;
+        this.factory = factory;
+        this.router = router;
         this.hub = hub;
-        this.messages = new TaskMessenger(store, router, hub, (runId, prompt, fromSessionId) => this.resume(runId, prompt, { invokedBySessionId: fromSessionId, callbackSessionId: fromSessionId, background: true }));
+        this.instance = instance;
+        const unreachable = (sessionId, what, why) => this.unreachable(sessionId, what, why);
+        this.messages = new TaskMessenger(store, router, hub, (runId, prompt, fromSessionId) => this.resume(runId, prompt, { invokedBySessionId: fromSessionId, callbackSessionId: fromSessionId, background: true }), unreachable);
         this.definitions = new TaskDefinitions(store, factory, router, hub);
-        this.callbacks = new TaskCallbacks(store, router, (run) => this.changed(run));
+        this.callbacks = new TaskCallbacks(store, router, (run) => this.changed(run), unreachable);
         this.groups = new TaskGroups(store, router, {
             getRun: (id) => this.getRun(id),
             cancel: (id) => { this.cancel(id); },
@@ -41,7 +51,7 @@ export class TaskService {
                 background: true,
                 groupId,
             }),
-        }, (group) => this.hub.emitWorkspace({ type: "task-group-changed", groupId: group.id }));
+        }, (group) => this.hub.emitWorkspace({ type: "task-group-changed", groupId: group.id }), unreachable);
         const agent = new AgentTaskRunner(factory, router, store, this.messages, (run) => this.changed(run));
         this.execution = new TaskExecution(store, this.definitions, this.callbacks, agent, {
             runChild: (taskId, parent) => this.run(taskId, parent.input, "task", parent.id, {
@@ -61,6 +71,9 @@ export class TaskService {
     start(tickMs = 1000) {
         if (this.timer)
             return;
+        // A service started again after pause()/stop() takes work again; without
+        // this, the refusal would outlive the drain that justified it.
+        this.paused = false;
         const now = Date.now();
         // A run that was running when the process died: it is being written off
         // here, and the previous boot's log is where its work stopped.
@@ -72,6 +85,9 @@ export class TaskService {
         this.definitions.resetNextRuns(now);
         this.callbacks.recover(now);
         this.groups.recover(now);
+        this.runTimer(tickMs);
+    }
+    runTimer(tickMs) {
         this.timer = setInterval(() => {
             // The scheduler's own loop: a throw here would stop nothing (the next
             // tick still fires) and say nothing, so due tasks would just stop.
@@ -79,11 +95,40 @@ export class TaskService {
         }, tickMs);
         this.timer.unref();
     }
+    /** Undo a `pause()` that was not followed by an exit — the auto-updater
+     *  drains before handing over, and a handover that never started must not
+     *  leave the scheduler switched off. Deliberately not `start()`: the boot
+     *  recovery in there would write off runs this process is still running. */
+    unpause(tickMs = 1000) {
+        if (this.timer)
+            return;
+        this.paused = false;
+        this.runTimer(tickMs);
+    }
     stop() {
+        this.pause();
+        this.execution.stop();
+    }
+    /** Stop taking new work but leave running runs alone — a graceful restart
+     *  (src/drain.ts) waits for them, where stop() would abort them. The
+     *  scheduler timer goes, and new root runs are refused; children of a run
+     *  that is still finishing stay allowed, because refusing them would fail
+     *  the very work the drain is waiting for. */
+    pause() {
+        this.paused = true;
         if (this.timer)
             clearInterval(this.timer);
         this.timer = null;
-        this.execution.stop();
+    }
+    paused = false;
+    refusePaused(parentRunId = null) {
+        if (this.paused && parentRunId === null) {
+            throw new Error("Pier is restarting — new task runs are not accepted; retry after the restart");
+        }
+    }
+    /** Runs a drain still has to wait for (queued ones start when a slot frees). */
+    activeRunCount() {
+        return this.store.countActiveRuns();
     }
     list() {
         return this.definitions.list();
@@ -126,8 +171,8 @@ export class TaskService {
     recentRuns(limit = 100) {
         return this.store.listRecentRuns(limit);
     }
-    recentMessages(since, limit = 200) {
-        return this.messages.recent(since, limit);
+    recentMessages(since) {
+        return this.messages.recent(since);
     }
     backgroundRuns(sessionId) {
         const cutoff = Date.now() - 60 * 60 * 1000;
@@ -138,6 +183,7 @@ export class TaskService {
             .map((run) => this.backgroundRun(run));
     }
     run(taskId, input = null, source = "manual", parentRunId = null, provenance = {}) {
+        this.refusePaused(parentRunId);
         const task = this.get(taskId);
         // `enabled:false` pauses scheduling only; manual and agent triggers still
         // run a paused task on demand. Archiving is the terminal state.
@@ -145,22 +191,15 @@ export class TaskService {
             throw new Error("archived tasks cannot run");
         return this.runs.enqueue(task, input, source, parentRunId, provenance);
     }
-    async waitForRun(id, signal) {
+    async waitForRun(id) {
         const current = this.getRun(id);
         if (isTerminal(current.state))
             return current;
-        if (signal?.aborted)
-            throw new Error("wait cancelled");
-        return new Promise((resolve, reject) => {
+        return new Promise((resolve) => {
             let set = this.waiters.get(id);
             if (!set)
                 this.waiters.set(id, (set = new Set()));
             set.add(resolve);
-            // An aborted caller must not leave its waiter behind forever.
-            signal?.addEventListener("abort", () => {
-                set.delete(resolve);
-                reject(new Error("wait cancelled"));
-            }, { once: true });
         });
     }
     /** Cascades: orphans must not outlive the delegation that wanted them. */
@@ -179,6 +218,7 @@ export class TaskService {
         return this.groups.members(id);
     }
     runGroup(definitions, join, callerSessionId, parentRunId, callbackSessionId) {
+        this.refusePaused(parentRunId);
         return this.groups.runAll(definitions, join, callerSessionId, parentRunId, callbackSessionId);
     }
     descendants(run) {
@@ -212,6 +252,7 @@ export class TaskService {
         return this.messages.reply(messageId, fromSessionId, message);
     }
     resume(id, message, provenance = {}) {
+        this.refusePaused();
         const prior = this.getRun(id);
         if (!isTerminal(prior.state))
             throw new Error("run must be terminal before resume");
@@ -234,23 +275,52 @@ export class TaskService {
     tool(raw, callerSessionId) {
         return handleTaskTool(this, this.definitions, this.store, this.messages, raw, callerSessionId);
     }
+    /** The deployment's model advice: the operator's pinned menu when one is
+     * set, the curated live catalog otherwise — an agent picks from names that
+     * exist right now, never from memory. */
+    async models() {
+        const menu = this.instance?.modelMenu() ?? [];
+        if (menu.length)
+            return { source: "menu", models: menu };
+        return { source: "catalog", models: await this.factory.availableModels() };
+    }
     async tick() {
         if (this.ticking)
             return;
         this.ticking = true;
         try {
             const now = Date.now();
-            for (const task of this.definitions.claimDue(now)) {
-                this.run(task.id, null, task.trigger.type === "watch" ? "watch" : "cron");
-            }
-            this.callbacks.recover(now);
-            this.groups.recover(now);
-            this.messages.retryUndelivered(now);
+            this.sweep("schedule", () => {
+                for (const task of this.definitions.claimDue(now)) {
+                    this.run(task.id, null, task.trigger.type === "watch" ? "watch" : "cron");
+                }
+            });
+            this.sweep("run callbacks", () => this.callbacks.recover(now));
+            this.sweep("group callbacks", () => this.groups.recover(now));
+            this.sweep("messages", () => this.messages.retryUndelivered(now));
         }
         finally {
             this.ticking = false;
         }
     }
+    /** A delivery nobody can complete. Retrying it forever costs the same
+     * silence as dropping it, so it stops here and says so on three surfaces:
+     * the operator's log, the record the tool and Console read, and the event
+     * stream of the session that was supposed to receive it (§5b). */
+    unreachable(sessionId, what, why) {
+        log.error(`gave up delivering ${what} to session ${sessionId}: ${why}`);
+        this.router.reportTo(sessionId, `${what} could not be delivered — ${why}`);
+    }
+    /** Four independent sweeps, isolated: one throwing (a group whose member row
+     * is gone throws on every pass) must not starve the retries behind it. */
+    sweep(what, run) {
+        try {
+            run();
+        }
+        catch (err) {
+            log.error(`${what} sweep failed`, err);
+        }
+    }
     settled(run) {
         const waiters = this.waiters.get(run.id);
         if (waiters)

package/dist/tasks/store.js

@@ -1,18 +1,26 @@
 import { pierDb } from "../db.js";
-const parseTask = (json) => JSON.parse(json);
-const parseRun = (json) => JSON.parse(json);
+const clamp = (limit, cap) => Math.min(Math.max(limit, 1), cap);
 export class TaskStore {
     db;
     constructor(db = pierDb()) {
         this.db = db;
     }
+    // Every table is one JSON column plus query columns; these two are the only
+    // readers, and the one seam where a future schema change normalizes old rows
+    // (pre-v1 databases are refused outright in db.ts).
+    #one(sql, ...params) {
+        const row = this.db.prepare(sql).get(...params);
+        return row ? JSON.parse(row.json) : undefined;
+    }
+    #many(sql, ...params) {
+        return this.db.prepare(sql).all(...params)
+            .map((row) => JSON.parse(row.json));
+    }
     listTasks() {
-        return this.db.prepare("SELECT json FROM tasks ORDER BY updated_at DESC").all()
-            .map((r) => parseTask(r.json));
+        return this.#many("SELECT json FROM tasks ORDER BY updated_at DESC");
     }
     getTask(id) {
-        const row = this.db.prepare("SELECT json FROM tasks WHERE id = ?").get(id);
-        return row ? parseTask(row.json) : undefined;
+        return this.#one("SELECT json FROM tasks WHERE id = ?", id);
     }
     saveTask(task) {
         this.db.prepare(`
@@ -21,15 +29,13 @@ export class TaskStore {
     `).run(task.id, task.updatedAt, JSON.stringify(task));
     }
     listRuns(taskId, limit = 50, offset = 0) {
-        return this.db.prepare(`
+        return this.#many(`
       SELECT json FROM task_runs WHERE task_id = ?
       ORDER BY queued_at DESC LIMIT ? OFFSET ?
-    `).all(taskId, limit, offset)
-            .map((r) => parseRun(r.json));
+    `, taskId, limit, offset);
     }
     getRun(id) {
-        const row = this.db.prepare("SELECT json FROM task_runs WHERE id = ?").get(id);
-        return row ? parseRun(row.json) : undefined;
+        return this.#one("SELECT json FROM task_runs WHERE id = ?", id);
     }
     saveRun(run) {
         this.db.prepare(`
@@ -40,42 +46,39 @@ export class TaskStore {
     `).run(run.id, run.taskId, run.queuedAt, run.state, run.callbackState, JSON.stringify(run));
     }
     listRecentRuns(limit = 100) {
-        return this.db.prepare(`
-      SELECT json FROM task_runs ORDER BY queued_at DESC LIMIT ?
-    `).all(Math.min(Math.max(limit, 1), 500))
-            .map((row) => parseRun(row.json));
+        return this.#many("SELECT json FROM task_runs ORDER BY queued_at DESC LIMIT ?", clamp(limit, 500));
     }
     listRunsByRoot(rootRunId, limit = 100) {
-        return this.db.prepare(`
+        return this.#many(`
       SELECT json FROM task_runs
       WHERE json_extract(json, '$.rootRunId') = ?
       ORDER BY queued_at LIMIT ?
-    `).all(rootRunId, Math.min(Math.max(limit, 1), 500))
-            .map((row) => parseRun(row.json));
+    `, rootRunId, clamp(limit, 500));
+    }
+    countActiveRuns() {
+        const row = this.db.prepare("SELECT COUNT(*) AS n FROM task_runs WHERE state IN ('queued', 'running')").get();
+        return row.n;
     }
     findActiveRun(taskId) {
-        const row = this.db.prepare(`
+        return this.#one(`
       SELECT json FROM task_runs
       WHERE task_id = ? AND state IN ('queued', 'running') LIMIT 1
-    `).get(taskId);
-        return row ? parseRun(row.json) : undefined;
+    `, taskId);
     }
     findActiveRunForTarget(sessionId) {
-        const row = this.db.prepare(`
+        return this.#one(`
       SELECT json FROM task_runs
       WHERE state IN ('queued', 'running')
         AND json_extract(json, '$.targetSessionId') = ?
       ORDER BY CASE state WHEN 'running' THEN 0 ELSE 1 END, queued_at DESC LIMIT 1
-    `).get(sessionId);
-        return row ? parseRun(row.json) : undefined;
+    `, sessionId);
     }
     listRunsForSession(sessionId, limit = 50) {
-        return this.db.prepare(`
+        return this.#many(`
       SELECT json FROM task_runs
       WHERE json_extract(json, '$.invokedBySessionId') = ?
       ORDER BY queued_at DESC LIMIT ?
-    `).all(sessionId, Math.min(Math.max(limit, 1), 200))
-            .map((row) => parseRun(row.json));
+    `, sessionId, clamp(limit, 200));
     }
     saveGroup(group) {
         this.db.prepare(`
@@ -86,19 +89,18 @@ export class TaskStore {
     `).run(group.id, group.createdAt, group.callbackState, group.finishedAt, JSON.stringify(group));
     }
     getGroup(id) {
-        const row = this.db.prepare("SELECT json FROM task_groups WHERE id = ?").get(id);
-        return row ? JSON.parse(row.json) : undefined;
+        return this.#one("SELECT json FROM task_groups WHERE id = ?", id);
     }
     /** Unfinished joins plus deliverable group callbacks, for settle and recovery. */
     listOpenGroups(now = Date.now()) {
-        return this.db.prepare(`
+        return this.#many(`
       SELECT json FROM task_groups
       WHERE finished_at IS NULL
         OR (callback_state IN ('pending', 'failed')
           AND (json_extract(json, '$.callbackNextAttemptAt') IS NULL
             OR json_extract(json, '$.callbackNextAttemptAt') <= ?))
       ORDER BY created_at
-    `).all(now).map((row) => JSON.parse(row.json));
+    `, now);
     }
     saveMessage(message) {
         this.db.prepare(`
@@ -108,54 +110,45 @@ export class TaskStore {
     `).run(message.id, message.runId, message.state, message.createdAt, JSON.stringify(message));
     }
     getMessage(id) {
-        const row = this.db.prepare("SELECT json FROM task_messages WHERE id = ?").get(id);
-        return row ? JSON.parse(row.json) : undefined;
+        return this.#one("SELECT json FROM task_messages WHERE id = ?", id);
     }
     listMessages(runId) {
-        return this.db.prepare(`
-      SELECT json FROM task_messages WHERE run_id = ? ORDER BY created_at
-    `).all(runId).map((row) => JSON.parse(row.json));
-    }
-    listRecentMessages(since, limit = 200) {
-        return this.db.prepare(`
-      SELECT json FROM task_messages WHERE created_at >= ? ORDER BY created_at DESC LIMIT ?
-    `).all(since, Math.min(Math.max(limit, 1), 500))
-            .map((row) => JSON.parse(row.json));
+        return this.#many("SELECT json FROM task_messages WHERE run_id = ? ORDER BY created_at", runId);
+    }
+    listRecentMessages(since) {
+        return this.#many("SELECT json FROM task_messages WHERE created_at >= ? ORDER BY created_at DESC LIMIT 200", since);
     }
     /** Messages whose injection never landed: the delivery sweep retries these. */
     listUndeliveredMessages() {
-        return this.db.prepare(`
-      SELECT json FROM task_messages WHERE state IN ('pending', 'failed') ORDER BY created_at
-    `).all().map((row) => JSON.parse(row.json));
+        return this.#many("SELECT json FROM task_messages WHERE state IN ('pending', 'failed') ORDER BY created_at");
     }
     /** Decisions are excluded: they have no timeout and stay answerable across
      * restarts — a reply to a terminal run resumes it. */
     expirePendingMessages() {
-        const rows = this.db.prepare(`
+        return this.#many(`
       SELECT json FROM task_messages
       WHERE state = 'pending' AND json_extract(json, '$.kind') != 'decision'
-    `).all();
-        return rows.map((row) => {
-            const message = JSON.parse(row.json);
+    `).map((message) => {
             message.state = "expired";
-            message.error = "Pier restarted before delivery completed";
+            // "Confirmed", not "completed": the input may well have been read — the
+            // proof of it lives in the recipient's transcript, which this layer
+            // cannot see, and the run it steered is interrupted by the same restart.
+            message.error = "Pier restarted before delivery could be confirmed";
             this.saveMessage(message);
             return message;
         });
     }
     listPendingCallbacks(now = Date.now()) {
-        return this.db.prepare(`
+        return this.#many(`
       SELECT json FROM task_runs
       WHERE callback_state IN ('pending', 'failed')
         AND (json_extract(json, '$.callbackNextAttemptAt') IS NULL
           OR json_extract(json, '$.callbackNextAttemptAt') <= ?)
       ORDER BY queued_at
-    `).all(now).map((row) => parseRun(row.json));
+    `, now);
     }
     interruptRunning(now = Date.now()) {
-        const rows = this.db.prepare("SELECT json FROM task_runs WHERE state IN ('queued', 'running')").all();
-        return rows.map((row) => {
-            const run = parseRun(row.json);
+        return this.#many("SELECT json FROM task_runs WHERE state IN ('queued', 'running')").map((run) => {
             run.state = "interrupted";
             run.error = "Pier restarted while the run was active";
             run.finishedAt = now;

package/dist/tasks/tool.js

@@ -36,13 +36,26 @@ const summarize = (run, pendingDecisionId) => defined({
     error: run.error,
     skipReason: run.skipReason,
 });
+/** A list echoes many results at once, so each is capped; a single-run `get`
+ * stays whole — it is the escape hatch every truncation note points at. */
+const trimResult = (summary) => {
+    if (summary.result?.type !== "agent" || summary.result.text.length <= 2000)
+        return summary;
+    return {
+        ...summary,
+        result: {
+            ...summary.result,
+            text: `${summary.result.text.slice(0, 2000)}\n[truncated — get run_id ${summary.runId} for the full text]`,
+        },
+    };
+};
 const summarizeGroup = (group, members, messages) => defined({
     groupId: group.id,
     join: group.join,
     state: group.finishedAt ? "finished" : "running",
     callbackState: group.callbackState,
     winnerRunId: group.winnerRunId,
-    members: members.map((run) => summarize(run, messages.openDecisionId(run.id))),
+    members: members.map((run) => trimResult(summarize(run, messages.openDecisionId(run.id)))),
 });
 // Model-facing draft shape. Guidance only: runtime truth stays in parseDraft,
 // so schema drift can never loosen boundary validation.
@@ -92,9 +105,9 @@ export function taskToolSpec(execute) {
     return {
         name: "task",
         label: "Pier Task",
-        description: "Manage durable Pier tasks and subagents. Agent tasks support reused, fresh, or forked sessions. Run executes a stored task by task_id, a one-shot subagent from an inline task draft, or a core-joined fan-out via tasks[] with join all|first. Get accepts run_id, group_id, or task_id for that task's recent runs. Every operation returns immediately: results, group joins, and decision replies arrive as callback messages. Use steer/follow_up/resume for child control and contact/reply for supervisor decisions.",
+        description: "Manage durable Pier tasks and subagents. Agent tasks support reused, fresh, or forked sessions. Run executes a stored task by task_id, a one-shot subagent from an inline task draft, or a core-joined fan-out via tasks[] with join all|first. Get accepts run_id, group_id, or task_id for that task's recent runs. Every operation returns immediately: results, group joins, and decision replies arrive as callback messages. Use steer/follow_up/resume for child control and contact/reply for supervisor decisions. models lists the deployment's model menu (operator pins with intent notes, else the live catalog).",
         parameters: Type.Object({
-            operation: strEnum("list", "create", "update", "run", "get", "cancel", "steer", "follow_up", "resume", "contact", "reply"),
+            operation: strEnum("list", "create", "update", "run", "get", "cancel", "steer", "follow_up", "resume", "contact", "reply", "models"),
             task_id: Type.Optional(Type.String()),
             run_id: Type.Optional(Type.String()),
             group_id: Type.Optional(Type.String()),
@@ -126,6 +139,8 @@ export async function handleTaskTool(host, definitions, store, messages, raw, ca
     const active = store.findActiveRunForTarget(callerSessionId);
     if (input.operation === "list")
         return definitions.list().filter((task) => task.kind !== "subagent");
+    if (input.operation === "models")
+        return host.models();
     if (input.operation === "create") {
         if (active)
             throw new Error("subagents cannot create task definitions");
@@ -188,7 +203,7 @@ export async function handleTaskTool(host, definitions, store, messages, raw, ca
         // Run history by task: without it, checking what a task did (or whether a
         // cascade landed) means leaving the tool for the database.
         if (input.run_id === undefined && typeof input.task_id === "string") {
-            return host.listRuns(input.task_id, 10).map((run) => summarize(run, messages.openDecisionId(run.id)));
+            return host.listRuns(input.task_id, 10).map((run) => trimResult(summarize(run, messages.openDecisionId(run.id))));
         }
         const run = host.getRun(requiredString(input.run_id, "run_id"));
         return summarize(run, messages.openDecisionId(run.id));

package/dist/tasks/types.js

@@ -1,3 +1,10 @@
+export const retryDelay = (attempts) => Math.min(60_000, 1000 * 2 ** Math.min(attempts, 6));
+/** Attempts before a delivery is given up on and reported. With the backoff
+ *  above that is ~4 minutes: long enough to outlast a busy or restarting
+ *  recipient, short enough that whoever is waiting still cares. */
+export const MAX_DELIVERY_ATTEMPTS = 8;
+/** What a delivery says when it stops trying. */
+export const undeliverable = (attempts, error) => `undeliverable after ${String(attempts)} attempts${error ? `: ${error}` : ""}`;
 export const isTerminal = (state) => state === "succeeded" ||
     state === "failed" ||
     state === "cancelled" ||

package/dist/update.js

@@ -0,0 +1,146 @@
+// The newer Pier: whether one exists, and when this one may become it.
+//
+// The registry is asked, not the GitHub API: `registry.npmjs.org` is a CDN with
+// no rate limit and no token, and it is the same place `npm i -g` would look,
+// so what it reports is what an update would actually get.
+//
+// Nothing here installs anything. Applying is handed to whatever supervises
+// this process (service.ts's oneshot unit, injected as `apply`): a web server
+// holding provider keys must not npm-install as its own child, and the two
+// gates below — the operator switched it on, and nothing is running — are why
+// a self-replacing timer is not simply a supply-chain surface (AGENTS.md 8).
+import { createRequire } from "node:module";
+import { logger } from "./log.js";
+const log = logger("update");
+const PACKAGE = "@timqi/pier";
+const ENDPOINT = `https://registry.npmjs.org/${PACKAGE}/latest`;
+/** One conditional-GET-sized request against a CDN, so the cost of asking is
+ *  not what sets this — how long a released fix may sit unnoticed is. */
+const TTL_MS = 30 * 60_000;
+const TIMEOUT_MS = 5_000;
+export const currentVersion = () => createRequire(import.meta.url)("../package.json").version;
+export const isValidVersion = (version) => /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.test(version);
+/**
+ * `1.2.3` against `1.10.0`, numerically per field: a string compare would call
+ * the second one older. A prerelease suffix loses to the release it precedes,
+ * which is all the semver this needs.
+ */
+export function isNewer(candidate, than) {
+    const parse = (v) => (v.split("-")[0] ?? "").split(".").map((n) => Number.parseInt(n, 10) || 0);
+    const [a, b] = [parse(candidate), parse(than)];
+    for (let i = 0; i < 3; i++) {
+        if ((a[i] ?? 0) !== (b[i] ?? 0))
+            return (a[i] ?? 0) > (b[i] ?? 0);
+    }
+    // Equal numbers: a prerelease is older than the release of the same version.
+    const pre = (v) => v.split("-")[1] ?? "";
+    return pre(candidate) === "" && pre(than) !== "";
+}
+/** One registry answer, cached, shared by every caller. */
+export class UpdateCheck {
+    current;
+    fetchLatest;
+    now;
+    #latest = null;
+    #checkedAt = 0;
+    #inFlight;
+    constructor(current = currentVersion(), fetchLatest = fetchLatestVersion, now = Date.now) {
+        this.current = current;
+        this.fetchLatest = fetchLatest;
+        this.now = now;
+    }
+    /** The last answer, and a refresh in the background when it is stale. Never
+     *  awaits the network: a workbench that loads is worth more than a fresh
+     *  version number. */
+    status() {
+        if (this.now() - this.#checkedAt >= TTL_MS)
+            void this.refresh();
+        return {
+            current: this.current,
+            latest: this.#latest,
+            available: this.#latest !== null && isNewer(this.#latest, this.current),
+        };
+    }
+    /** The answer, waiting for the very first check instead of reporting "no
+     *  idea". A browser asks once per page load, so a process that had never
+     *  checked told every one of them `latest: null` — which is exactly how a
+     *  published release looked undetected. Later loads are served from cache. */
+    async statusNow() {
+        if (this.#checkedAt === 0)
+            await this.refresh();
+        return this.status();
+    }
+    /** Ask now. Concurrent callers share the one request. */
+    refresh() {
+        this.#inFlight ??= this.fetchLatest()
+            .then((latest) => {
+            this.#latest = latest;
+            if (isNewer(latest, this.current))
+                log.info(`${latest} is available (running ${this.current})`);
+        })
+            // A failed check is not a failure: no network, an offline box, a registry
+            // hiccup. It is reported once at debug and retried at the next TTL.
+            .catch((err) => log.debug(`registry check failed: ${String(err)}`))
+            .finally(() => {
+            this.#checkedAt = this.now();
+            this.#inFlight = undefined;
+        });
+        return this.#inFlight;
+    }
+}
+/** Often enough to catch an idle window on a busy box, and cheap: the registry
+ *  itself is still only asked once per TTL (`status()` owns that). */
+const AUTO_POLL_MS = 15 * 60_000;
+/** Watch for the moment all three conditions hold. Returns its own stop. */
+export function startAutoUpdate(check, auto, pollMs = AUTO_POLL_MS) {
+    // A handover drains first, which can outlast a poll interval; a second
+    // attempt on top of it would drain an already-draining Pier.
+    let handingOver = false;
+    const tick = async () => {
+        if (handingOver || !auto.enabled())
+            return;
+        // Refreshes in the background when stale; today's answer is good enough,
+        // because the next tick is a quarter of an hour away either way.
+        const { latest, available } = check.status();
+        if (!available || !auto.idle())
+            return;
+        log.info(`auto-update: idle and ${latest ?? "a newer version"} is out — handing over to the updater`);
+        handingOver = true;
+        try {
+            const started = await auto.apply();
+            // Not silent (§5b): an update that never happens must not look like an
+            // update that was never wanted. `busy` is the one non-start that is
+            // fine — someone else is already restarting this Pier.
+            if (started === "busy")
+                log.info("auto-update: a handover or restart is already in progress");
+            else if (started !== "started")
+                log.error(`auto-update could not start: ${started}`);
+        }
+        catch (err) {
+            log.error("auto-update failed", err);
+        }
+        finally {
+            // Only reached when the handover did *not* take the process with it, so
+            // the next tick is allowed to try again.
+            handingOver = false;
+        }
+    };
+    const timer = setInterval(() => void tick(), pollMs);
+    timer.unref(); // a pending check must never be what keeps the process alive
+    return () => clearInterval(timer);
+}
+export async function fetchLatestVersion() {
+    // Plain JSON: the abbreviated-packument content type npm uses for a whole
+    // package is a 406 on this endpoint, which answers one version already.
+    const res = await fetch(ENDPOINT, {
+        signal: AbortSignal.timeout(TIMEOUT_MS),
+        headers: { accept: "application/json" },
+    });
+    if (!res.ok)
+        throw new Error(`registry answered ${res.status}`);
+    const body = (await res.json());
+    if (typeof body.version !== "string" || !isValidVersion(body.version)) {
+        throw new Error("registry answered without a valid version");
+    }
+    return body.version;
+}