toolroll 0.8.0 → 0.8.2

package/dist/checkout-cleanup.d.ts

@@ -0,0 +1,84 @@
+import { type CheckoutCleanup } from "./storage.js";
+import type { Store } from "./store.js";
+import { type WorktreePool } from "./worktree.js";
+/** A release candidate's checkout holds the build a deploy installs: kept a week after its task was done. */
+export declare const CANDIDATE_KEEP_MS: number;
+/** The worker's pass removes at most this many; a clean-up by hand has no cap. */
+export declare const AUTO_MAX = 20;
+export type KeepWhy = "in use" | "task not finished" | "waiting for review" | "release candidate" | "has changes" | "has commits" | "unreadable" | "git refused" | "not due yet" | "cleanup is off" | "no task";
+export type CheckoutItem = {
+    path: string;
+    repo: string;
+    branch: string;
+    taskId: string | null;
+    bytes: number;
+    releasedAt: string | null;
+    /** null: it goes. */
+    why: KeepWhy | null;
+    /** With "not due yet" or "release candidate": when it may go. */
+    dueAt?: string;
+};
+export type CheckoutPlan = {
+    at: string;
+    cleanup: CheckoutCleanup;
+    manual: boolean;
+    go: CheckoutItem[];
+    stay: CheckoutItem[];
+    /** Every checkout on disk. */
+    count: number;
+    totalBytes: number;
+    freeBytes: number;
+    waitingReview: number;
+    withChanges: number;
+};
+type Status = {
+    keep: KeepWhy | null;
+    taskId: string;
+    finishedAt: string | null;
+    dueAt?: string;
+};
+/** Where every task stands for cleanup, by task_ref id and by each branch it or its runs used. */
+export declare function taskStatuses(store: Store, now: Date): {
+    byRef: Map<number, Status>;
+    byBranch: Map<string, Status>;
+};
+/**
+ * What a clean-up would remove now, how much space it would free, and what stays and why. `manual` is a clean-up by
+ * hand (it doesn't wait for the setting); otherwise it is the worker's pass under the setting. Reads only.
+ */
+export declare function checkoutPlan(store: Store, pool: WorktreePool, now: Date, options: {
+    manual: boolean;
+    repo?: string;
+}): Promise<CheckoutPlan>;
+/** Names exactly what a preview would remove, so a confirmation removes that and nothing else. */
+export declare function previewDigest(plan: Pick<CheckoutPlan, "go">): string;
+export type CleanResult = {
+    removed: CheckoutItem[];
+    kept: {
+        path: string;
+        why: KeepWhy;
+    }[];
+    freed: number;
+};
+/**
+ * Remove what may go: the worker's pass (`manual` false: under the setting, at most AUTO_MAX, one repository) or a
+ * clean-up by hand (no cap, every repository). Each checkout is asked again right before it goes; each removal is in
+ * the ledger.
+ */
+export declare function cleanCheckouts(store: Store, pool: WorktreePool, now: () => Date, options: {
+    manual: boolean;
+    actor: string;
+    repo?: string;
+    only?: ReadonlySet<string>;
+}): Promise<CleanResult>;
+/** Throw away a checkout kept for its changes, on purpose; its branch stays. In the ledger. */
+export declare function discardCheckout(store: Store, pool: WorktreePool, path: string, now: Date, actor: string): Promise<{
+    ok: true;
+    bytes: number;
+} | {
+    ok: false;
+    message: string;
+}>;
+/** "Waiting for review", "Has changes" … as a sentence fragment for a person. */
+export declare function whyWords(item: Pick<CheckoutItem, "why" | "dueAt">): string;
+export {};

package/dist/checkout-cleanup.js

