toolroll 0.7.0 → 0.8.1

package/dist/first-run.d.ts

@@ -0,0 +1,57 @@
+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 -z -n` records ("file\0line\0text\n") to TODO or FIXME notes, one per file. NUL-separated so a
+ * file name with a colon or a newline in it is still one file name. */
+export declare function parseTodoLines(stdout: string, limit?: number): TodoComment[];
+/** The TODO search: no colour and no column whatever the person's git config says, NUL after each file name. */
+export declare const TODO_GREP_ARGS: readonly string[];
+/** 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,104 @@
+/**
+ * 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 -z -n` records ("file\0line\0text\n") to TODO or FIXME notes, one per file. NUL-separated so a
+ * file name with a colon or a newline in it is still one file name. */
+export function parseTodoLines(stdout, limit = 3) {
+    const found = [];
+    const seen = new Set();
+    for (const match of stdout.matchAll(/([^\0]*)\0(\d+)\0([^\n]*)(?:\n|$)/g)) {
+        const file = match[1];
+        if (file === "" || SKIPPED.test(file) || seen.has(file))
+            continue;
+        const note = /\b(?:TODO|FIXME)\b(?:\([^)]*\))?[:\s-]*(.*)$/.exec(match[3]);
+        if (note === null)
+            continue;
+        seen.add(file);
+        found.push({ file, line: Number(match[2]), text: clip(note[1].replace(/\s*(\*\/|-->)\s*$/, "").trim(), 120) });
+        if (found.length === limit)
+            break;
+    }
+    return found;
+}
+/** The TODO search: no colour and no column whatever the person's git config says, NUL after each file name. */
+export const TODO_GREP_ARGS = ["-c", "grep.column=false", "grep", "--no-color", "-z", "-n", "-I", "-w", "--max-count=1", "-E", "TODO|FIXME"];
+/** 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", [...TODO_GREP_ARGS], { 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

@@ -3,7 +3,7 @@
  * the one command that updates it that way. Only the path is read: nothing is
  * run and nothing leaves the computer.
  */
