mainflow 0.24.0 → 0.25.0

package/dist/cli.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
-import { $ as reopenIssue, A as addAction, C as setCriterionText, D as updateTask, E as supersedeDecision, F as setSessionArchived, J as appendOps, L as setSessionStatus, M as handoffSession, O as sessionBriefing, P as readSession, Q as planIssue, S as setCriterion, V as updateAction, X as createFinding, Y as closeIssue, Z as createIssue, _ as createTask, b as setArchived, et as setFindingArchived, f as acceptDecision, ft as WriteError, g as createMainline, gt as findHubRoot, h as createDecision, it as loadHub, l as migrateHub, lt as MAINLINE_FILE, m as addRepo, nt as setIssueArchived, p as addHub, rt as HubError, tt as setFindingStatus, ut as TASK_FILE, v as dropChecklistItem, w as setMainlineStatus, x as setChecklistItem, y as initHub, z as startSession } from "./host-2a_9-kKv.js";
-import { I as parseRef, L as refExample } from "./dist-Dy45myuN.js";
+import { $ as createIssue, A as sessionBriefing, C as setCriterionText, D as updateTask, E as supersedeDecision, F as loadSessions, I as readSession, L as setSessionArchived, M as addAction, O as untilState, P as handoffSession, Q as createFinding, S as setCriterion, U as updateAction, V as startSession, X as appendOps, Z as closeIssue, _ as createTask, at as HubError, b as setArchived, dt as MAINLINE_FILE, et as planIssue, f as acceptDecision, ft as TASK_FILE, g as createMainline, h as createDecision, it as setIssueArchived, k as duplicateClaimLines, l as migrateHub, m as addRepo, mt as WriteError, nt as setFindingArchived, ot as loadHub, p as addHub, rt as setFindingStatus, tt as reopenIssue, v as dropChecklistItem, vt as findHubRoot, w as setMainlineStatus, x as setChecklistItem, y as initHub, z as setSessionStatus } from "./host-Dr0bCHd8.js";
+import { B as parseUntil, O as UNTIL_FORMS, V as refExample, z as parseRef } from "./dist-DlmecRLf.js";
 import { t as listProgress } from "./progress-1BfPg2zN.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-Bk3UgS-o.js";
