kanbo-cli 0.4.0 → 0.6.0

package/dist/lib/index.d.mts

@@ -1,6 +1,6 @@
-import { a as IssuePullRequest, c as IssueStatus, f as issueFieldChanges, i as IssueMilestone, l as KanbanMeta, n as IssueComment, o as IssueRelation, r as IssueFieldChange, s as IssueRun, t as Issue, v as issues } from "./schema-D0MyXcej.mjs";
-import { _ as IssueRunStore, a as BoardMilestoneCardCount, c as BoardStore, d as IssueContextRefStore, f as IssueFieldChangeStore, g as IssueRowStore, h as IssueRelationStore, i as BoardLinkedPullRequest, l as BoardTransactionMode, m as IssuePullRequestStore, n as BoardCardPage, o as BoardRunProjection, p as IssueMilestoneStore, r as BoardCardQuery, s as BoardRunProjectionScope, t as BoardActiveRun, u as IssueCommentStore, v as IssueStatusStore, y as KanbanMetaStore } from "./board-store-D_Mpfb84.mjs";
-import { C as readEntryRules, S as readChecklist, _ as EntryRule, a as IssueActorReference, b as UnmetEntryRule, c as isOutsideWriter, d as KANBO_TOOL_CLI_EQUIVALENTS, f as KANBO_TOOL_NAMES, g as ENTRY_RULE_DESCRIPTIONS, h as ENTRY_RULES, i as IssueActorKind, l as normalizeCommentAuthorKind, m as KanboToolName, n as CardAttention, o as IssueView, p as KanboToolCliEquivalent, r as CardLastComment, s as IssueWriterProvenance, t as BoardApproval, u as toIssueView, v as EntryRuleFacts, w as serializeEntryRules, x as evaluateEntryRules, y as UNMET_ENTRY_RULE_REASONS } from "./approval-LRZ6ontC.mjs";
+import { a as IssuePullRequest, c as IssueStatus, f as issueFieldChanges, i as IssueMilestone, l as KanbanMeta, n as IssueComment, o as IssueRelation, r as IssueFieldChange, s as IssueRun, t as Issue, v as issues } from "./schema-Cwx3HosC.mjs";
+import { _ as IssueRelationStore, a as BoardLinkedPullRequest, b as IssueStatusStore, c as BoardRunProjectionScope, d as BoardWorkspaceFieldChange, f as IssueCommentStore, g as IssuePullRequestStore, h as IssueMilestoneStore, i as BoardFieldChangeQuery, l as BoardStore, m as IssueFieldChangeStore, n as BoardCardPage, o as BoardMilestoneCardCount, p as IssueContextRefStore, r as BoardCardQuery, s as BoardRunProjection, t as BoardActiveRun, u as BoardTransactionMode, v as IssueRowStore, x as KanbanMetaStore, y as IssueRunStore } from "./board-store-BjhiH9TZ.mjs";
+import { C as readEntryRules, D as FlowRule, E as FLOW_RULES, O as readFlowRules, S as readChecklist, T as ColumnFlowRules, _ as EntryRule, a as IssueActorReference, b as UnmetEntryRule, c as isOutsideWriter, d as KANBO_TOOL_CLI_EQUIVALENTS, f as KANBO_TOOL_NAMES, g as ENTRY_RULE_DESCRIPTIONS, h as ENTRY_RULES, i as IssueActorKind, l as normalizeCommentAuthorKind, m as KanboToolName, n as CardAttention, o as IssueView, p as KanboToolCliEquivalent, r as CardLastComment, s as IssueWriterProvenance, t as BoardApproval, u as toIssueView, v as EntryRuleFacts, w as serializeEntryRules, x as evaluateEntryRules, y as UNMET_ENTRY_RULE_REASONS } from "./approval-CnJJfwfi.mjs";
 import { z } from "zod";
 //#region src/cli/output.d.ts
 /**
@@ -366,7 +366,7 @@ export declare function maskDatabaseUrls(text: string): string;
  * (`../serve/board-error-responses.ts`), the one table `kanbo serve` and any app
  * serving the board over HTTP answer with.
  */
