toolroll 0.9.88 → 0.9.90

package/dist/surface.js

@@ -431,6 +431,13 @@ const GUIDE_ROWS = [
     operator("up", "console + worker + browser, one command"),
     operator("onboard", "add this repository, report signed-in agents, install or --remove the operator skill (--yes), offer the starter flows (--starter <ids>), and print the handoff"),
     operator("daemon", "install the loop under the OS service manager"),
+    operator("background on", "keep this computer's Toolroll running: a login item that starts `up --laptop` when you log in; hands over from the `up` this terminal runs and puts everything back if the service doesn't answer (--port)"),
+    operator("background off", "stop running in the background: unloads and removes only Toolroll's own login item"),
+    operatorRead("background show", "whether Toolroll runs in the background here, whether it is running now, and any other service on this database"),
+    operator("stop", "stop this computer's Toolroll after its running work is saved: the background service (until the next login), or the `up` running in a terminal"),
+    operator("open", "open this computer's Toolroll at a terminal, signed in: the terminal UI, or the browser with --web (starts it first when it isn't running); never prints a sign-in link"),
+    { ...operatorRead("welcome", "the three steps to a first result (agent, project, first task) as the console's welcome shows them; at a terminal it walks them one at a time"), flags: [jsonFlag, dbFlag] },
+    operator("password set", "set this computer's first password, typed twice at your own terminal (never a flag, file or environment variable); every session signs in again and local mode stays on"),
     { ...operatorRead("doctor", "check that Toolroll's service holds no key, token or password a build could read; names what it finds and the steps to fix it, never a value, and changes nothing"), flags: [jsonFlag] },
 ];
 /**
@@ -450,7 +457,7 @@ const REMOTE_NO = [
     // Workers, the loop and the services that run here.
     "claim", "heartbeat", "worker release", "reap", "tick", "build", "reconcile",
     "runner register", "runner retire", "runner bind", "runner capacity", "coordinator mint", "coordinator revoke", "mcp", "outbox deliver", "peek",
-    "serve", "serve check-public", "watch", "up", "onboard", "daemon", "doctor", "bridge", "setup show", "setup clear",
+    "serve", "serve check-public", "watch", "up", "onboard", "daemon", "background on", "background off", "background show", "stop", "open", "welcome", "password set", "doctor", "bridge", "setup show", "setup clear",
     // Provider keys and model tools on this machine.
     "providers", "keys status", "keys set", "keys clear", "keys verify", "keys auth", "models check", "models update", "models watch",
     // Publication and release.
@@ -497,6 +504,38 @@ export const REMOTE_POLICY = new Map([
 ]);
 /** How many times each invocation was classified — the contract test refuses a row stated twice. */
 export const REMOTE_POLICY_COUNT = REMOTE_NO.length + REMOTE_STEP_UP.length + REMOTE_YES.length;
+/**
+ * Easy-start C3: the commands a laptop's local owner may run through the terminal UI (local-owner.ts runAsLocalOwner),
+ * each with the act it is; every other row (and every command with no row) is refused to the local owner before any
+ * command code runs. Credential, people, policy and infrastructure commands are never here.
+ */
+const LOCAL_ALLOW = {
+    // Reads.
+    pulls: "read", graph: "read", repos: "read", status: "read", ready: "read", gaps: "read", contract: "read", "skills list": "read", "skills get": "read",
+    "task list": "read", "task show": "read", "task state": "read", "task wait": "read", "check-progress": "read", "review show": "read", welcome: "read",
+    // Acts (plan C1's list).
+    "task add": "file-task",
+    chat: "lead-send",
+    "task steer": "lead-send",
+    "task approve": "approve-plan",
+    decide: "answer-question",
+    "task stop": "stop-run",
+    "task pause": "pause-run",
+    "task hold": "pause-run",
+    "task resume": "resume-run",
+    "task continue": "resume-run",
+    "task unhold": "resume-run",
+    "task complete": "complete-task",
+    "task revise": "request-revision",
+    "task archive": "archive-task",
+    "task restore": "archive-task",
+    "repos add": "add-project",
+};
+/** Every guide row's local-owner mark, by invocation: `allow` with its act, else `deny`. Exported for the inventory test. */
+export const LOCAL_POLICY = new Map(GUIDE_ROWS.map(row => [row.invocation,
+    Object.prototype.hasOwnProperty.call(LOCAL_ALLOW, row.invocation) ? { local: "allow", act: LOCAL_ALLOW[row.invocation] } : { local: "deny" }]));
+/** The invocations LOCAL_ALLOW names, for the inventory test (one naming no row is stale). */
+export const LOCAL_ALLOWED_INVOCATIONS = Object.keys(LOCAL_ALLOW);
 /** Every declared command, in guide order, paired with the schema of its `--json` answer (src/contracts/cli.ts).
  * An unclassified row is "no": nothing runs remotely by omission. */
 export const COMMAND_ENTRIES = commandEntries(GUIDE_ROWS.map(row => ({ ...row, remote: REMOTE_POLICY.get(row.invocation) ?? "no" })));

