kanbo-cli 0.4.0 → 0.5.0

package/dist/cli-main.cjs

@@ -272,6 +272,14 @@ const BOARD_ERROR_TEXTS = {
 		text: "Only a person can approve a card.",
 		next: AS_A_PERSON
 	}),
+	board_card_not_ready: (details) => ({
+		text: details.reason === "run_active" ? `${named(details.issueId)} is taken: it has a run going.` : details.reason === "waiting_for_person" ? `${named(details.issueId)} is waiting for a person.` : `${named(details.issueId)} is not in To Do, so it is not there to take.`,
+		next: "kanbo ready"
+	}),
+	board_card_run_active: (details) => ({
+		text: `${named(details.issueId)} already has a run going: ${named(details.agentName)}'s, run ${named(details.runId)}.`,
+		next: `kanbo run finish ${named(details.runId)} --state stopped`
+	}),
 	board_column_name_taken: (details) => ({
 		text: `Another column, ${named(details.takenBy)}, already has that name (same slug). Pick another name.`,
 		next: "kanbo columns list"
@@ -302,6 +310,14 @@ const BOARD_ERROR_TEXTS = {
 	}),
 	board_entry_rule_invalid: (details) => ({ text: `Unknown column rule: ${list(details.rules)}. Use any of ${list(details.allowed)}.` }),
 	board_execution_mode_locked: (details) => ({ text: `${named(details.issueId)} has been started, so where it is worked (${named(details.executionMode)}) can't change now.` }),
+	board_flow_rule_invalid: (details) => details.wipLimit !== void 0 ? { text: `A column holds at least 1 card; ${named(details.wipLimit)} is not a limit. Use none for no limit.` } : {
+		text: `A column accepts cards only from other columns of its own board, and ${list(details.allowedFrom)} is not one.`,
+		next: "kanbo columns list"
+	},
+	board_nothing_ready: () => ({
+		text: "No card in To Do is ready to take: each one is taken or waits for a person, or there is none.",
+		next: "kanbo ready"
+	}),
 	board_pull_request_invalid: (details) => ({ text: `"${named(details.value)}" is not a GitHub pull request. Give its link or owner/repo#number.` }),
 	board_pull_request_not_found: (details) => ({
 		text: `${named(details.issueId)} has no pull request link "${named(details.linkId)}".`,
@@ -367,7 +383,7 @@ const BOARD_ERROR_TEXTS = {
 	issue_relation_self_reference: () => ({ text: "A card can't be linked to itself." }),
 	issue_status_name_empty: () => ({ text: "Give the column a name." }),
 	issue_status_not_found: (details) => ({
-		text: `No column "${named(details.statusName ?? details.statusId)}" on this board.`,
+		text: details.category !== void 0 ? `This board has no ${named(details.category)} column for a claimed card to go to.` : `No column "${named(details.statusName ?? details.statusId)}" on this board.`,
 		next: "kanbo columns list"
 	}),
 	issue_status_reference_conflict: () => ({ text: "Name the column once: by its id or by its name, not both." }),
@@ -3561,7 +3577,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.4.0";
+const KANBO_PACKAGE_VERSION = "0.5.0";
 //#endregion
 //#region src/cli/agent-shell.ts
 /**
@@ -3700,6 +3716,7 @@ const HUMAN_ONLY_ACTIONS = [
 	"return",
 	"sprint close",
 	"columns rules",
+	"columns flow",
 	"columns add",
 	"columns rename",
 	"columns move",
@@ -3713,6 +3730,7 @@ const HUMAN_ONLY_MESSAGES = {
 	"return": describeReturnRefusal,
 	"sprint close": describeSprintCloseRefusal,
 	"columns rules": describeColumnRulesRefusal,
+	"columns flow": describeColumnRulesRefusal,
 	"columns add": describeColumnChangesRefusal,
 	"columns rename": describeColumnChangesRefusal,
 	"columns move": describeColumnChangesRefusal,
@@ -10014,6 +10032,14 @@ const HIDDEN_ACTIVITY_FIELDS = /* @__PURE__ */ new Set([
 	"order",
 	"waitingFor"
 ]);
+/**
+* The column a card was created in, recorded as a change from no column at the
+* card's own creation time. The feed's `created` item already stands for it,
+* and the field history keeps it.
+*/
+function isStartingColumn(change, issue) {
+	return change.field === "statusId" && change.fromValue === null && change.createdAt === issue.createdAt;
+}
 const ACTIVITY_FIELD_BY_RAW_FIELD = {
 	assigneeId: "assignee",
 	description: "description",
@@ -10054,7 +10080,7 @@ async function listActivity(store, issueId, resolver) {
 		workspaceById: resolver.workspaceById
 	};
 	const commentItems = await Promise.all((await store.comments.listByIssue(issueId)).map(async (comment) => await toCommentActivityItem(comment, resolver)));
-	const fieldChangeItems = (await Promise.all((await store.fieldChanges.listByIssue(issueId)).map(async (change) => await toFieldChangeActivityItem(change, lookup, resolver)))).filter((item) => item !== null);
+	const fieldChangeItems = (await Promise.all((await store.fieldChanges.listByIssue(issueId)).filter((change) => !isStartingColumn(change, issue)).map(async (change) => await toFieldChangeActivityItem(change, lookup, resolver)))).filter((item) => item !== null);
 	return [
 		{
 			id: `${issue.id}:created`,
@@ -10678,6 +10704,63 @@ 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) {
@@ -10747,6 +10830,7 @@ async function applyColumnTemplate(store, workspaceId, columns, options, scope)
 			workspaceId,
 			...column
 		}, order);
+		await writeStandardFlow(tx, await listColumns(tx, workspaceId));
 		return {
 			statuses: await listColumns(tx, workspaceId),
 			added: columns.map((column) => column.name)
@@ -10856,6 +10940,77 @@ async function setColumnEntryRules(store, workspaceId, nameOrId, entryRules, act
 		return await updateColumn(tx, (await requireColumn(tx, workspaceId, nameOrId)).id, { entryRules }, actor, { tx });
 	}, scope);
 }
+/** The largest WIP limit: what a Postgres `integer` column holds. */
+const MAX_WIP_LIMIT = 2147483647;
+/**
+* Set where a card may enter the column from and how many cards it holds:
+* `allowedFrom` the ids of other columns of its board (`null` for any, `[]` for
+* none), kept once each in board order; `wipLimit` a whole number from 1 to 2147483647, or `null`. A
+* person's to set, like the entry rules: an agent that could open a column
+* could walk any card into it.
+*/
+async function setColumnFlowRules(store, columnId, rules, actor, scope) {
+	assertPersonSetsEntryRules(actor, { statusId: columnId });
+	if (rules.wipLimit !== null && !(Number.isSafeInteger(rules.wipLimit) && rules.wipLimit >= 1 && rules.wipLimit <= MAX_WIP_LIMIT)) throw new BoardError("board_flow_rule_invalid", {
+		statusId: columnId,
+		wipLimit: rules.wipLimit
+	});
+	return await runBoardWrite(store, async ({ tx }) => {
+		const column = await tx.statuses.findById(columnId);
+		if (!column) throw new BoardError("issue_status_not_found", { statusId: columnId });
+		const allowedFrom = rules.allowedFrom === null ? null : allowedFromInBoardOrder(await listColumns(tx, column.workspaceId), column, rules.allowedFrom);
+		await tx.statuses.update(columnId, {
+			allowedFrom: serializeAllowedFrom(allowedFrom),
+			wipLimit: rules.wipLimit
+		});
+		return await tx.statuses.findById(columnId);
+	}, scope);
+}
+/** The ids asked for, once each and in board order — or the refusal naming those that are not another column of this board. */
+function allowedFromInBoardOrder(columns, column, requested) {
+	const others = columns.filter((other) => other.id !== column.id);
+	const invalid = requested.filter((id) => !others.some((other) => other.id === id));
+	if (invalid.length > 0) throw new BoardError("board_flow_rule_invalid", {
+		statusId: column.id,
+		allowedFrom: invalid
+	});
+	return others.filter((other) => requested.includes(other.id)).map((other) => other.id);
+}
+/**
+* Put the standard flow on a board: Done accepts cards from In Review only —
+* and from QA, when the board has it — so nothing reaches Done but through
+* review. Done's WIP limit and every other column stay as they are. A board
+* without Done, or with neither In Review nor QA, has nothing to apply it to.
+*/
+async function applyStandardFlow(store, workspaceId, actor, scope) {
+	assertPersonSetsEntryRules(actor, { workspaceId });
+	return await runBoardWrite(store, async ({ tx }) => {
+		const columns = await listColumns(tx, workspaceId);
+		if (!await writeStandardFlow(tx, columns)) throw new BoardError("issue_status_not_found", {
+			workspaceId,
+			statusName: columns.some((column) => normalizeStatusName(column.name) === STANDARD_FLOW_TARGET) ? "In Review" : "Done"
+		});
+		return await listColumns(tx, workspaceId);
+	}, scope);
+}
+/** Done takes cards from the board's In Review and QA; `false`, with nothing written, when the board has no such columns. */
+async function writeStandardFlow(store, columns) {
+	const flow = standardFlowOf(columns);
+	if (!flow) return false;
+	await store.statuses.update(flow.target.id, { allowedFrom: serializeAllowedFrom(flow.sources.map((column) => column.id)) });
+	return true;
+}
+/**
+* Take a deleted column out of every list of where cards may come from. A list
+* it empties stays empty: a column that took cards only from it does not open
+* to every column.
+*/
+async function dropFromAllowedFrom(store, workspaceId, statusId) {
+	for (const other of await listColumns(store, workspaceId)) {
+		const { allowedFrom } = readFlowRules(other);
+		if (allowedFrom?.includes(statusId)) await store.statuses.update(other.id, { allowedFrom: serializeAllowedFrom(allowedFrom.filter((id) => id !== statusId)) });
+	}
+}
 /**
 * Take an empty column off the board, and number the columns left 0..n-1 in
 * the same write.
@@ -10882,6 +11037,7 @@ async function deleteColumn(store, statusId, scope, actor) {
 			hint: "Move its cards to another column first, or remove it with removeColumn and moveCardsTo."
 		});
 		await tx.statuses.delete(statusId);
+		await dropFromAllowedFrom(tx, column.workspaceId, statusId);
 		await renumberColumns(tx, column.workspaceId);
 	}, scope);
 }
@@ -11161,24 +11317,46 @@ function pullRequestFactKeys({ owner, repo, number }) {
 //#endregion
 //#region src/ops/entry-rules.ts
 /**
-* The column's entry rules the card does not meet (ruling 6-2). A column with
-* no rules answers at once, without reading anything; otherwise only the facts
-* the column's rules need are read.
+* The column's entry rules and flow rules the card does not meet, entry rules
+* first (ruling 6-2; board-workflow spec, Part 2). A column with no rules
+* answers at once, without reading anything; otherwise only the facts its
+* rules need are read. `entering` counts the cards this same write already let
+* into the column, so a bulk move is held to the WIP limit as a whole.
 */
-async function checkColumnEntry(store, card, column) {
+async function checkColumnEntry(store, card, column, entering) {
 	const rules = readEntryRules(column);
-	if (rules.length === 0) return [];
-	return evaluateEntryRules(card, rules, await readEntryRuleFacts(store, card.id, rules)).unmet;
+	const unmet = rules.length === 0 ? [] : evaluateEntryRules(card, rules, await readEntryRuleFacts(store, card.id, rules)).unmet;
+	const flow = readFlowRules(column);
+	if (flow.allowedFrom === null && flow.wipLimit === null) return unmet;
+	return [...unmet, ...evaluateFlowRules(card, column, flow, await readFlowRuleFacts(store, column, flow, entering))];
+}
+/** What the flow rules need: the board's column names when the column names where cards come from, and its card count when it has a limit. */
+async function readFlowRuleFacts(store, column, flow, entering) {
+	const columnNames = flow.allowedFrom === null ? /* @__PURE__ */ new Map() : new Map((await store.statuses.listByWorkspace(column.workspaceId)).map((other) => [other.id, other.name]));
+	if (flow.wipLimit === null) return {
+		columnNames,
+		cardsInColumn: 0
+	};
+	await store.statuses.lockById(column.id);
+	return {
+		columnNames,
+		cardsInColumn: (await store.issues.listPage({
+			workspaceId: column.workspaceId,
+			statusIds: [column.id],
+			limit: 1
+		})).total + entering
+	};
 }
 /**
-* Hold a card at the door of a column that asks for more than it has (ruling
-* 6-3). Anyone but a person — or a person's own terminal, `placesForPerson`
-* (ruling 6-6) — is refused with `board_column_rules_unmet`, which
-* names the column and every unmet rule; a person is let through, and the
-* unmet rules come back so the caller can warn them.
+* Hold a card at the door of a column that asks for more than it has — entry
+* rules (ruling 6-3), or flow rules: a column it may not come from, or a column
+* that is full. Anyone but a person — or a person's own terminal,
+* `placesForPerson` (ruling 6-6) — is refused with `board_column_rules_unmet`,
+* which names the column and everything unmet; a person is let through, and
+* the unmet list comes back so the caller can warn them.
 */
-async function enforceColumnEntry(store, card, column, actor) {
-	const unmet = await checkColumnEntry(store, card, column);
+async function enforceColumnEntry(store, card, column, actor, entering = 0) {
+	const unmet = await checkColumnEntry(store, card, column, entering);
 	if (unmet.length > 0 && actor.kind !== "user" && !actor.placesForPerson) throw new BoardError("board_column_rules_unmet", {
 		issueId: card.id,
 		column: column.name,
@@ -11191,14 +11369,17 @@ async function enforceColumnEntry(store, card, column, actor) {
 * The same door for several cards entering one column at once — a bulk status
 * change. All or nothing: the first card an agent may not move refuses the
 * whole change. A person gets back the cards that entered with rules unmet.
+* Each card counts against the column's WIP limit as the cards before it in the same change entered it.
 */
 async function enforceColumnEntryForCards(store, issueIds, statusId, actor) {
 	const column = await store.statuses.findById(statusId);
 	if (!column) throw new BoardError("issue_status_not_found", { statusId });
 	const entered = [];
+	let entering = 0;
 	for (const card of await store.issues.listByIds(issueIds)) {
 		if (card.statusId === column.id) continue;
-		const unmet = await enforceColumnEntry(store, card, column, actor);
+		const unmet = await enforceColumnEntry(store, card, column, actor, entering);
+		entering++;
 		if (unmet.length > 0) entered.push({
 			issueId: card.id,
 			unmet
@@ -11353,11 +11534,24 @@ const STOPPED_BY_YOU_STATUS_LINE = "stopped by you";
 * the board reads the same whether the agent was launched by an app or from
 * somewhere else entirely. The attempt number is simply how many runs the card
 * has had — a card whose runs were all launched elsewhere still counts them.
+*
+* A card has one run going at a time. A start on a card whose run is still going
+* is refused with `board_card_run_active`, naming that run — whichever path it
+* came by, an app's launch, `kanbo run start`, MCP, or a second app on a shared
+* Postgres board. The card's row is locked first, so two starts racing for it
+* are settled one after the other.
 */
 async function startRun(store, issueId, input, actor, scope) {
 	const externalSessionRef = readExternalSessionRef(input.externalSessionRef) ?? null;
 	return await runBoardWrite(store, async ({ tx }) => {
-		const card = await requireCard$1(tx, issueId);
+		const card = await tx.issues.lockById(issueId);
+		if (!card) throw new BoardError("issue_not_found", { issueId });
+		const [active] = await tx.runs.listRunning(issueId);
+		if (active) throw new BoardError("board_card_run_active", {
+			issueId,
+			runId: active.id,
+			agentName: active.agentName
+		});
 		const attempt = await tx.runs.countByIssue(issueId) + 1;
 		const executionMode = input.executionMode ?? card.executionMode;
 		const run = await tx.runs.create({
@@ -11623,7 +11817,8 @@ async function createCard(store, input, actor, scope) {
 		const column = statusId === null ? null : await tx.statuses.findById(statusId);
 		const unmet = column ? await enforceColumnEntry(tx, {
 			id: null,
-			description: input.description ?? null
+			description: input.description ?? null,
+			statusId: null
 		}, column, actor) : [];
 		const milestoneId = await requireMilestoneInWorkspace(tx, workspaceId, input.milestoneId ?? null);
 		const parentIssueId = await requireParentInWorkspace(tx, workspaceId, input.parentIssueId ?? null);
@@ -11631,8 +11826,9 @@ async function createCard(store, input, actor, scope) {
 		const now = currentUnixSeconds();
 		for (let attempt = 1;; attempt++) {
 			const identity = await nextIssueIdentity(input.workspace, tx);
+			let created;
 			try {
-				return withUnmetRules(await tx.issues.create({
+				created = await tx.issues.create({
 					id: identity.id,
 					workspaceId,
 					title: input.title?.trim() || identity.id,
@@ -11656,12 +11852,25 @@ async function createCard(store, input, actor, scope) {
 					order,
 					createdAt: now,
 					updatedAt: now
-				}), unmet);
+				});
 			} catch (error) {
 				const numberTaken = await tx.issues.findByNumber(workspaceId, identity.number);
 				const keyTaken = await tx.issues.findById(identity.id);
 				if (attempt >= NUMBERING_ATTEMPTS || !numberTaken && !keyTaken) throw error;
+				continue;
 			}
+			if (statusId !== null) await tx.fieldChanges.create({
+				id: (0, node_crypto.randomUUID)(),
+				issueId: created.id,
+				field: "statusId",
+				fromValue: null,
+				toValue: statusId,
+				actorKind: toStoredActorKind(actor),
+				actorId: actor.id ?? null,
+				sourceChatSessionId: actor.chatSessionId ?? null,
+				createdAt: now
+			});
+			return withUnmetRules(created, unmet);
 		}
 	}, scope);
 }
@@ -11717,7 +11926,8 @@ async function updateCard(store, issueId, input, actor, scope) {
 			const description = "description" in updates ? updates.description ?? null : card.description;
 			unmet = await enforceColumnEntry(tx, {
 				id: card.id,
-				description
+				description,
+				statusId: card.statusId
 			}, column, actor);
 		}
 		if ("assigneeKind" in input) updates.assigneeKind = input.assigneeKind ?? null;
@@ -12116,6 +12326,160 @@ async function reorderCards(store, workspaceId, orderedIds, scope) {
 	}, scope);
 }
 //#endregion
+//#region src/ops/ready.ts
+/** The column an agent takes its next card from. */
+const READY_COLUMN_SLUG = "to_do";
+/**
+* The cards an agent may pick up right now: spelled out, nobody working on them,
+* nobody's turn but the agent's.
+*
+* "Ready" is deliberately narrow. A card in Backlog is an idea, a card with a
+* run is taken, and a card waiting for a person belongs to that person until
+* they answer. What is left is the queue — in board order, so the card someone
+* dragged to the top is the one an agent asking for work gets.
+*/
+async function listReady(store, input) {
+	return (await queryReady(store, input)).cards;
+}
+/**
+* One page of the ready cards, how many are ready in all, and the columns read
+* on the way — the rule above, asked of the database in one statement rather
+* than of every card on the board.
+*/
+async function queryReady(store, input) {
+	const columns = await listColumns(store, input.workspaceId);
+	const column = columns.find((candidate) => normalizeStatusName(candidate.name) === READY_COLUMN_SLUG);
+	if (!column) return {
+		cards: [],
+		total: 0,
+		columns
+	};
+	return {
+		...await store.issues.listPage({
+			workspaceId: input.workspaceId,
+			statusIds: [column.id],
+			waitingForPerson: false,
+			hasActiveRun: false,
+			limit: input.limit,
+			offset: input.offset
+		}),
+		columns
+	};
+}
+//#endregion
+//#region src/ops/claim.ts
+/**
+* Take a card to work on, in one board write: pick it, start its run, and move
+* it into the board's first `started` column (In Progress on a standard
+* board), its entry and flow rules checked on the way in. Anything refused
+* leaves nothing written.
+*
+* Two claimers never get the same card. On SQLite the write holds the file
+* from its first read (`begin immediate`), so the second claimer reads the
+* board after the first one's commit. On Postgres the picked card's row is
+* locked (`select … for update`): a claimer that waited on the lock finds the
+* card taken, and moves on to the next ready one. The target's row is locked
+* first, always, in the order a move into it locks (column, then card), so a
+* claim and a move never wait on each other in a circle.
+*/
+async function claimCard(store, input, actor, scope) {
+	return await runBoardWrite(store, async ({ tx }) => {
+		const columns = await listColumns(tx, input.workspaceId);
+		const target = columns.find((column) => column.category === "started");
+		if (!target) throw new BoardError("issue_status_not_found", {
+			workspaceId: input.workspaceId,
+			category: "started"
+		});
+		await tx.statuses.lockById(target.id);
+		const toDo = columns.find((column) => normalizeStatusName(column.name) === "to_do") ?? null;
+		const card = input.issueId === void 0 ? await takeFirstReady(tx, input.workspaceId, toDo) : await takeNamed(tx, input.workspaceId, input.issueId, toDo);
+		const run = await startRun(tx, card.id, input.run, actor, { tx });
+		return {
+			card: await updateCard(tx, card.id, { statusId: target.id }, actor, { tx }),
+			run,
+			column: target
+		};
+	}, scope);
+}
+/**
+* The first ready card, locked. A card another claimer took while this one
+* waited for its lock is passed over, and the next read no longer lists it; the
+* cards passed over are counted so the loop ends with the list.
+*/
+async function takeFirstReady(store, workspaceId, toDo) {
+	const passed = /* @__PURE__ */ new Set();
+	for (;;) {
+		const { cards } = await queryReady(store, {
+			workspaceId,
+			limit: passed.size + 1
+		});
+		const candidate = cards.find((card) => !passed.has(card.id));
+		if (!candidate) throw new BoardError("board_nothing_ready", { workspaceId });
+		const locked = await store.issues.lockById(candidate.id);
+		if (locked && await notReadyReason(store, locked, toDo) === null) return locked;
+		passed.add(candidate.id);
+	}
+}
+/** The named card, locked, when it is on this board and ready — or why not. */
+async function takeNamed(store, workspaceId, issueId, toDo) {
+	const card = await store.issues.lockById(issueId);
+	if (!card || card.workspaceId !== workspaceId) throw new BoardError("issue_not_found", { issueId });
+	const reason = await notReadyReason(store, card, toDo);
+	if (reason) throw new BoardError("board_card_not_ready", {
+		issueId,
+		reason
+	});
+	return card;
+}
+/** `queryReady`'s rule for one card already read: nobody on it, nobody waited for, in To Do. */
+async function notReadyReason(store, card, toDo) {
+	if ((await store.runs.listRunning(card.id)).length > 0) return "run_active";
+	if (card.waitingFor === "human") return "waiting_for_person";
+	return toDo !== null && card.statusId === toDo.id ? null : "not_in_to_do";
+}
+//#endregion
+//#region src/ops/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. */
@@ -12300,6 +12664,7 @@ function subtaskSplitSentence(parentReference) {
 }
 const SUBTASK_RULE = `${SUBTASK_WHEN_SENTENCE} ${subtaskSplitSentence("the parent card's id")}`;
 const PULL_REQUEST_RULE = "Opened a pull request? Link it to the card. Its state and CI checks then reach the card as comments on their own — nothing else tells the board a pull request exists.";
+const CLAIM_RULE = "Taking a card from To Do yourself? Claim it instead of starting a run and moving it: the claim does both in one step, and no other agent gets the same card. Finish the run when you stop.";
 const OWN_SESSION_RULE = "Started the work yourself, not launched by an app that tracks the run for you? Record the run when you start and finish it when you stop. kanbo fills in the Claude Code or Codex session you are in; never invent a session id.";
 /** Said by the `kanbo init` block and the MCP instructions, which name the comment command or tool beside it. */
 const COMMENT_RULE = "Findings, results, decisions and questions go on the card as comments.";
@@ -12323,6 +12688,7 @@ const BOARD_RULES = [
 	EXECUTION_MODE_RULE,
 	SUBTASK_RULE,
 	PULL_REQUEST_RULE,
+	CLAIM_RULE,
 	OWN_SESSION_RULE,
 	"Read the column descriptions above before moving a card, and do all of this through the board tools or commands you have — a statement in your reply changes nothing."
 ];
@@ -12338,12 +12704,14 @@ const BOARD_RULES = [
 async function buildPrimeText(store, workspaceId) {
 	const columns = await listColumns(store, workspaceId);
 	const ruled = columns.some((column) => readEntryRules(column).length > 0);
+	const flowing = columns.some((column) => hasFlowRules(column));
 	return [
 		...await describeReturnedCards(store, workspaceId, columns),
 		"Columns of this board, in board order:",
 		"",
-		...columns.length > 0 ? columns.map(describeColumnLine) : ["- (this board has no columns yet)"],
+		...columns.length > 0 ? columns.map((column) => describeColumnLine(column, columns)) : ["- (this board has no columns yet)"],
 		...ruled ? ["", ENTRY_RULES_NOTE] : [],
+		...flowing ? ["", FLOW_RULES_NOTE] : [],
 		"",
 		"How this board works:",
 		"",
@@ -12385,11 +12753,22 @@ async function describeReturnedCards(store, workspaceId, columns) {
 * without any reads exactly as it did before they existed.
 */
 const ENTRY_RULES_NOTE = "A column that lists requirements refuses a card that does not meet them yet, with the list of what is missing: do that work first, then move the card. A person may still move it.";
-function describeColumnLine(column) {
+/** Said under the columns only when one of them has flow rules. */
+const FLOW_RULES_NOTE = "A column that says which columns it accepts cards from, or how many cards it holds, refuses a move that breaks that and says why: move the card through a column it accepts, or wait until a card leaves. A person may still move it.";
+function hasFlowRules(column) {
+	const { allowedFrom, wipLimit } = readFlowRules(column);
+	return allowedFrom !== null || wipLimit !== null;
+}
+function describeColumnLine(column, columns) {
 	const slug = normalizeStatusName(column.name);
 	const rules = readEntryRules(column);
-	const requires = rules.length > 0 ? ` Requires: ${rules.map((rule) => `${rule} (${ENTRY_RULE_DESCRIPTIONS[rule]})`).join("; ")}.` : "";
-	return column.description ? `- ${column.name} (\`${slug}\`) — ${column.description}${requires}` : `- ${column.name} (\`${slug}\`)${requires ? ` —${requires}` : ""}`;
+	const said = `${rules.length > 0 ? ` Requires: ${rules.map((rule) => `${rule} (${ENTRY_RULE_DESCRIPTIONS[rule]})`).join("; ")}.` : ""}${describeFlow(column, columns)}`;
+	return column.description ? `- ${column.name} (\`${slug}\`) — ${column.description}${said}` : `- ${column.name} (\`${slug}\`)${said ? ` —${said}` : ""}`;
+}
+/** Where a column takes cards from and how many it holds, as the prime text says it; nothing for a column without flow rules. */
+function describeFlow(column, columns) {
+	const { allowedFrom, wipLimit } = readFlowRules(column);
+	return `${allowedFrom === null ? "" : allowedFrom.length === 0 ? " Accepts no card from another column: only a person puts a card here." : ` Accepts cards from ${joinWords(columns.filter((other) => allowedFrom.includes(other.id)).map((other) => `\`${normalizeStatusName(other.name)}\``))} only.`}${wipLimit === null ? "" : ` Holds at most ${wipLimit} ${wipLimit === 1 ? "card" : "cards"}.`}`;
 }
 //#endregion
 //#region src/domain/pull-request-ref.ts
@@ -12559,47 +12938,6 @@ async function queryCards(store, input) {
 	};
 }
 //#endregion
-//#region src/ops/ready.ts
-/** The column an agent takes its next card from. */
-const READY_COLUMN_SLUG = "to_do";
-/**
-* The cards an agent may pick up right now: spelled out, nobody working on them,
-* nobody's turn but the agent's.
-*
-* "Ready" is deliberately narrow. A card in Backlog is an idea, a card with a
-* run is taken, and a card waiting for a person belongs to that person until
-* they answer. What is left is the queue — in board order, so the card someone
-* dragged to the top is the one an agent asking for work gets.
-*/
-async function listReady(store, input) {
-	return (await queryReady(store, input)).cards;
-}
-/**
-* One page of the ready cards, how many are ready in all, and the columns read
-* on the way — the rule above, asked of the database in one statement rather
-* than of every card on the board.
-*/
-async function queryReady(store, input) {
-	const columns = await listColumns(store, input.workspaceId);
-	const column = columns.find((candidate) => normalizeStatusName(candidate.name) === READY_COLUMN_SLUG);
-	if (!column) return {
-		cards: [],
-		total: 0,
-		columns
-	};
-	return {
-		...await store.issues.listPage({
-			workspaceId: input.workspaceId,
-			statusIds: [column.id],
-			waitingForPerson: false,
-			hasActiveRun: false,
-			limit: input.limit,
-			offset: input.offset
-		}),
-		columns
-	};
-}
-//#endregion
 //#region src/ops/relations.ts
 /**
 * Every edge touching the card, in either direction, each with the card on its
@@ -12889,6 +13227,8 @@ function createBoardOps(store) {
 		updateColumn: async (statusId, patch, actor, scope) => await updateColumn(store, statusId, patch, actor, scope),
 		describeColumn: async (workspaceId, nameOrId, description, scope) => await describeColumn(store, workspaceId, nameOrId, description, scope),
 		setColumnEntryRules: async (workspaceId, nameOrId, entryRules, actor, scope) => await setColumnEntryRules(store, workspaceId, nameOrId, entryRules, actor, scope),
+		setColumnFlowRules: async (columnId, rules, actor, scope) => await setColumnFlowRules(store, columnId, rules, actor, scope),
+		applyStandardFlow: async (workspaceId, actor, scope) => await applyStandardFlow(store, workspaceId, actor, scope),
 		enforceColumnEntryForCards: async (issueIds, statusId, actor) => await enforceColumnEntryForCards(store, issueIds, statusId, actor),
 		deleteColumn: async (statusId, scope, actor) => await deleteColumn(store, statusId, scope, actor),
 		reorderColumns: async (workspaceId, orderedIds, scope, actor) => await reorderColumns(store, workspaceId, orderedIds, scope, actor),
@@ -12899,6 +13239,7 @@ function createBoardOps(store) {
 		moveColumn: async (workspaceId, nameOrId, position, actor, scope) => await moveColumn$1(store, workspaceId, nameOrId, position, actor, scope),
 		removeColumn: async (workspaceId, nameOrId, options, actor, scope) => await removeColumn$1(store, workspaceId, nameOrId, options, actor, scope),
 		startRun: async (issueId, input, actor, scope) => await startRun(store, issueId, input, actor, scope),
+		claimCard: async (input, actor, scope) => await claimCard(store, input, actor, scope),
 		attachRunExecution: async (runId, input, scope) => await attachRunExecution(store, runId, input, scope),
 		recordRunSessionRef: async (runId, ref, scope) => await recordRunSessionRef(store, runId, ref, scope),
 		clearRunSessionRef: async (runId, actor, options, scope) => await clearRunSessionRef(store, runId, actor, options, scope),
@@ -12911,6 +13252,7 @@ function createBoardOps(store) {
 		readBoardProjectionForIssue: async (issueId) => await readBoardProjectionForIssue(store, issueId),
 		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)
 	};
 }
@@ -18777,6 +19119,10 @@ const issueStatuses$1 = pgTable("issue_statuses", {
 	order: integer$1("order").notNull().default(0),
 	/** A JSON array of `ENTRY_RULES`, or `null` for none — see the SQLite schema. */
 	entryRules: text$1("entry_rules"),
+	/** A JSON array of the status ids a card may enter from, or `null` for any — see the SQLite schema. */
+	allowedFrom: text$1("allowed_from"),
+	/** The most cards the column holds, or `null` — see the SQLite schema. */
+	wipLimit: integer$1("wip_limit"),
 	...createdAt$1()
 }, (table) => [index$1("issue_statuses_workspace_id_idx").on(table.workspaceId), uniqueIndex$1("issue_statuses_workspace_name_unique").on(table.workspaceId, table.name)]);
 const issueMilestones$1 = pgTable("issue_milestones", {
@@ -18924,7 +19270,7 @@ const issueFieldChanges$1 = pgTable("issue_field_changes", {
 	...createdAt$1(),
 	/** Insertion order, standing in for the `rowid` the SQLite board orders changes by. */
 	seq: bigserial("seq", { mode: "number" }).notNull()
-}, (table) => [index$1("issue_field_changes_issue_id_idx").on(table.issueId)]);
+}, (table) => [index$1("issue_field_changes_issue_id_idx").on(table.issueId), index$1("issue_field_changes_field_created_at_idx").on(table.field, table.createdAt)]);
 /** A pull request someone said belongs to a card — see the SQLite twin for what the row is and is not. */
 const issuePullRequests$1 = pgTable("issue_pull_requests", {
 	id: textPk$1(),
@@ -19000,6 +19346,10 @@ function toIssueComment({ seq: _seq, ...comment }) {
 function toIssueFieldChange({ seq: _seq, ...change }) {
 	return change;
 }
+/** A field change with its card's workspace, without `seq`, for the same reason. */
+function toWorkspaceFieldChange({ seq: _seq, ...change }) {
+	return change;
+}
 /** The pull-request link without `seq`, for the same reason. */
 function toIssuePullRequest({ seq: _seq, ...link }) {
 	return link;
@@ -19206,6 +19556,10 @@ function createStoreOver(database) {
 				const [row] = await database.select().from(issues$1).where(eq(issues$1.id, issueId)).limit(1);
 				return row ?? null;
 			},
+			lockById: async (issueId) => {
+				const [row] = await database.select().from(issues$1).where(eq(issues$1.id, issueId)).limit(1).for("update");
+				return row ?? null;
+			},
 			findInWorkspace: async (workspaceId, issueId) => {
 				const [row] = await database.select().from(issues$1).where(and(eq(issues$1.id, issueId), eq(issues$1.workspaceId, workspaceId))).limit(1);
 				return row ?? null;
@@ -19357,6 +19711,10 @@ function createStoreOver(database) {
 		fieldChanges: {
 			listByIssue: async (issueId) => (await database.select().from(issueFieldChanges$1).where(eq(issueFieldChanges$1.issueId, issueId)).orderBy(asc(issueFieldChanges$1.createdAt), asc(issueFieldChanges$1.seq))).map(toIssueFieldChange),
 			listByIssueField: async (issueId, field) => (await database.select().from(issueFieldChanges$1).where(and(eq(issueFieldChanges$1.issueId, issueId), eq(issueFieldChanges$1.field, field))).orderBy(asc(issueFieldChanges$1.createdAt), asc(issueFieldChanges$1.seq))).map(toIssueFieldChange),
+			listByFieldSince: async (field, query) => query.workspaceIds.length === 0 ? [] : (await database.select({
+				...getTableColumns(issueFieldChanges$1),
+				workspaceId: issues$1.workspaceId
+			}).from(issueFieldChanges$1).innerJoin(issues$1, eq(issues$1.id, issueFieldChanges$1.issueId)).where(and(eq(issueFieldChanges$1.field, field), isNotNull(issueFieldChanges$1.toValue), gte(issueFieldChanges$1.createdAt, query.since), query.until === void 0 ? void 0 : lte(issueFieldChanges$1.createdAt, query.until), inArray(issues$1.workspaceId, [...query.workspaceIds]))).orderBy(asc(issueFieldChanges$1.createdAt), asc(issueFieldChanges$1.id)).limit(query.limit ?? Number.MAX_SAFE_INTEGER)).map(toWorkspaceFieldChange),
 			create: async (values) => {
 				await database.insert(issueFieldChanges$1).values(values);
 			}
@@ -20174,6 +20532,14 @@ const issueStatuses = sqliteTable("issue_statuses", {
 	* through `readEntryRules`, never by hand.
 	*/
 	entryRules: text("entry_rules"),
+	/**
+	* The columns a card may enter this one from — a JSON array of status ids;
+	* `null` for any column, `[]` for none (only a person puts a card here). Read
+	* it through `readFlowRules`, never by hand.
+	*/
+	allowedFrom: text("allowed_from"),
+	/** The most cards this column holds, 1 or more; `null` for no limit. */
+	wipLimit: int("wip_limit"),
 	...createdAt()
 }, (table) => ({
 	byWorkspace: index("issue_statuses_workspace_id_idx").on(table.workspaceId),
@@ -20321,7 +20687,11 @@ const issueFieldChanges = sqliteTable("issue_field_changes", {
 	actorId: text("actor_id"),
 	sourceChatSessionId: text("source_chat_session_id"),
 	...createdAt()
-}, (table) => ({ byIssue: index("issue_field_changes_issue_id_idx").on(table.issueId) }));
+}, (table) => ({
+	byIssue: index("issue_field_changes_issue_id_idx").on(table.issueId),
+	/** The column-entry feed reads one field across a board by time. */
+	byFieldCreatedAt: index("issue_field_changes_field_created_at_idx").on(table.field, table.createdAt)
+}));
 /**
 * A pull request someone said belongs to a card.
 *
@@ -20664,6 +21034,7 @@ function createSqliteBoardStoreCore(resolveDatabase) {
 			}).from(issues).where(and(eq(issues.workspaceId, workspaceId), isNotNull(issues.milestoneId))).groupBy(issues.milestoneId, issues.statusId).all(),
 			listByIds: (issueIds) => resolveDatabase().select().from(issues).where(inArray(issues.id, issueIds)).all(),
 			findById: (issueId) => resolveDatabase().select().from(issues).where(eq(issues.id, issueId)).get() ?? null,
+			lockById: (issueId) => resolveDatabase().select().from(issues).where(eq(issues.id, issueId)).get() ?? null,
 			findInWorkspace: (workspaceId, issueId) => resolveDatabase().select().from(issues).where(and(eq(issues.id, issueId), eq(issues.workspaceId, workspaceId))).get() ?? null,
 			findByNumber: (workspaceId, number) => resolveDatabase().select().from(issues).where(and(eq(issues.workspaceId, workspaceId), eq(issues.number, number))).get() ?? null,
 			maxNumber: (workspaceId) => {
@@ -20761,6 +21132,10 @@ function createSqliteBoardStoreCore(resolveDatabase) {
 		fieldChanges: {
 			listByIssue: (issueId) => resolveDatabase().select().from(issueFieldChanges).where(eq(issueFieldChanges.issueId, issueId)).orderBy(asc(issueFieldChanges.createdAt), FIELD_CHANGE_INSERTION_ORDER).all(),
 			listByIssueField: (issueId, field) => resolveDatabase().select().from(issueFieldChanges).where(and(eq(issueFieldChanges.issueId, issueId), eq(issueFieldChanges.field, field))).orderBy(asc(issueFieldChanges.createdAt), FIELD_CHANGE_INSERTION_ORDER).all(),
+			listByFieldSince: (field, query) => query.workspaceIds.length === 0 ? [] : resolveDatabase().select({
+				...getTableColumns(issueFieldChanges),
+				workspaceId: issues.workspaceId
+			}).from(issueFieldChanges).innerJoin(issues, eq(issues.id, issueFieldChanges.issueId)).where(and(eq(issueFieldChanges.field, field), isNotNull(issueFieldChanges.toValue), gte(issueFieldChanges.createdAt, query.since), query.until === void 0 ? void 0 : lte(issueFieldChanges.createdAt, query.until), inArray(issues.workspaceId, [...query.workspaceIds]))).orderBy(asc(issueFieldChanges.createdAt), asc(issueFieldChanges.id)).limit(query.limit ?? Number.MAX_SAFE_INTEGER).all(),
 			create: (values) => {
 				resolveDatabase().insert(issueFieldChanges).values(values).run();
 			}
@@ -20841,6 +21216,7 @@ function createSqliteBoardStore(options) {
 			countByMilestone: async (workspaceId) => core.issues.countByMilestone(workspaceId),
 			listByIds: async (issueIds) => core.issues.listByIds(issueIds),
 			findById: async (issueId) => core.issues.findById(issueId),
+			lockById: async (issueId) => core.issues.lockById(issueId),
 			findInWorkspace: async (workspaceId, issueId) => core.issues.findInWorkspace(workspaceId, issueId),
 			findByNumber: async (workspaceId, number) => core.issues.findByNumber(workspaceId, number),
 			maxNumber: async (workspaceId) => core.issues.maxNumber(workspaceId),
@@ -20886,6 +21262,7 @@ function createSqliteBoardStore(options) {
 		fieldChanges: {
 			listByIssue: async (issueId) => core.fieldChanges.listByIssue(issueId),
 			listByIssueField: async (issueId, field) => core.fieldChanges.listByIssueField(issueId, field),
+			listByFieldSince: async (field, query) => core.fieldChanges.listByFieldSince(field, query),
 			create: async (values) => core.fieldChanges.create(values)
 		},
 		pullRequests: {
@@ -24007,9 +24384,10 @@ const SCHEMA_NOT_INSTALLED_MESSAGE = "This Postgres database has no kanbo board
 * caller's own risk but never written to — a write shaped by this build's idea
 * of the schema is how a person's board gets a column full of nothing. A file
 * of this package's own is this package's to migrate, so the same refusal
-* points at `kanbo migrate` instead of at the app. Reads stay open either way,
-* because a person who cannot migrate right now should still be able to look at
-* their cards.
+* points at `kanbo migrate` instead of at the app. Reads are held to the lesser
+* bar of `assertReadableBoard`: a file only a stamp behind is still read, so a
+* person who cannot migrate right now can look at their cards, but one missing
+* a table or column this build reads is refused with the same sentence.
 */
 function assertWritableBoard(database, owner) {
 	try {
@@ -24020,6 +24398,26 @@ function assertWritableBoard(database, owner) {
 	}
 }
 /**
+* Refuse a read of a board file that lacks a table or a column this build
+* reads — a file a migration behind — with the sentence a write gets, instead
+* of letting the first statement fail on what is missing. A file whose only
+* difference is its schema stamp is still read: every statement this build
+* makes works on it, and a person who cannot migrate now can still look at
+* their cards.
+*/
+function assertReadableBoard(database, owner) {
+	try {
+		assertBoardSchema$1(database);
+	} catch (error) {
+		if (!(error instanceof BoardError && error.code === "board_schema_outdated")) throw error;
+		if (lacksWhatThisBuildReads(error.details)) throw new CliError(3, owner === "kanbo" ? FILE_SCHEMA_OUTDATED_MESSAGE : SCHEMA_OUTDATED_MESSAGE);
+	}
+}
+/** Whether `assertBoardSchema` found a table or a column missing, rather than only another stamp. */
+function lacksWhatThisBuildReads(details) {
+	return details !== void 0 && ("missingTables" in details || "missingAddedTables" in details || "missingColumns" in details);
+}
+/**
 * Refuse an external board this build cannot speak for — before reading it as
 * well as before writing to it.
 *
@@ -24258,6 +24656,7 @@ async function openFileSession(target, options, mode, cwd) {
 			assertWritableBoard(board.database, target.owner);
 		};
 		if (mode === "write") assertWritableBoard(board.database, target.owner);
+		else assertReadableBoard(board.database, target.owner);
 		const workspace = resolveWorkspace(target.owner === "kanbo" ? { kind: "file" } : {
 			kind: "sqlite",
 			database: board.database
@@ -24281,8 +24680,9 @@ async function openFileSession(target, options, mode, cwd) {
 /**
 * The same, on a board that is a database of its own.
 *
-* The guard runs whatever the command came to do. A board file that this build
-* cannot write to is still a board worth reading; a connection string pointing
+* The guard runs whatever the command came to do. A board file whose only
+* difference from this build is its schema stamp is still a board worth
+* reading; a connection string pointing
 * at a database with no board in it is nothing to read at all, and every
 * command would otherwise fail one statement later with the driver's own words.
 */
@@ -24580,7 +24980,9 @@ function projectCardActiveRun(run) {
 		startedAt: run.startedAt
 	};
 }
-function projectColumn(column) {
+/** A column as the command line prints it; `board` is every column, to name the ones it accepts cards from. */
+function projectColumn(column, board) {
+	const { allowedFrom, wipLimit } = readFlowRules(column);
 	return {
 		id: column.id,
 		name: column.name,
@@ -24588,7 +24990,9 @@ function projectColumn(column) {
 		description: column.description,
 		category: column.category,
 		order: column.order,
-		entryRules: readEntryRules(column)
+		entryRules: readEntryRules(column),
+		allowedFrom: allowedFrom === null ? null : board.filter((other) => allowedFrom.includes(other.id)).map((other) => normalizeStatusName(other.name)),
+		wipLimit
 	};
 }
 function projectSprint(sprint) {
@@ -24660,7 +25064,9 @@ function describeColumns(columns) {
 	return columns.map((column) => [
 		`${padToWidth(sanitizeTerminalText(column.slug), slugWidth)}  ${sanitizeTerminalText(column.name)}`,
 		column.description ? ` — ${sanitizeTerminalText(column.description)}` : "",
-		column.entryRules.length > 0 ? ` [requires: ${column.entryRules.join(", ")}]` : ""
+		column.entryRules.length > 0 ? ` [requires: ${column.entryRules.join(", ")}]` : "",
+		column.allowedFrom === null ? "" : ` [from: ${column.allowedFrom.length > 0 ? column.allowedFrom.join(", ") : "no column"}]`,
+		column.wipLimit === null ? "" : ` [wip: ${column.wipLimit}]`
 	].join("")).join("\n");
 }
 /** A unix-seconds date as the UTC day it falls on, `—` for none. */
@@ -24854,6 +25260,7 @@ function colorsWanted() {
 const KANBO_TOOL_CLI_EQUIVALENTS = {
 	kanbo_prime: { kanbo: "kanbo prime" },
 	kanbo_ready: { kanbo: "kanbo ready" },
+	kanbo_card_claim: { kanbo: "kanbo claim [card] [--agent <name>]" },
 	kanbo_columns: { kanbo: "kanbo columns list" },
 	kanbo_sprints: { kanbo: "kanbo sprint list" },
 	kanbo_card_get: { kanbo: "kanbo card get <id>" },
@@ -25270,16 +25677,22 @@ function projectKanboSprint(sprint) {
 		doneCards: sprint.cards.done
 	};
 }
-/** A column of the board, from the row either transport holds. */
-function projectKanboColumn(column) {
+/** A column of the board, from the row either transport holds; `board` is every column, to name the ones it accepts cards from. */
+function projectKanboColumn(column, board) {
 	const stored = column.entryRules;
+	const allowedIds = typeof column.allowedFrom === "string" ? readFlowRules({
+		allowedFrom: column.allowedFrom,
+		wipLimit: null
+	}).allowedFrom : column.allowedFrom ?? null;
 	return {
 		id: column.id,
 		name: column.name,
 		slug: normalizeStatusName(column.name),
 		description: column.description,
 		order: column.order,
-		entryRules: typeof stored === "object" && stored !== null ? ENTRY_RULES.filter((rule) => stored.includes(rule)) : readEntryRules({ entryRules: stored ?? null })
+		entryRules: typeof stored === "object" && stored !== null ? ENTRY_RULES.filter((rule) => stored.includes(rule)) : readEntryRules({ entryRules: stored ?? null }),
+		allowedFrom: allowedIds === null ? null : board.filter((other) => allowedIds.includes(other.id)).map((other) => normalizeStatusName(other.name)),
+		wipLimit: column.wipLimit ?? null
 	};
 }
 /** A comment as a card read lists it, from the row either transport holds. */
@@ -25393,7 +25806,7 @@ function readMoment(value) {
 const cardMoveTool = defineKanboTool({
 	name: "kanbo_card_move",
 	title: "Move a card",
-	description: `Move a card to another column the moment its real state changes. Read kanbo_columns first: a card in the wrong column is a lie, and a column with entryRules refuses a card that does not meet them yet, listing what is missing. ${WRITTEN_CARD_ANSWER_SENTENCE}`,
+	description: `Move a card to another column the moment its real state changes. Read kanbo_columns first: a card in the wrong column is a lie, and a column refuses a card that does not meet its entryRules yet, that comes from a column it does not accept (allowedFrom), or that would overfill it (wipLimit), listing what is missing. ${WRITTEN_CARD_ANSWER_SENTENCE}`,
 	inputSchema: {
 		card: cardArgument,
 		column: string().min(1).describe("The column to move it to, by its slug or name: in_progress, \"In Progress\". Also accepted as `to`."),
@@ -25465,7 +25878,7 @@ const cardUpdateTool = defineKanboTool({
 const columnsTool = defineKanboTool({
 	name: "kanbo_columns",
 	title: "Columns of the board",
-	description: "List this board's columns in board order, each with the slug kanbo_card_move takes, what the column means here, and the entryRules a card must meet before you move it in.",
+	description: "List this board's columns in board order, each with the slug kanbo_card_move takes, what the column means here, the entryRules a card must meet before you move it in, the columns it accepts cards from (allowedFrom, slugs; null for any) and the most cards it holds (wipLimit).",
 	inputSchema: {},
 	run: async (transport) => await transport.columns()
 });
@@ -25479,6 +25892,38 @@ const primeTool = defineKanboTool({
 	inputSchema: {},
 	run: async (transport) => (await transport.prime()).text
 });
+//#endregion
+//#region src/mcp/tools/card-claim.ts
+/**
+* Taking a card to work on, in one step: the run starts and the card moves out
+* of To Do into the board's first work-in-progress column in the same write,
+* so two agents never get the same card. Published to every host, including
+* one that records the runs of the agents it launches: a claim is how an agent
+* in any terminal takes work.
+*/
+const cardClaimTool = defineKanboTool({
+	name: "kanbo_card_claim",
+	title: "Claim a card",
+	description: "Take a card to work on, in one step: it starts your run and moves the card from To Do into the board's first work-in-progress column. Without `card`, takes the first ready card. Two agents never get the same card: the one that loses is told board_nothing_ready or board_card_not_ready. Answers the card compact, the run id, the column, and the kanbo_run_finish call that ends the run.",
+	inputSchema: {
+		card: cardArgument.optional(),
+		agent: string().min(1).optional().describe("What to call whoever works the card; who this server writes as when absent.")
+	},
+	aliases: {
+		card: [...CARD_ALIASES, "issue"],
+		agent: ["agentName"]
+	},
+	example: { card: "TST-5" },
+	run: async (transport, input) => {
+		const claimed = await transport.cardClaim(input);
+		return {
+			card: compactKanboCard(claimed.card),
+			run: claimed.run.id,
+			column: claimed.column.slug,
+			finishWith: `kanbo_run_finish {"run":"${claimed.run.id}","state":"finished"}`
+		};
+	}
+});
 /** The cards an agent may pick up right now. */
 const readyTool = defineKanboTool({
 	name: "kanbo_ready",
@@ -25567,13 +26012,14 @@ const runStartTool = defineKanboTool({
 /**
 * Every tool the board has, in the order it declares them.
 *
-* The list is the board's, not a server's: the same sixteen are registered
+* The list is the board's, not a server's: the same seventeen are registered
 * whether they run against a server or against the board directly, and the
 * only thing a host decides is which of them it publishes.
 */
 const KANBO_TOOLS = [
 	primeTool,
 	readyTool,
+	cardClaimTool,
 	columnsTool,
 	defineKanboTool({
 		name: "kanbo_sprints",
@@ -25963,10 +26409,12 @@ function buildCapabilitiesManifest() {
 			"Only a person may close a sprint. `kanbo sprint close` refuses an agent's shell (exit 4), and the operation refuses any actor but a person; there is no MCP tool that closes one — `kanbo_sprints` only reads. Unlike approval, the database role does not enforce this.",
 			`The agent role (\`${BOARD_AGENT_ROLE}\`) may not delete a card at all — it holds select, insert and update on \`issues\` and nothing more, even though it may delete freely on every other board table.`,
 			"A column may ask a card to meet entry rules before it enters (`entryRules`). Anyone but a person moving, creating or bulk-moving a card into it early is refused with `board_column_rules_unmet` and one line per unmet rule (CLI exit 1); a person goes through and is told what is missing. Only a person sets the rules — `kanbo columns rules` refuses an agent's shell (exit 4). The database role does not enforce them.",
+			"A column may name the columns it accepts cards from (`allowedFrom`) and the most cards it holds (`wipLimit`). Anyone but a person moving, creating, bulk-moving or claiming a card against them is refused with `board_column_rules_unmet` (`allowed_from`, `wip_limit`); a person goes through and is told. A new board's Done accepts cards from In Review only. Only a person sets them — `kanbo columns flow` refuses an agent's shell (exit 4). The database role does not enforce them.",
+			"A claim (`kanbo claim`, `kanbo_card_claim`, `POST /issues/claim`) takes a ready card from To Do, starts its run and moves it into the board's first `started` column in one write; two claimers never get the same card, and the one that loses is told `board_nothing_ready` or `board_card_not_ready`. A card has one run going at a time: starting a second is refused with `board_card_run_active`, on every path.",
 			"Only a person changes the board's columns: `kanbo columns add`, `rename`, `move`, `remove`, `template` and `add-standard` refuse an agent's shell (exit 4), and the rename, move, remove and add-missing operations refuse any actor but a person (`board_column_structure_requires_user`); no MCP tool changes columns. To Do can be neither removed nor renamed away from its slug `to_do`: `kanbo ready` takes work from it.",
 			"No board tool or command deletes a card, agent role or not. Cancelling one is a move to another column. The one exception is `kanbo serve`'s `DELETE /issues/:id`, which it answers only for a request presenting its token, on a server a person started, that has not sent `x-kanbo-actor: agent` (403 `issue_delete_requires_user` otherwise).",
 			"`kanbo migrate` and `kanbo roles apply` refuse a host app's own database file: the app migrates it, and this package never touches it.",
-			"A write to a board older than this build's schema epoch is refused (exit 3) until `kanbo migrate` runs (on a host app's database, until the app migrates it) — reads stay open either way.",
+			"A write to a board older than this build's schema epoch is refused (exit 3) until `kanbo migrate` runs (on a host app's database, until the app migrates it), and so is a read of a board file that lacks a table or a column this build reads; a board whose only difference is its schema stamp stays readable.",
 			"There is no MCP tool that approves a card, and there never will be: `kanbo_wait_approval` hands the card to a person and ends the turn; only a person takes it back."
 		]
 	};
@@ -26111,6 +26559,52 @@ function registerCapabilitiesCommand(program) {
 	});
 }
 //#endregion
+//#region src/cli/commands/claim.ts
+/**
+* `kanbo claim [card]` — take a card to work on, in one step.
+*
+* The run starts and the card moves out of To Do into the board's first
+* work-in-progress column in one write, so two agents in two terminals never
+* take the same card. Filed as a placement: in a person's own terminal the
+* column's rules warn, in an agent's shell they refuse.
+*/
+function registerClaimCommand(program) {
+	withBoardOptions(program.command("claim").description("Take a card to work on: start your run and move it out of To Do, in one step").argument("[card]", "the card, as MAN-012, MAN-12 or 12 (default: the first ready card)").option("--agent <name>", "your name, e.g. claude (default: the name this shell writes as)").option("--session <ref>", "your session, to find it later: claude:<session id> or codex:<session id> (default: the one Claude Code or Codex names in the environment)")).action(async (reference, options) => {
+		await runBoardCommand(options, "write", async (session) => {
+			const actor = createPlacementActor();
+			const named = reference === void 0 ? void 0 : (await requireCard(session, reference)).id;
+			const claimed = await session.ops.claimCard({
+				workspaceId: session.workspace.id,
+				issueId: named,
+				run: {
+					agentName: options.agent ?? actor.id ?? "agent",
+					externalSessionRef: options.session ?? sessionRefFromEnvironment() ?? void 0,
+					launchedByKind: "external"
+				}
+			}, actor);
+			const [columns, projection, runs] = await Promise.all([
+				session.ops.listColumns(session.workspace.id),
+				session.ops.readBoardProjectionForIssue(claimed.card.id),
+				session.ops.listRuns(claimed.card.id)
+			]);
+			const card = projectCard(claimed.card, columns, projection);
+			for (const item of claimed.card.unmetRules ?? []) console.error(`kanbo: warning: ${card.id} entered "${claimed.column.name}" without ${item.rule}: ${item.detail}`);
+			const run = projectRun({
+				...claimed.run,
+				attempt: runs.find((each) => each.id === claimed.run.id)?.attempt ?? runs.length
+			});
+			return {
+				value: {
+					card,
+					run,
+					column: projectColumn(claimed.column, columns)
+				},
+				text: `Claimed ${card.id}: run ${run.id} started, card moved to ${claimed.column.name}\nWhen you are done: kanbo run finish ${run.id} --state finished`
+			};
+		});
+	});
+}
+//#endregion
 //#region src/cli/card-extras.ts
 async function readCardExtras(session, card, columns, include, commentLimit) {
 	const wants = new Set(include);
@@ -26491,10 +26985,11 @@ const COLUMN_CATEGORIES = [
 ];
 /** The whole board's columns after a change, and the sentence that says what changed. */
 async function changed(session, message, extra = {}) {
-	const views = (await session.ops.listColumns(session.workspace.id)).map(projectColumn);
+	const board = await session.ops.listColumns(session.workspace.id);
+	const views = board.map((column) => projectColumn(column, board));
 	return {
 		value: {
-			...extra,
+			...Object.fromEntries(Object.entries(extra).map(([key, value]) => [key, typeof value === "number" || Array.isArray(value) ? value : projectColumn(value, board)])),
 			columns: views
 		},
 		text: `${message}\n\n${describeColumns(views)}`
@@ -26523,14 +27018,14 @@ async function addColumn(session, request, actor) {
 		category: request.category ?? spec.category,
 		position: anchor ? request.after !== void 0 ? { after: anchor.id } : { before: anchor.id } : void 0
 	}, actor);
-	return await changed(session, `Added ${created.name} (slug ${normalizeStatusName(created.name)}).`, { added: projectColumn(created) });
+	return await changed(session, `Added ${created.name} (slug ${normalizeStatusName(created.name)}).`, { added: created });
 }
 /** Said after a rename: agents' instructions name no column but To Do, and `kanbo prime` gives them the rest. */
 const RENAME_NOTE = "Agents read column names from kanbo prime; rename is picked up there.";
 async function renameColumn(session, column, newName, actor) {
 	const before = await requireNamedColumn(session, column);
 	const renamed = await session.ops.renameColumn(session.workspace.id, before.id, newName, actor);
-	return await changed(session, before.name === renamed.name ? `${renamed.name} already has that name.` : `Renamed ${before.name} to ${renamed.name} (slug ${normalizeStatusName(renamed.name)}).\n${RENAME_NOTE}`, { renamed: projectColumn(renamed) });
+	return await changed(session, before.name === renamed.name ? `${renamed.name} already has that name.` : `Renamed ${before.name} to ${renamed.name} (slug ${normalizeStatusName(renamed.name)}).\n${RENAME_NOTE}`, { renamed });
 }
 /** `--first`, `--last`, `--before <column>` or `--after <column>` — exactly one. */
 function readColumnPosition(options) {
@@ -26562,7 +27057,7 @@ async function removeColumn(session, column, moveCardsTo, actor) {
 	const result = await session.ops.removeColumn(session.workspace.id, removing.id, { moveCardsTo }, actor);
 	for (const card of result.unmetRules ?? []) for (const item of card.unmet) console.error(`kanbo: warning: ${card.issueId} entered "${result.movedTo?.name ?? "—"}" without ${item.rule}: ${item.detail}`);
 	return await changed(session, result.movedTo ? `Removed ${result.removed.name} and moved ${describeCount(result.movedCards)} to ${result.movedTo.name}.` : `Removed ${result.removed.name}.`, {
-		removed: projectColumn(result.removed),
+		removed: result.removed,
 		movedCards: result.movedCards
 	});
 }
@@ -26686,7 +27181,7 @@ async function runColumnsMenu(ui) {
 		if (showList) say$2(ui, [
 			"",
 			"Columns of this board:",
-			describeColumns(columns.map(projectColumn))
+			describeColumns(columns.map((column) => projectColumn(column, columns)))
 		].join("\n"));
 		let choice;
 		try {
@@ -26914,7 +27409,8 @@ function registerColumnsCommands(program) {
 	const columns = program.command("columns").description("See and change the board's columns (alone: a menu)");
 	withBoardOptions(columns.command("list").description("List the columns in order, with the short name to move cards by")).action(async (options) => {
 		await runBoardCommand(options, "read", async (session) => {
-			const views = (await session.ops.listColumns(session.workspace.id)).map(projectColumn);
+			const board = await session.ops.listColumns(session.workspace.id);
+			const views = board.map((column) => projectColumn(column, board));
 			return {
 				value: views,
 				text: describeColumns(views)
@@ -26923,7 +27419,7 @@ function registerColumnsCommands(program) {
 	});
 	withBoardOptions(columns.command("describe").description("Say in one line when a card belongs in a column").argument("<column>", "the column, by slug, name or id").requiredOption("--text <text>", "what the column means")).action(async (column, options) => {
 		await runBoardCommand(options, "write", async (session) => {
-			const view = projectColumn(await session.ops.describeColumn(session.workspace.id, column, options.text));
+			const view = projectColumn(await session.ops.describeColumn(session.workspace.id, column, options.text), await session.ops.listColumns(session.workspace.id));
 			return {
 				value: view,
 				text: describeColumns([view])
@@ -26934,13 +27430,34 @@ function registerColumnsCommands(program) {
 		const actor = requireHumanActor("columns rules", typedWords(command));
 		const rules = readRequestedRules(options);
 		await runBoardCommand(options, "write", async (session) => {
-			const view = projectColumn(await session.ops.setColumnEntryRules(session.workspace.id, column, rules, actor));
+			const view = projectColumn(await session.ops.setColumnEntryRules(session.workspace.id, column, rules, actor), await session.ops.listColumns(session.workspace.id));
 			return {
 				value: view,
 				text: describeColumns([view])
 			};
 		});
 	});
+	withBoardOptions(columns.command("flow").description("Set which columns a card may come from, and how many cards a column holds").argument("<column>", "the column, by slug, name or id").option("--from <columns>", "comma-separated columns a card may enter it from, or any").option("--wip <count>", "the most cards it holds, or none")).action(async (column, options, command) => {
+		const actor = requireHumanActor("columns flow", typedWords(command));
+		if (options.from === void 0 && options.wip === void 0) throw new CliError(1, "Pass --from <columns|any>, --wip <count|none>, or both.");
+		const wipLimit = options.wip === void 0 ? void 0 : readWipLimit(options.wip);
+		await runBoardCommand(options, "write", async (session) => {
+			const workspaceId = session.workspace.id;
+			const board = await session.ops.listColumns(workspaceId);
+			const target = await session.ops.requireColumn(workspaceId, column);
+			const current = readFlowRules(target);
+			await session.ops.setColumnFlowRules(target.id, {
+				allowedFrom: options.from === void 0 ? current.allowedFrom : readAllowedFrom(board, workspaceId, options.from),
+				wipLimit: wipLimit === void 0 ? current.wipLimit : wipLimit
+			}, actor);
+			const after = await session.ops.listColumns(workspaceId);
+			const views = after.map((each) => projectColumn(each, after));
+			return {
+				value: views.find((view) => view.id === target.id),
+				text: describeColumns(views)
+			};
+		});
+	});
 	withBoardOptions(columns.command("add").description("Add a column (before Done unless you say where)").argument("<name>", "what the column is called").option("--after <column>", "put it right after this column").option("--before <column>", "put it right before this column").option("--description <text>", "when a card belongs in it, in one line agents read").addOption(new Option("--category <category>", "what kind of column it is").choices(COLUMN_CATEGORIES))).action(async (name, options, command) => {
 		const actor = requireHumanActor("columns add", typedWords(command));
 		await runBoardCommand(options, "write", async (session) => await addColumn(session, {
@@ -26982,7 +27499,7 @@ function registerColumnsCommands(program) {
 				mode: "add-missing",
 				actor
 			});
-			const views = statuses.map(projectColumn);
+			const views = statuses.map((column) => projectColumn(column, statuses));
 			return {
 				value: {
 					added,
@@ -27006,7 +27523,8 @@ function registerColumnsCommands(program) {
 			return;
 		}
 		await runBoardCommand({}, "read", async (session) => {
-			const views = (await session.ops.listColumns(session.workspace.id)).map(projectColumn);
+			const board = await session.ops.listColumns(session.workspace.id);
+			const views = board.map((column) => projectColumn(column, board));
 			return {
 				value: views,
 				text: describeColumns(views)
@@ -27036,6 +27554,26 @@ function readRequestedRules(options) {
 	if (options.require === void 0) throw new CliError(1, `Pass --require ${ENTRY_RULES.join(",")} (any of them) or --clear.`);
 	return options.require.split(",").map((rule) => rule.trim()).filter(Boolean);
 }
+/** `--from`: `any` for every column, else the columns named, by slug, name or id. */
+function readAllowedFrom(board, workspaceId, value) {
+	if (value.trim().toLowerCase() === "any") return null;
+	const names = value.split(",").map((name) => name.trim()).filter(Boolean);
+	if (names.length === 0) throw new CliError(1, "Name the columns a card may come from (--from in_review,qa), or --from any.");
+	return names.map((name) => {
+		const found = matchColumn(board, workspaceId, name);
+		if (!found) throw new BoardError("issue_status_not_found", {
+			workspaceId,
+			statusName: name
+		});
+		return found.id;
+	});
+}
+/** `--wip`: `none` for no limit, else a whole number of cards, 1 or more. */
+function readWipLimit(value) {
+	if (value.trim().toLowerCase() === "none") return null;
+	if (!/^\d+$/.test(value.trim()) || Number(value) < 1) throw new CliError(1, "--wip takes a whole number of cards, 1 or more, or none.");
+	return Number(value);
+}
 //#endregion
 //#region node_modules/zod/v3/helpers/util.js
 var util;
@@ -42978,7 +43516,7 @@ const INSTRUCTION_END_PATTERN = /<!-- KANBO_END\s*-->/g;
 const POINTER_KINDS = /* @__PURE__ */ new Set(["short", "global"]);
 /** The commands an agent uses, spelled once for the guide and the `kanbo prime` cheat sheet. */
 const COMMAND = {
-	ready: "kanbo ready",
+	claim: "kanbo claim",
 	move: "kanbo card move <id> <column>",
 	statusLine: "kanbo card status-line <id> --text \"...\"",
 	subtask: "kanbo card create --description \"...\" --parent <id>",
@@ -42997,7 +43535,7 @@ const AGENT_GUIDE_TEXT = [
 	"Work on this project is tracked on a kanbo board. Before starting a task run `kanbo prime` — it prints the board's columns and what each one means.",
 	"",
 	...[
-		`- Take a card from \`${COMMAND.ready}\`.`,
+		`- Take a card with \`${COMMAND.claim}\`: it starts your run and moves the card into work in one step, and no other agent gets the same card.`,
 		`- ${MOVE_CARD_RULE} (\`${COMMAND.move}\`)`,
 		`- ${STATUS_LINE_RULE} (\`${COMMAND.statusLine}\`)`,
 		`- ${SUBTASK_RULE} (\`${COMMAND.subtask}\`)`,
@@ -43027,12 +43565,13 @@ const COMMAND_SHEET = [
 	"- `kanbo card create --description \"...\" --parent TST-5` — a subtask",
 	"- `kanbo card update TST-7 --parent TST-5` — move a card at the wrong level under another (`--parent none`: the top level)",
 	"- `kanbo card wait-approval TST-5 --text \"Ready for review: ...\"` — ask a person, then end your turn",
-	"- `kanbo run start TST-5 --agent claude` — record a run you started yourself; it prints the finish command",
+	"- `kanbo claim` — take the first ready card: starts your run and moves it into work in one step (`kanbo claim TST-5` for that card); it prints the finish command",
+	"- `kanbo run start TST-5 --agent claude` — record a run on a card you did not claim; it prints the finish command",
 	"- `kanbo run finish <run id> --state finished` — end it: finished, failed or stopped",
 	`- \`${COMMAND.capabilities}\` — everything else, rarely needed`
 ].join("\n");
 /** How to take work and who approves it — said by both blocks after their first sentence. */
-const POINTER_TAIL = `Take work with \`${COMMAND.ready}\`. ${PERSON_ONLY_RULE}`;
+const POINTER_TAIL = `Take work with \`${COMMAND.claim}\`. ${PERSON_ONLY_RULE}`;
 /** The body of the project block: what `kanbo instructions short` prints. */
 const PROJECT_BODY = [
 	"## Kanbo board",
@@ -43052,7 +43591,7 @@ const GLOBAL_BODY = [
 * The block, markers included, with this body's version and hash on the start
 * marker — and, when given, the kind of text it is (`k=orchestrator`).
 */
-function wrapInstructionBlock(body, version = 2, kind) {
+function wrapInstructionBlock(body, version = 3, kind) {
 	return `<!-- KANBO_START v${version}${kind ? ` k=${kind}` : ""} h=${hashBody(body)} -->\n${body}\n${INSTRUCTION_END}`;
 }
 /** The block `kanbo init --instructions …` writes into a project's own file. */
@@ -43081,7 +43620,7 @@ function inspectBlock(text, current) {
 		kind
 	});
 	if (fields.trim() === "") return inspection(LEGACY_BLOCK_BODIES.includes(body) ? "legacy" : "edited");
-	if (version !== void 0 && Number(version) > 2) return inspection("newer");
+	if (version !== void 0 && Number(version) > 3) return inspection("newer");
 	if (kind !== null && !POINTER_KINDS.has(kind)) return inspection("chosen");
 	if (version === void 0 || hash === void 0 || hashBody(body) !== hash) return inspection("edited");
 	return inspection(normalized.slice(found.start, found.end) === current ? "current" : "outdated");
@@ -44153,7 +44692,7 @@ function startUpdateCheck(deps = {}) {
 		setTimeout: globalThis.setTimeout,
 		clearTimeout: globalThis.clearTimeout
 	};
-	const current = deps.currentVersion ?? "0.4.0";
+	const current = deps.currentVersion ?? "0.5.0";
 	const controller = new AbortController();
 	let found = null;
 	const timeout = timers.setTimeout(() => controller.abort(), UPDATE_CHECK_TIMEOUT_MS);
@@ -46670,7 +47209,7 @@ const KANBO_MCP_INSTRUCTIONS = [
 	"kanbo is a kanban board shared by people and agents; these tools read and change its cards.",
 	"",
 	`- At the start of a session call ${tool("kanbo_prime")} — it returns this board's columns and what each one means.`,
-	`- Take work from ${tool("kanbo_ready")}.`,
+	`- Take work from ${tool("kanbo_ready")}, and claim the card with ${tool("kanbo_card_claim")} before you start: it starts your run and moves the card into work in one step, so no other agent takes it.`,
 	`- ${MOVE_CARD_RULE} (${tool("kanbo_card_move")})`,
 	`- ${STATUS_LINE_RULE} (${tool("kanbo_status_line")})`,
 	`- ${COMMENT_RULE} (${tool("kanbo_card_comment")})`,
@@ -46761,7 +47300,7 @@ const ORCHESTRATOR_GUIDE = [
 	"## Start of every session",
 	"1. Run `kanbo prime` (tool: `kanbo_prime`) and read the column descriptions. On this board the description is the contract, not the name.",
 	"2. Run `kanbo ready` (`kanbo_ready`). If nothing is ready, say so and stop.",
-	"3. Take the first card. Run `kanbo run start <card> --agent orchestrator` (`kanbo_run_start`) and move it to the column this board uses for work in progress — `kanbo prime` lists the columns and what each is for — (`kanbo_card_move`) before doing anything else.",
+	"3. Take the first card with `kanbo claim --agent orchestrator` (`kanbo_card_claim`): it starts your run and moves the card out of To Do into the board's first work-in-progress column in one step, so no other agent takes it, and it prints the run id you finish later. If another agent got there first, run `kanbo ready` again.",
 	"",
 	"## While working",
 	"- Write a status line (`kanbo card status-line <card> --text \"…\"`, `kanbo_status_line`) at every step and before and after anything that takes more than a minute. One sentence, present tense.",
@@ -46788,7 +47327,7 @@ const ORCHESTRATOR_GUIDE = [
 	"- Returned: the reason is the newest comment. The card is back in an earlier column; start a new run and address the reason first.",
 	"",
 	"## Never",
-	"- Never run `kanbo approve`, `kanbo return`, `kanbo sprint close`, `kanbo run clear-session`, or anything that changes the columns: `kanbo columns add`, `kanbo columns rename`, `kanbo columns move`, `kanbo columns remove`, `kanbo columns template`, `kanbo columns add-standard`, `kanbo columns rules`. They are for a person and will fail in your shell anyway.",
+	"- Never run `kanbo approve`, `kanbo return`, `kanbo sprint close`, `kanbo run clear-session`, or anything that changes the columns: `kanbo columns add`, `kanbo columns rename`, `kanbo columns move`, `kanbo columns remove`, `kanbo columns template`, `kanbo columns add-standard`, `kanbo columns rules`, `kanbo columns flow`. They are for a person and will fail in your shell anyway.",
 	"- Never delete or edit the board's database directly."
 ].join("\n");
 //#endregion
@@ -46833,7 +47372,7 @@ function registerInstructionsCommand(program, dependencies = {}) {
 		const found = parseKind(kind);
 		const body = await readInstructionText(found);
 		const pointer = found === "short" || found === "global";
-		const text = options.markers ? wrapInstructionBlock(body, 2, pointer ? void 0 : found) : body;
+		const text = options.markers ? wrapInstructionBlock(body, 3, pointer ? void 0 : found) : body;
 		const hints = process.stderr.isTTY === true;
 		if (hints) process.stderr.write(`${HEADER}\n\n`);
 		console.log(text);
@@ -48266,7 +48805,8 @@ async function createDbTransport(input) {
 	const workspaceId = workspace.id;
 	const actor = input.actor;
 	async function readColumns() {
-		return (await ops.listColumns(workspaceId)).map(projectKanboColumn);
+		const rows = await ops.listColumns(workspaceId);
+		return rows.map((row) => projectKanboColumn(row, rows));
 	}
 	/** One card with what the run registry says about it, in the shape a tool prints. */
 	async function project(card, columns) {
@@ -48316,7 +48856,7 @@ async function createDbTransport(input) {
 	* the waiting and returned ones last said at most two more.
 	*/
 	async function projectPage(page, { attend = true } = {}) {
-		const columns = page.columns.map(projectKanboColumn);
+		const columns = page.columns.map((column) => projectKanboColumn(column, page.columns));
 		const runs = await ops.readBoardProjectionForIssues(page.cards.map((card) => card.id));
 		const attention = attend ? await ops.readCardAttention(page.cards, runs.map((run) => run.activeRun !== null)) : [];
 		return page.cards.map((card, index) => projectKanboCard({
@@ -48448,6 +48988,25 @@ async function createDbTransport(input) {
 				state,
 				errorText
 			}, actor));
+		},
+		cardClaim: async ({ card, agent }) => {
+			await session.assertWritable();
+			const named = card === void 0 ? void 0 : (await resolveCard(card)).id;
+			const claimed = await ops.claimCard({
+				workspaceId,
+				issueId: named,
+				run: {
+					agentName: agent ?? actor.id ?? "agent",
+					externalSessionRef: sessionRefFromEnvironment() ?? void 0,
+					launchedByKind: "external"
+				}
+			}, actor);
+			const columns = await readColumns();
+			return {
+				card: await project(claimed.card, columns),
+				run: projectKanboRun(claimed.run),
+				column: columns.find((column) => column.id === claimed.column.id)
+			};
 		}
 	};
 }
@@ -48489,7 +49048,8 @@ const TRANSPORT_METHODS = {
 	statusLine: true,
 	waitApproval: true,
 	runStart: true,
-	runFinish: true
+	runFinish: true,
+	cardClaim: true
 };
 async function openMcpBoard(input) {
 	try {
@@ -49095,7 +49655,7 @@ function sendBoardPage(response, pathname, assets) {
 * answering for a person — approving a card, sending it back or closing a
 * sprint — as anyone but one is 403, dropping a pull request link somebody else made is the same 403
 * for the same reason, and acting on a run that has already ended is 409,
-* because the answer would have been yes a moment earlier. An agent putting a
+* because the answer would have been yes a moment earlier. Starting a run on a card that has one going, and claiming a card nobody can take right now, are 409 for the same reason. An agent putting a
 * card in a column whose entry rules it does not meet yet is 409 for the same
 * reason turned around: the answer will be yes once the card meets them, and
 * `details.unmet` says what is missing. Deleting a column that still holds
@@ -49113,6 +49673,14 @@ const BOARD_ERROR_RESPONSES = {
 		message: "Only a person can approve a card",
 		code: "issue_approval_requires_user"
 	},
+	board_card_not_ready: {
+		status: 409,
+		message: "That card is not there to take: it is not in To Do, waits for a person, or has a run going"
+	},
+	board_card_run_active: {
+		status: 409,
+		message: "The card already has a run going"
+	},
 	board_column_name_taken: {
 		status: 400,
 		message: "Another column already has that name"
@@ -49152,6 +49720,14 @@ const BOARD_ERROR_RESPONSES = {
 		status: 400,
 		message: "Execution mode cannot change once the card has been launched"
 	},
+	board_flow_rule_invalid: {
+		status: 400,
+		message: "A column accepts cards from other columns of its own board, and holds at least one card"
+	},
+	board_nothing_ready: {
+		status: 409,
+		message: "No card in To Do is ready to take"
+	},
 	board_pull_request_invalid: {
 		status: 400,
 		message: "Not a GitHub pull request: give its URL or owner/repo#number"
@@ -49567,6 +50143,14 @@ const startRunBody = object$1({
 	]).optional(),
 	externalSessionRef: string().nullable().optional()
 });
+const claimBody = object$1({
+	workspaceId: id,
+	issueId: id.optional(),
+	agentName: id.optional(),
+	branch: string().nullable().optional(),
+	executionMode: executionMode.optional(),
+	externalSessionRef: string().nullable().optional()
+});
 const finishRunBody = object$1({
 	state: _enum([
 		"finished",
@@ -49613,7 +50197,8 @@ async function toWrittenCardView(ops, card) {
 function toStatusView(status) {
 	return {
 		...status,
-		entryRules: readEntryRules(status)
+		entryRules: readEntryRules(status),
+		allowedFrom: readFlowRules(status).allowedFrom
 	};
 }
 function toCommentView(comment, personWriterId = null) {
@@ -50048,6 +50633,31 @@ function createIssueRoutes(session, options = {}) {
 				}, actors.placement));
 			}
 		}),
+		route({
+			method: "POST",
+			path: "/issues/claim",
+			body: claimBody,
+			write: true,
+			handle: async ({ body, actors }) => {
+				const named = requireWorkspace(body.workspaceId);
+				if (body.issueId !== void 0) await requireCard(body.issueId);
+				const claimed = await ops.claimCard({
+					workspaceId: named,
+					issueId: body.issueId,
+					run: {
+						agentName: body.agentName ?? actors.writer.id ?? "agent",
+						branch: body.branch,
+						executionMode: body.executionMode,
+						externalSessionRef: body.externalSessionRef
+					}
+				}, actors.placement);
+				return {
+					card: await toWrittenCardView(ops, claimed.card),
+					run: await toRunView(claimed.run),
+					column: toStatusView(claimed.column)
+				};
+			}
+		}),
 		route({
 			method: "PATCH",
 			path: "/issues/bulk",
@@ -51189,6 +51799,7 @@ function registerKanboCommands(program, context = {}) {
 	registerServeCommand(program);
 	program.commandsGroup("For agents and integrations:");
 	registerMcpCommand(program);
+	registerClaimCommand(program);
 	registerRunCommands(program);
 	registerCapabilitiesCommand(program);
 	program.commandsGroup("Shared Postgres boards:");