kanbo-cli 0.5.0 → 0.6.0

package/dist/cli-main.cjs

@@ -212,6 +212,26 @@ var BoardError = class extends Error {
 	}
 };
 //#endregion
+//#region src/domain/iso-week.ts
+const DAY_SECONDS$2 = 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$2);
+	const monday = day - (day + 3) % 7;
+	const thursday = monday + 3;
+	const year = (/* @__PURE__ */ new Date(thursday * DAY_SECONDS$2 * 1e3)).getUTCFullYear();
+	const januaryFirst = Date.UTC(year, 0, 1) / 1e3 / DAY_SECONDS$2;
+	const week = Math.floor((thursday - januaryFirst) / 7) + 1;
+	return {
+		week: `${year}-W${String(week).padStart(2, "0")}`,
+		start: monday * DAY_SECONDS$2
+	};
+}
+/** 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/domain/status-name.ts
 /**
 * The columns a workspace gets the first time someone opens its board, in board
@@ -314,6 +334,7 @@ const BOARD_ERROR_TEXTS = {
 		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"
@@ -3577,7 +3598,7 @@ new Command();
 * `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.5.0";
+const KANBO_PACKAGE_VERSION = "0.6.0";
 //#endregion
 //#region src/cli/agent-shell.ts
 /**
@@ -9851,18 +9872,18 @@ function activityToken(token) {
 function currentUnixSeconds() {
 	return Math.floor(Date.now() / 1e3);
 }
-const DAY_SECONDS = 86400;
+const DAY_SECONDS$1 = 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$1) * DAY_SECONDS$1;
 }
 /** 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$1 - 1;
 }
 /** The largest unix seconds a moment is read as: past it, the number is milliseconds (year 5138 onwards). */
 const MAX_UNIX_SECONDS = 1e11;
@@ -10278,6 +10299,536 @@ function previewComment(comment) {
 	};
 }
 //#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/domain/flow-rules.ts
+/** 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/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)
+	};
+}
+/** 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 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 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.
@@ -10704,63 +11255,6 @@ function describeColumnRefusal(details) {
 	return [`board_column_rules_unmet: ${details.issueId ? `${details.issueId} cannot enter` : "A new card cannot be created in"} "${details.column}" yet:`, ...details.unmet.map((item) => `- ${item.rule}: ${item.detail}`)].join("\n");
 }
 //#endregion
-//#region src/domain/flow-rules.ts
-/** 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/ops/columns.ts
 /** The columns of one workspace, in board order. */
 async function listColumns(store, workspaceId) {
@@ -12438,48 +12932,6 @@ async function notReadyReason(store, card, toDo) {
 	return toDo !== null && card.statusId === toDo.id ? null : "not_in_to_do";
 }
 //#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/context-refs.ts
 const ContextRefsJsonSchema = string().transform((raw) => JSON.parse(raw)).pipe(array(string()));
 /** Add a context ref at the end of the card's list, recording the change in its history. */
@@ -12610,33 +13062,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.
@@ -13253,7 +13678,9 @@ function createBoardOps(store) {
 		listReady: async (input) => await listReady(store, input),
 		queryReady: async (input) => await queryReady(store, input),
 		listColumnEntries: async (input) => await listColumnEntries(store, input),
-		buildPrimeText: async (workspaceId) => await buildPrimeText(store, workspaceId)
+		buildPrimeText: async (workspaceId) => await buildPrimeText(store, workspaceId),
+		readBoardMetricsHistory: async (workspaceIds) => await readBoardMetricsHistory(store, workspaceIds),
+		boardMetrics: async (input, now) => await boardMetrics(store, input, now)
 	};
 }
 //#endregion