-type BoardErrorCode = 'board_approval_requires_user' | 'board_column_name_taken' | 'board_column_not_empty' | 'board_column_ready_protected' | 'board_column_remove_target_invalid' | 'board_column_rules_requires_user' | 'board_column_structure_requires_user' | 'board_column_rules_unmet' | 'board_entry_rule_invalid' | 'board_execution_mode_locked' | 'board_pull_request_invalid' | 'board_pull_request_not_found' | 'board_pull_request_not_yours' | 'board_return_no_previous_column' | 'board_return_requires_user' | 'board_run_already_finished' | 'board_run_not_found' | 'board_run_session_ref_conflict' | 'board_run_session_ref_invalid' | 'board_run_session_ref_requires_user' | 'board_schema_outdated' | 'board_sprint_carry_invalid' | 'board_sprint_close_requires_user' | 'board_sprint_dates_invalid' | 'issue_comment_delete_requires_user' | 'issue_comment_not_found' | 'issue_context_ref_invalid_index' | 'issue_milestone_not_found' | 'issue_not_found' | 'issue_parent_cycle' | 'issue_parent_not_found' | 'issue_parent_self_reference' | 'issue_relation_not_found' | 'issue_relation_self_reference' | 'issue_status_name_empty' | 'issue_status_not_found' | 'issue_status_reference_conflict' | 'issue_workspace_not_found';
+type BoardErrorCode = 'board_approval_requires_user' | 'board_card_not_ready' | 'board_card_run_active' | 'board_column_name_taken' | 'board_column_not_empty' | 'board_column_ready_protected' | 'board_column_remove_target_invalid' | 'board_column_rules_requires_user' | 'board_column_structure_requires_user' | 'board_column_rules_unmet' | 'board_entry_rule_invalid' | 'board_execution_mode_locked' | 'board_flow_rule_invalid' | 'board_metrics_range_invalid' | 'board_nothing_ready' | 'board_pull_request_invalid' | 'board_pull_request_not_found' | 'board_pull_request_not_yours' | 'board_return_no_previous_column' | 'board_return_requires_user' | 'board_run_already_finished' | 'board_run_not_found' | 'board_run_session_ref_conflict' | 'board_run_session_ref_invalid' | 'board_run_session_ref_requires_user' | 'board_schema_outdated' | 'board_sprint_carry_invalid' | 'board_sprint_close_requires_user' | 'board_sprint_dates_invalid' | 'issue_comment_delete_requires_user' | 'issue_comment_not_found' | 'issue_context_ref_invalid_index' | 'issue_milestone_not_found' | 'issue_not_found' | 'issue_parent_cycle' | 'issue_parent_not_found' | 'issue_parent_self_reference' | 'issue_relation_not_found' | 'issue_relation_self_reference' | 'issue_status_name_empty' | 'issue_status_not_found' | 'issue_status_reference_conflict' | 'issue_workspace_not_found';
 /** A board rule the caller broke, carrying the offending values in `details`. */
 export declare class BoardError extends Error {
   readonly code: BoardErrorCode;
@@ -960,6 +960,235 @@ type BoardRunView = IssueRun & {
   attempt: number;
 };
 //#endregion
+//#region src/ops/claim.d.ts
+/** What a claim takes: the board, the card when the claimer names one, and the run it starts. */
+interface ClaimCardInput {
+  workspaceId: string;
+  /** The card to take; the first ready card in To Do, in board order, when absent. */
+  issueId?: string;
+  run: StartRunInput;
+}
+/** What a claim did: the card where it now is, the run it started, and the column it moved to. */
+interface ClaimedCard {
+  /** Carries `unmetRules` when a person's claim put it in a column whose rules it does not meet. */
+  card: BoardCardWrite;
+  run: IssueRun;
+  column: IssueStatus;
+}
+/** Why a named card is not there to take, most telling first. */
+type CardNotReadyReason = 'run_active' | 'waiting_for_person' | 'not_in_to_do';
+//#endregion
+//#region src/ops/column-entries.d.ts
+/** One card entering one column: a move, or a card created in it (`fromStatusId: null`). */
+interface ColumnEntry {
+  changeId: string;
+  issueId: string;
+  workspaceId: string;
+  fromStatusId: string | null;
+  toStatusId: string;
+  actorKind: IssueFieldChange['actorKind'];
+  actorId: string | null;
+  /** Unix seconds. */
+  at: number;
+}
+/** Which boards to read, from when (unix seconds, inclusive), and where a page may end. */
+interface ListColumnEntriesInput {
+  workspaceIds: string[];
+  since: number;
+  limit?: number;
+}
+//#endregion
+//#region src/ops/board-metrics.d.ts
+/** What the metrics are asked about: the workspaces, the range (unix seconds, both ends included) and, for a sprint, its milestone. */
+interface BoardMetricsInput {
+  workspaceIds: readonly string[];
+  from: number;
+  to: number;
+  milestoneId?: string | null;
+}
+/** Every row the metrics are computed from, as the store lists them — one board's, or several boards' put together. */
+interface BoardMetricsHistory {
+  statuses: IssueStatus[];
+  milestones: IssueMilestone[];
+  cards: Issue[];
+  /** Every column change of those cards, from the first on. */
+  entries: ColumnEntry[];
+  runs: IssueRun[];
+  /** The approvals of those cards: `system.approved` comments. Returns are read from `entries` (R012-7). */
+  approvals: IssueComment[];
+}
+/** A duration over the cards a metric counts, in seconds: nearest-rank percentiles, `null` over no cards. */
+interface BoardMetricsDurations {
+  cards: number;
+  p50: number | null;
+  p85: number | null;
+}
+/** A column as the metrics name it: one per slug across the workspaces, in the first workspace's board order. */
+interface BoardMetricsColumn {
+  slug: string;
+  name: string;
+  category: IssueStatus['category'];
+}
+interface BoardMetricsWeek {
+  /** ISO 8601 week, `2026-W02`. */
+  week: string;
+  /** Monday 00:00 UTC of the week, unix seconds. */
+  start: number;
+  finished: number;
+}
+interface BoardMetricsWip {
+  slug: string;
+  cards: number;
+  /** The most cards the column may hold: the workspaces' limits added up when each has one, `null` for no limit. */
+  limit: number | null;
+}
+interface BoardMetricsCard {
+  issueId: string;
+  workspaceId: string;
+  title: string;
+}
+interface BoardMetricsAgingCard extends BoardMetricsCard {
+  /** The column the card is in now. */
+  slug: string;
+  startedAt: number;
+  ageSeconds: number;
+  inColumnSeconds: number;
+  /** Older than the range's cycle-time p85. */
+  overCycleP85: boolean;
+}
+interface BoardMetricsFinishedCard extends BoardMetricsCard {
+  /** `null` for a card that never entered a started column. */
+  startedAt: number | null;
+  finishedAt: number;
+  cycleSeconds: number | null;
+  leadSeconds: number;
+  returns: number;
+  runs: number;
+}
+interface BoardMetricsColumnTime {
+  slug: string;
+  seconds: number;
+}
+interface BoardMetricsFlowDay {
+  /** The UTC day, `2026-01-05`. */
+  day: string;
+  /** When the day is read: its last second, or the end of the range on its last day. */
+  at: number;
+  /** Cards per column slug at `at`; every column is present. */
+  cards: Record<string, number>;
+}
+interface BoardMetricsAgent {
+  /** `agentId` when its runs carry one, else `agentName` (`boardMetricsAgentKey`). */
+  key: string;
+  agentId: string | null;
+  /** The name its newest run was started under. */
+  agentName: string;
+  /** Its runs started in the range. */
+  runs: {
+    total: number;
+    finished: number;
+    failed: number;
+    stopped: number;
+    running: number;
+  };
+  /** Median length of those that ended (nearest rank), seconds; `null` when none ended. */
+  medianRunSeconds: number | null;
+  /** Cards finished in the range that it ran at least once. */
+  cardsFinished: number;
+  /** The share of those cards returned at least once; `null` when there are none. */
+  returnRate: number | null;
+}
+/**
+ * Moves back over the cards finished in the range (R012-7): a move to an
+ * earlier column of the same board whose category is unstarted or started, by
+ * anyone.
+ */
+interface BoardMetricsReturns {
+  total: number;
+  perFinishedCard: number | null;
+  /** Finished cards with zero returns ÷ finished cards. */
+  firstPassRate: number | null;
+  /** The same returns by who made them: a person, an agent (a provider target counts as one), or an outside writer (`system`). */
+  byActorKind: {
+    user: number;
+    agent: number;
+    external: number;
+  };
+}
+interface BoardMetricsPerson {
+  /** The person's actor id; `null` for one who gave none. */
+  id: string | null;
+  created: number;
+  approvals: number;
+  returns: number;
+  /** Column changes they made; creating a card is not one. */
+  moves: number;
+}
+/**
+ * How work flows on a board over a range (spec 2026-11-05, Part 4).
+ *
+ * Started is the first entry into a `started` column; finished is the latest
+ * entry into a `completed` column, for a card still in one; cycle time is
+ * finished − started and lead time finished − created, both as nearest-rank
+ * p50 and p85. Cards in a `canceled` column are counted in `canceled` and left
+ * out of everything else.
+ */
+interface BoardMetrics {
+  /** The range read; `to` is cut at now, so a range starting after now has `from` after `to` and empty series. */
+  range: {
+    from: number;
+    to: number;
+  };
+  now: number;
+  milestoneId: string | null;
+  columns: BoardMetricsColumn[];
+  cycleTime: BoardMetricsDurations;
+  leadTime: BoardMetricsDurations;
+  /** Cards finished per ISO week, every week the range touches. */
+  throughput: BoardMetricsWeek[];
+  /** Cards in each `started` column now. */
+  wip: BoardMetricsWip[];
+  /** The cards in `started` columns now, oldest first. */
+  aging: BoardMetricsAgingCard[];
+  /** Seconds the cards finished in the range spent in each column before they finished. */
+  timeInColumn: BoardMetricsColumnTime[];
+  /** Cards per column at the end of each UTC day of the range. */
+  cumulativeFlow: BoardMetricsFlowDay[];
+  /** The cards finished in the range, in the order they finished. */
+  finished: BoardMetricsFinishedCard[];
+  returns: BoardMetricsReturns;
+  attempts: {
+    runs: number;
+    perFinishedCard: number | null;
+  };
+  canceled: number;
+  agents: BoardMetricsAgent[];
+  people: BoardMetricsPerson[];
+}
+/**
+ * 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.
+ */
+export declare function nearestRank(values: readonly number[], percent: number): number | null;
+/** 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. */
+export declare function boardMetricsAgentKey(run: Pick<IssueRun, 'agentId' | 'agentName'>): string;
+/**
+ * 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.
+ */
+export declare function boardMetricsRuns(history: BoardMetricsHistory, input: BoardMetricsInput): {
+  counted: IssueRun[];
+  canceled: IssueRun[];
+};
+/**
+ * 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.
+ */
+export declare function computeBoardMetrics(history: BoardMetricsHistory, input: BoardMetricsInput, now: number): BoardMetrics;
+//#endregion
 //#region src/ops/activity.d.ts
 /**
  * What the host knows and the board does not: the names of its workspaces, who
@@ -1231,6 +1460,7 @@ export declare function createBoardOps<TStore extends BoardStore>(store: TStore)
   assertReturnable: (issueId: string, input: {
     toStatusName?: string | null;
   }, actor: BoardActor) => Promise<{
+    allowedFrom: string | null;
     category: "backlog" | "canceled" | "completed" | "started" | "triage" | "unstarted";
     color: string | null;
     createdAt: number;
@@ -1239,6 +1469,7 @@ export declare function createBoardOps<TStore extends BoardStore>(store: TStore)
     id: string;
     name: string;
     order: number;
+    wipLimit: number | null;
     workspaceId: string;
   }>;
   readApproval: (issueId: string) => Promise<BoardApproval>;
@@ -1317,6 +1548,7 @@ export declare function createBoardOps<TStore extends BoardStore>(store: TStore)
     carryTo?: string | null;
   }, actor: BoardActor, scope?: BoardWriteScope<TStore>) => Promise<CloseSprintResult>;
   listColumns: (workspaceId: string) => Promise<{
+    allowedFrom: string | null;
     category: "backlog" | "canceled" | "completed" | "started" | "triage" | "unstarted";
     color: string | null;
     createdAt: number;
@@ -1325,9 +1557,11 @@ export declare function createBoardOps<TStore extends BoardStore>(store: TStore)
     id: string;
     name: string;
     order: number;
+    wipLimit: number | null;
     workspaceId: string;
   }[]>;
   findColumn: (workspaceId: string, nameOrId: string) => Promise<{
+    allowedFrom: string | null;
     category: "backlog" | "canceled" | "completed" | "started" | "triage" | "unstarted";
     color: string | null;
     createdAt: number;
@@ -1336,9 +1570,11 @@ export declare function createBoardOps<TStore extends BoardStore>(store: TStore)
     id: string;
     name: string;
     order: number;
+    wipLimit: number | null;
     workspaceId: string;
   } | null>;
   requireColumn: (workspaceId: string, nameOrId: string) => Promise<{
+    allowedFrom: string | null;
     category: "backlog" | "canceled" | "completed" | "started" | "triage" | "unstarted";
     color: string | null;
     createdAt: number;
@@ -1347,9 +1583,11 @@ export declare function createBoardOps<TStore extends BoardStore>(store: TStore)
     id: string;
     name: string;
     order: number;
+    wipLimit: number | null;
     workspaceId: string;
   }>;
   ensureDefaultColumns: (workspaceId: string, scope?: BoardWriteScope<TStore>) => Promise<{
+    allowedFrom: string | null;
     category: "backlog" | "canceled" | "completed" | "started" | "triage" | "unstarted";
     color: string | null;
     createdAt: number;
@@ -1358,9 +1596,11 @@ export declare function createBoardOps<TStore extends BoardStore>(store: TStore)
     id: string;
     name: string;
     order: number;
+    wipLimit: number | null;
     workspaceId: string;
   }[]>;
   createColumn: (input: BoardColumnInput, actor: BoardActor, scope?: BoardWriteScope<TStore>) => Promise<{
+    allowedFrom: string | null;
     category: "backlog" | "canceled" | "completed" | "started" | "triage" | "unstarted";
     color: string | null;
     createdAt: number;
@@ -1369,9 +1609,11 @@ export declare function createBoardOps<TStore extends BoardStore>(store: TStore)
     id: string;
     name: string;
     order: number;
+    wipLimit: number | null;
     workspaceId: string;
   }>;
   updateColumn: (statusId: string, patch: BoardColumnPatch, actor: BoardActor, scope?: BoardWriteScope<TStore>) => Promise<{
+    allowedFrom: string | null;
     category: "backlog" | "canceled" | "completed" | "started" | "triage" | "unstarted";
     color: string | null;
     createdAt: number;
@@ -1380,9 +1622,11 @@ export declare function createBoardOps<TStore extends BoardStore>(store: TStore)
     id: string;
     name: string;
     order: number;
+    wipLimit: number | null;
     workspaceId: string;
   }>;
   describeColumn: (workspaceId: string, nameOrId: string, description: string | null, scope?: BoardWriteScope<TStore>) => Promise<{
+    allowedFrom: string | null;
     category: "backlog" | "canceled" | "completed" | "started" | "triage" | "unstarted";
     color: string | null;
     createdAt: number;
@@ -1391,9 +1635,24 @@ export declare function createBoardOps<TStore extends BoardStore>(store: TStore)
     id: string;
     name: string;
     order: number;
+    wipLimit: number | null;
     workspaceId: string;
   }>;
   setColumnEntryRules: (workspaceId: string, nameOrId: string, entryRules: readonly string[] | null, actor: BoardActor, scope?: BoardWriteScope<TStore>) => Promise<{
+    allowedFrom: string | null;
+    category: "backlog" | "canceled" | "completed" | "started" | "triage" | "unstarted";
+    color: string | null;
+    createdAt: number;
+    description: string | null;
+    entryRules: string | null;
+    id: string;
+    name: string;
+    order: number;
+    wipLimit: number | null;
+    workspaceId: string;
+  }>;
+  setColumnFlowRules: (columnId: string, rules: ColumnFlowRules, actor: BoardActor, scope?: BoardWriteScope<TStore>) => Promise<{
+    allowedFrom: string | null;
     category: "backlog" | "canceled" | "completed" | "started" | "triage" | "unstarted";
     color: string | null;
     createdAt: number;
@@ -1402,8 +1661,22 @@ export declare function createBoardOps<TStore extends BoardStore>(store: TStore)
     id: string;
     name: string;
     order: number;
+    wipLimit: number | null;
     workspaceId: string;
   }>;
+  applyStandardFlow: (workspaceId: string, actor: BoardActor, scope?: BoardWriteScope<TStore>) => Promise<{
+    allowedFrom: string | null;
+    category: "backlog" | "canceled" | "completed" | "started" | "triage" | "unstarted";
+    color: string | null;
+    createdAt: number;
+    description: string | null;
+    entryRules: string | null;
+    id: string;
+    name: string;
+    order: number;
+    wipLimit: number | null;
+    workspaceId: string;
+  }[]>;
   enforceColumnEntryForCards: (issueIds: string[], statusId: string, actor: BoardActor) => Promise<{
     issueId: string;
     unmet: UnmetEntryRule[];
@@ -1415,6 +1688,7 @@ export declare function createBoardOps<TStore extends BoardStore>(store: TStore)
     added: string[];
   }>;
   addColumn: (workspaceId: string, input: AddColumnInput, actor: BoardActor, scope?: BoardWriteScope<TStore>) => Promise<{
+    allowedFrom: string | null;
     category: "backlog" | "canceled" | "completed" | "started" | "triage" | "unstarted";
     color: string | null;
     createdAt: number;
@@ -1423,6 +1697,7 @@ export declare function createBoardOps<TStore extends BoardStore>(store: TStore)
     id: string;
     name: string;
     order: number;
+    wipLimit: number | null;
     workspaceId: string;
   }>;
   applyColumnTemplate: (workspaceId: string, columns: readonly ColumnSpec[], options: ApplyColumnTemplateOptions, scope?: BoardWriteScope<TStore>) => Promise<{
@@ -1430,6 +1705,7 @@ export declare function createBoardOps<TStore extends BoardStore>(store: TStore)
     added: string[];
   }>;
   renameColumn: (workspaceId: string, nameOrId: string, newName: string, actor: BoardActor, scope?: BoardWriteScope<TStore>) => Promise<{
+    allowedFrom: string | null;
     category: "backlog" | "canceled" | "completed" | "started" | "triage" | "unstarted";
     color: string | null;
     createdAt: number;
@@ -1438,9 +1714,11 @@ export declare function createBoardOps<TStore extends BoardStore>(store: TStore)
     id: string;
     name: string;
     order: number;
+    wipLimit: number | null;
     workspaceId: string;
   }>;
   moveColumn: (workspaceId: string, nameOrId: string, position: ColumnPosition, actor: BoardActor, scope?: BoardWriteScope<TStore>) => Promise<{
+    allowedFrom: string | null;
     category: "backlog" | "canceled" | "completed" | "started" | "triage" | "unstarted";
     color: string | null;
     createdAt: number;
@@ -1449,6 +1727,7 @@ export declare function createBoardOps<TStore extends BoardStore>(store: TStore)
     id: string;
     name: string;
     order: number;
+    wipLimit: number | null;
     workspaceId: string;
   }[]>;
   removeColumn: (workspaceId: string, nameOrId: string, options: RemoveColumnOptions, actor: BoardActor, scope?: BoardWriteScope<TStore>) => Promise<RemoveColumnResult>;
@@ -1469,6 +1748,7 @@ export declare function createBoardOps<TStore extends BoardStore>(store: TStore)
     state: "failed" | "finished" | "running" | "stopped";
     worktreePath: string | null;
   }>;
+  claimCard: (input: ClaimCardInput, actor: BoardActor, scope?: BoardWriteScope<TStore>) => Promise<ClaimedCard>;
   attachRunExecution: (runId: string, input: AttachRunExecutionInput, scope?: BoardWriteScope<TStore>) => Promise<{
     agentId: string | null;
     agentName: string;
@@ -1596,11 +1876,27 @@ export declare function createBoardOps<TStore extends BoardStore>(store: TStore)
     limit?: number;
     offset?: number;
   }) => Promise<CardQueryResult>;
+  listColumnEntries: (input: ListColumnEntriesInput) => Promise<ColumnEntry[]>;
   buildPrimeText: (workspaceId: string) => Promise<string>;
+  readBoardMetricsHistory: (workspaceIds: readonly string[]) => Promise<BoardMetricsHistory>;
+  boardMetrics: (input: BoardMetricsInput, now?: number) => Promise<BoardMetrics>;
 };
 /** The board's operations, as a type callers can name. */
 type BoardOps = ReturnType<typeof createBoardOps<BoardStore>>;
 //#endregion
+//#region src/domain/iso-week.d.ts
+/** An ISO 8601 week: its label and the Monday 00:00 UTC it starts at. */
+interface IsoWeek {
+  /** `2026-W02`: the ISO year, which around 1 January is not always the calendar year. */
+  week: string;
+  /** Monday 00:00 UTC, in unix seconds. */
+  start: number;
+}
+/** The ISO week a moment falls in, read in UTC like every board date (ruling 5x-6). */
+export declare function isoWeekOf(seconds: number): IsoWeek;
+/** The UTC day a moment falls on, as `2026-01-05`. */
+export declare function utcDayLabel(seconds: number): string;
+//#endregion
 //#region src/serve/board-error-responses.d.ts
 /** What one board failure is over HTTP: the status, the sentence, and the code a client matches on when it is renamed. */
 interface BoardErrorResponse {
@@ -1622,7 +1918,7 @@ interface BoardErrorResponse {
  * 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
@@ -1636,4 +1932,4 @@ interface BoardErrorResponse {
  */
 export declare const BOARD_ERROR_RESPONSES: Record<BoardErrorCode, BoardErrorResponse>;
 //#endregion
-export { type AddColumnInput, type AddCommentInput, type ApplyColumnTemplateOptions, type AttachRunExecutionInput, type BoardActiveRun, type BoardActor, type BoardApproval, type BoardCardPage, type BoardCardQuery, type BoardCardWrite, type BoardColumnInput, type BoardColumnPatch, type BoardErrorCode, type BoardErrorResponse, type BoardLinkedPullRequest, type BoardMilestoneCardCount, type BoardOps, type BoardPullRequestStanding, type BoardRunProjection, type BoardRunProjectionScope, type BoardRunView, type BoardSprint, type BoardStore, type BoardTransactionMode, type BoardWorkspaceIdentity, type BoardWriteScope, type BulkUpdateCardsInput, type BulkUpdateCardsResult, type CardAttention, type CardLastComment, type CardQueryInput, type CardQueryResult, type CloseSprintResult, type ColumnPosition, type ColumnSpec, type ColumnTemplateId, type CreateCardInput, type CreateCommentOnceInput, type CreateMilestoneInput, type CreateRelationInput, ENTRY_RULES, ENTRY_RULE_DESCRIPTIONS, type EntryRule, type EntryRuleFacts, type ExternalSessionRef, type FinishRunInput, type Issue, type IssueActivityAction, type IssueActivityCommentView, type IssueActivityField, type IssueActivityFieldChangeView, type IssueActivityItemView, type IssueActivityLookup, type IssueActivityResolver, type IssueActivityValueToken, type IssueActivityValueView, type IssueActorKind, type IssueActorReference, type IssueComment, type IssueCommentAuthorView, type IssueCommentStore, type IssueContextRefStore, type IssueFieldChange, type IssueFieldChangeStore, type IssueMilestone, type IssueMilestoneStore, type IssueMutationActor, type IssuePullRequest, type IssuePullRequestStore, type IssueRelation, type IssueRelationCounterpart, type IssueRelationStore, type IssueRelationView, type IssueRowStore, type IssueRun, type IssueRunStore, type IssueStatus, type IssueStatusStore, type IssueView, KANBO_TOOL_CLI_EQUIVALENTS, KANBO_TOOL_NAMES, type KanbanMeta, type KanbanMetaStore, type KanboBinding, type KanboCapabilities, type KanboCapabilitiesPackage, type KanboCapabilitiesRoles, type KanboCapabilityCommand, type KanboCapabilityCommandArgument, type KanboCapabilityCommandOption, type KanboCapabilityEntryRule, type KanboCapabilityStorage, type KanboCapabilityTool, type KanboToolCliEquivalent, type KanboToolName, type MigrateCardsInput, type MigrateCardsResult, type PullRequestFactKeys, type RemoveColumnOptions, type RemoveColumnResult, type StartRunInput, UNMET_ENTRY_RULE_REASONS, type UnmetEntryRule, type UpdateCardInput, type UpdateMilestoneInput, evaluateEntryRules, isOutsideWriter, normalizeCommentAuthorKind, readChecklist, readEntryRules, serializeEntryRules, toIssueView };
+export { type AddColumnInput, type AddCommentInput, type ApplyColumnTemplateOptions, type AttachRunExecutionInput, type BoardActiveRun, type BoardActor, type BoardApproval, type BoardCardPage, type BoardCardQuery, type BoardCardWrite, type BoardColumnInput, type BoardColumnPatch, type BoardErrorCode, type BoardErrorResponse, type BoardFieldChangeQuery, type BoardLinkedPullRequest, type BoardMetrics, type BoardMetricsAgent, type BoardMetricsAgingCard, type BoardMetricsCard, type BoardMetricsColumn, type BoardMetricsColumnTime, type BoardMetricsDurations, type BoardMetricsFinishedCard, type BoardMetricsFlowDay, type BoardMetricsHistory, type BoardMetricsInput, type BoardMetricsPerson, type BoardMetricsReturns, type BoardMetricsWeek, type BoardMetricsWip, type BoardMilestoneCardCount, type BoardOps, type BoardPullRequestStanding, type BoardRunProjection, type BoardRunProjectionScope, type BoardRunView, type BoardSprint, type BoardStore, type BoardTransactionMode, type BoardWorkspaceFieldChange, type BoardWorkspaceIdentity, type BoardWriteScope, type BulkUpdateCardsInput, type BulkUpdateCardsResult, type CardAttention, type CardLastComment, type CardNotReadyReason, type CardQueryInput, type CardQueryResult, type ClaimCardInput, type ClaimedCard, type CloseSprintResult, type ColumnEntry, type ColumnFlowRules, type ColumnPosition, type ColumnSpec, type ColumnTemplateId, type CreateCardInput, type CreateCommentOnceInput, type CreateMilestoneInput, type CreateRelationInput, ENTRY_RULES, ENTRY_RULE_DESCRIPTIONS, type EntryRule, type EntryRuleFacts, type ExternalSessionRef, FLOW_RULES, type FinishRunInput, type FlowRule, type IsoWeek, type Issue, type IssueActivityAction, type IssueActivityCommentView, type IssueActivityField, type IssueActivityFieldChangeView, type IssueActivityItemView, type IssueActivityLookup, type IssueActivityResolver, type IssueActivityValueToken, type IssueActivityValueView, type IssueActorKind, type IssueActorReference, type IssueComment, type IssueCommentAuthorView, type IssueCommentStore, type IssueContextRefStore, type IssueFieldChange, type IssueFieldChangeStore, type IssueMilestone, type IssueMilestoneStore, type IssueMutationActor, type IssuePullRequest, type IssuePullRequestStore, type IssueRelation, type IssueRelationCounterpart, type IssueRelationStore, type IssueRelationView, type IssueRowStore, type IssueRun, type IssueRunStore, type IssueStatus, type IssueStatusStore, type IssueView, KANBO_TOOL_CLI_EQUIVALENTS, KANBO_TOOL_NAMES, type KanbanMeta, type KanbanMetaStore, type KanboBinding, type KanboCapabilities, type KanboCapabilitiesPackage, type KanboCapabilitiesRoles, type KanboCapabilityCommand, type KanboCapabilityCommandArgument, type KanboCapabilityCommandOption, type KanboCapabilityEntryRule, type KanboCapabilityStorage, type KanboCapabilityTool, type KanboToolCliEquivalent, type KanboToolName, type ListColumnEntriesInput, type MigrateCardsInput, type MigrateCardsResult, type PullRequestFactKeys, type RemoveColumnOptions, type RemoveColumnResult, type StartRunInput, UNMET_ENTRY_RULE_REASONS, type UnmetEntryRule, type UpdateCardInput, type UpdateMilestoneInput, evaluateEntryRules, isOutsideWriter, normalizeCommentAuthorKind, readChecklist, readEntryRules, readFlowRules, serializeEntryRules, toIssueView };

package/dist/lib/index.mjs

@@ -1,3 +1,3 @@
-import { $ as COLUMN_TEMPLATES, B as createBoardOps, Ct as nextIssueIdentity, Et as readIssuePrefix, F as BINDING_FILE_PATH, G as ENTRY_RULES, H as formatExternalSessionRef, I as ignoreBoardFile, J as evaluateEntryRules, K as ENTRY_RULE_DESCRIPTIONS, L as readBinding, M as renderCapabilitiesMarkdown, N as maskDatabaseUrl, P as maskDatabaseUrls, Q as COLUMN_CATALOGUE, R as readProjectBinding, St as formatIssueId, Tt as nextIssueOrder, U as parseExternalSessionRef, V as cardDisplayTitle, W as pullRequestFactKeys, X as readEntryRules, Y as readChecklist, Z as serializeEntryRules, _ as suggestCardKey, _t as parseActivityStringArray, a as BOARD_ERROR_RESPONSES, at as TRACKED_FIELDS, bt as normalizeCommentAuthorKind, ct as BOARD_ACTOR, dt as activityText, et as COLUMN_TEMPLATE_IDS, ft as activityToken, g as isValidCardKey, gt as isEmptyActivityValue, h as CARD_KEY_PATTERN, ht as formatPlainActivityValue, i as KANBO_TOOL_NAMES, it as normalizeStatusName, lt as currentUnixSeconds, mt as formatActivityIssueReference, n as buildCapabilitiesManifest, nt as runBoardWrite, ot as diffFieldChanges, pt as commentAuthorReference, q as UNMET_ENTRY_RULE_REASONS, r as KANBO_TOOL_CLI_EQUIVALENTS, rt as DEFAULT_STATUSES, t as CAPABILITIES_MANIFEST_VERSION, tt as readChangeSeq, ut as activityKindOrder, v as DEFAULT_BOARD_FILE_PATH, vt as readSystemCommentKind, wt as nextIssueNumber, xt as toIssueView, yt as isOutsideWriter, z as writeBinding } from "./manifest-Dmo6IlWk.mjs";
+import { $ as COLUMN_TEMPLATE_IDS, At as formatIssueId, B as createBoardOps, Ct as formatPlainActivityValue, Dt as isOutsideWriter, Et as readSystemCommentKind, F as BINDING_FILE_PATH, G as ENTRY_RULE_DESCRIPTIONS, H as parseExternalSessionRef, I as ignoreBoardFile, J as readChecklist, K as UNMET_ENTRY_RULE_REASONS, L as readBinding, M as renderCapabilitiesMarkdown, Mt as nextIssueNumber, N as maskDatabaseUrl, Nt as nextIssueOrder, Ot as normalizeCommentAuthorKind, P as maskDatabaseUrls, Pt as readIssuePrefix, Q as COLUMN_TEMPLATES, R as readProjectBinding, St as formatActivityIssueReference, Tt as parseActivityStringArray, U as pullRequestFactKeys, V as formatExternalSessionRef, W as ENTRY_RULES, X as serializeEntryRules, Y as readEntryRules, Z as COLUMN_CATALOGUE, _ as suggestCardKey, _t as currentUnixSeconds, a as BOARD_ERROR_RESPONSES, at as boardMetricsRuns, bt as activityToken, ct as isoWeekOf, dt as readFlowRules, et as readChangeSeq, ft as DEFAULT_STATUSES, g as isValidCardKey, gt as BOARD_ACTOR, h as CARD_KEY_PATTERN, i as KANBO_TOOL_NAMES, it as boardMetricsAgentKey, jt as nextIssueIdentity, kt as toIssueView, lt as utcDayLabel, mt as cardDisplayTitle, n as buildCapabilitiesManifest, nt as TRACKED_FIELDS, ot as computeBoardMetrics, pt as normalizeStatusName, q as evaluateEntryRules, r as KANBO_TOOL_CLI_EQUIVALENTS, rt as diffFieldChanges, st as nearestRank, t as CAPABILITIES_MANIFEST_VERSION, tt as runBoardWrite, ut as FLOW_RULES, v as DEFAULT_BOARD_FILE_PATH, vt as activityKindOrder, wt as isEmptyActivityValue, xt as commentAuthorReference, yt as activityText, z as writeBinding } from "./manifest-DHI1fkoW.mjs";
 import { a as BoardError } from "./migrations-path-ClaYRNwk.mjs";
-export { BINDING_FILE_PATH, BOARD_ACTOR, BOARD_ERROR_RESPONSES, BoardError, CAPABILITIES_MANIFEST_VERSION, CARD_KEY_PATTERN, COLUMN_CATALOGUE, COLUMN_TEMPLATES, COLUMN_TEMPLATE_IDS, DEFAULT_BOARD_FILE_PATH, DEFAULT_STATUSES, ENTRY_RULES, ENTRY_RULE_DESCRIPTIONS, KANBO_TOOL_CLI_EQUIVALENTS, KANBO_TOOL_NAMES, TRACKED_FIELDS, UNMET_ENTRY_RULE_REASONS, activityKindOrder, activityText, activityToken, buildCapabilitiesManifest, cardDisplayTitle, commentAuthorReference, createBoardOps, currentUnixSeconds, diffFieldChanges, evaluateEntryRules, formatActivityIssueReference, formatExternalSessionRef, formatIssueId, formatPlainActivityValue, ignoreBoardFile, isEmptyActivityValue, isOutsideWriter, isValidCardKey, maskDatabaseUrl, maskDatabaseUrls, nextIssueIdentity, nextIssueNumber, nextIssueOrder, normalizeCommentAuthorKind, normalizeStatusName, parseActivityStringArray, parseExternalSessionRef, pullRequestFactKeys, readBinding, readChangeSeq, readChecklist, readEntryRules, readIssuePrefix, readProjectBinding, readSystemCommentKind, renderCapabilitiesMarkdown, runBoardWrite, serializeEntryRules, suggestCardKey, toIssueView, writeBinding };
+export { BINDING_FILE_PATH, BOARD_ACTOR, BOARD_ERROR_RESPONSES, BoardError, CAPABILITIES_MANIFEST_VERSION, CARD_KEY_PATTERN, COLUMN_CATALOGUE, COLUMN_TEMPLATES, COLUMN_TEMPLATE_IDS, DEFAULT_BOARD_FILE_PATH, DEFAULT_STATUSES, ENTRY_RULES, ENTRY_RULE_DESCRIPTIONS, FLOW_RULES, KANBO_TOOL_CLI_EQUIVALENTS, KANBO_TOOL_NAMES, TRACKED_FIELDS, UNMET_ENTRY_RULE_REASONS, activityKindOrder, activityText, activityToken, boardMetricsAgentKey, boardMetricsRuns, buildCapabilitiesManifest, cardDisplayTitle, commentAuthorReference, computeBoardMetrics, createBoardOps, currentUnixSeconds, diffFieldChanges, evaluateEntryRules, formatActivityIssueReference, formatExternalSessionRef, formatIssueId, formatPlainActivityValue, ignoreBoardFile, isEmptyActivityValue, isOutsideWriter, isValidCardKey, isoWeekOf, maskDatabaseUrl, maskDatabaseUrls, nearestRank, nextIssueIdentity, nextIssueNumber, nextIssueOrder, normalizeCommentAuthorKind, normalizeStatusName, parseActivityStringArray, parseExternalSessionRef, pullRequestFactKeys, readBinding, readChangeSeq, readChecklist, readEntryRules, readFlowRules, readIssuePrefix, readProjectBinding, readSystemCommentKind, renderCapabilitiesMarkdown, runBoardWrite, serializeEntryRules, suggestCardKey, toIssueView, utcDayLabel, writeBinding };