mainflow 0.28.0 → 0.29.0

package/dist/cli.js

@@ -1,65 +1,813 @@
 #!/usr/bin/env node
-import { $ as appendOps, A as untilState, B as setSessionArchived, C as setCriterion, D as supersedeDecision, H as setSessionStatus, I as handoffSession, K as updateAction, L as loadSessions, M as sessionBriefing, O as undropChecklistItem, P as addAction, R as readSession, S as setChecklistItem, T as setMainlineStatus, W as startSession, _ as createMainline, _t as WriteError, at as setFindingArchived, b as initHub, ct as HubError, et as closeIssue, g as createDecision, h as addRepo, ht as TASK_FILE, it as reopenIssue, j as duplicateClaimLines, k as updateTask, l as migrateHub, lt as loadHub, m as addHub, mt as MAINLINE_FILE, nt as createIssue, ot as setFindingStatus, p as acceptDecision, rt as planIssue, st as setIssueArchived, tt as createFinding, u as retroReport, v as createTask, w as setCriterionText, x as setArchived, xt as findHubRoot, y as dropChecklistItem } from "./host-CeN3dvXg.js";
+import { $ as nowMinute, G as loadHub, H as applyOperation, Q as requireSlug, S as readSession, U as checkHubName, W as HubError, X as MAINLINE_FILE, Z as TASK_FILE, _ as untilState, d as retroReportFromReceiver, f as receiverFromEnv, g as initHub, l as migrateHub, ot as DATA_DIR, p as RETRY_RULES, rt as findHubRoot, st as WriteError, tt as nodeStorage, u as retroReport, v as duplicateClaimLines, x as loadSessions, y as sessionBriefing } from "./host-BJnrv8xF.js";
 import { B as parseRef, H as refExample, V as parseUntil, k as UNTIL_FORMS } from "./dist-BbamrIPW.js";
 import { t as listProgress } from "./progress-1BfPg2zN.js";
+import { C as ServerError, S as ServerApi, _ as silentHint, a as remoteMode, c as syncSettings, d as startDaemon, f as DaemonRunning, g as readDaemon, h as probeDaemon, i as queuedCount, l as hookAnswer, m as callDaemon, n as hubWriter, o as ENV, p as DaemonUnavailable, r as writtenLines, s as hubName, t as CONFIRM_MS, u as planFlush, v as SETTINGS_FILE, x as syncPaths } from "./operation-Bp4U2bx3.js";
 import { COMMAND_SPECS, OPTIONS } from "./facts.js";
 import { hookFallback, parsePayload, runHook } from "./hooks.js";
