mainflow 0.12.0 → 0.13.1

package/dist/cli.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
-import { $ as HubError, A as readSession, C as setMainlineStatus, D as addAction, E as updateTask, F as startSession, G as closeIssue, J as planIssue, K as createFinding, L as updateAction, N as setSessionStatus, Q as setIssueArchived, R as sessionBriefing, S as setCriterion, T as supersedeDecision, W as appendOps, X as setFindingArchived, Y as reopenIssue, Z as setFindingStatus, _ as createTask, at as MAINLINE_FILE, b as setArchived, ct as WriteError, dt as findHubRoot, et as loadHub, f as acceptDecision, g as createMainline, h as createDecision, j as setSessionArchived, l as migrateHub, m as addRepo, ot as TASK_FILE, p as addHub, q as createIssue, v as dropChecklistItem, x as setChecklistItem, y as initHub } from "./host-Dwf1wLMd.js";
+import { $ as setFindingStatus, A as addAction, C as setCriterionText, D as updateTask, E as supersedeDecision, F as setSessionArchived, J as createFinding, K as appendOps, L as setSessionStatus, M as handoffSession, O as sessionBriefing, P as readSession, Q as setFindingArchived, S as setCriterion, V as updateAction, X as planIssue, Y as createIssue, Z as reopenIssue, _ as createTask, b as setArchived, ct as TASK_FILE, et as setIssueArchived, f as acceptDecision, g as createMainline, h as createDecision, l as migrateHub, m as addRepo, nt as loadHub, p as addHub, pt as findHubRoot, q as closeIssue, st as MAINLINE_FILE, tt as HubError, ut as WriteError, v as dropChecklistItem, w as setMainlineStatus, x as setChecklistItem, y as initHub, z as startSession } from "./host-mlpW8M1s.js";
+import { N as parseRef, P as refExample } from "./dist-BQmXEfAf.js";
 import { t as listProgress } from "./progress-1BfPg2zN.js";
 import { COMMAND_SPECS, OPTIONS } from "./facts.js";
 import { runHook } from "./hooks.js";
-import { l as CLI_VERSION, r as launchUi, s as startUiInBackground } from "./launch-D5K564tw.js";
+import { l as CLI_VERSION, r as launchUi, s as startUiInBackground } from "./launch-CJYDVfE9.js";
 import { readFileSync, realpathSync } from "node:fs";
 import { join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -54,6 +55,10 @@ const RUNS = {
 		});
 		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);
@@ -155,6 +160,13 @@ const RUNS = {
 		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,
@@ -172,6 +184,18 @@ const RUNS = {
 		});
 		return done(`updated ${args[0]} (${t.status})`);
 	},
