mainflow 0.35.0 → 0.37.0

package/dist/cli.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
-import { G as parseRef, K as parseUntil, N as UNTIL_FORMS, et as stampMs, n as CLOSED_STATUS, q as refExample } from "./dist-BdvWGTsb.js";
-import { B as applyOperation, C as readSession, H as HubError, Q as nodeStorage, S as loadSessions, V as checkHubName, W as loadHub, X as nowMinute, _ as initHub, _t as DATA_DIR, b as sessionBriefing, d as retroReport, dt as TASK_FILE, f as retroReportFromReceiver, ft as requireSlug, m as RETRY_RULES, mt as findHubRoot, nt as MAX_FILE_BYTES, p as receiverFromEnv, u as migrateHub, ut as MAINLINE_FILE, v as untilState, vt as WriteError, y as duplicateClaimLines } from "./host-bnHYIwuY.js";
+import { G as parseRef, K as parseUntil, N as UNTIL_FORMS, et as stampMs, n as CLOSED_STATUS, q as refExample } from "./dist-ud09dzZo.js";
+import { $ as nowMinute, B as applyOperation, C as readSession, Ct as WriteError, H as HubError, Q as unavailableHubs, S as loadSessions, St as DATA_DIR, V as checkHubName, W as loadHub, Y as memberOfGroup, Z as remoteMembers, _ as initHub, _t as requireSlug, at as MAX_FILE_BYTES, b as sessionBriefing, d as retroReport, f as retroReportFromReceiver, gt as TASK_FILE, ht as MAINLINE_FILE, m as RETRY_RULES, p as receiverFromEnv, tt as nodeStorage, u as migrateHub, v as untilState, y as duplicateClaimLines, yt as findHubRoot } from "./host-lY8ytTbw.js";
 import { t as listProgress } from "./progress-1BfPg2zN.js";
-import { C as ServerError, D as syncSettings, E as hubName, O as SETTINGS_FILE, S as ServerApi, T as earlierToken, _ as readDaemon, a as remoteMode, b as readRemote, c as planAnnounce, d as toolCallOf, f as startDaemon, g as probeDaemon, h as callDaemon, i as queuedCount, j as syncPaths, l as planFetch, m as DaemonUnavailable, n as hubWriter, o as fetchDenial, p as DaemonRunning, r as writtenLines, s as hookAnswer, t as CONFIRM_MS, u as planFlush, v as silentHint, w as ENV, x as oversizedFiles } from "./operation-DVcJgKM9.js";
+import { C as ServerError, D as syncSettings, E as hubName, O as SETTINGS_FILE, S as ServerApi, T as earlierToken, _ as readDaemon, a as remoteMode, b as readRemote, c as planAnnounce, d as toolCallOf, f as startDaemon, g as probeDaemon, h as callDaemon, i as queuedCount, j as syncPaths, l as planFetch, m as DaemonUnavailable, n as hubWriter, o as fetchDenial, p as DaemonRunning, r as writtenLines, s as hookAnswer, t as CONFIRM_MS, u as planFlush, v as silentHint, w as ENV, x as oversizedFiles } from "./operation-BZ7CHB6J.js";
 import { COMMAND_SPECS, OPTIONS } from "./facts.js";
 import { hookFallback, parsePayload, runHook } from "./hooks.js";
-import { f as CLI_VERSION, i as launchUi, l as startUiInBackground, r as exitCodeFor, u as watchHubGone } from "./launch-D80CYPcm.js";
+import { f as CLI_VERSION, i as launchUi, l as startUiInBackground, r as exitCodeFor, u as watchHubGone } from "./launch-3HLHjQF0.js";
 import { randomBytes } from "node:crypto";
 import { existsSync, readFileSync, readdirSync, realpathSync, rmSync, statSync } from "node:fs";
 import { basename, isAbsolute, join, relative, resolve, sep } from "node:path";
