toolroll 0.6.0 → 0.8.0

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,85 @@
+/**
+ * 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;
+/** The npm registry `toolroll update` downloads releases from. */
+export declare const REGISTRY = "https://registry.npmjs.org";
+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;
+/** The latest version, asked of npm now: for an explicit update (the command, Check now), not the once-a-day
+ * notice, so neither its cache nor its switch applies. Throws with npm's own reason. */
+export declare function latestVersionNow(io?: {
+    fetch?: typeof fetch;
+}): Promise<{
+    version: string;
+}>;

package/dist/releases.js

@@ -0,0 +1,238 @@
+/**
+ * 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;
+/** The npm registry `toolroll update` downloads releases from. */
+export const REGISTRY = "https://registry.npmjs.org";
+export const REGISTRY_URL = `${REGISTRY}/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);
+}
+/** The latest version, asked of npm now: for an explicit update (the command, Check now), not the once-a-day
+ * notice, so neither its cache nor its switch applies. Throws with npm's own reason. */
+export async function latestVersionNow(io = {}) {
+    const answer = await (io.fetch ?? fetch)(REGISTRY_URL, { signal: AbortSignal.timeout(10_000), headers: { accept: "application/json" } });
+    if (!answer.ok)
+        throw new Error(`npm answered ${answer.status}`);
+    const version = (await answer.json()).version;
+    if (typeof version !== "string" || !/^\d+\.\d+\.\d+$/.test(version))
+        throw new Error("npm did not name a version");
+    return { version };
+}

package/dist/serve.d.ts

@@ -11,9 +11,13 @@ import { run as execRun } from "./exec.js";
 import { type AgentChoice } from "./agentconfig.js";
 import { type RouteProjection, type RouteOverride, type RouteStamp, type RiskLevel } from "./phase-routing.js";
 import { type Phase } from "./provider.js";
+import { launchRuntimeUpdate } from "./toolroll-update.js";
 import type { RevisionLineage } from "./store.js";
 import type { SubscriptionMateRunner } from "./subscription-chat.js";
+import { type InstallMethod } from "./install-method.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;
@@ -51,6 +55,18 @@ export type ServeOptions = {
     configDir?: string;
     /** Test seam for the Slack setup handshake. */
     slackFetcher?: typeof fetch;
+    /** Settings → Updates seams: the latest release, how this Toolroll was
+     * installed, its version, and how the updater job starts. Tests and
+     * screenshots inject these; production reads the registry and launchd. */
+    updates?: {
+        latest?: () => Promise<{
+            version: string;
+        }>;
+        method?: InstallMethod;
+        current?: string;
+        dist?: string;
+        launch?: typeof launchRuntimeUpdate;
+    };
     discordFetcher?: typeof fetch;
     /** Injected by tests: Microsoft sign-in, key metadata and Teams conversation calls. */
     teamsFetcher?: typeof fetch;
@@ -105,6 +121,8 @@ export type ServeOptions = {
     additionalProjectRepos?: () => readonly string[];
     connectionProbe?: typeof execRun;
     connectionHome?: string;
+    /** Test seam for Chat's first tasks: the `gh` and `git grep` reads. */
+    firstTaskRunner?: typeof execRun;
     modelCatalogFetcher?: typeof fetch;
     /** Test seams for Settings → Models: CLI version probes and the PATH they search. */
     modelRunner?: VersionRunner;