+	"task show": ({ root, args }) => {
+		const { mainline, task } = findTask(loadHub(root), args[0]);
+		console.log(`${mainline.id}/${task.id}  ${task.status.padEnd(8)}  ${task.kind}  ${task.title}`);
+		if (task.checklist.length === 0) console.log("  (no checklist items)");
+		for (const c of task.checklist) {
+			const mark = c.done ? "[x]" : "[ ]";
+			const state = c.dropped ? "  (dropped)" : "";
+			console.log(`  ${mark} ${c.id}  ${c.text}${state}`);
+		}
+		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]}`);
@@ -216,13 +240,18 @@ const RUNS = {
 		return done(`logged ${entry.at} ${entry.operation}`);
 	},
 	"ops list": ({ root, opts }) => {
-		const shown = loadHub(root).ops.filter((o) => !opts.month || o.at.startsWith(opts.month));
+		const shown = loadHub(root).ops.filter((o) => (!opts.month || o.at.startsWith(opts.month)) && (!opts.ref || o.ref === opts.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}`);
+	},
+	"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`);
 	}
 };
 const COMMANDS = Object.fromEntries(Object.keys(COMMAND_SPECS).map((name) => [name, {
@@ -300,6 +329,24 @@ function sessionOf(opts, arg) {
 	return id;
 }
 const list = (value) => (value ?? "").split(",").map((v) => v.trim()).filter(Boolean);
+/** The mainline a reference names; throws with the same message resolve.ts gives when it is missing. */
+function findMainline(hub, id) {
+	const mainline = hub.mainlines.find((m) => m.id === id);
+	if (!mainline) throw new WriteError(`mainline ${id} not found; run "mainflow status --all" to list mainlines`);
+	return mainline;
+}
+/** The task a `m/t` reference names, with the mainline it sits in. */
+function findTask(hub, refInput) {
+	const ref = parseRef(refInput);
+	if (ref?.kind !== "task") throw new WriteError(`expected a task reference like ${refExample("task")}, got "${refInput}"`);
+	const mainline = findMainline(hub, ref.mainline);
+	const task = mainline.tasks.find((t) => t.id === ref.task);
+	if (!task) throw new WriteError(`task ${refInput} not found`);
+	return {
+		mainline,
+		task
+	};
+}
 function required(opts, name, example) {
 	const value = opts[name];
 	if (!value) throw new WriteError(`--${name} is required, e.g. ${example}`);

package/dist/facts.d.ts

@@ -73,6 +73,12 @@ export declare const COMMAND_SPECS: {
     readonly args: 0;
     readonly needsHub: true;
   };
+  readonly 'session handoff': {
+    readonly usage: 'session handoff <session> [--session <session>]';
+    readonly summary: 'Take over the unfinished actions of another session into this one';
+    readonly args: 1;
+    readonly needsHub: true;
+  };
   readonly 'session show': {
     readonly usage: 'session show [session]';
     readonly summary: 'Print the briefing a hook would give this session';
@@ -183,12 +189,24 @@ export declare const COMMAND_SPECS: {
     readonly args: 1;
     readonly needsHub: true;
   };
+  readonly 'criterion set': {
+    readonly usage: 'criterion set <m#r> [--text <text>] [--done-when <text>]';
+    readonly summary: 'Rewrite a criterion\'s text or doneWhen; done stays as it is (use criterion check/uncheck)';
+    readonly args: 1;
+    readonly needsHub: true;
+  };
   readonly 'task set': {
     readonly usage: 'task set <m/t> [--status] [--reason --waiting-for --signal] [--repo] [--branch --worktree --base --merge]';
     readonly summary: 'Change status, repository or branch state; --status blocked needs --reason';
     readonly args: 1;
     readonly needsHub: true;
   };
+  readonly 'task show': {
+    readonly usage: 'task show <m/t>';
+    readonly summary: 'Print a task: status, kind, checklist and links';
+    readonly args: 1;
+    readonly needsHub: true;
+  };
   readonly 'item check': {
     readonly usage: 'item check <m/t#c> --evidence <evidence>';
     readonly summary: 'Check an item with evidence';
@@ -280,8 +298,8 @@ export declare const COMMAND_SPECS: {
     readonly needsHub: true;
   };
   readonly 'ops list': {
-    readonly usage: 'ops list [--month YYYY-MM]';
-    readonly summary: 'List logged external operations';
+    readonly usage: 'ops list [--month YYYY-MM] [--ref <ref>]';
+    readonly summary: 'List logged external operations, optionally filtered by month or by the exact ref that was logged';
     readonly args: 0;
     readonly needsHub: true;
   };
@@ -291,6 +309,12 @@ export declare const COMMAND_SPECS: {
     readonly args: 1;
     readonly needsHub: true;
   };
+  readonly 'decision list': {
+    readonly usage: 'decision list <m>';
+    readonly summary: 'List a mainline\'s decisions';
+    readonly args: 1;
+    readonly needsHub: true;
+  };
 };
 export type CommandName = keyof typeof COMMAND_SPECS;
 export declare const OPTIONS: {
@@ -340,6 +364,9 @@ export declare const OPTIONS: {
   readonly text: {
     readonly type: 'string';
   };
+  readonly 'done-when': {
+    readonly type: 'string';
+  };
   readonly serves: {
     readonly type: 'string';
   };

package/dist/facts.js

@@ -49,6 +49,12 @@ const COMMAND_SPECS = {
 		args: 0,
 		needsHub: true
 	},
+	"session handoff": {
+		usage: "session handoff <session> [--session <session>]",
+		summary: "Take over the unfinished actions of another session into this one",
+		args: 1,
+		needsHub: true
+	},
 	"session show": {
 		usage: "session show [session]",
 		summary: "Print the briefing a hook would give this session",
@@ -159,12 +165,24 @@ const COMMAND_SPECS = {
 		args: 1,
 		needsHub: true
 	},
+	"criterion set": {
+		usage: "criterion set <m#r> [--text <text>] [--done-when <text>]",
+		summary: "Rewrite a criterion's text or doneWhen; done stays as it is (use criterion check/uncheck)",
+		args: 1,
+		needsHub: true
+	},
 	"task set": {
 		usage: "task set <m/t> [--status] [--reason --waiting-for --signal] [--repo] [--branch --worktree --base --merge]",
 		summary: "Change status, repository or branch state; --status blocked needs --reason",
 		args: 1,
 		needsHub: true
 	},
+	"task show": {
+		usage: "task show <m/t>",
+		summary: "Print a task: status, kind, checklist and links",
+		args: 1,
+		needsHub: true
+	},
 	"item check": {
 		usage: "item check <m/t#c> --evidence <evidence>",
 		summary: "Check an item with evidence",
@@ -256,8 +274,8 @@ const COMMAND_SPECS = {
 		needsHub: true
 	},
 	"ops list": {
-		usage: "ops list [--month YYYY-MM]",
-		summary: "List logged external operations",
+		usage: "ops list [--month YYYY-MM] [--ref <ref>]",
+		summary: "List logged external operations, optionally filtered by month or by the exact ref that was logged",
 		args: 0,
 		needsHub: true
 	},
@@ -266,6 +284,12 @@ const COMMAND_SPECS = {
 		summary: "Mark a decision as replaced by another",
 		args: 1,
 		needsHub: true
+	},
+	"decision list": {
+		usage: "decision list <m>",
+		summary: "List a mainline's decisions",
+		args: 1,
+		needsHub: true
 	}
 };
 const OPTIONS = {
@@ -287,6 +311,7 @@ const OPTIONS = {
 	"delegated-from": { type: "string" },
 	"handoff-from": { type: "string" },
 	text: { type: "string" },
+	"done-when": { type: "string" },
 	serves: { type: "string" },
 	before: { type: "string" },
 	note: { type: "string" },

package/dist/hooks.js

@@ -1,4 +1,4 @@
-import { $ as HubError, A as readSession, B as decorateReply, H as headerLine, M as setSessionInfo, N as setSessionStatus, O as ensureSession, P as settleSession, R as sessionBriefing, U as mayDecorate, V as endsWithMarker, dt as findHubRoot, et as loadHub, ft as worktreesOf, i as hostName, lt as DATA_DIR, ut as currentBranch, z as turnReminder } from "./host-Dwf1wLMd.js";
+import { G as mayDecorate, H as decorateReply, I as setSessionInfo, L as setSessionStatus, O as sessionBriefing, P as readSession, R as settleSession, U as endsWithMarker, W as headerLine, dt as DATA_DIR, ft as currentBranch, i as hostName, j as ensureSession, k as turnReminder, mt as worktreesOf, nt as loadHub, pt as findHubRoot, tt as HubError } from "./host-mlpW8M1s.js";
 import { appendFileSync, existsSync, readFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 //#region src/hooks.ts
@@ -75,21 +75,45 @@ const displayReply = (root, { payload }) => {
 		displayContent: shown
 	} });
 };
+/** Mainline ids a reply mentions, e.g. m001 in `m001/t003`; not inside a longer word or path. */
+const MAINLINE_MENTION = /(?<![\w/#.[-])(m\d{3})(?![\w\]])/g;
+/** The open mainlines the text mentions; loads the hub only when the text mentions one. */
+function openMainlinesIn(root, text) {
+	const mentioned = new Set([...text.matchAll(MAINLINE_MENTION)].map((m) => m[1]));
+	if (mentioned.size === 0) return [];
+	return loadHub(root, { remotes: false }).mainlines.filter((m) => mentioned.has(m.id) && !m.archivedAt && (m.status === "active" || m.status === "planning")).map((m) => m.id);
+}
+/**
+* What to ask for when a turn ends without its header line: the header itself when an action is in progress, or
+* an action first when the queue is empty but the reply talks about an open mainline, since the header only names
+* the session's own action in progress. Null when there is nothing to ask for.
+*/
+function missingHeaderRequest(root, { payload, cli }) {
+	if (!payload.session_id || payload.stop_hook_active) return null;
+	const message = payload.last_assistant_message ?? "";
+	if (endsWithMarker(message)) return null;
+	const session = readSession(root, claudeCodeSessionId(payload.session_id));
+	const header = headerLine(session);
+	if (header) return `[mainflow] 這一輪最後一則回覆的最後一行不是標頭。請只回一則內容為「${header}」的訊息，不加其他文字。`;
+	if (session && session.actions.length > 0) return null;
+	const mainlines = openMainlinesIn(root, message);
+	if (mainlines.length === 0) return null;
+	return `[mainflow] 這一輪的回覆提到 ${mainlines.join("、")}，但這場會話沒有行動，所以回覆結尾沒有標頭。這一輪若在推進它，先用 ${cli} action add "<做法>" --serves <m/t#c> 列出行動並用 ${cli} action set <a編號> --status doing 標為進行中，或用 ${cli} session handoff <會話> 接手上一場沒做完的行動；再只回一則內容為「▸ <m/t> · <a編號>」的訊息，不加其他文字。只是提到、沒有推進時，不必處理。`;
+}
 /**
-* Stop: settle the session, then ask for the header line when a session with an action in progress ended its
-* turn without one. Only the model knows which message closes a turn, so the header is its to write; this makes
-* a forgotten one cost a single extra message. stop_hook_active stops it from asking twice in a row.
+* Stop: ask for what the turn's header needs, then settle the session. Only the model knows which message closes a
+* turn, so the header is its to write; this makes a forgotten one cost a single extra message. stop_hook_active
+* stops it from asking twice in a row. A session asked to list an action is not settled yet: settling removes a
+* session with no actions, and the action it is asked to add needs the session to exist.
 */
 const settleAndCheckMarker = (root, context) => {
-	settleOnEnd(root, context);
-	const { payload } = context;
-	if (!payload.session_id || payload.stop_hook_active || endsWithMarker(payload.last_assistant_message ?? "")) return null;
-	const header = headerLine(readSession(root, claudeCodeSessionId(payload.session_id)));
-	if (!header) return null;
-	return JSON.stringify({ hookSpecificOutput: {
+	const request = missingHeaderRequest(root, context);
+	const session = context.payload.session_id ? readSession(root, claudeCodeSessionId(context.payload.session_id)) : null;
+	if (!request || session && session.actions.length > 0) settleOnEnd(root, context);
+	return request ? JSON.stringify({ hookSpecificOutput: {
 		hookEventName: "Stop",
-		additionalContext: `[mainflow] 這一輪最後一則回覆的最後一行不是標頭。請只回一則內容為「${header}」的訊息，不加其他文字。`
-	} });
+		additionalContext: request
+	} }) : null;
 };
 const CLAUDE_CODE_EVENTS = {
 	"session-start": (root, { payload, envFile, cli, startUi }) => {

package/dist/{host-Dwf1wLMd.js → host-mlpW8M1s.js}

@@ -32,10 +32,11 @@ function currentBranch(cwd) {
 }
 /**
 * The hub for `cwd`: the first directory upwards holding `.mainflow/config.yaml`, except that a linked
-* worktree's checkout of a hub resolves to the same hub in the main working tree. A worktree is another
-* checkout of the same repository, so without this every worktree would write its own copy of the hub and
-* the copies would conflict on merge. A different hub nested inside a worktree (a scratch hub under tmp/,
-* say) has no counterpart in the main tree and stays as found.
+* worktree's checkout of a hub at the repository root resolves to the same hub in the main working tree.
+* A worktree is another checkout of the same repository, so without this every worktree would write its
+* own copy of the hub and the copies would conflict on merge. A hub below the root (a sample hub under
+* examples/, a scratch hub under tmp/) stays as found: it is data the worktree's own branch owns, and
+* mapping it would let tests and migrations in the worktree write the main tree's copy.
 */
 function findHubRoot(cwd) {
 	let found = null;
@@ -48,8 +49,8 @@ function findHubRoot(cwd) {
 	}
 	const trees = worktreesOf(cwd);
 	if (!trees || trees.main === trees.current) return found;
-	const counterpart = join(trees.main, relative(trees.current, found ?? trees.current));
-	return isHub(counterpart) ? counterpart : found;
+	if (found && found !== trees.current) return found;
+	return isHub(trees.main) ? trees.main : found;
 }
 function subdirs(dir) {
 	if (!existsSync(dir)) return [];
@@ -846,7 +847,7 @@ function checkReferences(input) {
 		});
 	}
 }
-const isOpen = (kind, status) => !CLOSED_STATUS[kind].includes(status);
+const isOpen$2 = (kind, status) => !CLOSED_STATUS[kind].includes(status);
 /**
 * What a reader without the conversation needs to pick the work up: every open task says what it is for
 * and when it is done, and every open criterion or item says what has to be true to check it. Closed
@@ -871,10 +872,10 @@ function contentGaps(mainline, tasks) {
 			});
 		});
 	};
-	const mainlineOpen = isOpen("mainline", mainline.status);
+	const mainlineOpen = isOpen$2("mainline", mainline.status);
 	list(mainline.file, "criteria", mainline.criteria, mainlineOpen);
 	for (const task of tasks) {
-		const open = mainlineOpen && isOpen("task", task.status);
+		const open = mainlineOpen && isOpen$2("task", task.status);
 		list(task.file, "checklist", task.checklist, open);
 		if (!open) continue;
 		for (const section of TASK_REQUIRED_SECTIONS) if (!sectionText(task.body, section)) gaps.push({
@@ -1138,82 +1139,6 @@ function decorateReply(text, context) {
 /** Cheap test for text that decorateReply could change, so a display hook can skip loading the hub. */
 const mayDecorate = (text) => /m\d{3}|[if]\d{3}|\.mainflow\/mainlines/.test(text) || endsWithMarker(text);
 //#endregion
-//#region ../core/dist/briefing.js
-function describe(root, ref) {
-	const parsed = parseRef(ref);
-	if (parsed?.kind !== "checklistItem") return null;
-	try {
-		const mainline = readFrontMatter(mainlineFile(root, parsed.mainline), mainlineSchema).data;
-		const task = readFrontMatter(taskFile(root, parsed.mainline, parsed.task), taskSchema).data;
-		const item = task.checklist.find((c) => c.id === parsed.item);
-		if (!item) return null;
-		return {
-			ref,
-			text: item.text,
-			checked: item.done,
-			where: `${mainline.id} ${mainline.title} › ${task.id} ${task.title}`
-		};
-	} catch {
-		return null;
-	}
-}
-/** Problems in a session's queue that the executor should fix before going on, each with the command that fixes it. */
-function queueWarnings(root, session, cli) {
-	const warnings = [];
-	const doing = session.actions.filter((a) => a.status === "doing");
-	if (doing.length > 1) warnings.push(`同時有 ${doing.length} 個進行中的行動（${doing.map((a) => a.id).join("、")}）。一次只推進一個，其餘改回 todo。`);
-	for (const action of doing) {
-		const served = action.serves.map((ref) => describe(root, ref));
-		if (served.some((s) => s === null)) warnings.push(`${action.id} 服務的項目有的已不存在，用 ${cli} action set ${action.id} --serves <m/t#c> 改正。`);
-		else if (served.length > 0 && served.every((s) => s.checked)) warnings.push(`${action.id} 服務的項目都已勾選。做完了就執行 ${cli} action set ${action.id} --status done。`);
-	}
-	const next = session.actions.find((a) => a.status === "todo");
-	if (doing.length === 0 && next) warnings.push(`下一個行動是 ${next.id}。開始前先執行 ${cli} action set ${next.id} --status doing。`);
-	return warnings;
-}
-const current = (session) => session.actions.find((a) => a.status === "doing");
-const servedLine = (root, action) => action.serves.map((ref) => {
-	const s = describe(root, ref);
-	return s ? `${ref} ${s.text}（${s.where}）` : `${ref}（找不到這個項目）`;
-}).join("；") || "沒有指定服務的 checklist 項目";
-/** Full briefing for the start of a session, after resuming, clearing or compacting. */
-function sessionBriefing(root, session, options) {
-	const { cli } = options;
-	const lines = [`[mainflow] 這場會話的 id 是 ${session.id}${options.envNote ? `（${options.envNote}）` : ""}。`];
-	const doing = current(session);
-	const upcoming = session.actions.filter((a) => a.status === "todo").slice(0, 3);
-	if (session.actions.length === 0) {
-		const active = loadHub(root).mainlines.filter((m) => !m.archivedAt && (m.status === "active" || m.status === "planning"));
-		lines.push("這場會話還沒有行動。");
-		if (active.length > 0) {
-			lines.push("進行中的主脈絡：");
-			for (const m of active) lines.push(`- ${m.id} ${m.title}`);
-			lines.push(`要推進其中一個時，先用 ${cli} status 與它的任務 checklist 決定要做什麼，再列出行動。`);
-		}
-	} else {
-		lines.push(doing ? `目前行動：${doing.id} ${doing.do}` : "目前沒有進行中的行動。");
-		if (doing) lines.push(`服務：${servedLine(root, doing)}`);
-		if (upcoming.length > 0) lines.push(`接下來：${upcoming.map((a) => `${a.id} ${a.do}`).join("、")}`);
-	}
-	const warnings = queueWarnings(root, session, cli);
-	if (warnings.length > 0) lines.push("需要處理：", ...warnings.map((w) => `- ${w}`));
-	lines.push("工作方式：", `- 開始一件新工作前，先列進佇列：${cli} action add "<做法>" --serves <m/t#c>。`, `- 開始做標 doing，做完標 done：${cli} action set <a編號> --status doing。`, `- 勾選 checklist 要附證據：${cli} item check <m/t#c> --evidence <commit、檔案:行號或指令輸出>。`, `- 內容直接寫進檔案：意圖或需求寫進 mainline.md 的內文，任務的目標與完成定義寫進 task.md，選擇寫成決策（${cli} new decision <m> <slug> --title <標題> 建檔後再寫內文）。`, `- 改完 .mainflow/ 的檔案跑 ${cli} check，把它列出的問題修到沒有。`, "- 用完其他 skill 或子流程後，回到上面的目前行動再繼續。", "- 要開主脈絡、拆任務、記決策、延後或收尾時，用 mainflow skill，它依序帶過並告訴你資訊該寫在哪裡。");
-	return lines.join("\n");
-}
-/** One or two lines for every user turn; null when the session has no actions to anchor to. */
-function turnReminder(root, session, options) {
-	if (session.actions.length === 0) return null;
-	const doing = current(session);
-	const open = session.actions.filter((a) => a.status === "todo" || a.status === "doing");
-	const head = doing ? `[mainflow] 目前行動 ${doing.id} ${doing.do}，服務 ${doing.serves.join("、") || "（未指定）"}。這一輪的工作若不屬於它，先調整佇列再做。` : open.length === 0 ? `[mainflow] ${session.id} 的行動都已結束。繼續工作前先用 ${options.cli} action add 列出下一個行動。` : `[mainflow] ${session.id} 目前沒有進行中的行動。`;
-	const header = headerLine(session);
-	return [
-		head,
-		...header ? [`- 這一輪最後一則回覆的最後一行寫「${header}」，回覆範例等其他內容都放在它前面。有顯示 hook 時，它會換成標題與連結。`] : [],
-		...queueWarnings(root, session, options.cli).map((w) => `- ${w}`)
-	].join("\n");
-}
-//#endregion
 //#region ../core/dist/sessions.js
 const sessionsDir = (root) => join(root, DATA_DIR, "local", "sessions");
 const sessionFile = (root, id) => join(sessionsDir(root), `${id}.yaml`);
@@ -1290,8 +1215,44 @@ function requireServes(root, serves) {
 		if (!readFrontMatter(taskFile(root, parsed.mainline, parsed.task), taskSchema).data.checklist.some((c) => c.id === parsed.item)) throw new WriteError(`checklist item ${ref} not found`);
 	}
 }
+const isOpen$1 = (a) => a.status === "todo" || a.status === "doing";
+/**
+* The previous session's unfinished actions, numbered after `existing`, with the previous session marked
+* handed-off. Each carried action is dropped in the previous session with a note naming its new reference,
+* so the work stays open in one place only and the old session still shows where it went. Runs inside the
+* caller's lock.
+*/
+function takeUnfinished(root, from, to, existing) {
+	const previousFile = requireSession(root, from);
+	const previous = readYaml(previousFile, sessionSchema).data;
+	const ids = [...existing];
+	const carried = [];
+	const at = nowMinute();
+	const left = previous.actions.map((a) => {
+		if (!isOpen$1(a)) return a;
+		const id = nextId("a", ids);
+		ids.push(id);
+		carried.push({
+			...a,
+			id
+		});
+		const handedOff = `handed off to ${to}#${id}`;
+		return {
+			...a,
+			status: "dropped",
+			note: a.note ? `${a.note}; ${handedOff}` : handedOff,
+			doneAt: at
+		};
+	});
+	writeAtomic(previousFile, toYaml(validate(sessionSchema, {
+		...previous,
+		status: "handed-off",
+		actions: left
+	}, previousFile)));
+	return carried;
+}
 /**
-* Start a session. Taking over from another session copies its unfinished actions into this one and marks
+* Start a session. Taking over from another session moves its unfinished actions into this one and marks
 * the other session handed-off, so the queue continues where it stopped.
 */
 function startSession(root, input) {
@@ -1301,19 +1262,7 @@ function startSession(root, input) {
 		const file = sessionFile(root, id);
 		if (existsSync(file)) throw new WriteError(`session ${id} already exists`);
 		if (input.delegatedFrom) requireSession(root, input.delegatedFrom);
-		let carried = [];
-		if (input.handoffFrom) {
-			const previousFile = requireSession(root, input.handoffFrom);
-			const previous = readYaml(previousFile, sessionSchema).data;
-			carried = previous.actions.filter((a) => a.status === "todo" || a.status === "doing").map((a, i) => ({
-				...a,
-				id: `a${String(i + 1).padStart(3, "0")}`
-			}));
-			writeAtomic(previousFile, toYaml(validate(sessionSchema, {
-				...previous,
-				status: "handed-off"
-			}, previousFile)));
-		}
+		const carried = input.handoffFrom ? takeUnfinished(root, input.handoffFrom, id, []) : [];
 		const session = validate(sessionSchema, {
 			id,
 			agent: input.agent,
@@ -1351,6 +1300,32 @@ function ensureSession(root, input) {
 		created: false
 	};
 }
+/**
+* Take over another session's unfinished actions into a session that already exists, such as one a host hook
+* created when the conversation opened. The receiving session must have nothing unfinished of its own, so the
+* carried queue is not mixed into work already under way; its finished actions stay and the carried ones are
+* numbered after them.
+*/
+function handoffSession(root, id, from) {
+	if (id === from) throw new WriteError(`session ${id} cannot take over from itself`);
+	return withLock(root, () => {
+		const file = requireSession(root, id);
+		const session = readYaml(file, sessionSchema).data;
+		if (session.handoffFrom && session.handoffFrom !== from) throw new WriteError(`session ${id} already took over from ${session.handoffFrom}`);
+		const open = session.actions.filter(isOpen$1);
+		if (open.length > 0) throw new WriteError(`session ${id} has unfinished actions (${open.map((a) => a.id).join(", ")}); finish or drop them before taking over from ${from}`);
+		if (!readYaml(requireSession(root, from), sessionSchema).data.actions.some(isOpen$1)) throw new WriteError(`session ${from} has no unfinished actions to take over`);
+		const carried = takeUnfinished(root, from, id, session.actions.map((a) => a.id));
+		const next = validate(sessionSchema, {
+			...session,
+			status: "active",
+			handoffFrom: from,
+			actions: [...session.actions, ...carried]
+		}, file);
+		writeAtomic(file, toYaml(next));
+		return next;
+	});
+}
 /** Where a session's transcript is on disk: a platform records an absolute path, a hub may record one relative to its root. */
 function transcriptPath(root, transcript) {
 	return isAbsolute(transcript) ? transcript : join(root, transcript);
@@ -1455,6 +1430,106 @@ function updateAction(root, ref, patch) {
 	return updated;
 }
 //#endregion
+//#region ../core/dist/briefing.js
+function describe(root, ref) {
+	const parsed = parseRef(ref);
+	if (parsed?.kind !== "checklistItem") return null;
+	try {
+		const mainline = readFrontMatter(mainlineFile(root, parsed.mainline), mainlineSchema).data;
+		const task = readFrontMatter(taskFile(root, parsed.mainline, parsed.task), taskSchema).data;
+		const item = task.checklist.find((c) => c.id === parsed.item);
+		if (!item) return null;
+		return {
+			ref,
+			text: item.text,
+			checked: item.done,
+			where: `${mainline.id} ${mainline.title} › ${task.id} ${task.title}`
+		};
+	} catch {
+		return null;
+	}
+}
+/** Problems in a session's queue that the executor should fix before going on, each with the command that fixes it. */
+function queueWarnings(root, session, cli) {
+	const warnings = [];
+	const doing = session.actions.filter((a) => a.status === "doing");
+	if (doing.length > 1) warnings.push(`同時有 ${doing.length} 個進行中的行動（${doing.map((a) => a.id).join("、")}）。一次只推進一個，其餘改回 todo。`);
+	for (const action of doing) {
+		const served = action.serves.map((ref) => describe(root, ref));
+		if (served.some((s) => s === null)) warnings.push(`${action.id} 服務的項目有的已不存在，用 ${cli} action set ${action.id} --serves <m/t#c> 改正。`);
+		else if (served.length > 0 && served.every((s) => s.checked)) warnings.push(`${action.id} 服務的項目都已勾選。做完了就執行 ${cli} action set ${action.id} --status done。`);
+	}
+	const next = session.actions.find((a) => a.status === "todo");
+	if (doing.length === 0 && next) warnings.push(`下一個行動是 ${next.id}。開始前先執行 ${cli} action set ${next.id} --status doing。`);
+	return warnings;
+}
+const current = (session) => session.actions.find((a) => a.status === "doing");
+const isOpen = (a) => a.status === "todo" || a.status === "doing";
+/** Mainlines a session could be pushing forward. */
+const openMainlines = (root) => loadHub(root).mainlines.filter((m) => !m.archivedAt && (m.status === "active" || m.status === "planning"));
+/** How recently a session's transcript must have been written for the session to count as possibly still running. */
+const RUNNING_WINDOW_MS = 9e5;
+/** Whether the session's transcript was written within the running window; false when no transcript is recorded or readable. */
+function mayBeRunning(root, session) {
+	if (!session.transcript) return false;
+	try {
+		return Date.now() - statSync(transcriptPath(root, session.transcript)).mtimeMs < RUNNING_WINDOW_MS;
+	} catch {
+		return false;
+	}
+}
+/**
+* Lines naming the other top-level sessions that still hold unfinished actions, with the command that takes them
+* over into this one. Subagent sessions are left out: their work returns to the session that delegated it.
+*/
+function handoffLines(root, session, cli) {
+	const others = loadSessions(root).sessions.filter((s) => s.id !== session.id && !s.delegatedFrom && !s.archivedAt && (s.status === "active" || s.status === "paused") && s.actions.some(isOpen));
+	if (others.length === 0) return [];
+	return [`其他會話還有沒做完的行動。要接續的是其中一場已經停下的工作時，先用 ${cli} session handoff <會話> 把它的行動接進這場會話，再開始做：`, ...others.map((s) => `- ${s.id}${mayBeRunning(root, s) ? "（15 分鐘內還有寫入對話紀錄，可能還在執行，不要接手）" : ""}：${s.actions.filter(isOpen).map((a) => `${a.id} ${a.do}（${a.status}，服務 ${a.serves.join("、") || "未指定"}）`).join("；")}`)];
+}
+const servedLine = (root, action) => action.serves.map((ref) => {
+	const s = describe(root, ref);
+	return s ? `${ref} ${s.text}（${s.where}）` : `${ref}（找不到這個項目）`;
+}).join("；") || "沒有指定服務的 checklist 項目";
+/** Full briefing for the start of a session, after resuming, clearing or compacting. */
+function sessionBriefing(root, session, options) {
+	const { cli } = options;
+	const lines = [`[mainflow] 這場會話的 id 是 ${session.id}${options.envNote ? `（${options.envNote}）` : ""}。`];
+	const doing = current(session);
+	const upcoming = session.actions.filter((a) => a.status === "todo").slice(0, 3);
+	if (session.actions.length === 0) {
+		const active = openMainlines(root);
+		lines.push("這場會話還沒有行動。");
+		if (active.length > 0) {
+			lines.push("進行中的主脈絡：");
+			for (const m of active) lines.push(`- ${m.id} ${m.title}`);
+			lines.push(`要推進其中一個時，先用 ${cli} status 與它的任務 checklist 決定要做什麼，再列出行動。`);
+		}
+	} else {
+		lines.push(doing ? `目前行動：${doing.id} ${doing.do}` : "目前沒有進行中的行動。");
+		if (doing) lines.push(`服務：${servedLine(root, doing)}`);
+		if (upcoming.length > 0) lines.push(`接下來：${upcoming.map((a) => `${a.id} ${a.do}`).join("、")}`);
+	}
+	if (!session.actions.some(isOpen)) lines.push(...handoffLines(root, session, cli));
+	const warnings = queueWarnings(root, session, cli);
+	if (warnings.length > 0) lines.push("需要處理：", ...warnings.map((w) => `- ${w}`));
+	lines.push("工作方式：", `- 開始一件新工作前，先列進佇列：${cli} action add "<做法>" --serves <m/t#c>。`, `- 開始做標 doing，做完標 done：${cli} action set <a編號> --status doing。`, `- 勾選 checklist 要附證據：${cli} item check <m/t#c> --evidence <commit、檔案:行號或指令輸出>。`, `- 內容直接寫進檔案：意圖或需求寫進 mainline.md 的內文，任務的目標與完成定義寫進 task.md，選擇寫成決策（${cli} new decision <m> <slug> --title <標題> 建檔後再寫內文）。`, `- 改完 .mainflow/ 的檔案跑 ${cli} check，把它列出的問題修到沒有。`, "- 用完其他 skill 或子流程後，回到上面的目前行動再繼續。", "- 要開主脈絡、拆任務、記決策、延後或收尾時，用 mainflow skill，它依序帶過並告訴你資訊該寫在哪裡。");
+	return lines.join("\n");
+}
+/** One or two lines for every user turn; null when the session has no actions and the hub has no open mainline. */
+function turnReminder(root, session, options) {
+	if (session.actions.length === 0) return openMainlines(root).length > 0 ? `[mainflow] ${session.id} 還沒有行動。這一輪要推進主脈絡時，先用 ${options.cli} action add 列出行動並標為 doing，或用 ${options.cli} session handoff <會話> 接手上一場沒做完的行動，再開始做。回覆結尾的標頭只看這場會話進行中的行動。` : null;
+	const doing = current(session);
+	const open = session.actions.filter((a) => a.status === "todo" || a.status === "doing");
+	const head = doing ? `[mainflow] 目前行動 ${doing.id} ${doing.do}，服務 ${doing.serves.join("、") || "（未指定）"}。這一輪的工作若不屬於它，先調整佇列再做。` : open.length === 0 ? `[mainflow] ${session.id} 的行動都已結束。繼續工作前先用 ${options.cli} action add 列出下一個行動。` : `[mainflow] ${session.id} 目前沒有進行中的行動。`;
+	const header = headerLine(session);
+	return [
+		head,
+		...header ? [`- 這一輪最後一則回覆的最後一行寫「${header}」，回覆範例等其他內容都放在它前面。有顯示 hook 時，它會換成標題與連結。`] : [],
+		...queueWarnings(root, session, options.cli).map((w) => `- ${w}`)
+	].join("\n");
+}
+//#endregion
 //#region ../core/dist/write.js
 function checkTaskLinks(root, mainline, task) {
 	if (task.repo && !(task.repo in readConfig(root).repos)) throw new WriteError(`repo "${task.repo}" is not listed in .mainflow/config.yaml; add it under repos first`);
@@ -1583,6 +1658,17 @@ function setCriterion(root, refInput, done, evidence, expectedVersion) {
 		setListItem(criterion, done, evidence);
 	}, expectedVersion);
 }
+/** Rewrite a criterion's text or doneWhen, leaving done and evidence as they are. */
+function setCriterionText(root, refInput, patch, expectedVersion) {
+	const ref = requireRef(refInput, "criterion");
+	if (patch.text === void 0 && patch.doneWhen === void 0) throw new WriteError(`${refInput} needs --text or --done-when, e.g. --text "CLI can create mainlines"`);
+	return mutateFrontMatter(root, mainlineFile(root, ref.mainline), mainlineSchema, (m) => {
+		const criterion = m.criteria.find((c) => c.id === ref.criterion);
+		if (!criterion) throw new WriteError(`criterion ${refInput} not found`);
+		if (patch.text !== void 0) criterion.text = patch.text;
+		if (patch.doneWhen !== void 0) criterion.doneWhen = patch.doneWhen;
+	}, expectedVersion);
+}
 /** Check or uncheck a criterion or checklist item; checking clears a drop. */
 function setListItem(item, done, evidence) {
 	item.done = done;
@@ -2054,4 +2140,4 @@ function openInApp(hub, target, closeAfterMs = 150) {
 	return true;
 }
 //#endregion
-export { HubError as $, readSession as A, decorateReply as B, setMainlineStatus as C, addAction as D, updateTask as E, startSession as F, closeIssue as G, headerLine as H, transcriptPath as I, planIssue as J, createFinding as K, updateAction as L, setSessionInfo as M, setSessionStatus as N, ensureSession as O, settleSession as P, setIssueArchived as Q, sessionBriefing as R, setCriterion as S, supersedeDecision as T, mayDecorate as U, endsWithMarker as V, appendOps as W, setFindingArchived as X, reopenIssue as Y, setFindingStatus as Z, createTask as _, openInApp as a, MAINLINE_FILE as at, setArchived as b, syncHost as c, WriteError as ct, setArchivedMany as d, findHubRoot as dt, loadHub as et, acceptDecision as f, worktreesOf as ft, createMainline as g, createDecision as h, hostName as i, refIndex as it, setSessionArchived as j, loadSessions as k, migrateHub as l, DATA_DIR as lt, addRepo as m, DEFAULT_UI_PORT as n, mainlineEdges as nt, removeHostLink as o, TASK_FILE as ot, addHub as p, createIssue as q, caddySites as r, linksInto as rt, siteBlock as s, ConflictError as st, APP_BUNDLE_ID as t, dependencyGraph as tt, ARCHIVE_KINDS as u, currentBranch as ut, dropChecklistItem as v, setMainlineTitle as w, setChecklistItem as x, initHub as y, turnReminder as z };
+export { setFindingStatus as $, addAction as A, transcriptPath as B, setCriterionText as C, updateTask as D, supersedeDecision as E, setSessionArchived as F, mayDecorate as G, decorateReply as H, setSessionInfo as I, createFinding as J, appendOps as K, setSessionStatus as L, handoffSession as M, loadSessions as N, sessionBriefing as O, readSession as P, setFindingArchived as Q, settleSession as R, setCriterion as S, setMainlineTitle as T, endsWithMarker as U, updateAction as V, headerLine as W, planIssue as X, createIssue as Y, reopenIssue as Z, createTask as _, openInApp as a, linksInto as at, setArchived as b, syncHost as c, TASK_FILE as ct, setArchivedMany as d, DATA_DIR as dt, setIssueArchived as et, acceptDecision as f, currentBranch as ft, createMainline as g, createDecision as h, hostName as i, mainlineEdges as it, ensureSession as j, turnReminder as k, migrateHub as l, ConflictError as lt, addRepo as m, worktreesOf as mt, DEFAULT_UI_PORT as n, loadHub as nt, removeHostLink as o, refIndex as ot, addHub as p, findHubRoot as pt, closeIssue as q, caddySites as r, dependencyGraph as rt, siteBlock as s, MAINLINE_FILE as st, APP_BUNDLE_ID as t, HubError as tt, ARCHIVE_KINDS as u, WriteError as ut, dropChecklistItem as v, setMainlineStatus as w, setChecklistItem as x, initHub as y, startSession as z };

package/dist/host.js

@@ -1,2 +1,2 @@
-import { a as openInApp, c as syncHost, i as hostName, n as DEFAULT_UI_PORT, o as removeHostLink, r as caddySites, s as siteBlock, t as APP_BUNDLE_ID } from "./host-Dwf1wLMd.js";
+import { a as openInApp, c as syncHost, i as hostName, n as DEFAULT_UI_PORT, o as removeHostLink, r as caddySites, s as siteBlock, t as APP_BUNDLE_ID } from "./host-mlpW8M1s.js";
 export { APP_BUNDLE_ID, DEFAULT_UI_PORT, caddySites, hostName, openInApp, removeHostLink, siteBlock, syncHost };

package/dist/{launch-D5K564tw.js → launch-CJYDVfE9.js}

@@ -1,4 +1,4 @@
-import { c as syncHost, ct as WriteError, i as hostName, lt as DATA_DIR, n as DEFAULT_UI_PORT, o as removeHostLink } from "./host-Dwf1wLMd.js";
+import { c as syncHost, dt as DATA_DIR, i as hostName, n as DEFAULT_UI_PORT, o as removeHostLink, ut as WriteError } from "./host-mlpW8M1s.js";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { spawn, spawnSync } from "node:child_process";
@@ -176,7 +176,7 @@ async function launchUi(root, hub, configured, options) {
 	}
 	let server;
 	if (!reuse) {
-		const { serveUi } = await import("./ui-CLMrfnhR.js");
+		const { serveUi } = await import("./ui-BbIFSMKR.js");
 		server = await serveUi(root, choice.port);
 		writeUiRecord(root, {
 			port: choice.port,

package/dist/launch.js

@@ -1,2 +1,2 @@
-import { a as portCandidates, c as watchHubGone, i as networkProbe, n as choosePort, o as readUiRecord, r as launchUi, s as startUiInBackground, t as PORT_SPAN } from "./launch-D5K564tw.js";
+import { a as portCandidates, c as watchHubGone, i as networkProbe, n as choosePort, o as readUiRecord, r as launchUi, s as startUiInBackground, t as PORT_SPAN } from "./launch-CJYDVfE9.js";
 export { PORT_SPAN, choosePort, launchUi, networkProbe, portCandidates, readUiRecord, startUiInBackground, watchHubGone };

package/dist/{ui-CLMrfnhR.js → ui-BbIFSMKR.js}

@@ -1,6 +1,6 @@
-import { A as readSession, C as setMainlineStatus, E as updateTask, I as transcriptPath, Q as setIssueArchived, S as setCriterion, X as setFindingArchived, a as openInApp, b as setArchived, ct as WriteError, d as setArchivedMany, et as loadHub, it as refIndex, j as setSessionArchived, k as loadSessions, lt as DATA_DIR, nt as mainlineEdges, rt as linksInto, st as ConflictError, tt as dependencyGraph, u as ARCHIVE_KINDS, w as setMainlineTitle, x as setChecklistItem } from "./host-Dwf1wLMd.js";
+import { B as transcriptPath, D as updateTask, F as setSessionArchived, N as loadSessions, P as readSession, Q as setFindingArchived, S as setCriterion, T as setMainlineTitle, a as openInApp, at as linksInto, b as setArchived, d as setArchivedMany, dt as DATA_DIR, et as setIssueArchived, it as mainlineEdges, lt as ConflictError, nt as loadHub, ot as refIndex, rt as dependencyGraph, u as ARCHIVE_KINDS, ut as WriteError, w as setMainlineStatus, x as setChecklistItem } from "./host-mlpW8M1s.js";
 import { t as listProgress } from "./progress-1BfPg2zN.js";
-import { l as CLI_VERSION } from "./launch-D5K564tw.js";
+import { l as CLI_VERSION } from "./launch-CJYDVfE9.js";
 import { createRequire } from "node:module";
 import { closeSync, existsSync, openSync, readFileSync, readSync, statSync, watch } from "node:fs";
 import { basename, dirname, extname, join, normalize, relative, sep } from "node:path";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mainflow",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "description": "本機多 AI 協作的主脈絡任務管理：CLI 與介面",
   "license": "MIT",
   "type": "module",