-export type InstallKind = "npm" | "pnpm" | "bun" | "yarn" | "homebrew" | "npx" | "source";
+export type InstallKind = "npm" | "pnpm" | "bun" | "yarn" | "homebrew" | "npx" | "source" | "managed" | "desktop";
 export type InstallMethod = {
     kind: InstallKind;
     updateCommand: string;

package/dist/install-method.js

@@ -13,6 +13,10 @@ export const UPDATE_COMMANDS = {
     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 Toolroll app carries its own runtime and updates as a whole app, never through a package manager.
+    desktop: "Update from the Toolroll app",
 };
 /** 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 = {}) {
@@ -34,6 +38,10 @@ function installKind(bin, probe) {
     // by deploying from source, never from npm.
     if (path.includes("/staged-upgrades/browser-"))
         return "source";
+    if (/\.app\/Contents\/Resources\//.test(path))
+        return "desktop";
+    if (/\/staged-upgrades\/(release|rollback)-/.test(path))
+        return "managed";
     if (/\/Cellar\/toolroll\//i.test(path))
         return "homebrew";
     if (path.includes("/_npx/"))

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";
@@ -66,7 +67,16 @@ 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;
+        env?: Record<string, string | undefined>;
+        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 = {
@@ -106,6 +116,7 @@ export declare function runOperate(command: string, argv: readonly string[], wri
  * finding 27): exclusive, 0600, fsynced — file and directory both — so the
  * row only ever follows a durable secret. Throws on any failure. */
 export declare function writeLoginFileDurably(path: string, name: string, password: string): void;
+export declare function readUpConsoleUrl(dir: string): string | null;
 /**
  * The people allowed to agree to a scope.
  *

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";
@@ -73,7 +74,7 @@ import { sweepLiveLogs } from "./live.js";
 import { configPath, addRepos, removeRepos, updateRepos, loadRepos, loadProjectRegistry, updateProjectRegistry } from "./repos.js";
 import { deleteProject, holdingsWords, projectHoldings, projectRunning } from "./project-delete.js";
 import { pushPass } from "./push.js";
-import { chmodSync, closeSync, constants as fsConstants, existsSync, fstatSync, fsyncSync, openSync, readFileSync, readSync, realpathSync, unlinkSync, writeSync, writeFileSync, mkdirSync } from "node:fs";
+import { chmodSync, closeSync, constants as fsConstants, existsSync, fstatSync, fsyncSync, openSync, readFileSync, readSync, realpathSync, renameSync, unlinkSync, writeSync, writeFileSync, mkdirSync } from "node:fs";
 import { BRANCH_PREFIX, envTwins, envValue, existingOrFirst, namedPath, taskBranches } from "./names.js";
 import { createServer as createNetServer } from "node:net";
 import { spawn as spawnChild } from "node:child_process";
@@ -127,7 +128,7 @@ import { daemonLaunchCommand, daemonStatus, installReplacingLegacy, installedLeg
 import { bridgePass, clearBotToken, createTransport, followBridge, hashPairingCode, loadBotToken, mintPairingCode, redactToken, saveBotToken, PAIRING_TTL_MS, TOKEN_ENV, telegramHookSecret, telegramPushUrl, } from "./telegram.js";
 import { scanRepo } from "./capscan.js";
 import { computeGaps, describeCapability } from "./gaps.js";
-import { ask, askHidden, confirm, interactive } from "./prompt.js";
+import { ask, askHidden, confirm, interactive, underAgent } from "./prompt.js";
 import { runMateCli, answerContextLines } from "./mate-cli.js";
 import { confirmCoordinatorProposal, dismissCoordinatorProposal } from "./mate-doors.js";
 import { verifyApproverByPassword } from "./principal.js";
@@ -565,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.
@@ -725,6 +726,8 @@ export async function runOperate(command, argv, write, options = {}) {
             ...(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) {
@@ -939,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":
@@ -7660,6 +7665,102 @@ function openBrowser(url) {
         // A browser that will not open is a URL the greeting already printed.
     }
 }
+/** Where `up` last served its console, kept beside the database so `onboard` names the same address. */
+const UP_CONSOLE_FILE = "up-console.json";
+function recordUpConsoleUrl(dir, url, now) {
+    try {
+        const file = join(dir, UP_CONSOLE_FILE), temporary = `${file}.${process.pid}.tmp`;
+        writeFileSync(temporary, `${JSON.stringify({ url, at: now.toISOString() })}\n`, { mode: 0o600 });
+        renameSync(temporary, file);
+    }
+    catch {
+        // A display fact: a failed write only leaves onboard on the default port.
+    }
+}
+export function readUpConsoleUrl(dir) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(dir, UP_CONSOLE_FILE), "utf8"));
+        return typeof parsed.url === "string" && /^https?:\/\/[^\s]+$/.test(parsed.url) ? parsed.url.replace(/\/+$/, "") : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** How onboard says to sign in: the saved login file only while it still works (as `up` advertises it), else the
+ * account and its password; null only when there is no account yet. Never the password itself. */
+function onboardLogin(store, loginFile) {
+    const names = store.listApprovers().map(one => one.name);
+    const saved = readLoginFile(loginFile);
+    if (names.length === 0)
+        return saved === null ? null : { account: saved.name, file: loginFile }; // the next `up` adopts it
+    if (saved !== null && authenticateApprover(store, saved.name, saved.password).ok)
+        return { account: saved.name, file: loginFile };
+    return { account: names.length === 1 ? names[0] : null, file: null };
+}
+/**
+ * `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);
+    }
+    // The console where `up` last served, unless --port says otherwise.
+    const served = portGiven === undefined ? readUpConsoleUrl(dirname(context.databaseFile)) : null;
+    const home = seams.home ?? homedir();
+    const env = seams.env ?? process.env;
+    const loginFile = join(dirname(context.databaseFile), UP_LOGIN_FILE);
+    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: served ?? `http://127.0.0.1:${port}`,
+        login: onboardLogin(store, loginFile),
+        home,
+        worktrees: join(dirname(context.databaseFile), "worktrees"),
+        env,
+        version: PACKAGE_VERSION,
+        cwd: seams.cwd ?? process.cwd(),
+        // An agent's shell may be a terminal, but nobody answers y/N there.
+        interactive: seams.interactive ?? (interactive() && !underAgent(env)),
+        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 });
+            const topPath = top.code === 0 ? canonicalProject(top.stdout.trim()) : null;
+            if (topPath === null)
+                return null;
+            // A linked worktree's project is its main checkout: the folder whose .git is the common one.
+            const common = await gitRun("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], { cwd });
+            const commonDir = common.code === 0 ? common.stdout.trim() : "";
+            const main = basename(commonDir) === ".git" ? canonicalProject(dirname(commonDir)) : null;
+            return { top: topPath, main: main ?? topPath };
+        }),
+        enrolled: async (repo) => {
+            const registry = await loadProjectRegistry(registryPath);
+            return !("error" in registry) && registry.repos.includes(repo);
+        },
+        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");
@@ -7786,7 +7887,10 @@ async function upCommand(flags, context) {
     if (!reserved) {
         return fail(write, json, "up", "port-busy", `port ${port} is taken — another \`up\` or \`serve\` may already be running; stop it, or pick a different --port`, EXIT.refused);
     }
-    const canPrompt = !json && process.stdin.isTTY === true && process.stdout.isTTY === true;
+    // Under a coding agent nothing is asked and no secret is printed, even in a real terminal: what is shown lands in
+    // its transcript.
+    const agentRunning = underAgent(context.upSeams?.env ?? process.env);
+    const canPrompt = !json && !agentRunning && process.stdin.isTTY === true && process.stdout.isTTY === true;
     let runnerName = "";
     let runnerToken = "";
     let approver = null;
@@ -8099,6 +8203,12 @@ 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 = !agentRunning && (context.upSeams?.terminal ?? process.stdout.isTTY === true);
+    const upHandoff = buildHandoff({
+        url,
+        login: { account: approverPlan2.passwordFile === null ? approverPlan2.approver : loginAccount(approverPlan2.passwordFile) ?? approverPlan2.approver, file: approverPlan2.passwordFile },
+    });
+    recordUpConsoleUrl(dirname(context.databaseFile), url, clock());
     if (fatal === null) {
         if (json) {
             write(envelopeJson({
@@ -8111,8 +8221,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}`);
@@ -8137,8 +8256,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;

package/dist/prompt.d.ts

@@ -7,6 +7,12 @@
  */
 /** Whether asking is even possible: a human on both ends of the pipe. */
 export declare function interactive(): boolean;
