toolroll 0.5.0 → 0.7.0

package/dist/provider-auth.js

@@ -0,0 +1,291 @@
+import { PROVIDER_IDS } from "./provider.js";
+/** Every sign-in message's dedupe key starts here: `signin:<kind>:<provider>:<ordinal>:<person>`.
+ * Not a lifecycle (`life:`) key: those are progress chatter, and an undelivered
+ * one stays out of the attention list — this one needs a person. */
+export const SIGN_IN_KEY_PREFIX = "signin:";
+export const PROVIDER_AUTH_SCHEMA = `
+CREATE TABLE IF NOT EXISTS provider_auth_pause (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  provider    TEXT NOT NULL,
+  ordinal     INTEGER NOT NULL,
+  auth_mode   TEXT NOT NULL DEFAULT 'subscription' CHECK (auth_mode IN ('subscription', 'api-key')),
+  opened_at   TEXT NOT NULL,
+  first_run   INTEGER,
+  task_ref    INTEGER,
+  runs        INTEGER NOT NULL DEFAULT 1,
+  -- 1 once a sign-in probe during this pause said the provider is signed out:
+  -- only a probe that then sees it signed in again may lift the pause.
+  probe_saw_out INTEGER NOT NULL DEFAULT 0,
+  lifted_at   TEXT,
+  lifted_by   TEXT,
+  lifted_how  TEXT CHECK (lifted_how IS NULL OR lifted_how IN ('run', 'probe', 'person')),
+  resumed     INTEGER,
+  -- The last task let through as a trial while paused: a sign-in check can
+  -- say "logged in" for a session that no longer works, so a real run decides.
+  last_trial_at TEXT,
+  UNIQUE (provider, ordinal)
+);
+CREATE UNIQUE INDEX IF NOT EXISTS provider_auth_pause_open ON provider_auth_pause (provider) WHERE lifted_at IS NULL;
+`;
+const NAMES = { claude: "Claude", codex: "Codex", openrouter: "OpenRouter", gemini: "Gemini" };
+const SIGN_IN = { claude: "claude /login", codex: "codex login", gemini: "gemini", openrouter: "toolroll keys set openrouter" };
+export function providerName(provider) {
+    return PROVIDER_IDS.includes(provider) ? NAMES[provider] : provider;
+}
+/** The plain reason: "Claude needs you to sign in again". */
+export function signInReason(pause) {
+    const name = providerName(pause.provider);
+    return pause.authMode === "api-key" ? `${name} needs a working API key` : `${name} needs you to sign in again`;
+}
+/** What to run, as a command. */
+export function signInCommand(pause) {
+    return pause.authMode === "api-key" && pause.provider !== "openrouter" ? `toolroll keys set ${pause.provider}` : SIGN_IN[pause.provider];
+}
+/** The same command for a chat message: the phone scrub hides anything shaped
+ * like a path (`/login` included), so a message names Claude's equivalent
+ * `claude auth login`. */
+function messageCommand(pause) {
+    const command = signInCommand(pause);
+    return command === "claude /login" ? "claude auth login" : command;
+}
+/** One line for status, ready and the console. */
+export function signInWords(pause) {
+    return `${signInReason(pause)}. Run \`${signInCommand(pause)}\` on this computer; its tasks start again on their own once it works (or \`toolroll providers resume ${pause.provider}\`).`;
+}
+function readPause(row) {
+    return {
+        id: Number(row["id"]),
+        provider: String(row["provider"]),
+        ordinal: Number(row["ordinal"]),
+        authMode: row["auth_mode"] === "api-key" ? "api-key" : "subscription",
+        openedAt: String(row["opened_at"]),
+        firstRun: row["first_run"] == null ? null : Number(row["first_run"]),
+        taskRef: row["task_ref"] == null ? null : Number(row["task_ref"]),
+        runs: Number(row["runs"]),
+    };
+}
+/** The open pause for a provider, or null. */
+export function authPauseOf(store, provider) {
+    const row = store.handle.prepare("SELECT * FROM provider_auth_pause WHERE provider = ? AND lifted_at IS NULL").get(provider);
+    return row === undefined ? null : readPause(row);
+}
+/**
+ * SQL: whether the pause `pause` (a provider_auth_pause alias) is on one of
+ * the task_ref `taskRef`'s current providers — its pins, its working profile,
+ * route legs and fallback entries — so a task re-routed to another provider
+ * stops saying it waits on the old one. A task that names none yet (an
+ * unpinned planner, whose agent comes from configuration) keeps what the gate
+ * found.
+ */
+export function pauseOnTaskProviders(pause, taskRef) {
+    const providers = `SELECT r.agent_provider provider FROM task_ref r WHERE r.id = ${taskRef}
+    UNION ALL SELECT r.plan_provider FROM task_ref r WHERE r.id = ${taskRef}
+    UNION ALL SELECT json_extract(ts.profile_json, '$.provider') FROM task_ref r JOIN task_scope ts ON ts.task_id = r.external_id
+      WHERE r.id = ${taskRef} AND json_valid(ts.profile_json)
+    UNION ALL SELECT json_extract(leg.value, '$.provider') FROM task_ref r JOIN task_scope ts ON ts.task_id = r.external_id,
+      json_each(CASE WHEN json_valid(ts.proposed_route_json) THEN ts.proposed_route_json ELSE '{}' END, '$.legs') leg WHERE r.id = ${taskRef}
+    UNION ALL SELECT json_extract(entry.value, '$.profile.provider') FROM task_ref r JOIN task_scope ts ON ts.task_id = r.external_id,
+      json_each(CASE WHEN json_valid(ts.proposed_chain_json) THEN ts.proposed_chain_json ELSE '{}' END, '$.chain') entry WHERE r.id = ${taskRef}`;
+    return `(${pause}.provider IN (SELECT provider FROM (${providers}) WHERE provider IS NOT NULL)
+    OR NOT EXISTS (SELECT 1 FROM (${providers}) WHERE provider IS NOT NULL))`;
+}
+/** The open pause the dispatch gate last left this task waiting on, while it
+ * is still on one of the task's providers; or null. */
+export function authWaitOf(store, taskRef) {
+    const row = store.handle.prepare(`SELECT p.* FROM task_ref r JOIN provider_auth_pause p ON p.id = r.auth_wait_pause
+    WHERE r.id = ? AND p.lifted_at IS NULL AND ${pauseOnTaskProviders("p", "r.id")}`).get(taskRef);
+    return row === undefined ? null : readPause(row);
+}
+/** Every open pause, oldest first. */
+export function openAuthPauses(store) {
+    return store.handle.prepare("SELECT * FROM provider_auth_pause WHERE lifted_at IS NULL ORDER BY id").all().map(readPause);
+}
+/**
+ * Record an auth-expired run against its provider's pause, opening the
+ * incident (and its one notification) when none is open. Called inside the
+ * run's own failure transaction. Returns whether this run opened it.
+ */
+export function pauseForAuth(store, args) {
+    return store.transact(() => {
+        const db = store.handle;
+        const open = authPauseOf(store, args.provider);
+        if (open !== null) {
+            db.prepare("UPDATE provider_auth_pause SET runs = runs + 1 WHERE id = ?").run(open.id);
+            return { opened: false, pause: { ...open, runs: open.runs + 1 } };
+        }
+        const ordinal = Number(db.prepare("SELECT COALESCE(MAX(ordinal), 0) + 1 AS n FROM provider_auth_pause WHERE provider = ?").get(args.provider)?.["n"] ?? 1);
+        const inserted = db.prepare(`INSERT INTO provider_auth_pause (provider, ordinal, auth_mode, opened_at, first_run, task_ref)
+      VALUES (?, ?, ?, ?, ?, ?)`).run(args.provider, ordinal, args.authMode ?? "subscription", args.now.toISOString(), args.runId, args.taskRef);
+        const pause = readPause(db.prepare("SELECT * FROM provider_auth_pause WHERE id = ?").get(Number(inserted.lastInsertRowid)));
+        notifyOperators(store, `auth-expired:${pause.provider}:${pause.ordinal}`, {
+            kind: "auth-expired",
+            subject: signInReason(pause),
+            body: `Run \`${messageCommand(pause)}\` on this computer. Its tasks wait in the queue; one is tried every 10 minutes and the rest start again on their own once ${providerName(pause.provider)} works (or run \`toolroll providers resume ${pause.provider}\`).`,
+        }, args.now);
+        return { opened: true, pause };
+    });
+}
+/**
+ * One message per instance operator, addressed to them: only someone at this
+ * computer can sign an agent back in, and a personal notification reaches that
+ * person on every channel they paired (Telegram, Slack, Discord, Teams) and in
+ * the console, whichever projects those channels follow.
+ */
+function notifyOperators(store, key, message, now) {
+    const operators = store.accountFacts().map(one => one.name).filter(name => store.isInstanceOperator(name));
+    for (const recipient of operators) {
+        store.enqueueNotification({
+            dedupeKey: `${SIGN_IN_KEY_PREFIX}${key}:${recipient}`,
+            kind: message.kind,
+            pushClass: "attention",
+            link: "/work",
+            subject: message.subject,
+            body: message.body,
+            recipient,
+            source: { installation: true },
+        }, now);
+    }
+}
+/**
+ * Lift a provider's open pause — a run or probe on it succeeded, or a person
+ * resumed it — and send the one short "signed in again" message. Returns the
+ * number of tasks its incident sent back to the queue, or null when nothing
+ * was paused.
+ */
+export function liftAuthPause(store, provider, how, by, now, 
+/** For a run: when it started. A run that began before the pause opened proves nothing about the sign-in now. */
+runStartedAt) {
+    return store.transact(() => {
+        const pause = authPauseOf(store, provider);
+        if (pause === null)
+            return null;
+        if (runStartedAt !== undefined && runStartedAt.getTime() < Date.parse(pause.openedAt))
+            return null;
+        const resumed = Number(store.handle.prepare(`SELECT COUNT(DISTINCT task_ref) AS n FROM run
+      WHERE provider = ? AND reason = 'auth-expired' AND finished_at >= ?`).get(provider, pause.openedAt)?.["n"] ?? 0);
+        store.handle.prepare("UPDATE provider_auth_pause SET lifted_at = ?, lifted_by = ?, lifted_how = ?, resumed = ? WHERE id = ? AND lifted_at IS NULL")
+            .run(now.toISOString(), by.slice(0, 120), how, resumed, pause.id);
+        const name = providerName(provider);
+        notifyOperators(store, `auth-restored:${pause.provider}:${pause.ordinal}`, {
+            kind: "auth-restored",
+            subject: `${name} is signed in again, ${resumed} ${resumed === 1 ? "task" : "tasks"} resumed`,
+            body: how === "person" ? `Resumed by ${by.slice(0, 80)}.` : `A ${how === "run" ? "run" : "sign-in check"} on ${name} worked.`,
+        }, now);
+        if (how === "person") {
+            store.recordAction({ at: now.toISOString(), actor: by.slice(0, 120), repo: null, taskId: null, runId: null,
+                action: `resumed ${name} after a sign-in pause`, outcome: "resumed", source: "request", detail: `${resumed} ${resumed === 1 ? "task" : "tasks"}` });
+        }
+        store.bumpWake();
+        return { resumed, pause };
+    });
+}
+/**
+ * What a non-spending sign-in probe said. A probe lifts the pause only after
+ * one during the same pause saw the provider signed out: a CLI that reports
+ * "logged in" while its session cannot refresh must not lift and re-open the
+ * pause over and over.
+ */
+export function noteSignInProbe(store, provider, state, now) {
+    const pause = authPauseOf(store, provider);
+    if (pause === null)
+        return null;
+    if (state === "signed-out" || state === "key-refused" || state === "missing-key") {
+        store.handle.prepare("UPDATE provider_auth_pause SET probe_saw_out = 1 WHERE id = ?").run(pause.id);
+        return null;
+    }
+    if (state !== "connected" && state !== "key-works")
+        return null;
+    const sawOut = Number(store.handle.prepare("SELECT probe_saw_out FROM provider_auth_pause WHERE id = ?").get(pause.id)?.["probe_saw_out"] ?? 0) === 1;
+    if (!sawOut)
+        return null;
+    const lifted = liftAuthPause(store, provider, "probe", "sign-in check", now);
+    return lifted === null ? null : { resumed: lifted.resumed };
+}
+/** How often a paused provider lets one task through as a trial. */
+export const AUTH_TRIAL_MS = 10 * 60_000;
+/**
+ * Whether this task may go ahead as the paused provider's trial: at most one
+ * every AUTH_TRIAL_MS. A trial that works lifts the pause (its run proves the
+ * sign-in); one that fails the same way only counts against the open
+ * incident, so nobody is told twice. Null when no trial is due.
+ */
+export function claimAuthTrial(store, pause, now) {
+    return store.transact(() => {
+        const due = new Date(now.getTime() - AUTH_TRIAL_MS).toISOString();
+        const row = store.handle.prepare("SELECT last_trial_at FROM provider_auth_pause WHERE id = ?").get(pause.id);
+        const previous = row?.["last_trial_at"] == null ? null : String(row["last_trial_at"]);
+        const takenAt = now.toISOString();
+        const claimed = store.handle.prepare(`UPDATE provider_auth_pause SET last_trial_at = ?
+      WHERE id = ? AND lifted_at IS NULL AND COALESCE(last_trial_at, opened_at) <= ?`).run(takenAt, pause.id, due);
+        return Number(claimed.changes) === 1 ? { pauseId: pause.id, takenAt, previous } : null;
+    });
+}
+/** Give a trial back when its task never started (its claim failed), so the next pass may take it. */
+export function giveBackAuthTrial(store, trial) {
+    store.handle.prepare("UPDATE provider_auth_pause SET last_trial_at = ? WHERE id = ? AND last_trial_at = ? AND lifted_at IS NULL")
+        .run(trial.previous, trial.pauseId, trial.takenAt);
+}
+/**
+ * The sign-in gate every road that starts an agent asks before it claims
+ * anything: the tick's queue, and the roads beside it (fallback entries,
+ * attended continuations, contest resumes). Waits when a provider is paused,
+ * unless this is the pause's one trial. A waiting task is noted on its
+ * task_ref, so the work index says exactly what the gate decided; a task let
+ * through is un-noted. A road whose claim fails after a trial calls giveBack.
+ */
+export function signInGate(store, providers, now, taskRef) {
+    const pause = [...new Set(providers)].map(one => authPauseOf(store, one)).find(one => one !== null) ?? null;
+    const trial = pause === null ? null : claimAuthTrial(store, pause, now);
+    const waiting = pause !== null && trial === null ? pause : null;
+    if (taskRef !== undefined) {
+        store.handle.prepare("UPDATE task_ref SET auth_wait_pause = ? WHERE id = ? AND auth_wait_pause IS NOT ?").run(waiting?.id ?? null, taskRef, waiting?.id ?? null);
+    }
+    let given = false;
+    return {
+        waiting,
+        giveBack: () => {
+            if (trial === null || given)
+                return;
+            given = true;
+            giveBackAuthTrial(store, trial);
+        },
+    };
+}
+/** The loop beside the console: every two minutes, probe each paused
+ * provider's sign-in (no model, nothing spent) and lift the pause when it
+ * works again. Nothing is probed while nothing is paused. */
+export function startSignInProbes(store, check, everyMs = 120_000) {
+    let stopped = false;
+    let running = false;
+    const tick = async () => {
+        if (stopped || running)
+            return;
+        running = true;
+        try {
+            for (const pause of openAuthPauses(store)) {
+                try {
+                    noteSignInProbe(store, pause.provider, (await check(pause.provider, true)).state, new Date());
+                }
+                catch { /* the next pass asks again */ }
+            }
+        }
+        catch { /* the next pass asks again */ }
+        finally {
+            running = false;
+        }
+    };
+    const timer = setInterval(() => { void tick(); }, everyMs);
+    timer.unref?.();
+    return () => { stopped = true; clearInterval(timer); };
+}
+/** The console's view of every open pause: title, command, one action. */
+export function signInNotices(store) {
+    return openAuthPauses(store).map(pause => ({
+        provider: pause.provider,
+        title: signInReason(pause),
+        command: signInCommand(pause),
+        detail: "",
+        resumeLabel: `Resume ${providerName(pause.provider)}`,
+        resumeHref: `/providers/${pause.provider}/resume`,
+    }));
+}