-import { l as CLI_VERSION, r as launchUi, s as startUiInBackground } from "./launch-BKKoCyTj.js";
-import { readFileSync, realpathSync } from "node:fs";
-import { basename, join, relative } from "node:path";
+import { c as watchHubGone, l as CLI_VERSION, r as launchUi, s as startUiInBackground } from "./launch-DefacJEL.js";
+import { randomBytes } from "node:crypto";
+import { existsSync, readFileSync, realpathSync, rmSync, statSync } from "node:fs";
+import { basename, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
+//#region src/remote/sync.ts
+/**
+* Run the sync client for the hub at `root` until the process is told to stop, or the hub's directory goes. A write
+* that found no sync client may have started this one in the background (src/remote/start.ts); a clean stop clears
+* that record, so the next write does not take the stop for a failed start.
+*/
+async function syncRun(root) {
+	const settings = syncSettings(root);
+	if (!settings) {
+		console.error(`✗ no sync server: set ${ENV.url} and ${ENV.token}, or url and token in .mainflow/${SETTINGS_FILE}`);
+		return 1;
+	}
+	const running = await probeDaemon(root);
+	if (running && running.state !== "gone") {
+		console.error(`✗ mainflow sync already runs for this hub (pid ${running.daemon.pid})${running.state === "silent" ? `; ${silentHint(running.daemon)}` : ""}`);
+		return 1;
+	}
+	try {
+		await new ServerApi(settings).snapshot();
+	} catch (error) {
+		if (error instanceof ServerError) {
+			console.error(`✗ ${error.message} (hub ${settings.hub} at ${settings.url})`);
+			return 1;
+		}
+	}
+	let daemon;
+	try {
+		daemon = await startDaemon({
+			root,
+			settings,
+			log: (line) => console.log(line)
+		});
+	} catch (error) {
+		if (!(error instanceof DaemonRunning)) throw error;
+		console.error(`✗ ${error.message}`);
+		return 1;
+	}
+	console.log(`syncing hub ${settings.hub} with ${settings.url} (${daemon.client.online ? "online" : "offline, retrying"})`);
+	await new Promise((resolve) => {
+		process.once("SIGINT", resolve);
+		process.once("SIGTERM", resolve);
+		watchHubGone(root, resolve);
+	});
+	await daemon.stop();
+	forgetStarted(root);
+	return 0;
+}
+/** Clear the record of a background start when it names this process. */
+function forgetStarted(root) {
+	const file = syncPaths(root).started;
+	try {
+		if (JSON.parse(readFileSync(file, "utf8")).pid === process.pid) rmSync(file, { force: true });
+	} catch {}
+}
+function readPayload() {
+	try {
+		const parsed = JSON.parse(readFileSync(0, "utf8"));
+		return parsed && typeof parsed === "object" ? parsed : {};
+	} catch {
+		return {};
+	}
+}
+/**
+* Send every change now and report what did not reach the hub as written. With `hook`, read the PostToolUse
+* payload from stdin, skip tools that wrote nothing synced, and answer as the hook: a block with the problems as
+* the reason, or nothing. A hook never fails the tool, so without a running sync client it answers nothing.
+*/
+async function syncFlush(root, hook) {
+	const payload = hook ? readPayload() : {};
+	const daemon = readDaemon(root);
+	if (!daemon) {
+		if (hook) return 0;
+		console.error("✗ mainflow sync is not running for this hub");
+		return 1;
+	}
+	const plan = hook ? planFlush(root, payload) : { skip: false };
+	if (plan.skip) return 0;
+	let result;
+	try {
+		result = await callDaemon(daemon, "/flush", plan.edit ? { edit: plan.edit } : {}, 3e4);
+	} catch (error) {
+		if (hook && error instanceof DaemonUnavailable) return 0;
+		throw error;
+	}
+	if (hook) {
+		const answer = hookAnswer(result);
+		if (answer) console.log(answer);
+		return 0;
+	}
+	for (const problem of result.problems) console.log(`! ${problem.message}`);
+	console.log(`${result.problems.length} problems, ${result.queued} queued, ${result.online ? "online" : "offline"}`);
+	return result.problems.length > 0 ? 1 : 0;
+}
+async function syncStatus(root) {
+	const probe = await probeDaemon(root);
+	if (probe?.state === "silent") {
+		console.log(`mainflow sync runs for this hub (pid ${probe.daemon.pid}), but ${silentHint(probe.daemon)}`);
+		return 0;
+	}
+	if (probe?.state === "running") {
+		const { status, daemon } = probe;
+		if (!status) console.log(`mainflow sync runs for this hub (pid ${daemon.pid}); it did not give its status`);
+		else console.log(`mainflow sync runs (pid ${daemon.pid}): ${status.online ? status.caughtUp ? "online, caught up" : "online, catching up" : "offline"}, ${status.queued} queued, atomic exchange ${status.swapping ? "on" : "off"}, ${status.problems} problems so far`);
+		return 0;
+	}
+	const queue = queuedCount(root);
+	console.log(`mainflow sync is not running; ${remoteMode(root) ? `${queue} write(s) wait in the outbox until it runs` : "writes go to the local files"}`);
+	return 0;
+}
+//#endregion
 //#region src/retro.ts
-const int = (n) => n.toLocaleString("en-US");
+const int = (n) => Math.round(n).toLocaleString("en-US");
 const usd = (n) => `$${n.toFixed(2)}`;
 const pct = (n) => n === null ? "–" : `${(n * 100).toFixed(1)}%`;
+const sec = (ms) => `${(ms / 1e3).toFixed(1)} 秒`;
+/** A local stamp of the report (2026-10-05T10:01:12) as the text shows it. */
+const stampText = (s) => s.replace("T", " ");
 /** A transcript timestamp in local time, to the minute. */
 const local = (iso) => {
 	const d = new Date(iso);
-	return Number.isNaN(d.getTime()) ? iso : `${d.toLocaleDateString("sv-SE")} ${d.toTimeString().slice(0, 5)}`;
+	return Number.isNaN(d.getTime()) ? String(iso) : `${d.toLocaleDateString("sv-SE")} ${d.toTimeString().slice(0, 5)}`;
 };
 const tokens = (u) => `輸入 ${int(u.input)}、快取寫 5m ${int(u.cacheWrite5m)}、快取寫 1h ${int(u.cacheWrite1h)}、快取讀 ${int(u.cacheRead)}、輸出 ${int(u.output)}`;
 const costOf = (t) => `${usd(t.cost)}${t.unknownPriceModels.length ? `（另有未知單價：${t.unknownPriceModels.join("、")}）` : ""}`;
 const byCount = (r) => Object.entries(r).sort((a, b) => b[1] - a[1]).map(([k, v]) => `${k} ${v}`).join("、");
+const joined = (parts) => parts.filter(Boolean).join("，");
 const COMMAND_SHOWN = 100;
-function retroText(report) {
-	const { mainline, cost, precision } = report;
+const LISTED = 15;
+function calibration(s, undercount) {
+	const c = s.calibration;
+	if (!c) return "";
+	switch (c.method) {
+		case "otel": return `依 OTel api_request ${usd(c.calibrated)}`;
+		case "cost-state": {
+			const { total, after } = c.costState;
+			return after.calls > 0 ? `cost-state 合計 ${usd(total)}，加合計沒有的呼叫 ${usd(after.calibrated)}（${int(after.calls)} 次呼叫，對話紀錄 ${usd(after.transcript)}），共 ${usd(c.calibrated)}` : `和 cost-state 一致 ${usd(c.calibrated)}`;
+		}
+		case "cost-state-split": {
+			const { total, covered, outside, after } = c.costState;
+			const later = after.calls > 0 ? `；合計沒有的呼叫 ${usd(after.calibrated)}（${int(after.calls)} 次呼叫，對話紀錄 ${usd(after.transcript)}）` : "";
+			return `依 cost-state 分項校正 ${usd(c.calibrated)}（估算：cost-state ${usd(total)}，涵蓋的對話紀錄 ${usd(covered)}；範圍外 ${usd(outside)}${later}）`;
+		}
+		case "none": return `沒有校正，${undercount ?? ""}`;
+	}
+}
+function stretches(s) {
+	if (!s.window.length) return "沒有計入的時段";
+	if (s.window.length === 1 && !s.window[0].from && !s.window[0].to) return "整份對話紀錄";
+	const spans = s.window.map((w) => `${w.from ? stampText(w.from) : "開頭"} 到 ${w.to ? stampText(w.to) : "結尾"}`);
+	return spans.length > 3 ? `${spans.length} 段：${spans.slice(0, 3).join("、")} 等` : spans.join("、");
+}
+/** Which part of the transcript counted, and by which rule. */
+function window(s) {
+	const scope = s.scope;
+	if (!scope || scope.rule === "given") return stretches(s);
+	if (scope.rule === "time") return `${stretches(s)}（對話紀錄沒有 mainflow 的輪次標頭，依行動時段）`;
+	const notes = joined([
+		scope.inferred > 0 && `${scope.inferred} 輪開始時沒有進行中的行動，依這輪開始或接手的行動${scope.inferredCost !== void 0 ? `（對話紀錄 ${usd(scope.inferredCost)}）` : ""}`,
+		scope.inherited > 0 && `${scope.inherited} 輪沒有標頭，沿用前一輪或派出子代理的那一輪`,
+		scope.shared > 0 && `${scope.shared} 輪的行動也服務別條主脈絡，只算給第一個參照`,
+		scope.switched > 0 && `${scope.switched} 輪中途開始了別條主脈絡的行動，整輪仍算在這裡`,
+		scope.beforeHeads > 0 && `標頭出現前的 ${scope.beforeHeads} 輪依行動時段`
+	]);
+	return `${int(scope.counted)} / ${int(scope.turns)} 輪（依每輪的 mainflow 標頭${notes ? `；${notes}` : ""}）`;
+}
+function nodeLine(n) {
+	const cost = joined([
+		n.subagents > 0 && `子代理 ${usd(n.subagentCost)} ×${n.subagents}`,
+		n.occupancy.cost > 0 && `主會話佔用 ${usd(n.occupancy.cost)}${n.repeatOccupancy.cost > 0 ? `（其中重複注入 ${usd(n.repeatOccupancy.cost)}）` : ""}`,
+		n.skillTurns > 0 && `主會話 skill 輪次 ${usd(n.skillTurnCost)} ×${int(n.skillTurns)}`,
+		n.subagentOccupancy.cost > 0 && `子代理內佔用 ${usd(n.subagentOccupancy.cost)}（已含在子代理費用）`
+	]);
+	const work = joined([
+		n.hookRuns > 0 && `hook 執行 ${int(n.hookRuns)} 次 ${sec(n.hookMs)}${n.cancelled ? `，取消 ${n.cancelled}` : ""}${n.blocked ? `，擋下 ${n.blocked}` : ""}`,
+		n.injections > 0 && `注入 ${int(n.injections)} 次 ${int(n.chars)} 字${n.repeats ? `（同內容重複 ${n.repeats}）` : ""}`,
+		n.loads > 0 && `載入 ${int(n.loads)} 次`,
+		n.scriptRuns > 0 && `腳本執行 ${int(n.scriptRuns)} 次 ${sec(n.scriptMs)}`
+	]);
+	const timing = n.measured && joined([n.measured.unfinished > 0 && `未結束 ${n.measured.unfinished}`, n.measured.killed > 0 && `被訊號中止 ${n.measured.killed}`]);
+	return `- ${n.node}（${n.kind}）：歸因 ${usd(n.attributed)}${cost ? `；${cost}` : ""}${work ? `；${work}` : ""}${timing ? `（計時紀錄：${timing}）` : ""}`;
+}
+function sourceLine(s, by) {
+	const head = `- [${s.source}] ${s.key}：${s.anomalies} 則`;
+	const reasons = byCount(s.reasons);
+	if (by === "ratio") return `${head}，最大 ${s.maxRatio.toFixed(1)} 倍（${reasons}）`;
+	return `${head}，超出 ${sec(s.excessMs)}，預期 ${s.expectedMs === null ? "–" : sec(s.expectedMs)}，中位數 ${s.medianMs === null ? "–" : sec(s.medianMs)}（${reasons}）`;
+}
+function costSection(report) {
+	const { cost } = report;
 	return [
-		`retro ${mainline.id} ${mainline.title}（${mainline.status}）`,
-		`Claude Code 版本：${report.versions.join("、") || "（對話紀錄沒有版本欄位）"}`,
-		`費用為依牌價的估算：${report.pricing.url}（${report.pricing.date}，${report.pricing.unit}）`,
-		`無法解析的列：${int(report.unreadable)}`,
-		`對話紀錄：${cost.sessions.length} 場會話、${cost.subagents.length} 個子代理`,
-		"",
 		"== 費用 ==",
-		`估算合計：${usd(cost.total)}${cost.unknownPriceModels.length ? `，不含未知單價的 ${cost.unknownPriceModels.join("、")}` : ""}`,
+		`估算合計：${usd(cost.total)}（校正後，對話紀錄本身 ${usd(cost.transcriptTotal)}）${cost.unknownPriceModels.length ? `，不含未知單價的 ${cost.unknownPriceModels.join("、")}` : ""}`,
+		...cost.undercount ? [`誤差：有會話沒有 OTel 也沒有 cost-state，${cost.undercount}`] : [],
 		`快取命中率：${pct(cost.cacheHitRate)}（快取讀 ÷ 全部上下文）`,
 		"各模型：",
-		...cost.models.map((m) => `- ${m.model}：呼叫 ${int(m.calls)}，${tokens(m.usage)}，${m.cost === null ? "未知單價" : usd(m.cost)}`),
+		...cost.models.map((m) => `- ${m.model}：呼叫 ${int(m.calls)}，${tokens(m.usage)}，${m.cost === null ? "未知單價" : `對話紀錄 ${usd(m.cost)}，校正後 ${usd(m.calibrated ?? m.cost)}`}`),
 		"會話：",
-		...cost.sessions.map((s) => s.missing ? `- ${s.session}：沒有讀到對話紀錄（${s.missing}）` : `- ${s.session}：開場上下文 ${s.openingContext === null ? "–" : int(s.openingContext)} tokens，呼叫 ${int(s.calls)}，快取命中率 ${pct(s.cacheHitRate)}，${costOf(s)}`),
+		...cost.sessions.map((s) => s.missing ? `- ${s.session}：沒有讀到對話紀錄（${s.missing}）` : `- ${s.session}：計入 ${window(s)}，開場上下文 ${s.openingContext === null ? "–" : int(s.openingContext)} tokens，呼叫 ${int(s.calls)}，快取命中率 ${pct(s.cacheHitRate)}，${costOf(s)}；連同子代理：${calibration(s, cost.undercount)}${s.calibration?.otelSkipped ? `（沒用 OTel：${s.calibration.otelSkipped}）` : ""}`),
 		"子代理：",
 		...cost.subagents.length === 0 ? ["- 無"] : cost.subagents.map((a) => {
 			const who = [a.agentType, a.description].filter(Boolean).join("：");
 			return `- ${basename(a.file, ".jsonl")}${who ? `（${who}）` : ""}，委派自 ${a.parent}：${a.models.join("、") || "沒有回覆"}，呼叫 ${int(a.calls)}，${tokens(a.usage)}，開場上下文 ${a.openingContext === null ? "–" : int(a.openingContext)}，${costOf(a)}`;
 		}),
-		"hook 注入：",
-		...cost.hooks.length === 0 ? ["- 無"] : cost.hooks.map((h) => `- ${h.event}：${int(h.injections)} 次，${int(h.chars)} 字${h.blocked ? `，擋下 ${h.blocked} 次` : ""}`),
-		"",
+		cost.hooksNote ? `hook 事件（${cost.hooksNote}）：` : "hook 事件：",
+		...cost.hooks.length === 0 ? ["- 無"] : cost.hooks.map((h) => `- ${h.event}：${joined([
+			h.runs > 0 && `執行 ${int(h.runs)} 次 ${sec(h.durationMs)}${h.cancelled ? `（取消 ${h.cancelled}）` : ""}`,
+			`注入 ${int(h.injections)} 次，${int(h.chars)} 字`,
+			h.blocked > 0 && `擋下 ${h.blocked} 次`
+		])}`)
+	];
+}
+function attributionSection(report) {
+	const a = report.attribution;
+	return [
+		"== 來源歸因 ==",
+		`promptex 紀錄：${a.roots.filter((r) => r.units.length).map((r) => `${r.root}（${r.units.join("、")}）`).join("、") || "沒有找到，節點 id 依安裝路徑推得、未核對"}`,
+		`能對回節點：${usd(a.attributed)}，占已歸到來源的費用 ${pct(a.coverage)}（分母不含主會話自己的對話與輸出 ${usd(a.conversation)}），占總費用 ${pct(a.coverageOfTotal)}。以對話紀錄的費用 ${usd(a.total)} 計，未校正`,
+		`節點（依歸因金額，前 ${LISTED}）：`,
+		...a.nodes.length === 0 ? ["- 無"] : a.nodes.slice(0, LISTED).map(nodeLine),
+		"對不回節點：",
+		...a.unmapped.length === 0 ? ["- 無"] : a.unmapped.slice(0, 8).map((u) => `- ${u.reason}：${usd(u.cost)}（${int(u.count)} 筆）`),
+		...measuredLines(a.measured)
+	];
+}
+/** The hook timing log's part of the attribution, when the measurement receiver was read. */
+function measuredLines(m) {
+	if (!m) return [];
+	const states = joined([
+		m.unfinished > 0 && `未結束 ${int(m.unfinished)}`,
+		m.killed > 0 && `被訊號中止 ${int(m.killed)}`,
+		m.endOnly > 0 && `只收到結束列 ${int(m.endOnly)}`
+	]);
+	return [
+		`hook 計時紀錄：執行 ${int(m.runs)} 次 ${sec(m.ms)}，對回節點 ${int(m.mapped)} 次${states ? `（${states}）` : ""}。節點的 hook 執行次數與耗時取自它，再加上對話紀錄有、計時紀錄沒有對應的 ${int(m.transcriptOnly.runs)} 次 ${sec(m.transcriptOnly.ms)}`,
+		"計時紀錄對不回節點：",
+		...m.unmapped.length === 0 ? ["- 無"] : m.unmapped.map((u) => `- ${u.reason}：${int(u.runs)} 次 ${sec(u.ms)}${u.scripts.length ? `（${u.scripts.join("、")}）` : ""}`)
+	];
+}
+/** What the measurement receiver gave and what it could not. */
+function measurementSection(report) {
+	const m = report.measurements;
+	if (!m) return [];
+	const rows = Object.entries(m.rows).sort((a, b) => b[1] - a[1]).map(([k, v]) => `${k} ${int(v)}`).join("、");
+	return [
+		"== 量測接收端 ==",
+		`來源：${m.origin || "（沒有讀取）"}，${m.sessions} 場會話，列出物件 ${int(m.objects)} 個，下載 ${int(m.downloaded)} 個，缺 ${int(m.missing)} 個，請求 ${int(m.requests)} 次${report.timings.receiver !== void 0 ? `，耗時 ${int(report.timings.receiver)} ms` : ""}`,
+		`範圍內的列：${rows || "無"}`,
+		`api_request：範圍內 ${int(m.apiRequests.rows)} 列${m.apiRequests.withoutCost ? `，缺模型或費用 ${int(m.apiRequests.withoutCost)} 列` : ""}。涵蓋整個範圍的會話依它校正，其餘會話的校正方式寫在各會話那一行`,
+		"hook 批次（平台只記事件，不記腳本，所以對不回節點）：",
+		...m.hookBatches.length === 0 ? ["- 無"] : m.hookBatches.map((b) => `- ${b.event}：${joined([
+			`批次 ${int(b.batches)}`,
+			`hook ${int(b.hooks)} 支`,
+			sec(b.ms),
+			b.blocking > 0 && `擋下 ${int(b.blocking)}`,
+			b.cancelled > 0 && `取消 ${int(b.cancelled)}`,
+			b.nonBlockingErrors > 0 && `非阻擋錯誤 ${int(b.nonBlockingErrors)}`
+		])}`),
+		"缺的部分：",
+		...m.problems.length === 0 ? ["- 無"] : m.problems.map((p) => `- ${p}`)
+	];
+}
+function anomalySection(report) {
+	const x = report.anomalies;
+	const { TIMEOUT_SHARE, ROBUST_Z, MIN_EXCESS_MS, MIN_BASELINE, RERUN_WINDOW } = x.rules;
+	const types = [
+		"hook",
+		"script",
+		"subagent",
+		"bash"
+	].map((t) => `${t} ${x.anomalies.filter((a) => a.source === t).length}`).join("、");
+	const top = (list, by) => [
+		"hook",
+		"script",
+		"subagent",
+		"bash"
+	].flatMap((t) => list.filter((s) => s.source === t).slice(0, 3)).map((s) => sourceLine(s, by));
+	return [
+		"== 異常 ==",
+		`規則：每個來源以自己的基線判斷（至少 ${MIN_BASELINE} 筆熱執行），robust z > ${ROBUST_Z} 且超出 ${sec(MIN_EXCESS_MS)}，同組與整個來源都要超過；沒有基線的 hook 以宣告逾時的 ${TIMEOUT_SHARE * 100}% 當預期；逾時、取消、結束碼非 0、前 ${RERUN_WINDOW} 次內重跑同一指令、使用者中止一律列出`,
+		`共 ${x.anomalies.length} 則（${types}），計時的執行 ${int(x.runs.hook + x.runs.script + x.runs.subagent)} 筆，冷啟動 ${x.runs.cold} 筆不進基線`,
+		`擋下（把關的決定，不算異常）：${int(blockTotal(x.blocks))} 次，${blockMatch(blockTotal(x.blocks), report.precision.blocked.total)}。有紀錄的依節點，PreToolUse 只留訊息，依訊息開頭`,
+		...Object.entries(x.blocks).sort((a, b) => b[1] - a[1]).slice(0, 8).map(([k, v]) => `- ${k}：${v} 次`),
+		"超出時間 × 次數（各類前 3）：",
+		...x.byExcess.length ? top(x.byExcess, "excess") : ["- 無"],
+		"實際 ÷ 預期（各類前 3）：",
+		...x.byRatio.length ? top(x.byRatio, "ratio") : ["- 無"]
+	];
+}
+const blockTotal = (blocks) => Object.values(blocks).reduce((a, b) => a + b, 0);
+/** The gate decisions against the precision section's blocks, which count the same runs. */
+const blockMatch = (gates, blocked) => gates === blocked ? "和精準度候選的「被 hook 擋下」相同" : `比精準度候選的「被 hook 擋下」（${int(blocked)} 次）${gates > blocked ? "多" : "少"} ${int(Math.abs(gates - blocked))} 次`;
+function reviewSection(report) {
+	const r = report.reviews;
+	const tally = (t) => t.total ? `發現 ${t.total} 則（嚴重度 ${byCount(t.bySev)}；成因 ${byCount(t.byClass)}）` : "發現 0 則";
+	return [
+		"== 委派與審查 ==",
+		`委派 ${r.delegations} 個，帶標籤 ${r.labeled} 個${r.otherMainline ? `，其中 ${r.otherMainline} 個屬於其他主脈絡` : ""}，沒有標籤 ${r.unlabeled.length} 個`,
+		"各項目的輪數：",
+		...r.items.length === 0 ? ["- 無"] : r.items.map((i) => {
+			const roles = Object.entries(i.roles).map(([role, v]) => `${role} ${v.delegations}（到 r${v.maxRound}）`).join("、");
+			return `- ${i.item}：${roles}${i.roles.review ? `；${tally(i.findings)}` : ""}`;
+		}),
+		`審查發現合計：${tally(r.findings)}`,
+		`缺 review-findings 區塊的審查回覆：${r.missingBlock.length}`,
+		...r.missingBlock.map((m) => `- ${m.agentId}（${m.item} review r${m.round}）`),
+		`review-findings 區塊讀不懂的行：${r.badLines.length}`,
+		...r.badLines.slice(0, 10).map((b) => `- ${b.agentId}（${b.item}）：${b.why}：${b.line.slice(0, 80)}`),
+		`區塊之後還有文字的審查回覆：${r.trailingText.length}`,
+		...r.trailingText.slice(0, 10).map((t) => `- ${t.agentId}（${t.item}）：${t.text.replace(/\s+/g, " ").slice(0, 80)}`),
+		`無標籤的審查回覆（審查代理的委派沒寫標籤，發現不計入合計）：${r.unlabeledReviews.length}`,
+		...r.unlabeledReviews.map((u) => `- ${u.agentId}（${u.agentType}${u.description ? `：${u.description}` : ""}）：${u.found ? tally(u.findings) : "缺 review-findings 區塊"}${u.badLines ? `，讀不懂的行 ${u.badLines}` : ""}`)
+	];
+}
+const UNMATCHED = {
+	"hand-written": "手寫段",
+	"no-node": "標題對不到節點"
+};
+const STRENGTH = {
+	strong: "強",
+	weak: "弱",
+	stop: "Stop"
+};
+function retryLine(b) {
+	const between = b.between?.length ? `，中間呼叫 ${b.between.join("、")}` : "";
+	return `- [${STRENGTH[b.strength]}] ${b.blockedAt === void 0 ? "–" : local(b.blockedAt)} ${b.event} ${b.tool}，${b.hook}：擋下 ${b.attempts} 次後通過${between}（${b.where}）：${b.input}`;
+}
+function offlineSection(report) {
+	const { sections, sectionWarning, blockRetries } = report.offline;
+	const t = report.timings;
+	const strength = (k) => blockRetries.filter((b) => b.strength === k).length;
+	return [
+		"== 離線分析 ==",
+		`常駐指示與 rules 逐區段佔用（依會話載入的內容切 # 與 ## 標題，依佔用費用前 ${LISTED}，共 ${sections.length} 段）：`,
+		...sectionWarning ? [`警告：${sectionWarning}`] : [],
+		...sections.length === 0 ? ["- 無"] : sections.slice(0, LISTED).map((s) => `- ${s.file} ${s.heading}（${s.node ?? UNMATCHED[s.unmatched ?? "no-node"]}）：${int(s.chars)} 字 ${int(s.bytes)} B，載入 ${s.loads} 次${s.carried ? `、範圍前帶入 ${s.carried} 次` : ""}${s.versions > 1 ? `（${s.versions} 種版本）` : ""}，佔用 ${usd(s.occupancy.cost)}、${int(s.occupancy.tokenCalls)} token 次`),
+		`擋下誤判候選：強 ${strength("strong")}、弱 ${strength("weak")}、Stop ${strength("stop")}（強：${RETRY_RULES.strong}；弱：${RETRY_RULES.weak}；Stop：${RETRY_RULES.stop}）`,
+		...blockRetries.slice(0, 20).map(retryLine),
+		`耗時：讀取 ${int(t.read)} ms，${t.receiver !== void 0 ? `接收端 ${int(t.receiver)} ms，` : ""}來源歸因 ${int(t.attribution)} ms，異常 ${int(t.anomalies)} ms，委派與審查 ${int(t.reviews)} ms，逐區段佔用 ${int(t.sections)} ms，擋下誤判 ${int(t.blockRetries)} ms，合計 ${int(t.total)} ms`
+	];
+}
+function precisionSection(report) {
+	const { mainline, precision } = report;
+	return [
 		"== 精準度候選 ==",
 		`工具錯誤：${precision.toolErrors.total}${precision.toolErrors.total ? `（${byCount(precision.toolErrors.byTool)}）` : ""}`,
 		`同一個 Bash 指令重跑：${precision.bashReruns.total} 次`,
 		...precision.bashReruns.commands.slice(0, 10).map((c) => `- ${c.runs} 次（${c.session}）：${c.command.length > COMMAND_SHOWN ? `${c.command.slice(0, 99)}…` : c.command}`.replace(/\n/g, " ")),
-		`誤觸候選（hook 注入後，下一則回覆沒有任何工具呼叫）：${precision.misfireCandidates.total}${precision.misfireCandidates.total ? `（${byCount(precision.misfireCandidates.byEvent)}）` : ""}`,
 		`被 hook 擋下：${precision.blocked.total}${precision.blocked.total ? `（${byCount(precision.blocked.byEvent)}）` : ""}`,
 		`超過 5 分鐘的間隔：${precision.gaps.length}`,
 		...precision.gaps.map((g) => `- ${local(g.from)} → ${local(g.to)}，${g.minutes} 分鐘，${g.waitingForUser ? "等使用者" : "工具或子代理執行中"}（${g.session}）`),
 		`主脈絡：解決條件 ${mainline.criteria} 條，任務 ${mainline.tasks} 個，完成檢查未過 ${precision.failedChecks.length} 行`,
 		...precision.failedChecks.map((f) => `- ${f.task}：${f.line}`)
+	];
+}
+function retroText(report) {
+	const { mainline, cost } = report;
+	return [
+		`retro ${mainline.id} ${mainline.title}（${mainline.status}）`,
+		`Claude Code 版本：${report.versions.join("、") || "（對話紀錄沒有版本欄位）"}`,
+		`費用為依牌價的估算：${report.pricing.url}（${report.pricing.date}，${report.pricing.unit}）`,
+		`無法解析的列：${int(report.unreadable)}，重複 uuid 略過 ${int(report.records.duplicates)} 列，範圍外未計入 ${int(report.records.outsideWindow)} 列`,
+		`對話紀錄：${cost.sessions.length} 場會話、${cost.subagents.length} 個子代理`,
+		"",
+		...report.measurements ? [...measurementSection(report), ""] : [],
+		...costSection(report),
+		"",
+		...attributionSection(report),
+		"",
+		...anomalySection(report),
+		"",
+		...reviewSection(report),
+		"",
+		...offlineSection(report),
+		"",
+		...precisionSection(report)
 	].join("\n");
 }
 //#endregion
 //#region src/cli.ts
+const write = (spec) => spec;
+/** Where a document an operation created or changed is, as the commands print it: .mainflow/... */
+const inData = (...parts) => join(DATA_DIR, ...parts);
+const WRITES = {
+	"repo add": write({
+		op: "repo.add",
+		check: ({ root, args }) => {
+			requireSlug(args[0]);
+			const target = resolve(root, args[1]);
+			if (!existsSync(target) || !statSync(target).isDirectory()) throw new WriteError(`repo path ${args[1]} does not exist from the hub root (${target})`);
+		},
+		input: ({ args }) => ({
+			name: args[0],
+			path: args[1]
+		}),
+		print: ({ args }, name) => done(`registered ${name} ${args[1]}`)
+	}),
+	"hub add": write({
+		op: "hub.add",
+		check: ({ root, args }) => {
+			const [name, path] = [args[0], args[1]];
+			checkHubName(nodeStorage(root), name);
+			const target = resolve(root, path);
+			if (!existsSync(join(target, ".mainflow", "config.yaml"))) throw new WriteError(`no hub at ${path} from the hub root (${target})`);
+			const other = hubName(target);
+			if (other !== name) throw new WriteError(`${path} holds hub "${other}"; register it as "${other}"`);
+		},
+		input: ({ args }) => ({
+			name: args[0],
+			path: args[1]
+		}),
+		print: ({ args }, name) => done(`registered hub ${name} ${args[1]}`)
+	}),
+	"session start": write({
+		op: "session.start",
+		input: ({ opts }) => {
+			const agent = opts.agent ?? "manual";
+			return {
+				id: opts.id ?? `${agent}-${randomBytes(4).toString("hex")}`,
+				agent,
+				cwd: process.cwd(),
+				delegatedFrom: opts["delegated-from"],
+				handoffFrom: opts["handoff-from"]
+			};
+		},
+		print: (_, session) => done(`started ${session.id}${session.actions.length ? ` with ${session.actions.length} carried actions` : ""}`)
+	}),
+	"session handoff": write({
+		op: "session.handoff",
+		input: ({ args, opts }) => ({
+			id: sessionOf(opts),
+			from: args[0]
+		}),
+		print: ({ args }, session) => done(`${session.id} took over ${session.actions.filter((a) => a.status === "todo" || a.status === "doing").length} actions from ${args[0]}`)
+	}),
+	"session set": write({
+		op: "session.set",
+		input: ({ args, opts }) => ({
+			id: args[0],
+			status: required(opts, "status", "--status paused")
+		}),
+		print: ({ args }, session) => done(`updated ${args[0]} (${session.status})`)
+	}),
+	"session end": write({
+		op: "session.set",
+		input: ({ args, opts }) => ({
+			id: sessionOf(opts, args[0]),
+			status: "ended"
+		}),
+		print: (_, session) => done(`ended ${session.id}`)
+	}),
+	"session archive": write({
+		op: "session.archive",
+		input: ({ args }) => ({
+			id: args[0],
+			archived: true
+		}),
+		print: (_, session) => done(`archived ${session.id}`)
+	}),
+	"session unarchive": write({
+		op: "session.archive",
+		input: ({ args }) => ({
+			id: args[0],
+			archived: false
+		}),
+		print: (_, session) => done(`unarchived ${session.id}`)
+	}),
+	"action add": write({
+		op: "action.add",
+		input: ({ args, opts }) => ({
+			session: sessionOf(opts),
+			do: args[0],
+			serves: list(opts.serves),
+			before: opts.before
+		}),
+		print: ({ root }, ref) => {
+			done(`created ${ref}`);
+			return remindDuplicates(root, ref);
+		}
+	}),
+	"action set": write({
+		op: "action.set",
+		input: ({ args, opts }) => {
+			const blockedBy = opts.reason ? {
+				reason: opts.reason,
+				...opts["waiting-for"] ? { waitingFor: opts["waiting-for"] } : {},
+				...opts.until ? { until: opts.until } : {}
+			} : void 0;
+			if (!blockedBy && (opts["waiting-for"] || opts.until)) throw new WriteError("--waiting-for and --until need --reason, e.g. --status blocked --reason \"等 schema 定案\"");
+			return {
+				ref: actionRef(opts, args[0]),
+				patch: {
+					status: opts.status,
+					do: opts.text,
+					serves: opts.serves === void 0 ? void 0 : list(opts.serves),
+					before: opts.before,
+					note: opts.note,
+					blockedBy
+				}
+			};
+		},
+		print: ({ root, args, opts }, action) => {
+			const ref = actionRef(opts, args[0]);
+			done(`updated ${ref} (${action.status})`);
+			return opts.status === "doing" ? remindDuplicates(root, ref) : 0;
+		}
+	}),
+	"new mainline": write({
+		op: "mainline.new",
+		input: ({ args, opts }) => ({
+			slug: args[0],
+			title: required(opts, "title", "--title \"重建 mainline 任務管理\"")
+		}),
+		print: (_, { id, dir }) => done(`created ${id} ${inData(dir, MAINLINE_FILE)}`)
+	}),
+	"new task": write({
+		op: "task.new",
+		input: ({ args, opts }) => ({
+			mainline: args[0],
+			slug: args[1],
+			title: required(opts, "title", "--title \"定義資料格式 schema\""),
+			kind: opts.kind,
+			parent: opts.parent,
+			repo: opts.repo
+		}),
+		print: (_, { ref, dir }) => done(`created ${ref} ${inData(dir, TASK_FILE)}`)
+	}),
+	"new decision": write({
+		op: "decision.new",
+		input: ({ args, opts }) => ({
+			mainline: args[0],
+			slug: args[1],
+			title: required(opts, "title", "--title \"以文字檔為準\""),
+			status: opts.status,
+			by: opts.by,
+			basis: opts.basis,
+			affects: opts.affects ? list(opts.affects) : void 0
+		}),
+		print: (_, { ref, file }) => done(`created ${ref} ${inData(file)}`)
+	}),
+	"new issue": write({
+		op: "issue.new",
+		input: ({ args, opts }) => ({
+			slug: args[0],
+			title: required(opts, "title", "--title \"重試不穩定的 VM\""),
+			origin: opts.origin,
+			labels: opts.labels ? list(opts.labels) : void 0
+		}),
+		print: (_, { id, file }) => done(`created ${id} ${inData(file)}`)
+	}),
+	"new finding": write({
+		op: "finding.new",
+		input: ({ args, opts }) => ({
+			slug: args[0],
+			title: required(opts, "title", "--title \"先 await 再寫入 state\""),
+			origin: opts.origin,
+			labels: opts.labels ? list(opts.labels) : void 0
+		}),
+		print: (_, { id, file }) => done(`created ${id} ${inData(file)}`)
+	}),
+	"mainline set": write({
+		op: "mainline.set",
+		input: ({ args, opts }) => ({
+			id: args[0],
+			status: required(opts, "status", "--status active")
+		}),
+		print: (_, m) => done(`updated ${m.id} (${m.status})`)
+	}),
+	"mainline archive": write({
+		op: "mainline.archive",
+		input: ({ args }) => ({
+			id: args[0],
+			archived: true
+		}),
+		print: (_, m) => done(`archived ${m.id}`)
+	}),
+	"mainline unarchive": write({
+		op: "mainline.archive",
+		input: ({ args }) => ({
+			id: args[0],
+			archived: false
+		}),
+		print: (_, m) => done(`unarchived ${m.id}`)
+	}),
+	"criterion add": write({
+		op: "criterion.add",
+		input: ({ args, opts }) => ({
+			mainline: args[0],
+			text: args[1],
+			doneWhen: opts["done-when"] ?? ""
+		}),
+		print: (_, { ref }) => done(`created ${ref}`)
+	}),
+	"criterion check": write({
+		op: "criterion.check",
+		input: ({ args, opts }) => ({
+			ref: args[0],
+			done: true,
+			evidence: opts.evidence
+		}),
+		print: ({ args }) => done(`checked ${args[0]}`)
+	}),
+	"criterion uncheck": write({
+		op: "criterion.check",
+		input: ({ args }) => ({
+			ref: args[0],
+			done: false
+		}),
+		print: ({ args }) => done(`unchecked ${args[0]}`)
+	}),
+	"criterion set": write({
+		op: "criterion.set",
+		input: ({ args, opts }) => ({
+			ref: args[0],
+			patch: {
+				text: opts.text,
+				doneWhen: opts["done-when"]
+			}
+		}),
+		print: ({ args }) => done(`updated ${args[0]}`)
+	}),
+	"task set": write({
+		op: "task.set",
+		input: ({ args, opts }) => {
+			const blockedBy = opts.reason ? {
+				reason: opts.reason,
+				...opts["waiting-for"] ? { waitingFor: opts["waiting-for"] } : {},
+				...opts.signal ? { signal: opts.signal } : {}
+			} : void 0;
+			return {
+				ref: args[0],
+				patch: {
+					status: opts.status,
+					repo: opts.repo,
+					blockedBy,
+					branch: opts.branch,
+					worktree: opts.worktree,
+					base: opts.base,
+					merge: opts.merge
+				}
+			};
+		},
+		print: ({ args }, t) => done(`updated ${args[0]} (${t.status})`)
+	}),
+	"item add": write({
+		op: "item.add",
+		input: ({ args, opts }) => ({
+			task: args[0],
+			text: args[1],
+			doneWhen: opts["done-when"] ?? "",
+			serves: opts.serves === void 0 ? void 0 : list(opts.serves)
+		}),
+		print: (_, { ref }) => done(`created ${ref}`)
+	}),
+	"item check": write({
+		op: "item.check",
+		input: ({ args, opts }) => ({
+			ref: args[0],
+			done: true,
+			evidence: opts.evidence
+		}),
+		print: ({ args }) => done(`checked ${args[0]}`)
+	}),
+	"item uncheck": write({
+		op: "item.check",
+		input: ({ args }) => ({
+			ref: args[0],
+			done: false
+		}),
+		print: ({ args }) => done(`unchecked ${args[0]}`)
+	}),
+	"decision accept": write({
+		op: "decision.accept",
+		input: ({ args, opts }) => ({
+			ref: args[0],
+			by: opts.by,
+			basis: opts.basis
+		}),
+		print: ({ args }, d) => done(`accepted ${args[0]} (${d.decidedAt})`)
+	}),
+	"item drop": write({
+		op: "item.drop",
+		input: ({ args, opts }) => ({
+			ref: args[0],
+			supersededBy: opts.by,
+			note: opts.note
+		}),
+		print: ({ args }) => done(`dropped ${args[0]}`)
+	}),
+	"item undrop": write({
+		op: "item.undrop",
+		input: ({ args }) => ({ ref: args[0] }),
+		print: ({ args }) => done(`undropped ${args[0]}`)
+	}),
+	"issue plan": write({
+		op: "issue.plan",
+		input: ({ args }) => ({
+			id: args[0],
+			task: args[1]
+		}),
+		print: ({ args }, i) => done(`planned ${i.id} in ${args[1]}`)
+	}),
+	"issue close": write({
+		op: "issue.close",
+		input: ({ args, opts }) => ({
+			id: args[0],
+			resolution: opts.by ?? ""
+		}),
+		print: (_, i) => done(`closed ${i.id}`)
+	}),
+	"issue reopen": write({
+		op: "issue.reopen",
+		input: ({ args }) => ({ id: args[0] }),
+		print: (_, i) => done(`reopened ${i.id}`)
+	}),
+	"issue archive": write({
+		op: "issue.archive",
+		input: ({ args }) => ({
+			id: args[0],
+			archived: true
+		}),
+		print: (_, i) => done(`archived ${i.id}`)
+	}),
+	"issue unarchive": write({
+		op: "issue.archive",
+		input: ({ args }) => ({
+			id: args[0],
+			archived: false
+		}),
+		print: (_, i) => done(`unarchived ${i.id}`)
+	}),
+	"finding set": write({
+		op: "finding.set",
+		input: ({ args, opts }) => ({
+			id: args[0],
+			status: required(opts, "status", "--status obsolete")
+		}),
+		print: (_, f) => done(`updated ${f.id}`)
+	}),
+	"finding archive": write({
+		op: "finding.archive",
+		input: ({ args }) => ({
+			id: args[0],
+			archived: true
+		}),
+		print: (_, f) => done(`archived ${f.id}`)
+	}),
+	"finding unarchive": write({
+		op: "finding.archive",
+		input: ({ args }) => ({
+			id: args[0],
+			archived: false
+		}),
+		print: (_, f) => done(`unarchived ${f.id}`)
+	}),
+	"ops add": write({
+		op: "ops.add",
+		input: ({ opts }) => ({
+			target: required(opts, "target", "--target github.com/owner/repo"),
+			operation: required(opts, "op", "--op \"push tag v1.2.0\""),
+			result: required(opts, "result", "--result success"),
+			...opts.ref ? { ref: opts.ref } : {}
+		}),
+		print: (_, entry) => done(`logged ${entry.at} ${entry.operation}`)
+	}),
+	"section append": write({
+		op: "section.append",
+		input: ({ args }) => ({
+			ref: args[0],
+			section: args[1],
+			text: args[2]
+		}),
+		print: ({ args }, { file }) => done(`appended to ${args[0]} ## ${args[1].trim()} ${inData(file)}`)
+	}),
+	"decision supersede": write({
+		op: "decision.supersede",
+		input: ({ args, opts }) => ({
+			ref: args[0],
+			by: required(opts, "by", "--by d002")
+		}),
+		print: ({ args }, d) => done(`superseded ${args[0]} by ${d.supersededBy}`)
+	})
+};
+/**
+* Run a writing command. Locally, the operation runs on the hub's files under the write lock. In remote mode it is
+* applied here and put in the hub's outbox, and the command waits for the sync server's answer, which may give a
+* new entry another id; without an answer in time it ends with the write still in the outbox.
+*/
+function runWrite(ctx, spec) {
+	spec.check?.(ctx);
+	const input = spec.input(ctx);
+	if (!remoteMode(ctx.root)) return spec.print(ctx, applyOperation(nodeStorage(ctx.root), spec.op, input, { now: nowMinute() }).value);
+	return hubWriter(ctx.root, process.env, { confirmMs: CONFIRM_MS })(spec.op, input).then((written) => {
+		const code = spec.print(ctx, written.value);
+		for (const line of writtenLines(written)) (line.startsWith("!") ? console.error : console.log)(line);
+		return code;
+	});
+}
 const RUNS = {
 	init: ({ root, args }) => done(`created ${relative(root, initHub(root, args[0]))}`),
 	status: ({ root, opts }) => printStatus(loadHub(root), opts.all ?? false),
@@ -94,59 +842,12 @@ const RUNS = {
 		});
 		return 0;
 	},
-	"repo add": ({ root, args }) => done(`registered ${addRepo(root, args[0], args[1])} ${args[1]}`),
-	"hub add": ({ root, args }) => done(`registered hub ${addHub(root, args[0], args[1])} ${args[1]}`),
-	"session start": ({ root, opts }) => {
-		const session = startSession(root, {
-			id: opts.id,
-			agent: opts.agent ?? "manual",
-			cwd: process.cwd(),
-			delegatedFrom: opts["delegated-from"],
-			handoffFrom: opts["handoff-from"]
-		});
-		return done(`started ${session.id}${session.actions.length ? ` with ${session.actions.length} carried actions` : ""}`);
-	},
-	"session handoff": ({ root, args, opts }) => {
-		const session = handoffSession(root, sessionOf(opts), args[0]);
-		return done(`${session.id} took over ${session.actions.filter((a) => a.status === "todo" || a.status === "doing").length} actions from ${args[0]}`);
-	},
 	"session show": ({ root, args, opts }) => {
 		const id = sessionOf(opts, args[0]);
 		const session = readSession(root, id);
 		if (!session) throw new WriteError(`session ${id} not found; start one with "mainflow session start"`);
 		return done(sessionBriefing(root, session, { cli: CLI }));
 	},
-	"session set": ({ root, args, opts }) => done(`updated ${args[0]} (${setSessionStatus(root, args[0], required(opts, "status", "--status paused")).status})`),
-	"session end": ({ root, args, opts }) => done(`ended ${setSessionStatus(root, sessionOf(opts, args[0]), "ended").id}`),
-	"session archive": ({ root, args }) => done(`archived ${setSessionArchived(root, args[0], true).id}`),
-	"session unarchive": ({ root, args }) => done(`unarchived ${setSessionArchived(root, args[0], false).id}`),
-	"action add": ({ root, args, opts }) => {
-		const ref = addAction(root, sessionOf(opts), {
-			do: args[0],
-			serves: list(opts.serves),
-			before: opts.before
-		});
-		done(`created ${ref}`);
-		return remindDuplicates(root, ref);
-	},
-	"action set": ({ root, args, opts }) => {
-		const ref = actionRef(opts, args[0]);
-		const blockedBy = opts.reason ? {
-			reason: opts.reason,
-			...opts["waiting-for"] ? { waitingFor: opts["waiting-for"] } : {},
-			...opts.until ? { until: opts.until } : {}
-		} : void 0;
-		if (!blockedBy && (opts["waiting-for"] || opts.until)) throw new WriteError("--waiting-for and --until need --reason, e.g. --status blocked --reason \"等 schema 定案\"");
-		done(`updated ${ref} (${updateAction(root, ref, {
-			status: opts.status,
-			do: opts.text,
-			serves: opts.serves === void 0 ? void 0 : list(opts.serves),
-			before: opts.before,
-			note: opts.note,
-			blockedBy
-		}).status})`);
-		return opts.status === "doing" ? remindDuplicates(root, ref) : 0;
-	},
 	wait: ({ root, args, opts }) => waitUntil(root, args[0], opts),
 	hook: ({ args }) => {
 		let input = "";
@@ -163,100 +864,17 @@ const RUNS = {
 			if (fallback) console.log(fallback);
 			return 0;
 		}
-		const { stdout, error } = runHook(args[0], args[1], {
+		return runHook(args[0], args[1], {
 			payload,
 			envFile: process.env.CLAUDE_ENV_FILE,
 			projectDir: process.env.CLAUDE_PROJECT_DIR,
 			cli: CLI,
 			startUi: startUiInBackground
+		}).then(({ stdout, error }) => {
+			if (error) console.error(error);
+			if (stdout) console.log(stdout);
+			return 0;
 		});
-		if (error) console.error(error);
-		if (stdout) console.log(stdout);
-		return 0;
-	},
-	"new mainline": ({ root, args, opts }) => {
-		const { id, dir } = createMainline(root, {
-			slug: args[0],
-			title: required(opts, "title", "--title \"重建 mainline 任務管理\"")
-		});
-		return done(`created ${id} ${relative(root, join(dir, MAINLINE_FILE))}`);
-	},
-	"new task": ({ root, args, opts }) => {
-		const { ref, dir } = createTask(root, args[0], {
-			slug: args[1],
-			title: required(opts, "title", "--title \"定義資料格式 schema\""),
-			kind: opts.kind,
-			parent: opts.parent,
-			repo: opts.repo
-		});
-		return done(`created ${ref} ${relative(root, join(dir, TASK_FILE))}`);
-	},
-	"new decision": ({ root, args, opts }) => {
-		const { ref, file } = createDecision(root, args[0], {
-			slug: args[1],
-			title: required(opts, "title", "--title \"以文字檔為準\""),
-			status: opts.status,
-			by: opts.by,
-			basis: opts.basis,
-			affects: opts.affects ? list(opts.affects) : void 0
-		});
-		return done(`created ${ref} ${relative(root, file)}`);
-	},
-	"new issue": ({ root, args, opts }) => {
-		const { id, file } = createIssue(root, {
-			slug: args[0],
-			title: required(opts, "title", "--title \"重試不穩定的 VM\""),
-			origin: opts.origin,
-			labels: opts.labels ? list(opts.labels) : void 0
-		});
-		return done(`created ${id} ${relative(root, file)}`);
-	},
-	"new finding": ({ root, args, opts }) => {
-		const { id, file } = createFinding(root, {
-			slug: args[0],
-			title: required(opts, "title", "--title \"先 await 再寫入 state\""),
-			origin: opts.origin,
-			labels: opts.labels ? list(opts.labels) : void 0
-		});
-		return done(`created ${id} ${relative(root, file)}`);
-	},
-	"mainline set": ({ root, args, opts }) => {
-		const m = setMainlineStatus(root, args[0], required(opts, "status", "--status active"));
-		return done(`updated ${m.id} (${m.status})`);
-	},
-	"mainline archive": ({ root, args }) => done(`archived ${setArchived(root, args[0], true).id}`),
-	"mainline unarchive": ({ root, args }) => done(`unarchived ${setArchived(root, args[0], false).id}`),
-	"criterion check": ({ root, args, opts }) => {
-		setCriterion(root, args[0], true, opts.evidence);
-		return done(`checked ${args[0]}`);
-	},
-	"criterion uncheck": ({ root, args }) => {
-		setCriterion(root, args[0], false);
-		return done(`unchecked ${args[0]}`);
-	},
-	"criterion set": ({ root, args, opts }) => {
-		setCriterionText(root, args[0], {
-			text: opts.text,
-			doneWhen: opts["done-when"]
-		});
-		return done(`updated ${args[0]}`);
-	},
-	"task set": ({ root, args, opts }) => {
-		const blockedBy = opts.reason ? {
-			reason: opts.reason,
-			...opts["waiting-for"] ? { waitingFor: opts["waiting-for"] } : {},
-			...opts.signal ? { signal: opts.signal } : {}
-		} : void 0;
-		const t = updateTask(root, args[0], {
-			status: opts.status,
-			repo: opts.repo,
-			blockedBy,
-			branch: opts.branch,
-			worktree: opts.worktree,
-			base: opts.base,
-			merge: opts.merge
-		});
-		return done(`updated ${args[0]} (${t.status})`);
 	},
 	"task show": ({ root, args }) => {
 		const { mainline, task } = findTask(loadHub(root), args[0]);
@@ -270,79 +888,39 @@ const RUNS = {
 		for (const link of task.links ?? []) console.log(`  ${link.rel} → ${link.to}${link.note ? `  ${link.note}` : ""}`);
 		return done(`${task.checklist.length} checklist items`);
 	},
-	"item check": ({ root, args, opts }) => {
-		setChecklistItem(root, args[0], true, opts.evidence);
-		return done(`checked ${args[0]}`);
-	},
-	"item uncheck": ({ root, args }) => {
-		setChecklistItem(root, args[0], false);
-		return done(`unchecked ${args[0]}`);
-	},
-	"decision accept": ({ root, args, opts }) => done(`accepted ${args[0]} (${acceptDecision(root, args[0], {
-		by: opts.by,
-		basis: opts.basis
-	}).decidedAt})`),
-	"item drop": ({ root, args, opts }) => {
-		dropChecklistItem(root, args[0], {
-			supersededBy: opts.by,
-			note: opts.note
-		});
-		return done(`dropped ${args[0]}`);
-	},
-	"item undrop": ({ root, args }) => {
-		undropChecklistItem(root, args[0]);
-		return done(`undropped ${args[0]}`);
-	},
-	"issue plan": ({ root, args }) => done(`planned ${planIssue(root, args[0], args[1]).id} in ${args[1]}`),
-	"issue close": ({ root, args, opts }) => done(`closed ${closeIssue(root, args[0], opts.by ?? "").id}`),
-	"issue reopen": ({ root, args }) => done(`reopened ${reopenIssue(root, args[0]).id}`),
-	"issue archive": ({ root, args }) => done(`archived ${setIssueArchived(root, args[0], true).id}`),
-	"issue unarchive": ({ root, args }) => done(`unarchived ${setIssueArchived(root, args[0], false).id}`),
 	"issue list": ({ root, opts }) => {
 		const shown = loadHub(root).issues.filter((i) => opts.all || i.status !== "closed");
 		for (const i of shown) console.log(`  ${i.id}  ${i.status.padEnd(7)}  ${i.title}${i.plannedIn ? `  → ${i.plannedIn}` : ""}${i.origin ? `  (from ${i.origin})` : ""}`);
 		return done(`${shown.length} issues`);
 	},
-	"finding set": ({ root, args, opts }) => done(`updated ${setFindingStatus(root, args[0], required(opts, "status", "--status obsolete")).id}`),
-	"finding archive": ({ root, args }) => done(`archived ${setFindingArchived(root, args[0], true).id}`),
-	"finding unarchive": ({ root, args }) => done(`unarchived ${setFindingArchived(root, args[0], false).id}`),
 	"finding list": ({ root, opts }) => {
 		const shown = loadHub(root).findings.filter((f) => opts.all || f.status === "valid");
 		for (const f of shown) console.log(`  ${f.id}  ${f.created}  ${f.title}${f.labels?.length ? `  [${f.labels.join(", ")}]` : ""}`);
 		return done(`${shown.length} findings`);
 	},
-	"ops add": ({ root, opts }) => {
-		const entry = appendOps(root, {
-			target: required(opts, "target", "--target github.com/owner/repo"),
-			operation: required(opts, "op", "--op \"push tag v1.2.0\""),
-			result: required(opts, "result", "--result success"),
-			...opts.ref ? { ref: opts.ref } : {}
-		});
-		return done(`logged ${entry.at} ${entry.operation}`);
-	},
 	"ops list": ({ root, opts }) => {
 		const covers = (ref) => !opts.ref || ref !== void 0 && (ref === opts.ref || ref.startsWith(`${opts.ref}/`) || ref.startsWith(`${opts.ref}#`));
 		const shown = loadHub(root).ops.filter((o) => (!opts.month || o.at.startsWith(opts.month)) && covers(o.ref));
 		for (const o of shown) console.log(`  ${o.at}  ${o.target}  ${o.operation}  ${o.result}${o.ref ? `  ${o.ref}` : ""}`);
 		return done(`${shown.length} operations`);
 	},
-	"decision supersede": ({ root, args, opts }) => {
-		const d = supersedeDecision(root, args[0], required(opts, "by", "--by d002"));
-		return done(`superseded ${args[0]} by ${d.supersededBy}`);
-	},
 	retro: ({ root, args, opts }) => {
-		const report = retroReport(root, args[0]);
-		return done(opts.json ? JSON.stringify(report, null, 2) : retroText(report));
+		const print = (report) => done(opts.json ? JSON.stringify(report, null, 2) : retroText(report));
+		const receiver = receiverFromEnv(process.env);
+		return receiver ? retroReportFromReceiver(root, args[0], receiver).then(print) : print(retroReport(root, args[0]));
 	},
 	"decision list": ({ root, args }) => {
 		const mainline = findMainline(loadHub(root), args[0]);
 		for (const d of mainline.decisions) console.log(`  ${mainline.id}/${d.id}  ${d.status.padEnd(10)}  ${d.title}`);
 		return done(`${mainline.decisions.length} decisions`);
-	}
+	},
+	sync: ({ root }) => syncRun(root),
+	"sync flush": ({ root, opts }) => syncFlush(root, opts.hook ?? false),
+	"sync status": ({ root }) => syncStatus(root)
 };
 const COMMANDS = Object.fromEntries(Object.keys(COMMAND_SPECS).map((name) => [name, {
 	...COMMAND_SPECS[name],
-	run: RUNS[name]
+	run: name in WRITES ? (ctx) => runWrite(ctx, WRITES[name]) : RUNS[name]
 }]));
 const USAGE = [
 	"Usage: mainflow <command>",
@@ -354,11 +932,28 @@ const USAGE = [
 	"  --version  Print the version",
 	"  --help     Print this message"
 ].join("\n");
+/**
+* `argv` with `--` put before the last argument of a command whose last argument is literal text, unless the
+* caller already put it there, so the parser takes text such as "- 完成" as an argument and not as options.
+*/
+function literalLast(argv) {
+	for (const [name, spec] of Object.entries(COMMAND_SPECS)) {
+		if (!spec.literalLast) continue;
+		const words = name.split(" ");
+		const at = words.length + spec.args - 1;
+		if (words.every((word, i) => argv[i] === word) && argv.length > at && !argv.slice(0, at + 1).includes("--")) return [
+			...argv.slice(0, at),
+			"--",
+			...argv.slice(at)
+		];
+	}
+	return argv;
+}
 function run(argv, cwd) {
 	let parsed;
 	try {
 		parsed = parseArgs({
-			args: argv,
+			args: literalLast(argv),
 			allowPositionals: true,
 			options: OPTIONS
 		});
@@ -384,20 +979,25 @@ function run(argv, cwd) {
 		root = found;
 	}
 	try {
-		return command.run({
+		const exit = command.run({
 			root,
 			args,
 			opts
 		});
+		return typeof exit === "number" ? exit : exit.catch(reportError);
 	} catch (error) {
-		if (error instanceof HubError) {
-			printProblems(error.problems);
-			return fail(error.message);
-		}
-		if (error instanceof WriteError) return fail(`✗ ${error.message}`);
-		throw error;
+		return reportError(error);
 	}
 }
+/** A refused write or an unreadable hub ends the command with its message; anything else is a bug and is thrown. */
+function reportError(error) {
+	if (error instanceof HubError) {
+		printProblems(error.problems);
+		return fail(error.message);
+	}
+	if (error instanceof WriteError) return fail(`✗ ${error.message}`);
+	throw error;
+}
 function done(line) {
 	console.log(line);
 	return 0;
@@ -546,6 +1146,10 @@ function printProblems(problems, mark = "✗") {
 	for (const problem of problems) console.error(`${mark} ${problem.file}${problem.field ? ` › ${problem.field}` : ""}: ${problem.message}`);
 }
 const entry = process.argv[1];
-if (entry && realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url))) process.exitCode = run(process.argv.slice(2), process.cwd());
+if (entry && realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url))) {
+	const exit = run(process.argv.slice(2), process.cwd());
+	if (typeof exit === "number") process.exitCode = exit;
+	else exit.then((code) => process.exitCode = code);
+}
 //#endregion
 export { run };