toolroll 0.6.0 → 0.7.0

package/dist/browser-workspace.d.ts

@@ -241,6 +241,31 @@ export type BrowserSettingsView = {
             redirect: string | null;
         };
     } | null;
+    /** Settings → Updates: this version, the latest known one and its notes, how to update, the daily-check switch, and each worker's version. */
+    updates?: BrowserUpdates | null;
+};
+export type BrowserUpdates = {
+    current: string;
+    /** The latest release the last check found; null before any check has worked. */
+    latest: {
+        version: string;
+        newer: boolean;
+        security: boolean;
+        notes: string;
+        url: string;
+    } | null;
+    updateCommand: string;
+    /** The daily check: off by TOOLROLL_NO_UPDATE_CHECK (byEnv) or by this switch; only an operator may flip it. */
+    check: {
+        on: boolean;
+        byEnv: boolean;
+        canManage: boolean;
+    };
+    workers: {
+        name: string;
+        version: string | null;
+        older: boolean;
+    }[];
 };
 /** A fold on the task page. Its HTML is the server's own section body, so
  * forms, ids and page scripts are unchanged. */
@@ -756,6 +781,15 @@ export type BrowserWorkspace = {
     refreshSeconds?: number;
     /** Providers whose sign-in stopped working: their work waits (one per provider). */
     signIn?: BrowserSignIn[];
+    /** A newer Toolroll exists: a quiet notice for an operator, until they dismiss this version. */
+    update?: BrowserUpdateNotice;
+};
+/** The console's update notice: neutral, never the accent — an update does not need a person. */
+export type BrowserUpdateNotice = {
+    version: string;
+    security: boolean;
+    href: string;
+    dismissHref: string;
 };
 /** A provider's sign-in pause, as the console shows it: the plain reason,
  * what to run, and the one action that resumes its work. */

package/dist/desktop-update.d.ts