@@ -0,0 +1,245 @@
+/**
+ * Checkout cleanup (Settings → Storage, `toolroll storage clean`): which task checkouts can go, and removing them.
+ *
+ * A finished task's clean checkout goes as the setting says: when its task is complete or cancelled (the default),
+ * 2 days or a week after that, or never (only a clean-up by hand). A clean-up by hand doesn't wait for the setting.
+ * Only the working copy goes: its branch, and so every commit, stays, and a later lease of the branch makes a new one.
+ *
+ * Always kept: a checkout in use, one whose task isn't finished (on hold, failed, a revision under way), a result
+ * still waiting for review, a release candidate for a week after it was done (a deploy installs from it), a checkout
+ * with changes (files Toolroll wrote itself aside), and one with commits on no branch. A checkout no task names
+ * (adopted after a crash) goes only in a clean-up by hand. Every removal is in the ledger.
+ */
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { basename } from "node:path";
+import { taskBranches } from "./names.js";
+import { COMPLETION_ACTION } from "./result-completion.js";
+import { CLEANUP_CHOICES, bytesWords, diskBytes } from "./storage.js";
+import { worktreePath } from "./worktree.js";
+const DAY_MS = 86_400_000;
+/** A release candidate's checkout holds the build a deploy installs: kept a week after its task was done. */
+export const CANDIDATE_KEEP_MS = 7 * DAY_MS;
+/** The worker's pass removes at most this many; a clean-up by hand has no cap. */
+export const AUTO_MAX = 20;
+/** Git inspections at once. */
+const INSPECT_AT_ONCE = 8;
+const STRENGTH = { "in use": 5, "task not finished": 4, "waiting for review": 3, "release candidate": 2 };
+const strength = (one) => one === undefined ? -1 : one.keep === null ? 0 : STRENGTH[one.keep] ?? 1;
+const stronger = (a, b) => strength(b) > strength(a) || (strength(b) === 0 && strength(a) === 0 && (b.finishedAt ?? "") > (a.finishedAt ?? "")) ? b : a;
+/** Where every task stands for cleanup, by task_ref id and by each branch it or its runs used. */
+export function taskStatuses(store, now) {
+    const db = store.handle;
+    const refs = db.prepare(`SELECT r.id AS ref, r.external_id AS id, r.revision_of AS revision_of, t.state AS state, t.updated_at AS updated_at,
+      EXISTS (SELECT 1 FROM hold h WHERE h.task_ref = r.id) AS held,
+      EXISTS (SELECT 1 FROM run live WHERE live.task_ref = r.id AND live.finished_at IS NULL) AS live,
+      EXISTS (SELECT 1 FROM task_scope s WHERE s.task_id = r.external_id AND s.candidate IS NOT NULL) AS candidate
+    FROM task_ref r LEFT JOIN task t ON t.id = r.external_id AND r.backend = 'built-in'`).all();
+    const runs = db.prepare("SELECT id, task_ref, branch FROM run").all();
+    const refOfRun = new Map(runs.map(row => [Number(row["id"]), Number(row["task_ref"])]));
+    // The completion names its family's root; its run names the result it completes.
+    const completed = new Map();
+    const completedRef = new Map();
+    for (const row of db.prepare("SELECT task_id, run_id, at FROM action_ledger WHERE action = ?").all(COMPLETION_ACTION)) {
+        const at = String(row["at"]);
+        if (row["task_id"] !== null) {
+            const id = String(row["task_id"]);
+            if ((completed.get(id) ?? "") < at)
+                completed.set(id, at);
+        }
+        const ref = row["run_id"] === null ? undefined : refOfRun.get(Number(row["run_id"]));
+        if (ref !== undefined && (completedRef.get(ref) ?? "") < at)
+            completedRef.set(ref, at);
+    }
+    const byRef = new Map();
+    const byId = new Map();
+    const parentOf = new Map();
+    for (const row of refs) {
+        const ref = Number(row["ref"]);
+        const id = String(row["id"]);
+        const state = row["state"] === null ? null : String(row["state"]);
+        const updated = row["updated_at"] === null ? null : String(row["updated_at"]);
+        let status;
+        if (Number(row["live"]) === 1)
+            status = { keep: "in use", taskId: id, finishedAt: null };
+        else if (state === null || Number(row["held"]) === 1 || (state !== "done" && state !== "cancelled"))
+            status = { keep: "task not finished", taskId: id, finishedAt: null };
+        else if (state === "cancelled")
+            status = { keep: null, taskId: id, finishedAt: updated };
+        else {
+            const completedAt = [completed.get(id), completedRef.get(ref)].filter((one) => one !== undefined).sort().at(-1) ?? null;
+            if (Number(row["candidate"]) === 1) {
+                const since = completedAt ?? updated ?? now.toISOString();
+                const until = new Date(Date.parse(since) + CANDIDATE_KEEP_MS).toISOString();
+                status = until > now.toISOString() ? { keep: "release candidate", taskId: id, finishedAt: since, dueAt: until } : { keep: null, taskId: id, finishedAt: since };
+            }
+            else
+                status = completedAt === null ? { keep: "waiting for review", taskId: id, finishedAt: null } : { keep: null, taskId: id, finishedAt: completedAt };
+        }
+        byRef.set(ref, status);
+        byId.set(id, stronger(byId.get(id), status));
+        if (row["revision_of"] !== null)
+            parentOf.set(id, String(row["revision_of"]));
+    }
+    // A revision under way keeps what its ancestors worked on: it builds on their branch.
+    for (const [id, status] of byId) {
+        if (status.keep === null || status.keep === "release candidate")
+            continue;
+        const seen = new Set([id]);
+        for (let parent = parentOf.get(id); parent !== undefined && !seen.has(parent); parent = parentOf.get(parent)) {
+            seen.add(parent);
+            const lifted = { ...status, taskId: parent };
+            byId.set(parent, stronger(byId.get(parent), lifted));
+        }
+    }
+    for (const row of refs)
+        byRef.set(Number(row["ref"]), stronger(byRef.get(Number(row["ref"])), { ...byId.get(String(row["id"])), taskId: String(row["id"]) }));
+    const byBranch = new Map();
+    const note = (branch, status) => byBranch.set(branch, stronger(byBranch.get(branch), status));
+    for (const row of refs)
+        for (const branch of taskBranches(String(row["id"])))
+            note(branch, byRef.get(Number(row["ref"])));
+    for (const row of runs) {
+        if (row["branch"] === null)
+            continue;
+        const status = byRef.get(Number(row["task_ref"]));
+        if (status !== undefined)
+            note(String(row["branch"]), status);
+    }
+    return { byRef, byBranch };
+}
+/** Where one checkout's task stands: by its task, its branch, or (branch unknown) the name a lease of a branch would give it. */
+function statusOf(row, statuses) {
+    let found = stronger(row.taskRef === null ? undefined : statuses.byRef.get(row.taskRef), statuses.byBranch.get(row.branch));
+    if (found === undefined) {
+        const name = basename(row.path);
+        for (const [branch, status] of statuses.byBranch)
+            if (basename(worktreePath("/", row.repo, branch)) === name)
+                found = stronger(found, status);
+    }
+    return found;
+}
+/** Why a checkout stays before anyone looks at its files, or null: it may go (as far as its task and the setting say). */
+function keptFor(pool, row, statuses, now, cleanup) {
+    const status = statusOf(row, statuses);
+    const taskId = status?.taskId ?? null;
+    if (row.releasedAt === null || row.runner !== null || pool.inUse(row.path).held)
+        return { why: "in use", taskId };
+    if (status !== undefined && status.keep !== null)
+        return { why: status.keep, taskId, ...(status.dueAt === undefined ? {} : { dueAt: status.dueAt }) };
+    if (cleanup === "manual")
+        return { why: null, taskId };
+    // A checkout no task names (adopted after a crash, say) has no task to finish: only a clean-up by hand takes it.
+    if (status === undefined)
+        return { why: "no task", taskId };
+    if (cleanup === "finished")
+        return { why: null, taskId };
+    if (cleanup === "never")
+        return { why: "cleanup is off", taskId };
+    const days = CLEANUP_CHOICES.find(one => one.value === cleanup).days;
+    const since = [status.finishedAt, row.releasedAt].filter((one) => one !== null).sort().at(-1);
+    const dueAt = new Date(Date.parse(since) + days * DAY_MS).toISOString();
+    return dueAt > now.toISOString() ? { why: "not due yet", taskId, dueAt } : { why: null, taskId };
+}
+async function eachAtMost(items, limit, work) {
+    const out = new Array(items.length);
+    let next = 0;
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, async () => {
+        while (next < items.length) {
+            const at = next++;
+            out[at] = await work(items[at]);
+        }
+    }));
+    return out;
+}
+/**
+ * What a clean-up would remove now, how much space it would free, and what stays and why. `manual` is a clean-up by
+ * hand (it doesn't wait for the setting); otherwise it is the worker's pass under the setting. Reads only.
+ */
+export async function checkoutPlan(store, pool, now, options) {
+    const cleanup = store.checkoutCleanup();
+    const rows = store.listWorktrees().filter(row => existsSync(row.path) && (options.repo === undefined || row.repo === options.repo));
+    const sizes = diskBytes(rows.map(row => row.path));
+    const statuses = taskStatuses(store, now);
+    const items = await eachAtMost(rows, INSPECT_AT_ONCE, async (row) => {
+        const kept = keptFor(pool, row, statuses, now, options.manual ? "manual" : cleanup);
+        let why = kept.why;
+        if (why === null) {
+            const found = await pool.inspect(row.path);
+            why = found === "clean" ? null : found;
+        }
+        return { path: row.path, repo: row.repo, branch: row.branch, taskId: kept.taskId, bytes: sizes.get(row.path) ?? 0, releasedAt: row.releasedAt, why, ...(kept.dueAt === undefined ? {} : { dueAt: kept.dueAt }) };
+    });
+    const go = items.filter(one => one.why === null).sort((a, b) => b.bytes - a.bytes);
+    const stay = items.filter(one => one.why !== null).sort((a, b) => (a.why ?? "").localeCompare(b.why ?? "") || b.bytes - a.bytes);
+    return {
+        at: now.toISOString(), cleanup, manual: options.manual, go, stay,
+        count: items.length, totalBytes: items.reduce((sum, one) => sum + one.bytes, 0), freeBytes: go.reduce((sum, one) => sum + one.bytes, 0),
+        waitingReview: stay.filter(one => one.why === "waiting for review").length, withChanges: stay.filter(one => one.why === "has changes").length,
+    };
+}
+/** Names exactly what a preview would remove, so a confirmation removes that and nothing else. */
+export function previewDigest(plan) {
+    return createHash("sha256").update(plan.go.map(one => one.path).sort().join("\u0000"), "utf8").digest("hex").slice(0, 32);
+}
+/**
+ * Remove what may go: the worker's pass (`manual` false: under the setting, at most AUTO_MAX, one repository) or a
+ * clean-up by hand (no cap, every repository). Each checkout is asked again right before it goes; each removal is in
+ * the ledger.
+ */
+export async function cleanCheckouts(store, pool, now, options) {
+    const cleanup = store.checkoutCleanup();
+    if (!options.manual && cleanup === "never")
+        return { removed: [], kept: [], freed: 0 };
+    // `only`: the checkouts a person saw in the preview; nothing they didn't see goes.
+    const rows = store.listWorktrees().filter(row => existsSync(row.path) && (options.repo === undefined || row.repo === options.repo) && (options.only === undefined || options.only.has(row.path)));
+    let statuses = taskStatuses(store, now());
+    const sizes = new Map();
+    const wanted = (row, fresh) => {
+        // Right before a checkout goes, where its task stands is read afresh, and its size taken for the ledger.
+        if (fresh)
+            statuses = taskStatuses(store, now());
+        const go = keptFor(pool, row, statuses, now(), options.manual ? "manual" : cleanup).why === null;
+        if (go && fresh)
+            sizes.set(row.path, diskBytes([row.path]).get(row.path) ?? 0);
+        return go;
+    };
+    const pruned = await pool.prune(rows, wanted, options.manual ? Infinity : AUTO_MAX);
+    const removed = [];
+    for (const row of pruned.removed) {
+        const taskId = row.taskRef === null ? null : store.externalIdFor(row.taskRef);
+        const bytes = sizes.get(row.path) ?? 0;
+        removed.push({ path: row.path, repo: row.repo, branch: row.branch, taskId, bytes, releasedAt: row.releasedAt, why: null });
+        store.recordAction({ at: now().toISOString(), actor: options.actor, repo: row.repo, taskId, runId: null, action: "checkout removed", outcome: "removed",
+            source: options.manual ? "request" : "work", detail: `${basename(row.path)} (released ${row.releasedAt?.slice(0, 10) ?? "?"}, about ${bytesWords(bytes)}); branch ${row.branch} kept` });
+    }
+    return { removed, kept: pruned.kept, freed: removed.reduce((sum, one) => sum + one.bytes, 0) };
+}
+/** Throw away a checkout kept for its changes, on purpose; its branch stays. In the ledger. */
+export async function discardCheckout(store, pool, path, now, actor) {
+    const bytes = existsSync(path) ? diskBytes([path]).get(path) ?? 0 : 0;
+    const done = await pool.discardChanges(path);
+    if (!done.ok)
+        return done;
+    const taskId = done.row.taskRef === null ? null : store.externalIdFor(done.row.taskRef);
+    store.recordAction({ at: now.toISOString(), actor, repo: done.row.repo, taskId, runId: null, action: "checkout discarded", outcome: "removed", source: "request",
+        detail: `${basename(path)} and its uncommitted changes (about ${bytesWords(bytes)}); branch ${done.row.branch} kept` });
+    return { ok: true, bytes };
+}
+/** "Waiting for review", "Has changes" … as a sentence fragment for a person. */
+export function whyWords(item) {
+    switch (item.why) {
+        case null: return "goes";
+        case "in use": return "in use";
+        case "task not finished": return "its task isn't finished";
+        case "waiting for review": return "its result is waiting for review";
+        case "release candidate": return `release candidate, kept until ${item.dueAt?.slice(0, 10) ?? "a week after"}`;
+        case "has changes": return "has changes";
+        case "has commits": return "has commits on no branch";
+        case "unreadable": return "git couldn't read it";
+        case "git refused": return "git wouldn't remove it";
+        case "not due yet": return `due ${item.dueAt?.slice(0, 10) ?? "later"}`;
+        case "cleanup is off": return "automatic cleanup is off";
+        case "no task": return "no task names it; only a clean-up by hand removes it";
+    }
+}