package/dist/provider.d.ts

@@ -152,6 +152,8 @@ export declare const OPENROUTER_ENV_KEY = "OPENROUTER_API_KEY";
  * the argv and later turns cannot spend past it.
  */
 export declare const claudeHeldArgv: (invocation: Omit<Invocation, "brief">) => string[];
+/** Claude's own tools that only make sense with a person to wake them. */
+export declare const HEADLESS_DISALLOWED_TOOLS: readonly string[];
 /**
  * The diagnostic discipline (Phase 3 B6/C6): the harness's own words are
  * untrusted bytes headed for refusal screens and notifications — controls

package/dist/provider.js

@@ -184,6 +184,8 @@ const CLAUDE_REVIEW_JSON_SCHEMA = {
     required: ["version"],
     additionalProperties: false,
 };
+/** Claude's own tools that only make sense with a person to wake them. */
+export const HEADLESS_DISALLOWED_TOOLS = ["ScheduleWakeup", "CronCreate", "Monitor"];
 const claudeArgv = (invocation) => [
     "-p",
     invocation.brief,
@@ -207,7 +209,12 @@ const claudeArgv = (invocation) => [
     ...(invocation.maxBudgetUsd === undefined ? [] : ["--max-budget-usd", String(invocation.maxBudgetUsd)]),
     ...(invocation.phase === "review"
         ? [...CLAUDE_REVIEW_ISOLATION_ARGV, "--json-schema", JSON.stringify(CLAUDE_REVIEW_JSON_SCHEMA)]
-        : [...(invocation.toolArgv ?? []), ...(invocation.fence !== undefined && invocation.fence.length > 0 ? ["--settings", claudeFenceSettings(invocation.fence)] : [])]),
+        : [
+            // Headless (run 2085): a wakeup, cron job or monitor needs a later
+            // turn that a -p process never gets. Denied at the harness too.
+            "--disallowedTools", HEADLESS_DISALLOWED_TOOLS.join(","),
+            ...(invocation.toolArgv ?? []), ...(invocation.fence !== undefined && invocation.fence.length > 0 ? ["--settings", claudeFenceSettings(invocation.fence)] : [])
+        ]),
 ];
 /**
  * The turn's own words, preferring the schema-validated structured field

package/dist/releases.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Knowing, calmly, when a newer Toolroll exists.
+ *
+ * At most once a day one anonymous GET asks the npm registry for the latest
+ * version, and one more reads that version's GitHub release notes (the body
+ * only). Nothing identifies this installation: no telemetry, no id, no
+ * query string. The answer is cached in a small JSON file beside the
+ * database; offline or any other failure is silent and changes nothing.
+ * TOOLROLL_NO_UPDATE_CHECK=1 or the switch on Settings → Updates turns the
+ * check off entirely.
+ */
+import type { Store } from "./store.js";
+export declare const RELEASE_CACHE_FILE = "latest-release.json";
+/** Holds "off" while a person has switched the daily check off on Settings → Updates. */
+export declare const UPDATE_SWITCH_FILE = "update-check";
+export declare const RUNNER_VERSIONS_FILE = "runner-versions.json";
+export declare const CHECK_EVERY_MS: number;
+export declare const CHECK_TIMEOUT_MS = 5000;
+export declare const REGISTRY_URL = "https://registry.npmjs.org/toolroll/latest";
+export declare const RELEASES_PAGE = "https://github.com/ap9000/toolroll/releases/tag/";
+export type Release = {
+    version: string;
+    notes: string;
+    url: string;
+    security: boolean;
+};
+export type ReleaseIo = {
+    fetch?: typeof fetch;
+    now?: () => Date;
+    env?: Record<string, string | undefined>;
+};
+/** Off by the environment (it wins) or by the Settings switch. */
+export declare function updateChecksOff(env: Record<string, string | undefined>, dir: string): {
+    off: boolean;
+    byEnv: boolean;
+};
+export declare function setUpdateChecks(dir: string, on: boolean): void;
+/** What the last check found, whenever it ran; null when none has succeeded. Never touches the network. */
+export declare function cachedRelease(dir: string): Release | null;
+/**
+ * The latest published release, checked at most once a day. Returns what the
+ * cache knows while it is fresh, asks again once it is a day old, and on any
+ * failure keeps what it knew before (null when it knew nothing). Never throws.
+ */
+export declare function latestRelease(dir: string, io?: ReleaseIo): Promise<Release | null>;
+/** Notes that mention "Security" mark a security release. */
+/** A release marks itself as a security release with a line or heading that starts with "Security" (for example
+ * "## Security" or "- **Security fix.**"), not by mentioning the word ("no security changes"). */
+export declare function isSecurityRelease(notes: string): boolean;
+/** a > b for dotted versions; a pre-release sorts before its release. */
+export declare function isNewer(a: string, b: string): boolean;
+/** The release worth mentioning: newer than `current`, else null. */
+export declare function newerRelease(release: Release | null, current: string): Release | null;
+/** The one status line, only when a newer release exists. */
+export declare function updateLine(release: Release | null, current: string, updateCommand: string): string | null;
+/**
+ * A security release tells each instance operator once per version, through
+ * the outbox and addressed to them (like a sign-in pause): only someone at
+ * this computer can update it. Returns how many messages were queued.
+ */
+export declare function notifySecurityRelease(store: Store, release: Release | null, current: string, updateCommand: string, now: Date): number;
+/** Each runner's Toolroll version, as it last said at start. */
+export type RunnerVersion = {
+    runner: string;
+    version: string;
+    at: string;
+};
+export declare function recordRunnerVersion(dir: string, runner: string, version: string, now: Date): void;
+export declare function runnerVersions(dir: string): RunnerVersion[];
+/**
+ * The console's background check: at start and then hourly (the daily limit
+ * is latestRelease's own), and a security release notifies operators.
+ */
+export declare function startUpdateChecks(store: Store, dir: string, current: string, updateCommand: string, io?: ReleaseIo & {
+    everyMs?: number;
+}): () => void;