@@ -19624,6 +20051,10 @@ function createStoreOver(database) {
 		},
 		comments: {
 			listByIssue: async (issueId) => (await database.select().from(issueComments$1).where(eq(issueComments$1.issueId, issueId)).orderBy(asc(issueComments$1.createdAt), asc(issueComments$1.seq))).map(toIssueComment),
+			listByWorkspaces: async (workspaceIds, authorKinds) => {
+				if (workspaceIds.length === 0 || authorKinds.length === 0) return [];
+				return (await database.select(getTableColumns(issueComments$1)).from(issueComments$1).innerJoin(issues$1, eq(issues$1.id, issueComments$1.issueId)).where(and(inArray(issues$1.workspaceId, [...workspaceIds]), inArray(issueComments$1.authorKind, [...authorKinds]))).orderBy(asc(issueComments$1.createdAt), asc(issueComments$1.seq))).map(toIssueComment);
+			},
 			listLatestByIssues: async (issueIds, authorKinds) => {
 				if (issueIds.length === 0 || authorKinds?.length === 0) return [];
 				const ranked = database.select({
@@ -19660,6 +20091,10 @@ function createStoreOver(database) {
 			listByIssue: async (issueId) => (await database.select().from(issueRuns$1).where(eq(issueRuns$1.issueId, issueId)).orderBy(asc(issueRuns$1.startedAt), asc(issueRuns$1.seq))).map(toIssueRun),
 			listRunning: async (issueId) => (await database.select().from(issueRuns$1).where(and(eq(issueRuns$1.issueId, issueId), eq(issueRuns$1.state, "running"))).orderBy(asc(issueRuns$1.startedAt), asc(issueRuns$1.seq))).map(toIssueRun),
 			listRunningWithSession: async () => (await database.select().from(issueRuns$1).where(and(eq(issueRuns$1.state, "running"), isNotNull(issueRuns$1.chatSessionId))).orderBy(asc(issueRuns$1.startedAt), asc(issueRuns$1.seq))).map(toIssueRun),
+			listByWorkspaces: async (workspaceIds) => {
+				if (workspaceIds.length === 0) return [];
+				return (await database.select(getTableColumns(issueRuns$1)).from(issueRuns$1).innerJoin(issues$1, eq(issues$1.id, issueRuns$1.issueId)).where(inArray(issues$1.workspaceId, [...workspaceIds])).orderBy(asc(issueRuns$1.startedAt), asc(issueRuns$1.seq))).map(toIssueRun);
+			},
 			findById: async (runId) => {
 				const [row] = await database.select().from(issueRuns$1).where(eq(issueRuns$1.id, runId)).limit(1);
 				return row ? toIssueRun(row) : null;
@@ -21071,6 +21506,10 @@ function createSqliteBoardStoreCore(resolveDatabase) {
 		},
 		comments: {
 			listByIssue: (issueId) => resolveDatabase().select().from(issueComments).where(eq(issueComments.issueId, issueId)).orderBy(asc(issueComments.createdAt), COMMENT_INSERTION_ORDER).all(),
+			listByWorkspaces: (workspaceIds, authorKinds) => {
+				if (workspaceIds.length === 0 || authorKinds.length === 0) return [];
+				return resolveDatabase().select(getTableColumns(issueComments)).from(issueComments).innerJoin(issues, eq(issues.id, issueComments.issueId)).where(and(inArray(issues.workspaceId, [...workspaceIds]), inArray(issueComments.authorKind, [...authorKinds]))).orderBy(asc(issueComments.createdAt), COMMENT_INSERTION_ORDER).all();
+			},
 			listLatestByIssues: (issueIds, authorKinds) => {
 				if (issueIds.length === 0 || authorKinds?.length === 0) return [];
 				const database = resolveDatabase();
@@ -21100,6 +21539,10 @@ function createSqliteBoardStoreCore(resolveDatabase) {
 			listByIssue: (issueId) => resolveDatabase().select().from(issueRuns).where(eq(issueRuns.issueId, issueId)).orderBy(asc(issueRuns.startedAt), RUN_INSERTION_ORDER).all(),
 			listRunning: (issueId) => resolveDatabase().select().from(issueRuns).where(and(eq(issueRuns.issueId, issueId), eq(issueRuns.state, "running"))).orderBy(asc(issueRuns.startedAt), RUN_INSERTION_ORDER).all(),
 			listRunningWithSession: () => resolveDatabase().select().from(issueRuns).where(and(eq(issueRuns.state, "running"), isNotNull(issueRuns.chatSessionId))).orderBy(asc(issueRuns.startedAt), RUN_INSERTION_ORDER).all(),
+			listByWorkspaces: (workspaceIds) => {
+				if (workspaceIds.length === 0) return [];
+				return resolveDatabase().select(getTableColumns(issueRuns)).from(issueRuns).innerJoin(issues, eq(issues.id, issueRuns.issueId)).where(inArray(issues.workspaceId, [...workspaceIds])).orderBy(asc(issueRuns.startedAt), RUN_INSERTION_ORDER).all();
+			},
 			findById: (runId) => resolveDatabase().select().from(issueRuns).where(eq(issueRuns.id, runId)).get() ?? null,
 			findByChatSessionId: (chatSessionId) => resolveDatabase().select().from(issueRuns).where(eq(issueRuns.chatSessionId, chatSessionId)).orderBy(desc(issueRuns.startedAt), sql`${issueRuns}.rowid desc`).get() ?? null,
 			countByIssue: (issueId) => {
@@ -21232,6 +21675,7 @@ function createSqliteBoardStore(options) {
 		comments: {
 			listByIssue: async (issueId) => core.comments.listByIssue(issueId),
 			listLatestByIssues: async (issueIds, authorKinds) => core.comments.listLatestByIssues(issueIds, authorKinds),
+			listByWorkspaces: async (workspaceIds, authorKinds) => core.comments.listByWorkspaces(workspaceIds, authorKinds),
 			findById: async (commentId) => core.comments.findById(commentId),
 			findByDedupeKey: async (issueId, dedupeKey) => core.comments.findByDedupeKey(issueId, dedupeKey),
 			listByDedupeKeyPrefix: async (issueId, prefix) => core.comments.listByDedupeKeyPrefix(issueId, prefix),
@@ -21243,6 +21687,7 @@ function createSqliteBoardStore(options) {
 			listByIssue: async (issueId) => core.runs.listByIssue(issueId),
 			listRunning: async (issueId) => core.runs.listRunning(issueId),
 			listRunningWithSession: async () => core.runs.listRunningWithSession(),
+			listByWorkspaces: async (workspaceIds) => core.runs.listByWorkspaces(workspaceIds),
 			findById: async (runId) => core.runs.findById(runId),
 			findByChatSessionId: async (chatSessionId) => core.runs.findByChatSessionId(chatSessionId),
 			countByIssue: async (issueId) => core.runs.countByIssue(issueId),
@@ -24739,6 +25184,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
@@ -44692,7 +45148,7 @@ function startUpdateCheck(deps = {}) {
 		setTimeout: globalThis.setTimeout,
 		clearTimeout: globalThis.clearTimeout
 	};
-	const current = deps.currentVersion ?? "0.5.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);
@@ -49724,6 +50180,10 @@ const BOARD_ERROR_RESPONSES = {
 		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"
@@ -51543,17 +52003,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
@@ -51573,7 +52022,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,
@@ -51616,6 +52065,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 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) => {
@@ -51796,6 +52352,7 @@ function registerKanboCommands(program, context = {}) {
 	registerReadyCommand(program);
 	registerPrimeCommand(program);
 	registerSprintCommands(program);
+	registerStatsCommand(program);
 	registerServeCommand(program);
 	program.commandsGroup("For agents and integrations:");
 	registerMcpCommand(program);