@intentic/machine 1.331.0 → 1.333.0

package/dist/sync/commands.js

@@ -1,23 +1,24 @@
-import { spawnSync } from "node:child_process";
 import { mkdir, readdir } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
 import { errorMessage, undefinedIfMissing } from "@intentic/base/errors";
 import { plural } from "@intentic/base/format";
 import { WORKSPACE_ROOT } from "@intentic/constants";
-import { clearWindowsRunValue, createUi, homeDir } from "@intentic/local-agent";
+import { clearWindowsRunValue, explain, homeDir } from "@intentic/local-agent";
 import { environmentKeyOf, projectDirNameOf, sandboxIdFromUrl, SyncEnrollmentAnswerSchema, } from "@intentic/sandbox-contract";
-import { buildCommand, buildRouteMap } from "@stricli/core";
+import { buildRouteMap } from "@stricli/core";
+import { buildCommand, machineUi, sandboxUrlOf } from "../cli-ui.js";
 import { z } from "zod";
 import { postWhileWarming } from "../daemon-base.js";
 import { completeSetup, prepareSetup } from "../install.js";
 import { machineId } from "../machine-id.js";
 import { wslEnvironment } from "../environments/wsl.js";
-import { ensureResident, readResidentBuild, readResidentPid } from "../resident.js";
+import { ensureResident, readResidentBuild, readResidentPid } from "../resident/resident.js";
 import { MACHINE_VERSION } from "../version.js";
-import { machineLauncher } from "../supervision.js";
+import { machineLauncher } from "../resident/supervision.js";
 import { isAttachedPairing, isProjectPairing, pairingKey, pairingRemoteDir, readState, removePairing, setAutoHealOff, setMirrorOff, setPortIgnored, upsertPairing, } from "./config.js";
 import { transportFor } from "./endpoint.js";
+import { runProcess } from "./exec.js";
 import { overlappingPairing } from "./folders.js";
 import { realBridgeExec, runGitBridge } from "./git-bridge.js";
 import { retireMirroredPort, retirePairingMirror, teardownAllForwards } from "./mirror.js";
@@ -30,22 +31,35 @@ import { refuseAcrossPc } from "./siblings.js";
 import { syncSshPort, tunnelReady } from "./tunnel.js";
 import { assertSshConfigVisible, ensureSshKey, hostKeyOf, mutagenSshPath, pairingSshConfig, probeSshTransport, removeManagedSshConfig, replaceKnownHost, sanitizeId, sshAlias, writeManagedSshConfig, } from "./ssh.js";
 export { transportFor } from "./endpoint.js";
+const urlHost = (value) => {
+    if (!value.includes("://")) {
+        return undefined;
+    }
+    try {
+        return new URL(value).host;
+    }
+    catch {
+        return undefined;
+    }
+};
 export const selectPairings = (state, selector) => {
     if (selector === undefined) {
         return state.pairings;
     }
     const ids = [...new Set(state.pairings.map((pairing) => pairing.sandboxId))];
-    const exact = ids.filter((id) => id === sanitizeId(selector));
+    const wanted = sanitizeId(urlHost(selector) ?? selector);
+    const exact = ids.filter((id) => id === wanted);
     const matched = exact.length === 1 ? exact : ids.filter((id) => id.includes(selector));
     if (matched.length === 0) {
-        throw new Error(`no paired sandbox matches "${selector}". This machine pairs: ${ids.join(", ") || "none"}`);
+        throw new Error(explain(`No paired sandbox matches ${selector}.`, `this device pairs ${ids.length === 0 ? "no sandbox" : ids.join(", ")}.`));
     }
     if (matched.length > 1) {
-        throw new Error(`"${selector}" matches more than one paired sandbox: ${matched.join(", ")}`);
+        throw new Error(explain(`${selector} matches more than one paired sandbox.`, `it matches ${matched.join(", ")}.`, "name one of them in full with --sandbox."));
     }
     return state.pairings.filter((pairing) => pairing.sandboxId === matched[0]);
 };
