kanbo-cli 0.4.0 → 0.6.0

package/dist/lib/{manifest-DcIMYvWk.cjs → manifest-BFI4HGPh.cjs}

@@ -21,8 +21,8 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 //#endregion
 const require_migrations_path = require("./migrations-path-DBCE17dT.cjs");
-const require_roles_sql = require("./roles.sql-E58x7mLS.cjs");
-const require_migrate = require("./migrate-Dca5WdYd.cjs");
+const require_roles_sql = require("./roles.sql-BC7k_zPh.cjs");
+const require_migrate = require("./migrate-36aT0rV0.cjs");
 let commander = require("commander");
 let zod = require("zod");
 let node_os = require("node:os");
@@ -296,6 +296,7 @@ const HUMAN_ONLY_ACTIONS = [
 	"return",
 	"sprint close",
 	"columns rules",
+	"columns flow",
 	"columns add",
 	"columns rename",
 	"columns move",
@@ -309,6 +310,7 @@ const HUMAN_ONLY_MESSAGES = {
 	"return": describeReturnRefusal,
 	"sprint close": describeSprintCloseRefusal,
 	"columns rules": describeColumnRulesRefusal,
+	"columns flow": describeColumnRulesRefusal,
 	"columns add": describeColumnChangesRefusal,
 	"columns rename": describeColumnChangesRefusal,
 	"columns move": describeColumnChangesRefusal,
@@ -608,18 +610,18 @@ function activityToken(token) {
 function currentUnixSeconds() {
 	return Math.floor(Date.now() / 1e3);
 }
-const DAY_SECONDS = 86400;
+const DAY_SECONDS$2 = 86400;
 /**
 * A board date is a calendar day (ruling 5x-6): a start is kept as the first
 * second of its UTC day, a due date as the last, so a sprint runs through its
 * due day wherever the person reading it is.
 */
 function utcDayStart(seconds) {
-	return Math.floor(seconds / DAY_SECONDS) * DAY_SECONDS;
+	return Math.floor(seconds / DAY_SECONDS$2) * DAY_SECONDS$2;
 }
 /** The last second of the UTC day `seconds` falls on — see `utcDayStart`. */
 function utcDayEnd(seconds) {
-	return utcDayStart(seconds) + DAY_SECONDS - 1;
+	return utcDayStart(seconds) + DAY_SECONDS$2 - 1;
 }
 /** The largest unix seconds a moment is read as: past it, the number is milliseconds (year 5138 onwards). */
 const MAX_UNIX_SECONDS = 1e11;
@@ -789,6 +791,14 @@ const HIDDEN_ACTIVITY_FIELDS = /* @__PURE__ */ new Set([
 	"order",
 	"waitingFor"
 ]);
+/**
+* The column a card was created in, recorded as a change from no column at the
+* card's own creation time. The feed's `created` item already stands for it,
+* and the field history keeps it.
+*/
+function isStartingColumn(change, issue) {
+	return change.field === "statusId" && change.fromValue === null && change.createdAt === issue.createdAt;
+}
 const ACTIVITY_FIELD_BY_RAW_FIELD = {
 	assigneeId: "assignee",
 	description: "description",
@@ -829,7 +839,7 @@ async function listActivity(store, issueId, resolver) {
 		workspaceById: resolver.workspaceById
 	};
 	const commentItems = await Promise.all((await store.comments.listByIssue(issueId)).map(async (comment) => await toCommentActivityItem(comment, resolver)));
-	const fieldChangeItems = (await Promise.all((await store.fieldChanges.listByIssue(issueId)).map(async (change) => await toFieldChangeActivityItem(change, lookup, resolver)))).filter((item) => item !== null);
+	const fieldChangeItems = (await Promise.all((await store.fieldChanges.listByIssue(issueId)).filter((change) => !isStartingColumn(change, issue)).map(async (change) => await toFieldChangeActivityItem(change, lookup, resolver)))).filter((item) => item !== null);
 	return [
 		{
 			id: `${issue.id}:created`,
@@ -1027,62 +1037,31 @@ function previewComment(comment) {
 	};
 }
 //#endregion
-//#region src/domain/field-changes.ts
+//#region src/domain/card-display-title.ts
 /**
-* The issue columns whose edits are written to the audit trail.
+* What a card is called wherever a person or an agent reads it by name.
 *
-* `statusLine` is absent on purpose: `writeStatusLine` records every line it
-* writes itself, and no patch ever carries the column. `waitingFor` is absent
-* too — whose turn it is shows in the card's own line and in the
-* `system.approved` / `system.returned` comments around it, so a row saying the
-* same thing a third time would only crowd the history.
-*/
-const TRACKED_FIELDS = [
-	"workspaceId",
-	"title",
-	"description",
-	"priority",
-	"labels",
-	"milestoneId",
-	"parentIssueId",
-	"statusId",
-	"assigneeKind",
-	"assigneeId",
-	"dueDate",
-	"delegateAgentId",
-	"delegateProviderTargetId",
-	"contextRefs",
-	"executionMode",
-	"order"
-];
-/**
-* The audit rows one patch produces: a row per tracked field whose stringified
-* value actually changed. Nothing is written here — the caller inserts what
-* comes back, so the diff stays a pure function of the row, the patch, the
-* actor and the clock.
+* A card written as a description alone is titled with its own key (every
+* writer does that). Named by its key, such a card says nothing — so its name
+* is the first line of its description instead. A browser bundle that does not
+* load this package keeps the same rule on its own, tested with the same
+* examples.
 */
-function diffFieldChanges(before, updates, actor, now) {
-	const rows = [];
-	for (const field of TRACKED_FIELDS) {
-		if (!(field in updates)) continue;
-		const rawBefore = before[field === "labels" ? "labels" : field];
-		const rawAfter = updates[field];
-		const fromValue = rawBefore == null ? null : String(rawBefore);
-		const toValue = rawAfter == null ? null : String(rawAfter);
-		if (fromValue === toValue) continue;
-		rows.push({
-			id: (0, node_crypto.randomUUID)(),
-			issueId: before.id,
-			field,
-			fromValue,
-			toValue,
-			actorKind: actor.kind,
-			actorId: actor.id ?? null,
-			sourceChatSessionId: actor.sourceChatSessionId ?? null,
-			createdAt: now
-		});
+/** How long a description line may run before it is cut with an ellipsis. */
+const DESCRIPTION_LINE_LIMIT = 120;
+function cardDisplayTitle(card) {
+	if (card.title !== card.id) return card.title;
+	return descriptionFirstLine(card.description) ?? card.title;
+}
+function descriptionFirstLine(description) {
+	for (const rawLine of (description ?? "").split("\n")) {
+		const line = stripMarkdown(rawLine);
+		if (line) return line.length > DESCRIPTION_LINE_LIMIT ? `${line.slice(0, 119).trimEnd()}…` : line;
 	}
-	return rows;
+	return null;
+}
+function stripMarkdown(line) {
+	return line.replace(/^\s*(?:>\s*)+/, "").replace(/^\s*#{1,6}\s+/, "").replace(/^\s*(?:[-*+]|\d+[.)])\s+(?:\[[ x]\]\s+)?/i, "").replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/<[^>]+>/g, "").replace(/[*_~`]/g, "").replace(/\s+/g, " ").trim();
 }
 //#endregion
 //#region src/domain/status-name.ts
@@ -1137,6 +1116,603 @@ function normalizeStatusName(value) {
 	return value.trim().toLowerCase().replace(/[\s-]+/g, "_");
 }
 //#endregion
+//#region src/domain/flow-rules.ts
+/** The two flow rules, as an unmet entry names them. */
+const FLOW_RULES = ["allowed_from", "wip_limit"];
+/** The column the standard flow guards, and the columns it lets cards in from, by slug. */
+const STANDARD_FLOW_TARGET = "done";
+const STANDARD_FLOW_SOURCES = ["in_review", "qa"];
+/** A column's flow rules, out of what the row stores. */
+function readFlowRules(column) {
+	return {
+		allowedFrom: column.allowedFrom === null ? null : JSON.parse(column.allowedFrom),
+		wipLimit: column.wipLimit
+	};
+}
+/** A list of column ids as the row stores it: `null` stays `null`, and an empty list stays an empty list. */
+function serializeAllowedFrom(allowedFrom) {
+	return allowedFrom === null ? null : JSON.stringify(allowedFrom);
+}
+/**
+* The flow rules a card entering `column` does not meet, where it may come from
+* first. Pure: what the board holds arrives in `facts`. A card being created
+* comes from no column, so a column that names where cards come from does not
+* take it.
+*/
+function evaluateFlowRules(card, column, rules, facts) {
+	const unmet = [];
+	if (rules.allowedFrom !== null && (card.statusId === null || !rules.allowedFrom.includes(card.statusId))) unmet.push({
+		rule: "allowed_from",
+		reason: "not_allowed_from",
+		detail: describeAllowedFrom(column.name, rules.allowedFrom, facts.columnNames)
+	});
+	if (rules.wipLimit !== null && facts.cardsInColumn >= rules.wipLimit) unmet.push({
+		rule: "wip_limit",
+		reason: "column_full",
+		detail: `${column.name} holds ${facts.cardsInColumn} of ${rules.wipLimit}`
+	});
+	return unmet;
+}
+function describeAllowedFrom(name, allowedFrom, columnNames) {
+	const names = allowedFrom.map((id) => columnNames.get(id)).filter((found) => found !== void 0);
+	return names.length === 0 ? `${name} accepts cards from no column; only a person may put a card here` : `${name} accepts cards from ${joinWords(names)} only`;
+}
+/** `A`, `A and B`, `A, B and C`. */
+function joinWords(words) {
+	return words.length <= 1 ? words.join("") : `${words.slice(0, -1).join(", ")} and ${words.at(-1)}`;
+}
+/**
+* The standard flow on these columns: Done, and the columns it takes cards from
+* — In Review, and QA when there is one — in board order. `null` when the board
+* has no Done, or neither of the two.
+*/
+function standardFlowOf(columns) {
+	const target = columns.find((column) => normalizeStatusName(column.name) === STANDARD_FLOW_TARGET);
+	const sources = columns.filter((column) => STANDARD_FLOW_SOURCES.includes(normalizeStatusName(column.name)));
+	return target && sources.length > 0 ? {
+		target,
+		sources
+	} : null;
+}
+//#endregion
+//#region src/domain/iso-week.ts
+const DAY_SECONDS$1 = 86400;
+/** The ISO week a moment falls in, read in UTC like every board date (ruling 5x-6). */
+function isoWeekOf(seconds) {
+	const day = Math.floor(seconds / DAY_SECONDS$1);
+	const monday = day - (day + 3) % 7;
+	const thursday = monday + 3;
+	const year = (/* @__PURE__ */ new Date(thursday * DAY_SECONDS$1 * 1e3)).getUTCFullYear();
+	const januaryFirst = Date.UTC(year, 0, 1) / 1e3 / DAY_SECONDS$1;
+	const week = Math.floor((thursday - januaryFirst) / 7) + 1;
+	return {
+		week: `${year}-W${String(week).padStart(2, "0")}`,
+		start: monday * DAY_SECONDS$1
+	};
+}
+/** The UTC day a moment falls on, as `2026-01-05`. */
+function utcDayLabel(seconds) {
+	return (/* @__PURE__ */ new Date(seconds * 1e3)).toISOString().slice(0, 10);
+}
+//#endregion
+//#region src/ops/card-timeline.ts
+/**
+* A card's columns over time, oldest first, from its creation on: the column
+* it was created in, then one stretch per move. A card created before 0.5.0
+* carries no entry for its creation; one created since carries `null → column`
+* at its creation, which leaves a stretch of no length in no column.
+*
+* The feed lists moves by time and then by change id, and a change id is
+* random, so two moves of one card in the same second can come back in either
+* order. Within one second the moves are put back in the order they chain —
+* each leaves the column the one before it entered — which is the order they
+* were made in (ruling R012-5). Moves that do not chain keep the feed's order.
+*/
+function buildCardTimeline(card, entries) {
+	const ordered = chainSameSecond(entries.toSorted((left, right) => left.at - right.at || (left.changeId < right.changeId ? -1 : left.changeId > right.changeId ? 1 : 0)));
+	const stretches = [];
+	const first = ordered[0];
+	let current = {
+		statusId: first ? first.fromStatusId : card.statusId,
+		from: card.createdAt,
+		to: null
+	};
+	for (const entry of ordered) {
+		stretches.push({
+			...current,
+			to: entry.at
+		});
+		current = {
+			statusId: entry.toStatusId,
+			from: entry.at,
+			to: null
+		};
+	}
+	stretches.push(current);
+	return stretches;
+}
+/** The column the card was in at `at` — a move at `at` has already happened — or `undefined` before the card existed. */
+function statusAt(stretches, at) {
+	return stretches.find((stretch) => stretch.from <= at && (stretch.to === null || at < stretch.to))?.statusId;
+}
+function chainSameSecond(entries) {
+	const ordered = [];
+	let start = 0;
+	while (start < entries.length) {
+		let end = start;
+		while (end < entries.length && entries[end].at === entries[start].at) end++;
+		const group = entries.slice(start, end);
+		const previous = ordered.at(-1);
+		let current = previous ? previous.toStatusId : headOf(group)?.fromStatusId;
+		while (group.length > 0) {
+			let next = group.findIndex((entry) => entry.fromStatusId === current);
+			if (next < 0) next = Math.max(group.findIndex((entry) => entry === headOf(group)), 0);
+			const [picked] = group.splice(next, 1);
+			ordered.push(picked);
+			current = picked.toStatusId;
+		}
+		start = end;
+	}
+	return ordered;
+}
+/** The move nothing else in the group feeds into. */
+function headOf(group) {
+	return group.find((entry) => !group.some((other) => other !== entry && other.toStatusId === entry.fromStatusId));
+}
+//#endregion
+//#region src/ops/board-metrics.ts
+const DAY_SECONDS = 86400;
+const WEEK_SECONDS$1 = 7 * DAY_SECONDS;
+/**
+* The value at `percent` of `values` by nearest rank (ruling R012-2): the
+* ⌈percent·n/100⌉-th in ascending order. Always a value that occurred; `null`
+* for none.
+*/
+function nearestRank(values, percent) {
+	if (values.length === 0) return null;
+	const sorted = values.toSorted((left, right) => left - right);
+	return sorted[Math.max(Math.ceil(percent * sorted.length / 100), 1) - 1];
+}
+/** Who a run counts under in the agent rows: the host's agent id when the run names one, else the name it was started under. */
+function boardMetricsAgentKey(run) {
+	return run.agentId ?? run.agentName;
+}
+function scopeOf(history, input) {
+	const workspaceIds = new Set(input.workspaceIds);
+	const milestoneId = input.milestoneId ?? null;
+	const statusById = new Map(history.statuses.filter((status) => workspaceIds.has(status.workspaceId)).map((status) => [status.id, status]));
+	const cards = history.cards.filter((card) => workspaceIds.has(card.workspaceId)).filter((card) => milestoneId === null || card.milestoneId === milestoneId);
+	const isCanceled = (card) => card.statusId !== null && statusById.get(card.statusId)?.category === "canceled";
+	return {
+		statusById,
+		counted: cards.filter((card) => !isCanceled(card)),
+		canceled: cards.filter(isCanceled)
+	};
+}
+/**
+* The runs of the counted cards, and apart those of the cards in a canceled
+* column (R012-6): what a host prices to put a cost beside the metrics, and the
+* spend on canceled work on a line of its own.
+*/
+function boardMetricsRuns(history, input) {
+	const { counted, canceled } = scopeOf(history, input);
+	const countedIds = new Set(counted.map((card) => card.id));
+	const canceledIds = new Set(canceled.map((card) => card.id));
+	return {
+		counted: history.runs.filter((run) => countedIds.has(run.issueId)),
+		canceled: history.runs.filter((run) => canceledIds.has(run.issueId))
+	};
+}
+/** Who made a return, as `returns.byActorKind` counts it: a person, an agent (a provider target stands in for one), or a writer from outside. */
+function returnerOf(entry) {
+	if (entry.actorKind === "user") return "user";
+	return entry.actorKind === "system" ? "external" : "agent";
+}
+/**
+* The metrics of `input` over rows already read. Pure: the same rows give the
+* same answer in any order, so a host may put several boards' rows together
+* and compute once — percentiles of parts do not add up to the whole's.
+*/
+function computeBoardMetrics(history, input, now) {
+	if (input.from > input.to) throw new require_migrations_path.BoardError("board_metrics_range_invalid", {
+		from: input.from,
+		to: input.to
+	});
+	const milestoneId = input.milestoneId ?? null;
+	if (milestoneId !== null && !history.milestones.some((milestone) => milestone.id === milestoneId && input.workspaceIds.includes(milestone.workspaceId))) throw new require_migrations_path.BoardError("issue_milestone_not_found", { milestoneId });
+	const from = input.from;
+	const to = Math.min(input.to, now);
+	const inRange = (at) => from <= at && at <= to;
+	const { statusById, counted, canceled } = scopeOf(history, input);
+	const columns = groupColumns(input.workspaceIds, [...statusById.values()]);
+	const slugOf = (statusId) => {
+		const status = statusId === null ? void 0 : statusById.get(statusId);
+		return status ? normalizeStatusName(status.name) : null;
+	};
+	const categoryOf = (statusId) => statusId === null ? null : statusById.get(statusId)?.category ?? null;
+	const isReturn = (entry) => {
+		const source = entry.fromStatusId === null ? void 0 : statusById.get(entry.fromStatusId);
+		const target = statusById.get(entry.toStatusId);
+		return source !== void 0 && target !== void 0 && source.workspaceId === target.workspaceId && target.order < source.order && (target.category === "unstarted" || target.category === "started");
+	};
+	const entriesByCard = groupBy(history.entries, (entry) => entry.issueId);
+	const timelineOf = (card) => buildCardTimeline(card, entriesByCard.get(card.id) ?? []);
+	const countedIds = new Set(counted.map((card) => card.id));
+	const facts = counted.map((card) => {
+		const stretches = timelineOf(card);
+		return {
+			card,
+			stretches,
+			startedAt: stretches.find((stretch) => categoryOf(stretch.statusId) === "started")?.from ?? null
+		};
+	});
+	const finished = facts.filter((fact) => categoryOf(fact.card.statusId) === "completed").map((fact) => ({
+		...fact,
+		finishedAt: fact.stretches.at(-1).from
+	})).filter((fact) => inRange(fact.finishedAt)).toSorted((left, right) => left.finishedAt - right.finishedAt || left.card.id.localeCompare(right.card.id));
+	const runsByCard = groupBy(history.runs.filter((run) => countedIds.has(run.issueId)), (run) => run.issueId);
+	const returnsByCard = groupBy(history.entries.filter((entry) => countedIds.has(entry.issueId) && isReturn(entry)), (entry) => entry.issueId);
+	const finishedCards = finished.map((fact) => ({
+		...cardOf(fact.card),
+		startedAt: fact.startedAt,
+		finishedAt: fact.finishedAt,
+		cycleSeconds: fact.startedAt === null ? null : fact.finishedAt - fact.startedAt,
+		leadSeconds: fact.finishedAt - fact.card.createdAt,
+		returns: returnsByCard.get(fact.card.id)?.length ?? 0,
+		runs: runsByCard.get(fact.card.id)?.length ?? 0
+	}));
+	const cycleTime = durations(finishedCards.flatMap((card) => card.cycleSeconds === null ? [] : [card.cycleSeconds]));
+	const leadTime = durations(finishedCards.map((card) => card.leadSeconds));
+	const throughput = [];
+	for (let start = isoWeekOf(from).start; from <= to && start <= to; start += WEEK_SECONDS$1) throughput.push({
+		week: isoWeekOf(start).week,
+		start,
+		finished: finishedCards.filter((card) => card.finishedAt >= start && card.finishedAt < start + WEEK_SECONDS$1).length
+	});
+	const inProgress = facts.filter((fact) => categoryOf(fact.card.statusId) === "started");
+	const wip = columns.filter((column) => column.category === "started").map((column) => {
+		const limits = [...statusById.values()].filter((status) => normalizeStatusName(status.name) === column.slug).map((status) => readFlowRules(status).wipLimit);
+		return {
+			slug: column.slug,
+			cards: inProgress.filter((fact) => slugOf(fact.card.statusId) === column.slug).length,
+			limit: limits.every((limit) => limit !== null) ? limits.reduce((sum, limit) => sum + limit, 0) : null
+		};
+	});
+	const aging = inProgress.map((fact) => {
+		const current = fact.stretches.at(-1);
+		const startedAt = fact.startedAt ?? current.from;
+		return {
+			...cardOf(fact.card),
+			slug: slugOf(fact.card.statusId),
+			startedAt,
+			ageSeconds: now - startedAt,
+			inColumnSeconds: now - current.from,
+			overCycleP85: cycleTime.p85 !== null && now - startedAt > cycleTime.p85
+		};
+	}).toSorted((left, right) => right.ageSeconds - left.ageSeconds || left.issueId.localeCompare(right.issueId));
+	const columnSeconds = new Map(columns.map((column) => [column.slug, 0]));
+	for (const fact of finished) for (const stretch of fact.stretches) {
+		const slug = slugOf(stretch.statusId);
+		const end = Math.min(stretch.to ?? fact.finishedAt, fact.finishedAt);
+		if (slug !== null && end > stretch.from) columnSeconds.set(slug, (columnSeconds.get(slug) ?? 0) + end - stretch.from);
+	}
+	const cumulativeFlow = [];
+	for (let dayStart = utcDayStart(from); from <= to && dayStart <= to; dayStart += DAY_SECONDS) {
+		const at = Math.min(dayStart + DAY_SECONDS - 1, to);
+		const cards = Object.fromEntries(columns.map((column) => [column.slug, 0]));
+		for (const fact of facts) {
+			const statusId = statusAt(fact.stretches, at);
+			const slug = statusId === void 0 ? null : slugOf(statusId);
+			if (slug !== null) cards[slug] = (cards[slug] ?? 0) + 1;
+		}
+		cumulativeFlow.push({
+			day: utcDayLabel(dayStart),
+			at,
+			cards
+		});
+	}
+	const finishedReturns = finished.flatMap((fact) => returnsByCard.get(fact.card.id) ?? []);
+	const byActorKind = {
+		user: 0,
+		agent: 0,
+		external: 0
+	};
+	for (const entry of finishedReturns) byActorKind[returnerOf(entry)]++;
+	const runTotal = finishedCards.reduce((sum, card) => sum + card.runs, 0);
+	const share = (part, whole) => whole === 0 ? null : part / whole;
+	return {
+		range: {
+			from,
+			to
+		},
+		now,
+		milestoneId,
+		columns,
+		cycleTime,
+		leadTime,
+		throughput,
+		wip,
+		aging,
+		timeInColumn: columns.map((column) => ({
+			slug: column.slug,
+			seconds: columnSeconds.get(column.slug) ?? 0
+		})),
+		cumulativeFlow,
+		finished: finishedCards,
+		returns: {
+			total: finishedReturns.length,
+			perFinishedCard: share(finishedReturns.length, finishedCards.length),
+			firstPassRate: share(finishedCards.filter((card) => card.returns === 0).length, finishedCards.length),
+			byActorKind
+		},
+		attempts: {
+			runs: runTotal,
+			perFinishedCard: share(runTotal, finishedCards.length)
+		},
+		canceled: canceled.filter((card) => inRange(timelineOf(card).at(-1).from)).length,
+		agents: agentRows(history.runs.filter((run) => countedIds.has(run.issueId)), finishedCards, inRange),
+		people: personRows(counted, history, countedIds, inRange, isReturn)
+	};
+}
+function agentRows(runs, finished, inRange) {
+	const finishedIds = new Set(finished.map((card) => card.issueId));
+	const returned = new Set(finished.filter((card) => card.returns > 0).map((card) => card.issueId));
+	const rows = [];
+	for (const [key, own] of groupBy(runs, boardMetricsAgentKey)) {
+		const ranged = own.filter((run) => inRange(run.startedAt));
+		const worked = new Set(own.map((run) => run.issueId).filter((issueId) => finishedIds.has(issueId)));
+		if (ranged.length === 0 && worked.size === 0) continue;
+		const newest = own.toSorted((left, right) => right.startedAt - left.startedAt || right.id.localeCompare(left.id))[0];
+		const ended = ranged.flatMap((run) => run.endedAt === null ? [] : [run.endedAt - run.startedAt]);
+		rows.push({
+			key,
+			agentId: newest.agentId,
+			agentName: newest.agentName,
+			runs: {
+				total: ranged.length,
+				finished: ranged.filter((run) => run.state === "finished").length,
+				failed: ranged.filter((run) => run.state === "failed").length,
+				stopped: ranged.filter((run) => run.state === "stopped").length,
+				running: ranged.filter((run) => run.state === "running").length
+			},
+			medianRunSeconds: nearestRank(ended, 50),
+			cardsFinished: worked.size,
+			returnRate: worked.size === 0 ? null : [...worked].filter((issueId) => returned.has(issueId)).length / worked.size
+		});
+	}
+	return rows.toSorted((left, right) => right.runs.total - left.runs.total || left.key.localeCompare(right.key));
+}
+function personRows(counted, history, countedIds, inRange, isReturn) {
+	const rows = /* @__PURE__ */ new Map();
+	const row = (id) => {
+		let found = rows.get(id);
+		if (!found) {
+			found = {
+				id,
+				created: 0,
+				approvals: 0,
+				returns: 0,
+				moves: 0
+			};
+			rows.set(id, found);
+		}
+		return found;
+	};
+	for (const card of counted) if (card.createdByKind === "user" && inRange(card.createdAt)) row(card.createdById).created++;
+	for (const comment of history.approvals) if (comment.authorKind === "system.approved" && countedIds.has(comment.issueId) && inRange(comment.createdAt)) row(comment.authorId).approvals++;
+	for (const entry of history.entries) if (entry.actorKind === "user" && entry.fromStatusId !== null && countedIds.has(entry.issueId) && inRange(entry.at)) {
+		const person = row(entry.actorId);
+		person.moves++;
+		if (isReturn(entry)) person.returns++;
+	}
+	const activity = (person) => person.created + person.approvals + person.returns + person.moves;
+	return [...rows.values()].toSorted((left, right) => activity(right) - activity(left) || (left.id ?? "￿").localeCompare(right.id ?? "￿"));
+}
+/**
+* The workspaces' columns as one board shows them, one per slug (ruling
+* R012-8): the first workspace's columns set the order, and a column only a
+* later one has goes right after the column before it there. Name and category
+* are the first workspace's that has it.
+*/
+function groupColumns(workspaceIds, statuses) {
+	const columns = [];
+	for (const workspaceId of new Set(workspaceIds)) {
+		let previous = -1;
+		const own = statuses.filter((status) => status.workspaceId === workspaceId).toSorted((left, right) => left.order - right.order || left.id.localeCompare(right.id));
+		for (const status of own) {
+			const slug = normalizeStatusName(status.name);
+			let index = columns.findIndex((column) => column.slug === slug);
+			if (index === -1) {
+				index = previous + 1;
+				columns.splice(index, 0, {
+					slug,
+					name: status.name,
+					category: status.category
+				});
+			}
+			previous = index;
+		}
+	}
+	return columns;
+}
+function durations(values) {
+	return {
+		cards: values.length,
+		p50: nearestRank(values, 50),
+		p85: nearestRank(values, 85)
+	};
+}
+function cardOf(card) {
+	return {
+		issueId: card.id,
+		workspaceId: card.workspaceId,
+		title: cardDisplayTitle(card)
+	};
+}
+function groupBy(items, keyOf) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const item of items) {
+		const key = keyOf(item);
+		const group = groups.get(key);
+		if (group) group.push(item);
+		else groups.set(key, [item]);
+	}
+	return groups;
+}
+//#endregion
+//#region src/ops/column-entries.ts
+/**
+* Every entry into a column on the named boards at or after `since`, in order
+* of `(at, changeId)` — the one signal an app dispatching work on column
+* changes needs. It sees every writer, an outside `kanbo` on the same database
+* included, because it reads the cards' own history.
+*
+* A page never ends inside a second: when `limit` cuts into one, the rest of
+* that second comes too, so a page may be longer than `limit`. A reader keeps
+* its cursor at the last `at` it read after a short page — a write in that
+* second may still commit — and drops the `changeId`s it has seen; after a page
+* of `limit` or more it moves on to the last `at` + 1, which a second holding
+* more entries than `limit` would otherwise never let it pass.
+*/
+async function listColumnEntries(store, input) {
+	const page = await store.fieldChanges.listByFieldSince("statusId", input);
+	return (input.limit !== void 0 && input.limit > 0 && page.length === input.limit ? await withWholeLastSecond(store, input, page) : page).flatMap(toColumnEntry);
+}
+/** The page with every change of its last second, not only those `limit` let in. */
+async function withWholeLastSecond(store, input, page) {
+	const last = page.at(-1).createdAt;
+	const lastSecond = await store.fieldChanges.listByFieldSince("statusId", {
+		workspaceIds: input.workspaceIds,
+		since: last,
+		until: last
+	});
+	return [...page.filter((change) => change.createdAt < last), ...lastSecond];
+}
+/** A status change as an entry; a change that took the card out of every column enters none. */
+function toColumnEntry(change) {
+	return change.toValue === null ? [] : [{
+		changeId: change.id,
+		issueId: change.issueId,
+		workspaceId: change.workspaceId,
+		fromStatusId: change.fromValue,
+		toStatusId: change.toValue,
+		actorKind: change.actorKind,
+		actorId: change.actorId,
+		at: change.createdAt
+	}];
+}
+//#endregion
+//#region src/ops/board-metrics-read.ts
+/** The comment kind the metrics read: a person's approvals. Returns are moves (R012-7). */
+const APPROVAL_KINDS = ["system.approved"];
+/** `listColumnEntries` from the board's first column change on (drift check, item 3). */
+const FROM_THE_FIRST_CHANGE = 0;
+/**
+* Every row the metrics of these workspaces are computed from: three
+* statements per workspace (columns, milestones, cards) plus three across all
+* of them (column changes through the `(field, created_at)` index, runs,
+* approvals); none per card.
+*
+* The rows are read and the metrics computed in TypeScript rather than in SQL
+* (ruling R012-1): a board is thousands of rows, not millions; percentiles, ISO
+* weeks and a day-by-day replay would otherwise be written once per dialect;
+* and a host whose workspaces live on several boards can put their rows
+* together and compute once.
+*/
+async function readBoardMetricsHistory(store, workspaceIds) {
+	const ids = [...new Set(workspaceIds)];
+	if (ids.length === 0) return {
+		statuses: [],
+		milestones: [],
+		cards: [],
+		entries: [],
+		runs: [],
+		approvals: []
+	};
+	const perWorkspace = async (read) => (await Promise.all(ids.map(read))).flat();
+	const [statuses, milestones, cards, entries, runs, approvals] = await Promise.all([
+		perWorkspace(async (id) => await store.statuses.listByWorkspace(id)),
+		perWorkspace(async (id) => await store.milestones.listByWorkspace(id)),
+		perWorkspace(async (id) => await store.issues.listByWorkspace(id)),
+		listColumnEntries(store, {
+			workspaceIds: ids,
+			since: FROM_THE_FIRST_CHANGE
+		}),
+		store.runs.listByWorkspaces(ids),
+		store.comments.listByWorkspaces(ids, APPROVAL_KINDS)
+	]);
+	return {
+		statuses,
+		milestones,
+		cards,
+		entries,
+		runs,
+		approvals
+	};
+}
+/** How work flows on the board over `input`'s range (`computeBoardMetrics`), read from the store; without cost. */
+async function boardMetrics(store, input, now = currentUnixSeconds()) {
+	return computeBoardMetrics(await readBoardMetricsHistory(store, input.workspaceIds), input, now);
+}
+//#endregion
+//#region src/domain/field-changes.ts
+/**
+* The issue columns whose edits are written to the audit trail.
+*
+* `statusLine` is absent on purpose: `writeStatusLine` records every line it
+* writes itself, and no patch ever carries the column. `waitingFor` is absent
+* too — whose turn it is shows in the card's own line and in the
+* `system.approved` / `system.returned` comments around it, so a row saying the
+* same thing a third time would only crowd the history.
+*/
+const TRACKED_FIELDS = [
+	"workspaceId",
+	"title",
+	"description",
+	"priority",
+	"labels",
+	"milestoneId",
+	"parentIssueId",
+	"statusId",
+	"assigneeKind",
+	"assigneeId",
+	"dueDate",
+	"delegateAgentId",
+	"delegateProviderTargetId",
+	"contextRefs",
+	"executionMode",
+	"order"
+];
+/**
+* The audit rows one patch produces: a row per tracked field whose stringified
+* value actually changed. Nothing is written here — the caller inserts what
+* comes back, so the diff stays a pure function of the row, the patch, the
+* actor and the clock.
+*/
+function diffFieldChanges(before, updates, actor, now) {
+	const rows = [];
+	for (const field of TRACKED_FIELDS) {
+		if (!(field in updates)) continue;
+		const rawBefore = before[field === "labels" ? "labels" : field];
+		const rawAfter = updates[field];
+		const fromValue = rawBefore == null ? null : String(rawBefore);
+		const toValue = rawAfter == null ? null : String(rawAfter);
+		if (fromValue === toValue) continue;
+		rows.push({
+			id: (0, node_crypto.randomUUID)(),
+			issueId: before.id,
+			field,
+			fromValue,
+			toValue,
+			actorKind: actor.kind,
+			actorId: actor.id ?? null,
+			sourceChatSessionId: actor.sourceChatSessionId ?? null,
+			createdAt: now
+		});
+	}
+	return rows;
+}
+//#endregion
 //#region src/ops/change-seq.ts
 /** The `kanban_meta` row every board write bumps. */
 const BOARD_CHANGE_KEY = "board";
@@ -1372,7 +1948,9 @@ const UNMET_ENTRY_RULE_REASONS = [
 	"ci_red",
 	"approval_pending",
 	"returned",
-	"not_approved"
+	"not_approved",
+	"not_allowed_from",
+	"column_full"
 ];
 const entryRulesSchema = zod.z.array(zod.z.enum(ENTRY_RULES));
 /**
@@ -1588,6 +2166,7 @@ async function applyColumnTemplate(store, workspaceId, columns, options, scope)
 			workspaceId,
 			...column
 		}, order);
+		await writeStandardFlow(tx, await listColumns(tx, workspaceId));
 		return {
 			statuses: await listColumns(tx, workspaceId),
 			added: columns.map((column) => column.name)
@@ -1697,6 +2276,80 @@ async function setColumnEntryRules(store, workspaceId, nameOrId, entryRules, act
 		return await updateColumn(tx, (await requireColumn(tx, workspaceId, nameOrId)).id, { entryRules }, actor, { tx });
 	}, scope);
 }
+/** The largest WIP limit: what a Postgres `integer` column holds. */
+const MAX_WIP_LIMIT = 2147483647;
+/**
+* Set where a card may enter the column from and how many cards it holds:
+* `allowedFrom` the ids of other columns of its board (`null` for any, `[]` for
+* none), kept once each in board order; `wipLimit` a whole number from 1 to 2147483647, or `null`. A
+* person's to set, like the entry rules: an agent that could open a column
+* could walk any card into it.
+*/
+async function setColumnFlowRules(store, columnId, rules, actor, scope) {
+	assertPersonSetsEntryRules(actor, { statusId: columnId });
+	if (rules.wipLimit !== null && !(Number.isSafeInteger(rules.wipLimit) && rules.wipLimit >= 1 && rules.wipLimit <= MAX_WIP_LIMIT)) throw new require_migrations_path.BoardError("board_flow_rule_invalid", {
+		statusId: columnId,
+		wipLimit: rules.wipLimit
+	});
+	return await runBoardWrite(store, async ({ tx }) => {
+		const column = await tx.statuses.findById(columnId);
+		if (!column) throw new require_migrations_path.BoardError("issue_status_not_found", { statusId: columnId });
+		const allowedFrom = rules.allowedFrom === null ? null : allowedFromInBoardOrder(await listColumns(tx, column.workspaceId), column, rules.allowedFrom);
+		await tx.statuses.update(columnId, {
+			allowedFrom: serializeAllowedFrom(allowedFrom),
+			wipLimit: rules.wipLimit
+		});
+		return await tx.statuses.findById(columnId);
+	}, scope);
+}
+/** The ids asked for, once each and in board order — or the refusal naming those that are not another column of this board. */
+function allowedFromInBoardOrder(columns, column, requested) {
+	const others = columns.filter((other) => other.id !== column.id);
+	const invalid = requested.filter((id) => !others.some((other) => other.id === id));
+	if (invalid.length > 0) throw new require_migrations_path.BoardError("board_flow_rule_invalid", {
+		statusId: column.id,
+		allowedFrom: invalid
+	});
+	return others.filter((other) => requested.includes(other.id)).map((other) => other.id);
+}
+/**
+* Put the standard flow on a board: Done accepts cards from In Review only —
+* and from QA, when the board has it — so nothing reaches Done but through
+* review. Done's WIP limit and every other column stay as they are. A board
+* without Done, or with neither In Review nor QA, has nothing to apply it to.
+*/
+async function applyStandardFlow(store, workspaceId, actor, scope) {
+	assertPersonSetsEntryRules(actor, { workspaceId });
+	return await runBoardWrite(store, async ({ tx }) => {
+		const columns = await listColumns(tx, workspaceId);
+		if (!await writeStandardFlow(tx, columns)) {
+			const hasDone = columns.some((column) => normalizeStatusName(column.name) === STANDARD_FLOW_TARGET);
+			throw new require_migrations_path.BoardError("issue_status_not_found", {
+				workspaceId,
+				statusName: hasDone ? "In Review" : "Done"
+			});
+		}
+		return await listColumns(tx, workspaceId);
+	}, scope);
+}
+/** Done takes cards from the board's In Review and QA; `false`, with nothing written, when the board has no such columns. */
+async function writeStandardFlow(store, columns) {
+	const flow = standardFlowOf(columns);
+	if (!flow) return false;
+	await store.statuses.update(flow.target.id, { allowedFrom: serializeAllowedFrom(flow.sources.map((column) => column.id)) });
+	return true;
+}
+/**
+* Take a deleted column out of every list of where cards may come from. A list
+* it empties stays empty: a column that took cards only from it does not open
+* to every column.
+*/
+async function dropFromAllowedFrom(store, workspaceId, statusId) {
+	for (const other of await listColumns(store, workspaceId)) {
+		const { allowedFrom } = readFlowRules(other);
+		if (allowedFrom?.includes(statusId)) await store.statuses.update(other.id, { allowedFrom: serializeAllowedFrom(allowedFrom.filter((id) => id !== statusId)) });
+	}
+}
 /**
 * Take an empty column off the board, and number the columns left 0..n-1 in
 * the same write.
@@ -1723,6 +2376,7 @@ async function deleteColumn(store, statusId, scope, actor) {
 			hint: "Move its cards to another column first, or remove it with removeColumn and moveCardsTo."
 		});
 		await tx.statuses.delete(statusId);
+		await dropFromAllowedFrom(tx, column.workspaceId, statusId);
 		await renumberColumns(tx, column.workspaceId);
 	}, scope);
 }
@@ -2002,24 +2656,46 @@ function pullRequestFactKeys({ owner, repo, number }) {
 //#endregion
 //#region src/ops/entry-rules.ts
 /**
-* The column's entry rules the card does not meet (ruling 6-2). A column with
-* no rules answers at once, without reading anything; otherwise only the facts
-* the column's rules need are read.
+* The column's entry rules and flow rules the card does not meet, entry rules
+* first (ruling 6-2; board-workflow spec, Part 2). A column with no rules
+* answers at once, without reading anything; otherwise only the facts its
+* rules need are read. `entering` counts the cards this same write already let
+* into the column, so a bulk move is held to the WIP limit as a whole.
 */
-async function checkColumnEntry(store, card, column) {
+async function checkColumnEntry(store, card, column, entering) {
 	const rules = readEntryRules(column);
-	if (rules.length === 0) return [];
-	return evaluateEntryRules(card, rules, await readEntryRuleFacts(store, card.id, rules)).unmet;
+	const unmet = rules.length === 0 ? [] : evaluateEntryRules(card, rules, await readEntryRuleFacts(store, card.id, rules)).unmet;
+	const flow = readFlowRules(column);
+	if (flow.allowedFrom === null && flow.wipLimit === null) return unmet;
+	return [...unmet, ...evaluateFlowRules(card, column, flow, await readFlowRuleFacts(store, column, flow, entering))];
+}
+/** What the flow rules need: the board's column names when the column names where cards come from, and its card count when it has a limit. */
+async function readFlowRuleFacts(store, column, flow, entering) {
+	const columnNames = flow.allowedFrom === null ? /* @__PURE__ */ new Map() : new Map((await store.statuses.listByWorkspace(column.workspaceId)).map((other) => [other.id, other.name]));
+	if (flow.wipLimit === null) return {
+		columnNames,
+		cardsInColumn: 0
+	};
+	await store.statuses.lockById(column.id);
+	return {
+		columnNames,
+		cardsInColumn: (await store.issues.listPage({
+			workspaceId: column.workspaceId,
+			statusIds: [column.id],
+			limit: 1
+		})).total + entering
+	};
 }
 /**
-* Hold a card at the door of a column that asks for more than it has (ruling
-* 6-3). Anyone but a person — or a person's own terminal, `placesForPerson`
-* (ruling 6-6) — is refused with `board_column_rules_unmet`, which
-* names the column and every unmet rule; a person is let through, and the
-* unmet rules come back so the caller can warn them.
+* Hold a card at the door of a column that asks for more than it has — entry
+* rules (ruling 6-3), or flow rules: a column it may not come from, or a column
+* that is full. Anyone but a person — or a person's own terminal,
+* `placesForPerson` (ruling 6-6) — is refused with `board_column_rules_unmet`,
+* which names the column and everything unmet; a person is let through, and
+* the unmet list comes back so the caller can warn them.
 */
-async function enforceColumnEntry(store, card, column, actor) {
-	const unmet = await checkColumnEntry(store, card, column);
+async function enforceColumnEntry(store, card, column, actor, entering = 0) {
+	const unmet = await checkColumnEntry(store, card, column, entering);
 	if (unmet.length > 0 && actor.kind !== "user" && !actor.placesForPerson) throw new require_migrations_path.BoardError("board_column_rules_unmet", {
 		issueId: card.id,
 		column: column.name,
@@ -2032,14 +2708,17 @@ async function enforceColumnEntry(store, card, column, actor) {
 * The same door for several cards entering one column at once — a bulk status
 * change. All or nothing: the first card an agent may not move refuses the
 * whole change. A person gets back the cards that entered with rules unmet.
+* Each card counts against the column's WIP limit as the cards before it in the same change entered it.
 */
 async function enforceColumnEntryForCards(store, issueIds, statusId, actor) {
 	const column = await store.statuses.findById(statusId);
 	if (!column) throw new require_migrations_path.BoardError("issue_status_not_found", { statusId });
 	const entered = [];
+	let entering = 0;
 	for (const card of await store.issues.listByIds(issueIds)) {
 		if (card.statusId === column.id) continue;
-		const unmet = await enforceColumnEntry(store, card, column, actor);
+		const unmet = await enforceColumnEntry(store, card, column, actor, entering);
+		entering++;
 		if (unmet.length > 0) entered.push({
 			issueId: card.id,
 			unmet
@@ -2194,11 +2873,24 @@ const STOPPED_BY_YOU_STATUS_LINE = "stopped by you";
 * the board reads the same whether the agent was launched by an app or from
 * somewhere else entirely. The attempt number is simply how many runs the card
 * has had — a card whose runs were all launched elsewhere still counts them.
+*
+* A card has one run going at a time. A start on a card whose run is still going
+* is refused with `board_card_run_active`, naming that run — whichever path it
+* came by, an app's launch, `kanbo run start`, MCP, or a second app on a shared
+* Postgres board. The card's row is locked first, so two starts racing for it
+* are settled one after the other.
 */
 async function startRun(store, issueId, input, actor, scope) {
 	const externalSessionRef = readExternalSessionRef(input.externalSessionRef) ?? null;
 	return await runBoardWrite(store, async ({ tx }) => {
-		const card = await requireCard$1(tx, issueId);
+		const card = await tx.issues.lockById(issueId);
+		if (!card) throw new require_migrations_path.BoardError("issue_not_found", { issueId });
+		const [active] = await tx.runs.listRunning(issueId);
+		if (active) throw new require_migrations_path.BoardError("board_card_run_active", {
+			issueId,
+			runId: active.id,
+			agentName: active.agentName
+		});
 		const attempt = await tx.runs.countByIssue(issueId) + 1;
 		const executionMode = input.executionMode ?? card.executionMode;
 		const run = await tx.runs.create({
@@ -2464,7 +3156,8 @@ async function createCard(store, input, actor, scope) {
 		const column = statusId === null ? null : await tx.statuses.findById(statusId);
 		const unmet = column ? await enforceColumnEntry(tx, {
 			id: null,
-			description: input.description ?? null
+			description: input.description ?? null,
+			statusId: null
 		}, column, actor) : [];
 		const milestoneId = await requireMilestoneInWorkspace(tx, workspaceId, input.milestoneId ?? null);
 		const parentIssueId = await requireParentInWorkspace(tx, workspaceId, input.parentIssueId ?? null);
@@ -2472,8 +3165,9 @@ async function createCard(store, input, actor, scope) {
 		const now = currentUnixSeconds();
 		for (let attempt = 1;; attempt++) {
 			const identity = await nextIssueIdentity(input.workspace, tx);
+			let created;
 			try {
-				return withUnmetRules(await tx.issues.create({
+				created = await tx.issues.create({
 					id: identity.id,
 					workspaceId,
 					title: input.title?.trim() || identity.id,
@@ -2497,12 +3191,25 @@ async function createCard(store, input, actor, scope) {
 					order,
 					createdAt: now,
 					updatedAt: now
-				}), unmet);
+				});
 			} catch (error) {
 				const numberTaken = await tx.issues.findByNumber(workspaceId, identity.number);
 				const keyTaken = await tx.issues.findById(identity.id);
 				if (attempt >= NUMBERING_ATTEMPTS || !numberTaken && !keyTaken) throw error;
+				continue;
 			}
+			if (statusId !== null) await tx.fieldChanges.create({
+				id: (0, node_crypto.randomUUID)(),
+				issueId: created.id,
+				field: "statusId",
+				fromValue: null,
+				toValue: statusId,
+				actorKind: toStoredActorKind(actor),
+				actorId: actor.id ?? null,
+				sourceChatSessionId: actor.chatSessionId ?? null,
+				createdAt: now
+			});
+			return withUnmetRules(created, unmet);
 		}
 	}, scope);
 }
@@ -2558,7 +3265,8 @@ async function updateCard(store, issueId, input, actor, scope) {
 			const description = "description" in updates ? updates.description ?? null : card.description;
 			unmet = await enforceColumnEntry(tx, {
 				id: card.id,
-				description
+				description,
+				statusId: card.statusId
 			}, column, actor);
 		}
 		if ("assigneeKind" in input) updates.assigneeKind = input.assigneeKind ?? null;
@@ -2936,25 +3644,137 @@ async function bulkUpdateCards(store, issueIds, input, actor, scope) {
 	}, scope);
 }
 /**
-* Give the named cards of one workspace their positions in the order named.
-*
-* Positions are spaced by a gap rather than packed, so a card dropped between
-* two others later can take a midpoint without moving its neighbours. The whole
-* order is one write — a drag that half-applied would leave a board no client
-* could reconcile — and a card that is gone or belongs to another workspace is
-* skipped rather than failing the rest of the drop.
+* Give the named cards of one workspace their positions in the order named.
+*
+* Positions are spaced by a gap rather than packed, so a card dropped between
+* two others later can take a midpoint without moving its neighbours. The whole
+* order is one write — a drag that half-applied would leave a board no client
+* could reconcile — and a card that is gone or belongs to another workspace is
+* skipped rather than failing the rest of the drop.
+*/
+async function reorderCards(store, workspaceId, orderedIds, scope) {
+	await runBoardWrite(store, async ({ tx }) => {
+		for (const [index, issueId] of orderedIds.entries()) {
+			const card = await tx.issues.findById(issueId);
+			if (!card || card.workspaceId !== workspaceId) continue;
+			await tx.issues.update(issueId, {
+				order: (index + 1) * CARD_ORDER_GAP,
+				updatedAt: currentUnixSeconds()
+			});
+		}
+	}, scope);
+}
+//#endregion
+//#region src/ops/ready.ts
+/** The column an agent takes its next card from. */
+const READY_COLUMN_SLUG = "to_do";
+/**
+* The cards an agent may pick up right now: spelled out, nobody working on them,
+* nobody's turn but the agent's.
+*
+* "Ready" is deliberately narrow. A card in Backlog is an idea, a card with a
+* run is taken, and a card waiting for a person belongs to that person until
+* they answer. What is left is the queue — in board order, so the card someone
+* dragged to the top is the one an agent asking for work gets.
+*/
+async function listReady(store, input) {
+	return (await queryReady(store, input)).cards;
+}
+/**
+* One page of the ready cards, how many are ready in all, and the columns read
+* on the way — the rule above, asked of the database in one statement rather
+* than of every card on the board.
+*/
+async function queryReady(store, input) {
+	const columns = await listColumns(store, input.workspaceId);
+	const column = columns.find((candidate) => normalizeStatusName(candidate.name) === READY_COLUMN_SLUG);
+	if (!column) return {
+		cards: [],
+		total: 0,
+		columns
+	};
+	return {
+		...await store.issues.listPage({
+			workspaceId: input.workspaceId,
+			statusIds: [column.id],
+			waitingForPerson: false,
+			hasActiveRun: false,
+			limit: input.limit,
+			offset: input.offset
+		}),
+		columns
+	};
+}
+//#endregion
+//#region src/ops/claim.ts
+/**
+* Take a card to work on, in one board write: pick it, start its run, and move
+* it into the board's first `started` column (In Progress on a standard
+* board), its entry and flow rules checked on the way in. Anything refused
+* leaves nothing written.
+*
+* Two claimers never get the same card. On SQLite the write holds the file
+* from its first read (`begin immediate`), so the second claimer reads the
+* board after the first one's commit. On Postgres the picked card's row is
+* locked (`select … for update`): a claimer that waited on the lock finds the
+* card taken, and moves on to the next ready one. The target's row is locked
+* first, always, in the order a move into it locks (column, then card), so a
+* claim and a move never wait on each other in a circle.
+*/
+async function claimCard(store, input, actor, scope) {
+	return await runBoardWrite(store, async ({ tx }) => {
+		const columns = await listColumns(tx, input.workspaceId);
+		const target = columns.find((column) => column.category === "started");
+		if (!target) throw new require_migrations_path.BoardError("issue_status_not_found", {
+			workspaceId: input.workspaceId,
+			category: "started"
+		});
+		await tx.statuses.lockById(target.id);
+		const toDo = columns.find((column) => normalizeStatusName(column.name) === "to_do") ?? null;
+		const card = input.issueId === void 0 ? await takeFirstReady(tx, input.workspaceId, toDo) : await takeNamed(tx, input.workspaceId, input.issueId, toDo);
+		const run = await startRun(tx, card.id, input.run, actor, { tx });
+		return {
+			card: await updateCard(tx, card.id, { statusId: target.id }, actor, { tx }),
+			run,
+			column: target
+		};
+	}, scope);
+}
+/**
+* The first ready card, locked. A card another claimer took while this one
+* waited for its lock is passed over, and the next read no longer lists it; the
+* cards passed over are counted so the loop ends with the list.
 */
-async function reorderCards(store, workspaceId, orderedIds, scope) {
-	await runBoardWrite(store, async ({ tx }) => {
-		for (const [index, issueId] of orderedIds.entries()) {
-			const card = await tx.issues.findById(issueId);
-			if (!card || card.workspaceId !== workspaceId) continue;
-			await tx.issues.update(issueId, {
-				order: (index + 1) * CARD_ORDER_GAP,
-				updatedAt: currentUnixSeconds()
-			});
-		}
-	}, scope);
+async function takeFirstReady(store, workspaceId, toDo) {
+	const passed = /* @__PURE__ */ new Set();
+	for (;;) {
+		const { cards } = await queryReady(store, {
+			workspaceId,
+			limit: passed.size + 1
+		});
+		const candidate = cards.find((card) => !passed.has(card.id));
+		if (!candidate) throw new require_migrations_path.BoardError("board_nothing_ready", { workspaceId });
+		const locked = await store.issues.lockById(candidate.id);
+		if (locked && await notReadyReason(store, locked, toDo) === null) return locked;
+		passed.add(candidate.id);
+	}
+}
+/** The named card, locked, when it is on this board and ready — or why not. */
+async function takeNamed(store, workspaceId, issueId, toDo) {
+	const card = await store.issues.lockById(issueId);
+	if (!card || card.workspaceId !== workspaceId) throw new require_migrations_path.BoardError("issue_not_found", { issueId });
+	const reason = await notReadyReason(store, card, toDo);
+	if (reason) throw new require_migrations_path.BoardError("board_card_not_ready", {
+		issueId,
+		reason
+	});
+	return card;
+}
+/** `queryReady`'s rule for one card already read: nobody on it, nobody waited for, in To Do. */
+async function notReadyReason(store, card, toDo) {
+	if ((await store.runs.listRunning(card.id)).length > 0) return "run_active";
+	if (card.waitingFor === "human") return "waiting_for_person";
+	return toDo !== null && card.statusId === toDo.id ? null : "not_in_to_do";
 }
 //#endregion
 //#region src/ops/context-refs.ts
@@ -3087,33 +3907,6 @@ async function migrateCards(store, input) {
 	};
 }
 //#endregion
-//#region src/domain/card-display-title.ts
-/**
-* What a card is called wherever a person or an agent reads it by name.
-*
-* A card written as a description alone is titled with its own key (every
-* writer does that). Named by its key, such a card says nothing — so its name
-* is the first line of its description instead. A browser bundle that does not
-* load this package keeps the same rule on its own, tested with the same
-* examples.
-*/
-/** How long a description line may run before it is cut with an ellipsis. */
-const DESCRIPTION_LINE_LIMIT = 120;
-function cardDisplayTitle(card) {
-	if (card.title !== card.id) return card.title;
-	return descriptionFirstLine(card.description) ?? card.title;
-}
-function descriptionFirstLine(description) {
-	for (const rawLine of (description ?? "").split("\n")) {
-		const line = stripMarkdown(rawLine);
-		if (line) return line.length > DESCRIPTION_LINE_LIMIT ? `${line.slice(0, 119).trimEnd()}…` : line;
-	}
-	return null;
-}
-function stripMarkdown(line) {
-	return line.replace(/^\s*(?:>\s*)+/, "").replace(/^\s*#{1,6}\s+/, "").replace(/^\s*(?:[-*+]|\d+[.)])\s+(?:\[[ x]\]\s+)?/i, "").replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/<[^>]+>/g, "").replace(/[*_~`]/g, "").replace(/\s+/g, " ").trim();
-}
-//#endregion
 //#region src/ops/agent-rules.ts
 /**
 * The sentences that tell an agent how to work this board, written once.
@@ -3141,6 +3934,7 @@ function subtaskSplitSentence(parentReference) {
 }
 const SUBTASK_RULE = `${SUBTASK_WHEN_SENTENCE} ${subtaskSplitSentence("the parent card's id")}`;
 const PULL_REQUEST_RULE = "Opened a pull request? Link it to the card. Its state and CI checks then reach the card as comments on their own — nothing else tells the board a pull request exists.";
+const CLAIM_RULE = "Taking a card from To Do yourself? Claim it instead of starting a run and moving it: the claim does both in one step, and no other agent gets the same card. Finish the run when you stop.";
 const OWN_SESSION_RULE = "Started the work yourself, not launched by an app that tracks the run for you? Record the run when you start and finish it when you stop. kanbo fills in the Claude Code or Codex session you are in; never invent a session id.";
 /** Said by the `kanbo init` block and the MCP instructions, which name the comment command or tool beside it. */
 const COMMENT_RULE = "Findings, results, decisions and questions go on the card as comments.";
@@ -3164,6 +3958,7 @@ const BOARD_RULES = [
 	EXECUTION_MODE_RULE,
 	SUBTASK_RULE,
 	PULL_REQUEST_RULE,
+	CLAIM_RULE,
 	OWN_SESSION_RULE,
 	"Read the column descriptions above before moving a card, and do all of this through the board tools or commands you have — a statement in your reply changes nothing."
 ];
@@ -3179,12 +3974,14 @@ const BOARD_RULES = [
 async function buildPrimeText(store, workspaceId) {
 	const columns = await listColumns(store, workspaceId);
 	const ruled = columns.some((column) => readEntryRules(column).length > 0);
+	const flowing = columns.some((column) => hasFlowRules(column));
 	return [
 		...await describeReturnedCards(store, workspaceId, columns),
 		"Columns of this board, in board order:",
 		"",
-		...columns.length > 0 ? columns.map(describeColumnLine) : ["- (this board has no columns yet)"],
+		...columns.length > 0 ? columns.map((column) => describeColumnLine(column, columns)) : ["- (this board has no columns yet)"],
 		...ruled ? ["", ENTRY_RULES_NOTE] : [],
+		...flowing ? ["", FLOW_RULES_NOTE] : [],
 		"",
 		"How this board works:",
 		"",
@@ -3226,11 +4023,22 @@ async function describeReturnedCards(store, workspaceId, columns) {
 * without any reads exactly as it did before they existed.
 */
 const ENTRY_RULES_NOTE = "A column that lists requirements refuses a card that does not meet them yet, with the list of what is missing: do that work first, then move the card. A person may still move it.";
-function describeColumnLine(column) {
+/** Said under the columns only when one of them has flow rules. */
+const FLOW_RULES_NOTE = "A column that says which columns it accepts cards from, or how many cards it holds, refuses a move that breaks that and says why: move the card through a column it accepts, or wait until a card leaves. A person may still move it.";
+function hasFlowRules(column) {
+	const { allowedFrom, wipLimit } = readFlowRules(column);
+	return allowedFrom !== null || wipLimit !== null;
+}
+function describeColumnLine(column, columns) {
 	const slug = normalizeStatusName(column.name);
 	const rules = readEntryRules(column);
-	const requires = rules.length > 0 ? ` Requires: ${rules.map((rule) => `${rule} (${ENTRY_RULE_DESCRIPTIONS[rule]})`).join("; ")}.` : "";
-	return column.description ? `- ${column.name} (\`${slug}\`) — ${column.description}${requires}` : `- ${column.name} (\`${slug}\`)${requires ? ` —${requires}` : ""}`;
+	const said = `${rules.length > 0 ? ` Requires: ${rules.map((rule) => `${rule} (${ENTRY_RULE_DESCRIPTIONS[rule]})`).join("; ")}.` : ""}${describeFlow(column, columns)}`;
+	return column.description ? `- ${column.name} (\`${slug}\`) — ${column.description}${said}` : `- ${column.name} (\`${slug}\`)${said ? ` —${said}` : ""}`;
+}
+/** Where a column takes cards from and how many it holds, as the prime text says it; nothing for a column without flow rules. */
+function describeFlow(column, columns) {
+	const { allowedFrom, wipLimit } = readFlowRules(column);
+	return `${allowedFrom === null ? "" : allowedFrom.length === 0 ? " Accepts no card from another column: only a person puts a card here." : ` Accepts cards from ${joinWords(columns.filter((other) => allowedFrom.includes(other.id)).map((other) => `\`${normalizeStatusName(other.name)}\``))} only.`}${wipLimit === null ? "" : ` Holds at most ${wipLimit} ${wipLimit === 1 ? "card" : "cards"}.`}`;
 }
 //#endregion
 //#region src/domain/pull-request-ref.ts
@@ -3400,47 +4208,6 @@ async function queryCards(store, input) {
 	};
 }
 //#endregion
-//#region src/ops/ready.ts
-/** The column an agent takes its next card from. */
-const READY_COLUMN_SLUG = "to_do";
-/**
-* The cards an agent may pick up right now: spelled out, nobody working on them,
-* nobody's turn but the agent's.
-*
-* "Ready" is deliberately narrow. A card in Backlog is an idea, a card with a
-* run is taken, and a card waiting for a person belongs to that person until
-* they answer. What is left is the queue — in board order, so the card someone
-* dragged to the top is the one an agent asking for work gets.
-*/
-async function listReady(store, input) {
-	return (await queryReady(store, input)).cards;
-}
-/**
-* One page of the ready cards, how many are ready in all, and the columns read
-* on the way — the rule above, asked of the database in one statement rather
-* than of every card on the board.
-*/
-async function queryReady(store, input) {
-	const columns = await listColumns(store, input.workspaceId);
-	const column = columns.find((candidate) => normalizeStatusName(candidate.name) === READY_COLUMN_SLUG);
-	if (!column) return {
-		cards: [],
-		total: 0,
-		columns
-	};
-	return {
-		...await store.issues.listPage({
-			workspaceId: input.workspaceId,
-			statusIds: [column.id],
-			waitingForPerson: false,
-			hasActiveRun: false,
-			limit: input.limit,
-			offset: input.offset
-		}),
-		columns
-	};
-}
-//#endregion
 //#region src/ops/relations.ts
 /**
 * Every edge touching the card, in either direction, each with the card on its
@@ -3730,6 +4497,8 @@ function createBoardOps(store) {
 		updateColumn: async (statusId, patch, actor, scope) => await updateColumn(store, statusId, patch, actor, scope),
 		describeColumn: async (workspaceId, nameOrId, description, scope) => await describeColumn(store, workspaceId, nameOrId, description, scope),
 		setColumnEntryRules: async (workspaceId, nameOrId, entryRules, actor, scope) => await setColumnEntryRules(store, workspaceId, nameOrId, entryRules, actor, scope),
+		setColumnFlowRules: async (columnId, rules, actor, scope) => await setColumnFlowRules(store, columnId, rules, actor, scope),
+		applyStandardFlow: async (workspaceId, actor, scope) => await applyStandardFlow(store, workspaceId, actor, scope),
 		enforceColumnEntryForCards: async (issueIds, statusId, actor) => await enforceColumnEntryForCards(store, issueIds, statusId, actor),
 		deleteColumn: async (statusId, scope, actor) => await deleteColumn(store, statusId, scope, actor),
 		reorderColumns: async (workspaceId, orderedIds, scope, actor) => await reorderColumns(store, workspaceId, orderedIds, scope, actor),
@@ -3740,6 +4509,7 @@ function createBoardOps(store) {
 		moveColumn: async (workspaceId, nameOrId, position, actor, scope) => await moveColumn$1(store, workspaceId, nameOrId, position, actor, scope),
 		removeColumn: async (workspaceId, nameOrId, options, actor, scope) => await removeColumn$1(store, workspaceId, nameOrId, options, actor, scope),
 		startRun: async (issueId, input, actor, scope) => await startRun(store, issueId, input, actor, scope),
+		claimCard: async (input, actor, scope) => await claimCard(store, input, actor, scope),
 		attachRunExecution: async (runId, input, scope) => await attachRunExecution(store, runId, input, scope),
 		recordRunSessionRef: async (runId, ref, scope) => await recordRunSessionRef(store, runId, ref, scope),
 		clearRunSessionRef: async (runId, actor, options, scope) => await clearRunSessionRef(store, runId, actor, options, scope),
@@ -3752,7 +4522,10 @@ function createBoardOps(store) {
 		readBoardProjectionForIssue: async (issueId) => await readBoardProjectionForIssue(store, issueId),
 		listReady: async (input) => await listReady(store, input),
 		queryReady: async (input) => await queryReady(store, input),
-		buildPrimeText: async (workspaceId) => await buildPrimeText(store, workspaceId)
+		listColumnEntries: async (input) => await listColumnEntries(store, input),
+		buildPrimeText: async (workspaceId) => await buildPrimeText(store, workspaceId),
+		readBoardMetricsHistory: async (workspaceIds) => await readBoardMetricsHistory(store, workspaceIds),
+		boardMetrics: async (input, now) => await boardMetrics(store, input, now)
 	};
 }
 //#endregion
@@ -4457,9 +5230,10 @@ const SCHEMA_NOT_INSTALLED_MESSAGE = "This Postgres database has no kanbo board
 * caller's own risk but never written to — a write shaped by this build's idea
 * of the schema is how a person's board gets a column full of nothing. A file
 * of this package's own is this package's to migrate, so the same refusal
-* points at `kanbo migrate` instead of at the app. Reads stay open either way,
-* because a person who cannot migrate right now should still be able to look at
-* their cards.
+* points at `kanbo migrate` instead of at the app. Reads are held to the lesser
+* bar of `assertReadableBoard`: a file only a stamp behind is still read, so a
+* person who cannot migrate right now can look at their cards, but one missing
+* a table or column this build reads is refused with the same sentence.
 */
 function assertWritableBoard(database, owner) {
 	try {
@@ -4470,6 +5244,26 @@ function assertWritableBoard(database, owner) {
 	}
 }
 /**
+* Refuse a read of a board file that lacks a table or a column this build
+* reads — a file a migration behind — with the sentence a write gets, instead
+* of letting the first statement fail on what is missing. A file whose only
+* difference is its schema stamp is still read: every statement this build
+* makes works on it, and a person who cannot migrate now can still look at
+* their cards.
+*/
+function assertReadableBoard(database, owner) {
+	try {
+		require_migrate.assertBoardSchema(database);
+	} catch (error) {
+		if (!(error instanceof require_migrations_path.BoardError && error.code === "board_schema_outdated")) throw error;
+		if (lacksWhatThisBuildReads(error.details)) throw new CliError(3, owner === "kanbo" ? FILE_SCHEMA_OUTDATED_MESSAGE : SCHEMA_OUTDATED_MESSAGE);
+	}
+}
+/** Whether `assertBoardSchema` found a table or a column missing, rather than only another stamp. */
+function lacksWhatThisBuildReads(details) {
+	return details !== void 0 && ("missingTables" in details || "missingAddedTables" in details || "missingColumns" in details);
+}
+/**
 * Refuse an external board this build cannot speak for — before reading it as
 * well as before writing to it.
 *
@@ -4708,6 +5502,7 @@ async function openFileSession(target, options, mode, cwd) {
 			assertWritableBoard(board.database, target.owner);
 		};
 		if (mode === "write") assertWritableBoard(board.database, target.owner);
+		else assertReadableBoard(board.database, target.owner);
 		const workspace = resolveWorkspace(target.owner === "kanbo" ? { kind: "file" } : {
 			kind: "sqlite",
 			database: board.database
@@ -4731,8 +5526,9 @@ async function openFileSession(target, options, mode, cwd) {
 /**
 * The same, on a board that is a database of its own.
 *
-* The guard runs whatever the command came to do. A board file that this build
-* cannot write to is still a board worth reading; a connection string pointing
+* The guard runs whatever the command came to do. A board file whose only
+* difference from this build is its schema stamp is still a board worth
+* reading; a connection string pointing
 * at a database with no board in it is nothing to read at all, and every
 * command would otherwise fail one statement later with the driver's own words.
 */
@@ -4789,6 +5585,17 @@ function parseCount(value) {
 	return count;
 }
 /**
+* A date as the command line takes it: `YYYY-MM-DD`, read as a UTC day, or a
+* unix-seconds number taken as it is. `end` turns a day into its last second,
+* so a range or a sprint ending on a day runs through that day.
+*/
+function parseCalendarDay(value, end) {
+	if (/^\d+$/.test(value)) return Number(value);
+	const day = /^\d{4}-\d{2}-\d{2}$/.test(value) ? Date.parse(`${value}T00:00:00Z`) : NaN;
+	if (Number.isNaN(day) || new Date(day).toISOString().slice(0, 10) !== value) throw new CliError(1, `Expected a date as YYYY-MM-DD or unix seconds, got "${value}".`);
+	return day / 1e3 + (end ? 86399 : 0);
+}
+/**
 * The card a caller named, in the workspace the command is about.
 *
 * People and agents refer to a card by whatever they have in front of them: the
@@ -5030,7 +5837,9 @@ function projectCardActiveRun(run) {
 		startedAt: run.startedAt
 	};
 }
-function projectColumn(column) {
+/** A column as the command line prints it; `board` is every column, to name the ones it accepts cards from. */
+function projectColumn(column, board) {
+	const { allowedFrom, wipLimit } = readFlowRules(column);
 	return {
 		id: column.id,
 		name: column.name,
@@ -5038,7 +5847,9 @@ function projectColumn(column) {
 		description: column.description,
 		category: column.category,
 		order: column.order,
-		entryRules: readEntryRules(column)
+		entryRules: readEntryRules(column),
+		allowedFrom: allowedFrom === null ? null : board.filter((other) => allowedFrom.includes(other.id)).map((other) => normalizeStatusName(other.name)),
+		wipLimit
 	};
 }
 function projectSprint(sprint) {
@@ -5110,7 +5921,9 @@ function describeColumns(columns) {
 	return columns.map((column) => [
 		`${padToWidth(sanitizeTerminalText(column.slug), slugWidth)}  ${sanitizeTerminalText(column.name)}`,
 		column.description ? ` — ${sanitizeTerminalText(column.description)}` : "",
-		column.entryRules.length > 0 ? ` [requires: ${column.entryRules.join(", ")}]` : ""
+		column.entryRules.length > 0 ? ` [requires: ${column.entryRules.join(", ")}]` : "",
+		column.allowedFrom === null ? "" : ` [from: ${column.allowedFrom.length > 0 ? column.allowedFrom.join(", ") : "no column"}]`,
+		column.wipLimit === null ? "" : ` [wip: ${column.wipLimit}]`
 	].join("")).join("\n");
 }
 /** A unix-seconds date as the UTC day it falls on, `—` for none. */
@@ -5432,6 +6245,52 @@ function registerCapabilitiesCommand(program) {
 	});
 }
 //#endregion
+//#region src/cli/commands/claim.ts
+/**
+* `kanbo claim [card]` — take a card to work on, in one step.
+*
+* The run starts and the card moves out of To Do into the board's first
+* work-in-progress column in one write, so two agents in two terminals never
+* take the same card. Filed as a placement: in a person's own terminal the
+* column's rules warn, in an agent's shell they refuse.
+*/
+function registerClaimCommand(program) {
+	withBoardOptions(program.command("claim").description("Take a card to work on: start your run and move it out of To Do, in one step").argument("[card]", "the card, as MAN-012, MAN-12 or 12 (default: the first ready card)").option("--agent <name>", "your name, e.g. claude (default: the name this shell writes as)").option("--session <ref>", "your session, to find it later: claude:<session id> or codex:<session id> (default: the one Claude Code or Codex names in the environment)")).action(async (reference, options) => {
+		await runBoardCommand(options, "write", async (session) => {
+			const actor = createPlacementActor();
+			const named = reference === void 0 ? void 0 : (await requireCard(session, reference)).id;
+			const claimed = await session.ops.claimCard({
+				workspaceId: session.workspace.id,
+				issueId: named,
+				run: {
+					agentName: options.agent ?? actor.id ?? "agent",
+					externalSessionRef: options.session ?? sessionRefFromEnvironment() ?? void 0,
+					launchedByKind: "external"
+				}
+			}, actor);
+			const [columns, projection, runs] = await Promise.all([
+				session.ops.listColumns(session.workspace.id),
+				session.ops.readBoardProjectionForIssue(claimed.card.id),
+				session.ops.listRuns(claimed.card.id)
+			]);
+			const card = projectCard(claimed.card, columns, projection);
+			for (const item of claimed.card.unmetRules ?? []) console.error(`kanbo: warning: ${card.id} entered "${claimed.column.name}" without ${item.rule}: ${item.detail}`);
+			const run = projectRun({
+				...claimed.run,
+				attempt: runs.find((each) => each.id === claimed.run.id)?.attempt ?? runs.length
+			});
+			return {
+				value: {
+					card,
+					run,
+					column: projectColumn(claimed.column, columns)
+				},
+				text: `Claimed ${card.id}: run ${run.id} started, card moved to ${claimed.column.name}\nWhen you are done: kanbo run finish ${run.id} --state finished`
+			};
+		});
+	});
+}
+//#endregion
 //#region src/mcp/transport.ts
 /** What `kanbo_card_get` may bring along with the card. */
 const KANBO_CARD_INCLUDES = [
@@ -5548,16 +6407,22 @@ function projectKanboSprint(sprint) {
 		doneCards: sprint.cards.done
 	};
 }
-/** A column of the board, from the row either transport holds. */
-function projectKanboColumn(column) {
+/** A column of the board, from the row either transport holds; `board` is every column, to name the ones it accepts cards from. */
+function projectKanboColumn(column, board) {
 	const stored = column.entryRules;
+	const allowedIds = typeof column.allowedFrom === "string" ? readFlowRules({
+		allowedFrom: column.allowedFrom,
+		wipLimit: null
+	}).allowedFrom : column.allowedFrom ?? null;
 	return {
 		id: column.id,
 		name: column.name,
 		slug: normalizeStatusName(column.name),
 		description: column.description,
 		order: column.order,
-		entryRules: typeof stored === "object" && stored !== null ? ENTRY_RULES.filter((rule) => stored.includes(rule)) : readEntryRules({ entryRules: stored ?? null })
+		entryRules: typeof stored === "object" && stored !== null ? ENTRY_RULES.filter((rule) => stored.includes(rule)) : readEntryRules({ entryRules: stored ?? null }),
+		allowedFrom: allowedIds === null ? null : board.filter((other) => allowedIds.includes(other.id)).map((other) => normalizeStatusName(other.name)),
+		wipLimit: column.wipLimit ?? null
 	};
 }
 /**
@@ -5987,10 +6852,11 @@ const COLUMN_CATEGORIES = [
 ];
 /** The whole board's columns after a change, and the sentence that says what changed. */
 async function changed(session, message, extra = {}) {
-	const views = (await session.ops.listColumns(session.workspace.id)).map(projectColumn);
+	const board = await session.ops.listColumns(session.workspace.id);
+	const views = board.map((column) => projectColumn(column, board));
 	return {
 		value: {
-			...extra,
+			...Object.fromEntries(Object.entries(extra).map(([key, value]) => [key, typeof value === "number" || Array.isArray(value) ? value : projectColumn(value, board)])),
 			columns: views
 		},
 		text: `${message}\n\n${describeColumns(views)}`
@@ -6019,14 +6885,14 @@ async function addColumn(session, request, actor) {
 		category: request.category ?? spec.category,
 		position: anchor ? request.after !== void 0 ? { after: anchor.id } : { before: anchor.id } : void 0
 	}, actor);
-	return await changed(session, `Added ${created.name} (slug ${normalizeStatusName(created.name)}).`, { added: projectColumn(created) });
+	return await changed(session, `Added ${created.name} (slug ${normalizeStatusName(created.name)}).`, { added: created });
 }
 /** Said after a rename: agents' instructions name no column but To Do, and `kanbo prime` gives them the rest. */
 const RENAME_NOTE = "Agents read column names from kanbo prime; rename is picked up there.";
 async function renameColumn(session, column, newName, actor) {
 	const before = await requireNamedColumn(session, column);
 	const renamed = await session.ops.renameColumn(session.workspace.id, before.id, newName, actor);
-	return await changed(session, before.name === renamed.name ? `${renamed.name} already has that name.` : `Renamed ${before.name} to ${renamed.name} (slug ${normalizeStatusName(renamed.name)}).\n${RENAME_NOTE}`, { renamed: projectColumn(renamed) });
+	return await changed(session, before.name === renamed.name ? `${renamed.name} already has that name.` : `Renamed ${before.name} to ${renamed.name} (slug ${normalizeStatusName(renamed.name)}).\n${RENAME_NOTE}`, { renamed });
 }
 /** `--first`, `--last`, `--before <column>` or `--after <column>` — exactly one. */
 function readColumnPosition(options) {
@@ -6058,7 +6924,7 @@ async function removeColumn(session, column, moveCardsTo, actor) {
 	const result = await session.ops.removeColumn(session.workspace.id, removing.id, { moveCardsTo }, actor);
 	for (const card of result.unmetRules ?? []) for (const item of card.unmet) console.error(`kanbo: warning: ${card.issueId} entered "${result.movedTo?.name ?? "—"}" without ${item.rule}: ${item.detail}`);
 	return await changed(session, result.movedTo ? `Removed ${result.removed.name} and moved ${describeCount$1(result.movedCards)} to ${result.movedTo.name}.` : `Removed ${result.removed.name}.`, {
-		removed: projectColumn(result.removed),
+		removed: result.removed,
 		movedCards: result.movedCards
 	});
 }
@@ -6102,6 +6968,14 @@ const BOARD_ERROR_TEXTS = {
 		text: "Only a person can approve a card.",
 		next: AS_A_PERSON
 	}),
+	board_card_not_ready: (details) => ({
+		text: details.reason === "run_active" ? `${named(details.issueId)} is taken: it has a run going.` : details.reason === "waiting_for_person" ? `${named(details.issueId)} is waiting for a person.` : `${named(details.issueId)} is not in To Do, so it is not there to take.`,
+		next: "kanbo ready"
+	}),
+	board_card_run_active: (details) => ({
+		text: `${named(details.issueId)} already has a run going: ${named(details.agentName)}'s, run ${named(details.runId)}.`,
+		next: `kanbo run finish ${named(details.runId)} --state stopped`
+	}),
 	board_column_name_taken: (details) => ({
 		text: `Another column, ${named(details.takenBy)}, already has that name (same slug). Pick another name.`,
 		next: "kanbo columns list"
@@ -6132,6 +7006,15 @@ const BOARD_ERROR_TEXTS = {
 	}),
 	board_entry_rule_invalid: (details) => ({ text: `Unknown column rule: ${list(details.rules)}. Use any of ${list(details.allowed)}.` }),
 	board_execution_mode_locked: (details) => ({ text: `${named(details.issueId)} has been started, so where it is worked (${named(details.executionMode)}) can't change now.` }),
+	board_flow_rule_invalid: (details) => details.wipLimit !== void 0 ? { text: `A column holds at least 1 card; ${named(details.wipLimit)} is not a limit. Use none for no limit.` } : {
+		text: `A column accepts cards only from other columns of its own board, and ${list(details.allowedFrom)} is not one.`,
+		next: "kanbo columns list"
+	},
+	board_metrics_range_invalid: (details) => typeof details.from === "number" && typeof details.to === "number" ? { text: `The range starts after it ends: it starts on ${utcDayLabel(details.from)} and ends on ${utcDayLabel(details.to)}.` } : { text: "The range starts after it ends." },
+	board_nothing_ready: () => ({
+		text: "No card in To Do is ready to take: each one is taken or waits for a person, or there is none.",
+		next: "kanbo ready"
+	}),
 	board_pull_request_invalid: (details) => ({ text: `"${named(details.value)}" is not a GitHub pull request. Give its link or owner/repo#number.` }),
 	board_pull_request_not_found: (details) => ({
 		text: `${named(details.issueId)} has no pull request link "${named(details.linkId)}".`,
@@ -6197,7 +7080,7 @@ const BOARD_ERROR_TEXTS = {
 	issue_relation_self_reference: () => ({ text: "A card can't be linked to itself." }),
 	issue_status_name_empty: () => ({ text: "Give the column a name." }),
 	issue_status_not_found: (details) => ({
-		text: `No column "${named(details.statusName ?? details.statusId)}" on this board.`,
+		text: details.category !== void 0 ? `This board has no ${named(details.category)} column for a claimed card to go to.` : `No column "${named(details.statusName ?? details.statusId)}" on this board.`,
 		next: "kanbo columns list"
 	}),
 	issue_status_reference_conflict: () => ({ text: "Name the column once: by its id or by its name, not both." }),
@@ -6401,7 +7284,7 @@ async function runColumnsMenu(ui) {
 		if (showList) say$1(ui, [
 			"",
 			"Columns of this board:",
-			describeColumns(columns.map(projectColumn))
+			describeColumns(columns.map((column) => projectColumn(column, columns)))
 		].join("\n"));
 		let choice;
 		try {
@@ -6629,7 +7512,8 @@ function registerColumnsCommands(program) {
 	const columns = program.command("columns").description("See and change the board's columns (alone: a menu)");
 	withBoardOptions(columns.command("list").description("List the columns in order, with the short name to move cards by")).action(async (options) => {
 		await runBoardCommand(options, "read", async (session) => {
-			const views = (await session.ops.listColumns(session.workspace.id)).map(projectColumn);
+			const board = await session.ops.listColumns(session.workspace.id);
+			const views = board.map((column) => projectColumn(column, board));
 			return {
 				value: views,
 				text: describeColumns(views)
@@ -6638,7 +7522,7 @@ function registerColumnsCommands(program) {
 	});
 	withBoardOptions(columns.command("describe").description("Say in one line when a card belongs in a column").argument("<column>", "the column, by slug, name or id").requiredOption("--text <text>", "what the column means")).action(async (column, options) => {
 		await runBoardCommand(options, "write", async (session) => {
-			const view = projectColumn(await session.ops.describeColumn(session.workspace.id, column, options.text));
+			const view = projectColumn(await session.ops.describeColumn(session.workspace.id, column, options.text), await session.ops.listColumns(session.workspace.id));
 			return {
 				value: view,
 				text: describeColumns([view])
@@ -6649,13 +7533,34 @@ function registerColumnsCommands(program) {
 		const actor = requireHumanActor("columns rules", typedWords(command));
 		const rules = readRequestedRules(options);
 		await runBoardCommand(options, "write", async (session) => {
-			const view = projectColumn(await session.ops.setColumnEntryRules(session.workspace.id, column, rules, actor));
+			const view = projectColumn(await session.ops.setColumnEntryRules(session.workspace.id, column, rules, actor), await session.ops.listColumns(session.workspace.id));
 			return {
 				value: view,
 				text: describeColumns([view])
 			};
 		});
 	});
+	withBoardOptions(columns.command("flow").description("Set which columns a card may come from, and how many cards a column holds").argument("<column>", "the column, by slug, name or id").option("--from <columns>", "comma-separated columns a card may enter it from, or any").option("--wip <count>", "the most cards it holds, or none")).action(async (column, options, command) => {
+		const actor = requireHumanActor("columns flow", typedWords(command));
+		if (options.from === void 0 && options.wip === void 0) throw new CliError(1, "Pass --from <columns|any>, --wip <count|none>, or both.");
+		const wipLimit = options.wip === void 0 ? void 0 : readWipLimit(options.wip);
+		await runBoardCommand(options, "write", async (session) => {
+			const workspaceId = session.workspace.id;
+			const board = await session.ops.listColumns(workspaceId);
+			const target = await session.ops.requireColumn(workspaceId, column);
+			const current = readFlowRules(target);
+			await session.ops.setColumnFlowRules(target.id, {
+				allowedFrom: options.from === void 0 ? current.allowedFrom : readAllowedFrom(board, workspaceId, options.from),
+				wipLimit: wipLimit === void 0 ? current.wipLimit : wipLimit
+			}, actor);
+			const after = await session.ops.listColumns(workspaceId);
+			const views = after.map((each) => projectColumn(each, after));
+			return {
+				value: views.find((view) => view.id === target.id),
+				text: describeColumns(views)
+			};
+		});
+	});
 	withBoardOptions(columns.command("add").description("Add a column (before Done unless you say where)").argument("<name>", "what the column is called").option("--after <column>", "put it right after this column").option("--before <column>", "put it right before this column").option("--description <text>", "when a card belongs in it, in one line agents read").addOption(new commander.Option("--category <category>", "what kind of column it is").choices(COLUMN_CATEGORIES))).action(async (name, options, command) => {
 		const actor = requireHumanActor("columns add", typedWords(command));
 		await runBoardCommand(options, "write", async (session) => await addColumn(session, {
@@ -6697,7 +7602,7 @@ function registerColumnsCommands(program) {
 				mode: "add-missing",
 				actor
 			});
-			const views = statuses.map(projectColumn);
+			const views = statuses.map((column) => projectColumn(column, statuses));
 			return {
 				value: {
 					added,
@@ -6721,7 +7626,8 @@ function registerColumnsCommands(program) {
 			return;
 		}
 		await runBoardCommand({}, "read", async (session) => {
-			const views = (await session.ops.listColumns(session.workspace.id)).map(projectColumn);
+			const board = await session.ops.listColumns(session.workspace.id);
+			const views = board.map((column) => projectColumn(column, board));
 			return {
 				value: views,
 				text: describeColumns(views)
@@ -6751,6 +7657,26 @@ function readRequestedRules(options) {
 	if (options.require === void 0) throw new CliError(1, `Pass --require ${ENTRY_RULES.join(",")} (any of them) or --clear.`);
 	return options.require.split(",").map((rule) => rule.trim()).filter(Boolean);
 }
+/** `--from`: `any` for every column, else the columns named, by slug, name or id. */
+function readAllowedFrom(board, workspaceId, value) {
+	if (value.trim().toLowerCase() === "any") return null;
+	const names = value.split(",").map((name) => name.trim()).filter(Boolean);
+	if (names.length === 0) throw new CliError(1, "Name the columns a card may come from (--from in_review,qa), or --from any.");
+	return names.map((name) => {
+		const found = matchColumn(board, workspaceId, name);
+		if (!found) throw new require_migrations_path.BoardError("issue_status_not_found", {
+			workspaceId,
+			statusName: name
+		});
+		return found.id;
+	});
+}
+/** `--wip`: `none` for no limit, else a whole number of cards, 1 or more. */
+function readWipLimit(value) {
+	if (value.trim().toLowerCase() === "none") return null;
+	if (!/^\d+$/.test(value.trim()) || Number(value) < 1) throw new CliError(1, "--wip takes a whole number of cards, 1 or more, or none.");
+	return Number(value);
+}
 //#endregion
 //#region src/package-version.ts
 (0, node_path.dirname)((0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href));
@@ -6760,7 +7686,7 @@ function readRequestedRules(options) {
 * `package.version`. A build carries it as a literal; running from source
 * (tests, `tsx`) reads the package's own `package.json` instead.
 */
-const KANBO_PACKAGE_VERSION = "0.4.0";
+const KANBO_PACKAGE_VERSION = "0.6.0";
 //#endregion
 //#region src/cli/setup/paths.ts
 /**
@@ -7109,7 +8035,7 @@ const INSTRUCTION_END_PATTERN = /<!-- KANBO_END\s*-->/g;
 const POINTER_KINDS = /* @__PURE__ */ new Set(["short", "global"]);
 /** The commands an agent uses, spelled once for the guide and the `kanbo prime` cheat sheet. */
 const COMMAND = {
-	ready: "kanbo ready",
+	claim: "kanbo claim",
 	move: "kanbo card move <id> <column>",
 	statusLine: "kanbo card status-line <id> --text \"...\"",
 	subtask: "kanbo card create --description \"...\" --parent <id>",
@@ -7128,7 +8054,7 @@ const AGENT_GUIDE_TEXT = [
 	"Work on this project is tracked on a kanbo board. Before starting a task run `kanbo prime` — it prints the board's columns and what each one means.",
 	"",
 	...[
-		`- Take a card from \`${COMMAND.ready}\`.`,
+		`- Take a card with \`${COMMAND.claim}\`: it starts your run and moves the card into work in one step, and no other agent gets the same card.`,
 		`- ${MOVE_CARD_RULE} (\`${COMMAND.move}\`)`,
 		`- ${STATUS_LINE_RULE} (\`${COMMAND.statusLine}\`)`,
 		`- ${SUBTASK_RULE} (\`${COMMAND.subtask}\`)`,
@@ -7158,12 +8084,13 @@ const COMMAND_SHEET = [
 	"- `kanbo card create --description \"...\" --parent TST-5` — a subtask",
 	"- `kanbo card update TST-7 --parent TST-5` — move a card at the wrong level under another (`--parent none`: the top level)",
 	"- `kanbo card wait-approval TST-5 --text \"Ready for review: ...\"` — ask a person, then end your turn",
-	"- `kanbo run start TST-5 --agent claude` — record a run you started yourself; it prints the finish command",
+	"- `kanbo claim` — take the first ready card: starts your run and moves it into work in one step (`kanbo claim TST-5` for that card); it prints the finish command",
+	"- `kanbo run start TST-5 --agent claude` — record a run on a card you did not claim; it prints the finish command",
 	"- `kanbo run finish <run id> --state finished` — end it: finished, failed or stopped",
 	`- \`${COMMAND.capabilities}\` — everything else, rarely needed`
 ].join("\n");
 /** How to take work and who approves it — said by both blocks after their first sentence. */
-const POINTER_TAIL = `Take work with \`${COMMAND.ready}\`. ${PERSON_ONLY_RULE}`;
+const POINTER_TAIL = `Take work with \`${COMMAND.claim}\`. ${PERSON_ONLY_RULE}`;
 /** The body of the project block: what `kanbo instructions short` prints. */
 const PROJECT_BODY = [
 	"## Kanbo board",
@@ -7183,7 +8110,7 @@ const GLOBAL_BODY = [
 * The block, markers included, with this body's version and hash on the start
 * marker — and, when given, the kind of text it is (`k=orchestrator`).
 */
-function wrapInstructionBlock(body, version = 2, kind) {
+function wrapInstructionBlock(body, version = 3, kind) {
 	return `<!-- KANBO_START v${version}${kind ? ` k=${kind}` : ""} h=${hashBody(body)} -->\n${body}\n${INSTRUCTION_END}`;
 }
 /** The block `kanbo init --instructions …` writes into a project's own file. */
@@ -7212,7 +8139,7 @@ function inspectBlock(text, current) {
 		kind
 	});
 	if (fields.trim() === "") return inspection(LEGACY_BLOCK_BODIES.includes(body) ? "legacy" : "edited");
-	if (version !== void 0 && Number(version) > 2) return inspection("newer");
+	if (version !== void 0 && Number(version) > 3) return inspection("newer");
 	if (kind !== null && !POINTER_KINDS.has(kind)) return inspection("chosen");
 	if (version === void 0 || hash === void 0 || hashBody(body) !== hash) return inspection("edited");
 	return inspection(normalized.slice(found.start, found.end) === current ? "current" : "outdated");
@@ -8242,7 +9169,7 @@ function startUpdateCheck(deps = {}) {
 		setTimeout: globalThis.setTimeout,
 		clearTimeout: globalThis.clearTimeout
 	};
-	const current = deps.currentVersion ?? "0.4.0";
+	const current = deps.currentVersion ?? "0.6.0";
 	const controller = new AbortController();
 	let found = null;
 	const timeout = timers.setTimeout(() => controller.abort(), UPDATE_CHECK_TIMEOUT_MS);
@@ -10674,7 +11601,7 @@ const KANBO_MCP_INSTRUCTIONS = [
 	"kanbo is a kanban board shared by people and agents; these tools read and change its cards.",
 	"",
 	`- At the start of a session call ${tool("kanbo_prime")} — it returns this board's columns and what each one means.`,
-	`- Take work from ${tool("kanbo_ready")}.`,
+	`- Take work from ${tool("kanbo_ready")}, and claim the card with ${tool("kanbo_card_claim")} before you start: it starts your run and moves the card into work in one step, so no other agent takes it.`,
 	`- ${MOVE_CARD_RULE} (${tool("kanbo_card_move")})`,
 	`- ${STATUS_LINE_RULE} (${tool("kanbo_status_line")})`,
 	`- ${COMMENT_RULE} (${tool("kanbo_card_comment")})`,
@@ -10765,7 +11692,7 @@ const ORCHESTRATOR_GUIDE = [
 	"## Start of every session",
 	"1. Run `kanbo prime` (tool: `kanbo_prime`) and read the column descriptions. On this board the description is the contract, not the name.",
 	"2. Run `kanbo ready` (`kanbo_ready`). If nothing is ready, say so and stop.",
-	"3. Take the first card. Run `kanbo run start <card> --agent orchestrator` (`kanbo_run_start`) and move it to the column this board uses for work in progress — `kanbo prime` lists the columns and what each is for — (`kanbo_card_move`) before doing anything else.",
+	"3. Take the first card with `kanbo claim --agent orchestrator` (`kanbo_card_claim`): it starts your run and moves the card out of To Do into the board's first work-in-progress column in one step, so no other agent takes it, and it prints the run id you finish later. If another agent got there first, run `kanbo ready` again.",
 	"",
 	"## While working",
 	"- Write a status line (`kanbo card status-line <card> --text \"…\"`, `kanbo_status_line`) at every step and before and after anything that takes more than a minute. One sentence, present tense.",
@@ -10792,7 +11719,7 @@ const ORCHESTRATOR_GUIDE = [
 	"- Returned: the reason is the newest comment. The card is back in an earlier column; start a new run and address the reason first.",
 	"",
 	"## Never",
-	"- Never run `kanbo approve`, `kanbo return`, `kanbo sprint close`, `kanbo run clear-session`, or anything that changes the columns: `kanbo columns add`, `kanbo columns rename`, `kanbo columns move`, `kanbo columns remove`, `kanbo columns template`, `kanbo columns add-standard`, `kanbo columns rules`. They are for a person and will fail in your shell anyway.",
+	"- Never run `kanbo approve`, `kanbo return`, `kanbo sprint close`, `kanbo run clear-session`, or anything that changes the columns: `kanbo columns add`, `kanbo columns rename`, `kanbo columns move`, `kanbo columns remove`, `kanbo columns template`, `kanbo columns add-standard`, `kanbo columns rules`, `kanbo columns flow`. They are for a person and will fail in your shell anyway.",
 	"- Never delete or edit the board's database directly."
 ].join("\n");
 //#endregion
@@ -10837,7 +11764,7 @@ function registerInstructionsCommand(program, dependencies = {}) {
 		const found = parseKind(kind);
 		const body = await readInstructionText(found);
 		const pointer = found === "short" || found === "global";
-		const text = options.markers ? wrapInstructionBlock(body, 2, pointer ? void 0 : found) : body;
+		const text = options.markers ? wrapInstructionBlock(body, 3, pointer ? void 0 : found) : body;
 		const hints = process.stderr.isTTY === true;
 		if (hints) process.stderr.write(`${HEADER}\n\n`);
 		console.log(text);
@@ -11244,7 +12171,7 @@ function readMoment(value) {
 const cardMoveTool = defineKanboTool({
 	name: "kanbo_card_move",
 	title: "Move a card",
-	description: `Move a card to another column the moment its real state changes. Read kanbo_columns first: a card in the wrong column is a lie, and a column with entryRules refuses a card that does not meet them yet, listing what is missing. ${WRITTEN_CARD_ANSWER_SENTENCE}`,
+	description: `Move a card to another column the moment its real state changes. Read kanbo_columns first: a card in the wrong column is a lie, and a column refuses a card that does not meet its entryRules yet, that comes from a column it does not accept (allowedFrom), or that would overfill it (wipLimit), listing what is missing. ${WRITTEN_CARD_ANSWER_SENTENCE}`,
 	inputSchema: {
 		card: cardArgument,
 		column: zod.z.string().min(1).describe("The column to move it to, by its slug or name: in_progress, \"In Progress\". Also accepted as `to`."),
@@ -11316,7 +12243,7 @@ const cardUpdateTool = defineKanboTool({
 const columnsTool = defineKanboTool({
 	name: "kanbo_columns",
 	title: "Columns of the board",
-	description: "List this board's columns in board order, each with the slug kanbo_card_move takes, what the column means here, and the entryRules a card must meet before you move it in.",
+	description: "List this board's columns in board order, each with the slug kanbo_card_move takes, what the column means here, the entryRules a card must meet before you move it in, the columns it accepts cards from (allowedFrom, slugs; null for any) and the most cards it holds (wipLimit).",
 	inputSchema: {},
 	run: async (transport) => await transport.columns()
 });
@@ -11330,6 +12257,38 @@ const primeTool = defineKanboTool({
 	inputSchema: {},
 	run: async (transport) => (await transport.prime()).text
 });
+//#endregion
+//#region src/mcp/tools/card-claim.ts
+/**
+* Taking a card to work on, in one step: the run starts and the card moves out
+* of To Do into the board's first work-in-progress column in the same write,
+* so two agents never get the same card. Published to every host, including
+* one that records the runs of the agents it launches: a claim is how an agent
+* in any terminal takes work.
+*/
+const cardClaimTool = defineKanboTool({
+	name: "kanbo_card_claim",
+	title: "Claim a card",
+	description: "Take a card to work on, in one step: it starts your run and moves the card from To Do into the board's first work-in-progress column. Without `card`, takes the first ready card. Two agents never get the same card: the one that loses is told board_nothing_ready or board_card_not_ready. Answers the card compact, the run id, the column, and the kanbo_run_finish call that ends the run.",
+	inputSchema: {
+		card: cardArgument.optional(),
+		agent: zod.z.string().min(1).optional().describe("What to call whoever works the card; who this server writes as when absent.")
+	},
+	aliases: {
+		card: [...CARD_ALIASES, "issue"],
+		agent: ["agentName"]
+	},
+	example: { card: "TST-5" },
+	run: async (transport, input) => {
+		const claimed = await transport.cardClaim(input);
+		return {
+			card: compactKanboCard(claimed.card),
+			run: claimed.run.id,
+			column: claimed.column.slug,
+			finishWith: `kanbo_run_finish {"run":"${claimed.run.id}","state":"finished"}`
+		};
+	}
+});
 /** The cards an agent may pick up right now. */
 const readyTool = defineKanboTool({
 	name: "kanbo_ready",
@@ -11418,13 +12377,14 @@ const runStartTool = defineKanboTool({
 /**
 * Every tool the board has, in the order it declares them.
 *
-* The list is the board's, not a server's: the same sixteen are registered
+* The list is the board's, not a server's: the same seventeen are registered
 * whether they run against a server or against the board directly, and the
 * only thing a host decides is which of them it publishes.
 */
 const KANBO_TOOLS = [
 	primeTool,
 	readyTool,
+	cardClaimTool,
 	columnsTool,
 	defineKanboTool({
 		name: "kanbo_sprints",
@@ -11556,7 +12516,8 @@ async function createDbTransport(input) {
 	const workspaceId = workspace.id;
 	const actor = input.actor;
 	async function readColumns() {
-		return (await ops.listColumns(workspaceId)).map(projectKanboColumn);
+		const rows = await ops.listColumns(workspaceId);
+		return rows.map((row) => projectKanboColumn(row, rows));
 	}
 	/** One card with what the run registry says about it, in the shape a tool prints. */
 	async function project(card, columns) {
@@ -11606,7 +12567,7 @@ async function createDbTransport(input) {
 	* the waiting and returned ones last said at most two more.
 	*/
 	async function projectPage(page, { attend = true } = {}) {
-		const columns = page.columns.map(projectKanboColumn);
+		const columns = page.columns.map((column) => projectKanboColumn(column, page.columns));
 		const runs = await ops.readBoardProjectionForIssues(page.cards.map((card) => card.id));
 		const attention = attend ? await ops.readCardAttention(page.cards, runs.map((run) => run.activeRun !== null)) : [];
 		return page.cards.map((card, index) => projectKanboCard({
@@ -11738,6 +12699,25 @@ async function createDbTransport(input) {
 				state,
 				errorText
 			}, actor));
+		},
+		cardClaim: async ({ card, agent }) => {
+			await session.assertWritable();
+			const named = card === void 0 ? void 0 : (await resolveCard(card)).id;
+			const claimed = await ops.claimCard({
+				workspaceId,
+				issueId: named,
+				run: {
+					agentName: agent ?? actor.id ?? "agent",
+					externalSessionRef: sessionRefFromEnvironment() ?? void 0,
+					launchedByKind: "external"
+				}
+			}, actor);
+			const columns = await readColumns();
+			return {
+				card: await project(claimed.card, columns),
+				run: projectKanboRun(claimed.run),
+				column: columns.find((column) => column.id === claimed.column.id)
+			};
 		}
 	};
 }
@@ -11779,7 +12759,8 @@ const TRANSPORT_METHODS = {
 	statusLine: true,
 	waitApproval: true,
 	runStart: true,
-	runFinish: true
+	runFinish: true,
+	cardClaim: true
 };
 async function openMcpBoard(input) {
 	try {
@@ -12385,7 +13366,7 @@ function sendBoardPage(response, pathname, assets) {
 * answering for a person — approving a card, sending it back or closing a
 * sprint — as anyone but one is 403, dropping a pull request link somebody else made is the same 403
 * for the same reason, and acting on a run that has already ended is 409,
-* because the answer would have been yes a moment earlier. An agent putting a
+* because the answer would have been yes a moment earlier. Starting a run on a card that has one going, and claiming a card nobody can take right now, are 409 for the same reason. An agent putting a
 * card in a column whose entry rules it does not meet yet is 409 for the same
 * reason turned around: the answer will be yes once the card meets them, and
 * `details.unmet` says what is missing. Deleting a column that still holds
@@ -12403,6 +13384,14 @@ const BOARD_ERROR_RESPONSES = {
 		message: "Only a person can approve a card",
 		code: "issue_approval_requires_user"
 	},
+	board_card_not_ready: {
+		status: 409,
+		message: "That card is not there to take: it is not in To Do, waits for a person, or has a run going"
+	},
+	board_card_run_active: {
+		status: 409,
+		message: "The card already has a run going"
+	},
 	board_column_name_taken: {
 		status: 400,
 		message: "Another column already has that name"
@@ -12442,6 +13431,18 @@ const BOARD_ERROR_RESPONSES = {
 		status: 400,
 		message: "Execution mode cannot change once the card has been launched"
 	},
+	board_flow_rule_invalid: {
+		status: 400,
+		message: "A column accepts cards from other columns of its own board, and holds at least one card"
+	},
+	board_metrics_range_invalid: {
+		status: 400,
+		message: "The range starts after it ends"
+	},
+	board_nothing_ready: {
+		status: 409,
+		message: "No card in To Do is ready to take"
+	},
 	board_pull_request_invalid: {
 		status: 400,
 		message: "Not a GitHub pull request: give its URL or owner/repo#number"
@@ -12857,6 +13858,14 @@ const startRunBody = zod.z.object({
 	]).optional(),
 	externalSessionRef: zod.z.string().nullable().optional()
 });
+const claimBody = zod.z.object({
+	workspaceId: id,
+	issueId: id.optional(),
+	agentName: id.optional(),
+	branch: zod.z.string().nullable().optional(),
+	executionMode: executionMode.optional(),
+	externalSessionRef: zod.z.string().nullable().optional()
+});
 const finishRunBody = zod.z.object({
 	state: zod.z.enum([
 		"finished",
@@ -12903,7 +13912,8 @@ async function toWrittenCardView(ops, card) {
 function toStatusView(status) {
 	return {
 		...status,
-		entryRules: readEntryRules(status)
+		entryRules: readEntryRules(status),
+		allowedFrom: readFlowRules(status).allowedFrom
 	};
 }
 function toCommentView(comment, personWriterId = null) {
@@ -13338,6 +14348,31 @@ function createIssueRoutes(session, options = {}) {
 				}, actors.placement));
 			}
 		}),
+		route({
+			method: "POST",
+			path: "/issues/claim",
+			body: claimBody,
+			write: true,
+			handle: async ({ body, actors }) => {
+				const named = requireWorkspace(body.workspaceId);
+				if (body.issueId !== void 0) await requireCard(body.issueId);
+				const claimed = await ops.claimCard({
+					workspaceId: named,
+					issueId: body.issueId,
+					run: {
+						agentName: body.agentName ?? actors.writer.id ?? "agent",
+						branch: body.branch,
+						executionMode: body.executionMode,
+						externalSessionRef: body.externalSessionRef
+					}
+				}, actors.placement);
+				return {
+					card: await toWrittenCardView(ops, claimed.card),
+					run: await toRunView(claimed.run),
+					column: toStatusView(claimed.column)
+				};
+			}
+		}),
 		route({
 			method: "PATCH",
 			path: "/issues/bulk",
@@ -14216,17 +15251,6 @@ function parsePort(value) {
 //#endregion
 //#region src/cli/commands/sprint.ts
 /**
-* A date as the command line takes it: `YYYY-MM-DD`, read as a UTC day, or a
-* unix-seconds number taken as it is. `end` turns a day into its last second,
-* so a sprint due on a day is still current throughout that day.
-*/
-function parseDate(value, end) {
-	if (/^\d+$/.test(value)) return Number(value);
-	const day = /^\d{4}-\d{2}-\d{2}$/.test(value) ? Date.parse(`${value}T00:00:00Z`) : NaN;
-	if (Number.isNaN(day)) throw new CliError(1, `Expected a date as YYYY-MM-DD or unix seconds, got "${value}".`);
-	return day / 1e3 + (end ? 86399 : 0);
-}
-/**
 * `kanbo sprint …` — milestones read as sprints (ruling 5x-3).
 *
 * Listing and creating are anybody's. Closing one is a person's decision
@@ -14246,7 +15270,7 @@ function registerSprintCommands(program) {
 			};
 		});
 	});
-	withBoardOptions(sprint.command("create").description("Start a sprint with a first and a last day").requiredOption("--title <title>", "what the sprint is called").requiredOption("--start <date>", "first day, as YYYY-MM-DD (UTC) or unix seconds", (value) => parseDate(value, false)).requiredOption("--due <date>", "last day, as YYYY-MM-DD (UTC, through its end) or unix seconds", (value) => parseDate(value, true)).option("--description <text>", "what the sprint is for")).action(async (options) => {
+	withBoardOptions(sprint.command("create").description("Start a sprint with a first and a last day").requiredOption("--title <title>", "what the sprint is called").requiredOption("--start <date>", "first day, as YYYY-MM-DD (UTC) or unix seconds", (value) => parseCalendarDay(value, false)).requiredOption("--due <date>", "last day, as YYYY-MM-DD (UTC, through its end) or unix seconds", (value) => parseCalendarDay(value, true)).option("--description <text>", "what the sprint is for")).action(async (options) => {
 		await runBoardCommand(options, "write", async (session) => {
 			const created = await session.ops.createMilestone({
 				workspaceId: session.workspace.id,
@@ -14289,6 +15313,113 @@ function registerSprintCommands(program) {
 	});
 }
 //#endregion
+//#region src/cli/metrics-view.ts
+/** Every field `kanbo stats --json` may name, in the order the value carries them. */
+const BOARD_METRICS_FIELDS = [
+	"range",
+	"now",
+	"milestoneId",
+	"columns",
+	"cycleTime",
+	"leadTime",
+	"throughput",
+	"wip",
+	"aging",
+	"timeInColumn",
+	"cumulativeFlow",
+	"finished",
+	"returns",
+	"attempts",
+	"canceled",
+	"agents",
+	"people"
+];
+const LABEL_WIDTH = 16;
+/** A duration as the command line prints it: minutes under an hour, hours under a day, then days, to one decimal; a dash for none. */
+function formatDuration(seconds) {
+	if (seconds === null) return "—";
+	if (seconds < 3600) return `${Math.round(seconds / 60)}m`;
+	if (seconds < 86400) return `${Number((seconds / 3600).toFixed(1))}h`;
+	return `${Number((seconds / 86400).toFixed(1))}d`;
+}
+function percent(share) {
+	return share === null ? "—" : `${Math.round(share * 100)}%`;
+}
+function decimal(value) {
+	return value === null ? "—" : String(Number(value.toFixed(1)));
+}
+function count(n, noun) {
+	return `${n} ${noun}${n === 1 ? "" : "s"}`;
+}
+function day(seconds) {
+	return (/* @__PURE__ */ new Date(seconds * 1e3)).toISOString().slice(0, 10);
+}
+/** A labelled block: the first item beside the label, the rest under it; a dash when there is nothing. */
+function block(label, items) {
+	const [first = "—", ...rest] = items;
+	return [`${label.padEnd(LABEL_WIDTH)}${first}`, ...rest.map((item) => `${" ".repeat(LABEL_WIDTH)}${item}`)];
+}
+/** Items joined on one line, or none at all. */
+function oneLine(items) {
+	return items.length === 0 ? [] : [items.join(" · ")];
+}
+/**
+* The metrics as a person reads them in a terminal: the range, then one block
+* per figure. The cumulative flow is a series per day and has no one-screen
+* form, so the last line says how to get it.
+*/
+function describeMetrics(metrics, sprint) {
+	const column = (slug) => sanitizeTerminalText(metrics.columns.find((candidate) => candidate.slug === slug)?.name ?? slug);
+	const by = metrics.returns.byActorKind;
+	const lines = [`${day(metrics.range.from)} → ${day(metrics.range.to)}`];
+	if (sprint) lines.push(`${sanitizeTerminalText(sprint.title)}: ${sprint.cards.open + sprint.cards.done} planned · ${sprint.cards.done} done`);
+	if (metrics.range.from > metrics.range.to) return [...lines, "Nothing measured yet: the range starts after now."].join("\n");
+	lines.push(...block("Cycle time", [`p50 ${formatDuration(metrics.cycleTime.p50)} · p85 ${formatDuration(metrics.cycleTime.p85)} (${count(metrics.cycleTime.cards, "card")})`]), ...block("Lead time", [`p50 ${formatDuration(metrics.leadTime.p50)} · p85 ${formatDuration(metrics.leadTime.p85)}`]), ...block("Throughput", oneLine(metrics.throughput.map((week) => `${week.week} ${week.finished}`))), ...block("In progress", oneLine(metrics.wip.map((wip) => `${column(wip.slug)} ${wip.cards}${wip.limit === null ? "" : `/${wip.limit}`}`))), ...block("First pass", [`${percent(metrics.returns.firstPassRate)} · attempts ${decimal(metrics.attempts.perFinishedCard)} per card`]), ...block("Returns", [`${metrics.returns.total} (people ${by.user} · agents ${by.agent} · outside ${by.external}) · ${decimal(metrics.returns.perFinishedCard)} per card`]), ...block("Canceled", [String(metrics.canceled)]), ...block("Aging", metrics.aging.map((card) => `${card.issueId} ${column(card.slug)} ${formatDuration(card.ageSeconds)}${card.overCycleP85 ? " (older than p85)" : ""}`)), ...block("Time in column", oneLine(metrics.timeInColumn.filter((time) => time.seconds > 0).map((time) => `${column(time.slug)} ${formatDuration(time.seconds)}`))), ...block("Agents", metrics.agents.map(describeAgent)), ...block("People", metrics.people.map(describePerson)), "Cumulative flow by day: kanbo stats --json cumulativeFlow");
+	return lines.join("\n");
+}
+function describeAgent(agent) {
+	const { runs } = agent;
+	return `${sanitizeTerminalText(agent.agentName)}: ${count(runs.total, "run")} (${runs.finished} finished · ${runs.failed} failed · ${runs.stopped} stopped · ${runs.running} running) · median ${formatDuration(agent.medianRunSeconds)} · ${count(agent.cardsFinished, "card")} finished · ${percent(agent.returnRate)} returned`;
+}
+function describePerson(person) {
+	return `${sanitizeTerminalText(person.id ?? "unnamed")}: ${person.created} created · ${person.approvals} approved · ${person.returns} returned · ${person.moves} moved`;
+}
+const WEEK_SECONDS = 604800;
+/** The Monday that makes the range `DEFAULT_STATS_WEEKS` ISO weeks long, ending with the week of `now`. */
+function defaultStatsFrom(now) {
+	return isoWeekOf(now).start - 11 * WEEK_SECONDS;
+}
+/**
+* `kanbo stats` — how work flows on this board (spec 2026-11-05, Part 4).
+*
+* Reading only, so it is anybody's, an agent's shell included. A sprint sets
+* the range to its own dates and keeps its cards; `--from` and `--to` still
+* win over either end.
+*/
+function registerStatsCommand(program) {
+	withBoardOptions(program.command("stats").description("How work flows on this board: cycle time, throughput, work in progress, returns, agents").option("--from <date>", `first day, YYYY-MM-DD (UTC) or unix seconds (12 weeks back when left out)`, (value) => parseCalendarDay(value, false)).option("--to <date>", "last day, YYYY-MM-DD (UTC, through its end) or unix seconds (now when left out)", (value) => parseCalendarDay(value, true)).option("--sprint <id>", "only the cards of this sprint, over its dates")).action(async (options) => {
+		await runBoardCommand(options, "read", async (session) => {
+			const now = currentUnixSeconds();
+			const sprint = options.sprint === void 0 ? null : (await session.ops.listSprints(session.workspace.id, now)).find((candidate) => candidate.id === options.sprint) ?? null;
+			if (options.sprint !== void 0 && sprint === null) throw new require_migrations_path.BoardError("issue_milestone_not_found", {
+				milestoneId: options.sprint,
+				workspaceId: session.workspace.id
+			});
+			const metrics = await session.ops.boardMetrics({
+				workspaceIds: [session.workspace.id],
+				from: options.from ?? sprint?.startDate ?? defaultStatsFrom(now),
+				to: options.to ?? sprint?.dueDate ?? now,
+				milestoneId: sprint?.id ?? null
+			}, now);
+			return {
+				value: metrics,
+				text: describeMetrics(metrics, sprint),
+				fields: BOARD_METRICS_FIELDS
+			};
+		});
+	});
+}
+//#endregion
 //#region src/cli/commands/uninstall.ts
 function registerUninstallCommand(program) {
 	program.command("uninstall").description("Disconnect kanbo from your agents; the board stays unless --purge").option("--project", "only this project's files").option("--global", "only your own files, for every project").option("--purge", "also remove this project's board settings, and its board file after you confirm").option("--yes", "do it without asking (never deletes a board file)").option("--json [fields]", "print what was done as JSON; name comma-separated fields to print only those").action(async (options) => {
@@ -14469,9 +15600,11 @@ function registerKanboCommands(program, context = {}) {
 	registerReadyCommand(program);
 	registerPrimeCommand(program);
 	registerSprintCommands(program);
+	registerStatsCommand(program);
 	registerServeCommand(program);
 	program.commandsGroup("For agents and integrations:");
 	registerMcpCommand(program);
+	registerClaimCommand(program);
 	registerRunCommands(program);
 	registerCapabilitiesCommand(program);
 	program.commandsGroup("Shared Postgres boards:");
@@ -14495,6 +15628,7 @@ function registerKanboCommands(program, context = {}) {
 const KANBO_TOOL_NAMES = [
 	"kanbo_prime",
 	"kanbo_ready",
+	"kanbo_card_claim",
 	"kanbo_columns",
 	"kanbo_sprints",
 	"kanbo_card_get",
@@ -14520,6 +15654,7 @@ const KANBO_TOOL_NAMES = [
 const KANBO_TOOL_CLI_EQUIVALENTS = {
 	kanbo_prime: { kanbo: "kanbo prime" },
 	kanbo_ready: { kanbo: "kanbo ready" },
+	kanbo_card_claim: { kanbo: "kanbo claim [card] [--agent <name>]" },
 	kanbo_columns: { kanbo: "kanbo columns list" },
 	kanbo_sprints: { kanbo: "kanbo sprint list" },
 	kanbo_card_get: { kanbo: "kanbo card get <id>" },
@@ -14667,10 +15802,12 @@ function buildCapabilitiesManifest() {
 			"Only a person may close a sprint. `kanbo sprint close` refuses an agent's shell (exit 4), and the operation refuses any actor but a person; there is no MCP tool that closes one — `kanbo_sprints` only reads. Unlike approval, the database role does not enforce this.",
 			`The agent role (\`${require_roles_sql.BOARD_AGENT_ROLE}\`) may not delete a card at all — it holds select, insert and update on \`issues\` and nothing more, even though it may delete freely on every other board table.`,
 			"A column may ask a card to meet entry rules before it enters (`entryRules`). Anyone but a person moving, creating or bulk-moving a card into it early is refused with `board_column_rules_unmet` and one line per unmet rule (CLI exit 1); a person goes through and is told what is missing. Only a person sets the rules — `kanbo columns rules` refuses an agent's shell (exit 4). The database role does not enforce them.",
+			"A column may name the columns it accepts cards from (`allowedFrom`) and the most cards it holds (`wipLimit`). Anyone but a person moving, creating, bulk-moving or claiming a card against them is refused with `board_column_rules_unmet` (`allowed_from`, `wip_limit`); a person goes through and is told. A new board's Done accepts cards from In Review only. Only a person sets them — `kanbo columns flow` refuses an agent's shell (exit 4). The database role does not enforce them.",
+			"A claim (`kanbo claim`, `kanbo_card_claim`, `POST /issues/claim`) takes a ready card from To Do, starts its run and moves it into the board's first `started` column in one write; two claimers never get the same card, and the one that loses is told `board_nothing_ready` or `board_card_not_ready`. A card has one run going at a time: starting a second is refused with `board_card_run_active`, on every path.",
 			"Only a person changes the board's columns: `kanbo columns add`, `rename`, `move`, `remove`, `template` and `add-standard` refuse an agent's shell (exit 4), and the rename, move, remove and add-missing operations refuse any actor but a person (`board_column_structure_requires_user`); no MCP tool changes columns. To Do can be neither removed nor renamed away from its slug `to_do`: `kanbo ready` takes work from it.",
 			"No board tool or command deletes a card, agent role or not. Cancelling one is a move to another column. The one exception is `kanbo serve`'s `DELETE /issues/:id`, which it answers only for a request presenting its token, on a server a person started, that has not sent `x-kanbo-actor: agent` (403 `issue_delete_requires_user` otherwise).",
 			"`kanbo migrate` and `kanbo roles apply` refuse a host app's own database file: the app migrates it, and this package never touches it.",
-			"A write to a board older than this build's schema epoch is refused (exit 3) until `kanbo migrate` runs (on a host app's database, until the app migrates it) — reads stay open either way.",
+			"A write to a board older than this build's schema epoch is refused (exit 3) until `kanbo migrate` runs (on a host app's database, until the app migrates it), and so is a read of a board file that lacks a table or a column this build reads; a board whose only difference is its schema stamp stays readable.",
 			"There is no MCP tool that approves a card, and there never will be: `kanbo_wait_approval` hands the card to a person and ends the turn; only a person takes it back."
 		]
 	};
@@ -14760,6 +15897,12 @@ Object.defineProperty(exports, "ENTRY_RULE_DESCRIPTIONS", {
 		return ENTRY_RULE_DESCRIPTIONS;
 	}
 });
+Object.defineProperty(exports, "FLOW_RULES", {
+	enumerable: true,
+	get: function() {
+		return FLOW_RULES;
+	}
+});
 Object.defineProperty(exports, "KANBO_CAPABILITIES_MARKDOWN_RESOURCE_URI", {
 	enumerable: true,
 	get: function() {
@@ -14838,6 +15981,18 @@ Object.defineProperty(exports, "activityToken", {
 		return activityToken;
 	}
 });
+Object.defineProperty(exports, "boardMetricsAgentKey", {
+	enumerable: true,
+	get: function() {
+		return boardMetricsAgentKey;
+	}
+});
+Object.defineProperty(exports, "boardMetricsRuns", {
+	enumerable: true,
+	get: function() {
+		return boardMetricsRuns;
+	}
+});
 Object.defineProperty(exports, "buildCapabilitiesManifest", {
 	enumerable: true,
 	get: function() {
@@ -14862,6 +16017,12 @@ Object.defineProperty(exports, "commentAuthorReference", {
 		return commentAuthorReference;
 	}
 });
+Object.defineProperty(exports, "computeBoardMetrics", {
+	enumerable: true,
+	get: function() {
+		return computeBoardMetrics;
+	}
+});
 Object.defineProperty(exports, "createBoardOps", {
 	enumerable: true,
 	get: function() {
@@ -14940,6 +16101,12 @@ Object.defineProperty(exports, "isValidCardKey", {
 		return isValidCardKey;
 	}
 });
+Object.defineProperty(exports, "isoWeekOf", {
+	enumerable: true,
+	get: function() {
+		return isoWeekOf;
+	}
+});
 Object.defineProperty(exports, "maskDatabaseUrl", {
 	enumerable: true,
 	get: function() {
@@ -14958,6 +16125,12 @@ Object.defineProperty(exports, "matchesKanboCardQuery", {
 		return matchesKanboCardQuery;
 	}
 });
+Object.defineProperty(exports, "nearestRank", {
+	enumerable: true,
+	get: function() {
+		return nearestRank;
+	}
+});
 Object.defineProperty(exports, "nextIssueIdentity", {
 	enumerable: true,
 	get: function() {
@@ -15090,6 +16263,12 @@ Object.defineProperty(exports, "readEntryRules", {
 		return readEntryRules;
 	}
 });
+Object.defineProperty(exports, "readFlowRules", {
+	enumerable: true,
+	get: function() {
+		return readFlowRules;
+	}
+});
 Object.defineProperty(exports, "readIssuePrefix", {
 	enumerable: true,
 	get: function() {
@@ -15150,6 +16329,12 @@ Object.defineProperty(exports, "toIssueView", {
 		return toIssueView;
 	}
 });
+Object.defineProperty(exports, "utcDayLabel", {
+	enumerable: true,
+	get: function() {
+		return utcDayLabel;
+	}
+});
 Object.defineProperty(exports, "writeBinding", {
 	enumerable: true,
 	get: function() {