kanbo-cli 0.5.0 → 0.6.0

package/dist/lib/{manifest-t4LvFgzH.mjs → manifest-DHI1fkoW.mjs}

@@ -1,6 +1,6 @@
 import { a as BoardError } from "./migrations-path-ClaYRNwk.mjs";
-import { c as getBoardMigrationsPath, i as BOARD_PERSON_ROLE, l as createPostgresBoardStore, n as AGENT_WAITING_REFUSAL, o as BOARD_ROLE_SQL, r as BOARD_AGENT_ROLE, s as assertBoardSchema, t as AGENT_APPROVAL_COMMENT_REFUSAL } from "./roles.sql-BDmmNUdx.mjs";
-import { a as openBoardDatabase, c as boardQueryLogger, d as foldCase, i as markBoardFileOwnedByKanbo, l as createSqliteBoardStore, n as migrateBoardFile, o as readBoardFileContents, r as assertBoardSchema$1 } from "./migrate-BUsaTJlj.mjs";
+import { c as getBoardMigrationsPath, i as BOARD_PERSON_ROLE, l as createPostgresBoardStore, n as AGENT_WAITING_REFUSAL, o as BOARD_ROLE_SQL, r as BOARD_AGENT_ROLE, s as assertBoardSchema, t as AGENT_APPROVAL_COMMENT_REFUSAL } from "./roles.sql-9OkYvsNM.mjs";
+import { a as openBoardDatabase, c as boardQueryLogger, d as foldCase, i as markBoardFileOwnedByKanbo, l as createSqliteBoardStore, n as migrateBoardFile, o as readBoardFileContents, r as assertBoardSchema$1 } from "./migrate-Bgj_aABY.mjs";
 import { Command, Option } from "commander";
 import { z } from "zod";
 import { homedir, hostname, userInfo } from "node:os";