@@ -65,6 +65,7 @@ export declare function prepareDesktopUpdate(stateDir: string, installed: string
 export declare function sqliteLock(file: string, busyTimeoutMs?: number): DatabaseSync | null;
 export declare const installationLock: (j: UpdateJournal) => DatabaseSync | null;
 export declare function desktopUpdateStatus(stateDir: string): {
+    version?: never;
     active: boolean;
     phase: string;
     detail: string;
@@ -78,7 +79,6 @@ export declare function desktopUpdateStatus(stateDir: string): {
     wasRunning?: never;
     backupPath?: never;
     updateId?: never;
-    version?: never;
     buildId?: never;
     workDir?: never;
 } | {

package/dist/install-method.d.ts

@@ -0,0 +1,17 @@
+/**
+ * How this Toolroll was installed, read from where its bin really lives, and
+ * the one command that updates it that way. Only the path is read: nothing is
+ * run and nothing leaves the computer.
+ */
+export type InstallKind = "npm" | "pnpm" | "bun" | "yarn" | "homebrew" | "npx" | "source";
+export type InstallMethod = {
+    kind: InstallKind;
+    updateCommand: string;
+};
+export declare const UPDATE_COMMANDS: Record<InstallKind, string>;
+export type InstallProbe = {
+    realpath?: (path: string) => string;
+    exists?: (path: string) => boolean;
+};
+/** The install method of the bin at `bin` (the running one by default). Unknown shapes read as npm, the common case. */
+export declare function installMethod(bin?: string | undefined, probe?: InstallProbe): InstallMethod;

package/dist/install-method.js

@@ -0,0 +1,61 @@
+/**
+ * How this Toolroll was installed, read from where its bin really lives, and
+ * the one command that updates it that way. Only the path is read: nothing is
+ * run and nothing leaves the computer.
+ */
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+export const UPDATE_COMMANDS = {
+    npm: "npm install -g toolroll@latest",
+    pnpm: "pnpm add -g toolroll@latest",
+    bun: "bun add -g toolroll@latest",
+    yarn: "yarn global add toolroll@latest",
+    homebrew: "brew upgrade ap9000/toolroll/toolroll",
+    npx: "npx toolroll@latest",
+    source: "git pull && npm install && npm run build",
+};
+/** The install method of the bin at `bin` (the running one by default). Unknown shapes read as npm, the common case. */
+export function installMethod(bin = process.argv[1], probe = {}) {
+    const kind = installKind(bin, probe);
+    return { kind, updateCommand: UPDATE_COMMANDS[kind] };
+}
+function installKind(bin, probe) {
+    if (bin === undefined || bin === "")
+        return "npm";
+    let real = bin;
+    try {
+        real = (probe.realpath ?? realpathSync)(bin);
+    }
+    catch {
+        // A bin that cannot be resolved is judged by the path it was run by.
+    }
+    const path = real.replace(/\\/g, "/");
+    // A plane deployed from a checkout by scripts/deploy-browser.mjs runs from staged-upgrades/browser-*: it updates
+    // by deploying from source, never from npm.
+    if (path.includes("/staged-upgrades/browser-"))
+        return "source";
+    if (/\/Cellar\/toolroll\//i.test(path))
+        return "homebrew";
+    if (path.includes("/_npx/"))
+        return "npx";
+    if (/\/\.bun\/install\/global\//.test(path))
+        return "bun";
+    if (/\/pnpm\/global\//i.test(path))
+        return "pnpm";
+    if (/\/(?:\.config\/yarn|yarn\/data)\/global\//i.test(path))
+        return "yarn";
+    if (path.includes("/node_modules/"))
+        return "npm";
+    // Not inside node_modules: a checkout, when the package's own folder is a git working copy.
+    const exists = probe.exists ?? existsSync;
+    let folder = dirname(real);
+    for (let depth = 0; depth < 4; depth++) {
+        if (exists(join(folder, "package.json")) && exists(join(folder, ".git")))
+            return "source";
+        const parent = dirname(folder);
+        if (parent === folder)
+            break;
+        folder = parent;
+    }
+    return "npm";
+}

package/dist/operate.d.ts

@@ -6,6 +6,7 @@ import { type TelegramTransport } from "./telegram.js";
 import { type MateCliSeams } from "./mate-cli.js";
 import { type PublishExec } from "./publish.js";
 import { type Runner as CommandRunner } from "./builder.js";
+import { type ReleaseIo } from "./releases.js";
 export type Write = (line: string) => void;
 /**
  * 0 done · 1 broke · 2 bad usage · 3 ran fine, the answer is no.
@@ -33,6 +34,10 @@ export type OperateOptions = {
     additionalProjectRepos?: () => readonly string[];
     /** Overridden by tests and by an agent that wants its own queue. */
     databaseFile?: string;
+    /** Injected by tests: how `status` and the console ask for the latest release. */
+    releaseIo?: ReleaseIo;
+    /** Injected by tests: the bin whose real path says how Toolroll was installed. */
+    installBin?: string;
     openDatabase?: (file: string) => Store;
     now?: Date;
     /**

package/dist/operate.js

@@ -181,6 +181,9 @@ import { updateAdmissionPaused, UPDATE_PAUSED } from "./desktop-update-gate.js";
 import { beads } from "./beads.js";
 import { githubIssues } from "./issues.js";
 import { installationStatus, renderInstallationStatus, renderTaskWait, taskWaitSnapshot } from "./lead-status.js";
+import { latestRelease, newerRelease, notifySecurityRelease, recordRunnerVersion, startUpdateChecks, updateLine } from "./releases.js";
+import { installMethod } from "./install-method.js";
+import { PACKAGE_VERSION } from "./version.js";
 /**
  * 0 done · 1 broke · 2 bad usage · 3 ran fine, the answer is no.
  *
@@ -720,6 +723,8 @@ export async function runOperate(command, argv, write, options = {}) {
             ...(options.mateSeams === undefined ? {} : { mateSeams: options.mateSeams }),
             ...(options.heldCoordinator === undefined ? {} : { heldCoordinator: options.heldCoordinator }),
             ...(options.waitSleep === undefined ? {} : { waitSleep: options.waitSleep }),
+            ...(options.releaseIo === undefined ? {} : { releaseIo: options.releaseIo }),
+            ...(options.installBin === undefined ? {} : { installBin: options.installBin }),
         });
     }
     catch (error) {
@@ -2127,10 +2132,10 @@ async function tickCommand(flags, context) {
                 continue;
             }
             // The sign-in pause holds a resumed lane too: it waits, parked, instead of failing.
-            const laneSignedOut = signInGate(store, [racer.provider], clock());
-            if (laneSignedOut !== null) {
+            const laneGate = signInGate(store, [racer.provider], clock());
+            if (laneGate.waiting !== null) {
                 backToParked();
-                resumed.push({ id: taskId, outcome: "skipped", reason: "signed-out", detail: signInWords(laneSignedOut) });
+                resumed.push({ id: taskId, outcome: "skipped", reason: "signed-out", detail: signInWords(laneGate.waiting) });
                 continue;
             }
             // Legacy comparison lanes carried an absolute clock. New profiles use
@@ -2139,6 +2144,7 @@ async function tickCommand(flags, context) {
             // wall-clock contract.
             const remaining = waiting.kind === "comparison" ? null : racer.budgetMicrousd - racer.accountedMicrousd;
             if (remaining !== null && remaining <= 0) {
+                laneGate.giveBack();
                 const current = store.getContestant(racer.id);
                 if (current !== null)
                     store.casContestantState(racer.id, ["ready"], "stopped", current.generation);
@@ -2150,6 +2156,7 @@ async function tickCommand(flags, context) {
                 const laneProfile = racer.profile ?? contestantProfileOf(racer.provider, racer.model, racer.repairModel);
                 const clockCapMs = 3 * laneProfile.timeoutSeconds * 1000;
                 if (laneProfile.timeoutKind !== "idle" && store.contestantCumulativeMs(racer.id) >= clockCapMs) {
+                    laneGate.giveBack();
                     const current = store.getContestant(racer.id);
                     if (current !== null)
                         store.casContestantState(racer.id, ["ready"], "stopped", current.generation);
@@ -2160,12 +2167,14 @@ async function tickCommand(flags, context) {
             }
             const reclaimed = acquire(store, waiting.taskRef, runner, { now: clock(), token, ttlMs: leaseTtlMs });
             if (!reclaimed.ok) {
+                laneGate.giveBack();
                 backToParked();
                 continue;
             }
             const freshContest = store.getContest(waiting.id);
             if (freshContest === null || !store.casContestState(waiting.id, ["decision-wait", "racing"], "racing", freshContest.generation)) {
                 release(store, reclaimed.claim.leaseId, clock());
+                laneGate.giveBack();
                 backToParked();
                 continue;
             }
@@ -2384,7 +2393,10 @@ async function tickCommand(flags, context) {
     // gateway re-checks freshly at spawn; this cache only keeps a skipped
     // queue from probing once per task.
     const attestedThisPass = new Map();
+    let untakenTrial = null;
     for (const ref of ready) {
+        untakenTrial?.giveBack();
+        untakenTrial = null;
         // The build budget governs UNATTENDED admissions (round-1 finding 4):
         // once it is spent, the pass keeps SCANNING for attended
         // authorizations — operator-invoked sessions launch regardless —
@@ -2601,11 +2613,14 @@ async function tickCommand(flags, context) {
         // One task every AUTH_TRIAL_MS goes ahead as the trial: a sign-in check
         // can say "logged in" for a session that cannot refresh, so a real run
         // decides — it lifts the pause, or fails into the same incident.
-        const signedOut = signInGate(store, modeProviders, clock(), ref.id);
-        if (signedOut !== null) {
-            dispatched.push({ id, outcome: "skipped", reason: "signed-out", detail: signInWords(signedOut) });
+        const gate = signInGate(store, modeProviders, clock(), ref.id);
+        if (gate.waiting !== null) {
+            dispatched.push({ id, outcome: "skipped", reason: "signed-out", detail: signInWords(gate.waiting) });
             continue;
         }
+        // A trial whose task is skipped before its claim succeeds is given back
+        // at the next task (or after the pass), so the next pass may take it.
+        untakenTrial = gate;
         // The leg is the authority: what resolved must BE the leg, exactly —
         // the sealed build leg, or the parked fallback entry's own pair.
         const governingLeg = wantsPlan ? planLeg : parkedEntry !== null ? { provider: parkedEntry.provider, model: parkedEntry.model, chosen: "fallback" } : sealedBuildLeg;
@@ -2772,6 +2787,8 @@ async function tickCommand(flags, context) {
                 ? {}
                 : { maxOpenDecisions: Number(text(flags, "max-open-decisions")) }),
         });
+        if (claimed.ok)
+            untakenTrial = null;
         if (!claimed.ok) {
             // Losing a race, finding the task no longer ready, and a machine that
             // lacks what the task needs are all the system working. None fails the
@@ -3732,6 +3749,7 @@ async function tickCommand(flags, context) {
                 break;
         }
     }
+    untakenTrial?.giveBack();
     // THE CHAIN ADMISSION PASS (E3d): cycles a recognized exhaustion advanced
     // to pending-admission dispatch their NEXT approved entry here — the ONLY
     // road that runs a fallback entry. Every authority is re-derived inside
@@ -3779,9 +3797,9 @@ async function tickCommand(flags, context) {
             continue;
         }
         // The sign-in pause holds a fallback entry too: the admission stays pending until its provider works.
-        const entrySignedOut = signInGate(store, [peek.profile.provider], clock(), pending.taskRef);
-        if (entrySignedOut !== null) {
-            dispatched.push({ id: pending.taskId, outcome: "skipped", reason: "signed-out", detail: signInWords(entrySignedOut) });
+        const entryGate = signInGate(store, [peek.profile.provider], clock(), pending.taskRef);
+        if (entryGate.waiting !== null) {
+            dispatched.push({ id: pending.taskId, outcome: "skipped", reason: "signed-out", detail: signInWords(entryGate.waiting) });
             continue;
         }
         // The FALLBACK claim (finding 4): every acquireIfReady gate — task
@@ -3806,6 +3824,7 @@ async function tickCommand(flags, context) {
                 : { maxOpenDecisions: Number(text(flags, "max-open-decisions")) }),
         });
         if (!claimed.ok) {
+            entryGate.giveBack();
             dispatched.push({ id: pending.taskId, outcome: "skipped", reason: claimed.reason });
             continue;
         }
@@ -3974,13 +3993,14 @@ async function tickCommand(flags, context) {
                 continue;
             }
             // The sign-in pause holds a continuation too: its authorization stays open and it starts once the sign-in works.
-            const continuationSignedOut = signInGate(store, [pinned.provider], clock(), parent.taskRef);
-            if (continuationSignedOut !== null) {
-                dispatched.push({ id: taskId, outcome: "skipped", reason: "signed-out", detail: signInWords(continuationSignedOut) });
+            const continuationGate = signInGate(store, [pinned.provider], clock(), parent.taskRef);
+            if (continuationGate.waiting !== null) {
+                dispatched.push({ id: taskId, outcome: "skipped", reason: "signed-out", detail: signInWords(continuationGate.waiting) });
                 continue;
             }
             const claimed = acquireContinuation(store, continuation, runner, { now: clock(), token, ttlMs: leaseTtlMs });
             if (!claimed.ok) {
+                continuationGate.giveBack();
                 dispatched.push({ id: taskId, outcome: "skipped", reason: claimed.reason, ...("message" in claimed ? { detail: claimed.message } : {}) });
                 continue;
             }
@@ -4683,6 +4703,8 @@ async function startConsole(options) {
     // Sprint 8: scheduled backups, a pass a minute; its lease also tells a restore that the console is running.
     server.on("close", startBackups(context.store, context.databaseFile));
     server.on("close", startCodexLimits(context.store));
+    // At most one anonymous look a day for a newer Toolroll (Settings → Updates can switch it off).
+    server.on("close", startUpdateChecks(context.store, dirname(context.databaseFile), PACKAGE_VERSION, installMethod(context.installBin).updateCommand, context.releaseIo ?? {}));
     const bound = server.address();
     const port = typeof bound === "object" && bound !== null ? bound.port : options.port;
     // A bind-everywhere address is not a place a browser can go: the URL
@@ -7075,6 +7097,7 @@ async function runWatchLoop(args) {
     // attributes to this episode by runner and window, and `brief
     // --latest-watch` bounds itself to exactly it.
     store.startWatchEpisode({ repo, runner, incarnation }, new Date());
+    recordRunnerVersion(dirname(context.databaseFile), runner, PACKAGE_VERSION, new Date());
     args.onReady?.();
     // A false renewal is FATAL (arc 2 finding 15): the lease or the
     // credential is gone, and admitting one more pass would be work done for
@@ -8064,6 +8087,7 @@ async function upCommand(flags, context) {
         });
     };
     observeReadiness();
+    recordRunnerVersion(dirname(context.databaseFile), runnerName, PACKAGE_VERSION, clock());
     const runnerHeartbeat = setInterval(() => {
         const beat = heartbeatRunner(store, runnerName, runnerToken, clock());
         if (!beat.ok && !stopping) {
@@ -8949,7 +8973,7 @@ function readPaths(flags, backend) {
     return backend === BUILT_IN ? [BUILT_IN] : [];
 }
 // ---- authoring ------------------------------------------------------------
-function statusCommand(positional, flags, context) {
+async function statusCommand(positional, flags, context) {
     const command = "status";
     const allowed = new Set(["db", "json"]);
     for (const name of flags.keys()) {
@@ -8959,7 +8983,15 @@ function statusCommand(positional, flags, context) {
     if (positional.length > 0)
         return fail(context.write, context.json, command, "usage", "Use `toolroll status [--json]`.", EXIT.usage);
     const status = installationStatus(context.store, context.clock());
-    return succeed(context.write, context.json, command, { ...status }, () => renderInstallationStatus(status));
+    // One line, only when a newer Toolroll exists; offline or switched off says nothing.
+    const current = PACKAGE_VERSION;
+    const method = installMethod(context.installBin);
+    const release = newerRelease(await latestRelease(dirname(context.databaseFile), { now: context.clock, ...context.releaseIo }), current);
+    if (release !== null)
+        notifySecurityRelease(context.store, release, current, method.updateCommand, context.clock());
+    const line = updateLine(release, current, method.updateCommand);
+    const update = release === null ? {} : { update: { current, latest: release.version, security: release.security, updateCommand: method.updateCommand, url: release.url } };
+    return succeed(context.write, context.json, command, { ...status, ...update }, () => [...renderInstallationStatus(status), ...(line === null ? [] : [line])]);
 }
 async function waitTask(positional, flags, context) {
     const command = "task wait";

package/dist/provider-auth.d.ts

@@ -38,7 +38,17 @@ export declare function signInCommand(pause: Pick<AuthPause, "provider" | "authM
 export declare function signInWords(pause: AuthPause): string;
 /** The open pause for a provider, or null. */
 export declare function authPauseOf(store: Store, provider: string): AuthPause | null;
-/** The open pause the dispatch gate last left this task waiting on, or null. */
+/**
+ * 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 declare function pauseOnTaskProviders(pause: string, taskRef: string): string;
+/** 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 declare function authWaitOf(store: Store, taskRef: number): AuthPause | null;
 /** Every open pause, oldest first. */
 export declare function openAuthPauses(store: Store): AuthPause[];
@@ -80,22 +90,37 @@ export declare function noteSignInProbe(store: Store, provider: string, state: s
 } | null;
 /** How often a paused provider lets one task through as a trial. */
 export declare const AUTH_TRIAL_MS: number;
+/** A trial taken: the pause, when it was taken, and the trial time it replaced. */
+export type AuthTrial = {
+    pauseId: number;
+    takenAt: string;
+    previous: string | null;
+};
 /**
  * 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.
+ * incident, so nobody is told twice. Null when no trial is due.
  */
-export declare function claimAuthTrial(store: Store, pause: AuthPause, now: Date): boolean;
+export declare function claimAuthTrial(store: Store, pause: AuthPause, now: Date): AuthTrial | null;
+/** Give a trial back when its task never started (its claim failed), so the next pass may take it. */
+export declare function giveBackAuthTrial(store: Store, trial: AuthTrial): void;
+/** What the sign-in gate decided: the open pause the work waits on, or null
+ * when it may go ahead; and, when it goes ahead as a pause's trial, how to
+ * give that trial back if its claim then fails. */
+export type SignInGate = {
+    waiting: AuthPause | null;
+    giveBack: () => void;
+};
 /**
  * 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). The open pause the work waits
- * on, or null when it may go ahead — nothing paused, or 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.
+ * 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 declare function signInGate(store: Store, providers: readonly string[], now: Date, taskRef?: number): AuthPause | null;
+export declare function signInGate(store: Store, providers: readonly string[], now: Date, taskRef?: number): SignInGate;
 /** 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. */

package/dist/provider-auth.js

@@ -69,10 +69,31 @@ 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);
 }
-/** The open pause the dispatch gate last left this task waiting on, or null. */
+/**
+ * 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`).get(taskRef);
+    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. */
@@ -186,29 +207,49 @@ 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.
+ * incident, so nobody is told twice. Null when no trial is due.
  */
 export function claimAuthTrial(store, pause, now) {
-    const due = new Date(now.getTime() - AUTH_TRIAL_MS).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(now.toISOString(), pause.id, due);
-    return Number(claimed.changes) === 1;
+    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). The open pause the work waits
- * on, or null when it may go ahead — nothing paused, or 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.
+ * 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 waiting = pause !== null && !claimAuthTrial(store, pause, now) ? pause : 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);
     }
-    return waiting;
+    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

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;