toolroll 0.6.0 → 0.8.0

package/dist/first-run.d.ts

@@ -0,0 +1,54 @@
+import type { Runner } from "./backend.js";
+export declare const SIGN_IN_COMMAND = "claude auth login";
+export declare const SANDBOX_COMMAND = "npx toolroll demo";
+export type FirstRunAction = {
+    kind: "link";
+    label: string;
+    href: string;
+} | {
+    kind: "command";
+    command: string;
+};
+export type FirstRunStep = {
+    key: "agent" | "project" | "task";
+    title: string;
+    done: boolean;
+    action: FirstRunAction | null;
+};
+export type FirstRunFacts = {
+    agentSignedIn: boolean;
+    projects: number;
+    hasTask: boolean;
+    firstResultAt: string | null;
+};
+/** The three steps, each done or with the one action that does it; null once the first result has arrived. */
+export declare function firstRunSteps(facts: FirstRunFacts): FirstRunStep[] | null;
+export type OpenIssue = {
+    number: number;
+    title: string;
+};
+export type TodoComment = {
+    file: string;
+    line: number;
+    text: string;
+};
+export type FirstTaskSuggestion = {
+    source: "issue" | "todo" | "generic";
+    label: string;
+    draft: string;
+};
+export declare const GENERIC_FIRST_TASKS: readonly FirstTaskSuggestion[];
+/** Issue titles and TODO text are written by anyone: keep only what a person can see, so the draft they send is the
+ * draft the lead reads (no control, format, zero-width, bidi, tag or variation-selector characters). */
+export declare const visibleText: (text: string) => string;
+/** Three first tasks: open GitHub issues first, then TODO or FIXME comments, then safe generic ones. */
+export declare function firstTaskSuggestions(found: {
+    issues: readonly OpenIssue[];
+    todos: readonly TodoComment[];
+}): FirstTaskSuggestion[];
+/** `git grep` lines ("file:line:text") to TODO or FIXME notes, one per file. */
+export declare function parseTodoLines(stdout: string, limit?: number): TodoComment[];
+/** Read the project's own sources for suggestions: its open issues through the `gh` login, then its TODO comments. Failures fall through quietly. */
+export declare function findFirstTasks(repo: string, runner?: Runner): Promise<FirstTaskSuggestion[]>;
+/** "First result in 7 min": how long after the installation began its first Ready result arrived. */
+export declare function firstResultWords(since: string, at: string): string | null;

package/dist/first-run.js

