toolroll 0.7.0 → 0.8.1

package/dist/serve.js

@@ -125,7 +125,6 @@ import { openRouterModelsCache, openRouterPickerScript } from "./openrouter-mode
 import { checkModels, isNewModel, livePin, modelOptions, modelWords, RUNTIME_TOOLS, runtimeStates, seenModels, setWatch, updateRuntime, watchState } from "./model-catalog.js";
 import { MODELS_CSS, modelsHtml, modelsScript } from "./models-ui.js";
 import { ASSISTANTS, modelChoices, detectPreparation, previewProjectInstructions, addProjectInstructions } from "./setup-guide.js";
-import { projectSkillInstalled } from "./skills.js";
 import { previewSetup, approveSetup } from "./control-setup.js";
 import { controlSetupHtml, setupPreviewHtml, connectionHtml, connectionWords, hiddenFields } from "./control-ui.js";
 import { composerSchedule, scheduleEditorHtml, scheduleEditorScript } from "./task-composer.js";
@@ -171,6 +170,7 @@ import { parseGithubRepo, previewGithubRepo, cloneGithubRepo, listGithubRepos, i
 import { verifiedAuthor, LEAD_THREAD } from "./store.js";
 import { updateRepos, addRepos, removeRepos } from "./repos.js";
 import { run as execRun } from "./exec.js";
+import { findFirstTasks, firstResultWords, firstRunSteps, firstTaskSuggestions, SANDBOX_COMMAND } from "./first-run.js";
 /** A user agent, reduced to safe display words — never echoed raw. */
 function oneLineUa(raw) {
     const text = Array.isArray(raw) ? (raw[0] ?? "") : (raw ?? "");
@@ -206,6 +206,9 @@ import { BACKUP_EVERY_HOURS, MAX_KEEP, backupFolderOf, backupNow, checkBackupFol
 import { prometheusMetrics } from "./metrics.js";
 import { SPEND_CSS, spendCsv, spendHtml } from "./spend-ui.js";
 import { RETENTION_CSS, retentionHtml } from "./retention-ui.js";
+import { UPDATES_CSS, newerThan, updateStepsHtml, updatesHtml, updatesScript } from "./toolroll-update-ui.js";
+import { abandonRuntimeUpdate, launchRuntimeUpdate, markWhatsNewSeen, prepareRuntimeUpdate, requestRuntimeUpdateCancel, runningWorkWords, runtimeUpdateStatus, runtimeUpdateTerminal, currentRuntime } from "./toolroll-update.js";
+import { latestVersionNow } from "./releases.js";
 import { RETENTION_KINDS, lastSweepAt, parsePeriod, retentionPlan } from "./retention.js";
 import { EXPORT_CSS, dataExportHtml } from "./export-ui.js";
 import { buildExport, exportZip } from "./export.js";
@@ -1880,7 +1883,7 @@ export function createDecisionServer(options) {
                 })),
                 cancelledBlockers: cancelled,
                 gaps: project === null ? [] : computeGaps(store, project, now).filter(gap => gap.unblocks.length > 0).slice(0, 10),
-                wizard: wizardSteps(now),
+                wizard: firstRunStepsNow(now),
                 worker: (() => {
                     // The one fact the inbox must never hide (install review): with
                     // no worker answering, nothing here will ever build, and every
@@ -3373,10 +3376,13 @@ export function createDecisionServer(options) {
                     // A failed briefing query must not make the conversation vanish.
                 }
             }
+            // The first run belongs to the lead conversation, for someone who can act on it.
+            const firstRun = focusTask === null && who.role === "approver" ? chatFirstRun(now, chatProject) : undefined;
+            const withFirstRun = (shown) => firstRun === undefined ? shown : { ...shown, workspace: { ...shown.workspace, firstRun } };
             if (enabled.ok && mateSession !== null && principal !== null && !ceilingStale) {
                 {
                     const said = takeMateNote(who.session.csrf, mateSession.id);
-                    return sendScreen(response, 200, matePage(chromeFor(null, "chat", undefined, "all"), {
+                    return sendScreen(response, 200, withFirstRun(matePage(chromeFor(null, "chat", undefined, "all"), {
                         session: mateSession,
                         ...mateConversationRows(who, principal, focusTask, now, chatProject),
                         chatProject,
@@ -3394,10 +3400,10 @@ export function createDecisionServer(options) {
                         now,
                         resultPanel,
                         resultRunId: resultRun?.id ?? null,
-                    }));
+                    })));
                 }
             }
-            return sendScreen(response, 200, chatPage(chromeFor(null, "chat", undefined, "all"), {
+            return sendScreen(response, 200, withFirstRun(chatPage(chromeFor(null, "chat", undefined, "all"), {
                 settingsOpen: settingsView,
                 enabled,
                 pending,
@@ -3430,7 +3436,7 @@ export function createDecisionServer(options) {
                 resultPanel,
                 ...(enabled.ok && who.role === "approver" ? { mateMint: mateMintCard(who.session.csrf, enabled, focusTask === null ? "/chat" : taskChatHref(focusTask.id)) } : {}),
                 ...(who.role === "approver" ? { coordinatorProposals: coordinatorProposalsSection(coordinatorRows, decisionsFor(store, coordinatorRows), who.session.csrf, now, true, focusTask === null ? null : taskChatHref(focusTask.id)) } : {}),
-            }));
+            })));
         }
         const chatAck = /^\/chat\/ack\/([0-9]{1,15})$/.exec(url.pathname);
         if (chatAck !== null) {
@@ -3617,6 +3623,21 @@ export function createDecisionServer(options) {
             const view = { settings: readMonitoring(options.configDir), status: store.monitoringStatus(), head: store.ledgerHeadId(), origin: consoleOrigin(request.headers.host) };
             return sendScreen(response, 200, screen("Monitoring", `<p><a href="/settings">Settings</a></p><h1>Monitoring</h1>${monitoringHtml(view, who.session.csrf, { said: url.searchParams.get("said"), problem: url.searchParams.get("problem") })}`, { chrome: chromeFor(project, "settings") }));
         }
+        // Settings → Updates: the installed version, three ways to update, the update's steps live, then What's new. An instance operator's page.
+        if (url.pathname === "/settings/updates") {
+            const databaseFile = store.databaseFile();
+            if (who.via !== "cookie" || !store.isInstanceOperator(who.name) || databaseFile === null)
+                return refuse(response, who, 403, "An instance operator updates Toolroll.", "/settings");
+            const status = runtimeUpdateStatus(dirname(databaseFile));
+            if (url.searchParams.get("fragment") === "steps")
+                return respond(response, 200, "text/html; charset=utf-8", status.journal ? updateStepsHtml(status.journal, status.running) : `<div id="update-live" data-done="1"></div>`);
+            const active = status.journal !== null && !runtimeUpdateTerminal(status.journal.phase);
+            const current = options.updates?.current ?? PACKAGE_VERSION;
+            // While update checks are off the page asks npm nothing until Check now.
+            const checksOff = updateChecksOff(process.env, options.configDir ?? dirname(databaseFile)).off && url.searchParams.get("check") !== "now";
+            const view = { current, latest: active ? { version: current } : checksOff ? { off: true } : await latestReleaseFor(options.updates?.latest), method: options.updates?.method ?? installMethod(), journal: status.journal, running: status.running, whatsNew: status.whatsNew, csrf: who.session.csrf };
+            return sendScreen(response, 200, screen("Updates", `<p><a href="/settings">Settings</a></p><h1>Updates</h1>${updatesHtml(view, { said: url.searchParams.get("said"), problem: url.searchParams.get("problem") })}`, { chrome: chromeFor(project, "settings"), ...(active ? { functional: { script: updatesScript(), fetches: true } } : {}) }));
+        }
         // v105: Settings → Retention, how long each kind of data is kept. An instance operator's page.
         if (url.pathname === "/settings/retention") {
             if (who.via !== "cookie" || !store.isInstanceOperator(who.name))
@@ -3794,7 +3815,11 @@ export function createDecisionServer(options) {
                 const googleView = { connected: googleConnected(options.configDir ?? null)?.address ?? null, clientId: google?.clientId ?? "", redirect: origin === null ? null : `${origin}${GOOGLE_CALLBACK}` };
                 return email === null ? { set: false, host: "", port: 587, secure: false, user: "", from: "", imapHost: "", imapPort: 993, google: googleView }
                     : { set: true, host: email.host, port: email.port, secure: email.secure, user: email.user, from: email.from, imapHost: email.imap?.host ?? "", imapPort: email.imap?.port ?? 993, google: googleView };
-            })() : null, telegramDeliveryWords(store, loadBotToken(process.env, options.telegramTokenFile)), settingsWorkers(store, now), settingsUpdates(who.name, csrf)));
+            })() : null, telegramDeliveryWords(store, loadBotToken(process.env, options.telegramTokenFile)), settingsWorkers(store, now), settingsUpdates(who.name, csrf), (() => {
+                // The installation fact: when the first Ready result arrived, measured from the first account.
+                const at = store.firstSuccessAt(now), since = store.installationStartedAt();
+                return at === null || since === null ? null : firstResultWords(since, at);
+            })()));
         }
         if (url.pathname === "/push/key") {
             // Session-gated: the key is not secret, but strangers get nothing.
@@ -3834,62 +3859,72 @@ export function createDecisionServer(options) {
         return refuse(response, who, 404, "There's no page at this address.", "/chat");
     }
     /**
-     * The first-run checklist (adoption track, step 3) — derived from live
-     * state on every render, never a stored cursor, and retired PERMANENTLY
-     * by the first-success installation fact (Codex adoption review,
-     * finding 14). Every step is either something this console already has
-     * authority for, or the exact command where the CLI owns the act — the
-     * checklist instructs, it never gains authority (finding e).
+     * The first run (adoption track, step 3): three plain steps derived from
+     * live state on every render, never a stored cursor, and retired
+     * PERMANENTLY by the first-success installation fact (Codex adoption
+     * review, finding 14). Each step is either something this console can do,
+     * or the exact command where only the CLI can (finding e).
      */
-    function wizardSteps(now) {
-        if (restricted() || store.firstSuccessAt(now) !== null)
+    function firstRunStepsNow(now) {
+        if (restricted() || store.isDemo() || store.firstSuccessAt(now) !== null)
             return null;
-        const repos = admissionList() ?? [];
-        const setupDone = repos.filter(one => store.liveWorktreeSetup(one) !== null).length;
-        const skillDone = repos.filter(projectSkillInstalled).length;
-        const counted = (done) => repos.length <= 1 ? "" : ` (${done} of ${repos.length} repos)`;
-        return [
-            {
-                done: !unscopedMode,
-                title: "name what this console may see",
-                detail: unscopedMode
-                    ? `no ceiling is configured — this server currently shows everything. Restart it naming the repos: <code>toolroll serve --repo &lt;path&gt; --port …</code>`
-                    : repos.length === 0
-                        ? `the ceiling is configured but empty — no repository is visible here`
-                        : `ceiling: ${repos.map(one => escape(projectName(one))).join(", ")}`,
-            },
-            {
-                // A fact about THIS DATABASE only: binaries and authentication live
-                // on the worker's machine, which may not be this one — the console
-                // never claims to have checked them (finding 15).
-                done: store.hasPhaseConfig(),
-                title: "route the spend to a provider",
-                detail: store.hasPhaseConfig()
-                    ? `spend routing is configured in this database. Binary and authentication facts stay machine-side: run <code>toolroll providers</code> where the workers run`
-                    : `nothing routes builds to a provider yet: <code>toolroll config set build --provider claude --as &lt;you&gt; --token &lt;t&gt;</code> — then check <code>toolroll providers</code> on the worker's machine (installed, configured, historically-successful, and authenticated are four separate facts there)`,
-            },
-            {
-                done: repos.length > 0 && setupDone === repos.length,
-                title: "say how a fresh checkout gets ready",
-                detail: setupDone > 0
-                    ? `setup command set${counted(setupDone)}`
-                    : `agents build in throwaway workspaces; give them the preparation step: <code>toolroll setup set --repo &lt;path&gt; --command "npm ci"</code>`,
-            },
-            {
-                done: repos.length > 0 && skillDone === repos.length,
-                title: "teach the repo's agents this queue exists",
-                detail: skillDone > 0
-                    ? `skill installed${counted(skillDone)}`
-                    : `<code>toolroll skills install --repo &lt;path&gt;</code> previews; add <code>--yes</code> to write the skill file`,
-            },
-            {
-                done: store.hasAnyWork(),
-                title: "file the first standing order",
-                detail: store.hasAnyWork()
-                    ? `work is filed — approve its scope and the machine takes it from there`
-                    : `start from a template below, capture a one-off task underneath, or browse <a href="/routines">routines</a>`,
-            },
-        ];
+        return firstRunSteps({ agentSignedIn: agentSignedIn(now), projects: managedRepos().length, hasTask: store.hasAnyWork(), firstResultAt: null });
+    }
+    /**
+     * Whether a coding agent is signed in where the work runs. This machine's
+     * own checks (the ones Settings makes) speak only for a worker on this
+     * machine; a worker elsewhere speaks through its own readiness report, and
+     * the console never claims to have checked that machine (finding 15).
+     * Nothing here waits on a probe: this machine's answer is the last one
+     * seen, refreshed in the background.
+     */
+    function agentSignedIn(now) {
+        const here = hostname();
+        const workers = store.listRunners().filter(one => one.retiredAt === null && runnerAlive(one, now));
+        if ((options.localRunner !== undefined || workers.some(one => one.host === here)) && localAgentSignedIn())
+            return true;
+        return workers.some(one => one.host !== here && store.providerReadiness(one.name).some(seen => seen.state === "ready"));
+    }
+    let localSignIn = null;
+    let localSignInChecking = false;
+    function localAgentSignedIn() {
+        if (!localSignInChecking && (localSignIn === null || Date.now() - localSignIn.at > 30_000)) {
+            localSignInChecking = true;
+            void Promise.all(["claude", "codex"].map(one => connectionCheck(one).then(value => value.state, () => "unverified")))
+                .then(states => { localSignIn = { at: Date.now(), signedIn: states.some(state => state === "connected" || state === "key-works" || state === "key-present") }; })
+                .catch(() => { })
+                .finally(() => { localSignInChecking = false; });
+        }
+        return localSignIn?.signedIn ?? false;
+    }
+    /** First tasks per project: the last ones found (safe generic ones until then), re-read in the background at most
+     * every ten minutes. A render never waits on `gh` or `git grep`. */
+    const firstTasks = new Map();
+    function firstTasksFor(repo) {
+        const at = Date.now();
+        let entry = firstTasks.get(repo);
+        if (entry === undefined || (entry.until <= at && !entry.reading)) {
+            const reading = { until: at + 10 * 60_000, found: entry?.found ?? null, reading: true };
+            firstTasks.set(repo, reading);
+            entry = reading;
+            void findFirstTasks(repo, options.firstTaskRunner ?? execRun)
+                .then(found => { reading.found = found; }, () => { })
+                .finally(() => { reading.reading = false; });
+        }
+        return entry.found ?? firstTaskSuggestions({ issues: [], todos: [] });
+    }
+    /** Chat's first run: the steps, first tasks until the first task exists, and the sandbox while no agent is signed in. */
+    function chatFirstRun(now, project) {
+        const steps = firstRunStepsNow(now);
+        if (steps === null)
+            return undefined;
+        const taskFiled = steps.find(one => one.key === "task")?.done ?? true;
+        const repo = project ?? managedRepos()[0] ?? null;
+        return {
+            steps,
+            suggestions: taskFiled || repo === null ? [] : firstTasksFor(repo),
+            sandbox: steps.find(one => one.key === "agent")?.done === false ? SANDBOX_COMMAND : null,
+        };
     }
     // ---- fleet chat (v13) ----------------------------------------------------
     const chatFetcher = options.chatFetcher ?? fetch;
@@ -4473,6 +4508,7 @@ export function createDecisionServer(options) {
                 ...(s.refreshSeconds === undefined ? {} : { refreshSeconds: Math.max(5, Math.floor(s.refreshSeconds)) }),
                 ...(s.chrome.signIn === undefined ? {} : { signIn: s.chrome.signIn }),
                 ...(s.chrome.update === undefined ? {} : { update: s.chrome.update }),
+                ...(extras.firstRun === undefined ? {} : { firstRun: extras.firstRun }),
             };
             if (requestFacts.workspaceRead) {
                 const validator = requestFacts.workspaceValidator;
@@ -5808,8 +5844,8 @@ export function createDecisionServer(options) {
             }
             return redirect(response, safeReturn(body.get("return") ?? "/settings#updates"));
         }
-        // The daily check's switch: an installation setting, so an operator's.
-        if (url.pathname === "/settings/updates") {
+        // The daily check's switch: an installation setting, so an operator's. (Its own address: POST /settings/updates starts an update.)
+        if (url.pathname === "/settings/updates/checks") {
             if (options.configDir === undefined)
                 return refuse(response, who, 404, "Updates are not set up on this console.", "/settings");
             if (!store.isInstanceOperator(who.name))
@@ -6522,6 +6558,52 @@ export function createDecisionServer(options) {
             store.recordAction({ at: now.toISOString(), actor: who.name, repo: null, taskId: null, runId: null, action: before === null ? "sign-in with a provider turned on" : "sign-in with a provider changed", outcome: "changed", source: "policy", detail: ssoChangeWords(before, saved.settings) });
             return found.ok ? back("said", `Saved. People can sign in with ${saved.settings.label}.`) : back("problem", `Saved, but ${saved.settings.label} didn't answer: ${found.said}`);
         }
+        // Settings → Updates: start the `toolroll update` job. A step-up; the job writes the ledger entries.
+        if (url.pathname === "/settings/updates" || url.pathname === "/settings/updates/seen" || url.pathname === "/settings/updates/cancel") {
+            const databaseFile = store.databaseFile();
+            if (who.via !== "cookie" || !store.isInstanceOperator(who.name) || databaseFile === null)
+                return refuse(response, who, 403, "An instance operator updates Toolroll.", "/settings");
+            const stateDir = dirname(databaseFile);
+            const back = (key, words) => redirect(response, `/settings/updates?${key}=${encodeURIComponent(words)}`);
+            if (url.pathname === "/settings/updates/seen") {
+                markWhatsNewSeen(stateDir);
+                return redirect(response, "/settings/updates");
+            }
+            if (url.pathname === "/settings/updates/cancel")
+                return back("said", requestRuntimeUpdateCancel(stateDir));
+            if (!authenticateApprover(store, who.name, body.get("password") ?? "").ok)
+                return back("problem", "Enter your Toolroll password to update.");
+            const version = body.get("version") ?? "";
+            const when = { now: "now", "when-idle": "when-idle", tonight: "at" }[body.get("when") ?? ""] ?? null;
+            if (!/^\d+\.\d+\.\d+$/.test(version) || when === null)
+                return back("problem", "Choose when to update.");
+            const current = options.updates?.current ?? PACKAGE_VERSION;
+            if (!newerThan(version, current))
+                return back("problem", `Toolroll ${version} is not newer than ${current}. To go back, run toolroll update --rollback.`);
+            const method = options.updates?.method ?? installMethod();
+            if (method.kind === "npx" || method.kind === "source" || method.kind === "desktop")
+                return back("problem", method.kind === "npx" ? "npx runs the latest release each time; there is nothing to update." : method.kind === "desktop" ? "Update it from the Toolroll app." : "This runs from a source checkout. Update it with git.");
+            const before = runtimeUpdateStatus(stateDir).journal;
+            if (before !== null && !runtimeUpdateTerminal(before.phase))
+                return back("problem", "An update is already under way.");
+            if (when === "now") {
+                const running = runningWorkWords(store.raw());
+                if (running !== null)
+                    return back("problem", `Work is running: ${running}. Choose When idle to update once it finishes.`);
+            }
+            const prepared = prepareRuntimeUpdate({ stateDir, databaseFile, current: { version: current, dist: options.updates?.dist ?? currentRuntime(current).dist }, actor: who.name, version, when, at: "03:00" }, clock());
+            if ("refused" in prepared)
+                return back("problem", prepared.refused);
+            try {
+                await (options.updates?.launch ?? launchRuntimeUpdate)({ databaseFile, id: prepared.id });
+            }
+            catch (error) {
+                abandonRuntimeUpdate(stateDir, prepared.id, `The update could not start: ${error.message}`, clock());
+                return back("problem", `The update could not start: ${error.message}`);
+            }
+            // The job records its first step within moments; show it rather than the old page.
+            return back("said", when === "at" ? `Update to ${version} scheduled for 03:00.` : `Updating to ${version}.`);
+        }
         // v105: change how long each kind of data is kept. A step-up; the ledger keeps before → after for each kind.
         if (url.pathname === "/settings/retention") {
             if (who.via !== "cookie" || !store.isInstanceOperator(who.name))
@@ -13984,7 +14066,7 @@ button.pick-file { min-height: 1.75rem; padding: 0 .55rem; font-size: .75rem; }
 const THEME_CONTROLS_CSS = `.task-repo select{width:100%;min-height:2.75rem;font-size:1rem}.task-repo-add{margin:.35rem .1rem .5rem}.task-repo-add a{display:inline-flex;align-items:center;min-height:2.25rem}details.result-request-open.result-request-form>summary{border:0;background:transparent;padding:.5rem 0;min-height:2.75rem;font-weight:600;display:list-item;list-style:revert}details.result-request-open.result-request-form>summary::-webkit-details-marker{display:revert}form.js-autosave button[type=submit]{display:none}.provider-row{border-bottom:1px solid var(--so-line);padding:.35rem 0}.provider-row:first-of-type{border-top:1px solid var(--so-line)}.provider-head{display:flex;align-items:center;gap:.75rem;margin:.4rem 0 0}.provider-status{display:inline-flex;align-items:center;gap:.4rem;color:var(--so-muted);font-size:.875rem}.provider-status i{width:.5rem;height:.5rem;border-radius:50%;background:var(--so-muted)}.provider-status--ok i{background:var(--so-success)}.provider-status--warn i{background:var(--so-attention)}.provider-status--off i{background:transparent;border:1.5px solid var(--so-muted)}details.provider-manage>summary{cursor:pointer;color:var(--so-accent-text);font-size:.875rem;min-height:2.5rem;display:list-item;padding-block:.5rem}.card.props .row{display:grid;gap:.1rem;margin:0 0 .75rem}.card.props .row>.meta{display:block;font-size:.75rem}.card.props .row>.meta::first-letter{text-transform:uppercase}.card.props .row>.mono{font-family:var(--font-sans);font-size:.875rem}.card.props .row>.mono .seal{font-family:var(--font-mono);font-size:.8125rem}details.evidence-files{margin:1rem 0}details.evidence-files>summary{cursor:pointer;min-height:2.75rem;display:list-item;padding-block:.7rem;font-weight:600}details.evidence-files ul{list-style:none;margin:0;padding:0}details.evidence-files li{display:flex;justify-content:space-between;gap:1rem;padding:.5rem 0;border-bottom:1px solid var(--so-line)}.result-action .result-feedback-link{display:inline-flex;align-items:center;min-height:2.5rem;padding:.5rem 1rem;border:1px solid var(--so-input-line);border-radius:.5rem;background:var(--so-paper);color:var(--so-ink);font-weight:600;text-decoration:none}@media(hover:hover) and (pointer:fine){.result-action .result-feedback-link:hover{background:var(--so-raised)}}.so-sr-only{position:absolute!important;width:1px!important;height:1px!important;padding:0!important;margin:-1px!important;overflow:hidden!important;clip:rect(0,0,0,0)!important;white-space:nowrap!important;border:0!important}.verdict{margin:.5rem 0 .75rem}.verdict-chips{display:flex;flex-wrap:wrap;gap:.4rem;list-style:none;padding:0;margin:0}.verdict-chip{display:inline-flex;align-items:center;gap:.3rem;min-height:1.75rem;padding:.2rem .65rem;border-radius:999px;font-size:.8125rem;font-weight:600;background:var(--so-neutral-soft);color:var(--so-neutral-ink)}.verdict-chip svg{width:.9rem;height:.9rem}.verdict-chip--success{background:var(--so-success-soft);color:var(--so-success)}.verdict-chip--danger{background:var(--so-danger-soft);color:var(--so-danger)}.verdict-chip--warning{background:var(--so-warning-soft);color:var(--so-warning)}.verdict-chip--info{background:var(--so-info-soft);color:var(--so-info)}.verdict-by{margin:.4rem 0 0}details.result-request-open{margin:.5rem 0}details.result-request-open>summary{display:inline-flex;align-items:center;min-height:2.5rem;padding:.5rem 1rem;border:1px solid var(--so-input-line);border-radius:.5rem;background:var(--so-paper);color:var(--so-ink);font-weight:600;cursor:pointer;list-style:none}details.result-request-open>summary::-webkit-details-marker{display:none}details.result-request-open[open]>summary{margin-bottom:.75rem}.settings-tiles{display:grid;grid-template-columns:repeat(auto-fill,minmax(8.5rem,1fr));gap:.5rem;margin:0 0 2rem}.settings-tiles a{display:flex;align-items:center;gap:.6rem;min-height:3rem;padding:.65rem .8rem;border:1px solid var(--so-line);border-radius:.625rem;background:var(--so-paper);color:var(--so-ink);text-decoration:none;font-weight:550;font-size:.875rem}@media(hover:hover) and (pointer:fine){.settings-tiles a:hover{border-color:var(--so-input-line);background:var(--so-raised)}}.settings-tiles svg{width:1.1rem;height:1.1rem;flex-shrink:0;color:var(--so-accent-text)}details.settings-more{margin:.25rem 0 1.25rem}details.settings-more>summary{cursor:pointer;min-height:2.75rem;display:list-item;padding-block:.7rem;font-weight:550}details.settings-more>summary .meta{font-weight:400;margin-left:.35rem}.settings-changed{margin-top:-.25rem}.appearance{margin:0 0 28px}.appearance h2{margin:0 0 10px}.theme-switch{display:inline-flex;flex-wrap:nowrap;max-width:100%;gap:4px;padding:4px;margin:0;border:1px solid var(--so-line);border-radius:10px;background:var(--so-raised)}.theme-switch .theme-choice,.so-native-region .theme-switch .theme-choice{flex:1 1 0;width:auto;white-space:nowrap;min-height:40px;padding:8px 16px;border:0;border-radius:7px;background:transparent;color:var(--so-muted);font:inherit;font-weight:550;box-shadow:none;cursor:pointer}@media(hover:hover) and (pointer:fine){.theme-switch .theme-choice:hover{color:var(--so-ink)}}.theme-switch .theme-choice[aria-pressed="true"]{background:var(--so-paper);color:var(--so-ink);box-shadow:0 1px 2px rgb(0 0 0 / .1)}.appearance .meta{margin:8px 0 0}@media(max-width:600px){.theme-switch .theme-choice{min-height:44px}}.update-notes{white-space:pre-wrap;overflow-wrap:anywhere;font:inherit;max-height:18rem;overflow:auto}`;
 /** The page CSS this module writes itself (not the imported modules'), for the stylesheet contract tests. */
 export const PAGE_CSS = STYLE + THEME_CONTROLS_CSS;
-const WORKSPACE_STYLE = styleAsset(STYLE + APPROVAL_RULES_CSS + SPEND_CSS + RETENTION_CSS + LIMITS_CSS + MONITORING_CSS + BACKUP_CSS + EXPORT_CSS + PROJECT_DELETE_CSS + POLICY_CSS + EVIDENCE_PACK_CSS + THEME_CONTROLS_CSS + CODING_CSS + CODING_SHIPPING_CSS + RECIPE_CSS + SKILLS_CSS + TOOLS_CSS + FLOWS_CSS + TEAMMATE_CSS + KITS_CSS + SSO_CSS + CREDENTIALS_CSS + KNOWLEDGE_CSS + MODELS_CSS + CHAT_POLISH_CSS + TRANSITIONS_CSS + WORKSPACE_MOTION_CSS + ASSIGNMENT_CSS + LEAD_CONTEXT_CSS + '.learning{min-width:0;overflow-wrap:anywhere}.learning .card{min-width:0}.learning code,.learning blockquote,.learning pre{white-space:pre-wrap;overflow-wrap:anywhere;word-break:break-word}.learning button,.learning summary,.learning .button-link{min-height:44px}.learning button{white-space:nowrap}.learning summary{padding:12px 0;cursor:pointer}.learning form{margin:12px 0}.learning select{max-width:100%}.learning blockquote{margin:8px 0}.learning ul{padding-left:20px}');
+const WORKSPACE_STYLE = styleAsset(STYLE + APPROVAL_RULES_CSS + SPEND_CSS + RETENTION_CSS + UPDATES_CSS + LIMITS_CSS + MONITORING_CSS + BACKUP_CSS + EXPORT_CSS + PROJECT_DELETE_CSS + POLICY_CSS + EVIDENCE_PACK_CSS + THEME_CONTROLS_CSS + CODING_CSS + CODING_SHIPPING_CSS + RECIPE_CSS + SKILLS_CSS + TOOLS_CSS + FLOWS_CSS + TEAMMATE_CSS + KITS_CSS + SSO_CSS + CREDENTIALS_CSS + KNOWLEDGE_CSS + MODELS_CSS + CHAT_POLISH_CSS + TRANSITIONS_CSS + WORKSPACE_MOTION_CSS + ASSIGNMENT_CSS + LEAD_CONTEXT_CSS + '.learning{min-width:0;overflow-wrap:anywhere}.learning .card{min-width:0}.learning code,.learning blockquote,.learning pre{white-space:pre-wrap;overflow-wrap:anywhere;word-break:break-word}.learning button,.learning summary,.learning .button-link{min-height:44px}.learning button{white-space:nowrap}.learning summary{padding:12px 0;cursor:pointer}.learning form{margin:12px 0}.learning select{max-width:100%}.learning blockquote{margin:8px 0}.learning ul{padding-left:20px}');
 /**
  * The board's liveness: fetch this page's own fragment on a timer and swap
  * it in place — no flicker, no scroll reset, no long-lived stream to manage,
@@ -14635,26 +14717,20 @@ function inboxPage(chrome, data) {
                 `<span class="meta">frees ${gap.unblocks.length} task${gap.unblocks.length > 1 ? "s" : ""}</span>` +
                 `<span class="right meta">how to fix \u2192</span></p>`)
                 .join("\n");
-    // The first-run checklist replaces the empty-queue card while the
-    // installation has never succeeded; each step is live state, and the
-    // whole card retires permanently on the first successful run.
+    // The first-run steps, until the first Ready result: each is done or
+    // shows the one action that does it.
     const wizard = data.wizard === null
         ? ""
-        : `<div class="card">` +
-            `<p><strong>Getting started</strong> <span class="meta">\u2014 disappears after the first successful run</span></p>` +
-            `<p class="meta">Keep <span class="mono">toolroll up</span> running on this machine \u2014 it opens the app and reconnects every saved project's builder.</p>` +
+        : `<div class="card" data-first-run>` +
+            `<p><strong>Get to your first result</strong></p>` +
             data.wizard
-                .map(step => `<p class="row"><span class="mono">${step.done ? "\u2713" : "\u25cb"}</span> <strong>${escape(step.title)}</strong><br>` +
-                `<span class="meta">${step.detail}</span></p>`)
+                .map(step => `<p class="row" data-step="${step.key}"><span class="mono" aria-hidden="true">${step.done ? "\u2713" : "\u25cb"}</span> <strong>${escape(step.title)}</strong>` +
+                (step.action === null ? ` <span class="meta">done</span>`
+                    : step.action.kind === "link" ? ` <a href="${escape(step.action.href)}">${escape(step.action.label)}</a>`
+                        : ` <code>${escape(step.action.command)}</code>`) +
+                `</p>`)
                 .join("\n") +
-            `<p><a class="new-task" href="/recipes">Start with a guided recipe →</a></p>` +
-            `<p class="meta">templates \u2014 edit, then approve; nothing a template files carries authority: ` +
-            TEMPLATES.map(one => one.kind === "routine"
-                ? `<a href="/routines?template=${escape(one.name)}">${escape(one.name)}</a>`
-                : one.kind === "task"
-                    ? `<a href="/tasks?template=${escape(one.name)}">${escape(one.name)}</a>`
-                    : `<span title="a recipe \u2014 walk it in the terminal: toolroll template show ${escape(one.name)}">${escape(one.name)} (recipe)</span>`).join(" \u00b7 ") +
-            `</p></div>`;
+            `</div>`;
     const noWorker = data.worker.answering > 0
         ? ""
         : `<div class="card builder-notice" data-builder-status="${data.worker.registered === 0 ? "not-connected" : "disconnected"}">` +
@@ -21413,7 +21489,7 @@ function telegramDeliveryWords(store, bot) {
         return `Telegram pushes new messages to ${state.url}${state.problem === null ? "." : `, but ${state.problem.charAt(0).toLowerCase()}${state.problem.slice(1)}.`}`;
     return `Toolroll asks Telegram for new messages every few seconds${state?.problem ? ` (${state.problem})` : ""}.`;
 }
-function settingsPage(chrome, existing, hasEnv, csrf, problem, messaging = null, push = null, providerKeys = null, digest = null, permissionDefault = null, qualityDefault = null, email = null, telegramDelivery = null, workers = null, updates = null) {
+function settingsPage(chrome, existing, hasEnv, csrf, problem, messaging = null, push = null, providerKeys = null, digest = null, permissionDefault = null, qualityDefault = null, email = null, telegramDelivery = null, workers = null, updates = null, firstResult = null) {
     const permissionCard = permissionDefault === null
         ? ""
         : [
@@ -21610,6 +21686,7 @@ function settingsPage(chrome, existing, hasEnv, csrf, problem, messaging = null,
         email,
         workers,
         updates,
+        firstResult,
     };
     return screen("Settings", [
         "<h1>Settings</h1>",
@@ -21620,6 +21697,7 @@ function settingsPage(chrome, existing, hasEnv, csrf, problem, messaging = null,
         keysCard,
         workersCard(workers),
         updatesCard(updates, csrf),
+        firstResult === null ? "" : `<p class="meta" data-first-result>${escape(firstResult)}</p>`,
         pushCard === "" && messagingCard === "" && digestCard === "" ? "" : `<h2>Notifications</h2>`,
         messagingCard,
         pushCard,
@@ -21686,7 +21764,7 @@ function updatesCard(updates, csrf) {
                 (latest.notes === "" ? "" : `<details class="settings-more"><summary>What's new in ${escape(latest.version)}</summary><pre class="update-notes">${escape(latest.notes)}</pre></details>`)
             : "") +
         (updates.check.canManage && !updates.check.byEnv
-            ? `<form method="post" action="/settings/updates" class="inline"><input type="hidden" name="csrf" value="${escape(csrf)}"><input type="hidden" name="check" value="${updates.check.on ? "off" : "on"}"><button type="submit">${updates.check.on ? "Turn off daily check" : "Turn on daily check"}</button></form>`
+            ? `<form method="post" action="/settings/updates/checks" class="inline"><input type="hidden" name="csrf" value="${escape(csrf)}"><input type="hidden" name="check" value="${updates.check.on ? "off" : "on"}"><button type="submit">${updates.check.on ? "Turn off daily check" : "Turn on daily check"}</button></form>`
             : updates.check.byEnv ? `<p class="meta">Off by TOOLROLL_NO_UPDATE_CHECK.</p>` : "") +
         (updates.workers.length === 0 ? "" : `<ul>${updates.workers.map(one => `<li data-worker-version="${escape(one.name)}">${escape(one.name)} <span class="mono">${escape(one.version ?? "unknown")}</span>${one.older ? " \u00b7 older" : ""}</li>`).join("")}</ul>`) +
         `</section>`;
@@ -21694,6 +21772,22 @@ function updatesCard(updates, csrf) {
 /** Choices save the moment they change; without the script the Save
  * button stays and the form works the same. */
 const SETTINGS_AUTOSAVE_SCRIPT = `(function(){document.querySelectorAll('form[data-autosave]').forEach(function(form){form.classList.add('js-autosave');form.addEventListener('change',function(ev){var t=ev.target;if(t&&(t.type==='radio'||t.tagName==='SELECT')){if(form.requestSubmit)form.requestSubmit();else form.submit();}});});})();`;
+/** The newest release, remembered for a while so the page stays quick. */
+let latestSeen = null;
+async function latestReleaseFor(latest) {
+    if (latest === undefined && latestSeen !== null && Date.now() - latestSeen.at < ("problem" in latestSeen.value ? 60_000 : 900_000))
+        return latestSeen.value;
+    let value;
+    try {
+        value = { version: (await (latest ?? latestVersionNow)()).version };
+    }
+    catch (error) {
+        value = { problem: error.message };
+    }
+    if (latest === undefined)
+        latestSeen = { at: Date.now(), value };
+    return value;
+}
 /** Settings destinations as a scannable grid: an icon and a name each. */
 function settingsTiles() {
     const tiles = SETTINGS_TILE_ICONS;
@@ -21716,6 +21810,7 @@ const SETTINGS_TILE_ICONS = [
     ["/settings/approval", "Approval rules", `<path d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z"/><path d="m9 12 2 2 4-4"/>`],
     ["/settings/monitoring", "Monitoring", `<path d="M22 12h-4l-3 9L9 3l-3 9H2"/>`],
     ["/settings/retention", "Retention", `<circle cx="12" cy="12" r="9"/><path d="M12 7v5l3 2"/>`],
+    ["/settings/updates", "Updates", `<path d="M21 12a9 9 0 1 1-2.64-6.36"/><path d="M21 3v6h-6"/>`],
     ["/settings/backups", "Backups", `<ellipse cx="12" cy="5" rx="9" ry="3"/><path d="M3 5v14c0 1.7 4 3 9 3s9-1.3 9-3V5"/><path d="M3 12c0 1.7 4 3 9 3s9-1.3 9-3"/>`],
     ["/settings/data", "Data", `<path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><path d="m7 10 5 5 5-5"/><path d="M12 15V3"/>`],
 ];

package/dist/skills.d.ts

@@ -68,6 +68,8 @@ export declare function applyInstall(repo: string, writeContext: boolean): Insta
  */
 export declare const CLAUDE_CODE_MANAGED_MARK = "<!-- standing-orders:claude-code-skill:v1 -->";
 export declare const CLAUDE_CODE_GUIDES: readonly ["console", "operating", "runner"];
+/** The thin user-level skill `toolroll onboard` writes (agent-onboard.ts). */
+export declare const OPERATOR_SKILL_MARK = "<!-- toolroll:operator-skill:v1";
 export type ClaudeCodeSkillFile = {
     name: string;
     path: string;

package/dist/skills.js

@@ -162,6 +162,8 @@ export function applyInstall(repo, writeContext) {
  */
 export const CLAUDE_CODE_MANAGED_MARK = "<!-- standing-orders:claude-code-skill:v1 -->";
 export const CLAUDE_CODE_GUIDES = ["console", "operating", "runner"];
+/** The thin user-level skill `toolroll onboard` writes (agent-onboard.ts). */
+export const OPERATOR_SKILL_MARK = "<!-- toolroll:operator-skill:v1";
 export function defaultClaudeCodeSkillDir(home = homedir()) {
     return join(home, ".claude", "skills", "toolroll");
 }
@@ -232,7 +234,7 @@ function claudeCodeFiles(directory) {
 }
 function isClaudeCodeManaged(name, content) {
     if (name === "SKILL.md") {
-        return ownHeader(content) && content.includes(`\n${CLAUDE_CODE_MANAGED_MARK}\n`);
+        return ownHeader(content) && (content.includes(`\n${CLAUDE_CODE_MANAGED_MARK}\n`) || content.includes(`\n${OPERATOR_SKILL_MARK} `));
     }
     return content.startsWith(`${CLAUDE_CODE_MANAGED_MARK}\n\n`);
 }

package/dist/store.d.ts

@@ -4337,16 +4337,16 @@ export declare class Store {
      * createConsoleTask. Set-once: an already-stamped row never changes. */
     stampFiledVia(refId: number, via: string): void;
     /**
-     * When this installation first finished a run successfully — the
+     * When this installation first finished a run with a change — the
      * moment the first-run checklist retires, permanently. Derived from run
      * history the first time it is observed, then stamped as an append-only
      * installation fact so later pruning of those rows cannot resurrect the
      * checklist (adoption review, finding 14).
      */
     firstSuccessAt(now: Date): string | null;
-    /** Whether ANY spend routing is configured — a fact about this database,
-     * not about any machine's binaries or authentication. */
-    hasPhaseConfig(): boolean;
+    /** When this installation began: its first account. Accounts are never
+     * deleted (revocation is a stamp), so this never moves. */
+    installationStartedAt(): string | null;
     /** The jump palette's food: open (queued/running/failed) tasks, admission
      * inside the query before its LIMIT, newest first. */
     paletteTasks(repo: string | null, limit: number, admitted?: string[] | null, includeUnplaced?: boolean): {

package/dist/store.js

@@ -14391,7 +14391,7 @@ export class Store {
         this.db.prepare("UPDATE task_ref SET filed_via = ? WHERE id = ? AND filed_via IS NULL").run(via, refId);
     }
     /**
-     * When this installation first finished a run successfully — the
+     * When this installation first finished a run with a change — the
      * moment the first-run checklist retires, permanently. Derived from run
      * history the first time it is observed, then stamped as an append-only
      * installation fact so later pruning of those rows cannot resurrect the
@@ -14402,7 +14402,7 @@ export class Store {
         if (fact !== null)
             return fact;
         const row = this.db
-            .prepare("SELECT finished_at FROM run WHERE outcome IN ('built','no-change') AND finished_at IS NOT NULL ORDER BY id LIMIT 1")
+            .prepare("SELECT finished_at FROM run WHERE outcome = 'built' AND finished_at IS NOT NULL ORDER BY id LIMIT 1")
             .get();
         if (row === undefined)
             return null;
@@ -14410,10 +14410,11 @@ export class Store {
         this.recordInstallationFact("first-success-at", when, now);
         return when;
     }
-    /** Whether ANY spend routing is configured — a fact about this database,
-     * not about any machine's binaries or authentication. */
-    hasPhaseConfig() {
-        return this.db.prepare("SELECT 1 AS hit FROM phase_config LIMIT 1").get() !== undefined;
+    /** When this installation began: its first account. Accounts are never
+     * deleted (revocation is a stamp), so this never moves. */
+    installationStartedAt() {
+        const row = this.db.prepare("SELECT MIN(added_at) AS at FROM approver").get();
+        return row === undefined || row["at"] == null ? null : String(row["at"]);
     }
     /** The jump palette's food: open (queued/running/failed) tasks, admission
      * inside the query before its LIMIT, newest first. */
@@ -15936,6 +15937,11 @@ export class Store {
             // stop after an orphan or held supervisor finishes shutdown.
             this.recordRunProcessExits(id, result.now);
             this.settleRunStop(id, result.stopSettlement ?? "finished", result.now);
+            // The first Ready result is an installation fact the moment it lands,
+            // not only when something later looks for it. A run that changed
+            // nothing is not a first result.
+            if (result.outcome === "built")
+                this.firstSuccessAt(result.now);
             // The park rate is *measured* — parked over concluded builder attempts —
             // and maintained where attempts conclude, because the attention budget's
             // gate reads it inside a claim transaction and must never trust a number

package/dist/surface.js

@@ -105,6 +105,7 @@ export const COMMAND_GUIDE = [
     },
     operator("link", "put toolroll on PATH"),
     operator("unlink", "take it off PATH"),
+    operator("update", "update to the latest release: verified provenance, drained work, backup, rehearsal, health check, automatic restore; --rollback undoes it"),
     operator("demo", "a seeded throwaway sandbox"),
     { invocation: 'session capabilities', synopsis: 'Show executable session schemas and operator authority requirements; no credentials needed', audience: 'agent', agentMayInvoke: true, mutation: 'none', flags: [jsonFlag] },
     ...SESSION_DESCRIPTORS.map(spec => ({
@@ -348,5 +349,6 @@ export const COMMAND_GUIDE = [
     operator("serve", "the operations console (HTTP)"),
     operator("watch", "the unattended loop, kept running"),
     operator("up", "console + worker + browser, one command"),
+    operator("onboard", "add this repository, report signed-in agents, install or --remove the operator skill (--yes), and print the handoff"),
     operator("daemon", "install the loop under the OS service manager"),
 ];

package/dist/toolroll-update-cli.d.ts

@@ -0,0 +1,15 @@
+import { installMethod } from "./install-method.js";
+import { type RuntimeRef, type UpdateSystem } from "./toolroll-update.js";
+export declare const UPDATE_HELP = "toolroll update                 preview updating to the latest release\ntoolroll update --yes           update: verify, let running work finish, back up, rehearse, switch, restart, check\n  --version X                   a specific release instead of the latest\n  --when-idle                   pause new work and wait for running work (the default)\n  --now                         refuse if any work is running\n  --at HH:MM                    wait until then (e.g. --at 03:00)\n  --allow-downgrade             with --version, go back to an older release\ntoolroll update --rollback [--yes]   return to the previous version and its database backup\ntoolroll update --status | --resume | --cancel";
+export type UpdateCliDeps = {
+    system?: UpdateSystem;
+    current?: RuntimeRef;
+    method?: ReturnType<typeof installMethod>;
+    latest?: () => Promise<{
+        version: string;
+    }>;
+    databaseFile?: string;
+    /** Where the console's one-off update job's definition lives (tests). */
+    home?: string;
+};
+export declare function runUpdateCommand(args: readonly string[], write: (line: string) => void, deps?: UpdateCliDeps): Promise<number>;