toolroll 0.9.89 → 0.9.90

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;
+};

package/dist/tui-source.js

@@ -0,0 +1,182 @@
+/**
+ * The terminal UI's view of this installation (tui-contract.ts TuiSource), in this process.
+ *
+ * Reads come straight from the database through a read-only handle (the task list and a task's own envelopes through
+ * `runOperate`, live output through peek's tail reader, the store's wake sequence as the change signal). Every write
+ * goes through `runOperate` inside runAsLocalOwner: the same commands, rows and refusals as the CLI, bound to local
+ * mode when each command opens the database, never to anything the screen says. Every command runs with --json, so
+ * nothing ever prompts on the terminal the screen owns.
+ */
+import { dirname, join } from "node:path";
+import { assignmentOf } from "./assignment.js";
+import { runAsLocalOwner } from "./local-owner.js";
+import { snapshotLiveRuns } from "./peek-cli.js";
+import { loadProjectRegistry } from "./repos.js";
+import { describeScope } from "./scope.js";
+import { localModeOf, openStoreReadOnly } from "./store.js";
+import { terminalText } from "./terminal-text.js";
+import { welcomeHere, welcomeLines } from "./welcome-facts.js";
+const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+const words = (value, fallback = "") => typeof value === "string" ? value : fallback;
+/** Text for the screen: whatever wrote it (an agent, a person, a project's name), escapes and controls never reach the
+ * terminal (terminal-text.ts). Every displayed string below goes through here; ids and digests are only acted on. */
+const shown = (value, fallback = "") => terminalText(words(value, fallback));
+/** What a refused write says, and whether it is a local-owner refusal (the screen then leads to a password). */
+function refusalOf(envelope) {
+    const message = shown(envelope.message, "That was refused.");
+    return { ok: false, message, needsPassword: envelope.reason === "refused" || envelope.reason === "machine-proof" || envelope.reason === "person-required" || /password/i.test(message) };
+}
+export function createTuiSource(options) {
+    const file = options.databaseFile;
+    const clock = options.clock ?? (() => new Date());
+    const evidenceRoot = join(dirname(file), "evidence");
+    const tails = new Map();
+    let reader = null;
+    const read = () => {
+        reader ??= openStoreReadOnly(file);
+        return reader;
+    };
+    /** One command as the local owner, with --json: its envelope (an unreadable answer reads as a refusal). */
+    async function command(argv) {
+        const [name = "", ...rest] = argv;
+        let out = "";
+        const { runOperate } = await import("./operate.js");
+        await runAsLocalOwner(() => runOperate(name, [...rest, "--json", "--db", file], text => { out += `${text}\n`; }, options.operate ?? {}));
+        try {
+            return record(JSON.parse(out.trim()));
+        }
+        catch {
+            const last = out.trim().split("\n").at(-1) ?? "";
+            try {
+                return record(JSON.parse(last));
+            }
+            catch {
+                return { ok: false, reason: "unreadable", message: "Toolroll's answer couldn't be read." };
+            }
+        }
+    }
+    let setupCache = null;
+    return {
+        async snapshot() {
+            const listed = await command(["task", "list"]);
+            const tasks = Array.isArray(listed["tasks"]) ? listed["tasks"] : [];
+            const rows = tasks.map(one => {
+                const row = record(one), status = record(row["status"]);
+                const views = Array.isArray(status["views"]) ? status["views"] : [];
+                return {
+                    id: words(row["id"], words(row["rootId"])), title: shown(row["title"]), status: shown(status["label"], words(row["state"])), detail: shown(status["detail"]),
+                    needsYou: views.includes("needs-you"), liveRunId: typeof row["liveRunId"] === "number" ? row["liveRunId"] : null, repo: typeof row["repo"] === "string" ? row["repo"] : null,
+                };
+            });
+            const waiting = rows.filter(one => one.needsYou);
+            const needsYou = waiting.length === 0 ? null : `${waiting.length === 1 ? "1 task needs" : `${waiting.length} tasks need`} you: ${waiting[0].title}`;
+            const registry = await loadProjectRegistry(join(dirname(file), "repos.json"));
+            const store = read();
+            const mode = store === null ? null : localModeOf(store);
+            const passwordSet = store !== null && mode !== null && store.accountOf(mode.owner)?.passwordSet === true;
+            return { rows, needsYou, projects: "error" in registry ? [] : registry.repos, passwordSet };
+        },
+        async task(id) {
+            const answer = await command(["task", "show", id]);
+            if (answer.ok !== true)
+                return null;
+            const task = record(answer["task"]), work = record(answer["work"]), status = record(work["status"]);
+            const store = read();
+            const scope = store === null ? null : store.getScope(id);
+            const plan = scope === null || scope.approvedDigest === scope.digest ? null : { digest: scope.digest, lines: describeScope(scope).map(line => terminalText(line)) };
+            let hasResult = false;
+            try {
+                hasResult = store !== null && assignmentOf(store, id, clock(), { principal: "operator", repos: null })?.receipt != null;
+            }
+            catch {
+                hasResult = false;
+            }
+            const decisions = store === null ? [] : store.listDecisions("unanswered").filter(one => one.taskId === id)
+                .map(one => ({ id: one.id, question: terminalText(one.question), options: one.options.map(option => ({ id: option.id, label: terminalText(option.label) })) }));
+            return {
+                id, title: shown(task["title"], id), status: shown(status["label"], words(work["state"])), detail: shown(status["detail"]),
+                plan, liveRunId: typeof work["liveRunId"] === "number" ? work["liveRunId"] : null, hasResult, decisions,
+            };
+        },
+        live(id) {
+            const store = read();
+            if (store === null)
+                return [];
+            try {
+                return snapshotLiveRuns(store, evidenceRoot, clock(), tails).find(one => one.taskId === id)?.lines.map(line => terminalText(line)) ?? [];
+            }
+            catch {
+                return [];
+            }
+        },
+        changed() {
+            try {
+                return read()?.wakeSeq() ?? 0;
+            }
+            catch {
+                return 0;
+            }
+        },
+        async act(act) {
+            let argv;
+            let done;
+            switch (act.kind) {
+                case "new":
+                    argv = ["task", "add", act.text, ...(act.repo === null ? [] : ["--repo", act.repo])];
+                    done = "Filed. Its plan will be ready for you to approve.";
+                    break;
+                case "approve":
+                    argv = ["task", "approve", act.id, "--yes", "--digest", act.digest];
+                    done = "Approved. An agent starts on it.";
+                    break;
+                case "stop":
+                    argv = ["task", "stop", act.id, "--run", String(act.runId)];
+                    done = "Stopping. Its work so far is kept.";
+                    break;
+                case "revise":
+                    argv = ["task", "revise", act.id, "--feedback", act.text];
+                    done = "Revision requested.";
+                    break;
+                case "answer":
+                    argv = ["decide", String(act.decision), "--choose", act.option];
+                    done = "Answered.";
+                    break;
+                case "complete": {
+                    const store = read();
+                    let digest;
+                    try {
+                        digest = store === null ? undefined : assignmentOf(store, act.id, clock(), { principal: "operator", repos: null })?.receipt?.digest;
+                    }
+                    catch {
+                        digest = undefined;
+                    }
+                    if (digest === undefined)
+                        return { ok: false, message: "This task has no finished result to mark Complete.", needsPassword: false };
+                    argv = ["task", "complete", act.id, "--digest", digest];
+                    done = "Marked Complete.";
+                    break;
+                }
+            }
+            const answer = await command(argv);
+            if (answer.ok !== true)
+                return refusalOf(answer);
+            const filed = act.kind === "new" ? words(record(answer["task"])["id"], words(answer["id"])) : "";
+            return { ok: true, message: done, ...(filed === "" ? {} : { id: filed }) };
+        },
+        async setup() {
+            if (setupCache !== null && Date.now() - setupCache.at < 30_000)
+                return setupCache.value;
+            const store = read();
+            if (store === null)
+                return null;
+            const here = await welcomeHere(store, file, clock(), options.check === undefined ? {} : { check: options.check });
+            const value = here.model.left === 0 ? null : { left: here.model.left, lines: welcomeLines(here.model).map(line => terminalText(line)) };
+            setupCache = { at: Date.now(), value };
+            return value;
+        },
+        close() {
+            reader?.close();
+            reader = null;
+        },
+    };
+}