mainflow 0.42.0 → 0.43.0-alpha.2

package/dist/{host-BAMZmRy8.js → host-BJvqZy-i.js}

@@ -1,14 +1,20 @@
-import { $ as stampMs, A as TASK_REQUIRED_SECTIONS, B as mainlineSchema, C as RESERVED_HUB_NAMES, D as SLUG, E as SESSION_STATUS, F as decisionSchema, G as parseUntil, H as parseActionRef, I as findingSchema, J as sessionSchema, K as refExample, L as formatOpsEntry, M as UNTIL_FORMS, N as WORK_STATUS, O as SURVEY_LINES, P as configSchema, Q as OFFSET, R as groupSchema, S as REF_EXAMPLES, T as SESSION_ID, U as parseOpsLine, V as opsEntrySchema, W as parseRef, X as waitingForAction, Y as taskSchema, Z as waitingForRef, a as DECISION_SECTIONS, at as grantForm, b as MERGE_STATES, c as FINDING_SECTIONS, d as GROUP_SECTIONS, f as GROUP_STATUS, h as ISSUE_SECTIONS, i as DECISION_BASES, it as grantCovers, j as TASK_SECTIONS, k as SURVEY_SECTION, l as FINDING_STATUS, n as CLOSED_STATUS, ot as grantRepo, q as refMainline, r as DECIDERS, rt as describeRequest, s as DEFAULT_CATEGORIES, st as parseGrantTarget, v as MAINLINE_SECTIONS, w as SERVES_REF, x as PRIORITIES, y as MAINLINE_STATUS, z as issueSchema } from "./dist-zSabglPq.js";
+import { $ as removedUntil, A as SURVEY_LINES, B as groupSchema, C as PRIORITIES, D as SESSION_ID, E as SERVES_REF, F as WORK_STATUS, G as mainlineSchema, H as isMainflowRange, I as configSchema, J as parseOpsLine, K as opsEntrySchema, L as decisionSchema, M as TASK_REQUIRED_SECTIONS, N as TASK_SECTIONS, O as SESSION_STATUS, P as UNTIL_FORMS, Q as refMainline, R as findingSchema, S as MERGE_STATES, T as RESERVED_HUB_NAMES, U as issueSchema, V as hubRegistrySchema, W as listedRepos, X as parseUntil, Y as parseRef, Z as refExample, a as DECISION_SECTIONS, at as waitingForAction, b as MAINLINE_SECTIONS, c as FINDING_SECTIONS, ct as stampMs, d as GROUP_SECTIONS, et as repoPath, f as GROUP_STATUS, ft as describeRequest, g as ISSUE_SECTIONS, gt as parseGrantTarget, ht as grantRepo, i as DECISION_BASES, j as SURVEY_SECTION, k as SLUG, l as FINDING_STATUS, m as HUB_NAME, mt as grantForm, n as CLOSED_STATUS, nt as sessionSchema, ot as waitingForRef, pt as grantCovers, q as parseActionRef, r as DECIDERS, rt as taskSchema, s as DEFAULT_CATEGORIES, st as OFFSET, w as REF_EXAMPLES, x as MAINLINE_STATUS, y as MAINFLOW_RANGE, z as formatOpsEntry } from "./dist-D5rZ0MQH.js";
 import { a as LABEL_ROLES, i as FINDING_SEVERITIES, n as FINDING_CLASSES, r as FINDING_FIELDS, t as FINDINGS_FENCE } from "./retro-formats-ECy0gGOL.js";
 import { createHash } from "node:crypto";
-import { appendFileSync, closeSync, existsSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, symlinkSync, writeFileSync, writeSync } from "node:fs";
+import { appendFileSync, closeSync, cpSync, existsSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, symlinkSync, writeFileSync, writeSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, matchesGlob, parse, posix, relative, resolve, sep } from "node:path";
 import { execFileSync, spawn, spawnSync } from "node:child_process";
 import { parse as parse$1, stringify } from "yaml";
 import { homedir } from "node:os";
+import satisfies from "semver/functions/satisfies.js";
 import { performance } from "node:perf_hooks";
 import { gunzipSync, inflateRawSync } from "node:zlib";
 //#region ../core/dist/ops/document.js
+/**
+* How messages and the interface name the hub's data directory, whichever directory holds it on a machine: a file of
+* the hub is `.mainflow/{path}`, its path in the data directory. Also the name of the data directory inside a hub
+* repository before the data moved to the user's mainflow directory (`mainflow hub migrate-data`).
+*/
 const DATA_DIR = ".mainflow";
 const ENTRY_DIR = /^([mtdifw]\d{3})-(.+)$/;
 var WriteError = class extends Error {};
@@ -45,57 +51,92 @@ function stamps(ctx) {
 }
 //#endregion
 //#region ../core/dist/paths.js
