mainflow 0.41.0 → 0.43.0-alpha.1

package/dist/cli.js

@@ -1,30 +1,41 @@
 #!/usr/bin/env node
-import { $ as stampMs, G as parseUntil, K as refExample, M as UNTIL_FORMS, W as parseRef, n as CLOSED_STATUS } from "./dist-zSabglPq.js";
-import { At as WriteError, Ct as TASK_FILE, D as loadSessions, Et as findHubRoot, G as applyOperation, K as checkHubName, O as readSession, St as MAINLINE_FILE, X as sectionText, Y as loadHub, at as nowMinute, b as duplicateClaimLines, ct as nodeStorage, d as migrateHub, et as memberOfGroup, f as retroReport, ft as MAX_FILE_BYTES, h as RETRY_RULES, kt as DATA_DIR, m as receiverFromEnv, nt as remoteMembers, p as retroReportFromReceiver, q as HubError, rt as unavailableHubs, u as groupPlan, v as initHub, wt as requireSlug, x as sessionBriefing, y as untilState } from "./host-BAMZmRy8.js";
+import { P as UNTIL_FORMS, X as parseUntil, Y as parseRef, Z as refExample, ct as stampMs, it as untilProblem, n as CLOSED_STATUS } from "./dist-D5rZ0MQH.js";
+import { $t as WriteError, At as MAINLINE_FILE, Bt as registeredName, Gt as nodeStorage, Ht as resolveHub, It as listHubs, Lt as notRegisteredMessage, Mt as requireSlug, Nt as hubAtRoot, O as loadSessions, Pt as hubHoldingFile, Q as HubError, Qt as DATA_DIR, Rt as readRegistry, S as sessionBriefing, Ut as unregisterHub, Vt as registryFile, Wt as userDataDir, X as applyOperation, Yt as realPath, Z as checkHubName, _t as MAX_FILE_BYTES, at as memberOfGroup, b as untilState, ct as unavailableHubs, d as migrateHubData, et as loadHub, f as migrateHub, g as RETRY_RULES, gt as MAX_CHANGE_PAGE, h as receiverFromEnv, jt as TASK_FILE, k as readSession, m as retroReportFromReceiver, mt as BLOB_HASH, p as retroReport, qt as dataFile, st as remoteMembers, tt as sectionText, u as groupPlan, ut as nowMinute, x as duplicateClaimLines, y as initHub, zt as registerHub } from "./host-BJvqZy-i.js";
 import { t as listProgress } from "./progress-1BfPg2zN.js";
-import { C as ServerError, D as syncSettings, E as hubName, O as SETTINGS_FILE, S as ServerApi, T as earlierToken, _ as readDaemon, a as remoteMode, b as readRemote, c as planAnnounce, d as toolCallOf, f as startDaemon, g as probeDaemon, h as callDaemon, i as queuedCount, j as syncPaths, l as planFetch, m as DaemonUnavailable, n as hubWriter, o as fetchDenial, p as DaemonRunning, r as writtenLines, s as hookAnswer, t as CONFIRM_MS, u as planFlush, v as silentHint, w as ENV, x as oversizedFiles } from "./operation-DlR1P_Pt.js";
+import { A as hubName, C as readRemote, D as Unreachable, E as ServerError, F as syncPaths, M as SETTINGS_FILE, O as ENV, T as ServerApi, _ as DaemonUnavailable, a as versionGate, b as readDaemon, c as oversizedFiles, d as planAnnounce, f as planFetch, g as DaemonRunning, h as startDaemon, i as requireWritableVersion, j as syncSettings, k as earlierToken, l as fetchDenial, m as toolCallOf, n as hubWriter, o as queuedCount, p as planFlush, r as writtenLines, s as remoteMode, t as CONFIRM_MS, u as hookAnswer, v as callDaemon, w as HubRewritingError, x as silentHint, y as probeDaemon } from "./operation-BhBbGauo.js";
 import { COMMAND_SPECS, OPTIONS } from "./facts.js";
+import { t as CLI_VERSION } from "./version-Dvv4jwF1.js";
 import { hookFallback, parsePayload, runHook } from "./hooks.js";