package/dist/task-text.d.ts

@@ -23,3 +23,9 @@ export declare function validateTaskText(fields: {
     outOfScope?: string | null;
     touches?: readonly string[];
 }): TaskTextRefusal | null;
+/**
+ * A title that fits: words longer than the title limit are cut at the last whole word that fits, with an ellipsis,
+ * never mid-word (one unbroken word longer than half the limit is the only thing cut inside a word). Whitespace runs
+ * read as one space. Text within the limit is returned as it is.
+ */
+export declare function titleWithin(text: string, max?: number): string;

package/dist/task-text.js

@@ -41,3 +41,20 @@ export function validateTaskText(fields) {
     const bad = validateScopeText(fields);
     return bad === null ? null : refuse("bad-goal", bad.message);
 }
+/**
+ * A title that fits: words longer than the title limit are cut at the last whole word that fits, with an ellipsis,
+ * never mid-word (one unbroken word longer than half the limit is the only thing cut inside a word). Whitespace runs
+ * read as one space. Text within the limit is returned as it is.
+ */
+export function titleWithin(text, max = TASK_TEXT_LIMITS.title) {
+    if (text.length <= max)
+        return text;
+    const words = text.replace(/\s+/g, " ").trim();
+    if (words.length <= max)
+        return words;
+    const room = words.slice(0, max - 1);
+    // The room ends at a whole word when the next character is a space; else back to the last space in it.
+    const space = words[max - 1] === " " ? room.length : room.lastIndexOf(" ");
+    const cut = (space >= Math.floor(max / 2) ? room.slice(0, space) : room).replace(/[\s,;:.\-–—]+$/u, "");
+    return `${cut}…`;
+}

package/dist/teardown-git.js

@@ -20,6 +20,7 @@ import { basename, delimiter, dirname, isAbsolute, join, resolve } from "node:pa
 import { run } from "./exec.js";
 import { ENV, ENV_ALLOWLIST } from "./remote-main.js";
 import { WORKTREE_TIMEOUT_MS } from "./worktree.js";
