mainflow 0.42.0 → 0.43.0-alpha.2

package/dist/{dist-zSabglPq.js → dist-D5rZ0MQH.js}

@@ -1,3 +1,4 @@
+import validRange from "semver/ranges/valid.js";
 import { z } from "zod";
 //#region ../schema/dist/grants.js
 /** What a mainline can authorize ahead of time. */
@@ -43,7 +44,7 @@ const GRANT_TARGET_FORMS = {
 };
 const KEBAB = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 /** A git branch name, `*` standing for any run of characters. */
-const BRANCH$1 = /^(?!\/)(?!.*\/\/)(?!.*\.\.)[A-Za-z0-9._/*-]+(?<!\/)$/;
+const BRANCH = /^(?!\/)(?!.*\/\/)(?!.*\.\.)[A-Za-z0-9._/*-]+(?<!\/)$/;
 /** npm package names: lowercase, optionally scoped. */
 const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/;
 /** A tag pattern: no whitespace, `*` and `?` as in a shell glob. */
@@ -62,7 +63,7 @@ function parseGrantTarget(action, target) {
 			const repo = colon < 0 ? target : target.slice(0, colon);
 			const branch = colon < 0 ? void 0 : target.slice(colon + 1);
 			if (!repo) return fail(action, "the repo name is missing");
-			if (branch !== void 0 && !BRANCH$1.test(branch)) return fail(action, `"${branch}" is not a branch name`);
+			if (branch !== void 0 && !BRANCH.test(branch)) return fail(action, `"${branch}" is not a branch name`);
 			return {
 				ok: true,
 				target: {
@@ -666,17 +667,68 @@ const SURVEY_LINES = [
 		requires: "環境："
 	}
 ];
+/**
+* How a version is compared with config.yaml's `mainflow`: a prerelease satisfies a range by its place in semver order,
+* so 0.44.0-beta.1 satisfies ">=0.43.0" and 0.43.0-beta.1 does not.
+*/
+const MAINFLOW_RANGE = { includePrerelease: true };
+/** Whether `range` is a range config.yaml's `mainflow` may hold: one the semver package reads, and not blank, which it would read as any version. */
+const isMainflowRange = (range) => range.trim() !== "" && validRange(range, MAINFLOW_RANGE) !== null;
+/** A repository under `repos`: a path relative to the hub root, which is a primary repository, or the path with its role. */
+const repoEntrySchema = z.union([z.string(), z.object({
+	path: z.string(),
+	role: z.enum(["primary", "reference"])
+})]);
+/** The path of a listed repository, relative to the hub root. */
+const repoPath = (entry) => typeof entry === "string" ? entry : entry.path;
+/** The role of a listed repository; the plain path form is a primary repository. */
+const repoRole = (entry) => typeof entry === "string" ? "primary" : entry.role;
+/** Every repository config.yaml lists, by name, with its path relative to the hub root and its role. */
+const listedRepos = (repos) => Object.entries(repos).map(([name, entry]) => ({
+	name,
+	path: repoPath(entry),
+	role: repoRole(entry)
+}));
+/** Every listed repository's path relative to the hub root, by name, whatever its role. */
+const repoPaths = (repos) => Object.fromEntries(Object.entries(repos).map(([name, entry]) => [name, repoPath(entry)]));
 const configSchema = z.object({
 	/** Also the first label of the hub's host name, {hub}.mainflow.localhost, so kebab-case */
 	hub: z.string().regex(HUB_NAME, "hub name must be kebab-case, e.g. carlos-space"),
 	formatVersion: z.number().int().positive(),
-	repos: z.record(z.string(), z.string()),
+	/** Repositories tasks and grants may name: name to a path relative to the hub root, or to { path, role } */
+	repos: z.record(z.string(), repoEntrySchema),
 	/** Other hubs this hub's references point into: hub name to its root, relative to this hub's root */
 	hubs: z.record(z.string().regex(HUB_NAME, "a hub name must be kebab-case").refine((n) => !RESERVED_HUB_NAMES.includes(n), `${RESERVED_HUB_NAMES.join(" and ")} are reserved`), z.string()).optional(),
 	/** Categories this hub uses on top of DEFAULT_CATEGORIES */
 	categories: z.array(z.string().regex(SLUG, "a category must be kebab-case")).optional(),
 	/** The port `mainflow ui` tries first for this hub; when it is taken, the next free one is used and the host name follows */
-	ui: z.object({ port: z.number().int().min(1024).max(65535) }).optional()
+	ui: z.object({ port: z.number().int().min(1024).max(65535) }).optional(),
+	/**
+	* The mainflow versions that may write to this hub through a sync server, as a semver range like ">=0.43.0", compared as
+	* MAINFLOW_RANGE says: the server refuses every write from a CLI outside it, and from one that does not say its version
+	*/
+	mainflow: z.string().refine(isMainflowRange, "mainflow is a semver range of the mainflow versions that may write to this hub, like \">=0.43.0\"").optional()
+});
+/**
+* One hub as this machine registered it, every path absolute and resolved by the file system (realpath), so a path
+* is compared as the file system spells it. Derived from the hub's config.yaml by `mainflow hub register`.
+*/
+const registeredHubSchema = z.object({
+	/** The hub repository: the directory config.yaml's repository paths are relative to */
+	root: z.string(),
+	/** The directory holding config.yaml and the hub's documents */
+	data: z.string(),
+	/** Content hash of config.yaml when this entry was derived from it, so a changed config.yaml is noticed */
+	config: z.string(),
+	/** The repositories this hub is the primary hub of, by the name config.yaml gives them; the hub repository is one of them whether listed or not */
+	repos: z.record(z.string(), z.string()),
+	/** The repositories this hub lists as references, by name */
+	references: z.record(z.string(), z.string())
+});
+/** The user-level hub registry, $MAINFLOW_HOME/hubs.json: which hub a directory on this machine belongs to. */
+const hubRegistrySchema = z.object({
+	version: z.literal(1),
+	hubs: z.record(z.string().regex(HUB_NAME), registeredHubSchema)
 });
 const refSchema = z.object({
 	title: text,
@@ -889,11 +941,6 @@ function parseActionRef(input) {
 const waitingForAction = (waitingFor) => waitingFor && parseActionRef(waitingFor) ? waitingFor : void 0;
 /** The condition forms, one example each; facts and error messages read them from here. */
 const UNTIL_FORMS = [
-	{
-		kind: "commit",
-		format: "commit:{branch}:{text}",
-		example: "commit:main:feat(core): 行動阻塞"
-	},
 	{
 		kind: "action-done",
 		format: "action-done:{sessionId}#a{NNN}",
@@ -911,8 +958,14 @@ const UNTIL_FORMS = [
 	}
 ];
 const UNTIL_EXAMPLES = UNTIL_FORMS.map((f) => f.format).join(", ");
-/** A branch name git log can take as a revision; a leading hyphen would read as an option. */
-const BRANCH = /^[^\s:~^?*[\\-][^\s:~^?*[\\]*$/;
+/** What to tell the writer of an `input` that was a wait condition once and is removed now, or null when it is not one. */
+function removedUntil(input) {
+	return input.startsWith("commit:") ? `the commit: condition was removed; use one of ${UNTIL_EXAMPLES}, for example file:{relative path} for a file the commit produces` : null;
+}
+/** Why `input` is not a wait condition, for the messages that reject it; a form that was removed says so and names what to use. */
+function untilProblem(input) {
+	return removedUntil(input) ?? `expected a condition like ${UNTIL_EXAMPLES}`;
+}
 /** Parse a wait condition, or return null when it matches none of the forms. */
 function parseUntil(input) {
 	const colon = input.indexOf(":");
@@ -920,16 +973,6 @@ function parseUntil(input) {
 	const kind = input.slice(0, colon);
 	const argument = input.slice(colon + 1);
 	switch (kind) {
-		case "commit": {
-			const split = argument.indexOf(":");
-			const branch = argument.slice(0, split);
-			const text = argument.slice(split + 1);
-			return split > 0 && BRANCH.test(branch) && !branch.includes("..") && text.length > 0 ? {
-				kind,
-				branch,
-				text
-			} : null;
-		}
 		case "action-done": {
 			const ref = parseActionRef(argument);
 			return ref ? {
@@ -956,7 +999,12 @@ function parseUntil(input) {
 const actionBlockSchema = z.object({
 	reason: text,
 	waitingFor: text.optional(),
-	until: z.string().refine((s) => parseUntil(s) !== null, `expected a condition like ${UNTIL_EXAMPLES}`).optional()
+	until: z.string().superRefine((s, ctx) => {
+		if (parseUntil(s) === null) ctx.addIssue({
+			code: "custom",
+			message: untilProblem(s)
+		});
+	}).optional()
 });
 const actionSchema = z.object({
 	id: id("action"),
@@ -1110,4 +1158,4 @@ function parseOpsLine(line) {
 	return parsed.success ? parsed.data : null;
 }
 //#endregion
-export { stampMs as $, TASK_REQUIRED_SECTIONS as A, mainlineSchema as B, RESERVED_HUB_NAMES as C, SLUG as D, SESSION_STATUS as E, decisionSchema as F, parseUntil as G, parseActionRef as H, findingSchema as I, sessionSchema as J, refExample as K, formatOpsEntry as L, UNTIL_FORMS as M, WORK_STATUS as N, SURVEY_LINES as O, configSchema as P, OFFSET as Q, groupSchema as R, REF_EXAMPLES as S, SESSION_ID as T, parseOpsLine as U, opsEntrySchema as V, parseRef as W, waitingForAction as X, taskSchema as Y, waitingForRef as Z, LINK_RELS as _, DECISION_SECTIONS as a, grantForm as at, MERGE_STATES as b, FINDING_SECTIONS as c, GROUP_SECTIONS as d, GRANT_ACTIONS as et, GROUP_STATUS as f, ISSUE_STATUS as g, ISSUE_SECTIONS as h, DECISION_BASES as i, grantCovers as it, TASK_SECTIONS as j, SURVEY_SECTION as k, FINDING_STATUS as l, ID_PATTERNS as m, CLOSED_STATUS as n, GRANT_TARGET_FORMS as nt, DECISION_STATUS as o, grantRepo as ot, GROUP_SUMMARY_SECTION as p, refMainline as q, DECIDERS as r, describeRequest as rt, DEFAULT_CATEGORIES as s, parseGrantTarget as st, CHECKLIST_REF as t, GRANT_FORMS as tt, FORMAT_VERSION as u, MAINLINE_SECTIONS as v, SERVES_REF as w, PRIORITIES as x, MAINLINE_STATUS as y, issueSchema as z };
+export { removedUntil as $, SURVEY_LINES as A, groupSchema as B, PRIORITIES as C, SESSION_ID as D, SERVES_REF as E, WORK_STATUS as F, mainlineSchema as G, isMainflowRange as H, configSchema as I, parseOpsLine as J, opsEntrySchema as K, decisionSchema as L, TASK_REQUIRED_SECTIONS as M, TASK_SECTIONS as N, SESSION_STATUS as O, UNTIL_FORMS as P, refMainline as Q, findingSchema as R, MERGE_STATES as S, RESERVED_HUB_NAMES as T, issueSchema as U, hubRegistrySchema as V, listedRepos as W, parseUntil as X, parseRef as Y, refExample as Z, ISSUE_STATUS as _, DECISION_SECTIONS as a, waitingForAction as at, MAINLINE_SECTIONS as b, FINDING_SECTIONS as c, stampMs as ct, GROUP_SECTIONS as d, GRANT_TARGET_FORMS as dt, repoPath as et, GROUP_STATUS as f, describeRequest as ft, ISSUE_SECTIONS as g, parseGrantTarget as gt, ID_PATTERNS as h, grantRepo as ht, DECISION_BASES as i, untilProblem as it, SURVEY_SECTION as j, SLUG as k, FINDING_STATUS as l, GRANT_ACTIONS as lt, HUB_NAME as m, grantForm as mt, CLOSED_STATUS as n, sessionSchema as nt, DECISION_STATUS as o, waitingForRef as ot, GROUP_SUMMARY_SECTION as p, grantCovers as pt, parseActionRef as q, DECIDERS as r, taskSchema as rt, DEFAULT_CATEGORIES as s, OFFSET as st, CHECKLIST_REF as t, repoPaths as tt, FORMAT_VERSION as u, GRANT_FORMS as ut, LINK_RELS as v, REF_EXAMPLES as w, MAINLINE_STATUS as x, MAINFLOW_RANGE as y, formatOpsEntry as z };

package/dist/facts.d.ts

@@ -1,4 +1,4 @@
-import { g as SurveyLine, l as ID_PATTERNS, m as SLUG, o as FORMAT_VERSION, p as SERVES_REF, r as CHECKLIST_REF, v as Until } from "./index-Dk4fCI7q.js";
+import { g as SurveyLine, l as ID_PATTERNS, m as SLUG, o as FORMAT_VERSION, p as SERVES_REF, r as CHECKLIST_REF, v as Until } from "./index-BqPQp6TF.js";
 //#region src/facts.d.ts
 export interface CommandSpec {
   usage: string;
@@ -14,7 +14,37 @@ export interface CommandSpec {
 export declare const COMMAND_SPECS: {
   readonly init: {
     readonly usage: 'init <hub-name>';
-    readonly summary: 'Create .mainflow/ in the current directory';
+    readonly summary: 'Create the data directory of a new hub in $MAINFLOW_HOME/<hub-name> (~/.mainflow/<hub-name> by default) and register the hub on this machine with the current directory as its repository; nothing is written into the repository';
+    readonly args: 1;
+    readonly needsHub: false;
+  };
+  readonly 'hub register': {
+    readonly usage: 'hub register <name> <path>';
+    readonly summary: 'Register on this machine the hub whose repository is <path>, so mainflow run in its primary repositories and their worktrees works on it; run it again after config.yaml changes to update it at once';
+    readonly args: 2;
+    readonly needsHub: false;
+  };
+  readonly 'hub migrate-data': {
+    readonly usage: 'hub migrate-data <path> [--dry-run]';
+    readonly summary: '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. The data is copied and compared before the registry switches to it; the original is then renamed to <path>/.mainflow.migrated, not deleted. A .git file of a git worktree is not copied and git is not run: the command prints the git worktree remove to run. Refused while mainflow sync or the hub\'s interface runs, or when $MAINFLOW_HOME/<name> is taken; --dry-run says what it would do';
+    readonly args: 1;
+    readonly needsHub: false;
+  };
+  readonly 'hub list': {
+    readonly usage: 'hub list';
+    readonly summary: 'List the hubs registered on this machine with their primary and referenced repositories';
+    readonly args: 0;
+    readonly needsHub: false;
+  };
+  readonly 'hub which': {
+    readonly usage: 'hub which [--json]';
+    readonly summary: 'Print the name, repository root and data directory of the hub the current directory belongs to, as hub list finds it. --json prints one object {"name","root","data"}. Outside any registered hub it prints nothing to stdout, one line to stderr, and exits 1. Writes nothing';
+    readonly args: 0;
+    readonly needsHub: false;
+  };
+  readonly 'hub unregister': {
+    readonly usage: 'hub unregister <name>';
+    readonly summary: 'Remove a hub from this machine\'s registry; its files stay';
     readonly args: 1;
     readonly needsHub: false;
   };
@@ -26,13 +56,13 @@ export declare const COMMAND_SPECS: {
   };
   readonly check: {
     readonly usage: 'check';
-    readonly summary: 'Validate every file under .mainflow/';
+    readonly summary: 'Validate every file in the hub\'s data directory';
     readonly args: 0;
     readonly needsHub: true;
   };
   readonly migrate: {
     readonly usage: 'migrate [--dry-run]';
-    readonly summary: 'Convert the hub to the data format this CLI reads; --dry-run lists the changes without writing';
+    readonly summary: 'Convert the hub to the data format this CLI reads, on the sync server when it keeps the hub; --dry-run lists the changes without writing';
     readonly args: 0;
     readonly needsHub: true;
   };
@@ -44,7 +74,7 @@ export declare const COMMAND_SPECS: {
   };
   readonly 'repo add': {
     readonly usage: 'repo add <name> <path>';
-    readonly summary: 'Register a repository that tasks can point at (path relative to the hub root)';
+    readonly summary: 'Register a repository that tasks can point at as a primary repository of the hub (path relative to the hub root)';
     readonly args: 2;
     readonly needsHub: true;
   };
@@ -366,25 +396,25 @@ export declare const COMMAND_SPECS: {
   };
   readonly retro: {
     readonly usage: 'retro <m> [--json]';
-    readonly summary: 'Read the Claude Code transcripts of the sessions that served a mainline, and their subagents\', into estimated list-price cost (per model, opening context, cache hit rate, hook injections) and candidates for where work went wrong (tool errors, rerun Bash commands, hook injections followed by no tool call, blocks, pauses over 5 minutes, failed completion checks); read-only. With MAINFLOW_TELEMETRY_URL, MAINFLOW_TELEMETRY_ACCESS_CLIENT_ID and MAINFLOW_TELEMETRY_ACCESS_CLIENT_SECRET (a Cloudflare Access service token) set it also reads the measurement receiver\'s export: billed cost per request, and the run time of every hook, the silent ones too; sessions whose transcript is not on this machine are downloaded from the receiver into .mainflow/local/transcripts/ first';
+    readonly summary: 'Read the Claude Code transcripts of the sessions that served a mainline, and their subagents\', into estimated list-price cost (per model, opening context, cache hit rate, hook injections) and candidates for where work went wrong (tool errors, rerun Bash commands, hook injections followed by no tool call, blocks, pauses over 5 minutes, failed completion checks); read-only. With the measurement upload\'s settings (the receiver\'s origin from TRANSCRIPT_UPLOAD_URL, in the environment or the env of the Claude Code user settings; the Cloudflare Access service token from TELEMETRY_ACCESS_CLIENT_ID and TELEMETRY_ACCESS_CLIENT_SECRET, else the macOS keychain items telemetry-access-client-id and telemetry-access-client-secret) found it also reads the measurement receiver\'s export: billed cost per request, and the run time of every hook, the silent ones too; sessions whose transcript is not on this machine are downloaded from the receiver into .mainflow/local/transcripts/ first';
     readonly args: 1;
     readonly needsHub: true;
   };
   readonly sync: {
     readonly usage: 'sync';
-    readonly summary: `Keep .mainflow/ in step with the hub on the sync server until stopped: pull its changes, send every local change. The server is https://mainflow-sync.carlos209310.space unless MAINFLOW_SYNC_URL, or url in .mainflow/local/sync.json, names another; its Cloudflare Access service token comes from MAINFLOW_SYNC_CLIENT_ID and MAINFLOW_SYNC_CLIENT_SECRET, or clientId and clientSecret in the same file. On connecting it downloads only the files that differ from the versions it last synced; with MAINFLOW_SYNC_ON_DEMAND=1, or onDemand: true in sync.json, it leaves the artifacts of done and dropped mainlines on the server until they are used (sync fetch). While it runs, or with a service token set, every mainflow write is applied here and put in the outbox, which it sends in order; a writing command waits up to 15 s for the server's answer`;
+    readonly summary: `Keep .mainflow/ in step with the hub on the sync server until stopped: pull its changes, send every local change. The server is https://mainflow-sync.carlos209310.space unless MAINFLOW_SYNC_URL, or url in .mainflow/local/sync.json, names another; its Cloudflare Access service token comes from MAINFLOW_SYNC_CLIENT_ID and MAINFLOW_SYNC_CLIENT_SECRET, or clientId and clientSecret in the same file. On connecting it downloads only the files that differ from the versions it last synced; unless MAINFLOW_SYNC_ON_DEMAND=0, or onDemand: false in sync.json, it leaves the artifacts of done and dropped mainlines on the server until they are used (sync fetch). In a new environment whose data directory has no config.yaml yet (after mainflow hub register), the hub's name comes from the registry and config.yaml and the other files are downloaded. While it runs, or with a service token set, every mainflow write is applied here and put in the outbox, which it sends in order; a writing command waits up to 15 s for the server's answer`;
     readonly args: 0;
     readonly needsHub: true;
   };
   readonly 'sync flush': {
     readonly usage: 'sync flush [--hook]';
-    readonly summary: 'Send every change to .mainflow/ now and print what did not reach the hub as written, such as a refused edit and where it was saved; --hook reads a PostToolUse payload from stdin and answers as the hook';
+    readonly summary: 'Send every change to .mainflow/ now and print what did not reach the hub as written, such as a refused edit and where it was saved; --hook reads a PostToolUse payload from stdin and answers as the hook, for the hub whose data directory holds the file the tool wrote, else the hub of the payload\'s cwd, and nothing outside a registered hub';
     readonly args: 0;
     readonly needsHub: true;
   };
   readonly 'sync fetch': {
     readonly usage: 'sync fetch [<path|m|m/t>] [--hook]';
-    readonly summary: 'Download files only on the sync server: with MAINFLOW_SYNC_ON_DEMAND, or onDemand in .mainflow/local/sync.json, the artifacts of done and dropped mainlines stay there until used. Give a file or directory (from here or from .mainflow/), or a mainline or task ID for all of its artifacts; mainflow sync must be running. Grep and Glob do not see a file that is not downloaded, so fetch the mainline before searching it. --hook reads a PreToolUse payload from stdin: a Read or Write of such a file downloads it first (Claude Code 2.1.285 answers an Edit of a missing file before any hook runs, so Read it or fetch it before editing); a Write, a failed download, or a mainflow sync that does not run or does not answer within 30 s answers deny with the reason';
+    readonly summary: 'Download files only on the sync server: unless MAINFLOW_SYNC_ON_DEMAND=0, or onDemand: false in .mainflow/local/sync.json, the artifacts of done and dropped mainlines stay there until used. Give a file or directory (from here or from .mainflow/), or a mainline or task ID for all of its artifacts; mainflow sync must be running. Grep and Glob do not see a file that is not downloaded, so fetch the mainline before searching it. --hook reads a PreToolUse payload from stdin and acts only when its file_path is in a registered hub\'s data directory, from whatever directory it runs: a Read or Write of such a file downloads it first (Claude Code 2.1.285 answers an Edit of a missing file before any hook runs, so Read it or fetch it before editing); a Write, a failed download, or a mainflow sync that does not run or does not answer within 30 s answers deny with the reason';
     readonly args: 0;
     readonly optionalArgs: 1;
     readonly needsHub: true;
@@ -395,6 +425,20 @@ export declare const COMMAND_SPECS: {
     readonly args: 0;
     readonly needsHub: true;
   };
+  readonly 'sync log': {
+    readonly usage: 'sync log [<path|m|m/t>] [--limit <n>] [--json]';
+    readonly summary: 'List the changes the sync server logged, newest first (50 unless --limit says otherwise): of a file or directory (from here or from .mainflow/), of a mainline or task by its ID, or of the whole hub. Each line is the seq, when the server made the change, who sent it (the first 8 characters of the Cloudflare Access Client ID of its environment, (here) for this one), the request, what it did, the path, and what the path held before and after (a hash\'s first 7 digits, dir, or -). The server keeps a change a year, 1 GiB of texts and 2 GiB of binary files a hub; it lists from what seq the hub can be put back';
+    readonly args: 0;
+    readonly optionalArgs: 1;
+    readonly needsHub: true;
+  };
+  readonly 'sync restore': {
+    readonly usage: 'sync restore [<path|m|m/t>] (--seq <n> | --at <time>) [--dry-run] [--json]';
+    readonly summary: 'Put the whole hub, or a file, directory, mainline or task, back to what it held after a seq of sync log (--seq), or at a time (--at, local time unless it names its offset, like 2026-10-19T15:30), as a new change on the sync server, which every sync client takes in; nothing of the log is undone, so it prints the command that undoes it. --dry-run lists what it would change. A path whose content the server no longer keeps, or a directory it could not remove, is left as it is and the command fails, after the rest is put back';
+    readonly args: 0;
+    readonly optionalArgs: 1;
+    readonly needsHub: true;
+  };
 };
 export type CommandName = keyof typeof COMMAND_SPECS;
 export declare const OPTIONS: {
@@ -522,6 +566,15 @@ export declare const OPTIONS: {
   readonly month: {
     readonly type: 'string';
   };
+  readonly limit: {
+    readonly type: 'string';
+  };
+  readonly seq: {
+    readonly type: 'string';
+  };
+  readonly at: {
+    readonly type: 'string';
+  };
   readonly all: {
     readonly type: 'boolean';
     readonly default: false;
@@ -626,8 +679,7 @@ export declare const RETRO_FORMATS: {
   };
 };
 /**
- * Conditions a blocked action's `until` takes and `wait` checks, one example each: a commit on a branch whose
- * message contains the text (git log runs at the hub root), an action that is done, a path relative to the hub root that exists (`..` reaches sibling repositories), a mainline of this hub or a registered hub that is done.
+ * Conditions a blocked action's `until` takes and `wait` checks, one example each: an action that is done, a path relative to the hub root that exists (`..` reaches sibling repositories), a mainline of this hub or a registered hub that is done.
  */
 export declare const UNTIL: readonly {
   kind: Until['kind'];
@@ -658,7 +710,10 @@ export declare const GRANTS: {
     readonly release: '單獨執行 `gh release create <tag> -R <owner/repo>`（可加 --title、--notes、--generate-notes、--draft、--prerelease、--verify-tag）';
   };
 };
-/** Where each kind of entry lives under the hub root. */
+/**
+ * Where each kind of entry lives in the hub's data directory, written as messages name a file of the hub: `.mainflow/`
+ * stands for the data directory, $MAINFLOW_HOME/<hub> (~/.mainflow/<hub>) on a machine that registered the hub.
+ */
 export declare const LAYOUT: {
   readonly config: '.mainflow/config.yaml';
   readonly mainline: '.mainflow/mainlines/m{NNN}-{slug}/mainline.md';

package/dist/facts.js

@@ -1,10 +1,40 @@
-import { A as TASK_REQUIRED_SECTIONS, D as SLUG, E as SESSION_STATUS, M as UNTIL_FORMS, N as WORK_STATUS, O as SURVEY_LINES, _ as LINK_RELS, a as DECISION_SECTIONS, b as MERGE_STATES, c as FINDING_SECTIONS, d as GROUP_SECTIONS, et as GRANT_ACTIONS, f as GROUP_STATUS, g as ISSUE_STATUS, h as ISSUE_SECTIONS, i as DECISION_BASES, j as TASK_SECTIONS, k as SURVEY_SECTION, l as FINDING_STATUS, m as ID_PATTERNS, n as CLOSED_STATUS, nt as GRANT_TARGET_FORMS, o as DECISION_STATUS, r as DECIDERS, s as DEFAULT_CATEGORIES, t as CHECKLIST_REF, tt as GRANT_FORMS, u as FORMAT_VERSION, v as MAINLINE_SECTIONS, w as SERVES_REF, x as PRIORITIES, y as MAINLINE_STATUS } from "./dist-zSabglPq.js";
+import { A as SURVEY_LINES, C as PRIORITIES, E as SERVES_REF, F as WORK_STATUS, M as TASK_REQUIRED_SECTIONS, N as TASK_SECTIONS, O as SESSION_STATUS, P as UNTIL_FORMS, S as MERGE_STATES, _ as ISSUE_STATUS, a as DECISION_SECTIONS, b as MAINLINE_SECTIONS, c as FINDING_SECTIONS, d as GROUP_SECTIONS, dt as GRANT_TARGET_FORMS, f as GROUP_STATUS, g as ISSUE_SECTIONS, h as ID_PATTERNS, i as DECISION_BASES, j as SURVEY_SECTION, k as SLUG, l as FINDING_STATUS, lt as GRANT_ACTIONS, n as CLOSED_STATUS, o as DECISION_STATUS, r as DECIDERS, s as DEFAULT_CATEGORIES, t as CHECKLIST_REF, u as FORMAT_VERSION, ut as GRANT_FORMS, v as LINK_RELS, x as MAINLINE_STATUS } 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";
 //#region src/facts.ts
 const COMMAND_SPECS = {
 	init: {
 		usage: "init <hub-name>",
-		summary: "Create .mainflow/ in the current directory",
+		summary: "Create the data directory of a new hub in $MAINFLOW_HOME/<hub-name> (~/.mainflow/<hub-name> by default) and register the hub on this machine with the current directory as its repository; nothing is written into the repository",
+		args: 1,
+		needsHub: false
+	},
+	"hub register": {
+		usage: "hub register <name> <path>",
+		summary: "Register on this machine the hub whose repository is <path>, so mainflow run in its primary repositories and their worktrees works on it; run it again after config.yaml changes to update it at once",
+		args: 2,
+		needsHub: false
+	},
+	"hub migrate-data": {
+		usage: "hub migrate-data <path> [--dry-run]",
+		summary: "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. The data is copied and compared before the registry switches to it; the original is then renamed to <path>/.mainflow.migrated, not deleted. A .git file of a git worktree is not copied and git is not run: the command prints the git worktree remove to run. Refused while mainflow sync or the hub's interface runs, or when $MAINFLOW_HOME/<name> is taken; --dry-run says what it would do",
+		args: 1,
+		needsHub: false
+	},
+	"hub list": {
+		usage: "hub list",
+		summary: "List the hubs registered on this machine with their primary and referenced repositories",
+		args: 0,
+		needsHub: false
+	},
+	"hub which": {
+		usage: "hub which [--json]",
+		summary: "Print the name, repository root and data directory of the hub the current directory belongs to, as hub list finds it. --json prints one object {\"name\",\"root\",\"data\"}. Outside any registered hub it prints nothing to stdout, one line to stderr, and exits 1. Writes nothing",
+		args: 0,
+		needsHub: false
+	},
+	"hub unregister": {
+		usage: "hub unregister <name>",
+		summary: "Remove a hub from this machine's registry; its files stay",
 		args: 1,
 		needsHub: false
 	},
@@ -16,13 +46,13 @@ const COMMAND_SPECS = {
 	},
 	check: {
 		usage: "check",
-		summary: "Validate every file under .mainflow/",
+		summary: "Validate every file in the hub's data directory",
 		args: 0,
 		needsHub: true
 	},
 	migrate: {
 		usage: "migrate [--dry-run]",
-		summary: "Convert the hub to the data format this CLI reads; --dry-run lists the changes without writing",
+		summary: "Convert the hub to the data format this CLI reads, on the sync server when it keeps the hub; --dry-run lists the changes without writing",
 		args: 0,
 		needsHub: true
 	},
@@ -34,7 +64,7 @@ const COMMAND_SPECS = {
 	},
 	"repo add": {
 		usage: "repo add <name> <path>",
-		summary: "Register a repository that tasks can point at (path relative to the hub root)",
+		summary: "Register a repository that tasks can point at as a primary repository of the hub (path relative to the hub root)",
 		args: 2,
 		needsHub: true
 	},
@@ -356,25 +386,25 @@ const COMMAND_SPECS = {
 	},
 	retro: {
 		usage: "retro <m> [--json]",
-		summary: "Read the Claude Code transcripts of the sessions that served a mainline, and their subagents', into estimated list-price cost (per model, opening context, cache hit rate, hook injections) and candidates for where work went wrong (tool errors, rerun Bash commands, hook injections followed by no tool call, blocks, pauses over 5 minutes, failed completion checks); read-only. With MAINFLOW_TELEMETRY_URL, MAINFLOW_TELEMETRY_ACCESS_CLIENT_ID and MAINFLOW_TELEMETRY_ACCESS_CLIENT_SECRET (a Cloudflare Access service token) set it also reads the measurement receiver's export: billed cost per request, and the run time of every hook, the silent ones too; sessions whose transcript is not on this machine are downloaded from the receiver into .mainflow/local/transcripts/ first",
+		summary: "Read the Claude Code transcripts of the sessions that served a mainline, and their subagents', into estimated list-price cost (per model, opening context, cache hit rate, hook injections) and candidates for where work went wrong (tool errors, rerun Bash commands, hook injections followed by no tool call, blocks, pauses over 5 minutes, failed completion checks); read-only. With the measurement upload's settings (the receiver's origin from TRANSCRIPT_UPLOAD_URL, in the environment or the env of the Claude Code user settings; the Cloudflare Access service token from TELEMETRY_ACCESS_CLIENT_ID and TELEMETRY_ACCESS_CLIENT_SECRET, else the macOS keychain items telemetry-access-client-id and telemetry-access-client-secret) found it also reads the measurement receiver's export: billed cost per request, and the run time of every hook, the silent ones too; sessions whose transcript is not on this machine are downloaded from the receiver into .mainflow/local/transcripts/ first",
 		args: 1,
 		needsHub: true
 	},
 	sync: {
 		usage: "sync",
-		summary: `Keep .mainflow/ in step with the hub on the sync server until stopped: pull its changes, send every local change. The server is https://mainflow-sync.carlos209310.space unless MAINFLOW_SYNC_URL, or url in .mainflow/local/sync.json, names another; its Cloudflare Access service token comes from MAINFLOW_SYNC_CLIENT_ID and MAINFLOW_SYNC_CLIENT_SECRET, or clientId and clientSecret in the same file. On connecting it downloads only the files that differ from the versions it last synced; with MAINFLOW_SYNC_ON_DEMAND=1, or onDemand: true in sync.json, it leaves the artifacts of done and dropped mainlines on the server until they are used (sync fetch). While it runs, or with a service token set, every mainflow write is applied here and put in the outbox, which it sends in order; a writing command waits up to 15 s for the server's answer`,
+		summary: `Keep .mainflow/ in step with the hub on the sync server until stopped: pull its changes, send every local change. The server is https://mainflow-sync.carlos209310.space unless MAINFLOW_SYNC_URL, or url in .mainflow/local/sync.json, names another; its Cloudflare Access service token comes from MAINFLOW_SYNC_CLIENT_ID and MAINFLOW_SYNC_CLIENT_SECRET, or clientId and clientSecret in the same file. On connecting it downloads only the files that differ from the versions it last synced; unless MAINFLOW_SYNC_ON_DEMAND=0, or onDemand: false in sync.json, it leaves the artifacts of done and dropped mainlines on the server until they are used (sync fetch). In a new environment whose data directory has no config.yaml yet (after mainflow hub register), the hub's name comes from the registry and config.yaml and the other files are downloaded. While it runs, or with a service token set, every mainflow write is applied here and put in the outbox, which it sends in order; a writing command waits up to 15 s for the server's answer`,
 		args: 0,
 		needsHub: true
 	},
 	"sync flush": {
 		usage: "sync flush [--hook]",
-		summary: "Send every change to .mainflow/ now and print what did not reach the hub as written, such as a refused edit and where it was saved; --hook reads a PostToolUse payload from stdin and answers as the hook",
+		summary: "Send every change to .mainflow/ now and print what did not reach the hub as written, such as a refused edit and where it was saved; --hook reads a PostToolUse payload from stdin and answers as the hook, for the hub whose data directory holds the file the tool wrote, else the hub of the payload's cwd, and nothing outside a registered hub",
 		args: 0,
 		needsHub: true
 	},
 	"sync fetch": {
 		usage: "sync fetch [<path|m|m/t>] [--hook]",
-		summary: "Download files only on the sync server: with MAINFLOW_SYNC_ON_DEMAND, or onDemand in .mainflow/local/sync.json, the artifacts of done and dropped mainlines stay there until used. Give a file or directory (from here or from .mainflow/), or a mainline or task ID for all of its artifacts; mainflow sync must be running. Grep and Glob do not see a file that is not downloaded, so fetch the mainline before searching it. --hook reads a PreToolUse payload from stdin: a Read or Write of such a file downloads it first (Claude Code 2.1.285 answers an Edit of a missing file before any hook runs, so Read it or fetch it before editing); a Write, a failed download, or a mainflow sync that does not run or does not answer within 30 s answers deny with the reason",
+		summary: "Download files only on the sync server: unless MAINFLOW_SYNC_ON_DEMAND=0, or onDemand: false in .mainflow/local/sync.json, the artifacts of done and dropped mainlines stay there until used. Give a file or directory (from here or from .mainflow/), or a mainline or task ID for all of its artifacts; mainflow sync must be running. Grep and Glob do not see a file that is not downloaded, so fetch the mainline before searching it. --hook reads a PreToolUse payload from stdin and acts only when its file_path is in a registered hub's data directory, from whatever directory it runs: a Read or Write of such a file downloads it first (Claude Code 2.1.285 answers an Edit of a missing file before any hook runs, so Read it or fetch it before editing); a Write, a failed download, or a mainflow sync that does not run or does not answer within 30 s answers deny with the reason",
 		args: 0,
 		optionalArgs: 1,
 		needsHub: true
@@ -384,6 +414,20 @@ const COMMAND_SPECS = {
 		summary: "Say whether mainflow sync runs for this hub, whether it is online and caught up with the server, and how many writes wait to be sent",
 		args: 0,
 		needsHub: true
+	},
+	"sync log": {
+		usage: "sync log [<path|m|m/t>] [--limit <n>] [--json]",
+		summary: "List the changes the sync server logged, newest first (50 unless --limit says otherwise): of a file or directory (from here or from .mainflow/), of a mainline or task by its ID, or of the whole hub. Each line is the seq, when the server made the change, who sent it (the first 8 characters of the Cloudflare Access Client ID of its environment, (here) for this one), the request, what it did, the path, and what the path held before and after (a hash's first 7 digits, dir, or -). The server keeps a change a year, 1 GiB of texts and 2 GiB of binary files a hub; it lists from what seq the hub can be put back",
+		args: 0,
+		optionalArgs: 1,
+		needsHub: true
+	},
+	"sync restore": {
+		usage: "sync restore [<path|m|m/t>] (--seq <n> | --at <time>) [--dry-run] [--json]",
+		summary: "Put the whole hub, or a file, directory, mainline or task, back to what it held after a seq of sync log (--seq), or at a time (--at, local time unless it names its offset, like 2026-10-19T15:30), as a new change on the sync server, which every sync client takes in; nothing of the log is undone, so it prints the command that undoes it. --dry-run lists what it would change. A path whose content the server no longer keeps, or a directory it could not remove, is left as it is and the command fails, after the rest is put back",
+		args: 0,
+		optionalArgs: 1,
+		needsHub: true
 	}
 };
 const OPTIONS = {
@@ -431,6 +475,9 @@ const OPTIONS = {
 	result: { type: "string" },
 	ref: { type: "string" },
 	month: { type: "string" },
+	limit: { type: "string" },
+	seq: { type: "string" },
+	at: { type: "string" },
 	all: {
 		type: "boolean",
 		default: false
@@ -547,8 +594,7 @@ const RETRO_FORMATS = {
 	}
 };
 /**
-* Conditions a blocked action's `until` takes and `wait` checks, one example each: a commit on a branch whose
-* message contains the text (git log runs at the hub root), an action that is done, a path relative to the hub root that exists (`..` reaches sibling repositories), a mainline of this hub or a registered hub that is done.
+* Conditions a blocked action's `until` takes and `wait` checks, one example each: an action that is done, a path relative to the hub root that exists (`..` reaches sibling repositories), a mainline of this hub or a registered hub that is done.
 */
 const UNTIL = UNTIL_FORMS;
 /** Relation types a document's links take; readers derive the reverse direction. */
@@ -567,7 +613,10 @@ const GRANTS = {
 	enforcedByHook: ["publish", "release"],
 	forms: GRANT_FORMS
 };
-/** Where each kind of entry lives under the hub root. */
+/**
+* Where each kind of entry lives in the hub's data directory, written as messages name a file of the hub: `.mainflow/`
+* stands for the data directory, $MAINFLOW_HOME/<hub> (~/.mainflow/<hub>) on a machine that registered the hub.
+*/
 const LAYOUT = {
 	config: ".mainflow/config.yaml",
 	mainline: ".mainflow/mainlines/m{NNN}-{slug}/mainline.md",
@@ -672,7 +721,7 @@ const FIELDS = {
 		field("order", false, "在主脈絡內的順序，小的在前"),
 		field("dependsOn", false, "開始前必須先完成的任務"),
 		field("repo", false, "主要動到的倉庫，名稱需在 config.yaml 登記"),
-		field("touches", false, "預計會改到的路徑或 glob 清單，相對於 repo 的根目錄；兩條進行中的主脈絡各有未結束的任務在同一個 repo 碰到重疊的路徑、彼此又沒有 depends-on 時，check 列出警告；有 touches 卻沒填 repo 時路徑不會被比對，check 也列警告"),
+		field("touches", false, "預計會改到的路徑或 glob 清單，相對於 repo 的根目錄；只供開場簡報列出兩條進行中主脈絡的未結束任務在同一個 repo 重疊的路徑，check 不警告，重疊由提交時兩邊的會話協調，不必記 depends-on；有 touches 卻沒填 repo 時路徑不會被比對，check 也列警告"),
 		field("startedAt", false, "第一次轉為 doing 時由 CLI 寫入"),
 		field("checklist", true, "checklist 項目清單，每項的欄位見 checklistItem"),
 		field("blockedBy", false, "卡住時的原因、等待對象與繼續的訊號，blocked 時必填；等待對象整串是參照時（例如 m031/t002）會檢查它存在"),

package/dist/grant-commands.d.ts

@@ -1,4 +1,4 @@
-import "./index-Dk4fCI7q.js";
+import "./index-BqPQp6TF.js";
 //#region ../schema/dist/grants.d.ts
 /** An operation about to run, resolved to what a grant is written against. */
 type GrantRequest = {

package/dist/grant-commands.js

@@ -1,4 +1,4 @@
-import { tt as GRANT_FORMS } from "./dist-zSabglPq.js";
+import { ut as GRANT_FORMS } from "./dist-D5rZ0MQH.js";
 import { closeSync, constants, fstatSync, openSync, readFileSync, realpathSync } from "node:fs";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import { spawnSync } from "node:child_process";