@@ -0,0 +1,101 @@
+/**
+ * The first run: three plain steps to a first result, and three first tasks
+ * to try. Everything here is derived from live facts on each render; the
+ * list retires permanently with the first Ready result (the
+ * 'first-success-at' installation fact). A suggestion only drafts words in
+ * the composer: nothing is filed until the person sends it and confirms.
+ */
+import { run } from "./exec.js";
+import { githubIssues } from "./issues.js";
+export const SIGN_IN_COMMAND = "claude auth login";
+export const SANDBOX_COMMAND = "npx toolroll demo";
+/** The three steps, each done or with the one action that does it; null once the first result has arrived. */
+export function firstRunSteps(facts) {
+    if (facts.firstResultAt !== null)
+        return null;
+    const project = facts.projects > 0;
+    return [
+        { key: "agent", title: "Agent signed in", done: facts.agentSignedIn, action: facts.agentSignedIn ? null : { kind: "command", command: SIGN_IN_COMMAND } },
+        { key: "project", title: "Project added", done: project, action: project ? null : { kind: "link", label: "Add a project", href: "/projects" } },
+        { key: "task", title: "Your first task", done: facts.hasTask, action: facts.hasTask ? null : { kind: "link", label: "New task", href: "/tasks/new" } },
+    ];
+}
+export const GENERIC_FIRST_TASKS = [
+    { source: "generic", label: "Add a test for an untested function", draft: "Find one function without a test and add a focused test for it." },
+    { source: "generic", label: "Fix a lint warning", draft: "Fix one lint warning without changing behaviour." },
+    { source: "generic", label: "Improve the README's setup section", draft: "Improve the setup section of the README so a newcomer can install and run the project." },
+];
+const clip = (text, max) => (text.length > max ? `${text.slice(0, max - 1).trimEnd()}…` : text);
+/** Issue titles and TODO text are written by anyone: keep only what a person can see, so the draft they send is the
+ * draft the lead reads (no control, format, zero-width, bidi, tag or variation-selector characters). */
+export const visibleText = (text) => text.replace(/[\p{Cf}\u{FE00}-\u{FE0F}\u{E0100}-\u{E01EF}]/gu, "").replace(/[\p{Cc}\s]+/gu, " ").trim();
+/** Three first tasks: open GitHub issues first, then TODO or FIXME comments, then safe generic ones. */
+export function firstTaskSuggestions(found) {
+    const fromIssues = found.issues.map(({ number, title: raw }) => {
+        const title = visibleText(raw);
+        return { source: "issue", label: clip(`#${number} ${title}`, 80), draft: `Fix GitHub issue #${number}: ${title}` };
+    });
+    const fromTodos = found.todos.map(({ file: rawFile, line, text: rawText }) => ({ file: visibleText(rawFile), line, text: visibleText(rawText) })).map((todo) => ({
+        source: "todo", label: clip(todo.text === "" ? `The note in ${todo.file}` : todo.text.charAt(0).toUpperCase() + todo.text.slice(1), 80),
+        draft: `Resolve the note in ${todo.file} line ${todo.line}${todo.text === "" ? "" : `: ${todo.text}`}`,
+    }));
+    return [...fromIssues, ...fromTodos, ...GENERIC_FIRST_TASKS].slice(0, 3);
+}
+const SKIPPED = /(^|\/)(node_modules|dist|build|vendor|third_party|\.git)\//;
+/** `git grep` lines ("file:line:text") to TODO or FIXME notes, one per file. */
+export function parseTodoLines(stdout, limit = 3) {
+    const found = [];
+    const seen = new Set();
+    for (const line of stdout.split("\n")) {
+        const match = /^(.+?):(\d+):(.*)$/.exec(line);
+        if (match === null || SKIPPED.test(match[1]) || seen.has(match[1]))
+            continue;
+        const note = /\b(?:TODO|FIXME)\b(?:\([^)]*\))?[:\s-]*(.*)$/.exec(match[3]);
+        if (note === null)
+            continue;
+        seen.add(match[1]);
+        found.push({ file: match[1], line: Number(match[2]), text: clip(note[1].replace(/\s*(\*\/|-->)\s*$/, "").trim(), 120) });
+        if (found.length === limit)
+            break;
+    }
+    return found;
+}
+/** Read the project's own sources for suggestions: its open issues through the `gh` login, then its TODO comments. Failures fall through quietly. */
+export async function findFirstTasks(repo, runner = run) {
+    let issues = [];
+    try {
+        const listed = await githubIssues({ repo, runner, limit: 3, timeoutMs: 5_000 }).listReady();
+        if (listed.ok)
+            issues = listed.value.slice(0, 3).map(one => ({ number: Number(one.id), title: one.title })).filter(one => Number.isSafeInteger(one.number));
+    }
+    catch {
+        issues = [];
+    }
+    let todos = [];
+    if (issues.length < 3) {
+        try {
+            const result = await runner("git", ["grep", "-n", "-I", "-w", "--max-count=1", "-E", "TODO|FIXME"], { cwd: repo, timeoutMs: 5_000 });
+            if (result.code === 0 || result.stdout !== "")
+                todos = parseTodoLines(result.stdout);
+        }
+        catch {
+            todos = [];
+        }
+    }
+    return firstTaskSuggestions({ issues, todos });
+}
+/** "First result in 7 min": how long after the installation began its first Ready result arrived. */
+export function firstResultWords(since, at) {
+    const minutes = Math.round((Date.parse(at) - Date.parse(since)) / 60_000);
+    if (!Number.isFinite(minutes) || minutes < 0)
+        return null;
+    if (minutes < 1)
+        return "First result in under a minute";
+    if (minutes < 60)
+        return `First result in ${minutes} min`;
+    if (minutes < 48 * 60) {
+        const hours = Math.floor(minutes / 60), rest = minutes % 60;
+        return `First result in ${hours} h${rest === 0 ? "" : ` ${rest} min`}`;
+    }
+    return `First result in ${Math.round(minutes / (24 * 60))} days`;
+}

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" | "managed";
+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,65 @@
+/**
+ * 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",
+    // A runtime `toolroll update` installed (staged-upgrades/release-* or rollback-*): it updates itself.
+    managed: "toolroll update",
+};
+/** 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 (/\/staged-upgrades\/(release|rollback)-/.test(path))
+        return "managed";
+    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

@@ -1,3 +1,4 @@
+import { type OnboardIo } from "./agent-onboard.js";
 import { type TriggerIo } from "./flow-triggers.js";
 import { type StepIo } from "./flow-steps.js";
 import { type Store } from "./store.js";
@@ -6,6 +7,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 +35,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;
     /**
@@ -61,7 +67,15 @@ export type OperateOptions = {
     heldCoordinator?: import("./held.js").HeldSessionCoordinator;
     /** Test seam for the short indexed wait loop. */
     waitSleep?: (milliseconds: number) => Promise<void>;