@@ -585,18 +585,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;
@@ -1012,62 +1012,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: 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
@@ -1122,6 +1091,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 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.
+*
+* `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: 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";
@@ -1506,65 +2072,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 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/ops/columns.ts
 /** The columns of one workspace, in board order. */
 async function listColumns(store, workspaceId) {
@@ -3245,48 +3752,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 = z.string().transform((raw) => JSON.parse(raw)).pipe(z.array(z.string()));
 /** Add a context ref at the end of the card's list, recording the change in its history. */
@@ -3417,33 +3882,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.
@@ -4060,7 +4498,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
@@ -5120,6 +5560,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
@@ -6534,6 +6985,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"
@@ -7209,7 +7661,7 @@ dirname(fileURLToPath(import.meta.url));
 * `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/setup/paths.ts
 /**
@@ -8692,7 +9144,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);
@@ -12958,6 +13410,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"
@@ -14770,17 +15226,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
@@ -14800,7 +15245,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,
@@ -14843,6 +15288,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) => {
@@ -15023,6 +15575,7 @@ function registerKanboCommands(program, context = {}) {
 	registerReadyCommand(program);
 	registerPrimeCommand(program);
 	registerSprintCommands(program);
+	registerStatsCommand(program);
 	registerServeCommand(program);
 	program.commandsGroup("For agents and integrations:");
 	registerMcpCommand(program);
@@ -15235,4 +15788,4 @@ function buildCapabilitiesManifest() {
 	};
 }
 //#endregion
-export { serializeEntryRules as $, projectKanboSprint as A, createBoardOps as B, pageOf as C, toIssueView as Ct, projectKanboFieldChange as D, nextIssueOrder as Dt, projectKanboColumn as E, nextIssueNumber as Et, BINDING_FILE_PATH as F, FLOW_RULES as G, formatExternalSessionRef as H, ignoreBoardFile as I, ENTRY_RULE_DESCRIPTIONS as J, readFlowRules as K, readBinding as L, renderCapabilitiesMarkdown as M, maskDatabaseUrl as N, projectKanboPullRequest as O, readIssuePrefix as Ot, maskDatabaseUrls as P, readEntryRules as Q, readProjectBinding as R, matchesKanboCardQuery as S, normalizeCommentAuthorKind as St, projectKanboCardComment as T, nextIssueIdentity as Tt, parseExternalSessionRef as U, cardDisplayTitle as V, pullRequestFactKeys as W, evaluateEntryRules as X, UNMET_ENTRY_RULE_REASONS as Y, readChecklist as Z, suggestCardKey as _, formatPlainActivityValue as _t, BOARD_ERROR_RESPONSES as a, DEFAULT_STATUSES as at, DEFAULT_KANBO_COMMENT_LIMIT as b, readSystemCommentKind as bt, registerKanboTools as c, diffFieldChanges as ct, KANBO_MCP_INSTRUCTIONS as d, currentUnixSeconds as dt, COLUMN_CATALOGUE as et, KANBO_CAPABILITIES_MARKDOWN_RESOURCE_URI as f, activityKindOrder as ft, isValidCardKey as g, formatActivityIssueReference as gt, CARD_KEY_PATTERN as h, commentAuthorReference as ht, KANBO_TOOL_NAMES as i, runBoardWrite as it, projectKanboSubCard as j, projectKanboRun as k, KANBO_TOOLS as l, previewComment as lt, registerKanboCapabilitiesResources as m, activityToken as mt, buildCapabilitiesManifest as n, COLUMN_TEMPLATE_IDS as nt, KANBO_MCP_SERVER_NAME as o, normalizeStatusName as ot, KANBO_CAPABILITIES_RESOURCE_URI as p, activityText as pt, ENTRY_RULES as q, KANBO_TOOL_CLI_EQUIVALENTS as r, readChangeSeq as rt, createKanboMcpServer as s, TRACKED_FIELDS as st, CAPABILITIES_MANIFEST_VERSION as t, COLUMN_TEMPLATES as tt, buildKanboTools as u, BOARD_ACTOR as ut, DEFAULT_BOARD_FILE_PATH as v, isEmptyActivityValue as vt, projectKanboCard as w, formatIssueId as wt, KANBO_CARD_INCLUDES as x, isOutsideWriter as xt, DEFAULT_KANBO_CARD_INCLUDES as y, parseActivityStringArray as yt, writeBinding as z };
+export { COLUMN_TEMPLATE_IDS as $, projectKanboSprint as A, formatIssueId as At, createBoardOps as B, pageOf as C, formatPlainActivityValue as Ct, projectKanboFieldChange as D, isOutsideWriter as Dt, projectKanboColumn as E, readSystemCommentKind as Et, BINDING_FILE_PATH as F, ENTRY_RULE_DESCRIPTIONS as G, parseExternalSessionRef as H, ignoreBoardFile as I, readChecklist as J, UNMET_ENTRY_RULE_REASONS as K, readBinding as L, renderCapabilitiesMarkdown as M, nextIssueNumber as Mt, maskDatabaseUrl as N, nextIssueOrder as Nt, projectKanboPullRequest as O, normalizeCommentAuthorKind as Ot, maskDatabaseUrls as P, readIssuePrefix as Pt, COLUMN_TEMPLATES as Q, readProjectBinding as R, matchesKanboCardQuery as S, formatActivityIssueReference as St, projectKanboCardComment as T, parseActivityStringArray as Tt, pullRequestFactKeys as U, formatExternalSessionRef as V, ENTRY_RULES as W, serializeEntryRules as X, readEntryRules as Y, COLUMN_CATALOGUE as Z, suggestCardKey as _, currentUnixSeconds as _t, BOARD_ERROR_RESPONSES as a, boardMetricsRuns as at, DEFAULT_KANBO_COMMENT_LIMIT as b, activityToken as bt, registerKanboTools as c, isoWeekOf as ct, KANBO_MCP_INSTRUCTIONS as d, readFlowRules as dt, readChangeSeq as et, KANBO_CAPABILITIES_MARKDOWN_RESOURCE_URI as f, DEFAULT_STATUSES as ft, isValidCardKey as g, BOARD_ACTOR as gt, CARD_KEY_PATTERN as h, previewComment as ht, KANBO_TOOL_NAMES as i, boardMetricsAgentKey as it, projectKanboSubCard as j, nextIssueIdentity as jt, projectKanboRun as k, toIssueView as kt, KANBO_TOOLS as l, utcDayLabel as lt, registerKanboCapabilitiesResources as m, cardDisplayTitle as mt, buildCapabilitiesManifest as n, TRACKED_FIELDS as nt, KANBO_MCP_SERVER_NAME as o, computeBoardMetrics as ot, KANBO_CAPABILITIES_RESOURCE_URI as p, normalizeStatusName as pt, evaluateEntryRules as q, KANBO_TOOL_CLI_EQUIVALENTS as r, diffFieldChanges as rt, createKanboMcpServer as s, nearestRank as st, CAPABILITIES_MANIFEST_VERSION as t, runBoardWrite as tt, buildKanboTools as u, FLOW_RULES as ut, DEFAULT_BOARD_FILE_PATH as v, activityKindOrder as vt, projectKanboCard as w, isEmptyActivityValue as wt, KANBO_CARD_INCLUDES as x, commentAuthorReference as xt, DEFAULT_KANBO_CARD_INCLUDES as y, activityText as yt, writeBinding as z };