-export const enrollKey = async (sandboxUrl, pairToken, key, { attempts, delayMs, takeover = false, identity, } = {}) => {
+const SYNC_NOT_SET_UP = "Desktop sync was not set up.";
+export const enrollKey = async (sandboxUrl, pairToken, key, { attempts, delayMs, takeover = false, identity, say, } = {}) => {
     const response = await postWhileWarming(sandboxUrl, "/system/authorized-key", {
         headers: {
             "content-type": "application/json",
@@ -55,25 +69,26 @@ export const enrollKey = async (sandboxUrl, pairToken, key, { attempts, delayMs,
         body: JSON.stringify({ key, ...identity }),
     }, {
         doing: "enrolling the sync key",
-        expired: "pairing expired: click 'Enable desktop sync' again in your browser for a fresh command.",
+        expired: explain(SYNC_NOT_SET_UP, "the pairing has expired.", "click Enable desktop sync again in your browser for a fresh command."),
+        say,
         attempts,
         delayMs,
     });
     if (response.status === 423) {
         const held = (await response.json().catch(() => ({})));
         const from = held.machine !== undefined ? ` from "${held.machine}"` : "";
-        throw new Error(`desktop sync is already active on this sandbox${from}. Re-run with --takeover to move it to this machine (this stops syncing on the other one).`);
+        throw new Error(explain(`Desktop sync is already active on this sandbox${from}.`, "one device at a time holds a sandbox's file sync.", "run the same command again with --takeover to move it to this device; the other one stops syncing."));
     }
     if (!response.ok) {
-        throw new Error(`enrolling the sync key failed (${response.status}): ${await response.text()}`);
+        throw new Error(explain(SYNC_NOT_SET_UP, `enrolling the sync key failed (${response.status}): ${await response.text()}`));
     }
     const answer = SyncEnrollmentAnswerSchema.safeParse(await response.json());
     if (!answer.success) {
-        throw new Error(`the sandbox enrolled this machine but its answer could not be read: ${z.prettifyError(answer.error)}`);
+        throw new Error(explain(SYNC_NOT_SET_UP, `the sandbox enrolled this device but its answer could not be read: ${z.prettifyError(answer.error)}`));
     }
     const body = answer.data;
     if (body.syncToken === undefined) {
-        throw new Error("the sandbox enrolled this machine but returned no sync credential: update the sandbox and enable sync again.");
+        throw new Error(explain(SYNC_NOT_SET_UP, "the sandbox enrolled this device but returned no sync credential.", "update the sandbox, then enable sync again."));
     }
     return { syncToken: body.syncToken, mode: body.mode ?? "sync", hostKey: hostKeyOf(body.hostKey) };
 };
@@ -113,11 +128,12 @@ const wantedFolder = (flags, sandboxId) => resolve(flags.dir === undefined
     : flags.dir.replace(/^~(?=[\\/]|$)/, homeDir()));
 const setup = buildCommand({
     docs: {
-        brief: "Enroll this machine with a pairing token and start a Mutagen sync of the local dir ↔ sandbox /work (or a project folder in it), over ssh or, for a project on this machine's Docker engine, through Docker",
+        brief: "Enroll this device with a pairing token and start a Mutagen sync of the local dir ↔ sandbox /work (or a project folder in it), over ssh or, for a project on this device's Docker engine, through Docker",
     },
     parameters: {
         flags: {
-            url: { kind: "parsed", parse: String, brief: "The sandbox's public URL (e.g. https://sandbox-xxx.example.dev)" },
+            url: { kind: "parsed", parse: String, optional: true, brief: "The sandbox's public URL (e.g. https://sandbox-xxx.example.dev)" },
+            sandbox: { kind: "parsed", parse: String, optional: true, brief: "The same as --url" },
             pair: { kind: "parsed", parse: String, brief: "The one-time pairing token from the Desktop sync card" },
             dir: {
                 kind: "parsed",
@@ -126,7 +142,7 @@ const setup = buildCommand({
                 brief: "Local directory to sync (default: ~/intentic/<sandbox id>, the id in the sandbox's own URL)",
             },
             sandboxId: { kind: "parsed", parse: String, optional: true, brief: "Session/alias id (default: the sandbox URL host)" },
-            takeover: { kind: "boolean", brief: "Take over sync from another machine already enrolled on this sandbox (revokes its key)" },
+            takeover: { kind: "boolean", brief: "Take over sync from another device already enrolled on this sandbox (revokes its key)" },
             remoteDir: {
                 kind: "parsed",
                 parse: parseRemoteDir,
@@ -141,7 +157,7 @@ const setup = buildCommand({
                 kind: "parsed",
                 parse: parseTransport,
                 optional: true,
-                brief: "How the sandbox is reached: auto (the default: Docker for a project whose sandbox runs on this machine's engine, ssh otherwise), ssh or docker",
+                brief: "How the sandbox is reached: auto (the default: Docker for a project whose sandbox runs on this device's engine, ssh otherwise), ssh or docker",
             },
             projectsHost: {
                 kind: "boolean",
@@ -150,21 +166,18 @@ const setup = buildCommand({
             },
         },
     },
-    async func(flags) {
-        await prepareSetup((message) => void this.process.stdout.write(`${message}\n`), process.argv.slice(2));
-        const ui = createUi(this.process);
+    async func(given) {
+        const flags = { ...given, url: sandboxUrlOf(given.url, given.sandbox, "Desktop sync was not set up.") };
+        const ui = machineUi(this.process);
+        await prepareSetup(ui.note, process.argv.slice(2));
         const out = ui.note;
         ui.begin("intentic · desktop sync", SETUP_PLAN);
-        try {
-            await runSetup(ui, out, flags);
-        }
-        finally {
-            ui.close();
-        }
+        await runSetup(ui, out, flags);
+        ui.close();
     },
 });
 const SETUP_PLAN = [
-    { phase: "sync-enrolling", label: "Enrol this machine", weight: 25 },
+    { phase: "sync-enrolling", label: "Connect this device", weight: 25 },
     { phase: "sync-linking", label: "Link the folder", weight: 5 },
     { phase: "sync-starting", label: "Start syncing", weight: 20 },
 ];
@@ -175,27 +188,28 @@ export const placementChange = (held, placement) => {
     const same = pairingRemoteDir(held) === pairingRemoteDir(placement) && isProjectPairing(held) === isProjectPairing(placement);
     return same
         ? undefined
-        : `${held.sandboxId} already syncs ${held.localDir} with its ${pairingRemoteDir(held)}${isProjectPairing(held) ? " as a project" : ""}; setting it up again for ${pairingRemoteDir(placement)}${isProjectPairing(placement) ? " as a project" : ""} would rewrite what that folder holds. Unpair it first (\`intentic-machine sync uninstall --sandbox ${held.sandboxId}\`), then set it up again.`;
+        : explain(`${held.sandboxId} was not set up again.`, `it already syncs ${held.localDir} with its ${pairingRemoteDir(held)}${isProjectPairing(held) ? " as a project" : ""}; setting it up again for ${pairingRemoteDir(placement)}${isProjectPairing(placement) ? " as a project" : ""} would rewrite what that folder holds. Unpair it first, then set it up again.`, unpairCommand(held.sandboxId));
 };
+const unpairCommand = (sandboxId) => `intentic-machine sync uninstall --sandbox ${sandboxId}`;
 export const projectAskedWithoutFlag = (flags, env = process.env) => {
     const remote = env["SYNC_REMOTE_DIR"] ?? ``;
     const asked = (env["SYNC_PROJECT"] ?? ``) !== `` || (remote !== `` && remote !== WORKSPACE_ROOT);
     return asked && !flags.project
-        ? `This setup was asked to sync a project folder (SYNC_PROJECT, SYNC_REMOTE_DIR), but the install script that ran it did not pass --project: it is older than this agent. Nothing was enrolled. Run the setup again once the script is current.`
+        ? explain("Nothing was enrolled.", "this setup was asked to sync a project folder (SYNC_PROJECT, SYNC_REMOTE_DIR), but the install script that ran it did not pass --project: it is older than this agent.", "run the setup again once the script is current.")
         : undefined;
 };
 export const projectsHostChange = (held, flags) => {
     if (flags.projectsHost === true && (flags.dir !== undefined || flags.remoteDir !== undefined || flags.project)) {
-        return "--projects-host enrolls this computer's sandbox with no folder of its own, so it takes no --dir, --remote-dir or --project. Attach folders to it afterwards with `intentic-machine sync attach`.";
+        return explain("Nothing was enrolled.", "--projects-host enrolls this device's sandbox with no folder of its own, so it takes no --dir, --remote-dir or --project; folders attach to it afterwards.", "run the same command again without --dir, --remote-dir and --project.");
     }
     if (held === undefined) {
         return undefined;
     }
     if (flags.projectsHost === true && held.localDir !== undefined) {
-        return `${held.sandboxId} already syncs ${held.localDir}; setting it up as this computer's sandbox for folders would stop that. Unpair it first (\`intentic-machine sync uninstall --sandbox ${held.sandboxId}\`), then set it up again.`;
+        return explain(`${held.sandboxId} was not set up again.`, `it already syncs ${held.localDir}; setting it up as this device's sandbox for folders would stop that. Unpair it first, then set it up again.`, unpairCommand(held.sandboxId));
     }
     if (flags.projectsHost !== true && held.projectsHost === true) {
-        return `${held.sandboxId} is this computer's sandbox for folders, which attach to it; setting it up for a folder of its own would leave them without it. Set it up again with --projects-host, or unpair it first (\`intentic-machine sync uninstall --sandbox ${held.sandboxId}\`).`;
+        return explain(`${held.sandboxId} was not set up again.`, "it is this device's sandbox for folders, which attach to it; setting it up for a folder of its own would leave them without it. Set it up again with --projects-host, or unpair it first.", unpairCommand(held.sandboxId));
     }
     return undefined;
 };
@@ -227,7 +241,7 @@ const planSetup = async (flags) => {
     }
     const clash = await overlappingPairing(folder, sandboxId, pairings);
     if (clash !== undefined) {
-        throw new Error(`${folder} overlaps ${clash.localDir}, which already syncs with ${clash.sandboxId}: two syncs over one folder overwrite each other's files. Choose a folder that neither is, holds nor sits inside one this machine syncs (\`intentic-machine status\` lists them).`);
+        throw new Error(explain(`${folder} was not set up.`, `it overlaps ${clash.localDir}, which already syncs with ${clash.sandboxId}, and two syncs over one folder overwrite each other's files.`, "choose a folder that neither is, holds nor sits inside one this device syncs; intentic-machine status lists them."));
     }
     const across = await refuseAcrossPc(folder);
     if (across.refusal !== undefined) {
@@ -237,15 +251,16 @@ const planSetup = async (flags) => {
     return { sandboxId, placement, folder, reach, unread: across.unread };
 };
 const runSetup = async (ui, out, flags) => {
-    ui.step("sync-enrolling", "enrolling this machine with your sandbox…");
+    ui.step("sync-enrolling", "enrolling this device with your sandbox…");
     const { sandboxId, placement, folder, reach, unread = [] } = await planSetup(flags);
     if (unread.length > 0) {
-        out(`note: ${unread.join(", ")} could not be asked which folders ${unread.length === 1 ? "it syncs" : "they sync"}, so ${folder ?? "this folder"} was not checked against ${unread.length === 1 ? "it" : "them"}.`);
+        ui.warn(`${unread.join(", ")} could not be asked which folders ${unread.length === 1 ? "it syncs" : "they sync"}, so ${folder ?? "this folder"} was not checked against ${unread.length === 1 ? "it" : "them"}.`);
     }
     const publicKey = await ensureSshKey();
     const [{ syncToken, mode, hostKey }, mutagen] = await Promise.all([
         enrollKey(flags.url, flags.pair, publicKey, {
             takeover: flags.takeover,
+            say: out,
             identity: { machineId: machineId(), environment: environmentKeyOf({ wsl: await wslEnvironment() }) },
         }),
         ensureMutagen(),
@@ -254,8 +269,8 @@ const runSetup = async (ui, out, flags) => {
     const container = dockerContainerOf(reach, mode);
     await pinHostKey(sandboxId, hostKey, container);
     if ((placement.project === true || flags.projectsHost === true) && mode !== "sync") {
-        await revokeEnrollment(flags.url, syncToken).catch((error) => out(`note: ${flags.url} could not be told to forget this machine (${errorMessage(error)}), so its sync key is still authorized there. Remove this machine from that sandbox's Devices view.`));
-        throw new Error(`another machine holds file sync for this sandbox, so ${flags.projectsHost === true ? "no folder can attach to it" : "this project folder cannot sync"} here. Re-run with --takeover to move sync to this machine.`);
+        await revokeEnrollment(flags.url, syncToken).catch((error) => ui.warn(`${flags.url} could not be told to forget this device (${errorMessage(error)}), so its sync key is still authorized there. Remove this device from that sandbox's Devices view.`));
+        throw new Error(explain(flags.projectsHost === true ? "No folder can attach to this sandbox here." : "This project folder cannot sync here.", "another device holds file sync for this sandbox.", "run the same command again with --takeover to move sync to this device."));
     }
     const localDir = mode === "sync" ? folder : undefined;
     const adopt = localDir !== undefined && placement.project !== true && (await holdsEntries(localDir));
@@ -277,16 +292,19 @@ const runSetup = async (ui, out, flags) => {
     const pairings = (await readState()).pairings;
     await writeManagedSshConfig(pairingSshConfig(pairings));
     ui.step("sync-starting", "starting the sync engine…");
+    const later = [];
     await ensureResident(out);
     await completeSetup(out);
-    await proveTransport(out, sandboxId, container);
+    await proveTransport(out, ui.warn, sandboxId, container);
     if (mode === "sync" && localDir !== undefined && !(await syncSessionAppears(mutagen, sandboxId, SESSION_READY_MS))) {
-        out(await notStartedYet(localDir));
+        const late = await notStartedYet(localDir);
+        ui.warn(late.said);
+        later.push(late.later);
     }
     retireOrphanSessions(mutagen, pairings, out);
     runGitBridge(realBridgeExec, pairing, out, undefined);
     registerMutagenAutostart(mutagen, machineLauncher(), out);
-    finishSetup(ui, flags.url, pairing, pairings);
+    finishSetup(ui, flags.url, pairing, pairings, later);
 };
 const holdsEntries = async (dir) => ((await readdir(dir).catch(undefinedIfMissing))?.length ?? 0) > 0;
 const dockerContainerOf = (reach, mode) => mode === "sync" && reach.transport === "docker" ? reach.container : undefined;
@@ -295,18 +313,18 @@ const pinHostKey = async (sandboxId, hostKey, container) => {
         await replaceKnownHost(sshAlias(sandboxId), syncSshPort(sandboxId), hostKey);
     }
 };
-const proveTransport = async (out, sandboxId, container) => {
+const proveTransport = async (out, warn, sandboxId, container) => {
     if (container !== undefined) {
-        out(`reaching ${sandboxId} through Docker on this machine (${container}): no ssh key, tunnel or public address on the data path`);
+        out(`reaching ${sandboxId} through Docker on this device (${container}): no ssh key, tunnel or public address on the data path`);
         return;
     }
     const alias = sshAlias(sandboxId);
     const port = syncSshPort(sandboxId);
     if (!(await tunnelReady(port, TUNNEL_READY_MS))) {
-        out(`note: the sync transport for ${sandboxId} isn't listening on 127.0.0.1:${port} yet, syncing starts as soon as it is.`);
+        warn(`The sync transport for ${sandboxId} isn't listening on 127.0.0.1:${port} yet; syncing starts as soon as it is.`);
     }
     const ssh = mutagenSshPath(process.platform, process.env["MUTAGEN_SSH_PATH"]);
-    assertSshConfigVisible(ssh, alias, port);
+    await assertSshConfigVisible(ssh, alias, port);
     await probeSshTransport(ssh, alias, out);
 };
 const syncedSentence = (pairing) => {
@@ -315,25 +333,23 @@ const syncedSentence = (pairing) => {
         ? `${kept}\nThe folder already held files: any that differ from the sandbox's copy are moved to ${asidePrefix(pairing.localDir)}<time> first, so the sandbox's version is the one that syncs. Nothing is deleted.`
         : kept;
 };
-const finishSetup = (ui, sandboxUrl, pairing, pairings) => {
+const finishSetup = (ui, sandboxUrl, pairing, pairings, later = []) => {
     if (pairings.length > 1) {
-        ui.note(`This machine now syncs ${pairings.length} pairings:`);
+        ui.note(`This device now syncs ${pairings.length} pairings:`);
         for (const held of pairings) {
-            ui.note(`  ${pairingKey(held)}${held.projectsHost === true ? " (this computer's sandbox, for folders)" : held.localDir === undefined ? " (ports only)" : ` → ${held.localDir}`}`);
+            ui.note(`  ${pairingKey(held)}${held.projectsHost === true ? " (this device's sandbox, for folders)" : held.localDir === undefined ? " (ports only)" : ` → ${held.localDir}`}`);
         }
     }
     if (pairing.projectsHost === true) {
-        ui.finished("This computer's sandbox is ready for folders.", undefined, `Ports from ${sandboxUrl} answer on this machine's localhost, and folders attach to it as ${WORKSPACE_ROOT}/<name>.`, [
-            ["attach a folder", "intentic-machine sync attach --sandbox-url <url> --dir <folder> --name <name>"],
+        ui.finished("This device's sandbox is ready for folders.", undefined, `Ports from ${sandboxUrl} answer on this device's localhost, and folders attach to it as ${WORKSPACE_ROOT}/<name>.`, [
+            ["attach a folder", `intentic-machine sync attach --sandbox-url ${sandboxUrl} --dir <folder> --name <name>`],
             ["check it", "intentic-machine status"],
+            ...later,
         ]);
         return;
     }
     const syncing = pairing.mode === "sync";
-    ui.finished(syncing ? "Desktop sync is running." : "Enrolled for port mirroring.", syncing ? pairing.localDir : undefined, syncing ? syncedSentence(pairing) : `Ports from ${sandboxUrl} now answer on this machine's localhost (mirror-only, no file sync).`, [
-        ["check it", "intentic-machine status"],
-        ["remove it", "intentic-machine sync uninstall"],
-    ]);
+    ui.finished(syncing ? "Desktop sync is running." : "Enrolled for port mirroring.", syncing ? pairing.localDir : undefined, syncing ? syncedSentence(pairing) : `Ports from ${sandboxUrl} now answer on this device's localhost (mirror-only, no file sync).`, [["check it", "intentic-machine status"], ["remove it", unpairCommand(pairing.sandboxId)], ...later]);
 };
 const TUNNEL_READY_MS = 10_000;
 const SESSION_READY_MS = 90_000;
@@ -350,15 +366,21 @@ const syncSessionAppears = async (mutagen, key, withinMs) => {
 const notStartedYet = async (folder) => {
     const running = await readResidentBuild();
     return running !== undefined && running !== MACHINE_VERSION
-        ? `note: the agent running here is ${running}, which starts file sync for ${folder} only at its next start; \`intentic-machine upgrade\` brings it to ${MACHINE_VERSION} now.`
-        : `note: this machine's agent has not started file sync for ${folder} yet; it keeps trying, and \`intentic-machine status\` shows when it is running.`;
+        ? {
+            said: `The agent running here is ${running}, which starts file sync for ${folder} only at its next start; ${MACHINE_VERSION} starts it at once.`,
+            later: ["update it now", "intentic-machine upgrade"],
+        }
+        : {
+            said: `This device's agent has not started file sync for ${folder} yet; it keeps trying.`,
+            later: ["see when it runs", "intentic-machine status"],
+        };
 };
 const sandboxFlag = {
     sandbox: {
         kind: "parsed",
         parse: String,
         optional: true,
-        brief: "Act on one paired sandbox (its id, or any substring matching exactly one). Default: all of them",
+        brief: "Act on one paired sandbox (its URL, its id, or any part of the id matching exactly one). Default: all of them",
     },
 };
 export const syncSwitchPlan = (syncing, held) => {
@@ -372,44 +394,48 @@ const pairingCommand = (brief, flags, none, act) => buildCommand({
     docs: { brief },
     parameters: { flags },
     async func(given) {
-        const out = (message) => void this.process.stdout.write(`${message}\n`);
+        const ui = machineUi(this.process);
         const selected = selectPairings(await readState(), given.sandbox);
         if (selected.length === 0) {
-            out(none);
+            ui.quiet(none);
             return;
         }
-        await act(selected, given, out);
+        await act(selected, given, ui);
     },
 });
-const NONE_TO_MIRROR = "no sandboxes are paired on this machine: nothing to mirror. Enable it from a sandbox's Desktop sync card.";
-const noteIfStopped = async (out) => {
+const NONE_TO_MIRROR = "No sandbox is paired on this device, so there is nothing to mirror. Desktop sync starts from a sandbox's Desktop sync card.";
+const noteIfStopped = async (ui) => {
     if ((await readResidentPid()) === undefined) {
-        out("Note: this machine's agent is NOT running, so nothing will mirror until you start it: `intentic-machine run`.");
+        ui.warn("This device's agent is not running, so nothing mirrors until it starts.");
+        ui.later([["start the agent", "intentic-machine run"]]);
     }
 };
-const fileSyncSwitch = (brief, verb) => pairingCommand(brief, sandboxFlag, `no sandboxes are paired on this machine: nothing to ${verb}. Enable sync from a sandbox's Desktop sync card.`, async (selected, _flags, out) => {
+const fileSyncSwitch = (brief, verb) => pairingCommand(brief, sandboxFlag, `No sandbox is paired on this device, so there is nothing to ${verb}. Desktop sync starts from a sandbox's Desktop sync card.`, async (selected, _flags, ui) => {
+    const done = verb === "pause" ? "paused" : "resumed";
     const syncing = selected.filter((pairing) => pairing.mode === "sync" && pairing.projectsHost !== true);
     if (syncing.length === 0) {
-        out(`mirror-only enrollment${selected.length > 1 ? "s" : ""}, no file sync to ${verb}.`);
+        ui.quiet(`${selected.length > 1 ? "These enrollments only mirror ports" : "This enrollment only mirrors ports"}, so there is no file sync to ${verb}.`);
         return;
     }
+    ui.act(`${verb === "pause" ? "Pausing" : "Resuming"} file sync`);
     const mutagen = await ensureMutagen();
     const held = existingSyncSessions(mutagen, syncing.flatMap((pairing) => syncSessionNames(pairing)));
     if (held === undefined) {
-        throw new Error(`Mutagen did not answer when asked which sessions it holds, so nothing was ${verb === "pause" ? "paused" : "resumed"}. Try again in a moment.`);
+        throw new Error(explain(`File sync was not ${done}.`, "Mutagen did not answer when asked which sessions it holds.", "run the same command again in a moment."));
     }
     const plan = syncSwitchPlan(syncing, held);
     if (plan.names.length === 0) {
-        out(`No file-sync session is running for: ${named(syncing)}. Nothing to ${verb}; syncing starts when the sandbox answers again.`);
+        ui.done(`No file-sync session is running for ${named(syncing)}, so nothing was ${done}. Syncing starts when the sandbox answers again.`);
         return;
     }
     runMutagen(mutagen, ["sync", verb, ...plan.names]);
-    out(`${verb === "pause" ? "Paused" : "Resumed"} file sync for: ${named(plan.acted)}`);
     if (plan.idle.length > 0) {
-        out(`No file-sync session to ${verb} for: ${named(plan.idle)}.`);
+        ui.note(`No file-sync session to ${verb} for ${named(plan.idle)}.`);
     }
+    ui.done(`${verb === "pause" ? "Paused" : "Resumed"} file sync for ${named(plan.acted)}.`);
 });
-const mirrorSwitch = (brief, off) => pairingCommand(brief, sandboxFlag, NONE_TO_MIRROR, async (selected, _flags, out) => {
+const mirrorSwitch = (brief, off) => pairingCommand(brief, sandboxFlag, NONE_TO_MIRROR, async (selected, _flags, ui) => {
+    ui.act(off ? "Turning port mirroring off" : "Turning port mirroring on");
     const mutagen = await ensureMutagen();
     for (const pairing of selected) {
         await setMirrorOff(pairingKey(pairing), off);
@@ -418,22 +444,23 @@ const mirrorSwitch = (brief, off) => pairingCommand(brief, sandboxFlag, NONE_TO_
         for (const sandboxId of new Set(selected.map((pairing) => pairing.sandboxId))) {
             await retirePairingMirror(mutagen, sandboxId);
         }
-    }
-    if (off) {
-        out(`Port mirroring OFF for: ${named(selected)}. Those ports are off this device's localhost. File syncing is untouched.`);
+        ui.note("Those ports are off this device's localhost. File syncing is untouched.");
+        ui.done(`Turned port mirroring off for ${named(selected)}.`);
         return;
     }
-    out(`Port mirroring on for: ${named(selected)}. Their ports return to localhost within a few seconds.`);
-    await noteIfStopped(out);
+    ui.note("Their ports return to localhost within a few seconds.");
+    ui.done(`Turned port mirroring on for ${named(selected)}.`);
+    await noteIfStopped(ui);
 });
 const parsePort = (value) => {
     const port = Number(value);
     if (!Number.isInteger(port) || port < 1 || port > 65_535) {
-        throw new Error(`"${value}" is not a port number (1-65535).`);
+        throw new Error(`${value} is not a port number (1-65535).`);
     }
     return port;
 };
-const mirrorPortSwitch = (brief, ignored) => pairingCommand(brief, { ...sandboxFlag, port: { kind: "parsed", parse: parsePort, brief: "The port number, as the sandbox serves it" } }, NONE_TO_MIRROR, async (selected, flags, out) => {
+const mirrorPortSwitch = (brief, ignored) => pairingCommand(brief, { ...sandboxFlag, port: { kind: "parsed", parse: parsePort, brief: "The port number, as the sandbox serves it" } }, NONE_TO_MIRROR, async (selected, flags, ui) => {
+    ui.act(ignored ? `Leaving port ${flags.port} off this device` : `Mirroring port ${flags.port} again`);
     const mutagen = await ensureMutagen();
     let taken = 0;
     for (const pairing of selected.filter((held) => !isAttachedPairing(held))) {
@@ -443,11 +470,13 @@ const mirrorPortSwitch = (brief, ignored) => pairingCommand(brief, { ...sandboxF
         }
     }
     if (ignored) {
-        out(`Port ${flags.port} will not be mirrored for: ${named(selected)}.${taken === 0 ? "" : ` Took localhost:${flags.port} off this device.`} Every other port is untouched.`);
+        ui.note(`${taken === 0 ? "" : `Took localhost:${flags.port} off this device. `}Every other port is untouched.`);
+        ui.done(`Port ${flags.port} is no longer mirrored for ${named(selected)}.`);
         return;
     }
-    out(`Port ${flags.port} will be mirrored again for: ${named(selected)}. It returns to localhost within a few seconds, unless something else on this machine is holding it.`);
-    await noteIfStopped(out);
+    ui.note(`It returns to localhost within a few seconds, unless something else on this device is holding it.`);
+    ui.done(`Port ${flags.port} is mirrored again for ${named(selected)}.`);
+    await noteIfStopped(ui);
 });
 const mirror = buildRouteMap({
     routes: {
@@ -462,35 +491,44 @@ const clean = buildCommand({
     docs: { brief: "Clear build output this device left in directories the sandbox deleted, so those deletions can land" },
     parameters: { flags: sandboxFlag },
     async func(flags) {
-        const out = (message) => void this.process.stdout.write(`${message}\n`);
+        const ui = machineUi(this.process);
         const syncing = selectPairings(await readState(), flags.sandbox).filter((pairing) => pairing.mode === "sync");
         if (syncing.length === 0) {
-            out("no file-syncing sandbox is paired on this machine: there is no folder here to clear anything from.");
+            ui.quiet("No file-syncing sandbox is paired on this device, so there is no folder here to clear anything from.");
             return;
         }
+        ui.act("Clearing build output the sandbox's deletions are waiting on");
         const mutagen = await ensureMutagen();
         let removed = 0;
         let standing = 0;
         for (const pairing of syncing) {
-            const outcome = await healDerivedConflicts(mutagen, pairing, out, true);
+            const outcome = await healDerivedConflicts(mutagen, pairing, ui.note, true);
             removed += outcome.removed.length;
             standing += outcome.standing;
         }
-        out(removed === 0
-            ? "Nothing to clear: no directory the sandbox deleted is being held open by build output on this device."
-            : `Cleared ${removed} director${removed === 1 ? "y" : "ies"}. The deletions they were holding back land within a few seconds.`);
         if (standing > 0) {
-            out(`${plural(standing, "conflict")} still standing, and not this command's to settle: two copies somebody wrote is a choice only a person makes. \`intentic-machine status\` lists the paths.`);
+            ui.warn(`${plural(standing, "conflict")} still standing, and not this command's to settle: two copies somebody wrote is a choice only a person makes.`);
+        }
+        ui.done(removed === 0
+            ? "Nothing to clear: no directory the sandbox deleted is held open by build output on this device."
+            : `Cleared ${plural(removed, "directory", "directories")}. The deletions they held back land within a few seconds.`);
+        if (standing > 0) {
+            ui.later([["see the paths", "intentic-machine status"]]);
         }
     },
 });
-const autoHealSwitch = (brief, off) => pairingCommand(brief, sandboxFlag, "no sandboxes are paired on this machine: nothing to switch.", async (selected, _flags, out) => {
+const autoHealSwitch = (brief, off) => pairingCommand(brief, sandboxFlag, "No sandbox is paired on this device, so there is nothing to switch.", async (selected, _flags, ui) => {
+    ui.act(off ? "Turning off clearing build output" : "Turning on clearing build output");
     for (const pairing of selected) {
         await setAutoHealOff(pairingKey(pairing), off);
     }
-    out(off
-        ? `Clearing derived residue is OFF for: ${named(selected)}. A deletion the sandbox makes will now stop syncing whenever this device has build output inside it; \`intentic-machine sync clean\` clears one by hand.`
-        : `Clearing derived residue is on for: ${named(selected)}.`);
+    if (!off) {
+        ui.done(`This device clears build output that holds back a deletion for ${named(selected)}.`);
+        return;
+    }
+    ui.note("A deletion the sandbox makes now stops syncing whenever this device has build output inside it.");
+    ui.done(`This device no longer clears build output by itself for ${named(selected)}.`);
+    ui.later([["clear it by hand", "intentic-machine sync clean"]]);
 });
 const autoheal = buildRouteMap({
     routes: {
@@ -499,7 +537,7 @@ const autoheal = buildRouteMap({
     },
     docs: { brief: "Whether this device clears its own build output when it blocks a deletion, for one sandbox or all" },
 });
-export const syncUninstall = async (out, sandbox, { forGood = false } = {}) => {
+export const syncUninstall = async (say, sandbox, { forGood = false } = {}) => {
     const state = await readState();
     const dropped = selectPairings(state, sandbox);
     const mutagen = await ensureMutagen();
@@ -509,48 +547,46 @@ export const syncUninstall = async (out, sandbox, { forGood = false } = {}) => {
         const firstOfSandbox = !revoked.has(pairing.sandboxId);
         revoked.add(pairing.sandboxId);
         if (pairing.syncToken !== undefined && firstOfSandbox) {
-            await revokeEnrollment(pairing.sandboxUrl, pairing.syncToken).catch((error) => out(`note: ${pairing.sandboxUrl} could not be told to forget this machine (${errorMessage(error)}), so its sync key is still authorized there. Remove this machine from that sandbox's Devices view.`));
+            await revokeEnrollment(pairing.sandboxUrl, pairing.syncToken).catch((error) => say.warn(`${pairing.sandboxUrl} could not be told to forget this device (${errorMessage(error)}), so its sync key is still authorized there. Remove this device from that sandbox's Devices view.`));
         }
         if (pairing.mode === "sync" && syncSessionNames(pairing).length > 0) {
-            spawnSync(mutagen, ["sync", "terminate", ...syncSessionNames(pairing)], {
-                stdio: "ignore",
-                windowsHide: true,
-                timeout: MUTAGEN_CALL_TIMEOUT_MS,
-            });
+            await runProcess(mutagen, ["sync", "terminate", ...syncSessionNames(pairing)], { timeoutMs: MUTAGEN_CALL_TIMEOUT_MS });
         }
         if (firstOfSandbox) {
             await retirePairingMirror(mutagen, pairing.sandboxId);
         }
         await removePairing(pairingKey(pairing));
-        out(`unpaired ${pairingKey(pairing)}${pairing.localDir === undefined ? "" : ` (${pairing.localDir} is no longer synced)`}.`);
+        say.note(`Unpaired ${pairingKey(pairing)}${pairing.localDir === undefined ? "" : `; ${pairing.localDir} is no longer synced`}.`);
     }
     if (remaining.length > 0) {
         await writeManagedSshConfig(pairingSshConfig(remaining));
-        await ensureResident(out, { forGood });
-        out(`Still syncing ${plural(remaining.length, "pairing")}: ${named(remaining)}`);
-        return;
+        await ensureResident(say.note, { forGood });
+        return `Unpaired ${plural(dropped.length, "pairing")}. Still syncing ${plural(remaining.length, "pairing")}: ${named(remaining)}.`;
     }
-    await ensureResident(out, { forGood });
-    await teardownAllForwards(mutagen, out);
+    await ensureResident(say.note, { forGood });
+    await teardownAllForwards(mutagen, say.note);
     await removeManagedSshConfig();
     const ownCopy = isOwnMutagen(mutagen) && userMutagenOnPath() === undefined;
     if (ownCopy) {
         unregisterMutagenAutostart(mutagen);
-        spawnSync(mutagen, ["daemon", "stop"], { stdio: "ignore", windowsHide: true, timeout: MUTAGEN_CALL_TIMEOUT_MS });
+        await runProcess(mutagen, ["daemon", "stop"], { timeoutMs: MUTAGEN_CALL_TIMEOUT_MS });
+        say.note("Removed the ssh-config include, and stopped and unregistered the Mutagen daemon.");
     }
-    else if (process.platform === "win32") {
-        clearWindowsRunValue(MUTAGEN_RUN_VALUE);
+    else {
+        if (process.platform === "win32") {
+            clearWindowsRunValue(MUTAGEN_RUN_VALUE);
+        }
+        say.note("Removed the ssh-config include. Your own Mutagen install and its daemon are untouched.");
     }
-    out(ownCopy
-        ? "Sync terminated; ssh-config include removed; Mutagen daemon stopped and unregistered."
-        : "Sync terminated; ssh-config include removed. (Your own Mutagen install is untouched, `mutagen daemon unregister` if you no longer want its daemon at login.)");
+    return dropped.length === 0 ? "Nothing was syncing. Removed any leftovers." : "Stopped syncing on this device.";
 };
 const uninstall = buildCommand({
-    docs: { brief: "Unpair a sandbox (--sandbox), or stop syncing every sandbox on this machine" },
+    docs: { brief: "Unpair a sandbox (--sandbox), or stop syncing every sandbox on this device" },
     parameters: { flags: sandboxFlag },
     async func(flags) {
-        const out = (message) => void this.process.stdout.write(`${message}\n`);
-        await syncUninstall(out, flags.sandbox);
+        const ui = machineUi(this.process);
+        ui.act(flags.sandbox === undefined ? "Stopping sync on this device" : `Unpairing ${flags.sandbox}`);
+        ui.done(await syncUninstall(ui, flags.sandbox));
     },
 });
 const pause = fileSyncSwitch("Pause file syncing", "pause");