+/**
+ * Whether a coding agent is running this command. An agent's shell can be a
+ * real terminal, yet whatever is printed lands in its transcript and nobody
+ * types at the prompt, so it is treated like no terminal at all.
+ */
+export declare function underAgent(env?: Record<string, string | undefined>): boolean;
 export declare function ask(question: string): Promise<string>;
 /** Like ask, but what is typed never echoes — passwords live here. */
 /**

package/dist/prompt.js

@@ -10,6 +10,18 @@ import { createInterface } from "node:readline";
 export function interactive() {
     return process.stdin.isTTY === true && process.stdout.isTTY === true;
 }
+/** Variables a coding agent sets for the commands it runs. CODEX_HOME and CODEX_API_KEY are a person's own settings. */
+const AGENT_VARIABLES = ["CLAUDECODE", "CLAUDE_CODE_ENTRYPOINT", "GEMINI_CLI", "CURSOR_AGENT", "OPENCODE"];
+const PERSON_CODEX_VARIABLES = new Set(["CODEX_HOME", "CODEX_API_KEY"]);
+/**
+ * Whether a coding agent is running this command. An agent's shell can be a
+ * real terminal, yet whatever is printed lands in its transcript and nobody
+ * types at the prompt, so it is treated like no terminal at all.
+ */
+export function underAgent(env = process.env) {
+    return Object.entries(env).some(([name, value]) => value !== undefined && value !== ""
+        && (AGENT_VARIABLES.includes(name) || (name.startsWith("CODEX_") && !PERSON_CODEX_VARIABLES.has(name))));
+}
 export function ask(question) {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     return new Promise(resolve => rl.question(question, answer => {

package/dist/releases.d.ts

@@ -16,6 +16,8 @@ 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 = {
@@ -74,3 +76,10 @@ export declare function runnerVersions(dir: string): RunnerVersion[];
 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

@@ -18,7 +18,9 @@ export const UPDATE_SWITCH_FILE = "update-check";
 export const RUNNER_VERSIONS_FILE = "runner-versions.json";
 export const CHECK_EVERY_MS = 24 * 60 * 60 * 1000;
 export const CHECK_TIMEOUT_MS = 5_000;
-export const REGISTRY_URL = "https://registry.npmjs.org/toolroll/latest";
+/** 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;
@@ -223,3 +225,14 @@ function writeAtomic(file, content) {
     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,8 +11,10 @@ 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;
@@ -53,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;
@@ -107,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;