+    /** Injected by tests: `onboard`'s home folder, terminal and probes. */
+    onboardSeams?: OnboardSeams;
+    /** Injected by tests: whether `up` has a person at a terminal, and how it opens a browser. */
+    upSeams?: {
+        terminal?: boolean;
+        openBrowser?: (url: string) => void;
+    };
 };
+export type OnboardSeams = Partial<Pick<OnboardIo, "home" | "env" | "cwd" | "interactive" | "confirm" | "findRepo" | "checkConnection">>;
 export declare const OPERATE_HELP: string;
 /** Parsed flags, with the positionals left over. */
 type Args = {

package/dist/operate.js

@@ -12,6 +12,7 @@ import { buildExport, exportSummary, exportZip, writeExportFolder } from "./expo
 import { startBudgetAlerts } from "./budget-alerts.js";
 import { liftAuthPause, openAuthPauses, signInGate, signInWords, startSignInProbes } from "./provider-auth.js";
 import { createConnectionChecker } from "./provider-connection.js";
+import { buildHandoff, handoffLines, loginAccount, runOnboard } from "./agent-onboard.js";
 import { backupFiles, backupFolderOf, backupOwner, backupNow, restoreDatabase, startBackups } from "./backup.js";
 import { pushLimitSink } from "./provider-limits.js";
 import { limitsView } from "./limits-ui.js";
@@ -181,6 +182,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.
  *
@@ -562,13 +566,13 @@ export const OPERATE_VALUE_FLAGS = new Set([
     "command", "timeout-seconds", "setup-digest", "stop-grace", "title", "name", "every", "lines",
     "label", "reviewers", "limit", "role", "key-file", "weekly-usd", "daily-turns", "per-hour", "token-file", "race", "compare", "race-per-usd", "race-total-usd", "race-count", "race-agents", "budget-usd", "build-usd", "sync-max-age", "merge-method",
     "phase", "risk", "tier", "clear-phase",
-    "run", "containment",
+    "run", "containment", "agent",
     "token-env", "after", "repair-max-attempts", "consumer", "batch", "feedback", "source", "view", "cursor", "why", "supersedes", "decision", "sessions", "timeout",
 ]);
 export const OPERATE_BOOLEAN_FLAGS = new Set([
     "json", "yes", "all", "local", "history", "latest-watch", "dry-run", "file", "allow-paid-fallback",
     "clear", "follow", "ready", "all-tasks", "inbound-only", "help", "undo", "anyone", "allow-dispatch", "allow-merge", "merge-delete-branch",
-    "no-open", "no-verify", "no-follow", "end", "report", "off", "tmux",
+    "no-open", "remove", "no-verify", "no-follow", "end", "report", "off", "tmux",
     "self-heal", "plan-auto", "repair-auto", "review-retry-auto", "no-local",
     "html", "csv", "alerts-only",
     // v105: the full export.
@@ -720,6 +724,10 @@ 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 }),
+            ...(options.onboardSeams === undefined ? {} : { onboardSeams: options.onboardSeams }),
+            ...(options.upSeams === undefined ? {} : { upSeams: options.upSeams }),
         });
     }
     catch (error) {
@@ -934,6 +942,8 @@ async function dispatch(command, positional, flags, context) {
             return watchCommand(flags, context);
         case "up":
             return upCommand(flags, context);
+        case "onboard":
+            return onboardCommand(flags, context);
         case "daemon":
             return daemonCommand(positional, flags, context);
         case "bridge":
@@ -2127,10 +2137,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 +2149,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 +2161,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 +2172,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 +2398,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 +2618,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 +2792,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 +3754,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 +3802,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 +3829,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 +3998,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 +4708,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 +7102,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
@@ -7637,6 +7665,54 @@ function openBrowser(url) {
         // A browser that will not open is a URL the greeting already printed.
     }
 }
+/**
+ * `onboard`: the agent that installed Toolroll becomes its lead. The work
+ * lives in agent-onboard.ts; this wires it to the installation: the same
+ * registry and project row Projects → add writes, and the same sign-in
+ * checks Settings → AI providers makes.
+ */
+async function onboardCommand(flags, context) {
+    const { store, write, json, clock } = context;
+    const seams = context.onboardSeams ?? {};
+    const portGiven = text(flags, "port");
+    const port = Number(portGiven ?? 4180);
+    if (portGiven !== undefined && (!Number.isInteger(port) || port < 1 || port >= 65536)) {
+        return fail(write, json, "onboard", "usage", "--port is a whole number under 65536", EXIT.usage);
+    }
+    const home = seams.home ?? homedir();
+    const env = seams.env ?? process.env;
+    const gitRun = context.gitRunner ?? ((file, args, opts) => run(file, [...args], { ...(opts?.cwd === undefined ? {} : { cwd: opts.cwd }), timeoutMs: 10_000 }));
+    const registryPath = registryPathOf(context);
+    const checker = createConnectionChecker({ home, env });
+    return runOnboard({
+        write,
+        json,
+        yes: flag(flags, "yes"),
+        remove: flag(flags, "remove"),
+        agentFlag: text(flags, "agent"),
+        url: `http://127.0.0.1:${port}`,
+        loginFile: join(dirname(context.databaseFile), UP_LOGIN_FILE),
+        home,
+        env,
+        version: PACKAGE_VERSION,
+        cwd: seams.cwd ?? process.cwd(),
+        interactive: seams.interactive ?? interactive(),
+        confirm: seams.confirm ?? (async (question) => /^y(es)?$/i.test(await ask(`${question} `))),
+        findRepo: seams.findRepo ?? (async (cwd) => {
+            const top = await gitRun("git", ["rev-parse", "--show-toplevel"], { cwd });
+            return top.code === 0 ? canonicalProject(top.stdout.trim()) : null;
+        }),
+        enroll: async (repo) => {
+            const before = await loadProjectRegistry(registryPath);
+            const enrolled = await updateRepos(registryPath, repos => addRepos(repos, [repo]));
+            if (!enrolled.ok)
+                return { ok: false, message: enrolled.message };
+            store.upsertProject(repo, projectName(repo), clock());
+            return { ok: true, added: "error" in before || !before.repos.includes(repo) };
+        },
+        checkConnection: seams.checkConnection ?? (agent => checker(agent)),
+    });
+}
 async function upCommand(flags, context) {
     const { store, write, json, clock } = context;
     const demoFence = refuseDemo(context, "up");
@@ -8064,6 +8140,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) {
@@ -8075,6 +8152,8 @@ async function upCommand(flags, context) {
     // 9. Readiness, then the ONE startup envelope / greeting (finding 11/20).
     const approverPlan2 = approver;
     const url = console_.url;
+    const terminal = context.upSeams?.terminal ?? process.stdout.isTTY === true;
+    const upHandoff = buildHandoff({ url, loginFile: approverPlan2.passwordFile, account: approverPlan2.passwordFile === null ? approverPlan2.approver : loginAccount(approverPlan2.passwordFile) ?? approverPlan2.approver });
     if (fatal === null) {
         if (json) {
             write(envelopeJson({
@@ -8087,8 +8166,17 @@ async function upCommand(flags, context) {
                 approvers: approverPlan2.approvers,
                 approverVerified: approverPlan2.verified,
                 ...(approverPlan2.passwordFile === null ? {} : { passwordFile: approverPlan2.passwordFile }),
+                handoff: upHandoff,
             }));
         }
+        else if (!terminal) {
+            // No person at a terminal: an agent started this. It gets the
+            // handoff to relay, never the password, and no browser opens.
+            write("");
+            for (const line of handoffLines(upHandoff))
+                write(line);
+            write("Run `toolroll onboard` inside a repository to add it and install the Toolroll skill for your agent.");
+        }
         else {
             write("");
             write(`The console is on ${url}`);
@@ -8113,8 +8201,8 @@ async function upCommand(flags, context) {
             write("  The inbox checklist shows what remains before approved work builds unattended.");
             write("  Ctrl-C stops Toolroll on this machine.");
         }
-        if (!json && !flags.has("no-open") && process.stdout.isTTY === true)
-            openBrowser(url);
+        if (!json && !flags.has("no-open") && terminal)
+            (context.upSeams?.openBrowser ?? openBrowser)(url);
     }
     // 10. Supervise to the end.
     await stopped;
@@ -8949,7 +9037,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 +9047,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";