+import { l as CLI_VERSION, r as launchUi, s as startUiInBackground } from "./launch-lnD-Z3hb.js";
 import { readFileSync, realpathSync } from "node:fs";
 import { join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -15,9 +15,10 @@ const RUNS = {
 	status: ({ root, opts }) => printStatus(loadHub(root), opts.all ?? false),
 	check: ({ root }) => {
 		const hub = loadHub(root);
+		const problems = [...hub.problems, ...loadSessions(root).problems];
 		printProblems(hub.warnings, "!");
-		if (hub.problems.length === 0) return done(`✓ ${hub.mainlines.length} mainlines, no problems${hub.warnings.length ? `, ${hub.warnings.length} ${hub.warnings.length === 1 ? "warning" : "warnings"}` : ""}`);
-		printProblems(hub.problems);
+		if (problems.length === 0) return done(`✓ ${hub.mainlines.length} mainlines, no problems${hub.warnings.length ? `, ${hub.warnings.length} ${hub.warnings.length === 1 ? "warning" : "warnings"}` : ""}`);
+		printProblems(problems);
 		return 1;
 	},
 	migrate: ({ root, opts }) => {
@@ -69,21 +70,34 @@ const RUNS = {
 	"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 }) => done(`created ${addAction(root, sessionOf(opts), {
-		do: args[0],
-		serves: list(opts.serves),
-		before: opts.before
-	})}`),
+	"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 = /^a\d{3}$/.test(args[0]) ? `${sessionOf(opts)}#${args[0]}` : args[0];
-		return done(`updated ${ref} (${updateAction(root, ref, {
+		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
+			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 = "";
 		try {
@@ -341,6 +355,98 @@ function sessionOf(opts, arg) {
 	if (!id) throw new WriteError("no session given; pass --session <id> or set MAINFLOW_SESSION (the SessionStart hook sets it)");
 	return id;
 }
+/** An action named as a{NNN} in the current session, or as {session}#a{NNN}. */
+const actionRef = (opts, arg) => /^a\d{3}$/.test(arg) ? `${sessionOf(opts)}#${arg}` : arg;
+/** Print a line for each running session already doing what this action serves; a reminder, so the exit code stays 0. */
+function remindDuplicates(root, ref) {
+	const hash = ref.lastIndexOf("#");
+	for (const line of duplicateClaimLines(root, ref.slice(0, hash), ref.slice(hash + 1))) console.log(line);
+	return 0;
+}
+/** Exit codes of `wait`: the condition holds, the time ran out, or there is no condition to wait for. */
+const WAIT_EXIT = {
+	met: 0,
+	timedOut: 1,
+	unusable: 2
+};
+const WAIT_DEFAULTS = {
+	timeout: 1800,
+	interval: 10
+};
+const UNTIL_HINT = UNTIL_FORMS.map((f) => f.format).join(", ");
+/** Block the process for a while; wait runs synchronously like every other command. */
+const sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+function seconds(value, fallback, name, zero) {
+	if (value === void 0) return fallback;
+	const n = Number(value);
+	if (value.trim() === "" || !Number.isFinite(n) || n < 0 || !zero && n === 0) throw new WriteError(`--${name} takes ${zero ? "zero or more" : "more than zero"} seconds, got "${value}"`);
+	return n;
+}
+/**
+* Poll a condition until it holds or the time runs out. Given an action, its `until` is read again on each
+* round, so a condition changed while waiting is the one checked; once the action leaves blocked or loses its
+* `until`, there is nothing left to wait for. A condition that can no longer come true ends the wait at once.
+*/
+function waitUntil(root, arg, opts) {
+	let timeout;
+	let interval;
+	let ref;
+	let text;
+	let condition;
+	const unusable = (message) => {
+		console.error(`✗ ${message}`);
+		return WAIT_EXIT.unusable;
+	};
+	/** The action's current `until`, or the reason it has none. */
+	const untilOf = (actionRef) => {
+		const hash = actionRef.lastIndexOf("#");
+		let session;
+		try {
+			session = readSession(root, actionRef.slice(0, hash));
+		} catch (error) {
+			return { error: error.message };
+		}
+		const action = session?.actions.find((a) => a.id === actionRef.slice(hash + 1));
+		if (!action) return { error: `action ${actionRef} not found` };
+		return action.blockedBy?.until ?? { error: `${actionRef} has no until condition (it is ${action.status}); give it one with action set ${arg} --status blocked --reason <reason> --until <condition>, where the condition is one of ${UNTIL_HINT}` };
+	};
+	try {
+		timeout = seconds(opts.timeout, WAIT_DEFAULTS.timeout, "timeout", true);
+		interval = seconds(opts.interval, WAIT_DEFAULTS.interval, "interval", false);
+		if (arg && opts.until) return unusable("give an action or --until, not both");
+		if (!arg && !opts.until) return unusable(`name the action to wait for, e.g. wait a002, or pass --until <condition>, one of ${UNTIL_HINT}`);
+		if (arg) {
+			ref = actionRef(opts, arg);
+			if (!/^[^#]+#a\d{3}$/.test(ref)) return unusable(`expected an action like a002 or claude-code-1a2b3c4d#a002, got "${arg}"`);
+			const until = untilOf(ref);
+			if (typeof until !== "string") return unusable(until.error);
+			text = until;
+		} else text = opts.until;
+		const parsed = parseUntil(text);
+		if (!parsed) return unusable(`"${text}" is not a condition; use one of ${UNTIL_HINT}`);
+		condition = parsed;
+	} catch (error) {
+		if (error instanceof WriteError) return unusable(error.message);
+		throw error;
+	}
+	const deadline = Date.now() + timeout * 1e3;
+	for (;;) {
+		const state = untilState(root, condition);
+		if (state.met) return done(`✓ ${text}: ${state.detail}`);
+		if (state.unreachable) return unusable(`${text} can no longer hold: ${state.detail}`);
+		const left = deadline - Date.now();
+		if (left <= 0) {
+			console.error(`✗ still waiting after ${timeout}s for ${text}: ${state.detail}`);
+			return WAIT_EXIT.timedOut;
+		}
+		sleep(Math.min(interval * 1e3, left));
+		if (!ref) continue;
+		const next = untilOf(ref);
+		if (typeof next !== "string") return unusable(`stopped waiting: ${next.error}`);
+		text = next;
+		condition = parseUntil(next);
+	}
+}
 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) {

package/dist/{dist-Dy45myuN.js → dist-DlmecRLf.js}

@@ -43,7 +43,7 @@ const GRANT_TARGET_FORMS = {
 };
 const KEBAB = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 /** A git branch name, `*` standing for any run of characters. */
-const BRANCH = /^(?!\/)(?!.*\/\/)(?!.*\.\.)[A-Za-z0-9._/*-]+(?<!\/)$/;
+const BRANCH$1 = /^(?!\/)(?!.*\/\/)(?!.*\.\.)[A-Za-z0-9._/*-]+(?<!\/)$/;
 /** npm package names: lowercase, optionally scoped. */
 const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/;
 /** A tag pattern: no whitespace, `*` and `?` as in a shell glob. */
@@ -62,7 +62,7 @@ function parseGrantTarget(action, target) {
 			const repo = colon < 0 ? target : target.slice(0, colon);
 			const branch = colon < 0 ? void 0 : target.slice(colon + 1);
 			if (!repo) return fail(action, "the repo name is missing");
-			if (branch !== void 0 && !BRANCH.test(branch)) return fail(action, `"${branch}" is not a branch name`);
+			if (branch !== void 0 && !BRANCH$1.test(branch)) return fail(action, `"${branch}" is not a branch name`);
 			return {
 				ok: true,
 				target: {
@@ -805,16 +805,122 @@ const taskSchema = z.object({
 		message: "a task cannot depend on itself"
 	});
 });
+/** A session id: lowercase letters, digits and hyphens, e.g. claude-code-1a2b3c4d. */
+const SESSION_ID = /^[a-z0-9][a-z0-9-]*$/;
+/** An action in some session, `{sessionId}#a{NNN}`. */
+const ACTION_REF = /^([a-z0-9][a-z0-9-]*)#(a\d{3})$/;
+/** Split an action reference into its session and action ids, or return null when the text is not one. */
+function parseActionRef(input) {
+	const m = ACTION_REF.exec(input);
+	return m ? {
+		session: m[1],
+		action: m[2]
+	} : null;
+}
+/** The action a blocked action waits for, when its whole `waitingFor` text is an action reference; otherwise undefined. */
+const waitingForAction = (waitingFor) => waitingFor && parseActionRef(waitingFor) ? waitingFor : void 0;
+/** The condition forms, one example each; facts and error messages read them from here. */
+const UNTIL_FORMS = [
+	{
+		kind: "commit",
+		format: "commit:{branch}:{text}",
+		example: "commit:main:feat(core): 行動阻塞"
+	},
+	{
+		kind: "action-done",
+		format: "action-done:{sessionId}#a{NNN}",
+		example: "action-done:claude-code-1a2b3c4d#a003"
+	},
+	{
+		kind: "file",
+		format: "file:{relative path}",
+		example: "file:packages/cli/dist/cli.js"
+	}
+];
+const UNTIL_EXAMPLES = UNTIL_FORMS.map((f) => f.format).join(", ");
+/** A branch name git log can take as a revision; a leading hyphen would read as an option. */
+const BRANCH = /^[^\s:~^?*[\\-][^\s:~^?*[\\]*$/;
+/** Parse a wait condition, or return null when it matches none of the forms. */
+function parseUntil(input) {
+	const colon = input.indexOf(":");
+	if (colon < 0) return null;
+	const kind = input.slice(0, colon);
+	const argument = input.slice(colon + 1);
+	switch (kind) {
+		case "commit": {
+			const split = argument.indexOf(":");
+			const branch = argument.slice(0, split);
+			const text = argument.slice(split + 1);
+			return split > 0 && BRANCH.test(branch) && !branch.includes("..") && text.length > 0 ? {
+				kind,
+				branch,
+				text
+			} : null;
+		}
+		case "action-done": {
+			const ref = parseActionRef(argument);
+			return ref ? {
+				kind,
+				...ref
+			} : null;
+		}
+		case "file": return argument.length > 0 && !argument.startsWith("/") ? {
+			kind,
+			path: argument
+		} : null;
+		default: return null;
+	}
+}
+/**
+* Why a blocked action cannot move, what it waits for, and the condition a program checks to end the wait.
+* `waitingFor` is free text, another session's action such as claude-code-1a2b3c4d#a003, or a hub reference
+* such as m031/t002 when the whole text is one.
+*/
+const actionBlockSchema = z.object({
+	reason: text,
+	waitingFor: text.optional(),
+	until: z.string().refine((s) => parseUntil(s) !== null, `expected a condition like ${UNTIL_EXAMPLES}`).optional()
+});
 const actionSchema = z.object({
 	id: id("action"),
 	do: z.string().min(1),
 	status: z.enum(WORK_STATUS),
 	serves: z.array(z.string().regex(CHECKLIST_REF)),
 	note: text.optional(),
+	/** Required while blocked, absent otherwise */
+	blockedBy: actionBlockSchema.optional(),
 	/** Set when the action turns doing and done; the transcript trace attributes tool use by these */
 	startedAt: datetime.optional(),
 	doneAt: datetime.optional()
+}).superRefine((a, ctx) => {
+	if (a.status === "blocked" && !a.blockedBy) ctx.addIssue({
+		code: "custom",
+		path: ["blockedBy"],
+		message: "a blocked action must say what blocks it"
+	});
+	if (a.status !== "blocked" && a.blockedBy) ctx.addIssue({
+		code: "custom",
+		path: ["blockedBy"],
+		message: `only a blocked action carries blockedBy; this one is ${a.status}`
+	});
 });
+/** The reason a blocked action written before `blockedBy` existed is given when it carries no note either. */
+const LEGACY_BLOCK_REASON = "（舊資料未寫原因）";
+/**
+* Session files written before `blockedBy` existed hold blocked actions without one. Reading fills it from the
+* action's note, so those files stay readable and the next write stores the filled form. `actionSchema` itself
+* stays strict, so a new block still has to say what blocks it.
+*/
+function withLegacyBlock(input) {
+	if (typeof input !== "object" || input === null) return input;
+	const action = input;
+	if (action.status !== "blocked" || action.blockedBy !== void 0) return input;
+	const reason = typeof action.note === "string" && action.note.length > 0 ? action.note : LEGACY_BLOCK_REASON;
+	return {
+		...action,
+		blockedBy: { reason }
+	};
+}
 const sessionSchema = z.object({
 	id: z.string().min(1),
 	agent: z.string().min(1),
@@ -823,7 +929,7 @@ const sessionSchema = z.object({
 	delegatedFrom: z.string().min(1).nullable(),
 	handoffFrom: z.string().min(1).nullable(),
 	cwd: z.string().min(1),
-	actions: z.array(actionSchema),
+	actions: z.array(z.preprocess(withLegacyBlock, actionSchema)),
 	/** Where the platform keeps the conversation, for tracing and for opening it */
 	transcript: text.optional(),
 	worktree: text.optional(),
@@ -904,4 +1010,4 @@ function parseOpsLine(line) {
 	return parsed.success ? parsed.data : null;
 }
 //#endregion
-export { findingSchema as A, taskSchema as B, SURVEY_LINES as C, WORK_STATUS as D, TASK_SECTIONS as E, parseOpsLine as F, describeRequest as G, GRANT_ACTIONS as H, parseRef as I, grantRepo as J, grantCovers as K, refExample as L, issueSchema as M, mainlineSchema as N, configSchema as O, opsEntrySchema as P, refMainline as R, SLUG as S, TASK_REQUIRED_SECTIONS as T, GRANT_FORMS as U, waitingForRef as V, GRANT_TARGET_FORMS as W, parseGrantTarget as Y, MERGE_STATES as _, DECISION_SECTIONS as a, RESERVED_HUB_NAMES as b, FINDING_SECTIONS as c, ID_PATTERNS as d, ISSUE_SECTIONS as f, MAINLINE_STATUS as g, MAINLINE_SECTIONS as h, DECISION_BASES as i, formatOpsEntry as j, decisionSchema as k, FINDING_STATUS as l, LINK_RELS as m, CLOSED_STATUS as n, DECISION_STATUS as o, ISSUE_STATUS as p, grantForm as q, DECIDERS as r, DEFAULT_CATEGORIES as s, CHECKLIST_REF as t, FORMAT_VERSION as u, PRIORITIES as v, SURVEY_SECTION as w, SESSION_STATUS as x, REF_EXAMPLES as y, sessionSchema as z };
+export { grantRepo as $, configSchema as A, parseUntil as B, SLUG as C, TASK_SECTIONS as D, TASK_REQUIRED_SECTIONS as E, mainlineSchema as F, waitingForAction as G, refMainline as H, opsEntrySchema as I, GRANT_FORMS as J, waitingForRef as K, parseActionRef as L, findingSchema as M, formatOpsEntry as N, UNTIL_FORMS as O, issueSchema as P, grantForm as Q, parseOpsLine as R, SESSION_STATUS as S, SURVEY_SECTION as T, sessionSchema as U, refExample as V, taskSchema as W, describeRequest as X, GRANT_TARGET_FORMS as Y, grantCovers as Z, MERGE_STATES as _, DECISION_SECTIONS as a, RESERVED_HUB_NAMES as b, FINDING_SECTIONS as c, ID_PATTERNS as d, parseGrantTarget as et, ISSUE_SECTIONS as f, MAINLINE_STATUS as g, MAINLINE_SECTIONS as h, DECISION_BASES as i, decisionSchema as j, WORK_STATUS as k, FINDING_STATUS as l, LINK_RELS as m, CLOSED_STATUS as n, DECISION_STATUS as o, ISSUE_STATUS as p, GRANT_ACTIONS as q, DECIDERS as r, DEFAULT_CATEGORIES as s, CHECKLIST_REF as t, FORMAT_VERSION as u, PRIORITIES as v, SURVEY_LINES as w, SESSION_ID as x, REF_EXAMPLES as y, parseRef as z };

package/dist/facts.d.ts

@@ -1,4 +1,4 @@
-import { a as SurveyLine, i as SLUG, n as FORMAT_VERSION, r as ID_PATTERNS, t as CHECKLIST_REF } from "./index-CV30LkNZ.js";
+import { a as SurveyLine, i as SLUG, n as FORMAT_VERSION, o as Until, r as ID_PATTERNS, t as CHECKLIST_REF } from "./index-D4IIwDGE.js";
 //#region src/facts.d.ts
 export interface CommandSpec {
   usage: string;
@@ -98,16 +98,23 @@ export declare const COMMAND_SPECS: {
   };
   readonly 'action add': {
     readonly usage: 'action add <text> --serves <m/t#c>[,<m/t#c>] [--before <a>] [--session <session>]';
-    readonly summary: 'Add an action to the session queue';
+    readonly summary: 'Add an action to the session queue; prints a reminder when another session active in the last 15 minutes is doing an item it serves';
     readonly args: 1;
     readonly needsHub: true;
   };
   readonly 'action set': {
-    readonly usage: 'action set <a|session#a> [--status] [--text] [--serves] [--before <a>] [--note <text>] [--session <session>]';
-    readonly summary: 'Change, reorder or finish an action';
+    readonly usage: 'action set <a|session#a> [--status] [--reason --waiting-for --until] [--text] [--serves] [--before <a>] [--note <text>] [--session <session>]';
+    readonly summary: 'Change, reorder or finish an action; --status blocked needs --reason, and leaving blocked clears it. --status doing reminds like action add. A handed-off action keeps its note';
     readonly args: 1;
     readonly needsHub: true;
   };
+  readonly wait: {
+    readonly usage: 'wait [a|session#a] [--until <condition>] [--timeout <seconds>] [--interval <seconds>] [--session <session>]';
+    readonly summary: 'Wait until an action\'s until condition, or the --until one, holds: exits 0 when it does, 1 when the timeout (1800 s) runs out, 2 when there is no usable condition, the action leaves blocked, or the condition can no longer hold; checks every 10 s';
+    readonly args: 0;
+    readonly optionalArgs: 1;
+    readonly needsHub: true;
+  };
   readonly hook: {
     readonly usage: 'hook <platform> <event>';
     readonly summary: 'Handle a host hook event read from stdin, e.g. hook claude-code session-start';
@@ -373,6 +380,15 @@ export declare const OPTIONS: {
   readonly signal: {
     readonly type: 'string';
   };
+  readonly until: {
+    readonly type: 'string';
+  };
+  readonly timeout: {
+    readonly type: 'string';
+  };
+  readonly interval: {
+    readonly type: 'string';
+  };
   readonly branch: {
     readonly type: 'string';
   };
@@ -476,6 +492,15 @@ export declare const REFERENCES: readonly [{
   readonly format: '{sessionId}#a{NNN}';
   readonly example: 'claude-code-1a2b3c4d#a003';
 }];
+/**
+ * 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).
+ */
+export declare const UNTIL: readonly {
+  kind: Until['kind'];
+  format: string;
+  example: string;
+}[];
 /** Relation types a document's links take; readers derive the reverse direction. */
 export declare const LINKS: {
   readonly rels: readonly ["depends-on", "relates", "split-from"];
@@ -557,6 +582,7 @@ export declare const FIELDS: {
   readonly criterion: FieldSpec[];
   readonly checklistItem: readonly [...FieldSpec[], FieldSpec];
   readonly grant: readonly [FieldSpec, FieldSpec, FieldSpec, FieldSpec];
+  readonly action: readonly [FieldSpec, FieldSpec, FieldSpec, FieldSpec, FieldSpec, FieldSpec, FieldSpec, FieldSpec];
   readonly link: readonly [FieldSpec, FieldSpec, FieldSpec];
 };
 //#endregion

package/dist/facts.js

@@ -1,4 +1,4 @@
-import { C as SURVEY_LINES, D as WORK_STATUS, E as TASK_SECTIONS, H as GRANT_ACTIONS, S as SLUG, T as TASK_REQUIRED_SECTIONS, U as GRANT_FORMS, W as GRANT_TARGET_FORMS, _ as MERGE_STATES, a as DECISION_SECTIONS, c as FINDING_SECTIONS, d as ID_PATTERNS, f as ISSUE_SECTIONS, g as MAINLINE_STATUS, h as MAINLINE_SECTIONS, i as DECISION_BASES, l as FINDING_STATUS, m as LINK_RELS, n as CLOSED_STATUS, o as DECISION_STATUS, p as ISSUE_STATUS, r as DECIDERS, s as DEFAULT_CATEGORIES, t as CHECKLIST_REF, u as FORMAT_VERSION, v as PRIORITIES, w as SURVEY_SECTION, x as SESSION_STATUS } from "./dist-Dy45myuN.js";
+import { C as SLUG, D as TASK_SECTIONS, E as TASK_REQUIRED_SECTIONS, J as GRANT_FORMS, O as UNTIL_FORMS, S as SESSION_STATUS, T as SURVEY_SECTION, Y as GRANT_TARGET_FORMS, _ as MERGE_STATES, a as DECISION_SECTIONS, c as FINDING_SECTIONS, d as ID_PATTERNS, f as ISSUE_SECTIONS, g as MAINLINE_STATUS, h as MAINLINE_SECTIONS, i as DECISION_BASES, k as WORK_STATUS, l as FINDING_STATUS, m as LINK_RELS, n as CLOSED_STATUS, o as DECISION_STATUS, p as ISSUE_STATUS, q as GRANT_ACTIONS, r as DECIDERS, s as DEFAULT_CATEGORIES, t as CHECKLIST_REF, u as FORMAT_VERSION, v as PRIORITIES, w as SURVEY_LINES } from "./dist-DlmecRLf.js";
 //#region src/facts.ts
 const COMMAND_SPECS = {
 	init: {
@@ -89,16 +89,23 @@ const COMMAND_SPECS = {
 	},
 	"action add": {
 		usage: "action add <text> --serves <m/t#c>[,<m/t#c>] [--before <a>] [--session <session>]",
-		summary: "Add an action to the session queue",
+		summary: "Add an action to the session queue; prints a reminder when another session active in the last 15 minutes is doing an item it serves",
 		args: 1,
 		needsHub: true
 	},
 	"action set": {
-		usage: "action set <a|session#a> [--status] [--text] [--serves] [--before <a>] [--note <text>] [--session <session>]",
-		summary: "Change, reorder or finish an action",
+		usage: "action set <a|session#a> [--status] [--reason --waiting-for --until] [--text] [--serves] [--before <a>] [--note <text>] [--session <session>]",
+		summary: "Change, reorder or finish an action; --status blocked needs --reason, and leaving blocked clears it. --status doing reminds like action add. A handed-off action keeps its note",
 		args: 1,
 		needsHub: true
 	},
+	wait: {
+		usage: "wait [a|session#a] [--until <condition>] [--timeout <seconds>] [--interval <seconds>] [--session <session>]",
+		summary: "Wait until an action's until condition, or the --until one, holds: exits 0 when it does, 1 when the timeout (1800 s) runs out, 2 when there is no usable condition, the action leaves blocked, or the condition can no longer hold; checks every 10 s",
+		args: 0,
+		optionalArgs: 1,
+		needsHub: true
+	},
 	hook: {
 		usage: "hook <platform> <event>",
 		summary: "Handle a host hook event read from stdin, e.g. hook claude-code session-start",
@@ -319,6 +326,9 @@ const OPTIONS = {
 	reason: { type: "string" },
 	"waiting-for": { type: "string" },
 	signal: { type: "string" },
+	until: { type: "string" },
+	timeout: { type: "string" },
+	interval: { type: "string" },
 	branch: { type: "string" },
 	worktree: { type: "string" },
 	base: { type: "string" },
@@ -408,6 +418,11 @@ const REFERENCES = [
 		example: "claude-code-1a2b3c4d#a003"
 	}
 ];
+/**
+* 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).
+*/
+const UNTIL = UNTIL_FORMS;
 /** Relation types a document's links take; readers derive the reverse direction. */
 const LINKS = { rels: LINK_RELS };
 /**
@@ -562,6 +577,16 @@ const FIELDS = {
 		field("target", true, "授權的目標，格式依動作而定，見 GRANTS.targets；倉庫名稱需在 config.yaml 登記"),
 		field("note", false, "一句話說明")
 	],
+	action: [
+		field("id", true, "會話內不重複的編號 a{NNN}，由 action add 配發"),
+		field("do", true, "要做的事，一句話"),
+		field("status", true, "狀態值見 STATUSES，用 action set 改"),
+		field("serves", true, "推進的 checklist 項目參照清單，可以是空的"),
+		field("note", false, "一句備註"),
+		field("blockedBy", false, "卡住時的原因 reason、等待對象 waitingFor 與程式可判斷的條件 until，blocked 時必填，其他狀態不得有；等待對象整串是其他會話的行動（例如 claude-code-1a2b3c4d#a003）時，對方的簡報會列出有人在等它；條件格式見 UNTIL"),
+		field("startedAt", false, "轉為 doing 時由 CLI 寫入"),
+		field("doneAt", false, "轉為 done 或 dropped 時由 CLI 寫入")
+	],
 	link: [
 		field("rel", true, "關係類型：depends-on、relates、split-from，反向由讀者推出"),
 		field("to", true, "對方的參照，不能在同一條主脈絡內；其他 hub 的加 {hub}: 前綴"),
@@ -569,4 +594,4 @@ const FIELDS = {
 	]
 };
 //#endregion
-export { CHECKLIST_REF, CLASSIFICATION, CLOSED_STATUSES, COMMAND_SPECS, FIELDS, FORMAT_VERSION, GRANTS, ID_PATTERNS, LAYOUT, LINKS, OPTIONS, REFERENCES, SECTIONS, SLUG, STATUSES, SURVEY };
+export { CHECKLIST_REF, CLASSIFICATION, CLOSED_STATUSES, COMMAND_SPECS, FIELDS, FORMAT_VERSION, GRANTS, ID_PATTERNS, LAYOUT, LINKS, OPTIONS, REFERENCES, SECTIONS, SLUG, STATUSES, SURVEY, UNTIL };

package/dist/grant-commands.d.ts

@@ -1,4 +1,4 @@
-import "./index-CV30LkNZ.js";
+import "./index-D4IIwDGE.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 { U as GRANT_FORMS } from "./dist-Dy45myuN.js";
+import { J as GRANT_FORMS } from "./dist-DlmecRLf.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.js

@@ -1,5 +1,5 @@
-import { G as endsWithMarker, H as grantScope, I as setSessionInfo, J as appendOps, K as headerLine, L as setSessionStatus, O as sessionBriefing, P as readSession, R as settleSession, U as matchGrants, W as decorateReply, _t as worktreesOf, gt as findHubRoot, ht as currentBranch, i as hostName, it as loadHub, j as ensureSession, k as turnReminder, mt as DATA_DIR, pt as readYaml, q as mayDecorate, rt as HubError } from "./host-2a_9-kKv.js";
-import { G as describeRequest, O as configSchema } from "./dist-Dy45myuN.js";
+import { A as sessionBriefing, B as settleSession, F as loadSessions, G as matchGrants, I as readSession, J as headerLine, K as decorateReply, N as ensureSession, R as setSessionInfo, W as grantScope, X as appendOps, Y as mayDecorate, _t as currentBranch, at as HubError, gt as DATA_DIR, ht as readYaml, i as hostName, j as turnReminder, ot as loadHub, q as endsWithMarker, vt as findHubRoot, yt as worktreesOf, z as setSessionStatus } from "./host-Dr0bCHd8.js";
+import { A as configSchema, X as describeRequest } from "./dist-DlmecRLf.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";
@@ -320,7 +320,7 @@ function checkAfterWrite(root, { payload, cli }) {
 	}
 	let problems;
 	try {
-		problems = loadHub(hub).problems;
+		problems = [...loadHub(hub).problems, ...loadSessions(hub).problems];
 	} catch (error) {
 		problems = error instanceof HubError ? [...error.problems, {
 			file: `${DATA_DIR}/config.yaml`,

package/dist/{host-2a_9-kKv.js → host-Dr0bCHd8.js}

@@ -1,7 +1,7 @@
-import { A as findingSchema, B as taskSchema, C as SURVEY_LINES, D as WORK_STATUS, E as TASK_SECTIONS, F as parseOpsLine, G as describeRequest, I as parseRef, J as grantRepo, K as grantCovers, L as refExample, M as issueSchema, N as mainlineSchema, O as configSchema, P as opsEntrySchema, R as refMainline, S as SLUG, T as TASK_REQUIRED_SECTIONS, V as waitingForRef, Y as parseGrantTarget, _ as MERGE_STATES, a as DECISION_SECTIONS, b as RESERVED_HUB_NAMES, c as FINDING_SECTIONS, f as ISSUE_SECTIONS, g as MAINLINE_STATUS, h as MAINLINE_SECTIONS, i as DECISION_BASES, j as formatOpsEntry, k as decisionSchema, l as FINDING_STATUS, n as CLOSED_STATUS, q as grantForm, r as DECIDERS, s as DEFAULT_CATEGORIES, t as CHECKLIST_REF, w as SURVEY_SECTION, x as SESSION_STATUS, y as REF_EXAMPLES, z as sessionSchema } from "./dist-Dy45myuN.js";
+import { $ as grantRepo, A as configSchema, B as parseUntil, C as SLUG, D as TASK_SECTIONS, E as TASK_REQUIRED_SECTIONS, F as mainlineSchema, G as waitingForAction, H as refMainline, I as opsEntrySchema, K as waitingForRef, L as parseActionRef, M as findingSchema, N as formatOpsEntry, P as issueSchema, Q as grantForm, R as parseOpsLine, S as SESSION_STATUS, T as SURVEY_SECTION, U as sessionSchema, V as refExample, W as taskSchema, X as describeRequest, Z as grantCovers, _ as MERGE_STATES, a as DECISION_SECTIONS, b as RESERVED_HUB_NAMES, c as FINDING_SECTIONS, et as parseGrantTarget, f as ISSUE_SECTIONS, g as MAINLINE_STATUS, h as MAINLINE_SECTIONS, i as DECISION_BASES, j as decisionSchema, k as WORK_STATUS, l as FINDING_STATUS, n as CLOSED_STATUS, r as DECIDERS, s as DEFAULT_CATEGORIES, t as CHECKLIST_REF, w as SURVEY_LINES, x as SESSION_ID, y as REF_EXAMPLES, z as parseRef } from "./dist-DlmecRLf.js";
 import { appendFileSync, closeSync, existsSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync, writeSync } from "node:fs";
 import { dirname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
-import { spawn, spawnSync } from "node:child_process";
+import { execFileSync, spawn, spawnSync } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
 import { parse as parse$1, stringify } from "yaml";
 //#region ../core/dist/paths.js
@@ -1388,6 +1388,50 @@ function splitActionRef(ref) {
 		action
 	};
 }
+/** The note a handoff leaves on the dropped action, naming where the work went. */
+const handedOffNote = (to) => `handed off to ${to}`;
+const HANDED_OFF = /(?:^|; )handed off to ([a-z0-9][a-z0-9-]*#a\d{3})$/;
+/**
+* Find the action a reference names. A handoff drops the action and names its new place in the note, so the
+* reference is followed there: a wait on the old reference keeps working after the work moved to another session.
+*/
+function resolveAction(root, ref) {
+	const seen = /* @__PURE__ */ new Set();
+	let current = ref;
+	for (;;) {
+		const parsed = parseActionRef(current);
+		if (!parsed) return {
+			ref: current,
+			missing: `"${current}" is not an action reference like claude-code-1a2b3c4d#a003`
+		};
+		let session;
+		try {
+			session = readSession(root, parsed.session);
+		} catch (error) {
+			return {
+				ref: current,
+				missing: error.message
+			};
+		}
+		if (!session) return {
+			ref: current,
+			missing: `session ${parsed.session} not found`
+		};
+		const action = session.actions.find((a) => a.id === parsed.action);
+		if (!action) return {
+			ref: current,
+			missing: `action ${current} not found`
+		};
+		const next = action.status === "dropped" ? HANDED_OFF.exec(action.note ?? "")?.[1] : void 0;
+		if (!next || seen.has(next)) return {
+			ref: current,
+			session,
+			action
+		};
+		seen.add(current);
+		current = next;
+	}
+}
 /**
 * Every served checklist item must exist, so a session never points at work that is not in a mainline. Its
 * mainline must still be open: follow-up work on an ended one either reopens it with a criterion or task for the
@@ -1423,7 +1467,7 @@ function takeUnfinished(root, from, to, existing) {
 			...a,
 			id
 		});
-		const handedOff = `handed off to ${to}#${id}`;
+		const handedOff = handedOffNote(`${to}#${id}`);
 		return {
 			...a,
 			status: "dropped",
@@ -1444,7 +1488,7 @@ function takeUnfinished(root, from, to, existing) {
 */
 function startSession(root, input) {
 	const id = input.id ?? `${input.agent}-${randomBytes(4).toString("hex")}`;
-	if (!/^[a-z0-9][a-z0-9-]*$/.test(id)) throw new WriteError(`session id "${id}" must be lowercase letters, digits and hyphens`);
+	if (!SESSION_ID.test(id)) throw new WriteError(`session id "${id}" must be lowercase letters, digits and hyphens`);
 	return withLock(root, () => {
 		const file = sessionFile(root, id);
 		if (existsSync(file)) throw new WriteError(`session ${id} already exists`);
@@ -1586,16 +1630,40 @@ function addAction(root, sessionId, input) {
 	});
 	return `${sessionId}#${created}`;
 }
+/**
+* What a blocked action waits for must be checkable: an action it names has to exist and, followed through
+* handoffs, cannot be the action itself, and an `until` has to be one of the condition forms. An old reference
+* to work that has since been handed off to this very action would otherwise wait forever.
+*/
+function requireBlock(root, ref, block) {
+	const targets = [waitingForAction(block.waitingFor), block.until === void 0 ? void 0 : untilTarget(block.until)];
+	for (const target of targets) {
+		if (!target) continue;
+		const found = resolveAction(root, target);
+		if ("missing" in found) throw new WriteError(`${found.missing}; --waiting-for and --until action-done take an existing action like claude-code-1a2b3c4d#a003`);
+		if (found.ref === ref) throw new WriteError(`action ${ref} cannot wait for itself${target === ref ? "" : ` (${target} was handed off to it)`}`);
+	}
+}
+/** The action an `until` waits for; throws when the condition matches none of the forms. */
+function untilTarget(until) {
+	const parsed = parseUntil(until);
+	if (!parsed) throw new WriteError(`--until takes a condition like commit:{branch}:{text}, action-done:{sessionId}#a{NNN} or file:{relative path}, got "${until}"`);
+	return parsed.kind === "action-done" ? `${parsed.session}#${parsed.action}` : void 0;
+}
 function updateAction(root, ref, patch) {
 	const { session, action } = splitActionRef(ref);
 	const status = patch.status === void 0 ? void 0 : requireOneOf(patch.status, WORK_STATUS, "action status");
 	if (patch.serves) requireServes(root, patch.serves);
 	if (patch.before === action) throw new WriteError(`action ${action} cannot be placed before itself`);
+	if (status === "blocked" && !patch.blockedBy?.reason) throw new WriteError(`blocking ${ref} needs a reason, e.g. --reason "等 schema 定案" --waiting-for claude-code-1a2b3c4d#a003 --until action-done:claude-code-1a2b3c4d#a003`);
+	if (patch.blockedBy) requireBlock(root, `${session}#${action}`, patch.blockedBy);
 	let updated;
 	mutateYaml(root, requireSession(root, session), sessionSchema, (s) => {
 		const index = s.actions.findIndex((a) => a.id === action);
 		if (index < 0) throw new WriteError(`action ${ref} not found`);
 		const [current] = s.actions.splice(index, 1);
+		const handedTo = patch.note ? HANDED_OFF.exec(current.note ?? "")?.[1] : void 0;
+		if (handedTo) throw new WriteError(`${ref} was handed off to ${handedTo}, and references to ${ref} follow its note there, so the note stays as it is; add the note to ${handedTo} instead`);
 		const next = {
 			...current,
 			...status && { status },
@@ -1603,6 +1671,11 @@ function updateAction(root, ref, patch) {
 			...patch.serves && { serves: patch.serves },
 			...patch.note && { note: patch.note }
 		};
+		if (patch.blockedBy) {
+			if (next.status !== "blocked") throw new WriteError(`--reason, --waiting-for and --until go with --status blocked; ${ref} is ${next.status}`);
+			next.blockedBy = patch.blockedBy;
+		}
+		if (next.status !== "blocked") delete next.blockedBy;
 		if (status === "doing" && current.status !== "doing") {
 			next.startedAt = nowMinute();
 			delete next.doneAt;
@@ -1654,8 +1727,16 @@ function queueWarnings(root, session, cli) {
 }
 const current = (session) => session.actions.find((a) => a.status === "doing");
 const isOpen = (a) => a.status === "todo" || a.status === "doing";
-/** A blocked action and what it waits for; the note is where `action set --note` records the wait. */
-const waitingLine = (a) => `${a.id} ${a.do}${a.note ? `（${a.note}）` : ""}`;
+/** A blocked action and what it waits for: the reason, the other party and the condition, as `action set --status blocked` recorded them. */
+function waitingLine(a) {
+	const block = a.blockedBy;
+	const parts = block ? [
+		block.reason,
+		...block.waitingFor ? [`等 ${block.waitingFor}`] : [],
+		...block.until ? [`條件 ${block.until}`] : []
+	] : [];
+	return `${a.id} ${a.do}${parts.length > 0 ? `（${parts.join("；")}）` : ""}`;
+}
 /** Mainlines a session could be pushing forward. */
 const openMainlines = (root) => loadHub(root).mainlines.filter((m) => !m.archivedAt && (m.status === "active" || m.status === "planning"));
 /** How recently a session's transcript must have been written for the session to count as possibly still running. */
@@ -1669,6 +1750,69 @@ function mayBeRunning(root, session) {
 		return false;
 	}
 }
+/** The session and every session in its delegation tree: the sessions that delegated to it, and theirs, and all their subagents. */
+function family(sessions, id) {
+	const byId = new Map(sessions.map((s) => [s.id, s]));
+	const chain = /* @__PURE__ */ new Set([id]);
+	let top = id;
+	for (let up = byId.get(id)?.delegatedFrom; up && byId.has(up) && !chain.has(up); up = byId.get(up)?.delegatedFrom) {
+		chain.add(up);
+		top = up;
+	}
+	const members = /* @__PURE__ */ new Set([top]);
+	for (let grew = true; grew;) {
+		grew = false;
+		for (const s of sessions) if (s.delegatedFrom && members.has(s.delegatedFrom) && !members.has(s.id)) {
+			members.add(s.id);
+			grew = true;
+		}
+	}
+	return members.add(id);
+}
+/** The actions in this session that a blocked action elsewhere waits for, named by `waitingFor` or by an `until` of kind action-done. */
+function waitedFor(root, blocked) {
+	const until = blocked.blockedBy?.until ? parseUntil(blocked.blockedBy.until) : null;
+	const refs = [waitingForAction(blocked.blockedBy?.waitingFor), until?.kind === "action-done" ? `${until.session}#${until.action}` : void 0];
+	return [...new Set(refs.filter((r) => r !== void 0).map((r) => resolveAction(root, r).ref))];
+}
+/**
+* One line for each blocked action in another session that waits for an action of this one, followed through
+* handoffs, so the session being waited for sees it without the other side having to send a message. An action
+* already done or dropped has nothing left to deliver, so a wait on it is not shown.
+*/
+function waiterLines(root, session) {
+	const lines = [];
+	for (const other of loadSessions(root).sessions) {
+		if (other.id === session.id || other.archivedAt || other.status === "handed-off") continue;
+		for (const blocked of other.actions.filter((a) => a.status === "blocked")) for (const ref of waitedFor(root, blocked)) {
+			const mine = ref.startsWith(`${session.id}#`) ? session.actions.find((a) => `${session.id}#${a.id}` === ref) : void 0;
+			if (!mine || mine.status === "done" || mine.status === "dropped") continue;
+			const until = blocked.blockedBy?.until ? `。條件：${blocked.blockedBy.until}` : "";
+			lines.push(`有會話在等你：${other.id}#${blocked.id} 等 ${mine.id} ${mine.do}（${blocked.blockedBy.reason}）${until}`);
+		}
+	}
+	return lines;
+}
+/**
+* One reminder for each action in progress in another session that may still be running and serves an item
+* this action also serves. Sessions in the same delegation tree are left out: a subagent working on the item
+* its parent handed it is not a second claim.
+*/
+function duplicateClaimLines(root, sessionId, actionId) {
+	const { sessions } = loadSessions(root);
+	const action = sessions.find((s) => s.id === sessionId)?.actions.find((a) => a.id === actionId);
+	if (!action || action.serves.length === 0) return [];
+	const related = family(sessions, sessionId);
+	const lines = [];
+	for (const other of sessions) {
+		if (related.has(other.id) || !mayBeRunning(root, other)) continue;
+		for (const theirs of other.actions.filter((a) => a.status === "doing")) {
+			const shared = theirs.serves.filter((ref) => action.serves.includes(ref));
+			if (shared.length > 0) lines.push(`⚠ ${other.id}#${theirs.id}（15 分鐘內有活動）也在做 ${shared.join("、")}，先協調再開始`);
+		}
+	}
+	return lines;
+}
 /**
 * 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.
@@ -1705,6 +1849,7 @@ function sessionBriefing(root, session, options) {
 		const blocked = session.actions.filter((a) => a.status === "blocked");
 		if (blocked.length > 0) lines.push(`等外部條件：${blocked.map(waitingLine).join("；")}`);
 	}
+	lines.push(...waiterLines(root, session));
 	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}`));
@@ -1717,18 +1862,115 @@ function turnReminder(root, session, options) {
 	const doing = current(session);
 	const open = session.actions.filter(isOpen);
 	const blocked = session.actions.filter((a) => a.status === "blocked");
-	const head = doing ? `[mainflow] 目前行動 ${doing.id} ${doing.do}，服務 ${doing.serves.join("、") || "（未指定）"}。這一輪的工作若不屬於它，先調整佇列再做。` : open.length > 0 ? `[mainflow] ${session.id} 目前沒有進行中的行動。` : blocked.length > 0 ? `[mainflow] ${session.id} 的行動在等外部條件：${blocked.map(waitingLine).join("；")}。條件出現後用 ${options.cli} action set <a編號> --status doing 繼續；要先做別的事，用 ${options.cli} action add 列出行動。` : `[mainflow] ${session.id} 的行動都已結束。繼續工作前先用 ${options.cli} action add 列出下一個行動。`;
+	const head = doing ? `[mainflow] 目前行動 ${doing.id} ${doing.do}，服務 ${doing.serves.join("、") || "（未指定）"}。這一輪的工作若不屬於它，先調整佇列再做。` : open.length > 0 ? `[mainflow] ${session.id} 目前沒有進行中的行動。` : blocked.length > 0 ? `[mainflow] ${session.id} 的行動在等外部條件：${blocked.map(waitingLine).join("；")}。有條件（until）的可以在背景執行 ${options.cli} wait <a編號> 等它成立。條件出現後用 ${options.cli} action set <a編號> --status doing 繼續；要先做別的事，用 ${options.cli} action add 列出行動。` : `[mainflow] ${session.id} 的行動都已結束。繼續工作前先用 ${options.cli} action add 列出下一個行動。`;
 	const header = headerLine(session);
 	const marker = header ? [`- 這一輪最後一則回覆的最後一行寫「${header}」，回覆範例等其他內容都放在它前面。有顯示 hook 時，它會換成標題與連結。`] : [];
 	const grants = grantLines(root, session);
+	const granted = grants.length > 0 ? ["- 目前行動服務的主脈絡預先授權了這些動作：", ...grants.map((g) => `  ${g}`)] : [];
 	return [
 		head,
-		...grants.length > 0 ? ["- 目前行動服務的主脈絡預先授權了這些動作：", ...grants.map((g) => `  ${g}`)] : [],
+		...waiterLines(root, session).map((w) => `- ${w}`),
+		...granted,
 		...marker,
 		...queueWarnings(root, session, options.cli).map((w) => `- ${w}`)
 	].join("\n");
 }
 //#endregion
+//#region ../core/dist/waiting.js
+/** Separates commits in the git log output (%x1e); commit messages do not use this control character. */
+const RECORD = "";
+/** Whether git finds a repository at the hub root; false as well when git itself cannot run. */
+function inGitRepository(root) {
+	try {
+		execFileSync("git", ["rev-parse", "--git-dir"], {
+			cwd: root,
+			stdio: "ignore"
+		});
+		return true;
+	} catch {
+		return false;
+	}
+}
+/** Whether a commit on the branch has the text in its message; git runs at the hub root, so the branch is the hub repository's. */
+function commitState(root, branch, text) {
+	let log;
+	try {
+		log = execFileSync("git", [
+			"log",
+			"--format=%h %s%n%b%x1e",
+			branch,
+			"--"
+		], {
+			cwd: root,
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			],
+			maxBuffer: 268435456
+		});
+	} catch {
+		if (!inGitRepository(root)) return {
+			met: false,
+			unreachable: true,
+			detail: `the hub root ${root} is not in a git repository, so no commit can appear there`
+		};
+		return {
+			met: false,
+			detail: `branch ${branch} is not in the repository at the hub root yet`
+		};
+	}
+	for (const record of log.split(RECORD)) {
+		const entry = record.replace(/^\n/, "");
+		const space = entry.indexOf(" ");
+		const message = entry.slice(space + 1);
+		if (space > 0 && message.includes(text)) return {
+			met: true,
+			detail: `commit ${entry.slice(0, space)} on ${branch} contains "${text}": ${message.split("\n")[0]}`
+		};
+	}
+	return {
+		met: false,
+		detail: `no commit on ${branch} contains "${text}"`
+	};
+}
+function actionState(root, ref) {
+	const found = resolveAction(root, ref);
+	if ("missing" in found) return {
+		met: false,
+		detail: found.missing
+	};
+	const via = found.ref === ref ? "" : ` (handed off to ${found.ref})`;
+	if (found.action.status === "done") return {
+		met: true,
+		detail: `${ref}${via} is done`
+	};
+	if (found.action.status === "dropped") return {
+		met: false,
+		unreachable: true,
+		detail: `${ref}${via} was dropped without a handoff, so it will never be done`
+	};
+	return {
+		met: false,
+		detail: `${ref}${via} is ${found.action.status}`
+	};
+}
+/** Check a wait condition once. */
+function untilState(root, until) {
+	switch (until.kind) {
+		case "commit": return commitState(root, until.branch, until.text);
+		case "action-done": return actionState(root, `${until.session}#${until.action}`);
+		case "file": return existsSync(resolve(root, until.path)) ? {
+			met: true,
+			detail: `${until.path} exists`
+		} : {
+			met: false,
+			detail: `${until.path} does not exist yet`
+		};
+	}
+}
+//#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`);
@@ -2355,4 +2597,4 @@ function openInApp(hub, target, closeAfterMs = 150) {
 	return true;
 }
 //#endregion
-export { reopenIssue as $, addAction as A, transcriptPath as B, setCriterionText as C, updateTask as D, supersedeDecision as E, setSessionArchived as F, endsWithMarker as G, grantScope as H, setSessionInfo as I, appendOps as J, headerLine as K, setSessionStatus as L, handoffSession as M, loadSessions as N, sessionBriefing as O, readSession as P, planIssue as Q, settleSession as R, setCriterion as S, setMainlineTitle as T, matchGrants as U, updateAction as V, decorateReply as W, createFinding as X, closeIssue as Y, createIssue as Z, createTask as _, worktreesOf as _t, openInApp as a, dependencyGraph as at, setArchived as b, syncHost as c, refIndex as ct, setArchivedMany as d, ConflictError as dt, setFindingArchived as et, acceptDecision as f, WriteError as ft, createMainline as g, findHubRoot as gt, createDecision as h, currentBranch as ht, hostName as i, loadHub as it, ensureSession as j, turnReminder as k, migrateHub as l, MAINLINE_FILE as lt, addRepo as m, DATA_DIR as mt, DEFAULT_UI_PORT as n, setIssueArchived as nt, removeHostLink as o, mainlineEdges as ot, addHub as p, readYaml as pt, mayDecorate as q, caddySites as r, HubError as rt, siteBlock as s, linksInto as st, APP_BUNDLE_ID as t, setFindingStatus as tt, ARCHIVE_KINDS as u, TASK_FILE as ut, dropChecklistItem as v, setMainlineStatus as w, setChecklistItem as x, initHub as y, startSession as z };
+export { createIssue as $, sessionBriefing as A, settleSession as B, setCriterionText as C, updateTask as D, supersedeDecision as E, loadSessions as F, matchGrants as G, transcriptPath as H, readSession as I, headerLine as J, decorateReply as K, setSessionArchived as L, addAction as M, ensureSession as N, untilState as O, handoffSession as P, createFinding as Q, setSessionInfo as R, setCriterion as S, setMainlineTitle as T, updateAction as U, startSession as V, grantScope as W, appendOps as X, mayDecorate as Y, closeIssue as Z, createTask as _, currentBranch as _t, openInApp as a, HubError as at, setArchived as b, syncHost as c, mainlineEdges as ct, setArchivedMany as d, MAINLINE_FILE as dt, planIssue as et, acceptDecision as f, TASK_FILE as ft, createMainline as g, DATA_DIR as gt, createDecision as h, readYaml as ht, hostName as i, setIssueArchived as it, turnReminder as j, duplicateClaimLines as k, migrateHub as l, linksInto as lt, addRepo as m, WriteError as mt, DEFAULT_UI_PORT as n, setFindingArchived as nt, removeHostLink as o, loadHub as ot, addHub as p, ConflictError as pt, endsWithMarker as q, caddySites as r, setFindingStatus as rt, siteBlock as s, dependencyGraph as st, APP_BUNDLE_ID as t, reopenIssue as tt, ARCHIVE_KINDS as u, refIndex as ut, dropChecklistItem as v, findHubRoot as vt, setMainlineStatus as w, setChecklistItem as x, initHub as y, worktreesOf as yt, setSessionStatus 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-2a_9-kKv.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-Dr0bCHd8.js";
 export { APP_BUNDLE_ID, DEFAULT_UI_PORT, caddySites, hostName, openInApp, removeHostLink, siteBlock, syncHost };

package/dist/{index-CV30LkNZ.d.ts → index-D4IIwDGE.d.ts}

@@ -23,5 +23,22 @@ interface SurveyLine {
   /** Text a checked line must contain, e.g. the environment a spike ran in. */
   requires?: string;
 }
+/**
+ * A condition a program can check, written `{kind}:{argument}`. `commit` holds once a commit message on the
+ * branch contains the text, `action-done` once the action is done, `file` once the path exists under the hub
+ * root. Git branch names cannot contain a colon, so the text after the branch may.
+ */
+type Until = {
+  kind: 'commit';
+  branch: string;
+  text: string;
+} | {
+  kind: 'action-done';
+  session: string;
+  action: string;
+} | {
+  kind: 'file';
+  path: string;
+};
 //#endregion
-export { SurveyLine as a, SLUG as i, FORMAT_VERSION as n, ID_PATTERNS as r, CHECKLIST_REF as t };
+export { SurveyLine as a, SLUG as i, FORMAT_VERSION as n, Until as o, ID_PATTERNS as r, CHECKLIST_REF as t };

package/dist/{launch-Bk3UgS-o.js → launch-lnD-Z3hb.js}

@@ -1,4 +1,4 @@
-import { c as syncHost, ft as WriteError, i as hostName, mt as DATA_DIR, n as DEFAULT_UI_PORT, o as removeHostLink } from "./host-2a_9-kKv.js";
+import { c as syncHost, gt as DATA_DIR, i as hostName, mt as WriteError, n as DEFAULT_UI_PORT, o as removeHostLink } from "./host-Dr0bCHd8.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-Cngo5j6g.js");
+		const { serveUi } = await import("./ui-Cz8suWal.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-Bk3UgS-o.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-lnD-Z3hb.js";
 export { PORT_SPAN, choosePort, launchUi, networkProbe, portCandidates, readUiRecord, startUiInBackground, watchHubGone };

package/dist/{ui-Cngo5j6g.js → ui-Cz8suWal.js}

@@ -1,6 +1,6 @@
-import { B as transcriptPath, D as updateTask, F as setSessionArchived, N as loadSessions, P as readSession, S as setCriterion, T as setMainlineTitle, a as openInApp, at as dependencyGraph, b as setArchived, ct as refIndex, d as setArchivedMany, dt as ConflictError, et as setFindingArchived, ft as WriteError, it as loadHub, mt as DATA_DIR, nt as setIssueArchived, ot as mainlineEdges, st as linksInto, u as ARCHIVE_KINDS, w as setMainlineStatus, x as setChecklistItem } from "./host-2a_9-kKv.js";
+import { D as updateTask, F as loadSessions, H as transcriptPath, I as readSession, L as setSessionArchived, S as setCriterion, T as setMainlineTitle, a as openInApp, b as setArchived, ct as mainlineEdges, d as setArchivedMany, gt as DATA_DIR, it as setIssueArchived, lt as linksInto, mt as WriteError, nt as setFindingArchived, ot as loadHub, pt as ConflictError, st as dependencyGraph, u as ARCHIVE_KINDS, ut as refIndex, w as setMainlineStatus, x as setChecklistItem } from "./host-Dr0bCHd8.js";
 import { t as listProgress } from "./progress-1BfPg2zN.js";
-import { l as CLI_VERSION } from "./launch-Bk3UgS-o.js";
+import { l as CLI_VERSION } from "./launch-lnD-Z3hb.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.24.0",
+  "version": "0.25.0",
   "description": "本機多 AI 協作的主脈絡任務管理：CLI 與介面",
   "license": "MIT",
   "type": "module",