@@ -524,6 +524,18 @@ function retroText(report) {
 //#endregion
 //#region src/cli.ts
 const write = (spec) => spec;
+/**
+* A group of another hub (`other-hub:w001`) must exist there when that hub is on this machine; the operation only
+* checks that the hub is registered, since a hub kept on another machine cannot be read from here.
+*/
+const checkGroupOption = ({ root, opts }) => {
+	const ref = opts.group ? parseRef(opts.group) : null;
+	if (ref?.kind !== "group" || ref.hub === void 0) return;
+	const hub = loadHub(root);
+	if (ref.hub === hub.config.hub) return;
+	const remote = hub.remotes.find((r) => r.name === ref.hub);
+	if (remote?.hub && !remote.hub.groups.some((g) => g.id === ref.group)) throw new WriteError(`group ${ref.group} not found in hub "${ref.hub}"`);
+};
 /** Where a document an operation created or changed is, as the commands print it: .mainflow/... */
 const inData = (...parts) => join(DATA_DIR, ...parts);
 const WRITES = {
@@ -651,6 +663,7 @@ const WRITES = {
 		}
 	}),
 	"new mainline": write({
+		check: checkGroupOption,
 		op: "mainline.new",
 		input: ({ args, opts }) => ({
 			slug: args[0],
@@ -687,6 +700,7 @@ const WRITES = {
 		print: (_, { ref, file }) => done(`created ${ref} ${inData(file)}`)
 	}),
 	"new issue": write({
+		check: checkGroupOption,
 		op: "issue.new",
 		input: ({ args, opts }) => ({
 			slug: args[0],
@@ -734,6 +748,7 @@ const WRITES = {
 		print: (_, { id, file }) => done(`created ${id} ${inData(file)}`)
 	}),
 	"mainline set": write({
+		check: checkGroupOption,
 		op: "mainline.set",
 		input: ({ args, opts }) => ({
 			id: args[0],
@@ -891,6 +906,7 @@ const WRITES = {
 		print: (_, i) => done(`closed ${i.id}`)
 	}),
 	"issue set": write({
+		check: checkGroupOption,
 		op: "issue.set",
 		input: ({ args, opts }) => ({
 			id: args[0],
@@ -1353,14 +1369,23 @@ function printStatus(hub, all) {
 */
 function printGroups(hub, all) {
 	const rank = (p) => (p ?? "P2").slice(1);
+	const remoteByGroup = remoteMembers(hub.remotes, hub.config.hub);
 	const shown = hub.groups.filter((g) => all || g.status !== "done").sort((a, b) => rank(a.priority).localeCompare(rank(b.priority)) || a.id.localeCompare(b.id));
 	for (const g of shown) {
 		console.log(`  ${g.id}  ${g.status.padEnd(4)}  ${g.priority ?? "P2"}  ${g.title}${g.trigger ? `  （時機：${g.trigger}）` : ""}`);
-		const mainlines = hub.mainlines.filter((m) => m.group === g.id && (all || !m.archivedAt && !CLOSED_STATUS.mainline.includes(m.status)));
-		const issues = hub.issues.filter((i) => i.group === g.id && (all || !i.archivedAt && i.status !== "closed"));
+		const mainlines = hub.mainlines.filter((m) => memberOfGroup(m.group, g.id, hub.config.hub) && (all || !m.archivedAt && !CLOSED_STATUS.mainline.includes(m.status)));
+		const issues = hub.issues.filter((i) => memberOfGroup(i.group, g.id, hub.config.hub) && (all || !i.archivedAt && i.status !== "closed"));
 		for (const m of [...mainlines.filter((m) => m.role === "plan"), ...mainlines.filter((m) => m.role !== "plan")]) console.log(`      ${m.id}  ${(m.role ?? "impl").padEnd(4)}  ${m.status.padEnd(8)}  ${m.title}`);
 		for (const i of issues) console.log(`      ${i.id}  issue  ${i.status.padEnd(8)}  ${i.title}`);
+		const remote = (remoteByGroup.get(g.id) ?? []).filter((m) => all || !m.archived && m.open);
+		for (const m of [
+			...remote.filter((m) => m.role === "plan"),
+			...remote.filter((m) => m.kind === "mainline" && m.role !== "plan"),
+			...remote.filter((m) => m.kind === "issue")
+		]) console.log(`      ${m.ref}  ${(m.kind === "issue" ? "issue" : m.role).padEnd(4)}  ${m.status.padEnd(8)}  ${m.title}`);
 	}
+	const missing = unavailableHubs(hub.remotes);
+	if (missing.length) console.log(`  note: hub ${missing.join(", ")} not loaded, so their members are not listed`);
 	return done(`${shown.length} groups`);
 }
 function printProblems(problems, mark = "✗") {

package/dist/{dist-BdvWGTsb.js → dist-ud09dzZo.js}

@@ -699,8 +699,11 @@ const documentShape = {
 	links: z.array(linkSchema).optional()
 };
 const priority = z.enum(PRIORITIES).optional();
-/** The hub-level group a mainline or an issue belongs to, at most one; work that goes together, apart from what depends on what */
-const group = id("group").optional();
+/**
+* The hub-level group a mainline or an issue belongs to, at most one; work that goes together, apart from what depends on what.
+* It is a group of this hub (`w001`) or of another one (`other-hub:w001`), so work in one hub can join a group of another.
+*/
+const group = z.string().refine((s) => parseRef(s)?.kind === "group", `expected a group like ${refExample("group")}, or one of another hub's like other-hub:${refExample("group")}`).optional();
 const evidenceRequired = (item, ctx) => {
 	if (item.done && !item.evidence) ctx.addIssue({
 		code: "custom",
@@ -889,6 +892,11 @@ const UNTIL_FORMS = [
 		kind: "file",
 		format: "file:{relative path}",
 		example: "file:packages/cli/dist/cli.js"
+	},
+	{
+		kind: "mainline-done",
+		format: "mainline-done:m{NNN} or mainline-done:{hub}:m{NNN}",
+		example: "mainline-done:other-hub:m031"
 	}
 ];
 const UNTIL_EXAMPLES = UNTIL_FORMS.map((f) => f.format).join(", ");
@@ -922,6 +930,10 @@ function parseUntil(input) {
 			kind,
 			path: argument
 		} : null;
+		case "mainline-done": return parseRef(argument)?.kind === "mainline" ? {
+			kind,
+			mainline: argument
+		} : null;
 		default: return null;
 	}
 }

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-DgYB5u1f.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-B32s8PHu.js";
 //#region src/facts.d.ts
 export interface CommandSpec {
   usage: string;
@@ -125,7 +125,7 @@ export declare const COMMAND_SPECS: {
   };
   readonly 'new mainline': {
     readonly usage: 'new mainline <slug> --title <title> [--group <w>] [--role plan|impl] [--priority P0|P1|P2|P3]';
-    readonly summary: 'Create mainline.md with the next id and the section template; write the rest in the file. --group puts it in an existing group; --role plan makes it the mainline that splits the work, coordinates it and makes the final check (without --role it is an impl mainline)';
+    readonly summary: 'Create mainline.md with the next id and the section template; write the rest in the file. --group puts it in an existing group, or in one of another registered hub as {hub}:w001; --role plan makes it the mainline that splits the work, coordinates it and makes the final check (without --role it is an impl mainline)';
     readonly args: 1;
     readonly needsHub: true;
   };
@@ -143,7 +143,7 @@ export declare const COMMAND_SPECS: {
   };
   readonly 'new issue': {
     readonly usage: 'new issue <slug> --title <title> [--origin <ref>] [--labels a,b] [--group <w>] [--priority P0|P1|P2|P3]';
-    readonly summary: 'Create an issue file for a follow-up that must outlive its mainline; --group puts it with the work it is taken up with';
+    readonly summary: 'Create an issue file for a follow-up that must outlive its mainline; --group puts it with the work it is taken up with, in this hub or another registered one ({hub}:w001)';
     readonly args: 1;
     readonly needsHub: true;
   };
@@ -167,13 +167,13 @@ export declare const COMMAND_SPECS: {
   };
   readonly 'group list': {
     readonly usage: 'group list [--all]';
-    readonly summary: 'List open groups by priority with their trigger and members, plan mainlines first (--all includes done groups)';
+    readonly summary: 'List open groups by priority with their trigger and members, plan mainlines first; members in other hubs read {hub}:{id}, and a registered hub that is not loaded is noted (--all includes done groups)';
     readonly args: 0;
     readonly needsHub: true;
   };
   readonly 'mainline set': {
     readonly usage: 'mainline set <m> [--status <status>] [--group <w|none>] [--role plan|impl] [--priority P0|P1|P2|P3]';
-    readonly summary: 'Change status, group, role or priority; done needs every criterion met and no proposed decision. A planning mainline becomes active by itself when work on it starts, so use --status for paused, done and dropped. --group none leaves the group';
+    readonly summary: 'Change status, group, role or priority; done needs every criterion met and no proposed decision. A planning mainline becomes active by itself when work on it starts, so use --status for paused, done and dropped. --group none leaves the group; {hub}:w001 joins a group of another registered hub';
     readonly args: 1;
     readonly needsHub: true;
   };
@@ -293,7 +293,7 @@ export declare const COMMAND_SPECS: {
   };
   readonly 'issue set': {
     readonly usage: 'issue set <i> [--group <w|none>] [--priority P0|P1|P2|P3]';
-    readonly summary: 'Put an issue in a group, or take it out with --group none, and change its priority';
+    readonly summary: 'Put an issue in a group (of this hub, or {hub}:w001 of another registered one), or take it out with --group none, and change its priority';
     readonly args: 1;
     readonly needsHub: true;
   };
@@ -620,7 +620,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).
+ * 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.
  */
 export declare const UNTIL: readonly {
   kind: Until['kind'];

package/dist/facts.js

@@ -1,4 +1,4 @@
-import { A as SURVEY_SECTION, D as SESSION_STATUS, M as TASK_SECTIONS, N as UNTIL_FORMS, O as SLUG, P as WORK_STATUS, S as PRIORITIES, T as SERVES_REF, _ as LINK_RELS, a as DECISION_SECTIONS, b as MAINLINE_STATUS, c as DEFAULT_ROLE, d as FORMAT_VERSION, f as GROUP_SECTIONS, g as ISSUE_STATUS, h as ISSUE_SECTIONS, i as DECISION_BASES, j as TASK_REQUIRED_SECTIONS, k as SURVEY_LINES, l as FINDING_SECTIONS, m as ID_PATTERNS, n as CLOSED_STATUS, nt as GRANT_FORMS, o as DECISION_STATUS, p as GROUP_STATUS, r as DECIDERS, rt as GRANT_TARGET_FORMS, s as DEFAULT_CATEGORIES, t as CHECKLIST_REF, tt as GRANT_ACTIONS, u as FINDING_STATUS, v as MAINLINE_ROLES, x as MERGE_STATES, y as MAINLINE_SECTIONS } from "./dist-BdvWGTsb.js";
+import { A as SURVEY_SECTION, D as SESSION_STATUS, M as TASK_SECTIONS, N as UNTIL_FORMS, O as SLUG, P as WORK_STATUS, S as PRIORITIES, T as SERVES_REF, _ as LINK_RELS, a as DECISION_SECTIONS, b as MAINLINE_STATUS, c as DEFAULT_ROLE, d as FORMAT_VERSION, f as GROUP_SECTIONS, g as ISSUE_STATUS, h as ISSUE_SECTIONS, i as DECISION_BASES, j as TASK_REQUIRED_SECTIONS, k as SURVEY_LINES, l as FINDING_SECTIONS, m as ID_PATTERNS, n as CLOSED_STATUS, nt as GRANT_FORMS, o as DECISION_STATUS, p as GROUP_STATUS, r as DECIDERS, rt as GRANT_TARGET_FORMS, s as DEFAULT_CATEGORIES, t as CHECKLIST_REF, tt as GRANT_ACTIONS, u as FINDING_STATUS, v as MAINLINE_ROLES, x as MERGE_STATES, y as MAINLINE_SECTIONS } from "./dist-ud09dzZo.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 = {
@@ -115,7 +115,7 @@ const COMMAND_SPECS = {
 	},
 	"new mainline": {
 		usage: "new mainline <slug> --title <title> [--group <w>] [--role plan|impl] [--priority P0|P1|P2|P3]",
-		summary: "Create mainline.md with the next id and the section template; write the rest in the file. --group puts it in an existing group; --role plan makes it the mainline that splits the work, coordinates it and makes the final check (without --role it is an impl mainline)",
+		summary: "Create mainline.md with the next id and the section template; write the rest in the file. --group puts it in an existing group, or in one of another registered hub as {hub}:w001; --role plan makes it the mainline that splits the work, coordinates it and makes the final check (without --role it is an impl mainline)",
 		args: 1,
 		needsHub: true
 	},
@@ -133,7 +133,7 @@ const COMMAND_SPECS = {
 	},
 	"new issue": {
 		usage: "new issue <slug> --title <title> [--origin <ref>] [--labels a,b] [--group <w>] [--priority P0|P1|P2|P3]",
-		summary: "Create an issue file for a follow-up that must outlive its mainline; --group puts it with the work it is taken up with",
+		summary: "Create an issue file for a follow-up that must outlive its mainline; --group puts it with the work it is taken up with, in this hub or another registered one ({hub}:w001)",
 		args: 1,
 		needsHub: true
 	},
@@ -157,13 +157,13 @@ const COMMAND_SPECS = {
 	},
 	"group list": {
 		usage: "group list [--all]",
-		summary: "List open groups by priority with their trigger and members, plan mainlines first (--all includes done groups)",
+		summary: "List open groups by priority with their trigger and members, plan mainlines first; members in other hubs read {hub}:{id}, and a registered hub that is not loaded is noted (--all includes done groups)",
 		args: 0,
 		needsHub: true
 	},
 	"mainline set": {
 		usage: "mainline set <m> [--status <status>] [--group <w|none>] [--role plan|impl] [--priority P0|P1|P2|P3]",
-		summary: "Change status, group, role or priority; done needs every criterion met and no proposed decision. A planning mainline becomes active by itself when work on it starts, so use --status for paused, done and dropped. --group none leaves the group",
+		summary: "Change status, group, role or priority; done needs every criterion met and no proposed decision. A planning mainline becomes active by itself when work on it starts, so use --status for paused, done and dropped. --group none leaves the group; {hub}:w001 joins a group of another registered hub",
 		args: 1,
 		needsHub: true
 	},
@@ -283,7 +283,7 @@ const COMMAND_SPECS = {
 	},
 	"issue set": {
 		usage: "issue set <i> [--group <w|none>] [--priority P0|P1|P2|P3]",
-		summary: "Put an issue in a group, or take it out with --group none, and change its priority",
+		summary: "Put an issue in a group (of this hub, or {hub}:w001 of another registered one), or take it out with --group none, and change its priority",
 		args: 1,
 		needsHub: true
 	},
@@ -538,7 +538,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).
+* 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.
 */
 const UNTIL = UNTIL_FORMS;
 /** Relation types a document's links take; readers derive the reverse direction. */
@@ -654,7 +654,7 @@ const LIST_ITEM = [
 const FIELDS = {
 	mainline: [
 		...shared(...EVERY),
-		field("group", false, "所屬的組 w{NNN}，一條主脈絡最多一組；組和依賴無關"),
+		field("group", false, "所屬的組 w{NNN}，或其他 hub 的組 {hub}:w{NNN}，一條主脈絡最多一組；組和依賴無關"),
 		field("role", false, "plan 是拆分顆粒、整合調度與最終確認的規劃型，impl 是執行的實作型；沒填視為 impl"),
 		field("due", false, "預計完成的日期"),
 		field("archivedAt", false, "封存的日期，和狀態分開"),
@@ -690,7 +690,7 @@ const FIELDS = {
 	],
 	issue: [
 		...shared(...EVERY),
-		field("group", false, "所屬的組 w{NNN}，一筆待辦最多一組；同組的待辦在同一個時機一起做"),
+		field("group", false, "所屬的組 w{NNN}，或其他 hub 的組 {hub}:w{NNN}，一筆待辦最多一組；同組的待辦在同一個時機一起做"),
 		field("order", false, "待辦之間的順序"),
 		field("due", false, "預計完成的日期"),
 		field("plannedIn", false, "排進的任務，planned 時必填"),

package/dist/grant-commands.d.ts

@@ -1,4 +1,4 @@
-import "./index-DgYB5u1f.js";
+import "./index-B32s8PHu.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 { nt as GRANT_FORMS } from "./dist-BdvWGTsb.js";
+import { nt as GRANT_FORMS } from "./dist-ud09dzZo.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";

package/dist/hooks.d.ts

@@ -1,4 +1,4 @@
-import { _ as Task, a as Decision, c as Group, d as Mainline, f as OpsEntry, h as Session, i as ChecklistItem, n as ActionBlock, s as Finding, t as Action, u as Issue } from "./index-DgYB5u1f.js";
+import { _ as Task, a as Decision, c as Group, d as Mainline, f as OpsEntry, h as Session, i as ChecklistItem, n as ActionBlock, s as Finding, t as Action, u as Issue } from "./index-B32s8PHu.js";
 import { z } from "zod";
 //#region ../core/dist/ids/allocators.d.ts
 /** The letters ids start with. */

package/dist/hooks.js

@@ -1,6 +1,6 @@
-import { F as configSchema, it as describeRequest } from "./dist-BdvWGTsb.js";
-import { A as mayDecorate, C as readSession, D as decorateReply, E as matchGrants, H as HubError, O as endsWithMarker, S as loadSessions, T as grantScope, W as loadHub, Z as readYaml, _t as DATA_DIR, b as sessionBriefing, ht as worktreesOf, i as hostName, k as headerLine, mt as findHubRoot, pt as currentBranch, x as turnReminder } from "./host-bnHYIwuY.js";
-import { n as hubWriter, r as writtenLines } from "./operation-DVcJgKM9.js";
+import { F as configSchema, it as describeRequest } from "./dist-ud09dzZo.js";
+import { A as mayDecorate, C as readSession, D as decorateReply, E as matchGrants, H as HubError, O as endsWithMarker, S as loadSessions, St as DATA_DIR, T as grantScope, W as loadHub, b as sessionBriefing, bt as worktreesOf, et as readYaml, i as hostName, k as headerLine, mt as hubFormatVersion, pt as formatMismatch, tt as nodeStorage, vt as currentBranch, x as turnReminder, yt as findHubRoot } from "./host-lY8ytTbw.js";
+import { n as hubWriter, r as writtenLines } from "./operation-BZ7CHB6J.js";
 import { resolveFixed, scanCommand, scopedCwd } from "./grant-commands.js";
 import { appendFileSync, existsSync, readFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
@@ -425,6 +425,18 @@ const PROJECT_HUB_EVENTS = /* @__PURE__ */ new Set(["pre-tool-use"]);
 function hubRootFor(event, ctx) {
 	return (PROJECT_HUB_EVENTS.has(event) && ctx.projectDir && isAbsolute(ctx.projectDir) ? findHubRoot(ctx.projectDir) : null) ?? findHubRoot(typeof ctx.payload.cwd === "string" ? ctx.payload.cwd : process.cwd());
 }
+/** Events whose output reaches the model before it works, so they carry the notice that the hub's data format does not match this CLI. */
+const FORMAT_NOTICE_EVENTS = /* @__PURE__ */ new Set(["session-start", "user-prompt-submit"]);
+/** What the model is told when the hub's data format is not the one this CLI reads and writes; null when it is. */
+function formatNotice(root, cli) {
+	const found = hubFormatVersion(nodeStorage(root));
+	const reason = found === null ? null : formatMismatch(found);
+	if (found === null || reason === null) return null;
+	return {
+		text: found < 3 ? `[mainflow] 這個 hub 的資料格式是 ${found}，這版 mainflow 讀寫的是 3，要先跑 ${cli} migrate 才能讀寫紀錄。` : `[mainflow] 這個 hub 的資料格式是 ${found}，比這版 mainflow 讀寫的 3 新，要先在這個 hub 安裝對應版本的 mainflow 才能讀寫紀錄。`,
+		reason
+	};
+}
 /** What an event prints when it cannot run its handler; null for the events that stay silent. */
 function hookFallback(platform, event, ctx, failure) {
 	const fallback = HOOK_FALLBACKS[platform]?.[event];
@@ -461,6 +473,11 @@ async function runHook(platform, event, ctx) {
 			for (const line of writtenLines(written)) if (line.startsWith("!")) warn(`mainflow hook ${platform} ${event}: ${line.slice(2)}`);
 			return written;
 		};
+		const notice = FORMAT_NOTICE_EVENTS.has(event) ? formatNotice(root, ctx.cli) : null;
+		if (notice) return {
+			stdout: notice.text,
+			error: errorText(`mainflow hook ${platform} ${event}: ${notice.reason}`)
+		};
 		return {
 			stdout: await handler(root, {
 				...ctx,