+import { FOLDER_DIDNT_ANSWER, folderAnswers } from "./folder-gate.js";
 /** Fixed on every teardown command, ahead of its own arguments. */
 export const TEARDOWN_FLAGS = [
     "--no-optional-locks", "-c", "core.hooksPath=/dev/null", "-c", "core.fsmonitor=false", "-c", "protocol.ext.allow=never",
@@ -346,8 +347,16 @@ function gitDirsOf(checkout) {
     catch {
         return null;
     }
+    // Where the checkout's own files point (a build can write both): read, in the console, only while that folder
+    // answered a look lately, and never vouched for by the checkout pool's spelling (folder-gate.ts). Held back: not one
+    // git would read the same way, so every caller refuses.
+    if (gitdir !== join(checkout, ".git") && !folderAnswers(gitdir, true))
+        return null;
     const named = regularFile(join(gitdir, "commondir"))?.trim();
-    return { gitdir, common: named === undefined || named === "" ? gitdir : resolve(gitdir, named) };
+    const common = named === undefined || named === "" ? gitdir : resolve(gitdir, named);
+    if (common !== gitdir && !folderAnswers(common, true))
+        return null;
+    return { gitdir, common };
 }
 /** What includeIn answers when Git didn't finish parsing the file in time: still a refusal, named as what it is. */
 export const INCLUDE_PARSE_TIMED_OUT = "Git didn't finish reading it in time";
@@ -1062,6 +1071,9 @@ export function checkoutGit(inner = run, mode = "build", binding = {}) {
         if (file !== "git")
             return inner(file, args, options);
         const cwd = options?.cwd;
+        // In the console, a checkout whose folder hasn't answered a look lately is not read on its thread (folder-gate.ts).
+        if (cwd !== undefined && !folderAnswers(cwd))
+            return refused(FOLDER_DIDNT_ANSWER);
         if (cwd === undefined || checkoutIncludes(cwd))
             return refused("the checkout's git config includes another file, or couldn't be read as a plain file");
         // git-lfs also reads .lfsconfig from the checkout: one that names an extension (a command it would run) is refused.
@@ -1158,6 +1170,9 @@ export function viewedGitSync(cwd, args, options = {}) {
     const expire = () => { if (limit !== undefined && limit() <= 0)
         throw new Error("the read's deadline passed"); };
     expire();
+    // In the console, a checkout whose folder hasn't answered a look lately is not read on its thread (folder-gate.ts).
+    if (!folderAnswers(cwd))
+        throw new Error(FOLDER_DIDNT_ANSWER);
     if (checkoutIncludes(cwd, gitFile, limit))
         throw new Error("the checkout's git config includes another file, or couldn't be read as a plain file");
     expire();

package/dist/telegram-lead.js

@@ -285,6 +285,8 @@ export function applyProposalTap(store, binding, token, message, repos, options,
         return { effects, confirmed: false, ignored: true };
     }
     const outcome = confirmLeadProposal(store, who, proposal.id, now, {
+        // The paired phone speaks for its account's full authority (pairing is a full session's act).
+        authority: "full",
         via: "telegram",
         evidenceRoot: options.evidenceRoot,
         confirm: action.phase === "yes",

package/dist/terminal-text.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Text someone else wrote, made safe to print on a terminal: the one sanitizer the live view, `peek` and the terminal
+ * UI share. Escape sequences in every form go (CSI in 7- or 8-bit form, OSC such as hyperlinks and title changes,
+ * every other ESC sequence), and with them every C0 and C1 control character (a carriage return that would
+ * overwrite a line, a backspace, a bell), every invisible format character and bidi override; a tab becomes a space.
+ * Pure: no imports, so the terminal UI's bundle carries it as is.
+ */
+/** One line: controls, escapes and bidi overrides out; tabs to spaces. A newline is a control here too. */
+export declare function cleanTerminalLine(text: string): string;
+/** Any text for the terminal UI: each line cleaned as above, its newlines kept (a lone carriage return is not one). */
+export declare function terminalText(text: string): string;

package/dist/terminal-text.js

@@ -0,0 +1,26 @@
+/**
+ * Text someone else wrote, made safe to print on a terminal: the one sanitizer the live view, `peek` and the terminal
+ * UI share. Escape sequences in every form go (CSI in 7- or 8-bit form, OSC such as hyperlinks and title changes,
+ * every other ESC sequence), and with them every C0 and C1 control character (a carriage return that would
+ * overwrite a line, a backspace, a bell), every invisible format character and bidi override; a tab becomes a space.
+ * Pure: no imports, so the terminal UI's bundle carries it as is.
+ */
+/** Bidi embedding, override and isolate controls. */
+const BIDI_CONTROLS = /[‪-‮⁦-⁩]/g;
+/** One line: controls, escapes and bidi overrides out; tabs to spaces. A newline is a control here too. */
+export function cleanTerminalLine(text) {
+    return text
+        // Escape sequences in every form: CSI (7- or 8-bit, any parameter bytes including ':'), OSC, and the rest.
+        .replace(/(?:\x1b\[|\u009b)[0-?]*[ -/]*[@-~]/g, "")
+        .replace(/(?:\x1b\]|\u009d)[^\x07\x1b\u009c]*(?:\x07|\x1b\\|\u009c)?/g, "")
+        .replace(/\x1b[ -/]*[0-~]/g, "")
+        .replace(/\t/g, " ")
+        .replace(/[\x00-\x1f\x7f-\x9f]/g, "")
+        // Every invisible format character (zero-width, direction marks and overrides, joiners, BOM): never shown.
+        .replace(/\p{Cf}/gu, "")
+        .replace(BIDI_CONTROLS, "");
+}
+/** Any text for the terminal UI: each line cleaned as above, its newlines kept (a lone carriage return is not one). */
+export function terminalText(text) {
+    return text.split("\n").map(cleanTerminalLine).join("\n");
+}

package/dist/toolroll-update.d.ts

@@ -1,6 +1,7 @@
 import type { DatabaseSync } from "node:sqlite";
 import { type UpdateWaiting } from "./desktop-update.js";
 import { type SupervisorRunner } from "./daemon.js";
+import { type ProcessProbe } from "./runner-process.js";
 import { RUNTIME_PHASES, type RuntimeUpdateJournalRecord } from "./contracts/update-journal.js";
 export declare const PROVENANCE_REPOSITORY = "https://github.com/ap9000/toolroll";
 export declare const PROVENANCE_WORKFLOW = ".github/workflows/publish.yml";
@@ -226,13 +227,19 @@ type Exec = (command: string, args: string[], options?: {
     stderr: string;
 };
 export declare function currentRuntime(version: string): RuntimeRef;
-/** Seams for tests: npm, node and ps (`exec`), launchctl (`run`), process liveness, and launchd's waits (`sleep`). */
+/** Seams for tests: npm, node and ps (`exec`), launchctl or systemctl (`run`), process liveness, and launchd's waits
+ * (`sleep`); for the laptop service on Linux, the platform, process identity (`probe`), the host name its process
+ * record names, and the console proof (`consoleProof`: the database's console is live at that version). */
 export type MachineSeams = {
     exec?: Exec;
     run?: SupervisorRunner;
     alive?: (pid: number) => boolean;
     sleep?: (ms: number) => Promise<void>;
     execPath?: string;
+    platform?: NodeJS.Platform;
+    probe?: ProcessProbe;
+    host?: string;
+    consoleProof?: (databaseFile: string, version: string) => Promise<boolean>;
 };
 export declare function machineSystem(home?: string, env?: Record<string, string | undefined>, seams?: MachineSeams): UpdateSystem;
 /** npm's own Sigstore verifier. Found from npm itself (the `npm` on PATH, then the one beside node), never only from

package/dist/toolroll-update.js

@@ -26,7 +26,7 @@ import { inReadOnlyRequest } from "./read-only-request.js";
 import { createHash, randomUUID, verify as signatureValid, X509Certificate } from "node:crypto";
 import { spawnSync } from "node:child_process";
 import { accessSync, chmodSync, closeSync, constants, copyFileSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, readlinkSync, realpathSync, renameSync, rmSync, statfsSync, statSync, symlinkSync, writeFileSync } from "node:fs";
-import { homedir, userInfo } from "node:os";
+import { homedir, hostname, userInfo } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { createRequire } from "node:module";
@@ -36,8 +36,10 @@ import { processMayBeAlive } from "./process-liveness.js";
 import { removeTerminalUpdateGate } from "./terminal-catalog.js";
 import { assertCodingUpdateStopped, backupCodingCatalog, codingCatalogExists, releaseStaleCodingOwner, removeCodingUpdateGate } from "./coding-update.js";
 import { installLaunchdService, launchdPlist, stopLaunchdService, writeFileDurably } from "./daemon.js";
+import { LAPTOP_LABEL_DARWIN, LAPTOP_LABEL_LINUX, unitFlag } from "./laptop-service.js";
+import { processGone, readRunnerProcessRecord, realProcessProbe, recordStandsFor, RUNNER_PROCESS_DIR } from "./runner-process.js";
 import { NAME } from "./names.js";
-import { orphanKey, updateSafeSchema, V117_RENAMED_COLUMNS, V117_RENAMED_TABLES, V118_MERGED_TABLES, V119_ADDED_COLUMNS, V120_ADDED_COLUMNS, V121_ADDED_COLUMNS, V122_ADDED_COLUMNS, V123_ADDED_COLUMNS, V125_ADDED_COLUMNS, V126_ADDED_COLUMNS, V128_ADDED_COLUMNS, V129_ADDED_COLUMNS, V134_ADDED_COLUMNS, V135_ADDED_COLUMNS, V138_ADDED_COLUMNS, V143_ADDED_COLUMNS } from "./store.js";
+import { orphanKey, updateSafeSchema, V117_RENAMED_COLUMNS, V117_RENAMED_TABLES, V118_MERGED_TABLES, V119_ADDED_COLUMNS, V120_ADDED_COLUMNS, V121_ADDED_COLUMNS, V122_ADDED_COLUMNS, V123_ADDED_COLUMNS, V125_ADDED_COLUMNS, V126_ADDED_COLUMNS, V128_ADDED_COLUMNS, V129_ADDED_COLUMNS, V134_ADDED_COLUMNS, V135_ADDED_COLUMNS, V138_ADDED_COLUMNS, V143_ADDED_COLUMNS, V147_ADDED_COLUMNS } from "./store.js";
 import { isNewer, REGISTRY } from "./releases.js";
 import { markNeverIndex } from "./never-index.js";
 import { readRuntimeUpdateJournal, RUNTIME_PHASES, RUNTIME_UPDATE_STEPS, stagedStartedAt, updaterStartingOf } from "./contracts/update-journal.js";
@@ -409,7 +411,9 @@ const HISTORY_RULES = {
     // v126: a receipt's state, acceptance time and held item, a trigger's credential generation and turned-away count,
     // and who made a card read none, 0, or none. A table with an earlier rule (flow_trigger's v115 move) keeps it too.
     // v128: a lead message's pending flag reads waiting exactly for a team queue's unadmitted operator message.
-    ...Object.fromEntries(Object.entries(addedColumns(V119_ADDED_COLUMNS, V120_ADDED_COLUMNS, V121_ADDED_COLUMNS, V122_ADDED_COLUMNS, V123_ADDED_COLUMNS, V125_ADDED_COLUMNS, V126_ADDED_COLUMNS, V128_ADDED_COLUMNS, V129_ADDED_COLUMNS, V134_ADDED_COLUMNS, V135_ADDED_COLUMNS, V138_ADDED_COLUMNS, V143_ADDED_COLUMNS))
+    // v147: an account's password flag reads set (1), a browser session reads full with no local binding or key, and the
+    // console record reads no key epoch.
+    ...Object.fromEntries(Object.entries(addedColumns(V119_ADDED_COLUMNS, V120_ADDED_COLUMNS, V121_ADDED_COLUMNS, V122_ADDED_COLUMNS, V123_ADDED_COLUMNS, V125_ADDED_COLUMNS, V126_ADDED_COLUMNS, V128_ADDED_COLUMNS, V129_ADDED_COLUMNS, V134_ADDED_COLUMNS, V135_ADDED_COLUMNS, V138_ADDED_COLUMNS, V143_ADDED_COLUMNS, V147_ADDED_COLUMNS))
         .map(([table, rule]) => [table, { ...EARLIER_RULES[table], ...rule }])),
 };
 /** The tables a migration may remove whole (v115's removed features). */
@@ -1541,7 +1545,7 @@ export function markWhatsNewSeen(stateDir) {
     durableJson(join(j.stageDir, "update.json"), j);
 }
 const exec = (command, args, options = {}) => spawnSync(command, args, { encoding: "utf8", timeout: options.timeout ?? 300_000, maxBuffer: 16 * 1024 * 1024, ...(options.cwd ? { cwd: options.cwd } : {}), ...(options.input !== undefined ? { input: options.input } : {}) });
-const LABELS = ["com.toolroll.browser", "com.standing-orders.browser"];
+const LABELS = ["com.toolroll.browser", "com.standing-orders.browser", LAPTOP_LABEL_DARWIN];
 export function currentRuntime(version) {
     return { version, dist: dirname(fileURLToPath(import.meta.url)) };
 }
@@ -1568,6 +1572,9 @@ require(input.verifier).verify(input.bundle, { certificateIssuer: input.issuer,
 export function machineSystem(home = homedir(), env = process.env, seams = {}) {
     const sh = seams.exec ?? exec;
     const supervise = seams.run ?? (async (file, args, options) => (await import("./exec.js")).run(file, args, options));
+    // Linux: the laptop service is a systemd user unit; nothing else here runs under systemd (watches use launchd's road).
+    if ((seams.platform ?? process.platform) === "linux")
+        return { ...machineSystem(home, env, { ...seams, platform: "darwin" }), ...systemdLaptopService(home, sh, supervise, seams) };
     const unitFor = (from) => {
         for (const label of LABELS) {
             const unit = join(home, "Library", "LaunchAgents", `${label}.plist`);
@@ -1807,3 +1814,143 @@ export function retireUpdateJob(id, home = homedir()) {
     }
     catch { /* none */ }
 }
+// ---- the laptop service under systemd (easy-start D) --------------------------------------------------------------
+/**
+ * The parts of the update's machine that differ for toolroll-up.service, the laptop service on Linux: finding the
+ * unit, which processes it runs, stopping it and proving its controller exited through the controller's own signed
+ * process record (by start identity, never a pid alone), starting it again, and the health check (the unit active,
+ * running the new runtime, and its console proved live at the new version). Every outside effect is `supervise`
+ * (systemctl), `sh` (ps) or a seam, so a test scripts all of it.
+ */
+function systemdLaptopService(home, sh, supervise, seams) {
+    const unitPath = join(home, ".config", "systemd", "user", `${LAPTOP_LABEL_LINUX}.service`);
+    const name = `${LAPTOP_LABEL_LINUX}.service`;
+    const probe = seams.probe ?? realProcessProbe;
+    const host = seams.host ?? hostname();
+    const mainPid = async () => {
+        const shown = await supervise("systemctl", ["--user", "show", "--property=MainPID", name]);
+        const pid = Number(/MainPID=(\d+)/.exec(shown.stdout)?.[1] ?? 0);
+        return shown.code === 0 && pid > 1 ? pid : null;
+    };
+    const active = async () => (await supervise("systemctl", ["--user", "is-active", name])).stdout.trim() === "active";
+    /** The processes the controller's signed record names, when that record is authentic for its registration and its
+     * `up` is the unit's main process by start identity. Null: no such proof (the stop then waits on the pid alone). */
+    const recorded = (unit, pid) => {
+        const db = unitFlag(readFileSync(unit, "utf8"), "linux", "--db");
+        if (db === null || !isAbsolute(db))
+            return null;
+        let names;
+        const folder = join(dirname(db), RUNNER_PROCESS_DIR);
+        try {
+            names = readdirSync(folder).filter(one => one.endsWith(".json"));
+        }
+        catch {
+            return null;
+        }
+        let handle = null;
+        try {
+            handle = new (sqlite().DatabaseSync)(db, { readOnly: true });
+            for (const file of names) {
+                const record = readRunnerProcessRecord(join(folder, file));
+                const up = record?.processes.find(one => one.role === "up" && one.pid === pid);
+                if (record === null || up === undefined)
+                    continue;
+                const row = handle.prepare("SELECT name, host, registered_at, credential_hash FROM runner WHERE name = ?").get(record.runner);
+                if (row === undefined)
+                    continue;
+                const holder = { runner: { name: String(row["name"]), host: String(row["host"]), registeredAt: String(row["registered_at"]) }, credentialHash: String(row["credential_hash"]) };
+                if (recordStandsFor(record, holder, host) !== null || probe.start(pid) !== up.started)
+                    continue;
+                return record.processes;
+            }
+        }
+        catch {
+            return null;
+        }
+        finally {
+            handle?.close();
+        }
+        return null;
+    };
+    return {
+        serviceUnit: from => { try {
+            return readFileSync(unitPath, "utf8").includes(from.dist) ? unitPath : null;
+        }
+        catch {
+            return null;
+        } },
+        // `daemon install` watches keep launchd's road; on Linux the update switches only the laptop service.
+        watchUnits: () => [],
+        serviceLoaded: async () => active(),
+        servicePids: async () => {
+            const pid = await mainPid();
+            if (pid === null)
+                return [];
+            const children = await supervise("pgrep", ["-P", String(pid)]);
+            return [pid, ...(children.code === 0 ? children.stdout.trim().split(/\s+/).map(Number).filter(one => Number.isSafeInteger(one) && one > 1) : [])];
+        },
+        stopService: async (unit) => {
+            const pid = await mainPid();
+            const processes = pid === null ? null : recorded(unit, pid);
+            const stopped = await supervise("systemctl", ["--user", "stop", name]);
+            if (stopped.code !== 0)
+                throw Error(`systemctl could not stop ${LAPTOP_LABEL_LINUX}: ${(stopped.stderr || `exit ${stopped.code}`).trim().split("\n")[0]}. Nothing was replaced.`);
+            if (processes === null)
+                return;
+            // The controller drains and exits; every process its record names must be proved gone before anything is replaced.
+            for (let waited = 0;; waited += 250) {
+                const left = processes.filter(one => !processGone(one, probe));
+                if (left.length === 0)
+                    return;
+                if (waited >= UP_EXIT_MS)
+                    throw Error(`Toolroll's background service is still running (process ${left.map(one => one.pid).join(", ")}) after it was stopped. Nothing was replaced.`);
+                await (seams.sleep ?? sleep)(250);
+            }
+        },
+        restartService: async () => {
+            // The switch rewrote the unit on disk: systemd reads it again before starting it.
+            const reload = await supervise("systemctl", ["--user", "daemon-reload"]);
+            if (reload.code !== 0)
+                throw Error(`systemctl daemon-reload failed: ${(reload.stderr || `exit ${reload.code}`).trim()}`);
+            const started = await supervise("systemctl", ["--user", "start", name]);
+            if (started.code !== 0)
+                throw Error(`systemctl could not start ${LAPTOP_LABEL_LINUX}: ${(started.stderr || `exit ${started.code}`).trim()}`);
+        },
+        healthy: async (j) => {
+            const version = sh(process.execPath, [join(j.to.dist, "bin.js"), "--version"], { timeout: 30_000 });
+            if (version.status !== 0 || version.stdout.trim() !== j.to.version)
+                return false;
+            for (const link of j.switched?.links ?? []) {
+                try {
+                    if (realpathSync(link.path) !== realpathSync(join(j.to.dist, "bin.js")))
+                        return false;
+                }
+                catch {
+                    return false;
+                }
+            }
+            if (!j.switched?.unit?.path)
+                return true;
+            if (!(await active()))
+                return false;
+            const pid = await mainPid();
+            if (pid === null || !sh("/bin/ps", ["-p", String(pid), "-o", "command="]).stdout.includes(j.to.dist))
+                return false;
+            return (seams.consoleProof ?? liveConsoleAt)(j.databaseFile, j.to.version);
+        },
+    };
+}
+/** The database's console is proved live (socket and HTTP) and says it is `version`. */
+async function liveConsoleAt(databaseFile, version) {
+    const { proveLiveConsole } = await import("./console-instance.js");
+    const handle = new (sqlite().DatabaseSync)(databaseFile, { readOnly: true });
+    try {
+        return (await proveLiveConsole(databaseFile, { handle }, version)).ok;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        handle.close();
+    }
+}

package/dist/tui-contract.d.ts

@@ -0,0 +1,118 @@
+/**
+ * What the terminal UI (src/tui, bundled into dist/tui.js) reads and asks for, and nothing more. The CLI side
+ * (tui-source.ts) implements it with in-process reads of this installation's database and with every write sent
+ * through `runOperate` as the local owner (local-owner.ts runAsLocalOwner), so the screen holds no authority of its
+ * own: a write the local owner may not make is refused there, and the screen shows the refusal's words.
+ *
+ * Types only, with no imports: both the CLI build (tsc) and the terminal UI bundle (esbuild) read this file.
+ */
+/** One task in the list, as the board says it. */
+export type TuiRow = {
+    readonly id: string;
+    readonly title: string;
+    /** The board's one status word (Needs you, Running, Ready, …). */
+    readonly status: string;
+    readonly detail: string;
+    readonly needsYou: boolean;
+    /** The attempt running now, if any: what Stop names. */
+    readonly liveRunId: number | null;
+    readonly repo: string | null;
+};
+/** A parked question on a task, answered by choosing one of its options. */
+export type TuiDecision = {
+    readonly id: number;
+    readonly question: string;
+    readonly options: readonly {
+        readonly id: string;
+        readonly label: string;
+    }[];
+};
+/** One task in full. */
+export type TuiTask = {
+    readonly id: string;
+    readonly title: string;
+    readonly status: string;
+    readonly detail: string;
+    /** The plan waiting for approval: its exact digest (what the yes binds) and every line of it. Null: none waits. */
+    readonly plan: {
+        readonly digest: string;
+        readonly lines: readonly string[];
+    } | null;
+    readonly liveRunId: number | null;
+    /** A finished result that can be marked Complete or sent back with a revision. */
+    readonly hasResult: boolean;
+    readonly decisions: readonly TuiDecision[];
+};
+/** The welcome's steps, as lines (welcome-facts.ts). */
+export type TuiSetup = {
+    readonly left: number;
+    readonly lines: readonly string[];
+};
+export type TuiSnapshot = {
+    readonly rows: readonly TuiRow[];
+    /** One line about what waits on the person, or null when nothing does. */
+    readonly needsYou: string | null;
+    /** The projects tasks can be filed in (the first is the default). */
+    readonly projects: readonly string[];
+    /** Whether the local owner has set a password (decides where a refusal leads). */
+    readonly passwordSet: boolean;
+};
+export type TuiAct = {
+    readonly kind: "new";
+    readonly text: string;
+    readonly repo: string | null;
+} | {
+    readonly kind: "approve";
+    readonly id: string;
+    readonly digest: string;
+} | {
+    readonly kind: "stop";
+    readonly id: string;
+    readonly runId: number;
+} | {
+    readonly kind: "revise";
+    readonly id: string;
+    readonly text: string;
+} | {
+    readonly kind: "complete";
+    readonly id: string;
+} | {
+    readonly kind: "answer";
+    readonly decision: number;
+    readonly option: string;
+};
+/** A write's answer: its words. `needsPassword`: refused because the local owner may not do it. */
+export type TuiActResult = {
+    readonly ok: true;
+    readonly message: string;
+    readonly id?: string;
+} | {
+    readonly ok: false;
+    readonly message: string;
+    readonly needsPassword: boolean;
+};
+/** The plane, as the screen sees it. */
+export interface TuiSource {
+    snapshot(): Promise<TuiSnapshot>;
+    task(id: string): Promise<TuiTask | null>;
+    /** The newest output lines of the task's live attempt (empty when none runs). */
+    live(id: string): readonly string[];
+    /** A counter that moves when the plane's work changes (the store's wake sequence). */
+    changed(): number;
+    act(act: TuiAct): Promise<TuiActResult>;
+    /** The welcome's steps, or null once setup is done. */
+    setup(): Promise<TuiSetup | null>;
+}
+/** What only the process that opened the screen knows: whether quitting stops its agents, the browser, the ask-once. */
+export interface TuiSession {
+    /** Quitting would stop the Toolroll this terminal started (no background service runs it). */
+    owned(): boolean;
+    /** Open this computer's browser on the console, signed in. Resolves with what to say. */
+    openBrowser(): Promise<string>;
+    /** Whether to ask, now, "Keep Toolroll running in the background?" (once per installation). */
+    shouldAskBackground(): boolean;
+    /** Record the answer; yes moves Toolroll to the background service. Resolves with what to say. */
+    answerBackground(yes: boolean): Promise<string>;
+}
+/** How the screen ended: leave as it is, stop the agents this terminal started, or keep them running in the background. */
+export type TuiExit = "leave" | "stop" | "keep";

package/dist/tui-contract.js

@@ -0,0 +1,9 @@
+/**
+ * What the terminal UI (src/tui, bundled into dist/tui.js) reads and asks for, and nothing more. The CLI side
+ * (tui-source.ts) implements it with in-process reads of this installation's database and with every write sent
+ * through `runOperate` as the local owner (local-owner.ts runAsLocalOwner), so the screen holds no authority of its
+ * own: a write the local owner may not make is refused there, and the screen shows the refusal's words.
+ *
+ * Types only, with no imports: both the CLI build (tsc) and the terminal UI bundle (esbuild) read this file.
+ */
+export {};

package/dist/tui-source.d.ts

@@ -0,0 +1,14 @@
+import type { OperateOptions } from "./operate.js";
+import type { ConnectionChecker } from "./provider-connection.js";
+import type { TuiSource } from "./tui-contract.js";
+export type TuiSourceOptions = {
+    databaseFile: string;
+    clock?: () => Date;
+    /** Passed to every runOperate (tests: a fixed clock, seams). */
+    operate?: OperateOptions;
+    /** The agents' sign-in check for the Setup screen (tests pass their own). */
+    check?: ConnectionChecker;
+};
+export declare function createTuiSource(options: TuiSourceOptions): TuiSource & {
+    close(): void;
+};