-const isHub = (dir) => existsSync(join(dir, DATA_DIR, "config.yaml"));
-const git = (cwd, ...args) => {
-	const result = spawnSync("git", [
-		"-C",
-		cwd,
-		...args
-	], { encoding: "utf8" });
-	return result.status === 0 ? result.stdout.trim() : "";
-};
-/** The main working tree and the current working tree of the repository containing `cwd`, or null outside git. */
-function worktreesOf(cwd) {
-	const common = git(cwd, "rev-parse", "--path-format=absolute", "--git-common-dir");
-	const current = git(cwd, "rev-parse", "--show-toplevel");
-	if (!common.endsWith(`${sep}.git`) || !current) return null;
-	return {
-		main: dirname(common),
-		current
-	};
+/**
+* The absolute path of a file of the hub that messages and the interface name by its path in the data directory,
+* written `.mainflow/{path}` (hubPath). Any other path is taken as relative to the hub repository.
+*/
+function dataFile(dirs, named) {
+	if (named === ".mainflow") return dirs.data;
+	if (named.startsWith(`.mainflow/`)) return join(dirs.data, named.slice(10));
+	return resolve(dirs.root, named);
 }
-/** The branch checked out at `cwd`, or null outside git or on a detached HEAD. */
-function currentBranch(cwd) {
-	return git(cwd, "branch", "--show-current") || null;
+/**
+* How messages and the interface name `file`, an absolute path in the hub's data directory: `.mainflow/{path}`, with
+* `/` between names whatever the platform. The name is the same in every environment of the hub, wherever its data
+* directory is on each machine. A file outside the data directory keeps its absolute path.
+*/
+function hubPath(dirs, file) {
+	const path = relative(dirs.data, file);
+	if (path === "") return DATA_DIR;
+	if (path === ".." || path.startsWith(`..${sep}`) || isAbsolute(path)) return file;
+	return `${DATA_DIR}/${path.split(sep).join("/")}`;
 }
 /**
-* The hub for `cwd`: the first directory upwards holding `.mainflow/config.yaml`, except that a linked
-* worktree's checkout of a hub at the repository root resolves to the same hub in the main working tree.
-* A worktree is another checkout of the same repository, so without this every worktree would write its
-* own copy of the hub and the copies would conflict on merge. A hub below the root (a sample hub under
-* examples/, a scratch hub under tmp/) stays as found: it is data the worktree's own branch owns, and
-* mapping it would let tests and migrations in the worktree write the main tree's copy.
+* `path` as the file system spells it, symbolic links resolved, or null when it does not exist. The native call also
+* takes each name's case from the disk, so on a file system that ignores case (macOS and Windows by default) two
+* spellings of one directory come out the same, and on one that keeps case apart (Linux) they stay two directories.
 */
-function findHubRoot(cwd) {
-	let found = null;
-	for (let dir = cwd;; dir = dirname(dir)) {
-		if (isHub(dir)) {
-			found = dir;
-			break;
+function realPath(path) {
+	try {
+		return realpathSync.native(path);
+	} catch {
+		return null;
+	}
+}
+/**
+* The git checkout holding `dir`, read from the `.git` entries on disk without running git. `current` is the
+* checkout's root. `main` is the main working tree of the repository: the checkout itself, or, for a linked
+* worktree, the directory holding the `.git` directory its `gitdir` points into (through `commondir`); null
+* for a worktree of a bare repository, which has no main working tree. A submodule is a checkout of its own.
+*/
+function gitCheckout(dir) {
+	for (let at = resolve(dir);; at = dirname(at)) {
+		const dotGit = join(at, ".git");
+		const entry = statSync(dotGit, { throwIfNoEntry: false });
+		if (entry?.isDirectory()) return {
+			current: at,
+			main: at
+		};
+		if (entry?.isFile()) {
+			const gitdir = /^gitdir:\s*(.+?)\s*$/m.exec(readText$1(dotGit) ?? "")?.[1];
+			const commondir = gitdir ? readText$1(join(resolve(at, gitdir), "commondir"))?.trim() : void 0;
+			if (!gitdir || !commondir) return {
+				current: at,
+				main: at
+			};
+			const common = realPath(resolve(at, gitdir, commondir)) ?? resolve(at, gitdir, commondir);
+			return {
+				current: at,
+				main: basename(common) === ".git" ? dirname(common) : null
+			};
 		}
-		if (dirname(dir) === dir) break;
+		if (dirname(at) === at) return null;
 	}
-	const trees = worktreesOf(cwd);
-	if (!trees || trees.main === trees.current) return found;
-	if (found && found !== trees.current) return found;
-	return isHub(trees.main) ? trees.main : found;
 }
-function subdirs(dir) {
+/** The main working tree and the current working tree of the repository containing `cwd`, or null outside git or in a worktree of a bare repository. */
+function worktreesOf(cwd) {
+	const checkout = gitCheckout(realPath(cwd) ?? cwd);
+	return checkout?.main ? {
+		main: checkout.main,
+		current: checkout.current
+	} : null;
+}
+/** The branch checked out at `cwd`, or null outside git or on a detached HEAD. */
+function currentBranch(cwd) {
+	const result = spawnSync("git", [
+		"-C",
+		cwd,
+		"branch",
+		"--show-current"
+	], { encoding: "utf8" });
+	return (result.status === 0 ? result.stdout.trim() : "") || null;
+}
+function subdirs$1(dir) {
 	if (!existsSync(dir)) return [];
 	return readdirSync(dir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => join(dir, entry.name)).sort();
 }
 /** Read a UTF-8 file, or return null when it does not exist. */
-function readText(file) {
+function readText$1(file) {
 	return existsSync(file) ? readFileSync(file, "utf8") : null;
 }
 /** List every file below `dir`, sorted, skipping dot files. */
@@ -107,6 +148,586 @@ function listFiles(dir) {
 	}).filter((entry) => entry.isFile() && !entry.name.startsWith(".")).map((entry) => join(entry.parentPath, entry.name)).sort();
 }
 //#endregion
+//#region ../core/dist/storage/node.js
+const LOCK_WAIT_MS = 5e3;
+const LOCK_STALE_MS = 3e4;
+const sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+/**
+* Run `fn` while holding the hub-wide write lock in `local/` of the data directory `data`. When the lock had to create
+* that directory and `fn` refuses the write, the directory goes again, so a refused write leaves the hub as it was.
+*/
+function withLock(data, fn) {
+	const dir = join(data, "local");
+	const created = lockDir(data);
+	try {
+		return holdLock(join(dir, "write.lock"), fn);
+	} catch (error) {
+		if (created) removeIfEmpty(dir);
+		throw error;
+	}
+}
+/** withLock for an `fn` that waits on something, such as a request: the lock is held until its promise settles. */
+async function withLockAsync(data, fn) {
+	const dir = join(data, "local");
+	const lock = join(dir, "write.lock");
+	const created = lockDir(data);
+	try {
+		acquireLock(lock);
+	} catch (error) {
+		if (created) removeIfEmpty(dir);
+		throw error;
+	}
+	try {
+		return await fn();
+	} catch (error) {
+		rmSync(lock, { force: true });
+		if (created) removeIfEmpty(dir);
+		throw error;
+	} finally {
+		rmSync(lock, { force: true });
+	}
+}
+/**
+* Make `local/` of the data directory `data` for its lock, and say whether it had to. The data directory itself is never
+* made: a writer still holding a path the hub's data moved away from (mainflow hub migrate-data) fails here instead
+* of making an empty data directory there.
+*/
+function lockDir(data) {
+	try {
+		mkdirSync(join(data, "local"));
+		return true;
+	} catch (error) {
+		if (error.code === "EEXIST") return false;
+		if (error.code === "ENOENT") throw missingData(data);
+		throw error;
+	}
+}
+const missingData = (data) => new WriteError(`the hub's data directory ${data} does not exist; when the hub's data moved, run the command again, which reads where it is now from the hub registry`);
+function removeIfEmpty(dir) {
+	try {
+		rmdirSync(dir);
+	} catch {}
+}
+/**
+* Run `fn` while holding the lock file `lock`, created exclusively and removed afterwards. A lock older than
+* LOCK_STALE_MS belongs to a writer that died and is taken over; past `waitMs` (LOCK_WAIT_MS by default) the wait
+* ends with a WriteError saying `what` is locked. With `waitMs` 0 the lock is tried once and a held one fails at once.
+*/
+function holdLock(lock, fn, options = {}) {
+	acquireLock(lock, options);
+	try {
+		return fn();
+	} finally {
+		rmSync(lock, { force: true });
+	}
+}
+/**
+* Take the lock file `lock` as holdLock does; the caller removes it. When the lock's directory is gone, it is made
+* again, but not its parent: a lock whose whole directory moved away, as a hub's data directory does, fails instead.
+*/
+function acquireLock(lock, { what = "hub", waitMs = LOCK_WAIT_MS } = {}) {
+	const dir = dirname(lock);
+	const deadline = Date.now() + waitMs;
+	let vanished = 0;
+	for (;;) try {
+		const fd = openSync(lock, "wx");
+		writeSync(fd, String(process.pid));
+		closeSync(fd);
+		return;
+	} catch (error) {
+		if (error.code === "ENOENT") {
+			try {
+				mkdirSync(dir);
+			} catch (made) {
+				if (made.code === "ENOENT") throw what === "hub" ? missingData(dirname(dir)) : new WriteError(`${dirname(dir)}, which holds the lock of ${what}, does not exist`);
+				if (made.code !== "EEXIST") throw made;
+			}
+			continue;
+		}
+		if (error.code !== "EEXIST") throw error;
+		const held = statSync(lock, { throwIfNoEntry: false });
+		if (held && Date.now() - held.mtimeMs > LOCK_STALE_MS) {
+			rmSync(lock, { force: true });
+			continue;
+		}
+		if (Date.now() >= deadline) throw new WriteError(`${what} is locked by another writer (${lock}); retry in a moment`);
+		sleep(held ? 50 : Math.min(2 ** vanished++, 50));
+	}
+}
+/** Write through a temporary file and a rename, so a reader never sees half a file. */
+function writeAtomic(file, text) {
+	const temp = `${file}.${process.pid}.tmp`;
+	writeFileSync(temp, text);
+	renameSync(temp, file);
+}
+/** The hub at `dirs`, its data directory read and written on the local file system. */
+function nodeStorage(dirs) {
+	const file = (path) => join(dirs.data, path);
+	return {
+		read: (path) => {
+			const target = file(path);
+			return existsSync(target) ? readFileSync(target, "utf8") : null;
+		},
+		list: (dir) => {
+			const target = file(dir);
+			if (!existsSync(target)) return [];
+			return readdirSync(target, { withFileTypes: true }).map((entry) => ({
+				name: entry.name,
+				dir: entry.isDirectory()
+			})).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+		},
+		where: file,
+		write: (path, text) => {
+			mkdirSync(dirname(file(path)), { recursive: true });
+			writeAtomic(file(path), text);
+		},
+		append: (path, text) => {
+			mkdirSync(dirname(file(path)), { recursive: true });
+			appendFileSync(file(path), text);
+		},
+		makeDir: (path) => {
+			mkdirSync(file(path), { recursive: true });
+		},
+		remove: (path) => {
+			rmSync(file(path), { force: true });
+		},
+		lock: (fn) => withLock(dirs.data, fn)
+	};
+}
+//#endregion
+//#region ../core/dist/registry.js
+/** The registry's file name inside MAINFLOW_HOME. */
+const REGISTRY_FILE = "hubs.json";
+/** How a hub is registered, for the messages that ask for it. */
+const REGISTER_USAGE = "mainflow hub register <name> <path>";
+/** The user-level mainflow directory: MAINFLOW_HOME when set, ~/.mainflow otherwise. */
+const mainflowHome = (env = process.env) => resolve(env.MAINFLOW_HOME || join(homedir(), ".mainflow"));
+/** The registry file of the user-level mainflow directory. */
+const registryFile = (env = process.env) => join(mainflowHome(env), REGISTRY_FILE);
+/** The data directory of hub `name` in the user-level mainflow directory: $MAINFLOW_HOME/<name>. */
+const userDataDir = (name, env = process.env) => join(mainflowHome(env), name);
+/**
+* The data directory a hub kept inside its repository before its data moved to MAINFLOW_HOME, `<root>/.mainflow`, when
+* it holds a hub: what `mainflow hub migrate-data` moves.
+*/
+function inRepositoryData(root) {
+	const data = join(root, DATA_DIR);
+	const name = /^hub:\s*["']?([a-z0-9-]+)/m.exec(readText(join(data, "config.yaml")) ?? "")?.[1];
+	return name ? {
+		name,
+		data
+	} : null;
+}
+const readText = (file) => {
+	try {
+		return readFileSync(file, "utf8");
+	} catch {
+		return null;
+	}
+};
+const empty = () => ({
+	version: 1,
+	hubs: {}
+});
+/** The registry as the file holds it; empty when there is no file yet. */
+function readRegistry(env = process.env) {
+	const file = registryFile(env);
+	const text = readText(file);
+	if (text === null) return empty();
+	const redo = `fix it, or delete it and run ${REGISTER_USAGE} for each hub again`;
+	let data;
+	try {
+		data = JSON.parse(text);
+	} catch (error) {
+		throw new WriteError(`${file} is not JSON (${error.message}); ${redo}`);
+	}
+	const version = data?.version;
+	if (typeof version === "number" && version > 1) throw new WriteError(`${file} is format ${version}, written by a newer mainflow; this one reads format 1, so install the newer mainflow`);
+	const parsed = hubRegistrySchema.safeParse(data);
+	if (!parsed.success) throw new WriteError(`${file} is not a hub registry: ${parsed.error.issues.map((i) => `${i.path.join(".") || "(top)"}: ${i.message}`).join("; ")}; ${redo}`);
+	return parsed.data;
+}
+/**
+* Change the registry under its lock: read it, let `change` edit it, and write it back when it changed. The lock is
+* waited for as holdLock does, or with `wait` false tried once, so a hook never waits on another writer.
+*/
+function updateRegistry(env, change, wait = true) {
+	const file = registryFile(env);
+	mkdirSync(mainflowHome(env), { recursive: true });
+	return holdLock(`${file}.lock`, () => {
+		const registry = readRegistry(env);
+		const before = JSON.stringify(registry);
+		const result = change(registry);
+		const after = JSON.stringify(registry, null, 2);
+		if (JSON.stringify(registry) !== before) writeAtomic(file, `${after}\n`);
+		return result;
+	}, {
+		what: "the hub registry",
+		...wait ? {} : { waitMs: 0 }
+	});
+}
+/** The repositories a hub is the primary hub of, with the names config.yaml gives them; the hub repository first. */
+const primaries = (hub) => [["(the hub repository)", hub.root], ...Object.entries(hub.repos).filter(([, path]) => path !== hub.root)];
+/** Why the hub repository `root` cannot be registered with the data directory `data`, which holds no config.yaml. */
+function noDataMessage(root, data, env) {
+	const inRepository = inRepositoryData(root);
+	if (inRepository) return `hub "${inRepository.name}" still keeps its data inside its repository (${inRepository.data}); move it to ${mainflowHome(env)} and register the hub with: mainflow hub migrate-data ${root}`;
+	return `no hub data at ${data}: ${join(data, "config.yaml")} does not exist`;
+}
+/**
+* Whether the hub registered from `root` with the data directory `data` is a new environment: neither holds a
+* config.yaml. A repository that still keeps a hub's data inside it is not, since that data moves with
+* `mainflow hub migrate-data`.
+*/
+function awaitsData(root, data) {
+	const real = realPath(root);
+	if (!real) return false;
+	const dir = realPath(data) ?? resolve(data);
+	return readText(join(dir, "config.yaml")) === null && inRepositoryData(real) === null;
+}
+/** The entry of hub `name` whose files are not on this machine yet. */
+function pendingEntry(name, root, data) {
+	if (!HUB_NAME.test(name) || RESERVED_HUB_NAMES.includes(name)) throw new WriteError(`"${name}" is not a hub name: use lowercase letters, digits and hyphens, and not ${RESERVED_HUB_NAMES.join(" or ")}`);
+	const real = realPath(root);
+	if (!real) throw new WriteError(`${root} does not exist`);
+	mkdirSync(data, { recursive: true });
+	return {
+		name,
+		entry: {
+			root: real,
+			data: realPath(data) ?? resolve(data),
+			config: "",
+			repos: {},
+			references: {}
+		},
+		missing: []
+	};
+}
+/** The registry entry of the hub whose repository is `root` and whose data directory is `data`, derived from its config.yaml. */
+function derive(root, data, env) {
+	const real = realPath(root);
+	if (!real) throw new WriteError(`${root} does not exist`);
+	const dir = realPath(data) ?? resolve(data);
+	const file = join(dir, "config.yaml");
+	const text = readText(file);
+	if (text === null) throw new WriteError(noDataMessage(real, dir, env));
+	let raw;
+	try {
+		raw = parse$1(text);
+	} catch (error) {
+		throw new WriteError(`${file} is not valid YAML: ${error.message}`);
+	}
+	const parsed = configSchema.pick({
+		hub: true,
+		repos: true
+	}).safeParse(raw);
+	if (!parsed.success) throw new WriteError(`${file} is invalid: ${parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`);
+	const entry = {
+		root: real,
+		data: dir,
+		config: contentHash(text),
+		repos: {},
+		references: {}
+	};
+	const missing = [];
+	for (const repo of listedRepos(parsed.data.repos)) {
+		const listed = resolve(real, repo.path);
+		const path = realPath(listed);
+		if (!path) missing.push(`${repo.name} (${repo.path})`);
+		(repo.role === "primary" ? entry.repos : entry.references)[repo.name] = path ?? listed;
+	}
+	return {
+		name: parsed.data.hub,
+		entry,
+		missing
+	};
+}
+/** Each primary repository of `entry`, to be hub `name`, that another registered hub already has, one line each. */
+function claimConflicts(registry, name, entry) {
+	const out = [];
+	for (const [other, hub] of Object.entries(registry.hubs)) {
+		if (other === name || hub.root === entry.root) continue;
+		const theirs = new Set(primaries(hub).map(([, path]) => path));
+		for (const [repo, path] of primaries(entry)) {
+			if (!theirs.has(path)) continue;
+			out.push(`${repo === "(the hub repository)" ? "the hub repository" : `repo "${repo}"`} ${path} is already the primary repository of hub "${other}" (registered from ${hub.root})`);
+		}
+	}
+	return out;
+}
+/** The message for the conflicts claimConflicts found, opening with `lead`, and what to do about them. */
+const conflictMessage = (lead, conflicts) => [
+	lead,
+	...conflicts.map((c) => `  ${c}`),
+	"A repository has one primary hub. In the config.yaml of the hub that should only reference it, write it under repos as { path: ..., role: reference }, then run mainflow hub register again."
+].join("\n");
+/**
+* The data directory of hub `name` registered from the repository `root`: the one `options` names, else the one the
+* hub is registered with already, under this name or, when the hub was renamed, from this repository; else its
+* directory in MAINFLOW_HOME.
+*/
+function dataDirFor(registry, name, root, env) {
+	const real = realPath(root);
+	return registry.hubs[name]?.data ?? Object.values(registry.hubs).find((hub) => hub.root === real)?.data ?? userDataDir(name, env);
+}
+/**
+* Register the hub whose repository is `path`, or bring its entry up to date. `name` must be the name its config.yaml
+* gives it. Its data directory is `options.data` when given, as when its data has just moved there; otherwise the one
+* it is registered with already, or $MAINFLOW_HOME/<name> for a hub not registered yet. Refused when that directory
+* holds no hub, or when a repository the hub is the primary hub of is already another hub's primary repository. A new
+* environment (no entry yet, or one registered without data), where neither the repository nor that directory holds any hub data, is registered with only the name,
+* the repository and the data directory (`pending`); its repositories are matched, and checked against the other
+* hubs, once `mainflow sync` has downloaded config.yaml.
+*/
+function registerHub(name, path, env = process.env, options = {}) {
+	const data = options.data ?? dataDirFor(readRegistry(env), name, path, env);
+	let derived;
+	if (awaitsData(path, data)) {
+		const registry = readRegistry(env);
+		const real = realPath(path);
+		const [knownName, known] = registry.hubs[name] ? [name, registry.hubs[name]] : Object.entries(registry.hubs).find(([, hub]) => hub.root === real) ?? [];
+		if (known && known.config !== "") throw new WriteError(`${join(realPath(data) ?? resolve(data), "config.yaml")} does not exist, but hub "${knownName}" is registered with its data in ${known.data}; move the data back there, or run mainflow hub unregister ${knownName} and register it again`);
+		derived = pendingEntry(name, path, data);
+	} else derived = derivedAs(name, path, data, env);
+	return updateRegistry(env, (registry) => {
+		const registration = planRegistration(registry, name, derived);
+		if (registration.renamedFrom) delete registry.hubs[registration.renamedFrom];
+		registry.hubs[name] = derived.entry;
+		return registration;
+	});
+}
+/**
+* What registerHub would do with the same arguments, without writing the registry: it throws what registerHub would
+* refuse. `options.data` is required here, since the hub's data may not be in its directory yet.
+*/
+function previewRegistration(name, path, env, options) {
+	return planRegistration(readRegistry(env), name, derivedAs(name, path, options.data, env));
+}
+/** The entry of the hub at `path` with its data in `data`, which must be hub `name`. */
+function derivedAs(name, path, data, env) {
+	const derived = derive(path, data, env);
+	if (derived.name !== name) throw new WriteError(`${derived.entry.data} holds hub "${derived.name}"; register it as "${derived.name}"`);
+	return derived;
+}
+/** What registering `derived` as hub `name` changes in `registry`; refused when another hub has its repositories. */
+function planRegistration(registry, name, derived) {
+	const conflicts = claimConflicts(registry, name, derived.entry);
+	if (conflicts.length) throw new WriteError(conflictMessage(`hub "${name}" is not registered, since another hub already has its repositories:`, conflicts));
+	const previous = registry.hubs[name] ?? null;
+	const renamedFrom = Object.keys(registry.hubs).find((other) => other !== name && registry.hubs[other].root === derived.entry.root) ?? null;
+	return {
+		name,
+		entry: derived.entry,
+		previous,
+		renamedFrom,
+		missing: derived.missing,
+		pending: derived.entry.config === ""
+	};
+}
+/** Remove a hub from the registry; its files stay as they are. */
+function unregisterHub(name, env = process.env) {
+	return updateRegistry(env, (registry) => {
+		const hub = registry.hubs[name];
+		if (!hub) throw new WriteError(`hub "${name}" is not registered; registered: ${Object.keys(registry.hubs).join(", ") || "(none)"}`);
+		delete registry.hubs[name];
+		return hub;
+	});
+}
+/** Whether an entry may no longer say what its config.yaml says: the file changed, or a path it holds now resolves differently, as when a listed repository was cloned. */
+function stale(hub) {
+	const text = readText(join(hub.data, "config.yaml"));
+	if (text === null && hub.config === "") return false;
+	if (text === null || contentHash(text) !== hub.config) return true;
+	return [
+		hub.root,
+		hub.data,
+		...Object.values(hub.repos),
+		...Object.values(hub.references)
+	].some((path) => realPath(path) !== path);
+}
+/** Derive the entries of `names` again where stale; what cannot be updated keeps its entry and says why. */
+function refresh(registry, names, env) {
+	const warnings = [];
+	for (const name of names) {
+		const hub = registry.hubs[name];
+		if (!hub || !stale(hub)) continue;
+		let derived;
+		try {
+			derived = derive(hub.root, hub.data, env);
+		} catch (error) {
+			warnings.push(`hub "${name}" is registered from ${hub.root}, which cannot be read again (${error.message}); register it where it is now, or run mainflow hub unregister ${name}`);
+			continue;
+		}
+		if (derived.name !== name) {
+			warnings.push(`${hub.data} now holds hub "${derived.name}", registered as "${name}"; run mainflow hub register ${derived.name} ${hub.root}`);
+			continue;
+		}
+		const conflicts = claimConflicts(registry, name, derived.entry);
+		if (conflicts.length) {
+			warnings.push(conflictMessage(`the changed config.yaml of hub "${name}" is not applied, since another hub already has its repositories:`, conflicts));
+			continue;
+		}
+		registry.hubs[name] = derived.entry;
+	}
+	return warnings;
+}
+/**
+* The registry with the entries of `names` derived again where stale. The file is rewritten only when something
+* changed; when it cannot be, as when another writer holds the lock and `wait` is false, the updated entries are still
+* used for this run.
+*/
+function refreshed(env, names, warn, wait = true) {
+	const registry = readRegistry(env);
+	const probe = structuredClone(registry);
+	const warnings = refresh(probe, names, env);
+	if (JSON.stringify(probe) === JSON.stringify(registry)) {
+		warnings.forEach(warn);
+		return registry;
+	}
+	try {
+		return updateRegistry(env, (locked) => {
+			refresh(locked, names, env);
+			return locked;
+		}, wait);
+	} catch (error) {
+		warn(`cannot update ${registryFile(env)}: ${error.message}`);
+		return probe;
+	} finally {
+		warnings.forEach(warn);
+	}
+}
+/** Every registered hub, each entry brought up to date with its config.yaml first. */
+function listHubs(options = {}) {
+	const env = options.env ?? process.env;
+	return refreshed(env, Object.keys(readRegistry(env).hubs), options.warn ?? (() => {}));
+}
+const within = (path, dir) => path === dir || path.startsWith(dir.endsWith(sep) ? dir : dir + sep);
+/**
+* The hub whose primary repository or data directory holds `place` most closely, so a hub registered inside another
+* hub's repository wins there, and a command run in a hub's data directory runs on that hub. Paths are compared exactly
+* as given: they come from realPath, which spells them as the file system does.
+*/
+function hubClaiming(registry, place) {
+	let best = null;
+	for (const [name, hub] of Object.entries(registry.hubs)) for (const path of [...primaries(hub).map(([, path]) => path), hub.data]) if (within(place, path) && (!best || path.length > best.length)) best = {
+		name,
+		length: path.length
+	};
+	return best?.name ?? null;
+}
+/**
+* The places looked up for `cwd`, in order: its real path, matched against the registered paths that equal or hold it,
+* and for a linked worktree the root of the repository's main working tree, so every worktree of a repository belongs
+* to the hub of its main checkout. The git repository's root is not looked up on its own: when it is registered, the
+* real path of any directory in it already matches. The path inside the worktree is not carried over: a hub below the root of the main
+* checkout (a sample hub under examples/) is that checkout's data, not the worktree's.
+*/
+function places(cwd) {
+	const here = realPath(cwd) ?? resolve(cwd);
+	const checkout = gitCheckout(here);
+	return checkout?.main && checkout.main !== checkout.current ? [here, checkout.main] : [here];
+}
+const lookUp = (registry, spots) => {
+	for (const spot of spots) {
+		const name = hubClaiming(registry, spot);
+		if (name) return name;
+	}
+	return null;
+};
+/**
+* The hub `cwd` belongs to on this machine, from the registry alone, or null when no registered hub claims it. The
+* entry found is brought up to date with its config.yaml first, and the lookup repeated, since the change may have
+* moved the repository to another hub; when nothing claims `cwd`, every stale entry is, in case a change elsewhere
+* claims it now. `warn` receives what kept the entry found from being brought up to date. With `waitForLock` false, as
+* a hook asks, the registry's lock is tried once: when another writer holds it, the entries derived again are used
+* for this lookup without being written, so a hook never waits.
+*/
+function resolveHub(cwd, options = {}) {
+	const env = options.env ?? process.env;
+	const warn = options.warn ?? (() => {});
+	const wait = options.waitForLock ?? true;
+	const spots = places(cwd);
+	let registry = readRegistry(env);
+	let name = lookUp(registry, spots);
+	if (name) {
+		registry = refreshed(env, [name], warn, wait);
+		name = lookUp(registry, spots);
+	}
+	if (!name) {
+		registry = refreshed(env, Object.keys(registry.hubs), () => {}, wait);
+		name = lookUp(registry, spots);
+	}
+	const hub = name ? registry.hubs[name] : void 0;
+	return name && hub ? {
+		name,
+		root: hub.root,
+		data: hub.data
+	} : null;
+}
+/**
+* The registered hub whose data directory holds `file`, or null: a written file belongs to the hub whose data it is,
+* whichever directory the writer runs in. The innermost data directory wins.
+*/
+function hubHoldingFile(file, env = process.env) {
+	const dir = realPath(dirname(file));
+	const path = realPath(file) ?? (dir ? join(dir, basename(file)) : resolve(file));
+	let best = null;
+	for (const [name, hub] of Object.entries(readRegistry(env).hubs)) if (within(path, hub.data) && (!best || hub.data.length > best.data.length)) best = {
+		name,
+		root: hub.root,
+		data: hub.data
+	};
+	return best;
+}
+/** The name `dirs` is registered under, or null: how a hub whose config.yaml is not downloaded yet is told apart. */
+function registeredName(dirs, env = process.env) {
+	for (const [name, hub] of Object.entries(readRegistry(env).hubs)) if (hub.data === dirs.data && hub.root === dirs.root) return name;
+	return null;
+}
+/**
+* The registered hub whose repository is `root`, or null: how a hub reaches another hub its config.yaml lists under
+* `hubs` by the path of that hub's repository.
+*/
+function hubAtRoot(root, env = process.env) {
+	const real = realPath(root);
+	if (!real) return null;
+	for (const [name, hub] of Object.entries(readRegistry(env).hubs)) if (hub.root === real) return {
+		name,
+		root: hub.root,
+		data: hub.data
+	};
+	return null;
+}
+/**
+* A hub that still keeps its data inside the repository of `cwd` (`.mainflow/` at its main working tree's root or its
+* own, or in `cwd` itself, as in a directory outside git), with the repository; null when there is none. Only the
+* messages for an unregistered directory use it, to give the command that moves the data and registers the hub.
+*/
+function inRepositoryHubAt(cwd) {
+	const here = realPath(cwd) ?? resolve(cwd);
+	const checkout = gitCheckout(here);
+	for (const root of [
+		checkout?.main,
+		checkout?.current,
+		here
+	]) {
+		if (!root) continue;
+		const found = inRepositoryData(root);
+		if (found) return {
+			name: found.name,
+			root
+		};
+	}
+	return null;
+}
+/** What to tell the user when no registered hub claims `cwd`: how to register one, and the exact command when the repository still holds a hub's data. */
+function notRegisteredMessage(cwd) {
+	const found = inRepositoryHubAt(cwd);
+	const lines = [`No registered hub claims ${realPath(cwd) ?? cwd}. Register the hub it belongs to with: ${REGISTER_USAGE} (the path is the hub repository; the hub's data is in ${userDataDir("<name>")}).`];
+	if (found) lines.push(`This repository still keeps the data of hub "${found.name}" in ${join(found.root, DATA_DIR)}; move it and register the hub with: mainflow hub migrate-data ${found.root}`);
+	return lines.join("\n");
+}
+//#endregion
 //#region ../core/dist/ids/allocators.js
 /** The next id after the highest one taken, e.g. `m003` after `m001` and `m002`. */
 function nextId(prefix, existing) {
@@ -471,22 +1092,34 @@ function formatMismatch(found) {
 	if (found === 3) return null;
 	return found < 3 ? `data format version ${found} is older than this CLI's (3); run "mainflow migrate --dry-run" to preview the conversion, then "mainflow migrate"` : `data format version ${found} is newer than this CLI supports (3); install the matching mainflow version in this hub`;
 }
+/** What the text of a config.yaml asks of a writer, read in one parse; a text that is not YAML throws the parser's error. */
+function configRequirements(text) {
+	const data = parse$1(text);
+	const found = data?.formatVersion;
+	const range = data?.mainflow;
+	const valid = typeof range === "string" && isMainflowRange(range);
+	return {
+		formatVersion: typeof found === "number" ? found : null,
+		mainflow: valid ? range : null,
+		mainflowInvalid: range !== void 0 && range !== null && !valid
+	};
+}
 /**
-* The data format config.yaml declares; null when the hub has no config.yaml or it names no number, which loading
-* the config reports. A config.yaml that is not YAML is a WriteError, so the sync server refuses the request
-* instead of failing on it.
+* What the hub's config.yaml asks of a writer; null when the hub has none. A config.yaml that is not YAML is a
+* WriteError, so the sync server refuses the request instead of failing on it.
 */
-function hubFormatVersion(hub) {
+function hubRequirements(hub) {
 	const text = hub.read(CONFIG_FILE);
 	if (text === null) return null;
-	let data;
 	try {
-		data = parse$1(text);
+		return configRequirements(text);
 	} catch (error) {
 		throw new WriteError(`refusing to write: ${hub.where(CONFIG_FILE)} cannot be parsed as YAML: ${error.message}`);
 	}
-	const found = data?.formatVersion;
-	return typeof found === "number" ? found : null;
+}
+/** The data format config.yaml declares; null when the hub has no config.yaml or it names no number (hubRequirements). */
+function hubFormatVersion(hub) {
+	return hubRequirements(hub)?.formatVersion ?? null;
 }
 /**
 * Refuse a write to a hub whose data format is not the one this CLI writes: rewriting a document would drop what
@@ -498,6 +1131,22 @@ function requireWritableFormat(hub) {
 	const reason = formatMismatch(found);
 	if (reason) throw new WriteError(`refusing to write: ${reason}`);
 }
+/** The package the mainflow CLI is published as. */
+const CLI_PACKAGE = "mainflow";
+/**
+* The command that installs a mainflow CLI of the versions `range` names: pnpm installs the newest of them. Quoted for
+* the shell, since a range holds `>` and spaces.
+*/
+const upgradeCommand = (range) => `pnpm add -g '${CLI_PACKAGE}@${range}'`;
+/**
+* Why a CLI of `version`, null for one that did not say, may not write to a hub whose config.yaml asks for the mainflow
+* versions `required` (HubRequirements.mainflow), with the command that installs one it takes; null when it may.
+* `after` ends the message: what the sender does next, for a write it sent, so a caller that only warns gives its own.
+*/
+function versionMismatch(required, version, after = ", then send the write again") {
+	if (version !== null && satisfies(version, required, MAINFLOW_RANGE)) return null;
+	return `this hub takes writes from mainflow ${required} (mainflow in .mainflow/config.yaml), and the request came from ${version === null ? "a mainflow that does not say its version" : `mainflow ${version}`}; install one with ${upgradeCommand(required)}${after}`;
+}
 //#endregion
 //#region ../core/dist/ops/protocol.js
 /** `now` of a request: a local minute and its offset from UTC, `Z` for UTC itself. */
@@ -534,9 +1183,23 @@ const ROUTES = {
 	* refused then: the server holds the right content already. GET: download them. Neither carries the protocol version:
 	* the content is named by its own hash.
 	*/
-	blob: (hub, hash) => `/hub/${hub}/blob/${hash}`
+	blob: (hub, hash) => `/hub/${hub}/blob/${hash}`,
+	/** POST: a page of the hub's change log (ChangeLogRequest, answered with ChangeLogPage) */
+	changes: (hub) => `/hub/${hub}/changes`,
+	/** POST: put the hub, or a path of it, back to what it held after a seq, as a new change (RestoreRequest, answered with RestoreResponse) */
+	restore: (hub) => `/hub/${hub}/restore`,
+	/** POST: convert the hub to the data format of the server's mainflow (MigrateRequest, answered with MigrateResponse) */
+	migrate: (hub) => `/hub/${hub}/migrate`,
+	/** POST: the migration or restore the server runs in batches, or ran last (RewriteRequest, answered with RewriteStatus) */
+	rewrite: (hub) => `/hub/${hub}/rewrite`
 };
 /**
+* The header with the version of the mainflow CLI a request comes from, like 0.43.0, which every request and the
+* WebSocket's upgrade carry. A hub whose config.yaml names the mainflow versions that may write to it (`mainflow`)
+* refuses a write without it, or from a version outside them (`client-outdated`).
+*/
+const VERSION_HEADER = "x-mainflow-version";
+/**
 * The service token of Cloudflare Access, which stands in front of the sync server and lets through only the requests
 * that carry a valid one: every request, the WebSocket's upgrade included, sends both headers. The sync server itself
 * checks no credentials, so one deployed without Access in front serves anyone who knows its address.
@@ -617,116 +1280,25 @@ const SOCKET_MAX_AGE_CLOSE = {
 	code: 4e3,
 	reason: "the connection reached its maximum age; reconnect"
 };
-//#endregion
-//#region ../core/dist/storage/node.js
-const LOCK_WAIT_MS = 5e3;
-const LOCK_STALE_MS = 3e4;
-const sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-/**
-* Run `fn` while holding the hub-wide write lock in `.mainflow/local/`. When the lock had to create that
-* directory and `fn` refuses the write, the directory goes again, so a refused write leaves the hub as it was.
-*/
-function withLock(root, fn) {
-	const dir = join(root, DATA_DIR, "local");
-	const created = mkdirSync(dir, { recursive: true }) !== void 0;
-	try {
-		return holdLock(dir, fn);
-	} catch (error) {
-		if (created) removeIfEmpty(dir);
-		throw error;
-	}
-}
-function removeIfEmpty(dir) {
-	try {
-		rmdirSync(dir);
-	} catch {}
-}
-function holdLock(dir, fn) {
-	const lock = join(dir, "write.lock");
-	const deadline = Date.now() + LOCK_WAIT_MS;
-	let vanished = 0;
-	for (;;) try {
-		const fd = openSync(lock, "wx");
-		writeSync(fd, String(process.pid));
-		closeSync(fd);
-		break;
-	} catch (error) {
-		if (error.code === "ENOENT") {
-			mkdirSync(dir, { recursive: true });
-			continue;
-		}
-		if (error.code !== "EEXIST") throw error;
-		const held = statSync(lock, { throwIfNoEntry: false });
-		if (held && Date.now() - held.mtimeMs > LOCK_STALE_MS) {
-			rmSync(lock, { force: true });
-			continue;
-		}
-		if (Date.now() > deadline) throw new WriteError(`hub is locked by another writer (${lock}); retry in a moment`);
-		sleep(held ? 50 : Math.min(2 ** vanished++, 50));
-	}
-	try {
-		return fn();
-	} finally {
-		rmSync(lock, { force: true });
-	}
-}
-/** Write through a temporary file and a rename, so a reader never sees half a file. */
-function writeAtomic(file, text) {
-	const temp = `${file}.${process.pid}.tmp`;
-	writeFileSync(temp, text);
-	renameSync(temp, file);
-}
-/** The hub whose data directory is `{root}/.mainflow/`, read and written on the local file system. */
-function nodeStorage(root) {
-	const file = (path) => join(root, DATA_DIR, path);
-	return {
-		read: (path) => {
-			const target = file(path);
-			return existsSync(target) ? readFileSync(target, "utf8") : null;
-		},
-		list: (dir) => {
-			const target = file(dir);
-			if (!existsSync(target)) return [];
-			return readdirSync(target, { withFileTypes: true }).map((entry) => ({
-				name: entry.name,
-				dir: entry.isDirectory()
-			})).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
-		},
-		where: file,
-		write: (path, text) => {
-			mkdirSync(dirname(file(path)), { recursive: true });
-			writeAtomic(file(path), text);
-		},
-		append: (path, text) => {
-			mkdirSync(dirname(file(path)), { recursive: true });
-			appendFileSync(file(path), text);
-		},
-		makeDir: (path) => {
-			mkdirSync(file(path), { recursive: true });
-		},
-		remove: (path) => {
-			rmSync(file(path), { force: true });
-		},
-		lock: (fn) => withLock(root, fn)
-	};
-}
+/** The most changes a page of the change log carries. */
+const MAX_CHANGE_PAGE = 1e3;
 //#endregion
 //#region ../core/dist/io.js
 /** The time now to the minute with this machine's offset from UTC, the form sessions, actions and decisions use: 2026-09-24T15:30+08:00, or 2026-09-24T07:30Z in UTC. */
 const nowMinute = () => requestTime();
 /** The context an operation run from this machine gets: the local time, which is the user's. */
 const localContext = () => ({ now: nowMinute() });
-/** Run an operation on the hub at `root` under its write lock, apply its changes and return what it reports. */
-function runOp(root, run) {
+/** Run an operation on the hub at `dirs` under its write lock, apply its changes and return what it reports. */
+function runOp(dirs, run) {
 	const ctx = localContext();
-	return applyOp(nodeStorage(root), (hub) => {
+	return applyOp(nodeStorage(dirs), (hub) => {
 		requireWritableFormat(hub);
 		return run(hub, ctx);
 	}).value;
 }
 /** Run an operation that must not take the lock, such as one creating the hub the lock would live in. */
-function runUnlocked(root, run) {
-	const storage = nodeStorage(root);
+function runUnlocked(dirs, run) {
+	const storage = nodeStorage(dirs);
 	const result = run(storage, localContext());
 	commit(storage, result.changes);
 	return result.value;
@@ -751,13 +1323,13 @@ function readFrontMatter(file, schema) {
 //#endregion
 //#region ../core/dist/resolve.js
 /** The absolute path of a path inside the hub's data directory. */
-const onDisk = (root, path) => join(root, DATA_DIR, path);
-const mainlineDir = (root, id) => onDisk(root, mainlineDirIn(nodeStorage(root), id));
-const taskDir = (root, mainline, task) => onDisk(root, taskDirIn(nodeStorage(root), mainline, task));
-const mainlineFile = (root, id) => join(mainlineDir(root, id), MAINLINE_FILE);
-const taskFile = (root, mainline, task) => join(taskDir(root, mainline, task), TASK_FILE);
-const groupFile = (root, id) => onDisk(root, groupFileIn(nodeStorage(root), id));
-const readConfig = (root) => readConfigIn(nodeStorage(root));
+const onDisk = (dirs, path) => join(dirs.data, path);
+const mainlineDir = (dirs, id) => onDisk(dirs, mainlineDirIn(nodeStorage(dirs), id));
+const taskDir = (dirs, mainline, task) => onDisk(dirs, taskDirIn(nodeStorage(dirs), mainline, task));
+const mainlineFile = (dirs, id) => join(mainlineDir(dirs, id), MAINLINE_FILE);
+const taskFile = (dirs, mainline, task) => join(taskDir(dirs, mainline, task), TASK_FILE);
+const groupFile = (dirs, id) => onDisk(dirs, groupFileIn(nodeStorage(dirs), id));
+const readConfig = (dirs) => readConfigIn(nodeStorage(dirs));
 //#endregion
 //#region ../core/dist/refs.js
 const itemStatus = (item) => item.done ? "done" : item.dropped ? "dropped" : "open";
@@ -822,8 +1394,7 @@ function refIndex(hub) {
 	}
 	return index;
 }
-const isHubRoot = (dir) => existsSync(join(dir, DATA_DIR, "config.yaml"));
-/** Absolute root of a registered hub; `path` is relative to the registering hub's root. */
+/** Absolute path of the repository of a hub config.yaml lists; `path` is relative to the listing hub's repository. */
 const remoteRoot = (root, path) => resolve(root, path);
 /** Documents in `hub` whose links point at `hubName`'s documents; `hubName` undefined means links without a prefix. */
 function linksInto(hub, hubName) {
@@ -1070,7 +1641,9 @@ function touchesWithoutRepo(mainlines) {
 }
 /**
 * Open tasks of different open mainlines whose `touches` overlap in the same repo and which have no depends-on
-* between them in either direction, written on the mainline or on the task. Tasks without a repo are not compared,
+* between them in either direction, written on the mainline or on the task. The opening briefing lists them for the
+* session serving the mainline; check does not warn, and a commit that runs into the overlap is coordinated between
+* the sessions rather than by adding a depends-on. Tasks without a repo are not compared,
 * since their paths have no root to share; touchesWithoutRepo names them.
 */
 function touchOverlaps(mainlines, edges) {
@@ -1156,12 +1729,12 @@ function withSection(markdown, heading, text) {
 * Read config.yaml and check its format version; throws a HubError naming what is wrong when the hub cannot be
 * used at all. The interface answers 503 for it before loading anything else (docs/ui.md "壞檔與讀取失敗").
 */
-function loadConfig(root) {
-	const file = join(root, DATA_DIR, "config.yaml");
-	const where = relative(root, file);
+function loadConfig(dirs) {
+	const file = join(dirs.data, "config.yaml");
+	const where = hubPath(dirs, file);
 	let data;
 	try {
-		data = parse$1(readText(file) ?? "");
+		data = parse$1(readText$1(file) ?? "");
 	} catch (error) {
 		throw new HubError("invalid config.yaml", [{
 			file: where,
@@ -1180,7 +1753,7 @@ function loadConfig(root) {
 	if (mismatch) throw new HubError(mismatch, []);
 	return config;
 }
-function loadHub(root, options = {}) {
+function loadHub(dirs, options = {}) {
 	const problems = [];
 	const warnings = [];
 	/** References checked once everything they may point at is loaded */
@@ -1188,12 +1761,12 @@ function loadHub(root, options = {}) {
 	/** Documents whose file is there but failed to load; references into them are not reported twice */
 	const unreadable = /* @__PURE__ */ new Set();
 	const idOf = (path) => ENTRY_DIR.exec(path.split("/").at(-1)?.replace(/\.md$/, "") ?? "")?.[1];
-	const dataDir = join(root, DATA_DIR);
-	const rel = (path) => relative(root, path);
+	const dataDir = dirs.data;
+	const rel = (path) => hubPath(dirs, path);
 	const read = (file, schema, raw) => {
 		let data = raw;
 		if (data === void 0) try {
-			data = parse$1(readText(file) ?? "");
+			data = parse$1(readText$1(file) ?? "");
 		} catch (error) {
 			problems.push({
 				file: rel(file),
@@ -1219,12 +1792,12 @@ function loadHub(root, options = {}) {
 			message: `directory name must be "${id}-{slug}" in kebab-case`
 		});
 	};
-	const config = loadConfig(root);
-	problems.push(...repoPathProblems(root, config));
+	const config = loadConfig(dirs);
+	problems.push(...repoPathProblems(dirs.root, config));
 	const categories = /* @__PURE__ */ new Set([...DEFAULT_CATEGORIES, ...config.categories ?? []]);
 	/** Read a Markdown document's front matter against `schema`, with the attributes every document shares. */
 	const readDocument = (file, schema) => {
-		const text = readText(file);
+		const text = readText$1(file);
 		if (text === null) {
 			problems.push({
 				file: rel(file),
@@ -1261,7 +1834,7 @@ function loadHub(root, options = {}) {
 		};
 	};
 	const mainlines = [];
-	for (const mainlineDir of subdirs(join(dataDir, "mainlines"))) {
+	for (const mainlineDir of subdirs$1(join(dataDir, "mainlines"))) {
 		const mainline = readDocument(join(mainlineDir, MAINLINE_FILE), mainlineSchema);
 		if (!mainline) {
 			const id = idOf(mainlineDir);
@@ -1282,7 +1855,7 @@ function loadHub(root, options = {}) {
 			}
 		}
 		const tasks = [];
-		for (const taskDir of subdirs(join(mainlineDir, "tasks"))) {
+		for (const taskDir of subdirs$1(join(mainlineDir, "tasks"))) {
 			const task = readDocument(join(taskDir, TASK_FILE), taskSchema);
 			if (!task) {
 				unreadable.add(`${mainline.id}/${idOf(taskDir)}`);
@@ -1389,7 +1962,7 @@ function loadHub(root, options = {}) {
 			message: "expected \"YYYY-MM-DDTHH:mm | target | operation | result [| ref]\""
 		});
 	});
-	const remotes = options.remotes === false ? [] : loadRemotes(root, config, problems, warnings);
+	const remotes = options.remotes === false ? [] : loadRemotes(dirs.root, config, problems, warnings);
 	warnings.push(...groupWarnings(config.hub, groups, mainlines, hubIssues, remotes));
 	for (const doc of [...mainlines, ...hubIssues]) if (doc.group && splitGroup(doc.group, config.hub).hub !== void 0) pending.push({
 		ref: doc.group,
@@ -1423,21 +1996,14 @@ function loadHub(root, options = {}) {
 			message: `dependency cycle ${cycle.join(" → ")}; drop one of these dependencies`
 		});
 	}
-	for (const o of touchOverlaps(mainlines, deps.edges)) {
-		const pairs = o.paths.map(([a, b]) => a === b ? a : `${a} ~ ${b}`).join(", ");
-		warnings.push({
-			file: o.file,
-			field: "touches",
-			message: `${o.tasks[0]} and ${o.tasks[1]} both touch ${pairs} in repo ${o.repo}, and neither depends on the other; coordinate before both run, or add a depends-on link`
-		});
-	}
 	for (const t of touchesWithoutRepo(mainlines)) warnings.push({
 		file: t.file,
 		field: "repo",
 		message: `${t.task} lists touches but no repo, so its paths are not compared with other tasks; add the repo they are relative to`
 	});
 	return {
-		root,
+		root: dirs.root,
+		data: dirs.data,
 		config,
 		mainlines,
 		issues: hubIssues,
@@ -1482,7 +2048,10 @@ function groupWarnings(hubName, groups, mainlines, issues, remotes) {
 		}] : [];
 	});
 }
-/** Load every hub registered in config.yaml, read-only and without its own remotes. */
+/**
+* Load every hub registered in config.yaml, read-only and without its own remotes. Each is found by its repository,
+* `root` joined with the path config.yaml gives it, in this machine's hub registry, which names its data directory.
+*/
 function loadRemotes(root, config, problems, warnings) {
 	const file = `${DATA_DIR}/config.yaml`;
 	return Object.entries(config.hubs ?? {}).map(([name, path]) => {
@@ -1502,7 +2071,8 @@ function loadRemotes(root, config, problems, warnings) {
 				unavailable: "this hub"
 			};
 		}
-		if (!isHubRoot(remote.root)) {
+		const registered = hubAtRoot(remote.root);
+		if (!registered) {
 			warnings.push({
 				file,
 				field: `hubs.${name}`,
@@ -1514,7 +2084,7 @@ function loadRemotes(root, config, problems, warnings) {
 			};
 		}
 		try {
-			const hub = loadHub(remote.root, { remotes: false });
+			const hub = loadHub(registered, { remotes: false });
 			if (hub.config.hub !== name) {
 				problems.push({
 					file,
@@ -1649,7 +2219,8 @@ function checkReferences(input) {
 /**
 * A listed repository counts as part of the hub, so the PreToolUse hook lets grants act inside it. A path that
 * resolves to / or to a directory above the hub would put everything under it in scope. A path that does not
-* exist is fine: another machine may not have cloned that repository yet.
+* exist is fine: another machine may not have cloned that repository yet. The hub repository is always a primary
+* repository of its hub, so it cannot be listed as a reference.
 */
 function repoPathProblems(root, config) {
 	const real = (path) => {
@@ -1660,7 +2231,7 @@ function repoPathProblems(root, config) {
 		}
 	};
 	const hub = real(root) ?? root;
-	return Object.entries(config.repos).flatMap(([name, path]) => {
+	return listedRepos(config.repos).flatMap(({ name, path, role }) => {
 		const dir = real(resolve(root, path));
 		if (dir === null) return [];
 		const problem = (message) => [{
@@ -1670,6 +2241,7 @@ function repoPathProblems(root, config) {
 		}];
 		if (dir === parse(dir).root) return problem(`"${path}" resolves to the file system root; list the repository's own directory`);
 		if (hub.startsWith(dir.endsWith(sep) ? dir : dir + sep)) return problem(`"${path}" resolves to ${dir}, above the hub; list the repository's own directory`);
+		if (role === "reference" && dir === hub) return problem(`"${path}" is the hub repository, which always belongs to this hub; list it without role: reference`);
 		return [];
 	});
 }
@@ -1815,8 +2387,9 @@ function addRepo(hub, input) {
 	requireSlug(input.name);
 	const draft = new Draft(hub);
 	editYaml(draft, CONFIG_FILE, configSchema, (c) => {
-		if (c.repos[input.name] !== void 0 && c.repos[input.name] !== input.path) throw new WriteError(`repo "${input.name}" is already registered as ${c.repos[input.name]}`);
-		c.repos[input.name] = input.path;
+		const listed = c.repos[input.name];
+		if (listed !== void 0 && repoPath(listed) !== input.path) throw new WriteError(`repo "${input.name}" is already registered as ${repoPath(listed)}`);
+		c.repos[input.name] ??= input.path;
 	});
 	return draft.result(input.name);
 }
@@ -3001,7 +3574,7 @@ function requireMainlineTarget(hub, until) {
 /** The action an `until` waits for; throws when the condition matches none of the forms. */
 function untilTarget(until) {
 	const parsed = parseUntil(until);
-	if (!parsed) throw new WriteError(`--until takes a condition like ${UNTIL_FORMS.map((f) => f.format).join(", ")}, got "${until}"`);
+	if (!parsed) throw new WriteError(removedUntil(until) ?? `--until takes a condition like ${UNTIL_FORMS.map((f) => f.format).join(", ")}, got "${until}"`);
 	return parsed.kind === "action-done" ? `${parsed.session}#${parsed.action}` : void 0;
 }
 function updateAction(hub, input, ctx) {
@@ -3062,6 +3635,9 @@ const rename = (o, from, to) => {
 	}
 };
 const isClosed = (kind, status) => CLOSED_STATUS[kind].includes(status);
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** How messages and the report name a file: from the hub root, the way the CLI user sees them. */
+const rel = (path) => `${DATA_DIR}/${path}`;
 /** Drop the file's own H1, which format 2 replaces with the title in the front matter. */
 const withoutTitle = (markdown) => markdown.replace(/^\s*# [^\n]*\n/, "").replace(/^\n+/, "");
 /**
@@ -3105,122 +3681,198 @@ function migrateListItem(item) {
 	return item;
 }
 const openItem = (item) => !item.done && !item.dropped;
+/** The text of `path`; a WriteError when the hub holds no file there. */
+function readFile(hub, path) {
+	const text = hub.read(path);
+	if (text === null) throw new WriteError(`${hub.where(path)} does not exist`);
+	return text;
+}
+/** `text` read as YAML, which must be a mapping: a WriteError naming `path` otherwise. */
+function yamlRecord(text, path) {
+	let data;
+	try {
+		data = parse$1(text);
+	} catch (error) {
+		throw new WriteError(`${rel(path)} is not valid YAML: ${error.message}`);
+	}
+	if (!isRecord(data)) throw new WriteError(`${rel(path)} is not a YAML mapping of attributes, so it cannot be migrated; fix it and migrate again`);
+	return data;
+}
+/** A Markdown document's front matter, which must be a YAML mapping, and its body: a WriteError naming `path` otherwise. */
+function frontMatterOf(text, path) {
+	let split;
+	try {
+		split = splitFrontMatter(text);
+	} catch (error) {
+		throw new WriteError(`${rel(path)} has front matter that is not valid YAML: ${error.message}`);
+	}
+	if (!isRecord(split.data)) throw new WriteError(`${rel(path)} has no front matter, the YAML mapping of its attributes between --- lines at its top, so it cannot be migrated; add it, or move the file out of the hub, and migrate again`);
+	return {
+		data: split.data,
+		body: split.body
+	};
+}
+/** The list at `field` of a format 1 document, every item a mapping; none for a field it lacks. */
+function itemsOf(data, field, path) {
+	const value = data[field] ?? [];
+	if (!Array.isArray(value) || !value.every(isRecord)) throw new WriteError(`${rel(path)}: ${field} is not a list of items, so it cannot be migrated; fix it and migrate again`);
+	return value;
+}
+const subdirs = (hub, dir) => hub.list(dir).filter((e) => e.dir).map((e) => `${dir}/${e.name}`);
+const markdownIn = (hub, dir) => hub.list(dir).map((e) => e.name).filter((n) => n.endsWith(".md"));
 /**
-* Convert a format 1 or 2 hub to the current format. Times already written are never changed. The report lists what the changes write and remove; a dry
-* run reports them without applying them.
+* The data format config.yaml names, to migrate from: 1 or 2. A WriteError for a hub already of this CLI's format, of
+* a format this CLI does not convert, or without a readable config.yaml.
 */
-function migrateHub$1(hub) {
-	const rel = (path) => `${DATA_DIR}/${path}`;
-	const read = (path) => {
-		const text = hub.read(path);
-		if (text === null) throw new WriteError(`${hub.where(path)} does not exist`);
-		return text;
-	};
-	const subdirs = (dir) => hub.list(dir).filter((e) => e.dir).map((e) => `${dir}/${e.name}`);
-	const markdownIn = (dir) => hub.list(dir).map((e) => e.name).filter((n) => n.endsWith(".md"));
-	const config = parse$1(read(CONFIG_FILE));
+function migrationSource(hub) {
+	const config = yamlRecord(readFile(hub, CONFIG_FILE), CONFIG_FILE);
 	const from = Number(config.formatVersion);
 	if (from === 3) throw new WriteError(`${rel(CONFIG_FILE)} is already format 3; nothing to migrate`);
 	if (from !== 1 && from !== 2) throw new WriteError(`cannot migrate from format ${String(config.formatVersion)}; this CLI migrates format 1 or 2 to 3`);
-	const writes = /* @__PURE__ */ new Map();
-	const removes = [];
-	const missing = [];
+	return from;
+}
+/** A mainline's directory: mainline.yaml and context.md into mainline.md, each task.yaml and notes.md into task.md, each decision in its new shape. */
+function convertMainline(hub, mainlineDir, part) {
 	const document = (file, schema, data, body) => {
-		writes.set(file, frontMatterText(validate(schema, data, rel(file)), body));
-	};
-	/** Format 1 to 2: documents are rewritten in their new shape and the old files removed. */
-	const convertFormat1 = () => {
-		for (const mainlineDir of subdirs(MAINLINES_DIR)) {
-			const yamlFile = `${mainlineDir}/mainline.yaml`;
-			const yamlText = hub.read(yamlFile);
-			if (yamlText === null) continue;
-			const m = parse$1(yamlText);
-			dropNull(m, "archivedAt");
-			if (isClosed("mainline", m.status) && m.archivedAt) m.closedAt = m.archivedAt;
-			const criteria = (m.criteria ?? []).map(migrateListItem);
-			m.criteria = criteria;
-			const id = String(m.id);
-			const open = !isClosed("mainline", m.status);
-			if (open) {
-				for (const c of criteria) if (openItem(c) && !c.doneWhen) missing.push(`${id}#${c.id} doneWhen`);
-			}
-			const contextFile = `${mainlineDir}/context.md`;
-			const contextText = hub.read(contextFile);
-			const context = contextText === null ? "" : withoutTitle(contextText);
-			document(`${mainlineDir}/${MAINLINE_FILE}`, mainlineSchema, m, `\n${context.trimEnd()}\n`);
-			removes.push(yamlFile, ...contextText === null ? [] : [contextFile]);
-			for (const taskDir of subdirs(`${mainlineDir}/tasks`)) {
-				const taskYaml = `${taskDir}/task.yaml`;
-				const taskText = hub.read(taskYaml);
-				if (taskText === null) continue;
-				const t = parse$1(taskText);
-				const content = typeof t.content === "string" ? t.content.trim() : "";
-				drop(t, "content");
-				dropNull(t, "parent", "repo");
-				t.created ??= m.created;
-				const checklist = (t.checklist ?? []).map(migrateListItem);
-				t.checklist = checklist;
-				const doneDays = checklist.map((c) => c.doneAt).filter((d) => typeof d === "string").sort();
-				if (isClosed("task", t.status) && doneDays.length) t.closedAt = doneDays.at(-1);
-				let body = content ? withSection(TASK_BODY, "目標", content) : TASK_BODY;
-				const notesFile = `${taskDir}/notes.md`;
-				const notes = hub.read(notesFile);
-				if (notes !== null) {
-					body = foldNotes(body, notes);
-					removes.push(notesFile);
-				}
-				const taskRef = `${id}/${String(t.id)}`;
-				if (open && !isClosed("task", t.status)) {
-					for (const section of TASK_REQUIRED_SECTIONS) if (!sectionText(body, section)) missing.push(`${taskRef} ${section}`);
-					for (const c of checklist) if (openItem(c) && !c.doneWhen) missing.push(`${taskRef}#${c.id} doneWhen`);
-				}
-				document(`${taskDir}/${TASK_FILE}`, taskSchema, t, body);
-				removes.push(taskYaml);
-			}
-			const decisionsDir = `${mainlineDir}/decisions`;
-			for (const name of markdownIn(decisionsDir)) {
-				const file = `${decisionsDir}/${name}`;
-				const { data, body } = splitFrontMatter(read(file));
-				const d = data;
-				rename(d, "date", "created");
-				if (d.status !== "proposed") d.decidedAt = d.created;
-				dropNull(d, "supersededBy");
-				rename(d, "blocks", "affects");
-				document(file, decisionSchema, d, body);
-			}
-		}
-		const hubDocs = (dir, migrate, schema) => {
-			for (const name of markdownIn(dir)) {
-				const file = `${dir}/${name}`;
-				const { data, body } = splitFrontMatter(read(file));
-				migrate(data);
-				document(file, schema, data, body);
-			}
-		};
-		hubDocs(ISSUES_DIR, (i) => rename(i, "closedBy", "resolution"), issueSchema);
-		hubDocs(FINDINGS_DIR, (f) => {
-			rename(f, "date", "created");
-			rename(f, "tags", "labels");
-		}, findingSchema);
-	};
-	if (from === 1) convertFormat1();
-	const configText = read(CONFIG_FILE);
+		part.writes.set(file, frontMatterText(validate(schema, data, rel(file)), body));
+	};
+	const yamlFile = `${mainlineDir}/mainline.yaml`;
+	const yamlText = hub.read(yamlFile);
+	if (yamlText === null) return;
+	const m = yamlRecord(yamlText, yamlFile);
+	dropNull(m, "archivedAt");
+	if (isClosed("mainline", m.status) && m.archivedAt) m.closedAt = m.archivedAt;
+	const criteria = itemsOf(m, "criteria", yamlFile).map(migrateListItem);
+	m.criteria = criteria;
+	const id = String(m.id);
+	const open = !isClosed("mainline", m.status);
+	if (open) {
+		for (const c of criteria) if (openItem(c) && !c.doneWhen) part.missing.push(`${id}#${c.id} doneWhen`);
+	}
+	const contextFile = `${mainlineDir}/context.md`;
+	const contextText = hub.read(contextFile);
+	const context = contextText === null ? "" : withoutTitle(contextText);
+	document(`${mainlineDir}/${MAINLINE_FILE}`, mainlineSchema, m, `\n${context.trimEnd()}\n`);
+	part.removes.push(yamlFile, ...contextText === null ? [] : [contextFile]);
+	for (const taskDir of subdirs(hub, `${mainlineDir}/tasks`)) {
+		const taskYaml = `${taskDir}/task.yaml`;
+		const taskText = hub.read(taskYaml);
+		if (taskText === null) continue;
+		const t = yamlRecord(taskText, taskYaml);
+		const content = typeof t.content === "string" ? t.content.trim() : "";
+		drop(t, "content");
+		dropNull(t, "parent", "repo");
+		t.created ??= m.created;
+		const checklist = itemsOf(t, "checklist", taskYaml).map(migrateListItem);
+		t.checklist = checklist;
+		const doneDays = checklist.map((c) => c.doneAt).filter((d) => typeof d === "string").sort();
+		if (isClosed("task", t.status) && doneDays.length) t.closedAt = doneDays.at(-1);
+		let body = content ? withSection(TASK_BODY, "目標", content) : TASK_BODY;
+		const notesFile = `${taskDir}/notes.md`;
+		const notes = hub.read(notesFile);
+		if (notes !== null) {
+			body = foldNotes(body, notes);
+			part.removes.push(notesFile);
+		}
+		const taskRef = `${id}/${String(t.id)}`;
+		if (open && !isClosed("task", t.status)) {
+			for (const section of TASK_REQUIRED_SECTIONS) if (!sectionText(body, section)) part.missing.push(`${taskRef} ${section}`);
+			for (const c of checklist) if (openItem(c) && !c.doneWhen) part.missing.push(`${taskRef}#${c.id} doneWhen`);
+		}
+		document(`${taskDir}/${TASK_FILE}`, taskSchema, t, body);
+		part.removes.push(taskYaml);
+	}
+	const decisionsDir = `${mainlineDir}/decisions`;
+	for (const name of markdownIn(hub, decisionsDir)) {
+		const file = `${decisionsDir}/${name}`;
+		const { data: d, body } = frontMatterOf(readFile(hub, file), file);
+		rename(d, "date", "created");
+		if (d.status !== "proposed") d.decidedAt = d.created;
+		dropNull(d, "supersededBy");
+		rename(d, "blocks", "affects");
+		document(file, decisionSchema, d, body);
+	}
+}
+/**
+* Convert one unit of a format 1 hub (migrationUnit) as it is now: what it writes and removes, which only its own files.
+* A WriteError, naming the file, for a document it cannot read or one that would be invalid in the current format.
+*/
+function convertUnit(hub, unit) {
+	const part = {
+		writes: /* @__PURE__ */ new Map(),
+		removes: [],
+		missing: []
+	};
+	if (unit.kind === "mainline") {
+		convertMainline(hub, unit.path, part);
+		return part;
+	}
+	const { data, body } = frontMatterOf(readFile(hub, unit.path), unit.path);
+	if (unit.kind === "issue") rename(data, "closedBy", "resolution");
+	else {
+		rename(data, "date", "created");
+		rename(data, "tags", "labels");
+	}
+	part.writes.set(unit.path, frontMatterText(validate(unit.kind === "issue" ? issueSchema : findingSchema, data, rel(unit.path)), body));
+	return part;
+}
+/**
+* config.yaml in the current format, from the format `from` it names (migrationSource): its path and text. Format 2
+* to 3 changes how new times are written, not the times already there, so only the version changes, and the line is
+* replaced in place to keep the rest of config.yaml byte for byte.
+*/
+function convertConfig(hub, from) {
+	const configText = readFile(hub, CONFIG_FILE);
+	const config = yamlRecord(configText, CONFIG_FILE);
 	const versionLine = /^formatVersion:[ \t]*2[ \t]*$/m;
 	config.formatVersion = 3;
 	if (from === 2 && versionLine.test(configText)) {
 		validate(configSchema, config, rel(CONFIG_FILE));
-		writes.set(CONFIG_FILE, configText.replace(versionLine, `formatVersion: 3`));
-	} else writes.set(CONFIG_FILE, toYaml(validate(configSchema, config, rel(CONFIG_FILE))));
-	const draft = new Draft(hub);
-	for (const [file, text] of writes) draft.write(file, text);
-	for (const file of removes) draft.remove(file);
-	return draft.result({
+		return [CONFIG_FILE, configText.replace(versionLine, `formatVersion: 3`)];
+	}
+	return [CONFIG_FILE, toYaml(validate(configSchema, config, rel(CONFIG_FILE)))];
+}
+/** The report of the migration from format `from` that `parts` make up, in their order: each file by its path from the hub root. */
+function migrationReport(from, parts) {
+	return {
 		from,
 		to: 3,
-		written: [...writes.keys()].map(rel),
-		removed: removes.map(rel),
-		missingDefinitions: missing
+		written: parts.flatMap((part) => [...part.writes.keys()].map(rel)),
+		removed: parts.flatMap((part) => part.removes.map(rel)),
+		missingDefinitions: parts.flatMap((part) => part.missing)
+	};
+}
+/**
+* Convert a format 1 or 2 hub to the current format. Times already written are never changed. The report lists what the changes write and remove; a dry
+* run reports them without applying them.
+*/
+function migrateHub$1(hub) {
+	const from = migrationSource(hub);
+	const parts = [];
+	if (from === 1) {
+		for (const path of subdirs(hub, MAINLINES_DIR)) parts.push(convertUnit(hub, {
+			kind: "mainline",
+			path
+		}));
+		for (const name of markdownIn(hub, ISSUES_DIR)) parts.push(convertUnit(hub, {
+			kind: "issue",
+			path: `${ISSUES_DIR}/${name}`
+		}));
+		for (const name of markdownIn(hub, FINDINGS_DIR)) parts.push(convertUnit(hub, {
+			kind: "finding",
+			path: `${FINDINGS_DIR}/${name}`
+		}));
+	}
+	const [configFile, configText] = convertConfig(hub, from);
+	parts.push({
+		writes: /* @__PURE__ */ new Map([[configFile, configText]]),
+		removes: [],
+		missing: []
 	});
+	const draft = new Draft(hub);
+	for (const part of parts) for (const [file, text] of part.writes) draft.write(file, text);
+	for (const part of parts) for (const file of part.removes) draft.remove(file);
+	return draft.result(migrationReport(from, parts));
 }
 //#endregion
 //#region ../core/dist/ops/operations.js
@@ -3284,6 +3936,68 @@ function applyOperation(storage, name, input, ctx) {
 	});
 }
 //#endregion
+//#region ../core/dist/ops/scope.js
+/** Names programs leave behind while writing: editor swap and backup files, temporary files, Finder's. */
+const TRANSIENT = [
+	/\.tmp$/,
+	/\.sw[a-p]$/,
+	/\.swx$/,
+	/~$/,
+	/^\.#/,
+	/^4913$/,
+	/\.crswap$/,
+	/^\.DS_Store$/
+];
+/** Directories never synced, nor anything in them, at any depth. */
+const OWN_DIRS = /* @__PURE__ */ new Set(["scratch", "node_modules"]);
+/**
+* The parts of `path`, or null when it is no plain relative path, as no file of the hub has, or when a directory in
+* it, `path` itself too when `dir`, is one never synced (OWN_DIRS). `.git` is never synced, as a directory or as the
+* file a git worktree has.
+*/
+function partsOf(path, dir) {
+	const parts = path.split("/");
+	if (parts.some((part) => part === "" || part === "." || part === ".." || part === ".git")) return null;
+	return (dir ? parts : parts.slice(0, -1)).some((part) => OWN_DIRS.has(part)) ? null : parts;
+}
+/** Whether the file at `path` is synced: not in a directory never synced, not in local/ but local/sessions/, and not a transient name. */
+function syncedPath(path) {
+	const parts = partsOf(path, false);
+	if (parts === null) return false;
+	if (parts[0] === "local" && !(parts[1] === "sessions" && parts.length === 3)) return false;
+	return !TRANSIENT.some((pattern) => pattern.test(parts.at(-1)));
+}
+/** Whether the directory at `path` may hold synced files, so a scan walks into it: local/ itself and local/sessions/ but nothing else in local/. */
+function mayHoldSynced(path) {
+	if (path === "") return true;
+	if (partsOf(path, true) === null) return false;
+	return path === "local" || !path.startsWith("local/") || path === "local/sessions";
+}
+/** Whether the directory at `path` is synced: one that may hold synced files, apart from .mainflow/ and local/, which every machine has of its own. */
+const syncedDir = (path) => path !== "" && path !== "local" && mayHoldSynced(path);
+/** Whether the file or directory (`dir`) at `path` is of the sync scope: syncedPath for a file, syncedDir for a directory. */
+const syncedEntry = (path, dir) => dir ? syncedDir(path) : syncedPath(path);
+//#endregion
+//#region ../core/dist/ops/digest.js
+const DIGEST_DIGITS = 40;
+/** Whether the entry at `path`, a directory's when `dir`, is in the digest: one of the sync scope. */
+const digestCovers = syncedEntry;
+/** The term of one entry in the digest: a file by its path and content hash, a directory (`hash` null) by its path. */
+function digestTerm(path, hash) {
+	return BigInt(`0x${contentHash(hash === null ? `d\0${path}` : `f\0${path}\0${hash}`)}`);
+}
+/** A digest as it is stored and sent: 40 hex digits. */
+function digestText(value) {
+	return value.toString(16).padStart(DIGEST_DIGITS, "0");
+}
+/** The digest of the files (path to content hash) and directories given, those it covers (digestCovers). */
+function hubDigest(files, dirs) {
+	let value = 0n;
+	for (const [path, hash] of files) if (digestCovers(path, false)) value ^= digestTerm(path, hash);
+	for (const dir of dirs) if (digestCovers(dir, true)) value ^= digestTerm(dir, null);
+	return digestText(value);
+}
+//#endregion
 //#region ../core/dist/ids/renumber.js
 /** The id at the end of a reference: c003 in m001/t002#c003, a002 in claude-code-1a2b3c4d#a002. */
 const lastId = (ref) => /([a-z]\d{3})$/.exec(ref)?.[1] ?? "";
@@ -3669,7 +4383,7 @@ const sessionPath = (id) => `/sessions/${id}`;
 /** Fenced blocks, inline code, markdown links and bare URLs: text inside them is left as written. */
 const PROTECTED = /(```[\s\S]*?(?:```|$)|`[^`\n]*`|\[[^\]\n]*\]\([^)\n]*\)|https?:\/\/\S+)/;
 /** A file under a mainline directory, or a reference to a mainline, task, decision, issue, finding or group. */
-const MENTION = /\.mainflow\/mainlines\/(m\d{3})-[\w-]+\/([^\s`'")\]]+\.\w+)|(?<![\w/#.[-])(m\d{3}(?:\/[td]\d{3})?|[ifw]\d{3})(?![\w\]])/g;
+const MENTION = /\.mainflow\/(?:[a-z0-9-]+\/)?mainlines\/(m\d{3})-[\w-]+\/([^\s`'")\]]+\.\w+)|(?<![\w/#.[-])(m\d{3}(?:\/[td]\d{3})?|[ifw]\d{3})(?![\w\]])/g;
 /** Links for the references and mainline files the text mentions; references the hub does not have stay as text. */
 function linkMentions(text, context) {
 	const index = refIndex(context.hub);
@@ -3752,7 +4466,7 @@ function decorateReply(text, context) {
 	return line ? `${body}\n\n${line}\n` : `${body}\n`;
 }
 /** Cheap test for text that decorateReply could change, so a display hook can skip loading the hub. */
-const mayDecorate = (text) => /m\d{3}|[ifw]\d{3}|\.mainflow\/mainlines/.test(text) || endsWithMarker(text);
+const mayDecorate = (text) => /m\d{3}|[ifw]\d{3}|\.mainflow\/(?:[a-z0-9-]+\/)?mainlines/.test(text) || endsWithMarker(text);
 //#endregion
 //#region ../core/dist/grants.js
 /** Mainline statuses whose grants apply. */
@@ -3763,7 +4477,7 @@ const GRANTING_GROUP_STATUS = ["open"];
 * The grants in effect for a session. Reading a mainline that is missing or invalid throws, so a caller that
 * must fail closed catches it and asks.
 */
-function grantScope(root, session) {
+function grantScope(dirs, session) {
 	if (!session) return {
 		ok: false,
 		reason: "這場會話沒有 mainflow 紀錄"
@@ -3795,11 +4509,11 @@ function grantScope(root, session) {
 	const grants = [];
 	const served = {};
 	const closed = [];
-	const hubName = readConfig(root).hub;
+	const hubName = readConfig(dirs).hub;
 	const groups = new Map(direct);
 	const reachedByMainline = /* @__PURE__ */ new Set();
 	for (const id of mainlines) {
-		const mainline = readFrontMatter(mainlineFile(root, id), mainlineSchema).data;
+		const mainline = readFrontMatter(mainlineFile(dirs, id), mainlineSchema).data;
 		if (!GRANTING_STATUS.includes(mainline.status)) {
 			closed.push(`${id} 是 ${mainline.status}`);
 			continue;
@@ -3819,7 +4533,7 @@ function grantScope(root, session) {
 	for (const [id, via] of groups) {
 		let group;
 		try {
-			group = readFrontMatter(groupFile(root, id), groupSchema).data;
+			group = readFrontMatter(groupFile(dirs, id), groupSchema).data;
 		} catch (error) {
 			if (reachedByMainline.has(id)) continue;
 			throw error;
@@ -3878,9 +4592,9 @@ function matchGrants(scope, requests) {
 * the hook allows for it; empty when the session has none or they cannot be read, since a briefing must not fail
 * on them.
 */
-function grantLines(root, session) {
+function grantLines(dirs, session) {
 	try {
-		const result = grantScope(root, session);
+		const result = grantScope(dirs, session);
 		if (!result.ok) return [];
 		return result.scope.grants.map((g) => {
 			const parsed = parseGrantTarget(g.grant.action, g.grant.target);
@@ -3894,26 +4608,26 @@ function grantLines(root, session) {
 //#endregion
 //#region ../core/dist/sessions.js
 /** Read every session under `.mainflow/local/sessions/`; sessions are local and never version-controlled. */
-function loadSessions(root) {
-	return readSessionsIn(nodeStorage(root));
+function loadSessions(dirs) {
+	return readSessionsIn(nodeStorage(dirs));
 }
-function readSession(root, id) {
-	return readSessionIn(nodeStorage(root), id);
+function readSession(dirs, id) {
+	return readSessionIn(nodeStorage(dirs), id);
 }
 /**
 * Find the action a reference names. A handoff drops the action and names its new place in the note, so the
 * reference is followed there: a wait on the old reference keeps working after the work moved to another session.
 */
-function resolveAction(root, ref) {
-	return resolveActionIn(nodeStorage(root), ref);
+function resolveAction(dirs, ref) {
+	return resolveActionIn(nodeStorage(dirs), ref);
 }
 /** Where a session's transcript is on disk: a platform records an absolute path, a hub may record one relative to its root. */
-function transcriptPath(root, transcript) {
-	return isAbsolute(transcript) ? transcript : join(root, transcript);
+function transcriptPath(dirs, transcript) {
+	return isAbsolute(transcript) ? transcript : join(dirs.root, transcript);
 }
 /** Remember the digest of what the last turn reminder listed in full; null forgets it, so the next reminder lists everything again. */
-function setReminderDigest(root, id, digest) {
-	runOp(root, (hub) => setReminderDigest$1(hub, {
+function setReminderDigest(dirs, id, digest) {
+	runOp(dirs, (hub) => setReminderDigest$1(hub, {
 		id,
 		digest
 	}));
@@ -3992,14 +4706,16 @@ function readSyncState(data) {
 }
 /**
 * Kinds telling that a file did not reach the server. Once the file is the confirmed version it did, whenever it last
-* changed: a binary file an older server skipped is uploaded later as it is, without being written again.
+* changed: a binary file an older server skipped is uploaded later as it is, without being written again, and so is a
+* write the hub refused for the CLI's version, once a mainflow it takes runs here.
 */
 const UNSENT_KINDS = /* @__PURE__ */ new Set([
 	"skipped-binary",
 	"skipped-large",
 	"binary-text-file",
 	"upload-failing",
-	"download-failed"
+	"download-failed",
+	"client-outdated"
 ]);
 /**
 * Whether the files show a notice settled. With a saved text, once the saved text is removed. Without one, when the
@@ -4024,18 +4740,18 @@ function settled(data, notice, state) {
 		return false;
 	}
 }
-const handledFile = (root) => join(root, DATA_DIR, HANDLED_FILE);
+const handledFile = (dirs) => join(dirs.data, HANDLED_FILE);
 /** The keys marked handled by hand. */
-function readHandledKeys(root) {
-	const keys = readJson$1(handledFile(root), {}).keys;
+function readHandledKeys(dirs) {
+	const keys = readJson$1(handledFile(dirs), {}).keys;
 	return keys && typeof keys === "object" && !Array.isArray(keys) ? keys : {};
 }
 /** Every warn-level line of notices.jsonl, newest first, each with how it was handled if it was; unreadable lines are skipped. */
-function readNotices(root) {
-	const data = join(root, DATA_DIR);
+function readNotices(dirs) {
+	const data = dirs.data;
 	const file = join(data, NOTICES_FILE);
 	if (!existsSync(file)) return [];
-	const manual = readHandledKeys(root);
+	const manual = readHandledKeys(dirs);
 	const state = readSyncState(data);
 	const notices = [];
 	for (const line of readFileSync(file, "utf8").split("\n")) {
@@ -4050,19 +4766,19 @@ function readNotices(root) {
 	return notices.reverse();
 }
 /** The notices nobody has handled yet, newest first. */
-const unhandledNotices = (root) => readNotices(root).filter((n) => n.handled === void 0);
+const unhandledNotices = (dirs) => readNotices(dirs).filter((n) => n.handled === void 0);
 /**
 * Mark notices handled by hand, writing handled.json by a rename so a reader never sees half of it. `keys` names the
 * notices (noticeKey); without it every notice unhandled now is marked. Returns the number marked.
 */
-function markNoticesHandled(root, keys) {
-	const unhandled = new Set(unhandledNotices(root).map(noticeKey));
+function markNoticesHandled(dirs, keys) {
+	const unhandled = new Set(unhandledNotices(dirs).map(noticeKey));
 	const wanted = (keys ?? [...unhandled]).filter((key) => unhandled.has(key));
 	if (wanted.length === 0) return 0;
-	const marked = readHandledKeys(root);
+	const marked = readHandledKeys(dirs);
 	const now = (/* @__PURE__ */ new Date()).toISOString();
 	for (const key of wanted) marked[key] = now;
-	const file = handledFile(root);
+	const file = handledFile(dirs);
 	mkdirSync(dirname(file), { recursive: true });
 	const temp = `${file}.${process.pid}.tmp`;
 	writeFileSync(temp, JSON.stringify({ keys: marked }, null, 1));
@@ -4071,12 +4787,12 @@ function markNoticesHandled(root, keys) {
 }
 //#endregion
 //#region ../core/dist/briefing.js
-function describe(root, ref) {
+function describe(dirs, ref) {
 	const parsed = parseRef(ref);
 	if (parsed?.kind !== "checklistItem" && parsed?.kind !== "criterion" && parsed?.kind !== "groupCriterion") return null;
 	try {
 		if (parsed.kind === "groupCriterion") {
-			const group = readFrontMatter(groupFile(root, parsed.group), groupSchema).data;
+			const group = readFrontMatter(groupFile(dirs, parsed.group), groupSchema).data;
 			const criterion = group.criteria?.find((r) => r.id === parsed.criterion);
 			return criterion ? {
 				ref,
@@ -4085,7 +4801,7 @@ function describe(root, ref) {
 				where: `${group.id} ${group.title} › 解決條件`
 			} : null;
 		}
-		const mainline = readFrontMatter(mainlineFile(root, parsed.mainline), mainlineSchema).data;
+		const mainline = readFrontMatter(mainlineFile(dirs, parsed.mainline), mainlineSchema).data;
 		if (parsed.kind === "criterion") {
 			const criterion = mainline.criteria.find((r) => r.id === parsed.criterion);
 			return criterion ? {
@@ -4095,7 +4811,7 @@ function describe(root, ref) {
 				where: `${mainline.id} ${mainline.title} › 解決條件`
 			} : null;
 		}
-		const task = readFrontMatter(taskFile(root, parsed.mainline, parsed.task), taskSchema).data;
+		const task = readFrontMatter(taskFile(dirs, parsed.mainline, parsed.task), taskSchema).data;
 		const item = task.checklist.find((c) => c.id === parsed.item);
 		if (!item) return null;
 		return {
@@ -4109,11 +4825,11 @@ function describe(root, ref) {
 	}
 }
 /** The criteria a served checklist item pushes forward, as m{NNN}#r{NNN}; empty for a criterion or an item that cannot be read. */
-function criteriaOf(root, ref) {
+function criteriaOf(dirs, ref) {
 	const parsed = parseRef(ref);
 	if (parsed?.kind !== "checklistItem") return [];
 	try {
-		return (readFrontMatter(taskFile(root, parsed.mainline, parsed.task), taskSchema).data.checklist.find((c) => c.id === parsed.item)?.serves ?? []).map((r) => `${parsed.mainline}#${r}`);
+		return (readFrontMatter(taskFile(dirs, parsed.mainline, parsed.task), taskSchema).data.checklist.find((c) => c.id === parsed.item)?.serves ?? []).map((r) => `${parsed.mainline}#${r}`);
 	} catch {
 		return [];
 	}
@@ -4123,9 +4839,9 @@ function criteriaOf(root, ref) {
 * serves pushes forward, named as the item with its criterion. Two items serving the same criterion do not meet,
 * since splitting a criterion into items is how work on it runs in parallel.
 */
-function sharedServes(root, mine, theirs) {
+function sharedServes(dirs, mine, theirs) {
 	const shared = mine.filter((ref) => theirs.includes(ref));
-	const pushes = (items, criteria) => items.flatMap((item) => criteriaOf(root, item).filter((r) => criteria.includes(r)).map((r) => `${item}（推進 ${r}）`));
+	const pushes = (items, criteria) => items.flatMap((item) => criteriaOf(dirs, item).filter((r) => criteria.includes(r)).map((r) => `${item}（推進 ${r}）`));
 	const mineCriteria = mine.filter((ref) => parseRef(ref)?.kind === "criterion");
 	const theirCriteria = theirs.filter((ref) => parseRef(ref)?.kind === "criterion");
 	return [.../* @__PURE__ */ new Set([
@@ -4135,12 +4851,12 @@ function sharedServes(root, mine, theirs) {
 	])];
 }
 /** Problems in a session's queue that the executor should fix before going on, each with the command that fixes it. */
-function queueWarnings(root, session, cli) {
+function queueWarnings(dirs, session, cli) {
 	const warnings = [];
 	const doing = session.actions.filter((a) => a.status === "doing");
 	if (doing.length > 1) warnings.push(`同時有 ${doing.length} 個進行中的行動（${doing.map((a) => a.id).join("、")}）。一次只推進一個，其餘改回 todo。`);
 	for (const action of doing) {
-		const served = action.serves.map((ref) => describe(root, ref));
+		const served = action.serves.map((ref) => describe(dirs, ref));
 		if (served.some((s) => s === null)) warnings.push(`${action.id} 服務的項目有的已不存在，用 ${cli} action set ${action.id} --serves <m/t#c 或 m#r> 改正。`);
 		else if (served.length > 0 && served.every((s) => s.checked)) warnings.push(`${action.id} 服務的項目都已勾選或達成。做完了就執行 ${cli} action set ${action.id} --status done。`);
 	}
@@ -4163,14 +4879,14 @@ function waitingLine(a) {
 	return `${a.id} ${a.do}${parts.length > 0 ? `（${parts.join("；")}）` : ""}`;
 }
 /** Mainlines a session could be pushing forward. */
-const openMainlines = (root) => loadHub(root).mainlines.filter((m) => !m.archivedAt && (m.status === "active" || m.status === "planning"));
+const openMainlines = (dirs) => loadHub(dirs).mainlines.filter((m) => !m.archivedAt && (m.status === "active" || m.status === "planning"));
 /** How recently a session's transcript must have been written for the session to count as possibly still running. */
 const RUNNING_WINDOW_MS = 9e5;
 /** Whether the session's transcript was written within the running window; false when no transcript is recorded or readable. */
-function mayBeRunning(root, session) {
+function mayBeRunning(dirs, session) {
 	if (!session.transcript) return false;
 	try {
-		return Date.now() - statSync(transcriptPath(root, session.transcript)).mtimeMs < RUNNING_WINDOW_MS;
+		return Date.now() - statSync(transcriptPath(dirs, session.transcript)).mtimeMs < RUNNING_WINDOW_MS;
 	} catch {
 		return false;
 	}
@@ -4195,21 +4911,21 @@ function family(sessions, id) {
 	return members.add(id);
 }
 /** The actions in this session that a blocked action elsewhere waits for, named by `waitingFor` or by an `until` of kind action-done. */
-function waitedFor(root, blocked) {
+function waitedFor(dirs, blocked) {
 	const until = blocked.blockedBy?.until ? parseUntil(blocked.blockedBy.until) : null;
 	const refs = [waitingForAction(blocked.blockedBy?.waitingFor), until?.kind === "action-done" ? `${until.session}#${until.action}` : void 0];
-	return [...new Set(refs.filter((r) => r !== void 0).map((r) => resolveAction(root, r).ref))];
+	return [...new Set(refs.filter((r) => r !== void 0).map((r) => resolveAction(dirs, r).ref))];
 }
 /**
 * One line for each blocked action in another session that waits for an action of this one, followed through
 * handoffs, so the session being waited for sees it without the other side having to send a message. An action
 * already done or dropped has nothing left to deliver, so a wait on it is not shown.
 */
-function waiterLines(root, session) {
+function waiterLines(dirs, session) {
 	const lines = [];
-	for (const other of loadSessions(root).sessions) {
+	for (const other of loadSessions(dirs).sessions) {
 		if (other.id === session.id || other.archivedAt || other.status === "handed-off") continue;
-		for (const blocked of other.actions.filter((a) => a.status === "blocked")) for (const ref of waitedFor(root, blocked)) {
+		for (const blocked of other.actions.filter((a) => a.status === "blocked")) for (const ref of waitedFor(dirs, blocked)) {
 			const mine = ref.startsWith(`${session.id}#`) ? session.actions.find((a) => `${session.id}#${a.id}` === ref) : void 0;
 			if (!mine || mine.status === "done" || mine.status === "dropped") continue;
 			const until = blocked.blockedBy?.until ? `。條件：${blocked.blockedBy.until}` : "";
@@ -4223,16 +4939,16 @@ function waiterLines(root, session) {
 * action also serves: the same item or criterion, or a criterion and an item that pushes it forward. Sessions in the same delegation tree are left out: a subagent working on the item
 * its parent handed it is not a second claim.
 */
-function duplicateClaimLines(root, sessionId, actionId) {
-	const { sessions } = loadSessions(root);
+function duplicateClaimLines(dirs, sessionId, actionId) {
+	const { sessions } = loadSessions(dirs);
 	const action = sessions.find((s) => s.id === sessionId)?.actions.find((a) => a.id === actionId);
 	if (!action || action.serves.length === 0) return [];
 	const related = family(sessions, sessionId);
 	const lines = [];
 	for (const other of sessions) {
-		if (related.has(other.id) || !mayBeRunning(root, other)) continue;
+		if (related.has(other.id) || !mayBeRunning(dirs, other)) continue;
 		for (const theirs of other.actions.filter((a) => a.status === "doing")) {
-			const shared = sharedServes(root, action.serves, theirs.serves);
+			const shared = sharedServes(dirs, action.serves, theirs.serves);
 			if (shared.length > 0) lines.push(`⚠ ${other.id}#${theirs.id}（15 分鐘內有活動）也在做 ${shared.join("、")}，先協調再開始`);
 		}
 	}
@@ -4242,30 +4958,30 @@ function duplicateClaimLines(root, sessionId, actionId) {
 * Lines naming the other top-level sessions that still hold unfinished actions, with the command that takes them
 * over into this one. Subagent sessions are left out: their work returns to the session that delegated it.
 */
-function handoffLines(root, session, cli) {
-	const others = loadSessions(root).sessions.filter((s) => s.id !== session.id && !s.delegatedFrom && !s.archivedAt && (s.status === "active" || s.status === "paused") && s.actions.some(isCarried));
+function handoffLines(dirs, session, cli) {
+	const others = loadSessions(dirs).sessions.filter((s) => s.id !== session.id && !s.delegatedFrom && !s.archivedAt && (s.status === "active" || s.status === "paused") && s.actions.some(isCarried));
 	if (others.length === 0) return [];
-	return [`其他會話還有沒做完的行動。要接續的是其中一場已經停下的工作時，先用 ${cli} session handoff <會話> 把它的行動接進這場會話，再開始做：`, ...others.map((s) => `- ${s.id}${mayBeRunning(root, s) ? "（15 分鐘內還有寫入對話紀錄，可能還在執行，不要接手）" : ""}：${s.actions.filter(isCarried).map((a) => `${a.id} ${a.do}（${a.status}，服務 ${a.serves.join("、") || "未指定"}）`).join("；")}`)];
+	return [`其他會話還有沒做完的行動。要接續的是其中一場已經停下的工作時，先用 ${cli} session handoff <會話> 把它的行動接進這場會話，再開始做：`, ...others.map((s) => `- ${s.id}${mayBeRunning(dirs, s) ? "（15 分鐘內還有寫入對話紀錄，可能還在執行，不要接手）" : ""}：${s.actions.filter(isCarried).map((a) => `${a.id} ${a.do}（${a.status}，服務 ${a.serves.join("、") || "未指定"}）`).join("；")}`)];
 }
-const servedLine = (root, action) => action.serves.map((ref) => {
-	const s = describe(root, ref);
+const servedLine = (dirs, action) => action.serves.map((ref) => {
+	const s = describe(dirs, ref);
 	return s ? `${ref} ${s.text}（${s.where}）` : `${ref}（找不到這個項目或條件）`;
 }).join("；") || "沒有指定服務的 checklist 項目或解決條件";
 /**
 * Lines for each pair of overlapping touches that involves a mainline an action in progress serves: the other
 * mainline and task, and the paths they share. Empty when the session serves nothing that overlaps.
 */
-function overlapLines(root, session) {
+function overlapLines(dirs, session) {
 	const mine = new Set(session.actions.filter((a) => a.status === "doing").flatMap((a) => a.serves.map((ref) => parseRef(ref))).flatMap((parsed) => parsed && "mainline" in parsed ? [parsed.mainline] : []));
 	if (mine.size === 0) return [];
-	const hub = loadHub(root, { remotes: false });
+	const hub = loadHub(dirs, { remotes: false });
 	const lines = [];
 	for (const o of touchOverlaps(hub.mainlines, dependencyGraph(hub).edges)) {
 		const [own, other] = mine.has(o.tasks[0].split("/")[0]) ? [0, 1] : mine.has(o.tasks[1].split("/")[0]) ? [1, 0] : [-1, -1];
 		if (own < 0) continue;
 		const paths = o.paths.map(([a, b]) => own === 0 ? [a, b] : [b, a]).map(([a, b]) => a === b ? a : `${a} ~ ${b}`).join("、");
 		const title = hub.mainlines.find((m) => m.id === o.tasks[other].split("/")[0])?.title;
-		lines.push(`- ${o.tasks[own]} 和 ${o.tasks[other]}${title ? `（${title}）` : ""} 都會動到 ${paths}（倉庫 ${o.repo}），兩邊沒有 depends-on`);
+		lines.push(`- ${o.tasks[own]} 和 ${o.tasks[other]}${title ? `（${title}）` : ""} 都會動到 ${paths}（倉庫 ${o.repo}），提交時撞上就和對方的會話協調先後，不必記 depends-on`);
 	}
 	return lines;
 }
@@ -4274,8 +4990,8 @@ const BRIEFING_NOTICES = 5;
 /** Longest message summary of a notice in the briefing, in characters. */
 const NOTICE_SUMMARY = 80;
 /** The unhandled sync notices for the briefing: up to BRIEFING_NOTICES, the total, and where the page lists them; empty when none. */
-function syncNoticeLines(root) {
-	const notices = unhandledNotices(root);
+function syncNoticeLines(dirs) {
+	const notices = unhandledNotices(dirs);
 	if (notices.length === 0) return [];
 	const summary = (message) => message.length > NOTICE_SUMMARY ? `${message.slice(0, NOTICE_SUMMARY)}…` : message;
 	return [
@@ -4285,13 +5001,13 @@ function syncNoticeLines(root) {
 	];
 }
 /** Full briefing for the start of a session, after resuming, clearing or compacting. */
-function sessionBriefing(root, session, options) {
+function sessionBriefing(dirs, session, options) {
 	const { cli } = options;
 	const lines = [`[mainflow] 這場會話的 id 是 ${session.id}${options.envNote ? `（${options.envNote}）` : ""}。`];
 	const doing = current(session);
 	const upcoming = session.actions.filter((a) => a.status === "todo").slice(0, 3);
 	if (session.actions.length === 0) {
-		const active = openMainlines(root);
+		const active = openMainlines(dirs);
 		lines.push("這場會話還沒有行動。");
 		if (active.length > 0) {
 			lines.push("進行中的主脈絡：");
@@ -4300,21 +5016,21 @@ function sessionBriefing(root, session, options) {
 		}
 	} else {
 		lines.push(doing ? `目前行動：${doing.id} ${doing.do}` : "目前沒有進行中的行動。");
-		if (doing) lines.push(`服務：${servedLine(root, doing)}`);
-		const grants = grantLines(root, session);
+		if (doing) lines.push(`服務：${servedLine(dirs, doing)}`);
+		const grants = grantLines(dirs, session);
 		if (grants.length > 0) lines.push("目前行動服務的主脈絡與所屬的組預先授權了這些動作：", ...grants);
 		if (upcoming.length > 0) lines.push(`接下來：${upcoming.map((a) => `${a.id} ${a.do}`).join("、")}`);
 		const blocked = session.actions.filter((a) => a.status === "blocked");
 		if (blocked.length > 0) lines.push(`等外部條件：${blocked.map(waitingLine).join("；")}`);
 	}
-	lines.push(...waiterLines(root, session));
-	const overlaps = overlapLines(root, session);
+	lines.push(...waiterLines(dirs, session));
+	const overlaps = overlapLines(dirs, session);
 	if (overlaps.length > 0) lines.push("目前行動服務的主脈絡和其他進行中的主脈絡預計動到同樣的路徑，開始改之前先和對方協調，或加 depends-on：", ...overlaps);
-	if (!session.actions.some(isOpen)) lines.push(...handoffLines(root, session, cli));
-	const warnings = queueWarnings(root, session, cli);
+	if (!session.actions.some(isOpen)) lines.push(...handoffLines(dirs, session, cli));
+	const warnings = queueWarnings(dirs, session, cli);
 	if (warnings.length > 0) lines.push("需要處理：", ...warnings.map((w) => `- ${w}`));
-	lines.push(...syncNoticeLines(root));
-	lines.push("工作方式：", `- 開始一件新工作前，先列進佇列：${cli} action add "<做法>" --serves <m/t#c>。主脈絡還沒拆任務時（查核與規劃階段），--serves 指向解決條件 <m#r>。`, `- 開始做標 doing，做完標 done：${cli} action set <a編號> --status doing。`, `- 勾選 checklist 要附證據：${cli} item check <m/t#c> --evidence <commit、檔案:行號或指令輸出>。`, `- 內容直接寫進檔案：意圖或需求寫進 mainline.md 的內文，任務的目標與完成定義寫進 task.md，選擇寫成決策（${cli} new decision <m> <slug> --title <標題> 建檔後再寫內文）。`, `- 改完 .mainflow/ 的檔案跑 ${cli} check，把它列出的問題修到沒有。`, "- 用完其他 skill 或子流程後，回到上面的目前行動再繼續。", "- 要開主脈絡、拆任務、記決策、延後或收尾時，用 mainflow skill，它依序帶過並告訴你資訊該寫在哪裡。");
+	lines.push(...syncNoticeLines(dirs));
+	lines.push("工作方式：", `- 開始一件新工作前，先列進佇列：${cli} action add "<做法>" --serves <m/t#c>。主脈絡還沒拆任務時（查核與規劃階段），--serves 指向解決條件 <m#r>。`, `- 開始做標 doing，做完標 done：${cli} action set <a編號> --status doing。`, `- 勾選 checklist 要附證據：${cli} item check <m/t#c> --evidence <commit、檔案:行號或指令輸出>。`, `- 內容直接寫進檔案：意圖或需求寫進 mainline.md 的內文，任務的目標與完成定義寫進 task.md，選擇寫成決策（${cli} new decision <m> <slug> --title <標題> 建檔後再寫內文）。這些檔案在 hub 的資料目錄 ${dirs.data}，訊息裡的 .mainflow/ 指的就是這個目錄。`, `- 改完資料目錄裡的檔案跑 ${cli} check，把它列出的問題修到沒有。`, "- 用完其他 skill 或子流程後，回到上面的目前行動再繼續。", "- 要開主脈絡、拆任務、記決策、延後或收尾時，用 mainflow skill，它依序帶過並告訴你資訊該寫在哪裡。");
 	return lines.join("\n");
 }
 /**
@@ -4322,17 +5038,17 @@ function sessionBriefing(root, session, options) {
 * Records a digest of the grants, waits and warnings it lists in the session file, only when the digest changes;
 * `saveDigest` records it instead of writing the file here, as a host hook in remote mode sends it to the sync server.
 */
-function turnReminder(root, session, options) {
-	if (session.actions.length === 0) return openMainlines(root).length > 0 ? `[mainflow] ${session.id} 還沒有行動。這一輪要推進主脈絡時，先用 ${options.cli} action add 列出行動並標為 doing，或用 ${options.cli} session handoff <會話> 接手上一場沒做完的行動，再開始做。回覆結尾的標頭只看這場會話進行中的行動。` : null;
+function turnReminder(dirs, session, options) {
+	if (session.actions.length === 0) return openMainlines(dirs).length > 0 ? `[mainflow] ${session.id} 還沒有行動。這一輪要推進主脈絡時，先用 ${options.cli} action add 列出行動並標為 doing，或用 ${options.cli} session handoff <會話> 接手上一場沒做完的行動，再開始做。回覆結尾的標頭只看這場會話進行中的行動。` : null;
 	const doing = current(session);
 	const open = session.actions.filter(isOpen);
 	const blocked = session.actions.filter((a) => a.status === "blocked");
 	const head = doing ? `[mainflow] 目前行動 ${doing.id} ${doing.do}，服務 ${doing.serves.join("、") || "（未指定）"}。這一輪的工作若不屬於它，先調整佇列再做。` : open.length > 0 ? `[mainflow] ${session.id} 目前沒有進行中的行動。` : blocked.length > 0 ? `[mainflow] ${session.id} 的行動在等外部條件：${blocked.map(waitingLine).join("；")}。有條件（until）的可以在背景執行 ${options.cli} wait <a編號> 等它成立。條件出現後用 ${options.cli} action set <a編號> --status doing 繼續；要先做別的事，用 ${options.cli} action add 列出行動。` : `[mainflow] ${session.id} 的行動都已結束。繼續工作前先用 ${options.cli} action add 列出下一個行動。`;
 	const header = headerLine(session);
 	const marker = header ? [`- 這一輪最後一則回覆的最後一行寫「${header}」，回覆範例等其他內容都放在它前面。有顯示 hook 時，它會換成標題與連結。`] : [];
-	const grants = grantLines(root, session);
-	const waiters = waiterLines(root, session);
-	const warnings = queueWarnings(root, session, options.cli);
+	const grants = grantLines(dirs, session);
+	const waiters = waiterLines(dirs, session);
+	const warnings = queueWarnings(dirs, session, options.cli);
 	const digest = contentHash(JSON.stringify([
 		doing?.id ?? null,
 		grants,
@@ -4340,9 +5056,9 @@ function turnReminder(root, session, options) {
 		warnings
 	]));
 	const repeated = session.reminderDigest === digest;
-	if (!repeated && (session.reminderDigest !== void 0 || grants.length + waiters.length + warnings.length > 0) && readSession(root, session.id)) try {
+	if (!repeated && (session.reminderDigest !== void 0 || grants.length + waiters.length + warnings.length > 0) && readSession(dirs, session.id)) try {
 		if (options.saveDigest) options.saveDigest(digest);
-		else setReminderDigest(root, session.id, digest);
+		else setReminderDigest(dirs, session.id, digest);
 	} catch {}
 	const once = (lines, summary, full) => lines.length === 0 ? [] : repeated ? [summary] : full;
 	const granted = once(grants, `- 預先授權同上一輪，共 ${grants.length} 條。`, ["- 目前行動服務的主脈絡與所屬的組預先授權了這些動作：", ...grants.map((g) => `  ${g}`)]);
@@ -4358,66 +5074,8 @@ function turnReminder(root, session, options) {
 }
 //#endregion
 //#region ../core/dist/waiting.js
-/** Separates commits in the git log output (%x1e); commit messages do not use this control character. */
-const RECORD = "";
-/** Whether git finds a repository at the hub root; false as well when git itself cannot run. */
-function inGitRepository(root) {
-	try {
-		execFileSync("git", ["rev-parse", "--git-dir"], {
-			cwd: root,
-			stdio: "ignore"
-		});
-		return true;
-	} catch {
-		return false;
-	}
-}
-/** Whether a commit on the branch has the text in its message; git runs at the hub root, so the branch is the hub repository's. */
-function commitState(root, branch, text) {
-	let log;
-	try {
-		log = execFileSync("git", [
-			"log",
-			"--format=%h %s%n%b%x1e",
-			branch,
-			"--"
-		], {
-			cwd: root,
-			encoding: "utf8",
-			stdio: [
-				"ignore",
-				"pipe",
-				"pipe"
-			],
-			maxBuffer: 268435456
-		});
-	} catch {
-		if (!inGitRepository(root)) return {
-			met: false,
-			unreachable: true,
-			detail: `the hub root ${root} is not in a git repository, so no commit can appear there`
-		};
-		return {
-			met: false,
-			detail: `branch ${branch} is not in the repository at the hub root yet`
-		};
-	}
-	for (const record of log.split(RECORD)) {
-		const entry = record.replace(/^\n/, "");
-		const space = entry.indexOf(" ");
-		const message = entry.slice(space + 1);
-		if (space > 0 && message.includes(text)) return {
-			met: true,
-			detail: `commit ${entry.slice(0, space)} on ${branch} contains "${text}": ${message.split("\n")[0]}`
-		};
-	}
-	return {
-		met: false,
-		detail: `no commit on ${branch} contains "${text}"`
-	};
-}
-function actionState(root, ref) {
-	const found = resolveAction(root, ref);
+function actionState(dirs, ref) {
+	const found = resolveAction(dirs, ref);
 	if ("missing" in found) return {
 		met: false,
 		detail: found.missing
@@ -4442,16 +5100,16 @@ function actionState(root, ref) {
 * hub is not registered here. A registered hub that is missing on this machine or fails to load may return, so
 * that case keeps waiting. A prefix equal to this hub's own name reads the local hub.
 */
-function mainlineState(root, text) {
+function mainlineState(dirs, text) {
 	const ref = parseRef(text);
 	if (ref?.kind !== "mainline") return {
 		met: false,
 		unreachable: true,
 		detail: `"${text}" is not a mainline reference like m001 or other-hub:m001`
 	};
-	let target = root;
+	let target = dirs;
 	try {
-		const config = readConfig(root);
+		const config = readConfig(dirs);
 		if (ref.hub !== void 0 && ref.hub !== config.hub) {
 			const path = config.hubs?.[ref.hub];
 			if (path === void 0) return {
@@ -4459,11 +5117,12 @@ function mainlineState(root, text) {
 				unreachable: true,
 				detail: `hub "${ref.hub}" is not registered, so ${text} can never be read; run "mainflow hub add ${ref.hub} <path>"`
 			};
-			target = remoteRoot(root, path);
-			if (!isHubRoot(target)) return {
+			const registered = hubAtRoot(remoteRoot(dirs.root, path));
+			if (!registered) return {
 				met: false,
 				detail: `hub "${ref.hub}" is not at ${path} on this machine, so ${text} cannot be read yet`
 			};
+			target = registered;
 		}
 	} catch (error) {
 		return {
@@ -4503,13 +5162,15 @@ function mainlineState(root, text) {
 		detail: `mainline ${text} is ${status}`
 	};
 }
-/** Check a wait condition once. */
-function untilState(root, until) {
+/**
+* Check a wait condition once. A file is relative to the hub repository,
+* or in the data directory when named `.mainflow/{path}`.
+*/
+function untilState(dirs, until) {
 	switch (until.kind) {
-		case "commit": return commitState(root, until.branch, until.text);
-		case "action-done": return actionState(root, `${until.session}#${until.action}`);
-		case "mainline-done": return mainlineState(root, until.mainline);
-		case "file": return existsSync(resolve(root, until.path)) ? {
+		case "action-done": return actionState(dirs, `${until.session}#${until.action}`);
+		case "mainline-done": return mainlineState(dirs, until.mainline);
+		case "file": return existsSync(dataFile(dirs, until.path)) ? {
 			met: true,
 			detail: `${until.path} exists`
 		} : {
@@ -4520,9 +5181,9 @@ function untilState(root, until) {
 }
 //#endregion
 //#region ../core/dist/write.js
-function initHub(root, hub) {
-	runUnlocked(root, (h) => initHub$1(h, { name: hub }));
-	return join(root, DATA_DIR);
+function initHub(dirs, hub) {
+	runUnlocked(dirs, (h) => initHub$1(h, { name: hub }));
+	return dirs.data;
 }
 //#endregion
 //#region ../core/dist/archive.js
@@ -7356,17 +8017,70 @@ async function fetchTranscripts(source, wanted) {
 }
 //#endregion
 //#region ../core/dist/retro/receiver.js
-/** The environment variables a command reads the receiver from. None set: the retro does not read the receiver. */
+/**
+* Where a command reads the receiver from: the same names the measurement upload hooks use, so one setting serves both.
+* The address is the origin of the transcript upload URL; the Access service token is read from the environment first,
+* then from the macOS keychain.
+*/
 const RECEIVER_ENV = {
-	url: "MAINFLOW_TELEMETRY_URL",
-	accessClientId: "MAINFLOW_TELEMETRY_ACCESS_CLIENT_ID",
-	accessClientSecret: "MAINFLOW_TELEMETRY_ACCESS_CLIENT_SECRET"
+	url: "TRANSCRIPT_UPLOAD_URL",
+	accessClientId: "TELEMETRY_ACCESS_CLIENT_ID",
+	accessClientSecret: "TELEMETRY_ACCESS_CLIENT_SECRET"
 };
-/** The receiver named by the environment, or null when none of the three variables is set. A partial set is passed on, so the report says which is missing. */
-function receiverFromEnv(env) {
-	const url = env[RECEIVER_ENV.url]?.trim() ?? "";
-	const accessClientId = env[RECEIVER_ENV.accessClientId]?.trim() ?? "";
-	const accessClientSecret = env[RECEIVER_ENV.accessClientSecret]?.trim() ?? "";
+/** The macOS keychain items (generic passwords) holding the same service token. */
+const RECEIVER_KEYCHAIN = {
+	accessClientId: "telemetry-access-client-id",
+	accessClientSecret: "telemetry-access-client-secret"
+};
+function defaultReceiverSources(env) {
+	return {
+		settingsEnv: () => {
+			try {
+				const dir = env.CLAUDE_CONFIG_DIR?.trim() || join(env.HOME?.trim() || homedir(), ".claude");
+				const settings = JSON.parse(readFileSync(join(dir, "settings.json"), "utf8"));
+				return isObject(settings) && isObject(settings.env) ? settings.env : {};
+			} catch {
+				return {};
+			}
+		},
+		keychain: (service) => {
+			if (process.platform !== "darwin") return "";
+			try {
+				return execFileSync("security", [
+					"find-generic-password",
+					"-s",
+					service,
+					"-w"
+				], {
+					encoding: "utf8",
+					stdio: [
+						"ignore",
+						"pipe",
+						"ignore"
+					],
+					timeout: 5e3
+				}).trim();
+			} catch {
+				return "";
+			}
+		}
+	};
+}
+/**
+* The receiver the environment, the Claude Code user settings and the keychain name, or null when none of the three
+* values is found. A partial set is passed on, so the report says which is missing. The address is the origin of
+* TRANSCRIPT_UPLOAD_URL (the upload URL itself when it is no URL); each Access value is the environment variable, else
+* the keychain item. The keychain is asked only for what the environment lacks.
+*/
+function receiverFromEnv(env, sources = defaultReceiverSources(env)) {
+	const text = (v) => typeof v === "string" ? v.trim() : "";
+	const upload = text(env[RECEIVER_ENV.url]) || text(sources.settingsEnv()[RECEIVER_ENV.url]);
+	let url = upload;
+	try {
+		url = new URL(upload).origin;
+	} catch {}
+	const accessClientId = text(env[RECEIVER_ENV.accessClientId]) || sources.keychain(RECEIVER_KEYCHAIN.accessClientId).trim();
+	const accessClientSecret = text(env[RECEIVER_ENV.accessClientSecret]) || sources.keychain(RECEIVER_KEYCHAIN.accessClientSecret).trim();
 	return url || accessClientId || accessClientSecret ? {
 		url,
 		accessClientId,
@@ -7431,9 +8145,9 @@ async function readReceiver(config, scopes) {
 		problems
 	});
 	const absent = [
-		...config.url ? [] : [RECEIVER_ENV.url],
-		...config.accessClientId ? [] : [RECEIVER_ENV.accessClientId],
-		...config.accessClientSecret ? [] : [RECEIVER_ENV.accessClientSecret]
+		...config.url ? [] : [`${RECEIVER_ENV.url}（環境變數或 Claude Code 使用者設定的 env）`],
+		...config.accessClientId ? [] : [`${RECEIVER_ENV.accessClientId}（環境變數或鑰匙圈 ${RECEIVER_KEYCHAIN.accessClientId}）`],
+		...config.accessClientSecret ? [] : [`${RECEIVER_ENV.accessClientSecret}（環境變數或鑰匙圈 ${RECEIVER_KEYCHAIN.accessClientSecret}）`]
 	];
 	if (absent.length) {
 		problems.push(`${absent.join("、")} 沒有設定，沒有讀取接收端`);
@@ -7793,24 +8507,24 @@ const secondText = (ms) => {
 	return `${d.toLocaleDateString("sv-SE")}T${d.toTimeString().slice(0, 8)}`;
 };
 /** Where transcripts fetched from the receiver are kept: in the hub's local directory, which the hub ignores. */
-const transcriptCache = (root) => join(root, ".mainflow/local/transcripts");
+const transcriptCache = (dirs) => join(dirs.data, "local", "transcripts");
 /** The transcript to read: the recorded path when the file is there, else the copy fetched from the receiver, else the recorded path. */
-function transcriptOf(root, transcript) {
-	const recorded = transcriptPath(root, transcript);
+function transcriptOf(dirs, transcript) {
+	const recorded = transcriptPath(dirs, transcript);
 	if (existsSync(recorded)) return recorded;
-	const cached = join(transcriptCache(root), basename(recorded));
+	const cached = join(transcriptCache(dirs), basename(recorded));
 	return existsSync(cached) ? cached : recorded;
 }
 /** Sessions serving the mainline whose recorded transcript is not on this machine, as the receiver knows them. */
-function missingTranscripts(root, mainlineId) {
+function missingTranscripts(dirs, mainlineId) {
 	const wanted = /* @__PURE__ */ new Map();
-	for (const s of loadSessions(root).sessions) {
+	for (const s of loadSessions(dirs).sessions) {
 		if (!s.transcript || !s.actions.some((a) => servesMainline(a, mainlineId))) continue;
-		if (existsSync(transcriptPath(root, s.transcript))) continue;
+		if (existsSync(transcriptPath(dirs, s.transcript))) continue;
 		const sid = basename(s.transcript, ".jsonl");
 		wanted.set(sid, {
 			sid,
-			dir: transcriptCache(root)
+			dir: transcriptCache(dirs)
 		});
 	}
 	return [...wanted.values()];
@@ -7922,8 +8636,8 @@ const timed = (f) => {
 * counts inside its window; a subagent counts whole when the Agent call that started it falls inside its parent's
 * window, and not at all otherwise. Without the call, the subagent's first record stands in for it.
 */
-function readGroups(root, mainlineId, windowOf) {
-	const serving = loadSessions(root).sessions.filter((s) => s.actions.some((a) => servesMainline(a, mainlineId)));
+function readGroups(dirs, mainlineId, windowOf) {
+	const serving = loadSessions(dirs).sessions.filter((s) => s.actions.some((a) => servesMainline(a, mainlineId)));
 	const groups = [];
 	const bare = [];
 	const seen = /* @__PURE__ */ new Set();
@@ -7947,7 +8661,7 @@ function readGroups(root, mainlineId, windowOf) {
 	};
 	const ordered = [...serving].sort((a, b) => Number(Boolean(a.delegatedFrom)) - Number(Boolean(b.delegatedFrom)));
 	for (const s of ordered) {
-		const file = s.transcript ? transcriptOf(root, s.transcript) : void 0;
+		const file = s.transcript ? transcriptOf(dirs, s.transcript) : void 0;
 		if (s.delegatedFrom) {
 			if (!file || seen.has(file)) continue;
 			const parent = groups.find((g) => g.session === s.delegatedFrom);
@@ -7998,8 +8712,8 @@ function readGroups(root, mainlineId, windowOf) {
 * Read the transcripts of every session with an action serving the mainline, and their subagents', into cost,
 * attribution to promptex nodes, anomalies, review rounds and the offline analyses.
 */
-function retroReport(root, mainlineId, options = {}) {
-	return buildReport(root, readRetro(root, mainlineId, options), options);
+function retroReport(dirs, mainlineId, options = {}) {
+	return buildReport(dirs, readRetro(dirs, mainlineId, options), options);
 }
 /**
 * retroReport with the measurement receiver's export: the transcripts are read first, since their windows decide
@@ -8007,9 +8721,9 @@ function retroReport(root, mainlineId, options = {}) {
 * in part, leaves the report as retroReport would make it from what was read, with what is missing listed in
 * `measurements.problems`.
 */
-async function retroReportFromReceiver(root, mainlineId, receiver, options = {}) {
+async function retroReportFromReceiver(dirs, mainlineId, receiver, options = {}) {
 	if (receiver.url && receiver.accessClientId && receiver.accessClientSecret) {
-		const wanted = missingTranscripts(root, mainlineId);
+		const wanted = missingTranscripts(dirs, mainlineId);
 		if (wanted.length) {
 			const { warnings } = await fetchTranscripts({
 				url: receiver.url,
@@ -8020,19 +8734,19 @@ async function retroReportFromReceiver(root, mainlineId, receiver, options = {})
 			for (const line of warnings) (receiver.warn ?? ((l) => process.stderr.write(`${l}\n`)))(line);
 		}
 	}
-	const read = readRetro(root, mainlineId, options);
+	const read = readRetro(dirs, mainlineId, options);
 	const t = performance.now();
 	const exported = await readReceiver(receiver, receiverScopes(read.groups));
-	return buildReport(root, read, {
+	return buildReport(dirs, read, {
 		...options,
 		receiver: exported
 	}, performance.now() - t);
 }
-function readRetro(root, mainlineId, options) {
+function readRetro(dirs, mainlineId, options) {
 	const started = performance.now();
-	const mainline = loadHub(root, { remotes: false }).mainlines.find((m) => m.id === mainlineId);
+	const mainline = loadHub(dirs, { remotes: false }).mainlines.find((m) => m.id === mainlineId);
 	if (!mainline) throw new WriteError(`mainline ${mainlineId} not found; run "mainflow status --all" to list mainlines`);
-	const [{ groups, bare }, readMs] = timed(() => readGroups(root, mainlineId, options.windowOf));
+	const [{ groups, bare }, readMs] = timed(() => readGroups(dirs, mainlineId, options.windowOf));
 	return {
 		started,
 		mainline,
@@ -8042,7 +8756,7 @@ function readRetro(root, mainlineId, options) {
 		readMs
 	};
 }
-function buildReport(root, read, options, receiverMs) {
+function buildReport(dirs, read, options, receiverMs) {
 	const { started, mainline, mainlineId, groups, bare, readMs } = read;
 	const receiver = options.receiver;
 	const measuredRuns = [];
@@ -8189,7 +8903,7 @@ function buildReport(root, read, options, receiverMs) {
 	}))).sort((a, b) => b.runs - a.runs);
 	const modelList = [...models.values()].sort((a, b) => b.calls - a.calls || a.model.localeCompare(b.model));
 	const transcriptTotal = modelList.reduce((n, m) => n + (m.cost ?? 0), 0);
-	const nodes = loadNodeRegistry(options.promptexRoots ?? [homedir(), root]);
+	const nodes = loadNodeRegistry(options.promptexRoots ?? [homedir(), dirs.root]);
 	const metas = groups.flatMap((g) => g.subagents.map((a) => ({
 		agentId: basename(a.file, ".jsonl").replace(/^agent-/, ""),
 		...a.meta
@@ -8316,9 +9030,9 @@ function buildReport(root, read, options, receiverMs) {
 //#endregion
 //#region ../core/dist/migrate.js
 /** Convert a format 1 hub on disk to the current format, writing nothing when `dryRun` is set. */
-function migrateHub(root, options = {}) {
-	const storage = nodeStorage(root);
-	if (storage.read("config.yaml") === null) throw new WriteError(`no hub at ${root}; run mainflow init first`);
+function migrateHub(dirs, options = {}) {
+	const storage = nodeStorage(dirs);
+	if (storage.read("config.yaml") === null) throw new WriteError(`no hub at ${dirs.root}; run mainflow init first`);
 	return applyOp(storage, (hub) => {
 		const result = migrateHub$1(hub);
 		return options.dryRun ? {
@@ -8328,6 +9042,177 @@ function migrateHub(root, options = {}) {
 	}).value;
 }
 //#endregion
+//#region ../core/dist/migrate-data.js
+/** What the original data directory is renamed to, inside the hub repository, once the hub reads from its new place. */
+const MIGRATED_NAME = `${DATA_DIR}.migrated`;
+/** Paths of the data directory, relative to it with `/`, that the copy leaves out. */
+const LEFT_OUT = /* @__PURE__ */ new Set([".git", "local/write.lock"]);
+/**
+* Every entry under `dir` but the ones left out, by its path relative to `dir` with `/`; symbolic links are not followed.
+* Refused when an entry is none of a file, a directory or a symbolic link, such as a named pipe, which the copy cannot take.
+*/
+function inventory(dir) {
+	const items = /* @__PURE__ */ new Map();
+	const walk = (at) => {
+		for (const name of readdirSync(join(dir, at)).sort()) {
+			const path = at ? `${at}/${name}` : name;
+			if (LEFT_OUT.has(path)) continue;
+			const full = join(dir, path);
+			const info = lstatSync(full);
+			if (info.isSymbolicLink()) items.set(path, {
+				kind: "link",
+				target: readlinkSync(full)
+			});
+			else if (info.isDirectory()) {
+				items.set(path, { kind: "dir" });
+				walk(path);
+			} else if (info.isFile()) items.set(path, {
+				kind: "file",
+				hash: createHash("sha256").update(readFileSync(full)).digest("hex"),
+				size: info.size
+			});
+			else throw new WriteError(`${full} is neither a file, a directory nor a symbolic link, so it cannot be copied; move it out of ${dir} and run this again`);
+		}
+	};
+	walk("");
+	return items;
+}
+/** The first difference between the original's entries and the copy's, or null when the copy holds the same. */
+function difference(original, copy) {
+	for (const [path, item] of original) {
+		const copied = copy.get(path);
+		if (!copied) return `${path} is missing from the copy`;
+		if (JSON.stringify(copied) !== JSON.stringify(item)) return `${path} differs in the copy`;
+	}
+	for (const path of copy.keys()) if (!original.has(path)) return `${path} is in the copy only`;
+	return null;
+}
+/** `<root>/.mainflow.migrated`, or the first of `.mainflow.migrated.2`, `.3` … that is free. */
+function keptName(root) {
+	for (let n = 1;; n++) {
+		const kept = join(root, n === 1 ? MIGRATED_NAME : `${MIGRATED_NAME}.${n}`);
+		if (!existsSync(kept) && !isLink(kept)) return kept;
+	}
+}
+const isLink = (path) => {
+	try {
+		return lstatSync(path).isSymbolicLink();
+	} catch {
+		return false;
+	}
+};
+/** Whether `dir` is missing or an empty directory, so the copy can take its place. */
+const vacant = (dir) => !existsSync(dir) || statSync(dir).isDirectory() && readdirSync(dir).length === 0;
+/**
+* Move the data of the hub whose repository is `path` from `<path>/.mainflow` to `$MAINFLOW_HOME/<name>`, and register
+* the hub with its data there. With `dryRun` nothing changes: the move is checked and described. Refused when the
+* repository holds no hub data, when the hub already moved its data, when the new place is taken, when the hub could
+* not be registered from there, or when `busy` names something that still reads and writes the old place, such as a
+* running sync client; `busy` is asked again once the move holds the write lock, so nothing starts between the check
+* and the move.
+*/
+async function migrateHubData(path, options = {}) {
+	const env = options.env ?? process.env;
+	const dryRun = options.dryRun ?? false;
+	const root = realPath(path);
+	if (!root) throw new WriteError(`${path} does not exist`);
+	const found = inRepositoryData(root);
+	if (!found) {
+		const registered = hubAtRoot(root, env);
+		if (registered) throw new WriteError(`hub "${registered.name}" already keeps its data in ${registered.data}; ${join(root, DATA_DIR)} holds no hub data to move`);
+		throw new WriteError(`no hub data to move at ${root}: ${join(root, DATA_DIR, "config.yaml")} does not exist`);
+	}
+	const { name } = found;
+	const source = realPath(found.data);
+	const to = join(realPath(mainflowHome(env)) ?? mainflowHome(env), name);
+	const previous = readRegistry(env).hubs[name] ?? null;
+	if (previous && previous.root !== root) throw new WriteError(`hub "${name}" is registered from ${previous.root}, not ${root}; move its data from there, or run mainflow hub unregister ${name} first`);
+	if (previous && previous.data === (realPath(to) ?? to)) throw new WriteError(`hub "${name}" already moved its data to ${to} and reads it from there; ${found.data} is the original an earlier move could not rename. Check that the hub works from ${to}, then rename or delete ${found.data} yourself.`);
+	if (!vacant(to)) throw new WriteError(`${to} already exists, so the data of hub "${name}" cannot move there. When it holds this hub from an earlier move, check it and register it with: mainflow hub register ${name} ${root}. Otherwise move it away and run this again.`);
+	previewRegistration(name, root, env, { data: source });
+	const worktree = statSync(join(source, ".git"), { throwIfNoEntry: false })?.isFile() ?? false;
+	const files = [...inventory(source).values()].filter((item) => item.kind !== "dir");
+	const bytes = files.reduce((sum, item) => sum + (item.kind === "file" ? item.size : 0), 0);
+	const move = {
+		name,
+		root,
+		from: found.data,
+		to,
+		files: files.length,
+		bytes,
+		worktree,
+		kept: keptName(root),
+		previous,
+		dryRun
+	};
+	const busy = async () => {
+		const reason = options.busy ? await options.busy({
+			root,
+			data: found.data
+		}, name) : null;
+		if (reason) throw new WriteError(reason);
+	};
+	if (dryRun) {
+		await busy();
+		return move;
+	}
+	const staging = join(mainflowHome(env), `.${name}.migrating`);
+	const created = !existsSync(to);
+	mkdirSync(mainflowHome(env), { recursive: true });
+	return withLockAsync(source, async () => {
+		await busy();
+		rmSync(staging, {
+			recursive: true,
+			force: true
+		});
+		let placed = false;
+		try {
+			const copied = inventory(copyData(source, staging));
+			const differs = difference(inventory(source), copied);
+			if (differs) throw new WriteError(`the copy of ${source} in ${staging} is not the same (${differs})`);
+			renameSync(staging, to);
+			placed = true;
+			registerHub(name, root, env, { data: to });
+		} catch (error) {
+			rmSync(staging, {
+				recursive: true,
+				force: true
+			});
+			if (placed) {
+				rmSync(to, {
+					recursive: true,
+					force: true
+				});
+				if (!created) mkdirSync(to);
+			}
+			throw error instanceof WriteError ? new WriteError(`${error.message}; nothing moved, and ${found.data} is as it was`) : new WriteError(`could not move the data of hub "${name}" to ${to}: ${error.message}; nothing moved, and ${found.data} is as it was`);
+		}
+		try {
+			renameSync(found.data, move.kept);
+		} catch (error) {
+			return {
+				...move,
+				kept: found.data,
+				notRenamed: error.message
+			};
+		}
+		rmSync(join(move.kept, "local", "write.lock"), { force: true });
+		return move;
+	});
+}
+/** Copy the data directory `source` to `target`, leaving out LEFT_OUT, with each file's times kept; returns `target`. */
+function copyData(source, target) {
+	cpSync(source, target, {
+		recursive: true,
+		errorOnExist: true,
+		force: false,
+		preserveTimestamps: true,
+		verbatimSymlinks: true,
+		filter: (from) => !LEFT_OUT.has(relative(source, from).split(sep).join("/"))
+	});
+	return target;
+}
+//#endregion
 //#region ../core/dist/group-plan.js
 /** Sessions that can still hold work: not archived, and active or paused. */
 const live = (s) => !s.archivedAt && (s.status === "active" || s.status === "paused");
@@ -8501,13 +9386,13 @@ const realOf = (path) => existsSync(path) ? realpathSync(path) : resolve(path);
 * port differs from what Caddy already has, so an ordinary start leaves Caddy alone. A link owned by a
 * different hub of the same name stops here: overwriting it would silently take that hub's host name.
 */
-async function syncHost(root, hub, port, options = {}) {
+async function syncHost(dirs, hub, port, options = {}) {
 	const sites = caddySites();
 	if (!sites || !existsSync(sites)) return {
 		url: null,
 		reason: `Caddy's sites directory was not found (${sites ?? "no Homebrew prefix"}); install Caddy and import that directory from the Caddyfile, or set MAINFLOW_CADDY_SITES`
 	};
-	const dir = join(root, DATA_DIR, "local", "caddy");
+	const dir = join(dirs.data, "local", "caddy");
 	const file = join(dir, `${hub}.caddy`);
 	const link = join(sites, `mainflow-${hub}.caddy`);
 	removeDanglingLinks(sites);
@@ -8550,14 +9435,14 @@ async function syncHost(root, hub, port, options = {}) {
 * from loading every other site. Only a link that points into `root` is removed; the reload failure, if any,
 * is returned for the caller to log.
 */
-function removeHostLink(root, hub, reload = reloadCaddy) {
+function removeHostLink(dirs, hub, reload = reloadCaddy) {
 	const sites = caddySites();
 	if (!sites) return null;
 	const link = join(sites, `mainflow-${hub}.caddy`);
 	const linked = lstatSync(link, { throwIfNoEntry: false });
 	let removed = false;
 	if (linked?.isSymbolicLink()) {
-		if (resolve(dirname(link), readlinkSync(link)).startsWith(resolve(root) + "/")) {
+		if (resolve(dirname(link), readlinkSync(link)).startsWith(resolve(dirs.data) + "/")) {
 			rmSync(link);
 			removed = true;
 		}
@@ -8597,4 +9482,4 @@ function openInApp(hub, target, closeAfterMs = 150) {
 	return true;
 }
 //#endregion
-export { linksInto as $, grantScope as A, WriteError as At, renumberRequest as B, HANDLED_FILE as C, TASK_FILE as Ct, loadSessions as D, worktreesOf as Dt, readNotices as E, findHubRoot as Et, mayDecorate as F, applyOperation as G, renumberPath as H, attributeTrace as I, loadConfig as J, checkHubName as K, traceTranscript as L, decorateReply as M, splitFrontMatter as Mt, endsWithMarker as N, readSession as O, ConflictError as Ot, headerLine as P, mainlineEdges as Q, transcriptTitle as R, turnReminder as S, MAINLINE_FILE as St, parseWarn as T, currentBranch as Tt, renumberText as U, renumberFiles as V, scopeOfPath as W, sectionText as X, loadHub as Y, dependencyGraph as Z, setArchivedMany as _, readsAsText as _t, openInApp as a, nowMinute as at, duplicateClaimLines as b, formatMismatch as bt, siteBlock as c, nodeStorage as ct, migrateHub as d, MAX_BLOB_BYTES as dt, memberOfGroup as et, retroReport as f, MAX_FILE_BYTES as ft, ARCHIVE_KINDS as g, exceedsFileLimit as gt, RETRY_RULES as h, comparePaths as ht, hostName as i, taskFile as it, matchGrants as j, contentHash as jt, transcriptPath as k, DATA_DIR as kt, syncHost as l, ACCESS_HEADERS as lt, receiverFromEnv as m, SOCKET_MAX_AGE_CLOSE as mt, DEFAULT_UI_PORT as n, remoteMembers as nt, removeDanglingLinks as o, readFrontMatter as ot, retroReportFromReceiver as p, ROUTES as pt, HubError as q, caddySites as r, unavailableHubs as rt, removeHostLink as s, readYaml as st, APP_BUNDLE_ID as t, refIndex as tt, groupPlan as u, BLOB_HASH as ut, initHub as v, requestTime as vt, markNoticesHandled as w, requireSlug as wt, sessionBriefing as x, hubFormatVersion as xt, untilState as y, textBytes as yt, applyOffline as z };
+export { loadConfig as $, WriteError as $t, transcriptPath as A, MAINLINE_FILE as At, applyOffline as B, registeredName as Bt, turnReminder as C, readsAsText as Ct, readNotices as D, hubFormatVersion as Dt, parseWarn as E, formatMismatch as Et, headerLine as F, inRepositoryHubAt as Ft, scopeOfPath as G, nodeStorage as Gt, renumberFiles as H, resolveHub as Ht, mayDecorate as I, listHubs as It, syncedDir as J, hubPath as Jt, hubDigest as K, currentBranch as Kt, attributeTrace as L, notRegisteredMessage as Lt, matchGrants as M, requireSlug as Mt, decorateReply as N, hubAtRoot as Nt, loadSessions as O, hubRequirements as Ot, endsWithMarker as P, hubHoldingFile as Pt, HubError as Q, DATA_DIR as Qt, traceTranscript as R, readRegistry as Rt, sessionBriefing as S, exceedsFileLimit as St, markNoticesHandled as T, textBytes as Tt, renumberPath as U, unregisterHub as Ut, renumberRequest as V, registryFile as Vt, renumberText as W, userDataDir as Wt, applyOperation as X, worktreesOf as Xt, syncedPath as Y, realPath as Yt, checkHubName as Z, ConflictError as Zt, ARCHIVE_KINDS as _, MAX_FILE_BYTES as _t, openInApp as a, memberOfGroup as at, untilState as b, VERSION_HEADER as bt, siteBlock as c, unavailableHubs as ct, migrateHubData as d, readFrontMatter as dt, contentHash as en, loadHub as et, migrateHub as f, readYaml as ft, RETRY_RULES as g, MAX_CHANGE_PAGE as gt, receiverFromEnv as h, MAX_BLOB_BYTES as ht, hostName as i, linksInto as it, grantScope as j, TASK_FILE as jt, readSession as k, versionMismatch as kt, syncHost as l, taskFile as lt, retroReportFromReceiver as m, BLOB_HASH as mt, DEFAULT_UI_PORT as n, dependencyGraph as nt, removeDanglingLinks as o, refIndex as ot, retroReport as p, ACCESS_HEADERS as pt, mayHoldSynced as q, dataFile as qt, caddySites as r, mainlineEdges as rt, removeHostLink as s, remoteMembers as st, APP_BUNDLE_ID as t, splitFrontMatter as tn, sectionText as tt, groupPlan as u, nowMinute as ut, setArchivedMany as v, ROUTES as vt, HANDLED_FILE as w, requestTime as wt, duplicateClaimLines as x, comparePaths as xt, initHub as y, SOCKET_MAX_AGE_CLOSE as yt, transcriptTitle as z, registerHub as zt };