package/dist/daemon.d.ts

@@ -148,8 +148,12 @@ export declare function installLaunchdService(definition: ServiceDefinition, run
 /** Replace a file whole: a flushed temporary beside it, renamed over it, and the directory flushed, so a crash
  * leaves the old text or the new, never a torn one. */
 export declare function writeFileDurably(file: string, content: string | Uint8Array, mode?: number): void;
-/** Explicit stop: unload AND disable, so nothing relaunches it until a person installs again. */
-export declare function stopLaunchdService(definition: ServiceDefinition, run: SupervisorRunner): Promise<{
+/** Explicit stop: unload AND disable, so nothing relaunches it until a person installs again. `waitMs` is how long
+ * the job may take to leave launchd (5 s by default; a watch's `toolroll up` can take 45 s to exit). */
+export declare function stopLaunchdService(definition: ServiceDefinition, run: SupervisorRunner, wait?: {
+    waitMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<{
     ok: true;
     wasLoaded: boolean;
 } | {

package/dist/daemon.js

@@ -52,12 +52,12 @@ export function definitionDigest(unitContent) {
  * appears to succeed, then the pending bootout removes the new job too. Wait
  * for the observable supervisor boundary before loading the replacement.
  */
-async function waitForLaunchdBootout(run, service, attempts = 50) {
+async function waitForLaunchdBootout(run, service, attempts = 50, sleep = ms => new Promise(resolve => setTimeout(resolve, ms))) {
     for (let attempt = 0; attempt < attempts; attempt += 1) {
         const status = await run("launchctl", ["print", service]);
         if (status.code !== 0)
             return true;
-        await new Promise(resolve => setTimeout(resolve, 100));
+        await sleep(100);
     }
     return false;
 }
@@ -406,8 +406,9 @@ export function writeFileDurably(file, content, mode = 0o600) {
         }
     }
 }
-/** Explicit stop: unload AND disable, so nothing relaunches it until a person installs again. */
-export async function stopLaunchdService(definition, run) {
+/** Explicit stop: unload AND disable, so nothing relaunches it until a person installs again. `waitMs` is how long
+ * the job may take to leave launchd (5 s by default; a watch's `toolroll up` can take 45 s to exit). */
+export async function stopLaunchdService(definition, run, wait = {}) {
     const service = `gui/${launchdUid()}/${definition.label}`;
     const disabled = await run("launchctl", ["disable", service]);
     if (disabled.code !== 0)
@@ -415,7 +416,7 @@ export async function stopLaunchdService(definition, run) {
     const modern = await run("launchctl", ["bootout", service]);
     if (modern.code !== 0)
         await run("launchctl", ["unload", definition.unitPath]);
-    if (!(await waitForLaunchdBootout(run, service)))
+    if (!(await waitForLaunchdBootout(run, service, Math.ceil((wait.waitMs ?? 5000) / 100), wait.sleep)))
         return { ok: false, message: `launchctl did not stop ${definition.label}; the service is still loaded` };
     return { ok: true, wasLoaded: modern.code === 0 };
 }

package/dist/first-run.d.ts

@@ -9,14 +9,17 @@ export type FirstRunAction = {
     kind: "command";
     command: string;
 };
+/** `checking`: the answer is not in yet, so the step is shown neither done nor to do. */
 export type FirstRunStep = {
     key: "agent" | "project" | "task";
     title: string;
     done: boolean;
     action: FirstRunAction | null;
+    checking?: true;
 };
+/** agentSignedIn is null until this machine's first sign-in check has answered. */
 export type FirstRunFacts = {
-    agentSignedIn: boolean;
+    agentSignedIn: boolean | null;
     projects: number;
     hasTask: boolean;
     firstResultAt: string | null;
@@ -46,8 +49,11 @@ 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. */
+/** `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. */

package/dist/first-run.js

@@ -15,7 +15,8 @@ export function firstRunSteps(facts) {
         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 } },
+        facts.agentSignedIn === null ? { key: "agent", title: "Agent signed in", done: false, action: null, checking: true }
+            : { 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" } },
     ];
@@ -42,24 +43,27 @@ export function firstTaskSuggestions(found) {
     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. */
+/** `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 line of stdout.split("\n")) {
-        const match = /^(.+?):(\d+):(.*)$/.exec(line);
-        if (match === null || SKIPPED.test(match[1]) || seen.has(match[1]))
+    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(match[1]);
-        found.push({ file: match[1], line: Number(match[2]), text: clip(note[1].replace(/\s*(\*\/|-->)\s*$/, "").trim(), 120) });
+        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 = [];
@@ -74,7 +78,7 @@ export async function findFirstTasks(repo, runner = run) {
     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 });
+            const result = await runner("git", [...TODO_GREP_ARGS], { cwd: repo, timeoutMs: 5_000 });
             if (result.code === 0 || result.stdout !== "")
                 todos = parseTodoLines(result.stdout);
         }

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" | "managed";
+export type InstallKind = "npm" | "pnpm" | "bun" | "yarn" | "homebrew" | "npx" | "source" | "managed" | "desktop";
 export type InstallMethod = {
     kind: InstallKind;
     updateCommand: string;

package/dist/install-method.js

@@ -15,6 +15,8 @@ export const UPDATE_COMMANDS = {
     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 = {}) {
@@ -36,6 +38,8 @@ 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))

package/dist/mcp.js

@@ -1,5 +1,6 @@
 import { TASK_SCOPE_TEXT_SCHEMA } from "./task-text.js";
 import { dirname, join } from 'node:path';
+import { statSync } from 'node:fs';
 import { repositoryContextRead } from './repository-context.js';
 import { ASSIGNMENT_TOOLS, assignmentForCoordinator } from "./assignment-adapters.js";
 /**
@@ -367,12 +368,30 @@ function proposeTools() {
         make("answer", "Propose an answer to an open decision you read with get_decision, with a rationale. The approver confirms where every consequence and the builder's recommendation are shown; an irreversible option needs their explicit confirmation.", { decision: { type: "integer", minimum: 1 }, option: { type: "string", minLength: 1, maxLength: 64 }, rationale: { type: "string", maxLength: 400 } }, ["decision", "option", "rationale"]),
     ];
 }
+function fileIdentity(path) {
+    if (path === null)
+        return null;
+    try {
+        const at = statSync(path);
+        return { path, dev: at.dev, ino: at.ino };
+    }
+    catch {
+        return null;
+    }
+}
+/** Still the same file at the same path: not moved aside, deleted, or replaced by a rename. */
+function sameFile(was) {
+    const now = fileIdentity(was.path);
+    return now !== null && now.dev === was.dev && now.ino === was.ino;
+}
 /** Serve until EOF. The store is already open through the non-migrating
  * door; the token was startup-verified by the caller (and dies here again
  * if it does not hold). */
 export function serveMcp(store, token, io, clock = () => new Date(), enrolled = null, evidenceRoot) {
     /** Per connection: which decisions this credential read in full (v3). */
     const readDecisions = new Set();
+    /** The database file this server opened, by identity (null in memory). */
+    const database = fileIdentity(store.databaseFile());
     const auth = authenticateCoordinator(store, token);
     if (!auth.ok) {
         return {
@@ -414,6 +433,13 @@ export function serveMcp(store, token, io, clock = () => new Date(), enrolled =
         tools: TOOLS.map(tool => ({ name: tool.name, description: tool.description, inputSchema: tool.inputSchema })),
     });
     const callTool = (id, era, params) => {
+        // A restore or rollback puts a different file at the database's path: this server's connection still reads and
+        // writes the one it replaced, so it answers nothing more and exits (the agent starts it again on the new one).
+        if (database !== null && !sameFile(database)) {
+            error(id, -32000, "the database was replaced underneath this server (a Toolroll restore or rollback) — restart it");
+            io.exit(0);
+            return;
+        }
         // ONE snapshot per call (review finding 3): the version check, the
         // credential re-read, and every data read share a transaction, so a
         // concurrent migration cannot slip between them; filing's own

package/dist/operate.d.ts

@@ -22,10 +22,6 @@ export declare const EXIT: {
     readonly usage: 2;
     readonly refused: 3;
 };
-/** Storage retention: how long a finished task's clean checkout is kept after it was let go, and a result marked
- * complete's or a release candidate's after it was (its checkout holds the build a deploy installs). */
-export declare const CHECKOUT_KEEP_MS: number;
-export declare const RESULT_KEEP_MS: number;
 export type OperateOptions = {
     /** Native-shell proof key, passed in memory rather than command-line arguments. */
     desktopIdentity?: string;
@@ -72,6 +68,7 @@ export type OperateOptions = {
     /** 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;
     };
 };
@@ -115,6 +112,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.
  *