package/dist/releases.js

@@ -0,0 +1,225 @@
+/**
+ * Knowing, calmly, when a newer Toolroll exists.
+ *
+ * At most once a day one anonymous GET asks the npm registry for the latest
+ * version, and one more reads that version's GitHub release notes (the body
+ * only). Nothing identifies this installation: no telemetry, no id, no
+ * query string. The answer is cached in a small JSON file beside the
+ * database; offline or any other failure is silent and changes nothing.
+ * TOOLROLL_NO_UPDATE_CHECK=1 or the switch on Settings → Updates turns the
+ * check off entirely.
+ */
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { envValue } from "./names.js";
+export const RELEASE_CACHE_FILE = "latest-release.json";
+/** Holds "off" while a person has switched the daily check off on Settings → Updates. */
+export const UPDATE_SWITCH_FILE = "update-check";
+export const RUNNER_VERSIONS_FILE = "runner-versions.json";
+export const CHECK_EVERY_MS = 24 * 60 * 60 * 1000;
+export const CHECK_TIMEOUT_MS = 5_000;
+export const REGISTRY_URL = "https://registry.npmjs.org/toolroll/latest";
+export const RELEASES_PAGE = "https://github.com/ap9000/toolroll/releases/tag/";
+const NOTES_API = "https://api.github.com/repos/ap9000/toolroll/releases/tags/";
+const NOTES_MAX = 20_000;
+const VERSION = /^\d{1,6}\.\d{1,6}\.\d{1,6}(?:-[0-9A-Za-z.-]{1,40})?$/;
+/** Off by the environment (it wins) or by the Settings switch. */
+export function updateChecksOff(env, dir) {
+    const flag = envValue(env, "NO_UPDATE_CHECK");
+    if (flag !== undefined && flag !== "" && flag !== "0")
+        return { off: true, byEnv: true };
+    try {
+        return { off: readFileSync(join(dir, UPDATE_SWITCH_FILE), "utf8").trim() === "off", byEnv: false };
+    }
+    catch {
+        return { off: false, byEnv: false };
+    }
+}
+export function setUpdateChecks(dir, on) {
+    writeAtomic(join(dir, UPDATE_SWITCH_FILE), on ? "on\n" : "off\n");
+}
+/** What the last check found, whenever it ran; null when none has succeeded. Never touches the network. */
+export function cachedRelease(dir) {
+    return readCache(dir)?.release ?? null;
+}
+/**
+ * The latest published release, checked at most once a day. Returns what the
+ * cache knows while it is fresh, asks again once it is a day old, and on any
+ * failure keeps what it knew before (null when it knew nothing). Never throws.
+ */
+export async function latestRelease(dir, io = {}) {
+    const env = io.env ?? process.env;
+    if (updateChecksOff(env, dir).off)
+        return null;
+    const now = (io.now ?? (() => new Date()))();
+    const cache = readCache(dir);
+    if (cache !== null && now.getTime() - Date.parse(cache.checkedAt) < CHECK_EVERY_MS && Date.parse(cache.checkedAt) <= now.getTime())
+        return cache.release;
+    const request = io.fetch ?? fetch;
+    let release = cache?.release ?? null;
+    try {
+        const version = await askVersion(request);
+        if (version !== null) {
+            const notes = version === cache?.release?.version && cache.release.notes !== "" ? cache.release.notes : await askNotes(request, version);
+            release = { version, notes, url: `${RELEASES_PAGE}v${version}`, security: isSecurityRelease(notes) };
+        }
+    }
+    catch {
+        // Offline, slow or refused: nothing to say.
+    }
+    // The attempt is stamped either way, so a failure does not ask again until tomorrow.
+    try {
+        writeAtomic(join(dir, RELEASE_CACHE_FILE), `${JSON.stringify({ checkedAt: now.toISOString(), release })}\n`);
+    }
+    catch {
+        // A read-only folder only means asking again next time.
+    }
+    return release;
+}
+/** Notes that mention "Security" mark a security release. */
+/** A release marks itself as a security release with a line or heading that starts with "Security" (for example
+ * "## Security" or "- **Security fix.**"), not by mentioning the word ("no security changes"). */
+export function isSecurityRelease(notes) {
+    return /^\s*(?:#{1,6}\s*|[-*]\s*(?:\*\*)?)?security\b/im.test(notes);
+}
+/** a > b for dotted versions; a pre-release sorts before its release. */
+export function isNewer(a, b) {
+    const parse = (value) => {
+        const [core = "", pre] = value.replace(/^v/, "").split("-", 2);
+        return { parts: core.split(".").map(part => Number.parseInt(part, 10) || 0), pre: pre ?? null };
+    };
+    const left = parse(a), right = parse(b);
+    for (let index = 0; index < 3; index++) {
+        const diff = (left.parts[index] ?? 0) - (right.parts[index] ?? 0);
+        if (diff !== 0)
+            return diff > 0;
+    }
+    if (left.pre === right.pre)
+        return false;
+    if (left.pre === null)
+        return true;
+    if (right.pre === null)
+        return false;
+    return left.pre.localeCompare(right.pre, "en", { numeric: true }) > 0;
+}
+/** The release worth mentioning: newer than `current`, else null. */
+export function newerRelease(release, current) {
+    return release !== null && isNewer(release.version, current) ? release : null;
+}
+/** The one status line, only when a newer release exists. */
+export function updateLine(release, current, updateCommand) {
+    const newer = newerRelease(release, current);
+    return newer === null ? null : `${newer.version} is available — ${updateCommand} · ${newer.url}`;
+}
+/**
+ * A security release tells each instance operator once per version, through
+ * the outbox and addressed to them (like a sign-in pause): only someone at
+ * this computer can update it. Returns how many messages were queued.
+ */
+export function notifySecurityRelease(store, release, current, updateCommand, now) {
+    const newer = newerRelease(release, current);
+    if (newer === null || !newer.security)
+        return 0;
+    const operators = store.accountFacts().map(one => one.name).filter(name => store.isInstanceOperator(name));
+    let queued = 0;
+    for (const recipient of operators) {
+        const added = store.enqueueNotification({
+            dedupeKey: `release:security:${newer.version}:${recipient}`,
+            kind: "security-release",
+            pushClass: "attention",
+            link: "/settings#updates",
+            subject: `Toolroll ${newer.version} is a security release`,
+            body: `This computer runs ${current}. Update with \`${updateCommand}\`. Notes: ${newer.url}`,
+            recipient,
+            source: { installation: true },
+        }, now);
+        if (added)
+            queued++;
+    }
+    return queued;
+}
+export function recordRunnerVersion(dir, runner, version, now) {
+    const known = runnerVersions(dir).filter(one => one.runner !== runner);
+    known.push({ runner, version, at: now.toISOString() });
+    try {
+        writeAtomic(join(dir, RUNNER_VERSIONS_FILE), `${JSON.stringify(known.sort((a, b) => a.runner.localeCompare(b.runner)))}\n`);
+    }
+    catch {
+        // The version is a display fact; a failed write only leaves it unknown.
+    }
+}
+export function runnerVersions(dir) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(dir, RUNNER_VERSIONS_FILE), "utf8"));
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter((one) => typeof one === "object" && one !== null
+            && typeof one.runner === "string" && typeof one.version === "string" && VERSION.test(one.version) && typeof one.at === "string");
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * The console's background check: at start and then hourly (the daily limit
+ * is latestRelease's own), and a security release notifies operators.
+ */
+export function startUpdateChecks(store, dir, current, updateCommand, io = {}) {
+    let stopped = false;
+    const pass = async () => {
+        const release = await latestRelease(dir, io);
+        if (!stopped) {
+            try {
+                notifySecurityRelease(store, release, current, updateCommand, (io.now ?? (() => new Date()))());
+            }
+            catch {
+                // A closed store at shutdown: nothing to tell.
+            }
+        }
+    };
+    void pass();
+    const timer = setInterval(() => void pass(), io.everyMs ?? 60 * 60_000);
+    timer.unref?.();
+    return () => { stopped = true; clearInterval(timer); };
+}
+async function askVersion(request) {
+    const answer = await request(REGISTRY_URL, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(CHECK_TIMEOUT_MS), credentials: "omit", referrerPolicy: "no-referrer" });
+    if (!answer.ok)
+        return null;
+    const version = (await answer.json()).version;
+    return typeof version === "string" && VERSION.test(version) ? version : null;
+}
+async function askNotes(request, version) {
+    try {
+        const answer = await request(`${NOTES_API}v${version}`, { headers: { accept: "application/vnd.github+json" }, signal: AbortSignal.timeout(CHECK_TIMEOUT_MS), credentials: "omit", referrerPolicy: "no-referrer" });
+        if (!answer.ok)
+            return "";
+        const body = (await answer.json()).body;
+        return typeof body === "string" ? body.replace(/\r\n/g, "\n").slice(0, NOTES_MAX) : "";
+    }
+    catch {
+        return "";
+    }
+}
+function readCache(dir) {
+    const file = join(dir, RELEASE_CACHE_FILE);
+    if (!existsSync(file))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        if (typeof parsed.checkedAt !== "string" || Number.isNaN(Date.parse(parsed.checkedAt)))
+            return null;
+        const release = parsed.release;
+        const valid = release !== null && typeof release === "object" && release !== undefined
+            && typeof release.version === "string" && VERSION.test(release.version) && typeof release.notes === "string";
+        return { checkedAt: parsed.checkedAt, release: valid ? { version: release.version, notes: release.notes, url: `${RELEASES_PAGE}v${release.version}`, security: isSecurityRelease(release.notes) } : null };
+    }
+    catch {
+        return null;
+    }
+}
+function writeAtomic(file, content) {
+    const temporary = `${file}.${process.pid}.tmp`;
+    writeFileSync(temporary, content, { mode: 0o600 });
+    renameSync(temporary, file);
+}

package/dist/serve.d.ts

@@ -14,6 +14,8 @@ import { type Phase } from "./provider.js";
 import type { RevisionLineage } from "./store.js";
 import type { SubscriptionMateRunner } from "./subscription-chat.js";
 export type ServeOptions = {
+    /** Tests: the bin whose real path says how Toolroll was installed (Settings → Updates' command). */
+    installBin?: string;
     /** Native coding workspace injection for isolated integration tests. */
     codingWorkspace?: CodingWorkspace;
     store: Store;
@@ -183,6 +185,8 @@ export type RouteView = {
      * The form offers these and nothing else. */
     choices: Record<Phase, AgentChoice[]>;
 };
+/** The page CSS this module writes itself (not the imported modules'), for the stylesheet contract tests. */
+export declare const PAGE_CSS: string;
 /**
  * The sensitivity classifier (arc 4, findings 3/17): a body showing a
  * password input renders WITHOUT the chrome additions (palette, overlay,