-import { f as CLI_VERSION, i as launchUi, l as startUiInBackground, r as exitCodeFor, u as watchHubGone } from "./launch-CMeKJsNd.js";
+import { exitCodeFor, launchUi, networkProbe, readUiRecord, startUiInBackground, watchHubGone } from "./launch.js";
 import { randomBytes } from "node:crypto";
 import { existsSync, readFileSync, readdirSync, realpathSync, rmSync, statSync } from "node:fs";
 import { basename, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
+//#region src/migration.ts
+/**
+* What `mainflow migrate` prints of a migration's report, the same whether the hub's files are here or on the sync
+* server: the formats, each file written and removed, and the open entries still missing a definition of done.
+*/
+function migrationLines(report, dryRun) {
+	return [
+		`format ${report.from} → ${report.to}${dryRun ? " (dry run, nothing written)" : ""}`,
+		...report.written.map((file) => `  ${dryRun ? "would write" : "wrote"}   ${file}`),
+		...report.removed.map((file) => `  ${dryRun ? "would remove" : "removed"} ${file}`),
+		...report.missingDefinitions.length ? [`${report.missingDefinitions.length} open entries still need a definition of done; fill them in the files:`, ...report.missingDefinitions.map((entry) => `  ${entry}`)] : []
+	];
+}
+//#endregion
 //#region src/remote/sync.ts
 /**
 * Run the sync client for the hub at `root` until the process is told to stop, or the hub's directory goes. A write
 * that found no sync client may have started this one in the background (src/remote/start.ts); a clean stop clears
 * that record, so the next write does not take the stop for a failed start.
 */
-async function syncRun(root) {
-	const settings = syncSettings(root);
-	if (!settings) {
-		const earlier = earlierToken(root);
-		console.error(earlier ? `✗ ${earlier}` : `✗ no service token for the sync server: set ${ENV.clientId} and ${ENV.clientSecret}, or clientId and clientSecret in .mainflow/${SETTINGS_FILE}`);
-		return 1;
-	}
-	const running = await probeDaemon(root);
+async function syncRun(dirs) {
+	const settings = serverOf(dirs);
+	if (!settings) return 1;
+	const running = await probeDaemon(dirs);
 	if (running && running.state !== "gone") {
 		console.error(`✗ mainflow sync already runs for this hub (pid ${running.daemon.pid})${running.state === "silent" ? `; ${silentHint(running.daemon)}` : ""}`);
 		return 1;
@@ -43,7 +54,7 @@ async function syncRun(root) {
 	let daemon;
 	try {
 		daemon = await startDaemon({
-			root,
+			dirs,
 			settings,
 			log: (line) => console.log(line)
 		});
@@ -56,15 +67,15 @@ async function syncRun(root) {
 	await new Promise((resolve) => {
 		process.once("SIGINT", resolve);
 		process.once("SIGTERM", resolve);
-		watchHubGone(root, resolve);
+		watchHubGone(dirs, resolve);
 	});
 	await daemon.stop();
-	forgetStarted(root);
+	forgetStarted(dirs);
 	process.exit(0);
 }
 /** Clear the record of a background start when it names this process. */
-function forgetStarted(root) {
-	const file = syncPaths(root).started;
+function forgetStarted(dirs) {
+	const file = syncPaths(dirs).started;
 	try {
 		if (JSON.parse(readFileSync(file, "utf8")).pid === process.pid) rmSync(file, { force: true });
 	} catch {}
@@ -78,57 +89,89 @@ function readPayload() {
 	}
 }
 /**
-* Send every change now and report what did not reach the hub as written. With `hook`, read the PostToolUse
-* payload from stdin, skip tools that wrote nothing synced, and answer as the hook: a block with the problems as
-* the reason, or nothing. A hook never fails the tool, so without a running sync client it answers nothing.
+* The hub a sync hook acts on, from its payload: the registered hub whose data directory holds the file the tool names
+* (tool_input.file_path, relative to the payload's cwd), or, for a tool that names no file, such as Bash, the hub of the
+* payload's cwd, then of CLAUDE_PROJECT_DIR. Null when there is none, or the registry cannot be read: the hook then
+* answers nothing, so the forwarding script can hand the CLI every call without deciding which ones touch a hub.
+* A hub found is checked by the version gate as the `hook` command checks its hub: a version outside the range the
+* hub's config.yaml names is warned about on stderr and never blocks the hook.
 */
-async function syncFlush(root, hook) {
-	const payload = hook ? readPayload() : {};
-	const daemon = readDaemon(root);
+function hookHub(payload, cwd, env = process.env) {
+	const base = typeof payload.cwd === "string" && payload.cwd ? payload.cwd : cwd;
+	const file = payload.tool_input?.file_path;
+	let hub = null;
+	try {
+		if (typeof file === "string" && file) hub = hubHoldingFile(resolve(base, file), env);
+		else for (const dir of [base, env.CLAUDE_PROJECT_DIR]) {
+			hub = dir && existsSync(dir) ? resolveHub(dir, {
+				env,
+				waitForLock: false
+			}) : null;
+			if (hub) break;
+		}
+	} catch (error) {
+		console.error(`mainflow sync --hook: ${error.message}`);
+		return null;
+	}
+	if (hub) {
+		const verdict = versionGate(hub, CLI_VERSION, { writes: false });
+		if (verdict.kind !== "run") console.error(`! ${verdict.message}`);
+	}
+	return hub;
+}
+/** Send every change now and report what did not reach the hub as written. */
+async function syncFlush(dirs) {
+	const daemon = readDaemon(dirs);
 	if (!daemon) {
-		if (hook) return 0;
 		console.error("✗ mainflow sync is not running for this hub");
 		return 1;
 	}
-	let body = {};
-	if (hook) {
-		const plan = planFlush(root, payload);
-		if (plan.skip) return 0;
-		const call = toolCallOf(payload);
-		body = {
-			...plan.edit ? { edit: plan.edit } : {
-				tool: true,
-				...plan.path === void 0 ? {} : { path: plan.path }
-			},
-			...call ? { call } : {}
-		};
-	}
+	const result = await callDaemon(daemon, "/flush", {}, 3e4);
+	for (const problem of result.problems) console.log(`! ${problem.message}`);
+	console.log(`${result.problems.length} problems, ${result.queued} queued, ${result.online ? "online" : "offline"}`);
+	return result.problems.length > 0 ? 1 : 0;
+}
+/**
+* `sync flush --hook`: read the PostToolUse payload from stdin, skip tools that wrote nothing synced, and answer as the
+* hook: a block with the problems as the reason, or nothing. A hook never fails the tool, so outside a registered
+* hub, or without a running sync client, it answers nothing.
+*/
+async function syncFlushHook(cwd) {
+	const payload = readPayload();
+	const dirs = hookHub(payload, cwd);
+	const daemon = dirs ? readDaemon(dirs) : null;
+	if (!dirs || !daemon) return 0;
+	const plan = planFlush(dirs, payload);
+	if (plan.skip) return 0;
+	const call = toolCallOf(payload);
+	const body = {
+		...plan.edit ? { edit: plan.edit } : {
+			tool: true,
+			...plan.path === void 0 ? {} : { path: plan.path }
+		},
+		...call ? { call } : {}
+	};
 	let result;
 	try {
 		result = await callDaemon(daemon, "/flush", body, 3e4);
 	} catch (error) {
-		if (hook && error instanceof DaemonUnavailable) return 0;
+		if (error instanceof DaemonUnavailable) return 0;
 		throw error;
 	}
-	if (hook) {
-		const answer = hookAnswer(result);
-		if (answer) console.log(answer);
-		return 0;
-	}
-	for (const problem of result.problems) console.log(`! ${problem.message}`);
-	console.log(`${result.problems.length} problems, ${result.queued} queued, ${result.online ? "online" : "offline"}`);
-	return result.problems.length > 0 ? 1 : 0;
+	const answer = hookAnswer(result);
+	if (answer) console.log(answer);
+	return 0;
 }
 /** How long a download may take before the command or the hook gives up on the sync client's answer. */
 const FETCH_MS = 3e4;
 /**
 * What `target` names, as the sync client takes it: a mainline (m001) or a task (m001/t002), as its directory with every
-* file under it, or a path, from the current directory or from .mainflow/. Null when it names nothing of the hub.
+* file under it, or a path: from the current directory, as `.mainflow/{path}`, or from the hub's data directory. Null when it names nothing of the hub.
 */
-function fetchSpec(root, target) {
+function fetchSpec(dirs, target) {
 	const ref = /^(m\d{3})(?:\/(t\d{3}))?$/.exec(target);
 	if (ref) {
-		const dirOf = (parent, id) => existsSync(join(root, ".mainflow", parent)) ? readdirSync(join(root, DATA_DIR, parent)).find((name) => name.startsWith(`${id}-`)) : void 0;
+		const dirOf = (parent, id) => existsSync(join(dirs.data, parent)) ? readdirSync(join(dirs.data, parent)).find((name) => name.startsWith(`${id}-`)) : void 0;
 		const mainline = dirOf("mainlines", ref[1]);
 		if (!mainline) return null;
 		if (!ref[2]) return `mainlines/${mainline}/`;
@@ -136,33 +179,34 @@ function fetchSpec(root, target) {
 		return task ? `mainlines/${mainline}/tasks/${task}/` : null;
 	}
 	const inHub = (file) => {
-		const path = relative(join(root, DATA_DIR), file).split(sep).join("/");
+		const path = relative(dirs.data, file).split(sep).join("/");
 		return path === "" || path.startsWith("../") || path === ".." || isAbsolute(path) ? null : path;
 	};
-	return inHub(resolve(process.cwd(), target)) ?? (isAbsolute(target) ? null : inHub(join(root, ".mainflow", target)));
+	if (isAbsolute(target)) return inHub(target);
+	const named = target === ".mainflow" || target.startsWith(`.mainflow/`) ? dataFile(dirs, target) : join(dirs.data, target);
+	return inHub(resolve(process.cwd(), target)) ?? inHub(named);
 }
 /**
 * Download files only on the sync server, the artifacts of closed mainlines an environment with on-demand downloads
-* left there: one file, a directory, or a mainline's or task's, by its ID. With `hook`, read the PreToolUse payload from
-* stdin instead: a Read, Edit, Write or MultiEdit of an artifact that is not here downloads it first, when the host runs
+* left there: one file, a directory, or a mainline's or task's, by its ID. As a hook (syncFetchHook), it reads the
+* PreToolUse payload from stdin instead: a Read, Edit, Write or MultiEdit of an artifact that is not here downloads it first, when the host runs
 * the hook for it (Claude Code answers an Edit of a missing file before its hooks). A Read then goes ahead; a write is
 * stopped with the reason, so the agent reads the file before writing over it. When it cannot be
 * downloaded, or no sync client runs, the tool is stopped with the reason, so the agent does not take the file for one
 * that does not exist. An Edit of one replacement of a synced file here is announced to the sync client. Anything else
 * answers nothing.
 */
-async function syncFetch(root, target, hook) {
-	if (hook) return syncFetchHook(root, readPayload());
+async function syncFetch(dirs, target) {
 	if (target === void 0) {
 		console.error("✗ Usage: mainflow sync fetch <path|m|m/t> (or --hook for a PreToolUse hook)");
 		return 1;
 	}
-	const spec = fetchSpec(root, target);
+	const spec = fetchSpec(dirs, target);
 	if (spec === null) {
 		console.error(`✗ ${target} names no mainline, task or path in .mainflow/`);
 		return 1;
 	}
-	const daemon = readDaemon(root);
+	const daemon = readDaemon(dirs);
 	if (!daemon) {
 		console.error("✗ mainflow sync is not running for this hub; start it with mainflow sync, then fetch again");
 		return 1;
@@ -192,9 +236,9 @@ const ANNOUNCE_MS = 2e3;
 * rather than being taken for a rewrite of an older version (docs/sync.md "等 Edit 的回報"). Silent whatever happens:
 * without a sync client, or with one older than the announcement, which answers 404, the change is sent as unannounced.
 */
-async function announceEdit(root, payload) {
-	const edit = planAnnounce(root, payload);
-	const daemon = edit ? readDaemon(root) : null;
+async function announceEdit(dirs, payload) {
+	const edit = planAnnounce(dirs, payload);
+	const daemon = edit ? readDaemon(dirs) : null;
 	if (!edit || !daemon) return 0;
 	try {
 		const call = toolCallOf(payload);
@@ -205,14 +249,24 @@ async function announceEdit(root, payload) {
 	} catch {}
 	return 0;
 }
-async function syncFetchHook(root, payload) {
-	const plan = planFetch(root, payload);
-	if (!plan) return announceEdit(root, payload);
+/**
+* `sync fetch --hook`: read the PreToolUse payload from stdin and act on the file it names when that file is in a
+* registered hub's data directory (hookHub); any other call answers nothing.
+*/
+async function syncFetchHook(cwd) {
+	const payload = readPayload();
+	const file = payload.tool_input?.file_path;
+	const dirs = typeof file === "string" && file ? hookHub(payload, cwd) : null;
+	return dirs ? fetchAsHook(dirs, payload) : 0;
+}
+async function fetchAsHook(dirs, payload) {
+	const plan = planFetch(dirs, payload);
+	if (!plan) return announceEdit(dirs, payload);
 	const deny = (reason) => {
 		console.log(fetchDenial(reason));
 		return 0;
 	};
-	const daemon = readDaemon(root);
+	const daemon = readDaemon(dirs);
 	let result = null;
 	let busy = false;
 	if (daemon) try {
@@ -221,7 +275,7 @@ async function syncFetchHook(root, payload) {
 		busy = error instanceof DaemonUnavailable && error.silent;
 	}
 	if (!result) {
-		if (!(plan.path in readRemote(root))) return 0;
+		if (!(plan.path in readRemote(dirs))) return 0;
 		if (busy) return deny(`.mainflow/${plan.path} is only on the sync server and is not downloaded yet: mainflow sync did not answer within ${FETCH_MS / 1e3} s, as it is busy, such as with a large snapshot. Try again shortly, or run mainflow sync fetch ${plan.path}; the file exists, do not take it for missing.`);
 		return deny(`.mainflow/${plan.path} is only on the sync server and is not downloaded here, and mainflow sync is not running, so it cannot be downloaded now. Start mainflow sync and run mainflow sync fetch ${plan.path}; the file exists, do not take it for missing.`);
 	}
@@ -234,8 +288,8 @@ async function syncFetchHook(root, payload) {
 	if (plan.write) return deny(`.mainflow/${plan.path} was only on the sync server and is downloaded now. Read it before writing to it, so the write starts from what it holds.`);
 	return 0;
 }
-async function syncStatus(root) {
-	const probe = await probeDaemon(root);
+async function syncStatus(dirs) {
+	const probe = await probeDaemon(dirs);
 	if (probe?.state === "silent") {
 		console.log(`mainflow sync runs for this hub (pid ${probe.daemon.pid}), but ${silentHint(probe.daemon)}`);
 		return 0;
@@ -247,12 +301,403 @@ async function syncStatus(root) {
 		if (status?.waitingForUpload) console.log("! the sync server has no copy of this hub, and this environment downloads on demand, so it does not upload its copy; run mainflow sync with on-demand downloads off in an environment that keeps every file of the hub to upload it");
 		return 0;
 	}
-	const queue = queuedCount(root);
-	console.log(`mainflow sync is not running; ${remoteMode(root) ? `${queue} write(s) wait in the outbox until it runs` : "writes go to the local files"}`);
-	const earlier = remoteMode(root) ? null : earlierToken(root);
+	const queue = queuedCount(dirs);
+	console.log(`mainflow sync is not running; ${remoteMode(dirs) ? `${queue} write(s) wait in the outbox until it runs` : "writes go to the local files"}`);
+	const earlier = remoteMode(dirs) ? null : earlierToken(dirs);
 	if (earlier) console.error(`! ${earlier}`);
 	return 0;
 }
+/**
+* The service token and the server of the hub at `root`, with this CLI's version for every request to say
+* (VERSION_HEADER), or null after saying why there are none.
+*/
+function serverOf(dirs) {
+	const settings = syncSettings(dirs);
+	if (settings) return {
+		...settings,
+		version: CLI_VERSION
+	};
+	const earlier = earlierToken(dirs);
+	console.error(earlier ? `✗ ${earlier}` : `✗ no service token for the sync server: set ${ENV.clientId} and ${ENV.clientSecret}, or clientId and clientSecret in .mainflow/${SETTINGS_FILE}`);
+	return null;
+}
+/** What `target` names on the server: a mainline's or task's directory, or a path; null for the whole hub, undefined when it names nothing. */
+function historyPath(dirs, target) {
+	if (target === void 0) return null;
+	const spec = fetchSpec(dirs, target);
+	if (spec === null) {
+		console.error(`✗ ${target} names no mainline, task or path in .mainflow/`);
+		return;
+	}
+	return spec.replace(/\/+$/, "") || null;
+}
+/**
+* Run `call` against the sync server, saying why it failed: unreachable, refused, or a server from before the route,
+* which lacks `lacking`, like "change log".
+*/
+async function onServer(settings, call, lacking = "change log") {
+	const api = new ServerApi(settings);
+	try {
+		return await call(api);
+	} catch (error) {
+		if (error instanceof ServerError && error.status === 404 && !/hub name/.test(error.message)) {
+			console.error(`✗ the sync server at ${settings.url} has no ${lacking}, as one from before it does not; deploy the sync server of this mainflow version (apps/sync-server)`);
+			return null;
+		}
+		if (error instanceof ServerError || error instanceof Unreachable) {
+			console.error(`✗ ${error.message} (hub ${settings.hub} at ${settings.url})`);
+			return null;
+		}
+		throw error;
+	} finally {
+		api.close();
+	}
+}
+/** A time of the server's in this machine's time zone, to the second, as `ops list` shows them to the minute. */
+function localTime(iso) {
+	const d = new Date(iso);
+	return `${d.toLocaleDateString("sv-SE")}T${d.toTimeString().slice(0, 8)}`;
+}
+/** What a path held, short: a hash's first 7 digits, `dir`, or `-` for nothing. */
+const shortState = (state) => state === null ? "-" : state === "dir" ? "dir" : state.slice(0, 7);
+/** What a change did to its path, in a word. */
+function changeKind(before, after) {
+	const dir = before === "dir" || after === "dir";
+	if (before === null) return dir ? "dir created" : "created";
+	if (after === null) return dir ? "dir removed" : "removed";
+	if (BLOB_HASH.test(after) !== BLOB_HASH.test(before)) return BLOB_HASH.test(after) ? "made binary" : "made text";
+	return "changed";
+}
+/** Who sent a change: the first 8 characters of a service token's Client ID, or an email whole; `(here)` for this environment's. */
+function sourceLabel(source, settings) {
+	if (source === null) return "?";
+	const short = source.includes("@") ? source : source.slice(0, 8);
+	return source === settings.clientId ? `${short} (here)` : short;
+}
+/** How many changes `sync log` lists unless --limit says otherwise. */
+const LOG_LIMIT = 50;
+/**
+* List the changes the sync server logged, newest first: of a file or directory, a mainline's or a task's, or of the
+* whole hub. Each line is the change's seq, when the server made it, who sent it, the request, what it did and the
+* path, with what the path held before and after; --json prints the server's page as it is.
+*/
+async function syncLog(dirs, target, opts) {
+	const limit = opts.limit === void 0 ? LOG_LIMIT : Number(opts.limit);
+	if (!Number.isInteger(limit) || limit <= 0) {
+		console.error(`✗ --limit takes a whole number of changes above 0, e.g. --limit 100; got ${opts.limit}`);
+		return 1;
+	}
+	const path = historyPath(dirs, target);
+	const settings = path === void 0 ? null : serverOf(dirs);
+	if (path === void 0 || !settings) return 1;
+	const page = await onServer(settings, async (api) => {
+		const changes = [];
+		let first = null;
+		let after;
+		while (changes.length < limit && after !== null) {
+			const next = await api.changes({
+				...path === null ? {} : { path },
+				...after === void 0 ? {} : { after },
+				limit: limit - changes.length
+			});
+			first ??= next;
+			changes.push(...next.changes);
+			after = next.next;
+		}
+		return {
+			...first,
+			changes,
+			next: after ?? null
+		};
+	});
+	if (!page) return 1;
+	if (opts.json) {
+		console.log(JSON.stringify(page, null, 2));
+		return 0;
+	}
+	for (const change of page.changes) {
+		const op = `${change.op ?? "?"}${change.batch === void 0 ? "" : `#${change.batch}`}`;
+		console.log(`  ${change.seq}  ${localTime(change.at)}  ${sourceLabel(change.source, settings)}  ${op}  ${changeKind(change.before, change.after)}  ${change.path}  ${shortState(change.before)} → ${shortState(change.after)}`);
+	}
+	const more = page.next === null ? "" : `; older ones with --limit ${limit * 2}`;
+	console.log(`✓ ${page.changes.length} change${page.changes.length === 1 ? "" : "s"}${more}. The hub is at seq ${page.seq}, and can be put back to seq ${page.from} (${localTime(page.fromAt)}) or later`);
+	return 0;
+}
+/** How long `mainflow migrate` and `sync restore` wait before asking how far a rewrite in batches got: first, then each time after. */
+const REWRITE_POLL_FIRST_MS = 2e3;
+const REWRITE_POLL_MS = 5e3;
+const sleep$1 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Where a rewrite in batches is at, in words: its phase, its batches and the paths they changed. */
+function rewriteProgress(rewrite) {
+	const what = rewrite.kind === "migrate" ? "migrating" : "putting back";
+	const planned = rewrite.planned === void 0 ? "" : ` of ${rewrite.planned}`;
+	return `  … ${what}: ${rewrite.phase}, ${rewrite.batches} batch${rewrite.batches === 1 ? "" : "es"} written, ${rewrite.changed}${planned} paths changed`;
+}
+/**
+* Wait for the rewrite in batches `rewrite` to end, asking the server how far it got: after REWRITE_POLL_FIRST_MS, then
+* every REWRITE_POLL_MS, printing where it is at each time it moved on. The rewrite as it ended; one the server tells of
+* no more, since another started after it, is taken as done. A server that cannot be asked throws, as any call does; the
+* rewrite goes on regardless, and `mainflow sync log` shows its batches.
+*/
+async function awaitRewrite(api, rewrite) {
+	let last = "";
+	for (let wait = REWRITE_POLL_FIRST_MS;; wait = REWRITE_POLL_MS) {
+		const line = rewriteProgress(rewrite);
+		if (line !== last) console.log(line);
+		last = line;
+		await sleep$1(wait);
+		const now = (await api.rewrite()).rewrite;
+		if (now === null || now.startedAt !== rewrite.startedAt) return {
+			...rewrite,
+			state: "done"
+		};
+		rewrite = now;
+		if (rewrite.state !== "running") return rewrite;
+	}
+}
+/** The changes a rewrite in batches made: the hub's log from `rewrite.from` on to `rewrite.seq`, oldest first. */
+async function rewriteChanges(api, rewrite) {
+	const changes = [];
+	for (let after; after !== null;) {
+		const page = await api.changes({
+			...after === void 0 ? {} : { after },
+			limit: MAX_CHANGE_PAGE
+		});
+		changes.push(...page.changes.filter((change) => change.seq > rewrite.from && change.seq <= rewrite.seq));
+		after = page.changes.some((change) => change.seq <= rewrite.from) ? null : page.next;
+	}
+	return changes.reverse();
+}
+/** What a list of a rewrite holds past the REWRITE_LISTED it names, in words, or nothing. */
+const unlisted = (named, all, what) => all !== void 0 && all > named ? [`  … and ${all - named} more ${what}`] : [];
+/** What a restore did, or would do, to one path, in words. */
+const restoredLine = (step) => `  ${changeKind(step.from, step.to)}  ${step.path}  ${shortState(step.from)} → ${shortState(step.to)}`;
+/**
+* Put the hub, a mainline's or task's directory, or a path, back to what it held after a seq (--seq) or at a time
+* (--at, this machine's local time unless it names its offset), as a new change on the sync server, which the sync
+* clients take in. A path whose content the server no longer holds (missing), or one something outside the restore
+* holds the place of (kept: a directory something the log does not name is in, or a path below a file outside a
+* restore of one path), is left as it is and makes the command fail, after the rest is put back. --dry-run lists what
+* it would change and leave, from the restore applied and rolled back on the server, and fails as the restore would.
+*/
+async function syncRestore(dirs, target, opts) {
+	if (opts.seq === void 0 === (opts.at === void 0)) {
+		console.error("✗ name what to put the hub back to, either --seq <n>, a seq of mainflow sync log, or --at <time>, like --at 2026-10-19T15:30");
+		return 1;
+	}
+	const seq = opts.seq === void 0 ? void 0 : Number(opts.seq);
+	if (seq !== void 0 && !(Number.isInteger(seq) && seq >= 0)) {
+		console.error(`✗ --seq takes a seq of mainflow sync log, a whole number; got ${opts.seq}`);
+		return 1;
+	}
+	const at = opts.at === void 0 ? void 0 : Date.parse(opts.at);
+	if (at !== void 0 && Number.isNaN(at)) {
+		console.error(`✗ --at takes a time, this machine's local time unless it names its offset, like 2026-10-19T15:30 or 2026-10-19T15:30+08:00; got ${opts.at}`);
+		return 1;
+	}
+	const path = historyPath(dirs, target);
+	const settings = path === void 0 ? null : serverOf(dirs);
+	if (path === void 0 || !settings) return 1;
+	const request = {
+		...seq === void 0 ? { at } : { seq },
+		...path === null ? {} : { path }
+	};
+	const scope = path === null ? "the hub" : path;
+	const result = await onServer(settings, async (api) => {
+		if (opts.dryRun) {
+			const pages = [];
+			for (let after;;) {
+				const page = await api.restore({
+					...request,
+					dryRun: true,
+					...after === void 0 ? {} : { after }
+				});
+				if (!page.ok) return page.message;
+				if (page.value === "started") return `the sync server set off a restore for a dry run: ${page.rewrite.kind}`;
+				pages.push(page);
+				after = page.next;
+				if (after !== void 0) continue;
+				const { next: _next, ...first } = pages[0];
+				return {
+					...first,
+					files: pages.flatMap((p) => p.files),
+					missing: pages.flatMap((p) => p.missing),
+					kept: pages.flatMap((p) => p.kept)
+				};
+			}
+		}
+		const answer = await api.restore(request);
+		if (!answer.ok) return answer.message;
+		if (answer.value !== "started") return answer;
+		if (!opts.json) console.log(`  the sync server puts ${scope} back in batches; writes wait until it is done`);
+		return awaitRewrite(api, answer.rewrite).then(async (rewrite) => {
+			if (rewrite.state !== "done" || opts.json) return rewrite;
+			for (const change of await rewriteChanges(api, rewrite)) console.log(restoredLine({
+				path: change.path,
+				from: change.before,
+				to: change.after
+			}));
+			return rewrite;
+		});
+	});
+	if (result === null) return 1;
+	if (typeof result === "string") {
+		console.error(`✗ the sync server refused the restore: ${result}`);
+		return 1;
+	}
+	if ("kind" in result) return restoreEnded(dirs, target, scope, result, opts.json ?? false);
+	if (opts.json) {
+		console.log(JSON.stringify(result, null, 2));
+		return result.missing.length + result.kept.length > 0 ? 1 : 0;
+	}
+	const count = (n) => `${n} path${n === 1 ? "" : "s"}`;
+	for (const step of result.files) console.log(restoredLine(step));
+	const left = result.value === "planned" ? "would be left" : "was left";
+	for (const step of result.missing) console.log(missingLine(step, result.to, left));
+	for (const kept of result.kept) console.log(keptLine(kept, left));
+	if (result.value === "planned") {
+		console.log(`✓ putting ${scope} back to seq ${result.to} would change ${count(result.files.length)}; nothing was changed`);
+		return result.missing.length + result.kept.length > 0 ? 1 : 0;
+	}
+	if (result.value === "unchanged") console.log(`✓ ${scope} already holds what it held at seq ${result.to}; nothing was changed`);
+	else {
+		const undo = result.wholeAt === void 0 ? `; undo it with mainflow sync restore${target === void 0 ? "" : ` ${target}`} --seq ${result.seq - 1}` : "";
+		console.log(`✓ put ${scope} back to seq ${result.to}: ${count(result.files.length)} changed, as seq ${result.seq}${undo}`);
+		if (result.bookmark) console.log(bookmarkLine(result.bookmark));
+		if (!readDaemon(dirs)) console.log("! mainflow sync is not running for this hub; this copy takes the restore in once it runs");
+	}
+	return result.missing.length + result.kept.length > 0 ? 1 : 0;
+}
+/** A path a restore left, or would leave, since the server no longer holds what it held at `to`. */
+const missingLine = (step, to, left) => `! ${step.path}: the sync server no longer holds what it held at seq ${to} (${shortState(step.to)}), so it ${left} as it is`;
+/** A path a restore left, or would leave, since something outside it holds its place. */
+const keptLine = (kept, left) => `! ${kept} ${left} as it is: something outside what is put back holds its place, a file above it or, in a directory, something the change log does not name`;
+const bookmarkLine = (bookmark) => `  the Durable Object's point-in-time recovery bookmark from before it, kept 30 days: ${bookmark}`;
+/**
+* What a restore in batches came to, once it ended: the paths it left, and the restore that undoes it; or why it did
+* not finish, and how to go on. --json prints the rewrite as the server tells it. Fails as a restore done at once does.
+*/
+function restoreEnded(dirs, target, scope, rewrite, json) {
+	const missing = rewrite.missing ?? [];
+	const kept = rewrite.kept ?? [];
+	const failing = rewrite.state !== "done" || missing.length + kept.length > 0 ? 1 : 0;
+	if (json) {
+		console.log(JSON.stringify(rewrite, null, 2));
+		return failing;
+	}
+	if (rewrite.state !== "done") {
+		console.error(`✗ the restore on the sync server ${rewrite.state === "failed" ? "stopped partway" : "was refused"}: ${rewrite.message ?? ""}`);
+		const retry = `mainflow sync restore${target === void 0 ? "" : ` ${target}`} --seq ${rewrite.to}`;
+		if (rewrite.state === "failed") console.error(`  writes wait until it goes through: try it again with ${retry}, or put the whole hub back to before it with mainflow sync restore --seq ${rewrite.wholeAt ?? rewrite.from}`);
+		return 1;
+	}
+	for (const step of missing) console.log(missingLine(step, rewrite.to, "was left"));
+	for (const line of unlisted(missing.length, rewrite.counts?.missing, "paths whose content the server no longer holds")) console.log(line);
+	for (const path of kept) console.log(keptLine(path, "was left"));
+	for (const line of unlisted(kept.length, rewrite.counts?.kept, "paths something outside the restore holds the place of")) console.log(line);
+	const undo = rewrite.wholeAt === void 0 ? `; undo it with mainflow sync restore${target === void 0 ? "" : ` ${target}`} --seq ${rewrite.from}` : "";
+	if (rewrite.batches === 0) console.log(`✓ ${scope} already holds what it held at seq ${rewrite.to}; nothing was changed`);
+	else console.log(`✓ put ${scope} back to seq ${rewrite.to}: ${rewrite.changed} paths changed, as seq ${rewrite.from + 1} to ${rewrite.seq} in ${rewrite.batches} batches${undo}`);
+	if (rewrite.bookmark) console.log(bookmarkLine(rewrite.bookmark));
+	if (!readDaemon(dirs)) console.log("! mainflow sync is not running for this hub; this copy takes the restore in once it runs");
+	return failing;
+}
+/**
+* `mainflow migrate` of a hub the sync server keeps: the server converts the hub between the writes of every
+* environment, as one change, or for a hub of more paths than a batch of the server's in batches, each a change, while
+* it holds every write off; the command waits for them. The sync clients take it in as a snapshot. It prints the report
+* as a local migration does, and the command that puts the hub back to the seq before it. --dry-run lists what it would
+* write and remove. A migration that stopped partway is resumed by running it again.
+*/
+async function syncMigrate(dirs, opts) {
+	const dryRun = opts.dryRun ?? false;
+	const settings = serverOf(dirs);
+	if (!settings) return 1;
+	const outcome = await onServer(settings, async (api) => {
+		const reports = [];
+		let answer;
+		let attached = false;
+		try {
+			for (let after;;) {
+				answer = await api.migrate({
+					...dryRun ? { dryRun } : {},
+					...after === void 0 ? {} : { after }
+				});
+				if (!answer.ok) return { refused: answer.message };
+				if (answer.value !== "planned" || !answer.report) break;
+				reports.push(answer.report);
+				after = answer.next;
+				if (after === void 0) break;
+			}
+		} catch (error) {
+			if (!(error instanceof HubRewritingError && error.rewrite.kind === "migrate" && error.rewrite.state === "running" && !dryRun)) throw error;
+			console.log("  the sync server is migrating the hub in batches already, as another environment asked; waiting for it");
+			answer = {
+				ok: true,
+				value: "started",
+				from: error.rewrite.from,
+				rewrite: error.rewrite
+			};
+			attached = true;
+		}
+		if (answer.value === "planned") return {
+			report: reports.length === 0 ? null : {
+				...reports[0],
+				written: reports.flatMap((r) => r.written),
+				removed: reports.flatMap((r) => r.removed),
+				missingDefinitions: reports.flatMap((r) => r.missingDefinitions)
+			},
+			seq: answer.seq,
+			from: answer.from
+		};
+		if (answer.value !== "started") return {
+			report: answer.report ?? null,
+			seq: answer.seq,
+			from: answer.from,
+			...answer.bookmark ? { bookmark: answer.bookmark } : {}
+		};
+		if (!attached) console.log("  the sync server migrates the hub in batches; writes wait until it is done");
+		const rewrite = await awaitRewrite(api, answer.rewrite);
+		if (rewrite.state !== "done") return { ended: rewrite };
+		const changes = await rewriteChanges(api, rewrite);
+		const file = (state) => state !== null && state !== "dir";
+		return {
+			report: {
+				from: rewrite.format ?? 3,
+				to: 3,
+				written: changes.filter((change) => file(change.after)).map((change) => `${DATA_DIR}/${change.path}`),
+				removed: changes.filter((change) => change.after === null && file(change.before)).map((change) => `${DATA_DIR}/${change.path}`),
+				missingDefinitions: [...rewrite.missingDefinitions ?? [], ...unlisted(rewrite.missingDefinitions?.length ?? 0, rewrite.counts?.missingDefinitions, "entries").map((line) => line.trim())]
+			},
+			seq: rewrite.seq,
+			from: rewrite.from,
+			batches: rewrite.batches,
+			...rewrite.bookmark ? { bookmark: rewrite.bookmark } : {}
+		};
+	}, "migration route");
+	if (!outcome) return 1;
+	if ("refused" in outcome) {
+		console.error(`✗ the sync server refused the migration: ${outcome.refused}`);
+		return 1;
+	}
+	if ("ended" in outcome) {
+		const { ended } = outcome;
+		if (ended.state === "refused") console.error(`✗ the sync server refused the migration: ${ended.message ?? ""}; the hub was left as it was`);
+		else console.error(`✗ the migration on the sync server stopped partway: ${ended.message ?? ""}\n  writes wait until mainflow migrate goes on with it, or mainflow sync restore --seq ${ended.wholeAt ?? ended.from} puts the hub back to where it was before`);
+		return 1;
+	}
+	if (!outcome.report) {
+		console.log(`✓ the hub on the sync server is in the data format of this mainflow already; nothing was changed (seq ${outcome.seq})`);
+		return 0;
+	}
+	for (const line of migrationLines(outcome.report, dryRun)) console.log(line);
+	if (dryRun) return 0;
+	const as = outcome.batches === void 0 ? `as seq ${outcome.seq}` : `as seq ${outcome.from + 1} to ${outcome.seq} in ${outcome.batches} batches`;
+	console.log(`✓ migrated the hub on the sync server ${as}; undo it with mainflow sync restore --seq ${outcome.from}`);
+	if (outcome.bookmark) console.log(bookmarkLine(outcome.bookmark));
+	if (!readDaemon(dirs)) console.log("! mainflow sync is not running for this hub; this copy takes the migration in once it runs");
+	return 0;
+}
 //#endregion
 //#region src/retro.ts
 const int = (n) => Math.round(n).toLocaleString("en-US");
@@ -528,22 +973,22 @@ const write = (spec) => spec;
 * A group of another hub (`other-hub:w001`) must exist there when that hub is on this machine; the operation only
 * checks that the hub is registered, since a hub kept on another machine cannot be read from here.
 */
-const checkGroupOption = ({ root, opts }) => {
+const checkGroupOption = ({ dirs, opts }) => {
 	const ref = opts.group ? parseRef(opts.group) : null;
 	if (ref?.kind !== "group" || ref.hub === void 0) return;
-	const hub = loadHub(root);
+	const hub = loadHub(dirs);
 	if (ref.hub === hub.config.hub) return;
 	const remote = hub.remotes.find((r) => r.name === ref.hub);
 	if (remote?.hub && !remote.hub.groups.some((g) => g.id === ref.group)) throw new WriteError(`group ${ref.group} not found in hub "${ref.hub}"`);
 };
-/** Where a document an operation created or changed is, as the commands print it: .mainflow/... */
-const inData = (...parts) => join(DATA_DIR, ...parts);
+/** Where a document an operation created or changed is, as the commands print it: its absolute path in the hub's data directory. */
+const inData = (dirs, ...parts) => join(dirs.data, ...parts);
 const WRITES = {
 	"repo add": write({
 		op: "repo.add",
-		check: ({ root, args }) => {
+		check: ({ dirs, args }) => {
 			requireSlug(args[0]);
-			const target = resolve(root, args[1]);
+			const target = resolve(dirs.root, args[1]);
 			if (!existsSync(target) || !statSync(target).isDirectory()) throw new WriteError(`repo path ${args[1]} does not exist from the hub root (${target})`);
 		},
 		input: ({ args }) => ({
@@ -554,12 +999,13 @@ const WRITES = {
 	}),
 	"hub add": write({
 		op: "hub.add",
-		check: ({ root, args }) => {
+		check: ({ dirs, args }) => {
 			const [name, path] = [args[0], args[1]];
-			checkHubName(nodeStorage(root), name);
-			const target = resolve(root, path);
-			if (!existsSync(join(target, ".mainflow", "config.yaml"))) throw new WriteError(`no hub at ${path} from the hub root (${target})`);
-			const other = hubName(target);
+			checkHubName(nodeStorage(dirs), name);
+			const target = resolve(dirs.root, path);
+			const registered = hubAtRoot(target);
+			if (!registered) throw new WriteError(`no registered hub at ${path} from the hub root (${target}); register that hub with mainflow hub register first`);
+			const other = hubName(registered);
 			if (other !== name) throw new WriteError(`${path} holds hub "${other}"; register it as "${other}"`);
 		},
 		input: ({ args }) => ({
@@ -630,9 +1076,9 @@ const WRITES = {
 			serves: list(opts.serves),
 			before: opts.before
 		}),
-		print: ({ root }, ref) => {
+		print: ({ dirs }, ref) => {
 			done(`created ${ref}`);
-			return remindDuplicates(root, ref);
+			return remindDuplicates(dirs, ref);
 		}
 	}),
 	"action set": write({
@@ -656,10 +1102,10 @@ const WRITES = {
 				}
 			};
 		},
-		print: ({ root, args, opts }, action) => {
+		print: ({ dirs, args, opts }, action) => {
 			const ref = actionRef(opts, args[0]);
 			done(`updated ${ref} (${action.status})`);
-			return opts.status === "doing" ? remindDuplicates(root, ref) : 0;
+			return opts.status === "doing" ? remindDuplicates(dirs, ref) : 0;
 		}
 	}),
 	"new mainline": write({
@@ -671,7 +1117,7 @@ const WRITES = {
 			group: opts.group,
 			priority: opts.priority
 		}),
-		print: (_, { id, dir }) => done(`created ${id} ${inData(dir, MAINLINE_FILE)}`)
+		print: ({ dirs }, { id, dir }) => done(`created ${id} ${inData(dirs, dir, MAINLINE_FILE)}`)
 	}),
 	"new task": write({
 		op: "task.new",
@@ -683,7 +1129,7 @@ const WRITES = {
 			parent: opts.parent,
 			repo: opts.repo
 		}),
-		print: (_, { ref, dir }) => done(`created ${ref} ${inData(dir, TASK_FILE)}`)
+		print: ({ dirs }, { ref, dir }) => done(`created ${ref} ${inData(dirs, dir, TASK_FILE)}`)
 	}),
 	"new decision": write({
 		op: "decision.new",
@@ -696,7 +1142,7 @@ const WRITES = {
 			basis: opts.basis,
 			affects: opts.affects ? list(opts.affects) : void 0
 		}),
-		print: (_, { ref, file }) => done(`created ${ref} ${inData(file)}`)
+		print: ({ dirs }, { ref, file }) => done(`created ${ref} ${inData(dirs, file)}`)
 	}),
 	"new issue": write({
 		check: checkGroupOption,
@@ -709,7 +1155,7 @@ const WRITES = {
 			group: opts.group,
 			priority: opts.priority
 		}),
-		print: (_, { id, file }) => done(`created ${id} ${inData(file)}`)
+		print: ({ dirs }, { id, file }) => done(`created ${id} ${inData(dirs, file)}`)
 	}),
 	"new group": write({
 		op: "group.new",
@@ -721,7 +1167,7 @@ const WRITES = {
 			origin: opts.origin,
 			labels: opts.labels ? list(opts.labels) : void 0
 		}),
-		print: (_, { id, file }) => done(`created ${id} ${inData(file)}`)
+		print: ({ dirs }, { id, file }) => done(`created ${id} ${inData(dirs, file)}`)
 	}),
 	"group set": write({
 		op: "group.set",
@@ -744,7 +1190,7 @@ const WRITES = {
 			origin: opts.origin,
 			labels: opts.labels ? list(opts.labels) : void 0
 		}),
-		print: (_, { id, file }) => done(`created ${id} ${inData(file)}`)
+		print: ({ dirs }, { id, file }) => done(`created ${id} ${inData(dirs, file)}`)
 	}),
 	"mainline set": write({
 		check: checkGroupOption,
@@ -973,7 +1419,7 @@ const WRITES = {
 			section: args[1],
 			text: args[2]
 		}),
-		print: ({ args }, { file }) => done(`appended to ${args[0]} ## ${args[1].trim()} ${inData(file)}`)
+		print: ({ dirs, args }, { file }) => done(`appended to ${args[0]} ## ${args[1].trim()} ${inData(dirs, file)}`)
 	}),
 	"decision supersede": write({
 		op: "decision.supersede",
@@ -985,6 +1431,15 @@ const WRITES = {
 	})
 };
 /**
+* Commands outside WRITES that change the hub's files without the writer, with whether this run does (a dry run only
+* previews). The writer checks the mainflow version for WRITES (requireWritableVersion); run() checks these, and warns
+* about every other command, which only reads.
+*/
+const ALSO_WRITING = {
+	migrate: (opts) => !opts["dry-run"],
+	"sync restore": (opts) => !opts["dry-run"]
+};
+/**
 * Run a writing command. Locally, the operation runs on the hub's files under the write lock. In remote mode it is
 * applied here and put in the hub's outbox, and the command waits for the sync server's answer, which may give a
 * new entry another id; without an answer in time it ends with the write still in the outbox.
@@ -992,50 +1447,140 @@ const WRITES = {
 function runWrite(ctx, spec) {
 	spec.check?.(ctx);
 	const input = spec.input(ctx);
-	if (!remoteMode(ctx.root)) {
-		const code = spec.print(ctx, applyOperation(nodeStorage(ctx.root), spec.op, input, { now: nowMinute() }).value);
-		const earlier = earlierToken(ctx.root);
+	if (!remoteMode(ctx.dirs)) {
+		requireWritableVersion(ctx.dirs, CLI_VERSION);
+		const code = spec.print(ctx, applyOperation(nodeStorage(ctx.dirs), spec.op, input, { now: nowMinute() }).value);
+		const earlier = earlierToken(ctx.dirs);
 		if (earlier) console.error(`! ${earlier}`);
 		return code;
 	}
-	return hubWriter(ctx.root, process.env, { confirmMs: CONFIRM_MS })(spec.op, input).then((written) => {
+	return hubWriter(ctx.dirs, process.env, { confirmMs: CONFIRM_MS })(spec.op, input).then((written) => {
 		const code = spec.print(ctx, written.value);
 		for (const line of writtenLines(written)) (line.startsWith("!") ? console.error : console.log)(line);
 		return code;
 	});
 }
+/**
+* The lines describing a registered hub: its name and repository, its data directory, then each repository it is the
+* primary hub of or references.
+*/
+function hubLines(name, hub) {
+	const rows = [
+		[
+			"data",
+			"",
+			hub.data
+		],
+		...Object.entries(hub.repos).map(([repo, path]) => [
+			"primary",
+			repo,
+			path
+		]),
+		...Object.entries(hub.references).map(([repo, path]) => [
+			"reference",
+			repo,
+			path
+		])
+	];
+	const width = Math.max(0, ...rows.map(([, repo]) => repo.length));
+	return [`${name}  ${hub.root}`, ...rows.map(([role, repo, path]) => `  ${role.padEnd(9)}  ${repo.padEnd(width)}  ${path}`)];
+}
+/** Register the hub whose repository is `path` and print what the registry now holds for it. */
+function register(name, path, options = {}) {
+	const r = registerHub(name, path, process.env, options);
+	const moved = r.previous && r.previous.root !== r.entry.root ? ` (was ${r.previous.root})` : "";
+	const renamed = r.renamedFrom ? ` (registered as "${r.renamedFrom}" before)` : "";
+	console.log(`registered hub ${name} in ${registryFile()}${moved}${renamed}`);
+	for (const line of hubLines(name, r.entry)) console.log(line);
+	for (const repo of r.missing) console.error(`! repo ${repo} is not on this machine; it belongs to ${name} once it is`);
+	if (r.pending) console.error(`! hub ${name} has no data on this machine yet; set ${ENV.clientId} and ${ENV.clientSecret}, then run mainflow sync to download it from the sync server. Its repositories are matched once config.yaml is downloaded`);
+	return 0;
+}
+/**
+* Why the data in `dirs` cannot move now, or null: a sync client or the hub's interface running there keeps reading
+* and writing the old place, so it is stopped first.
+*/
+async function busyWith(dirs, name) {
+	const daemon = await probeDaemon(dirs);
+	if (daemon && daemon.state !== "gone") return `mainflow sync runs for hub "${name}" (pid ${daemon.daemon.pid}); stop it first, then run this again`;
+	const record = readUiRecord(dirs);
+	const server = record ? await networkProbe.serverAt(record.port) : null;
+	if (server && server.hub === name && (server.root === void 0 || server.root === dirs.root)) return `the interface of hub "${name}" runs on localhost:${record.port}${server.pid ? ` (pid ${server.pid})` : ""}; stop it first, then run this again`;
+	return null;
+}
+/** Move the data of the hub whose repository is `path` out of it, as `mainflow hub migrate-data` does, and say what happened. */
+async function migrateData(path, dryRun) {
+	const move = await migrateHubData(path, {
+		dryRun,
+		busy: busyWith
+	});
+	const size = `${move.files} ${move.files === 1 ? "file" : "files"}, ${move.bytes} bytes`;
+	const would = (done, plan) => dryRun ? plan : done;
+	console.log(`${would("moved", "would move")} the data of hub ${move.name}: ${move.from} → ${move.to} (${size})`);
+	console.log(`${would("registered", "would register")} hub ${move.name} in ${registryFile()} with its data in ${move.to}`);
+	if (move.notRenamed) console.error(`! could not rename ${move.from} (${move.notRenamed}); it stays where it is and the hub no longer reads it: rename or delete it yourself`);
+	else console.log(dryRun ? `would rename ${move.from} to ${move.kept}` : `kept the original as ${move.kept}; delete it once the hub works from ${move.to}`);
+	if (move.worktree) {
+		console.error(`! ${move.from} ${would("was", "is")} a git worktree; its .git file ${would("was", "would be")} left out and git ${would("was", "is")} not run. Once you no longer need the worktree, remove it from git with:`);
+		console.error(`  git -C ${move.root} worktree remove ${move.from}`);
+	}
+	return 0;
+}
+const warnLine = (message) => console.error(`! ${message}`);
 const RUNS = {
-	init: ({ root, args }) => done(`created ${relative(root, initHub(root, args[0]))}`),
-	status: ({ root, opts }) => printStatus(loadHub(root), opts.all ?? false),
-	check: ({ root }) => {
-		const hub = loadHub(root);
-		const problems = [...hub.problems, ...loadSessions(root).problems];
-		const oversized = oversizedFiles(root).map(({ path, bytes }) => ({
+	init: ({ cwd, args }) => {
+		const name = args[0];
+		const registered = readRegistry().hubs[name];
+		if (registered) throw new WriteError(`hub "${name}" is already registered, from ${registered.root} with its data in ${registered.data}; pick another name, or run mainflow hub unregister ${name} first`);
+		const data = userDataDir(name);
+		const created = initHub({
+			root: realPath(cwd) ?? cwd,
+			data
+		}, name);
+		console.log(`created ${realPath(created) ?? created}`);
+		try {
+			return register(name, cwd, { data });
+		} catch (error) {
+			rmSync(data, {
+				recursive: true,
+				force: true
+			});
+			throw error;
+		}
+	},
+	"hub register": ({ cwd, args }) => register(args[0], resolve(cwd, args[1])),
+	"hub migrate-data": ({ cwd, args, opts }) => migrateData(resolve(cwd, args[0]), opts["dry-run"] ?? false),
+	"hub list": () => {
+		const { hubs } = listHubs({ warn: warnLine });
+		for (const [name, hub] of Object.entries(hubs)) for (const line of hubLines(name, hub)) console.log(line);
+		const count = Object.keys(hubs).length;
+		return done(`${count} ${count === 1 ? "hub" : "hubs"} registered in ${registryFile()}`);
+	},
+	"hub unregister": ({ args }) => done(`unregistered hub ${args[0]} (${unregisterHub(args[0]).root})`),
+	status: ({ dirs, opts }) => printStatus(loadHub(dirs), opts.all ?? false),
+	check: ({ dirs }) => {
+		const hub = loadHub(dirs);
+		const problems = [...hub.problems, ...loadSessions(dirs).problems];
+		const oversized = oversizedFiles(dirs).map(({ path, bytes }) => ({
 			file: `${DATA_DIR}/${path}`,
 			field: "",
-			message: `${bytes} bytes, more than the ${MAX_FILE_BYTES} the sync server keeps of a file, so mainflow sync leaves it out and other environments do not see it; split it, or add it to .mainflow/.gitignore`
+			message: `${bytes} bytes, more than the ${MAX_FILE_BYTES} the sync server keeps of a file, so mainflow sync leaves it out and other environments do not see it; split it, or move it into a scratch/ directory, which is never synced`
 		}));
 		const warnings = [...hub.warnings, ...oversized];
-		printProblems(warnings, "!");
+		printProblems(warnings, "!", dirs);
 		if (problems.length === 0) return done(`✓ ${hub.mainlines.length} mainlines, no problems${warnings.length ? `, ${warnings.length} ${warnings.length === 1 ? "warning" : "warnings"}` : ""}`);
-		printProblems(problems);
+		printProblems(problems, "✗", dirs);
 		return 1;
 	},
-	migrate: ({ root, opts }) => {
+	migrate: ({ dirs, opts }) => {
 		const dryRun = opts["dry-run"] ?? false;
-		const report = migrateHub(root, { dryRun });
-		console.log(`format ${report.from} → ${report.to}${dryRun ? " (dry run, nothing written)" : ""}`);
-		for (const file of report.written) console.log(`  ${dryRun ? "would write" : "wrote"}   ${file}`);
-		for (const file of report.removed) console.log(`  ${dryRun ? "would remove" : "removed"} ${file}`);
-		if (report.missingDefinitions.length) {
-			console.log(`${report.missingDefinitions.length} open entries still need a definition of done; fill them in the files:`);
-			for (const entry of report.missingDefinitions) console.log(`  ${entry}`);
-		}
+		if (remoteMode(dirs)) return syncMigrate(dirs, { dryRun });
+		for (const line of migrationLines(migrateHub(dirs, { dryRun }), dryRun)) console.log(line);
 		return 0;
 	},
-	ui: ({ root, opts }) => {
-		const config = loadHub(root).config;
-		launchUi(root, config.hub, config.ui?.port, {
+	ui: ({ dirs, opts }) => {
+		const config = loadHub(dirs).config;
+		launchUi(dirs, config.hub, config.ui?.port, {
 			port: opts.port,
 			open: !opts["no-open"]
 		}).then((result) => {
@@ -1046,13 +1591,13 @@ const RUNS = {
 		});
 		return 0;
 	},
-	"session show": ({ root, args, opts }) => {
+	"session show": ({ dirs, args, opts }) => {
 		const id = sessionOf(opts, args[0]);
-		const session = readSession(root, id);
+		const session = readSession(dirs, id);
 		if (!session) throw new WriteError(`session ${id} not found; start one with "mainflow session start"`);
-		return done(sessionBriefing(root, session, { cli: CLI }));
+		return done(sessionBriefing(dirs, session, { cli: CLI }));
 	},
-	wait: ({ root, args, opts }) => waitUntil(root, args[0], opts),
+	wait: ({ dirs, args, opts }) => waitUntil(dirs, args[0], opts),
 	hook: ({ args }) => {
 		let input = "";
 		try {
@@ -1080,8 +1625,8 @@ const RUNS = {
 			return 0;
 		});
 	},
-	"task show": ({ root, args }) => {
-		const { mainline, task } = findTask(loadHub(root), args[0]);
+	"task show": ({ dirs, args }) => {
+		const { mainline, task } = findTask(loadHub(dirs), args[0]);
 		console.log(`${mainline.id}/${task.id}  ${task.status.padEnd(8)}  ${task.kind}  ${task.title}`);
 		if (task.checklist.length === 0) console.log("  (no checklist items)");
 		for (const c of task.checklist) {
@@ -1092,42 +1637,52 @@ const RUNS = {
 		for (const link of task.links ?? []) console.log(`  ${link.rel} → ${link.to}${link.note ? `  ${link.note}` : ""}`);
 		return done(`${task.checklist.length} checklist items`);
 	},
-	"issue list": ({ root, opts }) => {
-		const shown = loadHub(root).issues.filter((i) => opts.all || i.status !== "closed");
+	"issue list": ({ dirs, opts }) => {
+		const shown = loadHub(dirs).issues.filter((i) => opts.all || i.status !== "closed");
 		for (const i of shown) console.log(`  ${i.id}  ${i.status.padEnd(7)}  ${i.title}${i.plannedIn ? `  → ${i.plannedIn}` : ""}${i.origin ? `  (from ${i.origin})` : ""}${i.group ? `  [${i.group}]` : ""}`);
 		return done(`${shown.length} issues`);
 	},
-	"group list": ({ root, opts }) => printGroups(loadHub(root), opts.all ?? false),
-	"group show": ({ root, args }) => printGroup(loadHub(root), loadSessions(root).sessions, args[0]),
-	"finding list": ({ root, opts }) => {
-		const shown = loadHub(root).findings.filter((f) => opts.all || f.status === "valid");
+	"group list": ({ dirs, opts }) => printGroups(loadHub(dirs), opts.all ?? false),
+	"group show": ({ dirs, args }) => printGroup(loadHub(dirs), loadSessions(dirs).sessions, args[0]),
+	"finding list": ({ dirs, opts }) => {
+		const shown = loadHub(dirs).findings.filter((f) => opts.all || f.status === "valid");
 		for (const f of shown) console.log(`  ${f.id}  ${f.created}  ${f.title}${f.labels?.length ? `  [${f.labels.join(", ")}]` : ""}`);
 		return done(`${shown.length} findings`);
 	},
-	"ops list": ({ root, opts }) => {
+	"ops list": ({ dirs, opts }) => {
 		const covers = (ref) => !opts.ref || ref !== void 0 && (ref === opts.ref || ref.startsWith(`${opts.ref}/`) || ref.startsWith(`${opts.ref}#`));
 		const local = (at) => {
 			const d = new Date(stampMs(at));
 			return `${d.toLocaleDateString("sv-SE")}T${d.toTimeString().slice(0, 5)}`;
 		};
-		const shown = loadHub(root).ops.filter((o) => (!opts.month || local(o.at).startsWith(opts.month)) && covers(o.ref));
+		const shown = loadHub(dirs).ops.filter((o) => (!opts.month || local(o.at).startsWith(opts.month)) && covers(o.ref));
 		for (const o of shown) console.log(`  ${local(o.at)}  ${o.target}  ${o.operation}  ${o.result}${o.ref ? `  ${o.ref}` : ""}`);
 		return done(`${shown.length} operations`);
 	},
-	retro: ({ root, args, opts }) => {
+	retro: ({ dirs, args, opts }) => {
 		const print = (report) => done(opts.json ? JSON.stringify(report, null, 2) : retroText(report));
 		const receiver = receiverFromEnv(process.env);
-		return receiver ? retroReportFromReceiver(root, args[0], receiver).then(print) : print(retroReport(root, args[0]));
+		return receiver ? retroReportFromReceiver(dirs, args[0], receiver).then(print) : print(retroReport(dirs, args[0]));
 	},
-	"decision list": ({ root, args }) => {
-		const mainline = findMainline(loadHub(root), args[0]);
+	"decision list": ({ dirs, args }) => {
+		const mainline = findMainline(loadHub(dirs), args[0]);
 		for (const d of mainline.decisions) console.log(`  ${mainline.id}/${d.id}  ${d.status.padEnd(10)}  ${d.title}`);
 		return done(`${mainline.decisions.length} decisions`);
 	},
-	sync: ({ root }) => syncRun(root),
-	"sync flush": ({ root, opts }) => syncFlush(root, opts.hook ?? false),
-	"sync fetch": ({ root, args, opts }) => syncFetch(root, args[0], opts.hook ?? false),
-	"sync status": ({ root }) => syncStatus(root)
+	sync: ({ dirs }) => syncRun(dirs),
+	"sync flush": (ctx) => ctx.opts.hook ? syncFlushHook(ctx.cwd) : syncFlush(ctx.dirs),
+	"sync fetch": (ctx) => ctx.opts.hook ? syncFetchHook(ctx.cwd) : syncFetch(ctx.dirs, ctx.args[0]),
+	"sync status": ({ dirs }) => syncStatus(dirs),
+	"sync log": ({ dirs, args, opts }) => syncLog(dirs, args[0], {
+		limit: opts.limit,
+		json: opts.json
+	}),
+	"sync restore": ({ dirs, args, opts }) => syncRestore(dirs, args[0], {
+		seq: opts.seq,
+		at: opts.at,
+		dryRun: opts["dry-run"],
+		json: opts.json
+	})
 };
 const COMMANDS = Object.fromEntries(Object.keys(COMMAND_SPECS).map((name) => [name, {
 	...COMMAND_SPECS[name],
@@ -1183,23 +1738,61 @@ function run(argv, cwd) {
 	if (!command) return fail(`Unknown command "${positionals.join(" ")}".\n\n${USAGE}`);
 	const args = positionals.slice(key.split(" ").length);
 	if (args.length < command.args || args.length > command.args + (command.optionalArgs ?? 0)) return fail(`Usage: mainflow ${command.usage}`);
-	let root = cwd;
-	if (command.needsHub) {
-		const found = findHubRoot(cwd);
-		if (!found) return fail("No .mainflow/config.yaml found in this directory or any parent. Run mainflow inside a hub repository.");
-		root = found;
+	let hub = null;
+	if (command.needsHub && !(opts.hook && HOOK_FINDS_HUB.has(key))) {
+		try {
+			hub = resolveHub(cwd, {
+				warn: warnLine,
+				waitForLock: !opts.hook
+			});
+		} catch (error) {
+			return reportError(error);
+		}
+		if (!hub) return fail(notRegisteredMessage(cwd));
+		if (!existsSync(join(hub.data, "config.yaml")) && !NEEDS_NO_CONFIG.has(key)) return fail(`✗ hub "${registeredName(hub) ?? "(unnamed)"}" has no config.yaml in ${hub.data} yet; set ${ENV.clientId} and ${ENV.clientSecret}, then run mainflow sync to download the hub from the sync server`);
+	}
+	const hookHub = () => {
+		try {
+			return resolveHub(cwd, { waitForLock: false });
+		} catch {
+			return null;
+		}
+	};
+	const gated = command.needsHub ? hub : key === "hook" ? hookHub() : null;
+	if (gated && !(key in WRITES)) {
+		const verdict = versionGate(gated, CLI_VERSION, { writes: ALSO_WRITING[key]?.(opts) ?? false });
+		if (verdict.kind === "refuse") return fail(`✗ refusing to write: ${verdict.message}`);
+		if (verdict.kind === "warn") console.error(`! ${verdict.message}`);
 	}
 	try {
-		const exit = command.run({
-			root,
+		const context = {
+			cwd,
+			get dirs() {
+				if (!hub) throw new Error(`mainflow ${key} runs outside a hub and has no hub directories`);
+				return hub;
+			},
 			args,
 			opts
-		});
+		};
+		const exit = command.run(context);
 		return typeof exit === "number" ? exit : exit.catch(reportError);
 	} catch (error) {
 		return reportError(error);
 	}
 }
+/** Commands that run in a registered hub whose config.yaml is not downloaded yet: they are how it gets downloaded, or read the server alone. */
+const NEEDS_NO_CONFIG = /* @__PURE__ */ new Set([
+	"sync",
+	"sync status",
+	"sync log",
+	"sync restore"
+]);
+/**
+* Commands that, run with --hook, find their hub from the hook's payload rather than the current directory, and answer
+* nothing outside a registered hub: the forwarding script hands them calls without deciding which hub they belong to
+* (docs/hooks.md 轉發腳本).
+*/
+const HOOK_FINDS_HUB = /* @__PURE__ */ new Set(["sync flush", "sync fetch"]);
 /** A refused write or an unreadable hub ends the command with its message; anything else is a bug and is thrown. */
 function reportError(error) {
 	if (error instanceof HubError) {
@@ -1228,9 +1821,9 @@ function sessionOf(opts, arg) {
 /** An action named as a{NNN} in the current session, or as {session}#a{NNN}. */
 const actionRef = (opts, arg) => /^a\d{3}$/.test(arg) ? `${sessionOf(opts)}#${arg}` : arg;
 /** Print a line for each running session already doing what this action serves; a reminder, so the exit code stays 0. */
-function remindDuplicates(root, ref) {
+function remindDuplicates(dirs, ref) {
 	const hash = ref.lastIndexOf("#");
-	for (const line of duplicateClaimLines(root, ref.slice(0, hash), ref.slice(hash + 1))) console.log(line);
+	for (const line of duplicateClaimLines(dirs, ref.slice(0, hash), ref.slice(hash + 1))) console.log(line);
 	return 0;
 }
 /** Exit codes of `wait`: the condition holds, the time ran out, or there is no condition to wait for. */
@@ -1257,7 +1850,7 @@ function seconds(value, fallback, name, zero) {
 * round, so a condition changed while waiting is the one checked; once the action leaves blocked or loses its
 * `until`, there is nothing left to wait for. A condition that can no longer come true ends the wait at once.
 */
-function waitUntil(root, arg, opts) {
+function waitUntil(dirs, arg, opts) {
 	let timeout;
 	let interval;
 	let ref;
@@ -1272,7 +1865,7 @@ function waitUntil(root, arg, opts) {
 		const hash = actionRef.lastIndexOf("#");
 		let session;
 		try {
-			session = readSession(root, actionRef.slice(0, hash));
+			session = readSession(dirs, actionRef.slice(0, hash));
 		} catch (error) {
 			return { error: error.message };
 		}
@@ -1293,7 +1886,7 @@ function waitUntil(root, arg, opts) {
 			text = until;
 		} else text = opts.until;
 		const parsed = parseUntil(text);
-		if (!parsed) return unusable(`"${text}" is not a condition; use one of ${UNTIL_HINT}`);
+		if (!parsed) return unusable(`"${text}" is not a condition: ${untilProblem(text)}`);
 		condition = parsed;
 	} catch (error) {
 		if (error instanceof WriteError) return unusable(error.message);
@@ -1301,7 +1894,7 @@ function waitUntil(root, arg, opts) {
 	}
 	const deadline = Date.now() + timeout * 1e3;
 	for (;;) {
-		const state = untilState(root, condition);
+		const state = untilState(dirs, condition);
 		if (state.met) return done(`✓ ${text}: ${state.detail}`);
 		if (state.unreachable) return unusable(`${text} can no longer hold: ${state.detail}`);
 		const left = deadline - Date.now();
@@ -1407,8 +2000,15 @@ function printGroup(hub, sessions, idInput) {
 	if (plan.active.length) console.log(`  服務組條件的行動：${work(plan.active)}`);
 	return done(`${plan.members.length} members`);
 }
-function printProblems(problems, mark = "✗") {
-	for (const problem of problems) console.error(`${mark} ${problem.file}${problem.field ? ` › ${problem.field}` : ""}: ${problem.message}`);
+/**
+* Print problems one a line. Given the hub's directories, each file is printed as its absolute path, which the reader
+* opens as it is; otherwise as the problem names it, `.mainflow/{path}`.
+*/
+function printProblems(problems, mark = "✗", dirs) {
+	for (const problem of problems) {
+		const file = dirs ? dataFile(dirs, problem.file) : problem.file;
+		console.error(`${mark} ${file}${problem.field ? ` › ${problem.field}` : ""}: ${problem.message}`);
+	}
 }
 const entry = process.argv[1];
 if (entry && realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url))) {